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

package/src/vue/components/ProviderObjectMultiSelect.vue

@@ -0,0 +1,169 @@
+<script setup lang="ts">
+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 { resolvePlaceholder } from "../utils/placeholder";
+import {
+  fromMultiSelectShape,
+  resolveItemsSchema,
+  resolveObjectKeys,
+  sameObjectSet,
+  toMultiSelectShape,
+  type MultiSelectOption,
+  type ObjectKeys,
+} from "../utils/objectMultiSelect";
+import MultiSelect from "primevue/multiselect";
+
+const props = defineProps<{
+  uischema: ControlElement;
+  schema: JsonSchema;
+  path: string;
+}>();
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
+
+// Pull root schema so item-schema $refs resolve against the consumer's $defs.
+const jsonforms = inject<{
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  core?: { schema?: Record<string, any> };
+} | null>("jsonforms", null);
+const rootSchema = computed(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  () => (jsonforms?.core?.schema ?? control.value.schema) as Record<string, any>,
+);
+
+const itemsSchema = computed(() =>
+  resolveItemsSchema(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    control.value.schema as Record<string, any>,
+    rootSchema.value,
+  ),
+);
+
+const objectKeys = computed<ObjectKeys>(() => {
+  const resolved = resolveObjectKeys(
+    control.value.uischema?.options as
+      | { objectKeys?: { value?: unknown; label?: unknown } }
+      | undefined,
+    itemsSchema.value,
+  );
+  if (!resolved) {
+    throw new Error(
+      "[ProviderObjectMultiSelect] objectKeys could not be resolved. " +
+        "Specify `uischema.options.objectKeys = { value, label }` or declare " +
+        "exactly two `required` properties on the array's items schema so " +
+        "they can be inferred.",
+    );
+  }
+  return resolved;
+});
+
+const binding = computed(() => {
+  const provider = control.value.uischema?.options?.provider;
+  if (provider && typeof provider === "object" && !provider.load) {
+    return { ...provider, load: "mount" };
+  }
+  return provider;
+});
+
+const deps = computed(
+  () =>
+    ((
+      (control.value.schema as Record<string, unknown>)?.[
+        "x-provider"
+      ] as Record<string, unknown>
+    )?.dependsOn as string[]) ?? [],
+);
+const depValues = computed(() => deps.value.map(() => null));
+
+const injectedFormData = inject<{ value: unknown }>("formData", { value: {} });
+const rootData = computed(() => injectedFormData.value || {});
+
+const { items, loading, error } = useProvider(binding, {
+  data: rootData,
+  path: control.value.path,
+  dependsOnValues: depValues,
+});
+
+// Auto-select when provider returns only one item — paired-object variant.
+watch(
+  [items, loading],
+  ([newItems, isLoading]) => {
+    if (
+      !control.value.uischema?.options?.autoSelectSingle ||
+      isLoading ||
+      newItems.length !== 1
+    ) {
+      return;
+    }
+    const single = newItems[0]!;
+    const current = Array.isArray(projectedData.value) ? projectedData.value : [];
+    if (current.length === 0) {
+      handleChange(control.value.path, [
+        {
+          [objectKeys.value.value]: single.value,
+          [objectKeys.value.label]: single.label,
+        },
+      ]);
+    }
+  },
+  { immediate: true },
+);
+
+const value = computed<MultiSelectOption[]>({
+  get() {
+    return toMultiSelectShape(projectedData.value, objectKeys.value);
+  },
+  set(val) {
+    const next = fromMultiSelectShape(val, objectKeys.value);
+    const curr = Array.isArray(projectedData.value) ? projectedData.value : [];
+    if (!sameObjectSet(curr, next, objectKeys.value.value)) {
+      handleChange(control.value.path, next);
+    }
+  },
+});
+
+const placeholder = computed(() => {
+  if (loading.value) return "Loading…";
+  return resolvePlaceholder(
+    control.value.uischema,
+    projectedLabel.value,
+    "select",
+  );
+});
+</script>
+
+<template>
+  <div class="jf-control">
+    <label v-if="projectedLabel" class="jf-label">{{ projectedLabel }}</label>
+    <div v-if="control.description" class="jf-description">
+      {{ control.description }}
+    </div>
+    <MultiSelect
+      v-model="value"
+      class="w-full!"
+      :options="items"
+      option-label="label"
+      data-key="value"
+      display="chip"
+      :placeholder="placeholder"
+      :disabled="!control.enabled || loading"
+      :show-clear="true"
+    />
+    <small v-if="error" class="p-error" role="alert"
+      >Failed to load: {{ error }}</small
+    >
+  </div>
+</template>
+
+<style scoped>
+:deep(.p-multiselect-label) {
+  text-align: left;
+}
+</style>

package/src/vue/components/ProviderSelect.vue

@@ -3,7 +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<{
@@ -11,7 +14,12 @@ const props = defineProps<{
   schema: JsonSchema;
   path: string;
 }>();
-const { control, handleChange } = useJsonFormsControl(props);
+const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
+const {
+  projectedData,
+  projectedLabel,
+  handleProjectedChange: handleChange,
+} = useProjection(control, rawHandleChange);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -39,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],
@@ -53,42 +64,40 @@ watch(
         control.value.uischema?.options?.autoSelectSingle !== false,
       isLoading,
       items: newItems,
-      currentValue: control.value.data,
+      currentValue: projectedData.value,
     });
 
     if (valueToSelect !== null) {
       handleChange(control.value.path, valueToSelect);
     }
   },
-  { immediate: true }
+  { immediate: true },
 );
 
 const value = computed({
-  get: () => control.value.data,
+  get: () => projectedData.value,
   set: (v) => handleChange(control.value.path, v),
 });
 
 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="jf-control">
-    <label v-if="control.schema.title" class="jf-label">{{
-      control.schema.title
-    }}</label>
+    <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

@@ -0,0 +1,43 @@
+import {
+  ref,
+  provide,
+  inject,
+  readonly,
+  type DeepReadonly,
+  type Ref,
+} from "vue";
+import type { ConnectorDataLayer } from "../../core/types";
+
+export 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,14 @@
-import { computed, watch, inject, type Ref } from "vue";
+import {
+  computed,
+  ref,
+  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 +17,25 @@ 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 +48,17 @@ export function useDerive({ control, handleChange }: DeriveOptions) {
     };
   });
 
-  // Watch for changes in form data and external data and update derived field
+  // 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, externalData, deriveConfig],
+    [rootData, dataLayerData, deriveConfig],
     ([data, extData, config]) => {
       if (!config.expression || config.mode !== "follow") {
         return;
@@ -48,7 +70,31 @@ export function useDerive({ control, handleChange }: DeriveOptions) {
           data,
           extData,
         );
-        if (derivedValue !== 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);
         }
       } catch (error) {
@@ -65,12 +111,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 +128,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/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

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