nuxt-ui-tools 1.0.1 → 1.2.0

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

@@ -1,3 +1,4 @@
+import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
 import type { TableFilterOperator, TableQueryStateFilterRule, TableQueryStateFilterValue } from './query-state.js';
 import type { TableFacetExecutionResult, TableFacetRequestDescriptor, TableFacetsContext, TableQueryDefinition } from './source.js';
 import type { GenericObject, RenderableType, TableFieldPath, TableKnownFieldPath, TableTextValue } from './utils.js';
@@ -538,6 +539,41 @@ export interface TableFilterOptionQueryContext {
     cursor?: string | null;
 }
 export type TableFilterOptionQueryResult<TValue = TableFilterPrimitiveValue> = TableFilterOptionQueryResultForPresentation<TValue, TableOptionFilterPresentation>;
+/** Page requested from a remote option filter source. */
+export interface TableFilterRemoteOptionsRequest {
+    /** Current debounced search term. Empty when the editor lists unfiltered options. */
+    search: string;
+    /** Requested page: `index` (1-based) for page pagination, `cursor` for cursor pagination. */
+    page: RemoteOptionsPageRequest;
+}
+/** Selected values a remote option filter needs options for. */
+export interface TableFilterRemoteSelectedRequest<TValue = TableFilterPrimitiveValue> {
+    /** Committed filter values that the options loaded so far do not contain. */
+    values: readonly TValue[];
+}
+/**
+ * Remote option source loaded page by page, following the form engine's remote options:
+ * server-side search, page or cursor pagination loaded ahead of the scroll, and options for
+ * selected values the loaded pages do not contain (for example values restored from the URL).
+ */
+export interface TableFilterRemoteOptions<TValue = TableFilterPrimitiveValue, TPresentation extends TableOptionFilterPresentation = TableOptionFilterPresentation> {
+    /** Query definition of one page of options for the current search term. */
+    load: (request: TableFilterRemoteOptionsRequest) => TableQueryDefinition<RemoteOptionsResult<TableOptionEntryForPresentation<TValue, TPresentation>>>;
+    /**
+     * Query definition resolving the options of selected values the loaded pages do not contain, so
+     * tags and editors show their labels. Without it, such values show as their raw value.
+     */
+    resolveSelected?: {
+        bivarianceHack(request: TableFilterRemoteSelectedRequest<TValue>): TableQueryDefinition<readonly TableOptionEntryForPresentation<TValue, TPresentation>[]>;
+    }['bivarianceHack'];
+    /**
+     * Page size, and how far before the list end the next page loads. Defaults to
+     * `{ type: 'page', size: 25 }` with the next page requested three viewport heights ahead.
+     */
+    pagination?: RemoteOptionsPagination;
+    /** Search debounce (default 250 ms) and minimum term length (default 0). */
+    search?: RemoteOptionsSearch;
+}
 export type TableFilterFacetMode = boolean | 'exclude-self' | 'include-self';
 export interface TableFilterFacetQueryContext<TRow extends GenericObject = GenericObject, TContext extends GenericObject = GenericObject, TKey extends string = TableKnownFieldPath<TRow>> {
     table: Omit<TableFacetsContext<TRow, TContext, TKey>, 'facets'>;
@@ -596,7 +632,13 @@ export interface TableOptionFilterDefinition<TRow extends GenericObject = Generi
     kind: 'option';
     source?: {
         options?: readonly TableOptionEntryForPresentation<TValue, TPresentation>[];
+        /** Loads the whole option list in one query. For large lists, prefer `remote`. */
         query?: (context: TableFilterOptionQueryContext) => TableQueryDefinition<TableOptionEntryForPresentation<TValue, TPresentation>[] | TableFilterOptionQueryResultForPresentation<TValue, TPresentation>>;
+        /**
+         * Loads options page by page with server-side search, as the editor scrolls. Takes precedence
+         * over `options` and `query`.
+         */
+        remote?: TableFilterRemoteOptions<TValue, TPresentation>;
         facet?: TableFilterFacetSpec<TRow, TContext, TKey>;
         sort?: 'alpha' | 'count';
     };

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

@@ -1,10 +1,9 @@
-import type { InfiniteData, QueryFunction, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
+import type { InfiniteData, QueryFunction, QueryKey } from '@tanstack/vue-query';
+import type { QueryDefinition } from '../../shared/types/query.js';
 import type { TableResolvedFilterGroup } from './filters.js';
 import type { GenericObject, TableKnownFieldPath, TablePaginationState, TableSortKey, TableSortingRule, TableRowsFromSourceResult } from './utils.js';
-export type TableQueryDefinition<TData = unknown> = Omit<UseQueryOptions<TData>, 'queryFn'> & {
-    queryKey: QueryKey;
-    queryFn?: QueryFunction<TData, QueryKey, string | null>;
-};
+/** Table name of the shared `QueryDefinition`, kept for public type compatibility. */
+export type TableQueryDefinition<TData = unknown> = QueryDefinition<TData>;
 export interface TableInfiniteQueryDefinition<TData = unknown> {
     queryKey: QueryKey;
     queryFn: QueryFunction<TData, QueryKey, string | null>;
@@ -63,6 +62,11 @@ export interface TableFacetRequestDescriptor<TKey extends string = string> {
     search?: string;
     limit?: number;
     cursor?: string | null;
+    /**
+     * Values to count, and only these. Filters loading options page by page (`source.remote`) send
+     * the values of one loaded page, since no single request can know every value.
+     */
+    values?: readonly (string | number | boolean)[];
 }
 export interface TableFacetOptionResult<TValue = unknown> {
     value: TValue;

package/dist/runtime/table/utils/columns/menu.d.ts

@@ -36,4 +36,4 @@ export declare function getColumnHeaderIcon(options: {
         columnId: string;
     }) => 'left' | 'right' | null;
     canHide?: boolean;
-}): "i-lucide-arrow-up" | "i-lucide-arrow-down" | "i-lucide-chevrons-up-down" | "i-lucide-grip-vertical";
+}): "i-lucide-chevrons-up-down" | "i-lucide-arrow-up" | "i-lucide-arrow-down" | "i-lucide-grip-vertical";

package/dist/runtime/table/utils/columns/state.d.ts

@@ -186,4 +186,4 @@ export declare function createResetColumnState(options: {
 export declare function getPinnedState(options: {
     currentState: TableColumnState;
     columnId: string;
-}): "right" | "left" | null;
+}): "left" | "right" | null;

package/dist/runtime/table/utils/data-list-ui.d.ts

@@ -73,7 +73,7 @@ export declare function resolveDataListControlGeometry(size: DataListControlSize
     toolbarGap: string;
 };
 /** Downsizes controls nested inside another control, such as preview badges in filter tags. */
-export declare function resolveDataListNestedControlSize(size: DataListControlSize): "sm" | "md" | "lg" | "xs";
+export declare function resolveDataListNestedControlSize(size: DataListControlSize): "xs" | "sm" | "md" | "lg";
 /** Maps the resolved DataList size to table header, row, cell, and skeleton geometry. */
 export declare function resolveDataListTableSize(size: DataListControlSize): {
     cell: string;

package/dist/runtime/table/utils/filters/options.d.ts

@@ -10,6 +10,8 @@ export declare function resolveFilterOptionEntries(options: {
         count: number;
     }[];
     missingCountFallback?: number;
+    /** `options` is the complete answer (remote pages): an empty list stays empty instead of listing facet values. */
+    authoritative?: boolean;
 }): TableResolvedFilterOptionEntry<import("../../types/index.js").TableFilterPrimitiveValue>[] | {
     children: never[];
     count: number | undefined;

package/dist/runtime/table/utils/filters/options.js

@@ -21,7 +21,7 @@ export function resolveFilterOptionEntries(options) {
     return [];
   }
   const configuredOptions = options.options ?? options.definition.source?.options ?? [];
-  const sourceOptions = configuredOptions.length ? configuredOptions : (options.facetCounts ?? []).map((entry) => ({
+  const sourceOptions = configuredOptions.length || options.authoritative ? configuredOptions : (options.facetCounts ?? []).map((entry) => ({
     count: entry.count,
     label: String(entry.value),
     value: entry.value

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

@@ -40,7 +40,11 @@ export function prefetchTable(params) {
       route: params.route,
       schema
     });
-    return resolveTableQueries({ request, schema });
+    return resolveTableQueries({
+      request,
+      rules: resolveFilterState(params.route, schema).ui,
+      schema
+    });
   }).stage((stageContext) => {
     const rows = resolvePrefetchedRows(stageContext.source);
     const context = resolveContextData(schema, stageContext);
@@ -93,6 +97,13 @@ function resolveTableQueries(options) {
     ]);
   }
   for (const definition of definitions) {
+    const selectedOptions = resolveRemoteSelectedQuery(definition, options.rules);
+    if (selectedOptions) {
+      entries.push([
+        `filter-selected-options:${definition.key}`,
+        withQueryDefaults(selectedOptions, QUERY_DEFAULTS.staleTime.filterOptions)
+      ]);
+    }
     if (definition.kind === "option" && isOptionQueryResolver(definition.source?.query)) {
       entries.push([
         `filter-options:${definition.key}`,
@@ -130,6 +141,15 @@ function resolveTableQueries(options) {
   }
   return Object.fromEntries(entries);
 }
+function resolveRemoteSelectedQuery(definition, rules) {
+  const resolve = definition.kind === "option" ? definition.source?.remote?.resolveSelected : void 0;
+  if (!resolve) return;
+  const rule = rules.find((entry) => entry.key === definition.key);
+  const values = (Array.isArray(rule?.value) ? rule.value : isNullish(rule?.value) ? [] : [rule.value]).filter(
+    (value) => isString(value) || isNumber(value) || isBoolean(value)
+  );
+  return values.length ? resolve({ values }) : void 0;
+}
 function resolveSourcePrefetchQuery(options) {
   const definition = options.schema.source.mode === "remote" ? options.schema.source.query(
     toTableRemoteSourceRequest(options.request),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "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",
@@ -20,6 +20,9 @@
       ".": [
         "./dist/types.d.mts"
       ],
+      "dashboard": [
+        "./dist/runtime/dashboard/index.d.ts"
+      ],
       "form": [
         "./dist/runtime/form/index.d.ts"
       ],
@@ -41,6 +44,14 @@
     }
   },
   "imports": {
+    "#ui-tools/dashboard": {
+      "types": "./dist/runtime/dashboard/index.d.ts",
+      "default": "./dist/runtime/dashboard/index.js"
+    },
+    "#ui-tools/dashboard/*": {
+      "types": "./dist/runtime/dashboard/*.d.ts",
+      "default": "./dist/runtime/dashboard/*.js"
+    },
     "#ui-tools/form": {
       "types": "./dist/runtime/form/index.d.ts",
       "default": "./dist/runtime/form/index.js"
@@ -95,6 +106,10 @@
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
     },
+    "./dashboard": {
+      "types": "./dist/runtime/dashboard/index.d.ts",
+      "import": "./dist/runtime/dashboard/index.js"
+    },
     "./form": {
       "types": "./dist/runtime/form/index.d.ts",
       "import": "./dist/runtime/form/index.js"
@@ -169,6 +184,8 @@
     "@nuxt/ui": "^4.10.0",
     "@tiptap/y-tiptap": "3.0.9",
     "@types/node": "25.4.0",
+    "@unovis/ts": "1.7.0",
+    "@unovis/vue": "1.7.0",
     "@vitejs/plugin-vue": "^6.0.8",
     "@vitejs/plugin-vue-jsx": "^5.1.6",
     "@vue/test-utils": "2.5.1",
@@ -186,6 +203,8 @@
   "peerDependencies": {
     "@nuxt/ui": ">=4.10.0",
     "@tanstack/vue-query": ">=5.101.4",
+    "@unovis/ts": ">=1.6.0",
+    "@unovis/vue": ">=1.6.0",
     "nuxt": ">=4.5.2",
     "tailwindcss": ">=4.3.3",
     "typescript": ">=5.9.0",
@@ -193,6 +212,14 @@
     "vue-draggable-plus": ">=0.6.1",
     "vue-router": ">=4.6.4"
   },
+  "peerDependenciesMeta": {
+    "@unovis/ts": {
+      "optional": true
+    },
+    "@unovis/vue": {
+      "optional": true
+    }
+  },
   "overrides": {
     "@tiptap/y-tiptap": "3.0.9"
   }