@sixthshift/design-system 0.2.1 → 0.3.0

package/src/components/Modal/components/ModalHeader.tsx

@@ -5,13 +5,25 @@ import { ModalContext } from "./ModalContext";
 
 export type ModalHeaderProps = React.HTMLAttributes<HTMLDivElement>;
 
-export const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(({ className, children, ...props }, ref) => {
+export const ModalHeader = React.forwardRef<HTMLDivElement, ModalHeaderProps>(({ className, children, id, ...props }, ref) => {
   const context = React.useContext(ModalContext);
   const closable = context?.closable;
   const onClose = context?.onClose;
+  const registerTitle = context?.registerTitle;
+
+  // Tell the dialog it has a title to point `aria-labelledby` at, and take that
+  // back on unmount so a header removed at runtime doesn't leave a dangling
+  // reference behind. A caller-supplied `id` wins over the generated one, which
+  // also means the dialog can no longer find it — say so rather than pointing
+  // at an id that isn't in the DOM, and let the caller label the Modal itself.
+  const ownsTitleId = id === undefined;
+  React.useEffect(() => {
+    registerTitle?.(ownsTitleId);
+    return () => registerTitle?.(false);
+  }, [registerTitle, ownsTitleId]);
 
   return (
-    <div ref={ref} className={cn("flex flex-col space-y-1.5 p-6", closable && "pr-12", className)} {...props}>
+    <div ref={ref} id={id ?? context?.titleId} className={cn("flex flex-col space-y-1.5 p-6", closable && "pr-12", className)} {...props}>
       {children}
       {closable && (
         <button

package/src/components/NavBottom/NavBottom.tsx

@@ -1,5 +1,6 @@
 import { useComponents } from "@sixthshift/design-system/components";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 import type { NavItem as NavItemType, NavSection, RenderLinkFn } from "../NavSide";
 
 export type NavBottomProps = {
@@ -15,14 +16,14 @@ export type NavBottomProps = {
   className?: string;
 };
 
-export const NavBottom = ({ sections, isActive, renderLink, maxItems = 5, className }: NavBottomProps) => {
+export const NavBottom = React.forwardRef<HTMLElement, NavBottomProps>(({ sections, isActive, renderLink, maxItems = 5, className }, ref) => {
   const { Link } = useComponents();
   const linkRenderer: RenderLinkFn = renderLink ?? (({ to, ...rest }) => <Link href={to} {...rest} />);
   // Flatten all sections and limit to maxItems
   const items = sections.flatMap((section) => section.items).slice(0, maxItems);
 
   return (
-    <nav className={cn("fixed inset-x-0 bottom-0 z-app-bar bg-bg-brand-strong text-fg-on-brand-strong", className)}>
+    <nav ref={ref} className={cn("fixed inset-x-0 bottom-0 z-app-bar bg-bg-brand-strong text-fg-on-brand-strong", className)}>
       <ul className="flex items-center justify-around">
         {items.map((item) => {
           const Icon = item.icon;
@@ -35,7 +36,7 @@ export const NavBottom = ({ sections, isActive, renderLink, maxItems = 5, classN
                 className: cn(
                   "flex flex-col items-center gap-1 rounded-md px-3 py-2 text-xs",
                   "hover:bg-bg-brand-hovered hover:text-fg-on-brand-hovered",
-                  active && "bg-bg-brand-pressed"
+                  active && "bg-bg-brand-pressed text-fg-on-brand-pressed"
                 ),
                 children: (
                   <>
@@ -50,4 +51,5 @@ export const NavBottom = ({ sections, isActive, renderLink, maxItems = 5, classN
       </ul>
     </nav>
   );
-};
+});
+NavBottom.displayName = "NavBottom";

package/src/components/NavSide/NavItem.tsx

@@ -18,7 +18,7 @@ export const NavItem = ({ item, active, expanded, renderLink }: NavItemProps) =>
         className: cn(
           "flex items-center gap-3 rounded-md px-2 py-2 font-medium text-sm",
           "hover:bg-bg-brand-hovered hover:text-fg-on-brand-hovered",
-          active && "bg-bg-brand-pressed"
+          active && "bg-bg-brand-pressed text-fg-on-brand-pressed"
         ),
         // Only include title when collapsed (for tooltip)
         ...(expanded ? {} : { title: item.label }),

package/src/components/NavSide/NavSide.tsx

@@ -1,5 +1,6 @@
 import { useComponents } from "@sixthshift/design-system/components";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 import { NavItem } from "./NavItem";
 import type { NavItem as NavItemType, NavSection, RenderLinkFn } from "./types";
 
@@ -16,11 +17,11 @@ export type NavSideProps = {
   className?: string;
 };
 
-export const NavSide = ({ sections, expanded = true, isActive, renderLink, className }: NavSideProps) => {
+export const NavSide = React.forwardRef<HTMLElement, NavSideProps>(({ sections, expanded = true, isActive, renderLink, className }, ref) => {
   const { Link } = useComponents();
   const linkRenderer: RenderLinkFn = renderLink ?? (({ to, ...rest }) => <Link href={to} {...rest} />);
   return (
-    <aside className={cn("flex flex-col bg-bg-brand-strong text-fg-on-brand-strong", expanded ? "w-48" : "w-16", className)}>
+    <aside ref={ref} className={cn("flex flex-col bg-bg-brand-strong text-fg-on-brand-strong", expanded ? "w-48" : "w-16", className)}>
       <nav className="flex-1 overflow-y-auto py-3">
         {sections.map((section, sectionIndex) => (
           <div key={section.id}>
@@ -37,4 +38,5 @@ export const NavSide = ({ sections, expanded = true, isActive, renderLink, class
       </nav>
     </aside>
   );
-};
+});
+NavSide.displayName = "NavSide";

package/src/components/Popover/Popover.tsx

@@ -44,6 +44,12 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
 
   const id = useId();
   const contentId = `popover-content-${id}`;
+  // `Popover.Body` is a `role="dialog"`, and a dialog with no accessible name is
+  // announced as just "dialog". There is no title sub-part to read from, so the
+  // trigger — which always has a label, because it is what the user clicked —
+  // names the popover. A caller passing their own `aria-label`/`aria-labelledby`
+  // to `Popover.Body` still wins.
+  const triggerId = `popover-trigger-${id}`;
 
   const contextValue = {
     open,
@@ -56,6 +62,7 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
     getReferenceProps,
     getFloatingProps,
     contentId,
+    triggerId,
   };
 
   return <PopoverContext.Provider value={contextValue}>{children}</PopoverContext.Provider>;

package/src/components/Popover/components/PopoverBody.tsx

@@ -6,7 +6,11 @@ import { usePopoverContext } from "./PopoverContext";
 export type PopoverBodyProps = React.HTMLAttributes<HTMLDivElement>;
 
 export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({ className, children, ...props }, forwardedRef) => {
-  const { open, refs, floatingStyles, getFloatingProps, contentId } = usePopoverContext();
+  const { open, refs, floatingStyles, getFloatingProps, contentId, triggerId } = usePopoverContext();
+
+  // `aria-labelledby` outranks `aria-label` in the name computation, so the
+  // trigger only names the dialog when the caller hasn't named it themselves.
+  const hasOwnLabel = props["aria-label"] !== undefined || props["aria-labelledby"] !== undefined;
 
   if (!open) return null;
 
@@ -20,6 +24,7 @@ export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({
         }}
         id={contentId}
         role="dialog"
+        aria-labelledby={hasOwnLabel ? undefined : triggerId}
         style={floatingStyles}
         className={cn("z-popover rounded-lg border border-border-normal bg-bg-normal p-4 shadow-lg", className)}
         {...getFloatingProps(props)}

package/src/components/Popover/components/PopoverContext.tsx

@@ -11,6 +11,7 @@ export type PopoverContextValue = {
   getReferenceProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   getFloatingProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   contentId: string;
+  triggerId: string;
 };
 
 export const PopoverContext = createContext<PopoverContextValue | null>(null);

package/src/components/Popover/components/PopoverTrigger.tsx

@@ -8,7 +8,7 @@ export type PopoverTriggerProps = React.ButtonHTMLAttributes<HTMLButtonElement>
 };
 
 export const PopoverTrigger = React.forwardRef<HTMLButtonElement, PopoverTriggerProps>(({ asChild = false, children, ...props }, forwardedRef) => {
-  const { refs, getReferenceProps, contentId, open } = usePopoverContext();
+  const { refs, getReferenceProps, contentId, triggerId, open } = usePopoverContext();
   const Comp = asChild ? Slot : "button";
 
   return (
@@ -19,6 +19,7 @@ export const PopoverTrigger = React.forwardRef<HTMLButtonElement, PopoverTrigger
         else if (forwardedRef) forwardedRef.current = node;
       }}
       type={asChild ? undefined : "button"}
+      id={triggerId}
       aria-haspopup="dialog"
       aria-expanded={open}
       aria-controls={open ? contentId : undefined}

package/src/components/ProgressBar/ProgressBar.tsx

@@ -1,5 +1,6 @@
 import { Caption } from "@sixthshift/design-system/caption";
 import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
 
 export type ProgressBarProps = {
   completed: number;
@@ -10,33 +11,36 @@ export type ProgressBarProps = {
   className?: string;
 };
 
-export const ProgressBar = ({ completed, total, showFraction = true, label = "Progress", className }: ProgressBarProps) => {
-  // A caller can hand us anything; the bar must not render an out-of-range
-  // width (a negative `width` is invalid CSS) or report impossible progress.
-  const isMeasurable = total > 0;
-  const clamped = isMeasurable ? Math.min(Math.max(completed, 0), total) : 0;
-  const percentage = isMeasurable ? (clamped / total) * 100 : 0;
+export const ProgressBar = React.forwardRef<HTMLDivElement, ProgressBarProps>(
+  ({ completed, total, showFraction = true, label = "Progress", className }, ref) => {
+    // A caller can hand us anything; the bar must not render an out-of-range
+    // width (a negative `width` is invalid CSS) or report impossible progress.
+    const isMeasurable = total > 0;
+    const clamped = isMeasurable ? Math.min(Math.max(completed, 0), total) : 0;
+    const percentage = isMeasurable ? (clamped / total) * 100 : 0;
 
-  return (
-    <div className={cn("flex items-center gap-3", className)}>
-      <div
-        role="progressbar"
-        aria-label={label}
-        aria-valuemin={0}
-        aria-valuemax={isMeasurable ? total : undefined}
-        // An indeterminate progressbar omits aria-valuenow; with no positive
-        // total there is no meaningful progress to report.
-        aria-valuenow={isMeasurable ? clamped : undefined}
-        aria-valuetext={isMeasurable ? `${clamped} of ${total}` : undefined}
-        className="h-2 flex-1 overflow-hidden rounded-full bg-bg-strong"
-      >
-        <div className="h-full rounded-full bg-fg-success transition-all" style={{ width: `${percentage}%` }} />
+    return (
+      <div ref={ref} className={cn("flex items-center gap-3", className)}>
+        <div
+          role="progressbar"
+          aria-label={label}
+          aria-valuemin={0}
+          aria-valuemax={isMeasurable ? total : undefined}
+          // An indeterminate progressbar omits aria-valuenow; with no positive
+          // total there is no meaningful progress to report.
+          aria-valuenow={isMeasurable ? clamped : undefined}
+          aria-valuetext={isMeasurable ? `${clamped} of ${total}` : undefined}
+          className="h-2 flex-1 overflow-hidden rounded-full bg-bg-strong"
+        >
+          <div className="h-full rounded-full bg-fg-success transition-all" style={{ width: `${percentage}%` }} />
+        </div>
+        {showFraction && (
+          <Caption className="shrink-0">
+            {completed}/{total}
+          </Caption>
+        )}
       </div>
-      {showFraction && (
-        <Caption className="shrink-0">
-          {completed}/{total}
-        </Caption>
-      )}
-    </div>
-  );
-};
+    );
+  }
+);
+ProgressBar.displayName = "ProgressBar";

package/src/components/Select/Select.tsx

@@ -1,7 +1,7 @@
 import { autoUpdate, flip, offset, shift, size, useFloating } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
-import { type HTMLAttributes, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
-import { SelectDropdown } from "./SelectDropdown";
+import { forwardRef, type HTMLAttributes, type ReactElement, type Ref, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { SelectDropdown, selectOptionId } from "./SelectDropdown";
 import { SelectTriggerButton, SelectTriggerSearch } from "./SelectTrigger";
 import { useSelectKeyboard } from "./useSelectKeyboard";
 
@@ -37,7 +37,13 @@ type SelectMultipleProps<T extends string = string> = SelectBaseProps<T> & {
 
 export type SelectProps<T extends string = string> = SelectSingleProps<T> | SelectMultipleProps<T>;
 
-export const Select = <T extends string = string>(props: SelectProps<T>) => {
+/**
+ * `forwardRef` erases the generic, so the implementation takes the ref as an
+ * ordinary second argument and the exported `Select` re-declares the generic
+ * signature over it. Consumers keep `Select<"a" | "b">` inference *and* get a
+ * ref; without the cast they would have to choose.
+ */
+const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(props: SelectProps<T>, rootRef: Ref<HTMLDivElement>) {
   const {
     options,
     onBlur,
@@ -71,6 +77,11 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
   const [searchValue, setSearchValue] = useState("");
   const listboxRef = useRef<HTMLDivElement | null>(null);
+  // Also held in state: the listbox is portalled, and FloatingPortal creates its
+  // container in an effect, so the node lands a commit after `open` flips. A ref
+  // alone is still null when the open effect runs — state re-renders us when the
+  // node actually arrives.
+  const [listboxNode, setListboxNode] = useState<HTMLDivElement | null>(null);
   const inputRef = useRef<HTMLInputElement>(null);
   const optionRefs = useRef<Map<number, HTMLButtonElement>>(new Map());
   const wasOpenRef = useRef(false);
@@ -111,6 +122,11 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     whileElementsMounted: autoUpdate,
   });
 
+  const setListbox = useCallback((node: HTMLDivElement | null) => {
+    listboxRef.current = node;
+    setListboxNode(node);
+  }, []);
+
   const focusTrigger = useCallback(() => {
     (refs.reference.current as HTMLElement | null)?.focus();
   }, [refs.reference]);
@@ -142,18 +158,38 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     [isMultiple, setMultiValue, setSingleValue]
   );
 
+  const handleListKeyDown = useSelectKeyboard({
+    open,
+    searchable,
+    searchValue,
+    highlightedIndex,
+    displayOptions: filteredOptions,
+    setOpen,
+    setHighlightedIndex,
+    setSearchValue,
+    handleSelect,
+    focusTrigger,
+  });
+
   const handleTriggerKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLButtonElement>) => {
       if (disabled || collapsed) return;
       if (!open && (event.key === "ArrowDown" || event.key === "ArrowUp" || event.key === "Enter" || event.key === " ")) {
         event.preventDefault();
         setOpen(true);
+        return;
       }
       if (searchable && !open && event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
         setOpen(true);
+        return;
       }
+      // Focus normally moves into the listbox as it opens, but it can still be
+      // on the trigger — the frame the dropdown mounts in, or after the user
+      // shift-tabs back to it. Handle navigation here too rather than dropping
+      // the keystroke.
+      handleListKeyDown(event);
     },
-    [disabled, collapsed, open, setOpen, searchable]
+    [disabled, collapsed, open, setOpen, searchable, handleListKeyDown]
   );
 
   const handleSearchChange = useCallback((val: string) => {
@@ -186,6 +222,14 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     wasOpenRef.current = open;
   }, [open, filteredOptions, searchable, selectedValues]);
 
+  // Non-searchable: focus the listbox itself, so arrow keys reach the scoped
+  // keydown handler and a screen reader follows aria-activedescendant. The
+  // searchable variant keeps focus in its input instead.
+  useEffect(() => {
+    if (!open || searchable) return;
+    listboxNode?.focus();
+  }, [open, searchable, listboxNode]);
+
   // Scroll highlighted option into view
   useEffect(() => {
     if (open && highlightedIndex >= 0) {
@@ -215,32 +259,28 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
     return () => document.removeEventListener("mousedown", handler);
   }, [open, setOpen, refs]);
 
-  useSelectKeyboard({
-    open,
-    searchable,
-    searchValue,
-    highlightedIndex,
-    displayOptions: filteredOptions,
-    setOpen,
-    setHighlightedIndex,
-    setSearchValue,
-    handleSelect,
-    focusTrigger,
-  });
-
   // The listbox id must be unique per instance: it is referenced by
   // aria-controls, and a hardcoded value meant two Selects on one page
   // produced duplicate ids and cross-wired ARIA.
   const listboxId = useId();
+  const activeOptionId = open && highlightedIndex >= 0 && highlightedIndex < filteredOptions.length ? selectOptionId(listboxId, highlightedIndex) : undefined;
 
   // Strip mode from DOM props
   const { mode: _, value: _v, defaultValue: _dv, onValueChange: _oc, ...htmlProps } = restProps as Record<string, unknown>;
 
+  // `role="listbox"` requires an accessible name of its own, and the trigger
+  // can't supply one: its label is the current *value*, and in searchable mode
+  // it is an input whose name would resolve to whatever has been typed. Use the
+  // caller's `aria-label` when there is one, else the placeholder — the closest
+  // thing this component has to a field label.
+  const listboxLabel = typeof htmlProps["aria-label"] === "string" ? (htmlProps["aria-label"] as string) : placeholder;
+
   return (
     <>
       {searchable && open && !collapsed ? (
         <SelectTriggerSearch
           setReference={refs.setReference}
+          rootRef={rootRef}
           inputRef={inputRef}
           searchValue={searchValue}
           disabled={disabled}
@@ -248,12 +288,15 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
           open={open}
           className={className}
           onSearchChange={handleSearchChange}
+          onKeyDown={handleListKeyDown}
           listboxId={listboxId}
+          activeOptionId={activeOptionId}
           props={htmlProps as React.InputHTMLAttributes<HTMLInputElement>}
         />
       ) : (
         <SelectTriggerButton
           setReference={refs.setReference}
+          rootRef={rootRef}
           open={open}
           disabled={disabled}
           collapsed={collapsed}
@@ -272,7 +315,9 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
         <SelectDropdown
           setFloating={refs.setFloating}
           listboxId={listboxId}
-          listboxRef={listboxRef}
+          setListbox={setListbox}
+          label={listboxLabel}
+          activeOptionId={activeOptionId}
           floatingStyles={floatingStyles}
           displayOptions={filteredOptions}
           highlightedIndex={highlightedIndex}
@@ -282,8 +327,20 @@ export const Select = <T extends string = string>(props: SelectProps<T>) => {
           multiple={isMultiple}
           onSelect={handleSelect}
           onHighlight={setHighlightedIndex}
+          onKeyDown={handleListKeyDown}
         />
       )}
     </>
   );
-};
+});
+
+SelectRoot.displayName = "Select";
+
+/**
+ * The trigger is the ref target: `register` from a form library and
+ * scroll-into-view both want it, and it is a `<div>` in both the button and the
+ * searchable variants. It does swap nodes when the searchable trigger replaces
+ * the button one, so a callback ref sees null and then the new element — normal
+ * for conditional rendering, but worth knowing if you cache the node.
+ */
+export const Select = SelectRoot as <T extends string = string>(props: SelectProps<T> & { ref?: Ref<HTMLDivElement> }) => ReactElement;

package/src/components/Select/SelectDropdown.tsx

@@ -4,10 +4,22 @@ import { Check } from "lucide-react";
 import type React from "react";
 import type { WritableRefObject } from "../../internal/types";
 
+/**
+ * Options are addressed by id, not by focus: the listbox (or the search input)
+ * keeps focus and points `aria-activedescendant` at the highlighted option, so
+ * both sides need to agree on the id.
+ */
+export const selectOptionId = (listboxId: string, index: number) => `${listboxId}-option-${index}`;
+
 interface SelectDropdownProps<T extends string> {
   setFloating: (node: HTMLElement | null) => void;
   listboxId: string;
-  listboxRef: WritableRefObject<HTMLDivElement | null>;
+  /** Publishes the listbox node upward — Select focuses it and scrolls it. */
+  setListbox: (node: HTMLDivElement | null) => void;
+  /** Names the listbox — a bare `role="listbox"` has no accessible name. */
+  label: string;
+  /** The highlighted option's id, or undefined when nothing is highlighted. */
+  activeOptionId: string | undefined;
   floatingStyles: React.CSSProperties;
   displayOptions: readonly { value: T; label: string }[];
   highlightedIndex: number;
@@ -17,12 +29,15 @@ interface SelectDropdownProps<T extends string> {
   multiple: boolean;
   onSelect: (value: T) => void;
   onHighlight: (index: number) => void;
+  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
 }
 
 export const SelectDropdown = <T extends string>({
   setFloating,
   listboxId,
-  listboxRef,
+  setListbox,
+  label,
+  activeOptionId,
   floatingStyles,
   displayOptions,
   highlightedIndex,
@@ -32,17 +47,24 @@ export const SelectDropdown = <T extends string>({
   multiple,
   onSelect,
   onHighlight,
+  onKeyDown,
 }: SelectDropdownProps<T>) => (
   <FloatingPortal>
     <div
       ref={(node) => {
         setFloating(node);
-        listboxRef.current = node;
+        setListbox(node);
       }}
       id={listboxId}
       role="listbox"
+      aria-label={label}
       aria-multiselectable={multiple || undefined}
+      aria-activedescendant={activeOptionId}
+      // Focus lands here when the dropdown opens (the searchable variant keeps
+      // it in the input instead), which is what makes `aria-activedescendant`
+      // and the scoped keydown handler work.
       tabIndex={-1}
+      onKeyDown={onKeyDown}
       style={floatingStyles}
       className="z-popover max-h-60 overflow-y-auto rounded-md border border-border-normal bg-bg-normal shadow-lg"
     >
@@ -59,8 +81,15 @@ export const SelectDropdown = <T extends string>({
                 else optionRefs.current.delete(index);
               }}
               type="button"
+              id={selectOptionId(listboxId, index)}
               role="option"
               aria-selected={isSelected}
+              // The options are not tab stops and must not steal focus: the
+              // listbox holds it and delegates via aria-activedescendant, so a
+              // click that moved focus onto the option would strand the keyboard
+              // handler with nothing listening.
+              tabIndex={-1}
+              onMouseDown={(event) => event.preventDefault()}
               onClick={() => onSelect(option.value)}
               onMouseEnter={() => onHighlight(index)}
               className={cn(

package/src/components/Select/SelectTrigger.tsx

@@ -1,9 +1,12 @@
 import { cn } from "@sixthshift/design-system/utils";
 import { ChevronDown, X } from "lucide-react";
-import type { HTMLAttributes } from "react";
+import type { HTMLAttributes, Ref } from "react";
+import type { WritableRefObject } from "../../internal/types";
 
 interface SelectTriggerButtonProps {
   setReference: (node: HTMLElement | null) => void;
+  /** Consumer ref from Select, attached to this trigger's root element. */
+  rootRef?: Ref<HTMLDivElement>;
   listboxId: string;
   open: boolean;
   disabled: boolean;
@@ -19,6 +22,7 @@ interface SelectTriggerButtonProps {
 
 export const SelectTriggerButton = ({
   setReference,
+  rootRef,
   listboxId,
   open,
   disabled,
@@ -37,7 +41,7 @@ export const SelectTriggerButton = ({
   const showClear = showClearButton && !collapsed;
 
   return (
-    <div className="relative w-full">
+    <div ref={rootRef} className="relative w-full">
       <button
         ref={setReference}
         type="button"
@@ -85,7 +89,11 @@ export const SelectTriggerButton = ({
 
 interface SelectTriggerSearchProps {
   setReference: (node: HTMLElement | null) => void;
+  /** Consumer ref from Select, attached to this trigger's root element. */
+  rootRef?: Ref<HTMLDivElement>;
   listboxId: string;
+  /** Id of the highlighted option — the input keeps focus and delegates to it. */
+  activeOptionId: string | undefined;
   inputRef: React.RefObject<HTMLInputElement | null>;
   searchValue: string;
   disabled: boolean;
@@ -93,12 +101,15 @@ interface SelectTriggerSearchProps {
   open: boolean;
   className: string | undefined;
   onSearchChange: (value: string) => void;
+  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
   props: React.InputHTMLAttributes<HTMLInputElement>;
 }
 
 export const SelectTriggerSearch = ({
   setReference,
+  rootRef,
   listboxId,
+  activeOptionId,
   inputRef,
   searchValue,
   disabled,
@@ -106,14 +117,25 @@ export const SelectTriggerSearch = ({
   open,
   className,
   onSearchChange,
+  onKeyDown,
   props,
 }: SelectTriggerSearchProps) => (
-  <div ref={setReference} className={cn("relative flex w-full items-center", className)}>
+  // floating-ui anchors to this element and the consumer may also want it, so
+  // both refs run off one callback rather than one silently winning.
+  <div
+    ref={(node) => {
+      setReference(node);
+      if (typeof rootRef === "function") rootRef(node);
+      else if (rootRef) (rootRef as WritableRefObject<HTMLDivElement | null>).current = node;
+    }}
+    className={cn("relative flex w-full items-center", className)}
+  >
     <input
       ref={inputRef as React.RefObject<HTMLInputElement>}
       type="text"
       value={searchValue}
       onChange={(e) => onSearchChange(e.target.value)}
+      onKeyDown={onKeyDown}
       placeholder={displayLabel}
       disabled={disabled}
       className={cn(
@@ -122,6 +144,7 @@ export const SelectTriggerSearch = ({
       role="combobox"
       aria-expanded={open}
       aria-controls={listboxId}
+      aria-activedescendant={activeOptionId}
       aria-autocomplete="list"
       {...props}
     />