nuxt-ui-tools 1.2.0 → 1.4.0

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

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

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

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

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

@@ -1,85 +0,0 @@
-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 {};

package/dist/runtime/dashboard/utils/builders/dashboard-params.js

@@ -1,87 +0,0 @@
-import {
-  createListCodec,
-  createOptionValueCodec,
-  createSafeCodec,
-  dateRangeCodec,
-  localDateCodec,
-  optionalBooleanCodec,
-  optionalNumberCodec,
-  optionalStringCodec
-} from "../params/codecs.js";
-function defineParam(kind, codec, options = {}) {
-  const multiple = options.multiple === true;
-  return {
-    codec: multiple ? createListCodec(codec) : codec,
-    defaultValue: options.defaultValue ?? (multiple ? [] : void 0),
-    historyMode: options.historyMode,
-    items: options.items,
-    kind,
-    multiple,
-    omitDefault: options.omitDefault,
-    remote: options.remote,
-    urlKey: options.urlKey
-  };
-}
-function stringParam(options) {
-  return defineParam("string", optionalStringCodec, options);
-}
-function numberParam(options) {
-  return defineParam("number", optionalNumberCodec, options);
-}
-function booleanParam(options) {
-  return defineParam("boolean", optionalBooleanCodec, options);
-}
-function dateParam(options) {
-  return defineParam("date", localDateCodec, options);
-}
-function dateRangeParam(options) {
-  return defineParam("dateRange", dateRangeCodec, options);
-}
-function enumParam(values, options) {
-  const items = values.map((value) => ({ label: String(value), value }));
-  return defineParam("enum", createOptionValueCodec(values), { ...options, items });
-}
-function optionsParam(items, options) {
-  const codec = createOptionValueCodec(items.map((item) => item.value));
-  return defineParam("options", codec, { ...options, items });
-}
-function remoteParam(config) {
-  const { load, pagination, queryKey, resolveSelected, search, ...options } = config;
-  const remote = { load, pagination, queryKey, resolveSelected, search };
-  return defineParam("remote", optionalStringCodec, { ...options, remote });
-}
-export const DASHBOARD_COMPARISONS = [
-  "previous",
-  "year",
-  "none"
-];
-function comparisonParam(options) {
-  const items = DASHBOARD_COMPARISONS.map((value) => ({ label: value, value }));
-  return defineParam("comparison", createOptionValueCodec(DASHBOARD_COMPARISONS), {
-    ...options,
-    items
-  });
-}
-function customParam(codec, options) {
-  return defineParam("custom", createSafeCodec(codec), options);
-}
-export const dashboardParamBuilder = {
-  boolean: booleanParam,
-  /**
-   * Comparison period: `'previous'`, `'year'`, or `'none'`. Its option handle carries localized
-   * labels; `resolveDashboardComparisonRange(range, mode)` turns it into the range to fetch.
-   */
-  comparison: comparisonParam,
-  custom: customParam,
-  date: dateParam,
-  /** Inclusive date range, serialized as `YYYY-MM-DD..YYYY-MM-DD`. */
-  dateRange: dateRangeParam,
-  /** Value(s) from a literal list, e.g. `p.enum([2024, 2025, 2026], { defaultValue: 2026 })`. */
-  enum: enumParam,
-  number: numberParam,
-  /** Value(s) from labeled items: `{ value, label, icon?, avatar?, description? }`. */
-  options: optionsParam,
-  /** Id(s) picked from a remote, searchable, paginated option source. */
-  remote: remoteParam,
-  string: stringParam
-};