@justanarthur/modo-ui 0.6.0-canary.9 → 0.6.0

package/components/inputs/select/index.tsx

@@ -1,1044 +0,0 @@
-// biome-ignore-all lint: vendored upstream code keeps its own patterns (see the header)
-/*
- * Ported from Fluid Functionalism — github.com/mickadesign/fluid-functionalism
- * `registry/base/select.tsx` @ b3587bdbd83fc66c2a6aae3817ffb856cb09260b
- * MIT License © 2026 Micka Touillaud — fluidfunctionalism.com (notice: LICENSE.fluid-functionalism)
- * Local modifications:
- * - `"use client"` dropped; `framer-motion` → `motion/react`; `@/lib/*` and
- *   `@/hooks/*` → `../../../lib/*` (`SizeProvider` → `../../../primitives/sizes`);
- *   `@/lib/elevated` → `../../../primitives/surface`; `@/components/ui/scroll-area`
- *   → `../../../primitives/scroll-area`; `@/components/ui/fluid-hover-highlight` →
- *   `../../../lib/fluid-hover-highlight`.
- * - `SelectProps` members re-declared one per line with the FF docs API-table
- *   descriptions (modo's props table lists only members declared in the
- *   interface body, and drops members whose type spans lines).
- * - Uncontrolled selection was already upstream (`defaultValue` seeds the
- *   internal value, `onValueChange` still fires while controlled) — verified,
- *   kept as is rather than rerouted through `useControllableState`.
- * - Compound statics `Select.Trigger/.Content/.Item/.Group/.Label/.Separator`
- *   attached as expando properties on the root function (TS infers them, so
- *   `<Select.Item>` typechecks); upstream's named exports are kept.
- * - modo item: TSDoc + examples from the FF "Select" docs page, and a default
- *   export.
- * - Styling reads DS tokens (AGENTS.md styling): `text-[Npx]` →
- *   `text-<role>[-compact]`; the hex focus-ring fallback →
- *   `ring-focus-ring` / `border-focus-ring`; `duration-80|120|160` and
- *   tier-length JS durations → `duration-<tier>` / `spring.*`.
- * - The popup morphs out of its trigger through the shared morph layer
- *   (`lib/use-morph.ts` + `MorphSurface`, goo by default on
- *   `spring.goo`; `Select.Content` takes `from` / `effect` /
- *   `hideSource` / `tier`). The `scaleY` motion wrapper and the `actionsRef`
- *   deferred unmount (with its fallback timer) are gone: the morph holds Base
- *   UI's unmount itself. The popup paints its level through the morph's
- *   surface layers instead of `render={<Elevated/>}`, re-providing the level
- *   with `SurfaceProvider` as `Elevated` did.
- * - `effect="morph"` with `hideSource` opens the menu in place over its
- *   trigger: the positioner's `sideOffset` becomes the engine's `inPlaceOffset`.
- * - `Select.Item`'s `index` is optional: rows take their place in document
- *   order (`lib/row-order.tsx`), inside groups, conditionals and maps alike;
- *   the checked row is found by its own index rather than its DOM position.
- *   A row's label may be any node (the trigger shows it, through Base UI's
- *   `items`), with `textValue` for typeahead.
- * - `Select.Value` (local): the trigger's value slot as a part, so a trigger
- *   can take it as children (shadcn's `<SelectValue placeholder>`).
- * - `Select.Content` takes `side` / `align` / `sideOffset` (local).
- * - The keyboard focus ring is the shared `FocusRing` (`lib/focus-ring.tsx`,
- *   pinned to the popup's rounded shape), so it also snaps under reduced motion.
- * - `triggerVariants` moved to `variants.ts` (server-callable, no JSX or hooks)
- *   and re-exported here.
- * - Root `open` / `defaultOpen` / `onOpenChange(open, details)` (local): the 300ms
- *   pick acknowledgment runs only while the open state is uncontrolled; a
- *   controlled select follows the caller's `open` and reports every request.
- * - `Select.Content` takes `alignOffset` / `collisionPadding` (Positioner),
- *   `finalFocus` (Popup) and rest HTML props (Popup). `initialFocus` is not
- *   offered: Base UI's select popup always focuses the picked row itself.
- * - `Select.Trigger` / `Select.Item` take `render` / `asChild` (`lib/slot.ts`);
- *   the trigger takes `wrapperClassName` for its outer div. `Select.Value`
- *   and `Select.Group` forward their ref.
- */
-
-import { Select as SelectPrimitive } from '@base-ui/react/select'
-import type { VariantProps } from 'class-variance-authority'
-import { AnimatePresence, motion } from 'motion/react'
-import {
-  Children,
-  type ComponentProps,
-  cloneElement,
-  createContext,
-  forwardRef,
-  type HTMLAttributes,
-  isValidElement,
-  type ReactElement,
-  type ReactNode,
-  type Ref,
-  useCallback,
-  useContext,
-  useEffect,
-  useImperativeHandle,
-  useMemo,
-  useRef,
-  useState,
-  version,
-} from 'react'
-import { FluidHoverHighlight } from '../../../lib/fluid-hover-highlight'
-import { FocusRing } from '../../../lib/focus-ring'
-import type { IconComponent } from '../../../lib/icon-context'
-import { MorphSurface } from '../../../lib/morph-layers'
-import { isDisabledRow, popupScrollAreaClass, popupViewportClass } from '../../../lib/popup'
-import { RowOrderContext, useRowOrder, useRowSlot } from '../../../lib/row-order'
-import { shapeMap, useShape } from '../../../lib/shape-context'
-import { type SizeVariant, useSize } from '../../../lib/size-context'
-import { type SlotProps, slotId, slotRender } from '../../../lib/slot'
-import { spring } from '../../../lib/springs'
-import { SURFACE_BG, SURFACE_SHADOW } from '../../../lib/surface-classes'
-import { SurfaceProvider, useSurface } from '../../../lib/surface-context'
-import { useFluidHover, useRegisterFluidHoverItem } from '../../../lib/use-fluid-hover'
-import { useKeyboardNavGate } from '../../../lib/use-keyboard-nav-gate'
-import { inPlaceOffset, type MorphOrigin, opensInPlace, useMorph, useMorphOrigin } from '../../../lib/use-morph'
-import { cn } from '../../../lib/utils'
-import { ScrollArea } from '../../../primitives/scroll-area'
-import { SizeProvider } from '../../../primitives/sizes'
-import { triggerVariants } from './variants'
-
-// ---------------------------------------------------------------------------
-// Select context
-//
-// Built on Base UI's Select primitive, which owns positioning (collision
-// flipping, anchor tracking), dismissal (outside press, focus-out, Escape
-// nesting inside dialogs), list keyboard navigation + typeahead, combobox
-// ARIA, and the hidden form input. This layer keeps the
-// fluid-hover overlays, the morph open/close animation (lib/use-morph.ts),
-// and the animated checkmark.
-// ---------------------------------------------------------------------------
-
-// How long a selection holds the popup open before closing, so the
-// acknowledgment — the checkmark drawing in and the selected background
-// springing to the picked row — is visible instead of being cut off by the
-// ~60ms close fade. Escape and outside presses still close immediately.
-const selectionAckMs = 300
-
-interface SelectContextValue {
-  value: string
-  open: boolean
-  origin: React.RefObject<MorphOrigin>
-  /** Local: whether the picked row's label is plain text (trimmed and truncated) or a node (laid out as is). */
-  textLabel: boolean
-}
-
-const SelectContext = createContext<SelectContextValue | null>(null)
-
-function useSelectContext() {
-  const ctx = useContext(SelectContext)
-  if (!ctx) throw new Error('Select compound components must be inside <Select>')
-  return ctx
-}
-
-// Content context for fluid hover
-interface SelectContentContextValue {
-  registerItem: (index: number, element: HTMLElement | null) => void
-  activeIndex: number | null
-  checkedIndex?: number
-}
-
-const SelectContentContext = createContext<SelectContentContextValue | null>(null)
-
-// ---------------------------------------------------------------------------
-// Select (root)
-// ---------------------------------------------------------------------------
-
-// The trigger follows the global pill/rounded shape; the popup does not.
-// Like Dropdown and Combobox, the list keeps the smaller "rounded" radii
-// whatever the rest of the UI is shaped: pill corners on a popover distort
-// its padding and break the concentric fit of the rows' hover and selection
-// backgrounds inside it.
-const popupShape = shapeMap.rounded
-
-// An element's ref: `props.ref` on React 19, `element.ref` on 18. Reading `element.ref` warns on 19, so it
-// is only touched when `props.ref` is absent (React 18 never has it).
-function elementRef(el: ReactElement | undefined): Ref<HTMLDivElement> | undefined {
-  if (!el) return undefined
-  // React 19 keeps the ref in props, React 18 on the element; each warns when read the other way.
-  if (parseInt(version, 10) >= 19) return (el.props as { ref?: Ref<HTMLDivElement> }).ref
-  return (el as unknown as { ref?: Ref<HTMLDivElement> }).ref
-}
-
-const ownChildren = (el: ReactElement) => (el.props as { children?: ReactNode }).children
-
-// With `asChild` a row's children are the element that becomes the row, and its own children are
-// the label; a `render` element's own children are the label when the row has none.
-function itemLabel(asChild: boolean | undefined, render: ReactElement | undefined, children: ReactNode) {
-  if (asChild && isValidElement(children)) return ownChildren(children)
-  return children === undefined && render ? ownChildren(render) : children
-}
-
-/**
- * Walk the children tree collecting `{ value, label }` pairs from SelectItem
- * elements. Passed to Base UI's `items` prop so the trigger can resolve the
- * label of an initial value before the popup has ever mounted (items only
- * render while open). The label is the row's children, whatever node they
- * are; a row with none shows its raw value.
- */
-function collectSelectItems(node: ReactNode, out: { value: string; label: ReactNode }[] = []) {
-  Children.forEach(node, child => {
-    if (!isValidElement(child)) return
-    const props = child.props as { value?: unknown; children?: ReactNode; asChild?: boolean; render?: ReactElement }
-    if (typeof props.value === 'string') {
-      out.push({
-        value: props.value,
-        label: itemLabel(props.asChild, props.render, props.children) ?? props.value,
-      })
-    } else if (props.children) {
-      collectSelectItems(props.children, out)
-    }
-  })
-  return out
-}
-
-/** Base UI's change details for the select popup: `reason`, `event`, `trigger`, `cancel()`. */
-type SelectOpenChangeDetails = SelectPrimitive.Root.ChangeEventDetails
-
-interface SelectProps {
-  /** `Select.Trigger` and `Select.Content`. */
-  children: ReactNode
-  /** Controlled selected value. Pair with `onValueChange`. */
-  value?: string
-  /** Uncontrolled default value — the select then keeps the selection itself. */
-  defaultValue?: string
-  /** Called when the selected value changes. */
-  onValueChange?: (value: string) => void
-  /** Controlled open state. Pair with `onOpenChange`. A controlled select follows it exactly: it closes only when you say so, and the 300ms pick acknowledgment is skipped. */
-  open?: boolean
-  /** Uncontrolled initial open state. Defaults to `false`. */
-  defaultOpen?: boolean
-  /** Called when the popup asks to open or close, with Base UI's change details (`reason`, `event`, `trigger`, `cancel()`). Uncontrolled, a pick reports its close once the 300ms acknowledgment ends. */
-  onOpenChange?: (open: boolean, details: SelectOpenChangeDetails) => void
-  /** Disables the entire select. Defaults to `false`. */
-  disabled?: boolean
-  /** Name for form submission (renders a hidden native input). */
-  name?: string
-  /** Marks the select as required in forms. Defaults to `false`. */
-  required?: boolean
-  /** Pins trigger and popup to one step of the size ladder (default 36px, compact 28px — see Sizes). Omitted, both follow the surrounding SizeProvider. */
-  size?: SizeVariant
-}
-
-/**
- * An animated select menu: fluid hover on the rows, a popup that oozes out of
- * its trigger, and a checkmark that draws itself as the selection lands.
- *
- * Built on Base UI's Select — positioning and collision flipping, dismissal,
- * typeahead, combobox ARIA and the hidden form input all come from the
- * primitive. This layer adds the magnetic hover background, the selected
- * background that springs from the old row to the picked one, a keyboard
- * focus ring that only appears once you actually use the keyboard, and the
- * popup's open and close through the shared morph (see Morph), goo by
- * default. A pick holds the popup open for 300ms so that acknowledgment is
- * seen; Escape and outside presses close at once. Uncontrolled through
- * `defaultValue`, controlled through `value` + `onValueChange`. The popup's
- * open state follows the same rule: `defaultOpen`, or `open` +
- * `onOpenChange(open, details)`. A controlled `open` is obeyed exactly, so
- * a handler may refuse a close; it skips the 300ms hold, which only runs
- * while the select keeps its own open state.
- *
- * Rows need no `index`: they take their place in document order, inside a
- * `Select.Group` or out of a `map`. The trigger shows the picked row's
- * label, whatever node it is (an icon and text, a badge), and a row's
- * `textValue` is what typeahead matches when its children aren't plain text.
- *
- * Statics:
- * - `Select.Trigger` — the field: `variant`, `icon`, `placeholder`, `error`;
- *   children replace its value slot (a `Select.Value`). `render` / `asChild`
- *   swap the button for your own element (it brings its own look); an
- *   element with children of its own drops the icon, `placeholder` and
- *   chevron too, one without keeps them;
- *   `wrapperClassName` styles the div that holds the `error` message.
- * - `Select.Value` — the value slot: the picked row's label, else the muted
- *   `placeholder`.
- * - `Select.Content` — the popup: `side`, `align`, `sideOffset`, `alignOffset`,
- *   `collisionPadding`, `finalFocus`, the morph options `from`, `effect`,
- *   `hideSource`, `tier`, and HTML attributes (`id`, `aria-*`, `data-*`) for
- *   the popup element.
- * - `Select.Item` — one row: `value`, optional `index`, `textValue`, `icon`,
- *   `disabled`; its children are the label. `render` / `asChild` make the
- *   row your own element, a link for instance.
- * - `Select.Group`, `Select.Label`, `Select.Separator` — sections, their
- *   captions and hairlines between them.
- *
- * @example {@include ./examples.mdx}
- */
-function Select({
-  children,
-  value,
-  defaultValue,
-  onValueChange,
-  open: openProp,
-  defaultOpen = false,
-  onOpenChange,
-  disabled = false,
-  name,
-  required,
-  size,
-}: SelectProps) {
-  const [internalValue, setInternalValue] = useState(defaultValue ?? '')
-  const [internalOpen, setInternalOpen] = useState(defaultOpen)
-  const { origin, capture } = useMorphOrigin()
-  const currentValue = value !== undefined ? value : internalValue
-  const controlledOpen = openProp !== undefined
-  const open = controlledOpen ? openProp : internalOpen
-
-  const items = useMemo(() => collectSelectItems(children), [children])
-
-  const handleValueChange = useCallback(
-    (next: string | null) => {
-      const v = next ?? ''
-      if (value === undefined) setInternalValue(v)
-      onValueChange?.(v)
-    },
-    [value, onValueChange],
-  )
-
-  const ackTimeoutRef = useRef<number | null>(null)
-  const cancelAckClose = useCallback(() => {
-    if (ackTimeoutRef.current !== null) {
-      clearTimeout(ackTimeoutRef.current)
-      ackTimeoutRef.current = null
-    }
-  }, [])
-  useEffect(() => cancelAckClose, [cancelAckClose])
-
-  const onOpenChangeRef = useRef(onOpenChange)
-  onOpenChangeRef.current = onOpenChange
-  const controlledOpenRef = useRef(controlledOpen)
-  controlledOpenRef.current = controlledOpen
-
-  // Picking an item acknowledges before closing: the close is deferred by
-  // selectionAckMs so the checkmark draw and the selected background's spring
-  // to the picked row are seen. Every other close reason (Escape, outside
-  // press, trigger toggle, focus-out) closes immediately and cancels any
-  // pending acknowledgment; re-picking within the window restarts it. A
-  // controlled `open` is the caller's: every request is reported at once and
-  // nothing is deferred.
-  const handleOpenChange = useCallback(
-    (nextOpen: boolean, eventDetails: SelectOpenChangeDetails) => {
-      if (nextOpen) capture(eventDetails)
-      cancelAckClose()
-      if (!nextOpen && eventDetails.reason === 'item-press' && !controlledOpenRef.current) {
-        ackTimeoutRef.current = window.setTimeout(() => {
-          ackTimeoutRef.current = null
-          setInternalOpen(false)
-          onOpenChangeRef.current?.(false, eventDetails)
-        }, selectionAckMs)
-        return
-      }
-      if (!controlledOpenRef.current) setInternalOpen(nextOpen)
-      onOpenChangeRef.current?.(nextOpen, eventDetails)
-    },
-    [cancelAckClose, capture],
-  )
-
-  const picked = items.find(item => item.value === currentValue)?.label
-  const textLabel = picked === undefined || typeof picked === 'string' || typeof picked === 'number'
-  const ctx = useMemo(() => ({ value: currentValue, open, origin, textLabel }), [currentValue, open, origin, textLabel])
-
-  // A size prop pins the whole compound (trigger + portalled popup — React
-  // context crosses portals) to one step of the ladder.
-  const root = (
-    <SelectContext.Provider value={ctx}>
-      <SelectPrimitive.Root
-        // Always controlled; "" (no selection) maps to Base UI's null.
-        value={currentValue === '' ? null : currentValue}
-        onValueChange={handleValueChange}
-        open={open}
-        onOpenChange={handleOpenChange}
-        items={items}
-        disabled={disabled}
-        name={name}
-        required={required}
-        // Non-modal: the page keeps scrolling and the Positioner tracks the
-        // anchor, so the popup follows its trigger instead of detaching.
-        modal={false}
-      >
-        {children}
-      </SelectPrimitive.Root>
-    </SelectContext.Provider>
-  )
-
-  return size ? <SizeProvider size={size}>{root}</SizeProvider> : root
-}
-
-Select.displayName = 'Select'
-
-// ---------------------------------------------------------------------------
-// SelectValue
-// ---------------------------------------------------------------------------
-
-interface SelectValueProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'placeholder'> {
-  /** Shown, muted, while nothing is selected. Defaults to `"Select…"`. */
-  placeholder?: ReactNode
-  /** Extra classes for the value text. */
-  className?: string
-}
-
-/** The trigger's value slot: the picked row's label (its children), else the muted placeholder. */
-const SelectValue = forwardRef<HTMLSpanElement, SelectValueProps>(
-  ({ placeholder = 'Select…', className, ...props }, ref) => {
-    const { textLabel } = useSelectContext()
-    return (
-      <SelectPrimitive.Value
-        ref={ref}
-        placeholder={placeholder}
-        // py-1/-my-1: truncate's overflow:hidden clips at the padding
-        // box, and the trimmed box excludes ascenders/descenders — the
-        // padding gives glyphs room while the negative margin keeps the
-        // trimmed layout box.
-        className={cn(
-          'min-w-0 flex-1 text-left data-[placeholder]:text-muted-foreground',
-          // A node label (a badge, an icon and text) keeps its own box: trimming
-          // and clipping it would cut it top and bottom.
-          textLabel ? 'truncate [text-box:trim-both_cap_alphabetic] py-1 -my-1' : 'flex items-center',
-          className,
-        )}
-        {...props}
-      />
-    )
-  },
-)
-
-SelectValue.displayName = 'SelectValue'
-
-// ---------------------------------------------------------------------------
-// SelectTrigger
-// ---------------------------------------------------------------------------
-
-interface SelectTriggerProps extends Omit<SlotProps, 'children' | 'placeholder'>, VariantProps<typeof triggerVariants> {
-  /** Replaces the built-in value slot, typically with a `Select.Value` (shadcn's `<SelectValue placeholder>`). The icon and chevron stay. With `asChild`, the single child element that becomes the trigger instead, and `render` takes an element the same way: that element replaces the whole field. If it has children of its own, they are the entire body, so the `icon`, `placeholder` and chevron are not rendered and the field look, including the `error` border tint, is not applied (the `error` message and `aria-invalid` remain). If it has none, it still gets the value slot, `icon` and chevron, unstyled. */
-  children?: ReactNode
-  /** Visual style of the trigger. Defaults to `"bordered"`. */
-  variant?: 'bordered' | 'borderless'
-  /** Optional icon displayed before the value. */
-  icon?: IconComponent
-  /** Text shown when no value is selected. Defaults to `"Select…"`. */
-  placeholder?: string
-  /** Error message shown below the trigger; also tints the border and sets `aria-invalid`. */
-  error?: string
-  /** Size override for the trigger alone. Prefer the `size` prop on `<Select>` (or a surrounding SizeProvider) so the popup matches. */
-  size?: SizeVariant
-  /** Extra classes for the trigger button. The field has a minimum width of 160px (128px compact); pass `min-w-0` to lift that floor. */
-  className?: string
-  /** Extra classes for the div around the trigger, which holds the `error` message under it. It is a plain flex column, so `contents` makes it vanish from the layout. */
-  wrapperClassName?: string
-}
-
-const SelectTrigger = forwardRef<HTMLButtonElement, SelectTriggerProps>(
-  (
-    {
-      className,
-      wrapperClassName,
-      variant,
-      icon: Icon,
-      placeholder = 'Select…',
-      error,
-      size,
-      render,
-      asChild,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    const shape = useShape()
-    const sizeClasses = useSize(size)
-    const compact = sizeClasses.variant === 'compact'
-    // The element a `render` / `asChild` caller brings is the whole trigger, look included: it gets only
-    // the `group` class, so the field's border, size, padding and `error` border tint are not applied
-    // (the `error` message below it and `aria-invalid` still are). What goes inside depends on the
-    // element's own children:
-    //  - it has some: they are the whole body and replace the field's, so the icon, `placeholder` and
-    //    chevron are not rendered (add a `Select.Value` among them to show the picked label);
-    //  - it has none: it gets the field's body, `icon` (if any), value slot with `placeholder`, and
-    //    chevron, in an unstyled trigger.
-    const el = slotRender(render, asChild, asChild ? children : undefined)
-    const content = el ? itemLabel(asChild, render, children) : children
-
-    return (
-      <div className={cn('flex flex-col gap-1', wrapperClassName)}>
-        <SelectPrimitive.Trigger
-          ref={ref}
-          render={el}
-          aria-invalid={!!error || undefined}
-          className={
-            el
-              ? cn('group', className)
-              : cn(
-                  triggerVariants({ variant }),
-                  sizeClasses.control,
-                  sizeClasses.text,
-                  sizeClasses.px,
-                  sizeClasses.gap,
-                  compact ? 'min-w-[128px]' : 'min-w-[160px]',
-                  shape.input,
-                  error && 'border-destructive/50 hover:border-destructive/50',
-                  className,
-                )
-          }
-          {...props}
-          id={slotId(el, props.id)}
-        >
-          <span className={cn('flex items-center min-w-0 flex-1', sizeClasses.gap)}>
-            {Icon && (
-              <Icon
-                size={sizeClasses.icon}
-                strokeWidth={1.5}
-                className="shrink-0 text-muted-foreground transition-[color,stroke-width] duration-fast group-hover:text-foreground group-hover:stroke-[2]"
-              />
-            )}
-            {content ?? <SelectValue placeholder={placeholder} />}
-          </span>
-
-          <svg
-            width={sizeClasses.icon}
-            height={sizeClasses.icon}
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth={2}
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            className="shrink-0 text-muted-foreground transition-colors duration-fast group-hover:text-foreground"
-          >
-            <path d="M6 9l6 6 6-6" />
-          </svg>
-        </SelectPrimitive.Trigger>
-        {error && <span className="text-caption text-destructive pl-3">{error}</span>}
-      </div>
-    )
-  },
-)
-
-SelectTrigger.displayName = 'SelectTrigger'
-
-// ---------------------------------------------------------------------------
-// SelectContent
-// ---------------------------------------------------------------------------
-
-type SelectPositionerProps = ComponentProps<typeof SelectPrimitive.Positioner>
-type SelectPopupProps = ComponentProps<typeof SelectPrimitive.Popup>
-
-// Handlers the popup drives itself (fluid hover, the keyboard ring gate): not passed through.
-type PopupOwnHandlers =
-  | 'onKeyDownCapture'
-  | 'onMouseEnter'
-  | 'onMouseMove'
-  | 'onMouseLeave'
-  | 'onClick'
-  | 'onFocus'
-  | 'onBlur'
-
-interface SelectContentProps extends Omit<HTMLAttributes<HTMLDivElement>, PopupOwnHandlers | 'className' | 'children'> {
-  /** Where the menu grows from (see Morph): the trigger, the pointer, its own center, a viewport edge, or a ref to any element. Defaults to `'trigger'`. */
-  from?: 'trigger' | 'pointer' | 'center' | 'top' | 'right' | 'bottom' | 'left' | React.RefObject<HTMLElement | null>
-  /** How it grows (see Morph): with the liquid goo neck, a plain morph, a slide or a fade. Defaults to `'goo'`. */
-  effect?: 'goo' | 'morph' | 'slide' | 'fade'
-  /** Hide the trigger while open, so it reads as turning into the menu. Defaults to `false`. */
-  hideSource?: boolean
-  /** Spring tier of a plain morph, slide or fade; goo runs on its own `spring.goo`. Defaults to `'moderate'`. */
-  tier?: 'moderate' | 'slow'
-  /** Side of the trigger the menu prefers; it flips when there is no room. Defaults to `"bottom"`. */
-  side?: 'top' | 'bottom' | 'left' | 'right'
-  /** Alignment against the trigger. Defaults to `"start"`. */
-  align?: 'start' | 'center' | 'end'
-  /** Gap to the trigger, in px. Ignored when the menu opens in place over the trigger (`effect="morph"` with `hideSource`). Defaults to `6`. */
-  sideOffset?: number
-  /** Shift along the aligned edge in px, after `align` (a number, or Base UI's function of side, align and sizes). Defaults to `0`. */
-  alignOffset?: SelectPositionerProps['alignOffset']
-  /** Space kept between the menu and the edge of its collision boundary, in px or per side. Defaults to `5`. */
-  collisionPadding?: SelectPositionerProps['collisionPadding']
-  /** Where focus goes when the menu closes: a ref, `false` to leave it, `true` for the default, or a function of how it closed (`'mouse'`, `'touch'`, `'pen'`, `'keyboard'`). Defaults to the trigger. */
-  finalFocus?: SelectPopupProps['finalFocus']
-  /** Additional classes for the menu container. */
-  className?: string
-  /** `Select.Item`, `Select.Group`, `Select.Label`, `Select.Separator`. */
-  children: ReactNode
-}
-
-const SelectContent = forwardRef<HTMLDivElement, SelectContentProps>(
-  (
-    {
-      from,
-      effect,
-      hideSource,
-      tier = 'moderate',
-      side = 'bottom',
-      align = 'start',
-      sideOffset = 6,
-      alignOffset,
-      collisionPadding,
-      finalFocus,
-      className,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    const { open, value, origin } = useSelectContext()
-    const rowOrder = useRowOrder()
-    const morph = useMorph(open, origin, {
-      from,
-      effect,
-      hideSource,
-      tier,
-      // A custom `finalFocus` places focus itself; the morph's own return to the trigger would undo it.
-      returnFocus: typeof finalFocus === 'boolean' ? finalFocus : finalFocus === undefined,
-    })
-    useImperativeHandle(ref, () => morph.popup as HTMLDivElement, [morph.popup])
-    // Lifts 2 levels off its substrate with a fixed shadow (see Elevated).
-    const level = Math.min(useSurface() + 2, 8)
-    const shape = popupShape
-    const containerRef = useRef<HTMLDivElement>(null)
-
-    const hover = useFluidHover(containerRef, { isItemDisabled: isDisabledRow })
-    const { activeIndex, setActiveIndex, itemRects, isMeasured, handlers, registerItem, remeasure } = hover
-
-    const [focusedIndex, setFocusedIndex] = useState<number | null>(null)
-
-    // Keyboard focus ring gate: seeded from the trigger's :focus-visible at
-    // open, earned by navigation keys inside the popup.
-    const { keyboardNavRef, trackKeyboardNav } = useKeyboardNavGate(open)
-    const [checkedIndex, setCheckedIndex] = useState<number | undefined>(undefined)
-
-    // Fresh rects once per open. Measuring is the hook's job — it owns the
-    // one coalesced pass that item registration and container resizes both
-    // feed into, and a second pass from elsewhere is what used to land a
-    // corrected rect on an already-mounted overlay. The popup keeps its items
-    // registered while it sits hidden between opens, so registration alone
-    // would never trigger a fresh pass on reopen.
-    useEffect(() => {
-      if (!open) return
-      remeasure()
-    }, [open, remeasure])
-
-    // Detect the checked row. Deliberately does NOT remeasure on a value
-    // change while open: the rows haven't moved, so the published rects stay
-    // trustworthy and only checkedIndex switches — which lets the selected
-    // marker spring from the old row to the picked one (the selection
-    // acknowledgment) instead of unmounting and snapping.
-    useEffect(() => {
-      if (!open) return
-      // Double rAF: first waits for React commit, second for layout
-      let inner: number
-      const outer = requestAnimationFrame(() => {
-        inner = requestAnimationFrame(() => {
-          const container = containerRef.current
-          if (container) {
-            // The row's own index: rows may be numbered out of DOM order (an explicit `index`).
-            const row = Array.from(container.querySelectorAll<HTMLElement>('[data-fluid-hover-index]')).find(
-              el => el.getAttribute('data-value') === value,
-            )
-            setCheckedIndex(row ? Number(row.getAttribute('data-fluid-hover-index')) : undefined)
-          }
-        })
-      })
-      return () => {
-        cancelAnimationFrame(outer)
-        cancelAnimationFrame(inner)
-      }
-    }, [open, value])
-
-    // Reset every overlay index as the close begins. checkedIndex otherwise
-    // lags one open behind value (picking an item closes the popup before the
-    // effect above re-syncs it), and a leftover activeIndex is worse: Base UI
-    // keeps the popup mounted through the exit tween, so on reopen the hover
-    // pill would still be sitting on the previously active row and spring from
-    // there to the row that auto-focus lands on.
-    useEffect(() => {
-      if (open) return
-      setCheckedIndex(undefined)
-      setActiveIndex(null)
-      setFocusedIndex(null)
-    }, [open, setActiveIndex])
-
-    // Overlays read rects only once the hook reports the item set fully
-    // measured. Positioning one from an incomplete pass mounts it at the wrong
-    // row, and the correcting pass then springs it across the list.
-    const checkedRect = isMeasured && checkedIndex != null ? itemRects[checkedIndex] : null
-    const focusRect = isMeasured && focusedIndex !== null ? itemRects[focusedIndex] : null
-
-    const contentCtx = useMemo(
-      () => ({ registerItem, activeIndex, checkedIndex }),
-      [registerItem, activeIndex, checkedIndex],
-    )
-
-    return (
-      <SelectPrimitive.Portal>
-        <SelectPrimitive.Positioner
-          side={side}
-          align={align}
-          sideOffset={opensInPlace({ effect, hideSource }) ? inPlaceOffset : sideOffset}
-          alignOffset={alignOffset}
-          collisionPadding={collisionPadding}
-          alignItemWithTrigger={false}
-          className="z-50 outline-none"
-        >
-          <SelectContentContext.Provider value={contentCtx}>
-            <SelectPrimitive.Popup
-              ref={morph.popupRef}
-              finalFocus={finalFocus}
-              {...props}
-              // Capture phase: the primitive moves focus during its own keydown
-              // handling, so the nav flag must be set before then.
-              onKeyDownCapture={trackKeyboardNav}
-              onMouseEnter={() => {
-                handlers.onMouseEnter()
-                setFocusedIndex(null)
-              }}
-              onMouseMove={handlers.onMouseMove}
-              onMouseLeave={handlers.onMouseLeave}
-              onClick={handlers.onClick}
-              onFocus={e => {
-                const indexAttr = (e.target as HTMLElement)
-                  .closest('[data-fluid-hover-index]')
-                  ?.getAttribute('data-fluid-hover-index')
-                if (indexAttr != null) {
-                  const idx = Number(indexAttr)
-                  setActiveIndex(idx)
-                  setFocusedIndex(
-                    keyboardNavRef.current && (e.target as HTMLElement).matches(':focus-visible') ? idx : null,
-                  )
-                }
-              }}
-              onBlur={e => {
-                // The popup itself takes focus when the pointer leaves a row; only a
-                // departure from the whole popup ends the hover session.
-                if (e.currentTarget.contains(e.relatedTarget as Node)) return
-                setFocusedIndex(null)
-                setActiveIndex(null)
-              }}
-              className="relative select-none outline-none"
-            >
-              <SurfaceProvider value={level}>
-                <MorphSurface
-                  morph={morph}
-                  bg={SURFACE_BG[level]}
-                  shadow={SURFACE_SHADOW[3]}
-                  radius={shape.container}
-                  className={cn(
-                    // min-w tracks the trigger via the Positioner's --anchor-width
-                    // var, matching the pre-migration minWidth: triggerRect.width.
-                    `flex flex-col min-w-[var(--anchor-width)] max-h-[min(300px,var(--available-height))] overflow-hidden ${shape.container}`,
-                    className,
-                  )}
-                >
-                  {/* The list scrolls inside a ScrollArea; this wrapper is the rows'
-                    offsetParent, so the overlays scroll with them. */}
-                  <ScrollArea
-                    className={popupScrollAreaClass}
-                    viewportClassName={cn(popupViewportClass, 'scroll-fade')}
-                  >
-                    <div ref={containerRef} className="relative flex flex-col p-1">
-                      {/* The three overlays are torn down as the close begins rather
-                    than exit-animated, because an overlay still mounted when the
-                    popup reopens is one AnimatePresence re-adopts under its old
-                    key: `initial` never runs again, so it keeps the position of the
-                    row it had before and animates from there to the new one. The
-                    popup's own fade covers their disappearance. */}
-                      {/* Selected background */}
-                      {open && (
-                        <AnimatePresence>
-                          {checkedRect && (
-                            <motion.div
-                              className={`absolute ${shape.bg} bg-active pointer-events-none`}
-                              // Position lives in `animate` so an in-session value
-                              // change springs the marker to the picked row (the
-                              // selection acknowledgment). Safe against the reopen
-                              // slide: the `open &&` teardown means no marker
-                              // survives a close, and a fresh mount with
-                              // initial={false} renders snapped at these values.
-                              initial={false}
-                              animate={{
-                                top: checkedRect.top,
-                                left: checkedRect.left,
-                                width: checkedRect.width,
-                                height: checkedRect.height,
-                                opacity: 1,
-                              }}
-                              exit={{ opacity: 0, transition: spring.moderate.exit }}
-                              transition={{
-                                ...spring.moderate,
-                                opacity: { duration: spring.fast.duration },
-                              }}
-                            />
-                          )}
-                        </AnimatePresence>
-                      )}
-
-                      {/* Hover background */}
-                      <FluidHoverHighlight hover={hover} hidden={!open} className={shape.bg} />
-
-                      {/* Focus ring */}
-                      {open && <FocusRing rect={focusRect} shape="rounded" />}
-
-                      <RowOrderContext.Provider value={rowOrder}>{children}</RowOrderContext.Provider>
-                    </div>
-                  </ScrollArea>
-                </MorphSurface>
-              </SurfaceProvider>
-            </SelectPrimitive.Popup>
-          </SelectContentContext.Provider>
-        </SelectPrimitive.Positioner>
-      </SelectPrimitive.Portal>
-    )
-  },
-)
-
-SelectContent.displayName = 'SelectContent'
-
-// ---------------------------------------------------------------------------
-// SelectItem
-// ---------------------------------------------------------------------------
-
-interface SelectItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
-  /** The element that becomes the row, e.g. a router link (it must forward its ref); it gets the row's look and behaviour. Its children fill the label unless `children` is given. */
-  render?: ReactElement
-  /** Make the single child element the row, its own children being the label. Both spellings work. Defaults to `false`. */
-  asChild?: boolean
-  /** Optional icon displayed before the label. */
-  icon?: IconComponent
-  /** Position among the menu's rows — what fluid hover measures rows by. Defaults to the row's place in document order. */
-  index?: number
-  /** Unique value for this option. */
-  value: string
-  /** The row's text for typeahead, when its children are not a plain string. */
-  textValue?: string
-  /** Disables this individual item. Defaults to `false`. */
-  disabled?: boolean
-  /** The row label. A string label is also what the trigger shows for this value. With `asChild`, the single child element that becomes the row. */
-  children?: ReactNode
-}
-
-const SelectItem = forwardRef<HTMLDivElement, SelectItemProps>(
-  (
-    {
-      className,
-      children: childrenProp,
-      render,
-      asChild,
-      icon: Icon,
-      value,
-      index: indexProp,
-      textValue,
-      disabled = false,
-      ...props
-    },
-    ref,
-  ) => {
-    const el = slotRender(render, asChild, asChild ? childrenProp : undefined)
-    const children = itemLabel(asChild, render, childrenProp)
-    const selectCtx = useSelectContext()
-    const contentCtx = useContext(SelectContentContext)
-    const internalRef = useRef<HTMLDivElement>(null)
-    const shape = popupShape
-    const sizeClasses = useSize()
-    const compact = sizeClasses.variant === 'compact'
-    const hasMounted = useRef(false)
-
-    useEffect(() => {
-      hasMounted.current = true
-    }, [])
-
-    // Register with fluid hover. Depends on the (stable) registerItem
-    // rather than the content context, which is rebuilt on every activeIndex
-    // change: keying the effect to the whole context re-ran it per mousemove,
-    // unregistering and re-registering every row and so keeping the hook's
-    // measurement permanently unsettled while the pointer moved.
-    const registerItem = contentCtx?.registerItem
-    const { index } = useRowSlot(internalRef, indexProp)
-    useRegisterFluidHoverItem(registerItem, index, internalRef)
-
-    const isActive = contentCtx?.activeIndex === index
-    const isChecked = selectCtx.value === value
-    const skipAnimation = !hasMounted.current
-
-    const rowProps = {
-      ref: (node: HTMLDivElement | null) => {
-        ;(internalRef as React.MutableRefObject<HTMLDivElement | null>).current = node
-        for (const r of [ref, elementRef(el)]) {
-          if (typeof r === 'function') r(node)
-          else if (r) (r as React.MutableRefObject<HTMLDivElement | null>).current = node
-        }
-      },
-      'data-fluid-hover-index': index,
-      'data-value': value,
-      className: cn(
-        // Fixed height (was py-2 around a 19.5px line box ≈ 35.5px) so
-        // the text-box trim on the item text doesn't shrink the row.
-        // shrink-0: the popup is a max-height flex column, so without it
-        // a long list compresses rows to fit instead of scrolling.
-        `relative z-10 flex ${sizeClasses.control} shrink-0 items-center ${sizeClasses.gap} ${shape.item} ${sizeClasses.itemPx} ${sizeClasses.text} cursor-pointer outline-none select-none`,
-        'transition-[color] duration-fast',
-        isActive || isChecked ? 'text-foreground' : 'text-muted-foreground',
-        disabled && 'opacity-50 pointer-events-none',
-        className,
-      ),
-      ...props,
-    }
-
-    return (
-      <SelectPrimitive.Item
-        value={value}
-        disabled={disabled}
-        label={textValue ?? (typeof children === 'string' ? children : undefined)}
-        render={
-          el ? (
-            cloneElement(el, {
-              ...rowProps,
-              className: cn(rowProps.className, (el.props as { className?: string }).className),
-            })
-          ) : (
-            <div {...rowProps} />
-          )
-        }
-      >
-        {Icon && (
-          <Icon
-            size={sizeClasses.icon}
-            strokeWidth={isActive || isChecked ? 2 : 1.5}
-            className="shrink-0 transition-[color,stroke-width] duration-fast"
-          />
-        )}
-
-        <SelectPrimitive.ItemText
-          // py-1/-my-1 keeps truncate's overflow:hidden from clipping
-          // ascenders/descenders outside the trimmed box.
-          render={
-            <span
-              className={cn(
-                'flex-1 min-w-0',
-                // Nodes keep their own box; only text is trimmed and truncated.
-                typeof children === 'string' || typeof children === 'number'
-                  ? 'truncate [text-box:trim-both_cap_alphabetic] py-1 -my-1'
-                  : 'flex items-center',
-              )}
-            />
-          }
-        >
-          {children}
-        </SelectPrimitive.ItemText>
-
-        {/* Always-rendered fixed slot so the check appearing/disappearing
-            never changes the row's intrinsic width — without it the whole
-            popup resizes when a selection lands. */}
-        <span aria-hidden className={cn('shrink-0', compact ? 'w-3.5 h-3.5' : 'w-4 h-4')}>
-          <AnimatePresence>
-            {isChecked && (
-              <motion.svg
-                key="check"
-                width={sizeClasses.icon}
-                height={sizeClasses.icon}
-                viewBox="0 0 24 24"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth={2}
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                className="text-foreground"
-                initial={{ opacity: 1 }}
-                animate={{ opacity: 1 }}
-                exit={{ opacity: 1 }}
-              >
-                <motion.path
-                  d="M4 12L9 17L20 6"
-                  initial={{ pathLength: skipAnimation ? 1 : 0 }}
-                  animate={{
-                    pathLength: 1,
-                    transition: { duration: spring.fast.duration, ease: 'easeOut' },
-                  }}
-                  exit={{
-                    pathLength: 0,
-                    transition: { duration: 0.04, ease: 'easeIn' },
-                  }}
-                />
-              </motion.svg>
-            )}
-          </AnimatePresence>
-        </span>
-      </SelectPrimitive.Item>
-    )
-  },
-)
-
-SelectItem.displayName = 'SelectItem'
-
-// ---------------------------------------------------------------------------
-// SelectGroup + SelectLabel + SelectSeparator
-// ---------------------------------------------------------------------------
-
-const SelectGroup = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
-  ({ children, className, ...props }, ref) => (
-    <div ref={ref} role="group" className={className} {...props}>
-      {children}
-    </div>
-  ),
-)
-
-SelectGroup.displayName = 'SelectGroup'
-
-const SelectLabel = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => {
-  // Group labels are the caption role of the type scale — see /docs/sizes.
-  const compact = useSize().variant === 'compact'
-  return (
-    <div
-      ref={ref}
-      className={cn(
-        'px-2 py-1.5 shrink-0 text-muted-foreground',
-        compact ? 'text-caption-compact' : 'text-caption',
-        className,
-      )}
-      {...props}
-    />
-  )
-})
-
-SelectLabel.displayName = 'SelectLabel'
-
-const SelectSeparator = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => (
-  <div ref={ref} role="separator" className={cn('my-1 -mx-1 h-px shrink-0 bg-border/60', className)} {...props} />
-))
-
-SelectSeparator.displayName = 'SelectSeparator'
-
-// Compound statics: `<Select.Trigger>`, `<Select.Item>`, … Assigned directly
-// (not through Object.assign) so TypeScript's expando inference types them
-// onto the root function declaration.
-Select.Trigger = SelectTrigger
-Select.Value = SelectValue
-Select.Content = SelectContent
-Select.Item = SelectItem
-Select.Group = SelectGroup
-Select.Label = SelectLabel
-Select.Separator = SelectSeparator
-
-// ---------------------------------------------------------------------------
-// Exports
-// ---------------------------------------------------------------------------
-
-export type {
-  SelectContentProps,
-  SelectItemProps,
-  SelectOpenChangeDetails,
-  SelectProps,
-  SelectTriggerProps,
-  SelectValueProps,
-}
-export {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectLabel,
-  SelectSeparator,
-  SelectTrigger,
-  SelectValue,
-  triggerVariants,
-}
-
-export default Select