nuxt-ui-tools 1.25.1 → 1.27.0

package/dist/runtime/form/fields/date-family/utils.js

@@ -193,6 +193,19 @@ export function calendarSeedFromValue(value, type) {
   }
   return "";
 }
+export function formatDateFamilyBound(value, locale) {
+  const date = /^\d{4}$/u.test(value) ? void 0 : canonicalDateToJsDate(value);
+  if (!date) {
+    return value;
+  }
+  if (/^\d{4}-\d{2}$/u.test(value)) {
+    return new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(date);
+  }
+  return new Intl.DateTimeFormat(
+    locale,
+    value.includes("T") ? { dateStyle: "medium", timeStyle: "short" } : { dateStyle: "medium" }
+  ).format(date);
+}
 export function calendarDateToJsDate(value) {
   return value.toDate(getLocalTimeZone());
 }

package/dist/runtime/form/fields/number/component.vue

@@ -16,7 +16,7 @@ const { code } = useUiToolsLocale();
 const { fieldProps, form, controlProps, disabled, handleBlur, placeholder } = useFieldControl(
   () => props.field,
   () => props.path,
-  { omit: ["prefix", "suffix", "format", "controls", "mono"] }
+  { omit: ["prefix", "suffix", "format", "controls", "mono", "min", "max"] }
 );
 const model = computed({
   get: () => {
@@ -25,6 +25,12 @@ const model = computed({
   },
   set: (value) => form.setValue(props.path, value ?? null)
 });
+const atMax = computed(
+  () => isNumber(model.value) && isNumber(fieldProps.value.max) && model.value >= fieldProps.value.max
+);
+const atMin = computed(
+  () => isNumber(model.value) && isNumber(fieldProps.value.min) && model.value <= fieldProps.value.min
+);
 const prefix = computed(() => resolveFormText(fieldProps.value.prefix));
 const suffix = computed(() => resolveFormText(fieldProps.value.suffix));
 const controls = computed(() => fieldProps.value.controls !== false);
@@ -76,13 +82,13 @@ const affixStyle = computed(() => ({
       :ui="controlUi"
       :placeholder="placeholder"
       :disabled="disabled"
-      :min="fieldProps.min"
-      :max="fieldProps.max"
       :step="fieldProps.step"
       :locale="code"
       :format-options="fieldProps.format"
       :increment="controls"
       :decrement="controls"
+      :increment-disabled="atMax"
+      :decrement-disabled="atMin"
       @blur="handleBlur"
     />
     <span
@@ -121,13 +127,13 @@ const affixStyle = computed(() => ({
         :ui="controlUi"
         :placeholder="placeholder"
         :disabled="disabled"
-        :min="fieldProps.min"
-        :max="fieldProps.max"
         :step="fieldProps.step"
         :locale="code"
         :format-options="fieldProps.format"
         :increment="controls"
         :decrement="controls"
+        :increment-disabled="atMax"
+        :decrement-disabled="atMin"
         @blur="handleBlur"
       />
       <span

package/dist/runtime/form/fields/phone-number/component.vue

@@ -4,7 +4,12 @@ import UFieldGroup from "@nuxt/ui/components/FieldGroup.vue";
 import UIcon from "@nuxt/ui/components/Icon.vue";
 import UInput from "@nuxt/ui/components/Input.vue";
 import USelectMenu from "@nuxt/ui/components/SelectMenu.vue";
-import { getCountries, getCountryCallingCode, parsePhoneNumberFromString } from "libphonenumber-js";
+import {
+  getCountries,
+  getCountryCallingCode,
+  parsePhoneNumberFromString,
+  validatePhoneNumberLength
+} from "libphonenumber-js";
 import { computed, onMounted, ref, useId, watch } from "vue";
 import { useUiToolsLocale } from "../../../i18n/use-locale";
 import FormFieldShell from "../../components/renderer/form-field-shell.vue";
@@ -47,6 +52,20 @@ const processedValue = computed(() => {
   }
   return { valid: true, value: formatPhoneNumber(parsed) };
 });
+const inputError = computed(() => {
+  if (!phoneValue.value || !countryCode.value || processedValue.value.valid) {
+    return null;
+  }
+  return validatePhoneNumberLength(phoneValue.value, countryCode.value) === "TOO_SHORT" ? t("form.validation.phoneIncomplete") : t("form.validation.phoneInvalid");
+});
+watch(
+  [() => props.path, inputError],
+  ([path, message], _previous, onCleanup) => {
+    form.setInputError(path, message);
+    onCleanup(() => form.setInputError(path, null));
+  },
+  { immediate: true }
+);
 onMounted(() => {
   syncFromExternalValue(form.getValue(props.path));
   if (!countryCode.value) {

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

@@ -61,8 +61,8 @@ export interface FormFieldFormApi {
     submit: () => Promise<boolean>;
     /**
      * Closes the form the way its Cancel action does: asks to discard unsaved changes when the
-     * schema asks for it, then cancels (an overlay closes). Does nothing for a form rendered without
-     * a cancel handler.
+     * schema asks for it (an overlay form does by default), then cancels (an overlay closes). Does
+     * nothing for a form rendered without a cancel handler.
      */
     close: () => Promise<void>;
     /** Advances to the next step on stepped forms. */
@@ -206,6 +206,13 @@ export interface FormApi<TOutput = FormObject> {
     submit: () => Promise<void>;
     /** Resets the form and waits for dependency effects triggered by the reset. */
     reset: () => Promise<void>;
+    /**
+     * Closes the form the way its Cancel action does: asks to discard unsaved changes when the
+     * schema asks for it (an overlay form does by default), then cancels, so an overlay closes and
+     * its `createForm` promise resolves with `isCompleted: false`. Does nothing for a form rendered
+     * without a cancel handler.
+     */
+    close: () => Promise<void>;
 }
 export type FormSubmitAction = 'next' | 'previous' | 'submit' | 'reset';
 export type FormSubmitResult<TSubmitData = FormValue> = boolean | void | {

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

@@ -257,7 +257,10 @@ export interface FormRemoteOptionConfig<TOption, TContext = NonNullable<unknown>
     create?: FormCreateOption<TOption, TContext, TDeps, TValue>;
     /** Enables the field-level refresh affordance. */
     allowOptionsRefresh?: boolean;
-    /** Disable the field while its option source has no usable data yet. */
+    /**
+     * Ignored: remote options load once the menu opens and the menu shows the loading state, so the
+     * field and its search input stay usable while a page loads.
+     */
     disableOnLoading?: boolean;
 }
 /** Reuses one remote loader while keeping field-specific refresh and creation behavior local. */

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

@@ -80,6 +80,11 @@ export interface FormRuntime {
     validate: (options?: FormValidationOptions) => Promise<boolean>;
     validateCurrentStep: (options?: FormValidationOptions) => Promise<boolean>;
     setError: (path: string | readonly string[], message: string, options?: FormErrorOptions) => void;
+    /**
+     * Reports input a control holds but cannot store as a value, such as an incomplete phone number,
+     * or clears it with `null`. It shows like a rule error once the field is touched and blocks submit.
+     */
+    setInputError: (path: string | readonly string[], message: string | null) => void;
     clearError: (path?: string | readonly string[]) => void;
     focusRequest: Ref<FormFocusRequest | null>;
     registerFieldElement: (path: string | readonly string[], element: HTMLElement) => () => void;
@@ -94,4 +99,9 @@ export interface FormRuntime {
     goToStep: (index: number) => Promise<boolean>;
     /** Cancels the rendered form, as its Cancel action does. Set by the form root that renders it. */
     bindCancel: (cancel: (() => Promise<void>) | null) => void;
+    /**
+     * Closes the form the way its Cancel action does, asking first when it holds unsaved changes the
+     * schema protects. Resolves at once when no form root renders the runtime.
+     */
+    close: () => Promise<void>;
 }

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

@@ -18,7 +18,11 @@ export interface FormControlsConfig {
     ignoreDirtyPaths?: readonly string[];
     /** Focuses the first field after mount, or a specific raw field path. */
     autoFocus?: boolean | string;
-    /** Warns before an inline dirty form is closed or navigated away from. */
+    /**
+     * Asks before a modified form is cancelled, closed, or left for another page. A form opened as a
+     * modal, drawer, or fullscreen overlay asks before closing (Escape, outside click, close button,
+     * Cancel, `api.close()`) unless this is `false`; leaving the page asks only when it is set.
+     */
     confirmNavOnDirty?: boolean | FormDirtyNavigationConfig;
     /** Keeps external input changes synchronized after the initial mount. */
     syncInput?: boolean | readonly string[];

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

@@ -2,6 +2,7 @@ import { pathSegments } from "./path.js";
 export function createPublicFormApi(runtime) {
   return {
     clearError: (path) => runtime.clearError(path ? pathSegments(path) : void 0),
+    close: runtime.close,
     focus: runtime.focusField,
     get: runtime.getValue,
     initial: runtime.getInitialValue,

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

@@ -269,6 +269,7 @@ export default defineUiToolsLocale({
           open: "Open color picker"
         },
         date: {
+          calendar: "Calendar",
           clear: "Clear value",
           confirm: "Confirm",
           end: "End",
@@ -355,9 +356,17 @@ export default defineUiToolsLocale({
         fallback: "Step {number}"
       },
       validation: {
-        dateMax: "The date must be on or before {max}",
-        dateMin: "The date must be on or after {min}",
-        required: "This field is required"
+        dateMax: "Date after {max}",
+        dateMin: "Date before {min}",
+        monthMax: "Month after {max}",
+        monthMin: "Month before {min}",
+        numberMax: "Maximum value: {bound}",
+        numberMin: "Minimum value: {bound}",
+        phoneIncomplete: "Incomplete phone number",
+        phoneInvalid: "Invalid phone number",
+        required: "This field is required",
+        yearMax: "Year after {max}",
+        yearMin: "Year before {min}"
       }
     },
     spreadsheet: {

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

@@ -269,6 +269,7 @@ export default defineUiToolsLocale({
           open: "Ouvrir le s\xE9lecteur de couleur"
         },
         date: {
+          calendar: "Calendrier",
           clear: "Effacer la valeur",
           confirm: "Confirmer",
           end: "Fin",
@@ -355,9 +356,17 @@ export default defineUiToolsLocale({
         fallback: "\xC9tape {number}"
       },
       validation: {
-        dateMax: "La date doit \xEAtre au plus tard le {max}",
-        dateMin: "La date doit \xEAtre au plus t\xF4t le {min}",
-        required: "Ce champ est requis"
+        dateMax: "Date post\xE9rieure au {max}",
+        dateMin: "Date ant\xE9rieure au {min}",
+        monthMax: "Mois post\xE9rieur \xE0 {max}",
+        monthMin: "Mois ant\xE9rieur \xE0 {min}",
+        numberMax: "Valeur maximale : {bound}",
+        numberMin: "Valeur minimale : {bound}",
+        phoneIncomplete: "Num\xE9ro de t\xE9l\xE9phone incomplet",
+        phoneInvalid: "Num\xE9ro de t\xE9l\xE9phone invalide",
+        required: "Ce champ est requis",
+        yearMax: "Ann\xE9e post\xE9rieure \xE0 {max}",
+        yearMin: "Ann\xE9e ant\xE9rieure \xE0 {min}"
       }
     },
     spreadsheet: {

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

@@ -504,8 +504,22 @@ export interface UiToolsFormMessages {
     };
     validation: {
         required: string;
+        /** A date before the field's `min`: "Date before {min}". */
         dateMin: string;
+        /** A date after the field's `max`: "Date after {max}". */
         dateMax: string;
+        monthMin: string;
+        monthMax: string;
+        yearMin: string;
+        yearMax: string;
+        /** A number below the field's `min`: "Minimum value: {bound}". */
+        numberMin: string;
+        /** A number above the field's `max`: "Maximum value: {bound}". */
+        numberMax: string;
+        /** A phone number too short for its country. */
+        phoneIncomplete: string;
+        /** A phone number that is not valid for its country or allowed types. */
+        phoneInvalid: string;
     };
     fields: {
         text: {
@@ -562,6 +576,8 @@ export interface UiToolsFormMessages {
             end: string;
             clear: string;
             confirm: string;
+            /** Accessible name of the calendar when the field has no label, read before the month. */
+            calendar: string;
             tokens: {
                 day: string;
                 month: string;

package/dist/runtime/table/components/filters/tags/date-filter-tag.vue

@@ -464,6 +464,9 @@ function areSameCalendarDay(left, right) {
                 <UCalendar
                   :model-value="calendarRange"
                   :size="size"
+                  :calendar-label="
+  internals.filters.getFilterLabelText({ label: definition.label })
+"
                   range
                   :number-of-months="rangeCalendarPanels"
                   :paged-navigation="
@@ -602,6 +605,7 @@ function areSameCalendarDay(left, right) {
 "
               :model-value="localDate"
               :size="size"
+              :calendar-label="internals.filters.getFilterLabelText({ label: definition.label })"
               :fixed-weeks="filterUi.scalar.calendar.fixedWeeks"
               :ui="{
   root: mergeDataListUiClass(

package/dist/runtime/table/composables/use-filter-persistence.d.ts

@@ -0,0 +1,14 @@
+import type { ComputedRef, WritableComputedRef } from 'vue';
+import type { TableFilterState, TableSchemaView } from '../types/index.js';
+export interface UseFilterPersistenceParams {
+    schema: ComputedRef<TableSchemaView>;
+    filters: WritableComputedRef<TableFilterState>;
+    /** Writes the restored state without adding a browser history entry. */
+    restore: (state: TableFilterState) => void;
+}
+/**
+ * Keeps the value of every filter marked `behavior.persist` in `localStorage`. On setup, a stored
+ * value replaces the default of a filter the URL does not set; afterwards each change is written
+ * back, and a filter back at its default is forgotten.
+ */
+export declare function useFilterPersistence(params: UseFilterPersistenceParams): void;

package/dist/runtime/table/composables/use-filter-persistence.js

@@ -0,0 +1,77 @@
+import { watch } from "vue";
+import {
+  isTableFilterRuleDefault,
+  parsePersistedFilterRule,
+  persistedFilterStorageKey,
+  serializePersistedFilterRule
+} from "../utils/index.js";
+export function useFilterPersistence(params) {
+  const storage = resolveStorage();
+  const persisted = (params.schema.value.filters?.ui ?? []).filter(
+    (definition) => definition.behavior?.persist === true
+  );
+  if (!storage || persisted.length === 0) {
+    return;
+  }
+  const storageKey = (definition) => persistedFilterStorageKey({
+    tableKey: params.schema.value.tableKey,
+    filterKey: definition.key
+  });
+  const current = params.filters.value.ui;
+  const restored = persisted.flatMap((definition) => {
+    const rule = current.find((candidate) => candidate.key === definition.key);
+    if (rule && !isTableFilterRuleDefault({ definition, rule })) {
+      return [];
+    }
+    const stored = parsePersistedFilterRule({
+      definition,
+      raw: safeRead(storage, storageKey(definition))
+    });
+    return stored ? [stored] : [];
+  });
+  if (restored.length > 0) {
+    const keys = new Set(restored.map((rule) => rule.key));
+    params.restore({
+      ...params.filters.value,
+      ui: [...current.filter((rule) => !keys.has(rule.key)), ...restored]
+    });
+  }
+  watch(
+    () => params.filters.value.ui,
+    (rules) => {
+      for (const definition of persisted) {
+        const rule = rules.find((candidate) => candidate.key === definition.key);
+        safeWrite(
+          storage,
+          storageKey(definition),
+          rule && !isTableFilterRuleDefault({ definition, rule }) ? serializePersistedFilterRule({ definition, rule }) : null
+        );
+      }
+    }
+  );
+}
+function resolveStorage() {
+  try {
+    return typeof window === "undefined" ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+function safeRead(storage, key) {
+  try {
+    return storage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function safeWrite(storage, key, value) {
+  try {
+    if (value === null) {
+      storage.removeItem(key);
+    } else {
+      storage.setItem(key, value);
+    }
+  } catch {
+    return;
+  }
+}

package/dist/runtime/table/composables/use-query-state.js

@@ -19,6 +19,7 @@ import {
   resolveFilterSupportedOperators,
   serializeTableFilterQueryState
 } from "../utils/index.js";
+import { useFilterPersistence } from "./use-filter-persistence.js";
 export function useQueryState(params) {
   const defaultPageSize = getDefaultPageSize({
     layout: params.activeLayout.value,
@@ -96,32 +97,36 @@ export function useQueryState(params) {
       sortingState.value = value ? { dir: value.dir, key: value.key } : { dir: void 0, key: "" };
     }
   });
-  const filters = useQueryStates({
-    historyMode: "push",
-    prefix: "f",
-    schema: {
-      search: { codec: stringCodec, defaultValue: "" },
-      ui: dynamicQueryState({
-        defaultValue: resolveTableFilterDefaultRules(params.schema.value.filters?.ui ?? []),
-        definitions: () => params.schema.value.filters?.ui ?? [],
-        parse(entries, definitions) {
-          return parseTableFilterQueryState({ definitions, entries });
-        },
-        resolve(filter) {
-          const definition = normalizeFilterDefinition(filter);
-          const operators = resolveFilterSupportedOperators(definition);
-          const defaultOp = resolveFilterDefaultOperator(definition);
-          const codec = createTableFilterValueCodec(definition);
-          return operators.map((op) => ({
-            codec,
-            urlKey: op === defaultOp ? definition.key : `${definition.key}~${op}`
-          }));
-        },
-        serialize(rules, definitions) {
-          return serializeTableFilterQueryState({ definitions, rules });
-        },
-        urlPrefix: "ui"
-      })
+  const filterSchema = {
+    search: { codec: stringCodec, defaultValue: "" },
+    ui: dynamicQueryState({
+      defaultValue: resolveTableFilterDefaultRules(params.schema.value.filters?.ui ?? []),
+      definitions: () => params.schema.value.filters?.ui ?? [],
+      parse(entries, definitions) {
+        return parseTableFilterQueryState({ definitions, entries });
+      },
+      resolve(filter) {
+        const definition = normalizeFilterDefinition(filter);
+        const operators = resolveFilterSupportedOperators(definition);
+        const defaultOp = resolveFilterDefaultOperator(definition);
+        const codec = createTableFilterValueCodec(definition);
+        return operators.map((op) => ({
+          codec,
+          urlKey: op === defaultOp ? definition.key : `${definition.key}~${op}`
+        }));
+      },
+      serialize(rules, definitions) {
+        return serializeTableFilterQueryState({ definitions, rules });
+      },
+      urlPrefix: "ui"
+    })
+  };
+  const filters = useQueryStates({ historyMode: "push", prefix: "f", schema: filterSchema });
+  useFilterPersistence({
+    schema: params.schema,
+    filters,
+    restore(state) {
+      useQueryStates({ historyMode: "replace", prefix: "f", schema: filterSchema }).value = state;
     }
   });
   return {

package/dist/runtime/table/composables/use-table-api.js

@@ -23,6 +23,10 @@ export function useTableApi(params) {
     // SAFETY: raw rows follow the same schema source contract before client-side shaping.
     rawRows: computed(() => params.queryContent.rawData.value.rows),
     rawRowCount: computed(() => params.queryContent.rawData.value.rowCount),
+    // SAFETY: filtered rows are the raw source rows after client filtering and sorting.
+    filteredRows: computed(
+      () => params.queryContent.filteredRows.value
+    ),
     context: computed(
       // SAFETY: context keys are decoded from the schema context items before publication.
       () => params.queryContent.contextData.value

package/dist/runtime/table/composables/use-table-data.js

@@ -59,6 +59,7 @@ export function useTableData(params) {
     () => params.state.queryState.sorting.value ? [params.state.queryState.sorting.value] : []
   );
   const requestFilters = computed(() => params.state.resolvedFilterState.value);
+  const rowFilters = computed(() => params.state.rowFilterState.value);
   const requestSearch = computed(() => ({
     fields: params.schema.value.filters?.search?.fields ?? [],
     value: params.state.queryState.filters.value.search
@@ -214,7 +215,7 @@ export function useTableData(params) {
       return rawData.value.rows;
     }
     return filterClientRows({
-      filters: requestFilters.value,
+      filters: rowFilters.value,
       rows: rawData.value.rows,
       search: requestSearch.value
     });
@@ -269,7 +270,7 @@ export function useTableData(params) {
     if (params.schema.value.source.mode === "client") {
       return executeClientFacets({
         facets: clientFacetDescriptors.value,
-        request: requestContext.value,
+        request: { ...requestContext.value, filters: rowFilters.value },
         rows: rawData.value.rows
       });
     }

package/dist/runtime/table/composables/use-table-state.d.ts

@@ -49,4 +49,5 @@ export declare function useTableState(params: UseTableStateParams): {
         } | null>;
     };
     resolvedFilterState: ComputedRef<TableResolvedFilterGroup<string>>;
+    rowFilterState: ComputedRef<TableResolvedFilterGroup<string>>;
 };

package/dist/runtime/table/composables/use-table-state.js

@@ -1,5 +1,5 @@
 import { computed } from "vue";
-import { createResolvedFilterState } from "../utils/index.js";
+import { createResolvedFilterState, withoutQueryFilterRules } from "../utils/index.js";
 import { useQueryState } from "./use-query-state.js";
 export function useTableState(params) {
   const queryState = useQueryState({
@@ -13,8 +13,19 @@ export function useTableState(params) {
       staticFilters: params.schema.value.filters?.static
     })
   );
+  const rowFilterState = computed(
+    () => createResolvedFilterState({
+      definitions: params.schema.value.filters?.ui ?? [],
+      filters: withoutQueryFilterRules({
+        definitions: params.schema.value.filters?.ui ?? [],
+        filters: queryState.filters.value
+      }),
+      staticFilters: params.schema.value.filters?.static
+    })
+  );
   return {
     queryState,
-    resolvedFilterState
+    resolvedFilterState,
+    rowFilterState
   };
 }

package/dist/runtime/table/types/filters.d.ts

@@ -31,6 +31,17 @@ export interface TableFilterBehaviorCommon<TOperator extends TableFilterOperator
     commitMode?: TableFilterCommitMode;
     clearOnOperatorChange?: boolean;
     reopenOnOperatorChange?: boolean;
+    /**
+     * What the filter narrows. `rows` (default) matches every row against it. `query` only hands the
+     * value to the source query, through its `filters`, so a client source can ask the server for a
+     * different dataset (a period, a scope) while its rows are never matched against the rule.
+     */
+    applyTo?: 'rows' | 'query';
+    /**
+     * Remembers the last value in `localStorage`, per table key and filter key. It is restored when
+     * the URL carries no value of its own, and forgotten once the filter returns to its default.
+     */
+    persist?: boolean;
 }
 export interface TableFilterUiActionLabelsConfig {
     actions?: {
@@ -647,6 +658,23 @@ export interface TableOptionFilterDefinition<TRow extends GenericObject = Generi
          */
         remote?: TableFilterRemoteOptions<TValue, TPresentation>;
         facet?: TableFilterFacetSpec<TRow, TContext, TKey>;
+        /**
+         * Labels the values a facet lists when `options` is not set, such as provider statuses stored
+         * as `Approved` or `Security compromised`. The facet still decides which values show, with their
+         * counts; a value it returns `undefined` for shows as stored. Tags and previews of a committed
+         * value read the same label.
+         *
+         * @example
+         * ```ts
+         * source: {
+         *   facet: true,
+         *   label: (value) => ({ Approved: 'Validé', Done: 'Terminé' })[String(value)],
+         * }
+         * ```
+         */
+        label?: {
+            bivarianceHack(value: TValue): TableTextValue | undefined;
+        }['bivarianceHack'];
         sort?: 'alpha' | 'count';
     };
     editor?: TableOptionFilterEditorConfig<TPresentation>;

package/dist/runtime/table/types/table-api.d.ts

@@ -87,6 +87,11 @@ export interface TableApi<TSchema = TableSchemaView> {
         totalRowCount: ComputedRef<number | null>;
         rawRows: ComputedRef<ExtractTableRow<TSchema>[]>;
         rawRowCount: ComputedRef<number | null>;
+        /**
+         * Every row that passes the filters and the search, sorted, before pagination. Client sources
+         * only; `undefined` for remote sources, which never hold the whole result.
+         */
+        filteredRows: ComputedRef<ExtractTableRow<TSchema>[] | undefined>;
         context: ComputedRef<ExtractTableContextData<TSchema>>;
         pageContext: ComputedRef<ExtractTablePageContextData<TSchema>>;
         requestContext: ReturnType<typeof useTableData>['requestContext'];

package/dist/runtime/table/utils/filter-persistence.d.ts

@@ -0,0 +1,16 @@
+import type { TableQueryStateFilterRule, TableUiFilterDefinition } from '../types/index.js';
+/** Storage key of one persisted filter, scoped by table key. */
+export declare function persistedFilterStorageKey(options: {
+    tableKey: string;
+    filterKey: string;
+}): string;
+/** Serializes a rule with the filter's URL codec, or returns `null` when it has nothing to keep. */
+export declare function serializePersistedFilterRule(options: {
+    definition: TableUiFilterDefinition;
+    rule: TableQueryStateFilterRule;
+}): string | null;
+/** Reads a stored rule back, dropping anything the filter no longer accepts. */
+export declare function parsePersistedFilterRule(options: {
+    definition: TableUiFilterDefinition;
+    raw: string | null;
+}): TableQueryStateFilterRule | null;

package/dist/runtime/table/utils/filter-persistence.js

@@ -0,0 +1,42 @@
+import { isObject, isString } from "../../shared/utils/predicate.js";
+import {
+  createTableFilterValueCodec,
+  normalizeFilterDefinition,
+  resolveFilterDefaultOperator,
+  resolveFilterSupportedOperators
+} from "./query-state.js";
+const STORAGE_PREFIX = "nuxt-ui-tools:table-filter";
+export function persistedFilterStorageKey(options) {
+  return `${STORAGE_PREFIX}:${options.tableKey}:${options.filterKey}`;
+}
+export function serializePersistedFilterRule(options) {
+  const normalized = normalizeFilterDefinition(options.definition);
+  const value = createTableFilterValueCodec(normalized).serialize(options.rule.value);
+  return value === null ? null : JSON.stringify({
+    operator: options.rule.operator ?? resolveFilterDefaultOperator(normalized),
+    value
+  });
+}
+export function parsePersistedFilterRule(options) {
+  if (!options.raw) {
+    return null;
+  }
+  const stored = parseStoredRule(options.raw);
+  if (!stored) {
+    return null;
+  }
+  const normalized = normalizeFilterDefinition(options.definition);
+  const operator = resolveFilterSupportedOperators(normalized).find(
+    (candidate) => candidate === stored.operator
+  );
+  const value = createTableFilterValueCodec(normalized).parse(stored.value);
+  return operator && value !== void 0 ? { key: options.definition.key, operator, value } : null;
+}
+function parseStoredRule(raw) {
+  try {
+    const stored = JSON.parse(raw);
+    return isObject(stored) && isString(stored.operator) && isString(stored.value) ? { operator: stored.operator, value: stored.value } : null;
+  } catch {
+    return null;
+  }
+}