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

package/src/vue/composables/useProjection.ts

@@ -0,0 +1,245 @@
+import { computed, inject, type ComputedRef, type Ref } from "vue";
+import {
+  getProjectedValue,
+  setProjectedValue,
+  getProjectedSchema,
+  parseProjectionPath,
+} from "../../core/projection";
+import { deref } from "../../core/refs";
+
+interface ProjectionControl {
+  data: unknown;
+  path: string;
+  errors: string;
+  label?: string;
+  required?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: Record<string, any>;
+  uischema: { options?: { projection?: string; [key: string]: unknown } };
+}
+
+// Minimal AJV ErrorObject shape for filtering
+interface ErrorLike {
+  instancePath?: string;
+  keyword?: string;
+  message?: string;
+  params?: { missingProperty?: string };
+}
+
+/**
+ * Resolve the display label for a control.
+ * Priority: uischema options.label → schemaTitle (projected sub-schema) → control.label.
+ * Appends a trailing asterisk when the control is for a required property.
+ */
+function resolveLabel(
+  ctrl: ProjectionControl,
+  schemaTitle?: string,
+  required?: boolean,
+): string {
+  const base =
+    (ctrl.uischema?.options?.label as string) ??
+    schemaTitle ??
+    ctrl.label ??
+    "";
+  if (!base) return base;
+  return required ? `${base} *` : base;
+}
+
+/**
+ * Determine whether the leaf of a projection path is listed in its parent
+ * schema's `required` array. Numeric leaf segments (array indices) are not
+ * considered "required properties".
+ *
+ * Dereferences `$ref` at every step against `root` (defaulting to `schema`)
+ * so that schemas like `items: { $ref: '#/$defs/Foo' }` resolve correctly.
+ */
+function isProjectedFieldRequired(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: Record<string, any>,
+  path: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root?: Record<string, any>,
+): boolean {
+  const segments = parseProjectionPath(path);
+  if (segments.length === 0) return false;
+  const rootSchema = root ?? schema;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: Record<string, any> | undefined = deref(schema, rootSchema);
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i]!;
+    if (typeof seg === "number") {
+      current = deref(current?.items, rootSchema);
+    } else {
+      current = deref(current?.properties?.[seg], rootSchema);
+    }
+    if (!current) return false;
+  }
+  const last = segments[segments.length - 1];
+  if (typeof last !== "string") return false;
+  current = deref(current, rootSchema);
+  return Array.isArray(current?.required) && current.required.includes(last);
+}
+
+/**
+ * Normalize AJV error message fragments into user-friendly text.
+ * e.g. "is a required property" → "is required"
+ */
+function normalizeErrors(errors: string): string {
+  if (!errors) return errors;
+  return errors
+    .replace(/is a required property/g, "is required")
+    .replace(/must have required property '[^']*'/g, "is required");
+}
+
+/**
+ * Prefix each error message line with the field label so that AJV fragments
+ * like "is required" become "Name is required".
+ */
+function prefixErrors(label: string, errors: string): string {
+  if (!label || !errors) return errors;
+  return errors
+    .split("\n")
+    .map((line) => `${label} ${line}`)
+    .join("\n");
+}
+
+/**
+ * Convert an AJV ErrorObject's instancePath to a dot-separated control path.
+ * Replicates the logic from @jsonforms/core getControlPath.
+ */
+function getErrorPath(error: ErrorLike): string {
+  let p = (error.instancePath || "").replace(/\//g, ".").replace(/^\./, "");
+  if (error.keyword === "required" && error.params?.missingProperty) {
+    p = p
+      ? p + "." + error.params.missingProperty
+      : error.params.missingProperty;
+  }
+  return p;
+}
+
+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;
+  /** Resolved display label (options.label → projected schema title → control.label) */
+  projectedLabel: ComputedRef<string>;
+  /** Error string combining base-path and projected sub-path errors */
+  projectedErrors: ComputedRef<string>;
+}
+
+/**
+ * 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) {
+    const label = computed(() =>
+      resolveLabel(control.value, undefined, control.value.required),
+    );
+    return {
+      projectedData: computed(() => control.value.data),
+      projectedSchema: computed(() => control.value.schema),
+      handleProjectedChange: handleChange,
+      hasProjection: false,
+      projectedLabel: label,
+      projectedErrors: computed(() =>
+        prefixErrors(
+          label.value.replace(/\*$/, "").trim(),
+          normalizeErrors(control.value.errors),
+        ),
+      ),
+    };
+  }
+
+  // Inject JSONForms state to access raw AJV errors for projected sub-paths,
+  // and the root schema so that `$ref` resolution inside the projected slice
+  // can find `$defs` (which live at the root, not on the control's schema).
+  const jsonforms = inject<{
+    core?: {
+      errors?: ErrorLike[];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      schema?: Record<string, any>;
+    };
+  } | null>("jsonforms", null);
+
+  const fullProjectedPath = control.value.path + "." + projection;
+
+  const projectedData = computed(() =>
+    getProjectedValue(control.value.data, projection),
+  );
+
+  const projectedSchema = computed(() =>
+    getProjectedSchema(control.value.schema, projection),
+  );
+
+  const projectedRequired = computed(() =>
+    isProjectedFieldRequired(
+      control.value.schema,
+      projection,
+      jsonforms?.core?.schema ?? control.value.schema,
+    ),
+  );
+
+  const label = computed(() =>
+    resolveLabel(
+      control.value,
+      projectedSchema.value?.title,
+      projectedRequired.value,
+    ),
+  );
+
+  const projectedErrors = computed(() => {
+    const baseErrors = normalizeErrors(control.value.errors || "");
+
+    const rawErrors = jsonforms?.core?.errors ?? ([] as ErrorLike[]);
+    const matching = rawErrors.filter(
+      (err) => getErrorPath(err) === fullProjectedPath,
+    );
+
+    let errStr: string;
+    if (matching.length === 0) {
+      errStr = baseErrors;
+    } else {
+      const projMsg = matching
+        .map((e) => (e.keyword === "required" ? "is required" : e.message))
+        .filter(Boolean)
+        .join("\n");
+      errStr = [baseErrors, projMsg].filter(Boolean).join("\n");
+    }
+
+    return prefixErrors(label.value.replace(/\*$/, "").trim(), errStr);
+  });
+
+  const handleProjectedChange = (path: string, value: unknown) => {
+    const fullValue = setProjectedValue(control.value.data, projection, value);
+    handleChange(path, fullValue);
+  };
+
+  return {
+    projectedData,
+    projectedSchema,
+    handleProjectedChange,
+    hasProjection: true,
+    projectedLabel: label,
+    projectedErrors,
+  };
+}

package/src/vue/composables/useProvider.ts

@@ -10,6 +10,7 @@ import {
 } from "vue";
 import { cache as globalCache } from "../../core/cache";
 import { registry as globalRegistry } from "../../core/registry";
+import { renderObj } from "../../core/templating";
 import type {
   AuthConfig,
   ProviderBinding,
@@ -25,8 +26,11 @@ export function useProvider(
   ctxBits: {
     data: unknown | Ref<unknown> | ComputedRef<unknown>;
     path: string;
-    dependsOnValues?: unknown[];
-    uiQuery?: string;
+    dependsOnValues?: unknown[] | Ref<unknown[]> | ComputedRef<unknown[]>;
+    uiQuery?:
+      | string
+      | Ref<string | undefined>
+      | ComputedRef<string | undefined>;
   },
 ) {
   const registry = inject("providerRegistry", globalRegistry);
@@ -41,14 +45,27 @@ export function useProvider(
   const error = ref<string | undefined>(undefined);
   const ac = new AbortController();
 
-  const cacheKey = computed(() =>
-    JSON.stringify({
-      b: unref(binding),
-      d: ctxBits.dependsOnValues ?? [],
-      q: ctxBits.uiQuery ?? "",
-      data: unref(ctxBits.data), // Include data in cache key for reactivity
-    }),
-  );
+  // Cache key keys on the *rendered* binding config (with template variables
+  // substituted) plus dependsOnValues + uiQuery. This means:
+  //   - `{{data.country}}` in the URL → cache key changes when country changes,
+  //     auto-refetching without callers having to declare dependsOn.
+  //   - Unrelated form fields → rendered URL is unchanged → no refetch.
+  // The protocol's resolve() still receives the raw config and current data,
+  // so per-fetch URL rendering works as before.
+  const cacheKey = computed(() => {
+    const b = unref(binding);
+    const renderedBinding = b
+      ? {
+          ...b,
+          config: renderObj(b.config ?? {}, { data: unref(ctxBits.data) }),
+        }
+      : b;
+    return JSON.stringify({
+      b: renderedBinding,
+      d: unref(ctxBits.dependsOnValues) ?? [],
+      q: unref(ctxBits.uiQuery) ?? "",
+    });
+  });
 
   async function load() {
     const bindingValue = unref(binding);
@@ -71,7 +88,7 @@ export function useProvider(
       const out = await driver.resolve(bindingValue.config ?? {}, {
         data: unref(ctxBits.data),
         path: ctxBits.path,
-        ui: { query: ctxBits.uiQuery },
+        ui: { query: unref(ctxBits.uiQuery) },
         signal: ac.signal,
         auth: resolveAuth(bindingValue.auth, auth),
       });

package/src/vue/index.ts

@@ -1,43 +1,47 @@
 import type { UISchemaElement } from "@jsonforms/core";
 import {
   and,
+  isIntegerControl,
   isNumberControl,
   isStringControl,
   or,
   rankWith,
   isControl,
 } from "@jsonforms/core";
+import { resolveScopeSchema } from "../core/resolveScope";
+import { resolveItemsSchema } from "./utils/objectMultiSelect";
 import ProviderAutocomplete from "./components/ProviderAutocomplete.vue";
 import ProviderSelect from "./components/ProviderSelect.vue";
 import ProviderMultiSelect from "./components/ProviderMultiSelect.vue";
+import ProviderObjectMultiSelect from "./components/ProviderObjectMultiSelect.vue";
 
 // Custom tester that checks if provider option exists (as object or boolean)
 const hasProvider = (uischema: UISchemaElement) => {
   return uischema?.options?.provider !== undefined;
 };
 
+// Integer fallback tester — handles nested scopes like #/properties/parent/properties/child
+const isIntegerScope = (uischema: unknown, schema: unknown) => {
+  const ui = uischema as { type?: string; scope?: string };
+  if (ui?.type !== "Control" || !ui?.scope) return false;
+
+  const propertySchema = resolveScopeSchema(
+    ui.scope,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema as Record<string, any>,
+  );
+  return propertySchema?.type === "integer";
+};
+
 // Create specific testers for each component type
 const providerSelectTester = rankWith(
-  106, // Higher than PrimeVue base (100) to ensure providers take precedence
+  107, // Higher than PrimeVue JfNumber integer renderer (106) so provider wins
   and(
     or(
       isStringControl,
       isNumberControl,
-      and(isControl, (uischema: unknown, schema: unknown) => {
-        const ui = uischema as { type?: string; scope?: string };
-        const rootSchema = schema as {
-          properties?: Record<string, { type?: string }>;
-        };
-
-        if (ui?.type !== "Control" || !ui?.scope || !rootSchema?.properties)
-          return false;
-
-        // Extract property name from scope (e.g., "#/properties/age" -> "age")
-        const propertyName = ui.scope.replace("#/properties/", "");
-        const propertySchema = rootSchema.properties[propertyName];
-
-        return propertySchema?.type === "integer";
-      }),
+      isIntegerControl,
+      and(isControl, isIntegerScope),
     ),
     hasProvider,
     (uischema) => !uischema?.options?.autocomplete,
@@ -45,55 +49,75 @@ const providerSelectTester = rankWith(
 );
 
 const providerAutocompleteTester = rankWith(
-  107, // Higher than PrimeVue base (100) to ensure providers take precedence
+  108, // Higher than providerSelectTester so autocomplete variant wins when flagged
   and(
     or(
       isStringControl,
       isNumberControl,
-      and(isControl, (uischema: unknown, schema: unknown) => {
-        const ui = uischema as { type?: string; scope?: string };
-        const rootSchema = schema as {
-          properties?: Record<string, { type?: string }>;
-        };
-
-        if (ui?.type !== "Control" || !ui?.scope || !rootSchema?.properties)
-          return false;
-
-        // Extract property name from scope (e.g., "#/properties/age" -> "age")
-        const propertyName = ui.scope.replace("#/properties/", "");
-        const propertySchema = rootSchema.properties[propertyName];
-
-        return propertySchema?.type === "integer";
-      }),
+      isIntegerControl,
+      and(isControl, isIntegerScope),
     ),
     hasProvider,
     (uischema) => uischema?.options?.autocomplete === true,
   ),
 );
 
-// Custom array tester - check both uischema control type and schema type
-const isArrayControl = (uischema: UISchemaElement, schema: unknown) => {
+// Resolve the array schema at a control's scope, or undefined if the
+// control isn't an array. Shared by both array testers below.
+const getArraySchema = (uischema: UISchemaElement, schema: unknown) => {
   const controlSchema = uischema as { type: string; scope?: string };
-  if (controlSchema.type !== "Control" || !controlSchema.scope) {
-    return false;
-  }
+  if (controlSchema.type !== "Control" || !controlSchema.scope) return undefined;
+  const propertySchema = resolveScopeSchema(
+    controlSchema.scope,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema as Record<string, any>,
+  );
+  if (propertySchema?.type !== "array") return undefined;
+  return propertySchema;
+};
 
-  // Extract the property schema from the root schema
-  const rootSchema = schema as { properties?: Record<string, unknown> };
-  const propertyPath = controlSchema.scope.replace("#/properties/", "");
-  const propertySchema = rootSchema?.properties?.[propertyPath] as {
-    type?: string;
-  };
+// Object-item arrays — render with paired-object MultiSelect.
+const isObjectArrayControl = (uischema: UISchemaElement, schema: unknown) => {
+  const arr = getArraySchema(uischema, schema);
+  if (!arr) return false;
+  const items = resolveItemsSchema(
+    arr,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema as Record<string, any>,
+  );
+  return items?.type === "object";
+};
 
-  return propertySchema?.type === "array";
+// Scalar-item arrays — the original tester. Excludes object-item arrays so
+// the new ObjectMultiSelect renderer can claim them at a higher rank.
+const isScalarArrayControl = (uischema: UISchemaElement, schema: unknown) => {
+  const arr = getArraySchema(uischema, schema);
+  if (!arr) return false;
+  const items = resolveItemsSchema(
+    arr,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema as Record<string, any>,
+  );
+  // Treat unknown / no-items shapes as scalar (matches prior behavior where
+  // any array control was eligible for ProviderMultiSelect).
+  return items?.type !== "object";
 };
 
+const providerObjectMultiSelectTester = rankWith(
+  110, // One higher than scalar multi-select so object-item arrays match first.
+  and(isObjectArrayControl, hasProvider),
+);
+
 const providerMultiSelectTester = rankWith(
-  108, // Highest priority for array controls with providers
-  and(isArrayControl, hasProvider),
+  109,
+  and(isScalarArrayControl, hasProvider),
 );
 
 export const providerRenderers = [
+  {
+    tester: providerObjectMultiSelectTester,
+    renderer: ProviderObjectMultiSelect,
+  },
   { tester: providerMultiSelectTester, renderer: ProviderMultiSelect },
   { tester: providerAutocompleteTester, renderer: ProviderAutocomplete },
   { tester: providerSelectTester, renderer: ProviderSelect },
@@ -103,8 +127,20 @@ export const providerRenderers = [
 export { primevueRenderers, registerPrimevueRenderers } from "./primevue";
 
 // Export individual components
-export { ProviderAutocomplete, ProviderSelect, ProviderMultiSelect };
+export {
+  ProviderAutocomplete,
+  ProviderSelect,
+  ProviderMultiSelect,
+  ProviderObjectMultiSelect,
+};
 export { useProvider } from "./composables/useProvider";
+export { useProjection } from "./composables/useProjection";
+export type { ProjectionResult } from "./composables/useProjection";
+export { createDataLayer, useDataLayer } from "./composables/useDataLayer";
+export type { DataLayer } from "./composables/useDataLayer";
+export { useDeriveInitialValue } from "./composables/useDeriveInitialValue";
+export type { DeriveInitialValueCfg } from "./composables/useDeriveInitialValue";
+export { useDirtyValidation } from "./composables/useDirtyValidation";
 export * from "./testers";
 
 // Export individual PrimeVue components using lazy evaluation to avoid circular deps

package/src/vue/primevue/JfBoolean.vue

@@ -21,14 +21,17 @@ export default {
     renderers: {
       type: Array,
       required: false,
+      default: undefined,
     },
     cells: {
       type: Array,
       required: false,
+      default: undefined,
     },
     config: {
       type: Object,
       required: false,
+      default: undefined,
     },
   },
 };
@@ -38,26 +41,46 @@ export default {
 import type { ControlProps } from "@jsonforms/vue";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { getCurrentInstance } from "vue";
+import { useProjection } from "../composables/useProjection";
+import { useDirtyValidation } from "../composables/useDirtyValidation";
 import Checkbox from "primevue/checkbox";
 
 // Access props from the component instance
 const instance = getCurrentInstance()!;
 const props = instance.props as unknown as ControlProps;
-const { control, handleChange } = useJsonFormsControl(props);
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const {
+  projectedData,
+  handleProjectedChange: handleChange,
+  projectedErrors,
+  projectedLabel,
+} = useProjection(control, rawHandleChange);
 
-const onToggle = (val: boolean) => handleChange(control.value.path, val);
+// Track user interaction — errors only show after first toggle
+const { showErrors, markDirty } = useDirtyValidation(control, projectedErrors);
+
+const onToggle = (val: boolean) => {
+  markDirty();
+  handleChange(control.value.path, val);
+};
 </script>
 
 <template>
-  <div class="jf-control" style="flex-direction: row; align-items: center">
-    <Checkbox
-      :binary="true"
-      :model-value="!!control.data"
-      :disabled="!control.enabled"
-      :aria-invalid="!!control.errors || undefined"
-      @update:model-value="onToggle"
-    />
-    <label v-if="control.label" class="jf-label">{{ control.label }}</label>
-    <small v-if="control.errors" class="p-error">{{ control.errors }}</small>
+  <div class="jf-control">
+    <div style="display: flex; flex-direction: row; align-items: center; gap: 0.5rem">
+      <Checkbox
+        :binary="true"
+        :model-value="!!projectedData"
+        :disabled="!control.enabled"
+        :class="{ 'p-invalid': showErrors }"
+        :aria-invalid="showErrors || undefined"
+        @update:model-value="onToggle"
+      />
+      <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
+    </div>
+    <div v-if="control.description" class="jf-description">
+      {{ control.description }}
+    </div>
+    <small v-if="showErrors" class="p-error">{{ projectedErrors }}</small>
   </div>
 </template>