@duro-app/ui 5.12.0 → 5.14.0

package/src/components/Combobox/Combobox.native.tsx

@@ -0,0 +1,295 @@
+import {
+  createContext,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
+import {Pressable} from 'react-native'
+import {html} from 'react-strict-dom'
+import {DURATION_MS} from '@duro-app/tokens/keys'
+import {styles} from './styles.css'
+import {nativeStyles} from './native.css'
+import {matchesQuery, useComboboxState} from './comboboxState'
+import {Drawer} from '../Drawer/Drawer'
+import {Listbox} from '../Listbox/Listbox'
+import {sheetStyles} from '../Listbox/native.css'
+import {Button} from '../Button/Button'
+import {Icon} from '../Icon/Icon'
+import {Chevron} from '../SideNav/Chevron'
+import {focusForAccessibility} from '../../shared/accessibilityFocus'
+import {focusInput} from '../../shared/focusInput'
+import {textOf} from '../../shared/textOf'
+
+/** The picker sheet's detents (plan N0, Decision 5); a Combobox opens at large. */
+const SNAP_POINTS = ['medium', 'large'] as const
+
+interface NativeComboboxContextValue {
+  value: string | null
+  open: boolean
+  setOpen: (open: boolean) => void
+  choose: (value: string) => void
+  labels: Record<string, string>
+  registerLabel: (value: string, label: string) => void
+  /** The labels of the Items rendered now, by value: what Empty matches against */
+  items: ReadonlyMap<string, string>
+  registerItem: (value: string, label: string) => () => void
+  /** What is typed in the sheet's search field */
+  query: string
+  setQuery: (query: string) => void
+  /** The field's placeholder, also the search field's */
+  placeholder: string | undefined
+  setPlaceholder: (placeholder: string | undefined) => void
+  listboxId: string
+  triggerRef: RefObject<unknown>
+}
+
+const ComboboxContext = createContext<NativeComboboxContextValue | null>(null)
+
+function useCombobox() {
+  const ctx = useContext(ComboboxContext)
+  if (!ctx) throw new Error('Combobox compound components must be used within Combobox.Root')
+  return ctx
+}
+
+/** True while Popup renders its items unseen, so each registers its label. */
+const CollectContext = createContext(false)
+
+interface RootProps {
+  /** The web's hidden form input; native has no form post. */
+  name?: string
+  defaultValue?: string
+  value?: string
+  onValueChange?: (value: string | null) => void
+  /** The field's text: the chosen option's label on native */
+  inputValue?: string
+  onInputChange?: (value: string) => void
+  initialLabels?: Record<string, string>
+  children: ReactNode
+}
+
+/**
+ * Native Combobox (plan N0, Slice C): the field opens a bottom sheet at its
+ * large detent, above the keyboard, with a search field pinned under the
+ * header and focused; the list below filters as you type, and a press picks
+ * an option and closes the sheet (C0 direction A, "Check"). The search text
+ * is the sheet's own and starts empty each time it opens.
+ */
+function Root({
+  defaultValue,
+  value,
+  onValueChange,
+  inputValue,
+  onInputChange,
+  initialLabels,
+  children,
+}: RootProps) {
+  const state = useComboboxState({
+    defaultValue,
+    value,
+    onValueChange,
+    inputValue,
+    onInputChange,
+    initialLabels,
+  })
+  const {open, setOpen, chooseValue} = state
+  const [query, setQuery] = useState('')
+  const [items, setItems] = useState<ReadonlyMap<string, string>>(new Map())
+  const registerItem = useCallback((itemValue: string, label: string) => {
+    setItems((prev) => new Map(prev).set(itemValue, label))
+    return () =>
+      setItems((prev) => {
+        const next = new Map(prev)
+        next.delete(itemValue)
+        return next
+      })
+  }, [])
+  const [placeholder, setPlaceholder] = useState<string | undefined>(undefined)
+  const listboxId = useId()
+  const triggerRef = useRef<unknown>(null)
+
+  const wasOpen = useRef(open)
+  useEffect(() => {
+    if (open !== wasOpen.current) setQuery('')
+    if (wasOpen.current && !open) focusForAccessibility(triggerRef.current, 'Combobox')
+    wasOpen.current = open
+  }, [open])
+
+  const ctx: NativeComboboxContextValue = {
+    value: state.value,
+    open,
+    setOpen,
+    choose: chooseValue,
+    labels: state.labels,
+    registerLabel: state.registerLabel,
+    items,
+    registerItem,
+    query,
+    setQuery,
+    placeholder,
+    setPlaceholder,
+    listboxId,
+    triggerRef,
+  }
+
+  return (
+    <ComboboxContext.Provider value={ctx}>
+      <Drawer.Root
+        open={open}
+        onOpenChange={setOpen}
+        anchor="bottom"
+        snapPoints={SNAP_POINTS}
+        defaultSnapPoint="large"
+      >
+        <html.div style={[styles.root, nativeStyles.nativeFlex]}>{children}</html.div>
+      </Drawer.Root>
+    </ComboboxContext.Provider>
+  )
+}
+
+/**
+ * The closed field: the chosen option's label, or the placeholder. A press
+ * opens the sheet, where the typing happens.
+ */
+function Input({placeholder, children}: {placeholder?: string; children?: ReactNode}) {
+  const {value, labels, open, setOpen, setPlaceholder, triggerRef} = useCombobox()
+  const display = value ? (labels[value] ?? value) : null
+
+  useEffect(() => {
+    setPlaceholder(placeholder)
+  }, [placeholder, setPlaceholder])
+
+  return (
+    <Pressable
+      ref={triggerRef as RefObject<never>}
+      onPress={() => setOpen(true)}
+      accessibilityRole="combobox"
+      accessibilityLabel={display ?? placeholder}
+      accessibilityState={{expanded: open}}
+    >
+      <html.div style={[styles.inputWrapper, nativeStyles.field]}>
+        <html.span style={[nativeStyles.fieldText, !display && nativeStyles.fieldPlaceholder]}>
+          {display ?? placeholder}
+        </html.span>
+        {children}
+        <html.div style={nativeStyles.chevronDown}>
+          <Chevron color="textMuted" />
+        </html.div>
+      </html.div>
+    </Pressable>
+  )
+}
+
+/** The web's open/close button; on native the whole field opens the sheet. */
+function Trigger(_props: {children?: ReactNode}) {
+  return null
+}
+
+interface PopupProps {
+  children: ReactNode
+  /** The sheet's title (native) and the list's accessible name. */
+  label?: string
+  /** The sheet header's text button that closes it unchanged (native). Default: 'Cancel' */
+  cancelLabel?: string
+}
+
+function Popup({children, label, cancelLabel = 'Cancel'}: PopupProps) {
+  const {open, choose, query, setQuery, placeholder, listboxId} = useCombobox()
+  const inputRef = useRef<unknown>(null)
+
+  // Focus the search field once the sheet has entered: a TextInput's
+  // autoFocus fires on mount, before iOS has presented the Modal.
+  useEffect(() => {
+    if (!open) return
+    const timer = setTimeout(() => focusInput(inputRef.current), DURATION_MS.base)
+    return () => clearTimeout(timer)
+  }, [open])
+
+  return (
+    <>
+      <CollectContext.Provider value={true}>{children}</CollectContext.Provider>
+      <Drawer.Portal>
+        <Drawer.Header titleAlign="center">
+          {label ? <Drawer.Title>{label}</Drawer.Title> : null}
+          <Drawer.Close>
+            <Button variant="link">{cancelLabel}</Button>
+          </Drawer.Close>
+        </Drawer.Header>
+        <html.div style={sheetStyles.search}>
+          <Icon name="search" size="sm" color="textMuted" />
+          <html.input
+            ref={inputRef as Ref<never>}
+            type="search"
+            autoComplete="off"
+            autoCapitalize="none"
+            spellCheck={false}
+            value={query}
+            placeholder={placeholder}
+            aria-label={label ?? placeholder}
+            onChange={(e: {target: {value: string}}) => setQuery(e.target.value)}
+            style={sheetStyles.searchInput}
+          />
+        </html.div>
+        <Drawer.Body flush>
+          <Listbox.Root id={listboxId} open={open} onSelect={choose} aria-label={label}>
+            {children}
+          </Listbox.Root>
+        </Drawer.Body>
+      </Drawer.Portal>
+    </>
+  )
+}
+
+interface ItemProps {
+  value: string
+  children: ReactNode
+}
+
+function Item({value: itemValue, children}: ItemProps) {
+  const collecting = useContext(CollectContext)
+  const {value, labels, query, registerLabel, registerItem} = useCombobox()
+  const label = textOf(children)
+  useEffect(() => {
+    if (collecting && label) registerLabel(itemValue, label)
+  }, [collecting, itemValue, label, registerLabel])
+  useEffect(() => {
+    if (collecting) return registerItem(itemValue, label || itemValue)
+  }, [collecting, itemValue, label, registerItem])
+  if (collecting || !matchesQuery(labels[itemValue] ?? label, query)) return null
+  return (
+    <Listbox.Option value={itemValue} selected={value === itemValue}>
+      {children}
+    </Listbox.Option>
+  )
+}
+
+function ItemText({children}: {children: ReactNode}) {
+  return <html.span>{children}</html.span>
+}
+
+/** Shown under the search field when nothing matches what is typed. */
+function Empty({children}: {children: ReactNode}) {
+  const collecting = useContext(CollectContext)
+  const {query, items} = useCombobox()
+  if (collecting) return null
+  // Only the Items rendered now count: an initialLabels entry with no Item
+  // would otherwise hide Empty while the list shows nothing.
+  const anyMatch = [...items.values()].some((label) => matchesQuery(label, query))
+  if (anyMatch) return null
+  return <Listbox.Empty>{children}</Listbox.Empty>
+}
+
+export const Combobox = {
+  Root,
+  Input,
+  Trigger,
+  Popup,
+  Item,
+  ItemText,
+  Empty,
+}

package/src/components/Combobox/Combobox.tsx

@@ -3,6 +3,7 @@ import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {ComboboxContext, useCombobox} from './ComboboxContext'
 import {useComboboxRoot} from './useComboboxRoot'
+import {matchesQuery} from './comboboxState'
 import {Listbox, getAnchorProps} from '../Listbox/Listbox'
 
 // --- Root ---
@@ -134,7 +135,15 @@ function Trigger({children}: {children?: ReactNode}) {
 // A Listbox placed under the input, as wide as the field: rendered into the
 // ThemeProvider portal mount so it escapes ancestor `overflow: hidden` /
 // `transform` containing blocks (notably Dialog and Drawer).
-function Popup({children}: {children: ReactNode}) {
+interface PopupProps {
+  children: ReactNode
+  /** The list's accessible name; on native also the sheet's title. */
+  label?: string
+  /** Native only: the sheet header's text button that closes it unchanged. Default: 'Cancel' */
+  cancelLabel?: string
+}
+
+function Popup({children, label}: PopupProps) {
   const {open, listboxId, rootRef, highlightedId, setHighlightedId, setValue} = useCombobox()
   const anchor = useCallback(() => rootRef.current?.getBoundingClientRect(), [rootRef])
 
@@ -147,6 +156,7 @@ function Popup({children}: {children: ReactNode}) {
       highlightedId={highlightedId}
       onHighlight={setHighlightedId}
       onSelect={setValue}
+      aria-label={label}
       maxHeight="listMaxHSm"
     >
       {children}
@@ -167,9 +177,7 @@ function Item({value: itemValue, children}: ItemProps) {
   const isSelected = selectedValue === itemValue
 
   // Filter: check if this item matches the input
-  const label = labels[itemValue] ?? itemValue
-  const query = inputValue.toLowerCase()
-  const isVisible = !query || label.toLowerCase().includes(query)
+  const isVisible = matchesQuery(labels[itemValue] ?? itemValue, inputValue)
 
   useEffect(() => {
     const el = ref.current
@@ -205,10 +213,8 @@ function Empty({children}: {children: ReactNode}) {
   if (!open) return null
 
   // Check if any items are visible
-  const query = inputValue.toLowerCase()
-  const hasVisibleItems = query
-    ? Object.values(labels).some((label) => label.toLowerCase().includes(query))
-    : true
+  const hasVisibleItems =
+    !inputValue || Object.values(labels).some((label) => matchesQuery(label, inputValue))
 
   if (hasVisibleItems) return null
 

package/src/components/Combobox/comboboxState.ts

@@ -0,0 +1,107 @@
+import {useCallback, useEffect, useState} from 'react'
+import {useControllableValue} from '../../hooks/useControllableValue'
+
+export interface ComboboxStateOptions {
+  defaultValue?: string
+  value?: string
+  onValueChange?: (value: string | null) => void
+  inputValue?: string
+  onInputChange?: (value: string) => void
+  initialLabels?: Record<string, string>
+}
+
+/** Whether an option's label matches what was typed: a case-insensitive substring. */
+export function matchesQuery(label: string, query: string): boolean {
+  return !query || label.toLowerCase().includes(query.toLowerCase())
+}
+
+/**
+ * The Combobox's state both platforms share (plan N0, Decision 10): the value
+ * and the typed text (each controlled or not), whether it is open, each
+ * option's label, choosing an option, and the text/value reconcile on close.
+ * Highlight, document order, keys and DOM focus are the web adapter's
+ * (useComboboxRoot); the sheet and its pinned input are Combobox.native's.
+ */
+export function useComboboxState({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  inputValue: controlledInputValue,
+  onInputChange,
+  initialLabels,
+}: ComboboxStateOptions) {
+  const [value, setValue] = useControllableValue<string | null>(
+    controlledValue,
+    defaultValue ?? null,
+    onValueChange,
+  )
+  // Seed the visible text from the initially-selected value's label, so a
+  // defaultValue/value shows its label on mount — and so the reconcile effect
+  // below doesn't see "value set but input empty" and wipe the selection.
+  const [internalInputValue, setInternalInputValue] = useState<string>(() => {
+    const initial = controlledValue ?? defaultValue
+    return initial ? (initialLabels?.[initial] ?? '') : ''
+  })
+  const inputValue = controlledInputValue !== undefined ? controlledInputValue : internalInputValue
+  const setInputValue = useCallback(
+    (v: string) => {
+      if (controlledInputValue === undefined) setInternalInputValue(v)
+      onInputChange?.(v)
+    },
+    [controlledInputValue, onInputChange],
+  )
+
+  const [open, setOpen] = useState(false)
+  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+
+  const registerLabel = useCallback((v: string, label: string) => {
+    setLabels((prev) => (prev[v] === label ? prev : {...prev, [v]: label}))
+  }, [])
+
+  /** Choose an option: commit it, show its label, close. */
+  const chooseValue = useCallback(
+    (itemValue: string) => {
+      setValue(itemValue)
+      setInputValue(labels[itemValue] ?? itemValue)
+      setOpen(false)
+    },
+    [setValue, labels, setInputValue],
+  )
+
+  // Reconcile input text with the committed value once the popup closes.
+  // Three cases when transitioning from open → closed:
+  //   - inputValue is empty: user cleared the field, treat that as
+  //     "remove the selection" so the consumer's onValueChange fires
+  //     with null and downstream UI (e.g. dependent fields) can reset.
+  //   - inputValue doesn't match the selected label: user typed something
+  //     but didn't pick anything; restore the label so the visible text
+  //     and the committed value stay consistent.
+  //   - inputValue equals the selected label: nothing to do.
+  useEffect(() => {
+    if (open) return
+    // Treat an empty value (null OR '') as "no selection" — nothing to
+    // reconcile. Without this, a controlled value="" (e.g. a table column
+    // filter) fires setValue(null) every render → inline onValueChange →
+    // parent state change → re-render → infinite "Maximum update depth" loop.
+    if (!value) return
+    if (inputValue === '') {
+      setValue(null)
+      return
+    }
+    if (labels[value] && inputValue !== labels[value]) {
+      setInputValue(labels[value])
+    }
+  }, [open, value, labels, inputValue, setInputValue, setValue])
+
+  return {
+    value,
+    setValue,
+    inputValue,
+    setInputValue,
+    open,
+    setOpen,
+    labels,
+    registerLabel,
+    chooseValue,
+  }
+}

package/src/components/Combobox/native.css.ts

@@ -0,0 +1,33 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {typography} from '@duro-app/tokens/tokens/typography.css'
+
+/** Native Combobox additions to the shared styles: the closed field. */
+export const nativeStyles = css.create({
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+  },
+  // The closed field: the web input's padding, a down chevron at its end.
+  field: {
+    display: 'flex',
+    flexDirection: 'row',
+    paddingTop: spacing.sm,
+    paddingBottom: spacing.sm,
+    paddingRight: spacing.sm,
+  },
+  fieldText: {
+    color: colors.text,
+    fontFamily: typography.fontFamily,
+    fontSize: typography.fontSizeSm,
+  },
+  // SideNav's chevron points right; a picker's points down.
+  chevronDown: {
+    display: 'flex',
+    transform: 'rotate(90deg)',
+  },
+  fieldPlaceholder: {
+    color: colors.textMuted,
+  },
+})

package/src/components/Combobox/useComboboxRoot.ts

@@ -1,47 +1,14 @@
 import {useState, useCallback, useMemo, useRef, useId, useEffect} from 'react'
-import {useControllableValue} from '../../hooks/useControllableValue'
 import type {ComboboxContextValue} from './ComboboxContext'
-
-interface UseComboboxRootOptions {
-  defaultValue?: string
-  value?: string
-  onValueChange?: (value: string | null) => void
-  inputValue?: string
-  onInputChange?: (value: string) => void
-  initialLabels?: Record<string, string>
-}
-
-export function useComboboxRoot({
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  inputValue: controlledInputValue,
-  onInputChange,
-  initialLabels,
-}: UseComboboxRootOptions) {
-  const [value, setValue] = useControllableValue<string | null>(
-    controlledValue,
-    defaultValue ?? null,
-    onValueChange,
-  )
-  // Seed the visible text from the initially-selected value's label, so a
-  // defaultValue/value shows its label on mount — and so the reconcile effect
-  // below doesn't see "value set but input empty" and wipe the selection.
-  const [internalInputValue, setInternalInputValue] = useState<string>(() => {
-    const initial = controlledValue ?? defaultValue
-    return initial ? (initialLabels?.[initial] ?? '') : ''
-  })
-  const inputValue = controlledInputValue !== undefined ? controlledInputValue : internalInputValue
-  const setInputValue = useCallback(
-    (v: string) => {
-      if (controlledInputValue === undefined) setInternalInputValue(v)
-      onInputChange?.(v)
-    },
-    [controlledInputValue, onInputChange],
-  )
-
-  const [open, setOpen] = useState(false)
-  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+import {matchesQuery, useComboboxState, type ComboboxStateOptions} from './comboboxState'
+
+/**
+ * The web adapter over the shared Combobox state: the highlighted option,
+ * document order, keys and DOM focus (the WAI-ARIA editable combobox).
+ */
+export function useComboboxRoot(options: ComboboxStateOptions) {
+  const {value, inputValue, setInputValue, open, setOpen, labels, registerLabel, chooseValue} =
+    useComboboxState(options)
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
   const listboxId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
@@ -52,7 +19,7 @@ export function useComboboxRoot({
   const close = useCallback(() => {
     setOpen(false)
     setHighlightedId(null)
-  }, [])
+  }, [setOpen])
 
   const openPopup = useCallback(() => {
     setOpen(true)
@@ -68,27 +35,18 @@ export function useComboboxRoot({
       }
     }
     setHighlightedId(found ?? (order.length > 0 ? order[0] : null))
-  }, [value])
+  }, [value, setOpen])
 
+  // Choosing keeps focus in the input (the web's editable combobox).
   const selectValue = useCallback(
     (itemValue: string) => {
-      setValue(itemValue)
-      // Set input to show the selected label
-      const label = labels[itemValue] ?? itemValue
-      setInputValue(label)
-      close()
+      chooseValue(itemValue)
+      setHighlightedId(null)
       inputRef.current?.focus()
     },
-    [setValue, labels, setInputValue, close],
+    [chooseValue],
   )
 
-  const registerLabel = useCallback((v: string, label: string) => {
-    setLabels((prev) => {
-      if (prev[v] === label) return prev
-      return {...prev, [v]: label}
-    })
-  }, [])
-
   const registerItem = useCallback((id: string, itemValue: string, element: HTMLElement) => {
     itemsRef.current.set(id, {value: itemValue, element})
     const map = itemsRef.current
@@ -108,13 +66,10 @@ export function useComboboxRoot({
 
   // Get visible items (those matching the filter)
   const getVisibleOrder = useCallback(() => {
-    const query = inputValue.toLowerCase()
-    if (!query) return orderRef.current
+    if (!inputValue) return orderRef.current
     return orderRef.current.filter((id) => {
       const item = itemsRef.current.get(id)
-      if (!item) return false
-      const label = labels[item.value] ?? item.value
-      return label.toLowerCase().includes(query)
+      return item ? matchesQuery(labels[item.value] ?? item.value, inputValue) : false
     })
   }, [inputValue, labels])
 
@@ -130,10 +85,6 @@ export function useComboboxRoot({
       switch (e.key) {
         case 'ArrowDown': {
           e.preventDefault()
-          if (!open) {
-            setOpen(true)
-            return
-          }
           setHighlightedId((prev) => {
             const idx = prev ? visibleOrder.indexOf(prev) : -1
             return visibleOrder[(idx + 1) % visibleOrder.length] ?? null
@@ -196,31 +147,6 @@ export function useComboboxRoot({
     item?.element.scrollIntoView({block: 'nearest'})
   }, [highlightedId])
 
-  // Reconcile input text with the committed value once the popup closes.
-  // Three cases when transitioning from open → closed:
-  //   - inputValue is empty: user cleared the field, treat that as
-  //     "remove the selection" so the consumer's onValueChange fires
-  //     with null and downstream UI (e.g. dependent fields) can reset.
-  //   - inputValue doesn't match the selected label: user typed something
-  //     but didn't pick anything; restore the label so the visible text
-  //     and the committed value stay consistent.
-  //   - inputValue equals the selected label: nothing to do.
-  useEffect(() => {
-    if (open) return
-    // Treat an empty value (null OR '') as "no selection" — nothing to
-    // reconcile. Without this, a controlled value="" (e.g. a table column
-    // filter) fires setValue(null) every render → inline onValueChange →
-    // parent state change → re-render → infinite "Maximum update depth" loop.
-    if (!value) return
-    if (inputValue === '') {
-      setValue(null)
-      return
-    }
-    if (labels[value] && inputValue !== labels[value]) {
-      setInputValue(labels[value])
-    }
-  }, [open, value, labels, inputValue, setInputValue, setValue])
-
   const ctx: ComboboxContextValue = useMemo(
     () => ({
       open,

package/src/components/Drawer/Drawer.meta.ts

@@ -2,10 +2,11 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Modal sliding panel from a screen edge (right, left, or bottom). Slides in with backdrop overlay. Supports swipe-to-dismiss gestures on mobile, backdrop click dismiss, and Escape key. Swipe yields to an inner Duro ScrollArea: a drag there scrolls it, and dismisses only toward the edge from the scroll start (a native overflow:auto child is not covered — use ScrollArea). Use for secondary workflows, settings panels, or mobile-friendly detail views.',
+    'Modal sliding panel from a screen edge (right, left, or bottom). Slides in with backdrop overlay. Supports swipe-to-dismiss gestures on mobile, backdrop click dismiss, and Escape key. Swipe yields to an inner Duro ScrollArea: a drag there scrolls it, and dismisses only toward the edge from the scroll start (a native overflow:auto child is not covered — use ScrollArea). A bottom drawer with snapPoints (medium and large) is a phone sheet: it rests at its detents, a grabber steps through them on a tap, a drag moves between them and dismisses below the lowest; its Body is the scroll the drag defers to. Header titleAlign="center" centres the title with a text close at the end. Body flush drops its side padding, so rows run to the panel\'s edges (a picker\'s list); on React Native a bottom drawer rides above the on-screen keyboard. Use for secondary workflows, settings panels, or mobile-friendly detail views.',
   whenToUse: [
     'Settings or configuration panels that slide in from the side',
     'Mobile-friendly detail views (bottom sheet pattern)',
+    'Phone pickers and lists that need more room on demand (snapPoints)',
     'Secondary workflows that need more space than a dialog',
     'Filters, navigation drawers, or form panels',
   ],