nuxt-ui-tools 1.3.0 → 1.5.0

package/dist/runtime/form/composables/use-remote-field-options.js

@@ -1,4 +1,4 @@
-import { useQueryClient } from "@tanstack/vue-query";
+import { hashKey, useQueryClient } from "@tanstack/vue-query";
 import { debounceFilter, watchWithFilter } from "@vueuse/core";
 import { computed, ref, shallowRef, watch } from "vue";
 import { formOptionKey, mergeResolvedOptions, normalizeOptionItems } from "../utils/options.js";
@@ -384,7 +384,7 @@ export function useRemoteFieldOptions(params) {
         selectedError.value = null;
         return;
       }
-      retainSelected([]);
+      retainSelected(loaded.value);
       if (missingSelected.value.length) {
         void hydrateSelected({ reconcile: false });
       }
@@ -410,6 +410,25 @@ export function useRemoteFieldOptions(params) {
     },
     { deep: true }
   );
+  const pageIdentity = computed(() => {
+    const config = params.config.value;
+    return config?.queryKeyFor ? hashKey(
+      config.queryKeyFor({
+        page: { cursor: null, index: 1, size: pageSize.value },
+        search: ""
+      })
+    ) : null;
+  });
+  const selectedIdentity = computed(() => {
+    const config = params.config.value;
+    return config?.selectedQueryKeyFor ? hashKey(config.selectedQueryKeyFor({ values: [] })) : null;
+  });
+  watch([pageIdentity, selectedIdentity], ([page, selected], [previousPage, previousSelected]) => {
+    if (page === previousPage && selected === previousSelected) return;
+    selectionGeneration.value += 1;
+    if (page !== previousPage) void reload({ clearSearch: false });
+    if (selectedValues.value.length) void hydrateSelected({ reconcile: true });
+  });
   return {
     activate,
     error: errorValue,

package/dist/runtime/form/fields/checkbox-card/component.vue

@@ -5,18 +5,20 @@ import FormFieldShell from "../../components/renderer/form-field-shell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 import { formOptionKey } from "../../utils/options";
 import { isBoolean, isNumber, isString, isUndefined } from "../../utils/predicate";
-import { mergeFormUiClass } from "../../utils/ui";
-import { CARD_SELECTED_RING } from "../card-selection";
+import ChoiceCardLabel from "../choice-card/choice-card-label.vue";
+import { CHOICE_CARD_PROPS, useChoiceCard } from "../choice-card/use-choice-card";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
 const { fieldProps, form, controlProps, disabled, handleBlur, options } = useFieldControl(
   () => props.field,
-  () => props.path
+  () => props.path,
+  { omit: CHOICE_CARD_PROPS }
 );
-const valueByKey = computed(
-  () => new Map(options.items.value.map((item) => [formOptionKey(item.value), item.value]))
+const cards = useChoiceCard({ props: () => fieldProps.value, ui: () => controlProps.value.ui });
+const optionByKey = computed(
+  () => new Map(options.items.value.map((item) => [formOptionKey(item.value), item]))
 );
 const model = computed({
   get: () => {
@@ -26,22 +28,17 @@ const model = computed({
   set: (value) => form.setValue(
     props.path,
     value.flatMap((key) => {
-      const optionValue = valueByKey.value.get(key);
+      const optionValue = optionByKey.value.get(key)?.value;
       return isUndefined(optionValue) ? [] : [optionValue];
     })
   )
 });
 const items = computed(
-  () => options.items.value.map((item) => ({ ...item, value: formOptionKey(item.value) }))
+  () => options.items.value.map(({ icon: _icon, ...item }) => ({
+    ...item,
+    value: formOptionKey(item.value)
+  }))
 );
-const groupUi = computed(() => ({
-  ...controlProps.value.ui,
-  fieldset: mergeFormUiClass(
-    controlProps.value.ui?.fieldset,
-    fieldProps.value.orientation === "horizontal" ? "flex-wrap" : void 0
-  ),
-  item: mergeFormUiClass(CARD_SELECTED_RING, controlProps.value.ui?.item)
-}));
 function isOptionValue(value) {
   return isString(value) || isNumber(value) || isBoolean(value);
 }
@@ -56,12 +53,24 @@ function isOptionValue(value) {
       value-key="value"
       label-key="label"
       description-key="description"
-      :orientation="fieldProps.orientation"
-      :ui="groupUi"
       variant="card"
-      :indicator="fieldProps.indicator"
+      :orientation="cards.orientation.value"
+      :indicator="cards.indicator.value"
+      :ui="cards.ui.value"
+      :style="cards.style.value"
       :disabled="disabled"
       @blur="handleBlur"
-    />
+    >
+      <template #label="{ item }">
+        <ChoiceCardLabel
+          :label="optionByKey.get(item.value)?.label ?? item.label"
+          :icon="optionByKey.get(item.value)?.icon"
+          :tile="cards.tile.value"
+          :corner="cards.corner.value"
+          :selected="model.includes(item.value)"
+          :ui="cards.ui.value"
+        />
+      </template>
+    </UCheckboxGroup>
   </FormFieldShell>
 </template>

package/dist/runtime/form/fields/checkbox-card/types.d.ts

@@ -1,11 +1,8 @@
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldOptionValue, NullableValue } from '../../types/field-output-utils.js';
 import type { FormOptionConfig, FormOptionItem, FormOptionValue, FormOptionsSource } from '../../types/options.js';
-export interface FormCheckboxCardProps {
-    orientation?: 'horizontal' | 'vertical';
-    indicator?: 'start' | 'end' | 'hidden';
-}
-export interface FormCheckboxCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'checkbox-card', readonly TValue[] | null, TContext, TDeps, FormCheckboxCardProps> {
+import type { FormChoiceCardProps } from '../choice-card/types.js';
+export interface FormCheckboxCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'checkbox-card', readonly TValue[] | null, TContext, TDeps, FormChoiceCardProps> {
     options: FormOptionConfig<TOption, TContext, TDeps, readonly TValue[] | null> | FormOptionsSource<TOption, TContext, TDeps, readonly TValue[] | null>;
 }
 export type CheckboxCardFieldOutput<TField> = readonly FieldOptionValue<TField>[] | NullableValue;

package/dist/runtime/form/fields/choice-card/choice-card-label.d.vue.ts

@@ -0,0 +1,17 @@
+import type { FormControlUi } from '../../types/index.js';
+/**
+ * Content of a card's label: the option icon, inline or in a tile above the label, and the check
+ * a selected card shows in its corner. Styled through `ui.tile`, `ui.tileIcon`, `ui.optionIcon`,
+ * `ui.check`, and `ui.checkIcon`.
+ */
+type __VLS_Props = {
+    label?: string;
+    icon?: string;
+    tile: boolean;
+    corner: boolean;
+    selected: boolean;
+    ui?: FormControlUi;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/form/fields/choice-card/choice-card-label.vue

@@ -0,0 +1,50 @@
+<script setup>
+import UIcon from "@nuxt/ui/components/Icon.vue";
+import { mergeFormUiClass } from "../../utils/ui";
+defineProps({
+  label: { type: String, required: false },
+  icon: { type: String, required: false },
+  tile: { type: Boolean, required: true },
+  corner: { type: Boolean, required: true },
+  selected: { type: Boolean, required: true },
+  ui: { type: Object, required: false }
+});
+</script>
+
+<template>
+  <span
+    v-if="tile && icon"
+    :data-selected="selected || void 0"
+    :class="
+  mergeFormUiClass(
+    'grid size-8 place-items-center rounded-lg bg-elevated text-muted transition-colors data-[selected]:bg-primary/10 data-[selected]:text-primary',
+    ui?.tile
+  )
+"
+    data-choice-tile
+  >
+    <UIcon :name="icon" :class="mergeFormUiClass('size-4', ui?.tileIcon)" aria-hidden="true" />
+  </span>
+  <span v-if="!tile && icon" class="inline-flex items-center gap-2">
+    <UIcon
+      :name="icon"
+      :class="mergeFormUiClass('size-4 shrink-0', ui?.optionIcon)"
+      aria-hidden="true"
+    />
+    <span>{{ label }}</span>
+  </span>
+  <span v-else class="block">{{ label }}</span>
+  <span
+    v-if="corner && selected"
+    aria-hidden="true"
+    :class="
+  mergeFormUiClass(
+    'absolute end-3 top-3 grid size-4 place-items-center rounded-[4px] bg-primary text-inverted',
+    ui?.check
+  )
+"
+    data-choice-check
+  >
+    <UIcon name="i-lucide-check" :class="mergeFormUiClass('size-2.5', ui?.checkIcon)" />
+  </span>
+</template>

package/dist/runtime/form/fields/choice-card/choice-card-label.vue.d.ts

@@ -0,0 +1,17 @@
+import type { FormControlUi } from '../../types/index.js';
+/**
+ * Content of a card's label: the option icon, inline or in a tile above the label, and the check
+ * a selected card shows in its corner. Styled through `ui.tile`, `ui.tileIcon`, `ui.optionIcon`,
+ * `ui.check`, and `ui.checkIcon`.
+ */
+type __VLS_Props = {
+    label?: string;
+    icon?: string;
+    tile: boolean;
+    corner: boolean;
+    selected: boolean;
+    ui?: FormControlUi;
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/form/fields/choice-card/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Presentation of the radio and checkbox cards.
+ *
+ * @example
+ * ```ts
+ * // A fixed grid of cards, each with its icon in a tile above the label and a check in the
+ * // corner once selected.
+ * props: { columns: '1 md:2 lg:3', icon: 'tile', indicator: 'corner' }
+ * ```
+ */
+export interface FormChoiceCardProps {
+    /**
+     * Lays the cards out in a fixed grid of this many equal columns. Accepts breakpoints:
+     * `3` or `'1 md:2 lg:3'`. Without it, cards flow along `orientation`.
+     */
+    columns?: number | string;
+    /** Direction of the cards when they are not in a `columns` grid. */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Selection mark: the radio or checkbox before the content (`start`, the default), after it
+     * (`end`), none (`hidden`), or a check in the top corner of the selected cards (`corner`).
+     */
+    indicator?: 'start' | 'end' | 'hidden' | 'corner';
+    /**
+     * Where an option's `icon` shows: before its label (`inline`, the default), or in a tile above
+     * it (`tile`) that takes the selection color. Style the parts the engine renders with the
+     * `ui` slots `tile`, `tileIcon`, `optionIcon`, `check`, and `checkIcon`, next to the Nuxt UI
+     * slots of the group.
+     */
+    icon?: 'inline' | 'tile';
+}

package/dist/runtime/form/fields/choice-card/use-choice-card.d.ts

@@ -0,0 +1,22 @@
+import type { FormControlUi } from '../../types/index.js';
+import type { FormChoiceCardProps } from './types.js';
+/** Props the card fields render themselves, kept away from the Nuxt UI group. */
+export declare const CHOICE_CARD_PROPS: string[];
+/**
+ * Presentation of a radio or checkbox card group: the flowing row or fixed grid of cards, the
+ * selection mark, and where option icons go. Returns the props and `ui` slots for the Nuxt UI
+ * group, and what the card content renders (`tile`, `corner`).
+ */
+export declare function useChoiceCard(params: {
+    props: () => FormChoiceCardProps;
+    ui: () => FormControlUi | undefined;
+}): {
+    corner: import("vue").ComputedRef<boolean>;
+    indicator: import("vue").ComputedRef<"end" | "start" | "hidden" | undefined>;
+    orientation: import("vue").ComputedRef<"horizontal" | "vertical" | undefined>;
+    style: import("vue").ComputedRef<{
+        '--nut-choice-columns': string;
+    } | undefined>;
+    tile: import("vue").ComputedRef<boolean>;
+    ui: import("vue").ComputedRef<FormControlUi>;
+};

package/dist/runtime/form/fields/choice-card/use-choice-card.js

@@ -0,0 +1,52 @@
+import { computed } from "vue";
+import { useResponsiveValue } from "../../../shared/composables/use-responsive-value.js";
+import { mergeFormUiClass } from "../../utils/ui.js";
+import { CARD_SELECTED_RING } from "../card-selection.js";
+export const CHOICE_CARD_PROPS = ["columns", "icon", "indicator", "orientation"];
+export function useChoiceCard(params) {
+  const columnsValue = useResponsiveValue(() => String(params.props().columns ?? ""));
+  const columns = computed(() => {
+    const count = Math.trunc(Number(columnsValue.value));
+    return count > 0 ? count : void 0;
+  });
+  const corner = computed(() => params.props().indicator === "corner");
+  const tile = computed(() => params.props().icon === "tile");
+  const indicator = computed(() => {
+    const value = params.props().indicator;
+    return value === "corner" ? "hidden" : value;
+  });
+  const orientation = computed(() => params.props().orientation);
+  const style = computed(
+    () => columns.value ? { "--nut-choice-columns": String(columns.value) } : void 0
+  );
+  const ui = computed(() => {
+    const current = params.ui();
+    return {
+      ...current,
+      fieldset: mergeFormUiClass(
+        columns.value ? "grid grid-cols-[repeat(var(--nut-choice-columns),minmax(0,1fr))] gap-2.5" : `gap-2.5${orientation.value === "horizontal" ? " flex-wrap" : ""}`,
+        current?.fieldset
+      ),
+      item: mergeFormUiClass(
+        `border-default ${CARD_SELECTED_RING}`,
+        corner.value ? "relative" : void 0,
+        current?.item
+      ),
+      // A tile stacks above the title, and the description below it, with gaps.
+      label: mergeFormUiClass(
+        tile.value ? "flex flex-col items-start gap-2.5 font-semibold" : void 0,
+        current?.label
+      ),
+      // A hidden indicator centers the text: keep it aligned, and clear of an inline corner check.
+      wrapper: mergeFormUiClass(
+        tile.value ? "flex flex-col gap-1.5" : void 0,
+        [
+          indicator.value === "hidden" ? "ms-0 text-start" : "",
+          corner.value && !tile.value ? "pe-7" : ""
+        ].join(" "),
+        current?.wrapper
+      )
+    };
+  });
+  return { corner, indicator, orientation, style, tile, ui };
+}

package/dist/runtime/form/fields/radio-card/component.vue

@@ -1,20 +1,21 @@
 <script setup>
-import UIcon from "@nuxt/ui/components/Icon.vue";
 import URadioGroup from "@nuxt/ui/components/RadioGroup.vue";
 import { computed } from "vue";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
 import { useFieldControl } from "../../composables/use-field-control";
 import { isBoolean, isNumber, isString } from "../../utils/predicate";
-import { mergeFormUiClass } from "../../utils/ui";
-import { CARD_SELECTED_RING } from "../card-selection";
+import ChoiceCardLabel from "../choice-card/choice-card-label.vue";
+import { CHOICE_CARD_PROPS, useChoiceCard } from "../choice-card/use-choice-card";
 const props = defineProps({
   field: { type: Object, required: true },
   path: { type: Array, required: true }
 });
 const { fieldProps, form, controlProps, disabled, handleBlur, options } = useFieldControl(
   () => props.field,
-  () => props.path
+  () => props.path,
+  { omit: CHOICE_CARD_PROPS }
 );
+const cards = useChoiceCard({ props: () => fieldProps.value, ui: () => controlProps.value.ui });
 const model = computed({
   get: () => {
     const value = form.getValue(props.path);
@@ -26,14 +27,6 @@ const model = computed({
   set: (value) => form.setValue(props.path, value)
 });
 const items = computed(() => [...options.items.value]);
-const groupUi = computed(() => ({
-  ...controlProps.value.ui,
-  fieldset: mergeFormUiClass(
-    controlProps.value.ui?.fieldset,
-    fieldProps.value.orientation === "horizontal" ? "flex-wrap" : void 0
-  ),
-  item: mergeFormUiClass(CARD_SELECTED_RING, controlProps.value.ui?.item)
-}));
 </script>
 
 <template>
@@ -45,16 +38,22 @@ const groupUi = computed(() => ({
       label-key="label"
       variant="card"
       :items="items"
-      :orientation="fieldProps.orientation"
-      :ui="groupUi"
+      :orientation="cards.orientation.value"
+      :indicator="cards.indicator.value"
+      :ui="cards.ui.value"
+      :style="cards.style.value"
       :disabled="disabled"
       @blur="handleBlur"
     >
       <template #label="{ item }">
-        <span class="inline-flex items-center gap-2">
-          <UIcon v-if="item.icon" :name="item.icon" class="size-4 shrink-0" aria-hidden="true" />
-          <span>{{ item.label }}</span>
-        </span>
+        <ChoiceCardLabel
+          :label="item.label"
+          :icon="item.icon"
+          :tile="cards.tile.value"
+          :corner="cards.corner.value"
+          :selected="model === item.value"
+          :ui="cards.ui.value"
+        />
       </template>
     </URadioGroup>
   </FormFieldShell>

package/dist/runtime/form/fields/radio-card/types.d.ts

@@ -1,10 +1,8 @@
 import type { FormStatefulFieldBase } from '../../types/field-base.js';
 import type { FieldOptionValue, NullableValue } from '../../types/field-output-utils.js';
 import type { FormOptionItem, FormOptionValue, FormOptionsSource } from '../../types/options.js';
-export interface FormRadioCardProps {
-    orientation?: 'horizontal' | 'vertical';
-}
-export interface FormRadioCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'radio-card', TValue | null, TContext, TDeps, FormRadioCardProps> {
+import type { FormChoiceCardProps } from '../choice-card/types.js';
+export interface FormRadioCardField<TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue extends FormOptionValue = FormOptionValue, TOption extends FormOptionItem<TValue> = FormOptionItem<TValue>> extends FormStatefulFieldBase<'radio-card', TValue | null, TContext, TDeps, FormChoiceCardProps> {
     options: FormOptionsSource<TOption, TContext, TDeps, TValue | null>;
 }
 export type RadioCardFieldOutput<TField> = FieldOptionValue<TField> | NullableValue;

package/dist/runtime/form/index.d.ts

@@ -1,4 +1,4 @@
-export { defineFormField, defineFormFields, defineFormSchema } from './schema/index.js';
+export { defineFormField, defineFormFields, defineFormPageSchema, defineFormPageSection, defineFormSchema, } from './schema/index.js';
 export { useForm } from './composables/use-form.js';
 export { useFormUi } from './composables/use-form-ui.js';
 export { provideFormApi, useFormApi } from './composables/use-form-api.js';

package/dist/runtime/form/index.js

@@ -1,4 +1,10 @@
-export { defineFormField, defineFormFields, defineFormSchema } from "./schema/index.js";
+export {
+  defineFormField,
+  defineFormFields,
+  defineFormPageSchema,
+  defineFormPageSection,
+  defineFormSchema
+} from "./schema/index.js";
 export { useForm } from "./composables/use-form.js";
 export { useFormUi } from "./composables/use-form-ui.js";
 export { provideFormApi, useFormApi } from "./composables/use-form-api.js";

package/dist/runtime/form/schema/index.d.ts

@@ -81,4 +81,4 @@ export declare function defineFormField<const TField extends FormField>(field: T
  * Defines a reusable field group while preserving literal inference.
  */
 export declare function defineFormFields<const TFields extends readonly FormField[]>(fields: TFields): TFields;
-export {};
+export { defineFormPageSchema, defineFormPageSection } from './page.js';

package/dist/runtime/form/schema/index.js

@@ -7,3 +7,4 @@ export function defineFormField(field) {
 export function defineFormFields(fields) {
   return fields;
 }
+export { defineFormPageSchema, defineFormPageSection } from "./page.js";

package/dist/runtime/form/schema/page.d.ts

@@ -0,0 +1,50 @@
+import type { FormContextData, FormContextDefinition, FormPageSchema, FormPageSchemaInput, FormPageSection } from '../types/index.js';
+/**
+ * Defines one section of a form page while preserving literal field inference, so each section
+ * can live in its own file as a plain typed function.
+ *
+ * @example
+ * ```ts
+ * export function billingSection({ hasActiveContract }: { hasActiveContract: boolean }) {
+ *   return defineFormPageSection({
+ *     key: 'billing',
+ *     label: () => t('account.sections.billing'),
+ *     fields: [
+ *       {
+ *         key: 'vtestId',
+ *         type: 'text',
+ *         label: 'VTEST ID',
+ *         // `accountType` belongs to another section: a page is one form, one state.
+ *         dependencies: ['accountType'],
+ *         required: ({ deps }) => hasActiveContract || 'accountType' in deps,
+ *       },
+ *     ],
+ *   })
+ * }
+ * ```
+ */
+export declare function defineFormPageSection<const TSection extends FormPageSection>(section: TSection): TSection;
+/**
+ * Defines a form page: one form whose fields are grouped in `sections`. Each section becomes a
+ * card of the page and an entry of its navigation; render it with `<UiFormPage :form />`.
+ *
+ * The result is a normal form schema. Its `fields` are the cards generated from the sections,
+ * so `useForm`, validation, cross-section dependencies, and the typed `formData` work as for any
+ * schema, and the same schema opens in a modal or drawer as a stack of cards.
+ *
+ * @example
+ * ```ts
+ * export function accountFormSchema({ account }: { account?: Account } = {}) {
+ *   return defineFormPageSchema({
+ *     header: { title: () => t(account ? 'account.edit' : 'account.create') },
+ *     controls: { dirtyCheck: Boolean(account) },
+ *     navigation: { title: () => t('account.sections.title') },
+ *     sections: [accountTypeSection(), identitySection(), billingSection({ hasActiveContract: false })],
+ *   })
+ * }
+ * ```
+ */
+export declare function defineFormPageSchema<const TContext extends FormContextDefinition, const TSections extends readonly FormPageSection<FormContextData<NoInfer<TContext>>>[]>(schema: FormPageSchemaInput<TContext, TSections> & {
+    context: TContext;
+}): FormPageSchema<FormPageSchemaInput<TContext, TSections>>;
+export declare function defineFormPageSchema<const TSections extends readonly FormPageSection<FormContextData<undefined>>[]>(schema: FormPageSchemaInput<undefined, TSections>): FormPageSchema<FormPageSchemaInput<undefined, TSections>>;

package/dist/runtime/form/schema/page.js

@@ -0,0 +1,25 @@
+import { isRecord } from "../utils/path.js";
+export function defineFormPageSection(section) {
+  return section;
+}
+export function defineFormPageSchema(schema) {
+  if (!isRecord(schema) || !Array.isArray(schema.sections)) {
+    return schema;
+  }
+  return { ...schema, fields: schema.sections.filter(isRecord).map(toSectionCard) };
+}
+const CARD_PROPERTIES = ["condition", "dependencies", "description"];
+function toSectionCard(section) {
+  const card = {
+    fields: section.fields,
+    key: section.key,
+    label: section.label,
+    type: "card"
+  };
+  for (const property of CARD_PROPERTIES) {
+    if (section[property] !== void 0) {
+      card[property] = section[property];
+    }
+  }
+  return card;
+}

package/dist/runtime/form/types/index.d.ts

@@ -15,6 +15,7 @@ export type * from './layout';
 export type * from './options';
 export type * from './options-runtime';
 export type * from './overlay';
+export type * from './page';
 export type * from './output';
 export type * from './runtime';
 export type * from './schema';

package/dist/runtime/form/types/options.d.ts

@@ -1,4 +1,5 @@
-import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
+import type { QueryKey } from '@tanstack/vue-query';
+import type { RemoteOptionsLoader, RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { FormValue } from './/index.js';
 import type { FormFieldCallback, FormFieldCallbackParams } from './callbacks.js';
 import type { FormQueryOptions } from './context.js';
@@ -92,6 +93,15 @@ export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>
     resolveSelected?: (request: FormRemoteSelectedRequest<TContext, TDeps, TValue, TOption>) => FormRemoteSource<readonly TOption[]>;
     pagination: RemoteOptionsPagination;
     search?: RemoteOptionsSearch;
+    /** Identity of the first page, so reusable loaders follow external scope changes. */
+    queryKeyFor?: (request: {
+        search: string;
+        page: RemoteOptionsPageRequest;
+    }) => QueryKey;
+    /** Identity of selected labels, including scope absent from the page endpoint. */
+    selectedQueryKeyFor?: (request: {
+        values: readonly FormOptionValue[];
+    }) => QueryKey;
     /** Dependency aliases whose changes reset the loaded pages and re-run selected hydration. */
     refreshOn?: readonly string[];
     /** Clears selected values the latest successful selected hydration did not return. Defaults to `false`. */
@@ -103,4 +113,14 @@ export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>
     /** Disable the field while its option source has no usable data yet. */
     disableOnLoading?: boolean;
 }
-export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;
+/** Reuses one remote loader while keeping field-specific refresh and creation behavior local. */
+export interface FormRemoteLoaderOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> extends Omit<FormRemoteOptionConfig<TOption, TContext, TDeps, TValue>, 'source' | 'resolveSelected' | 'pagination' | 'search' | 'queryKeyFor' | 'selectedQueryKeyFor'> {
+    loader: RemoteOptionsLoader<TOption>;
+    source?: never;
+    resolveSelected?: never;
+    pagination?: never;
+    search?: never;
+    queryKeyFor?: never;
+    selectedQueryKeyFor?: never;
+}
+export type FormAnyOptionConfig<TOption, TContext = NonNullable<unknown>, TDeps = NonNullable<unknown>, TValue = FormValue> = FormOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteOptionConfig<TOption, TContext, TDeps, TValue> | FormRemoteLoaderOptionConfig<TOption, TContext, TDeps, TValue> | FormOptionsSource<TOption, TContext, TDeps, TValue>;