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

package/src/core/initFormData.ts

@@ -0,0 +1,189 @@
+/**
+ * Initialize a form data object from a JSON Schema.
+ * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.
+ *
+ * @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 all schema-defined fields initialized
+ */
+export function initFormDataFromSchema(
+  schema: Record<string, unknown>,
+  seed?: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = initProperty(schema, schema, seed) as Record<string, unknown>;
+
+  // If result is an object and seed has extra keys not in schema, preserve them
+  if (
+    result &&
+    typeof result === "object" &&
+    !Array.isArray(result) &&
+    seed &&
+    typeof seed === "object"
+  ) {
+    const schemaKeys = new Set(
+      Object.keys(
+        (resolveRef(schema, schema) as Record<string, unknown>)?.properties ??
+          {},
+      ),
+    );
+    for (const key of Object.keys(seed)) {
+      if (!schemaKeys.has(key) && !(key in result)) {
+        result[key] = seed[key];
+      }
+    }
+  }
+
+  return result ?? {};
+}
+
+/**
+ * Resolve a $ref pointer against the root schema's $defs.
+ * Supports nested $ref chains.
+ */
+function resolveRef(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> {
+  if (!property || typeof property !== "object") return property;
+
+  const ref = property.$ref as string | undefined;
+  if (!ref) return property;
+
+  // Guard against circular refs
+  const visited = seen ?? new Set<string>();
+  if (visited.has(ref)) return property;
+  visited.add(ref);
+
+  const resolved = resolvePointer(root, ref);
+  if (!resolved) return property;
+
+  // Continue resolving if the result itself has a $ref
+  return resolveRef(resolved as Record<string, unknown>, root, visited);
+}
+
+/**
+ * Resolve a JSON pointer like "#/$defs/Price" against an object.
+ */
+function resolvePointer(
+  obj: Record<string, unknown>,
+  pointer: string,
+): unknown {
+  if (!pointer.startsWith("#/")) return undefined;
+  const parts = pointer.slice(2).split("/");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Initialize a single property value based on its schema definition.
+ */
+function initProperty(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed?: unknown,
+): unknown {
+  if (!property || typeof property !== "object") return null;
+
+  // Resolve $ref first
+  const resolved = resolveRef(property, root);
+
+  // Handle oneOf with discriminator — pick first variant
+  if (Array.isArray(resolved.oneOf)) {
+    return initOneOf(resolved, root, seed);
+  }
+
+  // Priority 1: seed wins (for object types, we merge recursively below)
+  // For non-object types, return seed directly if present
+  const type = resolved.type as string | undefined;
+  if (seed !== undefined && seed !== null && type !== "object") {
+    return seed;
+  }
+
+  // Priority 2: const
+  if ("const" in resolved) {
+    return resolved.const;
+  }
+
+  // Priority 3: single-value enum
+  if (
+    Array.isArray(resolved.enum) &&
+    (resolved.enum as unknown[]).length === 1
+  ) {
+    return (resolved.enum as unknown[])[0];
+  }
+
+  // Priority 4: default
+  if ("default" in resolved) {
+    return resolved.default;
+  }
+
+  // Priority 5: typed empty values
+  switch (type) {
+    case "object":
+      return initObject(resolved, root, seed as Record<string, unknown>);
+    case "array":
+      return seed !== undefined && seed !== null ? seed : [];
+    case "string":
+      return "";
+    case "boolean":
+      return false;
+    case "number":
+    case "integer":
+      return null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Initialize an object type by recursing into its properties.
+ */
+function initObject(
+  schema: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed?: Record<string, unknown>,
+): Record<string, unknown> {
+  const properties = schema.properties as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!properties) {
+    // Object with no defined properties — return seed or empty object
+    return seed && typeof seed === "object" ? { ...seed } : {};
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const seedValue = seed && typeof seed === "object" ? seed[key] : undefined;
+    result[key] = initProperty(propSchema, root, seedValue);
+  }
+
+  return result;
+}
+
+/**
+ * Handle oneOf schemas — pick the first variant and initialize it.
+ */
+function initOneOf(
+  schema: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed?: unknown,
+): unknown {
+  const variants = schema.oneOf as Record<string, unknown>[];
+  if (!variants || variants.length === 0) return null;
+
+  const first = variants[0];
+  if (!first) return null;
+
+  // Pick first variant, resolve its $ref if needed
+  const firstVariant = resolveRef(first, root);
+  return initProperty(firstVariant, root, seed);
+}

package/src/core/projection.ts

@@ -26,10 +26,7 @@ export 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 function getProjectedValue(
-  data: unknown,
-  path: string,
-): unknown {
+export function getProjectedValue(data: unknown, path: string): unknown {
   const segments = parseProjectionPath(path);
   let current: unknown = data;
 
@@ -85,7 +82,10 @@ function setAtPath(
   } else {
     // Object key — ensure we have an object
     const obj: Record<string, unknown> =
-      current !== null && current !== undefined && typeof current === "object" && !Array.isArray(current)
+      current !== null &&
+      current !== undefined &&
+      typeof current === "object" &&
+      !Array.isArray(current)
         ? { ...(current as Record<string, unknown>) }
         : {};
     obj[seg] = setAtPath(obj[seg], segments, index + 1, value);

package/src/core/transforms.ts

@@ -14,7 +14,16 @@ 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 type FilterOperator =
+  | "eq"
+  | "neq"
+  | "empty"
+  | "notEmpty"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "contains";
 
 export interface FilterCondition {
   key: string;
@@ -153,13 +162,29 @@ function evaluateCondition(
     case "notEmpty":
       return !isEmpty(value);
     case "gt":
-      return typeof value === "number" && condition.values !== undefined && value > (condition.values[0] as number);
+      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);
+      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);
+      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);
+      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)));
@@ -208,7 +233,9 @@ function filterTransform(items: unknown[], config: Transform): unknown[] {
   return items.filter((item) => {
     if (typeof item !== "object" || item === null) return false;
     const itemObj = item as Record<string, unknown>;
-    return conditions.every((condition) => evaluateCondition(itemObj, condition));
+    return conditions.every((condition) =>
+      evaluateCondition(itemObj, condition),
+    );
   });
 }
 

package/src/core/types.ts

@@ -51,4 +51,5 @@ export interface ConnectorDataLayer {
   dataset_id?: number;
   profile_id?: string;
   profile_name?: string;
+  datasetWriteMode?: "append" | "overwrite";
 }

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./core/projection";
 export * from "./core/resolveScope";
 // Core exports
 export * from "./core/types";
+export { initFormDataFromSchema } from "./core/initFormData";
 
 // Protocol exports
 export { RestApiProtocol } from "./protocols/rest_api";

package/src/vue/components/ProviderAutocomplete.vue

@@ -12,7 +12,10 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(
+  control,
+  rawHandleChange,
+);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -53,16 +56,16 @@ const onSelect = (event: { value?: { value?: unknown } | unknown }) => {
 </script>
 
 <template>
-  <div class="flex flex-column gap-1">
-    <label v-if="control.schema.title" class="text-color text-left">{{
+  <div class="jf-control">
+    <label v-if="control.schema.title" class="jf-label">{{
       control.schema.title
     }}</label>
-    <div v-if="control.description" class="text-color-secondary text-left">
+    <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>
     <AutoComplete
       v-model="value"
-      class="w-full"
+      class="w-full!"
       :suggestions="items"
       option-label="label"
       :placeholder="placeholder"

package/src/vue/components/ProviderMultiSelect.vue

@@ -13,7 +13,10 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(
+  control,
+  rawHandleChange,
+);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -41,7 +44,7 @@ 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
@@ -55,14 +58,16 @@ watch(
         control.value.uischema?.options?.autoSelectSingle === true,
       isLoading,
       items: newItems,
-      currentValue: Array.isArray(projectedData.value) ? projectedData.value : [],
+      currentValue: Array.isArray(projectedData.value)
+        ? projectedData.value
+        : [],
     });
 
     if (valueToSelect !== null) {
       handleChange(control.value.path, valueToSelect);
     }
   },
-  { immediate: true }
+  { immediate: true },
 );
 
 // order-insensitive shallow equality for primitive arrays
@@ -98,16 +103,16 @@ const placeholder = computed(() => {
 </script>
 
 <template>
-  <div class="flex flex-column gap-2">
-    <label v-if="control.schema.title" class="text-color text-left">{{
+  <div class="jf-control">
+    <label v-if="control.schema.title" class="jf-label">{{
       control.schema.title
     }}</label>
-    <div v-if="control.description" class="text-color-secondary text-left">
+    <div v-if="control.description" class="jf-description">
       {{ control.description }}
     </div>
     <MultiSelect
       v-model="value"
-      class="w-full"
+      class="w-full!"
       :options="items"
       option-label="label"
       option-value="value"

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 { useDeriveInitialValue } from "../composables/useDeriveInitialValue";
 import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelect } from "../utils/autoSelect";
 import Dropdown from "primevue/dropdown";
@@ -13,7 +14,10 @@ const props = defineProps<{
   path: string;
 }>();
 const { control, handleChange: rawHandleChange } = useJsonFormsControl(props);
-const { projectedData, handleProjectedChange: handleChange } = useProjection(control, rawHandleChange);
+const { projectedData, handleProjectedChange: handleChange } = useProjection(
+  control,
+  rawHandleChange,
+);
 
 const binding = computed(() => {
   const provider = control.value.uischema?.options?.provider;
@@ -41,11 +45,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 +69,7 @@ watch(
       handleChange(control.value.path, valueToSelect);
     }
   },
-  { immediate: true }
+  { immediate: true },
 );
 
 const value = computed({
@@ -81,16 +88,16 @@ const placeholder = computed(() => {
 </script>
 
 <template>
-  <div class="flex flex-column gap-2">
-    <label v-if="control.schema.title" class="text-color text-left">{{
+  <div class="jf-control">
+    <label v-if="control.schema.title" class="jf-label">{{
       control.schema.title
     }}</label>
-    <div v-if="control.description" class="text-color-secondary text-left">
+    <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);
         }