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

package/README.md

@@ -108,11 +108,9 @@ const handleChange = (event) => data.value = event.data
 
 ### Examples
 - [Simple Dropdown](./docs/examples/simple-dropdown.md)
-- [Cascading Dropdowns](./docs/examples/cascading-dropdowns.md) 
-- [Autocomplete Search](./docs/examples/autocomplete-search.md)
-- [Custom Protocols](./docs/examples/custom-protocol.md)
 - [Custom Renderers](./docs/examples/custom-renderer.md)
-- [More Examples](./docs/examples/README.md)
+- [All Examples](./docs/examples/README.md)
+- For end-to-end usage of data layer, projection, validation gating, and the CSP-safe validator, see the demo app in `demo/`
 
 ### Help & Troubleshooting
 - [Troubleshooting Guide](./docs/troubleshooting.md)
@@ -190,7 +188,9 @@ Recursively flattens nested tree structures into a single-level array:
 - Adds `_depth`, `_parent`, and `_formattedLabel` metadata to items
 
 **Filter Transform**
-Filters items based on property values:
+Filters items based on conditions. Supports a simple single-key syntax and a multi-condition syntax with operators.
+
+Simple syntax (single key/values):
 
 ```json
 {
@@ -200,8 +200,31 @@ Filters items based on property values:
 }
 ```
 
-- `key`: The property to check
-- `values` (optional): Array of values to match. If omitted, filters by key existence
+Multi-condition syntax (AND logic):
+
+```json
+{
+  "name": "filter",
+  "conditions": [
+    { "key": "status", "values": ["active"] },
+    { "key": "connections", "operator": "empty" }
+  ]
+}
+```
+
+Available operators:
+
+| Operator | Description |
+|----------|-------------|
+| `eq` | Value matches one of `values` (default) |
+| `neq` | Value does NOT match any of `values` |
+| `empty` | Value is null, undefined, empty array, or empty string |
+| `notEmpty` | Inverse of `empty` |
+| `gt` | Value > `values[0]` |
+| `gte` | Value >= `values[0]` |
+| `lt` | Value < `values[0]` |
+| `lte` | Value <= `values[0]` |
+| `contains` | String includes substring, or array includes value |
 
 **Combining Transforms**
 Transforms are applied sequentially in pipeline order:
@@ -215,20 +238,6 @@ Transforms are applied sequentially in pipeline order:
 }
 ```
 
-**Custom Transforms**
-Register custom transforms for your specific needs:
-
-```typescript
-import { registerTransform } from '@narrative.io/jsonforms-provider-protocols'
-
-registerTransform('uppercase', (items, config) => {
-  return items.map(item => ({
-    ...item,
-    name: item.name.toUpperCase()
-  }))
-})
-```
-
 ### Template Variables
 Create dynamic URLs using form data:
 
@@ -247,7 +256,7 @@ Control when data is fetched:
 - `query` - Load when user types (autocomplete)
 
 ### Derive Functionality
-Auto-populate fields from form data or external sources:
+Auto-populate fields from form data or the dataLayer:
 
 ```json
 {
@@ -261,33 +270,56 @@ Auto-populate fields from form data or external sources:
 }
 ```
 
-#### External Data Support
-Access external data sources separate from form data using the `externalData()` syntax:
+#### DataLayer Support
+Inject external data into forms using the `createDataLayer` API and reference it with the `dataLayer()` derive syntax:
 
 ```vue
 <script setup>
-// Provide external data to the form
-const externalData = ref({
-  user: { preferences: { theme: "dark" } },
-  tree: { name: "Oak", type: "Deciduous" }
-})
+import { createDataLayer } from '@narrative.io/jsonforms-provider-protocols'
+
+const dataLayer = createDataLayer()
+dataLayer.push({ dataset_name: "My Dataset" })
 
-provide('externalData', externalData)
+// Merge additional data at any time
+dataLayer.push({ dataset_id: 42 })
 </script>
 ```
 
 ```json
 {
-  "type": "Control", 
-  "scope": "#/properties/tree_preference",
+  "type": "Control",
+  "scope": "#/properties/audience",
   "options": {
-    "derive": "externalData(tree.name)",
+    "derive": "dataLayer(dataset_name)",
     "mode": "follow",
     "readonly": true
   }
 }
 ```
 
+The `ConnectorDataLayer` type defines available properties:
+
+```typescript
+interface ConnectorDataLayer {
+  dataset_name?: string
+  dataset_description?: string
+  dataset_id?: number
+  profile_id?: string
+  profile_name?: string
+}
+```
+
+You can also read the dataLayer state directly in components:
+
+```vue
+<script setup>
+import { useDataLayer } from '@narrative.io/jsonforms-provider-protocols'
+
+const dataLayerState = useDataLayer()
+// dataLayerState.value.dataset_name
+</script>
+```
+
 ### Error Handling
 Control error display behavior with the `showError` property:
 
@@ -307,6 +339,44 @@ Control error display behavior with the `showError` property:
 
 When `showError` is `false`, failed requests return empty results instead of throwing errors. Defaults to `true`.
 
+### Projection
+Render simple controls (text, number) against deeply nested or array-wrapped data structures using the `projection` UISchema option. The control sees a simple value, while the underlying form data maintains the full structure.
+
+The projection path is **relative to the control's `scope`**. So when `scope` is `#/properties/data_rates` and the projection is `"0.video_rate_usd"`, it resolves to `data_rates[0].video_rate_usd` in the form data:
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/data_rates",
+  "options": {
+    "placeholder": "Enter video rate...",
+    "projection": "0.video_rate_usd"
+  }
+}
+```
+
+With form data `{ data_rates: [{ video_rate_usd: 2.5, display_rate_usd: 1.5 }] }`, the control renders `2.5` as a simple number input. When the user changes the value, only `video_rate_usd` is updated — all sibling properties are preserved.
+
+**Path syntax:** Dot-separated segments (similar to Lodash `_.get`) where numeric segments are array indices and string segments are object keys.
+
+| Projection Path | Data Shape | Control Sees |
+|-----------------|-----------|-------------|
+| `0` | `[123]` | `123` |
+| `0.video_rate_usd` | `[{ video_rate_usd: 2.5 }]` | `2.5` |
+| `include` | `{ include: ["a", "b"] }` | `["a", "b"]` |
+
+The schema is also resolved through the projection path, so validation works correctly on the projected value.
+
+Use `useProjection` directly in custom components:
+
+```vue
+<script setup>
+import { useProjection } from '@narrative.io/jsonforms-provider-protocols'
+
+const { projectedData, projectedSchema, handleProjectedChange, hasProjection } = useProjection(control, handleChange)
+</script>
+```
+
 ### Composables
 Use providers directly in your components:
 
@@ -318,6 +388,96 @@ const { items, loading, error, reload } = useProvider(binding, context)
 </script>
 ```
 
+The library also exposes `useProjection`, `useDirtyValidation`, `useDataLayer`, and `useDeriveInitialValue` for custom renderers — see [Vue Components](./docs/components.md) and the [API Reference](./docs/api/README.md).
+
+### Object Multi-Select
+
+For arrays whose items are paired objects (e.g. `[{ dataset_id, dataset_name }]`), `ProviderObjectMultiSelect` registers automatically and translates between the form-data shape and PrimeVue's `<MultiSelect>` model:
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/datasets",
+  "options": {
+    "objectKeys": { "value": "dataset_id", "label": "dataset_name" },
+    "autoSelectSingle": true,
+    "provider": { "ref": "datasets", "protocol": "rest_api", "config": { "...": "..." } }
+  }
+}
+```
+
+`objectKeys` is inferred from the array's `items.required` when one of the two required properties has `format: "uuid"`. Specify explicitly to override.
+
+### Schema-Aware Initialization
+
+`initFormDataFromSchema` walks `$ref`/`$defs`, seeds `const` and `default` values (including through optional `oneOf` containers), and omits unset optionals:
+
+```typescript
+import { initFormDataFromSchema, seedProjectionTargets } from '@narrative.io/jsonforms-provider-protocols'
+
+const data = seedProjectionTargets(initFormDataFromSchema(schema), uischema)
+```
+
+`seedProjectionTargets` is needed when an `options.projection` control targets an array index — without it, `items.required` validators see no item to apply against and the asterisk on the projected control would lie. It's idempotent and preserves any existing values at the target paths.
+
+### Validation Gating
+
+Renderers (both built-in and custom, via `useDirtyValidation`) gate error display behind user interaction. Errors and `p-invalid` styling appear only after `blur` (text/number/select) or first `change` (checkbox/multiselect). The full AJV error array still flows through `<JsonForms @change>` unchanged, so consumers decide separately when to enable a submit button.
+
+### Derive Initial Value (Async)
+
+When the initial value of a field comes from an API call rather than from local form data, use `options.deriveInitialValue`:
+
+```json
+{
+  "type": "Control",
+  "scope": "#/properties/advertiser",
+  "options": {
+    "deriveInitialValue": {
+      "protocol": "rest_api",
+      "config": {
+        "url": "https://api.example.com/profiles/{{data.profile_id}}",
+        "items": "$",
+        "map": { "value": "$.mdm_id" }
+      }
+    }
+  }
+}
+```
+
+The fetched value is applied on mount once template variables resolve, re-fetched when dependencies change, and not re-applied when the user has already changed the field with the same template context. See [API: useDeriveInitialValue](./docs/api/README.md#usederiveinitialvalue).
+
+### CSP-Safe Validation
+
+For environments that forbid `new Function` (Cloudflare Pages, strict CSP), import the AJV-shaped facade backed by `@cfworker/json-schema` from the `./no-eval-ajv` subpath:
+
+```typescript
+import { createNoEvalAjv } from '@narrative.io/jsonforms-provider-protocols/no-eval-ajv'
+
+const ajv = createNoEvalAjv({ draft: '2020-12' })
+```
+
+```vue
+<JsonForms
+  :data="data"
+  :schema="schema"
+  :uischema="uischema"
+  :ajv="ajv"
+  :renderers="markRaw(providerRenderers)"
+  @change="handleChange"
+/>
+```
+
+Only `compile()` is functional; `addSchema`/`getSchema`/`addFormat`/`addKeyword` are no-ops kept for forward compatibility with plugins that probe the AJV interface. AJV error shapes (`instancePath`, `keyword`, `params`, `message`) are preserved so JsonForms can render errors identically.
+
+### Migrating from Earlier Betas
+
+| Old API | New API |
+|---------|---------|
+| `provide('externalData', ref)` | `createDataLayer().provide()` |
+| `derive: "externalData(field)"` | `derive: "dataLayer(field)"` |
+| `registerTransform(...)` | Filter transform `conditions` array (see [Filter Transform](#built-in-transforms)) |
+
 ## 🛠 Development
 
 ```bash

package/dist/core/initFormData.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Initialize a form data object from a JSON Schema.
+ * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.
+ *
+ * Optional fields (not listed in the parent schema's `required` array) that
+ * have no `const`, no single-value `enum`, and no `default` are omitted
+ * entirely from the result. This avoids seeding values (e.g. `null` for
+ * `type: "integer"`) that fail AJV's type check and surface spurious errors
+ * on untouched fields. Required fields retain legacy typed-empty seeding
+ * (`""`, `null`, `false`, `[]`) so that "is required" surfaces cleanly.
+ *
+ * @param schema - The full JSON Schema (must include $defs if $refs are used)
+ * @param seed   - Optional existing data to merge (seed values take priority)
+ * @returns A data object with schema-defined fields initialized
+ */
+export declare function initFormDataFromSchema(schema: Record<string, unknown>, seed?: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=initFormData.d.ts.map

package/dist/core/initFormData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initFormData.d.ts","sourceRoot":"","sources":["../../src/core/initFormData.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BzB"}

package/dist/core/initFormData.js

@@ -0,0 +1,99 @@
+import { resolveRef } from "./refs.js";
+function initFormDataFromSchema(schema, seed) {
+  const result = initProperty(schema, schema, seed, true);
+  const base = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+  if (seed && typeof seed === "object") {
+    const schemaKeys = new Set(
+      Object.keys(
+        resolveRef(schema, schema)?.properties ?? {}
+      )
+    );
+    for (const key of Object.keys(seed)) {
+      if (!schemaKeys.has(key) && !(key in base)) {
+        base[key] = seed[key];
+      }
+    }
+  }
+  return base;
+}
+function initProperty(property, root, seed, required) {
+  if (!property || typeof property !== "object") {
+    return required ? null : void 0;
+  }
+  const resolved = resolveRef(property, root);
+  const type = resolved.type;
+  const isOneOf = Array.isArray(resolved.oneOf);
+  if (seed !== void 0 && seed !== null && type !== "object" && !isOneOf) {
+    return seed;
+  }
+  if ("const" in resolved) {
+    return resolved.const;
+  }
+  if (Array.isArray(resolved.enum) && resolved.enum.length === 1) {
+    return resolved.enum[0];
+  }
+  if ("default" in resolved) {
+    return resolved.default;
+  }
+  if (isOneOf) {
+    const value = initOneOf(resolved, root, seed, required);
+    if (!required && (value === void 0 || value !== null && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 0)) {
+      return void 0;
+    }
+    return value;
+  }
+  if (type === "object") {
+    const obj = initObject(
+      resolved,
+      root,
+      seed,
+      required
+    );
+    if (!required && Object.keys(obj).length === 0) return void 0;
+    return obj;
+  }
+  if (!required) return void 0;
+  switch (type) {
+    case "array":
+      return seed !== void 0 && seed !== null ? seed : [];
+    case "string":
+      return "";
+    case "boolean":
+      return false;
+    case "number":
+    case "integer":
+    default:
+      return null;
+  }
+}
+function initObject(schema, root, seed, parentRequired) {
+  const properties = schema.properties;
+  if (!properties) {
+    return seed && typeof seed === "object" ? { ...seed } : {};
+  }
+  const requiredSet = new Set(
+    Array.isArray(schema.required) ? schema.required : []
+  );
+  const result = {};
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const seedValue = seed && typeof seed === "object" ? seed[key] : void 0;
+    const effectiveRequired = parentRequired && requiredSet.has(key);
+    const value = initProperty(propSchema, root, seedValue, effectiveRequired);
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function initOneOf(schema, root, seed, required) {
+  const variants = schema.oneOf;
+  if (!variants || variants.length === 0) return required ? null : void 0;
+  const first = variants[0];
+  if (!first) return required ? null : void 0;
+  const firstVariant = resolveRef(first, root);
+  return initProperty(firstVariant, root, seed, required);
+}
+export {
+  initFormDataFromSchema
+};
+//# sourceMappingURL=initFormData.js.map

package/dist/core/initFormData.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initFormData.js","sources":["../../src/core/initFormData.ts"],"sourcesContent":["/**\n * Initialize a form data object from a JSON Schema.\n * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.\n *\n * Optional fields (not listed in the parent schema's `required` array) that\n * have no `const`, no single-value `enum`, and no `default` are omitted\n * entirely from the result. This avoids seeding values (e.g. `null` for\n * `type: \"integer\"`) that fail AJV's type check and surface spurious errors\n * on untouched fields. Required fields retain legacy typed-empty seeding\n * (`\"\"`, `null`, `false`, `[]`) so that \"is required\" surfaces cleanly.\n *\n * @param schema - The full JSON Schema (must include $defs if $refs are used)\n * @param seed   - Optional existing data to merge (seed values take priority)\n * @returns A data object with schema-defined fields initialized\n */\nexport function initFormDataFromSchema(\n  schema: Record<string, unknown>,\n  seed?: Record<string, unknown>,\n): Record<string, unknown> {\n  const result = initProperty(schema, schema, seed, true) as\n    | Record<string, unknown>\n    | undefined;\n\n  const base =\n    result && typeof result === \"object\" && !Array.isArray(result)\n      ? result\n      : {};\n\n  // Preserve seed keys not described by the schema's properties.\n  if (seed && typeof seed === \"object\") {\n    const schemaKeys = new Set(\n      Object.keys(\n        (resolveRef(schema, schema) as Record<string, unknown>)?.properties ??\n          {},\n      ),\n    );\n    for (const key of Object.keys(seed)) {\n      if (!schemaKeys.has(key) && !(key in base)) {\n        base[key] = seed[key];\n      }\n    }\n  }\n\n  return base;\n}\n\nimport { resolveRef } from \"./refs\";\n\n/**\n * Initialize a single property value based on its schema definition.\n * Returns `undefined` when the property is optional and has nothing\n * concrete to seed — the caller then omits the key from its result.\n */\nfunction initProperty(\n  property: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  if (!property || typeof property !== \"object\") {\n    return required ? null : undefined;\n  }\n\n  const resolved = resolveRef(property, root);\n  const type = resolved.type as string | undefined;\n  const isOneOf = Array.isArray(resolved.oneOf);\n\n  // Priority 1: seed wins for non-object, non-oneOf types. For oneOf we still\n  // descend so that a partial seed (e.g. `{value: 5}` missing the\n  // discriminator) picks up the variant's const/default for untouched fields.\n  if (seed !== undefined && seed !== null && type !== \"object\" && !isOneOf) {\n    return seed;\n  }\n\n  // Priority 2: const (schema-invariant — always set).\n  if (\"const\" in resolved) {\n    return resolved.const;\n  }\n\n  // Priority 3: single-value enum (same reasoning — only one valid value).\n  if (\n    Array.isArray(resolved.enum) &&\n    (resolved.enum as unknown[]).length === 1\n  ) {\n    return (resolved.enum as unknown[])[0];\n  }\n\n  // Priority 4: default (explicit author intent — always honored).\n  if (\"default\" in resolved) {\n    return resolved.default;\n  }\n\n  // Priority 5: oneOf. Recurse into the first variant, propagating the\n  // `required` flag so that the variant's own schema-declared required fields\n  // only get typed-empty seeding when the container is required. For optional\n  // containers, the variant's const / default / single-value enum still seed\n  // (author intent is unconditional) but typed-empty placeholders do not.\n  // If recursion yields nothing forced, we collapse back to undefined.\n  if (isOneOf) {\n    const value = initOneOf(resolved, root, seed, required);\n    if (\n      !required &&\n      (value === undefined ||\n        (value !== null &&\n          typeof value === \"object\" &&\n          !Array.isArray(value) &&\n          Object.keys(value as Record<string, unknown>).length === 0))\n    ) {\n      return undefined;\n    }\n    return value;\n  }\n\n  // Priority 6: objects recurse. The `required` flag propagates downward:\n  // inside an optional ancestor, nested required primitives also collapse,\n  // so an optional object with nested required fields stays absent instead\n  // of materializing a shell that AJV would flag.\n  if (type === \"object\") {\n    const obj = initObject(\n      resolved,\n      root,\n      seed as Record<string, unknown>,\n      required,\n    );\n    if (!required && Object.keys(obj).length === 0) return undefined;\n    return obj;\n  }\n\n  // Priority 7: optional primitives — omit.\n  if (!required) return undefined;\n\n  // Priority 8: required primitives — legacy typed empty.\n  switch (type) {\n    case \"array\":\n      return seed !== undefined && seed !== null ? seed : [];\n    case \"string\":\n      return \"\";\n    case \"boolean\":\n      return false;\n    case \"number\":\n    case \"integer\":\n    default:\n      return null;\n  }\n}\n\n/**\n * Initialize an object type by recursing into its properties.\n * Keys whose initialization returns `undefined` are omitted.\n *\n * `parentRequired` controls how schema.required propagates: a child is\n * treated as required only if both its parent is required AND it appears in\n * the parent's required array. Inside an optional ancestor the whole\n * subtree collapses (except for author-forced values: const, default,\n * single-value enum, or seeded values).\n */\nfunction initObject(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: Record<string, unknown> | undefined,\n  parentRequired: boolean,\n): Record<string, unknown> {\n  const properties = schema.properties as\n    | Record<string, Record<string, unknown>>\n    | undefined;\n  if (!properties) {\n    return seed && typeof seed === \"object\" ? { ...seed } : {};\n  }\n\n  const requiredSet = new Set<string>(\n    Array.isArray(schema.required) ? (schema.required as string[]) : [],\n  );\n\n  const result: Record<string, unknown> = {};\n\n  for (const [key, propSchema] of Object.entries(properties)) {\n    const seedValue = seed && typeof seed === \"object\" ? seed[key] : undefined;\n    const effectiveRequired = parentRequired && requiredSet.has(key);\n    const value = initProperty(propSchema, root, seedValue, effectiveRequired);\n    if (value !== undefined) {\n      result[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Handle oneOf schemas — pick the first variant and initialize it.\n * `required` propagates: if the outer oneOf is required, the variant is\n * materialized with typed-empty seeding for its required fields; if optional,\n * only author-forced values (const / default / single-enum / seed) survive.\n */\nfunction initOneOf(\n  schema: Record<string, unknown>,\n  root: Record<string, unknown>,\n  seed: unknown,\n  required: boolean,\n): unknown {\n  const variants = schema.oneOf as Record<string, unknown>[];\n  if (!variants || variants.length === 0) return required ? null : undefined;\n\n  const first = variants[0];\n  if (!first) return required ? null : undefined;\n\n  const firstVariant = resolveRef(first, root);\n  return initProperty(firstVariant, root, seed, required);\n}\n"],"names":[],"mappings":"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"}

package/dist/core/projection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 declare function parseProjectionPath(path: string): ProjectionSegment[];
+/**
+ * Read a value from `data` by following the projection path.
+ * Returns `undefined` if any segment along the path is missing.
+ */
+export declare function getProjectedValue(data: unknown, path: string): unknown;
+/**
+ * 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 declare function setProjectedValue(data: unknown, path: string, value: unknown): unknown;
+/**
+ * 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 declare function getProjectedSchema(schema: Record<string, any>, path: string): Record<string, any>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/core/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../src/core/projection.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAMrE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAGT;AAqCD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAEhC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GAEX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAmCrB"}

package/dist/core/projection.js

@@ -0,0 +1,77 @@
+import { deref, tryCombinatorBranches } from "./refs.js";
+function parseProjectionPath(path) {
+  if (!path) return [];
+  return path.split(".").map((s) => {
+    const n = Number(s);
+    return Number.isInteger(n) && n >= 0 ? n : s;
+  });
+}
+function getProjectedValue(data, path) {
+  const segments = parseProjectionPath(path);
+  let current = data;
+  for (const seg of segments) {
+    if (current === null || current === void 0) return void 0;
+    if (typeof seg === "number") {
+      if (!Array.isArray(current)) return void 0;
+      current = current[seg];
+    } else {
+      if (typeof current !== "object") return void 0;
+      current = current[seg];
+    }
+  }
+  return current;
+}
+function setProjectedValue(data, path, value) {
+  const segments = parseProjectionPath(path);
+  return setAtPath(data, segments, 0, value);
+}
+function setAtPath(current, segments, index, value) {
+  if (index === segments.length) {
+    return value;
+  }
+  const seg = segments[index];
+  if (typeof seg === "number") {
+    const arr = Array.isArray(current) ? [...current] : [];
+    while (arr.length <= seg) {
+      arr.push(void 0);
+    }
+    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);
+    return arr;
+  } else {
+    const obj = current !== null && current !== void 0 && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
+    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);
+    return obj;
+  }
+}
+function getProjectedSchema(schema, path) {
+  const segments = parseProjectionPath(path);
+  let current = schema;
+  for (const seg of segments) {
+    current = deref(current, schema);
+    if (!current) return {};
+    const navigate = (node) => {
+      if (typeof seg === "number") {
+        const items = node.items;
+        return items && typeof items === "object" ? items : void 0;
+      }
+      const properties = node.properties;
+      if (properties && properties[seg]) return properties[seg];
+      return void 0;
+    };
+    let next = navigate(current);
+    if (next === void 0) {
+      next = tryCombinatorBranches(current, schema, navigate);
+    }
+    if (!next) return {};
+    current = next;
+  }
+  const resolved = deref(current, schema);
+  return resolved ?? {};
+}
+export {
+  getProjectedSchema,
+  getProjectedValue,
+  parseProjectionPath,
+  setProjectedValue
+};
+//# sourceMappingURL=projection.js.map

package/dist/core/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sources":["../../src/core/projection.ts"],"sourcesContent":["import { deref as derefSchema, tryCombinatorBranches } from \"./refs\";\n\n/**\n * Projection utilities for navigating complex data structures\n * through a dot-separated path where numeric segments are array indices.\n *\n * Examples:\n *   \"0\"                → first element of an array\n *   \"include\"          → the `include` property of an object\n *   \"0.video_rate_usd\" → nested property inside the first array element\n */\n\nexport type ProjectionSegment = string | number;\n\n/**\n * Parse a projection path string into typed segments.\n * Numeric strings become numbers (array indices), others stay as strings (object keys).\n */\nexport function parseProjectionPath(path: string): ProjectionSegment[] {\n  if (!path) return [];\n  return path.split(\".\").map((s) => {\n    const n = Number(s);\n    return Number.isInteger(n) && n >= 0 ? n : s;\n  });\n}\n\n/**\n * Read a value from `data` by following the projection path.\n * Returns `undefined` if any segment along the path is missing.\n */\nexport function getProjectedValue(data: unknown, path: string): unknown {\n  const segments = parseProjectionPath(path);\n  let current: unknown = data;\n\n  for (const seg of segments) {\n    if (current === null || current === undefined) return undefined;\n\n    if (typeof seg === \"number\") {\n      if (!Array.isArray(current)) return undefined;\n      current = current[seg];\n    } else {\n      if (typeof current !== \"object\") return undefined;\n      current = (current as Record<string, unknown>)[seg];\n    }\n  }\n\n  return current;\n}\n\n/**\n * Immutably set a value at the projection path, preserving all sibling data.\n * Constructs missing intermediate structures (arrays for numeric segments, objects for string segments).\n */\nexport function setProjectedValue(\n  data: unknown,\n  path: string,\n  value: unknown,\n): unknown {\n  const segments = parseProjectionPath(path);\n  return setAtPath(data, segments, 0, value);\n}\n\nfunction setAtPath(\n  current: unknown,\n  segments: ProjectionSegment[],\n  index: number,\n  value: unknown,\n): unknown {\n  if (index === segments.length) {\n    return value;\n  }\n\n  const seg = segments[index]!;\n\n  if (typeof seg === \"number\") {\n    // Array index — ensure we have an array\n    const arr = Array.isArray(current) ? [...current] : [];\n    // Pad array if index is out of bounds\n    while (arr.length <= seg) {\n      arr.push(undefined);\n    }\n    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);\n    return arr;\n  } else {\n    // Object key — ensure we have an object\n    const obj: Record<string, unknown> =\n      current !== null &&\n      current !== undefined &&\n      typeof current === \"object\" &&\n      !Array.isArray(current)\n        ? { ...(current as Record<string, unknown>) }\n        : {};\n    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);\n    return obj;\n  }\n}\n\n/**\n * Resolve the schema at the projected path.\n * Numeric segments traverse into `items` (array item schema).\n * String segments traverse into `properties[segment]`.\n *\n * Dereferences `$ref` nodes transparently at every step, and falls through\n * to `oneOf` / `anyOf` / `allOf` branches when a segment can't resolve\n * directly — picks the first branch that satisfies the navigation.\n */\nexport function getProjectedSchema(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  schema: Record<string, any>,\n  path: string,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): Record<string, any> {\n  const segments = parseProjectionPath(path);\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  let current: Record<string, any> | undefined = schema;\n\n  for (const seg of segments) {\n    current = derefSchema(current, schema);\n    if (!current) return {};\n\n    const navigate = (\n      node: Record<string, unknown>,\n    ): Record<string, unknown> | undefined => {\n      if (typeof seg === \"number\") {\n        const items = (node as { items?: unknown }).items;\n        return items && typeof items === \"object\"\n          ? (items as Record<string, unknown>)\n          : undefined;\n      }\n      const properties = (node as { properties?: unknown }).properties as\n        | Record<string, Record<string, unknown>>\n        | undefined;\n      if (properties && properties[seg]) return properties[seg];\n      return undefined;\n    };\n\n    let next = navigate(current);\n    if (next === undefined) {\n      next = tryCombinatorBranches(current, schema, navigate);\n    }\n    if (!next) return {};\n    current = next;\n  }\n\n  const resolved = derefSchema(current, schema);\n  return resolved ?? {};\n}\n"],"names":["derefSchema"],"mappings":";AAkBO,SAAS,oBAAoB,MAAmC;AACrE,MAAI,CAAC,KAAM,QAAO,CAAA;AAClB,SAAO,KAAK,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM;AAChC,UAAM,IAAI,OAAO,CAAC;AAClB,WAAO,OAAO,UAAU,CAAC,KAAK,KAAK,IAAI,IAAI;AAAA,EAC7C,CAAC;AACH;AAMO,SAAS,kBAAkB,MAAe,MAAuB;AACtE,QAAM,WAAW,oBAAoB,IAAI;AACzC,MAAI,UAAmB;AAEvB,aAAW,OAAO,UAAU;AAC1B,QAAI,YAAY,QAAQ,YAAY,OAAW,QAAO;AAEtD,QAAI,OAAO,QAAQ,UAAU;AAC3B,UAAI,CAAC,MAAM,QAAQ,OAAO,EAAG,QAAO;AACpC,gBAAU,QAAQ,GAAG;AAAA,IACvB,OAAO;AACL,UAAI,OAAO,YAAY,SAAU,QAAO;AACxC,gBAAW,QAAoC,GAAG;AAAA,IACpD;AAAA,EACF;AAEA,SAAO;AACT;AAMO,SAAS,kBACd,MACA,MACA,OACS;AACT,QAAM,WAAW,oBAAoB,IAAI;AACzC,SAAO,UAAU,MAAM,UAAU,GAAG,KAAK;AAC3C;AAEA,SAAS,UACP,SACA,UACA,OACA,OACS;AACT,MAAI,UAAU,SAAS,QAAQ;AAC7B,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,SAAS,KAAK;AAE1B,MAAI,OAAO,QAAQ,UAAU;AAE3B,UAAM,MAAM,MAAM,QAAQ,OAAO,IAAI,CAAC,GAAG,OAAO,IAAI,CAAA;AAEpD,WAAO,IAAI,UAAU,KAAK;AACxB,UAAI,KAAK,MAAS;AAAA,IACpB;AACA,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT,OAAO;AAEL,UAAM,MACJ,YAAY,QACZ,YAAY,UACZ,OAAO,YAAY,YACnB,CAAC,MAAM,QAAQ,OAAO,IAClB,EAAE,GAAI,QAAA,IACN,CAAA;AACN,QAAI,GAAG,IAAI,UAAU,IAAI,GAAG,GAAG,UAAU,QAAQ,GAAG,KAAK;AACzD,WAAO;AAAA,EACT;AACF;AAWO,SAAS,mBAEd,QACA,MAEqB;AACrB,QAAM,WAAW,oBAAoB,IAAI;AAEzC,MAAI,UAA2C;AAE/C,aAAW,OAAO,UAAU;AAC1B,cAAUA,MAAY,SAAS,MAAM;AACrC,QAAI,CAAC,QAAS,QAAO,CAAA;AAErB,UAAM,WAAW,CACf,SACwC;AACxC,UAAI,OAAO,QAAQ,UAAU;AAC3B,cAAM,QAAS,KAA6B;AAC5C,eAAO,SAAS,OAAO,UAAU,WAC5B,QACD;AAAA,MACN;AACA,YAAM,aAAc,KAAkC;AAGtD,UAAI,cAAc,WAAW,GAAG,EAAG,QAAO,WAAW,GAAG;AACxD,aAAO;AAAA,IACT;AAEA,QAAI,OAAO,SAAS,OAAO;AAC3B,QAAI,SAAS,QAAW;AACtB,aAAO,sBAAsB,SAAS,QAAQ,QAAQ;AAAA,IACxD;AACA,QAAI,CAAC,KAAM,QAAO,CAAA;AAClB,cAAU;AAAA,EACZ;AAEA,QAAM,WAAWA,MAAY,SAAS,MAAM;AAC5C,SAAO,YAAY,CAAA;AACrB;"}

package/dist/core/refs.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare function resolvePointer(obj: Record<string, unknown>, pointer: string): unknown;
+/**
+ * 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 declare function resolveRef(property: Record<string, unknown>, root: Record<string, unknown>, seen?: Set<string>): Record<string, unknown>;
+/**
+ * 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 declare function deref(node: Record<string, any> | undefined, root: Record<string, any>): Record<string, any> | undefined;
+/**
+ * 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 declare function tryCombinatorBranches<T>(node: Record<string, any> | undefined, root: Record<string, any>, tryFn: (candidate: Record<string, any>) => T | undefined, depth?: number): T | 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 declare function deepDeref(node: any, root: Record<string, any>, seen?: Set<string>): any;
+//# sourceMappingURL=refs.d.ts.map

package/dist/core/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/core/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,MAAM,GACd,OAAO,CAYT;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAEnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAErC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAExB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAGjC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAErC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAErC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAEzB,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,EACxD,KAAK,SAAI,GACR,CAAC,GAAG,SAAS,CAoBf;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAEvB,IAAI,EAAE,GAAG,EAET,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,IAAI,GAAE,GAAG,CAAC,MAAM,CAAa,GAE5B,GAAG,CAoBL"}