nuxt-ui-tools 1.2.0 → 1.3.0

package/dist/runtime/dashboard/schema/index.d.ts

@@ -1,42 +1,36 @@
-import type { DashboardDeriveMap, DashboardDerivedResources, DashboardEmptyMap, DashboardKeyError, DashboardParamMap, DashboardReservedKey, DashboardSchema, DashboardScopeGuard, DashboardScopeInput, DashboardSourceMap, DashboardViewBuilder, DashboardViewMap } from '../types/index.js';
+import type { LazyTextValue } from '../../shared/types/utils.js';
+import type { DashboardCondition, DashboardDeriveMap, DashboardEmptyMap, DashboardFilterMap, DashboardKeyError, DashboardReservedKey, DashboardSchema, DashboardScopeGuard, DashboardScopeInput, DashboardSourceMap, DashboardView, DashboardViewMap } from '../types/index.js';
 type DashboardViewsGuard<TQueries, TDerive, TViews> = [
     Extract<keyof TViews, DashboardReservedKey | keyof TQueries | keyof TDerive>
 ] extends [never] ? unknown : {
     views: DashboardKeyError<`View key "${Extract<keyof TViews, DashboardReservedKey | keyof TQueries | keyof TDerive> & string}" is reserved or collides with a root query or derived value.`>;
 };
 /**
- * Declares a dashboard: typed URL-synced params, staged queries, derived values, and optional
- * views (tabs). Nothing runs here — `useDashboard(schema)` instantiates it.
+ * Declares a dashboard: its filters, staged queries and derived values, and its views (tabs).
+ * Nothing runs here — `useDashboard()` instantiates it.
+ *
+ * Wrap it in a function taking what the dashboard is about (an account, the workspace): the page
+ * passes it, and the function hands it on to its views. Filters are the state the user controls;
+ * they are declared inline, with the `f` builder.
  *
  * Keys are checked at compile time: a query, derived value, or view named after a runtime member
- * (`params`, `options`, `state`, `refreshing`, `refresh`, `updatedAt`, `autoRefresh`, `view`,
- * `schema`) or after a sibling is a type error.
+ * (`filters`, `controls`, `filtered`, `resetFilters`, `state`, `refreshing`, `refresh`, `updatedAt`,
+ * `autoRefresh`, `view`, `schema`) or after a sibling is a type error.
  *
  * @example
  * ```ts
- * const schema = defineDashboardSchema({
- *   key: 'sales',
- *   params: (p) => ({ period: p.enum([7, 30, 90], { defaultValue: 30 }) }),
- *   queries: ({ essential, background, params }) => ({
- *     summary: essential.query(() => ({
- *       queryKey: ['sales', 'summary', params.period],
- *       queryFn: () => api.sales.summary({ days: params.period }),
- *     })),
- *     channels: background.query({
- *       defaultValue: [],
- *       query: () => ({
- *         queryKey: ['sales', 'channels', params.period],
- *         queryFn: () => api.sales.channels({ days: params.period }),
- *       }),
- *     }),
- *   }),
- *   derive: ({ data }) => ({
- *     channelCount: () => data.channels.length,
- *   }),
- * })
+ * export function accountSchema(params: { accountId: string }) {
+ *   return defineDashboardSchema({
+ *     key: 'account',
+ *     views: {
+ *       activity: accountActivityView(params),
+ *       invoices: accountInvoicesView(params),
+ *     },
+ *   })
+ * }
  * ```
  */
-export declare function defineDashboardSchema<const TParams extends DashboardParamMap = DashboardEmptyMap, const TQueries extends DashboardSourceMap = DashboardEmptyMap, const TDerive extends DashboardDeriveMap = DashboardEmptyMap, const TViews extends DashboardViewMap = DashboardEmptyMap>(schema: {
+export declare function defineDashboardSchema<const TFilters extends DashboardFilterMap = DashboardEmptyMap, const TQueries extends DashboardSourceMap = DashboardEmptyMap, const TDerive extends DashboardDeriveMap = DashboardEmptyMap, const TViews extends DashboardViewMap = DashboardEmptyMap>(schema: {
     /** Stable identity, used in default query keys and devtools labels. */
     key: string;
     /** Prefix prepended to every URL key this dashboard owns. */
@@ -47,11 +41,49 @@ export declare function defineDashboardSchema<const TParams extends DashboardPar
      */
     autoRefresh?: number;
     /**
-     * Views (tabs). Each view owns params and queries; queries of a view never fetch until the
-     * view is opened once, then stay warm.
+     * Views (tabs), each declared with `defineDashboardView`. A view's queries never fetch until
+     * the view is opened once, then stay warm.
      */
-    views?: (view: DashboardViewBuilder<TParams, TQueries & DashboardDerivedResources<TDerive>>) => TViews;
+    views?: TViews;
     /** View shown when the URL does not select one. Defaults to the first declared view. */
     defaultView?: NoInfer<keyof TViews & string>;
-} & DashboardScopeInput<DashboardEmptyMap, DashboardEmptyMap, TParams, TQueries, TDerive> & DashboardScopeGuard<TQueries, TDerive> & DashboardViewsGuard<TQueries, TDerive, TViews>): DashboardSchema<TParams, TQueries, TDerive, TViews>;
+} & DashboardScopeInput<TFilters, TQueries, TDerive> & DashboardScopeGuard<TQueries, TDerive> & DashboardViewsGuard<TQueries, TDerive, TViews>): DashboardSchema<NoInfer<TFilters>, NoInfer<TQueries>, NoInfer<TDerive>, NoInfer<TViews>>;
+/**
+ * Declares one view (tab), self-contained: its label, its filters, its queries and derived values.
+ * Wrap it in a function taking what it needs from the dashboard's input, and give it its own file.
+ *
+ * A filter key names one state across the dashboard: two views declaring `year` share its value,
+ * so it survives a tab change. Components under the dashboard get the typed view handle with
+ * `useDashboardView(consumptionView)`.
+ *
+ * @example
+ * ```ts
+ * export function consumptionView(params: { workspace: Workspace }) {
+ *   const { $api, $i18n } = useNuxtApp()
+ *   return defineDashboardView({
+ *     label: () => $i18n.t('dashboard.tabs.consumption'),
+ *     enabled: () => canRead(params.workspace, 'consumption'),
+ *     filters: (f) => ({
+ *       year: f.enum([2025, 2026], { defaultValue: 2026, label: () => $i18n.t('filters.year') }),
+ *     }),
+ *     queries: ({ essential, filters }) => {
+ *       const overview = () => $api.consumption.queryOptions({ query: { year: filters.year } })
+ *       return {
+ *         summary: essential.query({ query: overview, select: (data) => data.summary }),
+ *         months: essential.query({ query: overview, select: (data) => data.months }),
+ *       }
+ *     },
+ *   })
+ * }
+ * ```
+ */
+export declare function defineDashboardView<const TFilters extends DashboardFilterMap = DashboardEmptyMap, const TQueries extends DashboardSourceMap = DashboardEmptyMap, const TDerive extends DashboardDeriveMap = DashboardEmptyMap>(view: {
+    /** Tab label. The lazy form keeps it translation-friendly. */
+    label?: LazyTextValue;
+    /**
+     * Availability of the view, read lazily: a disabled view has no tab, is never the current view
+     * (the URL falls back to an enabled one), and its queries report `disabled`.
+     */
+    enabled?: DashboardCondition;
+} & DashboardScopeInput<TFilters, TQueries, TDerive> & DashboardScopeGuard<TQueries, TDerive>): DashboardView<NoInfer<TFilters>, NoInfer<TQueries>, NoInfer<TDerive>>;
 export {};

package/dist/runtime/dashboard/schema/index.js

@@ -1,3 +1,6 @@
 export function defineDashboardSchema(schema) {
   return schema;
 }
+export function defineDashboardView(view) {
+  return view;
+}

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

@@ -2,9 +2,30 @@ import type { ButtonProps } from '@nuxt/ui/components/Button.vue';
 import type { DropdownMenuItem } from '@nuxt/ui/components/DropdownMenu.vue';
 import type { RouteLocationRaw } from 'vue-router';
 import type { LazyTextValue } from '../../shared/types/utils.js';
+import type { DashboardFilterControl } from './controls.js';
 import type { DashboardBlockUi } from './ui.js';
 /** Formats a numeric value for axes, tooltips, legends, and totals. */
-export type DashboardValueFormat = (value: number) => string;
+export type DashboardValueFormatter = (value: number) => string;
+/**
+ * Named number formats, in the dashboard locale:
+ *
+ * - `number`: grouped, one decimal at most, compact from 10,000 (`12.6K`). The block default.
+ * - `integer`: grouped, no decimals (`12,345`).
+ * - `decimal`: one decimal at most (`3.5`).
+ * - `compact`: short form (`12K`, `1.2M`).
+ * - `percent`: a share out of 100 (`57` → `57%`).
+ * - `ratio`: a share out of 1 (`0.57` → `57%`).
+ * - `delta`: a signed percent change (`12.4` → `+12.4%`).
+ * - `points`: a signed difference of percentages (`2.1` → `+2.1 pts`).
+ * - `signed`: a signed number (`3` → `+3`).
+ */
+export type DashboardFormatPreset = 'number' | 'integer' | 'decimal' | 'compact' | 'percent' | 'ratio' | 'delta' | 'points' | 'signed';
+/**
+ * How a block formats numbers: a preset (`'integer'`), `Intl.NumberFormat` options, or a function.
+ * Options with a `currency` and no `style` format whole amounts in that currency: `{ currency: 'EUR' }`,
+ * or `{ currency: 'EUR', notation: 'compact' }` for an axis.
+ */
+export type DashboardValueFormat = DashboardFormatPreset | Intl.NumberFormatOptions | DashboardValueFormatter;
 /**
  * Series color: a palette slot (`'series-1'` … `'series-6'`), a Nuxt UI color (`'primary'`,
  * `'success'`, `'warning'`, `'error'`, `'info'`, `'neutral'`), or any CSS color / `var(--x)`.
@@ -42,10 +63,12 @@ export interface DashboardSeries<TRow> {
  */
 export type DashboardHighlight<TRow> = 'max' | 'min' | 'last' | ((row: TRow, index: number) => boolean);
 /**
- * Rows shown as selected, typically the value a `select` handler stored in a param (drill-down,
+ * Rows shown as selected, typically the value a `select` handler stored in a filter (drill-down,
  * cross-filter). Selected rows are marked; in charts the other bars, points, and segments recede.
  */
 export type DashboardSelected<TRow> = (row: TRow, index: number) => boolean;
+/** Footer totals of a chart, one per solid series: `true` or `'sum'` adds them up, `'average'` averages them. */
+export type DashboardChartTotals = boolean | 'sum' | 'average';
 export interface DashboardAxisOptions {
     format?: DashboardValueFormat;
     /** Fixed domain bounds. Defaults to `0` and a rounded maximum of the data. */
@@ -192,8 +215,6 @@ export interface DashboardBlockBaseProps {
     subtitle?: LazyTextValue;
     /** Grid span, responsive: `"12 md:6 xl:4"`. Defaults to the full row. */
     size?: string;
-    /** Grid row span, responsive. */
-    rows?: string;
     /** Render without card chrome (no border, padding, or background). Defaults to `true`. */
     card?: boolean;
     activation?: DashboardBlockActivation;
@@ -203,6 +224,11 @@ export interface DashboardBlockBaseProps {
     menu?: DashboardMenu;
     /** Buttons in the header, next to the menu, or full width under the content (`placement`). */
     actions?: readonly DashboardAction[];
+    /**
+     * Filters narrowing this block, such as a drill-down value picked on another block: each one
+     * shows as a removable chip in the toolbar while it differs from its default.
+     */
+    filters?: readonly DashboardFilterControl[];
     /**
      * Shows when the data was last fetched ("Updated 3 min ago") under the content. Inherits the
      * enclosing grid's `freshness` when omitted.

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

@@ -1,4 +1,4 @@
-import type { DashboardValueFormat } from './blocks.js';
+import type { DashboardValueFormatter } from './blocks.js';
 /** Normalized chart row: series values in series order. */
 export interface DashboardChartDatum {
     index: number;
@@ -18,7 +18,7 @@ export interface DashboardChartFrameAxis {
     domain: [number, number];
     /** Tick values, evenly spaced on round numbers. */
     ticks: number[];
-    format: DashboardValueFormat;
+    format: DashboardValueFormatter;
 }
 export interface DashboardChartFrameReference {
     value: number;

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

@@ -0,0 +1,123 @@
+import type { DashboardFilterKind, DashboardOption, DashboardOptionValue } from './filters.js';
+/**
+ * Props ready to spread onto a Nuxt UI `USelectMenu`:
+ * `<USelectMenu v-model="dashboard.filters.account" v-bind="dashboard.controls.account.menu" />`.
+ */
+export interface DashboardOptionsMenuBindings<TValue extends DashboardOptionValue = DashboardOptionValue> {
+    items: DashboardOption<TValue>[];
+    valueKey: 'value';
+    labelKey: 'label';
+    multiple: boolean;
+    loading?: boolean;
+    searchTerm?: string;
+    ignoreFilter?: boolean;
+    'onUpdate:searchTerm'?: (value: string) => void;
+    'onUpdate:open'?: (value: boolean) => void;
+}
+/** A preset as the control exposes it: resolved text, and whether the value matches it. */
+export interface DashboardControlPreset<TValue = unknown> {
+    label: string;
+    value: TValue;
+    icon?: string;
+    hint?: string;
+    /** The filter's value is this preset's. */
+    active: boolean;
+    /** Sets the filter's value to this preset's. */
+    apply: () => void;
+}
+/**
+ * Everything a control needs to drive one filter: its value, how to present it, its option list,
+ * and the actions a picker performs. `UiDashboardFilter` renders one; any other component can bind
+ * to it directly.
+ *
+ * Remote lists 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 DashboardFilterControl<TValue = unknown, TItem extends DashboardOptionValue = DashboardOptionValue> {
+    readonly key: string;
+    readonly kind: DashboardFilterKind;
+    readonly multiple: boolean;
+    /** Not rendered by `UiDashboardFilters`; ignored by `filtered` and `resetFilters()`. */
+    readonly headless: boolean;
+    /**
+     * The filter's `enabled` condition holds. A disabled filter is out of every bar, reads its
+     * default, and ignores writes.
+     */
+    readonly enabled: boolean;
+    /** Filter name. */
+    readonly label: string;
+    /** Text of an empty selection ("All"). */
+    readonly placeholder: string;
+    /** Current value. Writable; `null` / `undefined` restore the default. */
+    value: TValue;
+    readonly defaultValue: TValue;
+    /** The value differs from the default. */
+    readonly changed: boolean;
+    /** Text of the current value: selected labels, or the placeholder. */
+    readonly display: string;
+    /** Options matching the current search: loaded pages and hydrated selected options for remote lists. */
+    readonly items: readonly DashboardOption<TItem>[];
+    /** Options of the current value, in value order. */
+    readonly selected: readonly DashboardOption<TItem>[];
+    /** Menu columns declared on the filter. */
+    readonly columns: number | undefined;
+    readonly searchable: boolean;
+    /** Most values a `multiple` filter picks. */
+    readonly max: number | undefined;
+    /** `value` is, or contains, this option value. */
+    isSelected(value: TItem): boolean;
+    /**
+     * Picks an option. Multiple filters add or remove it (in item order, up to `max`); single filters
+     * take it as their value.
+     */
+    toggle(value: TItem): void;
+    /** Restores the default value. */
+    reset(): void;
+    /** Shortcut values declared with `presets`. */
+    readonly presets: readonly DashboardControlPreset<TValue>[];
+    readonly loading: boolean;
+    readonly loadingMore: boolean;
+    readonly hasMore: boolean;
+    readonly error: unknown;
+    /** Search term. Writable; remote sources debounce it before loading. */
+    search: string;
+    /**
+     * A picker shows the list. Writable; setting it starts loading a remote list's first page.
+     * `UiDashboardFilter` sets it while its menu is open.
+     */
+    open: boolean;
+    loadMore(): void;
+    refresh(): Promise<void>;
+    readonly menu: DashboardOptionsMenuBindings<TItem>;
+}
+/** Value a filter picks from its list: its value, or its element type for `multiple` filters. */
+type DashboardControlItem<TFilter> = TFilter extends {
+    readonly defaultValue: infer TValue;
+} ? Extract<NonNullable<TValue> extends readonly (infer TItem)[] ? TItem : NonNullable<TValue>, DashboardOptionValue> : never;
+type DashboardControlValue<TFilter> = TFilter extends {
+    readonly defaultValue: infer TValue;
+} ? TValue : never;
+/** Controls of a filter map, by filter key. */
+export type DashboardFilterControls<TFilters> = {
+    readonly [K in keyof TFilters]: DashboardFilterControl<DashboardControlValue<TFilters[K]>, DashboardControlItem<TFilters[K]>>;
+};
+/** What a filter bar drives: a dashboard (its root and current view) or one view handle. */
+export interface DashboardFiltersTarget {
+    readonly controls: Readonly<Record<string, DashboardFilterControl>>;
+    readonly filtered: boolean;
+    resetFilters(): void;
+    /** The dashboard's view controller; view handles carry their own meta, without `current`. */
+    readonly view?: {
+        readonly current?: string;
+    };
+}
+type DashboardControlsOf<TTarget> = TTarget extends {
+    readonly controls: infer TControls;
+} ? TControls : never;
+/** Keys of every filter a bar may show: the root's, and those of each view. */
+export type DashboardFilterKeysOf<TTarget> = keyof DashboardControlsOf<TTarget> | (TTarget extends {
+    readonly view: {
+        readonly current: infer TKey;
+    };
+} ? TKey extends keyof TTarget ? keyof DashboardControlsOf<TTarget[TKey]> : never : never);
+export {};

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

@@ -0,0 +1,236 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { Ref } from 'vue';
+import type { HistoryMode, QueryCodec, StaticQueryStateOptions } from '../../query-state/index.js';
+import type { QueryDefinition } from '../../shared/types/query.js';
+import type { RemoteOptionsPageRequest, RemoteOptionsPagination, RemoteOptionsResult, RemoteOptionsSearch } from '../../shared/types/remote-options.js';
+import type { LazyTextValue } from '../../shared/types/utils.js';
+import type { dashboardFilterBuilder } from '../utils/builders/dashboard-filters.js';
+import type { DashboardCondition } from './resource.js';
+export type DashboardFilterKind = '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 a filter can pick. */
+export type DashboardOptionValue = string | number | boolean;
+/**
+ * Option item shape. It matches Nuxt UI `USelect` / `USelectMenu` items, so filter controls can be
+ * bound to those components directly.
+ */
+export interface DashboardOption<TValue extends DashboardOptionValue = DashboardOptionValue> {
+    value: TValue;
+    label: string;
+    description?: string;
+    /** Short trailing text in filter menus: a count, a code. */
+    hint?: string;
+    icon?: string;
+    avatar?: {
+        src?: string;
+        alt?: string;
+        text?: string;
+    };
+    disabled?: boolean;
+}
+export interface DashboardDateRange {
+    start: Date;
+    end: Date;
+}
+/**
+ * Where a filter keeps its value.
+ *
+ * - `'url'` (default): the query string, under the filter's URL key.
+ * - `'memory'`: component state, gone on reload.
+ * - a `Ref`: an external store, read and written both ways (e.g. a Pinia `storeToRefs` ref).
+ * - a getter: an external, read-only source; writes are ignored and the filter is headless.
+ *
+ * A nullish external value reads as the default value.
+ */
+export type DashboardFilterSync<TValue> = 'url' | 'memory' | Ref<TValue | null | undefined> | (() => TValue | null | undefined);
+/** A value a filter offers as a shortcut: "Last 30 days", "English range". */
+export interface DashboardFilterPreset<TValue> {
+    label: LazyTextValue;
+    value: TValue;
+    icon?: string;
+    /** Short trailing text: a count, a range. */
+    hint?: string;
+}
+/** Presets of a filter: fixed, or read reactively (e.g. from another query's data). */
+export type DashboardFilterPresets<TValue> = readonly DashboardFilterPreset<TValue>[] | (() => readonly DashboardFilterPreset<TValue>[]);
+/**
+ * A default value, or a getter reading it from data. A getter may return `undefined` while its data
+ * loads; the filter type then keeps `undefined` (a list filter falls back to `[]`).
+ */
+export type DashboardFilterDefault<TValue> = TValue | (() => TValue | undefined);
+/** Options shared by every `f.*` builder. `TValue` is the filter value. */
+export interface DashboardFilterOptions<TDefault, TValue = unknown> {
+    /**
+     * Value used when the filter is unset (missing or unparsable URL key, nullish external value).
+     * A non-`undefined` default narrows the filter type: `f.string()` is `string | undefined`,
+     * `f.string({ defaultValue: '' })` is `string`. Values equal to the default never reach the URL.
+     *
+     * A getter makes the default follow data, e.g. the top three products of a loaded list: the
+     * filter reads it while unset, and a value equal to it keeps following it.
+     */
+    defaultValue?: TDefault;
+    /** Where the value lives. Defaults to `'url'`. */
+    sync?: DashboardFilterSync<TValue>;
+    /**
+     * Override the URL key. Defaults to the filter key: filters with the same URL key are one
+     * filter, so `year` declared by two views keeps its value when the tab changes.
+     */
+    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 filter. Filters default to `'replace'`. */
+    historyMode?: HistoryMode;
+    /** Filter name, shown on its pill and read by assistive tech. Defaults to the filter key. */
+    label?: LazyTextValue;
+    /** Text of an empty selection. Defaults to the localized "All". */
+    placeholder?: LazyTextValue;
+    /**
+     * State only: `UiDashboardFilters` does not render it, and `filtered` / `resetFilters()` ignore
+     * it. Use it for values driven by the app (a store, a chart drill-down you render yourself).
+     */
+    headless?: boolean;
+    /**
+     * Whether the filter exists right now, e.g. an account filter only an admin gets. While it is
+     * `false` its control leaves every bar, its value reads as the default (queries never send it),
+     * and writes are ignored.
+     */
+    enabled?: DashboardCondition;
+    /** Shortcuts the filter menu offers under its options; picking one sets the whole value. */
+    presets?: DashboardFilterPresets<TValue>;
+}
+/** Presentation of filters whose values have no label of their own (`enum`, `boolean`, `number`…). */
+export interface DashboardFilterFormatOptions<TItem> {
+    /** Text of one value, in the menu and on the pill. Evaluated reactively. */
+    format?: (value: TItem) => string;
+}
+/** Options of filters picked from a list. */
+export interface DashboardFilterListOptions {
+    /** Menu columns: `3` lays twelve months out as a 3×4 grid. */
+    columns?: number;
+    /**
+     * Shows a search field in the menu. Remote lists always search on the server; static lists
+     * filter their items locally. Defaults to `true` for remote lists, `false` otherwise.
+     */
+    searchable?: boolean;
+}
+/** Options of `multiple` filters. */
+export interface DashboardFilterMultipleOptions {
+    /** Most values the filter picks; the other items disable once it is reached. */
+    max?: number;
+}
+/** 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;
+}
+/**
+ * What a remote source returns for one request: a query definition (the dashboard runs its
+ * `queryFn`, e.g. a Tuyau / TanStack `queryOptions()` object), or a promise.
+ */
+export type DashboardRemoteResult<TResult> = QueryDefinition<TResult> | Promise<TResult>;
+/**
+ * Remote option source, following the same contract as the form engine and table filters:
+ * 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). `remoteTableOptions()` builds one
+ * for any endpoint that speaks the table request protocol.
+ */
+export interface DashboardRemoteOptionsConfig {
+    /** Loads one page of options for the current search term. */
+    load: (request: DashboardRemoteOptionsRequest) => DashboardRemoteResult<RemoteOptionsResult<DashboardOption<string>>>;
+    /** Resolves labels for selected values missing from the loaded pages. */
+    resolveSelected?: (request: {
+        values: readonly string[];
+    }) => DashboardRemoteResult<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 filter location. */
+    queryKey?: QueryKey;
+}
+/** Option items of a filter: fixed, or read reactively (e.g. from another query's data). */
+export type DashboardFilterItems = readonly DashboardOption[] | (() => readonly DashboardOption[]);
+/** Runtime view of a filter definition, with its value type erased. */
+export interface DashboardRuntimeFilter extends DashboardFilterLike {
+    /** Erased codec, in the shape `useQueryStates` accepts for heterogeneous schemas. */
+    readonly codec: StaticQueryStateOptions['codec'];
+    /**
+     * The current default: the declared value, or what the default getter returns now.
+     * `defaultValue` holds the unset form (the static default, or `undefined` / `[]` for a getter).
+     */
+    readonly resolveDefault: () => unknown;
+    readonly sync?: DashboardFilterSync<unknown>;
+    readonly urlKey?: string;
+    readonly omitDefault?: boolean;
+    readonly historyMode?: HistoryMode;
+    readonly label?: LazyTextValue;
+    readonly placeholder?: LazyTextValue;
+    readonly headless?: boolean;
+    readonly enabled?: DashboardCondition;
+    /** Text of one value. A method, so builders' typed `format` callbacks fit the erased shape. */
+    format?(value: unknown): string;
+    readonly columns?: number;
+    readonly searchable?: boolean;
+    readonly max?: number;
+    /** Presets, read reactively (fixed lists are normalized to getters). */
+    readonly presets?: () => readonly DashboardFilterPreset<unknown>[];
+    /** Option items of `f.enum`, `f.options`, `f.boolean`, `f.comparison`, read reactively. */
+    readonly items?: () => readonly DashboardOption[];
+    /** Remote option source of `f.remote`. */
+    readonly remote?: DashboardRemoteOptionsConfig;
+    /** Points `value` at the filter's state once its dashboard runs. */
+    bind(read: () => unknown): void;
+}
+/**
+ * Filter definition produced by the `f.*` builders. `defaultValue` carries the resolved value type:
+ * it includes `undefined` only when no default was declared.
+ */
+export type DashboardFilterDefinition<TValue> = Omit<DashboardRuntimeFilter, 'bind' | 'codec' | 'defaultValue' | 'value'> & {
+    readonly codec: QueryCodec<TValue | undefined>;
+    readonly defaultValue: TValue;
+    /**
+     * Current value, once the dashboard runs (the default before). Read it in another filter's lazy
+     * options, e.g. a `format` naming the year before the selected one:
+     * `f.boolean({ format: (on) => (on ? String(year.value - 1) : 'None') })`.
+     */
+    readonly value: TValue;
+};
+/** Structural constraint every filter definition satisfies, whatever its value type. */
+export interface DashboardFilterLike {
+    readonly kind: DashboardFilterKind;
+    readonly multiple: boolean;
+    readonly defaultValue: unknown;
+    readonly value: unknown;
+}
+/** Filters of a scope, by key. */
+export type DashboardFilterMap = Record<string, DashboardFilterLike>;
+/** Empty map used when a scope declares no filters, queries, or derived values. */
+export type DashboardEmptyMap = Record<never, never>;
+/** Writable values of a filter map. Every property is a `v-model` target. */
+export type DashboardFilterValues<TFilters> = {
+    -readonly [K in keyof TFilters]: TFilters[K] extends {
+        readonly defaultValue: infer TValue;
+    } ? TValue : never;
+};
+/**
+ * Filters of a scope, declared inline with the `f` builder.
+ *
+ * @example
+ * ```ts
+ * filters: (f) => {
+ *   const year = f.enum([2025, 2026], { defaultValue: 2026, label: 'Year' })
+ *   return {
+ *     year,
+ *     compare: f.boolean({ format: (on) => (on ? String(year.value - 1) : 'None') }),
+ *   }
+ * }
+ * ```
+ */
+export type DashboardFiltersInput<TFilters> = (f: DashboardFilterBuilder) => TFilters;
+/** The `f` builder handed to every `filters` callback. */
+export type DashboardFilterBuilder = typeof dashboardFilterBuilder;

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

@@ -1,5 +1,6 @@
-export type * from './options';
-export type * from './params';
+export type * from './controls';
+export type * from './filters';
+export type * from './page';
 export type * from './resource';
 export type * from './schema';
 export type * from './blocks';

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

@@ -0,0 +1,17 @@
+import type { DashboardFiltersTarget } from './controls.js';
+import type { DashboardViewController } from './schema.js';
+/** What `UiDashboardPage` renders: the dashboard object returned by `useDashboard`. */
+export interface DashboardPageTarget extends DashboardFiltersTarget {
+    refresh: () => Promise<void>;
+    readonly refreshing: boolean;
+    readonly updatedAt: number | undefined;
+    autoRefresh: number;
+}
+/** A dashboard with views: `UiDashboardPage` renders their tabs and the current one's slot. */
+export interface DashboardViewsTarget {
+    readonly view: DashboardViewController<string>;
+}
+/** Names of a dashboard's views, which name the view slots of `UiDashboardPage`. */
+export type DashboardViewKeysOf<TDashboard> = TDashboard extends {
+    readonly view: DashboardViewController<infer TKey>;
+} ? TKey : never;