nuxt-ui-tools 1.0.0 → 1.1.0

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

@@ -0,0 +1,117 @@
+import { useInfiniteQuery, useQuery } from "@tanstack/vue-query";
+import { refDebounced } from "@vueuse/core";
+import { computed, markRaw, shallowRef } from "vue";
+import { DASHBOARD_REMOTE_OPTIONS_DEFAULTS } from "../constants/query.js";
+import {
+  mergeDashboardOptions,
+  resolveDashboardOptionValues,
+  resolveDashboardRemoteNextPage
+} from "../utils/options.js";
+export function useDashboardRemoteOptions(params) {
+  const { config } = params;
+  const queryKey = config.queryKey ?? params.queryKey;
+  const pageSize = config.pagination?.size ?? DASHBOARD_REMOTE_OPTIONS_DEFAULTS.pageSize;
+  const minLength = config.search?.minLength ?? 0;
+  const open = shallowRef(false);
+  const searchInput = shallowRef("");
+  const search = refDebounced(
+    searchInput,
+    config.search?.debounce ?? DASHBOARD_REMOTE_OPTIONS_DEFAULTS.searchDebounce
+  );
+  const pages = useInfiniteQuery(
+    computed(() => ({
+      enabled: (open.value || searchInput.value !== "") && (search.value.length === 0 || search.value.length >= minLength),
+      getNextPageParam: (lastPage, allPages) => resolveDashboardRemoteNextPage(lastPage, allPages.length),
+      initialPageParam: { cursor: null, index: 1 },
+      queryFn: ({ pageParam }) => config.load({ page: { ...pageParam, size: pageSize }, search: search.value }),
+      queryKey: [...queryKey, "options", search.value],
+      staleTime: DASHBOARD_REMOTE_OPTIONS_DEFAULTS.staleTime
+    }))
+  );
+  const loaded = computed(
+    () => pages.data.value?.pages.flatMap((page) => page.options) ?? []
+  );
+  const loadedByValue = computed(
+    () => new Map(loaded.value.map((option) => [option.value, option]))
+  );
+  const selectedValues = computed(() => resolveDashboardOptionValues(params.value()));
+  const missing = computed(
+    () => selectedValues.value.filter((value) => !loadedByValue.value.has(value))
+  );
+  const hydration = useQuery(
+    computed(() => ({
+      enabled: Boolean(config.resolveSelected) && missing.value.length > 0,
+      queryFn: () => config.resolveSelected?.({ values: missing.value }) ?? Promise.resolve([]),
+      queryKey: [...queryKey, "selected", missing.value],
+      staleTime: DASHBOARD_REMOTE_OPTIONS_DEFAULTS.selectedStaleTime
+    }))
+  );
+  const selected = computed(() => {
+    const hydrated = new Map((hydration.data.value ?? []).map((option) => [option.value, option]));
+    return selectedValues.value.map(
+      (value) => loadedByValue.value.get(value) ?? hydrated.get(value) ?? { label: value, value }
+    );
+  });
+  const items = computed(
+    () => mergeDashboardOptions(loaded.value, selected.value)
+  );
+  const loading = computed(
+    () => pages.isFetching.value && !pages.isFetchingNextPage.value || hydration.isFetching.value
+  );
+  function setSearch(next) {
+    searchInput.value = next;
+  }
+  function setOpen(next) {
+    open.value = next;
+  }
+  return markRaw({
+    get error() {
+      return pages.error.value ?? hydration.error.value;
+    },
+    get hasMore() {
+      return pages.hasNextPage.value;
+    },
+    get items() {
+      return items.value;
+    },
+    get loading() {
+      return loading.value;
+    },
+    get loadingMore() {
+      return pages.isFetchingNextPage.value;
+    },
+    loadMore() {
+      if (pages.hasNextPage.value && !pages.isFetchingNextPage.value) void pages.fetchNextPage();
+    },
+    get menu() {
+      return {
+        ignoreFilter: true,
+        items: items.value,
+        labelKey: "label",
+        loading: loading.value,
+        "onUpdate:open": setOpen,
+        "onUpdate:searchTerm": setSearch,
+        searchTerm: searchInput.value,
+        valueKey: "value"
+      };
+    },
+    get open() {
+      return open.value;
+    },
+    set open(next) {
+      setOpen(next);
+    },
+    async refresh() {
+      await pages.refetch();
+    },
+    get search() {
+      return searchInput.value;
+    },
+    set search(next) {
+      setSearch(next);
+    },
+    get selected() {
+      return selected.value;
+    }
+  });
+}

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

@@ -0,0 +1,35 @@
+import type { QueryKey } from '@tanstack/vue-query';
+import type { ComputedRef } from 'vue';
+import type { DashboardResourceState, DashboardStage } from '../types/index.js';
+import type { DashboardRuntimeQueryInput } from '../types/runtime.js';
+/**
+ * Owns one declared query: exactly one `useQuery`, its widget params, and the deferred activation
+ * latch. Gating rewrites `enabled` on a stable definition, so hook order never changes, and a gated
+ * resource never evaluates its factory (it does not subscribe to params it cannot use yet).
+ */
+export declare function useDashboardResource(params: {
+    id: string;
+    key: string;
+    stage: DashboardStage;
+    input: DashboardRuntimeQueryInput;
+    scope: {
+        active: ComputedRef<boolean>;
+        settled: ComputedRef<boolean>;
+        prefix: string;
+        queryKey: QueryKey;
+        /** Dashboard auto-refresh interval in milliseconds, `0` when off. */
+        refetchInterval: ComputedRef<number>;
+    };
+}): {
+    activate: () => void;
+    active: ComputedRef<boolean>;
+    data: ComputedRef<unknown>;
+    error: import("vue").Ref<Error, Error> | import("vue").Ref<null, null>;
+    id: string;
+    refresh: () => Promise<void>;
+    refreshing: ComputedRef<boolean>;
+    stage: DashboardStage;
+    state: ComputedRef<DashboardResourceState>;
+    updatedAt: ComputedRef<number | undefined>;
+    widget: import("./use-dashboard-param-scope.js").DashboardParamScope;
+};

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

@@ -0,0 +1,80 @@
+import { keepPreviousData, useQuery } from "@tanstack/vue-query";
+import { computed, shallowRef } from "vue";
+import { hasProperty, isNullish } from "../../shared/utils/predicate.js";
+import { DASHBOARD_QUERY_DEFAULTS } from "../constants/query.js";
+import { dashboardParamBuilder } from "../utils/builders/dashboard-params.js";
+import { joinDashboardUrlKey } from "../utils/state.js";
+import { useDashboardParamScope } from "./use-dashboard-param-scope.js";
+export function useDashboardResource(params) {
+  const { input, stage, scope } = params;
+  const activated = shallowRef(stage !== "deferred");
+  const widget = useDashboardParamScope({
+    definitions: input.params?.(dashboardParamBuilder) ?? {},
+    prefix: joinDashboardUrlKey(scope.prefix, params.key),
+    queryKey: [...scope.queryKey, params.id, "params"]
+  });
+  const active = computed(() => scope.active.value && activated.value);
+  const gate = computed(() => {
+    if (!active.value) return false;
+    if (stage === "background" && !scope.settled.value) return false;
+    return input.enabled?.() ?? true;
+  });
+  const required = computed(() => gate.value && input.requires ? input.requires() : true);
+  const enabled = computed(() => gate.value && !isNullish(required.value));
+  const query = useQuery(
+    computed(() => enabled.value ? resolveDefinition() : idleDefinition(params.id))
+  );
+  function resolveDefinition() {
+    const definition = input.query({ params: widget.values, required: required.value });
+    const interval = scope.refetchInterval.value;
+    return {
+      placeholderData: input.keepPreviousData === false ? void 0 : keepPreviousData,
+      // Polling pauses while the page is hidden (TanStack's `refetchIntervalInBackground: false`).
+      refetchInterval: interval > 0 ? interval : false,
+      refetchOnWindowFocus: DASHBOARD_QUERY_DEFAULTS.refetchOnWindowFocus,
+      staleTime: input.staleTime ?? DASHBOARD_QUERY_DEFAULTS.staleTime[stage],
+      ...definition,
+      enabled: !(hasProperty(definition, "enabled") && definition.enabled === false)
+    };
+  }
+  const state = computed(() => {
+    if (!enabled.value) return "idle";
+    if (query.isError.value) return "error";
+    return query.data.value === void 0 ? "loading" : "ready";
+  });
+  const data = computed(
+    () => enabled.value && query.data.value !== void 0 ? query.data.value : input.defaultValue
+  );
+  const refreshing = computed(() => state.value === "ready" && query.isFetching.value);
+  const updatedAt = computed(
+    () => state.value === "ready" && query.dataUpdatedAt.value > 0 ? query.dataUpdatedAt.value : void 0
+  );
+  function activate() {
+    activated.value = true;
+  }
+  async function refresh() {
+    if (!activated.value) return activate();
+    if (!enabled.value) return;
+    await query.refetch({ throwOnError: true });
+  }
+  return {
+    activate,
+    active,
+    data,
+    error: query.error,
+    id: params.id,
+    refresh,
+    refreshing,
+    stage,
+    state,
+    updatedAt,
+    widget
+  };
+}
+function idleDefinition(id) {
+  return {
+    enabled: false,
+    queryFn: () => Promise.resolve(null),
+    queryKey: ["nuxt-ui-tools", "dashboard", "idle", id]
+  };
+}

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

@@ -0,0 +1,46 @@
+import type { ComputedRef } from 'vue';
+import type { DashboardResourceState, DashboardSourceLike, DashboardStage } from '../types/index.js';
+import type { DashboardRuntimeScopeInput } from '../types/runtime.js';
+import type { DashboardReadTracker } from '../utils/tracker.js';
+import { useDashboardParamScope } from './use-dashboard-param-scope.js';
+/**
+ * One scope of a dashboard: the root, or one view. It owns the scope params, declares its queries
+ * in a single synchronous pass, instantiates them once their keys are known, and derives the scope
+ * state from its essential queries.
+ */
+export declare function useDashboardScope(params: {
+    schemaKey: string;
+    /** `''` for the root, the view key otherwise. */
+    scopeKey: string;
+    input: DashboardRuntimeScopeInput;
+    prefix: string;
+    active: ComputedRef<boolean>;
+    /** Dashboard auto-refresh interval in milliseconds, `0` when off. */
+    refetchInterval: ComputedRef<number>;
+    /** Root params, visible inside a view's builders. */
+    shared?: ReturnType<typeof useDashboardParamScope>;
+    /** Root queries and derived values, readable from a view's `derive`. */
+    rootSources?: ReadonlyMap<string, DashboardSourceLike>;
+    tracker: DashboardReadTracker;
+}): {
+    label: import("../../shared/index.js").LazyTextValue | undefined;
+    members: Map<string, DashboardSourceLike<unknown>>;
+    paramScope: import("./use-dashboard-param-scope.js").DashboardParamScope;
+    refresh: () => Promise<void>;
+    refreshing: import("vue").ShallowRef<boolean, boolean>;
+    resources: {
+        activate: () => void;
+        active: ComputedRef<boolean>;
+        data: ComputedRef<unknown>;
+        error: import("vue").Ref<Error, Error> | import("vue").Ref<null, null>;
+        id: string;
+        refresh: () => Promise<void>;
+        refreshing: ComputedRef<boolean>;
+        stage: DashboardStage;
+        state: ComputedRef<DashboardResourceState>;
+        updatedAt: ComputedRef<number | undefined>;
+        widget: import("./use-dashboard-param-scope.js").DashboardParamScope;
+    }[];
+    state: ComputedRef<DashboardResourceState>;
+    updatedAt: ComputedRef<number | undefined>;
+};

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

@@ -0,0 +1,127 @@
+import { computed, shallowRef } from "vue";
+import { dashboardParamBuilder } from "../utils/builders/dashboard-params.js";
+import { createDashboardResourceFacade } from "../utils/resource.js";
+import { assertDashboardMemberKey } from "../utils/schema.js";
+import {
+  combineDashboardStates,
+  refreshDashboardSources,
+  resolveDashboardUpdatedAt
+} from "../utils/state.js";
+import { createDashboardTrackedData } from "../utils/tracker.js";
+import { useDashboardDerived } from "./use-dashboard-derived.js";
+import { mergeDashboardParamValues, useDashboardParamScope } from "./use-dashboard-param-scope.js";
+import { useDashboardResource } from "./use-dashboard-resource.js";
+export function useDashboardScope(params) {
+  const { input, scopeKey } = params;
+  const queryKey = [params.schemaKey, scopeKey || "$root"];
+  const paramScope = useDashboardParamScope({
+    definitions: input.params?.(dashboardParamBuilder) ?? {},
+    prefix: params.prefix,
+    queryKey
+  });
+  const visibleParams = mergeDashboardParamValues(
+    params.shared ? [params.shared, paramScope] : [paramScope]
+  );
+  const declared = shallowRef(false);
+  const declarations = /* @__PURE__ */ new Map();
+  const resources = [];
+  const settled = computed(
+    () => declared.value && resources.every(
+      (resource) => resource.stage !== "essential" || resource.state.value !== "loading"
+    )
+  );
+  function createStage(stage) {
+    return {
+      query(definition) {
+        const query = typeof definition === "function" ? { query: definition } : definition;
+        const slot = shallowRef(null);
+        const facade = createDashboardResourceFacade(stage, slot, query.defaultValue);
+        declarations.set(facade, { input: query, slot, stage });
+        return facade;
+      }
+    };
+  }
+  const exposed = input.queries?.({
+    background: createStage("background"),
+    deferred: createStage("deferred"),
+    essential: createStage("essential"),
+    params: visibleParams
+  });
+  const scopeLabel = scopeKey ? `view "${scopeKey}"` : "the dashboard root";
+  const taken = new Set(params.rootSources?.keys());
+  const members = /* @__PURE__ */ new Map();
+  function instantiate(key, declaration) {
+    const resource = useDashboardResource({
+      id: scopeKey ? `${scopeKey}.${key}` : key,
+      input: declaration.input,
+      key,
+      scope: {
+        active: params.active,
+        prefix: params.prefix,
+        queryKey,
+        refetchInterval: params.refetchInterval,
+        settled
+      },
+      stage: declaration.stage
+    });
+    declaration.slot.value = resource;
+    resources.push(resource);
+  }
+  for (const [key, facade] of Object.entries(exposed ?? {})) {
+    const declaration = declarations.get(facade);
+    if (!declaration)
+      throw new Error(`[dashboard] "${key}" in ${scopeLabel} is not a declared query.`);
+    assertDashboardMemberKey(key, taken, scopeLabel);
+    taken.add(key);
+    declarations.delete(facade);
+    instantiate(key, declaration);
+    members.set(key, facade);
+  }
+  let anonymous = 0;
+  for (const declaration of declarations.values()) instantiate(`$${anonymous++}`, declaration);
+  declared.value = true;
+  const data = createDashboardTrackedData(
+    new Map([...params.rootSources ?? [], ...members]),
+    params.tracker
+  );
+  const derived = input.derive?.({ data, params: visibleParams }) ?? {};
+  for (const [key, evaluate] of Object.entries(derived)) {
+    assertDashboardMemberKey(key, taken, scopeLabel);
+    taken.add(key);
+    const id = scopeKey ? `${scopeKey}.${key}` : key;
+    members.set(key, useDashboardDerived({ evaluate, id, tracker: params.tracker }));
+  }
+  const essentials = resources.filter((resource) => resource.stage === "essential");
+  const state = computed(() => {
+    if (!params.active.value) return "idle";
+    const combined = combineDashboardStates(essentials.map((resource) => resource.state.value));
+    return combined === "idle" ? "ready" : combined;
+  });
+  const updatedAt = computed(
+    () => resolveDashboardUpdatedAt(
+      resources.flatMap((resource) => resource.active.value ? [resource.updatedAt.value] : [])
+    )
+  );
+  const refreshing = shallowRef(false);
+  let pending = null;
+  function refresh() {
+    pending ??= refreshDashboardSources(
+      resources.filter((resource) => resource.active.value)
+    ).finally(() => {
+      pending = null;
+      refreshing.value = false;
+    });
+    refreshing.value = true;
+    return pending;
+  }
+  return {
+    label: input.label,
+    members,
+    paramScope,
+    refresh,
+    refreshing,
+    resources,
+    state,
+    updatedAt
+  };
+}

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

@@ -0,0 +1,13 @@
+import type { DashboardTimeValue } from '../types/index.js';
+/**
+ * Locale-aware time formatting that stays current: relative times re-render every 30 seconds
+ * through one shared clock.
+ */
+export declare function useDashboardTime(): {
+    /** Full date and time, for `title` attributes. */
+    absolute: (value: DashboardTimeValue) => string;
+    /** Day heading: `Today`, `Yesterday`, then the date. */
+    day: (value: DashboardTimeValue) => string;
+    /** `3 min ago`, `yesterday`, then the date. */
+    relative: (value: DashboardTimeValue) => string;
+};

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

@@ -0,0 +1,40 @@
+import { onBeforeUnmount, onMounted, readonly, shallowRef } from "vue";
+import { useUiToolsLocale } from "../../i18n/use-locale.js";
+import {
+  formatDashboardDateTime,
+  formatDashboardDay,
+  formatDashboardRelativeTime,
+  toDashboardTime
+} from "../utils/time.js";
+const TICK = 3e4;
+const now = shallowRef(Date.now());
+let subscribers = 0;
+let timer;
+function useDashboardNow() {
+  now.value = Date.now();
+  onMounted(() => {
+    subscribers += 1;
+    if (subscribers > 1) return;
+    now.value = Date.now();
+    timer = setInterval(() => {
+      now.value = Date.now();
+    }, TICK);
+  });
+  onBeforeUnmount(() => {
+    subscribers -= 1;
+    if (subscribers === 0) clearInterval(timer);
+  });
+  return readonly(now);
+}
+export function useDashboardTime() {
+  const { code } = useUiToolsLocale();
+  const clock = useDashboardNow();
+  return {
+    /** Full date and time, for `title` attributes. */
+    absolute: (value) => formatDashboardDateTime(toDashboardTime(value), code.value),
+    /** Day heading: `Today`, `Yesterday`, then the date. */
+    day: (value) => formatDashboardDay(toDashboardTime(value), clock.value, code.value),
+    /** `3 min ago`, `yesterday`, then the date. */
+    relative: (value) => formatDashboardRelativeTime(toDashboardTime(value), clock.value, code.value)
+  };
+}

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

@@ -0,0 +1,22 @@
+import type { ComputedRef } from 'vue';
+import type { DashboardMenu, DashboardUiConfig } from '../types/index.js';
+/** App-wide dashboard class overrides from `appConfig.nuxtUiTools.dashboard`. */
+export declare function useDashboardUi(): ComputedRef<DashboardUiConfig>;
+interface DashboardGridContext {
+    panels: ComputedRef<boolean>;
+    /** Card menu of the blocks that do not set their own. */
+    menu: ComputedRef<DashboardMenu | undefined>;
+    /** `freshness` of the blocks that do not set their own. */
+    freshness: ComputedRef<boolean | undefined>;
+}
+/**
+ * Lets blocks know whether they sit in a `panels` grid (joined cells, no card borders), and hands
+ * them the grid's block defaults. A nested grid inherits the defaults it does not set.
+ */
+export declare function provideDashboardGrid(params: {
+    panels: () => boolean;
+    menu: () => DashboardMenu | undefined;
+    freshness: () => boolean | undefined;
+}): void;
+export declare function useDashboardGridContext(): DashboardGridContext | null;
+export {};

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

@@ -0,0 +1,19 @@
+import { useAppConfig } from "nuxt/app";
+import { computed, inject, provide } from "vue";
+import { resolveAppDashboardUi } from "../utils/ui.js";
+export function useDashboardUi() {
+  const appConfig = useAppConfig();
+  return computed(() => resolveAppDashboardUi(appConfig));
+}
+const dashboardGridKey = Symbol("nuxt-ui-tools.dashboard-grid");
+export function provideDashboardGrid(params) {
+  const parent = useDashboardGridContext();
+  provide(dashboardGridKey, {
+    freshness: computed(() => params.freshness() ?? parent?.freshness.value),
+    menu: computed(() => params.menu() ?? parent?.menu.value),
+    panels: computed(params.panels)
+  });
+}
+export function useDashboardGridContext() {
+  return inject(dashboardGridKey, null);
+}

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

@@ -0,0 +1,46 @@
+import type { ComputedRef } from 'vue';
+import type { DashboardSourceLike } from '../types/index.js';
+import type { DashboardRuntimeSchema } from '../types/runtime.js';
+import type { DashboardReadTracker } from '../utils/tracker.js';
+import { useDashboardScope } from './use-dashboard-scope.js';
+/**
+ * Owns the view controller: the URL-synced current view (`view`, pushed to history so Back returns
+ * to the previous tab) and one scope per view. A view's queries stay idle until the view is opened
+ * once, then stay warm across switches.
+ */
+export declare function useDashboardViews(params: {
+    schema: DashboardRuntimeSchema;
+    root: ReturnType<typeof useDashboardScope>;
+    refetchInterval: ComputedRef<number>;
+    tracker: DashboardReadTracker;
+}): {
+    current: import("vue").WritableComputedRef<string, string>;
+    keys: string[];
+    views: {
+        key: string;
+        label: () => string;
+        opened: import("vue").ShallowRef<boolean, boolean>;
+        scope: {
+            label: import("../../shared/index.js").LazyTextValue | undefined;
+            members: Map<string, DashboardSourceLike<unknown>>;
+            paramScope: import("./use-dashboard-param-scope.js").DashboardParamScope;
+            refresh: () => Promise<void>;
+            refreshing: import("vue").ShallowRef<boolean, boolean>;
+            resources: {
+                activate: () => void;
+                active: ComputedRef<boolean>;
+                data: ComputedRef<unknown>;
+                error: import("vue").Ref<Error, Error> | import("vue").Ref<null, null>;
+                id: string;
+                refresh: () => Promise<void>;
+                refreshing: ComputedRef<boolean>;
+                stage: import("..").DashboardStage;
+                state: ComputedRef<import("..").DashboardResourceState>;
+                updatedAt: ComputedRef<number | undefined>;
+                widget: import("./use-dashboard-param-scope.js").DashboardParamScope;
+            }[];
+            state: ComputedRef<import("..").DashboardResourceState>;
+            updatedAt: ComputedRef<number | undefined>;
+        };
+    }[];
+};

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

@@ -0,0 +1,49 @@
+import { computed, shallowRef, watch } from "vue";
+import { createEnumCodec, useQueryState } from "../../query-state/index.js";
+import { resolveTextValue } from "../../shared/utils/render.js";
+import {
+  DASHBOARD_VIEW_URL_KEY,
+  resolveDashboardScopePrefix,
+  resolveDashboardViewKey
+} from "../utils/state.js";
+import { useDashboardScope } from "./use-dashboard-scope.js";
+export function useDashboardViews(params) {
+  const { schema } = params;
+  if (params.root.paramScope.urlKeys.includes(DASHBOARD_VIEW_URL_KEY)) {
+    throw new Error(
+      `[dashboard] Root param URL key "${DASHBOARD_VIEW_URL_KEY}" is reserved for the current view of "${schema.key}". Rename the param or set its \`urlKey\`.`
+    );
+  }
+  const keys = schema.views.map(([key]) => key);
+  const current = useQueryState({
+    codec: createEnumCodec(keys),
+    defaultValue: schema.defaultView ?? keys[0] ?? "",
+    historyMode: "push",
+    key: resolveDashboardViewKey(schema.urlPrefix)
+  });
+  const rootSources = new Map(params.root.members);
+  const views = schema.views.map(([key, input]) => {
+    const opened = shallowRef(false);
+    watch(
+      () => current.value === key,
+      (visible) => {
+        if (visible) opened.value = true;
+      },
+      { flush: "sync", immediate: true }
+    );
+    const scope = useDashboardScope({
+      active: computed(() => opened.value),
+      input,
+      prefix: resolveDashboardScopePrefix(schema.urlPrefix, key),
+      refetchInterval: params.refetchInterval,
+      rootSources,
+      schemaKey: schema.key,
+      scopeKey: key,
+      shared: params.root.paramScope,
+      tracker: params.tracker
+    });
+    const label = () => resolveTextValue(input.label, key);
+    return { key, label, opened, scope };
+  });
+  return { current, keys, views };
+}

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

@@ -0,0 +1,24 @@
+import type { DashboardApi, DashboardSchemaLike } from '../types/index.js';
+/**
+ * Instantiates a dashboard schema. Call it once in `<script setup>`; every query and URL binding is
+ * created synchronously here, so hook order is stable.
+ *
+ * The returned object has no refs: `dashboard.params.year`, `dashboard.revenue.data`,
+ * `dashboard.state` are plain reads, params are `v-model` targets, and every query / derived value
+ * can be bound to a block with `:source="dashboard.revenue"`.
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * const dashboard = useDashboard(salesDashboard)
+ * </script>
+ *
+ * <template>
+ *   <USelect v-model="dashboard.params.period" v-bind="dashboard.options.period.menu" />
+ *   <UiDashboardGrid>
+ *     <UiDashboardStat :source="dashboard.summary" label="Revenue" :value="(d) => d.revenue" />
+ *   </UiDashboardGrid>
+ * </template>
+ * ```
+ */
+export declare function useDashboard<const TSchema extends DashboardSchemaLike>(schema: TSchema): DashboardApi<TSchema>;

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

@@ -0,0 +1,42 @@
+import { computed } from "vue";
+import { numberCodec, useQueryState } from "../../query-state/index.js";
+import { resolveDashboardRuntimeSchema } from "../utils/schema.js";
+import {
+  DASHBOARD_REFRESH_URL_KEY,
+  resolveDashboardRefreshKey,
+  resolveDashboardScopePrefix
+} from "../utils/state.js";
+import { createDashboardReadTracker } from "../utils/tracker.js";
+import { useDashboardApi } from "./use-dashboard-api.js";
+import { useDashboardScope } from "./use-dashboard-scope.js";
+import { useDashboardViews } from "./use-dashboard-views.js";
+export function useDashboard(schema) {
+  const runtime = resolveDashboardRuntimeSchema(schema);
+  const tracker = createDashboardReadTracker();
+  const autoRefresh = useQueryState({
+    codec: numberCodec,
+    defaultValue: Math.max(0, runtime.autoRefresh ?? 0),
+    historyMode: "replace",
+    key: resolveDashboardRefreshKey(runtime.urlPrefix)
+  });
+  const refetchInterval = computed(
+    () => Number.isFinite(autoRefresh.value) && autoRefresh.value > 0 ? autoRefresh.value * 1e3 : 0
+  );
+  const root = useDashboardScope({
+    active: computed(() => true),
+    input: runtime,
+    prefix: resolveDashboardScopePrefix(runtime.urlPrefix),
+    refetchInterval,
+    schemaKey: runtime.key,
+    scopeKey: "",
+    tracker
+  });
+  if (root.paramScope.urlKeys.includes(DASHBOARD_REFRESH_URL_KEY)) {
+    throw new Error(
+      `[dashboard] Root param URL key "${DASHBOARD_REFRESH_URL_KEY}" is reserved for the auto-refresh interval of "${runtime.key}". Rename the param or set its \`urlKey\`.`
+    );
+  }
+  const views = runtime.views.length > 0 ? useDashboardViews({ refetchInterval, root, schema: runtime, tracker }) : null;
+  const api = useDashboardApi({ autoRefresh, root, schema, views });
+  return api;
+}