nuxt-ui-tools 1.0.1 → 1.2.0

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

@@ -0,0 +1,106 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardOptionsHandles } from './options.js';
+import type { DashboardEmptyMap, DashboardParamBuilder, DashboardParamMap, DashboardParamValues } from './params.js';
+import type { DashboardKeyError } from './schema.js';
+/**
+ * Fetch stage of a query.
+ *
+ * - `essential` fetches as soon as its scope is active and drives the scope `state`.
+ * - `background` fetches once every essential query of the same scope has settled.
+ * - `deferred` never fetches until `resource.activate()` runs (blocks call it when they mount or
+ *   scroll into view).
+ */
+export type DashboardStage = 'essential' | 'background' | 'deferred';
+export type DashboardResourceState = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * Contract every block binds to through `:source`. Query resources and derived resources both
+ * satisfy it. Every member is a plain value read through a getter — there is no `.value`.
+ */
+export interface DashboardSourceLike<TData = unknown> {
+    /** Stable identity, e.g. `consumption.productLines`. */
+    readonly id: string;
+    readonly data: TData;
+    readonly state: DashboardResourceState;
+    readonly error: unknown;
+    /** A background refetch is running while `state` is still `'ready'`. */
+    readonly refreshing: boolean;
+    /**
+     * When the data was last fetched successfully (epoch milliseconds). `undefined` until the first
+     * success. A derived value reports its oldest input.
+     */
+    readonly updatedAt: number | undefined;
+    /** Opts an idle `deferred` resource in. No-op for other resources. */
+    activate(): void;
+    refresh(): Promise<void>;
+}
+/** A declared query, as exposed on the dashboard facade. */
+export interface DashboardResource<TData, TParams extends DashboardParamMap = DashboardEmptyMap, TStage extends DashboardStage = DashboardStage> extends DashboardSourceLike<TData> {
+    readonly kind: 'query';
+    readonly stage: TStage;
+    /** `false` while the owning view has never been opened or a `deferred` query was not activated. */
+    readonly active: boolean;
+    /** Widget-scoped params, URL-synced under this resource's key. */
+    readonly params: DashboardParamValues<TParams>;
+    /** Option handles for option-backed widget params. */
+    readonly options: DashboardOptionsHandles<TParams>;
+}
+/** A value declared in `derive`, exposed as a resource whose state follows the data it reads. */
+export interface DashboardDerived<TData> extends DashboardSourceLike<TData> {
+    readonly kind: 'derived';
+}
+export type DashboardSourceMap = Record<string, DashboardSourceLike>;
+/** Data of a source once it is `ready` (`undefined` is excluded, `null` is kept). */
+export type DashboardReadyData<TSource> = TSource extends DashboardSourceLike<infer TData> ? Exclude<TData, undefined> : never;
+/** Row type of a source whose ready data is an array. */
+export type DashboardSourceRow<TSource> = DashboardReadyData<TSource> extends readonly (infer TRow)[] ? TRow : never;
+/** Minimal query shape accepted from query factories (TanStack `queryOptions()` objects fit). */
+export interface DashboardQueryLike {
+    queryKey: QueryKey;
+}
+/** Result type of a query definition, read from its `queryFn`. */
+export type DashboardQueryData<TQuery> = TQuery extends {
+    queryFn?: infer TFn;
+} ? TFn extends (...args: never[]) => infer TResult ? Awaited<TResult> : never : never;
+/** Scope handed to the configured query factory. */
+export interface DashboardQueryScope<TParams extends DashboardParamMap, TRequired> {
+    /** Widget-scoped params declared on this query. */
+    params: Readonly<DashboardParamValues<TParams>>;
+    /** Non-nullish value returned by `requires`. */
+    required: NonNullable<TRequired>;
+}
+export interface DashboardQueryInput<TQuery extends DashboardQueryLike, TParams extends DashboardParamMap, TRequired> {
+    /** Widget-scoped params, URL-synced under `<scope>.<queryKey>.<param>`. */
+    params?: (p: DashboardParamBuilder) => TParams;
+    /**
+     * Gate and narrow. While it returns `null` or `undefined`, the resource stays `idle` and never
+     * fetches; once set, `scope.required` is the non-nullish value. Reading another resource's
+     * `data` here expresses a dependent query.
+     */
+    requires?: () => TRequired;
+    /** Extra boolean gate, combined with `requires` and with stage activation. */
+    enabled?: () => boolean;
+    /** Reactive query factory returning a TanStack query definition. */
+    query: (scope: DashboardQueryScope<NoInfer<TParams>, NoInfer<TRequired>>) => TQuery;
+    /** Keep previous data while a new key loads. Defaults to `true`. */
+    keepPreviousData?: boolean;
+    staleTime?: number;
+}
+/**
+ * One fetch stage. Declared once and instantiated for `essential`, `background` and `deferred`.
+ */
+export interface DashboardQueryStage<TStage extends DashboardStage> {
+    /** Plain query. `data` is `T | undefined`. */
+    query<TQuery extends DashboardQueryLike>(factory: () => TQuery): DashboardResource<DashboardQueryData<TQuery> | undefined, DashboardEmptyMap, TStage>;
+    /** Configured query without a default. `data` is `T | undefined`. */
+    query<TQuery extends DashboardQueryLike, const TParams extends DashboardParamMap = DashboardEmptyMap, TRequired = undefined>(input: DashboardQueryInput<TQuery, TParams, TRequired> & {
+        defaultValue?: undefined;
+    }): DashboardResource<DashboardQueryData<TQuery> | undefined, TParams, TStage>;
+    /**
+     * Configured query with a default. `data` is always defined. The default is inferred on its own
+     * (so property order inside the object does not matter) and checked against the query result: a
+     * mismatching default turns the resource into a `DashboardKeyError`, rejected by `queries`.
+     */
+    query<TQuery extends DashboardQueryLike, const TParams extends DashboardParamMap = DashboardEmptyMap, TRequired = undefined, TDefault = never>(input: DashboardQueryInput<TQuery, TParams, TRequired> & {
+        defaultValue: TDefault;
+    }): [TDefault] extends [DashboardQueryData<TQuery>] ? DashboardResource<DashboardQueryData<TQuery>, TParams, TStage> : DashboardKeyError<'defaultValue is not assignable to the query data type.'>;
+}

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

@@ -0,0 +1,44 @@
+import type { QueryDefinition } from '../../shared/types/query.js';
+import type { LazyTextValue } from '../../shared/types/utils.js';
+import type { DashboardParamBuilder, DashboardParamMap } from './params.js';
+import type { DashboardSourceLike, DashboardStage } from './resource.js';
+/**
+ * Runtime (type-erased) view of the schema. The public schema types carry precise generics; the
+ * runtime reads the same objects through these shapes after one normalization step.
+ */
+export interface DashboardRuntimeQueryInput {
+    params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    requires?: () => unknown;
+    enabled?: () => boolean;
+    query: (scope: {
+        params: object;
+        required: unknown;
+    }) => QueryDefinition;
+    defaultValue?: unknown;
+    keepPreviousData?: boolean;
+    staleTime?: number;
+}
+export interface DashboardRuntimeStage {
+    query: (input: DashboardRuntimeQueryInput | (() => QueryDefinition)) => DashboardSourceLike;
+}
+export type DashboardRuntimeStages = Record<DashboardStage, DashboardRuntimeStage>;
+export interface DashboardRuntimeQueriesContext extends DashboardRuntimeStages {
+    params: object;
+}
+export interface DashboardRuntimeDeriveContext {
+    data: object;
+    params: object;
+}
+export interface DashboardRuntimeScopeInput {
+    label?: LazyTextValue;
+    params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    queries?: (context: DashboardRuntimeQueriesContext) => Record<string, DashboardSourceLike>;
+    derive?: (context: DashboardRuntimeDeriveContext) => Record<string, () => unknown>;
+}
+export interface DashboardRuntimeSchema extends DashboardRuntimeScopeInput {
+    key: string;
+    urlPrefix?: string;
+    autoRefresh?: number;
+    defaultView?: string;
+    views: [key: string, view: DashboardRuntimeScopeInput][];
+}

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

@@ -0,0 +1,171 @@
+import type { LazyTextValue, Prettify } from '../../shared/types/utils.js';
+import type { DashboardOptionsHandles } from './options.js';
+import type { DashboardEmptyMap, DashboardParamBuilder, DashboardParamMap, DashboardParamValues } from './params.js';
+import type { DashboardDerived, DashboardQueryStage, DashboardResourceState, DashboardSourceLike, DashboardSourceMap } from './resource.js';
+/** `derive` entries: each one is a function evaluated reactively into a derived resource. */
+export type DashboardDeriveMap = Record<string, () => unknown>;
+/** Context received by a scope's `queries` builder. */
+export interface DashboardQueriesContext<TParams> {
+    essential: DashboardQueryStage<'essential'>;
+    background: DashboardQueryStage<'background'>;
+    deferred: DashboardQueryStage<'deferred'>;
+    /** Params visible to this scope (shared params plus the view's own params). */
+    params: Readonly<DashboardParamValues<TParams>>;
+}
+/** `data` of every source a `derive` builder can read. */
+export type DashboardSourceData<TSources> = {
+    readonly [K in keyof TSources]: TSources[K] extends DashboardSourceLike<infer TData> ? TData : never;
+};
+/** Context received by a scope's `derive` builder. */
+export interface DashboardDeriveContext<TParams, TSources> {
+    /**
+     * Current data of every query visible to this scope. Reads are tracked: a derived value's
+     * `state` follows the state of the queries it actually read during its last evaluation.
+     */
+    data: DashboardSourceData<TSources>;
+    params: Readonly<DashboardParamValues<TParams>>;
+}
+export type DashboardDerivedResources<TDerive> = {
+    readonly [K in keyof TDerive]: TDerive[K] extends () => infer TResult ? DashboardDerived<TResult> : never;
+};
+/** Params, queries and derived values of one scope (the dashboard root or one view). */
+export interface DashboardScopeInput<TShared extends DashboardParamMap, TVisibleSources, TParams extends DashboardParamMap, TQueries extends DashboardSourceMap, TDerive extends DashboardDeriveMap> {
+    /** Typed, URL-synced params owned by this scope. */
+    params?: (p: DashboardParamBuilder) => TParams;
+    /** Staged queries owned by this scope. Declared once, when `useDashboard()` runs. */
+    queries?: (context: DashboardQueriesContext<TShared & TParams>) => TQueries;
+    /** Derived values computed from query data, exposed as resources with automatic state. */
+    derive?: (context: DashboardDeriveContext<TShared & TParams, TVisibleSources & TQueries>) => TDerive;
+}
+/** Names owned by the runtime on the dashboard root and on every view handle. */
+export type DashboardReservedKey = 'params' | 'options' | 'state' | 'refreshing' | 'refresh' | 'updatedAt' | 'autoRefresh' | 'view' | 'schema';
+declare const DashboardKeyErrorBrand: unique symbol;
+/** Unsatisfiable type. Its hover text is the error message the consumer reads. */
+export interface DashboardKeyError<TMessage extends string> {
+    readonly [DashboardKeyErrorBrand]: TMessage;
+}
+type Guard<TSlot extends string, TBad, TMessage extends string> = [TBad] extends [never] ? unknown : {
+    [K in TSlot]: DashboardKeyError<TMessage>;
+};
+/** Compile-time collision checks for one scope's queries and derived values. */
+export type DashboardScopeGuard<TQueries, TDerive, TTaken = never> = Guard<'queries', Extract<keyof TQueries, DashboardReservedKey | TTaken>, `Query key "${Extract<keyof TQueries, DashboardReservedKey | TTaken> & string}" is reserved or already used.`> & Guard<'derive', Extract<keyof TDerive, DashboardReservedKey | TTaken | keyof TQueries>, `Derived key "${Extract<keyof TDerive, DashboardReservedKey | TTaken | keyof TQueries> & string}" is reserved or already used.`>;
+/** A view declared through the `view(...)` builder. */
+export interface DashboardView<TParams extends DashboardParamMap, TQueries extends DashboardSourceMap, TDerive extends DashboardDeriveMap> {
+    /** Tab label. The lazy form keeps it translation-friendly. */
+    readonly label?: LazyTextValue;
+    readonly params?: (p: DashboardParamBuilder) => TParams;
+    readonly queries?: (context: never) => TQueries;
+    readonly derive?: (context: never) => TDerive;
+}
+export type DashboardViewMap = Record<string, DashboardView<DashboardParamMap, DashboardSourceMap, DashboardDeriveMap>>;
+type DashboardViewResult<TParams extends DashboardParamMap, TQueries extends DashboardSourceMap, TDerive extends DashboardDeriveMap, TRootSources> = [Extract<keyof TQueries | keyof TDerive, DashboardReservedKey | keyof TRootSources>] extends [
+    never
+] ? [Extract<keyof TDerive, keyof TQueries>] extends [never] ? DashboardView<TParams, TQueries, TDerive> : DashboardKeyError<`Derived key "${Extract<keyof TDerive, keyof TQueries> & string}" collides with a query of the same view.`> : DashboardKeyError<`View member "${Extract<keyof TQueries | keyof TDerive, DashboardReservedKey | keyof TRootSources> & string}" is reserved or collides with a root query or derived value.`>;
+/**
+ * Declares one view. Its queries see the shared params plus its own, and its `derive` can read root
+ * queries and derived values as well as its own queries.
+ *
+ * The result is `NoInfer`: otherwise the contextual `DashboardViewMap` would become an inference
+ * candidate, and a view without queries would infer `TQueries` as the open constraint.
+ */
+export type DashboardViewBuilder<TShared extends DashboardParamMap, TRootSources> = <const TParams extends DashboardParamMap = DashboardEmptyMap, const TQueries extends DashboardSourceMap = DashboardEmptyMap, const TDerive extends DashboardDeriveMap = DashboardEmptyMap>(view: {
+    label?: LazyTextValue;
+} & DashboardScopeInput<TShared, TRootSources, TParams, TQueries, TDerive>) => DashboardViewResult<NoInfer<TParams>, NoInfer<TQueries>, NoInfer<TDerive>, TRootSources>;
+/** Resolved dashboard schema returned by `defineDashboardSchema`. */
+export interface DashboardSchema<TParams extends DashboardParamMap = DashboardEmptyMap, TQueries extends DashboardSourceMap = DashboardEmptyMap, TDerive extends DashboardDeriveMap = DashboardEmptyMap, TViews extends DashboardViewMap = DashboardEmptyMap> {
+    /** Stable identity, used in default query keys and devtools labels. */
+    readonly key: string;
+    /** Prefix prepended to every URL key this dashboard owns. Use it when two dashboards share a page. */
+    readonly urlPrefix?: string;
+    /** Default auto-refresh interval in seconds (`0`: off). */
+    readonly autoRefresh?: number;
+    readonly params?: (p: DashboardParamBuilder) => TParams;
+    readonly queries?: (context: never) => TQueries;
+    readonly derive?: (context: never) => TDerive;
+    readonly views?: (view: never) => TViews;
+    readonly defaultView?: keyof TViews & string;
+}
+/** Structural constraint every schema returned by `defineDashboardSchema` satisfies. */
+export interface DashboardSchemaLike {
+    readonly key: string;
+    readonly urlPrefix?: string;
+    readonly autoRefresh?: number;
+    readonly params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    readonly queries?: (context: never) => DashboardSourceMap;
+    readonly derive?: (context: never) => DashboardDeriveMap;
+    readonly views?: (view: never) => DashboardViewMap;
+    readonly defaultView?: string;
+}
+type InferParams<T> = T extends {
+    params?: (p: never) => infer TParams;
+} ? TParams extends DashboardParamMap ? TParams : DashboardEmptyMap : DashboardEmptyMap;
+type InferQueries<T> = T extends {
+    queries?: (context: never) => infer TQueries;
+} ? TQueries extends DashboardSourceMap ? TQueries : DashboardEmptyMap : DashboardEmptyMap;
+type InferDerive<T> = T extends {
+    derive?: (context: never) => infer TDerive;
+} ? TDerive extends DashboardDeriveMap ? TDerive : DashboardEmptyMap : DashboardEmptyMap;
+type InferViews<T> = T extends {
+    views?: (view: never) => infer TViews;
+} ? TViews extends DashboardViewMap ? TViews : DashboardEmptyMap : DashboardEmptyMap;
+/** Runtime members shared by the dashboard root and every view handle. */
+export interface DashboardScopeMembers<TParams> {
+    /** Params owned by this scope. Writable, URL-synced, `v-model`-ready. */
+    readonly params: DashboardParamValues<TParams>;
+    /** Option handles of this scope's option-backed params. */
+    readonly options: DashboardOptionsHandles<TParams>;
+    /**
+     * `idle` while the scope has never been active, `error` if an active essential query failed,
+     * `loading` while essentials load, `ready` once they all succeeded.
+     */
+    readonly state: DashboardResourceState;
+    /** A refresh started by `refresh()` is in flight. */
+    readonly refreshing: boolean;
+    /**
+     * Oldest `updatedAt` among the active queries (the dashboard root also counts the current
+     * view): everything on screen is at least this fresh. `undefined` until one has loaded.
+     */
+    readonly updatedAt: number | undefined;
+    /** Refetches every active query of this scope. */
+    refresh(): Promise<void>;
+}
+export interface DashboardViewMeta<TKey extends string> {
+    readonly key: TKey;
+    readonly label: string;
+    /** The view is the current one. */
+    readonly active: boolean;
+    /** The view has been opened at least once; its queries stay warm afterwards. */
+    readonly opened: boolean;
+}
+export interface DashboardViewController<TKey extends string> {
+    /** Current view. Writable and URL-synced under `view`. */
+    current: TKey;
+    /** Ordered view descriptors, ready for `UTabs` items. */
+    readonly items: readonly {
+        value: TKey;
+        label: string;
+    }[];
+}
+export type DashboardViewHandle<TView, TKey extends string> = Prettify<InferQueries<TView> & DashboardDerivedResources<InferDerive<TView>> & DashboardScopeMembers<InferParams<TView>> & {
+    readonly view: DashboardViewMeta<TKey>;
+}>;
+type DashboardViewHandles<TViews> = {
+    readonly [K in keyof TViews]: DashboardViewHandle<TViews[K], K & string>;
+};
+/** Runtime members of the dashboard root only. */
+export interface DashboardRootMembers {
+    /**
+     * Auto-refresh interval in seconds, `0` when off. Writable and URL-synced under `refresh`. Every
+     * active query refetches on that interval while the page is visible (polling pauses in a
+     * background tab); a query's own `refetchInterval` wins.
+     */
+    autoRefresh: number;
+}
+type DashboardRootViewMembers<TViews> = [keyof TViews] extends [never] ? unknown : {
+    readonly view: DashboardViewController<keyof TViews & string>;
+};
+/** Facade returned by `useDashboard(schema)`. */
+export type DashboardApi<TSchema> = Prettify<InferQueries<TSchema> & DashboardDerivedResources<InferDerive<TSchema>> & DashboardViewHandles<InferViews<TSchema>> & DashboardScopeMembers<InferParams<TSchema>> & DashboardRootMembers & DashboardRootViewMembers<InferViews<TSchema>> & {
+    readonly schema: TSchema;
+}>;
+export {};

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

@@ -0,0 +1,201 @@
+/**
+ * Class overrides for dashboard blocks. Every slot is merged (tailwind-merge) in this order:
+ * library defaults → `appConfig.nuxtUiTools.dashboard` → the block's `ui` prop.
+ */
+/** Card chrome shared by every block. */
+export interface DashboardBlockUi {
+    root?: string;
+    header?: string;
+    title?: string;
+    subtitle?: string;
+    actions?: string;
+    /** Row under the header (`#toolbar` slot). */
+    toolbar?: string;
+    body?: string;
+    footer?: string;
+    /** Row of `actions` placed under the content (`placement: 'footer'`). */
+    footerActions?: string;
+    /** `…` button of the card menu. */
+    menu?: string;
+    /** "Updated 3 min ago" line under the content. */
+    freshness?: string;
+}
+export interface DashboardGridUi {
+    root?: string;
+    /** Container of `variant="panels"` grids: joined cells separated by 1px rules. */
+    panels?: string;
+    /** Card root of blocks placed inside a `panels` grid. */
+    panel?: string;
+}
+export interface DashboardStatUi {
+    /** KPI label, rendered as the card title. */
+    label?: string;
+    value?: string;
+    /** Row under the value: delta, then caption. */
+    meta?: string;
+    delta?: string;
+    /** `▲` / `▼` before the delta. */
+    mark?: string;
+    caption?: string;
+    /** Colored dot and label of `status`, on the title row. */
+    status?: string;
+    /** Sparkline of `trend`. */
+    trend?: string;
+    /** Track of the `goal` progress bar. */
+    progress?: string;
+    /** Line under the progress bar: goal and completion. */
+    goal?: string;
+}
+export interface DashboardStatsUi {
+    /** Grid of the figures. */
+    grid?: string;
+    item?: string;
+    /** Icon tile before the label. */
+    icon?: string;
+    label?: string;
+    value?: string;
+    /** Row under the value: delta, then caption. */
+    meta?: string;
+    delta?: string;
+    caption?: string;
+    /** Track of the `progress` bar. */
+    progress?: string;
+    /** Badge of `status`. */
+    status?: string;
+}
+export interface DashboardGaugeUi {
+    /** Ring and its centered text. */
+    ring?: string;
+    value?: string;
+    /** Text under the value, inside the ring. */
+    caption?: string;
+    /** Line under the ring: min / target / max. */
+    scale?: string;
+}
+export interface DashboardAlertsUi {
+    row?: string;
+    /** Severity icon tile. */
+    icon?: string;
+    label?: string;
+    description?: string;
+    value?: string;
+    action?: string;
+}
+export interface DashboardFeedUi {
+    /** Day heading when `groupBy` is set. */
+    group?: string;
+    item?: string;
+    /** Icon, avatar, or dot on the timeline rail. */
+    marker?: string;
+    label?: string;
+    description?: string;
+    time?: string;
+}
+export interface DashboardTableUi {
+    /** Scroll container around the table. */
+    wrapper?: string;
+    table?: string;
+    head?: string;
+    /** Header cells. */
+    th?: string;
+    row?: string;
+    /** Body cells. */
+    td?: string;
+    /** Inline bar of `bar` columns. */
+    bar?: string;
+}
+export interface DashboardLegendUi {
+    root?: string;
+    item?: string;
+    swatch?: string;
+}
+export interface DashboardTotalUi {
+    root?: string;
+    label?: string;
+    value?: string;
+}
+export interface DashboardListUi {
+    row?: string;
+    avatar?: string;
+    code?: string;
+    /** Progress ring of `leading: 'ring'`. */
+    ring?: string;
+    label?: string;
+    description?: string;
+    share?: string;
+    delta?: string;
+    value?: string;
+}
+export interface DashboardBarsUi {
+    row?: string;
+    label?: string;
+    tag?: string;
+    meta?: string;
+    track?: string;
+    fill?: string;
+}
+export interface DashboardPairedBarsUi {
+    row?: string;
+    label?: string;
+    track?: string;
+    value?: string;
+}
+export interface DashboardFunnelUi {
+    step?: string;
+    label?: string;
+    value?: string;
+    note?: string;
+    track?: string;
+}
+export interface DashboardStackBarUi {
+    track?: string;
+    legend?: string;
+    item?: string;
+}
+export interface DashboardDonutUi {
+    legend?: string;
+    item?: string;
+    /** Big value in the middle of the ring. */
+    center?: string;
+    centerLabel?: string;
+}
+export interface DashboardStateUi {
+    root?: string;
+    icon?: string;
+    title?: string;
+    description?: string;
+}
+/**
+ * App-wide dashboard theming, read from `appConfig.nuxtUiTools.dashboard`.
+ *
+ * @example
+ * ```ts
+ * export default defineAppConfig({
+ *   nuxtUiTools: {
+ *     dashboard: {
+ *       card: { root: 'px-6 py-5', title: 'font-semibold' },
+ *       stat: { value: 'font-light tracking-tight' },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export interface DashboardUiConfig {
+    card?: DashboardBlockUi;
+    grid?: DashboardGridUi;
+    stat?: DashboardStatUi;
+    stats?: DashboardStatsUi;
+    gauge?: DashboardGaugeUi;
+    legend?: DashboardLegendUi;
+    total?: DashboardTotalUi;
+    list?: DashboardListUi;
+    bars?: DashboardBarsUi;
+    pairedBars?: DashboardPairedBarsUi;
+    funnel?: DashboardFunnelUi;
+    stackBar?: DashboardStackBarUi;
+    donut?: DashboardDonutUi;
+    alerts?: DashboardAlertsUi;
+    feed?: DashboardFeedUi;
+    table?: DashboardTableUi;
+    state?: DashboardStateUi;
+}

package/dist/runtime/dashboard/utils/builders/dashboard-params.d.ts

@@ -0,0 +1,85 @@
+import type { QueryCodec } from '../../../query-state/index.js';
+import type { DashboardComparison, DashboardDateRange, DashboardOption, DashboardOptionValue, DashboardParamDefinition, DashboardParamOptions, DashboardRemoteOptionsConfig } from '../../types/index.js';
+type ResolveParamValue<TValue, TDefault> = undefined extends TDefault ? TValue | undefined : TValue;
+declare function stringParam<const TDefault extends string | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<string, TDefault>> & {
+    readonly kind: 'string';
+};
+declare function numberParam<const TDefault extends number | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<number, TDefault>> & {
+    readonly kind: 'number';
+};
+declare function booleanParam<const TDefault extends boolean | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<boolean, TDefault>> & {
+    readonly kind: 'boolean';
+};
+declare function dateParam<const TDefault extends Date | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<Date, TDefault>> & {
+    readonly kind: 'date';
+};
+declare function dateRangeParam<const TDefault extends DashboardDateRange | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<DashboardDateRange, TDefault>> & {
+    readonly kind: 'dateRange';
+};
+declare function enumParam<const TValues extends readonly DashboardOptionValue[]>(values: TValues, options: DashboardParamOptions<readonly TValues[number][]> & {
+    multiple: true;
+}): DashboardParamDefinition<TValues[number][]> & {
+    readonly kind: 'enum';
+};
+declare function enumParam<const TValues extends readonly DashboardOptionValue[], const TDefault extends TValues[number] | undefined = undefined>(values: TValues, options?: DashboardParamOptions<TDefault> & {
+    multiple?: false;
+}): DashboardParamDefinition<ResolveParamValue<TValues[number], TDefault>> & {
+    readonly kind: 'enum';
+};
+declare function optionsParam<const TItems extends readonly DashboardOption[]>(items: TItems, options: DashboardParamOptions<readonly TItems[number]['value'][]> & {
+    multiple: true;
+}): DashboardParamDefinition<TItems[number]['value'][]> & {
+    readonly kind: 'options';
+};
+declare function optionsParam<const TItems extends readonly DashboardOption[], const TDefault extends TItems[number]['value'] | undefined = undefined>(items: TItems, options?: DashboardParamOptions<TDefault> & {
+    multiple?: false;
+}): DashboardParamDefinition<ResolveParamValue<TItems[number]['value'], TDefault>> & {
+    readonly kind: 'options';
+};
+declare function remoteParam(config: DashboardRemoteOptionsConfig & DashboardParamOptions<readonly string[]> & {
+    multiple: true;
+}): DashboardParamDefinition<string[]> & {
+    readonly kind: 'remote';
+};
+declare function remoteParam<const TDefault extends string | undefined = undefined>(config: DashboardRemoteOptionsConfig & DashboardParamOptions<TDefault> & {
+    multiple?: false;
+}): DashboardParamDefinition<ResolveParamValue<string, TDefault>> & {
+    readonly kind: 'remote';
+};
+/** Values of `p.comparison`, in menu order. */
+export declare const DASHBOARD_COMPARISONS: readonly ["previous", "year", "none"];
+declare function comparisonParam<const TDefault extends DashboardComparison | undefined = undefined>(options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<DashboardComparison, TDefault>> & {
+    readonly kind: 'comparison';
+};
+declare function customParam<TValue, const TDefault extends TValue | undefined = undefined>(codec: QueryCodec<TValue>, options?: DashboardParamOptions<TDefault>): DashboardParamDefinition<ResolveParamValue<TValue, TDefault>> & {
+    readonly kind: 'custom';
+};
+/**
+ * The `p` builder handed to every `params` callback. Each method declares one typed, URL-synced
+ * param; the engine renders no controls, the app binds `v-model` to the resulting value.
+ *
+ * Every param accepts `defaultValue` (narrows away `undefined`), `urlKey`, `omitDefault`, and
+ * `historyMode`. Option-backed params (`enum`, `options`, `remote`) also accept `multiple: true`,
+ * which turns the value into an always-defined array.
+ */
+export declare const dashboardParamBuilder: {
+    boolean: typeof booleanParam;
+    /**
+     * Comparison period: `'previous'`, `'year'`, or `'none'`. Its option handle carries localized
+     * labels; `resolveDashboardComparisonRange(range, mode)` turns it into the range to fetch.
+     */
+    comparison: typeof comparisonParam;
+    custom: typeof customParam;
+    date: typeof dateParam;
+    /** Inclusive date range, serialized as `YYYY-MM-DD..YYYY-MM-DD`. */
+    dateRange: typeof dateRangeParam;
+    /** Value(s) from a literal list, e.g. `p.enum([2024, 2025, 2026], { defaultValue: 2026 })`. */
+    enum: typeof enumParam;
+    number: typeof numberParam;
+    /** Value(s) from labeled items: `{ value, label, icon?, avatar?, description? }`. */
+    options: typeof optionsParam;
+    /** Id(s) picked from a remote, searchable, paginated option source. */
+    remote: typeof remoteParam;
+    string: typeof stringParam;
+};
+export {};