@collective-intelligence/extensions-sdk-frontend-react

Public, host-neutral contracts for React contributions rendered by Collective Intelligence Studio or Dashboard.

React and React DOM are host-provided peers. The optional @collective-intelligence/ui-react peer is required when importing the /workflow or /ui-react subpaths; declaration-only consumers do not need it.

import { declareFrontendCatalogContribution } from "@collective-intelligence/extensions-sdk-frontend"
import { declareStudioComponent } from "@collective-intelligence/extensions-sdk-frontend-react/studio"
import { customerPageProps } from "./schemas"

const sourceRef = "com.acme.crm.studio.customer-view"

export const studioCatalog = declareFrontendCatalogContribution({
  fqn: sourceRef,
  host: "studio",
  load: () => import("./studio-catalog")
})

export const customerPage = declareStudioComponent({
  definition: {
    category: "page",
    propsSchema: customerPageProps,
    sourceRef
  },
  manifest: {
    fqn: "com.acme.crm.studio.customer-page",
    version: "1.0.0"
  },
  presentation: { displayName: "Customer" }
})

Declarations are data: they do not register with Studio or Dashboard and do not own module delivery, host resolution, or error-boundary rendering. Catalog Hosted Contributions come from the React-free frontend SDK and can be passed to declarePackage({ hostedContributions: [...] }); their lazy load functions never enter the serialized package manifest. This React package intentionally does not expose the retired leaf declareStudioView or declareDashboardWorkflowField helpers.

sourceRef is required on every Studio component render leaf and remains in the serialized package manifest. It identifies the same package's hosted Studio contribution; it is not a source path or an alternate runtime URL.

Frontend runtime

The frontend entrypoint provides the shared React execution boundary for declarations from @collective-intelligence/extensions-sdk-frontend:

import {
  createHostedDiagnostic,
  HostedExtensionRender,
  loadDeclarationModule
} from "@collective-intelligence/extensions-sdk-frontend-react/frontend"

;<HostedExtensionRender
  declaration={declaration}
  componentProps={{ customerId: "customer-1" }}
  load={() => loadDeclarationModule(declaration)}
/>

The frontend entrypoint owns module loading, React component validation, and error-boundary diagnostics. It also exports createHostedDiagnostic and the HostedDiagnostic, HostedDiagnosticPhase, and SourceMapLocation types for hosts that report failures outside the provided render boundary. Host applications still own catalog activation, routing, and product-specific fallback UI.

Wrap the Host tree in HostedExtensionFailureProvider to replace the plain failure message with the Host's own design-system UI. Its render callback receives the HostedDiagnostic. Load failures are also logged with console.error together with their original cause; React logs render failures.

HostedExtensionRender keeps the mounted component when props or callback identities change, preserving local edits and focus. Loading restarts when the declaration object or implementationRole changes; hosts should keep declarations stable until the contribution changes. Pending load failures use the latest onDiagnostic callback.

Workflow UI

The workflow entrypoint provides host-neutral workflow field and node renderers, catalog activation, and query helpers:

import {
  WorkflowFieldResolver,
  activateWorkflowCatalog,
  workflowFieldOptions
} from "@collective-intelligence/extensions-sdk-frontend-react/workflow"

Field bindings use inputBinding for node inputs and parameter for node config. The exported read and patch helpers preserve sibling values and store field display labels under the same canonical binding key in metadata. Stored {mode: "fixed"} envelopes and compiled literals are unwrapped at every path segment when a field renderer or a visibleWhen rule reads a binding; expression values pass through unchanged. Visibility equals compares JSON structurally, and in matches a scalar value or any member of a multi-value field. CatalogNodeDetailsEditor renders sections and fields by ascending order (default 0, ties keep declaration order). resource_selector and credential_selector fields that resolve only to a widget fallback render as the remote-options select, which shows the field's declared placeholder.

WorkflowFieldFrame and ExpressionSlot accept optional help text, shown below the field label. Custom fixed and expression controls should forward the render prop’s describedBy to their input’s aria-describedby, preserving any existing description IDs. The built-in expression editor combines this contextual help with validation descriptions. Read-only fields show the saved Fixed or Expression mode as text.

Opening expression suggestions preserves focus in the expression input or textarea, so typing continues in the authored value. The suggestion search remains explicitly focusable for filtering and inserting available values.

Hosts provide remote workflow-field options through configureWorkflowFieldOptionsProvider. The SDK keeps that adapter outside the public package so the same workflow UI can be used with different backend clients and host applications.

Hosts can provide context.chart.presentation with an icon React component (accepting an optional className) and a tone CSS class string. Use the node type’s semantic icon and its category’s styling consistently in the catalog and canvas. CatalogNodeChartBlock applies the supplied tone to the card and icon badge, ahead of the renderer’s legacy accent. The default charts and built-in chart overrides that delegate to this component share this behavior. Without presentation, standalone consumers retain the kind-based icon and accent. The host owns identity resolution; the public SDK does not import host catalogs or private presentation registries.

The chart exposes every declared input and output with its port name, direction, connection limit, and allowed peer constraints. Port targets are 20 pixels wide; the card grows to keep dense port lists and contextual add controls separated.

Building in the workspace

This package needs the built @collective-intelligence/ui-react declarations to compile its own declarations. From the repository root, run bunx turbo run build --filter=@collective-intelligence/extensions-sdk-frontend-react to build this package and its dependencies in order. The workspace development dependency on ui-react supplies that build ordering; it remains an optional peer for consumers of the published package.

Hosted module references may supply a load callback alongside module and exportName. loadDeclarationModule prefers that callback for the requested implementation role, falling back to the render role when absent. Without a callback it imports the module locator. Keep actual renderer functions reachable through the callback so bundlers retain them in catalog-only entrypoints. The callback is a runtime sidecar and is excluded from canonical package metadata.

Hosted workflow field, configuration, and template declarations require a load callback. Their render paths reject locator-only implementations so hosted bundles contain no computed imports outside the declared module graph. The general loadDeclarationModule API retains its locator fallback for host-owned loading outside those workflow render paths.

The package build emits production JSX while keeping React and React DOM external. The built /frontend renderer is tested with both production and development consumer React peers, including its loading state and loaded component props.

Enum value spelling

Repository-owned enum values use lower snake_case. This includes component kinds, dataset statuses, schema consumer profiles, and hosted contribution identity. Notification enum values retain their existing spelling. External protocol values, including HTTP methods and JSON Schema keywords and formats, retain the protocol spelling.