nuxt-ui-tools 1.2.0 → 1.3.0

package/dist/runtime/dashboard/components/dashboard-tabs.vue.d.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.
          */

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

@@ -1,8 +1,13 @@
 import type { LazyTextValue } from '#ui-tools/shared/types/utils';
-import type { DashboardTotalUi } from '../types/index.js';
+import type { DashboardTotalUi, DashboardValueFormat } from '../types/index.js';
 type __VLS_Props = {
     label: LazyTextValue;
-    value: LazyTextValue;
+    /**
+     * Numbers go through `format` (locale number format by default); text shows as is; `null` /
+     * `undefined` show "—".
+     */
+    value: LazyTextValue | null | undefined;
+    format?: DashboardValueFormat;
     ui?: DashboardTotalUi;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -1,16 +1,24 @@
 <script setup>
 import { computed } from "vue";
+import { isNumber } from "#ui-tools/shared/utils/predicate";
 import { resolveTextValue } from "#ui-tools/shared/utils/render";
+import { DASHBOARD_MISSING_VALUE, useDashboardFormat } from "../composables/use-dashboard-format";
 import { useDashboardUi } from "../composables/use-dashboard-ui";
 import { resolveDashboardClasses } from "../utils/ui";
 const props = defineProps({
   label: { type: [String, Number, Function], required: true },
-  value: { type: [String, Number, Function], required: true },
+  value: { type: [String, Number, Function, null], required: true, skipCheck: true },
+  format: { type: [String, Function], required: false, skipCheck: true },
   ui: { type: Object, required: false }
 });
 const appUi = useDashboardUi();
+const formats = useDashboardFormat();
 const label = computed(() => resolveTextValue(props.label));
-const value = computed(() => resolveTextValue(props.value));
+const value = computed(() => {
+  const resolved = typeof props.value === "function" ? props.value() : props.value;
+  if (resolved === null || resolved === void 0) return DASHBOARD_MISSING_VALUE;
+  return isNumber(resolved) ? formats.resolve(props.format)(resolved) : resolveTextValue(resolved);
+});
 const classes = computed(
   () => resolveDashboardClasses(
     {

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

@@ -1,8 +1,13 @@
 import type { LazyTextValue } from '#ui-tools/shared/types/utils';
-import type { DashboardTotalUi } from '../types/index.js';
+import type { DashboardTotalUi, DashboardValueFormat } from '../types/index.js';
 type __VLS_Props = {
     label: LazyTextValue;
-    value: LazyTextValue;
+    /**
+     * Numbers go through `format` (locale number format by default); text shows as is; `null` /
+     * `undefined` show "—".
+     */
+    value: LazyTextValue | null | undefined;
+    format?: DashboardValueFormat;
     ui?: DashboardTotalUi;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;

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

@@ -0,0 +1,33 @@
+import type { DashboardViewController, DashboardViewTabsUi } from '../types/index.js';
+declare const __VLS_export: <TKey extends string>(__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: {
+            readonly view: DashboardViewController<TKey>;
+        };
+        ui?: DashboardViewTabsUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        /** Content of one tab. */
+        tab?: (props: {
+            item: {
+                value: TKey;
+                label: string;
+            };
+            active: boolean;
+        }) => 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-view-tabs.vue

@@ -0,0 +1,66 @@
+<script setup>
+import { computed, nextTick, onMounted, useTemplateRef, watch } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+import { useDashboardUi } from "../composables/use-dashboard-ui";
+import { resolveDashboardClasses } from "../utils/ui";
+const { dashboard, ui } = defineProps({
+  dashboard: { type: Object, required: true },
+  ui: { type: Object, required: false }
+});
+defineSlots();
+const EDGE = 16;
+const { t } = useUiToolsLocale();
+const appUi = useDashboardUi();
+const strip = useTemplateRef("strip");
+const classes = computed(
+  () => resolveDashboardClasses(
+    {
+      root: "flex min-w-0 gap-0.5 overflow-x-auto border-b border-default [scrollbar-width:none]",
+      tab: "relative inline-flex h-10 flex-none items-center px-3 text-sm font-medium whitespace-nowrap text-muted transition-colors outline-none hover:text-default focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-inset data-[active]:text-highlighted data-[active]:after:absolute data-[active]:after:inset-x-2 data-[active]:after:-bottom-px data-[active]:after:h-0.5 data-[active]:after:rounded-full data-[active]:after:bg-primary"
+    },
+    appUi.value.viewTabs,
+    ui
+  )
+);
+function reveal(behavior) {
+  const element = strip.value;
+  const tab = element?.querySelector('[aria-current="page"]');
+  if (!element || !tab) return;
+  const bounds = element.getBoundingClientRect();
+  const box = tab.getBoundingClientRect();
+  const overflow = box.left < bounds.left + EDGE ? box.left - bounds.left - EDGE : Math.max(0, box.right - bounds.right + EDGE);
+  if (overflow) element.scrollBy({ behavior, left: overflow });
+}
+onMounted(() => reveal("instant"));
+watch(
+  () => dashboard.view.current,
+  async () => {
+    await nextTick();
+    reveal("smooth");
+  }
+);
+</script>
+
+<template>
+  <nav
+    v-if="dashboard.view.items.length > 1"
+    ref="strip"
+    :class="classes.root"
+    :aria-label="t('dashboard.filters.views')"
+    data-dashboard-view-tabs
+  >
+    <button
+      v-for="item in dashboard.view.items"
+      :key="item.value"
+      type="button"
+      :class="classes.tab"
+      :data-active="dashboard.view.current === item.value || void 0"
+      :aria-current="dashboard.view.current === item.value ? 'page' : void 0"
+      @click="dashboard.view.current = item.value"
+    >
+      <slot name="tab" :item :active="dashboard.view.current === item.value">
+        {{ item.label }}
+      </slot>
+    </button>
+  </nav>
+</template>

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

@@ -0,0 +1,33 @@
+import type { DashboardViewController, DashboardViewTabsUi } from '../types/index.js';
+declare const __VLS_export: <TKey extends string>(__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: {
+            readonly view: DashboardViewController<TKey>;
+        };
+        ui?: DashboardViewTabsUi;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        /** Content of one tab. */
+        tab?: (props: {
+            item: {
+                value: TKey;
+                label: string;
+            };
+            active: boolean;
+        }) => 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-widget.vue

@@ -15,12 +15,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 },
   ui: { type: Object, required: false },
   source: { type: Object, required: true },

package/dist/runtime/dashboard/components/filter/dashboard-filter-menu.d.vue.ts

@@ -0,0 +1,44 @@
+import type { DashboardFilterControl, DashboardFilterUi, DashboardOption, DashboardOptionValue } from '../../types/index.js';
+declare const __VLS_export: <TValue, TItem extends DashboardOptionValue>(__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<{
+        filter: DashboardFilterControl<TValue, TItem>;
+        classes: Required<DashboardFilterUi>;
+        /** Heading above the list. */
+        title?: string;
+        /** What the menu lists: the options, the presets, or both (presets under the options). */
+        list?: "all" | "options" | "presets";
+    } & {
+        onPicked?: (() => any) | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        item?: (props: {
+            item: DashboardOption<TItem>;
+            selected: boolean;
+            disabled: boolean;
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        header?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        footer?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        empty?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+    };
+    emit: (evt: "picked") => void;
+}>) => 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/filter/dashboard-filter-menu.vue

@@ -0,0 +1,220 @@
+<script setup>
+import UIcon from "@nuxt/ui/components/Icon.vue";
+import { useEventListener } from "@vueuse/core";
+import { computed, nextTick, useTemplateRef, watch } from "vue";
+import { useUiToolsLocale } from "#ui-tools/i18n";
+const PREFETCH_VIEWPORTS = 3;
+const {
+  filter,
+  classes,
+  title,
+  list = "all"
+} = defineProps({
+  filter: { type: Object, required: true },
+  classes: { type: Object, required: true },
+  title: { type: String, required: false },
+  list: { type: String, required: false }
+});
+const emit = defineEmits(["picked"]);
+defineSlots();
+const { t } = useUiToolsLocale();
+const listbox = useTemplateRef("listbox");
+const showOptions = computed(() => list !== "presets");
+const showPresets = computed(() => list !== "options" && filter.presets.length > 0);
+const searching = computed(() => filter.search.trim() !== "");
+const clearRow = computed(
+  () => !filter.multiple && filter.defaultValue === void 0 && !searching.value
+);
+const full = computed(
+  () => filter.multiple && filter.max !== void 0 && filter.selected.length >= filter.max
+);
+const grid = computed(
+  () => filter.columns && filter.columns > 1 ? { gridTemplateColumns: `repeat(${filter.columns}, minmax(0, 1fr))` } : void 0
+);
+function pick(item) {
+  filter.toggle(item.value);
+  if (!filter.multiple) emit("picked");
+}
+function clear() {
+  filter.reset();
+  if (!filter.multiple) emit("picked");
+}
+function apply(preset) {
+  preset.apply();
+  emit("picked");
+}
+function loadAhead() {
+  const element = listbox.value;
+  if (!element || element.clientHeight === 0) return;
+  if (!filter.hasMore || filter.loadingMore || filter.loading || filter.error) return;
+  const remaining = element.scrollHeight - element.scrollTop - element.clientHeight;
+  if (remaining <= element.clientHeight * PREFETCH_VIEWPORTS) filter.loadMore();
+}
+useEventListener(listbox, "scroll", loadAhead, { passive: true });
+watch(
+  () => [filter.items.length, filter.hasMore, filter.loadingMore],
+  async () => {
+    await nextTick();
+    loadAhead();
+  },
+  { immediate: true }
+);
+function onKeydown(event) {
+  const rows = [
+    ...listbox.value?.querySelectorAll("[data-filter-row]:not(:disabled)") ?? []
+  ];
+  const current = rows.findIndex((row) => row === document.activeElement);
+  const target = (/* @__PURE__ */ new Map([
+    ["ArrowDown", current + 1],
+    ["ArrowUp", current - 1],
+    ["End", rows.length - 1],
+    ["Home", 0]
+  ])).get(event.key);
+  if (target === void 0 || rows.length === 0) return;
+  event.preventDefault();
+  rows[Math.max(0, Math.min(rows.length - 1, target))]?.focus();
+}
+function focusFirstRow(event) {
+  if (event.key !== "ArrowDown") return;
+  event.preventDefault();
+  listbox.value?.querySelector("[data-filter-row]:not(:disabled)")?.focus();
+}
+</script>
+
+<template>
+  <div v-if="title" :class="classes.title">{{ title }}</div>
+  <label v-if="showOptions && filter.searchable" :class="classes.search" data-filter-search>
+    <UIcon name="i-lucide-search" class="size-3.5 flex-none text-dimmed" />
+    <input
+      v-model="filter.search"
+      type="search"
+      :placeholder="t('dashboard.filters.search')"
+      :aria-label="t('dashboard.filters.search')"
+      class="min-w-0 flex-1 border-0 bg-transparent text-[13px] outline-none placeholder:text-dimmed"
+      autocomplete="off"
+      @keydown="focusFirstRow"
+    />
+  </label>
+  <slot name="header" :filter />
+  <div
+    v-if="showOptions"
+    ref="listbox"
+    role="listbox"
+    :aria-label="filter.label"
+    :aria-multiselectable="filter.multiple || void 0"
+    :class="[classes.list, grid && 'grid']"
+    :style="grid"
+    data-filter-list
+    @keydown="onKeydown"
+  >
+    <button
+      v-if="clearRow"
+      type="button"
+      role="option"
+      :aria-selected="filter.selected.length === 0"
+      :class="classes.item"
+      :data-selected="filter.selected.length === 0 || void 0"
+      data-filter-row
+      data-filter-clear-row
+      @click="clear"
+    >
+      <span class="truncate">{{ filter.placeholder }}</span>
+      <UIcon v-if="filter.selected.length === 0" name="i-lucide-check" :class="classes.tick" />
+    </button>
+    <button
+      v-for="item in filter.items"
+      :key="String(item.value)"
+      type="button"
+      role="option"
+      :aria-selected="filter.isSelected(item.value)"
+      :disabled="item.disabled || full && !filter.isSelected(item.value)"
+      :class="classes.item"
+      :data-selected="filter.isSelected(item.value) || void 0"
+      data-filter-row
+      @click="pick(item)"
+    >
+      <slot
+        name="item"
+        :item
+        :selected="filter.isSelected(item.value)"
+        :disabled="Boolean(item.disabled || full && !filter.isSelected(item.value))"
+        :filter
+      >
+        <span
+          v-if="filter.multiple"
+          :class="classes.check"
+          :data-checked="filter.isSelected(item.value) || void 0"
+          aria-hidden="true"
+        >
+          <UIcon name="i-lucide-check" class="size-3" />
+        </span>
+        <UIcon v-if="item.icon" :name="item.icon" class="size-3.5 flex-none text-muted" />
+        <img
+          v-else-if="item.avatar?.src"
+          :src="item.avatar.src"
+          :alt="item.avatar.alt ?? ''"
+          :class="classes.avatar"
+        />
+        <span v-else-if="item.avatar?.text" :class="classes.avatar" aria-hidden="true">
+          {{ item.avatar.text }}
+        </span>
+        <span class="min-w-0 flex-1 truncate">{{ item.label }}</span>
+        <span v-if="item.hint" :class="classes.hint">{{ item.hint }}</span>
+        <UIcon
+          v-if="!filter.multiple && filter.isSelected(item.value)"
+          name="i-lucide-check"
+          :class="classes.tick"
+        />
+      </slot>
+    </button>
+    <div
+      v-if="filter.loading || filter.loadingMore"
+      :class="classes.note"
+      class="col-span-full"
+      data-filter-loading
+    >
+      {{ t("dashboard.filters.loading") }}
+    </div>
+    <div v-else-if="filter.error" :class="classes.note" class="col-span-full text-error">
+      <span class="truncate">{{ t("dashboard.filters.loadError") }}</span>
+      <button
+        type="button"
+        class="ms-2 font-medium underline-offset-2 hover:underline"
+        @click="filter.refresh()"
+      >
+        {{ t("dashboard.filters.retry") }}
+      </button>
+    </div>
+    <div v-else-if="filter.items.length === 0" :class="classes.note" class="col-span-full">
+      <slot name="empty" :filter>{{ t("dashboard.filters.empty") }}</slot>
+    </div>
+  </div>
+  <template v-if="showOptions && filter.multiple && filter.selected.length > 0">
+    <div :class="classes.separator" role="separator" />
+    <button type="button" :class="classes.item" data-filter-clear-selection @click="clear">
+      <UIcon name="i-lucide-x" class="size-3.5 flex-none text-muted" />
+      <span class="truncate">{{ t("dashboard.filters.clearSelection") }}</span>
+    </button>
+  </template>
+  <template v-if="showPresets">
+    <template v-if="showOptions">
+      <div :class="classes.separator" role="separator" />
+      <div :class="classes.title">{{ t("dashboard.filters.presets") }}</div>
+    </template>
+    <button
+      v-for="preset in filter.presets"
+      :key="preset.label"
+      type="button"
+      :class="classes.item"
+      :data-selected="preset.active || void 0"
+      data-filter-preset
+      @click="apply(preset)"
+    >
+      <UIcon :name="preset.icon ?? 'i-lucide-layers'" class="size-3.5 flex-none text-muted" />
+      <span class="min-w-0 flex-1 truncate">{{ preset.label }}</span>
+      <span v-if="preset.hint" :class="classes.hint">{{ preset.hint }}</span>
+      <UIcon v-if="preset.active" name="i-lucide-check" :class="classes.tick" />
+    </button>
+  </template>
+  <slot name="footer" :filter />
+</template>

package/dist/runtime/dashboard/components/filter/dashboard-filter-menu.vue.d.ts

@@ -0,0 +1,44 @@
+import type { DashboardFilterControl, DashboardFilterUi, DashboardOption, DashboardOptionValue } from '../../types/index.js';
+declare const __VLS_export: <TValue, TItem extends DashboardOptionValue>(__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<{
+        filter: DashboardFilterControl<TValue, TItem>;
+        classes: Required<DashboardFilterUi>;
+        /** Heading above the list. */
+        title?: string;
+        /** What the menu lists: the options, the presets, or both (presets under the options). */
+        list?: "all" | "options" | "presets";
+    } & {
+        onPicked?: (() => any) | undefined;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        item?: (props: {
+            item: DashboardOption<TItem>;
+            selected: boolean;
+            disabled: boolean;
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        header?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        footer?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+        empty?: (props: {
+            filter: DashboardFilterControl<TValue, TItem>;
+        }) => unknown;
+    };
+    emit: (evt: "picked") => void;
+}>) => 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

@@ -5,6 +5,8 @@ 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.
+ *
+ * Returns the facade and the view handles by view key.
  */
 export declare function useDashboardApi(params: {
     schema: DashboardSchemaLike;
@@ -12,4 +14,7 @@ export declare function useDashboardApi(params: {
     autoRefresh: WritableComputedRef<number>;
     root: ReturnType<typeof useDashboardScope>;
     views: ReturnType<typeof useDashboardViews> | null;
-}): object;
+}): {
+    api: import("vue").Raw<Record<string, unknown>>;
+    handles: Map<string, object>;
+};

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

@@ -7,6 +7,7 @@ import {
 export function useDashboardApi(params) {
   const { root, views } = params;
   const api = Object.fromEntries(root.members);
+  const handles = /* @__PURE__ */ new Map();
   for (const view of views?.views ?? []) {
     const handle = Object.fromEntries(view.scope.members);
     Object.defineProperties(handle, {
@@ -17,6 +18,9 @@ export function useDashboardApi(params) {
           get active() {
             return views?.current.value === view.key;
           },
+          get enabled() {
+            return view.enabled.value;
+          },
           key: view.key,
           get label() {
             return view.label();
@@ -27,16 +31,20 @@ export function useDashboardApi(params) {
         })
       }
     });
-    api[view.key] = markRaw(handle);
+    const facade = markRaw(handle);
+    api[view.key] = facade;
+    handles.set(view.key, facade);
   }
   const openedScopes = () => [
     root,
     ...views?.views.filter((view) => view.opened.value).map((view) => view.scope) ?? []
   ];
+  const currentView = () => views?.views.find((view) => view.key === views.current.value);
   const visibleScopes = () => {
-    const current = views?.views.find((view) => view.key === views.current.value);
+    const current = currentView();
     return current ? [root, current.scope] : [root];
   };
+  const visibleFilters = () => visibleScopes().map((scope) => scope.filterScope);
   Object.defineProperties(api, {
     ...scopeMembers(root),
     autoRefresh: {
@@ -46,11 +54,21 @@ export function useDashboardApi(params) {
         params.autoRefresh.value = Number.isFinite(seconds) ? Math.max(0, Math.round(seconds)) : 0;
       }
     },
+    filtered: {
+      enumerable: true,
+      get: () => visibleFilters().some((filters) => filters.changed())
+    },
     refresh: { enumerable: true, value: () => refreshDashboardSources(openedScopes()) },
     refreshing: {
       enumerable: true,
       get: () => openedScopes().some((scope) => scope.refreshing.value)
     },
+    resetFilters: {
+      enumerable: true,
+      value: () => {
+        for (const filters of visibleFilters()) filters.reset();
+      }
+    },
     schema: { enumerable: true, value: params.schema },
     state: {
       enumerable: true,
@@ -72,19 +90,24 @@ export function useDashboardApi(params) {
           views.current.value = next;
         },
         get items() {
-          return views.views.map((view) => ({ label: view.label(), value: view.key }));
+          return views.views.flatMap(
+            (view) => view.enabled.value ? [{ label: view.label(), value: view.key }] : []
+          );
         }
       })
     });
   }
-  return markRaw(api);
+  return { api: markRaw(api), handles };
 }
 function scopeMembers(scope) {
+  const { filterScope } = scope;
   return {
-    options: { enumerable: true, value: scope.paramScope.options },
-    params: { enumerable: true, value: scope.paramScope.values },
+    controls: { enumerable: true, value: filterScope.controls },
+    filtered: { enumerable: true, get: () => filterScope.changed() },
+    filters: { enumerable: true, value: filterScope.values },
     refresh: { enumerable: true, value: scope.refresh },
     refreshing: { enumerable: true, get: () => scope.refreshing.value },
+    resetFilters: { enumerable: true, value: () => filterScope.reset() },
     state: { enumerable: true, get: () => scope.state.value },
     updatedAt: { enumerable: true, get: () => scope.updatedAt.value }
   };

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

@@ -1,8 +1,9 @@
 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.
+ * Non-visual block behaviour: reduces the source into one render phase, hides the block while its
+ * source is `disabled`, activates deferred sources (on mount or when the block nears the viewport),
+ * and resolves the grid cell.
  *
  * 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.
@@ -12,11 +13,11 @@ export declare function useDashboardBlock(params: {
     empty: () => boolean;
     activation: () => DashboardBlockActivation | undefined;
     size: () => string | undefined;
-    rows: () => string | undefined;
     root: Readonly<ShallowRef<HTMLElement | null>>;
 }): {
+    fetching: import("vue").ComputedRef<boolean>;
+    hidden: import("vue").ComputedRef<boolean>;
     phase: import("vue").ComputedRef<DashboardBlockPhase>;
-    refreshing: import("vue").ComputedRef<boolean>;
     retry: () => void;
     style: import("vue").ComputedRef<string>;
 };