@workbench-kit/field-remap 0.0.1-prototype.0 → 0.0.2-prototype.0.2.10

package/src/domain/shapes/projectShapes.ts

@@ -0,0 +1,116 @@
+/**
+ * Project source/target shape trees for Flow / browse with optional `hidden` filtering.
+ */
+
+import type { MappingEdge, SourceField, TargetSlot } from '../types.js';
+import { pruneMappingEdgesForShapes } from './shapeEdit.js';
+
+export type ProjectShapesOptions = {
+  /**
+   * When `false` (default), omit fields/slots with `hidden: true` (and prune empty
+   * child lists). When `true`, keep hidden nodes for browse / authoring overlays.
+   */
+  readonly includeHidden?: boolean;
+};
+
+function projectSourceNode(field: SourceField, includeHidden: boolean): SourceField | null {
+  if (!includeHidden && field.hidden === true) {
+    return null;
+  }
+  if (!field.children?.length) {
+    return field;
+  }
+  const children = projectSourceFields(field.children, { includeHidden });
+  if (children === field.children) {
+    return field;
+  }
+  return children.length > 0 ? { ...field, children } : { ...field, children: undefined };
+}
+
+function projectTargetNode(slot: TargetSlot, includeHidden: boolean): TargetSlot | null {
+  if (!includeHidden && slot.hidden === true) {
+    return null;
+  }
+  if (!slot.children?.length) {
+    return slot;
+  }
+  const children = projectTargetSlots(slot.children, { includeHidden });
+  if (children === slot.children) {
+    return slot;
+  }
+  return children.length > 0 ? { ...slot, children } : { ...slot, children: undefined };
+}
+
+/** Filter a source field tree by `hidden` (default: omit hidden leaves/branches). */
+export function projectSourceFields(
+  fields: readonly SourceField[],
+  options?: ProjectShapesOptions,
+): readonly SourceField[] {
+  const includeHidden = options?.includeHidden === true;
+  const next: SourceField[] = [];
+  let changed = false;
+  for (const field of fields) {
+    const projected = projectSourceNode(field, includeHidden);
+    if (projected === null) {
+      changed = true;
+      continue;
+    }
+    if (projected !== field) {
+      changed = true;
+    }
+    next.push(projected);
+  }
+  return changed ? next : fields;
+}
+
+/** Filter a target slot tree by `hidden` (default: omit hidden leaves/branches). */
+export function projectTargetSlots(
+  slots: readonly TargetSlot[],
+  options?: ProjectShapesOptions,
+): readonly TargetSlot[] {
+  const includeHidden = options?.includeHidden === true;
+  const next: TargetSlot[] = [];
+  let changed = false;
+  for (const slot of slots) {
+    const projected = projectTargetNode(slot, includeHidden);
+    if (projected === null) {
+      changed = true;
+      continue;
+    }
+    if (projected !== slot) {
+      changed = true;
+    }
+    next.push(projected);
+  }
+  return changed ? next : slots;
+}
+
+export type ProjectShapesInput = {
+  readonly sources: readonly SourceField[];
+  readonly targets: readonly TargetSlot[];
+  readonly edges?: readonly MappingEdge[];
+  readonly options?: ProjectShapesOptions;
+};
+
+export type ProjectShapesResult = {
+  readonly sources: readonly SourceField[];
+  readonly targets: readonly TargetSlot[];
+  readonly edges?: readonly MappingEdge[];
+};
+
+/**
+ * Project sources/targets with `includeHidden`, and optionally prune mapping edges
+ * whose endpoints disappeared from the projected id set.
+ */
+export function projectShapes(input: ProjectShapesInput): ProjectShapesResult {
+  const sources = projectSourceFields(input.sources, input.options);
+  const targets = projectTargetSlots(input.targets, input.options);
+  if (input.edges === undefined) {
+    return { sources, targets };
+  }
+  return {
+    sources,
+    targets,
+    edges: pruneMappingEdgesForShapes(input.edges, sources, targets),
+  };
+}

package/src/domain/shapes/shapeEdit.ts

@@ -0,0 +1,114 @@
+/**
+ * Host-owned shape editing helpers: type patches and edge pruning when ids disappear.
+ */
+
+import { flattenSourceFields, flattenTargetSlots } from '../mapping/treeUtils.js';
+import type { FieldDataType, MappingEdge, SourceField, TargetSlot } from '../types.js';
+
+export const FIELD_DATA_TYPES = [
+  'string',
+  'number',
+  'boolean',
+  'date',
+  'time',
+  'datetime',
+  'object',
+  'array',
+  'unknown',
+] as const satisfies readonly FieldDataType[];
+
+export function isFieldDataType(value: unknown): value is FieldDataType {
+  return typeof value === 'string' && (FIELD_DATA_TYPES as readonly string[]).includes(value);
+}
+
+export function collectSourceFieldIds(fields: readonly SourceField[]): ReadonlySet<string> {
+  return new Set(flattenSourceFields(fields).map((field) => field.id));
+}
+
+export function collectTargetSlotIds(slots: readonly TargetSlot[]): ReadonlySet<string> {
+  return new Set(flattenTargetSlots(slots).map((slot) => slot.id));
+}
+
+function pruneEdgeList(
+  edges: readonly MappingEdge[],
+  sourceIds: ReadonlySet<string>,
+  targetIds: ReadonlySet<string>,
+): MappingEdge[] {
+  const next: MappingEdge[] = [];
+  for (const edge of edges) {
+    if (!sourceIds.has(edge.sourceFieldId) || !targetIds.has(edge.targetSlotId)) {
+      continue;
+    }
+    if (!edge.itemEdges?.length) {
+      next.push(edge);
+      continue;
+    }
+    const itemEdges = pruneEdgeList(edge.itemEdges, sourceIds, targetIds);
+    next.push(itemEdges.length === edge.itemEdges.length ? edge : { ...edge, itemEdges });
+  }
+  return next;
+}
+
+/**
+ * Drop (or trim nested `itemEdges` of) bindings whose source/target ids are gone.
+ * Hosts should call this after shape ingest / structural edits.
+ */
+export function pruneMappingEdgesForShapes(
+  edges: readonly MappingEdge[],
+  sources: readonly SourceField[],
+  targets: readonly TargetSlot[],
+): readonly MappingEdge[] {
+  return pruneEdgeList(edges, collectSourceFieldIds(sources), collectTargetSlotIds(targets));
+}
+
+function mapSourceTree(
+  fields: readonly SourceField[],
+  fieldId: string,
+  mapper: (field: SourceField) => SourceField,
+): SourceField[] {
+  return fields.map((field) => {
+    if (field.id === fieldId) {
+      return mapper(field);
+    }
+    if (!field.children?.length) {
+      return field;
+    }
+    const children = mapSourceTree(field.children, fieldId, mapper);
+    return children === field.children ? field : { ...field, children };
+  });
+}
+
+function mapTargetTree(
+  slots: readonly TargetSlot[],
+  slotId: string,
+  mapper: (slot: TargetSlot) => TargetSlot,
+): TargetSlot[] {
+  return slots.map((slot) => {
+    if (slot.id === slotId) {
+      return mapper(slot);
+    }
+    if (!slot.children?.length) {
+      return slot;
+    }
+    const children = mapTargetTree(slot.children, slotId, mapper);
+    return children === slot.children ? slot : { ...slot, children };
+  });
+}
+
+/** Patch `dataType` on a source field id (nested-aware). */
+export function setSourceFieldDataType(
+  fields: readonly SourceField[],
+  fieldId: string,
+  dataType: FieldDataType,
+): readonly SourceField[] {
+  return mapSourceTree(fields, fieldId, (field) => ({ ...field, dataType }));
+}
+
+/** Patch `dataType` on a target slot id (nested-aware). */
+export function setTargetSlotDataType(
+  slots: readonly TargetSlot[],
+  slotId: string,
+  dataType: FieldDataType,
+): readonly TargetSlot[] {
+  return mapTargetTree(slots, slotId, (slot) => ({ ...slot, dataType }));
+}

package/src/domain/types.ts

@@ -1,182 +1,242 @@
-/**
- * Shared field / slot / edge types for field-remap UIs.
- */
-
-export type FieldDataType =
-  | 'string'
-  | 'number'
-  | 'boolean'
-  | 'date'
-  | 'time'
-  | 'datetime'
-  /**
-   * Plain object (record) — e.g. for `string:template` object → string.
-   */
-  | 'object'
-  /**
-   * Collection hint — badge + array→array wiring.
-   * Optional per-item projection via `MappingEdge.itemSourcePath`.
-   */
-  | 'array'
-  | 'unknown';
-
-export interface SourceField {
-  readonly id: string;
-  readonly label: string;
-  /** Dot-path or capability path hint for hosts. */
-  readonly path?: string;
-  /**
-   * Owning managed shape id when fields are merged from multiple source shapes.
-   * Used by `convertToShape` to pick the correct named input bag.
-   */
-  readonly shapeId?: string;
-  readonly dataType?: FieldDataType;
-  /** Optional sample used by live preview / transform labels. */
-  readonly sampleValue?: unknown;
-  readonly group?: string;
-  readonly children?: readonly SourceField[];
-}
-
-export interface TargetSlot {
-  readonly id: string;
-  readonly label: string;
-  /**
-   * Dot-path used when assembling nested JSON output via `convertToShape`.
-   * When omitted, hosts may fall back to slot id / label.
-   */
-  readonly path?: string;
-  readonly dataType?: FieldDataType;
-  readonly required?: boolean;
-  readonly description?: string;
-  /** Nested slot groups (expand/collapse in the mapper tree). */
-  readonly children?: readonly TargetSlot[];
-}
-
-export interface MappingEdge {
-  readonly id: string;
-  readonly sourceFieldId: string;
-  readonly targetSlotId: string;
-  /**
-   * Ordered transform chain (max 3). Empty / omitted means identity.
-   * Prefer this over `transformId` for new writers.
-   * For arrays: use reduce builtins (`array:join`, `array:first`, …) here after
-   * optional item projection / item transforms.
-   */
-  readonly transformIds?: readonly string[];
-  /**
-   * Legacy single transform. Prefer `transformIds`.
-   * Readers should use `edgeTransformIds` / `normalizeMappingEdge`.
-   * `null` / omitted (with no `transformIds`) means identity (pass-through).
-   */
-  readonly transformId?: string | null;
-  /**
-   * Per-step options aligned with `transformIds` (index N applies to step N).
-   * Prefer this when steps need different bags (e.g. `showSeconds` then `maxLength`).
-   */
-  readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  /**
-   * Shared options for all `transformIds` steps (legacy / apply-to-all).
-   * Used when `transformOptionSteps` is omitted. Still written as a back-compat
-   * summary of step 0 (or the first non-empty step) by `normalizeMappingEdge`.
-   */
-  readonly transformOptions?: Readonly<Record<string, unknown>>;
-  /**
-   * When the source is an array of objects, optional dotted path into each item
-   * (e.g. `name` or `meta.label`) before the value is written to the target.
-   * Omit / empty for whole-array pass-through (or reduce on the full array).
-   */
-  readonly itemSourcePath?: string;
-  /**
-   * Ordered per-item transform chain (max 3) applied after `itemSourcePath`
-   * projection (or to each element when projecting is a no-op). Empty / omitted
-   * means identity per item. Independent of `transformIds` (which run on the
-   * whole collection afterward — e.g. reduce).
-   */
-  readonly itemTransformIds?: readonly string[];
-  /**
-   * Per-step options aligned with `itemTransformIds`.
-   */
-  readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
-  /**
-   * Shared options for all `itemTransformIds` steps (legacy / apply-to-all).
-   * Independent of `transformOptions` / `transformOptionSteps`.
-   */
-  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
-  /**
-   * List-context child bindings (Stedi-style): when source is an array of objects,
-   * each element is converted through these edges into a target item object.
-   * Child `sourceFieldId` / `targetSlotId` should resolve to item-schema fields
-   * (ingest ids like `a.tags.item.name`) whose `path` is item-relative.
-   *
-   * Takes precedence over `itemSourcePath` / `itemTransformIds` for the outer edge.
-   * Nested `itemEdges` on children are ignored (one collection level per edge).
-   */
-  readonly itemEdges?: readonly MappingEdge[];
-}
-
-/**
- * Minimal JSON-serializable mapping document for host persistence.
- * Hosts own schema trees; this document stores the binding graph only.
- */
-export interface FieldRemapDocument {
-  readonly version: 1;
-  readonly edges: readonly MappingEdge[];
-}
-
-export interface TransformContext {
-  readonly locale?: string;
-  /** Reference instant for time/date presets; defaults to `new Date()`. */
-  readonly now?: Date;
-  readonly sampleValue?: unknown;
-  /**
-   * Optional plain object for `string:template` placeholder resolution when the
-   * transform input is not itself an object (hosts / demos).
-   */
-  readonly record?: Readonly<Record<string, unknown>>;
-  readonly options?: Readonly<Record<string, unknown>>;
-}
-
-/** Declares a host-editable option consumed via `context.options[key]`. */
-export interface TransformOptionField {
-  readonly key: string;
-  readonly label: string;
-  /**
-   * - `string` / `number` / `boolean` — single scalar inputs
-   * - `stringMap` — key/value row editor for string→string maps (e.g. `codeLabels`),
-   *   with an optional List / JSON view toggle in `TransformOptionsEditor`
-   * - `json` — validated JSON textarea for plain objects (advanced / free-form);
-   *   drafts commit when parseable and pretty-print on blur
-   */
-  readonly kind: 'string' | 'number' | 'boolean' | 'stringMap' | 'json';
-}
-
-export interface ValueTransformDefinition {
-  readonly id: string;
-  readonly label: string;
-  readonly description?: string;
-  readonly category?: string;
-  readonly inputTypes?: readonly FieldDataType[];
-  readonly outputType?: FieldDataType;
-  readonly apply: (value: unknown, context: TransformContext) => unknown;
-  /** Optional picker label that includes a live format sample. */
-  readonly formatSampleLabel?: (context: TransformContext) => string;
-  /**
-   * Data-driven option editors (mapped rows / convert panel).
-   * Values are stored per step (`transformOptionSteps` / `itemTransformOptionSteps`)
-   * or as a shared bag (`transformOptions` / `itemTransformOptions`), or on host
-   * `TransformContext.options`.
-   */
-  readonly optionFields?: readonly TransformOptionField[];
-}
-
-export interface ValueTransformListFilter {
-  readonly inputType?: FieldDataType;
-  readonly category?: string;
-}
-
-export interface ValueTransformRegistry {
-  list(filter?: ValueTransformListFilter): ValueTransformDefinition[];
-  get(id: string): ValueTransformDefinition | undefined;
-  apply(id: string, value: unknown, context?: TransformContext): unknown;
-  register(definition: ValueTransformDefinition): void;
-}
+/**
+ * Shared field / slot / edge types for field-remap UIs.
+ */
+
+export type FieldDataType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'time'
+  | 'datetime'
+  /**
+   * Plain object (record) — e.g. for `string:template` object → string.
+   */
+  | 'object'
+  /**
+   * Collection hint — badge + array→array wiring.
+   * Optional per-item projection via `MappingEdge.itemSourcePath`.
+   */
+  | 'array'
+  | 'unknown';
+
+/**
+ * Stable class identity for a port/field whose nested `children` describe that class.
+ * Hosts own the class registry vocabulary; kit only carries the ref for browse / Flow.
+ */
+export type ClassRef = {
+  readonly id: string;
+  readonly version: number;
+};
+
+export interface SourceField {
+  readonly id: string;
+  readonly label: string;
+  /** Dot-path or capability path hint for hosts. */
+  readonly path?: string;
+  /**
+   * Owning managed shape id when fields are merged from multiple source shapes.
+   * Used by `convertToShape` to pick the correct named input bag.
+   */
+  readonly shapeId?: string;
+  readonly dataType?: FieldDataType;
+  /** Optional sample used by live preview / transform labels. */
+  readonly sampleValue?: unknown;
+  readonly group?: string;
+  /** When set with nested `children`, marks a class-typed object shape. */
+  readonly classRef?: ClassRef;
+  /**
+   * When `true`, omit from default Flow / mapper projections unless
+   * `projectShapes({ includeHidden: true })` (or browse with show-hidden).
+   */
+  readonly hidden?: boolean;
+  readonly children?: readonly SourceField[];
+}
+
+export interface TargetSlot {
+  readonly id: string;
+  readonly label: string;
+  /**
+   * Dot-path used when assembling nested JSON output via `convertToShape`.
+   * When omitted, hosts may fall back to slot id / label.
+   */
+  readonly path?: string;
+  readonly dataType?: FieldDataType;
+  readonly required?: boolean;
+  readonly description?: string;
+  /** When set with nested `children`, marks a class-typed object shape. */
+  readonly classRef?: ClassRef;
+  /**
+   * When `true`, omit from default Flow / mapper projections unless
+   * `projectShapes({ includeHidden: true })` (or browse with show-hidden).
+   */
+  readonly hidden?: boolean;
+  /** Nested slot groups (expand/collapse in the mapper tree). */
+  readonly children?: readonly TargetSlot[];
+}
+
+export interface MappingEdge {
+  readonly id: string;
+  readonly sourceFieldId: string;
+  readonly targetSlotId: string;
+  /**
+   * Ordered transform chain (max 3). Empty / omitted means identity.
+   * Prefer this over `transformId` for new writers.
+   * For arrays: use reduce builtins (`array:join`, `array:first`, …) here after
+   * optional item projection / item transforms.
+   */
+  readonly transformIds?: readonly string[];
+  /**
+   * Legacy single transform. Prefer `transformIds`.
+   * Readers should use `edgeTransformIds` / `normalizeMappingEdge`.
+   * `null` / omitted (with no `transformIds`) means identity (pass-through).
+   */
+  readonly transformId?: string | null;
+  /**
+   * Per-step options aligned with `transformIds` (index N applies to step N).
+   * Prefer this when steps need different bags (e.g. `showSeconds` then `maxLength`).
+   */
+  readonly transformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
+  /**
+   * Shared options for all `transformIds` steps (legacy / apply-to-all).
+   * Used when `transformOptionSteps` is omitted. Still written as a back-compat
+   * summary of step 0 (or the first non-empty step) by `normalizeMappingEdge`.
+   */
+  readonly transformOptions?: Readonly<Record<string, unknown>>;
+  /**
+   * When the source is an array of objects, optional dotted path into each item
+   * (e.g. `name` or `meta.label`) before the value is written to the target.
+   * Omit / empty for whole-array pass-through (or reduce on the full array).
+   */
+  readonly itemSourcePath?: string;
+  /**
+   * Ordered per-item transform chain (max 3) applied after `itemSourcePath`
+   * projection (or to each element when projecting is a no-op). Empty / omitted
+   * means identity per item. Independent of `transformIds` (which run on the
+   * whole collection afterward — e.g. reduce).
+   */
+  readonly itemTransformIds?: readonly string[];
+  /**
+   * Per-step options aligned with `itemTransformIds`.
+   */
+  readonly itemTransformOptionSteps?: readonly (Readonly<Record<string, unknown>> | undefined)[];
+  /**
+   * Shared options for all `itemTransformIds` steps (legacy / apply-to-all).
+   * Independent of `transformOptions` / `transformOptionSteps`.
+   */
+  readonly itemTransformOptions?: Readonly<Record<string, unknown>>;
+  /**
+   * List-context child bindings (Stedi-style): when source is an array of objects,
+   * each element is converted through these edges into a target item object.
+   * Child `sourceFieldId` / `targetSlotId` should resolve to item-schema fields
+   * (ingest ids like `a.tags.item.name`) whose `path` is item-relative.
+   *
+   * Takes precedence over `itemSourcePath` / `itemTransformIds` for the outer edge.
+   * Nested `itemEdges` on children are ignored (one collection level per edge).
+   */
+  readonly itemEdges?: readonly MappingEdge[];
+}
+
+/** Fan-in: multiple source fields → one target slot. */
+export interface CombineMappingOperator {
+  readonly kind: 'combine';
+  readonly id: string;
+  readonly inputFieldIds: readonly string[];
+  readonly outputSlotId: string;
+  /** Optional chain applied to the combined object bag (max 3 via registry). */
+  readonly transformIds?: readonly string[];
+}
+
+/** Fan-out: one source field → multiple target slots. */
+export interface SplitMappingOperator {
+  readonly kind: 'split';
+  readonly id: string;
+  readonly inputFieldId: string;
+  readonly outputSlotIds: readonly string[];
+  /** Optional chain applied to the source value before splitting an object. */
+  readonly transformIds?: readonly string[];
+}
+
+export type MappingOperator = CombineMappingOperator | SplitMappingOperator;
+
+/**
+ * Minimal JSON-serializable mapping document for host persistence.
+ * Hosts own schema trees; this document stores the binding graph (and optional
+ * n→m operators from document v2 onward).
+ */
+export interface FieldRemapDocument {
+  /** `1` = edges-only; `2` = edges + optional `operators[]`. */
+  readonly version: 1 | 2;
+  readonly edges: readonly MappingEdge[];
+  /**
+   * Optional n→m combine/split operators (document v2).
+   * Omitted / empty on v1 documents and on v2 hosts that only use 1→1 edges.
+   */
+  readonly operators?: readonly MappingOperator[];
+}
+export interface TransformContext {
+  readonly locale?: string;
+  /** Reference instant for time/date presets; defaults to `new Date()`. */
+  readonly now?: Date;
+  readonly sampleValue?: unknown;
+  /**
+   * Optional plain object for `string:template` placeholder resolution when the
+   * transform input is not itself an object (hosts / demos).
+   */
+  readonly record?: Readonly<Record<string, unknown>>;
+  readonly options?: Readonly<Record<string, unknown>>;
+  /**
+   * Optional cancellation signal. `applyTransformChain` / `convertToShape` check
+   * between steps and reject with `AbortError` when aborted.
+   */
+  readonly signal?: AbortSignal;
+}
+
+/** Declares a host-editable option consumed via `context.options[key]`. */
+export interface TransformOptionField {
+  readonly key: string;
+  readonly label: string;
+  /**
+   * - `string` / `number` / `boolean` — single scalar inputs
+   * - `stringMap` — key/value row editor for string→string maps (e.g. `codeLabels`),
+   *   with an optional List / JSON view toggle in `TransformOptionsEditor`
+   * - `json` — validated JSON textarea for plain objects (advanced / free-form);
+   *   drafts commit when parseable and pretty-print on blur
+   */
+  readonly kind: 'string' | 'number' | 'boolean' | 'stringMap' | 'json';
+}
+
+export interface ValueTransformDefinition {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly category?: string;
+  readonly inputTypes?: readonly FieldDataType[];
+  readonly outputType?: FieldDataType;
+  /**
+   * May return a Promise (e.g. host JSONata 2.x). Prefer `applyTransformChain` /
+   * `convertToShape`, which always await transform results.
+   */
+  readonly apply: (value: unknown, context: TransformContext) => unknown | PromiseLike<unknown>;
+  /** Optional picker label that includes a live format sample. */
+  readonly formatSampleLabel?: (context: TransformContext) => string;
+  /**
+   * Data-driven option editors (mapped rows / convert panel).
+   * Values are stored per step (`transformOptionSteps` / `itemTransformOptionSteps`)
+   * or as a shared bag (`transformOptions` / `itemTransformOptions`), or on host
+   * `TransformContext.options`.
+   */
+  readonly optionFields?: readonly TransformOptionField[];
+}
+
+export interface ValueTransformListFilter {
+  readonly inputType?: FieldDataType;
+  readonly category?: string;
+}
+
+export interface ValueTransformRegistry {
+  list(filter?: ValueTransformListFilter): ValueTransformDefinition[];
+  get(id: string): ValueTransformDefinition | undefined;
+  apply(id: string, value: unknown, context?: TransformContext): unknown | PromiseLike<unknown>;
+  register(definition: ValueTransformDefinition): void;
+}