@justanarthur/modo-ui 0.5.0 → 0.6.0-canary.0

package/components/overlays/dropdown/dropdown-search.tsx

@@ -0,0 +1,395 @@
+// biome-ignore-all lint: vendored upstream code keeps its own patterns (see the header)
+/*
+ * Ported from Fluid Functionalism — github.com/mickadesign/fluid-functionalism
+ * `registry/default/dropdown-search.tsx` @ b3587bdbd83fc66c2a6aae3817ffb856cb09260b
+ * MIT License © 2026 Micka Touillaud — fluidfunctionalism.com (notice: LICENSE.fluid-functionalism)
+ * Local modifications:
+ * - `"use client"` dropped; `@/lib/*` imports rewritten to `../../../lib/*`.
+ * - `filter` mode (local addition): `value` / `onValueChange` become optional
+ *   and, with `filter`, the field reads and writes the query the surrounding
+ *   panel holds (`DropdownFilterContext`), which filters the rows itself. The
+ *   controlled `value` + `onValueChange` API is untouched.
+ * - Styling reads DS tokens (AGENTS.md styling): `duration-80|120|160` and
+ *   tier-length JS durations → `duration-<tier>` / `spring.*`.
+ */
+
+import {
+  createContext,
+  forwardRef,
+  type HTMLAttributes,
+  type InputHTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type RefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { useIcon } from '../../../lib/icon-context'
+import { useSize } from '../../../lib/size-context'
+import { SURFACE_BG } from '../../../lib/surface-classes'
+import { useSurface } from '../../../lib/surface-context'
+import { cn } from '../../../lib/utils'
+
+// ---------------------------------------------------------------------------
+// Search inside a dropdown menu.
+//
+// DropdownSearch is a text field pinned to the top of a DropdownContent popup.
+// It is controlled: the consumer filters the MenuItems it renders against
+// `value`, so the list can be re-indexed freely (fluid hover keys on the
+// indices of whatever is currently mounted). Two things make a field inside a
+// menu behave:
+//
+//   1. The menu primitive's typeahead must not steal keystrokes from the
+//      field — every typing key stops propagating at the input.
+//   2. Typing while a ROW is focused must land in the field: the popup
+//      hosts a capture-phase keydown handler (useDropdownSearchHost) that
+//      refocuses the input and appends the character.
+//
+// Arrow keys leave the field for the list (first / last row), Enter picks
+// the first row, Escape closes the menu as usual. While the field has focus
+// the first row carries the hover background, so what Enter will pick is
+// always in view; it follows the query as the rows re-filter.
+//
+// Local addition — `filter`: the same field, with the query held by the
+// surrounding panel instead of the consumer. The panel then drops the rows
+// whose `label` doesn't match and re-indexes the survivors, which is exactly
+// the work the controlled form asks the consumer to do.
+// ---------------------------------------------------------------------------
+
+interface SearchHandle {
+  input: HTMLInputElement | null
+  append: (text: string) => void
+  deleteBackward: () => void
+}
+
+interface DropdownSearchHostValue {
+  register: (handle: SearchHandle) => () => void
+  /** Whether the popup is open. Popups stay mounted through their exit
+   *  animation, so the field watches this rather than its own mount. */
+  open: boolean
+  /** Move the hover background to the first enabled row (what Enter picks). */
+  highlightFirst: () => void
+}
+
+export const DropdownSearchHostContext = createContext<DropdownSearchHostValue | null>(null)
+
+/** Local addition. The query a filtering panel holds for its `filter` field. */
+export interface DropdownFilterContextValue {
+  query: string
+  setQuery: (query: string) => void
+}
+
+export const DropdownFilterContext = createContext<DropdownFilterContextValue | null>(null)
+
+const ROW_SELECTOR = [
+  '[role="menuitem"]:not([aria-disabled="true"])',
+  '[role="menuitemradio"]:not([aria-disabled="true"])',
+  '[role="menuitemcheckbox"]:not([aria-disabled="true"])',
+].join(', ')
+
+function menuRows(from: HTMLElement | null): HTMLElement[] {
+  const menu = from?.closest<HTMLElement>('[role="menu"]')
+  return menu ? Array.from(menu.querySelectorAll<HTMLElement>(ROW_SELECTOR)) : []
+}
+
+interface DropdownSearchHostOptions {
+  /** The rows' container: where the first enabled row is looked up. */
+  containerRef: RefObject<HTMLElement | null>
+  /** The popup's fluid-hover setter, for the first-row highlight. */
+  setActiveIndex: (index: number | null) => void
+}
+
+/**
+ * Hosts a DropdownSearch inside a popup. Returns the context value to
+ * provide, a capture-phase keydown handler for the popup element,
+ * `hasSearch()` / `searchMounted` for decisions that depend on a field
+ * being present, and the first-row highlight the field keeps while it has
+ * focus (`isSearchField` / `highlightFirst`, for the popup's focus and
+ * mouse-leave handlers).
+ */
+export function useDropdownSearchHost(open: boolean, { containerRef, setActiveIndex }: DropdownSearchHostOptions) {
+  const handleRef = useRef<SearchHandle | null>(null)
+  // Reactive twin of the ref, for render-time decisions (the popup drops its
+  // scroll fade while a field is pinned at the top).
+  const [searchMounted, setSearchMounted] = useState(false)
+
+  const register = useCallback((handle: SearchHandle) => {
+    handleRef.current = handle
+    setSearchMounted(true)
+    return () => {
+      if (handleRef.current === handle) {
+        handleRef.current = null
+        setSearchMounted(false)
+      }
+    }
+  }, [])
+
+  // The row Enter will pick carries the hover background while the field
+  // has focus. Rows re-index from 0 on every filter, so this is looked up
+  // in the DOM each time rather than remembered.
+  const highlightFirst = useCallback(() => {
+    const first = containerRef.current?.querySelector<HTMLElement>(ROW_SELECTOR)
+    const index = first?.getAttribute('data-fluid-hover-index')
+    setActiveIndex(index != null ? Number(index) : null)
+  }, [containerRef, setActiveIndex])
+
+  /** Whether `target` is the mounted search field. */
+  const isSearchField = useCallback(
+    (target: EventTarget | null) => target !== null && target === handleRef.current?.input,
+    [],
+  )
+
+  const host = useMemo(() => ({ register, open, highlightFirst }), [register, open, highlightFirst])
+
+  // Typing on a focused row: redirect the character (or Backspace) into the
+  // field. Space is left alone — on a row it activates the item, which is
+  // what a menu user expects once they have arrowed down.
+  const onKeyDownCapture = useCallback((e: ReactKeyboardEvent<HTMLElement>) => {
+    const handle = handleRef.current
+    if (!handle?.input) return
+    if (e.target === handle.input) return
+    if (e.metaKey || e.ctrlKey || e.altKey) return
+    if (e.key.length === 1 && e.key !== ' ') {
+      e.preventDefault()
+      e.stopPropagation()
+      handle.input.focus()
+      handle.append(e.key)
+    } else if (e.key === 'Backspace') {
+      e.preventDefault()
+      e.stopPropagation()
+      handle.input.focus()
+      handle.deleteBackward()
+    }
+  }, [])
+
+  /** Whether a search field is mounted in the popup right now. */
+  const hasSearch = useCallback(() => handleRef.current !== null, [])
+
+  return {
+    host,
+    hasSearch,
+    searchMounted,
+    onKeyDownCapture,
+    isSearchField,
+    highlightFirst,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// DropdownSearch
+// ---------------------------------------------------------------------------
+
+export interface DropdownSearchProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'size' | 'defaultValue'> {
+  /** The query. Filter the MenuItems you render against it. Optional under `filter`, where the panel holds the query. */
+  value?: string
+  /** Called on every keystroke, and with `""` on close (see `clearOnClose`). Optional under `filter`. */
+  onValueChange?: (value: string) => void
+  /** Local addition. Let the surrounding panel hold the query and filter its own `Dropdown.Item` rows by `label`, re-indexing the survivors and showing `Dropdown.Empty` when none match. Defaults to `false`. */
+  filter?: boolean
+  /** Placeholder text. Defaults to `"Search…"`. */
+  placeholder?: string
+  /** Reset the query to "" when the popup closes (the field unmounts with
+   *  it), so the menu reopens unfiltered. @default true */
+  clearOnClose?: boolean
+  /** Take focus when the popup opens. @default true */
+  autoFocus?: boolean
+}
+
+const DropdownSearch = forwardRef<HTMLInputElement, DropdownSearchProps>(
+  (
+    {
+      value,
+      onValueChange,
+      filter = false,
+      placeholder = 'Search…',
+      clearOnClose = true,
+      autoFocus = true,
+      className,
+      onKeyDown,
+      ...props
+    },
+    ref,
+  ) => {
+    const SearchIcon = useIcon('search')
+    const sizeClasses = useSize()
+    const compact = sizeClasses.variant === 'compact'
+    const host = useContext(DropdownSearchHostContext)
+    // Outside a popup host (an inline panel) the field is simply open.
+    const open = host?.open ?? true
+    // `filter`: the panel is the source of truth, and the consumer's own
+    // `onValueChange` (if any) still hears every keystroke.
+    const panel = useContext(DropdownFilterContext)
+    const managed = filter ? panel : null
+    const query = managed ? managed.query : (value ?? '')
+    const setQuery = useCallback(
+      (next: string) => {
+        managed?.setQuery(next)
+        onValueChange?.(next)
+      },
+      [managed, onValueChange],
+    )
+    // The popup surface, painted explicitly: rows scroll underneath the sticky
+    // field, and the field's parent is often a display:contents group (the
+    // menu's radio group) that `bg-inherit` would resolve to transparent.
+    const surface = useSurface()
+    const inputRef = useRef<HTMLInputElement | null>(null)
+
+    // Latest value / callback for the imperative handle and the unmount
+    // cleanup, without re-registering on every keystroke.
+    const valueRef = useRef(query)
+    valueRef.current = query
+    const onValueChangeRef = useRef(setQuery)
+    onValueChangeRef.current = setQuery
+    const clearOnCloseRef = useRef(clearOnClose)
+    clearOnCloseRef.current = clearOnClose
+
+    useEffect(() => {
+      if (!host) return
+      return host.register({
+        get input() {
+          return inputRef.current
+        },
+        append: text => onValueChangeRef.current(valueRef.current + text),
+        deleteBackward: () => onValueChangeRef.current(valueRef.current.slice(0, -1)),
+      })
+    }, [host])
+
+    // On every open (mount, or a reopen while the popup was still playing
+    // its exit): reset the query so the list starts unfiltered, then take
+    // focus. The popup's own initial focus (first row on a keyboard open,
+    // the panel on a pointer open) is queued a frame after mount; the field
+    // takes over one frame later so a menu with a search opens ready to type.
+    useEffect(() => {
+      if (!open) return
+      if (clearOnCloseRef.current && valueRef.current !== '') {
+        onValueChangeRef.current('')
+      }
+      if (!autoFocus) return
+      let inner: number | undefined
+      const outer = requestAnimationFrame(() => {
+        inner = requestAnimationFrame(() => inputRef.current?.focus())
+      })
+      return () => {
+        cancelAnimationFrame(outer)
+        if (inner !== undefined) cancelAnimationFrame(inner)
+      }
+    }, [open, autoFocus])
+
+    // The rows re-filter in the same commit as the query, so after it the
+    // first enabled row is whatever Enter would pick now: highlight it while
+    // the field has focus. (Focus arriving at the field is the popup's
+    // onFocus; this covers the query moving under a focused field.)
+    useEffect(() => {
+      if (!host || document.activeElement !== inputRef.current) return
+      host.highlightFirst()
+    }, [host, query])
+
+    // Unmount (the popup finished closing): reset the query so the next
+    // open shows the full list.
+    useEffect(
+      () => () => {
+        if (clearOnCloseRef.current && valueRef.current !== '') {
+          onValueChangeRef.current('')
+        }
+      },
+      [],
+    )
+
+    const handleKeyDown = (e: ReactKeyboardEvent<HTMLInputElement>) => {
+      onKeyDown?.(e)
+      if (e.defaultPrevented) return
+      // Escape and Tab belong to the menu (close / leave). Everything else is
+      // either typing, which the menu's typeahead must not see, or list
+      // navigation handled right here.
+      if (e.key === 'Escape' || e.key === 'Tab') return
+      e.stopPropagation()
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+        const rows = menuRows(e.currentTarget)
+        if (rows.length === 0) return
+        e.preventDefault()
+        ;(e.key === 'ArrowDown' ? rows[0] : rows[rows.length - 1])?.focus()
+      } else if (e.key === 'Enter') {
+        e.preventDefault()
+        menuRows(e.currentTarget)[0]?.click()
+      }
+    }
+
+    return (
+      <div
+        // Sticky at the top of the scrolling popup, bleeding into its 4px
+        // padding so the divider runs edge to edge and rows scroll underneath
+        // it; margin + the list gap put the first row 4px below the divider —
+        // the same inset as the popup's side padding.
+        className={cn(
+          'group/search sticky top-0 z-20 -mx-1 -mt-1 mb-0.5 flex shrink-0 items-center border-b border-border/60',
+          SURFACE_BG[surface],
+          sizeClasses.control,
+          sizeClasses.gap,
+          compact ? 'px-2.5' : 'px-3',
+          className,
+        )}
+      >
+        <SearchIcon
+          size={sizeClasses.icon}
+          strokeWidth={1.5}
+          className="shrink-0 text-muted-foreground transition-[color,stroke-width] duration-fast group-focus-within/search:text-foreground group-focus-within/search:stroke-[2]"
+        />
+        <input
+          ref={node => {
+            inputRef.current = node
+            if (typeof ref === 'function') ref(node)
+            else if (ref) ref.current = node
+          }}
+          type="text"
+          role="searchbox"
+          autoComplete="off"
+          autoCorrect="off"
+          spellCheck={false}
+          value={query}
+          onChange={e => setQuery(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder={placeholder}
+          // rounded-none: the site's base :focus-visible rule hands focused
+          // elements the shape radius, and a text input clips its caret to
+          // its own corners (pill mode nicks the caret at the left edge).
+          className={cn(
+            'min-w-0 flex-1 rounded-none bg-transparent text-foreground placeholder:text-muted-foreground outline-none font-[inherit]',
+            sizeClasses.text,
+            // The line box: Safari runs the caret its full height, so the
+            // ladder's leading keeps it in proportion to the row. (Chrome
+            // sizes the caret to the font itself, whatever the leading.)
+            compact ? 'leading-5' : 'leading-6',
+          )}
+          {...props}
+        />
+      </div>
+    )
+  },
+)
+
+DropdownSearch.displayName = 'DropdownSearch'
+
+// ---------------------------------------------------------------------------
+// DropdownEmpty — the "no results" row a filtered menu shows instead of items.
+// ---------------------------------------------------------------------------
+
+const DropdownEmpty = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => {
+  const sizeClasses = useSize()
+  return (
+    <div
+      ref={ref}
+      role="status"
+      aria-live="polite"
+      className={cn('px-2 py-6 text-center text-muted-foreground', sizeClasses.text, className)}
+      {...props}
+    />
+  )
+})
+
+DropdownEmpty.displayName = 'DropdownEmpty'
+
+export { DropdownEmpty, DropdownSearch }

package/components/overlays/dropdown/examples.mdx

@@ -0,0 +1,294 @@
+import Dropdown from './index'
+import Button from '../../button'
+import Dialog from '../dialog'
+import { Bell, ChevronDown, Clock, Copy, Ellipsis, Lock, LogOut, Mail, Monitor, Palette, Pencil, Settings, Shield, SquareLibrary, Star, Trash2, User, Users } from 'lucide-react'
+
+# Basic
+
+The inline panel, running its own selection: `defaultCheckedIndex` makes
+the rows radio options and the panel moves the marker itself.
+
+<Dropdown defaultCheckedIndex={0}>
+  <Dropdown.Item index={0} icon={SquareLibrary} label="Teamspaces" />
+  <Dropdown.Item index={1} icon={Clock} label="Recents" />
+  <Dropdown.Item index={2} icon={Star} label="Favorites" />
+  <Dropdown.Item index={3} icon={Users} label="Shared" />
+  <Dropdown.Item index={4} icon={Lock} label="Private" />
+</Dropdown>
+
+# Groups
+
+Without any checked state the rows are plain actions. Dropdown.Label
+captions a run of them, Dropdown.Separator rules between the runs, and the
+indices keep counting across both.
+
+<Dropdown>
+  <Dropdown.Label>Account</Dropdown.Label>
+  <Dropdown.Item index={0} icon={Mail} label="Email" />
+  <Dropdown.Item index={1} icon={Bell} label="Notifications" />
+  <Dropdown.Item index={2} icon={Shield} label="Privacy" />
+  <Dropdown.Separator />
+  <Dropdown.Label>Appearance</Dropdown.Label>
+  <Dropdown.Item index={3} icon={Settings} label="General" />
+  <Dropdown.Item index={4} icon={Palette} label="Theme" />
+  <Dropdown.Item index={5} icon={Monitor} label="Display" />
+</Dropdown>
+
+# Triggered menu
+
+3 parts: Dropdown.Menu, Dropdown.Trigger, Dropdown.Content. Any element
+goes in `render`, and picking a row closes the menu.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="ghost">Open menu</Button>} />
+  <Dropdown.Content defaultCheckedIndex={0}>
+    <Dropdown.Item index={0} icon={SquareLibrary} label="Teamspaces" />
+    <Dropdown.Item index={1} icon={Clock} label="Recents" />
+    <Dropdown.Item index={2} icon={Star} label="Favorites" />
+    <Dropdown.Item index={3} icon={Users} label="Shared" />
+    <Dropdown.Item index={4} icon={Lock} label="Private" />
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Morph
+
+The menu oozes out of its trigger by default. `effect="morph"` with `hideSource` turns the trigger itself into the menu and shrinks it back, one continuous surface.
+
+<div className="flex flex-wrap items-start justify-center gap-3">
+  <Dropdown.Menu>
+    <Dropdown.Trigger render={<Button variant="secondary">Goo</Button>} />
+    <Dropdown.Content defaultCheckedIndex={0}>
+      <Dropdown.Item index={0} icon={Mail} label="Email" />
+      <Dropdown.Item index={1} icon={Bell} label="Notifications" />
+      <Dropdown.Item index={2} icon={Shield} label="Privacy" />
+    </Dropdown.Content>
+  </Dropdown.Menu>
+  <Dropdown.Menu>
+    <Dropdown.Trigger render={<Button variant="secondary">Morph</Button>} />
+    <Dropdown.Content effect="morph" hideSource defaultCheckedIndex={0}>
+      <Dropdown.Item index={0} icon={Settings} label="General" />
+      <Dropdown.Item index={1} icon={Palette} label="Theme" />
+      <Dropdown.Item index={2} icon={Monitor} label="Display" />
+    </Dropdown.Content>
+  </Dropdown.Menu>
+</div>
+
+# Multiple selection
+
+`defaultCheckedIndices` (or `checkedIndices`): rows become checkboxes, the
+menu stays open as you toggle, and touching picks share one background.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="ghost">Status</Button>} />
+  <Dropdown.Content defaultCheckedIndices={[0, 1, 2]}>
+    {['Open', 'In progress', 'In review', 'Blocked', 'Done', 'Archived'].map((status, i) => (
+      <Dropdown.Item key={status} index={i} label={status} />
+    ))}
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Searchable menu
+
+Put a Dropdown.Search marked `filter` first and the panel filters its own
+rows by `label`. Type to filter, press Enter to pick the first match.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="ghost" trailingIcon={ChevronDown}>Language</Button>} />
+  <Dropdown.Content defaultCheckedIndex={0}>
+    <Dropdown.Search filter placeholder="Search languages" />
+    {['Auto detect', 'Arabic', 'Bengali', 'Chinese (Simplified)', 'Czech', 'Danish', 'Dutch', 'English (UK)', 'English (US)', 'Finnish', 'French', 'German', 'Greek', 'Hebrew', 'Hindi', 'Hungarian', 'Indonesian', 'Italian', 'Japanese', 'Korean', 'Norwegian', 'Polish', 'Portuguese (Brazil)', 'Romanian', 'Russian', 'Spanish', 'Swedish', 'Thai', 'Turkish', 'Ukrainian', 'Vietnamese'].map((language, i) => (
+      <Dropdown.Item key={language} index={i} label={language} />
+    ))}
+    <Dropdown.Empty>No languages found</Dropdown.Empty>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Searchable multiple selection
+
+Both at once. The panel filters the rows and keeps the picks on the rows
+themselves, so a filtered-away pick is still checked when it comes back.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="ghost">Labels</Button>} />
+  <Dropdown.Content defaultCheckedIndices={[0, 3]}>
+    <Dropdown.Search filter placeholder="Search labels" />
+    {['Bug', 'Feature', 'Docs', 'Design', 'Performance', 'Accessibility', 'Refactor', 'Testing', 'Infrastructure', 'Security', 'Good first issue', 'Help wanted'].map((label, i) => (
+      <Dropdown.Item key={label} index={i} label={label} />
+    ))}
+    <Dropdown.Empty>No labels found</Dropdown.Empty>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Children items
+
+Rows written shadcn-style: the content as children and no `index` — each row
+takes its place in document order, conditional rows included. `shortcut`
+adds a muted caption at the end, `inset` lines a text-only row up with the
+rows that have an icon, and `onSelect` runs on a pick by pointer or keyboard.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger asChild>
+    <Button variant="ghost" size="icon" aria-label="Row actions"><Ellipsis /></Button>
+  </Dropdown.Trigger>
+  <Dropdown.Content align="end">
+    <Dropdown.Item icon={Pencil} shortcut="⌘E">Edit</Dropdown.Item>
+    <Dropdown.Item icon={Copy} shortcut="⌘D">Duplicate</Dropdown.Item>
+    <Dropdown.Item inset>Move to…</Dropdown.Item>
+    <Dropdown.Item disabled inset>Archive</Dropdown.Item>
+    <Dropdown.Separator />
+    <Dropdown.Item icon={Trash2} shortcut="⌫">Delete</Dropdown.Item>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Groups and labels
+
+`Dropdown.Group` holds a run of related rows; a `Dropdown.Label` inside it
+names the group for assistive tech. Labels and separators break the row
+order, so nothing selected melts across them.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="secondary" leadingIcon={User}>Account</Button>} />
+  <Dropdown.Content>
+    <Dropdown.Group>
+      <Dropdown.Label>My account</Dropdown.Label>
+      <Dropdown.Item icon={User}>Profile</Dropdown.Item>
+      <Dropdown.Item icon={Settings}>Settings</Dropdown.Item>
+    </Dropdown.Group>
+    <Dropdown.Separator />
+    <Dropdown.Group>
+      <Dropdown.Label inset>Team</Dropdown.Label>
+      <Dropdown.Item inset>Invite members</Dropdown.Item>
+      <Dropdown.Item inset>New team</Dropdown.Item>
+    </Dropdown.Group>
+    <Dropdown.Separator />
+    <Dropdown.Item icon={LogOut}>Log out</Dropdown.Item>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Shortcut
+
+`Dropdown.Shortcut` is the trailing caption on its own, for rows that lay
+out their own content.
+
+<Dropdown className="w-64">
+  <Dropdown.Item>
+    <Mail />
+    New message
+    <Dropdown.Shortcut>⌘N</Dropdown.Shortcut>
+  </Dropdown.Item>
+  <Dropdown.Item>
+    <Bell />
+    Mute thread
+    <Dropdown.Shortcut>⇧⌘M</Dropdown.Shortcut>
+  </Dropdown.Item>
+</Dropdown>
+
+# Submenu
+
+A `Dropdown.Sub` holds a trigger row and its panel. ArrowRight, a press or a
+resting pointer opens it, ArrowLeft or Escape closes it; it grows out of its
+row, which stays lit while it is open, and nests as deep as you like.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="secondary">Options</Button>} />
+  <Dropdown.Content keepMounted>
+    <Dropdown.Item icon={User}>Profile</Dropdown.Item>
+    <Dropdown.Sub>
+      <Dropdown.SubTrigger icon={Palette}>Theme</Dropdown.SubTrigger>
+      <Dropdown.SubContent keepMounted>
+        <Dropdown.RadioGroup defaultValue="system">
+          <Dropdown.RadioItem value="light">Light</Dropdown.RadioItem>
+          <Dropdown.RadioItem value="dark">Dark</Dropdown.RadioItem>
+          <Dropdown.RadioItem value="system">System</Dropdown.RadioItem>
+        </Dropdown.RadioGroup>
+      </Dropdown.SubContent>
+    </Dropdown.Sub>
+    <Dropdown.Sub>
+      <Dropdown.SubTrigger icon={Users}>Invite users</Dropdown.SubTrigger>
+      <Dropdown.SubContent>
+        <Dropdown.Item icon={Mail}>Email</Dropdown.Item>
+        <Dropdown.Item icon={Copy}>Copy link</Dropdown.Item>
+        <Dropdown.Separator />
+        <Dropdown.Sub>
+          <Dropdown.SubTrigger inset>More</Dropdown.SubTrigger>
+          <Dropdown.SubContent>
+            <Dropdown.Item>Slack</Dropdown.Item>
+            <Dropdown.Item>Teams</Dropdown.Item>
+          </Dropdown.SubContent>
+        </Dropdown.Sub>
+      </Dropdown.SubContent>
+    </Dropdown.Sub>
+    <Dropdown.Separator />
+    <Dropdown.Item icon={LogOut}>Log out</Dropdown.Item>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Checkbox items
+
+`Dropdown.CheckboxItem` toggles itself — `defaultChecked`, or `checked` with
+`onCheckedChange` — and keeps the menu open. Touching checked rows share one
+background, as in a multiple selection. Uncontrolled rows live inside the
+popup, so `keepMounted` keeps their state across opens.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="secondary" trailingIcon={ChevronDown}>Columns</Button>} />
+  <Dropdown.Content align="end" keepMounted>
+    <Dropdown.Label>Visible columns</Dropdown.Label>
+    <Dropdown.CheckboxItem defaultChecked>Name</Dropdown.CheckboxItem>
+    <Dropdown.CheckboxItem defaultChecked>Email</Dropdown.CheckboxItem>
+    <Dropdown.CheckboxItem>Role</Dropdown.CheckboxItem>
+    <Dropdown.CheckboxItem defaultChecked>Status</Dropdown.CheckboxItem>
+    <Dropdown.CheckboxItem disabled>Created</Dropdown.CheckboxItem>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Radio group
+
+`Dropdown.RadioGroup` picks one of its `Dropdown.RadioItem` rows by `value`
+(`defaultValue`, or `value` with `onValueChange`). Picking one closes the
+menu.
+
+<Dropdown.Menu>
+  <Dropdown.Trigger render={<Button variant="secondary" trailingIcon={ChevronDown}>Language</Button>} />
+  <Dropdown.Content keepMounted>
+    <Dropdown.RadioGroup defaultValue="sk">
+      <Dropdown.Label>Language</Dropdown.Label>
+      <Dropdown.RadioItem value="sk">Slovenčina</Dropdown.RadioItem>
+      <Dropdown.RadioItem value="cs">Čeština</Dropdown.RadioItem>
+      <Dropdown.RadioItem value="en">English</Dropdown.RadioItem>
+      <Dropdown.RadioItem value="de" disabled>Deutsch</Dropdown.RadioItem>
+    </Dropdown.RadioGroup>
+  </Dropdown.Content>
+</Dropdown.Menu>
+
+# Inside a dialog
+
+A menu lifts 2 surface levels above whatever it opens over — a dialog
+included — and so does its submenu above the menu.
+
+<Dialog>
+  <Dialog.Trigger render={<Button variant="tertiary">Open dialog</Button>} />
+  <Dialog.Content>
+    <Dialog.Header>
+      <Dialog.Title>Share document</Dialog.Title>
+      <Dialog.Description>Pick who can see it.</Dialog.Description>
+    </Dialog.Header>
+    <Dropdown.Menu>
+      <Dropdown.Trigger render={<Button variant="secondary" trailingIcon={ChevronDown}>Access</Button>} />
+      <Dropdown.Content keepMounted>
+        <Dropdown.RadioGroup defaultValue="team">
+          <Dropdown.RadioItem value="private" icon={Lock}>Only me</Dropdown.RadioItem>
+          <Dropdown.RadioItem value="team" icon={Users}>My team</Dropdown.RadioItem>
+        </Dropdown.RadioGroup>
+        <Dropdown.Separator />
+        <Dropdown.Sub>
+          <Dropdown.SubTrigger icon={Shield}>Advanced</Dropdown.SubTrigger>
+          <Dropdown.SubContent keepMounted>
+            <Dropdown.CheckboxItem defaultChecked>Allow comments</Dropdown.CheckboxItem>
+            <Dropdown.CheckboxItem>Allow downloads</Dropdown.CheckboxItem>
+          </Dropdown.SubContent>
+        </Dropdown.Sub>
+      </Dropdown.Content>
+    </Dropdown.Menu>
+  </Dialog.Content>
+</Dialog>