@narrative.io/jsonforms-provider-protocols 3.0.0-beta.2 → 3.0.0-beta.21

package/src/vue/components/ProviderSelect.vue

@@ -3,8 +3,10 @@ import type { ControlElement, JsonSchema } from "@jsonforms/core";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, inject, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
+import { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelect } from "../utils/autoSelect";
+import { resolvePlaceholder } from "../utils/placeholder";
 import Dropdown from "primevue/dropdown";
 
 const props = defineProps<{
@@ -13,7 +15,11 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -41,11 +47,14 @@ const rootData = computed(() => injectedFormData.value || {});
 const { items, loading, error } = useProvider(binding, {
   data: rootData, // Pass the reactive reference
   path: control.value.path,
-  dependsOnValues: depValues.value,
+  dependsOnValues: depValues,
 });
 
 // Provider will automatically reload when rootData changes due to reactive cache key
 
+// deriveInitialValue — async API-based initial value seeding
+useDeriveInitialValue({ control, handleChange });
+
 // Auto-select when provider returns only one item (enabled by default)
 watch(
   [items, loading],
@@ -62,7 +71,7 @@ watch(
       handleChange(control.value.path, valueToSelect);
     }
   },
-  { immediate: true }
+  { immediate: true },
 );
 
 const value = computed({
@@ -72,25 +81,23 @@ const value = computed({
 
 const placeholder = computed(() => {
   if (loading.value) return "Loading…";
-  // Check for placeholder in uischema options
-  const uischemaPlaceholder = (
-    control.value.uischema as { options?: { placeholder?: string } }
-  )?.options?.placeholder;
-  return uischemaPlaceholder || "Select…";
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
+  );
 });
 </script>
 
 <template>
-  <div class="flex flex-column gap-2">
-    <label v-if="control.schema.title" class="text-color text-left">{{
-      control.schema.title
-    }}</label>
-    <div v-if="control.description" class="text-color-secondary text-left">
+  <div class="jf-control">
+    <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
+    <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>
     <Dropdown
       v-model="value"
-      class="w-full"
+      class="w-full!"
       :options="items"
       option-label="label"
       option-value="value"

package/src/vue/composables/useDataLayer.ts

@@ -8,7 +8,7 @@ import {
 } from "vue";
 import type { ConnectorDataLayer } from "../../core/types";
 
-const DATA_LAYER_KEY = Symbol("dataLayer");
+export const DATA_LAYER_KEY = Symbol("dataLayer");
 
 export interface DataLayer {
   push(data: Partial<ConnectorDataLayer>): void;

package/src/vue/composables/useDerive.ts

@@ -1,4 +1,12 @@
-import { computed, watch, unref, inject, type Ref, type ComputedRef } from "vue";
+import {
+  computed,
+  ref,
+  watch,
+  unref,
+  inject,
+  type Ref,
+  type ComputedRef,
+} from "vue";
 import { type ControlElement } from "@jsonforms/core";
 import { useDataLayer } from "./useDataLayer";
 
@@ -14,7 +22,11 @@ interface DeriveOptions {
   data?: Ref<unknown> | ComputedRef<unknown>;
 }
 
-export function useDerive({ control, handleChange, data: dataOverride }: DeriveOptions) {
+export function useDerive({
+  control,
+  handleChange,
+  data: dataOverride,
+}: DeriveOptions) {
   // Get the root form data from JSONForms context
   const injectedFormData = inject<{ value: unknown }>("formData", {
     value: {},
@@ -36,6 +48,14 @@ export function useDerive({ control, handleChange, data: dataOverride }: DeriveO
     };
   });
 
+  // Track the last resolved source value so we only update the field
+  // when the source itself changes, not on every form data mutation.
+  const lastDerivedValue = ref<unknown>(undefined);
+  // First watch fire is special: a pre-populated field (edit flow seeded
+  // from a saved connection) must not be clobbered by whatever the source
+  // resolves to on mount. We record the source value but skip handleChange.
+  let isFirstRun = true;
+
   // Watch for changes in form data and dataLayer and update derived field
   watch(
     [rootData, dataLayerData, deriveConfig],
@@ -50,7 +70,30 @@ export function useDerive({ control, handleChange, data: dataOverride }: DeriveO
           data,
           extData,
         );
-        const compareData = dataOverride ? unref(dataOverride) : control.value.data;
+        const compareData = dataOverride
+          ? unref(dataOverride)
+          : control.value.data;
+
+        if (isFirstRun) {
+          isFirstRun = false;
+          lastDerivedValue.value = derivedValue;
+          // On mount, only populate the field if it's empty.
+          // A non-empty seed represents user intent (edit flow) and must
+          // be preserved. Subsequent source changes will still propagate.
+          const isFieldEmpty =
+            compareData === undefined ||
+            compareData === null ||
+            compareData === "";
+          if (isFieldEmpty && derivedValue !== compareData) {
+            handleChange(control.value.path, derivedValue);
+          }
+          return;
+        }
+
+        // Only update if the SOURCE value changed, not just the field value
+        if (derivedValue === lastDerivedValue.value) return;
+        lastDerivedValue.value = derivedValue;
+
         if (derivedValue !== compareData) {
           handleChange(control.value.path, derivedValue);
         }

package/src/vue/composables/useDeriveInitialValue.ts

@@ -0,0 +1,195 @@
+import { computed, inject, ref, watch, type Ref, type ComputedRef } from "vue";
+import { type ControlElement } from "@jsonforms/core";
+import { renderTpl, renderObj } from "../../core/templating";
+import { jp } from "../../core/jsonpath";
+import {
+  applyTransformPipeline,
+  type TransformPipeline,
+} from "../../core/transforms";
+import type { AuthConfig } from "../../core/types";
+
+export interface DeriveInitialValueCfg {
+  protocol: string;
+  config: {
+    url: string;
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    body?: unknown;
+    auth?: AuthConfig;
+    items: string;
+    map: { value: string };
+    transforms?: TransformPipeline;
+    showError?: boolean;
+  };
+}
+
+interface DeriveInitialValueOptions {
+  control: Ref<{
+    uischema: ControlElement;
+    path: string;
+    data: unknown;
+  }>;
+  handleChange: (path: string, value: unknown) => void;
+  data?: Ref<unknown> | ComputedRef<unknown>;
+}
+
+function buildAuthHeaders(
+  auth?: AuthConfig,
+  globalAuth?: Record<string, unknown>,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (!auth) return headers;
+
+  if (auth.use && globalAuth?.[auth.use]) {
+    const globalValue = globalAuth[auth.use];
+    const value =
+      typeof globalValue === "function" ? globalValue() : globalValue;
+    if (auth.use === "apiKey") headers["X-API-Key"] = String(value);
+    else if (auth.use === "bearer")
+      headers["Authorization"] = `Bearer ${value}`;
+    else if (auth.use === "token") headers["Authorization"] = `Token ${value}`;
+    return headers;
+  }
+
+  if (auth.bearer) {
+    const v = typeof auth.bearer === "function" ? auth.bearer() : auth.bearer;
+    headers["Authorization"] = `Bearer ${v}`;
+  }
+  if (auth.apiKey) {
+    const v = typeof auth.apiKey === "function" ? auth.apiKey() : auth.apiKey;
+    headers["X-API-Key"] = String(v);
+  }
+  if (auth.token) {
+    const v = typeof auth.token === "function" ? auth.token() : auth.token;
+    headers["Authorization"] = `Token ${v}`;
+  }
+
+  return headers;
+}
+
+/**
+ * Returns true when the template URL contains `{{…}}` placeholders but
+ * one or more of those placeholders resolved to an empty string, which
+ * means a required data dependency hasn't been set yet.
+ */
+function hasUnresolvedTemplates(
+  templateUrl: string,
+  renderedUrl: string,
+): boolean {
+  if (!templateUrl.includes("{{")) return false;
+  // After protocol, empty segments indicate unresolved vars
+  const pathPart = renderedUrl.replace(/^https?:\/\/[^/]+/, "");
+  if (pathPart.includes("//")) return true;
+  // Trailing slash when the template didn't have one
+  if (renderedUrl.endsWith("/") && !templateUrl.endsWith("/")) return true;
+  return false;
+}
+
+export function useDeriveInitialValue({
+  control,
+  handleChange,
+}: DeriveInitialValueOptions) {
+  const injectedFormData = inject<{ value: unknown }>("formData", {
+    value: {},
+  });
+  const rootData = computed(() => injectedFormData.value || {});
+  const auth = inject("providerAuth", {}) as Record<string, unknown>;
+
+  const cfg = computed<DeriveInitialValueCfg | undefined>(() => {
+    return control.value.uischema?.options?.deriveInitialValue as
+      | DeriveInitialValueCfg
+      | undefined;
+  });
+
+  // Compute the resolved URL reactively
+  const resolvedUrl = computed<string | null>(() => {
+    const c = cfg.value;
+    if (!c?.config?.url) return null;
+    const rendered = renderTpl(c.config.url, { data: rootData.value });
+    if (hasUnresolvedTemplates(c.config.url, rendered)) return null;
+    return rendered;
+  });
+
+  const lastFetchedUrl = ref<string | null>(null);
+  const loading = ref(false);
+  const error = ref<string | undefined>(undefined);
+
+  watch(
+    resolvedUrl,
+    async (url) => {
+      if (!url || !cfg.value) return;
+      // Only fetch when the URL changes (new context).
+      // Same URL = same context; don't override user selection.
+      if (url === lastFetchedUrl.value) return;
+      lastFetchedUrl.value = url;
+
+      loading.value = true;
+      error.value = undefined;
+
+      try {
+        const c = cfg.value.config;
+        const fullUrl = new URL(url);
+
+        // Query params
+        const q = renderObj(c.query ?? {}, {
+          data: rootData.value,
+        }) as Record<string, unknown>;
+        for (const [k, v] of Object.entries(q)) {
+          if (v !== undefined && v !== "")
+            fullUrl.searchParams.set(k, String(v));
+        }
+
+        // Headers
+        const baseHeaders = renderObj(c.headers ?? {}, {
+          data: rootData.value,
+        }) as Record<string, string>;
+        const authHeaders = buildAuthHeaders(c.auth, auth);
+        const headers = { ...baseHeaders, ...authHeaders };
+
+        const method = c.method ?? "GET";
+        const requestInit: RequestInit = { method, headers };
+        if (method !== "GET" && c.body) {
+          requestInit.body = JSON.stringify(
+            renderObj(c.body, { data: rootData.value }),
+          );
+        }
+
+        const res = await fetch(fullUrl.toString(), requestInit);
+        if (!res.ok) {
+          if (c.showError !== false) {
+            throw new Error(`REST ${res.status}`);
+          }
+          return;
+        }
+
+        const json = await res.json();
+        let items = jp(json, c.items);
+
+        // Apply transforms if provided
+        if (c.transforms && c.transforms.length > 0) {
+          items = applyTransformPipeline(items, c.transforms);
+        }
+
+        if (items.length === 0) return; // No items → leave field empty
+
+        // Extract value from first item
+        const derivedValue = jp(items[0], c.map.value)[0];
+        if (derivedValue !== undefined) {
+          handleChange(control.value.path, derivedValue);
+        }
+      } catch (e) {
+        error.value = (e as Error)?.message ?? String(e);
+        console.warn(
+          `deriveInitialValue fetch failed for ${control.value.path}:`,
+          e,
+        );
+      } finally {
+        loading.value = false;
+      }
+    },
+    { immediate: true },
+  );
+
+  return { loading, error };
+}

package/src/vue/composables/useDirtyValidation.ts

@@ -1,10 +1,15 @@
-import { ref, computed, type Ref } from "vue";
+import { ref, computed, type Ref, type ComputedRef } from "vue";
 
-export function useDirtyValidation(control: Ref<{ errors: string }>) {
+export function useDirtyValidation(
+  control: Ref<{ errors: string }>,
+  errorsOverride?: Ref<string> | ComputedRef<string>,
+) {
   const hasInteracted = ref(false);
 
   const showErrors = computed(
-    () => hasInteracted.value && !!control.value.errors,
+    () =>
+      hasInteracted.value &&
+      !!(errorsOverride ? errorsOverride.value : control.value.errors),
   );
 
   const markDirty = () => {

package/src/vue/composables/useProjection.ts

@@ -1,18 +1,122 @@
-import { computed, type ComputedRef, type Ref } from "vue";
+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>;
@@ -23,6 +127,10 @@ export interface ProjectionResult {
   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>;
 }
 
 /**
@@ -44,14 +152,37 @@ export function useProjection(
     | 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),
   );
@@ -60,6 +191,44 @@ export function useProjection(
     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);
@@ -70,5 +239,7 @@ export function useProjection(
     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),
       });