@narrative.io/jsonforms-provider-protocols 2.10.0 → 3.0.0-beta.1

package/src/core/projection.ts

@@ -0,0 +1,136 @@
+/**
+ * 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]`.
+ */
+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> = schema;
+
+  for (const seg of segments) {
+    if (!current) return {};
+
+    if (typeof seg === "number") {
+      // Array index → traverse into items schema
+      const items = current.items;
+      if (items && typeof items === "object") {
+        current = items as Record<string, unknown>;
+      } else {
+        return {};
+      }
+    } else {
+      // Object key → traverse into properties[key]
+      const properties = current.properties as
+        | Record<string, Record<string, unknown>>
+        | undefined;
+      if (properties && properties[seg]) {
+        current = properties[seg];
+      } else {
+        return {};
+      }
+    }
+  }
+
+  return current;
+}

package/src/core/resolveScope.ts

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+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 rootSchema;
+
+  const segments = path.split("/");
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: any = rootSchema;
+
+  for (const segment of segments) {
+    if (!current || typeof current !== "object") return undefined;
+
+    if (segment === "properties") {
+      current = current.properties;
+    } else if (segment === "items") {
+      current = current.items;
+    } else {
+      current = current[segment];
+    }
+  }
+
+  return current;
+}

package/src/core/transforms.ts

@@ -14,30 +14,29 @@ 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 +123,95 @@ 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;

package/src/core/types.ts

@@ -44,3 +44,11 @@ export interface AuthConfig {
   token?: string | (() => string); // Generic token auth
   [key: string]: unknown; // Custom auth fields
 }
+
+export interface ConnectorDataLayer {
+  dataset_name?: string;
+  dataset_description?: string;
+  dataset_id?: number;
+  profile_id?: string;
+  profile_name?: string;
+}

package/src/index.ts

@@ -3,11 +3,15 @@ import { cache as globalCache } from "./core/cache";
 import { registry as globalRegistry } from "./core/registry";
 import type { Protocol, AuthConfig } from "./core/types";
 
+console.log("[jsonforms-provider-protocols] loaded v2.10.0 (symlink)");
+
 export { cache } from "./core/cache";
 export * from "./core/jsonpath";
 export { registry } from "./core/registry";
 export * from "./core/templating";
 export * from "./core/transforms";
+export * from "./core/projection";
+export * from "./core/resolveScope";
 // Core exports
 export * from "./core/types";
 
@@ -22,6 +26,8 @@ export {
   ProviderSelect,
   ProviderMultiSelect,
   useProvider,
+  createDataLayer,
+  useDataLayer,
   JfText,
   JfTextArea,
   JfNumber,
@@ -29,6 +35,7 @@ export {
   JfEnumArray,
   JfBoolean,
 } from "./vue";
+export type { DataLayer } from "./vue";
 
 export interface ProviderConfig {
   protocols?: Protocol[];

package/src/vue/components/ProviderAutocomplete.vue

@@ -3,6 +3,7 @@ import type { ControlElement, JsonSchema } from "@jsonforms/core";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, ref, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
+import { useProjection } from "../composables/useProjection";
 import AutoComplete from "primevue/autocomplete";
 
 const props = defineProps<{
@@ -10,7 +11,8 @@ const props = defineProps<{
   schema: JsonSchema;
   path: string;
 }>();
-const { control, handleChange } = useJsonFormsControl(props);
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -33,7 +35,7 @@ watch(query, () => {
 });
 
 const value = computed({
-  get: () => control.value.data,
+  get: () => projectedData.value,
   set: (v) => handleChange(control.value.path, v),
 });
 

package/src/vue/components/ProviderMultiSelect.vue

@@ -3,6 +3,7 @@ import type { ControlElement, JsonSchema } from "@jsonforms/core";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, inject, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
+import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelectMulti } from "../utils/autoSelect";
 import MultiSelect from "primevue/multiselect";
 
@@ -11,7 +12,8 @@ const props = defineProps<{
   schema: JsonSchema;
   path: string;
 }>();
-const { control, handleChange } = useJsonFormsControl(props);
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -53,7 +55,7 @@ watch(
         control.value.uischema?.options?.autoSelectSingle === true,
       isLoading,
       items: newItems,
-      currentValue: Array.isArray(control.value.data) ? control.value.data : [],
+      currentValue: Array.isArray(projectedData.value) ? projectedData.value : [],
     });
 
     if (valueToSelect !== null) {
@@ -74,13 +76,13 @@ const sameSet = (a: unknown[], b: unknown[]) => {
 // v-model with guard to avoid recursive updates
 const value = computed({
   get() {
-    const curr = Array.isArray(control.value.data) ? control.value.data : [];
+    const curr = Array.isArray(projectedData.value) ? projectedData.value : [];
     // return a fresh copy so MultiSelect can't mutate JSONForms' array in place
     return [...curr];
   },
   set(val) {
     const next = Array.isArray(val) ? [...val] : [];
-    const curr = Array.isArray(control.value.data) ? control.value.data : [];
+    const curr = Array.isArray(projectedData.value) ? projectedData.value : [];
     if (!sameSet(curr, next)) handleChange(control.value.path, next);
   },
 });

package/src/vue/components/ProviderSelect.vue

@@ -3,6 +3,7 @@ import type { ControlElement, JsonSchema } from "@jsonforms/core";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, inject, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
+import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelect } from "../utils/autoSelect";
 import Dropdown from "primevue/dropdown";
 
@@ -11,7 +12,8 @@ const props = defineProps<{
   schema: JsonSchema;
   path: string;
 }>();
-const { control, handleChange } = useJsonFormsControl(props);
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -53,7 +55,7 @@ watch(
         control.value.uischema?.options?.autoSelectSingle !== false,
       isLoading,
       items: newItems,
-      currentValue: control.value.data,
+      currentValue: projectedData.value,
     });
 
     if (valueToSelect !== null) {
@@ -64,7 +66,7 @@ watch(
 );
 
 const value = computed({
-  get: () => control.value.data,
+  get: () => projectedData.value,
   set: (v) => handleChange(control.value.path, v),
 });
 

package/src/vue/composables/useDataLayer.ts

@@ -0,0 +1,43 @@
+import {
+  ref,
+  provide,
+  inject,
+  readonly,
+  type DeepReadonly,
+  type Ref,
+} from "vue";
+import type { ConnectorDataLayer } from "../../core/types";
+
+const DATA_LAYER_KEY = Symbol("dataLayer");
+
+export interface DataLayer {
+  push(data: Partial<ConnectorDataLayer>): void;
+  state: DeepReadonly<Ref<ConnectorDataLayer>>;
+}
+
+export function createDataLayer(): DataLayer {
+  const state = ref<ConnectorDataLayer>({});
+
+  const dataLayer: DataLayer = {
+    push(data: Partial<ConnectorDataLayer>) {
+      state.value = { ...state.value, ...data };
+    },
+    state: readonly(state) as DeepReadonly<Ref<ConnectorDataLayer>>,
+  };
+
+  provide(DATA_LAYER_KEY, dataLayer);
+
+  return dataLayer;
+}
+
+export function useDataLayer(): DeepReadonly<Ref<ConnectorDataLayer>> {
+  const dataLayer = inject<DataLayer | null>(DATA_LAYER_KEY, null);
+  if (dataLayer) {
+    return dataLayer.state;
+  }
+
+  // No dataLayer provided — return empty reactive ref
+  return readonly(ref<ConnectorDataLayer>({})) as DeepReadonly<
+    Ref<ConnectorDataLayer>
+  >;
+}

package/src/vue/composables/useDerive.ts

@@ -1,5 +1,6 @@
-import { computed, watch, inject, type Ref } from "vue";
+import { computed, watch, unref, inject, type Ref, type ComputedRef } from "vue";
 import { type ControlElement } from "@jsonforms/core";
+import { useDataLayer } from "./useDataLayer";
 
 interface DeriveOptions {
   control: Ref<{
@@ -8,20 +9,21 @@ interface DeriveOptions {
     data: unknown;
   }>;
   handleChange: (path: string, value: unknown) => void;
+  /** When projection is active, pass projectedData so the comparison
+   *  matches the projected (unwrapped) value rather than raw scope data. */
+  data?: Ref<unknown> | ComputedRef<unknown>;
 }
 
-export function useDerive({ control, handleChange }: DeriveOptions) {
+export function useDerive({ control, handleChange, data: dataOverride }: DeriveOptions) {
   // Get the root form data from JSONForms context
   const injectedFormData = inject<{ value: unknown }>("formData", {
     value: {},
   });
   const rootData = computed(() => injectedFormData.value || {});
 
-  // Get external data from context if available
-  const injectedExternalData = inject<{ value: unknown }>("externalData", {
-    value: {},
-  });
-  const externalData = computed(() => injectedExternalData.value || {});
+  // Get data from the dataLayer
+  const dataLayerState = useDataLayer();
+  const dataLayerData = computed(() => dataLayerState.value || {});
 
   // Extract derive configuration from uischema options
   const deriveConfig = computed(() => {
@@ -34,9 +36,9 @@ export function useDerive({ control, handleChange }: DeriveOptions) {
     };
   });
 
-  // Watch for changes in form data and external data and update derived field
+  // Watch for changes in form data and dataLayer and update derived field
   watch(
-    [rootData, externalData, deriveConfig],
+    [rootData, dataLayerData, deriveConfig],
     ([data, extData, config]) => {
       if (!config.expression || config.mode !== "follow") {
         return;
@@ -48,7 +50,8 @@ export function useDerive({ control, handleChange }: DeriveOptions) {
           data,
           extData,
         );
-        if (derivedValue !== control.value.data) {
+        const compareData = dataOverride ? unref(dataOverride) : control.value.data;
+        if (derivedValue !== compareData) {
           handleChange(control.value.path, derivedValue);
         }
       } catch (error) {
@@ -65,12 +68,12 @@ export function useDerive({ control, handleChange }: DeriveOptions) {
 function resolveDeriveExpression(
   expression: string,
   data: unknown,
-  externalData?: unknown,
+  dataLayerData?: unknown,
 ): unknown {
-  // Handle externalData() syntax
-  if (expression.startsWith("externalData(") && expression.endsWith(")")) {
-    const propertyPath = expression.slice(13, -1); // Remove "externalData(" and ")"
-    return resolvePropertyPath(propertyPath, externalData);
+  // Handle dataLayer() syntax
+  if (expression.startsWith("dataLayer(") && expression.endsWith(")")) {
+    const propertyPath = expression.slice(10, -1); // Remove "dataLayer(" and ")"
+    return resolvePropertyPath(propertyPath, dataLayerData);
   }
 
   // Handle simple property paths like "country.name"
@@ -82,7 +85,7 @@ function resolveDeriveExpression(
     return resolvePropertyPath(expression, data);
   }
 
-  // For now, we'll only support simple property paths and externalData() calls
+  // For now, we'll only support simple property paths and dataLayer() calls
   // Complex expressions would require a safe expression evaluator
   return resolvePropertyPath(expression, data);
 }

package/src/vue/composables/useProjection.ts

@@ -0,0 +1,74 @@
+import { computed, type ComputedRef, type Ref } from "vue";
+import {
+  getProjectedValue,
+  setProjectedValue,
+  getProjectedSchema,
+} from "../../core/projection";
+
+interface ProjectionControl {
+  data: unknown;
+  path: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: Record<string, any>;
+  uischema: { options?: { projection?: string; [key: string]: unknown } };
+}
+
+export interface ProjectionResult {
+  /** The value at the projected path (for rendering) */
+  projectedData: ComputedRef<unknown>;
+  /** The schema at the projected path (for renderer selection) */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  projectedSchema: ComputedRef<Record<string, any>>;
+  /** Wrapped handleChange that writes through the projection */
+  handleProjectedChange: (path: string, value: unknown) => void;
+  /** Whether projection is active */
+  hasProjection: boolean;
+}
+
+/**
+ * Composable that wraps a JSON Forms control with projection support.
+ *
+ * When `options.projection` is set on the uischema, this composable:
+ * - Reads the projected sub-value from the control data
+ * - Resolves the projected sub-schema for renderer type resolution
+ * - Wraps handleChange to write back through the projection path (preserving siblings)
+ *
+ * When no projection is set, it passes through control data/schema/handleChange unchanged.
+ */
+export function useProjection(
+  control: Ref<ProjectionControl>,
+  handleChange: (path: string, value: unknown) => void,
+): ProjectionResult {
+  const projection = control.value.uischema?.options?.projection as
+    | string
+    | undefined;
+
+  if (!projection) {
+    return {
+      projectedData: computed(() => control.value.data),
+      projectedSchema: computed(() => control.value.schema),
+      handleProjectedChange: handleChange,
+      hasProjection: false,
+    };
+  }
+
+  const projectedData = computed(() =>
+    getProjectedValue(control.value.data, projection),
+  );
+
+  const projectedSchema = computed(() =>
+    getProjectedSchema(control.value.schema, projection),
+  );
+
+  const handleProjectedChange = (path: string, value: unknown) => {
+    const fullValue = setProjectedValue(control.value.data, projection, value);
+    handleChange(path, fullValue);
+  };
+
+  return {
+    projectedData,
+    projectedSchema,
+    handleProjectedChange,
+    hasProjection: true,
+  };
+}