@narrative.io/jsonforms-provider-protocols 2.11.0-beta.0 → 2.12.0

package/src/core/projection.ts

@@ -0,0 +1,147 @@
+import { deref as derefSchema, tryCombinatorBranches } from "./refs";
+
+/**
+ * Projection utilities for navigating complex data structures
+ * through a dot-separated path where numeric segments are array indices.
+ *
+ * Examples:
+ *   "0"                → first element of an array
+ *   "include"          → the `include` property of an object
+ *   "0.video_rate_usd" → nested property inside the first array element
+ */
+
+export type ProjectionSegment = string | number;
+
+/**
+ * Parse a projection path string into typed segments.
+ * Numeric strings become numbers (array indices), others stay as strings (object keys).
+ */
+export function parseProjectionPath(path: string): ProjectionSegment[] {
+  if (!path) return [];
+  return path.split(".").map((s) => {
+    const n = Number(s);
+    return Number.isInteger(n) && n >= 0 ? n : s;
+  });
+}
+
+/**
+ * Read a value from `data` by following the projection path.
+ * Returns `undefined` if any segment along the path is missing.
+ */
+export function getProjectedValue(data: unknown, path: string): unknown {
+  const segments = parseProjectionPath(path);
+  let current: unknown = data;
+
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+
+    if (typeof seg === "number") {
+      if (!Array.isArray(current)) return undefined;
+      current = current[seg];
+    } else {
+      if (typeof current !== "object") return undefined;
+      current = (current as Record<string, unknown>)[seg];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Immutably set a value at the projection path, preserving all sibling data.
+ * Constructs missing intermediate structures (arrays for numeric segments, objects for string segments).
+ */
+export function setProjectedValue(
+  data: unknown,
+  path: string,
+  value: unknown,
+): unknown {
+  const segments = parseProjectionPath(path);
+  return setAtPath(data, segments, 0, value);
+}
+
+function setAtPath(
+  current: unknown,
+  segments: ProjectionSegment[],
+  index: number,
+  value: unknown,
+): unknown {
+  if (index === segments.length) {
+    return value;
+  }
+
+  const seg = segments[index]!;
+
+  if (typeof seg === "number") {
+    // Array index — ensure we have an array
+    const arr = Array.isArray(current) ? [...current] : [];
+    // Pad array if index is out of bounds
+    while (arr.length <= seg) {
+      arr.push(undefined);
+    }
+    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);
+    return arr;
+  } else {
+    // Object key — ensure we have an object
+    const obj: Record<string, unknown> =
+      current !== null &&
+      current !== undefined &&
+      typeof current === "object" &&
+      !Array.isArray(current)
+        ? { ...(current as Record<string, unknown>) }
+        : {};
+    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);
+    return obj;
+  }
+}
+
+/**
+ * Resolve the schema at the projected path.
+ * Numeric segments traverse into `items` (array item schema).
+ * String segments traverse into `properties[segment]`.
+ *
+ * Dereferences `$ref` nodes transparently at every step, and falls through
+ * to `oneOf` / `anyOf` / `allOf` branches when a segment can't resolve
+ * directly — picks the first branch that satisfies the navigation.
+ */
+export function getProjectedSchema(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: Record<string, any>,
+  path: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> {
+  const segments = parseProjectionPath(path);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: Record<string, any> | undefined = schema;
+
+  for (const seg of segments) {
+    current = derefSchema(current, schema);
+    if (!current) return {};
+
+    const navigate = (
+      node: Record<string, unknown>,
+    ): Record<string, unknown> | undefined => {
+      if (typeof seg === "number") {
+        const items = (node as { items?: unknown }).items;
+        return items && typeof items === "object"
+          ? (items as Record<string, unknown>)
+          : undefined;
+      }
+      const properties = (node as { properties?: unknown }).properties as
+        | Record<string, Record<string, unknown>>
+        | undefined;
+      if (properties && properties[seg]) return properties[seg];
+      return undefined;
+    };
+
+    let next = navigate(current);
+    if (next === undefined) {
+      next = tryCombinatorBranches(current, schema, navigate);
+    }
+    if (!next) return {};
+    current = next;
+  }
+
+  const resolved = derefSchema(current, schema);
+  return resolved ?? {};
+}

package/src/core/refs.ts

@@ -0,0 +1,166 @@
+/**
+ * JSON Schema $ref resolution helpers.
+ *
+ * Supports the pointer grammar used across consumer schemas:
+ *   - "#/$defs/Name"
+ *   - "#/properties/foo/items"
+ *
+ * External refs (URIs, file refs) are intentionally out of scope. A ref that
+ * doesn't resolve leaves the node untouched — callers can still inspect the
+ * unresolved `$ref` for debugging.
+ */
+
+/**
+ * Resolve a JSON pointer (`#/a/b/c`) against an object. Returns the node at
+ * that path, or `undefined` if any segment is missing or the pointer doesn't
+ * start with `#/`.
+ */
+export function resolvePointer(
+  obj: Record<string, unknown>,
+  pointer: string,
+): unknown {
+  if (!pointer.startsWith("#/")) return undefined;
+  const parts = pointer.slice(2).split("/");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Dereference a schema node along a chain of `$ref`s. Follows `A → B → C`
+ * transitively. A cycle (same `$ref` seen twice in one chain) returns the
+ * last unresolved node rather than hanging. An unresolvable pointer returns
+ * the current node unchanged.
+ */
+export function resolveRef(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> {
+  if (!property || typeof property !== "object") return property;
+
+  const ref = property.$ref as string | undefined;
+  if (!ref) return property;
+
+  const visited = seen ?? new Set<string>();
+  if (visited.has(ref)) return property;
+  visited.add(ref);
+
+  const resolved = resolvePointer(root, ref);
+  if (!resolved) return property;
+
+  return resolveRef(resolved as Record<string, unknown>, root, visited);
+}
+
+/**
+ * Convenience wrapper around `resolveRef` that starts a fresh cycle-detection
+ * set. Intended for schema walkers that need to dereference at every step;
+ * each call is an independent resolution.
+ */
+export function deref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> | undefined {
+  if (!node || typeof node !== "object") return node;
+  return resolveRef(node, root) as Record<string, unknown> | undefined;
+}
+
+/**
+ * Depth limit for combinator (oneOf/anyOf/allOf) branch descent. Schemas
+ * rarely nest combinators beyond one or two levels; this guard protects
+ * against pathological nesting and cycles (e.g. `oneOf: [$ref back to self]`).
+ */
+const COMBINATOR_DEPTH_LIMIT = 8;
+
+/**
+ * Try to navigate a segment through a schema node's combinator branches
+ * (`oneOf` / `anyOf` / `allOf`) when direct navigation has failed.
+ *
+ * Semantics: for walker purposes (renderer-tester matching), we only need
+ * ONE concrete schema that satisfies the next navigation step. First-match
+ * by structural shape wins, same convention as `initOneOf` uses for seeding.
+ *
+ * @param node     the schema node to search (already dereffed by caller)
+ * @param root     the root schema, for dereferencing branch `$ref`s
+ * @param tryFn    predicate that attempts navigation on a candidate branch
+ *                 and returns the navigated value, or `undefined` if the
+ *                 branch doesn't have what the caller's looking for
+ * @param depth    recursion depth (capped at `COMBINATOR_DEPTH_LIMIT`)
+ */
+export function tryCombinatorBranches<T>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tryFn: (candidate: Record<string, any>) => T | undefined,
+  depth = 0,
+): T | undefined {
+  if (depth > COMBINATOR_DEPTH_LIMIT) return undefined;
+  if (!node || typeof node !== "object") return undefined;
+
+  const branches = (node.oneOf || node.anyOf || node.allOf) as
+    | Record<string, unknown>[]
+    | undefined;
+  if (!Array.isArray(branches)) return undefined;
+
+  for (const raw of branches) {
+    const branch = deref(raw as Record<string, unknown>, root);
+    if (!branch || typeof branch !== "object") continue;
+
+    const direct = tryFn(branch);
+    if (direct !== undefined) return direct;
+
+    const nested = tryCombinatorBranches(branch, root, tryFn, depth + 1);
+    if (nested !== undefined) return nested;
+  }
+  return undefined;
+}
+
+/**
+ * Recursively dereference every `$ref` in a schema subtree, producing a
+ * concrete schema with no remaining refs. Cycles along any single chain are
+ * handled by leaving the first recursion back into a seen ref as the
+ * unresolved node — matching `resolveRef`'s semantics.
+ *
+ * Intended for use at API boundaries (e.g. `resolveScopeSchema`'s return)
+ * so downstream walkers can operate on self-contained schemas without
+ * needing the original root.
+ */
+export function deepDeref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  seen: Set<string> = new Set(),
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((n) => deepDeref(n, root, seen));
+
+  const ref = (node as Record<string, unknown>).$ref as string | undefined;
+  if (typeof ref === "string") {
+    if (seen.has(ref)) return node;
+    const resolved = resolvePointer(root, ref);
+    if (!resolved || typeof resolved !== "object") return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(ref);
+    return deepDeref(resolved, root, nextSeen);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = deepDeref(value, root, seen);
+  }
+  return result;
+}

package/src/core/resolveScope.ts

@@ -0,0 +1,54 @@
+import { deepDeref, deref, tryCombinatorBranches } from "./refs";
+
+/**
+ * Resolve a JSON Forms scope path to its schema within a root schema.
+ * Handles nested paths like "#/properties/parent/properties/child".
+ *
+ * Follows JSON Schema structure:
+ *   - "properties" segments navigate into object `.properties`
+ *   - "items" segments navigate into array `.items`
+ *   - all other segments index directly into the current object
+ *
+ * Dereferences `$ref` nodes transparently at every step, and falls through
+ * to `oneOf` / `anyOf` / `allOf` branches when a segment can't resolve
+ * directly — picks the first branch that satisfies the navigation. The
+ * returned schema is deep-dereferenced so downstream walkers can operate on
+ * a self-contained sub-schema without needing the original root.
+ */
+export function resolveScopeSchema(
+  scope: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rootSchema: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> | undefined {
+  if (!scope || !rootSchema) return undefined;
+
+  // Remove the leading "#/" and split into segments
+  const path = scope.replace(/^#\/?/, "");
+  if (!path) return deepDeref(rootSchema, rootSchema);
+
+  const segments = path.split("/");
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: any = rootSchema;
+
+  for (const segment of segments) {
+    current = deref(current, rootSchema);
+    if (!current || typeof current !== "object") return undefined;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const navigate = (node: Record<string, any>): unknown => {
+      if (segment === "properties") return node.properties;
+      if (segment === "items") return node.items;
+      return node[segment];
+    };
+
+    let next = navigate(current);
+    if (next === undefined) {
+      next = tryCombinatorBranches(current, rootSchema, navigate);
+    }
+    if (next === undefined) return undefined;
+    current = next;
+  }
+
+  return deepDeref(current, rootSchema);
+}

package/src/core/seedProjectionTargets.ts

@@ -0,0 +1,144 @@
+import {
+  getProjectedValue,
+  parseProjectionPath,
+  setProjectedValue,
+} from "./projection";
+
+/**
+ * Materialize array indices targeted by `options.projection` controls in a
+ * UI schema, so that JSON Schema validators (AJV / cfworker) emit
+ * `items.required` errors on otherwise-empty arrays.
+ *
+ * Why this exists:
+ *   `initFormDataFromSchema` omits optional fields, so an optional array
+ *   like `data_rates: { type: 'array', items: { $ref: '#/$defs/DataRate' } }`
+ *   produces `undefined` (or, historically, `[]`). Both shapes pass schema
+ *   validation: `undefined` doesn't trigger `type: array`, and `[]` has no
+ *   items to apply `items.required` to. As a result, a projection-targeted
+ *   field rendered with `Video CPM rate *` lies — the asterisk says
+ *   "required" but the validator never enforces it on an untouched form.
+ *
+ *   This utility opts the consumer into per-item enforcement by walking the
+ *   UI schema, finding every `Control` with `options.projection` that
+ *   addresses an array index, and ensuring the corresponding data path has
+ *   that index materialized as at least `{}`. With the empty object in
+ *   place, the schema's `items.required` fires and the projected control's
+ *   error string surfaces at form-validity time.
+ *
+ * Tradeoff:
+ *   This re-introduces "noise" on untouched forms — required-field errors
+ *   for fields the user hasn't seen yet. Use it when validation enforcement
+ *   on projection targets matters more than a clean initial form state.
+ *   The alternative is to declare these arrays as `required` + `minItems: 1`
+ *   + `default: [{}]` at the schema level, which avoids needing this helper.
+ *
+ * Properties:
+ *   - Idempotent: running twice yields the same result as running once.
+ *   - Non-destructive: existing values at target paths are preserved.
+ *   - Pure: returns a new object; does not mutate `data`.
+ *
+ * Example:
+ *   ```ts
+ *   const data = initFormDataFromSchema(schema);
+ *   const seeded = seedProjectionTargets(data, uischema);
+ *   // For uischema controls like
+ *   //   { type: 'Control', scope: '#/properties/data_rates',
+ *   //     options: { projection: '0.video_rate_usd' } }
+ *   // seeded.data_rates is now `[{}]` (was `undefined` or `[]`).
+ *   ```
+ */
+export function seedProjectionTargets(
+  data: unknown,
+  uischema: UISchemaLike | UISchemaLike[] | undefined,
+): unknown {
+  if (!uischema) return data;
+
+  const controls: { scope: string; projection: string }[] = [];
+  collectProjectionControls(uischema, controls);
+
+  let result = data;
+  for (const { scope, projection } of controls) {
+    const dataPath = scopeToDataPath(scope);
+    const segments = parseProjectionPath(projection);
+
+    // Seed only when a numeric segment is followed by a *string* segment —
+    // i.e., the consumer is reading a property of the array item, so the
+    // item must be an object. Numeric-at-end (`'0'`) addresses the array
+    // element itself, which can be any type (primitive, nested array,
+    // object) — we can't infer it from the uischema alone, so leave it
+    // alone. Numeric-followed-by-numeric (`'0.0'`) is a nested array; we'd
+    // need to seed `[]`, but again the inner item type is unknown.
+    for (let i = 0; i < segments.length; i++) {
+      if (typeof segments[i] !== "number") continue;
+      if (i + 1 >= segments.length) continue;
+      if (typeof segments[i + 1] !== "string") continue;
+
+      const partial = segments
+        .slice(0, i + 1)
+        .map((s) => String(s))
+        .join(".");
+      const fullPath = dataPath ? `${dataPath}.${partial}` : partial;
+
+      if (getProjectedValue(result, fullPath) === undefined) {
+        result = setProjectedValue(result, fullPath, {});
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Minimal UI schema shape this utility traverses. Compatible with
+ * `@jsonforms/core`'s `UISchemaElement` but kept local to avoid a runtime
+ * dep on `@jsonforms/core` (it's a peer dep — types only).
+ */
+export interface UISchemaLike {
+  type?: string;
+  scope?: string;
+  options?: { projection?: string; [key: string]: unknown };
+  elements?: UISchemaLike[];
+  [key: string]: unknown;
+}
+
+function collectProjectionControls(
+  ui: UISchemaLike | UISchemaLike[] | undefined,
+  out: { scope: string; projection: string }[],
+): void {
+  if (!ui) return;
+  if (Array.isArray(ui)) {
+    for (const el of ui) collectProjectionControls(el, out);
+    return;
+  }
+  if (typeof ui !== "object") return;
+
+  const projection = ui.options?.projection;
+  if (
+    ui.type === "Control" &&
+    typeof ui.scope === "string" &&
+    typeof projection === "string"
+  ) {
+    out.push({ scope: ui.scope, projection });
+  }
+
+  if (Array.isArray(ui.elements)) {
+    for (const el of ui.elements) collectProjectionControls(el, out);
+  }
+}
+
+/**
+ * Convert a JsonForms scope pointer (`#/properties/foo/properties/bar`) to
+ * a dot-separated data path (`foo.bar`). Drops `items` segments — array
+ * indices are added at runtime via the projection path, not the scope.
+ */
+function scopeToDataPath(scope: string): string {
+  if (!scope.startsWith("#/")) return "";
+  const parts = scope.slice(2).split("/");
+  const out: string[] = [];
+  for (let i = 0; i < parts.length; i++) {
+    if (parts[i] === "properties" && i + 1 < parts.length) {
+      out.push(parts[++i]!);
+    }
+  }
+  return out.join(".");
+}

package/src/core/transforms.ts

@@ -14,30 +14,38 @@ export interface FlattenTransform extends Transform {
   labelFormat?: string; // Optional format string like "{parent.name} → {name}"
 }
 
+export type FilterOperator =
+  | "eq"
+  | "neq"
+  | "empty"
+  | "notEmpty"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains";
+
+export interface FilterCondition {
+  key: string;
+  operator?: FilterOperator; // Defaults to "eq" when values is provided, "exists" behavior when neither
+  values?: unknown[];
+}
+
 export interface FilterTransform extends Transform {
   name: "filter";
-  key: string; // The key to check
-  values?: unknown[]; // Optional array of values to match against
+  key?: string; // Legacy: single key to check
+  values?: unknown[]; // Legacy: single values array
+  conditions?: FilterCondition[]; // Multi-condition filter (AND logic)
 }
 
 export type TransformStep = FlattenTransform | FilterTransform;
 
 export type TransformPipeline = TransformStep[];
 
-/**
- * Registry of transform functions
- */
 type TransformFunction = (items: unknown[], config: Transform) => unknown[];
 
 const transformRegistry: Record<string, TransformFunction> = {};
 
-/**
- * Register a transform function
- */
-export function registerTransform(name: string, fn: TransformFunction): void {
-  transformRegistry[name] = fn;
-}
-
 /**
  * Apply a pipeline of transforms to data
  */
@@ -124,29 +132,113 @@ function flattenTransform(items: unknown[], config: Transform): unknown[] {
   return flattened;
 }
 
+function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "string") return value.length === 0;
+  return false;
+}
+
+function evaluateCondition(
+  itemObj: Record<string, unknown>,
+  condition: FilterCondition,
+): boolean {
+  const value = itemObj[condition.key];
+  const operator = condition.operator ?? (condition.values ? "eq" : "eq");
+
+  switch (operator) {
+    case "eq":
+      if (!condition.values || condition.values.length === 0) {
+        return condition.key in itemObj;
+      }
+      return condition.values.includes(value);
+    case "neq":
+      if (!condition.values || condition.values.length === 0) {
+        return !(condition.key in itemObj);
+      }
+      return !condition.values.includes(value);
+    case "empty":
+      return isEmpty(value);
+    case "notEmpty":
+      return !isEmpty(value);
+    case "gt":
+      return (
+        typeof value === "number" &&
+        condition.values !== undefined &&
+        value > (condition.values[0] as number)
+      );
+    case "gte":
+      return (
+        typeof value === "number" &&
+        condition.values !== undefined &&
+        value >= (condition.values[0] as number)
+      );
+    case "lt":
+      return (
+        typeof value === "number" &&
+        condition.values !== undefined &&
+        value < (condition.values[0] as number)
+      );
+    case "lte":
+      return (
+        typeof value === "number" &&
+        condition.values !== undefined &&
+        value <= (condition.values[0] as number)
+      );
+    case "contains":
+      if (typeof value === "string" && condition.values) {
+        return condition.values.some((v) => value.includes(String(v)));
+      }
+      if (Array.isArray(value) && condition.values) {
+        return condition.values.some((v) => value.includes(v));
+      }
+      return false;
+    default:
+      return false;
+  }
+}
+
 /**
- * Filter transform - filters items based on a key and optional values
+ * Filter transform - filters items based on conditions
+ *
+ * Supports legacy single key/values syntax and new multi-condition syntax.
+ * When using conditions, all conditions must match (AND logic).
+ *
+ * Operators:
+ *   eq       - item[key] matches one of values (default)
+ *   neq      - item[key] does NOT match any of values
+ *   empty    - item[key] is null, undefined, empty array, or empty string
+ *   notEmpty - inverse of empty
+ *   gt       - item[key] > values[0]
+ *   gte      - item[key] >= values[0]
+ *   lt       - item[key] < values[0]
+ *   lte      - item[key] <= values[0]
+ *   contains - string includes substring, or array includes value
  */
 function filterTransform(items: unknown[], config: Transform): unknown[] {
   const filterConfig = config as FilterTransform;
-  const { key, values } = filterConfig;
+
+  // Build conditions array from either new or legacy syntax
+  let conditions: FilterCondition[];
+
+  if (filterConfig.conditions) {
+    conditions = filterConfig.conditions;
+  } else if (filterConfig.key) {
+    // Legacy single key/values syntax
+    conditions = [{ key: filterConfig.key, values: filterConfig.values }];
+  } else {
+    return items;
+  }
 
   return items.filter((item) => {
     if (typeof item !== "object" || item === null) return false;
-
     const itemObj = item as Record<string, unknown>;
-
-    // If no values array provided, just check if the key exists
-    if (!values || values.length === 0) {
-      return key in itemObj;
-    }
-
-    // If values array provided, check if item[key] matches any of the values
-    const itemValue = itemObj[key];
-    return values.includes(itemValue);
+    return conditions.every((condition) =>
+      evaluateCondition(itemObj, condition),
+    );
   });
 }
 
 // Register built-in transforms
-registerTransform("flatten", flattenTransform);
-registerTransform("filter", filterTransform);
+transformRegistry["flatten"] = flattenTransform;
+transformRegistry["filter"] = filterTransform;