@collective-intelligence/extensions-sdk-frontend-react 0.0.0-stage → 0.1.1

package/dist/workflows/field-editor/workflow-field-frame.d.ts

@@ -0,0 +1,53 @@
+import type { JsonValue, WorkflowJsonSchema } from "../contracts";
+import type { AuthoredExpressionValue, ExpressionEnvironment, ExpressionValidation, ExpressionMode } from "../expressions/domain";
+export interface WorkflowFieldFrameDraft {
+    mode: ExpressionMode;
+    fixed: JsonValue;
+    expression: string;
+}
+interface FixedControlProps {
+    controlId?: string;
+    describedBy?: string;
+    disabled: boolean;
+    labelledBy?: string;
+    onChange: (value: JsonValue) => void;
+    value: JsonValue;
+}
+interface ExpressionControlProps {
+    controlId?: string;
+    describedBy?: string;
+    disabled: boolean;
+    labelledBy?: string;
+    onChange: (source: string) => void;
+    value: string;
+}
+interface WorkflowFieldFrameDiagnostic {
+    code: string;
+    message: string;
+    severity: string;
+}
+export declare const WorkflowFieldFrame: ({ allowExpression, allowFixed, controlId, diagnostics, expressionEditor, expressionMultiline, help, label, onValueChange, readOnly, renderExpression, renderFixed, required, sensitive, value }: {
+    allowExpression?: boolean;
+    allowFixed?: boolean;
+    controlId?: string;
+    diagnostics?: readonly WorkflowFieldFrameDiagnostic[];
+    expressionEditor?: {
+        environment?: ExpressionEnvironment;
+        error?: string;
+        loading?: boolean;
+        validate?: (source: string, signal: AbortSignal) => Promise<ExpressionValidation>;
+        /** Bound field schema; ranks suggestions by type compatibility. */
+        targetSchema?: WorkflowJsonSchema;
+    };
+    expressionMultiline?: boolean;
+    help?: string;
+    label: string;
+    onValueChange: (value: AuthoredExpressionValue) => void;
+    readOnly?: boolean;
+    renderExpression?: (props: ExpressionControlProps) => React.ReactNode;
+    renderFixed: (props: FixedControlProps) => React.ReactNode;
+    required?: boolean;
+    sensitive?: boolean;
+    value: AuthoredExpressionValue;
+}) => import("react").JSX.Element;
+export {};

package/dist/workflows/field-resolver.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from "react";
+import type { WorkflowFieldComponentContext } from "./workflow-types";
+export declare const WorkflowFieldResolver: ({ context }: {
+    context: WorkflowFieldComponentContext;
+}) => ReactNode;

package/dist/workflows/field-type-select/catalog.d.ts

@@ -0,0 +1,22 @@
+import type { EffectiveWorkflowCatalog, JsonObject } from "../contracts";
+import type { WorkflowFieldTypeCollection } from "./field-type-select";
+type JsonSchema = JsonObject;
+export interface AvailableWorkflowField {
+    catalogTemplateId: string;
+    configSchema: JsonSchema;
+    fqn: string;
+    version: string;
+    label: string;
+    schema: JsonSchema;
+    collectionKey: string;
+}
+export interface AvailableWorkflowFieldCollection {
+    key: string;
+    label: string;
+    weight: number;
+    fields: AvailableWorkflowField[];
+}
+export declare const fieldCollectionsFromCatalog: (catalog: EffectiveWorkflowCatalog | undefined, boundary: "input" | "output") => AvailableWorkflowFieldCollection[];
+export declare const toFieldTypeCollection: (collection: AvailableWorkflowFieldCollection) => WorkflowFieldTypeCollection;
+export declare const schemaForWorkflowField: (schema: JsonSchema, field: AvailableWorkflowField) => JsonSchema;
+export {};

package/dist/workflows/field-type-select/field-type-select.d.ts

@@ -0,0 +1,18 @@
+export interface WorkflowFieldTypeOption {
+    fqn: string;
+    version: string;
+    label: string;
+    searchTerms?: readonly string[];
+}
+export interface WorkflowFieldTypeCollection {
+    key: string;
+    label: string;
+    options: readonly WorkflowFieldTypeOption[];
+}
+export declare const fieldTypeIdentity: (field: Pick<WorkflowFieldTypeOption, "fqn" | "version">) => string;
+export declare const FieldTypeSelect: ({ collections, value, onChange, ariaLabel }: {
+    collections: readonly WorkflowFieldTypeCollection[];
+    value: string;
+    onChange: (option: WorkflowFieldTypeOption) => void;
+    ariaLabel?: string;
+}) => import("react").JSX.Element;

package/dist/workflows/index.d.ts

@@ -0,0 +1,26 @@
+export { activateDashboardWorkflowCatalog, activateWorkflowCatalog, dashboardWorkflowPackage, parseWorkflowTemplateKind, resolveWorkflowField, resolveWorkflowTemplate, workflowCatalogSnapshot } from "./catalog";
+export type { WorkflowCatalogResolution, WorkflowDeclarationMetadata } from "./catalog";
+export { WorkflowFieldConfigurationResolver } from "./field-configuration-resolver";
+export { WorkflowFieldResolver } from "./field-resolver";
+export * from "./contracts";
+export * from "./expressions/domain";
+export * from "./field-editor";
+export * from "./field-editor/expression-slots";
+export * from "./field-type-select/catalog";
+export * from "./field-type-select/field-type-select";
+export { CatalogNodeChartBlock } from "./default-template-ui/actions/catalog-node-chart-block";
+export { CatalogNodeDetailsEditor } from "./default-template-ui/actions/catalog-node-details-editor";
+export { defaultWorkflowTemplateDeclarations } from "./default-template-ui/declarations";
+export { renderDefaultActionChart, renderDefaultActionDetails, renderDefaultInputChart, renderDefaultInputDetails, renderDefaultOutputChart, renderDefaultOutputDetails, renderDefaultTriggerChart, renderDefaultTriggerDetails } from "./default-template-ui/renderers";
+export { WorkflowTemplateDetails } from "./runtime/workflow-template-details";
+export { patchWorkflowFieldPartDisplayValue, patchWorkflowFieldValue, readWorkflowFieldDisplayValue, readWorkflowBindingValue, readWorkflowFieldPartDisplayValue, readWorkflowFieldValue } from "./runtime/field-bindings";
+export type { WorkflowFieldDisplayValue, WorkflowFieldValues } from "./runtime/field-bindings";
+export { isWorkflowFieldVisible } from "./runtime/field-visibility";
+export * from "../runtime/type-guards";
+export { catalogText } from "./default-template-ui/actions/catalog-text";
+export * from "./expression-editor";
+export * from "./expression-editor/source-browser";
+export * from "./options";
+export { normalizeExpressionEnvironment, normalizeExpressionValidation } from "./expressions/domain";
+export type { ExpressionEnvironment, ExpressionValidation } from "./expressions/domain";
+export type { WorkflowCatalogNodeTemplate, WorkflowFieldComponentContext, WorkflowFieldConfigurationContext, WorkflowFieldConfigurationRender, WorkflowFieldRender, WorkflowTemplateChartData, WorkflowTemplateKind, WorkflowTemplateReference, WorkflowTemplateRender, WorkflowTemplateUiCommands, WorkflowTemplateUiContext, WorkflowValueContract } from "./workflow-types";

package/dist/workflows/node-presentation/node-presentation.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentType } from "react";
+export interface WorkflowNodePresentation {
+    label: string;
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    tone: string;
+}
+export declare const workflowNodePresentation: (kind: string) => WorkflowNodePresentation;

package/dist/workflows/options.d.ts

@@ -0,0 +1,28 @@
+import type { FieldOptionPage, JsonObject, JsonValue } from "@collective-intelligence/extensions-sdk";
+import type { InfiniteData, UseInfiniteQueryOptions, UseQueryOptions } from "@tanstack/react-query";
+export type WorkflowFieldOptionsRequest = Readonly<{
+    catalogTemplateId: string;
+    config?: JsonObject;
+    cursor?: string | null;
+    dependencies: JsonObject;
+    limit: number;
+    organizationId: string;
+    ownerWorkflowId?: string;
+    partPath?: readonly string[];
+    search?: string | null;
+}>;
+export type WorkflowFieldOptionsProvider = (request: WorkflowFieldOptionsRequest, signal?: AbortSignal) => Promise<FieldOptionPage<JsonValue>>;
+type WorkflowFieldOptionsQueryInput = WorkflowFieldOptionsRequest & {
+    optionsProvider?: WorkflowFieldOptionsProvider;
+};
+type WorkflowFieldOptionsQueryKey = readonly [
+    "workflow-field-options",
+    WorkflowFieldOptionsRequest
+];
+type WorkflowFieldOptionsQueryOptions = Pick<UseQueryOptions<FieldOptionPage<JsonValue>, Error, FieldOptionPage<JsonValue>, WorkflowFieldOptionsQueryKey>, "queryFn" | "queryKey">;
+type WorkflowFieldOptionsInfiniteQueryOptions = Pick<UseInfiniteQueryOptions<FieldOptionPage<JsonValue>, Error, InfiniteData<FieldOptionPage<JsonValue>>, WorkflowFieldOptionsQueryKey, string | null>, "getNextPageParam" | "initialPageParam" | "queryFn" | "queryKey">;
+/** Installs the Host-owned options adapter for the current contribution graph. */
+export declare const configureWorkflowFieldOptionsProvider: (provider: WorkflowFieldOptionsProvider | undefined) => void;
+export declare const workflowFieldOptions: (input: WorkflowFieldOptionsQueryInput) => WorkflowFieldOptionsQueryOptions;
+export declare const workflowFieldOptionsInfinite: (input: Omit<WorkflowFieldOptionsQueryInput, "cursor">) => WorkflowFieldOptionsInfiniteQueryOptions;
+export {};

package/dist/workflows/runtime/field-bindings.d.ts

@@ -0,0 +1,21 @@
+import type { JsonObject, JsonValue, WorkflowFormField } from "../contracts";
+type RuntimeValue = JsonValue | undefined;
+export interface WorkflowFieldValues {
+    config: JsonObject;
+    inputs: JsonObject;
+    settings: JsonObject;
+    metadata?: JsonObject;
+}
+export interface WorkflowFieldDisplayValue extends JsonObject {
+    label: string;
+    value: JsonValue;
+}
+/** Reads a bound value, unwrapping fixed envelopes at every path segment. */
+export declare const readWorkflowBindingValue: (values: WorkflowFieldValues, binding: WorkflowFormField["binding"]) => RuntimeValue;
+export declare const readWorkflowFieldValue: (values: WorkflowFieldValues, field: WorkflowFormField) => RuntimeValue;
+/** Retains unclaimed sibling values when a known catalog field is edited. */
+export declare const patchWorkflowFieldValue: (values: WorkflowFieldValues, field: WorkflowFormField, nextValue: JsonValue, displayOption?: WorkflowFieldDisplayValue | null) => Partial<WorkflowFieldValues>;
+export declare const readWorkflowFieldDisplayValue: (values: WorkflowFieldValues, field: WorkflowFormField) => WorkflowFieldDisplayValue | undefined;
+export declare const readWorkflowFieldPartDisplayValue: (values: WorkflowFieldValues, field: WorkflowFormField, partPath: (string | number)[]) => WorkflowFieldDisplayValue | undefined;
+export declare const patchWorkflowFieldPartDisplayValue: (values: WorkflowFieldValues, field: WorkflowFormField, partPath: (string | number)[], displayOption: WorkflowFieldDisplayValue | null) => Partial<WorkflowFieldValues>;
+export {};

package/dist/workflows/runtime/field-visibility.d.ts

@@ -0,0 +1,7 @@
+import type { WorkflowFormField } from "../contracts";
+import type { WorkflowFieldValues } from "./field-bindings";
+/**
+ * Evaluates declared visibility rules against authored node values. Stored
+ * values are `{mode: "fixed"}` envelopes; rules compare the plain value.
+ */
+export declare const isWorkflowFieldVisible: (field: Pick<WorkflowFormField, "visibleWhen">, values: WorkflowFieldValues) => boolean;

package/dist/workflows/runtime/load-workflow-module.d.ts

@@ -0,0 +1,4 @@
+import type { FrontendComponentDeclaration } from "@collective-intelligence/extensions-sdk-frontend";
+import type { HostedComponentModule } from "../../frontend";
+/** Hosted workflow code must stay within the statically declared module graph. */
+export declare const loadWorkflowModule: <Props extends object>(declaration: FrontendComponentDeclaration, role?: string) => Promise<HostedComponentModule<Props>>;

package/dist/workflows/runtime/workflow-template-details.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowTemplateUiContext } from "../workflow-types";
+export declare const WorkflowTemplateDetails: ({ context }: {
+    context: WorkflowTemplateUiContext;
+}) => import("react").JSX.Element;

package/dist/workflows/workflow-runtime/remote-options-select-field.d.ts

@@ -0,0 +1,4 @@
+import type { WorkflowFieldComponentContext } from "../workflow-types";
+export declare const RemoteOptionsSelectField: ({ context }: {
+    context: WorkflowFieldComponentContext;
+}) => import("react").JSX.Element;

package/dist/workflows/workflow-runtime/translations.d.ts

@@ -0,0 +1,5 @@
+export declare const workflowFieldResolverTranslations: {
+    readonly field: "Field";
+    readonly unavailableConfiguration: (label: string) => string;
+    readonly unavailableControl: (label: string, control: string) => string;
+};

package/dist/workflows/workflow-types.d.ts

@@ -0,0 +1,156 @@
+import type { FieldOption } from "@collective-intelligence/extensions-sdk";
+import type { ComponentType, ReactNode } from "react";
+import { WorkflowTemplateKinds } from "@collective-intelligence/extensions-sdk";
+import type { EffectiveWorkflowCatalog, EffectiveWorkflowCatalogTemplate, JsonObject, JsonValue, WorkflowFormField, WorkflowFieldProjection, WorkflowJsonSchema, WorkflowOutputContract, WorkflowPortContract, WorkflowTemplateContract } from "./contracts";
+import type { ExpressionEnvironment, ExpressionValidation } from "./expressions/domain";
+import type { WorkflowFieldOptionsProvider } from "./options";
+import type { WorkflowFieldValues } from "./runtime/field-bindings";
+export type WorkflowTemplateKind = (typeof WorkflowTemplateKinds)[number];
+export declare const parseWorkflowTemplateKind: (value: string) => WorkflowTemplateKind | undefined;
+export interface WorkflowTemplateReference {
+    fqn: string;
+    kind: string;
+    version?: string;
+}
+export type WorkflowCatalogNodeTemplate = EffectiveWorkflowCatalogTemplate & {
+    contract: WorkflowTemplateContract;
+    kind: WorkflowTemplateKind;
+};
+export interface WorkflowValueContract {
+    jsonSchema: JsonObject;
+    fieldProjections?: WorkflowFieldProjection[];
+}
+export interface WorkflowTemplateUiCommands {
+    updateNodeConfiguration: (value: JsonObject) => void;
+    updateNodeValues?: (value: Partial<WorkflowFieldValues>) => void;
+    updateInputContract: (value: WorkflowValueContract) => void;
+    updateOutputContract: (value: WorkflowOutputContract) => void;
+    updateTriggerConfiguration?: (value: {
+        config?: JsonObject;
+        settings?: JsonObject;
+        inputBindings?: JsonObject;
+        invocation?: JsonObject;
+    }) => void;
+    closeDetails: () => void;
+}
+export interface WorkflowTemplateChartData {
+    presentation?: {
+        icon: ComponentType<{
+            className?: string;
+        }>;
+        tone: string;
+    };
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    summary?: string;
+    fields?: readonly string[];
+    onOpenDetails: () => void;
+    onAddFromPort?: (port: WorkflowPortContract) => void;
+    connectedOutputPortKeys?: readonly string[];
+}
+export interface WorkflowFieldComponentContext {
+    field: WorkflowFormField;
+    value: JsonValue;
+    readOnly: boolean;
+    mode?: "configuration" | "value" | "read_only";
+    /** Issues of this field; `path` is relative to it, `[index]` for a list row. */
+    diagnostics: readonly {
+        code: string;
+        message: string;
+        severity: string;
+        path?: readonly (string | number)[];
+    }[];
+    options: readonly FieldOption<JsonValue>[];
+    selectedOption?: {
+        label: string;
+        value: JsonValue;
+    };
+    partDisplayValues?: Record<string, {
+        label: string;
+        value: JsonValue;
+    }>;
+    remoteOptions?: {
+        organizationId: string;
+        catalogTemplateId: string;
+        ownerWorkflowId?: string;
+        dependencies?: JsonObject;
+        config?: JsonObject;
+        optionsProvider?: WorkflowFieldOptionsProvider;
+    };
+    schema?: JsonObject;
+    supportsMapping: boolean;
+    expressionEditor?: {
+        environment?: ExpressionEnvironment;
+        loading?: boolean;
+        error?: string;
+        validate?: (source: string, signal: AbortSignal) => Promise<ExpressionValidation>;
+        /** Bound field schema; ranks suggestions by type compatibility. */
+        targetSchema?: WorkflowJsonSchema;
+    };
+    expressionEditorForPath?: (path: (string | number)[]) => WorkflowFieldComponentContext["expressionEditor"];
+    onValueChange: (value: JsonValue, displayOption?: {
+        label: string;
+        value: JsonValue;
+    } | null) => void;
+    onPartDisplayValueChange?: (path: (string | number)[], displayOption: {
+        label: string;
+        value: JsonValue;
+    } | null) => void;
+    openConnectionCreator?: (connectionTemplateFqn: string, onCreated: (connectionId: string) => void) => void;
+}
+export interface WorkflowFieldConfigurationContext {
+    field: {
+        catalogTemplateId: string;
+        configSchema: JsonObject;
+        fqn: string;
+        label: string;
+        version: string;
+    };
+    config: JsonObject;
+    readOnly: boolean;
+    remoteOptions?: {
+        organizationId: string;
+        catalogTemplateId: string;
+        optionsProvider?: WorkflowFieldOptionsProvider;
+    };
+    onChange: (config: JsonObject) => void;
+}
+export interface WorkflowTemplateUiContext {
+    template: WorkflowCatalogNodeTemplate;
+    nodeId: string | null;
+    ports: readonly WorkflowPortContract[];
+    readOnly: boolean;
+    loading: boolean;
+    diagnostics: readonly {
+        code: string;
+        message: string;
+        severity: string;
+        path?: readonly (string | number)[];
+    }[];
+    workflowContracts?: {
+        inputContract: WorkflowValueContract;
+        outputContract: WorkflowOutputContract;
+    };
+    workflowCatalog?: EffectiveWorkflowCatalog;
+    organizationId?: string;
+    availableOutputPorts?: readonly {
+        value: string;
+        label: string;
+    }[];
+    trigger?: {
+        inputBindings: JsonObject;
+        invocation: JsonObject;
+    };
+    /** Live backend validator for the expression bound to one workflow input key. */
+    triggerInputExpressionValidator?: (inputKey: string) => ((source: string, signal: AbortSignal) => Promise<ExpressionValidation>) | undefined;
+    nodeValues?: WorkflowFieldValues;
+    getDynamicInputFieldContext?: (field: WorkflowFormField) => WorkflowFieldComponentContext;
+    isFieldVisible?: (field: WorkflowFormField) => boolean;
+    chart: WorkflowTemplateChartData;
+    getFieldContext?: (field: WorkflowFormField) => WorkflowFieldComponentContext;
+    commands: WorkflowTemplateUiCommands;
+}
+export type WorkflowTemplateRender = (context: WorkflowTemplateUiContext) => ReactNode;
+export type WorkflowFieldRender = (context: WorkflowFieldComponentContext) => ReactNode;
+export type WorkflowFieldConfigurationRender = (context: WorkflowFieldConfigurationContext) => ReactNode;

package/package.json

@@ -1,6 +1,103 @@
 {
   "name": "@collective-intelligence/extensions-sdk-frontend-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Public hosted React contribution contracts for Collective Intelligence extensions.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "ci-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./dashboard": {
+      "ci-source": "./src/dashboard.ts",
+      "types": "./dist/dashboard.d.ts",
+      "import": "./dist/dashboard.js",
+      "default": "./dist/dashboard.js"
+    },
+    "./workflow": {
+      "ci-source": "./src/workflow.ts",
+      "types": "./dist/workflows/index.d.ts",
+      "import": "./dist/workflow.js",
+      "default": "./dist/workflow.js"
+    },
+    "./studio": {
+      "ci-source": "./src/studio.ts",
+      "types": "./dist/studio.d.ts",
+      "import": "./dist/studio.js",
+      "default": "./dist/studio.js"
+    },
+    "./ui-react": {
+      "ci-source": "./src/ui-react.ts",
+      "types": "./dist/ui-react.d.ts",
+      "import": "./dist/ui-react.js",
+      "default": "./dist/ui-react.js"
+    },
+    "./frontend": {
+      "ci-source": "./src/frontend/index.tsx",
+      "types": "./dist/frontend/index.d.ts",
+      "import": "./dist/frontend/index.js",
+      "default": "./dist/frontend/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun tools/build.ts",
+    "test": "bun test src tools && bun run test:pack && vitest run test/frontend-runtime.test.tsx test/built-runtime.test.ts test/workflow-field-help.test.tsx",
+    "test:unit": "bun test src",
+    "test:pack": "bun tools/test-pack.ts",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "format:check:staged": "oxfmt --check",
+    "lint": "node \"../../../.agents/scripts/managed-lint-runner.mjs\" --scope \"packages/public/extensions-sdk-frontend-react\"",
+    "lint:staged": "oxlint --no-error-on-unmatched-pattern",
+    "prepack": "bun run build",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@collective-intelligence/extensions-sdk": "0.1.1",
+    "@collective-intelligence/extensions-sdk-frontend": "0.1.1"
+  },
+  "peerDependencies": {
+    "@collective-intelligence/ui-react": "0.1.1",
+    "@tanstack/react-query": ">=5 <6",
+    "@xyflow/react": ">=12 <13",
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
+  },
+  "peerDependenciesMeta": {
+    "@collective-intelligence/ui-react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@collective-intelligence/ui-react": "workspace:*",
+    "@oxlint/plugins": "1.85.0",
+    "@tanstack/react-query": "5.101.4",
+    "@testing-library/react": "^16.3.2",
+    "@types/bun": "1.3.14",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@xyflow/react": "^12.10.2",
+    "eslint-plugin-react-you-might-not-need-an-effect": "latest",
+    "jsdom": "^28.1.0",
+    "oxfmt": "0.66.0",
+    "oxlint": "1.82.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "5.9.3",
+    "ultracite": "7.10.7",
+    "vitest": "^3.2.7",
+    "es-module-lexer": "2.3.2"
+  }
+}