nuxt-ui-tools 1.1.0 → 1.3.0

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

@@ -5,6 +5,7 @@ export type * from './data-list';
 export type * from './filters';
 export type * from './layout';
 export type * from './query-state';
+export type * from './remote-options';
 export type * from './schema';
 export type * from './source';
 export type * from './state';

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

@@ -0,0 +1,64 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { QueryFnDefinition } from '../../shared/types/query.js';
+import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
+import type { TableResolvedFilterGroup } from './filters.js';
+import type { TableCursorPageResult, TableOffsetPageResult, TableRemoteSourceRequest, TableSourceExecutionResult, TableSourceQueryResult, TableSourceRow } from './source.js';
+import type { GenericObject, TableKnownFieldPath, TableSortingRule, TableSortKey } from './utils.js';
+/** Response of an endpoint speaking the table request protocol. */
+export type RemoteTableResult<TRow extends GenericObject> = TableOffsetPageResult<TRow, string> | TableCursorPageResult<TRow, string> | TableSourceExecutionResult<TRow, string>;
+/** Option built from one row: a value and a label, plus any extra option fields. */
+export interface RemoteTableOption {
+    value: string | number;
+    label: string;
+}
+/** A TanStack query definition: its key, and a `queryFn` or the options that carry one. */
+export interface RemoteTableQueryDefinition {
+    queryKey: QueryKey;
+}
+/**
+ * Query definition of one table request, typically the endpoint a remote table already uses:
+ * `(request) => $api.accounts.query.queryOptions({ body: request })`. The row type is read from
+ * its result, as `tableSource` does.
+ */
+export type RemoteTableQuery<TQuery extends RemoteTableQueryDefinition = RemoteTableQueryDefinition> = (request: TableRemoteSourceRequest) => TQuery;
+/** Row type of the table response a `RemoteTableQuery` resolves to. */
+export type RemoteTableQueryRow<TQuery> = TableSourceRow<TableSourceQueryResult<TQuery>>;
+export interface RemoteTableOptionsConfig<TRow extends GenericObject, TOption extends RemoteTableOption> {
+    /** Option of one row. A method, so the typed callback fits the builder's erased signature. */
+    option(row: TRow): TOption;
+    /**
+     * Fields the search term looks in, or those fields with the debounce (default 250 ms) and
+     * minimum term length (default 0).
+     */
+    search?: readonly TableKnownFieldPath<TRow>[] | ({
+        fields: readonly TableKnownFieldPath<TRow>[];
+    } & RemoteOptionsSearch);
+    /** Order of the options: a field, ascending, or explicit sorting rules. */
+    sort?: TableSortKey<TRow> | readonly TableSortingRule<TableSortKey<TRow>>[];
+    /**
+     * Field holding the option value, matched with `isAnyOf` to resolve the labels of selected
+     * values the loaded pages do not contain. Defaults to `'id'`.
+     */
+    valueKey?: TableKnownFieldPath<TRow> | 'id';
+    /** Filters applied to every request, e.g. active accounts only. */
+    filters?: readonly TableResolvedFilterGroup<TableKnownFieldPath<TRow> | string>[];
+    /** Page type and size. Must match what the endpoint pages by. Defaults to cursor pages of 25. */
+    pagination?: RemoteOptionsPagination;
+}
+/**
+ * Remote option source built by `remoteTableOptions()`. It fits dashboard `p.remote()`, table
+ * option filters (`source.remote`), and form remote options (`source: options.load`).
+ */
+export interface RemoteTableOptions<TOption> {
+    /** Query definition of one page of options for a search term. */
+    load: (request: {
+        search: string;
+        page: RemoteOptionsPageRequest;
+    }) => QueryFnDefinition<RemoteOptionsResult<TOption>>;
+    /** Query definition of the options of selected values. */
+    resolveSelected: (request: {
+        values: readonly (string | number | boolean)[];
+    }) => QueryFnDefinition<readonly TOption[]>;
+    pagination: RemoteOptionsPagination;
+    search?: RemoteOptionsSearch;
+}

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

@@ -1,9 +1,18 @@
-import type { InfiniteData, QueryFunction, QueryKey } from '@tanstack/vue-query';
+import type { InfiniteData, QueryFunction, QueryKey, UseQueryOptions } 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';
 /** Table name of the shared `QueryDefinition`, kept for public type compatibility. */
 export type TableQueryDefinition<TData = unknown> = QueryDefinition<TData>;
+/**
+ * Result of a query definition: what its `queryFn` resolves to, or the data type of TanStack
+ * options whose `queryFn` may be a ref or `skipToken` (Tuyau's `queryOptions()`).
+ */
+export type TableSourceQueryResult<TQuery> = TQuery extends {
+    queryFn: (...args: never[]) => infer TResult;
+} ? Awaited<TResult> : TQuery extends UseQueryOptions<infer _TQueryFnData, infer _TError, infer TResult, infer _TQueryData, infer _TQueryKey> ? Awaited<TResult> : never;
+/** Row of a table query result: an array of rows, or a page (`{ rows }`). */
+export type TableSourceRow<TResult> = TableRowsFromSourceResult<Awaited<TResult>> extends infer TRow ? TRow extends GenericObject ? TRow : GenericObject : GenericObject;
 export interface TableInfiniteQueryDefinition<TData = unknown> {
     queryKey: QueryKey;
     queryFn: QueryFunction<TData, QueryKey, string | null>;
@@ -62,6 +71,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/builders/table-source.d.ts

@@ -1,6 +1,5 @@
-import type { QueryKey, UseQueryOptions } from '@tanstack/vue-query';
-import type { GenericObject, TableClientSource, TableCursorPageResult, TableGlobalFacetDescriptor, TableOffsetPageResult, TablePaginationState, TableRemoteSource, TableRemoteSourceRequest, TableResolvedFilterGroup, TableRowsFromSourceResult, TableSourceExecutionResult, TableSortingRule } from '../../types/index.js';
-type TableSourceRow<TResult> = TableRowsFromSourceResult<Awaited<TResult>> extends infer TRow ? TRow extends GenericObject ? TRow : GenericObject : GenericObject;
+import type { QueryKey } from '@tanstack/vue-query';
+import type { GenericObject, TableClientSource, TableCursorPageResult, TableGlobalFacetDescriptor, TableOffsetPageResult, TablePaginationState, TableRemoteSource, TableRemoteSourceRequest, TableResolvedFilterGroup, TableSourceExecutionResult, TableSourceQueryResult, TableSourceRow, TableSortingRule } from '../../types/index.js';
 type ClientTableSourceResult<TResult> = TResult extends readonly GenericObject[] ? TableSourceRow<TResult>[] : TableSourceExecutionResult<TableSourceRow<TResult>>;
 type RemoteTableSourceResult<TResult> = TResult extends {
     pageInfo: {
@@ -25,9 +24,6 @@ interface TableSourceInferenceContext {
 interface TableSourceQueryDefinition {
     queryKey: QueryKey;
 }
-type TableSourceQueryResult<TQuery> = TQuery extends {
-    queryFn: (...args: never[]) => infer TResult;
-} ? Awaited<TResult> : TQuery extends UseQueryOptions<infer _TQueryFnData, infer _TError, infer TResult, infer _TQueryData, infer _TQueryKey> ? Awaited<TResult> : never;
 interface ClientTableSourceInput<TQuery extends TableSourceQueryDefinition> {
     mode?: 'client';
     query: (context: TableSourceInferenceContext) => TQuery;

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/index.d.ts

@@ -8,6 +8,7 @@ export * from './filters/index.js';
 export * from './pagination.js';
 export * from './prefetch.js';
 export * from './query-state.js';
+export * from './remote-table-options.js';
 export * from './resolved-filters.js';
 export * from './rows.js';
 export * from './schema.js';

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

@@ -8,6 +8,7 @@ export * from "./filters/index.js";
 export * from "./pagination.js";
 export * from "./prefetch.js";
 export * from "./query-state.js";
+export * from "./remote-table-options.js";
 export * from "./resolved-filters.js";
 export * from "./rows.js";
 export * from "./schema.js";

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/dist/runtime/table/utils/remote-table-options.d.ts

@@ -0,0 +1,26 @@
+import type { RemoteTableOption, RemoteTableOptions, RemoteTableOptionsConfig, RemoteTableQuery, RemoteTableQueryDefinition, RemoteTableQueryRow } from '../types/index.js';
+/**
+ * Turns an endpoint that speaks the table request protocol into a remote option source: searchable,
+ * paged, with labels of selected values resolved by an `isAnyOf` filter on `valueKey`. Use it for
+ * dashboard filters (`p.remote(...)`), table option filters (`source.remote`), and form remote
+ * options (`source: options.load`).
+ *
+ * Each page is its own query, keyed after the endpoint's key, so pages are cached and shared by
+ * every picker using the same source.
+ *
+ * The query comes first: the row type is read from its result, so `option` and `search` are typed
+ * whatever order the options are written in.
+ *
+ * @example
+ * ```ts
+ * const accounts = remoteTableOptions(
+ *   (request) => $api.accounts.query.queryOptions({ body: request }),
+ *   {
+ *     search: ['name'],
+ *     sort: 'name',
+ *     option: (account) => ({ label: account.name, value: account.id }),
+ *   },
+ * )
+ * ```
+ */
+export declare function remoteTableOptions<TQuery extends RemoteTableQueryDefinition, const TOption extends RemoteTableOption>(query: RemoteTableQuery<TQuery>, config: RemoteTableOptionsConfig<RemoteTableQueryRow<TQuery>, TOption>): RemoteTableOptions<TOption>;

package/dist/runtime/table/utils/remote-table-options.js

@@ -0,0 +1,88 @@
+import { isArray, isFunction, isObject } from "../../shared/utils/predicate.js";
+const DEFAULT_PAGINATION = { size: 25, type: "cursor" };
+export function remoteTableOptions(query, config) {
+  const pagination = config.pagination ?? DEFAULT_PAGINATION;
+  const { fields, search } = resolveSearch(config.search);
+  const sorting = resolveSorting(config.sort);
+  function request(params) {
+    const { page } = params;
+    return {
+      filters: [...config.filters ?? [], ...params.filters ?? []],
+      pagination: pagination.type === "cursor" ? { count: "none", cursor: page.cursor, mode: "cursor", pageSize: page.size } : { count: "exact", mode: "offset", pageIndex: page.index - 1, pageSize: page.size },
+      search: { fields: [...fields], value: params.search },
+      sorting: params.filters ? [] : [...sorting]
+    };
+  }
+  return {
+    load: ({ page, search: term }) => mapQuery(query(request({ page, search: term })), (result) => ({
+      ...resolvePage(result),
+      options: result.rows.map(config.option)
+    })),
+    pagination,
+    resolveSelected: ({ values }) => mapQuery(
+      query(
+        request({
+          filters: [
+            {
+              children: [
+                {
+                  key: config.valueKey ?? "id",
+                  operator: "isAnyOf",
+                  type: "condition",
+                  value: [...values]
+                }
+              ],
+              combinator: "and",
+              type: "group"
+            }
+          ],
+          page: { cursor: null, index: 1, size: Math.max(1, values.length) },
+          search: ""
+        })
+      ),
+      (result) => result.rows.map(config.option)
+    ),
+    search
+  };
+}
+function mapQuery(definition, map) {
+  const { queryKey } = definition;
+  const queryFn = "queryFn" in definition ? definition.queryFn : void 0;
+  return {
+    async queryFn(context) {
+      if (!isQueryFn(queryFn))
+        throw new Error("[remoteTableOptions] `query` must return a query with a queryFn.");
+      const result = await queryFn({ ...context, queryKey });
+      if (!isTableResult(result))
+        throw new Error("[remoteTableOptions] the query must resolve to a table response (`rows`).");
+      return map(result);
+    },
+    queryKey: [...queryKey, "remote-options"]
+  };
+}
+function isQueryFn(value) {
+  return isFunction(value);
+}
+function isTableResult(value) {
+  return isObject(value) && isArray(value.rows);
+}
+function resolvePage(result) {
+  if (!("pageInfo" in result)) return { hasMore: false };
+  return result.pageInfo.mode === "cursor" ? { nextCursor: result.pageInfo.nextCursor } : { hasMore: result.pageInfo.hasNextPage };
+}
+function resolveSearch(search) {
+  if (!search) return { fields: [], search: void 0 };
+  if (isFieldList(search)) return { fields: search, search: void 0 };
+  const { fields, ...options } = search;
+  return { fields, search: options };
+}
+function isFieldList(value) {
+  return Array.isArray(value);
+}
+function resolveSorting(sort) {
+  if (sort === void 0) return [];
+  return isSortingRules(sort) ? sort : [{ dir: "asc", key: sort }];
+}
+function isSortingRules(sort) {
+  return Array.isArray(sort);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-ui-tools",
-  "version": "1.1.0",
+  "version": "1.3.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",
@@ -182,18 +182,21 @@
     "@nuxt/module-builder": "^1.0.3",
     "@nuxt/schema": "^4.5.2",
     "@nuxt/ui": "^4.10.0",
+    "@tailwindcss/vite": "4.3.3",
     "@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",
+    "@vitest/browser-playwright": "4.1.11",
     "@vue/test-utils": "2.5.1",
     "changelogen": "^0.6.2",
     "happy-dom": "20.14.5",
     "nuxt": "^4.5.2",
     "oxfmt": "0.64.0",
     "oxlint": "^1.82.0",
+    "playwright": "1.63.0",
     "typescript": "~5.9.3",
     "ultracite": "7.12.0",
     "vitest": "^4.1.11",

package/dist/runtime/dashboard/composables/use-dashboard-param-scope.d.ts

@@ -1,30 +0,0 @@
-import type { QueryKey } from '@tanstack/vue-query';
-import type { DashboardOptionsHandle, DashboardParamMap } from '../types/index.js';
-/**
- * What one param scope exposes. Declared rather than inferred: the inferred type would carry Vue's
- * `Raw<…>` marker, which declaration files cannot name.
- */
-export interface DashboardParamScope {
-    keys: readonly string[];
-    /** Option handles of option-backed params, by param key. */
-    options: Readonly<Record<string, DashboardOptionsHandle>>;
-    /** URL segments of this scope's params, before the scope prefix. */
-    urlKeys: readonly string[];
-    /** Writable facade: one getter / setter per param. */
-    values: object;
-}
-/**
- * Owns the params of one scope (dashboard root, a view, or a query's widget params): exactly one
- * `useQueryStates` instance, a writable values facade, and the option handles of option-backed
- * params. Scopes without params allocate nothing.
- */
-export declare function useDashboardParamScope(params: {
-    definitions: DashboardParamMap;
-    prefix: string;
-    queryKey: QueryKey;
-}): DashboardParamScope;
-/**
- * Exposes several scopes' values through one object, e.g. shared params plus a view's own params
- * inside the view's query factories. Reads and writes go straight to the owning scope.
- */
-export declare function mergeDashboardParamValues(scopes: readonly DashboardParamScope[]): object;

package/dist/runtime/dashboard/composables/use-dashboard-param-scope.js

@@ -1,71 +0,0 @@
-import { markRaw } from "vue";
-import { useQueryStates } from "../../query-state/index.js";
-import { hasProperty } from "../../shared/utils/predicate.js";
-import { useDashboardOptions } from "./use-dashboard-options.js";
-const emptyFacade = markRaw({});
-const noUrlKeys = [];
-export function useDashboardParamScope(params) {
-  const entries = Object.entries(params.definitions).flatMap(
-    ([key, definition]) => isRuntimeParam(definition) ? [[key, definition]] : []
-  );
-  if (entries.length === 0)
-    return { keys: [], options: emptyFacade, urlKeys: noUrlKeys, values: emptyFacade };
-  const schema = {};
-  for (const [key, definition] of entries) {
-    schema[key] = {
-      codec: definition.codec,
-      defaultValue: definition.defaultValue,
-      historyMode: definition.historyMode,
-      omitDefault: definition.omitDefault,
-      urlKey: definition.urlKey
-    };
-  }
-  const state = useQueryStates({ historyMode: "replace", prefix: params.prefix, schema });
-  function read(key) {
-    const current = state.value;
-    return current[key];
-  }
-  function write(key, value) {
-    state.value = { ...state.value, [key]: value ?? params.definitions[key]?.defaultValue };
-  }
-  const values = {};
-  for (const [key] of entries) {
-    Object.defineProperty(values, key, {
-      enumerable: true,
-      get: () => read(key),
-      set: (value) => write(key, value)
-    });
-  }
-  const options = {};
-  for (const [key, definition] of entries) {
-    if (!definition.items && !definition.remote) continue;
-    options[key] = useDashboardOptions({
-      definition,
-      queryKey: [...params.queryKey, key],
-      value: () => read(key)
-    });
-  }
-  return {
-    keys: entries.map(([key]) => key),
-    options: markRaw(options),
-    /** URL segments of this scope's params, before the scope prefix. */
-    urlKeys: entries.map(([key, definition]) => definition.urlKey ?? key),
-    values: markRaw(values)
-  };
-}
-export function mergeDashboardParamValues(scopes) {
-  const merged = {};
-  for (const scope of scopes) {
-    for (const key of scope.keys) {
-      Object.defineProperty(merged, key, {
-        enumerable: true,
-        get: () => Reflect.get(scope.values, key),
-        set: (value) => Reflect.set(scope.values, key, value)
-      });
-    }
-  }
-  return markRaw(merged);
-}
-function isRuntimeParam(definition) {
-  return hasProperty(definition, "codec");
-}

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

@@ -1,46 +0,0 @@
-import type { DashboardOption, DashboardOptionParamKeys, DashboardOptionValue } from './params.js';
-/**
- * Props ready to spread onto a Nuxt UI `USelectMenu`:
- * `<USelectMenu v-model="dashboard.params.account" v-bind="dashboard.options.account.menu" />`.
- */
-export interface DashboardOptionsMenuBindings<TValue extends DashboardOptionValue = DashboardOptionValue> {
-    items: DashboardOption<TValue>[];
-    valueKey: 'value';
-    labelKey: 'label';
-    loading?: boolean;
-    searchTerm?: string;
-    ignoreFilter?: boolean;
-    'onUpdate:searchTerm'?: (value: string) => void;
-    'onUpdate:open'?: (value: boolean) => void;
-}
-/**
- * Option state of an option-backed param (`p.enum`, `p.options`, `p.remote`).
- *
- * Remote handles load nothing until `open` becomes `true` (or `search` is set), then page through
- * the source; selected values restored from the URL are hydrated through `resolveSelected`.
- */
-export interface DashboardOptionsHandle<TValue extends DashboardOptionValue = DashboardOptionValue> {
-    /** Loaded options merged with the hydrated selected options. */
-    readonly items: readonly DashboardOption<TValue>[];
-    /** Options matching the current param value, in value order. */
-    readonly selected: readonly DashboardOption<TValue>[];
-    readonly loading: boolean;
-    readonly loadingMore: boolean;
-    readonly hasMore: boolean;
-    readonly error: unknown;
-    /** Search term. Writable; remote sources debounce it before loading. */
-    search: string;
-    /** Picker open state. Writable; opening a remote picker starts loading its first page. */
-    open: boolean;
-    loadMore(): void;
-    refresh(): Promise<void>;
-    readonly menu: DashboardOptionsMenuBindings<TValue>;
-}
-/** Option value type of a param: its value, or its element type for `multiple` params. */
-type DashboardParamOptionValue<TParam> = TParam extends {
-    readonly defaultValue: infer TValue;
-} ? Extract<NonNullable<TValue> extends readonly (infer TItem)[] ? TItem : NonNullable<TValue>, DashboardOptionValue> : never;
-export type DashboardOptionsHandles<TParams> = {
-    readonly [K in DashboardOptionParamKeys<TParams>]: DashboardOptionsHandle<DashboardParamOptionValue<TParams[K]>>;
-};
-export {};

package/dist/runtime/dashboard/types/params.d.ts

@@ -1,115 +0,0 @@
-import type { QueryKey } from '@tanstack/vue-query';
-import type { HistoryMode, QueryCodec, StaticQueryStateOptions } from '../../query-state/index.js';
-import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
-import type { dashboardParamBuilder } from '../utils/builders/dashboard-params.js';
-export type DashboardParamKind = 'string' | 'number' | 'boolean' | 'date' | 'dateRange' | 'enum' | 'options' | 'remote' | 'comparison' | 'custom';
-/**
- * Period a dashboard compares against: the one right before the current range (`previous`), the
- * same dates a year earlier (`year`), or no comparison (`none`).
- */
-export type DashboardComparison = 'previous' | 'year' | 'none';
-/** Primitive value an option-backed param can hold. */
-export type DashboardOptionValue = string | number;
-/**
- * Option item shape. It matches Nuxt UI `USelect` / `USelectMenu` items, so option handles can be
- * bound to those components directly.
- */
-export interface DashboardOption<TValue extends DashboardOptionValue = DashboardOptionValue> {
-    value: TValue;
-    label: string;
-    description?: string;
-    icon?: string;
-    avatar?: {
-        src?: string;
-        alt?: string;
-        text?: string;
-    };
-    disabled?: boolean;
-}
-export interface DashboardDateRange {
-    start: Date;
-    end: Date;
-}
-/** Options shared by every `p.*` param builder. */
-export interface DashboardParamOptions<TDefault> {
-    /**
-     * Value used when the URL key is absent or cannot be parsed.
-     * A non-`undefined` default narrows the param type: `p.string()` is `string | undefined`,
-     * `p.string({ defaultValue: '' })` is `string`. Values equal to the default never reach the URL.
-     */
-    defaultValue?: TDefault;
-    /** Override the URL segment. Defaults to the param name inside its scope prefix. */
-    urlKey?: string;
-    /** Remove the key from the URL when the value equals the default. Defaults to `true`. */
-    omitDefault?: boolean;
-    /** Router history mode for writes to this param. Params default to `'replace'`. */
-    historyMode?: HistoryMode;
-}
-/** Request received by a remote option source. */
-export interface DashboardRemoteOptionsRequest {
-    /** Current debounced search term. Empty when the menu lists unfiltered options. */
-    search: string;
-    /** Requested page. */
-    page: RemoteOptionsPageRequest;
-}
-/**
- * Remote option source, following the same contract as the form engine's remote options:
- * server-side search, page or cursor pagination, and hydration of selected values that the loaded
- * pages do not contain (for example ids restored from the URL).
- */
-export interface DashboardRemoteOptionsConfig {
-    /** Loads one page of options for the current search term. */
-    load: (request: DashboardRemoteOptionsRequest) => Promise<RemoteOptionsResult<DashboardOption<string>>>;
-    /** Resolves labels for selected values missing from the loaded pages. */
-    resolveSelected?: (request: {
-        values: readonly string[];
-    }) => Promise<readonly DashboardOption<string>[]>;
-    /** Defaults to `{ type: 'page', size: 25 }`. */
-    pagination?: RemoteOptionsPagination;
-    search?: RemoteOptionsSearch;
-    /** Cache identity of the option source. Defaults to a key derived from the param location. */
-    queryKey?: QueryKey;
-}
-/** Runtime view of a param definition, with its value type erased. */
-export interface DashboardRuntimeParam extends DashboardParamLike {
-    /** Erased codec, in the shape `useQueryStates` accepts for heterogeneous schemas. */
-    readonly codec: StaticQueryStateOptions['codec'];
-    readonly urlKey?: string;
-    readonly omitDefault?: boolean;
-    readonly historyMode?: HistoryMode;
-    /** Static option items for `p.enum` and `p.options`. */
-    readonly items?: readonly DashboardOption[];
-    /** Remote option source for `p.remote`. */
-    readonly remote?: DashboardRemoteOptionsConfig;
-}
-/**
- * Param definition produced by the `p.*` builders. `defaultValue` carries the resolved value type:
- * it includes `undefined` only when no default was declared.
- */
-export type DashboardParamDefinition<TValue> = Omit<DashboardRuntimeParam, 'codec' | 'defaultValue'> & {
-    readonly codec: QueryCodec<TValue | undefined>;
-    readonly defaultValue: TValue;
-};
-/** Structural constraint every param definition satisfies, whatever its value type. */
-export interface DashboardParamLike {
-    readonly kind: DashboardParamKind;
-    readonly multiple: boolean;
-    readonly defaultValue: unknown;
-}
-export type DashboardParamMap = Record<string, DashboardParamLike>;
-/** Empty map used when a scope declares no params, queries, or derived values. */
-export type DashboardEmptyMap = Record<never, never>;
-/** Writable, URL-synced values of a param map. Every property is a `v-model` target. */
-export type DashboardParamValues<TParams> = {
-    -readonly [K in keyof TParams]: TParams[K] extends {
-        readonly defaultValue: infer TValue;
-    } ? TValue : never;
-};
-/** Keys of params that carry option items (`p.enum`, `p.options`, `p.remote`, `p.comparison`). */
-export type DashboardOptionParamKeys<TParams> = {
-    [K in keyof TParams]: TParams[K] extends {
-        readonly kind: 'enum' | 'options' | 'remote' | 'comparison';
-    } ? K : never;
-}[keyof TParams];
-/** The `p` builder handed to every `params` callback. */
-export type DashboardParamBuilder = typeof dashboardParamBuilder;