@hilum/ui 3.8.6 → 3.10.0

package/src/components/color-picker.tsx

@@ -460,7 +460,7 @@ const PANEL_WIDTH = 280;
 const SQUARE_HEIGHT = 156;
 const CHECKER_BG: CSSProperties = {
   backgroundImage:
-    "conic-gradient(var(--checker-a) 0 25%, var(--checker-b) 0 50%, var(--checker-a) 0 75%, var(--checker-b) 0)",
+    "conic-gradient(var(--checker-a, #ffffff) 0 25%, var(--checker-b, #e5e5e5) 0 50%, var(--checker-a, #ffffff) 0 75%, var(--checker-b, #e5e5e5) 0)",
   backgroundSize: "8px 8px",
 };
 
@@ -553,10 +553,12 @@ function SaturationSquare({ h, s, v, onChange }: SaturationSquareProps) {
   const thumbColor = `rgb(${Math.round(r)}, ${Math.round(g)}, ${Math.round(b)})`;
 
   return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- 2D saturation/brightness area: role=application + tabIndex with full arrow-key support (onKeyDown); no native 2D control exists
     <div
       ref={ref}
       role="application"
       aria-label="Saturation and brightness"
+      // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- keyboard-operable 2D picker (see above)
       tabIndex={0}
       onFocus={(e) => {
         if (e.currentTarget.matches(":focus-visible")) setFocused(true);
@@ -576,7 +578,7 @@ function SaturationSquare({ h, s, v, onChange }: SaturationSquareProps) {
       className={cn("relative w-full select-none touch-none cursor-none outline-none", shape.bg)}
       style={{
         height: SQUARE_HEIGHT,
-        boxShadow: focused ? "0 0 0 2px #6B97FF" : undefined,
+        boxShadow: focused ? "0 0 0 2px var(--ring)" : undefined,
       }}
     >
       <div
@@ -639,7 +641,8 @@ function HueSlider({ h, onChange }: { h: number; onChange: (h: number) => void }
       showValue={false}
       hideFill
       thumbColor={hueColor}
-      thumbBorderColor="rgba(255,255,255,0.9)"
+      thumbBorderColor="rgba(255,255,255,0.95)"
+      trackSize={12}
       trackStyle={{
         background:
           "linear-gradient(to right, hsl(0,100%,50%), hsl(60,100%,50%), hsl(120,100%,50%), hsl(180,100%,50%), hsl(240,100%,50%), hsl(300,100%,50%), hsl(360,100%,50%))",
@@ -682,11 +685,11 @@ function AlphaSlider({
       showValue={false}
       hideFill
       thumbColor={solidColor}
-      thumbBorderColor="rgba(255,255,255,0.9)"
+      thumbBorderColor="rgba(255,255,255,0.95)"
+      trackSize={12}
       trackStyle={{
-        backgroundImage: `linear-gradient(to right, ${transparentColor} 0%, ${solidColor} 98%), conic-gradient(var(--checker-a) 0 25%, var(--checker-b) 0 50%, var(--checker-a) 0 75%, var(--checker-b) 0)`,
+        backgroundImage: `linear-gradient(to right, ${transparentColor} 0%, ${solidColor} 98%), conic-gradient(var(--checker-a, #ffffff) 0 25%, var(--checker-b, #e5e5e5) 0 50%, var(--checker-a, #ffffff) 0 75%, var(--checker-b, #e5e5e5) 0)`,
         backgroundSize: "100% 100%, 8px 8px",
-        borderWidth: 0,
       }}
       aria-label="Alpha"
     />
@@ -790,7 +793,6 @@ function FormatDropdown({
   };
   const triggerRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
-  const shape = useShape();
   const portalContainer = useContext(ColorPickerPortalContainerContext);
   const [pos, setPos] = useState<
     | { mode: "fixed"; top: number; left: number; width: number }
@@ -860,15 +862,15 @@ function FormatDropdown({
         aria-haspopup="menu"
         aria-expanded={open}
         className={cn(
-          "flex items-center justify-between gap-2 h-9 px-3 text-[13px] bg-transparent hover:bg-hover hover:text-foreground transition-colors duration-80 outline-none focus-visible:ring-1 focus-visible:ring-[#6B97FF] cursor-pointer",
-          open ? "bg-active text-foreground" : "text-muted-foreground active:bg-active",
-          shape.input,
+          "flex items-center justify-between gap-1.5 h-6 min-w-[4.5rem] pl-2 pr-1.5 text-[12px] rounded-[5px] border border-border bg-background text-foreground",
+          "hover:border-border-strong transition-colors duration-80 outline-none focus-visible:ring-2 focus-visible:ring-ring cursor-pointer",
+          open && "border-border-strong bg-active",
         )}
         style={{ fontVariationSettings: fontWeights.medium }}
       >
         <span>{FORMAT_LABELS[value]}</span>
         <ChevronDownIcon
-          size={14}
+          size={12}
           strokeWidth={1.5}
           className={cn(
             "text-muted-foreground transition-transform duration-150",
@@ -976,7 +978,6 @@ const ColorInput = forwardRef<HTMLInputElement, ColorInputProps>(
       scrubbing: boolean;
       pointerId: number;
     } | null>(null);
-    const shape = useShape();
 
     useEffect(() => {
       if (!interactingRef.current) setDraft(value);
@@ -1075,15 +1076,16 @@ const ColorInput = forwardRef<HTMLInputElement, ColorInputProps>(
         onPointerUp={onWrapperPointerUp}
         onPointerCancel={onWrapperPointerUp}
         className={cn(
-          "flex items-center h-9 px-2 bg-transparent hover:bg-hover active:bg-active transition-colors duration-80 focus-within:ring-1 focus-within:ring-[#6B97FF] select-none",
-          shape.input,
+          "flex h-6 min-w-0 items-center rounded-[5px] border border-border bg-background px-1.5 text-[12px] tabular-nums select-none",
+          "transition-[border-color,box-shadow] duration-80 hover:border-border-strong",
+          "focus-within:border-ring focus-within:ring-2 focus-within:ring-ring/35",
           scrubbable && !editing && "cursor-ew-resize",
           className,
         )}
         style={{ width }}
       >
         {prefix && (
-          <span className="text-[12px] text-muted-foreground mr-1 select-none">{prefix}</span>
+          <span className="text-[11px] text-muted-foreground mr-1 select-none">{prefix}</span>
         )}
         <input
           ref={setInputRef}
@@ -1148,7 +1150,6 @@ interface EyeDropperGlobal {
 
 function EyeDropperButton({ onPick }: { onPick: (hex: string) => void }) {
   const [supported, setSupported] = useState(false);
-  const shape = useShape();
   const PipetteIcon = useIcon("pipette");
 
   useEffect(() => {
@@ -1174,11 +1175,10 @@ function EyeDropperButton({ onPick }: { onPick: (hex: string) => void }) {
       onClick={handleClick}
       aria-label="Pick color from screen"
       className={cn(
-        "flex items-center justify-center h-9 px-3 text-muted-foreground bg-transparent hover:bg-hover hover:text-foreground active:bg-active transition-colors duration-80 outline-none focus-visible:ring-1 focus-visible:ring-[#6B97FF] cursor-pointer",
-        shape.input,
+        "flex size-6 shrink-0 items-center justify-center rounded-[5px] text-muted-foreground bg-transparent hover:bg-hover hover:text-foreground active:bg-active transition-colors duration-80 outline-none focus-visible:ring-2 focus-visible:ring-ring cursor-pointer",
       )}
     >
-      <PipetteIcon size={16} strokeWidth={1.5} />
+      <PipetteIcon size={14} strokeWidth={1.5} />
     </button>
   );
 }
@@ -1221,7 +1221,7 @@ const ColorSwatch = forwardRef<HTMLButtonElement, ColorSwatchProps>(
     const shape = useShape();
     const [hovered, setHovered] = useState(false);
     const ring = selected
-      ? "inset 0 0 0 1px rgba(127,127,127,0.25), 0 0 0 2px var(--background), 0 0 0 4px #6B97FF"
+      ? "inset 0 0 0 1px rgba(127,127,127,0.25), 0 0 0 2px var(--background), 0 0 0 4px var(--ring)"
       : hovered
         ? "inset 0 0 0 1px rgba(127,127,127,0.25), 0 0 0 2px var(--background), 0 0 0 4px rgba(127,127,127,0.4)"
         : "inset 0 0 0 1px rgba(127,127,127,0.25)";
@@ -1278,7 +1278,8 @@ function SwatchStrip({
   }, [current]);
 
   return (
-    <div className="flex flex-wrap gap-2">
+    // Fixed 8-column grid (20px swatches) so rows never end in a lone orphan.
+    <div className="grid grid-cols-[repeat(8,20px)] justify-between gap-y-2 pt-1">
       {swatches.map((sw, i) => {
         const parsed = parseColor(sw);
         const normalized = parsed
@@ -1289,7 +1290,7 @@ function SwatchStrip({
           <ColorSwatch
             key={`${sw}-${i}`}
             color={sw}
-            size={28}
+            size={20}
             selected={isSelected}
             onClick={() => onPick(sw)}
           />
@@ -1319,6 +1320,7 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
       hideEyedropper,
       formatOpen,
       defaultFormatOpen,
+      disabled = false,
       className,
       ...props
     },
@@ -1456,10 +1458,15 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
         <div
           ref={ref}
           aria-label={ariaLabel}
+          aria-disabled={disabled || undefined}
+          data-disabled={disabled ? "" : undefined}
+          // `inert` removes the whole panel from pointer + keyboard interaction.
+          inert={disabled || undefined}
           className={cn(
             "flex flex-col gap-2 p-3",
             surfaceClasses(pickerLevel, 1),
             shape.container,
+            disabled && "pointer-events-none select-none opacity-50",
             className,
           )}
           style={{ width: PANEL_WIDTH }}
@@ -1472,7 +1479,9 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
             onChange={(s, v) => updateHsv({ s, v })}
           />
 
-          <div className="flex flex-col [&>*]:mb-0 [&>*+*]:-mt-px">
+          {/* Hue + alpha strips: slider boxes carry 8px hit slop top/bottom; the
+              negative margins collapse that so the strips sit 12px apart. */}
+          <div className="-my-2 flex flex-col [&>*]:mb-0 [&>*+*]:-mt-3">
             <HueSlider
               h={hsv.h}
               onChange={(h) => {
@@ -1490,7 +1499,7 @@ const ColorPicker = forwardRef<HTMLDivElement, ColorPickerProps>(
             />
           </div>
 
-          <div className="grid grid-cols-2 gap-2">
+          <div className="flex items-center justify-between gap-2">
             <FormatDropdown
               value={currentFormat}
               onChange={handleFormatChange}
@@ -1620,7 +1629,7 @@ function ColorInputsRow({
   if (format === "hex") {
     const hexNoHash = parsed.hex.replace(/^#/, "").toUpperCase();
     return (
-      <div className="grid grid-cols-2 gap-2">
+      <div className="grid grid-cols-[minmax(0,1fr)_4rem] gap-1.5">
         <ChannelTooltip label="Hex">
           <ColorInput
             value={hexNoHash}
@@ -1925,11 +1934,14 @@ const ColorPickerPopover = forwardRef<HTMLDivElement, ColorPickerPopoverProps>(
           ref={triggerRef}
           type="button"
           onClick={() => setOpen((o) => !o)}
+          disabled={pickerProps.disabled}
           aria-haspopup="dialog"
           aria-expanded={open}
           className={cn(
-            "flex items-center gap-2 h-9 px-2 border border-border bg-transparent hover:bg-hover transition-colors duration-80 outline-none focus-visible:ring-1 focus-visible:ring-[#6B97FF] cursor-pointer",
+            "flex items-center gap-2 h-9 px-2 border border-border bg-transparent hover:bg-hover hover:border-border-strong transition-colors duration-80 outline-none focus-visible:ring-2 focus-visible:ring-ring cursor-pointer",
+            "disabled:pointer-events-none disabled:opacity-50",
             shape.input,
+            "compact:h-6 compact:gap-1.5 compact:px-1 compact:rounded-[5px]",
             triggerClassName,
           )}
           style={{ fontVariationSettings: fontWeights.medium }}

package/src/components/combobox.tsx

@@ -13,7 +13,15 @@ export interface ComboboxOption {
   avatar?: string;
 }
 
-interface ComboboxProps {
+/** ARIA attributes the combobox manages itself and therefore doesn't accept. */
+type ManagedAria =
+  | "aria-expanded"
+  | "aria-controls"
+  | "aria-activedescendant"
+  | "aria-autocomplete"
+  | "aria-haspopup";
+
+interface ComboboxProps extends Omit<React.AriaAttributes, ManagedAria> {
   options: ComboboxOption[];
   value?: string;
   onValueChange?: (value: string) => void;
@@ -21,17 +29,31 @@ interface ComboboxProps {
   searchPlaceholder?: string;
   emptyText?: string;
   className?: string;
+  /** id of the text input (e.g. for a `<label htmlFor>`). */
+  id?: string;
+  /** Form field name. Submits the selected option's `value` via a hidden input. */
+  name?: string;
+  disabled?: boolean;
+  onBlur?: React.FocusEventHandler<HTMLInputElement>;
 }
 
-function Combobox({
-  options,
-  value,
-  onValueChange,
-  placeholder = "Select...",
-  searchPlaceholder = "Search...",
-  emptyText = "No results found.",
-  className,
-}: ComboboxProps) {
+const Combobox = React.forwardRef<HTMLInputElement, ComboboxProps>(function Combobox(
+  {
+    options,
+    value,
+    onValueChange,
+    placeholder = "Select...",
+    searchPlaceholder = "Search...",
+    emptyText = "No results found.",
+    className,
+    id,
+    name,
+    disabled = false,
+    onBlur,
+    ...ariaProps
+  },
+  ref,
+) {
   const shape = useShape();
   const [open, setOpen] = React.useState(false);
   const [query, setQuery] = React.useState("");
@@ -39,6 +61,7 @@ function Combobox({
   const containerRef = React.useRef<HTMLDivElement>(null);
   const inputRef = React.useRef<HTMLInputElement>(null);
   const listboxId = React.useId();
+  React.useImperativeHandle(ref, () => inputRef.current as HTMLInputElement, []);
 
   const selectedOption = options.find((o) => o.value === value);
 
@@ -56,6 +79,22 @@ function Combobox({
     setActiveIndex(-1);
   }, [filtered.length, open]);
 
+  // Keep the keyboard-active option visible in the scrollable list.
+  React.useEffect(() => {
+    if (!open || activeIndex < 0) return;
+    document
+      .getElementById(`${listboxId}-option-${activeIndex}`)
+      ?.scrollIntoView?.({ block: "nearest" });
+  }, [open, activeIndex, listboxId]);
+
+  // Close when disabled while open.
+  React.useEffect(() => {
+    if (disabled) {
+      setOpen(false);
+      setQuery("");
+    }
+  }, [disabled]);
+
   // Close on outside click
   React.useEffect(() => {
     function onMouseDown(e: MouseEvent) {
@@ -123,9 +162,12 @@ function Combobox({
           />
         )}
         <input
+          {...ariaProps}
           ref={inputRef}
+          id={id}
           type="text"
           role="combobox"
+          disabled={disabled}
           aria-expanded={open}
           aria-haspopup="listbox"
           aria-controls={open ? listboxId : undefined}
@@ -137,7 +179,7 @@ function Combobox({
             "flex h-10 w-full border border-border bg-background pr-10 body text-foreground",
             shape.input,
             "placeholder:text-muted-foreground",
-            "focus-visible:border-border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/30",
+            "focus-visible:border-border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
             "disabled:cursor-not-allowed disabled:opacity-50",
             selectedOption?.avatar && !open
               ? "pl-8"
@@ -155,11 +197,14 @@ function Combobox({
             setOpen(true);
             setQuery("");
           }}
+          onBlur={onBlur}
           onKeyDown={handleInputKeyDown}
         />
+        {name !== undefined && <input type="hidden" name={name} value={value ?? ""} />}
         <button
           type="button"
           tabIndex={-1}
+          disabled={disabled}
           aria-label={open ? "Close" : "Open"}
           className="absolute inset-y-0 right-0 flex w-10 items-center justify-center text-muted-foreground hover:text-muted-foreground transition-colors"
           onClick={() => {
@@ -204,6 +249,7 @@ function Combobox({
                   const isSelected = option.value === value;
                   const isActive = idx === activeIndex;
                   return (
+                    // eslint-disable-next-line jsx-a11y/click-events-have-key-events -- aria-activedescendant listbox: keyboard selection is handled by the input (Arrow/Enter), options are pointer targets only
                     <li
                       key={option.value}
                       id={`${listboxId}-option-${idx}`}
@@ -267,8 +313,9 @@ function Combobox({
       )}
     </div>
   );
-}
+});
 
 Combobox.displayName = "Combobox";
 
 export { Combobox };
+export type { ComboboxProps };

package/src/components/command-palette.tsx

@@ -2,7 +2,8 @@
 
 import * as React from "react";
 import { Search, ArrowRight } from "lucide-react";
-import { Dialog, DialogContent } from "./dialog";
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from "./dialog";
+import { cn } from "../lib/utils";
 
 export interface CommandPaletteItem {
   id?: string | number;
@@ -20,6 +21,16 @@ interface CommandPaletteProps {
   items: CommandPaletteItem[];
   placeholder?: string;
   emptyText?: string;
+  /** Accessible name of the dialog (visually hidden). */
+  title?: string;
+  /** Accessible description of the dialog (visually hidden). */
+  description?: string;
+  /**
+   * Called for items with an `href` (instead of a full page load via
+   * `window.location`). Pass your router's navigate function for client-side
+   * routing. As before, an item's `href` takes precedence over its `onSelect`.
+   */
+  onNavigate?: (href: string) => void;
 }
 
 function CommandPalette({
@@ -28,15 +39,23 @@ function CommandPalette({
   items,
   placeholder = "Search...",
   emptyText = "No results found.",
+  title = "Command palette",
+  description = "Search for a command or page. Use the arrow keys to move and Enter to select.",
+  onNavigate,
 }: CommandPaletteProps) {
   const [query, setQuery] = React.useState("");
+  const [activeIndex, setActiveIndex] = React.useState(0);
   const inputRef = React.useRef<HTMLInputElement>(null);
+  const listRef = React.useRef<HTMLDivElement>(null);
+  const listboxId = React.useId();
+  const optionId = (index: number) => `${listboxId}-option-${index}`;
 
   // Focus input when opened
   React.useEffect(() => {
     if (open) {
       setTimeout(() => inputRef.current?.focus(), 50);
       setQuery("");
+      setActiveIndex(0);
     }
   }, [open]);
 
@@ -50,42 +69,88 @@ function CommandPalette({
             item.category?.toLowerCase().includes(query.toLowerCase()),
         );
 
-  // Group by category
+  // Group by category. `ordered` is the visual (grouped) order, which is the
+  // order arrow keys walk through and what activeIndex indexes into.
   const grouped = filtered.reduce<Record<string, CommandPaletteItem[]>>((acc, item) => {
     const cat = item.category ?? "";
     if (!acc[cat]) acc[cat] = [];
     acc[cat].push(item);
     return acc;
   }, {});
-
   const categories = Object.keys(grouped);
+  const ordered = categories.flatMap((cat) => grouped[cat]);
+  const safeActive = ordered.length === 0 ? -1 : Math.min(activeIndex, ordered.length - 1);
+
+  // Keep the active option in view while arrowing through a long list.
+  React.useEffect(() => {
+    if (safeActive < 0) return;
+    const el = listRef.current?.querySelector<HTMLElement>(`[data-index="${safeActive}"]`);
+    el?.scrollIntoView?.({ block: "nearest" });
+  }, [safeActive]);
 
   function handleSelect(item: CommandPaletteItem) {
     if (item.href) {
-      window.location.href = item.href;
+      if (onNavigate) onNavigate(item.href);
+      else if (typeof window !== "undefined") window.location.assign(item.href);
     } else {
       item.onSelect?.();
     }
     onClose();
   }
 
+  function handleKeyDown(e: React.KeyboardEvent<HTMLInputElement>) {
+    if (e.key === "Escape") {
+      onClose();
+      return;
+    }
+    if (ordered.length === 0) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActiveIndex((safeActive + 1) % ordered.length);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex((safeActive - 1 + ordered.length) % ordered.length);
+    } else if (e.key === "Home" && e.ctrlKey) {
+      e.preventDefault();
+      setActiveIndex(0);
+    } else if (e.key === "End" && e.ctrlKey) {
+      e.preventDefault();
+      setActiveIndex(ordered.length - 1);
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      const item = ordered[safeActive];
+      if (item) handleSelect(item);
+    }
+  }
+
+  let runningIndex = 0;
+
   return (
     <Dialog open={open} onOpenChange={(v) => !v && onClose()}>
       <DialogContent className="gap-0 overflow-hidden p-0 sm:max-w-xl">
+        <DialogTitle className="sr-only">{title}</DialogTitle>
+        <DialogDescription className="sr-only">{description}</DialogDescription>
         {/* Search input */}
         <div className="flex items-center gap-3 border-b border-border px-4">
-          <Search size={16} className="shrink-0 text-muted-foreground" />
+          <Search size={16} className="shrink-0 text-muted-foreground" aria-hidden="true" />
           <input
             ref={inputRef}
             type="text"
+            role="combobox"
+            aria-label={title}
+            aria-expanded={ordered.length > 0}
+            aria-controls={listboxId}
+            aria-autocomplete="list"
+            aria-activedescendant={safeActive >= 0 ? optionId(safeActive) : undefined}
+            autoComplete="off"
             className="h-12 flex-1 bg-transparent body text-foreground placeholder:text-muted-foreground focus:outline-none"
             placeholder={placeholder}
             value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            onKeyDown={(e) => {
-              if (e.key === "Escape") onClose();
-              if (e.key === "Enter" && filtered.length > 0) handleSelect(filtered[0]);
+            onChange={(e) => {
+              setQuery(e.target.value);
+              setActiveIndex(0);
             }}
+            onKeyDown={handleKeyDown}
           />
           <kbd className="hidden items-center gap-0.5 sm:flex">
             <span className="caption-xs font-medium text-muted-foreground rounded border border-border px-1.5 py-0.5">
@@ -95,40 +160,82 @@ function CommandPalette({
         </div>
 
         {/* Results */}
-        <div className="max-h-80 overflow-y-auto">
-          {filtered.length === 0 ? (
-            <p className="px-4 py-8 text-center body text-muted-foreground">{emptyText}</p>
+        <div ref={listRef} className="max-h-80 overflow-y-auto">
+          {ordered.length === 0 ? (
+            <p role="status" className="px-4 py-8 text-center body text-muted-foreground">
+              {emptyText}
+            </p>
           ) : (
-            <ul role="list" className="py-2">
-              {categories.map((cat) => (
-                <li key={cat}>
-                  {cat && <p className="label px-4 py-2 text-muted-foreground">{cat}</p>}
-                  {grouped[cat].map((item, i) => (
-                    <button
-                      key={item.id ?? i}
-                      type="button"
-                      className="flex min-h-10 w-full items-center gap-3 px-4 py-2.5 body text-left transition-colors hover:bg-muted focus-visible:bg-muted focus-visible:outline-none"
-                      onClick={() => handleSelect(item)}
-                    >
-                      {item.icon && (
-                        <span className="flex size-8 shrink-0 items-center justify-center rounded-lg border border-border bg-card text-muted-foreground">
-                          {item.icon}
-                        </span>
-                      )}
-                      <div className="min-w-0 flex-1">
-                        <p className="font-medium text-foreground truncate">{item.label}</p>
-                        {item.description && (
-                          <p className="caption text-muted-foreground truncate">
-                            {item.description}
-                          </p>
-                        )}
-                      </div>
-                      <ArrowRight size={13} className="shrink-0 text-muted-foreground" />
-                    </button>
-                  ))}
-                </li>
-              ))}
-            </ul>
+            <div id={listboxId} role="listbox" aria-label={title} className="py-2">
+              {categories.map((cat) => {
+                const headingId = `${listboxId}-group-${cat}`;
+                return (
+                  <div
+                    key={cat}
+                    role="group"
+                    {...(cat ? { "aria-labelledby": headingId } : {})}
+                  >
+                    {cat && (
+                      <p
+                        id={headingId}
+                        role="presentation"
+                        className="label px-4 py-2 text-muted-foreground"
+                      >
+                        {cat}
+                      </p>
+                    )}
+                    {grouped[cat].map((item, i) => {
+                      const index = runningIndex++;
+                      const isActive = index === safeActive;
+                      return (
+                        // Options aren't focusable: focus stays in the input and
+                        // the active option is conveyed via aria-activedescendant.
+                        // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/interactive-supports-focus -- aria-activedescendant pattern: keyboard selection handled by the input (Arrow/Enter)
+                        <div
+                          key={item.id ?? `${cat}-${i}`}
+                          id={optionId(index)}
+                          role="option"
+                          aria-selected={isActive}
+                          data-index={index}
+                          data-active={isActive || undefined}
+                          className={cn(
+                            "flex min-h-10 w-full cursor-pointer items-center gap-3 px-4 py-2.5 body text-left transition-colors",
+                            isActive ? "bg-muted" : "hover:bg-muted",
+                          )}
+                          onMouseDown={(e) => e.preventDefault()}
+                          onMouseMove={() => {
+                            if (!isActive) setActiveIndex(index);
+                          }}
+                          onClick={() => handleSelect(item)}
+                        >
+                          {item.icon && (
+                            <span
+                              aria-hidden="true"
+                              className="flex size-8 shrink-0 items-center justify-center rounded-lg border border-border bg-card text-muted-foreground"
+                            >
+                              {item.icon}
+                            </span>
+                          )}
+                          <div className="min-w-0 flex-1">
+                            <p className="font-medium text-foreground truncate">{item.label}</p>
+                            {item.description && (
+                              <p className="caption text-muted-foreground truncate">
+                                {item.description}
+                              </p>
+                            )}
+                          </div>
+                          <ArrowRight
+                            size={13}
+                            className="shrink-0 text-muted-foreground"
+                            aria-hidden="true"
+                          />
+                        </div>
+                      );
+                    })}
+                  </div>
+                );
+              })}
+            </div>
           )}
         </div>
       </DialogContent>
@@ -139,3 +246,4 @@ function CommandPalette({
 CommandPalette.displayName = "CommandPalette";
 
 export { CommandPalette };
+export type { CommandPaletteProps };