@jcoreio/clarity-plugin-api

@jcoreio/clarity-plugin-api

This package provides a mock environment for developing plugins for Clarity. Many of the exports from this package are nonfunctional stubs; Clarity injects a runtime implementation of this package with the same API as provided here.

Table of Contents

• @jcoreio/clarity-plugin-api
• Table of Contents
• Client API
  • type DashboardWidgetProps
  • type ClientPluginContributions
  • Tag State
    • useTagState(tag: string): { loading: boolean, error?: Error, data?: TagState }
      • Example
    • type TagState
  • Drag and Drop
    • useDrop(spec, deps?)
      • Arguments
        • spec: FactoryOrInstance<ClarityDropTargetHookSpec>
        • deps?: unknown[]
      • Returns [ClarityCollectedProps, ConnectDropTarget]
      • Example
  • Routing Hooks
    • useCurrentPluginRoute(): PluginRouteInfo
    • useOrganizationId(options): number | undefined
  • Styling
    • useSeverityPulseStyles(options)
      • options.property
      • options.variant
      • Returns
  • Sidebar Components
    • SidebarItem
    • SidebarItemText
    • SidebarItemIcon
    • SidebarItemSecondaryAction
    • SidebarSection
    • SidebarSectionHeader
• Server API
  • type WebappPluginContributions
  • type MigratePluginContributions
  • getAPIContext(request: Request): APIContext
  • type APIContext
    • Properties
      • appContext: AppContext
      • actorId: number | null | undefined
      • actorIp: string | null | undefined
  • type AppContext
    • Properties
      • postgresPool
• Shared API
  • Plugin Route Paths
    • PluginRouteStub<Params extends {}>
      • parse(pathname: string): Params
      • format(params: Params): string
      • partialFormat(params: Partial<Params>): string
    • apiBasePath: PluginRouteStub<{ plugin: string }>
    • uiBasePath: PluginRouteStub<{ plugin: string }>
    • organizationUIBasePath: PluginRouteStub<{ plugin: string }>

Client API

type DashboardWidgetProps

import { DashboardWidgetProps } from '@jcoreio/clarity-plugin-api/client'

The props Clarity passes to a dashboard widget component provided by a plugin.

See DashboardWidgetProps.ts

type ClientPluginContributions

import { ClientPluginContributions } from '@jcoreio/clarity-plugin-api/client'

Components and behaviors contributed to the client side of Clarity by a plugin. You should make sure the default export from your client entrypoint satisfies this type.

See ClientPluginContributions.ts

Tag State

useTagState(tag: string): { loading: boolean, error?: Error, data?: TagState }

import { useTagState } from '@jcoreio/clarity-plugin-api/client'

React hook that subscribes to the realtime value, metadata, and alarm state of a tag.

Example

import * as React from 'react'
import {
  useTagState,
  DashboardWidgetProps,
} from '@jcoreio/clarity-plugin-api/client'

export function MyWidget({
  config,
}: DashboardWidgetProps<{ tag: string } | undefined>) {
  const { loading, error, data } = useTagState(config?.tag)

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  const t = data?.t
  const v = data?.v
  const metadata = data?.metadata
  const notification = data?.notification
  const name = metadata?.fullName?.join('/') || tag
  return <div>
    Most recent data for {name}:
    <p>Time: {t != null ? new Date(t).toLocaleString()}</p>
    <p>Value: {v}</p>
    <p>Notification: {notification?.severity}</p>
  </div>
}

type TagState

import { TagState } from '@jcoreio/clarity-plugin-api/client'

See TagState.ts

Drag and Drop

useDrop(spec, deps?)

import { useDrop } from '@jcoreio/clarity-plugin-api/client'

React hook for connecting a drop target to Clarity

Arguments

See types in dnd.ts

spec: FactoryOrInstance<ClarityDropTargetHookSpec>

The drop target specification (object or function, function preferred)

deps?: unknown[]

The memoization deps array to use when evaluating spec changes

Returns [ClarityCollectedProps, ConnectDropTarget]

See types in dnd.ts

Example

import * as React from 'react'
import {
  useTagState,
  DashboardWidgetProps,
} from '@jcoreio/clarity-plugin-api/client'

export function MyWidget({
  config,
  setConfig,
}: DashboardWidgetProps<{ tag?: string } | undefined>) {
  const [{ isOver, canDrop, tag, MetadataItem }, connectDropTarget] = useDrop(
    {
      canDrop: ({ tag, MetadataItem }) => tag != null,
      drop: ({ tag, MetadataItem }): undefined => {
        if (tag != null) setConfig({ tag })
      },
    },
    [setConfig]
  )

  return (
    <div ref={connectDropTarget}>
      {tag != null ?
        <p>Drop to set tag to {tag}</p>
      : <p>Tag: {config?.tag}</p>}
    </div>
  )
}

Routing Hooks

useCurrentPluginRoute(): PluginRouteInfo

import { useCurrentPluginRoute } from '@jcoreio/clarity-plugin-api/client'

Returns information about the plugin route associated with the current location.pathname. Throws if location.pathname is not a plugin route or subroute

See useCurrentPluginRoute.ts for properties of the PluginRouteInfo return type.

useOrganizationId(options): number | undefined

import { useOrganizationId } from '@jcoreio/clarity-plugin-api/client'

Returns the id of the current organization the user is viewing from the URL path. Returns undefined if the user isn't in an organization route and options?.optional is truthy Throws if the user isn't in an organization route and options?.optional is falsy

Styling

useSeverityPulseStyles(options)

import { useSeverityPulseStyles } from '@jcoreio/clarity-plugin-api/client'

Creates CSS classes to apply a color pulse animation for a warning, alarm, or critical condition to the given CSS property.

options.property

The camel-cased CSS property to animate (e.g. backgroundColor)

options.variant

Which set of colors to use:

• 'pale' - light, less saturated colors (used for gauge backgrounds)
• 'bright' - fully saturated colors

Returns

An object with info, warning, alarm, and critical properties, which are CSS class names. The info class doesn't apply an animation, but is provided for convenience since info is one of the severity enum constants.

Sidebar Components

You can use these in a component provided by your plugin in the sidebarSections property of your `ClientPluginContributions.

SidebarItem

import { SidebarItem } from '@jcoreio/clarity-plugin-api/client'

The React component for a single item in the sidebar.

See SidebarItem.tsx for properties.

SidebarItemText

import { SidebarItemText } from '@jcoreio/clarity-plugin-api/client'

The React component for text inside a <SidebarItem>

See SidebarItemText.tsx for properties.

SidebarItemIcon

import { SidebarItemIcon } from '@jcoreio/clarity-plugin-api/client'

The React component for an icon inside a <SidebarItem>

See SidebarItemIcon.tsx for properties.

SidebarItemSecondaryAction

import { SidebarItemSecondaryAction } from '@jcoreio/clarity-plugin-api/client'

The React component for a secondary action (icon button, loading spinner, etc) inside a <SidebarItem> on the right hand side.

See SidebarItemSecondaryAction.tsx for properties.

SidebarSection

import { SidebarSection } from '@jcoreio/clarity-plugin-api/client'

The React component for a sidebar section, which comprises a header item (rendered via <SidebarSectionHeader>) and a collapsible list of children, which may be <SidebarItem>s or other elements.

See SidebarSection.tsx for properties.

SidebarSectionHeader

import { SidebarSectionHeader } from '@jcoreio/clarity-plugin-api/client'

The React component for the header of a <SidebarSection>, renders a <SidebarItem>.

See SidebarSectionHeader.tsx for properties.

Server API

type WebappPluginContributions

import { WebappPluginContributions } from '@jcoreio/clarity-plugin-api/server'

Components and behaviors contributed to the server side webapp task of Clarity by a plugin, like API methods.

See WebappPluginContributions.ts for properties.

type MigratePluginContributions

import { MigratePluginContributions } from '@jcoreio/clarity-plugin-api/server'

Behaviors contributed to the server side migrate task of Clarity by a plugin, like database migrations.

See MigratePluginContributions.ts for properties.

getAPIContext(request: Request): APIContext

import { getAPIContext } from '@jcoreio/clarity-plugin-api/server'

type APIContext

import type { APIContext } from '@jcoreio/clarity-plugin-api/server'

The context of a Clarity API request Use getAPIContext to get the APIContext from an express Request

See APIContext.ts for more info.

Properties

appContext: AppContext

The Clarity AppContext

actorId: number | null | undefined

The id of the Clarity user who is performing the request, if any

actorIp: string | null | undefined

The IP address of the user who is performing the request, if available

type AppContext

import type { AppContext } from '@jcoreio/clarity-plugin-api/server'

The Clarity application context types exposed to plugins. In an API method handler, you can get the AppContext via getAPIContext(request).appContext

See AppContext.ts for more info.

Properties

postgresPool

The postgres pool of connections to the app database. This may not be a true {@link Pool pg.Pool} instance, instead it may be an adapter that provides the Pool.connect, Pool.query, and PoolClient.release() with the same signatures in pg.

Shared API

Plugin Route Paths

Provides URL route parsers and formatters for plugins. The specific URL formats are determined by Clarity, so you should use these helpers instead of hardcoding any base paths in your plugin.

See pluginRoutePaths.ts

PluginRouteStub<Params extends {}>

The interface for parsing/formatting URL routes

parse(pathname: string): Params

Parses the given URL pathname and returns the parsed Params for this route. Throws if pathname doesn't match this route

format(params: Params): string

Creates a URL pathname for the given params.

partialFormat(params: Partial<Params>): string

Creates a URL pathname pattern for the given params. If a value for a parameter like plugin is omitted, that part of the pattern will be left as :plugin instead of being replaced by the parameter value.

apiBasePath: PluginRouteStub<{ plugin: string }>

import { apiBasePath } from '@jcoreio/clarity-plugin-api/client'
// or
import { apiBasePath } from '@jcoreio/clarity-plugin-api/server'

The base path for plugins' API routes

uiBasePath: PluginRouteStub<{ plugin: string }>

import { uiBasePath } from '@jcoreio/clarity-plugin-api/client'
// or
import { uiBasePath } from '@jcoreio/clarity-plugin-api/server'

The base path for plugins' UI routes that aren't under the base path for an organization

organizationUIBasePath: PluginRouteStub<{ plugin: string }>

import { organizationUIBasePath } from '@jcoreio/clarity-plugin-api/client'
// or
import { organizationUIBasePath } from '@jcoreio/clarity-plugin-api/server'

The base path for plugins' UI routes under the base path for an organization