nuxt-ui-tools 1.1.0 → 1.3.0

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

@@ -1,6 +1,6 @@
 import type { QueryKey } from '@tanstack/vue-query';
-import type { DashboardOptionsHandles } from './options.js';
-import type { DashboardEmptyMap, DashboardParamBuilder, DashboardParamMap, DashboardParamValues } from './params.js';
+import type { DashboardFilterControls } from './controls.js';
+import type { DashboardEmptyMap, DashboardFilterMap, DashboardFilterValues, DashboardFiltersInput } from './filters.js';
 import type { DashboardKeyError } from './schema.js';
 /**
  * Fetch stage of a query.
@@ -11,7 +11,18 @@ import type { DashboardKeyError } from './schema.js';
  *   scroll into view).
  */
 export type DashboardStage = 'essential' | 'background' | 'deferred';
-export type DashboardResourceState = 'idle' | 'loading' | 'ready' | 'error';
+/**
+ * - `idle`: not requested yet (a deferred query nobody activated, an unopened view).
+ * - `loading` / `ready` / `error`: the fetch lifecycle.
+ * - `disabled`: an `enabled` condition does not hold (its own, or its view's). The resource never
+ *   fetches and holds its `defaultValue`; blocks bound to it render nothing.
+ */
+export type DashboardResourceState = 'idle' | 'loading' | 'ready' | 'error' | 'disabled';
+/**
+ * Whether a view, query, or filter is part of the dashboard right now, read lazily and reactively:
+ * what the schema function knows (the audience), another filter, data.
+ */
+export type DashboardCondition = () => boolean;
 /**
  * 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`.
@@ -24,6 +35,13 @@ export interface DashboardSourceLike<TData = unknown> {
     readonly error: unknown;
     /** A background refetch is running while `state` is still `'ready'`. */
     readonly refreshing: boolean;
+    /**
+     * A request for this source is in flight, whatever its state: the first load, a refetch of shown
+     * data, or a retry after an error (TanStack keeps an errored query in `error` while it refetches).
+     * Blocks draw their progress bar from it. Optional so hand-written sources keep fitting; blocks
+     * fall back to `refreshing`.
+     */
+    readonly fetching?: boolean;
     /**
      * When the data was last fetched successfully (epoch milliseconds). `undefined` until the first
      * success. A derived value reports its oldest input.
@@ -34,19 +52,21 @@ export interface DashboardSourceLike<TData = unknown> {
     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> {
+export interface DashboardResource<TData, TFilters extends DashboardFilterMap = DashboardEmptyMap, TStage extends DashboardStage = DashboardStage> extends DashboardSourceLike<TData> {
     readonly kind: 'query';
+    readonly fetching: boolean;
     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>;
+    /** Values of the filters declared on this query, URL-synced under the query key. */
+    readonly filters: DashboardFilterValues<TFilters>;
+    /** Controls of the same filters: bind them to a chart's `series`, `UiDashboardFilter`, or any control. */
+    readonly controls: DashboardFilterControls<TFilters>;
 }
 /** 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';
+    readonly fetching: boolean;
 }
 export type DashboardSourceMap = Record<string, DashboardSourceLike>;
 /** Data of a source once it is `ready` (`undefined` is excluded, `null` is kept). */
@@ -62,25 +82,42 @@ 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>>;
+export interface DashboardQueryScope<TFilters extends DashboardFilterMap, TRequired> {
+    /** Values of the filters declared on this query. */
+    filters: Readonly<DashboardFilterValues<TFilters>>;
     /** 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;
+export interface DashboardQueryInput<TQuery extends DashboardQueryLike, TFilters extends DashboardFilterMap, TRequired, TSelected> {
+    /**
+     * Filters of this query only, e.g. the products a chart tracks, URL-synced under
+     * `<queryKey>.<filter>`. Their controls drive the block bound to the query.
+     */
+    filters?: DashboardFiltersInput<TFilters>;
     /**
-     * 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.
+     * Gate and narrow. While it returns `null` or `undefined` the query does not fetch; once set,
+     * `scope.required` is the non-nullish value. Reading another resource's `data` here expresses a
+     * dependent query: the resource is `loading` while the resources it read load, and once they
+     * are ready without satisfying it, `ready` with its `defaultValue` (`idle` without one).
      */
     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;
+    /**
+     * Whether the query exists for the current dashboard state, e.g. a section this workspace may
+     * not see. While it is `false` the query never fetches, its state is `disabled` and its data its
+     * `defaultValue`, and every block bound to it renders nothing (grids close the gap). To wait for
+     * data instead, use `requires`.
+     */
+    enabled?: DashboardCondition;
+    /**
+     * Reactive query factory returning a TanStack query definition. Several resources may share one
+     * factory: they share its request and cache entry, and each `select`s its own part.
+     */
+    query: (scope: DashboardQueryScope<NoInfer<TFilters>, NoInfer<TRequired>>) => TQuery;
+    /**
+     * Picks or reshapes the part of the query result this resource exposes. The cached result stays
+     * whole, so resources selecting from the same query never refetch it.
+     */
+    select?: (data: DashboardQueryData<TQuery>) => TSelected;
     /** Keep previous data while a new key loads. Defaults to `true`. */
     keepPreviousData?: boolean;
     staleTime?: number;
@@ -91,16 +128,17 @@ export interface DashboardQueryInput<TQuery extends DashboardQueryLike, TParams
 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> & {
+    /** Configured query without a default. `data` is `T | undefined` (`T`: the `select` result). */
+    query<TQuery extends DashboardQueryLike, const TFilters extends DashboardFilterMap = DashboardEmptyMap, TRequired = undefined, TSelected = DashboardQueryData<TQuery>>(input: DashboardQueryInput<TQuery, TFilters, TRequired, TSelected> & {
         defaultValue?: undefined;
-    }): DashboardResource<DashboardQueryData<TQuery> | undefined, TParams, TStage>;
+    }): DashboardResource<NoInfer<TSelected> | undefined, TFilters, 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`.
+     * (so property order inside the object does not matter) and checked against the query result (or
+     * the `select` 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> & {
+    query<TQuery extends DashboardQueryLike, const TFilters extends DashboardFilterMap = DashboardEmptyMap, TRequired = undefined, TSelected = DashboardQueryData<TQuery>, TDefault = never>(input: DashboardQueryInput<TQuery, TFilters, TRequired, TSelected> & {
         defaultValue: TDefault;
-    }): [TDefault] extends [DashboardQueryData<TQuery>] ? DashboardResource<DashboardQueryData<TQuery>, TParams, TStage> : DashboardKeyError<'defaultValue is not assignable to the query data type.'>;
+    }): [TDefault] extends [NoInfer<TSelected>] ? DashboardResource<NoInfer<TSelected>, TFilters, TStage> : DashboardKeyError<'defaultValue is not assignable to the query data type.'>;
 }

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

@@ -1,19 +1,23 @@
+import type { ComputedRef, Ref } from 'vue';
 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';
+import type { DashboardOptionsMenuBindings } from './controls.js';
+import type { DashboardFilterBuilder, DashboardFilterLike, DashboardOption } from './filters.js';
+import type { DashboardCondition, 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 type DashboardRuntimeFiltersInput = (f: DashboardFilterBuilder) => Record<string, DashboardFilterLike>;
 export interface DashboardRuntimeQueryInput {
-    params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    filters?: DashboardRuntimeFiltersInput;
     requires?: () => unknown;
-    enabled?: () => boolean;
+    enabled?: DashboardCondition;
     query: (scope: {
-        params: object;
+        filters: object;
         required: unknown;
     }) => QueryDefinition;
+    select?: (data: unknown) => unknown;
     defaultValue?: unknown;
     keepPreviousData?: boolean;
     staleTime?: number;
@@ -23,15 +27,17 @@ export interface DashboardRuntimeStage {
 }
 export type DashboardRuntimeStages = Record<DashboardStage, DashboardRuntimeStage>;
 export interface DashboardRuntimeQueriesContext extends DashboardRuntimeStages {
-    params: object;
+    filters: object;
 }
 export interface DashboardRuntimeDeriveContext {
     data: object;
-    params: object;
+    filters: object;
 }
 export interface DashboardRuntimeScopeInput {
     label?: LazyTextValue;
-    params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    /** Availability of a view. */
+    enabled?: DashboardCondition;
+    filters?: DashboardRuntimeFiltersInput;
     queries?: (context: DashboardRuntimeQueriesContext) => Record<string, DashboardSourceLike>;
     derive?: (context: DashboardRuntimeDeriveContext) => Record<string, () => unknown>;
 }
@@ -40,5 +46,30 @@ export interface DashboardRuntimeSchema extends DashboardRuntimeScopeInput {
     urlPrefix?: string;
     autoRefresh?: number;
     defaultView?: string;
+    /** Views in declaration order. Each input is the object the schema declared. */
     views: [key: string, view: DashboardRuntimeScopeInput][];
 }
+/**
+ * Option list behind one filter control, static or remote. Both option composables return this
+ * shape so the control composes either without branching.
+ */
+export interface DashboardRuntimeOptionList {
+    /** Options matching the current search. */
+    items: ComputedRef<readonly DashboardOption[]>;
+    /** Every option known so far (all static items; loaded pages and hydrated values), by value key. */
+    known: ComputedRef<ReadonlyMap<string, DashboardOption>>;
+    /** Position of each static option, used to keep multiple values in item order. */
+    order: ComputedRef<ReadonlyMap<string, number> | null>;
+    loading: ComputedRef<boolean>;
+    loadingMore: ComputedRef<boolean>;
+    hasMore: ComputedRef<boolean>;
+    error: ComputedRef<unknown>;
+    /** Labels of selected values are being fetched. */
+    resolving: ComputedRef<boolean>;
+    search: Ref<string>;
+    open: Ref<boolean>;
+    loadMore: () => void;
+    refresh: () => Promise<void>;
+    /** Menu bindings beyond items and keys (search wiring of remote lists). */
+    menu: ComputedRef<Partial<DashboardOptionsMenuBindings>>;
+}

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

@@ -1,44 +1,47 @@
 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';
+import type { DashboardFilterControls } from './controls.js';
+import type { DashboardEmptyMap, DashboardFilterBuilder, DashboardFilterLike, DashboardFilterMap, DashboardFiltersInput, DashboardFilterValues } from './filters.js';
+import type { DashboardCondition, 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> {
+export interface DashboardQueriesContext<TFilters> {
     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>>;
+    /** Values of the scope's filters. */
+    filters: Readonly<DashboardFilterValues<TFilters>>;
 }
 /** `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> {
+export interface DashboardDeriveContext<TFilters, 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.
+     * Current data of every query of 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>>;
+    filters: Readonly<DashboardFilterValues<TFilters>>;
 }
 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;
+/** Filters, queries and derived values of one scope (the dashboard root or one view). */
+export interface DashboardScopeInput<TFilters extends DashboardFilterMap, TQueries extends DashboardSourceMap, TDerive extends DashboardDeriveMap> {
+    /**
+     * Filters of this scope, declared inline with the `f` builder. A filter key names one state across
+     * the dashboard: two views declaring `year` share its value, so it survives a tab change.
+     */
+    filters?: DashboardFiltersInput<TFilters>;
+    /** Staged queries of this scope. Declared once, when `useDashboard()` runs. */
+    queries?: (context: DashboardQueriesContext<TFilters>) => TQueries;
     /** Derived values computed from query data, exposed as resources with automatic state. */
-    derive?: (context: DashboardDeriveContext<TShared & TParams, TVisibleSources & TQueries>) => TDerive;
+    derive?: (context: DashboardDeriveContext<TFilters, 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';
+export type DashboardReservedKey = 'filters' | 'controls' | 'filtered' | 'resetFilters' | '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> {
@@ -49,40 +52,31 @@ type Guard<TSlot extends string, TBad, TMessage extends string> = [TBad] extends
 };
 /** 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> {
+/** A view (tab): its label, its own filters, queries and derived values. */
+export interface DashboardView<TFilters extends DashboardFilterMap, TQueries extends DashboardSourceMap, TDerive extends DashboardDeriveMap> {
     /** Tab label. The lazy form keeps it translation-friendly. */
     readonly label?: LazyTextValue;
-    readonly params?: (p: DashboardParamBuilder) => TParams;
+    /** Availability of the view (see `defineDashboardView`). */
+    readonly enabled?: DashboardCondition;
+    readonly filters?: (f: DashboardFilterBuilder) => TFilters;
     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>;
+/** Loosest filters input, for structural constraints. */
+type DashboardFiltersLike = (f: DashboardFilterBuilder) => Record<string, DashboardFilterLike>;
+export type DashboardViewMap = Record<string, DashboardView<DashboardFilterMap, DashboardSourceMap, DashboardDeriveMap>>;
 /** 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> {
+export interface DashboardSchema<TFilters extends DashboardFilterMap = 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 filters?: (f: DashboardFilterBuilder) => TFilters;
     readonly queries?: (context: never) => TQueries;
     readonly derive?: (context: never) => TDerive;
-    readonly views?: (view: never) => TViews;
+    readonly views?: TViews;
     readonly defaultView?: keyof TViews & string;
 }
 /** Structural constraint every schema returned by `defineDashboardSchema` satisfies. */
@@ -90,15 +84,34 @@ export interface DashboardSchemaLike {
     readonly key: string;
     readonly urlPrefix?: string;
     readonly autoRefresh?: number;
-    readonly params?: (p: DashboardParamBuilder) => DashboardParamMap;
+    readonly filters?: DashboardFiltersLike;
     readonly queries?: (context: never) => DashboardSourceMap;
     readonly derive?: (context: never) => DashboardDeriveMap;
-    readonly views?: (view: never) => DashboardViewMap;
+    readonly views?: DashboardViewMap;
     readonly defaultView?: string;
 }
-type InferParams<T> = T extends {
-    params?: (p: never) => infer TParams;
-} ? TParams extends DashboardParamMap ? TParams : DashboardEmptyMap : DashboardEmptyMap;
+/** Structural constraint every view returned by `defineDashboardView` satisfies. */
+export interface DashboardViewLike {
+    readonly label?: LazyTextValue;
+    readonly enabled?: DashboardCondition;
+    readonly filters?: DashboardFiltersLike;
+    readonly queries?: (context: never) => DashboardSourceMap;
+    readonly derive?: (context: never) => DashboardDeriveMap;
+}
+/**
+ * A schema, or a function returning one: `salesSchema`, `accountSchema` (which takes the account),
+ * `() => accountSchema({ accountId })`.
+ */
+export type DashboardSchemaInput = DashboardSchemaLike | ((...args: never[]) => DashboardSchemaLike);
+/** The schema a `DashboardSchemaInput` describes: the object, or what the function returns. */
+export type DashboardSchemaOf<TInput> = TInput extends (...args: never[]) => infer TSchema ? TSchema : TInput;
+/** A view, or a function returning one: `consumptionView` (which takes the workspace). */
+export type DashboardViewInput = DashboardViewLike | ((...args: never[]) => DashboardViewLike);
+/** The view a `DashboardViewInput` describes: the object, or what the function returns. */
+export type DashboardViewOf<TInput> = TInput extends (...args: never[]) => infer TView ? TView : TInput;
+type InferFilters<T> = T extends {
+    filters?: (f: never) => infer TFilters;
+} ? TFilters extends DashboardFilterMap ? TFilters : DashboardEmptyMap : DashboardEmptyMap;
 type InferQueries<T> = T extends {
     queries?: (context: never) => infer TQueries;
 } ? TQueries extends DashboardSourceMap ? TQueries : DashboardEmptyMap : DashboardEmptyMap;
@@ -106,14 +119,24 @@ 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;
+    views?: infer TViews;
+} ? Exclude<TViews, undefined> extends DashboardViewMap ? Exclude<TViews, undefined> : 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>;
+export interface DashboardScopeMembers<TFilters> {
+    /** Values of the scope's filters. Writable, `v-model`-ready: `consumption.filters.year`. */
+    readonly filters: DashboardFilterValues<TFilters>;
+    /**
+     * Controls of the same filters: label, display text, option list, and the `toggle` / `reset`
+     * actions. Bind them to `UiDashboardFilter`, a chart's `series`, or any control.
+     */
+    readonly controls: DashboardFilterControls<TFilters>;
+    /**
+     * A filter on screen differs from its default: the root's and the current view's for the
+     * dashboard, the view's own for a view handle. Headless filters are ignored.
+     */
+    readonly filtered: boolean;
+    /** Restores the default of every filter `filtered` considers. */
+    resetFilters(): void;
     /**
      * `idle` while the scope has never been active, `error` if an active essential query failed,
      * `loading` while essentials load, `ready` once they all succeeded.
@@ -134,19 +157,26 @@ export interface DashboardViewMeta<TKey extends string> {
     readonly label: string;
     /** The view is the current one. */
     readonly active: boolean;
+    /** The view's `enabled` condition holds. A disabled view has no tab and cannot be current. */
+    readonly enabled: 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 view. Writable and URL-synced under `view`. Always an enabled view: a URL naming a
+     * disabled one reads as the default view (or the first enabled), and writing a disabled view is
+     * ignored.
+     */
     current: TKey;
-    /** Ordered view descriptors, ready for `UTabs` items. */
+    /** Enabled views in declaration order, 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>> & {
+/** Handle of one view: its queries, derived values and filters (`consumption.filters.year`). */
+export type DashboardViewHandle<TView, TKey extends string> = Prettify<InferQueries<TView> & DashboardDerivedResources<InferDerive<TView>> & DashboardScopeMembers<InferFilters<TView>> & {
     readonly view: DashboardViewMeta<TKey>;
 }>;
 type DashboardViewHandles<TViews> = {
@@ -165,7 +195,17 @@ 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>> & {
+export type DashboardApi<TSchema> = Prettify<InferQueries<TSchema> & DashboardDerivedResources<InferDerive<TSchema>> & DashboardViewHandles<InferViews<TSchema>> & DashboardScopeMembers<InferFilters<TSchema>> & DashboardRootMembers & DashboardRootViewMembers<InferViews<TSchema>> & {
     readonly schema: TSchema;
 }>;
+/**
+ * Type of the dashboard `useDashboard` returns, for props and helpers:
+ * `InferDashboard<typeof accountSchema>` (a schema function) or `InferDashboard<typeof salesSchema>`.
+ */
+export type InferDashboard<TInput> = DashboardApi<DashboardSchemaOf<TInput>>;
+/**
+ * Type of the handle `useDashboardView` returns: `InferDashboardView<typeof consumptionView>` (a
+ * view function) or the type of a view object.
+ */
+export type InferDashboardView<TInput> = DashboardViewHandle<DashboardViewOf<TInput>, string>;
 export {};

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

@@ -165,6 +165,79 @@ export interface DashboardStateUi {
     title?: string;
     description?: string;
 }
+/** Classes of `UiDashboardFilter`: the pill, its menu, and the `button` variant. */
+export interface DashboardFilterUi {
+    /** Pill around the trigger and the clear button. Carries `data-active` once the filter filters. */
+    root?: string;
+    trigger?: string;
+    /** Filter name, before the value. */
+    label?: string;
+    value?: string;
+    chevron?: string;
+    /** Clear button of an active pill. */
+    clear?: string;
+    /** Trigger of `variant="button"`. */
+    button?: string;
+    /** Popover panel. */
+    content?: string;
+    /** Heading of the panel (`variant="button"`). */
+    title?: string;
+    search?: string;
+    list?: string;
+    item?: string;
+    /** Checkbox of multiple filters. */
+    check?: string;
+    /** Check mark of the selected item of single filters. */
+    tick?: string;
+    /** Initials tile of items with an `avatar`. */
+    avatar?: string;
+    /** Trailing text of items with a `hint`. */
+    hint?: string;
+    separator?: string;
+    /** "No results", loading, and error rows. */
+    note?: string;
+}
+/** Classes of `UiDashboardFilters`. */
+export interface DashboardFiltersUi {
+    /** The bar: a row that scrolls sideways on narrow screens and wraps on large ones. */
+    root?: string;
+    reset?: string;
+}
+/**
+ * Classes of the chips a block draws in its toolbar: the series a filter picks on a chart, and the
+ * drill-down filters (`filters`) a block is narrowed by.
+ */
+export interface DashboardChipsUi {
+    chip?: string;
+    /** Color square of a series chip. */
+    swatch?: string;
+    /** Filter name, before its value, on a filter chip. */
+    label?: string;
+    remove?: string;
+}
+/** Classes of `UiDashboardPage`. */
+export interface DashboardPageUi {
+    /** The page, and its scroll container: the tabs and filters stick to its top. */
+    root?: string;
+    header?: string;
+    title?: string;
+    /** Today's date and when the data was fetched, under the title. */
+    description?: string;
+    /** Page actions and the refresh control. */
+    actions?: string;
+    /** Pinned band of the tabs and the filter bar. Carries `data-stuck` once content scrolls under it. */
+    toolbar?: string;
+    tabs?: string;
+    filters?: string;
+    /** Around the current view: its padding and the space between its grids. */
+    body?: string;
+}
+/** Classes of `UiDashboardViewTabs`. */
+export interface DashboardViewTabsUi {
+    /** The strip: it scrolls sideways when the tabs overflow. */
+    root?: string;
+    tab?: string;
+}
 /**
  * App-wide dashboard theming, read from `appConfig.nuxtUiTools.dashboard`.
  *
@@ -198,4 +271,9 @@ export interface DashboardUiConfig {
     feed?: DashboardFeedUi;
     table?: DashboardTableUi;
     state?: DashboardStateUi;
+    filter?: DashboardFilterUi;
+    filters?: DashboardFiltersUi;
+    viewTabs?: DashboardViewTabsUi;
+    page?: DashboardPageUi;
+    chips?: DashboardChipsUi;
 }