nuxt-ui-tools 1.0.0 → 1.1.0

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

@@ -0,0 +1,46 @@
+import type { DashboardBlockBaseProps, DashboardDataTable, DashboardLegendItem, DashboardSkeletonKind, DashboardSourceLike } from '../types/index.js';
+declare const __VLS_export: <TData>(__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<DashboardBlockBaseProps & {
+        source: DashboardSourceLike<TData>;
+        /** Whether ready data has nothing to show. Defaults to `null` or an empty array. */
+        isEmpty?: (data: TData & ({} | null)) => boolean;
+        legend?: readonly DashboardLegendItem[];
+        /** Built-in skeleton drawn while the source loads, unless a `#skeleton` slot is given. */
+        skeleton?: DashboardSkeletonKind;
+        /** Tabular data behind the `table` and `csv` menu actions. */
+        tabulate?: (data: TData & ({} | null)) => DashboardDataTable;
+        /** Offers the `expand` menu action; the default slot receives `expanded`. */
+        expandable?: boolean;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default: (props: {
+            data: TData & ({} | null);
+            refreshing: boolean;
+            refresh: () => Promise<void>;
+            /** Rendered in the expand dialog. */
+            expanded: boolean;
+        }) => unknown;
+        skeleton?: () => unknown;
+        'header-right'?: (props: {
+            data: (TData & ({} | null)) | undefined;
+        }) => unknown;
+        toolbar?: () => unknown;
+        footer?: (props: {
+            data: TData & ({} | null);
+        }) => 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/composables/use-dashboard-api.d.ts

@@ -0,0 +1,15 @@
+import type { WritableComputedRef } from 'vue';
+import type { DashboardSchemaLike } from '../types/index.js';
+import type { useDashboardScope } from './use-dashboard-scope.js';
+import type { useDashboardViews } from './use-dashboard-views.js';
+/**
+ * Facade only: projects the owning scopes into the public dashboard object. Every runtime member is
+ * a getter over a ref owned elsewhere, so templates read plain values and `v-model` writes through.
+ */
+export declare function useDashboardApi(params: {
+    schema: DashboardSchemaLike;
+    /** Auto-refresh interval in seconds (URL-synced). */
+    autoRefresh: WritableComputedRef<number>;
+    root: ReturnType<typeof useDashboardScope>;
+    views: ReturnType<typeof useDashboardViews> | null;
+}): object;

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

@@ -0,0 +1,91 @@
+import { markRaw } from "vue";
+import {
+  combineDashboardStates,
+  refreshDashboardSources,
+  resolveDashboardUpdatedAt
+} from "../utils/state.js";
+export function useDashboardApi(params) {
+  const { root, views } = params;
+  const api = Object.fromEntries(root.members);
+  for (const view of views?.views ?? []) {
+    const handle = Object.fromEntries(view.scope.members);
+    Object.defineProperties(handle, {
+      ...scopeMembers(view.scope),
+      view: {
+        enumerable: true,
+        value: markRaw({
+          get active() {
+            return views?.current.value === view.key;
+          },
+          key: view.key,
+          get label() {
+            return view.label();
+          },
+          get opened() {
+            return view.opened.value;
+          }
+        })
+      }
+    });
+    api[view.key] = markRaw(handle);
+  }
+  const openedScopes = () => [
+    root,
+    ...views?.views.filter((view) => view.opened.value).map((view) => view.scope) ?? []
+  ];
+  const visibleScopes = () => {
+    const current = views?.views.find((view) => view.key === views.current.value);
+    return current ? [root, current.scope] : [root];
+  };
+  Object.defineProperties(api, {
+    ...scopeMembers(root),
+    autoRefresh: {
+      enumerable: true,
+      get: () => params.autoRefresh.value,
+      set: (seconds) => {
+        params.autoRefresh.value = Number.isFinite(seconds) ? Math.max(0, Math.round(seconds)) : 0;
+      }
+    },
+    refresh: { enumerable: true, value: () => refreshDashboardSources(openedScopes()) },
+    refreshing: {
+      enumerable: true,
+      get: () => openedScopes().some((scope) => scope.refreshing.value)
+    },
+    schema: { enumerable: true, value: params.schema },
+    state: {
+      enumerable: true,
+      get: () => combineDashboardStates(visibleScopes().map((scope) => scope.state.value))
+    },
+    updatedAt: {
+      enumerable: true,
+      get: () => resolveDashboardUpdatedAt(visibleScopes().map((scope) => scope.updatedAt.value))
+    }
+  });
+  if (views) {
+    Object.defineProperty(api, "view", {
+      enumerable: true,
+      value: markRaw({
+        get current() {
+          return views.current.value;
+        },
+        set current(next) {
+          views.current.value = next;
+        },
+        get items() {
+          return views.views.map((view) => ({ label: view.label(), value: view.key }));
+        }
+      })
+    });
+  }
+  return markRaw(api);
+}
+function scopeMembers(scope) {
+  return {
+    options: { enumerable: true, value: scope.paramScope.options },
+    params: { enumerable: true, value: scope.paramScope.values },
+    refresh: { enumerable: true, value: scope.refresh },
+    refreshing: { enumerable: true, get: () => scope.refreshing.value },
+    state: { enumerable: true, get: () => scope.state.value },
+    updatedAt: { enumerable: true, get: () => scope.updatedAt.value }
+  };
+}

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

@@ -0,0 +1,22 @@
+import type { ShallowRef } from 'vue';
+import type { DashboardBlockActivation, DashboardBlockPhase, DashboardSourceLike } from '../types/index.js';
+/**
+ * Non-visual block behaviour: reduces the source into one render phase, activates deferred sources
+ * (on mount or when the block nears the viewport), and resolves the grid placement.
+ *
+ * The phase is a branch, not a mask: while a block is `idle` or `loading`, its real values are not
+ * in the DOM at all, so nothing can flash through.
+ */
+export declare function useDashboardBlock(params: {
+    source: () => DashboardSourceLike | undefined;
+    empty: () => boolean;
+    activation: () => DashboardBlockActivation | undefined;
+    size: () => string | undefined;
+    rows: () => string | undefined;
+    root: Readonly<ShallowRef<HTMLElement | null>>;
+}): {
+    phase: import("vue").ComputedRef<DashboardBlockPhase>;
+    refreshing: import("vue").ComputedRef<boolean>;
+    retry: () => void;
+    style: import("vue").ComputedRef<string>;
+};

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

@@ -0,0 +1,35 @@
+import { computed, onBeforeUnmount, onMounted } from "vue";
+import { useResponsiveValue } from "../../shared/composables/use-responsive-value.js";
+import { observeDashboardVisibility } from "../utils/visibility.js";
+export function useDashboardBlock(params) {
+  const phase = computed(() => {
+    const source = params.source();
+    if (!source) return "content";
+    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 style = computed(
+    () => [span.value ?? "grid-column: 1 / -1", rowSpan.value].filter(Boolean).join("; ")
+  );
+  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());
+  });
+  onBeforeUnmount(() => stopObserving?.());
+  function retry() {
+    params.source()?.refresh().catch(() => void 0);
+  }
+  return { phase, refreshing, retry, style };
+}
+function waitsForActivation(source) {
+  return !("stage" in source) || source.stage === "deferred";
+}

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

@@ -0,0 +1,36 @@
+import type { LazyTextValue } from '../../shared/types/utils.js';
+import type { DashboardAxisOptions, DashboardChartFrame, 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;
+/**
+ * Resolves chart inputs into one plain frame: normalized datums (series values by index), x labels,
+ * value domains with their ticks, and formatters. Rows and accessors are read once per data change;
+ * the renderer only receives the frame. Also provides the chart's table (menu actions) and maps
+ * renderer selections back to rows.
+ */
+export declare function useDashboardChart<TRow>(params: {
+    rows: () => readonly TRow[];
+    x: () => (row: TRow, index: number) => string | number | Date;
+    xFormat: () => ((value: string | number | Date) => string) | undefined;
+    /** Header of the category column in the table view. */
+    xLabel: () => LazyTextValue | undefined;
+    series: () => readonly DashboardSeries<TRow>[];
+    defaultType: 'bar' | 'line' | 'area';
+    yAxis: () => DashboardAxisOptions | undefined;
+    y2Axis?: () => DashboardAxisOptions | undefined;
+    references: () => DashboardReferenceLine | readonly DashboardReferenceLine[] | undefined;
+    stacked?: () => boolean;
+    format: () => DashboardValueFormat | undefined;
+    onSelect: () => ((event: DashboardSelectEvent<TRow>) => void) | undefined;
+    /** Bar charts: bars drawn at full strength, the others faded. */
+    highlight?: () => DashboardHighlight<TRow> | undefined;
+    selected?: () => DashboardSelected<TRow> | undefined;
+    /** Bar charts: prints each group's value above its bars. */
+    labels?: () => boolean;
+}): {
+    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;
+};

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

@@ -0,0 +1,118 @@
+import { computed } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import { isDate } from "../../shared/utils/predicate.js";
+import { resolveTextValue } from "../../shared/utils/render.js";
+import { tabulateDashboardFrame } from "../utils/chart-frame.js";
+import {
+  resolveDashboardAxis,
+  resolveDashboardEmphasis,
+  resolveDashboardSeries,
+  toDashboardLegend
+} from "../utils/charts.js";
+import { useDashboardFormat } from "./use-dashboard-format.js";
+export function resolveDashboardExpandedHeight(height) {
+  return Math.max(420, Math.round(height * 1.6));
+}
+export function useDashboardChart(params) {
+  const { t } = useUiToolsLocale();
+  const formats = useDashboardFormat();
+  const series = computed(
+    () => resolveDashboardSeries(
+      params.series(),
+      params.defaultType,
+      (label) => t("dashboard.compare.series", { label })
+    )
+  );
+  const legend = computed(
+    () => toDashboardLegend([
+      ...series.value.filter((entry) => !entry.dashed),
+      ...series.value.filter((entry) => entry.dashed)
+    ])
+  );
+  const frame = computed(() => {
+    const rows = params.rows();
+    const accessor = params.x();
+    const formatX = params.xFormat();
+    const resolved = series.value;
+    const data = rows.map((row, index) => ({
+      index,
+      values: resolved.map((entry) => entry.value(row, index) ?? void 0)
+    }));
+    const xLabels = rows.map((row, index) => {
+      const value = accessor(row, index);
+      if (formatX) return formatX(value);
+      return isDate(value) ? value.toLocaleDateString() : String(value);
+    });
+    const stacked = params.stacked?.() ?? false;
+    const hasBars = resolved.some((entry) => entry.type === "bar");
+    const labels = hasBars && (params.labels?.() ?? false);
+    const headroom = labels ? 1.16 : hasBars ? 1.05 : 1.08;
+    const references = [params.references() ?? []].flat().map((reference) => ({
+      axis: reference.axis ?? "left",
+      label: resolveTextValue(reference.label, ""),
+      position: reference.position ?? "end",
+      value: reference.value
+    }));
+    const axisValues = (axis) => {
+      const indexes = resolved.flatMap((entry, index) => entry.axis === axis ? [index] : []);
+      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 yAxis = params.yAxis();
+    const y2Axis = params.y2Axis?.();
+    const hasRight = resolved.some((entry) => entry.axis === "right");
+    const last = Math.max(0, data.length - 1);
+    const barIndexes = resolved.flatMap((entry, index) => entry.type === "bar" ? [index] : []);
+    const barValues = data.map((datum) => barIndexes.map((index) => datum.values[index] ?? 0));
+    const barTotals = barValues.map(
+      (values) => stacked ? values.reduce((sum, value) => sum + value, 0) : Math.max(0, ...values)
+    );
+    const selected = params.selected?.();
+    const emphasis = hasBars ? resolveDashboardEmphasis(rows, barTotals, params.highlight?.(), selected) : null;
+    const leftFormat = yAxis?.format ?? format;
+    return {
+      data,
+      emphasis,
+      labels: xLabels,
+      left: {
+        ...resolveDashboardAxis(axisValues("left"), yAxis, headroom),
+        format: leftFormat
+      },
+      references,
+      right: hasRight ? {
+        ...resolveDashboardAxis(axisValues("right"), y2Axis, headroom),
+        format: y2Axis?.format ?? format
+      } : null,
+      series: resolved.map(({ axis, color, dashed, key, label, type }, index) => ({
+        axis,
+        color,
+        dashed,
+        index,
+        key,
+        label,
+        type
+      })),
+      selection: selected ? rows.flatMap((row, index) => selected(row, index) ? [index] : []) : [],
+      stacked,
+      valueLabels: labels ? barTotals.map((value, index) => ({
+        index,
+        strong: emphasis?.[index] ?? false,
+        text: leftFormat(value),
+        value
+      })) : [],
+      // A single point still needs a non-empty domain, so it is centered like a bar slot.
+      xDomain: hasBars || last === 0 ? [-0.5, last + 0.5] : [0, last]
+    };
+  });
+  const tabulate = () => tabulateDashboardFrame(
+    frame.value,
+    resolveTextValue(params.xLabel(), t("dashboard.table.category"))
+  );
+  const selectable = computed(() => params.onSelect() !== void 0);
+  function select(index) {
+    const row = params.rows()[index];
+    if (row !== void 0) params.onSelect()?.({ index, row });
+  }
+  return { frame, legend, select, selectable, tabulate };
+}

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

@@ -0,0 +1,12 @@
+import type { DashboardDerived } from '../types/index.js';
+import type { DashboardReadTracker } from '../utils/tracker.js';
+/**
+ * One `derive` entry. A single computed evaluates the value and records the sources it read; the
+ * derived state is the combined state of those sources, so a card bound to a derived value gets the
+ * same skeleton / error / refresh behaviour as a card bound to a query.
+ */
+export declare function useDashboardDerived(params: {
+    id: string;
+    evaluate: () => unknown;
+    tracker: DashboardReadTracker;
+}): DashboardDerived<unknown>;

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

@@ -0,0 +1,47 @@
+import { computed, markRaw } from "vue";
+import {
+  combineDashboardStates,
+  refreshDashboardSources,
+  resolveDashboardUpdatedAt
+} from "../utils/state.js";
+export function useDashboardDerived(params) {
+  const evaluation = computed(() => {
+    const reads = /* @__PURE__ */ new Set();
+    try {
+      const value = params.tracker.run(reads, params.evaluate);
+      return { error: void 0, sources: [...reads], value };
+    } catch (error) {
+      return { error, sources: [...reads], value: void 0 };
+    }
+  });
+  const sourcesState = computed(
+    () => combineDashboardStates(evaluation.value.sources.map((source) => source.state))
+  );
+  const state = computed(() => {
+    if (sourcesState.value !== "ready") return sourcesState.value;
+    return evaluation.value.error === void 0 ? "ready" : "error";
+  });
+  return markRaw({
+    activate() {
+      for (const source of evaluation.value.sources) source.activate();
+    },
+    get data() {
+      return evaluation.value.value;
+    },
+    get error() {
+      return evaluation.value.error ?? evaluation.value.sources.find((source) => source.state === "error")?.error;
+    },
+    id: params.id,
+    kind: "derived",
+    refresh: () => refreshDashboardSources(evaluation.value.sources),
+    get refreshing() {
+      return evaluation.value.sources.some((source) => source.refreshing);
+    },
+    get state() {
+      return state.value;
+    },
+    get updatedAt() {
+      return resolveDashboardUpdatedAt(evaluation.value.sources.map((source) => source.updatedAt));
+    }
+  });
+}

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

@@ -0,0 +1,6 @@
+/** 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>;
+};

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

@@ -0,0 +1,12 @@
+import { computed } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import { resolveDashboardFormats } from "../utils/charts.js";
+export function useDashboardFormat() {
+  const { code } = useUiToolsLocale();
+  const formats = computed(() => resolveDashboardFormats(code.value));
+  return {
+    delta: computed(() => formats.value.delta),
+    number: computed(() => formats.value.number),
+    percent: computed(() => formats.value.percent)
+  };
+}

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

@@ -0,0 +1,8 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardOptionsHandle, DashboardRuntimeParam } from '../types/index.js';
+/** Option handle of one option-backed param: static items, or a remote source. */
+export declare function useDashboardOptions(params: {
+    definition: DashboardRuntimeParam;
+    queryKey: QueryKey;
+    value: () => unknown;
+}): DashboardOptionsHandle;

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

@@ -0,0 +1,63 @@
+import { computed, markRaw, shallowRef } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import { resolveDashboardOptionValues } from "../utils/options.js";
+import { useDashboardRemoteOptions } from "./use-dashboard-remote-options.js";
+export function useDashboardOptions(params) {
+  const { definition } = params;
+  if (definition.remote)
+    return useDashboardRemoteOptions({
+      config: definition.remote,
+      queryKey: params.queryKey,
+      value: params.value
+    });
+  const items = definition.items ?? [];
+  if (definition.kind !== "comparison") return createStaticOptionsHandle(() => items, params.value);
+  const { t } = useUiToolsLocale();
+  const localized = computed(
+    () => items.map((item) => ({ ...item, label: t(`dashboard.compare.${String(item.value)}`) }))
+  );
+  return createStaticOptionsHandle(() => localized.value, params.value);
+}
+function createStaticOptionsHandle(items, value) {
+  const search = shallowRef("");
+  const open = shallowRef(false);
+  const byValue = computed(() => new Map(items().map((item) => [String(item.value), item])));
+  const selected = computed(
+    () => resolveDashboardOptionValues(value()).flatMap((entry) => byValue.value.get(entry) ?? [])
+  );
+  const menu = computed(() => ({
+    items: [...items()],
+    labelKey: "label",
+    valueKey: "value"
+  }));
+  return markRaw({
+    error: void 0,
+    hasMore: false,
+    get items() {
+      return items();
+    },
+    loading: false,
+    loadingMore: false,
+    loadMore() {
+    },
+    get menu() {
+      return menu.value;
+    },
+    get open() {
+      return open.value;
+    },
+    set open(next) {
+      open.value = next;
+    },
+    refresh: () => Promise.resolve(),
+    get search() {
+      return search.value;
+    },
+    set search(next) {
+      search.value = next;
+    },
+    get selected() {
+      return selected.value;
+    }
+  });
+}

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

@@ -0,0 +1,30 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardOptionsHandle, DashboardParamMap } from '../types/index.js';
+/**
+ * What one param scope exposes. Declared rather than inferred: the inferred type would carry Vue's
+ * `Raw<…>` marker, which declaration files cannot name.
+ */
+export interface DashboardParamScope {
+    keys: readonly string[];
+    /** Option handles of option-backed params, by param key. */
+    options: Readonly<Record<string, DashboardOptionsHandle>>;
+    /** URL segments of this scope's params, before the scope prefix. */
+    urlKeys: readonly string[];
+    /** Writable facade: one getter / setter per param. */
+    values: object;
+}
+/**
+ * Owns the params of one scope (dashboard root, a view, or a query's widget params): exactly one
+ * `useQueryStates` instance, a writable values facade, and the option handles of option-backed
+ * params. Scopes without params allocate nothing.
+ */
+export declare function useDashboardParamScope(params: {
+    definitions: DashboardParamMap;
+    prefix: string;
+    queryKey: QueryKey;
+}): DashboardParamScope;
+/**
+ * Exposes several scopes' values through one object, e.g. shared params plus a view's own params
+ * inside the view's query factories. Reads and writes go straight to the owning scope.
+ */
+export declare function mergeDashboardParamValues(scopes: readonly DashboardParamScope[]): object;

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

@@ -0,0 +1,71 @@
+import { markRaw } from "vue";
+import { useQueryStates } from "../../query-state/index.js";
+import { hasProperty } from "../../shared/utils/predicate.js";
+import { useDashboardOptions } from "./use-dashboard-options.js";
+const emptyFacade = markRaw({});
+const noUrlKeys = [];
+export function useDashboardParamScope(params) {
+  const entries = Object.entries(params.definitions).flatMap(
+    ([key, definition]) => isRuntimeParam(definition) ? [[key, definition]] : []
+  );
+  if (entries.length === 0)
+    return { keys: [], options: emptyFacade, urlKeys: noUrlKeys, values: emptyFacade };
+  const schema = {};
+  for (const [key, definition] of entries) {
+    schema[key] = {
+      codec: definition.codec,
+      defaultValue: definition.defaultValue,
+      historyMode: definition.historyMode,
+      omitDefault: definition.omitDefault,
+      urlKey: definition.urlKey
+    };
+  }
+  const state = useQueryStates({ historyMode: "replace", prefix: params.prefix, schema });
+  function read(key) {
+    const current = state.value;
+    return current[key];
+  }
+  function write(key, value) {
+    state.value = { ...state.value, [key]: value ?? params.definitions[key]?.defaultValue };
+  }
+  const values = {};
+  for (const [key] of entries) {
+    Object.defineProperty(values, key, {
+      enumerable: true,
+      get: () => read(key),
+      set: (value) => write(key, value)
+    });
+  }
+  const options = {};
+  for (const [key, definition] of entries) {
+    if (!definition.items && !definition.remote) continue;
+    options[key] = useDashboardOptions({
+      definition,
+      queryKey: [...params.queryKey, key],
+      value: () => read(key)
+    });
+  }
+  return {
+    keys: entries.map(([key]) => key),
+    options: markRaw(options),
+    /** URL segments of this scope's params, before the scope prefix. */
+    urlKeys: entries.map(([key, definition]) => definition.urlKey ?? key),
+    values: markRaw(values)
+  };
+}
+export function mergeDashboardParamValues(scopes) {
+  const merged = {};
+  for (const scope of scopes) {
+    for (const key of scope.keys) {
+      Object.defineProperty(merged, key, {
+        enumerable: true,
+        get: () => Reflect.get(scope.values, key),
+        set: (value) => Reflect.set(scope.values, key, value)
+      });
+    }
+  }
+  return markRaw(merged);
+}
+function isRuntimeParam(definition) {
+  return hasProperty(definition, "codec");
+}

package/dist/runtime/dashboard/composables/use-dashboard-remote-options.d.ts

@@ -0,0 +1,12 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { DashboardOptionsHandle, DashboardRemoteOptionsConfig } from '../types/index.js';
+/**
+ * Remote option handle. Nothing loads until the picker opens or a search term is typed; pages are
+ * cached per search term by TanStack Query, and selected values missing from the loaded pages are
+ * hydrated through `resolveSelected` so URL-restored ids render their labels.
+ */
+export declare function useDashboardRemoteOptions(params: {
+    config: DashboardRemoteOptionsConfig;
+    queryKey: QueryKey;
+    value: () => unknown;
+}): DashboardOptionsHandle;