nuxt-ui-tools 1.3.0 → 1.5.0

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

@@ -0,0 +1,172 @@
+import type { FormValue } from './/index.js';
+import type { FormAction } from './actions.js';
+import type { FormApi, FormSubmitHandler } from './api.js';
+import type { FormFieldCallback } from './callbacks.js';
+import type { FormContextData, FormContextDefinition } from './context.js';
+import type { FormField } from './field.js';
+import type { FormLayoutConfig } from './layout.js';
+import type { FormControlsConfig, FormDrawerConfig, FormFullscreenConfig, FormHeaderConfig, FormModalConfig } from './schema.js';
+import type { FormUiConfig } from './ui.js';
+import type { FormText } from './utils.js';
+/**
+ * One section of a form page: a card in the page and an entry in its navigation.
+ *
+ * Every text accepts a function, so it can be translated:
+ * `label: () => t('account.sections.identity')`.
+ *
+ * @example
+ * ```ts
+ * export function identitySection() {
+ *   return defineFormPageSection({
+ *     key: 'identity',
+ *     label: 'Identity',
+ *     description: 'display name, legal entity and official identifiers',
+ *     fields: [
+ *       { key: 'name', type: 'text', label: 'Name', required: true },
+ *       { key: 'legalEntity', type: 'text', label: 'Legal entity', required: true },
+ *     ],
+ *   })
+ * }
+ * ```
+ */
+export interface FormPageSection<TContext = NonNullable<unknown>, TFields extends readonly FormField<TContext>[] = readonly FormField<TContext>[]> {
+    /**
+     * Names the section: its navigation entry, its scroll target, and the URL hash that opens the
+     * page on it (`#identity`). Also used as the section element's `id`, so keep it unique on the
+     * page. It does not prefix the keys of the section's fields.
+     */
+    key: string;
+    /** Title on the section card and in the navigation. */
+    label: FormText;
+    /** Supporting copy next to the title. */
+    description?: FormText;
+    /**
+     * Shows the section as optional and leaves it out of the sections left to complete. A section
+     * without a required field is optional already; set this when its required fields are filled
+     * by their defaults and the user has nothing to do there.
+     */
+    optional?: boolean;
+    /** Grid of the section's fields, merged over the schema `layout`. */
+    layout?: FormLayoutConfig;
+    /** Raw dependency paths read before evaluating `condition`. */
+    dependencies?: readonly (string | readonly [string, string])[];
+    /** Hides the section, its navigation entry, and its fields while it returns `false`. */
+    condition?: FormFieldCallback<boolean, TContext>;
+    /** Fields of the section. They write at the form root, as if the section were not there. */
+    fields: TFields;
+}
+/**
+ * Side navigation of a form page. Its entries are the page sections.
+ */
+export interface FormPageNavigationConfig {
+    /** Heading above the entries, e.g. `'Création'`. Accepts a function to translate it. */
+    title?: FormText;
+}
+/**
+ * Schema accepted by `defineFormPageSchema`: a form schema whose `sections` replace `fields`.
+ */
+export interface FormPageSchemaInput<TContext extends FormContextDefinition | undefined, TSections extends readonly FormPageSection<FormContextData<TContext>>[]> {
+    /** Stable key used by persistence, diagnostics, and test selectors. */
+    formKey?: string;
+    /** Page heading: `title`, `description`, and the `eyebrow` above the title. */
+    header?: FormHeaderConfig;
+    /** Form-scoped data sources exposed to fields as `ctx`. */
+    context?: TContext;
+    /** Default grid of every section. */
+    layout?: FormLayoutConfig;
+    /** Form-scoped presentation overrides, merged after app defaults. */
+    ui?: FormUiConfig;
+    /** Runtime lifecycle and validation controls. `dirtyCheck` rings the modified sections. */
+    controls?: FormControlsConfig;
+    /** Modal-shell sizing, used when the same schema opens in a modal. */
+    modal?: FormModalConfig;
+    /** Drawer-shell sizing, used when the same schema opens in a drawer. */
+    drawer?: FormDrawerConfig;
+    /** Fullscreen-shell behavior, used when the same schema opens fullscreen. */
+    fullscreen?: FormFullscreenConfig;
+    /** Page actions. Omit to render the built-in submit action. */
+    actions?: readonly FormAction[];
+    /** Runs after validation and before the external submit handler. Return `false` to cancel submit. */
+    onBeforeSubmit?: FormSubmitHandler<FormValue, never>;
+    /** Submit lifecycle hook. */
+    submit?: (params: {
+        value: FormValue;
+        api: FormApi;
+        ctx: FormContextData<TContext>;
+    }) => Promise<void> | void;
+    /** Side navigation of the page. */
+    navigation?: FormPageNavigationConfig;
+    /** Sections of the page, in navigation order. */
+    sections: TSections;
+}
+/**
+ * Card field generated from a section. It renders the section when the schema opens in an
+ * overlay, and its fields keep their root paths because a card adds no path segment.
+ */
+export type FormPageSectionCard<TSection> = TSection extends {
+    readonly key: infer TKey extends string;
+    readonly fields: infer TFields;
+} ? {
+    readonly type: 'card';
+    readonly key: TKey;
+    readonly fields: TFields;
+} : never;
+/** Card fields generated from the sections of a form page, in order. */
+export type FormPageSectionCards<TSections extends readonly FormValue[]> = {
+    readonly [TIndex in keyof TSections]: FormPageSectionCard<TSections[TIndex]>;
+};
+/**
+ * Schema returned by `defineFormPageSchema`: a normal form schema whose `fields` are the cards
+ * generated from `sections`, plus the `sections` and `navigation` that `FormPage` reads.
+ */
+export type FormPageSchema<TInput extends {
+    readonly sections: readonly FormValue[];
+}> = TInput & {
+    readonly fields: FormPageSectionCards<TInput['sections']>;
+};
+/** A section paired with the card generated for it, as the page runtime reads them. */
+export interface FormPageSectionEntry {
+    section: FormPageSection;
+    card: FormField;
+}
+/** How a form page scrolls to a section. */
+export interface FormPageScrollOptions {
+    /** Defaults to `smooth`, or `instant` when the user prefers reduced motion. */
+    behavior?: ScrollBehavior;
+    /** Records the section in the URL hash. Defaults to the page `hash` option. */
+    hash?: boolean;
+    /** Moves focus to the section title, for keyboard and screen reader users. */
+    focus?: boolean;
+}
+/**
+ * Where a section stands:
+ *
+ * - `invalid`: it shows at least one validation error
+ * - `complete`: nothing required is missing and it shows no error; an optional section also
+ *   needs a value, entered by the user or provided by the form input
+ * - `pending`: anything else
+ */
+export type FormPageSectionStatus = 'invalid' | 'complete' | 'pending';
+/**
+ * Live state of a visible section, as the page navigation and section slots receive it.
+ */
+export interface FormPageSectionState {
+    /** Section key. */
+    key: string;
+    /** Position among the visible sections. */
+    index: number;
+    /** Resolved title. */
+    label: string;
+    /** Resolved supporting copy. */
+    description?: string;
+    /** True when the section is declared optional or has no required field. */
+    optional: boolean;
+    /** Number of required fields without a value. */
+    missing: number;
+    /** Summary of the section's requirements, see `FormPageSectionStatus`. */
+    status: FormPageSectionStatus;
+    /** True when a value of the section differs from the form's baseline. */
+    dirty: boolean;
+    /** Dirty paths inside the section. */
+    dirtyPaths: readonly string[];
+}

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

@@ -183,6 +183,64 @@ export interface FormOverlayUi {
     overlay?: FormUiClass;
     content?: FormUiClass;
 }
+/**
+ * Slots of a form page and its parts. Data attributes carry the live state, so a slot can
+ * restyle one state: `data-active` on the current navigation entry, `data-state`
+ * (`complete`, `invalid`, `pending`) on entries and indicators, `data-dirty` on modified
+ * sections and entries.
+ *
+ * Two CSS variables place sections under the pinned header: `--nut-form-page-header` (its
+ * measured height, set by the page) and `--nut-form-page-gap` (the room below it, `24px` by
+ * default). Set them on an element around the navigation and sections, such as the root.
+ */
+export interface FormPageUi {
+    /** The `<form>` element, which scrolls on its own and is the container of the page queries. */
+    root?: FormUiClass;
+    /** Grid holding the navigation and the sections. */
+    body?: FormUiClass;
+    header?: FormUiClass;
+    headerContent?: FormUiClass;
+    heading?: FormUiClass;
+    eyebrow?: FormUiClass;
+    title?: FormUiClass;
+    /** Line under the title: the description and the unsaved-changes badge. */
+    meta?: FormUiClass;
+    unsaved?: FormUiClass;
+    actions?: FormUiClass;
+    navigation?: FormUiClass;
+    /** Holds the navigation title and the entries. */
+    navigationGroup?: FormUiClass;
+    navigationTitle?: FormUiClass;
+    navigationList?: FormUiClass;
+    /** List item around each entry. */
+    navigationEntry?: FormUiClass;
+    navigationItem?: FormUiClass;
+    navigationIndicator?: FormUiClass;
+    /** Check of a complete section in the indicator. */
+    navigationIndicatorIcon?: FormUiClass;
+    /** Dot in the indicator of the current section while it is pending. */
+    navigationIndicatorMarker?: FormUiClass;
+    navigationLabel?: FormUiClass;
+    navigationOptional?: FormUiClass;
+    navigationDirty?: FormUiClass;
+    /** Wrapper under the entries, whose padding insets the summary. */
+    navigationFooter?: FormUiClass;
+    /** The summary, with its top border: "3 sections left to complete". */
+    navigationSummary?: FormUiClass;
+    /** The bold "3 sections" of the summary. */
+    navigationSummaryCount?: FormUiClass;
+    sections?: FormUiClass;
+    /** Placeholder card shown while the schema context loads. */
+    sectionSkeleton?: FormUiClass;
+    section?: FormUiClass;
+    sectionHeader?: FormUiClass;
+    sectionTitle?: FormUiClass;
+    sectionDescription?: FormUiClass;
+    sectionOptional?: FormUiClass;
+    sectionActions?: FormUiClass;
+    sectionReset?: FormUiClass;
+    sectionBody?: FormUiClass;
+}
 export interface FormUiPartConfig<TUi> {
     ui?: TUi;
 }
@@ -219,4 +277,6 @@ export interface FormUiConfig {
     modal?: FormUiPartConfig<FormOverlayUi>;
     drawer?: FormUiPartConfig<FormOverlayUi>;
     fullscreen?: FormUiPartConfig<FormOverlayUi>;
+    /** Form page rendered by `FormPage` and its parts. */
+    page?: FormUiPartConfig<FormPageUi>;
 }

package/dist/runtime/form/utils/controls.d.ts

@@ -0,0 +1,15 @@
+import type { FormUiConfig, FormValidationMode, FormValue } from '../types/index.js';
+/** Reads the schema `controls` object. */
+export declare function getSchemaControls(schema: FormValue): any;
+/** Resolves `controls.syncInput`: `true`, a path list, or no synchronization. */
+export declare function getSchemaSyncInput(schema: FormValue): boolean | readonly string[];
+/** Resolves `controls.validate`, validating everything by default. */
+export declare function getSchemaValidationMode(schema: FormValue): FormValidationMode;
+/** Resolves `controls.autoFocus`: a raw field path, `true` for the first field, or `false`. */
+export declare function getSchemaAutoFocus(schema: FormValue): string | boolean;
+/** True when `controls.dirtyCheck` enables dirty metadata and reset affordances. */
+export declare function getSchemaDirtyCheck(schema: FormValue): boolean;
+/** Reads `controls.confirmNavOnDirty` as authored. */
+export declare function getSchemaDirtyNavigation(schema: FormValue): unknown;
+/** Reads the schema-level `ui` overrides. */
+export declare function getSchemaUi(schema: FormValue): FormUiConfig | undefined;

package/dist/runtime/form/utils/controls.js

@@ -0,0 +1,38 @@
+import { isRecord } from "./path.js";
+import { isBoolean, isString, stringArray } from "./predicate.js";
+export function getSchemaControls(schema) {
+  if (!isRecord(schema)) {
+    return;
+  }
+  const controls = Object.getOwnPropertyDescriptor(schema, "controls")?.value;
+  return isRecord(controls) ? controls : void 0;
+}
+function getSchemaControl(schema, name) {
+  const controls = getSchemaControls(schema);
+  return controls ? Object.getOwnPropertyDescriptor(controls, name)?.value : void 0;
+}
+export function getSchemaSyncInput(schema) {
+  const value = getSchemaControl(schema, "syncInput");
+  return isBoolean(value) ? value : stringArray(value);
+}
+export function getSchemaValidationMode(schema) {
+  const value = getSchemaControl(schema, "validate");
+  return value === false || value === "required" || value === "validators" ? value : true;
+}
+export function getSchemaAutoFocus(schema) {
+  const value = getSchemaControl(schema, "autoFocus");
+  return isString(value) || isBoolean(value) ? value : false;
+}
+export function getSchemaDirtyCheck(schema) {
+  return getSchemaControl(schema, "dirtyCheck") === true;
+}
+export function getSchemaDirtyNavigation(schema) {
+  return getSchemaControl(schema, "confirmNavOnDirty");
+}
+export function getSchemaUi(schema) {
+  if (!isRecord(schema)) {
+    return void 0;
+  }
+  const value = Object.getOwnPropertyDescriptor(schema, "ui")?.value;
+  return isRecord(value) ? value : void 0;
+}

package/dist/runtime/form/utils/layout.js

@@ -8,7 +8,9 @@ export function resolveFormLayoutConfig(base, override) {
   return {
     columns: override?.columns ?? base?.columns ?? FORM_LAYOUT_DEFAULTS.columns,
     fieldSpan: override?.fieldSpan ?? base?.fieldSpan ?? FORM_LAYOUT_DEFAULTS.fieldSpan,
-    gap: override?.gap ?? base?.gap ?? FORM_LAYOUT_DEFAULTS.gap
+    gap: override?.gap ?? base?.gap ?? FORM_LAYOUT_DEFAULTS.gap,
+    labelPosition: override?.labelPosition ?? base?.labelPosition,
+    labelWidth: override?.labelWidth ?? base?.labelWidth
   };
 }
 export function normalizeFormLayoutGap(value) {

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

@@ -0,0 +1,20 @@
+import type { FormObject, FormPageSectionEntry, FormPageSectionState, FormRuntime, FormValue } from '../types/index.js';
+/** Pairs each section of a page schema with the card `defineFormPageSchema` generated for it. */
+export declare function getFormPageSections(schema: FormValue): readonly FormPageSectionEntry[];
+/** Resolved heading of the page navigation. */
+export declare function getFormPageNavigationTitle(schema: FormValue): string | undefined;
+/** True while the section's `condition` lets it render. */
+export declare function isFormPageSectionVisible(entry: FormPageSectionEntry, runtime: FormRuntime): boolean;
+/**
+ * Live state of one visible section: what it still misses, whether it shows errors, and what
+ * changed since the baseline.
+ */
+export declare function resolveFormPageSectionState(params: {
+    entry: FormPageSectionEntry;
+    index: number;
+    runtime: FormRuntime;
+    /** Input the form was opened with: a value it provides counts as filled in. */
+    input: FormObject | undefined;
+    /** False when the validation mode does not enforce required fields. */
+    requiredEnforced: boolean;
+}): FormPageSectionState;

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

@@ -0,0 +1,107 @@
+import { createFormFieldInstance } from "./field-instance.js";
+import { getPathValue, isRecord } from "./path.js";
+import { isBoolean, isFunction, isNumber, isString } from "./predicate.js";
+import {
+  fieldPath,
+  getChildFields,
+  getSchemaFields,
+  isEmptyValue,
+  isFlatPassthroughField,
+  isObjectContainerField,
+  resolveRequired
+} from "./state.js";
+import { resolveFormText } from "./text.js";
+export function getFormPageSections(schema) {
+  if (!isRecord(schema) || !Array.isArray(schema.sections)) {
+    return [];
+  }
+  const cards = getSchemaFields(schema);
+  return schema.sections.filter(isFormPageSection).flatMap((section) => {
+    const card = cards.find((field) => field.key === section.key);
+    return card ? [{ card, section }] : [];
+  });
+}
+export function getFormPageNavigationTitle(schema) {
+  if (!isRecord(schema) || !isRecord(schema.navigation)) {
+    return void 0;
+  }
+  const { title } = schema.navigation;
+  return isFormText(title) ? resolveFormText(title) : void 0;
+}
+export function isFormPageSectionVisible(entry, runtime) {
+  return !hasCondition(entry.card) || runtime.shouldRender(entry.card, [entry.card.key]);
+}
+export function resolveFormPageSectionState(params) {
+  const { entry, runtime } = params;
+  const leaves = collectVisibleLeaves(entry.section.fields, [], runtime);
+  const paths = leaves.map((leaf) => leaf.path.join("."));
+  const contains = (candidate) => paths.some((path) => isPathWithin(candidate, path));
+  const dirtyPaths = runtime.dirtyPaths.value.filter(contains);
+  const invalid = runtime.errors.value.some((error) => contains(error.path));
+  const required = params.requiredEnforced ? leaves.filter((leaf) => isRequiredLeaf(leaf, runtime)) : [];
+  const missing = required.filter((leaf) => isEmptyValue(runtime.getValue(leaf.path))).length;
+  const optional = entry.section.optional === true || required.length === 0;
+  const filled = !optional || leaves.some((leaf) => isProvided(leaf, runtime, dirtyPaths, params.input));
+  return {
+    description: resolveFormText(entry.section.description),
+    dirty: dirtyPaths.length > 0,
+    dirtyPaths,
+    index: params.index,
+    key: entry.section.key,
+    label: resolveFormText(entry.section.label) ?? entry.section.key,
+    missing,
+    optional,
+    status: invalid ? "invalid" : missing === 0 && filled ? "complete" : "pending"
+  };
+}
+function collectVisibleLeaves(fields, parentPath, runtime) {
+  return fields.flatMap((field) => {
+    if (field.ignore === true) {
+      return [];
+    }
+    const path = fieldPath(parentPath, field);
+    if (hasCondition(field) && !runtime.shouldRender(field, path)) {
+      return [];
+    }
+    if (createFormFieldInstance(field).state.is("stateless")) {
+      return [];
+    }
+    if (isFlatPassthroughField(field)) {
+      return collectVisibleLeaves(getChildFields(field), parentPath, runtime);
+    }
+    if (isObjectContainerField(field)) {
+      return collectVisibleLeaves(getChildFields(field), path, runtime);
+    }
+    return [{ field, path }];
+  });
+}
+function isRequiredLeaf(leaf, runtime) {
+  const required = Object.getOwnPropertyDescriptor(leaf.field, "required")?.value;
+  if (isBoolean(required)) {
+    return required;
+  }
+  const validation = Object.getOwnPropertyDescriptor(leaf.field, "validation")?.value;
+  if (!isFunction(required) && !isRecord(validation)) {
+    return false;
+  }
+  return resolveRequired(leaf.field, runtime.getFieldCallbackParams(leaf.path, leaf.field)) === true;
+}
+function isProvided(leaf, runtime, dirtyPaths, input) {
+  if (isEmptyValue(runtime.getValue(leaf.path))) {
+    return false;
+  }
+  const path = leaf.path.join(".");
+  return dirtyPaths.some((dirtyPath) => isPathWithin(dirtyPath, path)) || !isEmptyValue(getPathValue(input ?? {}, leaf.path));
+}
+function hasCondition(field) {
+  return isFunction(Object.getOwnPropertyDescriptor(field, "condition")?.value);
+}
+function isPathWithin(path, scope) {
+  return path === scope || path.startsWith(`${scope}.`);
+}
+function isFormPageSection(value) {
+  return isRecord(value) && isString(value.key) && isFormText(value.label) && Array.isArray(value.fields);
+}
+function isFormText(value) {
+  return isString(value) || isNumber(value) || isFunction(value);
+}

package/dist/runtime/form/utils/state.d.ts

@@ -30,4 +30,6 @@ export declare function getMatrixRows(field: FormField): any[];
 export declare function resolveRequired(field: FormField, params: FormFieldCallbackParams): any;
 export declare function resolveRequiredMessage(field: FormField, fallback?: string): string;
 export declare function isEmptyValue(value: FormValue): boolean;
+/** Child fields of a container, with the fields of every tab for tabs. */
+export declare function getChildFields(field: FormField): FormField[];
 export declare function getArrayItemFields(field: FormField, item: FormObject): FormField[];

package/dist/runtime/form/utils/state.js

@@ -588,7 +588,7 @@ function isFormField(value) {
   const type = Object.getOwnPropertyDescriptor(value, "type")?.value;
   return isString(value.key) && isString(type) && isRegisteredFormFieldType(type);
 }
-function getChildFields(field) {
+export function getChildFields(field) {
   const tabs = Object.getOwnPropertyDescriptor(field, "tabs")?.value;
   if (Array.isArray(tabs)) {
     return tabs.flatMap((tab) => {

package/dist/runtime/form/utils/ui.js

@@ -39,6 +39,7 @@ function mergeFormUiPair(current, next) {
     group: mergePart(current.group, next.group),
     matrix: mergePart(current.matrix, next.matrix),
     modal: mergePart(current.modal, next.modal),
+    page: mergePart(current.page, next.page),
     root: mergePart(current.root, next.root),
     tree: mergePart(current.tree, next.tree),
     treeSelect: mergePart(current.treeSelect, next.treeSelect)

package/dist/runtime/i18n/locales/en.js

@@ -101,6 +101,24 @@ export default defineUiToolsLocale({
         resetButton: "Reset",
         submitButton: "Submit"
       },
+      page: {
+        complete: "Everything is ready.",
+        modifiedOne: "{count} modified.",
+        modifiedOther: "{count} modified.",
+        navigation: "Form sections",
+        optional: "optional",
+        remaining: "{count} left to complete.",
+        resetSection: "Reset",
+        sectionsOne: "{count} section",
+        sectionsOther: "{count} sections",
+        status: {
+          complete: "Complete",
+          invalid: "Has errors",
+          pending: "To complete"
+        },
+        unmodified: "No unsaved changes.",
+        unsavedChanges: "Unsaved changes"
+      },
       fields: {
         array: {
           addItem: "Add item",

package/dist/runtime/i18n/locales/fr.js

@@ -101,6 +101,24 @@ export default defineUiToolsLocale({
         resetButton: "R\xE9initialiser",
         submitButton: "Soumettre"
       },
+      page: {
+        complete: "Tout est pr\xEAt.",
+        modifiedOne: "{count} modifi\xE9e.",
+        modifiedOther: "{count} modifi\xE9es.",
+        navigation: "Sections du formulaire",
+        optional: "optionnel",
+        remaining: "{count} \xE0 compl\xE9ter.",
+        resetSection: "R\xE9initialiser",
+        sectionsOne: "{count} section",
+        sectionsOther: "{count} sections",
+        status: {
+          complete: "Compl\xE8te",
+          invalid: "Contient des erreurs",
+          pending: "\xC0 compl\xE9ter"
+        },
+        unmodified: "Aucune modification en cours.",
+        unsavedChanges: "Modifications non enregistr\xE9es"
+      },
       fields: {
         array: {
           addItem: "Ajouter un \xE9l\xE9ment",

package/dist/runtime/i18n/types.d.ts

@@ -275,6 +275,35 @@ export interface UiToolsFormMessages {
         cancelButton: string;
         resetButton: string;
     };
+    /** Form page chrome. Counts use `Intl.PluralRules`: `One` for "one", `Other` otherwise. */
+    page: {
+        /** Accessible name of the section navigation when the schema gives it no title. */
+        navigation: string;
+        /** Marks an optional section, in the navigation and on its card. */
+        optional: string;
+        /** Badge under the page title and name of a section's dirty marker. */
+        unsavedChanges: string;
+        /** Button of a modified section that puts its values back. */
+        resetSection: string;
+        /** Bold count inserted in `remaining` and `modified`: "{count} sections". */
+        sectionsOne: string;
+        sectionsOther: string;
+        /** Navigation summary while required sections are incomplete: "{count} to complete." */
+        remaining: string;
+        /** Navigation summary once every required section is complete. */
+        complete: string;
+        /** Navigation summary of a form with dirty checking: "{count} modified." */
+        modifiedOne: string;
+        modifiedOther: string;
+        /** Navigation summary of a form with dirty checking and no change. */
+        unmodified: string;
+        /** Accessible status of a navigation entry. */
+        status: {
+            complete: string;
+            pending: string;
+            invalid: string;
+        };
+    };
     states: {
         contextError: {
             title: string;

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

@@ -1,5 +1,6 @@
 export * from './composables/use-responsive-value.js';
 export * from './composables/use-range-select.js';
+export { defineRemoteOptions } from './utils/define-remote-options.js';
 export * from './types/responsive.js';
 export * from './types/utils.js';
 export * from './utils/object.js';

package/dist/runtime/shared/index.js

@@ -1,5 +1,6 @@
 export * from "./composables/use-responsive-value.js";
 export * from "./composables/use-range-select.js";
+export { defineRemoteOptions } from "./utils/define-remote-options.js";
 export * from "./types/responsive.js";
 export * from "./types/utils.js";
 export * from "./utils/object.js";

package/dist/runtime/shared/types/query.d.ts

@@ -1,4 +1,4 @@
-import type { QueryFunction, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
+import type { QueryFunction, QueryKey, QueryOptions, UseQueryOptions } from '@tanstack/vue-query';
 /**
  * TanStack query definition accepted by runtime domains that own the `useQuery` call themselves
  * (table sources, dashboard queries): an explicit `queryKey`, an optional `queryFn`, and any other
@@ -16,3 +16,7 @@ export interface QueryFnDefinition<TData = unknown> {
     queryKey: QueryKey;
     queryFn: QueryFunction<TData, QueryKey, string | null>;
 }
+/** Data returned by a query function, including generated options whose function may be a ref. */
+export type QueryFunctionResult<TQuery> = TQuery extends {
+    queryFn: (...args: never[]) => infer TResult;
+} ? Awaited<TResult> : TQuery extends QueryOptions<infer TQueryFnData, infer _TError, infer _TData, infer _TQueryData, infer _TQueryKey> ? Awaited<TQueryFnData> : TQuery extends UseQueryOptions<infer _TQueryFnData, infer _TError, infer TData, infer _TQueryData, infer _TQueryKey> ? Awaited<TData> : never;

package/dist/runtime/shared/types/remote-options.d.ts

@@ -1,3 +1,11 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { QueryFnDefinition, QueryFunctionResult } from './query.js';
+export type RemoteOptionValue = string | number | boolean;
+/** Option shape shared by dashboard, table, and form remote pickers. */
+export interface RemoteOption<TValue extends RemoteOptionValue = RemoteOptionValue> {
+    value: TValue;
+    label: string;
+}
 /**
  * Page envelope returned by an index-paginated remote option source.
  */
@@ -35,3 +43,51 @@ export interface RemoteOptionsSearch {
     /** Minimum term length before a search request runs. Defaults to 0. */
     minLength?: number;
 }
+/** One reusable, query-backed option source. Inline remote definitions remain supported. */
+export interface RemoteOptionsLoader<TOption> {
+    load: (request: {
+        search: string;
+        page: RemoteOptionsPageRequest;
+    }) => QueryFnDefinition<RemoteOptionsResult<TOption>>;
+    resolveSelected: (request: {
+        values: readonly RemoteOptionValue[];
+    }) => QueryFnDefinition<readonly TOption[]>;
+    pagination: RemoteOptionsPagination;
+    search?: RemoteOptionsSearch;
+    /** Identity of a page query, used by pickers that cache an infinite list as one query. */
+    queryKeyFor?: (request: {
+        search: string;
+        page: RemoteOptionsPageRequest;
+    }) => QueryKey;
+    /** Identity of a selected-value lookup, including any scope used only by that endpoint. */
+    selectedQueryKeyFor?: (request: {
+        values: readonly RemoteOptionValue[];
+    }) => QueryKey;
+}
+/** Query options returned by an endpoint or generated client. */
+export interface RemoteOptionsQueryDefinition {
+    queryKey: QueryKey;
+}
+/** Endpoint query definitions; supplied before mapping so their result types are inferred first. */
+export interface RemoteOptionsQueries<TPageQuery extends RemoteOptionsQueryDefinition, TSelectedQuery extends RemoteOptionsQueryDefinition> {
+    load: (request: {
+        search: string;
+        page: RemoteOptionsPageRequest;
+    }) => TPageQuery;
+    resolveSelected: (request: {
+        values: readonly RemoteOptionValue[];
+    }) => TSelectedQuery;
+}
+/** Maps endpoint responses to the option result shared by all three pickers. */
+export interface DefineRemoteOptionsConfig<TPageQuery extends RemoteOptionsQueryDefinition, TSelectedQuery extends RemoteOptionsQueryDefinition, TOption extends RemoteOption> {
+    /** Stable namespace for mapped query results; requests still use their endpoint query keys. */
+    key: string;
+    /** Maps the endpoint page to options and the next-page marker. */
+    mapPage: (result: QueryFunctionResult<TPageQuery>) => RemoteOptionsResult<TOption>;
+    /** Maps selected lookup results to option items. */
+    mapSelected: (result: QueryFunctionResult<TSelectedQuery>) => readonly NoInfer<TOption>[];
+    /** Page type and size expected by the endpoint. */
+    pagination: RemoteOptionsPagination;
+    /** Debounce and minimum term length applied by the consuming picker. */
+    search?: RemoteOptionsSearch;
+}