nuxt-ui-tools 1.1.0 → 1.3.0

package/dist/runtime/dashboard/composables/use-dashboard-block.js

@@ -1,34 +1,51 @@
-import { computed, onBeforeUnmount, onMounted } from "vue";
+import { computed, onBeforeUnmount, watch } from "vue";
 import { useResponsiveValue } from "../../shared/composables/use-responsive-value.js";
+import { parseDashboardSpan, resolveDashboardCellStyle } from "../utils/grid.js";
 import { observeDashboardVisibility } from "../utils/visibility.js";
+import { useDashboardGridContext } from "./use-dashboard-ui.js";
 export function useDashboardBlock(params) {
+  const hidden = computed(() => params.source()?.state === "disabled");
   const phase = computed(() => {
     const source = params.source();
     if (!source) return "content";
+    if (source.state === "disabled") return "idle";
     if (source.state !== "ready") return source.state;
     return params.empty() ? "empty" : "content";
   });
-  const refreshing = computed(() => params.source()?.refreshing ?? false);
-  const span = useResponsiveValue(() => params.size() ?? "", "col");
-  const rowSpan = useResponsiveValue(() => params.rows() ?? "", "row");
+  const fetching = computed(() => {
+    const source = params.source();
+    return source ? source.fetching ?? source.refreshing : false;
+  });
+  const grid = useDashboardGridContext();
+  const span = useResponsiveValue(() => params.size() ?? "", "integer");
   const style = computed(
-    () => [span.value ?? "grid-column: 1 / -1", rowSpan.value].filter(Boolean).join("; ")
+    () => grid ? resolveDashboardCellStyle({
+      columns: grid.columns.value,
+      fill: grid.fill.value,
+      gap: grid.gap.value,
+      span: parseDashboardSpan(span.value)
+    }) : ""
   );
   let stopObserving;
-  onMounted(() => {
-    const source = params.source();
-    const activation = params.activation() ?? "visible";
-    if (!source || activation === "manual" || !waitsForActivation(source)) return;
-    const element = params.root.value;
-    if (activation === "mount" || !element || typeof IntersectionObserver === "undefined")
-      return source.activate();
-    stopObserving = observeDashboardVisibility(element, () => params.source()?.activate());
-  });
+  watch(
+    () => params.root.value,
+    (element) => {
+      stopObserving?.();
+      stopObserving = void 0;
+      const source = params.source();
+      const activation = params.activation() ?? "visible";
+      if (!element || !source || activation === "manual" || !waitsForActivation(source)) return;
+      if (activation === "mount" || typeof IntersectionObserver === "undefined")
+        return source.activate();
+      stopObserving = observeDashboardVisibility(element, () => params.source()?.activate());
+    },
+    { flush: "post", immediate: true }
+  );
   onBeforeUnmount(() => stopObserving?.());
   function retry() {
     params.source()?.refresh().catch(() => void 0);
   }
-  return { phase, refreshing, retry, style };
+  return { fetching, hidden, phase, retry, style };
 }
 function waitsForActivation(source) {
   return !("stage" in source) || source.stage === "deferred";

package/dist/runtime/dashboard/composables/use-dashboard-chart.d.ts

@@ -1,5 +1,5 @@
 import type { LazyTextValue } from '../../shared/types/utils.js';
-import type { DashboardAxisOptions, DashboardChartFrame, DashboardHighlight, DashboardReferenceLine, DashboardSelected, DashboardSelectEvent, DashboardSeries, DashboardValueFormat } from '../types/index.js';
+import type { DashboardAxisOptions, DashboardChartFrame, DashboardChartTotals, DashboardHighlight, DashboardReferenceLine, DashboardSelected, DashboardSelectEvent, DashboardSeries, DashboardValueFormat } from '../types/index.js';
 /** A chart drawn taller in the expand dialog. */
 export declare function resolveDashboardExpandedHeight(height: number): number;
 /**
@@ -27,10 +27,17 @@ export declare function useDashboardChart<TRow>(params: {
     selected?: () => DashboardSelected<TRow> | undefined;
     /** Bar charts: prints each group's value above its bars. */
     labels?: () => boolean;
+    /** Footer totals of the solid series: their sum, or their average. */
+    totals?: () => DashboardChartTotals | undefined;
 }): {
     frame: import("vue").ComputedRef<DashboardChartFrame>;
     legend: import("vue").ComputedRef<import("../types/index.js").DashboardLegendItem[]>;
     select: (index: number) => void;
     selectable: import("vue").ComputedRef<boolean>;
     tabulate: () => import("../types/index.js").DashboardDataTable;
+    totals: import("vue").ComputedRef<{
+        key: string;
+        label: string;
+        text: string;
+    }[]>;
 };

package/dist/runtime/dashboard/composables/use-dashboard-chart.js

@@ -58,7 +58,7 @@ export function useDashboardChart(params) {
       const values = stacked && axis === "left" ? data.map((datum) => indexes.reduce((sum, index) => sum + (datum.values[index] ?? 0), 0)) : data.flatMap((datum) => indexes.map((index) => datum.values[index]));
       return [...values, ...references.filter((ref) => ref.axis === axis).map((ref) => ref.value)];
     };
-    const format = params.format() ?? formats.number.value;
+    const format = formats.resolve(params.format());
     const yAxis = params.yAxis();
     const y2Axis = params.y2Axis?.();
     const hasRight = resolved.some((entry) => entry.axis === "right");
@@ -70,7 +70,7 @@ export function useDashboardChart(params) {
     );
     const selected = params.selected?.();
     const emphasis = hasBars ? resolveDashboardEmphasis(rows, barTotals, params.highlight?.(), selected) : null;
-    const leftFormat = yAxis?.format ?? format;
+    const leftFormat = yAxis?.format ? formats.resolve(yAxis.format) : format;
     return {
       data,
       emphasis,
@@ -82,7 +82,7 @@ export function useDashboardChart(params) {
       references,
       right: hasRight ? {
         ...resolveDashboardAxis(axisValues("right"), y2Axis, headroom),
-        format: y2Axis?.format ?? format
+        format: y2Axis?.format ? formats.resolve(y2Axis.format) : format
       } : null,
       series: resolved.map(({ axis, color, dashed, key, label, type }, index) => ({
         axis,
@@ -105,6 +105,18 @@ export function useDashboardChart(params) {
       xDomain: hasBars || last === 0 ? [-0.5, last + 0.5] : [0, last]
     };
   });
+  const totals = computed(() => {
+    const mode = params.totals?.();
+    if (!mode) return [];
+    const { data, left, right, series: entries } = frame.value;
+    return entries.filter((entry) => !entry.dashed && !entry.key.endsWith(":compare")).map((entry) => {
+      const values = data.flatMap((datum) => datum.values[entry.index] ?? []);
+      const sum = values.reduce((total, value2) => total + value2, 0);
+      const value = mode === "average" ? values.length ? sum / values.length : 0 : sum;
+      const format = (entry.axis === "right" ? right?.format : void 0) ?? left.format;
+      return { key: entry.key, label: entry.label, text: format(value) };
+    });
+  });
   const tabulate = () => tabulateDashboardFrame(
     frame.value,
     resolveTextValue(params.xLabel(), t("dashboard.table.category"))
@@ -114,5 +126,5 @@ export function useDashboardChart(params) {
     const row = params.rows()[index];
     if (row !== void 0) params.onSelect()?.({ index, row });
   }
-  return { frame, legend, select, selectable, tabulate };
+  return { frame, legend, select, selectable, tabulate, totals };
 }

package/dist/runtime/dashboard/composables/use-dashboard-context.d.ts

@@ -0,0 +1,50 @@
+import type { DashboardSchemaInput, DashboardSchemaLike, DashboardViewInput, InferDashboard, InferDashboardView } from '../types/index.js';
+/** One dashboard created by `useDashboard`, as its descendants find it. */
+export interface DashboardContextEntry {
+    /** What `useDashboard` received: a schema, or a function returning one. */
+    readonly source: unknown;
+    /** The schema the dashboard currently runs. */
+    schema(): DashboardSchemaLike;
+    /** The dashboard object `useDashboard` returned. */
+    readonly api: object;
+    /** Handle of a view, stable across rebuilds. */
+    view(key: string): object | undefined;
+    /** Key of the view declared with this object, if the current schema has one. */
+    findView(declaration: object): string | undefined;
+    /** Key of the view on screen. */
+    current(): string | undefined;
+}
+/** Makes a dashboard available to descendant components. */
+export declare function provideDashboard(entry: DashboardContextEntry): void;
+/**
+ * Marks the components below as rendering one view of a dashboard, so `useDashboardView` resolves
+ * a view function to it. `UiDashboardPage` does it around the current view's slot.
+ */
+export declare function provideDashboardView(dashboard: object, key: string): void;
+/**
+ * Returns the dashboard an ancestor component created with `useDashboard`, fully typed, so nested
+ * components read it without props. Pass the schema, or the schema function: the nearest dashboard
+ * built from it answers (for a function, the nearest dashboard).
+ *
+ * @example
+ * ```ts
+ * const account = injectDashboard(accountSchema)
+ * account.filters.year
+ * ```
+ */
+export declare function injectDashboard<const TInput extends DashboardSchemaInput>(input: TInput): InferDashboard<TInput>;
+/**
+ * Returns the handle of a view: its queries, derived values, filters and controls, fully typed. A
+ * tab component needs nothing else.
+ *
+ * Pass the view, or the view function. Under `UiDashboardPage`, the view is the one whose slot
+ * renders the component; elsewhere, a view object is found by identity and a view function reads
+ * the view on screen.
+ *
+ * @example
+ * ```ts
+ * const consumption = useDashboardView(consumptionView)
+ * consumption.filters.year
+ * ```
+ */
+export declare function useDashboardView<const TInput extends DashboardViewInput>(input: TInput): InferDashboardView<TInput>;

package/dist/runtime/dashboard/composables/use-dashboard-context.js

@@ -0,0 +1,56 @@
+import { getCurrentInstance, inject, provide } from "vue";
+const dashboardContextKey = Symbol("nuxt-ui-tools.dashboard");
+function injectDashboardContext() {
+  return getCurrentInstance() ? inject(dashboardContextKey, null) : null;
+}
+export function provideDashboard(entry) {
+  if (!getCurrentInstance()) return;
+  const parent = injectDashboardContext();
+  provide(dashboardContextKey, { dashboards: [...parent?.dashboards ?? [], entry] });
+}
+export function provideDashboardView(dashboard, key) {
+  const parent = injectDashboardContext();
+  const entry = parent ? findLastEntry(parent.dashboards, (candidate) => candidate.api === dashboard) : void 0;
+  if (!parent || !entry) return;
+  provide(dashboardContextKey, { dashboards: parent.dashboards, view: { entry, key } });
+}
+export function injectDashboard(input) {
+  const dashboards = injectDashboardContext()?.dashboards ?? [];
+  const entry = findLastEntry(
+    dashboards,
+    (candidate) => candidate.source === input || candidate.schema() === input
+  ) ?? (typeof input === "function" ? dashboards.at(-1) : void 0);
+  if (!entry)
+    throw new Error(
+      "[dashboard] injectDashboard() found no dashboard. Call useDashboard() in a parent component."
+    );
+  return entry.api;
+}
+export function useDashboardView(input) {
+  const context = injectDashboardContext();
+  const handle = resolveView(context, input);
+  if (!handle)
+    throw new Error(
+      "[dashboard] useDashboardView() found no view. Render the component in a view slot of UiDashboardPage, under a dashboard created with useDashboard() whose schema declares the view."
+    );
+  return handle;
+}
+function resolveView(context, input) {
+  if (!context) return void 0;
+  const enclosing = context.view;
+  if (enclosing && (typeof input === "function" || enclosing.entry.findView(input) === enclosing.key))
+    return enclosing.entry.view(enclosing.key);
+  for (let index = context.dashboards.length - 1; index >= 0; index--) {
+    const entry = context.dashboards[index];
+    const key = typeof input === "function" ? entry?.current() : entry?.findView(input);
+    if (entry && key !== void 0) return entry.view(key);
+  }
+  return void 0;
+}
+function findLastEntry(dashboards, match) {
+  for (let index = dashboards.length - 1; index >= 0; index--) {
+    const entry = dashboards[index];
+    if (entry && match(entry)) return entry;
+  }
+  return void 0;
+}

package/dist/runtime/dashboard/composables/use-dashboard-derived.js

@@ -21,16 +21,20 @@ export function useDashboardDerived(params) {
     if (sourcesState.value !== "ready") return sourcesState.value;
     return evaluation.value.error === void 0 ? "ready" : "error";
   });
-  return markRaw({
+  const derived = markRaw({
     activate() {
       for (const source of evaluation.value.sources) source.activate();
     },
     get data() {
+      params.tracker.record(derived);
       return evaluation.value.value;
     },
     get error() {
       return evaluation.value.error ?? evaluation.value.sources.find((source) => source.state === "error")?.error;
     },
+    get fetching() {
+      return evaluation.value.sources.some((source) => source.fetching ?? source.refreshing);
+    },
     id: params.id,
     kind: "derived",
     refresh: () => refreshDashboardSources(evaluation.value.sources),
@@ -44,4 +48,5 @@ export function useDashboardDerived(params) {
       return resolveDashboardUpdatedAt(evaluation.value.sources.map((source) => source.updatedAt));
     }
   });
+  return derived;
 }

package/dist/runtime/dashboard/composables/use-dashboard-filter-control.d.ts

@@ -0,0 +1,16 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardFilterControl, DashboardRuntimeFilter } from '../types/index.js';
+import type { DashboardLocale } from '../utils/environment.js';
+/**
+ * Control of one filter: its value and presentation (label, display text, option list) plus the
+ * actions pickers perform (`toggle`, `reset`). It owns no state of its own besides the option list;
+ * the value lives wherever the filter syncs it.
+ */
+export declare function useDashboardFilterControl(params: {
+    key: string;
+    definition: DashboardRuntimeFilter;
+    queryKey: QueryKey;
+    locale: DashboardLocale;
+    get: () => unknown;
+    set: (value: unknown) => void;
+}): DashboardFilterControl;

package/dist/runtime/dashboard/composables/use-dashboard-filter-control.js

@@ -0,0 +1,161 @@
+import { computed, markRaw } from "vue";
+import { isNullish } from "../../shared/utils/predicate.js";
+import { resolveTextValue } from "../../shared/utils/render.js";
+import {
+  formatDashboardFilterValue,
+  isDashboardOptionValue,
+  isDashboardFilterHeadless
+} from "../utils/filters.js";
+import { resolveDashboardCondition } from "../utils/state.js";
+import { useDashboardOptions } from "./use-dashboard-options.js";
+export function useDashboardFilterControl(params) {
+  const { definition, get, set } = params;
+  const { code, t } = params.locale;
+  const options = useDashboardOptions({
+    definition,
+    locale: params.locale,
+    queryKey: params.queryKey,
+    value: get
+  });
+  const listed = definition.items !== void 0 || definition.remote !== void 0;
+  const label = computed(() => resolveTextValue(definition.label, params.key));
+  const placeholder = computed(
+    () => resolveTextValue(definition.placeholder, t("dashboard.filters.all"))
+  );
+  const changed = computed(
+    () => definition.codec.serialize(get()) !== definition.codec.serialize(definition.resolveDefault())
+  );
+  const values = computed(() => {
+    const value = get();
+    const list = Array.isArray(value) ? value : [value];
+    return list.filter(isDashboardOptionValue);
+  });
+  const keys = computed(() => new Set(values.value.map(String)));
+  const selected = computed(
+    () => values.value.map(
+      (value) => options.known.value.get(String(value)) ?? {
+        label: options.resolving.value ? "\u2026" : describe(value),
+        value
+      }
+    )
+  );
+  const display = computed(() => {
+    const value = get();
+    if (isNullish(value) || Array.isArray(value) && value.length === 0) return placeholder.value;
+    const [first, second] = selected.value;
+    if (!first) return describe(value);
+    if (!second) return first.label;
+    return selected.value.length === 2 ? `${first.label}, ${second.label}` : t("dashboard.filters.more", { count: selected.value.length - 1, label: first.label });
+  });
+  function describe(value) {
+    return definition.format ? definition.format(value) : formatDashboardFilterValue(value, code.value);
+  }
+  const presets = computed(() => {
+    const current = definition.codec.serialize(get());
+    return (definition.presets?.() ?? []).map((preset) => ({
+      active: definition.codec.serialize(preset.value) === current,
+      apply: () => set(preset.value),
+      hint: preset.hint,
+      icon: preset.icon,
+      label: resolveTextValue(preset.label),
+      value: preset.value
+    }));
+  });
+  const menu = computed(() => ({
+    items: [...options.items.value],
+    labelKey: "label",
+    multiple: definition.multiple,
+    valueKey: "value",
+    ...options.menu.value
+  }));
+  function toggle(value) {
+    if (!definition.multiple) return set(value);
+    const current = Array.isArray(get()) ? values.value : [];
+    const key = String(value);
+    if (keys.value.has(key)) return set(current.filter((entry) => String(entry) !== key));
+    if (definition.max !== void 0 && current.length >= definition.max) return;
+    const order = options.order.value;
+    const next = [...current, value];
+    if (order) {
+      const rank = (entry) => order.get(String(entry)) ?? order.size;
+      next.sort((first, second) => rank(first) - rank(second));
+    }
+    set(next);
+  }
+  return markRaw({
+    get changed() {
+      return changed.value;
+    },
+    get columns() {
+      return definition.columns;
+    },
+    get defaultValue() {
+      return definition.resolveDefault();
+    },
+    get display() {
+      return display.value;
+    },
+    get error() {
+      return options.error.value;
+    },
+    get hasMore() {
+      return options.hasMore.value;
+    },
+    get enabled() {
+      return resolveDashboardCondition(definition.enabled);
+    },
+    headless: isDashboardFilterHeadless(definition),
+    isSelected: (value) => keys.value.has(String(value)),
+    get items() {
+      return listed ? options.items.value : [];
+    },
+    key: params.key,
+    kind: definition.kind,
+    get label() {
+      return label.value;
+    },
+    get loading() {
+      return options.loading.value;
+    },
+    get loadingMore() {
+      return options.loadingMore.value;
+    },
+    loadMore: options.loadMore,
+    max: definition.max,
+    get menu() {
+      return menu.value;
+    },
+    multiple: definition.multiple,
+    get open() {
+      return options.open.value;
+    },
+    set open(next) {
+      options.open.value = next;
+    },
+    get placeholder() {
+      return placeholder.value;
+    },
+    get presets() {
+      return presets.value;
+    },
+    refresh: options.refresh,
+    reset: () => set(definition.resolveDefault()),
+    get search() {
+      return options.search.value;
+    },
+    set search(next) {
+      options.search.value = next;
+    },
+    searchable: definition.searchable === true,
+    get selected() {
+      return selected.value;
+    },
+    toggle,
+    get value() {
+      return get();
+    },
+    set value(next) {
+      set(next);
+    }
+  });
+}

package/dist/runtime/dashboard/composables/use-dashboard-filter-scope.d.ts

@@ -0,0 +1,37 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardFilterControl, DashboardFilterLike } from '../types/index.js';
+import type { DashboardEnvironment } from '../utils/environment.js';
+/**
+ * What one filter scope exposes. Declared rather than inferred: the inferred type would carry Vue's
+ * `Raw<…>` marker, which declaration files cannot name.
+ */
+export interface DashboardFilterScope {
+    keys: readonly string[];
+    /** Controls, by filter key. */
+    controls: Readonly<Record<string, DashboardFilterControl>>;
+    /** URL segments of this scope's URL-synced filters, before the dashboard prefix. */
+    urlKeys: readonly string[];
+    /** Writable facade: one getter / setter per filter. */
+    values: object;
+    /** A filter that is enabled and not headless differs from its default. */
+    changed: () => boolean;
+    /** Restores the default of every filter that is enabled and not headless. */
+    reset: () => void;
+}
+/**
+ * Owns the filters of one scope (dashboard root, a view, or a query): where each value lives (one
+ * `useQueryStates` for the URL-synced ones, a ref per memory filter, the external ref or getter of
+ * synced ones), a writable values facade, and one control per filter. Scopes without filters
+ * allocate nothing.
+ *
+ * A URL key names one filter across the dashboard: scopes declaring the same key read and write the
+ * same value, and must declare it the same way.
+ */
+export declare function useDashboardFilterScope(params: {
+    definitions: Readonly<Record<string, DashboardFilterLike>>;
+    /** Where the scope sits, for error messages: `view "consumption"`. */
+    owner: string;
+    prefix: string;
+    queryKey: QueryKey;
+    environment: DashboardEnvironment;
+}): DashboardFilterScope;

package/dist/runtime/dashboard/composables/use-dashboard-filter-scope.js

@@ -0,0 +1,107 @@
+import { computed, isRef, markRaw, shallowRef } from "vue";
+import { useQueryStates } from "../../query-state/index.js";
+import { hasProperty, isNullish } from "../../shared/utils/predicate.js";
+import { registerDashboardFilter } from "../utils/environment.js";
+import { joinDashboardUrlKey, resolveDashboardCondition } from "../utils/state.js";
+import { useDashboardFilterControl } from "./use-dashboard-filter-control.js";
+const emptyFacade = markRaw({});
+const noUrlKeys = [];
+export function useDashboardFilterScope(params) {
+  const entries = Object.entries(params.definitions).flatMap(
+    ([key, definition]) => isRuntimeFilter(definition) ? [[key, definition]] : []
+  );
+  if (entries.length === 0)
+    return {
+      changed: () => false,
+      controls: emptyFacade,
+      keys: [],
+      reset() {
+      },
+      urlKeys: noUrlKeys,
+      values: emptyFacade
+    };
+  const urlEntries = entries.filter(([, definition]) => (definition.sync ?? "url") === "url");
+  const schema = {};
+  for (const [key, definition] of urlEntries) {
+    registerDashboardFilter(params.environment.registry, {
+      definition,
+      owner: `${params.owner} ("${key}")`,
+      urlKey: joinDashboardUrlKey(params.prefix, definition.urlKey ?? key)
+    });
+    schema[key] = {
+      codec: definition.codec,
+      defaultValue: definition.defaultValue,
+      historyMode: definition.historyMode,
+      omitDefault: definition.omitDefault,
+      urlKey: definition.urlKey
+    };
+  }
+  const state = urlEntries.length > 0 ? useQueryStates({ historyMode: "replace", prefix: params.prefix, schema }) : null;
+  function createAccessor(key, definition) {
+    const { defaultValue, sync = "url" } = definition;
+    if (sync === "url" && state) {
+      return {
+        get: () => {
+          const current = state.value;
+          return current[key];
+        },
+        set: (value) => {
+          state.value = { ...state.value, [key]: value };
+        }
+      };
+    }
+    if (sync === "url" || sync === "memory") {
+      const cell = shallowRef(defaultValue);
+      return { get: () => cell.value, set: (value) => cell.value = value };
+    }
+    if (isRef(sync)) return { get: () => sync.value, set: (value) => sync.value = value };
+    return { get: () => sync(), set() {
+    } };
+  }
+  const values = {};
+  const controls = {};
+  for (const [key, definition] of entries) {
+    const accessor = createAccessor(key, definition);
+    const { codec, multiple } = definition;
+    const enabled = () => resolveDashboardCondition(definition.enabled);
+    const get = () => {
+      if (!enabled()) return definition.resolveDefault();
+      const value = accessor.get();
+      const unset = isNullish(value) || multiple && Array.isArray(value) && value.length === 0;
+      return unset ? definition.resolveDefault() : value;
+    };
+    const set = (value) => {
+      if (!enabled()) return;
+      const next = value ?? definition.resolveDefault();
+      const isDefault = codec.serialize(next) === codec.serialize(definition.resolveDefault());
+      accessor.set(isDefault ? definition.defaultValue : next);
+    };
+    Object.defineProperty(values, key, { enumerable: true, get, set });
+    definition.bind(get);
+    controls[key] = useDashboardFilterControl({
+      definition,
+      get,
+      key,
+      locale: params.environment.locale,
+      queryKey: [...params.queryKey, key],
+      set
+    });
+  }
+  const visible = Object.values(controls).filter((control) => !control.headless);
+  const changed = computed(
+    () => visible.some((control) => control.enabled && control.changed)
+  );
+  return {
+    changed: () => changed.value,
+    controls: markRaw(controls),
+    keys: entries.map(([key]) => key),
+    reset() {
+      for (const control of visible) if (control.enabled) control.reset();
+    },
+    urlKeys: urlEntries.map(([key, definition]) => definition.urlKey ?? key),
+    values: markRaw(values)
+  };
+}
+function isRuntimeFilter(definition) {
+  return hasProperty(definition, "codec");
+}

package/dist/runtime/dashboard/composables/use-dashboard-format.d.ts

@@ -1,6 +1,46 @@
-/** Locale-aware default formatters used when a block receives no explicit `format`. */
-export declare function useDashboardFormat(): {
-    delta: import("vue").ComputedRef<import("../types/index.js").DashboardValueFormat>;
-    number: import("vue").ComputedRef<import("../types/index.js").DashboardValueFormat>;
-    percent: import("vue").ComputedRef<import("../types/index.js").DashboardValueFormat>;
-};
+import type { DashboardFormatPreset, DashboardValueFormat, DashboardValueFormatter } from '../types/index.js';
+/**
+ * The number and month formatters dashboard blocks use, in the dashboard locale (the Nuxt UI locale
+ * unless overridden). Use them for captions, labels, and any text next to a block so everything on
+ * screen reads the same way. Reads are reactive: a locale switch re-renders what used them.
+ *
+ * @example
+ * ```ts
+ * const format = useDashboardFormat()
+ * format.integer(12345) // "12,345"
+ * format.percent(57) // "57%"
+ * format.points(2.1) // "+2.1 pts"
+ * format.currency(1200, 'EUR') // "€1,200"
+ * format.month(3) // "Mar"
+ * format.ratio(null) // "—"
+ * ```
+ *
+ * Every number formatter takes `null` / `undefined` too, and prints "—" for them, so a missing rate
+ * or an empty period needs no fallback in the template.
+ */
+export declare function useDashboardFormat(): import("vue").Raw<{
+    /** `12600` → "12.6K". */
+    compact: (value: number | null | undefined) => string;
+    /** An amount in a currency, rounded to units unless `options` say otherwise. */
+    currency: (value: number | null | undefined, currency: string, options?: Intl.NumberFormatOptions) => string;
+    /** One decimal at most. */
+    decimal: (value: number | null | undefined) => string;
+    /** Signed percent change: `12.4` → "+12.4%". */
+    delta: (value: number | null | undefined) => string;
+    /** Grouped, no decimals. */
+    integer: (value: number | null | undefined) => string;
+    /** Month name, capitalized: `3` (1–12) or a date → "Mar" (`'long'`: "March"). */
+    month: (value: number | Date, width?: "short" | "long") => string;
+    /** Grouped, one decimal at most, compact from 10,000. */
+    number: (value: number | null | undefined) => string;
+    /** A share out of 100: `57` → "57%". */
+    percent: (value: number | null | undefined) => string;
+    points: (value: number | null | undefined) => string;
+    /** A share out of 1: `0.57` → "57%". */
+    ratio: (value: number | null | undefined) => string;
+    resolve: (format: DashboardValueFormat | undefined, fallback?: DashboardFormatPreset) => DashboardValueFormatter;
+    /** Signed number: `3` → "+3". */
+    signed: (value: number | null | undefined) => string;
+}>;
+/** Text of a missing number: an empty period, a rate without a base. */
+export declare const DASHBOARD_MISSING_VALUE = "\u2014";