nuxt-ui-tools 1.1.0 → 1.3.0

package/dist/runtime/dashboard/components/dashboard-list.vue.d.ts

@@ -1,3 +1,4 @@
+import type { RouteLocationRaw } from 'vue-router';
 import type { LazyTextValue } from '#ui-tools/shared/types/utils';
 import type { DashboardBlockBaseProps, DashboardBlockUi, DashboardListUi, DashboardRowActions, DashboardSelected, DashboardSelectEvent, DashboardSeriesColor, DashboardSourceLike, DashboardValueFormat } from '../types/index.js';
 declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
@@ -27,6 +28,8 @@ declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS
         rowKey?: (row: TRow, index: number) => PropertyKey;
         /** Rows shown as selected (the value a `select` handler stored). */
         selected?: DashboardSelected<TRow>;
+        /** Makes each row a link to what this returns (rows returning `undefined` stay plain). */
+        to?: (row: TRow, index: number) => RouteLocationRaw | undefined;
         /** Actions of each row: inline icon buttons and a `⋮` menu at the end of the row. */
         rowActions?: DashboardRowActions<TRow>;
         /** Makes each row a button. */

package/dist/runtime/dashboard/components/dashboard-page.d.vue.ts

@@ -0,0 +1,53 @@
+import type { ButtonProps } from '@nuxt/ui/components/Button.vue';
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { DashboardPageTarget, DashboardPageUi, DashboardViewKeysOf } from '../types/index.js';
+declare const __VLS_export: <TDashboard extends DashboardPageTarget>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        dashboard: TDashboard;
+        title?: LazyTextValue;
+        /**
+         * Line under the title. Defaults to today's date and when the data on screen was fetched;
+         * `false` removes it.
+         */
+        description?: LazyTextValue | false;
+        /** Buttons before the refresh control. A button with an icon shows only the icon on phones. */
+        actions?: readonly ButtonProps[];
+        /** The refresh control and its auto-refresh menu. Defaults to `true`. */
+        refresh?: boolean;
+        /** The view tabs, while two views or more are enabled. Defaults to `true`. */
+        tabs?: boolean;
+        /** The filter bar. Defaults to `true`. */
+        filters?: boolean;
+        /** Keeps the tabs and the filter bar pinned while the page scrolls. Defaults to `true`. */
+        sticky?: boolean;
+        ui?: DashboardPageUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: { [TKey in DashboardViewKeysOf<TDashboard>]?: (() => unknown) | undefined; } & {
+        /** Content of a dashboard without views, or of a view without its own slot. */
+        default?: (props: {
+            view: DashboardViewKeysOf<TDashboard> | undefined;
+        }) => unknown;
+        title?: () => unknown;
+        description?: () => unknown;
+        /** Replaces the page actions and the refresh control. */
+        actions?: () => unknown;
+        /** Replaces the view tabs. */
+        tabs?: () => unknown;
+        /** Replaces the filter bar, e.g. with a `UiDashboardFilters` that customizes some filters. */
+        filters?: () => unknown;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/dashboard/components/dashboard-page.vue

@@ -0,0 +1,156 @@
+<script setup>
+import UButton from "@nuxt/ui/components/Button.vue";
+import { twMerge } from "tailwind-merge";
+import { computed, onBeforeUnmount, shallowRef, useTemplateRef, watch } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { isObject, isString } from "#ui-tools/shared/utils/predicate";
+import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import { useDashboardTime } from "../composables/use-dashboard-time";
+import { useDashboardUi } from "../composables/use-dashboard-ui";
+import { resolveDashboardClasses } from "../utils/ui";
+import DashboardViewScope from "./block/dashboard-view-scope.vue";
+import DashboardFilters from "./dashboard-filters.vue";
+import DashboardRefresh from "./dashboard-refresh.vue";
+import DashboardRelativeTime from "./dashboard-relative-time.vue";
+import DashboardViewTabs from "./dashboard-view-tabs.vue";
+const {
+  dashboard,
+  title = void 0,
+  description = void 0,
+  actions = [],
+  refresh = true,
+  tabs = true,
+  filters = true,
+  sticky = true,
+  ui
+} = defineProps({
+  dashboard: { type: null, required: true },
+  title: { type: [String, Number, Function], required: false },
+  description: { type: [String, Number, Function, Boolean], required: false },
+  actions: { type: Array, required: false },
+  refresh: { type: Boolean, required: false },
+  tabs: { type: Boolean, required: false },
+  filters: { type: Boolean, required: false },
+  sticky: { type: Boolean, required: false },
+  ui: { type: Object, required: false }
+});
+defineSlots();
+const { t } = useUiToolsLocale();
+const time = useDashboardTime();
+const appUi = useDashboardUi();
+const classes = computed(
+  () => resolveDashboardClasses(
+    {
+      actions: "flex min-h-[34px] items-center gap-2",
+      body: "flex flex-col gap-4 px-4 pt-1 pb-12 lg:gap-6 lg:px-7 lg:pb-15",
+      description: "col-span-full mt-1 text-[12.5px] font-light text-muted md:text-[13.5px]",
+      filters: "px-4 py-3 lg:px-7 lg:py-4",
+      header: "grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-4 bg-default px-4 pt-4 pb-3.5 lg:px-7 lg:pt-[22px] lg:pb-[18px]",
+      root: "h-full overflow-auto bg-muted",
+      tabs: "bg-default px-2 lg:px-7",
+      title: "m-0 min-w-0 truncate text-2xl leading-[1.1] font-light tracking-[-0.04em] text-highlighted md:text-[30px]",
+      toolbar: [
+        "z-20 bg-muted transition-shadow duration-200 data-[stuck]:shadow-[0_10px_24px_-18px_rgb(0_0_0/0.35)]",
+        sticky && "sticky top-0"
+      ].filter(Boolean).join(" ")
+    },
+    appUi.value.page,
+    ui
+  )
+);
+const views = computed(() => hasViews(dashboard) ? dashboard : void 0);
+const current = computed(() => views.value?.view.current);
+const marker = useTemplateRef("marker");
+const stuck = shallowRef(false);
+let observer;
+watch(
+  () => sticky ? marker.value : null,
+  (element) => {
+    observer?.disconnect();
+    observer = void 0;
+    stuck.value = false;
+    if (!element || typeof IntersectionObserver === "undefined") return;
+    observer = new IntersectionObserver(
+      ([entry]) => {
+        stuck.value = Boolean(
+          entry && !entry.isIntersecting && entry.boundingClientRect.top < (entry.rootBounds?.top ?? 0)
+        );
+      },
+      { root: scrollContainer(element) }
+    );
+    observer.observe(element);
+  },
+  { flush: "post", immediate: true }
+);
+onBeforeUnmount(() => observer?.disconnect());
+function hasViews(target) {
+  return isObject(target.view) && "items" in target.view;
+}
+function scrollContainer(element) {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    if (/auto|scroll/u.test(getComputedStyle(node).overflowY)) return node;
+  }
+  return null;
+}
+function actionUi(action) {
+  const label = action.ui?.label;
+  if (!action.icon || label !== void 0 && !isString(label)) return action.ui;
+  return { ...action.ui, label: twMerge(label, "max-sm:sr-only") };
+}
+</script>
+
+<template>
+  <!-- Without a dashboard (its schema threw during setup), render nothing: that error stays the one reported. -->
+  <div v-if="dashboard" :class="classes.root" data-dashboard-page>
+    <header :class="classes.header">
+      <h1 :class="classes.title">
+        <slot name="title">{{ title === void 0 ? "" : resolveTextValue(title) }}</slot>
+      </h1>
+      <div :class="classes.actions">
+        <slot name="actions">
+          <UButton
+            v-for="(action, index) in actions"
+            :key="index"
+            color="neutral"
+            variant="outline"
+            size="md"
+            v-bind="action"
+            :ui="actionUi(action)"
+          />
+          <DashboardRefresh v-if="refresh" :dashboard :updated="false" size="md" />
+        </slot>
+      </div>
+      <p v-if="description !== false" :class="classes.description" data-allow-mismatch="text">
+        <slot name="description">
+          <template v-if="description !== void 0">{{ resolveTextValue(description) }}</template>
+          <template v-else>
+            {{ time.today() }} ·
+            <template v-if="dashboard.updatedAt !== void 0">
+              {{ t("dashboard.page.updated") }}
+              <DashboardRelativeTime :value="dashboard.updatedAt" />
+            </template>
+            <template v-else>{{ t("dashboard.page.loading") }}</template>
+          </template>
+        </slot>
+      </p>
+    </header>
+
+    <div ref="marker" aria-hidden="true" />
+    <div :class="classes.toolbar" :data-stuck="stuck || void 0">
+      <slot name="tabs">
+        <DashboardViewTabs v-if="tabs && views" :dashboard="views" :class="classes.tabs" />
+      </slot>
+      <slot name="filters">
+        <DashboardFilters v-if="filters" :dashboard :class="classes.filters" />
+      </slot>
+    </div>
+
+    <div :class="classes.body">
+      <DashboardViewScope v-if="current" :key="current" :dashboard :view="current">
+        <slot v-if="$slots[current]" :name="current" />
+        <slot v-else :view="current" />
+      </DashboardViewScope>
+      <slot v-else :view="current" />
+    </div>
+  </div>
+</template>

package/dist/runtime/dashboard/components/dashboard-page.vue.d.ts

@@ -0,0 +1,53 @@
+import type { ButtonProps } from '@nuxt/ui/components/Button.vue';
+import type { LazyTextValue } from '#ui-tools/shared/types/utils';
+import type { DashboardPageTarget, DashboardPageUi, DashboardViewKeysOf } from '../types/index.js';
+declare const __VLS_export: <TDashboard extends DashboardPageTarget>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        dashboard: TDashboard;
+        title?: LazyTextValue;
+        /**
+         * Line under the title. Defaults to today's date and when the data on screen was fetched;
+         * `false` removes it.
+         */
+        description?: LazyTextValue | false;
+        /** Buttons before the refresh control. A button with an icon shows only the icon on phones. */
+        actions?: readonly ButtonProps[];
+        /** The refresh control and its auto-refresh menu. Defaults to `true`. */
+        refresh?: boolean;
+        /** The view tabs, while two views or more are enabled. Defaults to `true`. */
+        tabs?: boolean;
+        /** The filter bar. Defaults to `true`. */
+        filters?: boolean;
+        /** Keeps the tabs and the filter bar pinned while the page scrolls. Defaults to `true`. */
+        sticky?: boolean;
+        ui?: DashboardPageUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: { [TKey in DashboardViewKeysOf<TDashboard>]?: (() => unknown) | undefined; } & {
+        /** Content of a dashboard without views, or of a view without its own slot. */
+        default?: (props: {
+            view: DashboardViewKeysOf<TDashboard> | undefined;
+        }) => unknown;
+        title?: () => unknown;
+        description?: () => unknown;
+        /** Replaces the page actions and the refresh control. */
+        actions?: () => unknown;
+        /** Replaces the view tabs. */
+        tabs?: () => unknown;
+        /** Replaces the filter bar, e.g. with a `UiDashboardFilters` that customizes some filters. */
+        filters?: () => unknown;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/dashboard/components/dashboard-paired-bars.vue

@@ -34,12 +34,12 @@ const {
   title: { type: [String, Number, Function], required: false },
   subtitle: { type: [String, Number, Function], required: false },
   size: { type: String, required: false },
-  rows: { type: String, required: false },
   card: { type: Boolean, required: false },
   activation: { type: String, required: false },
   empty: { type: Object, required: false },
   menu: { type: [Boolean, Array, Function], required: false },
   actions: { type: Array, required: false },
+  filters: { type: Array, required: false },
   freshness: { type: Boolean, required: false },
   source: { type: Object, required: true },
   label: { type: Function, required: true },
@@ -47,7 +47,7 @@ const {
   value: { type: Function, required: true },
   totalLabel: { type: [String, Number, Function], required: false },
   valueLabel: { type: [String, Number, Function], required: false },
-  format: { type: Function, required: false },
+  format: { type: [String, Function], required: false, skipCheck: true },
   colors: { type: Array, required: false },
   limit: { type: Number, required: false },
   rowKey: { type: Function, required: false },
@@ -78,7 +78,7 @@ const legend = computed(
     { color: valueColor.value, key: "value", label: resolveTextValue(valueLabel) }
   ] : void 0
 );
-const formatValue = computed(() => format ?? formats.number.value);
+const formatValue = computed(() => formats.resolve(format));
 const entries = computed(
   () => (source.data ?? []).map((row, index) => {
     const outer = total(row);
@@ -90,7 +90,7 @@ const entries = computed(
       key: rowKey?.(row, index) ?? index,
       label: resolveTextValue(label(row)),
       outer,
-      ratio: outer > 0 ? formats.percent.value(Math.round(inner / outer * 100)) : "",
+      ratio: outer > 0 ? formats.percent(Math.round(inner / outer * 100)) : "",
       row
     };
   })

package/dist/runtime/dashboard/components/dashboard-refresh.d.vue.ts

@@ -20,7 +20,7 @@ type __VLS_Props = {
     intervals?: readonly number[];
     /** Shows when the data on screen was last fetched. */
     updated?: boolean;
-    /** Shows the "Refresh" label next to the icon. */
+    /** Shows the "Refresh" label next to the icon, from the `sm` breakpoint up (phones get the icon). */
     label?: boolean;
     size?: 'xs' | 'sm' | 'md';
 };

package/dist/runtime/dashboard/components/dashboard-refresh.vue

@@ -64,6 +64,7 @@ function refresh() {
         icon="i-lucide-refresh-cw"
         :label="label ? t('dashboard.refresh.label') : void 0"
         :aria-label="label ? void 0 : t('dashboard.refresh.label')"
+        :ui="{ label: 'max-sm:sr-only' }"
         :loading="dashboard.refreshing"
         @click="refresh"
       />

package/dist/runtime/dashboard/components/dashboard-refresh.vue.d.ts

@@ -20,7 +20,7 @@ type __VLS_Props = {
     intervals?: readonly number[];
     /** Shows when the data on screen was last fetched. */
     updated?: boolean;
-    /** Shows the "Refresh" label next to the icon. */
+    /** Shows the "Refresh" label next to the icon, from the `sm` breakpoint up (phones get the icon). */
     label?: boolean;
     size?: 'xs' | 'sm' | 'md';
 };

package/dist/runtime/dashboard/components/dashboard-stack-bar.vue

@@ -30,12 +30,12 @@ const {
   title: { type: [String, Number, Function], required: false },
   subtitle: { type: [String, Number, Function], required: false },
   size: { type: String, required: false },
-  rows: { type: String, required: false },
   card: { type: Boolean, required: false },
   activation: { type: String, required: false },
   empty: { type: Object, required: false },
   menu: { type: [Boolean, Array, Function], required: false },
   actions: { type: Array, required: false },
+  filters: { type: Array, required: false },
   freshness: { type: Boolean, required: false },
   source: { type: Object, required: true },
   label: { type: Function, required: true },
@@ -78,7 +78,7 @@ const parts = computed(() => {
       label: resolveTextValue(label(row)),
       row,
       share,
-      text: text ? resolveTextValue(text(row, share)) : formats.percent.value(share),
+      text: text ? resolveTextValue(text(row, share)) : formats.percent(share),
       width: `${share}%`
     };
   });
@@ -92,8 +92,8 @@ function tabulate() {
     ],
     rows: parts.value.map((part) => [
       toDashboardCell(part.label),
-      toDashboardCell(part.amount, formats.number.value(part.amount)),
-      toDashboardCell(Math.round(part.share * 10) / 10, formats.percent.value(part.share))
+      toDashboardCell(part.amount, formats.number(part.amount)),
+      toDashboardCell(Math.round(part.share * 10) / 10, formats.percent(part.share))
     ])
   };
 }

package/dist/runtime/dashboard/components/dashboard-stat.d.vue.ts

@@ -5,14 +5,21 @@ declare const __VLS_export: <TData>(__VLS_props: NonNullable<Awaited<typeof __VL
         source: DashboardSourceLike<TData>;
         /** KPI label, shown above the value. */
         label: LazyTextValue;
-        /** Main value. Numbers go through `format` (locale number format by default). */
-        value: (data: TData & ({} | null)) => LazyTextValue;
+        /**
+         * Main value. Numbers go through `format` (locale number format by default); `null` /
+         * `undefined` (an average without units, a rate without a base) show "—".
+         */
+        value: (data: TData & ({} | null)) => LazyTextValue | null | undefined;
         format?: DashboardValueFormat;
         /**
          * Change indicator, in percent by default. `null` hides it. Defaults to the change from
          * `compare` when that is set.
          */
         delta?: (data: TData & ({} | null)) => number | null | undefined;
+        /**
+         * Format of the delta. Defaults to a signed percent (`delta`), or with `compare-mode="difference"`
+         * to `points` for `percent` / `ratio` values and a signed number otherwise.
+         */
         deltaFormat?: DashboardValueFormat;
         /** A decrease is good news (e.g. a failure rate): colors the delta accordingly. */
         invertDelta?: boolean;
@@ -29,6 +36,11 @@ declare const __VLS_export: <TData>(__VLS_props: NonNullable<Awaited<typeof __VL
          * default `delta`, and the default caption ("vs 1,204 previous period").
          */
         compare?: (data: TData & ({} | null)) => number | null | undefined;
+        /**
+         * How the default delta compares `value` with `compare`: the relative change in percent
+         * (`change`, default), or the difference (`difference`: `+12` accounts, `+2.1 pts` of margin).
+         */
+        compareMode?: "change" | "difference";
         /**
          * Caption shown with `compare`, as text or built from the formatted previous value. Defaults to
          * "vs <value> previous period".

package/dist/runtime/dashboard/components/dashboard-stat.vue

@@ -5,7 +5,7 @@ import { computed } from "vue";
 import { useUiToolsLocale } from "#ui-tools/i18n";
 import { isNumber, isString } from "#ui-tools/shared/utils/predicate";
 import { resolveTextValue } from "#ui-tools/shared/utils/render";
-import { useDashboardFormat } from "../composables/use-dashboard-format";
+import { DASHBOARD_MISSING_VALUE, useDashboardFormat } from "../composables/use-dashboard-format";
 import { useDashboardUi } from "../composables/use-dashboard-ui";
 import { resolveDashboardColor } from "../utils/charts";
 import { resolveDashboardSparkBars, resolveDashboardSparkline } from "../utils/sparkline";
@@ -29,6 +29,7 @@ const {
   trendType = "area",
   trendColor = "series-1",
   compare,
+  compareMode = "change",
   compareLabel,
   goal,
   status,
@@ -36,19 +37,19 @@ const {
   ...block
 } = defineProps({
   size: { type: String, required: false },
-  rows: { type: String, required: false },
   card: { type: Boolean, required: false },
   activation: { type: String, required: false },
   empty: { type: Object, required: false },
   menu: { type: [Boolean, Array, Function], required: false },
   actions: { type: Array, required: false },
+  filters: { type: Array, required: false },
   freshness: { type: Boolean, required: false },
   source: { type: Object, required: true },
   label: { type: [String, Number, Function], required: true },
   value: { type: Function, required: true },
-  format: { type: Function, required: false },
+  format: { type: [String, Function], required: false, skipCheck: true },
   delta: { type: Function, required: false },
-  deltaFormat: { type: Function, required: false },
+  deltaFormat: { type: [String, Function], required: false, skipCheck: true },
   invertDelta: { type: Boolean, required: false },
   caption: { type: [String, Function], required: false },
   icon: { type: String, required: false },
@@ -56,6 +57,7 @@ const {
   trendType: { type: String, required: false },
   trendColor: { type: String, required: false },
   compare: { type: Function, required: false },
+  compareMode: { type: String, required: false },
   compareLabel: { type: [String, Number, Function], required: false },
   goal: { type: Function, required: false },
   status: { type: Function, required: false },
@@ -70,22 +72,38 @@ const ready = computed(() => {
   return data === void 0 ? null : { data };
 });
 const resolved = computed(() => ready.value ? value(ready.value.data) : void 0);
-const formatValue = computed(() => format ?? formats.number.value);
+const formatValue = computed(() => formats.resolve(format));
 const display = computed(() => {
-  if (resolved.value === void 0) return "";
-  return isNumber(resolved.value) ? formatValue.value(resolved.value) : resolveTextValue(resolved.value);
+  if (!ready.value) return "";
+  const shown = resolved.value;
+  if (shown === null || shown === void 0) return DASHBOARD_MISSING_VALUE;
+  return isNumber(shown) ? formatValue.value(shown) : resolveTextValue(shown);
 });
 const previous = computed(() => {
   if (!ready.value || !compare) return null;
   const amount = compare(ready.value.data);
   return isNumber(amount) && Number.isFinite(amount) ? amount : null;
 });
+const scale = computed(() => compareMode === "difference" && format === "ratio" ? 100 : 1);
+const deltaFallback = computed(() => {
+  if (compareMode !== "difference") return "delta";
+  return format === "percent" || format === "ratio" ? "points" : "signed";
+});
 const change = computed(() => {
   if (!ready.value) return null;
-  const amount = delta ? delta(ready.value.data) : previous.value !== null && previous.value !== 0 && isNumber(resolved.value) ? (resolved.value - previous.value) / Math.abs(previous.value) * 100 : null;
+  const current = resolved.value;
+  const before = previous.value;
+  let amount = null;
+  if (delta) amount = delta(ready.value.data);
+  else if (before !== null && isNumber(current))
+    amount = compareMode === "difference" ? (current - before) * scale.value : before === 0 ? null : (current - before) / Math.abs(before) * 100;
   if (amount === null || amount === void 0 || !Number.isFinite(amount)) return null;
   const good = invertDelta ? amount <= 0 : amount >= 0;
-  return { good, label: (deltaFormat ?? formats.delta.value)(amount), up: amount >= 0 };
+  return {
+    good,
+    label: formats.resolve(deltaFormat, deltaFallback.value)(amount),
+    up: amount >= 0
+  };
 });
 const captionText = computed(() => {
   if (!ready.value) return "";
@@ -113,7 +131,7 @@ const progress = computed(() => {
   const completion = resolved.value / target * 100;
   const filled = Math.round(Math.max(0, Math.min(100, completion)));
   return {
-    completion: formats.percent.value(completion),
+    completion: formats.percent(completion),
     filled,
     goal: t("dashboard.stat.goal", { value: formatValue.value(target) }),
     reached: completion >= 100

package/dist/runtime/dashboard/components/dashboard-stat.vue.d.ts

@@ -5,14 +5,21 @@ declare const __VLS_export: <TData>(__VLS_props: NonNullable<Awaited<typeof __VL
         source: DashboardSourceLike<TData>;
         /** KPI label, shown above the value. */
         label: LazyTextValue;
-        /** Main value. Numbers go through `format` (locale number format by default). */
-        value: (data: TData & ({} | null)) => LazyTextValue;
+        /**
+         * Main value. Numbers go through `format` (locale number format by default); `null` /
+         * `undefined` (an average without units, a rate without a base) show "—".
+         */
+        value: (data: TData & ({} | null)) => LazyTextValue | null | undefined;
         format?: DashboardValueFormat;
         /**
          * Change indicator, in percent by default. `null` hides it. Defaults to the change from
          * `compare` when that is set.
          */
         delta?: (data: TData & ({} | null)) => number | null | undefined;
+        /**
+         * Format of the delta. Defaults to a signed percent (`delta`), or with `compare-mode="difference"`
+         * to `points` for `percent` / `ratio` values and a signed number otherwise.
+         */
         deltaFormat?: DashboardValueFormat;
         /** A decrease is good news (e.g. a failure rate): colors the delta accordingly. */
         invertDelta?: boolean;
@@ -29,6 +36,11 @@ declare const __VLS_export: <TData>(__VLS_props: NonNullable<Awaited<typeof __VL
          * default `delta`, and the default caption ("vs 1,204 previous period").
          */
         compare?: (data: TData & ({} | null)) => number | null | undefined;
+        /**
+         * How the default delta compares `value` with `compare`: the relative change in percent
+         * (`change`, default), or the difference (`difference`: `+12` accounts, `+2.1 pts` of margin).
+         */
+        compareMode?: "change" | "difference";
         /**
          * Caption shown with `compare`, as text or built from the formatted previous value. Defaults to
          * "vs <value> previous period".

package/dist/runtime/dashboard/components/dashboard-stats.vue

@@ -26,12 +26,12 @@ const {
   title: { type: [String, Number, Function], required: false },
   subtitle: { type: [String, Number, Function], required: false },
   size: { type: String, required: false },
-  rows: { type: String, required: false },
   card: { type: Boolean, required: false },
   activation: { type: String, required: false },
   empty: { type: Object, required: false },
   menu: { type: [Boolean, Array, Function], required: false },
   actions: { type: Array, required: false },
+  filters: { type: Array, required: false },
   freshness: { type: Boolean, required: false },
   source: { type: Object, required: true },
   items: { type: Array, required: true },
@@ -89,14 +89,14 @@ const entries = computed(() => {
       caption: resolveTextValue(caption),
       change: isNumber(amount) && Number.isFinite(amount) ? amount : null,
       color: resolveDashboardColor(item.color, index),
-      delta: isNumber(amount) && Number.isFinite(amount) ? { good, label: formats.delta.value(amount), up: amount >= 0 } : null,
+      delta: isNumber(amount) && Number.isFinite(amount) ? { good, label: formats.delta(amount), up: amount >= 0 } : null,
       icon: item.icon,
       key: item.key,
       label: resolveTextValue(item.label),
       progress: isNumber(done) ? Math.round(Math.max(0, Math.min(100, done))) : null,
       raw,
       status: status ? { color: resolveDashboardColor(status.color, 0), label: resolveTextValue(status.label) } : null,
-      value: raw === null || raw === void 0 ? "\u2013" : isNumber(raw) ? (item.format ?? formats.number.value)(raw) : resolveTextValue(raw)
+      value: raw === null || raw === void 0 ? "\u2013" : isNumber(raw) ? formats.resolve(item.format)(raw) : resolveTextValue(raw)
     };
   });
 });

package/dist/runtime/dashboard/components/dashboard-table.d.vue.ts

@@ -18,7 +18,7 @@ declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS
     } & {
         /**
          * Sort state. Header clicks cycle a column through its natural direction (numbers descending, text
-         * ascending), the opposite one, then source order. Bind it to keep the sort in a param.
+         * ascending), the opposite one, then source order. Bind it to keep the sort in a filter.
          */
         sort?: DashboardTableSort | null | undefined;
     }) & {

package/dist/runtime/dashboard/components/dashboard-table.vue

@@ -34,12 +34,12 @@ const {
   title: { type: [String, Number, Function], required: false },
   subtitle: { type: [String, Number, Function], required: false },
   size: { type: String, required: false },
-  rows: { type: String, required: false },
   card: { type: Boolean, required: false },
   activation: { type: String, required: false },
   empty: { type: Object, required: false },
   menu: { type: [Boolean, Array, Function], required: false },
   actions: { type: Array, required: false },
+  filters: { type: Array, required: false },
   freshness: { type: Boolean, required: false },
   source: { type: Object, required: true },
   columns: { type: Array, required: true },
@@ -93,9 +93,9 @@ const entries = computed(() => {
       const { column, type } = resolved;
       if (type === "delta") {
         const good = column.invert ? value <= 0 : value >= 0;
-        return { good, text: (column.format ?? formats.delta.value)(value), value };
+        return { good, text: formats.resolve(column.format, "delta")(value), value };
       }
-      const format = column.format ?? (type === "percent" ? formats.percent.value : formats.number.value);
+      const format = formats.resolve(column.format, type === "percent" ? "percent" : "number");
       const max = maxima[position] ?? 0;
       const width = type === "bar" && max > 0 ? `${Math.max(0, Math.min(100, value / max * 100))}%` : void 0;
       return { text: format(value), value, width };

package/dist/runtime/dashboard/components/dashboard-table.vue.d.ts

@@ -18,7 +18,7 @@ declare const __VLS_export: <TRow>(__VLS_props: NonNullable<Awaited<typeof __VLS
     } & {
         /**
          * Sort state. Header clicks cycle a column through its natural direction (numbers descending, text
-         * ascending), the opposite one, then source order. Bind it to keep the sort in a param.
+         * ascending), the opposite one, then source order. Bind it to keep the sort in a filter.
          */
         sort?: DashboardTableSort | null | undefined;
     }) & {

package/dist/runtime/dashboard/components/dashboard-tabs.d.vue.ts

@@ -9,7 +9,7 @@ declare const __VLS_export: <TValue extends string | number>(__VLS_props: NonNul
         full?: boolean;
     } & {
         /**
-         * Tab strip for dashboard cards, bound with `v-model`. Bind it to a widget param to switch what a
+         * Tab strip for dashboard cards, bound with `v-model`. Bind it to a query filter to switch what a
          * block fetches (the tab lands in the URL, and the block refreshes in place), or to a local ref to
          * switch between blocks: render only the active one, so the others' deferred queries stay idle.
          */