nuxt-ui-tools 1.0.1 → 1.1.0

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

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

package/dist/runtime/dashboard/utils/chart-frame.d.ts

@@ -0,0 +1,5 @@
+import type { DashboardChartDatum, DashboardChartFrame, DashboardDataTable } from '../types/index.js';
+/** Table of a chart: one row per x position, one column per series, values in their axis format. */
+export declare function tabulateDashboardFrame(frame: DashboardChartFrame, category: string): DashboardDataTable;
+/** Tooltip HTML for one x position: the label, then one row per series with its formatted value. */
+export declare function renderDashboardChartTooltip(frame: DashboardChartFrame, datum: DashboardChartDatum): string;

package/dist/runtime/dashboard/utils/chart-frame.js

@@ -0,0 +1,27 @@
+import { escapeDashboardHtml } from "./charts.js";
+import { toDashboardCell } from "./export.js";
+export function tabulateDashboardFrame(frame, category) {
+  return {
+    columns: [
+      { key: "$x", label: category, numeric: false },
+      ...frame.series.map((series) => ({ key: series.key, label: series.label, numeric: true }))
+    ],
+    rows: frame.data.map((datum) => [
+      toDashboardCell(frame.labels[datum.index]),
+      ...frame.series.map((series) => {
+        const value = datum.values[series.index];
+        const axis = series.axis === "right" && frame.right ? frame.right : frame.left;
+        return toDashboardCell(value, value === void 0 ? "" : axis.format(value));
+      })
+    ])
+  };
+}
+export function renderDashboardChartTooltip(frame, datum) {
+  const rows = frame.series.map((series) => {
+    const value = datum.values[series.index];
+    if (value === void 0) return "";
+    const axis = series.axis === "right" && frame.right ? frame.right : frame.left;
+    return `<div class="nut-dash-tip-row"><i style="background:${series.color}"></i><span>${escapeDashboardHtml(series.label)}</span><b>${escapeDashboardHtml(axis.format(value))}</b></div>`;
+  }).join("");
+  return `<div class="nut-dash-tip"><div class="nut-dash-tip-title">${escapeDashboardHtml(frame.labels[datum.index] ?? "")}</div>${rows}</div>`;
+}

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

@@ -0,0 +1,61 @@
+import type { DashboardAxisOptions, DashboardChartFrameAxis, DashboardHighlight, DashboardLegendItem, DashboardSelected, DashboardSeries, DashboardSeriesColor, DashboardValueFormat } 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
+ * charts follow the theme and dark mode without re-rendering. Nuxt UI has no `--ui-neutral` (neutral
+ * is only a scale), so `neutral` maps to the muted text gray, which adapts to the color mode.
+ */
+export declare function resolveDashboardColor(color: DashboardSeriesColor | undefined, index: number): string;
+/** A series with its display fields resolved once per render. */
+export interface DashboardResolvedSeries<TRow> {
+    key: string;
+    label: string;
+    color: string;
+    dashed: boolean;
+    type: 'bar' | 'line' | 'area';
+    axis: 'left' | 'right';
+    value: DashboardSeries<TRow>['value'];
+}
+/**
+ * A faded tone of a color, mixed into the page background: `keep` percent of the color remains.
+ * Used for the bars that recede around a highlight or a selection, and for comparison series.
+ */
+export declare function fadeDashboardColor(color: string, keep?: number): string;
+/**
+ * Resolves the series of a chart. A series with `compare` expands into itself and its comparison
+ * series right after it: a faded bar, or a dashed line for lines and areas.
+ */
+export declare function resolveDashboardSeries<TRow>(series: readonly DashboardSeries<TRow>[], defaultType: 'bar' | 'line' | 'area', compareLabel?: (label: string) => string): DashboardResolvedSeries<TRow>[];
+/**
+ * Datums a bar chart draws at full strength, or `null` when every datum does. A selection wins over
+ * a highlight; `max`, `min`, and `last` read the total of each datum's values.
+ */
+export declare function resolveDashboardEmphasis<TRow>(rows: readonly TRow[], totals: readonly number[], highlight: DashboardHighlight<TRow> | undefined, selected: DashboardSelected<TRow> | undefined): boolean[] | null;
+export declare function toDashboardLegend<TRow>(series: readonly DashboardResolvedSeries<TRow>[]): DashboardLegendItem[];
+/** Rounds a maximum up to a readable axis bound (1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8 × 10ⁿ). */
+export declare function niceDashboardMax(value: number): number;
+/** Readable interval count for a nice maximum: `2000` → 4 (every 500), `1500` → 3, `50` → 5. */
+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.
+ */
+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. */
+export declare function createDashboardSeededRandom(seed: string): () => number;

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

@@ -0,0 +1,142 @@
+import { isNullish } from "../../shared/utils/predicate.js";
+import { resolveTextValue } from "../../shared/utils/render.js";
+export const DASHBOARD_PALETTE_SIZE = 6;
+const nuxtUiColors = /* @__PURE__ */ new Set(["error", "info", "primary", "secondary", "success", "warning"]);
+export function resolveDashboardColor(color, index) {
+  if (isNullish(color)) return `var(--nut-dash-s${index % DASHBOARD_PALETTE_SIZE + 1})`;
+  const slot = /^series-(\d)$/u.exec(color);
+  if (slot) return `var(--nut-dash-s${slot[1]})`;
+  if (color === "neutral") return "var(--ui-text-muted)";
+  if (nuxtUiColors.has(color)) return `var(--ui-${color})`;
+  return color;
+}
+export function fadeDashboardColor(color, keep = 30) {
+  return `color-mix(in oklab, ${color} ${keep}%, var(--ui-bg))`;
+}
+export function resolveDashboardSeries(series, defaultType, compareLabel = (label) => label) {
+  return series.flatMap((entry, index) => {
+    const type = entry.type ?? defaultType;
+    const label = resolveTextValue(entry.label, entry.key);
+    const resolved = {
+      // Bars always use the left axis: the secondary axis only draws lines and areas.
+      axis: type === "bar" ? "left" : entry.axis ?? "left",
+      color: resolveDashboardColor(entry.color, index),
+      dashed: entry.dashed ?? false,
+      key: entry.key,
+      label,
+      type,
+      value: entry.value
+    };
+    if (!entry.compare) return [resolved];
+    return [
+      resolved,
+      {
+        axis: resolved.axis,
+        color: fadeDashboardColor(resolved.color, type === "bar" ? 38 : 55),
+        dashed: type !== "bar",
+        key: `${entry.key}:compare`,
+        label: resolveTextValue(entry.compareLabel, compareLabel(label)),
+        type: type === "bar" ? "bar" : "line",
+        value: entry.compare
+      }
+    ];
+  });
+}
+export function resolveDashboardEmphasis(rows, totals, highlight, selected) {
+  const picked = selected ? rows.map((row, index) => selected(row, index)) : [];
+  if (picked.includes(true)) return picked;
+  if (!highlight || rows.length === 0) return null;
+  if (highlight === "last") return rows.map((_, index) => index === rows.length - 1);
+  if (highlight === "max" || highlight === "min") {
+    const target = highlight === "max" ? Math.max(...totals) : Math.min(...totals);
+    const first = totals.indexOf(target);
+    return rows.map((_, index) => index === first);
+  }
+  return rows.map((row, index) => highlight(row, index));
+}
+export function toDashboardLegend(series) {
+  return series.map(({ color, dashed, key, label }) => ({ color, dashed, key, label }));
+}
+export function niceDashboardMax(value) {
+  if (value <= 0) return 1;
+  const power = 10 ** Math.floor(Math.log10(value));
+  const step = [1, 1.2, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10].find((candidate) => value / power <= candidate) ?? 10;
+  return step * power;
+}
+const niceTickCounts = /* @__PURE__ */ new Map([
+  [1, 4],
+  [1.2, 4],
+  [1.5, 3],
+  [2, 4],
+  [2.5, 5],
+  [3, 3],
+  [4, 4],
+  [5, 5],
+  [6, 3],
+  [8, 4],
+  [10, 5]
+]);
+export function niceDashboardTickCount(max) {
+  if (max <= 0) return 4;
+  const power = 10 ** Math.floor(Math.log10(max));
+  return niceTickCounts.get(Number((max / power).toFixed(2))) ?? 4;
+}
+export function resolveDashboardAxis(values, axis, headroom = 1.05) {
+  const finite = values.filter((value) => Number.isFinite(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);
+  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 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);
+  const power = 10 ** Math.floor(Math.log10(rough));
+  const step = ([1, 2, 2.5, 5, 10].find((candidate) => rough / power <= candidate) ?? 10) * power;
+  const min = -Math.ceil(bottom / step) * step;
+  const max = Math.ceil(top / step) * step;
+  const count = Math.max(1, Math.round((max - min) / step));
+  return {
+    domain: [min, max],
+    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;");
+}
+export function createDashboardSeededRandom(seed) {
+  let state = [...seed].reduce(
+    (hash, char) => Math.imul(hash ^ char.charCodeAt(0), 16777619),
+    2166136261
+  );
+  return () => {
+    state = Math.imul(state ^ state >>> 15, state | 1);
+    state ^= state + Math.imul(state ^ state >>> 7, state | 61);
+    return ((state ^ state >>> 14) >>> 0) / 4294967296;
+  };
+}

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

@@ -0,0 +1,15 @@
+import type { DashboardComparison, DashboardDateRange } from '../types/index.js';
+/**
+ * Range to compare `range` against: the period of the same length right before it (`previous`), or
+ * the same dates a year earlier (`year`, Feb 29 falling back to Feb 28). `undefined` without a range
+ * or with `none`. Days are calendar days: the result never drifts across daylight-saving changes.
+ *
+ * @example
+ * ```ts
+ * queryFn: () => api.revenue({
+ *   range: params.range,
+ *   previous: resolveDashboardComparisonRange(params.range, params.compare),
+ * })
+ * ```
+ */
+export declare function resolveDashboardComparisonRange(range: DashboardDateRange | null | undefined, comparison: DashboardComparison | null | undefined): DashboardDateRange | undefined;

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

@@ -0,0 +1,19 @@
+export function resolveDashboardComparisonRange(range, comparison) {
+  if (!range || !comparison || comparison === "none") return void 0;
+  if (comparison === "year") return { end: yearBefore(range.end), start: yearBefore(range.start) };
+  const days = calendarDaysBetween(range.start, range.end) + 1;
+  const end = addDays(range.start, -1);
+  return { end, start: addDays(end, -(days - 1)) };
+}
+function addDays(date, days) {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+}
+function yearBefore(date) {
+  const shifted = new Date(date.getFullYear() - 1, date.getMonth(), date.getDate());
+  return shifted.getMonth() === date.getMonth() ? shifted : new Date(shifted.getFullYear(), shifted.getMonth(), 0);
+}
+function calendarDaysBetween(start, end) {
+  const from = Date.UTC(start.getFullYear(), start.getMonth(), start.getDate());
+  const to = Date.UTC(end.getFullYear(), end.getMonth(), end.getDate());
+  return Math.max(0, Math.round((to - from) / 864e5));
+}

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

@@ -0,0 +1,13 @@
+import type { DashboardDataCell, DashboardDataTable } from '../types/index.js';
+/** A table cell from a raw value and, optionally, its display text (defaults to the value). */
+export declare function toDashboardCell(value: string | number | null | undefined, text?: string): DashboardDataCell;
+/**
+ * Serializes a data table to CSV the way spreadsheet apps of the locale read it: numbers are raw
+ * (not formatted) with the locale decimal mark, and locales whose decimal mark is a comma use `;`
+ * between fields. Every text field is quoted.
+ */
+export declare function toDashboardCsv(table: DashboardDataTable, locale: string): string;
+/** File name from a card title: `Consommation mensuelle` → `consommation-mensuelle.csv`. */
+export declare function resolveDashboardFileName(title: string, extension: string): string;
+/** Downloads text as a file. The BOM lets spreadsheet apps detect UTF-8 (accents, `€`). */
+export declare function downloadDashboardFile(name: string, content: string, type?: string): void;

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

@@ -0,0 +1,45 @@
+import { isNumber } from "../../shared/utils/predicate.js";
+export function toDashboardCell(value, text) {
+  return {
+    text: text ?? (value === null || value === void 0 ? "" : String(value)),
+    value: value ?? null
+  };
+}
+const decimalByLocale = /* @__PURE__ */ new Map();
+function decimalSeparator(locale) {
+  let separator = decimalByLocale.get(locale);
+  if (separator === void 0) {
+    separator = new Intl.NumberFormat(locale).formatToParts(1.5).find((part) => part.type === "decimal")?.value ?? ".";
+    decimalByLocale.set(locale, separator);
+  }
+  return separator;
+}
+export function toDashboardCsv(table, locale) {
+  const decimal = decimalSeparator(locale);
+  const delimiter = decimal === "," ? ";" : ",";
+  const field = (cell) => {
+    if (cell.value === null) return "";
+    if (isNumber(cell.value)) return String(cell.value).replace(".", decimal);
+    return quote(cell.value);
+  };
+  const lines = [
+    table.columns.map((column) => quote(column.label)).join(delimiter),
+    ...table.rows.map((row) => row.map(field).join(delimiter))
+  ];
+  return lines.join("\r\n");
+}
+function quote(text) {
+  return `"${text.replaceAll('"', '""')}"`;
+}
+export function resolveDashboardFileName(title, extension) {
+  const slug = title.normalize("NFD").replaceAll(/[̀-ͯ]/gu, "").toLowerCase().replaceAll(/[^a-z0-9]+/gu, "-").replaceAll(/^-+|-+$/gu, "");
+  return `${slug || "dashboard"}.${extension}`;
+}
+export function downloadDashboardFile(name, content, type = "text/csv") {
+  const url = URL.createObjectURL(new Blob(["\uFEFF", content], { type: `${type};charset=utf-8` }));
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = name;
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

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

@@ -0,0 +1,12 @@
+import type { RemoteOptionsResult } from '../../shared/types/remote-options.js';
+import type { DashboardOption } from '../types/index.js';
+export interface DashboardRemotePageParam {
+    index: number;
+    cursor: string | null;
+}
+/** Normalizes a single or multiple param value to its string keys, in value order. */
+export declare function resolveDashboardOptionValues(value: unknown): string[];
+/** Next page of a page- or cursor-paginated remote source, or `undefined` at the end. */
+export declare function resolveDashboardRemoteNextPage(page: RemoteOptionsResult<DashboardOption<string>>, loadedPages: number): DashboardRemotePageParam | undefined;
+/** Unique options by value, keeping the first occurrence. */
+export declare function mergeDashboardOptions(...lists: readonly (readonly DashboardOption[])[]): DashboardOption[];

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

@@ -0,0 +1,23 @@
+import { isNullish } from "../../shared/utils/predicate.js";
+export function resolveDashboardOptionValues(value) {
+  if (Array.isArray(value)) return value.filter((entry) => !isNullish(entry)).map(String);
+  return isNullish(value) ? [] : [String(value)];
+}
+export function resolveDashboardRemoteNextPage(page, loadedPages) {
+  if ("nextCursor" in page)
+    return page.nextCursor ? { cursor: page.nextCursor, index: loadedPages + 1 } : void 0;
+  return page.hasMore ? { cursor: null, index: loadedPages + 1 } : void 0;
+}
+export function mergeDashboardOptions(...lists) {
+  const seen = /* @__PURE__ */ new Set();
+  const merged = [];
+  for (const list of lists) {
+    for (const option of list) {
+      const key = String(option.value);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      merged.push(option);
+    }
+  }
+  return merged;
+}

package/dist/runtime/dashboard/utils/params/codecs.d.ts

@@ -0,0 +1,14 @@
+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>;
+/** Calendar date, serialized as local `YYYY-MM-DD` so it never shifts across time zones. */
+export declare const localDateCodec: QueryCodec<Date | undefined>;
+export declare const dateRangeCodec: QueryCodec<DashboardDateRange | undefined>;
+/** Single value from a fixed list of strings or numbers. Unknown raw values parse to `undefined`. */
+export declare function createOptionValueCodec(values: readonly DashboardOptionValue[]): QueryCodec<DashboardOptionValue | undefined>;
+/** Comma-separated list over an item codec. Invalid items are dropped; empty lists leave the URL. */
+export declare function createListCodec<TItem>(itemCodec: QueryCodec<TItem | undefined>): QueryCodec<TItem[] | undefined>;
+/** Wraps a consumer codec so parse failures fall back to the default instead of throwing. */
+export declare function createSafeCodec<TValue>(codec: QueryCodec<TValue>): QueryCodec<TValue | undefined>;

package/dist/runtime/dashboard/utils/params/codecs.js

@@ -0,0 +1,69 @@
+import { isNullish } from "../../../shared/utils/predicate.js";
+export const optionalStringCodec = {
+  parse: (raw) => raw === "" ? void 0 : raw,
+  serialize: (value) => isNullish(value) || value === "" ? null : value
+};
+export const optionalNumberCodec = {
+  parse(raw) {
+    const value = Number(raw);
+    return raw === "" || Number.isNaN(value) ? void 0 : value;
+  },
+  serialize: (value) => isNullish(value) ? null : String(value)
+};
+export const optionalBooleanCodec = {
+  parse: (raw) => raw === "true" ? true : raw === "false" ? false : void 0,
+  serialize: (value) => isNullish(value) ? null : String(value)
+};
+export const localDateCodec = {
+  parse: parseLocalDate,
+  serialize: (value) => isNullish(value) ? null : formatLocalDate(value)
+};
+export const dateRangeCodec = {
+  parse(raw) {
+    const [start, end] = raw.split("..").map(parseLocalDate);
+    return start && end ? { end, start } : void 0;
+  },
+  serialize: (value) => isNullish(value) ? null : `${formatLocalDate(value.start)}..${formatLocalDate(value.end)}`
+};
+export function createOptionValueCodec(values) {
+  const byRaw = new Map(values.map((value) => [String(value), value]));
+  return {
+    parse: (raw) => byRaw.get(raw),
+    serialize: (value) => isNullish(value) || !byRaw.has(String(value)) ? null : String(value)
+  };
+}
+export function createListCodec(itemCodec) {
+  return {
+    parse(raw) {
+      if (raw === "") return [];
+      return raw.split(",").map((part) => itemCodec.parse(part)).filter((item) => item !== void 0);
+    },
+    serialize(value) {
+      if (isNullish(value) || value.length === 0) return null;
+      return value.map((item) => itemCodec.serialize(item)).filter((item) => item !== null).join(",");
+    }
+  };
+}
+export function createSafeCodec(codec) {
+  return {
+    parse(raw) {
+      try {
+        return codec.parse(raw);
+      } catch {
+        return void 0;
+      }
+    },
+    serialize: (value) => value === void 0 ? null : codec.serialize(value)
+  };
+}
+function parseLocalDate(raw) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/u.exec(raw);
+  if (!match) return void 0;
+  const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+function formatLocalDate(value) {
+  const month = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  return `${value.getFullYear()}-${month}-${day}`;
+}

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

@@ -0,0 +1,16 @@
+import type { ShallowRef } from 'vue';
+import type { useDashboardResource } from '../composables/use-dashboard-resource.js';
+import type { DashboardSourceLike, DashboardStage } from '../types/index.js';
+export type DashboardResourceSlot = ShallowRef<ReturnType<typeof useDashboardResource> | null>;
+/**
+ * Public resource object returned by `stage.query(...)`. It exists before its key is known (keys
+ * come from the object the `queries` builder returns), so it reads the resource runtime through a
+ * slot. Reads before instantiation track the slot, which keeps dependent gates reactive.
+ */
+export declare function createDashboardResourceFacade(stage: DashboardStage, slot: DashboardResourceSlot, defaultValue: unknown): DashboardSourceLike & {
+    kind: 'query';
+    stage: DashboardStage;
+    active: boolean;
+    params: object;
+    options: object;
+};

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

@@ -0,0 +1,39 @@
+import { markRaw } from "vue";
+const emptyFacade = markRaw({});
+export function createDashboardResourceFacade(stage, slot, defaultValue) {
+  return markRaw({
+    activate() {
+      slot.value?.activate();
+    },
+    get active() {
+      return slot.value?.active.value ?? false;
+    },
+    get data() {
+      return slot.value ? slot.value.data.value : defaultValue;
+    },
+    get error() {
+      return slot.value?.error.value ?? void 0;
+    },
+    get id() {
+      return slot.value?.id ?? "";
+    },
+    kind: "query",
+    get options() {
+      return slot.value?.widget.options ?? emptyFacade;
+    },
+    get params() {
+      return slot.value?.widget.values ?? emptyFacade;
+    },
+    refresh: () => slot.value?.refresh() ?? Promise.resolve(),
+    get refreshing() {
+      return slot.value?.refreshing.value ?? false;
+    },
+    stage,
+    get state() {
+      return slot.value?.state.value ?? "idle";
+    },
+    get updatedAt() {
+      return slot.value?.updatedAt.value;
+    }
+  });
+}

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

@@ -0,0 +1,9 @@
+import type { DashboardSchemaLike } from '../types/index.js';
+import type { DashboardRuntimeSchema } from '../types/runtime.js';
+/**
+ * Erases the schema generics once so the runtime can invoke every builder with the contexts it
+ * creates. Views are resolved here (their builder is an identity function at runtime).
+ */
+export declare function resolveDashboardRuntimeSchema(schema: DashboardSchemaLike): DashboardRuntimeSchema;
+/** Dev guard mirroring the compile-time key checks, for schemas assembled without inference. */
+export declare function assertDashboardMemberKey(key: string, taken: ReadonlySet<string>, scope: string): void;

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

@@ -0,0 +1,31 @@
+const reservedKeys = /* @__PURE__ */ new Set([
+  "autoRefresh",
+  "options",
+  "params",
+  "refresh",
+  "refreshing",
+  "schema",
+  "state",
+  "updatedAt",
+  "view"
+]);
+export function resolveDashboardRuntimeSchema(schema) {
+  const input = schema;
+  const views = Object.entries(input.views?.((view) => view) ?? {});
+  return {
+    autoRefresh: input.autoRefresh,
+    defaultView: input.defaultView ?? views[0]?.[0],
+    derive: input.derive,
+    key: input.key,
+    label: input.label,
+    params: input.params,
+    queries: input.queries,
+    urlPrefix: input.urlPrefix,
+    views
+  };
+}
+export function assertDashboardMemberKey(key, taken, scope) {
+  if (reservedKeys.has(key) || taken.has(key)) {
+    throw new Error(`[dashboard] "${key}" in ${scope} is reserved or already used.`);
+  }
+}