nuxt-ui-tools 1.0.1 → 1.2.0

package/dist/runtime/dashboard/constants/query.d.ts

@@ -0,0 +1,16 @@
+/** Default TanStack Query options applied to dashboard queries. */
+export declare const DASHBOARD_QUERY_DEFAULTS: {
+    refetchOnWindowFocus: boolean;
+    /** How long fetched data is considered fresh (ms), per stage. */
+    staleTime: {
+        background: number;
+        deferred: number;
+        essential: number;
+    };
+};
+export declare const DASHBOARD_REMOTE_OPTIONS_DEFAULTS: {
+    pageSize: number;
+    searchDebounce: number;
+    selectedStaleTime: number;
+    staleTime: number;
+};

package/dist/runtime/dashboard/constants/query.js

@@ -0,0 +1,15 @@
+export const DASHBOARD_QUERY_DEFAULTS = {
+  refetchOnWindowFocus: false,
+  /** How long fetched data is considered fresh (ms), per stage. */
+  staleTime: {
+    background: 6e4,
+    deferred: 6e4,
+    essential: 3e4
+  }
+};
+export const DASHBOARD_REMOTE_OPTIONS_DEFAULTS = {
+  pageSize: 25,
+  searchDebounce: 250,
+  selectedStaleTime: 3e5,
+  staleTime: 3e4
+};

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

@@ -0,0 +1,4 @@
+export { useDashboard } from './composables/use-dashboard.js';
+export { defineDashboardSchema } from './schema/index.js';
+export { resolveDashboardComparisonRange } from './utils/comparison.js';
+export type * from './types';

package/dist/runtime/dashboard/index.js

@@ -0,0 +1,3 @@
+export { useDashboard } from "./composables/use-dashboard.js";
+export { defineDashboardSchema } from "./schema/index.js";
+export { resolveDashboardComparisonRange } from "./utils/comparison.js";

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

@@ -0,0 +1,57 @@
+import type { DashboardDeriveMap, DashboardDerivedResources, DashboardEmptyMap, DashboardKeyError, DashboardParamMap, DashboardReservedKey, DashboardSchema, DashboardScopeGuard, DashboardScopeInput, DashboardSourceMap, DashboardViewBuilder, 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.
+ *
+ * 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.
+ *
+ * @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 declare function defineDashboardSchema<const TParams extends DashboardParamMap = 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. */
+    urlPrefix?: string;
+    /**
+     * Default auto-refresh interval in seconds (`0`: off). `dashboard.autoRefresh` changes it at
+     * runtime and keeps it in the URL (`refresh`).
+     */
+    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?: (view: DashboardViewBuilder<TParams, TQueries & DashboardDerivedResources<TDerive>>) => 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>;
+export {};

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

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

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

@@ -0,0 +1,251 @@
+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 { DashboardBlockUi } from './ui.js';
+/** Formats a numeric value for axes, tooltips, legends, and totals. */
+export type DashboardValueFormat = (value: number) => string;
+/**
+ * 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)`.
+ * Omitted colors follow the palette order.
+ */
+export type DashboardSeriesColor = string;
+/** One series of a chart, read from each row through an accessor. */
+export interface DashboardSeries<TRow> {
+    /** Stable identity, also used for legend keys. */
+    key: string;
+    label?: LazyTextValue;
+    value: (row: TRow, index: number) => number | null | undefined;
+    color?: DashboardSeriesColor;
+    /** Draws the series as a dashed line (comparison / previous period). */
+    dashed?: boolean;
+    /** Combo charts only: how the series is drawn. Defaults to the chart's own mark. */
+    type?: 'bar' | 'line' | 'area';
+    /**
+     * Combo charts only: which value axis a line or area series uses. Defaults to `'left'`. Bars
+     * always use the left axis.
+     */
+    axis?: 'left' | 'right';
+    /**
+     * The same measure over the comparison period (previous period, previous year). Drawn next to the
+     * series in a faded tone of its color (dashed for lines), and listed in the legend, tooltip,
+     * table view, and CSV.
+     */
+    compare?: (row: TRow, index: number) => number | null | undefined;
+    /** Legend label of `compare`. Defaults to "<label> (previous period)". */
+    compareLabel?: LazyTextValue;
+}
+/**
+ * Emphasized bars of a bar chart: the largest, the smallest, the last, or the rows an accessor
+ * picks. The other bars take a faded tone of their color.
+ */
+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,
+ * cross-filter). Selected rows are marked; in charts the other bars, points, and segments recede.
+ */
+export type DashboardSelected<TRow> = (row: TRow, index: number) => boolean;
+export interface DashboardAxisOptions {
+    format?: DashboardValueFormat;
+    /** Fixed domain bounds. Defaults to `0` and a rounded maximum of the data. */
+    min?: number;
+    max?: number;
+    /** Number of intervals between ticks. Defaults to a readable count for the maximum. */
+    ticks?: number;
+}
+/** Horizontal reference line, e.g. an objective. */
+export interface DashboardReferenceLine {
+    value: number;
+    label?: LazyTextValue;
+    axis?: 'left' | 'right';
+    /** Where the label sits along the line. Defaults to `'end'`. */
+    position?: 'start' | 'end';
+}
+/** Shape of the loading skeleton, one per block family. */
+export type DashboardSkeletonKind = 'stat' | 'bars' | 'lines' | 'donut' | 'rows' | 'hbars' | 'funnel' | 'stack' | 'paired' | 'feed' | 'table' | 'stats' | 'gauge';
+/**
+ * Built-in card menu actions: `table` switches the content to a data table, `csv` downloads that
+ * data, `expand` opens the card in a large dialog.
+ */
+export type DashboardMenuAction = 'table' | 'csv' | 'expand';
+/** Entries of a card menu: built-in actions and Nuxt UI dropdown items, in display order. */
+export type DashboardMenuEntries = readonly (DashboardMenuAction | DropdownMenuItem)[];
+/** What a function `menu` receives: the block's own data actions, to reuse in custom items. */
+export interface DashboardMenuContext {
+    /** Resolved block title. */
+    title: string;
+    /** The block's tabular data (the table view / CSV source); `undefined` until content shows. */
+    table: () => DashboardDataTable | undefined;
+    /** Downloads that table as CSV. */
+    download: () => void;
+    /** Opens the expand dialog. */
+    expand: () => void;
+}
+/**
+ * Card menu, opened from a `…` button in the header. `true` lists every built-in action the block
+ * supports; an array picks and orders built-in actions and mixes in Nuxt UI dropdown items; a
+ * function builds that array from the block's context (its table, CSV download, expand).
+ */
+export type DashboardMenu = boolean | DashboardMenuEntries | ((context: DashboardMenuContext) => DashboardMenuEntries);
+/**
+ * Button of a block, in its header next to the menu (default) or full width under the content.
+ * Takes any Nuxt UI button prop: `label`, `icon`, `to`, `onClick`, `color`, `variant`, `loading`…
+ */
+export interface DashboardAction extends ButtonProps {
+    placement?: 'header' | 'footer';
+}
+/** Action on one row: a Nuxt UI dropdown item, listed in the row's `⋮` menu. */
+export interface DashboardRowAction extends DropdownMenuItem {
+    /** Renders the action as an icon button on the row instead (needs an `icon`). */
+    inline?: boolean;
+}
+/** Builds the actions of one row. An empty result leaves the row without actions. */
+export type DashboardRowActions<TRow> = (row: TRow, index: number) => readonly DashboardRowAction[] | null | undefined;
+/** One column of a block's tabular data. */
+export interface DashboardDataColumn {
+    key: string;
+    label: string;
+    /** Numeric columns align to the end and export their raw values. */
+    numeric: boolean;
+}
+/** One cell: the raw value (exported to CSV) and its display text. */
+export interface DashboardDataCell {
+    value: string | number | null;
+    text: string;
+}
+/** Tabular view of a block's data, behind the `table` and `csv` menu actions. */
+export interface DashboardDataTable {
+    columns: DashboardDataColumn[];
+    rows: DashboardDataCell[][];
+}
+/** A point in time as blocks receive it: a `Date`, epoch milliseconds, or an ISO string. */
+export type DashboardTimeValue = Date | number | string;
+/** Payload of a block's `select` event: the clicked row and its index in the source data. */
+export interface DashboardSelectEvent<TRow> {
+    row: TRow;
+    index: number;
+}
+/** Status of a KPI, shown as a colored dot and label on the title row. */
+export interface DashboardStatus {
+    color: 'success' | 'warning' | 'error' | 'info' | 'neutral';
+    label?: LazyTextValue;
+}
+/** Severity of an alert row, most severe first. */
+export type DashboardAlertSeverity = 'error' | 'warning' | 'info' | 'success';
+/** Button at the end of an alert row. */
+export interface DashboardAlertAction {
+    label: LazyTextValue;
+    icon?: string;
+    to?: RouteLocationRaw;
+    onClick?: (event: MouseEvent) => void;
+}
+/** One column of `UiDashboardTable`. */
+export interface DashboardTableColumn<TRow> {
+    /** Stable identity: sort key and `#cell-<key>` slot name. */
+    key: string;
+    label?: LazyTextValue;
+    /** Cell value. Numbers go through `format` and sort numerically. */
+    value: (row: TRow, index: number) => LazyTextValue | null | undefined;
+    /**
+     * `text` (default); `number`; `delta` (signed percent, colored by sign); `percent` (a share);
+     * `bar` (the number with an inline bar scaled to the column maximum).
+     */
+    type?: 'text' | 'number' | 'delta' | 'percent' | 'bar';
+    format?: DashboardValueFormat;
+    /** `delta` columns: a decrease is good news. */
+    invert?: boolean;
+    /** `bar` columns: bar color. */
+    color?: DashboardSeriesColor;
+    /** `bar` columns: value of a full bar. Defaults to the column maximum. */
+    max?: number;
+    /** Defaults to `end` for numeric types, `start` otherwise. */
+    align?: 'start' | 'center' | 'end';
+    /** Header click sorts by this column. Defaults to `true`. */
+    sortable?: boolean;
+    /** Column width, any CSS length. */
+    width?: string;
+    /** Classes of the column's cells. */
+    class?: string;
+}
+/** Sort state of `UiDashboardTable` (`v-model:sort`). */
+export interface DashboardTableSort {
+    key: string;
+    direction: 'asc' | 'desc';
+}
+/** Visual state a block renders, reduced from its source. */
+export type DashboardBlockPhase = 'idle' | 'loading' | 'empty' | 'error' | 'content';
+/**
+ * When a block activates a `deferred` source: once it scrolls near the viewport (default), as soon
+ * as it mounts, or never (`manual`, the app calls `source.activate()`).
+ */
+export type DashboardBlockActivation = 'visible' | 'mount' | 'manual';
+/** Empty state content, shown when a source is ready but has nothing to display. */
+export interface DashboardEmptyContent {
+    icon?: string;
+    title?: LazyTextValue;
+    description?: LazyTextValue;
+}
+/** Props shared by every block. */
+export interface DashboardBlockBaseProps {
+    title?: LazyTextValue;
+    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;
+    /** Empty state content. Defaults to a localized "no data" message. */
+    empty?: DashboardEmptyContent;
+    /** Card menu. Inherits the enclosing grid's `menu` when omitted. */
+    menu?: DashboardMenu;
+    /** Buttons in the header, next to the menu, or full width under the content (`placement`). */
+    actions?: readonly DashboardAction[];
+    /**
+     * Shows when the data was last fetched ("Updated 3 min ago") under the content. Inherits the
+     * enclosing grid's `freshness` when omitted.
+     */
+    freshness?: boolean;
+    /** Class overrides for the card parts, merged over `appConfig.nuxtUiTools.dashboard.card`. */
+    ui?: DashboardBlockUi;
+}
+/** One figure of `UiDashboardStats`, read from the source data. */
+export interface DashboardStatsItem<TData> {
+    /** Stable identity. */
+    key: string;
+    label: LazyTextValue;
+    /** Numbers go through `format` (locale number format by default). */
+    value: (data: TData) => LazyTextValue | null | undefined;
+    format?: DashboardValueFormat;
+    /** Change in percent, colored by sign. `null` hides it. */
+    delta?: (data: TData) => number | null | undefined;
+    /** A decrease is good news. */
+    invertDelta?: boolean;
+    /** Secondary text after the delta. */
+    caption?: LazyTextValue | ((data: TData) => LazyTextValue | undefined);
+    icon?: string;
+    /** Accent of the icon and the progress bar. Defaults to the palette order. */
+    color?: DashboardSeriesColor;
+    /** Completion in percent (0–100), drawn as a bar under the value. `null` hides it. */
+    progress?: (data: TData) => number | null | undefined;
+    /** Badge next to the value ("Good", "At risk"). `null` hides it. */
+    status?: (data: TData) => DashboardStatus | null | undefined;
+}
+/** One tab of `UiDashboardTabs`. */
+export interface DashboardTab<TValue extends string | number = string | number> {
+    value: TValue;
+    label: LazyTextValue;
+    icon?: string;
+    /** Count shown after the label (items waiting in that tab…). */
+    count?: number | null;
+    disabled?: boolean;
+}
+/** Legend entry rendered in a block header. */
+export interface DashboardLegendItem {
+    key: string;
+    label: string;
+    color: string;
+    dashed?: boolean;
+}

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

@@ -0,0 +1,60 @@
+import type { DashboardValueFormat } from './blocks.js';
+/** Normalized chart row: series values in series order. */
+export interface DashboardChartDatum {
+    index: number;
+    values: (number | undefined)[];
+}
+export interface DashboardChartFrameSeries {
+    key: string;
+    label: string;
+    color: string;
+    dashed: boolean;
+    type: 'bar' | 'line' | 'area';
+    axis: 'left' | 'right';
+    /** Position in `DashboardChartDatum.values`. */
+    index: number;
+}
+export interface DashboardChartFrameAxis {
+    domain: [number, number];
+    /** Tick values, evenly spaced on round numbers. */
+    ticks: number[];
+    format: DashboardValueFormat;
+}
+export interface DashboardChartFrameReference {
+    value: number;
+    label: string;
+    axis: 'left' | 'right';
+    position: 'start' | 'end';
+}
+/** Value printed above one bar group: the stack total, or the tallest bar of the group. */
+export interface DashboardChartValueLabel {
+    index: number;
+    value: number;
+    text: string;
+    /** Emphasized datum (highlight or selection): the label stands out too. */
+    strong: boolean;
+}
+/** Everything a chart renderer needs, precomputed from the block props and source data. */
+export interface DashboardChartFrame {
+    data: DashboardChartDatum[];
+    labels: string[];
+    series: DashboardChartFrameSeries[];
+    /**
+     * Datums drawn at full strength, by index; the other bars take a faded tone. `null` when every
+     * datum does (no highlight, no selection).
+     */
+    emphasis: boolean[] | null;
+    /** Selected datum indexes, marked with a band behind line-only charts. */
+    selection: number[];
+    /** Values printed above the bars (`labels` prop), empty otherwise. */
+    valueLabels: DashboardChartValueLabel[];
+    /**
+     * X domain in datum indexes. Charts with bars pad half a slot on both sides so every bar group
+     * is centered on its label; line-only charts run edge to edge.
+     */
+    xDomain: [number, number];
+    left: DashboardChartFrameAxis;
+    right: DashboardChartFrameAxis | null;
+    references: DashboardChartFrameReference[];
+    stacked: boolean;
+}

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

@@ -0,0 +1,7 @@
+export type * from './options';
+export type * from './params';
+export type * from './resource';
+export type * from './schema';
+export type * from './blocks';
+export type * from './charts';
+export type * from './ui';

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

@@ -0,0 +1,46 @@
+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

@@ -0,0 +1,115 @@
+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;