@workbench-kit/field-remap 0.0.1-prototype.0

package/src/domain/shapes/conversionDefinition.ts

@@ -0,0 +1,95 @@
+import {
+  createFieldRemapDocument,
+  normalizeFieldRemapDocument,
+} from '../document/fieldRemapDocument.js';
+import type { MappingEdge, FieldRemapDocument } from '../types.js';
+
+/**
+ * Managed conversion between one or more source shapes and a target shape.
+ * Edges live in `document`; runtime uses `convertToShape` (not a method on a shape).
+ */
+export interface ConversionDefinition {
+  readonly id: string;
+  readonly label?: string;
+  /** One or more managed source shape ids (multi-input). */
+  readonly sourceShapeIds: readonly string[];
+  readonly targetShapeId: string;
+  readonly document: FieldRemapDocument;
+}
+
+export interface ConversionRegistry {
+  register(conversion: ConversionDefinition): void;
+  get(id: string): ConversionDefinition | undefined;
+  list(): readonly ConversionDefinition[];
+}
+
+export interface DefineConversionInput {
+  readonly id: string;
+  readonly label?: string;
+  readonly sourceShapeIds: readonly string[];
+  readonly targetShapeId: string;
+  readonly document?: FieldRemapDocument;
+  readonly edges?: readonly MappingEdge[];
+}
+
+export function defineConversion(input: DefineConversionInput): ConversionDefinition {
+  const id = input.id.trim();
+  if (!id) {
+    throw new Error('ConversionDefinition.id must be a non-empty string.');
+  }
+  const sourceShapeIds = input.sourceShapeIds.map((item) => item.trim()).filter(Boolean);
+  if (sourceShapeIds.length === 0) {
+    throw new Error('ConversionDefinition.sourceShapeIds must include at least one shape id.');
+  }
+  const targetShapeId = input.targetShapeId.trim();
+  if (!targetShapeId) {
+    throw new Error('ConversionDefinition.targetShapeId must be a non-empty string.');
+  }
+
+  const document = input.document
+    ? normalizeFieldRemapDocument(input.document)
+    : createFieldRemapDocument(input.edges ?? []);
+
+  return {
+    id,
+    ...(input.label?.trim() ? { label: input.label.trim() } : {}),
+    sourceShapeIds,
+    targetShapeId,
+    document,
+  };
+}
+
+export function createConversionRegistry(
+  initial: readonly ConversionDefinition[] = [],
+): ConversionRegistry {
+  const byId = new Map<string, ConversionDefinition>();
+
+  const api: ConversionRegistry = {
+    register(conversion) {
+      const defined = defineConversion(conversion);
+      byId.set(defined.id, defined);
+    },
+    get(id) {
+      return byId.get(id.trim());
+    },
+    list() {
+      return [...byId.values()];
+    },
+  };
+
+  for (const conversion of initial) {
+    api.register(conversion);
+  }
+  return api;
+}
+
+/** Replace edges on a conversion (immutable). */
+export function withConversionEdges(
+  conversion: ConversionDefinition,
+  edges: readonly MappingEdge[],
+): ConversionDefinition {
+  return {
+    ...conversion,
+    document: createFieldRemapDocument(edges),
+  };
+}

package/src/domain/shapes/convertToShape.ts

@@ -0,0 +1,187 @@
+import type { ConversionDefinition } from './conversionDefinition.js';
+import {
+  mergeSourceShapes,
+  targetSlotsFromShape,
+  type DataShape,
+  type DataShapeRegistry,
+} from './dataShape.js';
+import { convertArrayWithItemEdges } from '../mapping/convertItemEdges.js';
+import { isPlainObject, readObjectPath, writeObjectPath } from '../mapping/pathUtils.js';
+import { findSourceField, resolveMappedValue } from '../mapping/resolveMappedValue.js';
+import { findTargetSlot, flattenTargetSlots } from '../mapping/treeUtils.js';
+import type {
+  SourceField,
+  TargetSlot,
+  TransformContext,
+  ValueTransformRegistry,
+} from '../types.js';
+
+export interface ConvertToShapeInput {
+  readonly conversion: ConversionDefinition;
+  /** Shape registry, or an explicit list containing at least the referenced shapes. */
+  readonly shapes: DataShapeRegistry | readonly DataShape[];
+  /**
+   * Named input bags keyed by source shape id.
+   * Example: `{ order: liveOrder, customer: liveCustomer }`.
+   */
+  readonly inputs: Readonly<Record<string, unknown>>;
+  readonly transforms: ValueTransformRegistry;
+  readonly context?: TransformContext;
+}
+
+export interface ConvertToShapeSlotResult {
+  readonly edgeId: string;
+  readonly targetSlotId: string;
+  readonly path: string;
+  readonly value: unknown;
+}
+
+export interface ConvertToShapeResult {
+  /** Nested JSON matching target shape paths. */
+  readonly output: Record<string, unknown>;
+  /** Flat per-slot results (debug / UI panels). */
+  readonly slots: readonly ConvertToShapeSlotResult[];
+}
+
+function isDataShapeRegistry(
+  shapes: DataShapeRegistry | readonly DataShape[],
+): shapes is DataShapeRegistry {
+  return typeof (shapes as DataShapeRegistry).get === 'function';
+}
+
+function resolveShape(
+  shapes: DataShapeRegistry | readonly DataShape[],
+  id: string,
+): DataShape | undefined {
+  if (isDataShapeRegistry(shapes)) {
+    return shapes.get(id);
+  }
+  return shapes.find((shape) => shape.id === id);
+}
+
+function outputPathForTarget(slot: TargetSlot): string {
+  const path = slot.path?.trim();
+  if (path) {
+    return path;
+  }
+  // Prefer last id segment when hosts use dotted ids (`slot.display.timeText`).
+  const id = slot.id.trim();
+  if (id.includes('.')) {
+    const parts = id.split('.').filter(Boolean);
+    // Drop a leading registry prefix like `slot` when present with 3+ segments.
+    if (parts.length >= 3 && (parts[0] === 'slot' || parts[0] === 'tgt')) {
+      return parts.slice(1).join('.');
+    }
+    if (parts.length >= 2) {
+      return parts.slice(1).join('.');
+    }
+  }
+  return slot.label.trim() || id;
+}
+
+function readFieldValue(field: SourceField, inputs: Readonly<Record<string, unknown>>): unknown {
+  const shapeId = field.shapeId?.trim();
+  const bag =
+    shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)
+      ? inputs[shapeId]
+      : // Single-bag fallback: use the only input, or the whole inputs record.
+        Object.keys(inputs).length === 1
+        ? inputs[Object.keys(inputs)[0]!]
+        : inputs;
+
+  const path = field.path?.trim();
+  if (path) {
+    // When bags are per-shape, paths are relative to that bag.
+    // When falling back to the whole inputs record, absolute paths still work.
+    if (shapeId && Object.prototype.hasOwnProperty.call(inputs, shapeId)) {
+      return readObjectPath(bag, path);
+    }
+    const fromBag = readObjectPath(bag, path);
+    if (fromBag !== undefined) {
+      return fromBag;
+    }
+    // Absolute path into combined inputs (e.g. `order.totalCents`).
+    return readObjectPath(inputs, path);
+  }
+
+  return field.sampleValue;
+}
+
+/**
+ * Apply a conversion to named input bags and build target-shaped JSON.
+ *
+ * This is the host runtime entry point — not `sourceShape.convert(target, data)`.
+ * Multiple source shapes are supported via `inputs[shapeId]`.
+ */
+export function convertToShape(input: ConvertToShapeInput): ConvertToShapeResult {
+  const sourceShapes: DataShape[] = [];
+  for (const shapeId of input.conversion.sourceShapeIds) {
+    const shape = resolveShape(input.shapes, shapeId);
+    if (!shape) {
+      throw new Error(`Unknown source shape "${shapeId}" for conversion "${input.conversion.id}".`);
+    }
+    if (shape.role === 'target') {
+      throw new Error(`Shape "${shapeId}" has role "target" and cannot be used as a source.`);
+    }
+    sourceShapes.push(shape);
+  }
+
+  const targetShape = resolveShape(input.shapes, input.conversion.targetShapeId);
+  if (!targetShape) {
+    throw new Error(
+      `Unknown target shape "${input.conversion.targetShapeId}" for conversion "${input.conversion.id}".`,
+    );
+  }
+
+  const sources = mergeSourceShapes(sourceShapes);
+  const targets = targetSlotsFromShape(targetShape);
+  const targetLeaves = flattenTargetSlots(targets);
+
+  let output: Record<string, unknown> = {};
+  const slots: ConvertToShapeSlotResult[] = [];
+
+  for (const edge of input.conversion.document.edges) {
+    const sourceField = findSourceField(sources, edge.sourceFieldId);
+    if (!sourceField) {
+      continue;
+    }
+    const targetSlot =
+      findTargetSlot(targets, edge.targetSlotId) ??
+      targetLeaves.find((slot) => slot.id === edge.targetSlotId);
+    if (!targetSlot) {
+      continue;
+    }
+
+    const sourceValue = readFieldValue(sourceField, input.inputs);
+    const value =
+      edge.itemEdges && edge.itemEdges.length > 0
+        ? convertArrayWithItemEdges({
+            items: sourceValue,
+            itemEdges: edge.itemEdges,
+            sources,
+            targets,
+            transforms: input.transforms,
+            context: input.context,
+          })
+        : resolveMappedValue(edge, sourceValue, input.transforms, {
+            ...input.context,
+            sampleValue: sourceValue,
+            record: isPlainObject(sourceValue)
+              ? sourceValue
+              : isPlainObject(input.context?.record)
+                ? input.context.record
+                : undefined,
+          });
+
+    const path = outputPathForTarget(targetSlot);
+    output = writeObjectPath(output, path, value);
+    slots.push({
+      edgeId: edge.id,
+      targetSlotId: edge.targetSlotId,
+      path,
+      value,
+    });
+  }
+
+  return { output, slots };
+}

package/src/domain/shapes/dataShape.ts

@@ -0,0 +1,109 @@
+import type { SourceField, TargetSlot } from '../types.js';
+
+/** How a managed shape is used in conversions. */
+export type DataShapeRole = 'source' | 'target' | 'both';
+
+/**
+ * Managed structure descriptor ("class-like" fixed shape).
+ * Source/target field trees are host-owned; this wraps them for registry lookup.
+ */
+export interface DataShape {
+  readonly id: string;
+  readonly label: string;
+  readonly role: DataShapeRole;
+  /**
+   * Field tree for source and/or target use.
+   * When `role` is `target`, treat as `TargetSlot[]` (compatible structural shape).
+   * When `role` is `source` or `both`, treat as `SourceField[]`.
+   */
+  readonly fields: readonly SourceField[] | readonly TargetSlot[];
+}
+
+export interface DataShapeRegistry {
+  register(shape: DataShape): void;
+  get(id: string): DataShape | undefined;
+  list(role?: DataShapeRole): readonly DataShape[];
+}
+
+export function defineDataShape(input: DataShape): DataShape {
+  const id = input.id.trim();
+  if (!id) {
+    throw new Error('DataShape.id must be a non-empty string.');
+  }
+  return {
+    id,
+    label: input.label.trim() || id,
+    role: input.role,
+    fields: input.fields,
+  };
+}
+
+export function createDataShapeRegistry(initial: readonly DataShape[] = []): DataShapeRegistry {
+  const byId = new Map<string, DataShape>();
+
+  const api: DataShapeRegistry = {
+    register(shape) {
+      const defined = defineDataShape(shape);
+      byId.set(defined.id, defined);
+    },
+    get(id) {
+      return byId.get(id.trim());
+    },
+    list(role) {
+      const all = [...byId.values()];
+      if (!role) {
+        return all;
+      }
+      return all.filter((shape) => shape.role === role || shape.role === 'both');
+    },
+  };
+
+  for (const shape of initial) {
+    api.register(shape);
+  }
+  return api;
+}
+
+/** Recursively stamp `shapeId` on source fields (for multi-input convert). */
+export function attachShapeIdToSourceFields(
+  fields: readonly SourceField[],
+  shapeId: string,
+): SourceField[] {
+  return fields.map((field) => {
+    const next: SourceField = {
+      ...field,
+      shapeId,
+      ...(field.children ? { children: attachShapeIdToSourceFields(field.children, shapeId) } : {}),
+    };
+    return next;
+  });
+}
+
+/**
+ * Merge source shapes into one tree for `FieldRemap` / convert:
+ * each shape becomes a non-mappable group whose children carry `shapeId`.
+ */
+export function mergeSourceShapes(shapes: readonly DataShape[]): SourceField[] {
+  const sources: SourceField[] = [];
+  for (const shape of shapes) {
+    if (shape.role === 'target') {
+      continue;
+    }
+    const children = attachShapeIdToSourceFields(shape.fields as readonly SourceField[], shape.id);
+    sources.push({
+      id: `shape.${shape.id}`,
+      label: shape.label,
+      group: 'Shapes',
+      children,
+    });
+  }
+  return sources;
+}
+
+/** Target slots from a target (or both) shape. */
+export function targetSlotsFromShape(shape: DataShape): TargetSlot[] {
+  if (shape.role === 'source') {
+    throw new Error(`DataShape "${shape.id}" has role "source" and cannot provide target slots.`);
+  }
+  return shape.fields as TargetSlot[];
+}

package/src/domain/types.ts

@@ -0,0 +1,182 @@
+/**
+ * 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;
+}