@eifi1/ui-kit 0.6.0 → 0.7.0

package/src/i18n/locales/zh.ts

@@ -0,0 +1,348 @@
+import { formatFileSize } from "../kit-labels";
+import type { UiKitLabels } from "../kit-labels";
+
+/**
+ * The kit's words in Chinese (Simplified): every namespace of {@link UiKitLabels}, for
+ * `<UiKitProvider labels={UI_KIT_LABELS_ZH}>`.
+ *
+ * Self-contained on purpose — nothing but the kit's own `formatFileSize` — so it works
+ * as a starting point to copy and adjust. Counts and sizes are formatted with
+ * `zh-CN` digits; {@link uiKitLabelsZh} takes another number locale
+ * (e.g. `"de-CH"` for 1’234) without touching the words.
+ */
+export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
+  const num = new Intl.NumberFormat(numberLocale);
+  const n = (value: number) => num.format(value);
+
+  return {
+    feedbackAttachment: {
+      attachmentAdd: "附加图片",
+      attachmentCapture: "截取屏幕",
+      attachmentPaste: "……或从剪贴板粘贴截图。",
+      attachmentRemove: "移除附件",
+    },
+    measuredGrid: {
+      view: "表格视图",
+      cellsView: "单元格",
+      textView: "文本",
+      addRow: "添加行",
+      removeRow: (row) => `删除第 ${row} 行`,
+      clear: "清空表格",
+      pasteHint: "可将电子表格中的一块数据粘贴到任意单元格",
+      cell: (column, row) => `${column}，第 ${row} 行`,
+      rowNumber: "行",
+      rowActions: "行操作",
+      keyboardHint:
+        "方向键在单元格之间移动。直接输入替换单元格内容，F2 编辑，Esc 撤销编辑。回车向下移动，并在末尾添加一行。",
+      lineError: (line) => `无法读取第 ${line} 行`,
+      points: (count) => `${count} 个点`,
+      problems: (count) => `${count} 个单元格不是数字`,
+    },
+    pageContents: { title: "本页目录" },
+    common: {
+      close: "关闭",
+      clear: "清除",
+      search: "搜索",
+      done: "完成",
+      cancel: "取消",
+      save: "保存",
+      back: "上一步",
+      next: "下一步",
+      remove: "移除",
+      loading: "加载中…",
+      noResults: "无结果",
+      // Full-width colon, no space after it.
+      fieldValue: (field, value) => `${field}：${value}`,
+    },
+    dataTable: {
+      columns: "列",
+      selectAllRows: "全选所有行",
+      sortHint: "点击排序 · 按住 Shift 点击可添加排序",
+      filter: "筛选",
+      close: "关闭",
+      selectRow: "选择行",
+      autoSize: "自动调整列宽",
+      loading: "加载中…",
+      filters: "筛选条件",
+      clearAll: "全部清除",
+      done: "完成",
+      pageSize: "每页行数",
+      pageSizeAll: "全部",
+      prevPage: "上一页",
+      nextPage: "下一页",
+      clearFilter: "清除筛选",
+      filterPlaceholder: "筛选…",
+      selectFilter: "选择",
+      selectAll: "全部",
+      selectNone: "无",
+      dateFrom: "从",
+      dateTo: "至",
+      numberMin: "最小值",
+      numberMax: "最大值",
+      numberAbs: "绝对值",
+      presets: {
+        today: "今天",
+        yesterday: "昨天",
+        this_week: "本周",
+        last_week: "上周",
+        last_7_days: "最近 7 天",
+        last_30_days: "最近 30 天",
+        this_month: "本月",
+        last_month: "上月",
+        last_3_months: "最近 3 个月",
+        ytd: "今年至今",
+        last_year: "去年",
+      },
+      table: "数据表格",
+      filterResults: (shown, total) => `显示 ${n(shown)} 行，共 ${n(total)} 行`,
+      sortedAscending: (column) => `已按“${column}”升序排序`,
+      sortedDescending: (column) => `已按“${column}”降序排序`,
+      sortCleared: (column) => `已取消“${column}”的排序`,
+      pageChanged: (page, totalPages) => `第 ${n(page)} 页，共 ${n(totalPages)} 页`,
+      pageRange: (from, to, total) => `${n(from)}–${n(to)} / ${n(total)}`,
+      rowCount: (total) => n(total),
+      columnsCount: (visible, total) => `列（${n(visible)}/${n(total)}）`,
+    },
+    miniCalendar: {
+      previousMonth: "上个月",
+      nextMonth: "下个月",
+      // Already formatted in the provider's locale ("2026年9月14日星期一").
+      day: (date) => date,
+      chooseStart: "请选择开始日期",
+      chooseEnd: "请选择结束日期",
+      startSelected: (date) => `已选择 ${date} 为开始日期。请选择结束日期。`,
+      rangeSelected: (from, to) => `已选择 ${from} 至 ${to}。如需重新选择，请先选择开始日期。`,
+    },
+    monthPicker: {
+      previousYear: "上一年",
+      nextYear: "下一年",
+      panel: "选择月份",
+      month: (monthYear) => monthYear,
+    },
+    datePicker: {
+      panel: "选择日期",
+      rangePanel: "选择日期范围",
+      clear: "清除",
+      previousDay: "前一天",
+      nextDay: "后一天",
+      today: "今天",
+    },
+    popover: {
+      panel: "弹出框",
+    },
+    combobox: {
+      search: "搜索",
+      noResults: "无结果",
+      clear: "清除",
+      loading: "加载中…",
+      create: (query) => `创建“${query}”`,
+      selectedCount: (count) => `已选 ${n(count)} 项`,
+      loadError: "无法加载结果",
+      resultCount: (count) => `${n(count)} 个结果`,
+      minChars: (count) => `请至少输入 ${n(count)} 个字符`,
+    },
+    multiSelect: {
+      search: "搜索",
+      selectAll: "全选",
+      clear: "清除",
+      all: "全部",
+      // The bare count, as in English: the trigger has always shown just the number.
+      selectedCount: (count) => n(count),
+    },
+    calculator: {
+      open: "打开计算器",
+      panel: "计算器",
+      calculation: "算式",
+      backspace: "退格",
+      clear: "清除",
+      equals: "等于",
+      done: "完成",
+      plus: "加",
+      minus: "减",
+      times: "乘",
+      divide: "除以",
+      decimal: "小数点",
+    },
+    currency: {
+      currency: "货币",
+      search: "搜索货币",
+    },
+    chipInput: {
+      added: (value) => `已添加“${value}”`,
+      removed: (value) => `已移除“${value}”`,
+      remove: "移除",
+      atLimit: (max) => `已达上限（${n(max)} 项）`,
+      duplicate: (value) => `“${value}”已在列表中`,
+    },
+    swatchPicker: {
+      none: "无颜色",
+      mixed: "混合：所选项目的颜色各不相同",
+    },
+    iconPicker: {
+      none: "无图标",
+      mixed: "混合：所选项目的图标各不相同",
+      search: "搜索图标",
+      noResults: "没有匹配的图标",
+      resultCount: (count) => `${n(count)} 个图标`,
+    },
+    fieldSync: {
+      synced: "已保存",
+      edited: "有未保存的更改",
+      pending: "正在保存…",
+      error: "保存失败",
+      retry: "重试",
+    },
+    passwordReveal: {
+      show: "显示密码",
+      hide: "隐藏密码",
+    },
+    dangerConfirm: {
+      arm: "删除…",
+      confirm: "删除",
+      cancel: "取消",
+      prompt: "此操作无法撤销。",
+      password: "密码",
+      phrase: (phrase) => `输入“${phrase}”以确认`,
+    },
+    tabs: {
+      add: "添加标签页",
+      // Quoted, so the spacing rule holds whether the tab's name is Han or Latin.
+      remove: (tab) => `移除“${tab}”`,
+    },
+    appShell: {
+      collapse: "收起侧边栏",
+      expand: "展开侧边栏",
+      toggleGroup: (groupLabel) => `${groupLabel}：页面`,
+    },
+    topBar: {
+      theme: "切换主题",
+      palette: "外观预设",
+      language: "语言",
+      switchRole: "切换角色",
+      role: (value) => `角色：${value}`,
+    },
+    pickerSheet: {
+      close: "关闭",
+    },
+    dialogFrame: {
+      close: "关闭",
+    },
+    swipeableRow: {
+      actions: "行操作",
+    },
+    file: {
+      // The kit's own `Intl` unit formatting, pinned to this locale.
+      size: (bytes) => formatFileSize(bytes, numberLocale),
+    },
+    filePicker: {
+      rejectedPick: (count) => (count === 1 ? "未添加该文件" : `${count} 个文件均未添加`),
+      rejectedType: (name) => `“${name}”的文件类型不受支持`,
+      rejectedTypeOnly: (accept) => `仅限 ${accept} 文件`,
+      rejectedSize: (name, maxSize) => `“${name}”超过 ${maxSize}`,
+      rejectedCount: (name, maxFiles) => `未添加“${name}”：最多 ${n(maxFiles)} 个文件`,
+      rejectedInvalid: (name) => `“${name}”无法在此使用`,
+      rejectedMany: (count) => `${n(count)} 个文件未添加`,
+      selected: (count, firstName) =>
+        count === 1 ? `已选择“${firstName}”` : `已选择 ${n(count)} 个文件`,
+      remove: (name) => `移除“${name}”`,
+      clearAll: "移除所有文件",
+      removed: (name) => `已移除“${name}”`,
+      cleared: "已移除所有文件",
+    },
+    wizard: {
+      cancel: "取消",
+      back: "上一步",
+      next: "下一步",
+      skip: "跳过",
+      finish: "完成",
+      submitting: "正在创建…",
+      steps: "步骤",
+      step: (current, total) => `第 ${n(current)} 步，共 ${n(total)} 步`,
+      cancelTitle: "放弃此表单？",
+      confirmCancel: "已填写的内容将会丢失。",
+      cancelConfirmLabel: "放弃",
+      cancelDismissLabel: "继续编辑",
+      reviewTitle: "确认信息",
+      edit: "编辑",
+      missingRequired: "请填写所有必填字段。",
+      genericError: "发生错误",
+    },
+    tour: {
+      next: "下一步",
+      back: "上一步",
+      skip: "跳过",
+      done: "完成",
+      awaitClickHint: "点击高亮的元素以继续",
+      step: (current, total) => `${n(current)} / ${n(total)}`,
+    },
+    commandPalette: {
+      placeholder: "搜索…",
+      empty: "无结果",
+      loading: "搜索中…",
+      dialog: "搜索",
+      error: "搜索失败，请重试。",
+    },
+    sparkline: {
+      rising: (first, last) => `从 ${first} 上升到 ${last}`,
+      falling: (first, last) => `从 ${first} 下降到 ${last}`,
+      flat: (value) => `保持在 ${value} 不变`,
+      single: (value) => `仅一个值：${value}`,
+      noData: "无数据",
+      named: (name, summary) => `${name}：${summary}`,
+    },
+    statTile: {
+      increase: (amount) => `上升 ${amount}`,
+      decrease: (amount) => `下降 ${amount}`,
+      unchanged: "无变化",
+      better: (change) => `${change}（向好）`,
+      worse: (change) => `${change}（变差）`,
+      noValue: "无数据",
+      loading: "加载中…",
+    },
+    signaturePad: {
+      label: "签名",
+      instructions: "请使用鼠标、手指或触控笔在框内签名。",
+      typedFallbackHint: "如果无法手写，可以改为输入姓名。",
+      empty: "尚未签名",
+      signed: "已签名",
+      undo: "撤销上一笔",
+      clear: "清除",
+      save: "保存签名",
+      useTyped: "改为输入姓名",
+      useDrawn: "改为手写",
+      typedName: "姓名",
+      cleared: "签名已清除",
+      undone: "已撤销上一笔",
+      viewEmpty: "未签名",
+      viewDrawn: "手写签名",
+      // Quoted, so the spacing rule holds whether the name is Han or Latin.
+      viewTyped: (name) => `以输入的姓名“${name}”签名`,
+    },
+    passwordStrength: {
+      tooShort: "太短",
+      weak: "弱",
+      fair: "一般",
+      good: "良好",
+      strong: "强",
+      announcement: (level) => `密码强度：${level}`,
+      // Unformatted, as in the English default.
+      ruleLength: (minLength) => `至少 ${minLength} 个字符`,
+      ruleCase: "包含大写和小写字母",
+      ruleDigit: "包含数字",
+      ruleSymbol: "包含符号",
+      optional: (rule) => `${rule}（可选）`,
+      met: "已满足：",
+      notMet: "未满足：",
+      tooLong: (maxBytes) => `最多 ${maxBytes} 个字符（带重音的字母和表情符号按多个字符计算）。`,
+    },
+    seriesChart: {
+      resetZoom: "重置缩放",
+      zoomHint:
+        "拖动以缩放：近似正方形的选区同时缩放两条坐标轴，细长的选区只缩放其所沿的那条轴。双击可重置。",
+      empty: "无数据",
+      legend: "数据系列",
+    },
+  };
+}
+
+export const UI_KIT_LABELS_ZH: UiKitLabels = uiKitLabelsZh();

package/src/index.ts

@@ -87,6 +87,9 @@ export * from "./components/swatch-picker";
 export * from "./components/icon-picker";
 export * from "./components/choice-card";
 export * from "./components/autocomplete";
+export * from "./components/measured-grid";
+export { useWindowedRows } from "./hooks/use-windowed-rows";
+export type { WindowedRows } from "./hooks/use-windowed-rows";
 // Named, not `export *`: file-button.tsx also holds the screening helpers the
 // dropzone shares, which are internal.
 export { FileButton, useFilePicker, matchesAccept, DEFAULT_FILE_PICKER_LABELS } from "./components/file-button";
@@ -131,7 +134,13 @@ export { FilterPopover } from "./components/data-table-filter-popover";
 // data-table re-exports SortState internally; export the rest explicitly to
 // avoid a duplicate SortState star-export (it comes from data-table-sort).
 export { DataTable } from "./components/data-table";
-export type { DataTableColumn, DataTableProps, ServerPagination, FilterState } from "./components/data-table";
+export type {
+  DataTableColumn,
+  DataTableProps,
+  ServerPagination,
+  FilterState,
+  MobileSwipeActions,
+} from "./components/data-table";
 
 // ── shell (composable app chrome) ────────────────────────────────────────────
 export * from "./shell/topbar-controls";

package/src/lib/direction.ts

@@ -0,0 +1,37 @@
+/**
+ * Reading direction, as the DOM has it — internal, not exported from the barrel.
+ *
+ * The kit lays itself out with logical classes (`ps-*`, `end-*`, `text-start`), which
+ * need no JavaScript. These helpers are for the two things CSS cannot do:
+ *
+ * - **Arrow keys.** ←/→ mean previous/next in LTR and the reverse in RTL. Resolve the
+ *   key through {@link horizontalStep} instead of comparing to "ArrowRight".
+ * - **Portals.** A panel portalled to `document.body` leaves the subtree whose `dir`
+ *   it inherited. Read the anchor's direction with {@link dirOf} and put it on the
+ *   portalled root, and position it from the anchor's START edge, not `rect.left`.
+ */
+
+export type Direction = "ltr" | "rtl";
+
+/** The effective direction at `el`: its nearest `[dir]` ancestor (or itself), else the
+ *  document's, else LTR. Attribute-based on purpose — jsdom computes no `direction`. */
+export function dirOf(el: Element | null | undefined): Direction {
+  const source =
+    el?.closest("[dir]") ??
+    (typeof document !== "undefined" ? document.documentElement : null);
+  return source?.getAttribute("dir") === "rtl" ? "rtl" : "ltr";
+}
+
+export function isRtl(el: Element | null | undefined): boolean {
+  return dirOf(el) === "rtl";
+}
+
+/**
+ * +1 for a key that moves FORWARD along the reading direction, -1 for backward, 0 for
+ * any other key. ArrowRight is forward in LTR and backward in RTL.
+ */
+export function horizontalStep(key: string, el: Element | null | undefined): 1 | -1 | 0 {
+  if (key !== "ArrowRight" && key !== "ArrowLeft") return 0;
+  const forward = (key === "ArrowRight") !== isRtl(el);
+  return forward ? 1 : -1;
+}

package/src/rhf/form.tsx

@@ -51,6 +51,27 @@
  * `<Input {...field} invalid={fieldState.invalid} />`. `FormControl` does not inject
  * `invalid` itself because its child may be a native element, which would print it
  * into the DOM as an unknown attribute.
+ *
+ * ## Clearing a picker: `null`, unless the picker is told otherwise
+ *
+ * Nothing here touches a value. `FormField` is `Controller`, so what a control hands
+ * `field.onChange` is exactly what lands in the form — and what the entity pickers
+ * hand it on a clear is `null`: `EntityCombobox`'s "×", `InlineEntityCombobox`'s "×"
+ * and its emptied text. (`MultiEntityCombobox` and `MultiSelect` clear to `[]`.)
+ *
+ * A zod schema that spells "no choice" as `""` (`z.string()`, or `z.literal("")` in a
+ * union) then fails on the `null`. Say so on the PICKER, not here:
+ *
+ * ```tsx
+ * <EntityCombobox clearValue="" value={field.value} onChange={field.onChange} … />
+ * ```
+ *
+ * `clearValue` also types `onChange` (`(v: V | "") => void` rather than
+ * `V | null`) and reads `""` back as "nothing selected", so an initial `defaultValues`
+ * of `""` shows the placeholder rather than an unresolvable id. The adapter does not
+ * coerce because it cannot see the schema: mapping `null` to `""` for every field
+ * would break every schema that wants `null` (`z.string().nullable()`), which is the
+ * pickers' default for a reason — it is the one value no option can have.
  */
 import {
   Children,

package/src/search/command-palette.tsx

@@ -1,9 +1,11 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { Search } from "lucide-react";
 import { cn } from "../lib/cn";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
+import { useFocusTrap } from "../hooks/use-focus-trap";
+import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useKitLabels } from "../i18n/kit-labels";
 
 export interface CommandItem {
@@ -42,6 +44,11 @@ export interface CommandPaletteLabels {
    * `CommandPaletteLabels` keeps compiling; the default always carries it.
    */
   dialog?: string;
+  /**
+   * Shown in place of the results when the `search` provider throws or its promise
+   * rejects. Optional for the same reason as `dialog`; the default always carries it.
+   */
+  error?: string;
 }
 
 export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
@@ -49,6 +56,7 @@ export const DEFAULT_COMMAND_PALETTE_LABELS: CommandPaletteLabels = {
   empty: "No results",
   loading: "Searching…",
   dialog: "Search",
+  error: "Search failed. Try again.",
 };
 
 /** The defaults minus `dialog`, so a resolved `dialog` means someone SUPPLIED one —
@@ -124,7 +132,16 @@ export function CommandPalette({
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<CommandItem[]>([]);
   const [loading, setLoading] = useState(false);
+  const [failed, setFailed] = useState(false);
   const [active, setActive] = useState(0);
+  // Per instance: these were the literal "command-palette-list" / "command-item-<id>",
+  // so two palettes on one page (an app-wide one and a scoped one) pointed each
+  // other's `aria-controls` and `aria-activedescendant` at the wrong list.
+  const uid = useId();
+  const listId = `${uid}-list`;
+  const itemId = (id: string) => `${uid}-item-${id}`;
+  const groupId = (index: number) => `${uid}-group-${index}`;
+  const dialogRef = useRef<HTMLDivElement>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const listRef = useRef<HTMLUListElement>(null);
   const searchRef = useRef(search);
@@ -137,13 +154,17 @@ export function CommandPalette({
   // mounting-while-open is what lets it sit here.
   useOverlayHistory(open, onClose);
 
-  // Reset + focus when opened.
+  // A modal like any other: Tab stays inside, the page behind does not scroll, and
+  // focus goes back to whatever opened it — the palette used to drop it on <body>.
+  // Initial focus is the field, not the container: typing is the only reason to open it.
+  useFocusTrap(dialogRef, { active: open, initialFocus: () => inputRef.current });
+  useBodyScrollLock(open);
+
+  // Reset when opened.
   useEffect(() => {
     if (!open) return;
     setQuery("");
     setActive(0);
-    const id = requestAnimationFrame(() => inputRef.current?.focus());
-    return () => cancelAnimationFrame(id);
   }, [open]);
 
   // Debounced, race-safe search.
@@ -156,8 +177,18 @@ export function CommandPalette({
         const r = await Promise.resolve(searchRef.current(query));
         if (reqId.current === id) {
           setResults(r);
+          setFailed(false);
+          setActive(0);
+        }
+      } catch (err) {
+        // There was no catch: the previous query's results stayed on screen as if they
+        // answered this one, and the rejection went unhandled. Clear them and say so.
+        if (reqId.current === id) {
+          setResults([]);
+          setFailed(true);
           setActive(0);
         }
+        console.error("CommandPalette: search failed", err);
       } finally {
         if (reqId.current === id) setLoading(false);
       }
@@ -202,7 +233,13 @@ export function CommandPalette({
     } else if (e.key === "Enter") {
       e.preventDefault();
       choose(flat[active]);
-    } else if (e.key === "Escape") {
+    }
+  };
+
+  // Escape on the whole dialog, not only the field: once Tab has moved focus to a row
+  // (or a footer control), Escape used to do nothing at all.
+  const onDialogKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === "Escape") {
       e.preventDefault();
       onClose();
     }
@@ -224,11 +261,17 @@ export function CommandPalette({
         if (e.target === e.currentTarget) onClose();
       }}
     >
+      {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- Escape from anywhere in the dialog */}
       <div
+        ref={dialogRef}
         role="dialog"
         aria-modal="true"
         aria-label={dialogName}
-        className="flex max-h-[70vh] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-2xl"
+        // The trap's fallback target when the field is not there to take focus.
+        tabIndex={-1}
+        // Escape bubbling up from anything inside — a dialog is where it belongs.
+        onKeyDown={onDialogKeyDown}
+        className="flex max-h-[70vh] w-full max-w-xl flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--bg-surface)] shadow-2xl outline-none"
       >
         <div className="flex items-center gap-2 border-b border-[var(--border)] px-3">
           <Search className="size-4 shrink-0 text-[var(--text-placeholder)]" />
@@ -236,8 +279,8 @@ export function CommandPalette({
             ref={inputRef}
             role="combobox"
             aria-expanded
-            aria-controls="command-palette-list"
-            aria-activedescendant={flat[active] ? `command-item-${flat[active].id}` : undefined}
+            aria-controls={listId}
+            aria-activedescendant={flat[active] ? itemId(flat[active].id) : undefined}
             value={query}
             onChange={(e) => setQuery(e.target.value)}
             onKeyDown={onKeyDown}
@@ -247,16 +290,31 @@ export function CommandPalette({
           {loading && <span className="shrink-0 text-[11px] text-[var(--text-placeholder)]">{l.loading}</span>}
         </div>
 
-        <ul id="command-palette-list" ref={listRef} role="listbox" className="min-h-0 flex-1 overflow-y-auto py-1">
-          {flat.length === 0 && !loading && (
-            <li className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">{l.empty}</li>
-          )}
-          {groups.map(({ group, items }) => (
-            <li key={group}>
-              <div className="px-3 pb-0.5 pt-2 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+        {/* The status lines sit outside the listbox: a listbox owns options and groups,
+            and "No results" is neither. */}
+        {failed && !loading && (
+          <div role="alert" className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">
+            {l.error ?? DEFAULT_COMMAND_PALETTE_LABELS.error}
+          </div>
+        )}
+        {!failed && flat.length === 0 && !loading && (
+          <div className="px-3 py-6 text-center text-sm text-[var(--text-muted)]">{l.empty}</div>
+        )}
+        {/* Listbox grouping: each group is a `role="group"` named by its heading, and
+            the list markup in between is presentational so the listbox's children are
+            groups and options only — as a plain <li>/<ul> tree a reader announced
+            "list, 2 items" between options and never tied the heading to its rows. */}
+        <ul id={listId} ref={listRef} role="listbox" aria-label={dialogName} className="min-h-0 flex-1 overflow-y-auto py-1">
+          {groups.map(({ group, items }, groupIndex) => (
+            <li key={group} role="presentation">
+              <div
+                id={groupId(groupIndex)}
+                role="presentation"
+                className="px-3 pb-0.5 pt-2 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]"
+              >
                 {group}
               </div>
-              <ul>
+              <ul role="group" aria-labelledby={groupId(groupIndex)}>
                 {items.map((item) => {
                   flatIndex += 1;
                   const idx = flatIndex;
@@ -266,13 +324,13 @@ export function CommandPalette({
                   // `role="option"` on an <a href> is fine: the browser's middle-click
                   // behaviour keys off the element, not the ARIA role.
                   const shared = {
-                    id: `command-item-${item.id}`,
+                    id: itemId(item.id),
                     role: "option" as const,
                     "aria-selected": isActive,
                     "data-index": idx,
                     onMouseMove: () => setActive(idx),
                     className: cn(
-                      "flex w-full items-center gap-2.5 px-3 py-2 text-left text-sm",
+                      "flex w-full items-center gap-2.5 px-3 py-2 text-start text-sm",
                       isActive
                         ? "bg-[var(--bg-active)] text-[var(--text-primary)]"
                         : "text-[var(--text-secondary)]",
@@ -292,7 +350,7 @@ export function CommandPalette({
                     </>
                   );
                   return (
-                    <li key={item.id}>
+                    <li key={item.id} role="presentation">
                       {item.href ? (
                         <a
                           {...shared}