@boyernick/standard-ui-react 0.1.0 → 0.1.1-canary.10

package/src/carousel.tsx

@@ -8,7 +8,8 @@ import {
   useCallback,
   useContext,
   useEffect,
-  useState,
+  useRef,
+  useSyncExternalStore,
   type ComponentProps,
   type KeyboardEvent,
 } from "react"
@@ -21,6 +22,9 @@ type UseCarouselParameters = Parameters<typeof useEmblaCarousel>
 type CarouselOptions = UseCarouselParameters[0]
 type CarouselPlugin = UseCarouselParameters[1]
 
+const TRACKPAD_SWIPE_THRESHOLD = 24
+const TRACKPAD_GESTURE_END_DELAY = 140
+
 type CarouselContextValue = {
   carouselRef: ReturnType<typeof useEmblaCarousel>[0]
   api: CarouselApi
@@ -46,6 +50,8 @@ export type CarouselProps = ComponentProps<"div"> & {
   plugins?: CarouselPlugin
   orientation?: "horizontal" | "vertical"
   setApi?: (api: CarouselApi) => void
+  /** Adds directional edge fades wherever more slides are available. */
+  fade?: boolean
 }
 
 export type CarouselContentProps = ComponentProps<"div">
@@ -53,16 +59,54 @@ export type CarouselItemProps = ComponentProps<"div">
 export type CarouselPreviousProps = ComponentProps<typeof Button>
 export type CarouselNextProps = ComponentProps<typeof Button>
 
+const CarouselEdgeFades = () => {
+  const { orientation, canScrollPrev, canScrollNext } = useCarousel()
+  const horizontal = orientation === "horizontal"
+  const sharedClassName =
+    "pointer-events-none absolute z-10 opacity-0 transition-opacity duration-[var(--duration-lg)] ease-enter data-[visible=true]:opacity-100 motion-reduce:transition-none"
+
+  return (
+    <>
+      <div
+        aria-hidden="true"
+        data-slot={horizontal ? "carousel-fade-left" : "carousel-fade-top"}
+        data-visible={canScrollPrev}
+        className={cn(
+          sharedClassName,
+          horizontal
+            ? "-top-px -bottom-px -left-px w-20 bg-linear-to-r from-surface via-surface/60 via-40% to-transparent"
+            : "-top-px -right-px -left-px h-20 bg-linear-to-b from-surface via-surface/60 via-40% to-transparent",
+        )}
+      />
+      <div
+        aria-hidden="true"
+        data-slot={horizontal ? "carousel-fade-right" : "carousel-fade-bottom"}
+        data-visible={canScrollNext}
+        className={cn(
+          sharedClassName,
+          horizontal
+            ? "-top-px -right-px -bottom-px w-20 bg-linear-to-l from-surface via-surface/60 via-40% to-transparent"
+            : "-right-px -bottom-px -left-px h-20 bg-linear-to-t from-surface via-surface/60 via-40% to-transparent",
+        )}
+      />
+    </>
+  )
+}
+
 export const Carousel = ({
   orientation = "horizontal",
+  fade = false,
   opts,
   setApi,
   plugins,
   className,
   children,
   onKeyDownCapture,
+  tabIndex,
+  ref: forwardedRef,
   ...props
 }: CarouselProps) => {
+  const carouselRootRef = useRef<HTMLDivElement | null>(null)
   const [carouselRef, api] = useEmblaCarousel(
     {
       ...opts,
@@ -70,14 +114,34 @@ export const Carousel = ({
     },
     plugins,
   )
-  const [canScrollPrev, setCanScrollPrev] = useState(false)
-  const [canScrollNext, setCanScrollNext] = useState(false)
+  // Embla is an external store, so read from it directly rather than mirroring
+  // it into state. Seeding mirrored state meant calling setState synchronously
+  // inside an effect, costing an extra render on mount and on every slide
+  // change. Both snapshots return booleans, so there is no object identity to
+  // keep stable between reads.
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!api) return () => {}
+      api.on("reInit", onStoreChange)
+      api.on("select", onStoreChange)
+      return () => {
+        api.off("reInit", onStoreChange)
+        api.off("select", onStoreChange)
+      }
+    },
+    [api],
+  )
 
-  const handleSelect = useCallback((instance: CarouselApi) => {
-    if (!instance) return
-    setCanScrollPrev(instance.canScrollPrev())
-    setCanScrollNext(instance.canScrollNext())
-  }, [])
+  const canScrollPrev = useSyncExternalStore(
+    subscribe,
+    () => api?.canScrollPrev() ?? false,
+    () => false,
+  )
+  const canScrollNext = useSyncExternalStore(
+    subscribe,
+    () => api?.canScrollNext() ?? false,
+    () => false,
+  )
 
   const scrollPrev = useCallback(() => {
     api?.scrollPrev()
@@ -87,6 +151,35 @@ export const Carousel = ({
     api?.scrollNext()
   }, [api])
 
+  const canScrollPrevRef = useRef(canScrollPrev)
+  const canScrollNextRef = useRef(canScrollNext)
+  const scrollPrevRef = useRef(scrollPrev)
+  const scrollNextRef = useRef(scrollNext)
+
+  useEffect(() => {
+    canScrollPrevRef.current = canScrollPrev
+    canScrollNextRef.current = canScrollNext
+    scrollPrevRef.current = scrollPrev
+    scrollNextRef.current = scrollNext
+  }, [canScrollNext, canScrollPrev, scrollNext, scrollPrev])
+
+  const trackpadDelta = useRef(0)
+  const trackpadGestureHandled = useRef(false)
+  const trackpadGestureTimeout = useRef<ReturnType<typeof setTimeout> | null>(
+    null,
+  )
+
+  const scheduleTrackpadGestureEnd = useCallback(() => {
+    if (trackpadGestureTimeout.current) {
+      clearTimeout(trackpadGestureTimeout.current)
+    }
+    trackpadGestureTimeout.current = setTimeout(() => {
+      trackpadDelta.current = 0
+      trackpadGestureHandled.current = false
+      trackpadGestureTimeout.current = null
+    }, TRACKPAD_GESTURE_END_DELAY)
+  }, [])
+
   const handleKeyDown = useCallback(
     (event: KeyboardEvent<HTMLDivElement>) => {
       onKeyDownCapture?.(event)
@@ -102,21 +195,76 @@ export const Carousel = ({
     [onKeyDownCapture, scrollNext, scrollPrev],
   )
 
-  useEffect(() => {
-    if (!api || !setApi) return
-    setApi(api)
-  }, [api, setApi])
+  const handleWheel = useCallback(
+    (event: globalThis.WheelEvent) => {
+      if (event.defaultPrevented || orientation !== "horizontal") return
+
+      const deltaMultiplier =
+        event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? 100 : 1
+      const horizontalDelta = event.deltaX * deltaMultiplier
+      const verticalDelta = event.deltaY * deltaMultiplier
+
+      if (
+        Math.abs(horizontalDelta) <= Math.abs(verticalDelta) ||
+        Math.abs(horizontalDelta) < 1
+      ) {
+        return
+      }
+
+      if (trackpadGestureHandled.current) {
+        event.preventDefault()
+        scheduleTrackpadGestureEnd()
+        return
+      }
+
+      const canScrollInDirection =
+        horizontalDelta > 0
+          ? canScrollNextRef.current
+          : canScrollPrevRef.current
+      if (!canScrollInDirection) return
+
+      event.preventDefault()
+      trackpadDelta.current += horizontalDelta
+      scheduleTrackpadGestureEnd()
+
+      if (Math.abs(trackpadDelta.current) < TRACKPAD_SWIPE_THRESHOLD) return
+
+      trackpadGestureHandled.current = true
+      trackpadDelta.current = 0
+      if (horizontalDelta > 0) scrollNextRef.current()
+      else scrollPrevRef.current()
+    },
+    [orientation, scheduleTrackpadGestureEnd],
+  )
 
   useEffect(() => {
-    if (!api) return
-    handleSelect(api)
-    api.on("reInit", handleSelect)
-    api.on("select", handleSelect)
+    const root = carouselRootRef.current
+    if (!root) return
+
+    root.addEventListener("wheel", handleWheel, { passive: false })
     return () => {
-      api.off("reInit", handleSelect)
-      api.off("select", handleSelect)
+      root.removeEventListener("wheel", handleWheel)
+      if (trackpadGestureTimeout.current) {
+        clearTimeout(trackpadGestureTimeout.current)
+      }
+      trackpadDelta.current = 0
+      trackpadGestureHandled.current = false
     }
-  }, [api, handleSelect])
+  }, [handleWheel])
+
+  const setCarouselRootRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      carouselRootRef.current = node
+      if (typeof forwardedRef === "function") forwardedRef(node)
+      else if (forwardedRef) forwardedRef.current = node
+    },
+    [forwardedRef],
+  )
+
+  useEffect(() => {
+    if (!api || !setApi) return
+    setApi(api)
+  }, [api, setApi])
 
   return (
     <CarouselContext.Provider
@@ -131,14 +279,23 @@ export const Carousel = ({
       }}
     >
       <div
+        ref={setCarouselRootRef}
         role="region"
         aria-roledescription="carousel"
         data-slot="carousel"
-        className={cn("relative", className)}
+        data-fade={fade || undefined}
+        className={cn(
+          "relative",
+          fade &&
+            "rounded-xl outline-none focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
+          className,
+        )}
         onKeyDownCapture={handleKeyDown}
+        tabIndex={tabIndex ?? (fade ? 0 : undefined)}
         {...props}
       >
         {children}
+        {fade ? <CarouselEdgeFades /> : null}
       </div>
     </CarouselContext.Provider>
   )
@@ -151,7 +308,16 @@ export const CarouselContent = ({
   const { carouselRef, orientation } = useCarousel()
 
   return (
-    <div ref={carouselRef} className="overflow-hidden" data-slot="carousel-viewport">
+    <div
+      ref={carouselRef}
+      className={cn(
+        "overflow-hidden",
+        orientation === "horizontal"
+          ? "touch-pan-y overscroll-x-contain"
+          : "touch-pan-x overscroll-y-contain",
+      )}
+      data-slot="carousel-viewport"
+    >
       <div
         data-slot="carousel-content"
         className={cn(
@@ -185,7 +351,7 @@ export const CarouselItem = ({ className, ...props }: CarouselItemProps) => {
 
 export const CarouselPrevious = ({
   className,
-  variant = "outline",
+  variant = "ghost",
   size = "md",
   ...props
 }: CarouselPreviousProps) => {
@@ -202,7 +368,7 @@ export const CarouselPrevious = ({
       aria-label="Previous slide"
       data-slot="carousel-previous"
       className={cn(
-        "absolute size-9",
+        "absolute size-9 border-0 focus-visible:border-0",
         orientation === "horizontal"
           ? "top-1/2 -left-12 -translate-y-1/2 active:!-translate-y-1/2"
           : "-top-12 left-1/2 -translate-x-1/2 rotate-90 active:!-translate-x-1/2 active:!translate-y-0",
@@ -218,7 +384,7 @@ export const CarouselPrevious = ({
 
 export const CarouselNext = ({
   className,
-  variant = "outline",
+  variant = "ghost",
   size = "md",
   ...props
 }: CarouselNextProps) => {
@@ -235,7 +401,7 @@ export const CarouselNext = ({
       aria-label="Next slide"
       data-slot="carousel-next"
       className={cn(
-        "absolute size-9",
+        "absolute size-9 border-0 focus-visible:border-0",
         orientation === "horizontal"
           ? "top-1/2 -right-12 -translate-y-1/2 active:!-translate-y-1/2"
           : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90 active:!-translate-x-1/2 active:!translate-y-0",

package/src/checkbox.tsx

@@ -4,28 +4,50 @@ import { Checkbox as BaseCheckbox } from "@base-ui/react/checkbox"
 import type { ComponentProps } from "react"
 import { IconCheckmark1, IconMinus } from "./icons"
 import { cn } from "./lib/cn"
+import { motion } from "./lib/motion"
 
 export type CheckboxProps = ComponentProps<typeof BaseCheckbox.Root>
 
 export const Checkbox = ({ className, ...props }: CheckboxProps) => (
   <BaseCheckbox.Root
     className={cn(
-      "group flex size-4 shrink-0 items-center justify-center rounded-sm border border-border-secondary bg-surface transition-colors duration-150 ease-out motion-reduce:transition-none outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20 data-checked:border-brand-primary data-checked:bg-brand-primary data-indeterminate:border-brand-primary data-indeterminate:bg-brand-primary data-disabled:cursor-not-allowed data-disabled:opacity-50",
+      "group flex size-4 shrink-0 items-center justify-center rounded-sm border border-border-secondary bg-surface outline-none",
+      // motion.all, not motion.colors: the filled state brings a box shadow
+      // with it, which has to fade in alongside the background.
+      motion.all,
+      "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
+      // Ticked and mixed are both filled controls, so they carry the primary
+      // button's treatment: brand fill, the border token that pairs with it,
+      // and the top-edge highlight that makes a solid control read as raised.
+      "data-checked:border-brand-primary-border data-checked:bg-brand-primary data-checked:inset-shadow-solid-top",
+      "data-indeterminate:border-brand-primary-border data-indeterminate:bg-brand-primary data-indeterminate:inset-shadow-solid-top",
+      "data-checked:hover:bg-brand-primary-hover data-indeterminate:hover:bg-brand-primary-hover",
+      "data-checked:active:bg-brand-primary-active data-indeterminate:active:bg-brand-primary-active",
+      "data-disabled:cursor-not-allowed data-disabled:opacity-50",
       className,
     )}
     {...props}
   >
-    <BaseCheckbox.Indicator className="flex text-brand-foreground data-unchecked:hidden">
-      <IconCheckmark1
-        size={12}
-        className="size-3 group-data-indeterminate:hidden"
-        aria-hidden
-      />
-      <IconMinus
-        size={12}
-        className="hidden size-3 group-data-indeterminate:block"
-        aria-hidden
-      />
-    </BaseCheckbox.Indicator>
+    {/* Only the active glyph is mounted. Central Icons give every instance of
+        an icon the same mask id, so a CSS-hidden twin would claim that id for
+        the whole document; a `display: none` subtree renders no mask, leaving
+        the visible instance to paint its backing rect unmasked as a solid
+        block. Mounting one icon keeps every id in the document resolvable. */}
+    {/* No `data-unchecked:hidden` here. Base UI keeps the indicator mounted
+        through its exit and flags it with both `data-unchecked` and
+        `data-ending-style`; hiding on the former would cut the latter's
+        transition short and the mark would vanish instantly. */}
+    <BaseCheckbox.Indicator
+      className={cn("flex text-brand-foreground", motion.checkIndicator)}
+      render={(props, state) => (
+        <span {...props}>
+          {state.indeterminate ? (
+            <IconMinus size={12} className="size-3" aria-hidden />
+          ) : (
+            <IconCheckmark1 size={12} className="size-3" aria-hidden />
+          )}
+        </span>
+      )}
+    />
   </BaseCheckbox.Root>
 )

package/src/collapsible.tsx

@@ -25,7 +25,7 @@ export const CollapsibleTrigger = ({
     className={cn(
       "group flex h-9 w-full cursor-pointer items-center justify-between gap-2 rounded-md border border-border-secondary bg-surface px-3 text-sm text-fg-primary inset-shadow-outline-top outline-none",
       motion.colors,
-      "hover:bg-background-tertiary outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20 data-disabled:cursor-not-allowed data-disabled:opacity-50",
+      "outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20 data-disabled:cursor-not-allowed data-disabled:opacity-50",
       className,
     )}
     {...props}
@@ -56,6 +56,8 @@ export const CollapsiblePanel = ({
     )}
     {...props}
   >
-    <div className="pt-2 leading-relaxed">{children}</div>
+    {/* px-3 matches the trigger's own padding, so the panel copy lines up
+        under the trigger's label instead of starting at the panel edge. */}
+    <div className="px-3 pt-2 leading-relaxed">{children}</div>
   </BaseCollapsible.Panel>
 )

package/src/combobox.tsx

@@ -5,6 +5,7 @@ import type { ComponentProps, ReactElement } from "react"
 import { IconChevronDownSmall, IconCrossSmall } from "./icons"
 import { cn } from "./lib/cn"
 import { motion } from "./lib/motion"
+import { popupInset, popupItem, popupLabel, popupMessage, popupSurface } from "./lib/popup"
 
 export type ComboboxProps<
   Value,
@@ -77,7 +78,6 @@ export const ComboboxInputGroup = ({
   <BaseCombobox.InputGroup
     className={cn(
       "relative flex min-h-9 w-full items-center rounded-md border border-border-secondary bg-surface inset-shadow-outline-top outline-none transition-[color,box-shadow]",
-      "has-[[data-popup-open]]:bg-background-tertiary/60",
       "focus-within:border-ring focus-within:ring-[3px] focus-within:ring-offset-1 focus-within:ring-offset-background-primary focus-within:ring-ring/20",
       "aria-invalid:border-destructive aria-invalid:focus-within:border-destructive aria-invalid:focus-within:ring-destructive/20",
       "has-[[aria-invalid=true]]:border-destructive has-[[aria-invalid=true]]:focus-within:border-destructive has-[[aria-invalid=true]]:focus-within:ring-destructive/20",
@@ -139,7 +139,7 @@ export const ComboboxClear = ({
     {...props}
   >
     {children ?? (
-      <IconCrossSmall size={14} className="size-3.5" aria-hidden />
+      <IconCrossSmall size={16} className="size-4" aria-hidden />
     )}
   </BaseCombobox.Clear>
 )
@@ -160,7 +160,7 @@ export const ComboboxBackdrop = ({
 )
 
 export const ComboboxPositioner = ({
-  sideOffset = 4,
+  sideOffset = 6,
   className,
   ...props
 }: ComboboxPositionerProps) => (
@@ -174,7 +174,8 @@ export const ComboboxPositioner = ({
 export const ComboboxPopup = ({ className, ...props }: ComboboxPopupProps) => (
   <BaseCombobox.Popup
     className={cn(
-      "z-50 max-h-[min(24rem,var(--available-height))] w-[var(--anchor-width)] overflow-hidden rounded-md border border-border-primary bg-surface shadow-md outline-none",
+      "z-50 max-h-[min(24rem,var(--available-height))] w-[var(--anchor-width)] overflow-hidden",
+      popupSurface,
       motion.popupAnchor,
       className,
     )}
@@ -199,7 +200,7 @@ export const ComboboxArrow = ({ className, ...props }: ComboboxArrowProps) => (
 
 export const ComboboxList = ({ className, ...props }: ComboboxListProps) => (
   <BaseCombobox.List
-    className={cn("max-h-[inherit] overflow-y-auto p-1 outline-none", className)}
+    className={cn("max-h-[inherit] overflow-y-auto outline-none", popupInset, className)}
     {...props}
   />
 )
@@ -207,7 +208,7 @@ export const ComboboxList = ({ className, ...props }: ComboboxListProps) => (
 export const ComboboxItem = ({ className, ...props }: ComboboxItemProps) => (
   <BaseCombobox.Item
     className={cn(
-      "flex min-h-8 cursor-default items-center gap-2 rounded-xs px-2.5 py-1.5 text-sm text-fg-primary outline-none select-none",
+      popupItem,
       motion.colors,
       "data-disabled:cursor-not-allowed data-disabled:opacity-50 data-highlighted:bg-background-tertiary data-highlighted:text-fg-primary",
       className,
@@ -238,14 +239,14 @@ export const ComboboxItemIndicator = ({
 
 export const ComboboxEmpty = ({ className, ...props }: ComboboxEmptyProps) => (
   <BaseCombobox.Empty
-    className={cn("px-2.5 py-2 text-sm text-fg-tertiary empty:hidden", className)}
+    className={cn(cn(popupMessage, "empty:hidden"), className)}
     {...props}
   />
 )
 
 export const ComboboxStatus = ({ className, ...props }: ComboboxStatusProps) => (
   <BaseCombobox.Status
-    className={cn("px-2.5 py-2 text-sm text-fg-tertiary", className)}
+    className={cn(popupMessage, className)}
     {...props}
   />
 )
@@ -259,7 +260,7 @@ export const ComboboxGroupLabel = ({
   ...props
 }: ComboboxGroupLabelProps) => (
   <BaseCombobox.GroupLabel
-    className={cn("px-2.5 py-1.5 text-xs text-fg-tertiary", className)}
+    className={cn(popupLabel, className)}
     {...props}
   />
 )
@@ -291,7 +292,7 @@ export const ComboboxChips = ({ className, ...props }: ComboboxChipsProps) => (
 export const ComboboxChip = ({ className, ...props }: ComboboxChipProps) => (
   <BaseCombobox.Chip
     className={cn(
-      "inline-flex h-6 items-center gap-1 rounded-xs bg-background-tertiary px-1.5 text-xs text-fg-primary",
+      "inline-flex h-6 items-center gap-1 rounded-xs bg-background-tertiary px-1.5 text-xs-strong text-fg-primary",
       className,
     )}
     {...props}
@@ -305,13 +306,13 @@ export const ComboboxChipRemove = ({
 }: ComboboxChipRemoveProps) => (
   <BaseCombobox.ChipRemove
     className={cn(
-      "inline-flex size-3.5 cursor-pointer items-center justify-center text-fg-tertiary outline-none hover:text-fg-primary focus-visible:outline-none",
+      "inline-flex size-3.5 cursor-pointer items-center justify-center text-fg-primary outline-none focus-visible:outline-none",
       className,
     )}
     {...props}
   >
     {children ?? (
-      <IconCrossSmall size={12} className="size-3" aria-hidden />
+      <IconCrossSmall size={14} className="size-3.5" aria-hidden />
     )}
   </BaseCombobox.ChipRemove>
 )

package/src/command.tsx

@@ -4,8 +4,10 @@ import { Dialog as BaseDialog } from "@base-ui/react/dialog"
 import {
   createContext,
   useContext,
+  useEffect,
   useId,
   useMemo,
+  useRef,
   type ButtonHTMLAttributes,
   type ComponentProps,
   type HTMLAttributes,
@@ -108,7 +110,7 @@ export const CommandBackdrop = ({
 export const CommandPopup = ({ className, ...props }: CommandPopupProps) => (
   <BaseDialog.Popup
     className={cn(
-      "fixed top-1/2 left-1/2 z-50 flex h-[min(80vh,32rem)] w-full max-w-xl -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-2xl border border-border-primary bg-surface-raised shadow-xl outline-none max-sm:max-w-[calc(100vw-2rem)]",
+      "fixed top-1/2 left-1/2 z-50 flex h-[min(80vh,32rem)] w-full max-w-3xl -translate-x-1/2 -translate-y-1/2 flex-col overflow-hidden rounded-2xl bg-surface-raised shadow-ambient outline-none max-sm:max-w-[calc(100vw-2rem)]",
       motion.popupCenter,
       className,
     )}
@@ -147,7 +149,6 @@ export const CommandInput = ({
       aria-activedescendant={activeOptionId}
       className={cn(
         "h-9 min-w-0 flex-1 cursor-text rounded-md bg-transparent px-2.5 text-base text-fg-primary outline-none placeholder:text-fg-quaternary",
-        "focus-visible:bg-background-tertiary/60 focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
         "[&::-webkit-search-cancel-button]:appearance-none [&::-webkit-search-decoration]:appearance-none",
         className,
       )}
@@ -174,9 +175,9 @@ export const CommandClear = ({
   <button
     type="button"
     className={cn(
-      "cursor-pointer rounded-full px-3 py-1.5 text-sm text-fg-quaternary outline-none",
+      "inline-flex h-8 cursor-pointer items-center rounded-full border border-transparent px-3 text-sm text-fg-quaternary outline-none",
       motion.colors,
-      "hover:bg-background-tertiary hover:text-fg-primary focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20 data-[active=true]:text-fg-primary",
+      "hover:bg-background-tertiary hover:text-fg-primary focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20 data-[active=true]:text-fg-primary",
       className,
     )}
     {...props}
@@ -203,9 +204,9 @@ export const CommandClose = ({
 }: CommandCloseProps) => (
   <BaseDialog.Close
     className={cn(
-      "inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full text-fg-primary outline-none",
+      "inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-full border border-transparent text-fg-primary outline-none",
       motion.colors,
-      "hover:bg-background-tertiary focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
+      "hover:bg-background-tertiary focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
       className,
     )}
     aria-label={props["aria-label"] ?? "Close"}
@@ -223,7 +224,7 @@ export const CommandContent = ({
 }: CommandContentProps) => (
   <div
     className={cn(
-      "flex min-h-0 flex-1 flex-col gap-3 overflow-x-visible overflow-y-auto overscroll-contain px-4 pt-1 pb-5",
+      "flex min-h-0 flex-1 flex-col gap-3 overflow-hidden px-4 pt-1 pb-5",
       className,
     )}
     {...props}
@@ -256,9 +257,9 @@ export const CommandFilter = ({
       aria-pressed={selected}
       data-selected={selected || undefined}
       className={cn(
-        "cursor-pointer rounded-full px-4 py-2 text-sm text-fg-quaternary outline-none",
+        "inline-flex h-9 cursor-pointer items-center rounded-full border border-transparent px-4 text-sm text-fg-quaternary outline-none",
         motion.colors,
-        "hover:text-fg-primary focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
+        "hover:text-fg-primary focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
         "data-selected:bg-background-tertiary data-selected:text-fg-primary",
         className,
       )}
@@ -277,7 +278,7 @@ export const CommandList = ({ className, ...props }: CommandListProps) => {
       id={listboxId}
       role="listbox"
       className={cn(
-        "grid min-h-0 flex-1 content-start gap-0 overflow-visible overscroll-contain py-0.5",
+        "grid min-h-0 flex-1 content-start gap-0 overflow-y-auto overscroll-contain py-0.5",
         className,
       )}
       {...props}
@@ -295,12 +296,21 @@ export const CommandItem = ({
   onClick,
   ...props
 }: CommandItemProps) => {
+  const ref = useRef<HTMLAnchorElement & HTMLButtonElement>(null)
+
+  // Keyboard selection moves the highlight without moving focus, so nothing
+  // scrolls the list on its own. `nearest` only acts when the row is actually
+  // out of view, which leaves hover-driven selection alone.
+  useEffect(() => {
+    if (selected) ref.current?.scrollIntoView({ block: "nearest" })
+  }, [selected])
+
   const itemClassName = cn(
-    "flex h-15 min-h-15 w-full cursor-pointer items-center justify-between gap-4 rounded-lg px-4 text-left text-sm font-medium text-fg-primary outline-none select-none",
+    "flex h-15 min-h-15 w-full cursor-pointer items-center justify-between gap-4 rounded-lg border border-transparent px-4 text-left text-sm font-medium text-fg-primary outline-none select-none",
     motion.colors,
     "hover:bg-background-tertiary data-selected:bg-background-tertiary",
     "data-disabled:cursor-not-allowed data-disabled:opacity-50",
-    "focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
+    "focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-offset-1 focus-visible:ring-offset-background-primary focus-visible:ring-ring/20",
     className,
   )
 
@@ -308,6 +318,7 @@ export const CommandItem = ({
     <li role="presentation" className="m-0">
       {href ? (
         <a
+          ref={ref}
           id={id}
           href={disabled ? undefined : href}
           role="option"
@@ -323,6 +334,7 @@ export const CommandItem = ({
         </a>
       ) : (
         <button
+          ref={ref}
           id={id}
           type="button"
           role="option"

package/src/context-menu.tsx

@@ -5,6 +5,7 @@ import type { ComponentProps } from "react"
 import { IconCheckmark1, IconChevronRightSmall } from "./icons"
 import { cn } from "./lib/cn"
 import { motion } from "./lib/motion"
+import { popupInset, popupItem, popupLabel, popupSurface } from "./lib/popup"
 
 export type ContextMenuProps = ComponentProps<typeof BaseContextMenu.Root>
 export type ContextMenuTriggerProps = ComponentProps<
@@ -53,7 +54,7 @@ export type ContextMenuSubmenuTriggerProps = ComponentProps<
 >
 
 const itemClassName = cn(
-  "flex min-h-8 cursor-default items-center gap-2 rounded-xs px-2.5 py-1.5 text-sm text-fg-primary outline-none select-none",
+  popupItem,
   motion.colors,
   "data-disabled:cursor-not-allowed data-disabled:opacity-50 data-highlighted:bg-background-tertiary",
 )
@@ -100,7 +101,9 @@ export const ContextMenuPopup = ({
 }: ContextMenuPopupProps) => (
   <BaseContextMenu.Popup
     className={cn(
-      "z-50 min-w-40 overflow-hidden rounded-md border border-border-primary bg-surface p-1 shadow-md outline-none",
+      "z-50 min-w-40 overflow-hidden",
+      popupSurface,
+      popupInset,
       motion.popupAnchor,
       className,
     )}
@@ -165,7 +168,7 @@ export const ContextMenuGroupLabel = ({
   ...props
 }: ContextMenuGroupLabelProps) => (
   <BaseContextMenu.GroupLabel
-    className={cn("px-2.5 py-1.5 text-xs text-fg-tertiary", className)}
+    className={cn(popupLabel, className)}
     {...props}
   />
 )