nuxt-ui-tools 1.26.0 → 1.27.1

package/dist/module.json

@@ -5,7 +5,7 @@
   "configKey": "nuxtUiTools",
   "docs": "https://ui.nuxt.com/docs/getting-started/installation/nuxt",
   "name": "nuxt-ui-tools",
-  "version": "1.26.0",
+  "version": "1.27.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "unknown"

package/dist/runtime/table/builders/index.d.ts

@@ -1,7 +1,7 @@
-import type { GenericObject, TableColumnBuilder, TableColumnCollection, TableFilterBuilder, TableSortKey, TableUiFilterCollection, TableUiFilterDefinition } from '../types/index.js';
+import type { GenericObject, TableColumnBuilder, TableColumnCollection, TableFilterBuilder, TableSortKey, TableUiFilterCollection, TableUiFilterCollectionItem } from '../types/index.js';
 export { type TableSortKey } from '../types/index.js';
 export declare function createTableColumnBuilder<TRow extends GenericObject, TContext extends GenericObject, TPageContext extends GenericObject, TSortKey extends string = TableSortKey<TRow>, TData = unknown>(): TableColumnBuilder<TRow, TContext, TPageContext, TSortKey, TData>;
 export declare function createTableFilterBuilder<TRow extends GenericObject, TContext extends GenericObject = GenericObject>(): TableFilterBuilder<TRow, TContext>;
 export declare function resolveCollection<TBuilder, TResult>(collection: TResult | ((builder: TBuilder) => TResult) | undefined, builder: TBuilder): TResult | undefined;
 export declare function resolveColumns<TRow extends GenericObject, TContext extends GenericObject, TPageContext extends GenericObject, TSortKey extends string = TableSortKey<TRow>, TData = unknown, TColumns extends TableColumnCollection<TRow, TContext, TPageContext, string, TSortKey, TData> | undefined = TableColumnCollection<TRow, TContext, TPageContext, string, TSortKey, TData> | undefined>(columns: TColumns): TColumns extends (...args: never[]) => infer TResult ? TResult : TColumns;
-export declare function resolveUiFilters<TRow extends GenericObject, TContext extends GenericObject, TKey extends string>(filters: TableUiFilterCollection<TRow, TContext, TKey> | undefined): TableUiFilterDefinition<TRow, TContext, TKey>[] | undefined;
+export declare function resolveUiFilters<TRow extends GenericObject, TContext extends GenericObject, TKey extends string>(filters: TableUiFilterCollection<TRow, TContext, TKey> | undefined): TableUiFilterCollectionItem<TRow, TContext, TKey>[] | undefined;

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?: {
@@ -697,14 +708,34 @@ export type TableOptionFilterOptions<TRow extends GenericObject = GenericObject,
 export type TableBooleanFilterOptions<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = Omit<TableBooleanFilterDefinition<TRow, TContext, TKey>, 'key' | 'kind'>;
 export type TableNumberFilterOptions<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = Omit<TableNumberFilterDefinition<TRow, TContext, TKey>, 'key' | 'kind'>;
 export type TableDateFilterOptions<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = Omit<TableDateFilterDefinition<TRow, TContext, TKey>, 'key' | 'kind'>;
+/**
+ * Keys a filter may use. A row field path filters rows; any other key names a query parameter of
+ * the source and requires `behavior.applyTo: 'query'`.
+ */
+export type TableFilterKey<TRow extends GenericObject = GenericObject> = TableKnownFieldPath<TRow> | (string & {});
+/** What a filter key adds to its options: nothing for a row field, `applyTo: 'query'` otherwise. */
+export type TableFilterKeyScope<TRow extends GenericObject, TKey extends string> = TKey extends TableKnownFieldPath<TRow> ? unknown : {
+    behavior: {
+        applyTo: 'query';
+    };
+};
 export interface TableFilterBuilder<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject> {
-    text<TKey extends TableKnownFieldPath<TRow>>(key: TKey, options: TableTextFilterOptions<TRow, TContext, TKey>): TableTextFilterDefinition<TRow, TContext, TKey>;
-    option<TKey extends TableKnownFieldPath<TRow>, TValue extends TableFilterPrimitiveValue, TPresentation extends TableOptionFilterPresentation = TableOptionFilterPresentation>(key: TKey, options: TableOptionFilterOptions<TRow, TContext, TKey, TValue, TPresentation>): TableOptionFilterDefinition<TRow, TContext, TKey, TValue, TPresentation>;
-    boolean<TKey extends TableKnownFieldPath<TRow>>(key: TKey, options: TableBooleanFilterOptions<TRow, TContext, TKey>): TableBooleanFilterDefinition<TRow, TContext, TKey>;
-    number<TKey extends TableKnownFieldPath<TRow>>(key: TKey, options: TableNumberFilterOptions<TRow, TContext, TKey>): TableNumberFilterDefinition<TRow, TContext, TKey>;
-    date<TKey extends TableKnownFieldPath<TRow>>(key: TKey, options: TableDateFilterOptions<TRow, TContext, TKey>): TableDateFilterDefinition<TRow, TContext, TKey>;
+    text<TKey extends TableFilterKey<TRow>>(key: TKey, options: TableTextFilterOptions<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>): TableTextFilterDefinition<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>;
+    option<TKey extends TableFilterKey<TRow>, TValue extends TableFilterPrimitiveValue, TPresentation extends TableOptionFilterPresentation = TableOptionFilterPresentation>(key: TKey, options: TableOptionFilterOptions<TRow, TContext, TKey, TValue, TPresentation> & TableFilterKeyScope<TRow, TKey>): TableOptionFilterDefinition<TRow, TContext, TKey, TValue, TPresentation> & TableFilterKeyScope<TRow, TKey>;
+    boolean<TKey extends TableFilterKey<TRow>>(key: TKey, options: TableBooleanFilterOptions<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>): TableBooleanFilterDefinition<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>;
+    number<TKey extends TableFilterKey<TRow>>(key: TKey, options: TableNumberFilterOptions<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>): TableNumberFilterDefinition<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>;
+    date<TKey extends TableFilterKey<TRow>>(key: TKey, options: TableDateFilterOptions<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>): TableDateFilterDefinition<TRow, TContext, TKey> & TableFilterKeyScope<TRow, TKey>;
 }
-export type TableUiFilterCollection<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = TableUiFilterDefinition<TRow, TContext, TKey>[] | ((filter: TableFilterBuilder<TRow, TContext>) => TableUiFilterDefinition<TRow, TContext, TKey>[]);
+/**
+ * One filter of a table: a row filter keyed by a row field, or a query filter
+ * (`behavior.applyTo: 'query'`) keyed by any query parameter.
+ */
+export type TableUiFilterCollectionItem<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = TableUiFilterDefinition<TRow, TContext, TKey> | (TableUiFilterDefinition<TRow, TContext, string> & {
+    behavior: {
+        applyTo: 'query';
+    };
+});
+export type TableUiFilterCollection<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> = TableUiFilterCollectionItem<TRow, TContext, TKey>[] | ((filter: TableFilterBuilder<TRow, TContext>) => TableUiFilterCollectionItem<TRow, TContext, TKey>[]);
 export interface TableFiltersSchema<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> {
     search?: TableSearchFilter<TRow>;
     static?: TableStaticFilterNode<TRow, TContext, TKey>[];

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

package/dist/runtime/table/utils/index.d.ts

@@ -4,6 +4,7 @@ export * from './columns/index.js';
 export * from './cursor-query.js';
 export * from './data-list-ui.js';
 export * from './facets.js';
+export * from './filter-persistence.js';
 export * from './filters/index.js';
 export * from './pagination.js';
 export * from './prefetch.js';

package/dist/runtime/table/utils/index.js

@@ -4,6 +4,7 @@ export * from "./columns/index.js";
 export * from "./cursor-query.js";
 export * from "./data-list-ui.js";
 export * from "./facets.js";
+export * from "./filter-persistence.js";
 export * from "./filters/index.js";
 export * from "./pagination.js";
 export * from "./prefetch.js";

package/dist/runtime/table/utils/resolved-filters.d.ts

@@ -5,3 +5,11 @@ export declare function createResolvedFilterState<TRow extends GenericObject = G
     staticFilters?: TableStaticFilterNode<TRow, TContext, TKey>[];
     context?: TContext;
 }): TableResolvedFilterGroup<string>;
+/**
+ * Drops the rules of filters marked `behavior.applyTo: 'query'`, which feed the source query but
+ * never narrow client rows.
+ */
+export declare function withoutQueryFilterRules(options: {
+    definitions: TableUiFilterDefinition[];
+    filters: TableFilterState;
+}): TableFilterState;

package/dist/runtime/table/utils/resolved-filters.js

@@ -67,3 +67,9 @@ function normalizeResolvedFilterNode(node) {
 function isResolvedFilterGroup(value) {
   return !!value && isObject(value) && "type" in value && value.type === "group" && "children" in value && isArray(value.children);
 }
+export function withoutQueryFilterRules(options) {
+  const queryKeys = new Set(
+    options.definitions.filter((definition) => definition.behavior?.applyTo === "query").map((definition) => definition.key)
+  );
+  return queryKeys.size === 0 ? options.filters : { ...options.filters, ui: options.filters.ui.filter((rule) => !queryKeys.has(rule.key)) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.26.0",
+  "version": "1.27.1",
   "description": "Nuxt module and runtime toolkit for UI-heavy Nuxt applications",
   "homepage": "https://github.com/ChronicStone/nuxt-ui-tools#readme",
   "bugs": "https://github.com/ChronicStone/nuxt-ui-tools/issues",