nuxt-ui-tools 1.2.0 → 1.3.0

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

@@ -0,0 +1,142 @@
+import type { QueryCodec } from '../../../query-state/index.js';
+import type { DashboardComparison, DashboardDateRange, DashboardOption, DashboardOptionValue, DashboardFilterDefault, DashboardFilterDefinition, DashboardFilterFormatOptions, DashboardFilterListOptions, DashboardFilterMultipleOptions, DashboardFilterOptions, DashboardRemoteOptionsConfig } from '../../types/index.js';
+/** Options of a single-value filter whose values carry no label of their own. */
+type SingleOptions<TValue> = DashboardFilterOptions<DashboardFilterDefault<TValue>, TValue> & DashboardFilterFormatOptions<TValue> & {
+    multiple?: false;
+};
+/** Options of a `multiple` filter: the value is an always-defined array. */
+type MultipleOptions<TItem> = DashboardFilterOptions<DashboardFilterDefault<readonly TItem[]>, TItem[]> & DashboardFilterMultipleOptions & {
+    multiple: true;
+};
+/** Options of a filter holding one value, or a list with `multiple: true`. */
+type FilterOptions<TItem> = SingleOptions<TItem> | (MultipleOptions<TItem> & DashboardFilterFormatOptions<TItem>);
+/** The same, for filters picked from a list. */
+type ListFilterOptions<TItem> = FilterOptions<TItem> & DashboardFilterListOptions;
+/** Options of filters whose items carry their own labels (`f.options`, `f.remote`). */
+type LabeledFilterOptions<TItem> = ((DashboardFilterOptions<DashboardFilterDefault<TItem>, TItem> & {
+    multiple?: false;
+}) | MultipleOptions<TItem>) & DashboardFilterListOptions;
+/**
+ * Value of a filter declared with `TOptions`: an array with `multiple: true`; otherwise defined once
+ * a default is declared (a value, or a getter that never returns `undefined`).
+ *
+ * Builders infer the whole options object rather than overloading on its shape: every overload
+ * would contextually type a default or presets getter on its own, and the first one tried fixes
+ * the getter's result (widening `() => 2026` to `() => number`).
+ */
+type FilterValue<TItem, TOptions> = TOptions extends {
+    multiple: true;
+} ? TItem[] : TOptions extends {
+    defaultValue: infer TDefault;
+} ? undefined extends (TDefault extends () => infer TResult ? TResult : TDefault) ? TItem | undefined : TItem : TItem | undefined;
+declare function stringFilter(): DashboardFilterDefinition<string | undefined> & {
+    readonly kind: 'string';
+};
+declare function stringFilter<const TOptions extends FilterOptions<string>>(options: TOptions): DashboardFilterDefinition<FilterValue<string, TOptions>> & {
+    readonly kind: 'string';
+};
+declare function numberFilter(): DashboardFilterDefinition<number | undefined> & {
+    readonly kind: 'number';
+};
+declare function numberFilter<const TOptions extends FilterOptions<number>>(options: TOptions): DashboardFilterDefinition<FilterValue<number, TOptions>> & {
+    readonly kind: 'number';
+};
+declare function booleanFilter(): DashboardFilterDefinition<boolean | undefined> & {
+    readonly kind: 'boolean';
+};
+declare function booleanFilter<const TOptions extends SingleOptions<boolean>>(options: TOptions): DashboardFilterDefinition<FilterValue<boolean, TOptions>> & {
+    readonly kind: 'boolean';
+};
+declare function dateFilter(): DashboardFilterDefinition<Date | undefined> & {
+    readonly kind: 'date';
+};
+declare function dateFilter<const TOptions extends SingleOptions<Date>>(options: TOptions): DashboardFilterDefinition<FilterValue<Date, TOptions>> & {
+    readonly kind: 'date';
+};
+declare function dateRangeFilter(): DashboardFilterDefinition<DashboardDateRange | undefined> & {
+    readonly kind: 'dateRange';
+};
+declare function dateRangeFilter<const TOptions extends SingleOptions<DashboardDateRange>>(options: TOptions): DashboardFilterDefinition<FilterValue<DashboardDateRange, TOptions>> & {
+    readonly kind: 'dateRange';
+};
+declare function enumFilter<const TValues extends readonly DashboardOptionValue[]>(values: TValues): DashboardFilterDefinition<TValues[number] | undefined> & {
+    readonly kind: 'enum';
+};
+declare function enumFilter<const TValues extends readonly DashboardOptionValue[], const TOptions extends ListFilterOptions<TValues[number]>>(values: TValues, options: TOptions): DashboardFilterDefinition<FilterValue<TValues[number], TOptions>> & {
+    readonly kind: 'enum';
+};
+declare function optionsFilter<const TItems extends readonly DashboardOption[]>(items: TItems): DashboardFilterDefinition<TItems[number]['value'] | undefined> & {
+    readonly kind: 'options';
+};
+declare function optionsFilter<const TItems extends readonly DashboardOption[], const TOptions extends LabeledFilterOptions<TItems[number]['value']>>(items: TItems, options: TOptions): DashboardFilterDefinition<FilterValue<TItems[number]['value'], TOptions>> & {
+    readonly kind: 'options';
+};
+declare function optionsFilter(items: () => readonly DashboardOption<string>[]): DashboardFilterDefinition<string | undefined> & {
+    readonly kind: 'options';
+};
+declare function optionsFilter<const TOptions extends LabeledFilterOptions<string>>(items: () => readonly DashboardOption<string>[], options: TOptions): DashboardFilterDefinition<FilterValue<string, TOptions>> & {
+    readonly kind: 'options';
+};
+type RemoteSource = DashboardRemoteOptionsConfig;
+declare function remoteFilter<const TConfig extends RemoteSource & LabeledFilterOptions<string>>(config: TConfig): DashboardFilterDefinition<FilterValue<string, TConfig>> & {
+    readonly kind: 'remote';
+};
+declare function remoteFilter<const TOptions extends LabeledFilterOptions<string>>(source: RemoteSource, options: TOptions): DashboardFilterDefinition<FilterValue<string, TOptions>> & {
+    readonly kind: 'remote';
+};
+/** Values of `f.comparison`, in menu order. */
+export declare const DASHBOARD_COMPARISONS: readonly ["previous", "year", "none"];
+declare function comparisonFilter(): DashboardFilterDefinition<DashboardComparison | undefined> & {
+    readonly kind: 'comparison';
+};
+declare function comparisonFilter<const TOptions extends DashboardFilterOptions<DashboardFilterDefault<DashboardComparison>, DashboardComparison>>(options: TOptions): DashboardFilterDefinition<FilterValue<DashboardComparison, TOptions>> & {
+    readonly kind: 'comparison';
+};
+declare function customFilter<TValue>(codec: QueryCodec<TValue>): DashboardFilterDefinition<TValue | undefined> & {
+    readonly kind: 'custom';
+};
+declare function customFilter<TValue, const TOptions extends SingleOptions<TValue>>(codec: QueryCodec<TValue>, options: TOptions): DashboardFilterDefinition<FilterValue<TValue, TOptions>> & {
+    readonly kind: 'custom';
+};
+/**
+ * The `f` builder handed to every `filters` callback. Each method declares one typed filter: its
+ * value is `dashboard.filters.<key>`, and its control `dashboard.controls.<key>` drives it from any
+ * component.
+ *
+ * Every filter accepts `defaultValue` (a value or a getter; it narrows away `undefined`), `sync`
+ * (URL, memory, or an external store), `urlKey`, `omitDefault`, `historyMode`, `presets`, and the
+ * filter presentation: `label`, `placeholder`, `headless`. Filters picked from a list also accept
+ * `columns` and `searchable`; `multiple: true` turns the value into an always-defined array, capped
+ * by `max`.
+ */
+export declare const dashboardFilterBuilder: {
+    /** `true` / `false`. Its filter lists both, labeled by `format` or the localized Yes / No. */
+    boolean: typeof booleanFilter;
+    /**
+     * Comparison period: `'previous'`, `'year'`, or `'none'`. Its filter carries localized labels;
+     * `resolveDashboardComparisonRange(range, mode)` turns it into the range to fetch.
+     */
+    comparison: typeof comparisonFilter;
+    custom: typeof customFilter;
+    date: typeof dateFilter;
+    /** Inclusive date range, serialized as `YYYY-MM-DD..YYYY-MM-DD`. */
+    dateRange: typeof dateRangeFilter;
+    /** Value(s) from a literal list, e.g. `f.enum([2024, 2025, 2026], { defaultValue: 2026 })`. */
+    enum: typeof enumFilter;
+    /** Number, or `number[]` with `multiple: true`. */
+    number: typeof numberFilter;
+    /**
+     * Value(s) from labeled items: `{ value, label, icon?, avatar?, hint?, description? }`. Pass a
+     * getter to read the items from data, e.g. `f.options(() => products.data?.map(toOption) ?? [])`;
+     * their values are strings.
+     */
+    options: typeof optionsFilter;
+    /**
+     * Id(s) picked from a remote, searchable, paginated option source:
+     * `f.remote(remoteTableOptions(query, { ... }), { label: 'Account' })`.
+     */
+    remote: typeof remoteFilter;
+    /** String, or `string[]` with `multiple: true`. */
+    string: typeof stringFilter;
+};
+export {};

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

@@ -0,0 +1,135 @@
+import { isFunction } from "../../../shared/utils/predicate.js";
+import {
+  createListCodec,
+  createOptionValueCodec,
+  createSafeCodec,
+  dateRangeCodec,
+  localDateCodec,
+  optionalBooleanCodec,
+  optionalNumberCodec,
+  optionalStringCodec
+} from "../codecs.js";
+function defineFilter(kind, codec, options = {}) {
+  const multiple = options.multiple === true;
+  const { defaultValue, items, presets } = options;
+  const unset = multiple ? [] : void 0;
+  const resolveDefault = isFunction(defaultValue) ? () => defaultValue() ?? unset : () => defaultValue ?? unset;
+  let read = resolveDefault;
+  return {
+    bind(next) {
+      read = next;
+    },
+    codec: multiple ? createListCodec(codec) : codec,
+    columns: options.columns,
+    defaultValue: isFunction(defaultValue) ? unset : defaultValue ?? unset,
+    enabled: options.enabled,
+    format: options.format,
+    headless: options.headless === true,
+    historyMode: options.historyMode,
+    // Fixed lists become getters too, so the option list reads every list the same way.
+    items: items === void 0 || isItemsGetter(items) ? items : () => items,
+    kind,
+    label: options.label,
+    max: options.max,
+    multiple,
+    omitDefault: options.omitDefault,
+    placeholder: options.placeholder,
+    presets: presets === void 0 || isPresetsGetter(presets) ? presets : () => presets,
+    remote: options.remote,
+    resolveDefault,
+    searchable: options.searchable,
+    sync: options.sync,
+    urlKey: options.urlKey,
+    get value() {
+      return read();
+    }
+  };
+}
+function isItemsGetter(items) {
+  return !Array.isArray(items);
+}
+function isPresetsGetter(presets) {
+  return !Array.isArray(presets);
+}
+function stringFilter(options) {
+  return defineFilter("string", optionalStringCodec, options);
+}
+function numberFilter(options) {
+  return defineFilter("number", optionalNumberCodec, options);
+}
+const BOOLEAN_ITEMS = [
+  { label: "true", value: true },
+  { label: "false", value: false }
+];
+function booleanFilter(options) {
+  return defineFilter("boolean", optionalBooleanCodec, { ...options, items: BOOLEAN_ITEMS });
+}
+function dateFilter(options) {
+  return defineFilter("date", localDateCodec, options);
+}
+function dateRangeFilter(options) {
+  return defineFilter("dateRange", dateRangeCodec, options);
+}
+function enumFilter(values, options) {
+  const items = values.map((value) => ({ label: String(value), value }));
+  return defineFilter("enum", createOptionValueCodec(values), { ...options, items });
+}
+function optionsFilter(items, options) {
+  const codec = isItemsGetter(items) ? optionalStringCodec : createOptionValueCodec(items.map((item) => item.value));
+  return defineFilter("options", codec, { ...options, items });
+}
+function remoteFilter(config, extra) {
+  const { load, pagination, queryKey, resolveSelected, search, ...options } = config;
+  const remote = { load, pagination, queryKey, resolveSelected, search };
+  return defineFilter("remote", optionalStringCodec, {
+    searchable: true,
+    ...options,
+    ...extra,
+    remote
+  });
+}
+export const DASHBOARD_COMPARISONS = [
+  "previous",
+  "year",
+  "none"
+];
+function comparisonFilter(options) {
+  const items = DASHBOARD_COMPARISONS.map((value) => ({ label: value, value }));
+  return defineFilter("comparison", createOptionValueCodec(DASHBOARD_COMPARISONS), {
+    ...options,
+    items
+  });
+}
+function customFilter(codec, options) {
+  return defineFilter("custom", createSafeCodec(codec), options);
+}
+export const dashboardFilterBuilder = {
+  /** `true` / `false`. Its filter lists both, labeled by `format` or the localized Yes / No. */
+  boolean: booleanFilter,
+  /**
+   * Comparison period: `'previous'`, `'year'`, or `'none'`. Its filter carries localized labels;
+   * `resolveDashboardComparisonRange(range, mode)` turns it into the range to fetch.
+   */
+  comparison: comparisonFilter,
+  custom: customFilter,
+  date: dateFilter,
+  /** Inclusive date range, serialized as `YYYY-MM-DD..YYYY-MM-DD`. */
+  dateRange: dateRangeFilter,
+  /** Value(s) from a literal list, e.g. `f.enum([2024, 2025, 2026], { defaultValue: 2026 })`. */
+  enum: enumFilter,
+  /** Number, or `number[]` with `multiple: true`. */
+  number: numberFilter,
+  /**
+   * Value(s) from labeled items: `{ value, label, icon?, avatar?, hint?, description? }`. Pass a
+   * getter to read the items from data, e.g. `f.options(() => products.data?.map(toOption) ?? [])`;
+   * their values are strings.
+   */
+  options: optionsFilter,
+  /**
+   * Id(s) picked from a remote, searchable, paginated option source:
+   * `f.remote(remoteTableOptions(query, { ... }), { label: 'Account' })`.
+   */
+  remote: remoteFilter,
+  /** String, or `string[]` with `multiple: true`. */
+  string: stringFilter
+};

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

@@ -1,4 +1,4 @@
-import type { DashboardAxisOptions, DashboardChartFrameAxis, DashboardHighlight, DashboardLegendItem, DashboardSelected, DashboardSeries, DashboardSeriesColor, DashboardValueFormat } from '../types/index.js';
+import type { DashboardAxisOptions, DashboardChartFrameAxis, DashboardHighlight, DashboardLegendItem, DashboardSelected, DashboardSeries, DashboardSeriesColor } from '../types/index.js';
 export declare const DASHBOARD_PALETTE_SIZE = 6;
 /**
  * Resolves a series color to a CSS value. Palette slots and Nuxt UI colors map to CSS variables, so
@@ -39,22 +39,11 @@ export declare function niceDashboardTickCount(max: number): number;
 /**
  * Value domain and tick values covering every value: `0` included, the top rounded to a readable
  * bound with some headroom, and evenly spaced ticks that land on round numbers.
+ *
+ * When every value is a whole number (counts, units, or nothing but zeros), so are the top and the
+ * step: a quarter tick would print as a repeated label once formatted as an integer.
  */
 export declare function resolveDashboardAxis(values: readonly (number | null | undefined)[], axis: DashboardAxisOptions | undefined, headroom?: number): Pick<DashboardChartFrameAxis, 'domain' | 'ticks'>;
-/** Default formatters of one locale: numbers, signed changes, and shares (both in percent). */
-export interface DashboardFormats {
-    /** Locale number, compact from 10 000 (`12,6 k`). */
-    number: DashboardValueFormat;
-    /** Signed percent change: `12.4` → `+12,4 %`. */
-    delta: DashboardValueFormat;
-    /** Percent share: `57` → `57 %`. */
-    percent: DashboardValueFormat;
-}
-/**
- * Formatters of one locale. `Intl.NumberFormat` instances are costly to build and stateless, so they
- * are created once per locale and shared by every block.
- */
-export declare function resolveDashboardFormats(locale: string): DashboardFormats;
 /** Escapes text interpolated into chart tooltip HTML. */
 export declare function escapeDashboardHtml(value: string): string;
 /** Deterministic pseudo-random sequence, so placeholders render identically on server and client. */

package/dist/runtime/dashboard/utils/charts.js

@@ -83,21 +83,39 @@ export function niceDashboardTickCount(max) {
 }
 export function resolveDashboardAxis(values, axis, headroom = 1.05) {
   const finite = values.filter((value) => Number.isFinite(value));
+  const integral = finite.every((value) => Number.isInteger(value));
   const lowest = Math.min(0, ...finite);
   if (lowest < 0 && axis?.min === void 0 && axis?.max === void 0)
-    return resolveDivergingAxis(lowest, Math.max(0, ...finite), headroom, axis?.ticks);
+    return resolveDivergingAxis({
+      headroom,
+      highest: Math.max(0, ...finite),
+      integral,
+      lowest,
+      ticks: axis?.ticks
+    });
   const min = axis?.min ?? lowest;
-  const max = axis?.max ?? niceDashboardMax(Math.max(0, ...finite) * headroom);
-  const count = Math.max(1, Math.round(axis?.ticks ?? niceDashboardTickCount(max - min)));
+  const top = niceDashboardMax(Math.max(0, ...finite) * headroom);
+  const max = axis?.max ?? (integral ? Math.ceil(top) : top);
+  const nice = Math.max(1, Math.round(axis?.ticks ?? niceDashboardTickCount(max - min)));
+  const count = integral && axis?.ticks === void 0 && Number.isInteger(max - min) ? wholeStepCount(max - min, nice) : nice;
   const ticks = Array.from({ length: count + 1 }, (_, index) => min + (max - min) * index / count);
   return { domain: [min, max], ticks };
 }
-function resolveDivergingAxis(lowest, highest, headroom, ticks = 4) {
-  const bottom = -lowest * headroom;
-  const top = highest * headroom;
-  const rough = (top + bottom) / Math.max(1, ticks);
+function wholeStepCount(range, count) {
+  for (let candidate = count; candidate > 1; candidate -= 1) {
+    if (Number.isInteger(range / candidate)) return candidate;
+  }
+  return 1;
+}
+function resolveDivergingAxis(params) {
+  const { headroom, integral } = params;
+  const bottom = -params.lowest * headroom;
+  const top = params.highest * headroom;
+  const rough = (top + bottom) / Math.max(1, params.ticks ?? 4);
   const power = 10 ** Math.floor(Math.log10(rough));
-  const step = ([1, 2, 2.5, 5, 10].find((candidate) => rough / power <= candidate) ?? 10) * power;
+  const mantissas = integral && power <= 1 ? [1, 2, 5, 10] : [1, 2, 2.5, 5, 10];
+  const nice = (mantissas.find((candidate) => rough / power <= candidate) ?? 10) * power;
+  const step = integral ? Math.max(1, nice) : nice;
   const min = -Math.ceil(bottom / step) * step;
   const max = Math.ceil(top / step) * step;
   const count = Math.max(1, Math.round((max - min) / step));
@@ -106,26 +124,6 @@ function resolveDivergingAxis(lowest, highest, headroom, ticks = 4) {
     ticks: Array.from({ length: count + 1 }, (_, index) => min + step * index)
   };
 }
-const formatsByLocale = /* @__PURE__ */ new Map();
-export function resolveDashboardFormats(locale) {
-  const cached = formatsByLocale.get(locale);
-  if (cached) return cached;
-  const plain = new Intl.NumberFormat(locale, { maximumFractionDigits: 1 });
-  const compact = new Intl.NumberFormat(locale, { maximumFractionDigits: 1, notation: "compact" });
-  const delta = new Intl.NumberFormat(locale, {
-    maximumFractionDigits: 1,
-    signDisplay: "exceptZero",
-    style: "percent"
-  });
-  const percent = new Intl.NumberFormat(locale, { maximumFractionDigits: 1, style: "percent" });
-  const formats = {
-    delta: (value) => delta.format(value / 100),
-    number: (value) => Math.abs(value) >= 1e4 ? compact.format(value) : plain.format(value),
-    percent: (value) => percent.format(value / 100)
-  };
-  formatsByLocale.set(locale, formats);
-  return formats;
-}
 export function escapeDashboardHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }

package/dist/runtime/dashboard/utils/{params/codecs.d.ts → codecs.d.ts}

@@ -1,5 +1,5 @@
-import type { QueryCodec } from '../../../query-state/index.js';
-import type { DashboardDateRange, DashboardOptionValue } from '../../types/index.js';
+import type { QueryCodec } from '../../query-state/index.js';
+import type { DashboardDateRange, DashboardOptionValue } from '../types/index.js';
 export declare const optionalStringCodec: QueryCodec<string | undefined>;
 export declare const optionalNumberCodec: QueryCodec<number | undefined>;
 export declare const optionalBooleanCodec: QueryCodec<boolean | undefined>;

package/dist/runtime/dashboard/utils/{params/codecs.js → codecs.js}

@@ -1,4 +1,4 @@
-import { isNullish } from "../../../shared/utils/predicate.js";
+import { isNullish } from "../../shared/utils/predicate.js";
 export const optionalStringCodec = {
   parse: (raw) => raw === "" ? void 0 : raw,
   serialize: (value) => isNullish(value) || value === "" ? null : value

package/dist/runtime/dashboard/utils/environment.d.ts

@@ -0,0 +1,36 @@
+import type { useUiToolsLocale } from '../../i18n/use-locale.js';
+import type { DashboardRuntimeFilter } from '../types/index.js';
+export type DashboardLocale = ReturnType<typeof useUiToolsLocale>;
+/**
+ * Runs `build` with `locale` as the locale of the dashboard being built. A schema function runs
+ * again outside setup when its input changes; the formats it creates (`useDashboardFormat()`) keep
+ * the locale of the component that created the dashboard.
+ */
+export declare function withDashboardLocale<TResult>(locale: DashboardLocale, build: () => TResult): TResult;
+/** Locale of the dashboard being built, while one builds. */
+export declare function currentDashboardLocale(): import("../../i18n/index.js").UiToolsLocaleContext<import("../../i18n/index.js").Messages> | undefined;
+/** URL-synced filters of one dashboard, by full URL key. */
+export type DashboardFilterRegistry = Map<string, {
+    owner: string;
+    signature: string;
+}>;
+/**
+ * What a dashboard reads from the component that creates it, once, during setup. A dashboard built
+ * from a schema function is rebuilt outside setup when the function's input changes; it keeps these.
+ */
+export interface DashboardEnvironment {
+    /** Locale of the creating component (Nuxt UI's `UApp` locale, or the ui-tools one). */
+    locale: DashboardLocale;
+    /** Filters with a URL key, across the dashboard's scopes. */
+    registry: DashboardFilterRegistry;
+}
+/**
+ * Records a URL-synced filter. A URL key names one filter across the dashboard: two scopes may both
+ * declare `year` (they share its value), but not as two different kinds of filter, or with two
+ * defaults, which would make the shared value read differently from one tab to the next.
+ */
+export declare function registerDashboardFilter(registry: DashboardFilterRegistry, params: {
+    urlKey: string;
+    owner: string;
+    definition: DashboardRuntimeFilter;
+}): void;

package/dist/runtime/dashboard/utils/environment.js

@@ -0,0 +1,30 @@
+let buildingLocale;
+export function withDashboardLocale(locale, build) {
+  const previous = buildingLocale;
+  buildingLocale = locale;
+  try {
+    return build();
+  } finally {
+    buildingLocale = previous;
+  }
+}
+export function currentDashboardLocale() {
+  return buildingLocale;
+}
+export function registerDashboardFilter(registry, params) {
+  const { definition } = params;
+  const signature = [
+    definition.kind,
+    definition.multiple ? "multiple" : "single",
+    definition.codec.serialize(definition.defaultValue)
+  ].join(":");
+  const known = registry.get(params.urlKey);
+  if (!known) {
+    registry.set(params.urlKey, { owner: params.owner, signature });
+    return;
+  }
+  if (known.signature !== signature)
+    throw new Error(
+      `[dashboard] The filter of ${params.owner} and the filter of ${known.owner} share the URL key "${params.urlKey}", so they share one value, but they are declared differently (${signature} vs ${known.signature}). Declare them the same way, or give one another key or \`urlKey\`.`
+    );
+}

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

@@ -0,0 +1,44 @@
+import type { DashboardFilterControl, DashboardOptionValue, DashboardRuntimeFilter, DashboardSeries } from '../types/index.js';
+/**
+ * One chart series per option a filter picks, in pick order: keyed and labelled by the option,
+ * colored by position in the palette (as the picker chips are), valued by `value(row, option)`.
+ */
+export declare function resolveDashboardFilterSeries<TRow, TItem extends DashboardOptionValue>(filter: DashboardFilterControl<unknown, TItem>, value: ((row: TRow, item: TItem) => number | null | undefined) | undefined): DashboardSeries<TRow>[];
+/** The filter has a menu: options to pick from, or presets. */
+export declare function hasDashboardFilterMenu(filter: Pick<DashboardFilterControl, 'kind' | 'presets'>): boolean;
+/**
+ * Default classes of `UiDashboardFilter`. Pills are 32px high, menus dense (28px rows, 13px text;
+ * taller rows on touch screens only). An active pill takes the `--nut-dash-filter-*` tokens.
+ */
+export declare const DASHBOARD_FILTER_CLASSES: {
+    avatar: string;
+    button: string;
+    check: string;
+    chevron: string;
+    clear: string;
+    content: string;
+    hint: string;
+    item: string;
+    label: string;
+    list: string;
+    note: string;
+    root: string;
+    search: string;
+    separator: string;
+    tick: string;
+    title: string;
+    trigger: string;
+    value: string;
+};
+/**
+ * The filter is state only: declared `headless`, or read from a getter (a read-only source no control
+ * can drive).
+ */
+export declare function isDashboardFilterHeadless(definition: DashboardRuntimeFilter): boolean;
+/** A value a filter can pick from a list: a string, a number, or a boolean. */
+export declare function isDashboardOptionValue(value: unknown): value is DashboardOptionValue;
+/**
+ * Default text of a filter value without an option label: dates and ranges in the locale's medium
+ * style, numbers with its grouping, lists joined.
+ */
+export declare function formatDashboardFilterValue(value: unknown, locale: string): string;

package/dist/runtime/dashboard/utils/filters.js

@@ -0,0 +1,62 @@
+import { isRef } from "vue";
+import { isBoolean, isDate, isNumber, isObject, isString } from "../../shared/utils/predicate.js";
+import { DASHBOARD_PALETTE_SIZE } from "./charts.js";
+const DASHBOARD_LISTED_KINDS = /* @__PURE__ */ new Set([
+  "boolean",
+  "comparison",
+  "enum",
+  "options",
+  "remote"
+]);
+export function resolveDashboardFilterSeries(filter, value) {
+  return filter.selected.map((option, index) => ({
+    color: `series-${index % DASHBOARD_PALETTE_SIZE + 1}`,
+    key: String(option.value),
+    label: option.label,
+    value: (row) => value?.(row, option.value) ?? null
+  }));
+}
+export function hasDashboardFilterMenu(filter) {
+  return DASHBOARD_LISTED_KINDS.has(filter.kind) || filter.presets.length > 0;
+}
+export const DASHBOARD_FILTER_CLASSES = {
+  avatar: "inline-grid size-[18px] flex-none place-items-center rounded-[4px] bg-muted text-[8.5px] font-semibold text-muted",
+  button: "inline-flex h-7 flex-none items-center justify-center gap-1.5 rounded-[7px] border border-default bg-default px-2.5 text-[12.5px] font-medium whitespace-nowrap text-default transition-colors outline-none hover:bg-elevated/60 focus-visible:ring-2 focus-visible:ring-primary",
+  check: "inline-grid size-3.5 flex-none place-items-center rounded-[4px] border border-accented bg-default text-transparent transition-colors data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-inverted",
+  chevron: "size-3.5 flex-none text-dimmed",
+  clear: "ms-px me-[5px] inline-grid size-5 flex-none place-items-center rounded-full text-[var(--nut-dash-filter-ink)] outline-none hover:bg-[var(--nut-dash-filter-active-line)] focus-visible:ring-2 focus-visible:ring-primary",
+  content: "min-w-[max(160px,var(--reka-popover-trigger-width,0px))] max-w-[min(320px,calc(100vw-24px))] p-1 text-[13px]",
+  hint: "ms-auto shrink-0 ps-2 text-[11px] text-dimmed tabular-nums",
+  item: "flex h-7 w-full min-w-0 items-center gap-2 rounded-[4px] px-2 text-start text-[13px] text-default outline-none hover:bg-[var(--nut-dash-row-hover)] focus-visible:bg-[var(--nut-dash-row-hover)] disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent data-[selected]:font-medium pointer-coarse:h-9",
+  label: "text-muted",
+  list: "max-h-[300px] overflow-y-auto overscroll-contain",
+  note: "flex items-center justify-center px-2 py-1.5 text-xs text-dimmed",
+  // The trigger's keyboard focus rings the whole pill, clear button included.
+  root: "group/filter inline-flex h-8 max-w-full flex-none items-center rounded-[7px] border border-default bg-default text-[13px] whitespace-nowrap transition-[background-color,border-color] duration-150 hover:bg-elevated/60 has-[[data-dashboard-filter-trigger]:focus-visible]:ring-2 has-[[data-dashboard-filter-trigger]:focus-visible]:ring-primary data-[active]:border-[var(--nut-dash-filter-active-line)] data-[active]:bg-[var(--nut-dash-filter-active)] data-[active]:hover:bg-[var(--nut-dash-filter-active)]",
+  search: "mb-1 flex h-7 items-center gap-1.5 rounded-md border border-default px-2 focus-within:border-primary",
+  separator: "my-1 h-px bg-[var(--ui-border-muted)]",
+  tick: "ms-auto size-3.5 flex-none text-[var(--nut-dash-filter-ink)]",
+  title: "px-2 pt-1 pb-1 text-[11.5px] font-medium text-muted",
+  trigger: "inline-flex h-full min-w-0 items-center gap-1.5 rounded-[6px] ps-[11px] pe-[9px] outline-none group-data-[active]/filter:pe-1",
+  value: "max-w-[200px] min-w-0 truncate font-medium text-default group-data-[active]/filter:text-[var(--nut-dash-filter-ink)]"
+};
+export function isDashboardFilterHeadless(definition) {
+  const { sync } = definition;
+  if (definition.headless === true) return true;
+  return sync !== void 0 && sync !== "url" && sync !== "memory" && !isRef(sync);
+}
+export function isDashboardOptionValue(value) {
+  return isString(value) || isNumber(value) || isBoolean(value);
+}
+export function formatDashboardFilterValue(value, locale) {
+  if (Array.isArray(value))
+    return value.map((entry) => formatDashboardFilterValue(entry, locale)).join(", ");
+  if (isDate(value)) return new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(value);
+  if (isNumber(value)) return new Intl.NumberFormat(locale).format(value);
+  if (isObject(value) && isDate(value.start) && isDate(value.end))
+    return new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).formatRange(
+      value.start,
+      value.end
+    );
+  return String(value ?? "");
+}

package/dist/runtime/dashboard/utils/format.d.ts

@@ -0,0 +1,25 @@
+import type { DashboardFormatPreset, DashboardValueFormatter } from '../types/index.js';
+/** Number formatters of one locale, one per preset except `points` (which needs messages). */
+export type DashboardFormats = Record<Exclude<DashboardFormatPreset, 'points'>, DashboardValueFormatter>;
+/**
+ * Intl uses a narrow no-break space (U+202F) to group digits in some locales (French). Several UI
+ * fonts draw it with no width, so it becomes a regular no-break space: digits never touch, and a
+ * value still never wraps.
+ */
+export declare function normalizeDashboardSpaces(text: string): string;
+/**
+ * One cached `Intl.NumberFormat` per locale and option set: building them is costly. A `currency`
+ * without a `style` is the currency shorthand: whole amounts in that currency (`{ currency: 'EUR' }`
+ * → `12 345 €`), unless the options set their own fraction digits.
+ */
+export declare function resolveDashboardNumberFormat(locale: string, options: Intl.NumberFormatOptions): DashboardValueFormatter;
+/**
+ * Preset formatters of one locale. They are created once per locale and shared by every block and
+ * every `useDashboardFormat()` caller.
+ */
+export declare function resolveDashboardFormats(locale: string): DashboardFormats;
+/**
+ * Name of a month, capitalized as a standalone label: `3` (1–12) or a date → "Mar" / "March".
+ * Months use the stand-alone form of the locale ("mars" in French becomes "Mars").
+ */
+export declare function formatDashboardMonth(locale: string, value: number | Date, width?: 'short' | 'long'): string;