@svadmin/ui 0.88.1 → 0.92.0

package/dist/components/ComboboxField.svelte

@@ -4,6 +4,7 @@
   import { useTranslation } from '@svadmin/core/i18n';
   import { captureAdminContext, captureAuthSession, useResourceContract, useSelect } from '@svadmin/core';
   import { onDestroy, untrack } from 'svelte';
+  import { on } from 'svelte/events';
   import type { BaseRecord, Filter } from '@svadmin/core';
   import type { HTMLButtonAttributes } from 'svelte/elements';
   import type { ButtonProps } from './ui/button/index.js';
@@ -14,12 +15,16 @@
 
   const i18n = useTranslation();
 
-  function clickOutside(node: HTMLElement) {
+  function menuInteractions(node: HTMLElement) {
     const handler = (e: MouseEvent) => {
-      if (e.target instanceof Node && !node.contains(e.target)) open = false;
+      if (e.target instanceof Node && !node.contains(e.target) && open) closeMenu();
     };
     document.addEventListener('click', handler, true);
-    return { destroy() { document.removeEventListener('click', handler, true); } };
+    const removeKeydown = on(node, 'keydown', handleMenuKeydown);
+    return { destroy() {
+      document.removeEventListener('click', handler, true);
+      removeKeydown();
+    } };
   }
 
   interface Props extends Omit<HTMLButtonAttributes, 'value' | 'onchange' | 'children' | 'onclick' | 'type'> {
@@ -33,6 +38,10 @@
     multiple?: boolean;
     onSearch?: (value: string) => Filter[];
     fetchSize?: number;
+    requestTimeout?: number;
+    virtualized?: boolean;
+    itemHeight?: number;
+    viewportHeight?: number;
     id?: string;
     class?: string;
   }
@@ -48,6 +57,10 @@
     multiple = false,
     onSearch,
     fetchSize = 50,
+    requestTimeout,
+    virtualized = true,
+    itemHeight = 36,
+    viewportHeight = 280,
     disabled = false,
     ...restProps
   }: Props = $props();
@@ -57,23 +70,43 @@
   let searchInputValue = $state('');
   let page = $state(1);
   let appliedSearch = $state('');
+  let triggerButton = $state<HTMLButtonElement | HTMLAnchorElement | null>(null);
+  let searchInput = $state<HTMLInputElement | null>(null);
+  let commandRoot = $state<HTMLElement | null>(null);
+  let listElement = $state<HTMLElement | null>(null);
+  let listScrollTop = $state(0);
+  let activeIndex = $state(-1);
+  let loadMoreButton = $state<HTMLButtonElement | HTMLAnchorElement | null>(null);
   let timer: ReturnType<typeof setTimeout> | undefined;
   onDestroy(() => clearTimeout(timer));
   const normalizedFetchSize = $derived(
     Number.isSafeInteger(fetchSize) && fetchSize >= 10 && fetchSize <= 200 ? fetchSize : 50,
   );
+  const normalizedItemHeight = $derived(
+    Number.isSafeInteger(itemHeight) && itemHeight >= 32 && itemHeight <= 100 ? itemHeight : 36,
+  );
+  const normalizedViewportHeight = $derived(
+    Number.isSafeInteger(viewportHeight) && viewportHeight >= 120 && viewportHeight <= 800 ? viewportHeight : 280,
+  );
 
   const binding = useResourceContract(() => resource);
   const context = captureAdminContext();
+  const instanceId = $props.id();
+  const listboxId = $derived(`${instanceId}-listbox`);
+  const optionId = (index: number) => `${instanceId}-option-${index}`;
   const sourceScope = $derived({
     contract: binding.resource, provider: context.providers?.[binding.dataProviderName],
     meta: JSON.stringify(binding.meta), tenant: context.tenantCacheKey?.__svadminTenant,
     auth: context.authProvider, session: captureAuthSession(context.authProvider).cacheKey,
     access: context.accessControlProvider, router: context.routerProvider,
-    optionLabel, optionValue, onSearch, searchable, normalizedFetchSize,
+    optionLabel, optionValue, onSearch, searchable, normalizedFetchSize, requestTimeout: String(requestTimeout),
   });
+  function sameSourceScope(left: typeof sourceScope, right: typeof sourceScope): boolean {
+    return (Object.keys(left) as (keyof typeof sourceScope)[]).every(key => left[key] === right[key]);
+  }
   type Option = { value: string | number; label: string };
   let loaded = $state.raw<{ scope: typeof sourceScope; search: string; options: Option[] }>();
+  let observedSourceScope = untrack(() => sourceScope);
   const defaultSearch = $derived.by(() => {
     const field = optionLabel;
     return (v: string): Filter[] => v ? [{ field, operator: 'contains', value: v }] : [];
@@ -102,6 +135,7 @@
     },
     get projectionKey() { return `combobox:${optionLabel}:${optionValue}`; },
     get fetchSize() { return normalizedFetchSize; },
+    get requestTimeout() { return requestTimeout; },
     get pagination() { return { current: page, pageSize: normalizedFetchSize }; },
     get defaultValue() {
       if (Array.isArray(value)) return value;
@@ -110,14 +144,21 @@
     get filters() { return searchFilters.filters; },
     get queryOptions() { return { enabled: !searchFilters.invalid }; },
   }));
+  onDestroy(() => select.cancel());
 
   $effect.pre(() => {
-    void sourceScope;
+    const nextScope = sourceScope;
+    const previousScope = untrack(() => observedSourceScope);
+    // 字段说明和错误更新不改变查询作用域，也不应打断当前操作。
+    if (sameSourceScope(previousScope, nextScope)) return;
+    observedSourceScope = nextScope;
     clearTimeout(timer);
     searchInputValue = appliedSearch = '';
     open = false;
     page = 1;
     loaded = undefined;
+    listScrollTop = 0;
+    select.cancel();
   });
   $effect(() => {
     const data = select.query.data;
@@ -126,7 +167,7 @@
     const search = appliedSearch;
     const previous = untrack(() => loaded);
     const options = new Map<string | number, Option>(
-      page > 1 && previous?.scope === scope && previous.search === search
+      page > 1 && previous && sameSourceScope(previous.scope, scope) && previous.search === search
         ? previous.options.map(option => [option.value, option]) : [],
     );
     for (const option of data.options) options.set(option.value, option);
@@ -139,22 +180,86 @@
   const availableOptions = $derived.by(() => {
     if (select.isError || searchFilters.invalid) return [];
     const options = new Map<string | number, Option>(
-      loaded?.scope === sourceScope && loaded.search === appliedSearch
+      loaded && sameSourceScope(loaded.scope, sourceScope) && loaded.search === appliedSearch
         ? loaded.options.map(option => [option.value, option]) : [],
     );
     for (const option of select.options) options.set(option.value, option);
     return [...options.values()];
   });
   const totalOptions = $derived(select.query.data?.total ?? availableOptions.length);
-  const hasMore = $derived(totalOptions > page * normalizedFetchSize && !select.isError
+  const shouldVirtualize = $derived(virtualized && availableOptions.length >= 200);
+  const virtualTotalHeight = $derived(availableOptions.length * normalizedItemHeight);
+  const virtualMaxScroll = $derived(Math.max(0, virtualTotalHeight - normalizedViewportHeight));
+  const clampedListScrollTop = $derived(Math.max(0, Math.min(listScrollTop, virtualMaxScroll)));
+  const virtualStart = $derived(Math.max(0, Math.floor(clampedListScrollTop / normalizedItemHeight) - 5));
+  const virtualEnd = $derived(Math.min(availableOptions.length,
+    Math.ceil((clampedListScrollTop + normalizedViewportHeight) / normalizedItemHeight) + 5));
+  const renderedOptions = $derived(shouldVirtualize
+    ? availableOptions.slice(virtualStart, virtualEnd) : availableOptions);
+  const activeOptionId = $derived(shouldVirtualize && activeIndex >= 0 && availableOptions[activeIndex]
+    && activeIndex >= virtualStart && activeIndex < virtualEnd ? optionId(activeIndex) : undefined);
+  const hasMore = $derived((totalOptions > page * normalizedFetchSize || (select.query.isFetching && page > 1)) && !select.isError
     && !searchFilters.invalid && searchInputValue === appliedSearch);
   const invalidOptions = $derived(select.isError || searchFilters.invalid);
+  // 已确认值的回显独立于候选列表的错误/搜索过滤，避免后续分页失败或搜索期间清空选中摘要。
+  const selectionOptions = $derived.by(() => {
+    const options = new Map<string | number, Option>();
+    // 已选记录查询失败时沿用旧实现的隐藏标签边界，不能用旧页缓存回显。
+    if (select.defaultValueQuery.isError) return options;
+    if (loaded && sameSourceScope(loaded.scope, sourceScope)) {
+      for (const option of loaded.options) options.set(option.value, option);
+    }
+    for (const option of select.options) options.set(option.value, option);
+    return options;
+  });
   const selectedLabels = $derived(selectedValues.flatMap(selectedValue => {
-    const option = availableOptions.find(candidate => candidate.value === selectedValue);
+    const option = selectionOptions.get(selectedValue);
     return option ? [option.label] : [];
   }));
   const selectedLabel = $derived(selectedLabels.join(', '));
 
+  $effect.pre(() => {
+    if (disabled) closeMenu();
+  });
+  $effect(() => {
+    if (open && !disabled) (searchable ? searchInput : commandRoot)?.focus();
+  });
+  $effect.pre(() => {
+    if (!hasMore && open && loadMoreButton && document.activeElement === loadMoreButton) {
+      (searchable ? searchInput : commandRoot)?.focus();
+    }
+  });
+  $effect(() => {
+    const count = availableOptions.length;
+    if (activeIndex >= count) activeIndex = count > 0 ? count - 1 : -1;
+  });
+  $effect(() => {
+    if (!shouldVirtualize || activeIndex < 0) return;
+    if (activeIndex < virtualStart || activeIndex >= virtualEnd) activeIndex = -1;
+  });
+  $effect(() => {
+    if (listScrollTop !== clampedListScrollTop) {
+      listScrollTop = clampedListScrollTop;
+      if (listElement) listElement.scrollTop = clampedListScrollTop;
+    }
+  });
+
+  function closeMenu(restoreFocus = false): void {
+    open = false;
+    activeIndex = -1;
+    resetSearch();
+    if (restoreFocus && !disabled) triggerButton?.focus();
+  }
+
+  function retainMultiSelectFocus(): void {
+    if (!open || disabled) return;
+    const target = searchable ? searchInput : commandRoot;
+    const active = document.activeElement;
+    if (!target || (active !== document.body && active !== document.documentElement
+      && !commandRoot?.contains(active))) return;
+    target.focus();
+  }
+
   function handleSelect(optValue: string | number) {
     if (disabled || invalidOptions || select.isFetching || searchInputValue !== appliedSearch) return;
     if (multiple) {
@@ -162,26 +267,31 @@
         ? selectedValues.filter(selectedValue => selectedValue !== optValue)
         : [...selectedValues, optValue];
       onchange?.(next);
+      retainMultiSelectFocus();
       return;
     }
-    onchange?.(optValue === value ? null : optValue);
-    open = false;
-    resetSearch();
+    const next = optValue === value ? null : optValue;
+    closeMenu(true);
+    onchange?.(next);
   }
 
   function handleClear(e: Event) {
     e.stopPropagation();
     if (disabled) return;
+    closeMenu(true);
     onchange?.(multiple ? [] : null);
-    open = false;
-    resetSearch();
   }
 
   function resetSearch(): void {
     clearTimeout(timer);
+    timer = undefined;
     searchInputValue = appliedSearch = '';
     page = 1;
     loaded = undefined;
+    listScrollTop = 0;
+    activeIndex = -1;
+    if (listElement) listElement.scrollTop = 0;
+    select.cancel();
   }
 
   function handleSearchInput(e: Event) {
@@ -191,10 +301,13 @@
     clearTimeout(timer);
     const scope = sourceScope;
     const apply = () => {
-      if (scope !== sourceScope || disabled) return;
+      if (!open || searchInputValue !== v || !sameSourceScope(scope, sourceScope) || disabled) return;
       appliedSearch = v;
       page = 1;
       loaded = undefined;
+      listScrollTop = 0;
+      activeIndex = -1;
+      if (listElement) listElement.scrollTop = 0;
     };
     if (!v) apply();
     else timer = setTimeout(apply, 300);
@@ -204,19 +317,123 @@
     if (disabled || select.isFetching || !hasMore) return;
     page += 1;
   }
+
+  function handleTriggerKeydown(event: KeyboardEvent): void {
+    if (event.defaultPrevented || disabled || event.isComposing
+      || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault();
+      if (open) (searchable ? searchInput : commandRoot)?.focus();
+      else open = true;
+    }
+  }
+
+  function isButtonKeydown(
+    event: KeyboardEvent,
+  ): event is KeyboardEvent & { currentTarget: HTMLButtonElement } {
+    return event.currentTarget instanceof HTMLButtonElement;
+  }
+
+  function handleTriggerKeydownWithHost(event: KeyboardEvent): void {
+    if (isButtonKeydown(event)) restProps.onkeydown?.(event);
+    handleTriggerKeydown(event);
+  }
+
+  function handleMenuKeydown(event: KeyboardEvent): void {
+    if (!open || event.key !== 'Escape' || event.defaultPrevented || event.isComposing) return;
+    event.preventDefault();
+    event.stopPropagation();
+    closeMenu(true);
+  }
+
+  function revealActive(): void {
+    if (!shouldVirtualize || activeIndex < 0) return;
+    const top = activeIndex * normalizedItemHeight;
+    const bottom = top + normalizedItemHeight;
+    if (top < clampedListScrollTop) listScrollTop = top;
+    else if (bottom > clampedListScrollTop + normalizedViewportHeight) {
+      listScrollTop = bottom - normalizedViewportHeight;
+    }
+    if (listElement) listElement.scrollTop = listScrollTop;
+  }
+
+  function moveActive(delta: number): void {
+    const count = availableOptions.length;
+    if (!count) {
+      activeIndex = -1;
+      return;
+    }
+    const start = activeIndex < 0 ? (delta > 0 ? -1 : count) : activeIndex;
+    activeIndex = (start + delta + count) % count;
+    revealActive();
+  }
+
+  // 窗口化只挂载少量 Command.Item，键盘导航必须基于完整候选而不是已挂载节点。
+  function handleVirtualNavigation(event: KeyboardEvent): void {
+    if (!open || disabled || event.defaultPrevented || event.isComposing
+      || event.altKey || event.ctrlKey || event.metaKey || !shouldVirtualize) return;
+    const target = event.target;
+    if (!(target instanceof Node) || (target !== searchInput
+      && !(commandRoot && commandRoot.contains(target)))) return;
+    if (!availableOptions.length) return;
+    const key = event.key;
+    if (key === 'ArrowDown' || key === 'ArrowUp' || key === 'Home' || key === 'End') {
+      event.preventDefault();
+      event.stopPropagation();
+      if (key === 'ArrowDown' || key === 'ArrowUp') moveActive(key === 'ArrowDown' ? 1 : -1);
+      else {
+        activeIndex = key === 'Home' ? 0 : availableOptions.length - 1;
+        revealActive();
+      }
+      return;
+    }
+    if (key === 'Enter' && activeIndex >= 0) {
+      const option = availableOptions[activeIndex];
+      if (!option) return;
+      event.preventDefault();
+      event.stopPropagation();
+      handleSelect(option.value);
+    }
+  }
+
+  function handleFocusOut(event: FocusEvent): void {
+    const next = event.relatedTarget;
+    // 点击不可聚焦的选项时 relatedTarget 为空，保留弹层以完成随后的 click。
+    if (next instanceof Node && event.currentTarget instanceof HTMLElement
+      && !event.currentTarget.contains(next)) closeMenu();
+  }
+
 </script>
 
-<div class="svadmin-u-d89972fe17d6" use:clickOutside>
+{#snippet optionRow(opt: Option, index: number)}
+  <Command.Item
+    id={optionId(index)}
+    disabled={select.isFetching || searchInputValue !== appliedSearch}
+    value={`${typeof opt.value}:${opt.value}`}
+    onSelect={() => handleSelect(opt.value)}
+    style={shouldVirtualize ? `height:${normalizedItemHeight}px;` : undefined}
+    class="svadmin-u-d89972fe17d6 svadmin-u-60fbb7713999 svadmin-u-50ca6ba56aa3 svadmin-u-7f6912283f11 svadmin-u-3960ffc248d9 svadmin-u-36d4469299aa svadmin-u-d5eab218aa34 svadmin-u-ec0091ee009b svadmin-u-fc7473ca09eb svadmin-u-df37b1fd9495 svadmin-u-99afb1cc3b47 svadmin-u-529780e25268"
+  >
+    <Check class="svadmin-u-d2347e8497a9 svadmin-u-7fc7f732bf7e svadmin-u-bf600f8e029c {selectedValues.includes(opt.value) ? 'svadmin-u-3972e98dc84f' : 'svadmin-u-7065497e1ca0'}" />
+    {opt.label}
+  </Command.Item>
+{/snippet}
+
+<div class="svadmin-u-d89972fe17d6" use:menuInteractions onfocusout={handleFocusOut}
+  onkeydowncapture={handleVirtualNavigation}>
   <div class="select-control">
   <Button
+    bind:ref={triggerButton}
     variant="outline"
     type="button"
     class="svadmin-u-6da6a3c3f741 svadmin-u-8ef2268efbbc svadmin-u-8ecebc9f80e6"
-    onclick={() => { open = !open; }}
+    onclick={() => { if (open) closeMenu(); else open = true; }}
     {...buttonRestProps}
+    onkeydown={handleTriggerKeydownWithHost}
     {disabled}
     aria-haspopup="listbox"
     aria-expanded={open}
+    aria-controls={open ? listboxId : undefined}
     aria-multiselectable={multiple || undefined}
     aria-busy={select.isFetching}
     aria-invalid={invalidOptions || restProps['aria-invalid']}
@@ -247,21 +464,32 @@
 
   {#if open && !disabled}
     <div class="svadmin-u-da4dbfbc4fdc svadmin-u-181b286668b5 svadmin-u-b6b02c0ebef6 svadmin-u-6da6a3c3f741 svadmin-u-421ac2be5045 svadmin-u-ca6bcd4b6f3f svadmin-u-e541d86d1ec8 svadmin-u-06bbb43166db">
-      <Command.Root shouldFilter={false} class="svadmin-u-60fbb7713999 svadmin-u-8dddea0773ed svadmin-u-2cd02d11d1af svadmin-u-421ac2be5045 svadmin-u-e541d86d1ec8 svadmin-u-9b13e8ae5c9c">
+      <Command.Root bind:ref={commandRoot} shouldFilter={false} class="svadmin-u-60fbb7713999 svadmin-u-8dddea0773ed svadmin-u-2cd02d11d1af svadmin-u-421ac2be5045 svadmin-u-e541d86d1ec8 svadmin-u-9b13e8ae5c9c">
         {#if searchable}
           <div class="svadmin-u-60fbb7713999 svadmin-u-3960ffc248d9 svadmin-u-65fdbade2025 svadmin-u-d5eab218aa34">
             <Search class="svadmin-u-82cc6c6581cd svadmin-u-7fc7f732bf7e svadmin-u-bf600f8e029c svadmin-u-012fbd121f37 svadmin-u-0b8c506a0596" />
             <Command.Input
+              bind:ref={searchInput}
               bind:value={searchInputValue}
               oninput={handleSearchInput}
+              aria-activedescendant={activeOptionId}
               placeholder={i18n.t('common.search')}
               class="svadmin-u-60fbb7713999 svadmin-u-e7a768f922d2 svadmin-u-6da6a3c3f741 svadmin-u-7f19cdf4c5bb svadmin-u-03b4dd7f172b svadmin-u-fc7473ca09eb svadmin-u-df37b1fd9495 svadmin-u-9c24ab70af61"
             />
           </div>
         {/if}
         <Command.List
+          bind:ref={listElement}
+          id={listboxId}
           role="listbox"
+          tabindex={-1}
+          aria-activedescendant={activeOptionId}
           aria-multiselectable={multiple || undefined}
+          style={shouldVirtualize
+            ? `height:${normalizedViewportHeight}px;max-height:${normalizedViewportHeight}px;overflow-y:auto;` : undefined}
+          onscroll={(event: Event) => {
+            if (event.currentTarget instanceof HTMLElement) listScrollTop = event.currentTarget.scrollTop;
+          }}
           class="svadmin-u-558f64349245 svadmin-u-92bf82f493b1 svadmin-u-eb6a3cef9686"
         >
           {#if select.isLoading}
@@ -274,25 +502,28 @@
                 {i18n.t('select.noResults')}
               </Command.Empty>
             {/if}
-            {#each availableOptions as opt (`${typeof opt.value}:${opt.value}`)}
-              <Command.Item
-                disabled={select.isFetching || searchInputValue !== appliedSearch}
-                value={`${typeof opt.value}:${opt.value}`}
-                onSelect={() => handleSelect(opt.value)}
-                class="svadmin-u-d89972fe17d6 svadmin-u-60fbb7713999 svadmin-u-50ca6ba56aa3 svadmin-u-7f6912283f11 svadmin-u-3960ffc248d9 svadmin-u-36d4469299aa svadmin-u-d5eab218aa34 svadmin-u-ec0091ee009b svadmin-u-fc7473ca09eb svadmin-u-df37b1fd9495 svadmin-u-99afb1cc3b47 svadmin-u-529780e25268"
-              >
-                <Check class="svadmin-u-d2347e8497a9 svadmin-u-7fc7f732bf7e svadmin-u-bf600f8e029c {selectedValues.includes(opt.value) ? 'svadmin-u-3972e98dc84f' : 'svadmin-u-7065497e1ca0'}" />
-                {opt.label}
-              </Command.Item>
-            {/each}
+            {#if shouldVirtualize}
+              <div style={`height:${virtualTotalHeight}px;position:relative;`}>
+                <div style={`position:absolute;top:${virtualStart * normalizedItemHeight}px;left:0;right:0;`}>
+                  {#each renderedOptions as opt, offset (`${typeof opt.value}:${opt.value}`)}
+                    {@render optionRow(opt, virtualStart + offset)}
+                  {/each}
+                </div>
+              </div>
+            {:else}
+              {#each renderedOptions as opt, index (`${typeof opt.value}:${opt.value}`)}
+                {@render optionRow(opt, index)}
+              {/each}
+            {/if}
           {/if}
         </Command.List>
-        {#if hasMore}
-          <Button type="button" variant="ghost" size="sm" disabled={select.isFetching} onclick={loadMore}>
-            {i18n.t('select.loadMore')}
-          </Button>
-        {/if}
       </Command.Root>
+      {#if hasMore}
+        <Button bind:ref={loadMoreButton} type="button" variant="ghost" size="sm"
+          aria-disabled={select.isFetching} aria-busy={select.isFetching} onclick={loadMore}>
+          {i18n.t('select.loadMore')}
+        </Button>
+      {/if}
     </div>
   {/if}
 </div>
@@ -302,6 +533,11 @@
     display: flex;
     align-items: center;
     gap: 4px;
+    min-inline-size: 0;
+  }
+  .select-control > :global(button[data-slot='button']:first-child) {
+    flex: 1 1 auto;
+    min-inline-size: 0;
   }
   .select-error {
     color: var(--destructive);

package/dist/components/ComboboxField.svelte.d.ts

@@ -11,6 +11,10 @@ interface Props extends Omit<HTMLButtonAttributes, 'value' | 'onchange' | 'child
     multiple?: boolean;
     onSearch?: (value: string) => Filter[];
     fetchSize?: number;
+    requestTimeout?: number;
+    virtualized?: boolean;
+    itemHeight?: number;
+    viewportHeight?: number;
     id?: string;
     class?: string;
 }

package/dist/components/CommandPalette.svelte

@@ -103,7 +103,7 @@
             {#if adminContext.accessControlProvider}
               <CanAccess resource={r.name} action="list">
                 <Command.Item
-                  value={r.name}
+                  value={`${r.name} ${r.label}`}
                   onSelect={() => act(() => navigation.list(r.name))}
                   class={itemClass}
                 >
@@ -113,7 +113,7 @@
               </CanAccess>
             {:else}
               <Command.Item
-                value={r.name}
+                value={`${r.name} ${r.label}`}
                 onSelect={() => act(() => navigation.list(r.name))}
                 class={itemClass}
               >
@@ -132,13 +132,13 @@
             {#if r.canCreate !== false}
               {#if adminContext.accessControlProvider}
                 <CanAccess resource={r.name} action="create">
-                  <Command.Item value={"create-" + r.name} onSelect={() => act(() => navigation.create(r.name))} class={itemClass}>
+                  <Command.Item value={`${"create-" + r.name} ${r.label}`} onSelect={() => act(() => navigation.create(r.name))} class={itemClass}>
                     <Plus class="svadmin-u-11e59c6d5f6b svadmin-u-dc7972ebf3f3 svadmin-u-bfa603190748" />
                     {i18n.t('common.create')} {r.label}
                   </Command.Item>
                 </CanAccess>
               {:else}
-                <Command.Item value={"create-" + r.name} onSelect={() => act(() => navigation.create(r.name))} class={itemClass}>
+                <Command.Item value={`${"create-" + r.name} ${r.label}`} onSelect={() => act(() => navigation.create(r.name))} class={itemClass}>
                   <Plus class="svadmin-u-11e59c6d5f6b svadmin-u-dc7972ebf3f3 svadmin-u-bfa603190748" />
                   {i18n.t('common.create')} {r.label}
                 </Command.Item>

package/dist/components/DashboardView.svelte

@@ -4,7 +4,10 @@
     DashboardContractError, captureAdminContext, captureAuthSession, createEnterpriseRequestContext,
     decodeDashboardQuery, decodeDashboardSnapshot,
   } from '@svadmin/core';
-  import type { DashboardProvider, DashboardSnapshot, EnterpriseProviderRequestContext } from '@svadmin/core';
+  import type {
+    DashboardDrilldown, DashboardMetric, DashboardProvider, DashboardQuery, DashboardSnapshot, DashboardTimeRange,
+    DashboardWidget, EnterpriseProviderRequestContext,
+  } from '@svadmin/core';
   import { useTranslation } from '@svadmin/core/i18n';
   import { onDestroy, untrack } from 'svelte';
   import MetricStrip, { type MetricStripItem } from './MetricStrip.svelte';
@@ -15,15 +18,20 @@
     dashboardId: string;
     requestContext?: EnterpriseProviderRequestContext;
     filters?: readonly { field: string; value: string | number | boolean | null }[];
+    timeRange?: DashboardTimeRange;
+    onDrillDown?: ((input: DashboardDrilldown) => void | Promise<void>) | undefined;
     title?: string;
   }
-  let { provider, dashboardId, requestContext, filters = [], title }: Props = $props();
+  let { provider, dashboardId, requestContext, filters = [], timeRange, onDrillDown, title }: Props = $props();
   const context = captureAdminContext();
   const i18n = useTranslation();
   let snapshot = $state<DashboardSnapshot>();
+  let loadedQuery: DashboardQuery | undefined;
   let loading = $state(false);
   let error = $state<'load' | 'invalid'>();
+  let drillError = $state(false);
   let epoch = 0;
+  let drillSequence = 0;
   let mounted = true;
   let generatedContext: EnterpriseProviderRequestContext | undefined;
   onDestroy(() => { mounted = false; });
@@ -45,13 +53,18 @@
       const request = decodeDashboardQuery({
         dashboardId: dashboardId.trim(),
         ...(filters.length ? { filters: filters.map(filter => ({ ...filter })) } : {}),
+        ...(timeRange ? { timeRange: { from: timeRange.from, to: timeRange.to } } : {}),
       });
+      // 独立保存已校验查询；Provider 可能原位修改传入的 request。
+      const loaded = decodeDashboardQuery(request);
       const result = decodeDashboardSnapshot(await provider.get(resolveContext(), request));
       if (!mounted || currentEpoch !== epoch) return;
       snapshot = result;
+      loadedQuery = loaded;
     } catch (cause) {
       if (!mounted || currentEpoch !== epoch) return;
       snapshot = undefined;
+      loadedQuery = undefined;
       error = cause instanceof DashboardContractError ? 'invalid' : 'load';
     } finally {
       if (mounted && currentEpoch === epoch) loading = false;
@@ -63,14 +76,58 @@
       id: `${widget.id}:${metric.id}`, label: metric.label,
       value: typeof metric.value === 'boolean' ? String(metric.value) : metric.value ?? '—',
       ...(metric.tone ? { tone: metric.tone } : {}),
-      ...(metric.href ? { href: metric.href } : {}),
+      ...(onDrillDown
+        ? { onActivate: () => drillDown(widget, metric) }
+        : metric.href ? { href: metric.href } : {}),
     })) : [],
   ) ?? []);
 
+  function drillDown(widget: DashboardWidget, metric?: DashboardMetric): void {
+    const query = loadedQuery;
+    if (!onDrillDown || !query) return;
+    const currentLoad = epoch;
+    const currentDrill = ++drillSequence;
+    drillError = false;
+    const settle = (failed: boolean): void => {
+      if (!mounted || currentLoad !== epoch || currentDrill !== drillSequence) return;
+      drillError = failed;
+    };
+    const input: DashboardDrilldown = {
+      dashboardId: query.dashboardId,
+      widget: { id: widget.id, title: widget.title, kind: widget.kind },
+      ...(metric ? { metric: { ...metric } } : {}),
+      filters: (query.filters ?? []).map(filter => ({ ...filter })),
+      ...(query.timeRange ? { timeRange: { ...query.timeRange } } : {}),
+    };
+    try {
+      const result = onDrillDown(input);
+      void Promise.resolve(result).then(() => settle(false), () => settle(true));
+    } catch { settle(true); }
+  }
+
+  function trackQueryInputs(): void {
+    for (const filter of filters) {
+      void filter.field;
+      void filter.value;
+    }
+    if (timeRange) {
+      void timeRange.from;
+      void timeRange.to;
+    }
+  }
+
+  // 显式跟踪嵌套查询值；Provider 执行留在下方 untrack 内，避免 effect 重入。
   $effect(() => {
-    void provider; void dashboardId; void requestContext; void filters;
+    void provider; void dashboardId; void requestContext;
+    trackQueryInputs();
     void captureAuthSession(context.authProvider).cacheKey;
-    untrack(() => { snapshot = undefined; void load(); });
+    untrack(() => {
+      drillSequence += 1;
+      drillError = false;
+      snapshot = undefined;
+      loadedQuery = undefined;
+      void load();
+    });
   });
 </script>
 
@@ -82,10 +139,19 @@
     </Button>
   </header>
   {#if loading}<div role="status"><Loader2 aria-hidden="true" /> {i18n.t('common.loading')}</div>
-  {:else if error}<div role="alert">{i18n.t(`dashboard.${error}`)}</div>
+  {:else if error}<div role="alert">{i18n.t(`dashboard.${error}`)}
+    <Button type="button" variant="outline" size="sm" onclick={() => void load()}>{i18n.t('common.retry')}</Button>
+  </div>
   {:else if snapshot}
+    {#if drillError}<div role="alert">{i18n.t('common.operationFailed')}</div>{/if}
     {#each snapshot.widgets.filter(widget => widget.kind === 'text') as widget (widget.id)}
-      <section aria-labelledby={`dashboard-widget-${widget.id}`}><h3 id={`dashboard-widget-${widget.id}`}>{widget.title}</h3><p>{widget.text}</p></section>
+      <section aria-labelledby={`dashboard-widget-${widget.id}`}><h3 id={`dashboard-widget-${widget.id}`}>{widget.title}</h3><p>{widget.text}</p>
+        {#if onDrillDown}
+          <Button type="button" variant="outline" size="sm"
+            aria-label={`${i18n.t('dashboard.drilldown')}: ${widget.title}`}
+            onclick={() => drillDown(widget)}>{i18n.t('dashboard.drilldown')}</Button>
+        {/if}
+      </section>
     {/each}
     <MetricStrip items={metricItems} ariaLabel={title ?? i18n.t('dashboard.metrics')} />
   {:else}<div role="status">{i18n.t('dashboard.empty')}</div>{/if}