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

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,
+  };
+}

package/src/vue/index.ts

@@ -7,6 +7,7 @@ import {
   rankWith,
   isControl,
 } from "@jsonforms/core";
+import { resolveScopeSchema } from "../core/resolveScope";
 import ProviderAutocomplete from "./components/ProviderAutocomplete.vue";
 import ProviderSelect from "./components/ProviderSelect.vue";
 import ProviderMultiSelect from "./components/ProviderMultiSelect.vue";
@@ -16,29 +17,21 @@ 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;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const propertySchema = resolveScopeSchema(ui.scope, 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
   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";
-      }),
-    ),
+    or(isStringControl, isNumberControl, and(isControl, isIntegerScope)),
     hasProvider,
     (uischema) => !uischema?.options?.autocomplete,
   ),
@@ -47,44 +40,21 @@ const providerSelectTester = rankWith(
 const providerAutocompleteTester = rankWith(
   107, // Higher than PrimeVue base (100) to ensure providers take precedence
   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";
-      }),
-    ),
+    or(isStringControl, isNumberControl, and(isControl, isIntegerScope)),
     hasProvider,
     (uischema) => uischema?.options?.autocomplete === true,
   ),
 );
 
-// Custom array tester - check both uischema control type and schema type
+// Custom array tester - supports nested scope paths
 const isArrayControl = (uischema: UISchemaElement, schema: unknown) => {
   const controlSchema = uischema as { type: string; scope?: string };
   if (controlSchema.type !== "Control" || !controlSchema.scope) {
     return false;
   }
 
-  // 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;
-  };
-
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const propertySchema = resolveScopeSchema(controlSchema.scope, schema as Record<string, any>);
   return propertySchema?.type === "array";
 };
 
@@ -105,6 +75,10 @@ export { primevueRenderers, registerPrimevueRenderers } from "./primevue";
 // Export individual components
 export { ProviderAutocomplete, ProviderSelect, ProviderMultiSelect };
 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 * 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,12 +41,14 @@ export default {
 import type { ControlProps } from "@jsonforms/vue";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { getCurrentInstance } from "vue";
+import { useProjection } from "../composables/useProjection";
 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 } = useProjection(control, rawHandleChange);
 
 const onToggle = (val: boolean) => handleChange(control.value.path, val);
 </script>
@@ -52,7 +57,7 @@ const onToggle = (val: boolean) => handleChange(control.value.path, val);
   <div class="flex items-center gap-2">
     <Checkbox
       :binary="true"
-      :model-value="!!control.data"
+      :model-value="!!projectedData"
       :disabled="!control.enabled"
       :aria-invalid="!!control.errors || undefined"
       @update:model-value="onToggle"

package/src/vue/primevue/JfEnum.vue

@@ -22,14 +22,17 @@ export default {
     renderers: {
       type: Array,
       required: false,
+      default: undefined,
     },
     cells: {
       type: Array,
       required: false,
+      default: undefined,
     },
     config: {
       type: Object,
       required: false,
+      default: undefined,
     },
   },
 };
@@ -42,13 +45,15 @@ import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, ref, inject, getCurrentInstance, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
 import { useDerive } from "../composables/useDerive";
+import { useProjection } from "../composables/useProjection";
 import { shouldAutoSelect } from "../utils/autoSelect";
 import Dropdown from "primevue/dropdown";
 
 // 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 } = useProjection(control, rawHandleChange);
 
 type Opt = { label: string; value: unknown };
 const toOptions = (schema?: JsonSchema): Opt[] => {
@@ -134,7 +139,7 @@ const options = computed(() => {
 });
 
 // Add derive functionality
-useDerive({ control, handleChange });
+useDerive({ control, handleChange, data: projectedData });
 
 // Auto-select when provider returns only one item (enabled by default)
 watch(
@@ -145,7 +150,7 @@ watch(
         control.value.uischema?.options?.autoSelectSingle !== false,
       isLoading,
       items,
-      currentValue: control.value.data,
+      currentValue: projectedData.value,
     });
 
     if (valueToSelect !== null) {
@@ -182,7 +187,7 @@ const onBlur = () => {
       :options="options"
       option-label="label"
       option-value="value"
-      :model-value="control.data ?? null"
+      :model-value="projectedData ?? null"
       :placeholder="placeholder"
       :disabled="!control.enabled || loading"
       :aria-invalid="!!showErrors || undefined"

package/src/vue/primevue/JfEnumArray.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,15 +41,18 @@ export default {
 import type { JsonSchema } from "@jsonforms/core";
 import type { ControlProps } from "@jsonforms/vue";
 import { useJsonFormsControl } from "@jsonforms/vue";
-import { computed, inject, getCurrentInstance } from "vue";
+import { computed, inject, getCurrentInstance, watch } from "vue";
 import { useProvider } from "../composables/useProvider";
 import { useDerive } from "../composables/useDerive";
+import { useProjection } from "../composables/useProjection";
+import { shouldAutoSelectMulti } from "../utils/autoSelect";
 import MultiSelect from "primevue/multiselect";
 
 // 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 } = useProjection(control, rawHandleChange);
 
 type Opt = { label: string; value: unknown };
 const toOptions = (schema?: JsonSchema): Opt[] => {
@@ -124,7 +130,26 @@ const options = computed(() => {
 });
 
 // Add derive functionality
-useDerive({ control, handleChange });
+useDerive({ control, handleChange, data: projectedData });
+
+// Auto-select when provider returns only one item (opt-in for multiselect)
+watch(
+  [providerItems, loading],
+  ([items, isLoading]) => {
+    const valueToSelect = shouldAutoSelectMulti({
+      autoSelectSingle:
+        control.value.uischema?.options?.autoSelectSingle === true,
+      isLoading,
+      items,
+      currentValue: Array.isArray(projectedData.value) ? projectedData.value : [],
+    });
+
+    if (valueToSelect !== null) {
+      handleChange(control.value.path, valueToSelect);
+    }
+  },
+  { immediate: true }
+);
 
 const placeholder = computed<string | undefined>(() => {
   if (loading.value) return "Loading…";
@@ -145,13 +170,13 @@ const sameSet = (a: unknown[], b: unknown[]) => {
 // v-model with guard to avoid recursive updates
 const model = computed<unknown[]>({
   get() {
-    const curr = Array.isArray(control.value.data) ? control.value.data : [];
+    const curr = Array.isArray(projectedData.value) ? projectedData.value : [];
     // return a fresh copy so PrimeMultiSelect 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/primevue/JfNumber.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,
     },
   },
 };
@@ -39,12 +42,14 @@ import type { ControlProps } from "@jsonforms/vue";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, ref, getCurrentInstance } from "vue";
 import { useDerive } from "../composables/useDerive";
+import { useProjection } from "../composables/useProjection";
 import InputNumber from "primevue/inputnumber";
 
 // 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 } = useProjection(control, rawHandleChange);
 
 const options = computed(
   () =>
@@ -57,7 +62,7 @@ const placeholder = computed<string | undefined>(
 );
 
 // Add derive functionality
-useDerive({ control, handleChange });
+useDerive({ control, handleChange, data: projectedData });
 
 // Currency and decimal configuration
 const mode = computed(() => {
@@ -125,7 +130,7 @@ const onBlur = () => {
       :currency="currency"
       :min-fraction-digits="minFractionDigits"
       :max-fraction-digits="maxFractionDigits"
-      :model-value="typeof control.data === 'number' ? control.data : null"
+      :model-value="typeof projectedData === 'number' ? projectedData : null"
       :placeholder="placeholder"
       :disabled="!control.enabled"
       :aria-invalid="!!showErrors || undefined"

package/src/vue/primevue/JfText.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,
     },
   },
 };
@@ -40,13 +43,15 @@ import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, ref, inject, watch, getCurrentInstance } from "vue";
 import { useProvider } from "../composables/useProvider";
 import { useDerive } from "../composables/useDerive";
+import { useProjection } from "../composables/useProjection";
 import InputText from "primevue/inputtext";
 import AutoComplete from "primevue/autocomplete";
 
 // 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 } = useProjection(control, rawHandleChange);
 
 // Provider support for autocomplete functionality
 const binding = computed(() => {
@@ -110,7 +115,7 @@ const placeholder = computed<string | undefined>(() => {
 const isAutocomplete = computed(() => !!binding.value);
 
 // Add derive functionality
-useDerive({ control, handleChange });
+useDerive({ control, handleChange, data: projectedData });
 
 // Track user interaction
 const hasInteracted = ref(false);
@@ -121,7 +126,7 @@ const showErrors = computed(() => hasInteracted.value && control.value.errors);
 function onInput(val: string | undefined) {
   // Convert empty strings to undefined for proper required field validation
   const newValue = val && val.trim() !== "" ? val : undefined;
-  if (control.value.data !== newValue) {
+  if (projectedData.value !== newValue) {
     handleChange(control.value.path, newValue);
   }
 }
@@ -158,7 +163,7 @@ const onSelect = (event: { value?: { value?: unknown } | unknown }) => {
     <AutoComplete
       v-if="isAutocomplete"
       class="w-full"
-      :model-value="control.data ?? ''"
+      :model-value="projectedData ?? ''"
       :suggestions="items"
       option-label="label"
       :placeholder="placeholder"
@@ -173,7 +178,7 @@ const onSelect = (event: { value?: { value?: unknown } | unknown }) => {
     <InputText
       v-else
       class="w-full"
-      :model-value="control.data ?? ''"
+      :model-value="(projectedData as string) ?? ''"
       :disabled="!control.enabled"
       :aria-invalid="!!showErrors || undefined"
       :placeholder="placeholder"

package/src/vue/primevue/JfTextArea.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,12 +41,14 @@ export default {
 import type { ControlProps } from "@jsonforms/vue";
 import { useJsonFormsControl } from "@jsonforms/vue";
 import { computed, ref, getCurrentInstance } from "vue";
+import { useProjection } from "../composables/useProjection";
 import Textarea from "primevue/textarea";
 
 // 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 } = useProjection(control, rawHandleChange);
 
 const placeholder = computed<string | undefined>(
   () =>
@@ -59,7 +64,7 @@ const showErrors = computed(() => hasInteracted.value && control.value.errors);
 function onInput(val: string | undefined) {
   // Convert empty strings to undefined for proper required field validation
   const newValue = val && val.trim() !== "" ? val : undefined;
-  if (control.value.data !== newValue) {
+  if (projectedData.value !== newValue) {
     handleChange(control.value.path, newValue);
   }
 }
@@ -79,7 +84,7 @@ function onBlur() {
     </div>
     <Textarea
       class="w-full"
-      :model-value="control.data ?? ''"
+      :model-value="(projectedData as string) ?? ''"
       :disabled="!control.enabled"
       :aria-invalid="!!showErrors || undefined"
       :placeholder="placeholder"

package/src/vue/primevue/index.ts

@@ -4,6 +4,8 @@ import JfNumber from "./JfNumber.vue";
 import JfEnum from "./JfEnum.vue";
 import JfEnumArray from "./JfEnumArray.vue";
 import JfBoolean from "./JfBoolean.vue";
+import { getProjectedSchema } from "../../core/projection";
+import { resolveScopeSchema } from "../../core/resolveScope";
 
 // Auto-inject layout styles
 const injectLayoutStyles = () => {
@@ -54,6 +56,7 @@ export function registerPrimevueRenderers(jsonformsCore: any): unknown[] {
     isNumberControl,
     isIntegerControl,
     and,
+    or,
     isControl,
     schemaMatches,
     isBooleanControl,
@@ -97,27 +100,49 @@ export function registerPrimevueRenderers(jsonformsCore: any): unknown[] {
     );
   };
 
+  // Projection-aware schema check: when options.projection is set,
+  // resolve the projected schema and test against it instead of the original
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const projectedSchemaMatches = (check: (schema: any) => boolean) =>
+    (uischema: unknown, schema: unknown): boolean => {
+      const ui = uischema as { type?: string; scope?: string; options?: { projection?: string } };
+      const projection = ui?.options?.projection;
+      if (!projection || ui?.type !== "Control" || !ui?.scope) return false;
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const propertySchema = resolveScopeSchema(ui.scope, schema as Record<string, any>);
+      if (!propertySchema) return false;
+
+      return check(getProjectedSchema(propertySchema, projection));
+    };
+
+  const isMultilineProjection = (uischema: unknown, schema: unknown) => {
+    const ui = uischema as { options?: { multi?: boolean } };
+    return ui?.options?.multi === true &&
+      projectedSchemaMatches((s) => s?.type === "string")(uischema, schema);
+  };
+
   const renderers = [
     // Multiline text has higher priority than regular text
-    { tester: rankWith(PRIME + 4, isMultilineString), renderer: JfTextArea },
-    { tester: rankWith(PRIME + 3, isStringControl), renderer: JfText },
+    { tester: rankWith(PRIME + 4, or(isMultilineString, isMultilineProjection)), renderer: JfTextArea },
+    { tester: rankWith(PRIME + 3, or(isStringControl, projectedSchemaMatches((s) => s?.type === "string"))), renderer: JfText },
     {
-      tester: rankWith(PRIME + 6, isIntegerControl),
+      tester: rankWith(PRIME + 6, or(isIntegerControl, projectedSchemaMatches((s) => s?.type === "integer"))),
       renderer: JfNumber,
     },
     {
-      tester: rankWith(PRIME + 4, isNumberControl),
+      tester: rankWith(PRIME + 4, or(isNumberControl, projectedSchemaMatches((s) => s?.type === "number"))),
       renderer: JfNumber,
     },
     {
-      tester: rankWith(PRIME + 7, and(isControl, schemaMatches(isScalarEnum))),
+      tester: rankWith(PRIME + 7, or(and(isControl, schemaMatches(isScalarEnum)), and(isControl, projectedSchemaMatches(isScalarEnum)))),
       renderer: JfEnum,
     },
     {
-      tester: rankWith(PRIME + 8, and(isControl, schemaMatches(isEnumArray))),
+      tester: rankWith(PRIME + 8, or(and(isControl, schemaMatches(isEnumArray)), and(isControl, projectedSchemaMatches(isEnumArray)))),
       renderer: JfEnumArray,
     },
-    { tester: rankWith(PRIME + 3, isBooleanControl), renderer: JfBoolean },
+    { tester: rankWith(PRIME + 3, or(isBooleanControl, projectedSchemaMatches((s) => s?.type === "boolean"))), renderer: JfBoolean },
   ];
 
   // Update the exported array

package/src/vue/utils/autoSelect.ts

@@ -8,11 +8,11 @@ export interface AutoSelectParams {
 }
 
 /**
- * Determines if auto-select should trigger and returns the value to select.
+ * Determines if auto-select should trigger for single-select dropdowns.
  * Returns null if auto-select should not trigger.
  *
  * Auto-select triggers when:
- * - autoSelectSingle option is enabled
+ * - autoSelectSingle option is enabled (default: true for single-select)
  * - Provider has finished loading
  * - Exactly one item is available
  * - Current value is empty (undefined/null) OR not in the current options
@@ -38,3 +38,47 @@ export function shouldAutoSelect(params: AutoSelectParams): unknown | null {
 
   return null;
 }
+
+export interface AutoSelectMultiParams {
+  autoSelectSingle: boolean;
+  isLoading: boolean;
+  items: ProviderItem[];
+  currentValue: unknown[];
+}
+
+/**
+ * Determines if auto-select should trigger for multiselect dropdowns.
+ * Returns null if auto-select should not trigger, otherwise returns an array with the single value.
+ *
+ * Auto-select triggers when:
+ * - autoSelectSingle option is explicitly enabled (default: false for multiselect)
+ * - Provider has finished loading
+ * - Exactly one item is available
+ * - Current value is empty array OR current selection is not in the current options
+ */
+export function shouldAutoSelectMulti(
+  params: AutoSelectMultiParams
+): unknown[] | null {
+  const { autoSelectSingle, isLoading, items, currentValue } = params;
+
+  if (!autoSelectSingle || isLoading || items.length !== 1) {
+    return null;
+  }
+
+  const singleItem = items[0];
+  if (!singleItem) {
+    return null;
+  }
+
+  const currentArray = Array.isArray(currentValue) ? currentValue : [];
+  const isValueEmpty = currentArray.length === 0;
+  const hasValidSelection = currentArray.some((val) =>
+    items.some((item) => item.value === val)
+  );
+
+  if (isValueEmpty || !hasValidSelection) {
+    return [singleItem.value];
+  }
+
+  return null;
+}