@process.co/element-types 0.0.8 → 0.0.10

package/src/authoring-contract.ts

@@ -0,0 +1,243 @@
+import type {
+  MaterializedActionAuthoringEntry,
+  MaterializedAuthoringCatalog,
+  MaterializedSignalAuthoringEntry,
+} from './materialize-authoring-from-cli-output';
+import type { MaterializedSlotBranch, MaterializedSlotDefinition } from './materialize-slot-definition';
+import type { ProcessElementCliOutputWire } from './process-element-cli-output';
+import { materializeAuthoringCatalogFromCliOutput } from './materialize-authoring-from-cli-output';
+
+/**
+ * Bump when this contract changes — regenerate workflow-sdk / codegen consumers.
+ * Raw CLI JSON does not carry this; the **contract** is the stable TS surface.
+ */
+export const ELEMENT_AUTHORING_CONTRACT_VERSION = 1 as const;
+
+/**
+ * Normalized prop kind for **`keyof` / conditional types** (not the raw loader string).
+ */
+export type AuthoringPropWireKind =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'integer'
+  | 'object'
+  | 'array'
+  | 'unknown';
+
+/** One action prop in the **locked** authoring shape. */
+export interface AuthoringPropContract {
+  readonly key: string;
+  readonly label: string;
+  readonly wireKind: AuthoringPropWireKind;
+  readonly required: boolean;
+}
+
+/**
+ * One container branch. **`childStepsProperty`** is intentionally a **string literal type** so
+ * `defineGroup`-style APIs can use `B['childStepsProperty']` and get `'actions'`, not `string`.
+ */
+export interface SlotBranchAuthoringContract {
+  readonly kind: 'static' | 'dynamic';
+  readonly slotRowId?: string;
+  readonly paths: Readonly<{
+    row?: string;
+    id?: string;
+    label?: string;
+    enabled?: string;
+    actions?: string;
+    exports?: string;
+  }>;
+  /**
+   * Where nested steps attach on each branch row, relative to that row’s object.
+   * Locked default **`actions`**; override only if element contract documents otherwise.
+   */
+  readonly childStepsProperty: 'actions';
+  /** Branch-level export callback property when present (e.g. switch **`export`**). */
+  readonly branchExportsProperty?: 'export' | 'exports';
+}
+
+export interface SlotsAuthoringContract {
+  readonly layout: Readonly<{
+    showBranchLabels?: boolean;
+    activeSlotId?: string;
+    activeSlotLabel?: string;
+    hideDisabled?: boolean;
+    hideDisabledPath?: string;
+    hideOnDisable?: boolean;
+    exportSchemaPath?: string;
+  }>;
+  readonly branches: readonly SlotBranchAuthoringContract[];
+}
+
+/** Locked per-action shape for FERN-keyed inference. */
+export interface ActionAuthoringContract {
+  readonly fern: string;
+  readonly elementKey: string;
+  readonly name: string;
+  readonly returnsTypeName?: string;
+  readonly props: readonly AuthoringPropContract[];
+  readonly slots: SlotsAuthoringContract | null;
+}
+
+export interface SignalAuthoringContract {
+  readonly fern: string;
+  readonly elementKey: string;
+  readonly name: string;
+  readonly returnsTypeName?: string;
+  readonly props: readonly AuthoringPropContract[];
+}
+
+/**
+ * **Canonical object** for TypeScript to hang inference off — not the CLI blob.
+ *
+ * - Runtime: **`authoringCatalogContractFromCliOutput`** / **`toAuthoringCatalogContract`**.
+ * - Best inference: codegen emits **`export const X = { … } as const satisfies ElementAuthoringCatalogContract`**
+ *   so **`keyof X['actions']`** is a **union of FERN literals**, not plain **`string`**.
+ */
+export interface ElementAuthoringCatalogContract {
+  readonly version: typeof ELEMENT_AUTHORING_CONTRACT_VERSION;
+  readonly namespace: string;
+  readonly actions: Readonly<Record<string, ActionAuthoringContract>>;
+  readonly signals: Readonly<Record<string, SignalAuthoringContract>>;
+}
+
+// --- Type-level helpers (the “magic” entry points) -------------------------------------------
+
+export type ChildStepsPropertyForBranch<B extends SlotBranchAuthoringContract> = B['childStepsProperty'];
+
+export type ActionPropKeys<A extends ActionAuthoringContract> = A['props'][number]['key'];
+
+export type ActionContractByFern<
+  C extends ElementAuthoringCatalogContract,
+  Fern extends keyof C['actions'] & string,
+> = C['actions'][Fern];
+
+// --- Normalization: materialized → contract ---------------------------------------------------
+
+function normalizeWireKind(wireType: string): AuthoringPropWireKind {
+  const t = wireType.trim().toLowerCase();
+  if (t === 'string' || t === 'number' || t === 'boolean' || t === 'integer') {
+    return t as AuthoringPropWireKind;
+  }
+  if (t === 'object' || t.startsWith('object(')) {
+    return 'object';
+  }
+  if (t === 'array' || t.startsWith('array<')) {
+    return 'array';
+  }
+  return 'unknown';
+}
+
+function inferBranchExportsProperty(branch: MaterializedSlotBranch): 'export' | 'exports' | undefined {
+  const e = branch.exportsPath;
+  if (e === undefined) {
+    return undefined;
+  }
+  if (e.endsWith('.export') || e.includes('.export.')) {
+    return 'export';
+  }
+  if (e.endsWith('.exports') || e.includes('.exports.')) {
+    return 'exports';
+  }
+  return undefined;
+}
+
+function branchToContract(branch: MaterializedSlotBranch): SlotBranchAuthoringContract {
+  const exportsProp = inferBranchExportsProperty(branch);
+  return {
+    kind: branch.kind,
+    slotRowId: branch.id,
+    paths: {
+      row: branch.path,
+      id: branch.idPath,
+      label: branch.labelPath,
+      enabled: branch.enabledPath,
+      actions: branch.actionsPath,
+      exports: branch.exportsPath,
+    },
+    childStepsProperty: 'actions',
+    ...(exportsProp !== undefined ? { branchExportsProperty: exportsProp } : {}),
+  };
+}
+
+function slotsToContract(slots: MaterializedSlotDefinition | null): SlotsAuthoringContract | null {
+  if (slots === null) {
+    return null;
+  }
+  return {
+    layout: { ...slots.layout },
+    branches: slots.branches.map(branchToContract),
+  };
+}
+
+function propToContract(p: { key: string; label: string; wireType: string; required: boolean }): AuthoringPropContract {
+  return {
+    key: p.key,
+    label: p.label,
+    wireKind: normalizeWireKind(p.wireType),
+    required: p.required,
+  };
+}
+
+function actionToContract(a: MaterializedActionAuthoringEntry): ActionAuthoringContract {
+  return {
+    fern: a.fern,
+    elementKey: a.elementKey,
+    name: a.name,
+    returnsTypeName: a.returns,
+    props: a.props.map(propToContract),
+    slots: slotsToContract(a.slots),
+  };
+}
+
+function signalToContract(s: MaterializedSignalAuthoringEntry): SignalAuthoringContract {
+  return {
+    fern: s.fern,
+    elementKey: s.elementKey,
+    name: s.name,
+    returnsTypeName: s.returns,
+    props: s.props.map(propToContract),
+  };
+}
+
+/**
+ * Map **loose materialized catalog** (from CLI JSON) into the **locked `ElementAuthoringCatalogContract`**.
+ */
+export function toAuthoringCatalogContract(cat: MaterializedAuthoringCatalog): ElementAuthoringCatalogContract {
+  const actions: Record<string, ActionAuthoringContract> = {};
+  const signals: Record<string, SignalAuthoringContract> = {};
+  for (const [fern, a] of Object.entries(cat.actionsByFern)) {
+    actions[fern] = actionToContract(a);
+  }
+  for (const [fern, s] of Object.entries(cat.signalsByFern)) {
+    signals[fern] = signalToContract(s);
+  }
+  return {
+    version: ELEMENT_AUTHORING_CONTRACT_VERSION,
+    namespace: cat.namespace,
+    actions,
+    signals,
+  };
+}
+
+/** One-shot: **`process-element` JSON shape** → locked contract. */
+export function authoringCatalogContractFromCliOutput(
+  info: ProcessElementCliOutputWire,
+  namespace?: string,
+): ElementAuthoringCatalogContract {
+  return toAuthoringCatalogContract(materializeAuthoringCatalogFromCliOutput(info, namespace));
+}
+
+/**
+ * **Early** artifact: one file per element / build, written by **`@process.co/compatibility`**.
+ * **Late** step merges many shards into **`workflow-sdk`** `fern-authoring-registry.generated.ts`.
+ */
+export type FernAuthoringShardFileV1 = {
+  readonly version: typeof ELEMENT_AUTHORING_CONTRACT_VERSION;
+  /** Source path or id (optional, for debugging). */
+  readonly source?: string;
+  readonly namespace: string;
+  readonly actions: Record<string, ActionAuthoringContract>;
+  readonly signals: Record<string, SignalAuthoringContract>;
+};

package/src/builtin-action-slots-registry.ts

@@ -0,0 +1,36 @@
+import type { ISlotDefinition } from './slot-definition';
+
+/**
+ * Optional bootstrap registry (FERN → **`ISlotDefinition`**).
+ * Prefer driving inference from **`@process.co/compatibility`** **`authoring-spec`** **`materializeAuthoringCatalogFromCliOutput`**
+ * on the full **`process-element` / `loadElementPointers`** JSON — that includes **props**, **returns**, and **slots**.
+ */
+export const builtinActionSlotsRegistry = {
+  'process-internal::action:switch': {
+    hideDisabled: true,
+    slots: [
+      {
+        type: 'static' as const,
+        id: '{{ID_GUID}}_default_case',
+        labelPath: '$.data.cases.defaultLabel',
+        enabledPath: '$.data.cases.defaultEnabled',
+        hideOnDisable: true,
+      },
+      {
+        path: '$.data.cases.cases[*]',
+        idPath: '$.data.cases.cases[*].id',
+        labelPath: '$.data.cases.cases[*].label',
+        enabledPath: '$.data.cases.cases[*].enabled',
+        hideOnDisable: true,
+      },
+    ],
+  } satisfies ISlotDefinition,
+} as const;
+
+export type BuiltinActionSlotsRegistry = typeof builtinActionSlotsRegistry;
+
+export type BuiltinActionSlotsFern = keyof BuiltinActionSlotsRegistry;
+
+export type InferBuiltinActionSlots<Fern extends string> = Fern extends BuiltinActionSlotsFern
+  ? BuiltinActionSlotsRegistry[Fern]
+  : undefined;

package/src/index.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import type { z } from 'zod';
 
 // Element types
@@ -15,35 +16,49 @@ export type ElementSignal<T> = { type: "signal"; icon?: ElementIcon; label?: str
 
 export type ElementIcon = { type: "FontAwesome" | "MaterialIcons" | "ProcessIcons" | "RemoteImage" | "image"; icon: string | ['far' | 'fas' | 'fab' | 'fal' | 'fad', string] } | string;
 
-export type ISlotInstanceDefinition = {
-    id?: string;
-    label?: string;
-    enabled?: boolean;
-    path?: string;
-    idPath?: string;
-    labelPath?: string;
-    enabledPath?: string;
-    labelPlaceholderTemplate?: string;
-    labelPlaceholderValue?: string;
-    branchValue?: string;
-    hideOnDisable?: boolean;
-    actionsPath?: string;
-    exportsPath?: string;
-}
-
-export type ISlotStaticInstanceDefinition = ISlotInstanceDefinition & {
-    type: "static";
-}
-
-export type ISlotDefinition = {
-    showBranchLabels?: boolean;
-    activeSlotId?: string;
-    activeSlotLabel?: string;
-    hideDisabled?: boolean;
-    hideOnDisable?: boolean;
-    exportSchemaPath?: string;
-    slots?: (ISlotInstanceDefinition | ISlotStaticInstanceDefinition)[];
-}
+import type {
+    ISlotInstanceDefinition,
+    ISlotStaticInstanceDefinition,
+    ISlotDefinition,
+} from './slot-definition';
+
+export type { ISlotInstanceDefinition, ISlotStaticInstanceDefinition, ISlotDefinition };
+
+export {
+    builtinActionSlotsRegistry,
+    type BuiltinActionSlotsRegistry,
+    type BuiltinActionSlotsFern,
+    type InferBuiltinActionSlots,
+} from './builtin-action-slots-registry';
+
+/** Full **`process-element` CLI** JSON shape (types only; materialize in **`@process.co/compatibility`** **`authoring-spec`**). */
+export type {
+    ProcessElementPropCliWire,
+    ProcessElementActionCliWire,
+    ProcessElementSignalCliWire,
+    ProcessElementCliOutputWire,
+} from './process-element-cli-output';
+
+/** Locked authoring catalog **types** + version (runtime materialize: **`@process.co/compatibility`** **`authoring-spec`**). */
+export { ELEMENT_AUTHORING_CONTRACT_VERSION } from './authoring-contract-types';
+export type {
+    AuthoringPropWireKind,
+    AuthoringPropContract,
+    SlotBranchAuthoringContract,
+    SlotsAuthoringContract,
+    ActionAuthoringContract,
+    SignalAuthoringContract,
+    ElementAuthoringCatalogContract,
+    ChildStepsPropertyForBranch,
+    ActionPropKeys,
+    ActionContractByFern,
+    FernAuthoringShardFileV1,
+} from './authoring-contract-types';
+
+export {
+  PLATFORM_BOUND_LOADER_TYPE_PREFIXES,
+  isPlatformBoundLoaderType,
+} from './platform-loader-type';
 
 // Base types for module definitions
 export type ModuleDefinition = {

package/src/materialize-authoring-from-cli-output.ts

@@ -0,0 +1,157 @@
+import { materializeSlotDefinition, type MaterializedSlotDefinition } from './materialize-slot-definition';
+import type {
+  ProcessElementActionCliWire,
+  ProcessElementCliOutputWire,
+  ProcessElementPropCliWire,
+  ProcessElementSignalCliWire,
+} from './process-element-cli-output';
+
+export type MaterializedPropAuthoring = {
+  key: string;
+  label: string;
+  description: string;
+  /** String from loader **`type`** (e.g. **`string`**, **`object`**, or zodex-serialized object as JSON). */
+  wireType: string;
+  required: boolean;
+  hasJsonType: boolean;
+  isFunction: boolean;
+};
+
+export type MaterializedActionAuthoringEntry = {
+  kind: 'action';
+  fern: string;
+  /** Raw action key from the element (may include namespace prefix). */
+  elementKey: string;
+  name: string;
+  description?: string;
+  returns?: string;
+  props: MaterializedPropAuthoring[];
+  slots: MaterializedSlotDefinition | null;
+};
+
+export type MaterializedSignalAuthoringEntry = {
+  kind: 'signal';
+  fern: string;
+  elementKey: string;
+  name: string;
+  description?: string;
+  returns?: string;
+  props: MaterializedPropAuthoring[];
+};
+
+export type MaterializedAuthoringCatalog = {
+  namespace: string;
+  actionsByFern: Record<string, MaterializedActionAuthoringEntry>;
+  signalsByFern: Record<string, MaterializedSignalAuthoringEntry>;
+};
+
+function stripNamespacePrefixFromActionKey(namespace: string, key: string): string {
+  const prefix = `${namespace}-`;
+  return key.startsWith(prefix) ? key.slice(prefix.length) : key;
+}
+
+/**
+ * Build registry FERN for an action (**`namespace::action:slug`**), matching common API normalization.
+ */
+export function buildProcessActionFern(namespace: string, actionKey: string): string {
+  const slug = stripNamespacePrefixFromActionKey(namespace, actionKey);
+  return `${namespace}::action:${slug}`;
+}
+
+/** Build registry FERN for a signal (**`namespace::signal:slug`**). */
+export function buildProcessSignalFern(namespace: string, signalKey: string): string {
+  const slug = stripNamespacePrefixFromActionKey(namespace, signalKey);
+  return `${namespace}::signal:${slug}`;
+}
+
+function wireTypeLabel(type: unknown): string {
+  if (type === undefined || type === null) {
+    return 'unknown';
+  }
+  if (typeof type === 'string') {
+    return type;
+  }
+  try {
+    return JSON.stringify(type);
+  } catch {
+    return 'unknown';
+  }
+}
+
+function materializeProp(p: ProcessElementPropCliWire): MaterializedPropAuthoring {
+  return {
+    key: p.key,
+    label: p.label,
+    description: typeof p.description === 'string' ? p.description : '',
+    wireType: wireTypeLabel(p.type),
+    required: p.required === true,
+    hasJsonType: p.jsonType !== undefined && p.jsonType !== null,
+    isFunction: p.isFunction === true,
+  };
+}
+
+function materializeAction(
+  namespace: string,
+  a: ProcessElementActionCliWire,
+): MaterializedActionAuthoringEntry {
+  const fern = buildProcessActionFern(namespace, a.key);
+  return {
+    kind: 'action',
+    fern,
+    elementKey: a.key,
+    name: a.name,
+    description: typeof a.description === 'string' ? a.description : undefined,
+    returns: typeof a.returns === 'string' ? a.returns : undefined,
+    props: (Array.isArray(a.props) ? a.props : []).map(materializeProp),
+    slots: materializeSlotDefinition(a.slots),
+  };
+}
+
+function materializeSignal(
+  namespace: string,
+  s: ProcessElementSignalCliWire,
+): MaterializedSignalAuthoringEntry {
+  const fern = buildProcessSignalFern(namespace, s.key);
+  return {
+    kind: 'signal',
+    fern,
+    elementKey: s.key,
+    name: s.name,
+    description: typeof s.description === 'string' ? s.description : undefined,
+    returns: typeof s.returns === 'string' ? s.returns : undefined,
+    props: (Array.isArray(s.props) ? s.props : []).map(materializeProp),
+  };
+}
+
+/**
+ * Turn the **entire compatibility CLI / `loadElementPointers` JSON** into FERN-keyed authoring material
+ * (props + slot paths + returns hints) for codegen or merging into **`@process.co/workflow-sdk`**.
+ *
+ * @param namespace — FERN namespace segment (e.g. **`process-internal`**). Defaults to **`info.name`** (element app slug).
+ */
+export function materializeAuthoringCatalogFromCliOutput(
+  info: ProcessElementCliOutputWire,
+  namespace?: string,
+): MaterializedAuthoringCatalog {
+  const ns = namespace ?? info.name;
+  const actionsByFern: Record<string, MaterializedActionAuthoringEntry> = {};
+  const signalsByFern: Record<string, MaterializedSignalAuthoringEntry> = {};
+
+  for (const a of info.actions) {
+    if (a?.type !== 'action' || typeof a.key !== 'string') {
+      continue;
+    }
+    const entry = materializeAction(ns, a as ProcessElementActionCliWire);
+    actionsByFern[entry.fern] = entry;
+  }
+
+  for (const s of info.signals) {
+    if (s?.type !== 'signal' || typeof s.key !== 'string') {
+      continue;
+    }
+    const entry = materializeSignal(ns, s as ProcessElementSignalCliWire);
+    signalsByFern[entry.fern] = entry;
+  }
+
+  return { namespace: ns, actionsByFern, signalsByFern };
+}

package/src/materialize-slot-definition.ts

@@ -0,0 +1,88 @@
+import type {
+  ISlotDefinition,
+  ISlotInstanceDefinition,
+  ISlotStaticInstanceDefinition,
+} from './slot-definition';
+
+export type MaterializedSlotBranch = {
+  kind: 'static' | 'dynamic';
+  id?: string;
+  label?: string;
+  branchValue?: string;
+  path?: string;
+  idPath?: string;
+  labelPath?: string;
+  enabledPath?: string;
+  actionsPath?: string;
+  exportsPath?: string;
+  hideOnDisable?: boolean;
+  labelPlaceholderTemplate?: string;
+  labelPlaceholderValue?: string;
+};
+
+export type MaterializedSlotLayout = {
+  showBranchLabels?: boolean;
+  activeSlotId?: string;
+  activeSlotLabel?: string;
+  hideDisabled?: boolean;
+  hideDisabledPath?: string;
+  hideOnDisable?: boolean;
+  exportSchemaPath?: string;
+};
+
+export type MaterializedSlotDefinition = {
+  layout: MaterializedSlotLayout;
+  branches: MaterializedSlotBranch[];
+};
+
+function branchKind(row: ISlotInstanceDefinition | ISlotStaticInstanceDefinition): 'static' | 'dynamic' {
+  return 'type' in row && row.type === 'static' ? 'static' : 'dynamic';
+}
+
+function pickBranch(row: ISlotInstanceDefinition | ISlotStaticInstanceDefinition): MaterializedSlotBranch {
+  const b: MaterializedSlotBranch = { kind: branchKind(row) };
+  if (row.id !== undefined) b.id = row.id;
+  if (row.label !== undefined) b.label = row.label;
+  if (row.branchValue !== undefined) b.branchValue = row.branchValue;
+  if (row.path !== undefined) b.path = row.path;
+  if (row.idPath !== undefined) b.idPath = row.idPath;
+  if (row.labelPath !== undefined) b.labelPath = row.labelPath;
+  if (row.enabledPath !== undefined) b.enabledPath = row.enabledPath;
+  if (row.actionsPath !== undefined) b.actionsPath = row.actionsPath;
+  if (row.exportsPath !== undefined) b.exportsPath = row.exportsPath;
+  if (row.hideOnDisable !== undefined) b.hideOnDisable = row.hideOnDisable;
+  if (row.labelPlaceholderTemplate !== undefined) b.labelPlaceholderTemplate = row.labelPlaceholderTemplate;
+  if (row.labelPlaceholderValue !== undefined) b.labelPlaceholderValue = row.labelPlaceholderValue;
+  return b;
+}
+
+function pickLayout(def: ISlotDefinition): MaterializedSlotLayout {
+  const layout: MaterializedSlotLayout = {};
+  if (def.showBranchLabels !== undefined) layout.showBranchLabels = def.showBranchLabels;
+  if (def.activeSlotId !== undefined) layout.activeSlotId = def.activeSlotId;
+  if (def.activeSlotLabel !== undefined) layout.activeSlotLabel = def.activeSlotLabel;
+  if (def.hideDisabled !== undefined) layout.hideDisabled = def.hideDisabled;
+  if (def.hideDisabledPath !== undefined) layout.hideDisabledPath = def.hideDisabledPath;
+  if (def.hideOnDisable !== undefined) layout.hideOnDisable = def.hideOnDisable;
+  if (def.exportSchemaPath !== undefined) layout.exportSchemaPath = def.exportSchemaPath;
+  return layout;
+}
+
+function isEffectivelyEmpty(def: ISlotDefinition): boolean {
+  const rows = def.slots ?? [];
+  const layout = pickLayout(def);
+  return rows.length === 0 && Object.keys(layout).length === 0;
+}
+
+/** Normalize **`ISlotDefinition`** for codegen / workflow inference (JSON-serializable). */
+export function materializeSlotDefinition(
+  def: ISlotDefinition | null | undefined,
+): MaterializedSlotDefinition | null {
+  if (def == null || isEffectivelyEmpty(def)) {
+    return null;
+  }
+  return {
+    layout: pickLayout(def),
+    branches: (def.slots ?? []).map(pickBranch),
+  };
+}

package/src/platform-loader-type.ts

@@ -0,0 +1,14 @@
+/**
+ * **`prop.type`** string prefixes that bind to runtime platform implementations
+ * (**`$.interface.http`**, **`$.service.db`**, **`$.interface.timer`**, …).
+ *
+ * Keep in sync with:
+ * - **`@process.co/compatibility`** authoring registry (**`excludeFromAuthoringInstanceShape`**)
+ * - **`apps/web`** expression validation / console (skip misleading type-mismatch noise)
+ */
+export const PLATFORM_BOUND_LOADER_TYPE_PREFIXES = ['$.interface.', '$.service.'] as const;
+
+export function isPlatformBoundLoaderType(type: string): boolean {
+  const t = type.trim();
+  return PLATFORM_BOUND_LOADER_TYPE_PREFIXES.some((p) => t.startsWith(p));
+}