@duro-app/ui 5.12.0 → 5.13.0

package/src/components/Drawer/useSwipeDismiss.ts

@@ -1,14 +1,14 @@
 import {useRef, useCallback, useEffect} from 'react'
-import type {DrawerAnchor} from './Drawer'
-
-/** Threshold: fraction of panel size the user must drag to dismiss */
-const DISMISS_THRESHOLD = 0.3
-
-/** Minimum velocity (px/ms) to dismiss even below threshold */
-const VELOCITY_THRESHOLD = 0.5
-
-/** Duration for the dismiss slide-out animation (ms) */
-const DISMISS_DURATION = 160
+import type {DrawerAnchor} from './parts'
+import {
+  DISMISS_DURATION,
+  DRAG_SLOP,
+  SNAP_DURATION,
+  SNAP_MAX_OVERSHOOT,
+  rubberBand,
+  settleDetent,
+  shouldDismissEdge,
+} from './sheetPhysics'
 
 /**
  * Max pixels the panel visually "grows" when dragged in the opposite direction.
@@ -17,6 +17,16 @@ const DISMISS_DURATION = 160
  */
 const OPPOSITE_MAX_OVERSCROLL = 12
 
+/** A bottom sheet's detents: the drag moves between them before it dismisses. */
+export interface SwipeSnap {
+  /** Each detent's height in px, ascending */
+  heights: readonly number[]
+  /** The detent the sheet rests at */
+  index: number
+  /** A drag settled on another detent */
+  onSnap: (index: number) => void
+}
+
 interface UseSwipeDismissOptions {
   anchor: DrawerAnchor
   enabled: boolean
@@ -27,6 +37,8 @@ interface UseSwipeDismissOptions {
    * exists, and listeners must follow the element that is actually shown.
    */
   panel: HTMLDivElement | null
+  /** Bottom anchor with snapPoints: drag between detents, dismiss below the lowest */
+  snap?: SwipeSnap | null
 }
 
 interface SwipeState {
@@ -39,6 +51,8 @@ interface SwipeState {
   panelSize: number
   /** Inner Duro scroll viewport the gesture started in; capture is deferred until the axis is decided */
   deferredScroll: HTMLElement | null
+  /** Started on a snap sheet's grabber: a tap stays its click, a drag moves the sheet */
+  fromGrabber: boolean
   pointerId: number
 }
 
@@ -49,7 +63,13 @@ interface SwipeState {
  * Opposite direction: iOS-style — panel stays anchored, shows subtle
  * overscroll feedback (box-shadow intensifies), then snaps back.
  */
-export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDismissOptions) {
+export function useSwipeDismiss({
+  anchor,
+  enabled,
+  onDismiss,
+  panel,
+  snap = null,
+}: UseSwipeDismissOptions) {
   const stateRef = useRef<SwipeState>({
     startX: 0,
     startY: 0,
@@ -59,8 +79,13 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
     swiping: false,
     panelSize: 0,
     deferredScroll: null,
+    fromGrabber: false,
     pointerId: 0,
   })
+  // Read at event time, so a settle that re-renders mid-gesture is never stale.
+  const snapRef = useRef(snap)
+  snapRef.current = snap
+  const snapping = snap !== null
 
   const isHorizontal = anchor === 'left' || anchor === 'right'
 
@@ -117,6 +142,8 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
   const resetStyles = useCallback((panelEl: HTMLDivElement) => {
     panelEl.style.transform = ''
     panelEl.style.boxShadow = ''
+    panelEl.style.height = ''
+    panelEl.style.transition = ''
 
     const backdrop = panelEl.closest('[data-drawer-viewport]')
       ?.previousElementSibling as HTMLElement | null
@@ -178,19 +205,79 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
     setTimeout(cleanup, 250)
   }, [])
 
+  /**
+   * Snap sheet drag: the visible height follows the finger. Between the lowest
+   * and the largest detent the panel resizes; past the largest it resists;
+   * below the lowest it slides down and the backdrop fades.
+   */
+  const applySnapDrag = useCallback((movement: number, panelEl: HTMLDivElement) => {
+    const current = snapRef.current
+    if (!current) return
+    const {heights, index} = current
+    const low = heights[0]
+    const high = heights[heights.length - 1]
+    const visible = heights[index] - movement
+    const backdrop = backdropOf(panelEl)
+    if (visible > high) {
+      panelEl.style.height = `${high + rubberBand(visible - high, SNAP_MAX_OVERSHOOT)}px`
+      panelEl.style.transform = ''
+    } else if (visible >= low) {
+      panelEl.style.height = `${visible}px`
+      panelEl.style.transform = ''
+    } else {
+      panelEl.style.height = `${low}px`
+      panelEl.style.transform = `translateY(${low - visible}px)`
+    }
+    if (backdrop) backdrop.style.opacity = String(Math.min(1, Math.max(0, visible / low)))
+  }, [])
+
+  /** Settle a snap sheet on a detent, then hand the height back to React */
+  const animateToDetent = useCallback((panelEl: HTMLDivElement, target: number) => {
+    const current = snapRef.current
+    if (!current) return
+    const ease = `${SNAP_DURATION}ms cubic-bezier(0.25, 1, 0.5, 1)`
+    panelEl.style.transition = `height ${ease}, transform ${ease}`
+    panelEl.style.height = `${current.heights[target]}px`
+    panelEl.style.transform = ''
+    const backdrop = backdropOf(panelEl)
+    if (backdrop) {
+      backdrop.style.transition = `opacity ${ease}`
+      backdrop.style.opacity = ''
+    }
+    let settled = false
+    const done = () => {
+      if (settled) return
+      settled = true
+      current.onSnap(target)
+      // React now sizes the panel at this detent: drop the inline copy.
+      requestAnimationFrame(() => {
+        panelEl.style.transition = ''
+        panelEl.style.height = ''
+        if (backdrop) backdrop.style.transition = ''
+      })
+    }
+    panelEl.addEventListener('transitionend', done, {once: true})
+    setTimeout(done, SNAP_DURATION + 50)
+  }, [])
+
   useEffect(() => {
     if (!enabled || !panel) return
 
     function handlePointerDown(e: PointerEvent) {
       if (e.button !== 0) return
       const target = e.target as HTMLElement
-      const scrollEl = target.closest<HTMLElement>('[data-duro-scroll]')
+      const fromGrabber = snapping && target.closest('[data-drawer-grabber]') !== null
+      const scrollEl = fromGrabber ? null : target.closest<HTMLElement>('[data-duro-scroll]')
       // Outside a ScrollArea a control keeps its press. Inside one the gesture
       // is decided on the first move even from a control: a list of toggles is
       // all buttons, and touch adjustment snaps a finger onto one. A tap
       // (under the 8px slop) still presses it; a drag never captures before
       // the decision, so the release lands on the panel, not the control.
-      if (!scrollEl && target.closest('button, a, input, textarea, select, [role="button"]')) {
+      if (
+        !fromGrabber &&
+        !scrollEl &&
+        target.closest('button, a, input, textarea, select, [role="button"]')
+      ) {
         return
       }
 
@@ -206,11 +293,13 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
 
       state.pointerId = e.pointerId
       state.deferredScroll = scrollEl
+      state.fromGrabber = fromGrabber
 
       panel!.dataset.panelSize = String(state.panelSize)
 
-      // Inside a Duro ScrollArea the scroll may own the gesture: wait for the first move.
-      if (!state.deferredScroll) beginCapture(e.pointerId)
+      // Inside a Duro ScrollArea the scroll may own the gesture, and a press on
+      // the grabber may be a tap: wait for the first move.
+      if (!state.deferredScroll && !fromGrabber) beginCapture(e.pointerId)
     }
 
     function beginCapture(pointerId: number) {
@@ -219,6 +308,14 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
       // Freeze CSS animation — we take over positioning.
       // Never restore it; the panel is already at its final resting position.
       panel!.style.animation = 'none'
+      // A snap sheet animates its height between detents; the finger drives it now.
+      if (snapping) panel!.style.transition = 'none'
+    }
+
+    /** A snap sheet below its largest detent grows when dragged up from its content */
+    function canGrow() {
+      const current = snapRef.current
+      return current !== null && current.index < current.heights.length - 1
     }
 
     /** True when the viewport can't scroll further against the dismiss direction */
@@ -240,7 +337,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
 
       if (!state.swiping) {
         const totalMovement = Math.sqrt(dx * dx + dy * dy)
-        if (totalMovement < 8) return
+        if (totalMovement < DRAG_SLOP) return
 
         if (isHorizontal && dx > dy) {
           state.swiping = true
@@ -250,13 +347,19 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
           // Wrong axis — abort gesture
           state.startTime = 0
           state.deferredScroll = null
+          state.fromGrabber = false
           return
         }
 
         const scrollEl = state.deferredScroll
-        if (scrollEl) {
+        if (state.fromGrabber) {
+          beginCapture(state.pointerId)
+        } else if (scrollEl) {
           state.deferredScroll = null
-          if (getMovement(state) <= 0 || !isAtDismissEdge(scrollEl)) {
+          const movement = getMovement(state)
+          const sheetOwns =
+            movement > 0 ? isAtDismissEdge(scrollEl) : snapping && movement < 0 && canGrow()
+          if (!sheetOwns) {
             // The scroll owns this gesture: no swiping, no capture, no preventDefault
             state.swiping = false
             state.startTime = 0
@@ -269,7 +372,8 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
       if (state.swiping) {
         e.preventDefault()
         const movement = getMovement(state)
-        applyTransform(movement, panel!)
+        if (snapping) applySnapDrag(movement, panel!)
+        else applyTransform(movement, panel!)
       }
     }
 
@@ -283,6 +387,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
 
       state.startTime = 0
       state.deferredScroll = null
+      state.fromGrabber = false
 
       if (!state.swiping) {
         return
@@ -290,16 +395,26 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
 
       state.swiping = false
 
+      const current = snapRef.current
+      if (current) {
+        const settled = settleDetent({
+          heights: current.heights,
+          from: current.index,
+          height: current.heights[current.index] - movement,
+          velocity,
+        })
+        if (settled === 'dismiss') animateDismiss(panel!)
+        else animateToDetent(panel!, settled)
+        return
+      }
+
       if (movement <= 0) {
         // Was dragging in opposite direction — just reset (no translate was applied)
         resetStyles(panel!)
         return
       }
 
-      const fraction = movement / state.panelSize
-      const shouldDismiss = fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
-
-      if (shouldDismiss) {
+      if (shouldDismissEdge(movement, state.panelSize, velocity)) {
         animateDismiss(panel!)
       } else {
         animateSnapBack(panel!)
@@ -311,6 +426,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
       state.startTime = 0
       state.swiping = false
       state.deferredScroll = null
+      state.fromGrabber = false
       resetStyles(panel!)
     }
 
@@ -340,8 +456,15 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panel}: UseSwipeDis
     isHorizontal,
     getMovement,
     applyTransform,
+    applySnapDrag,
+    animateToDetent,
     resetStyles,
     animateSnapBack,
     animateDismiss,
+    snapping,
   ])
 }
+
+function backdropOf(panelEl: HTMLDivElement) {
+  return panelEl.closest('[data-drawer-viewport]')?.previousElementSibling as HTMLElement | null
+}

package/src/components/Menu/Menu.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog.',
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it). Menu.Trigger renders the button itself: give it the label (text, an Icon), never a Button; an icon-only trigger takes aria-label, and variant="ghost" suits toolbars; size="small" matches small Toggles and Buttons (a small ghost trigger is iconButtonSm). The popup is portalled and placed against the trigger (never clipped by a sticky or overflow ancestor), capped at sizes.listMaxH with scrolling, and takes focus on open (WAI-ARIA menu button); Escape closes only the menu, not an enclosing Popover or Dialog. On React Native the popup is placed against the trigger in a modal overlay; a press outside or the Android back button closes it, and an item runs its onClick after the menu has gone (so an item can open a Dialog). Menu.LinkItem takes onNavigate(href, event) on both platforms (ADR-0002); on native, without it or without preventDefault, the link opens with the system. Native has no arrow keys: each item is its own screen-reader stop.',
   whenToUse: [
     'Context menu or "more actions" dropdown',
     'Navigation links in a dropdown',

package/src/components/Menu/Menu.native.tsx

@@ -0,0 +1,268 @@
+import {
+  createContext,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+} from 'react'
+import {Linking, Platform, Pressable, ScrollView, StyleSheet} from 'react-native'
+import {html} from 'react-strict-dom'
+import {SIZES_PX} from '@duro-app/tokens/keys'
+import {styles} from './styles.css'
+import {nativeStyles} from './native.css'
+import {useMenuOpen} from './useMenuOpen'
+import {AnchoredOverlay} from '../../shared/portal/AnchoredOverlay'
+import {focusForAccessibility} from '../../shared/accessibilityFocus'
+import {mergeRefs} from '../../shared/mergeRefs'
+import type {LinkClickEvent, OnNavigate} from '../../shared/navigate'
+import type {ControlSize} from '../../shared/types'
+import {useTooltipHint} from '../Tooltip/TooltipHint'
+import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
+
+interface NativeMenuContextValue {
+  open: boolean
+  toggle: () => void
+  /**
+   * Close, then run `after` once the menu's Modal is gone: an item that opens
+   * a Dialog would otherwise present during a dismissal, which iOS drops.
+   */
+  closeThen: (after?: () => void) => void
+  menuId: string
+  triggerRef: RefObject<unknown>
+}
+
+const MenuContext = createContext<NativeMenuContextValue | null>(null)
+
+function useMenu() {
+  const ctx = useContext(MenuContext)
+  if (!ctx) throw new Error('Menu compound components must be used within Menu.Root')
+  return ctx
+}
+
+interface RootProps {
+  children: ReactNode
+  /** Controlled open state. */
+  open?: boolean
+  /** Initial open state (uncontrolled). */
+  defaultOpen?: boolean
+  /** Called when the menu opens or closes. */
+  onOpenChange?: (open: boolean) => void
+}
+
+/**
+ * Native Menu (plan N0, Slice B): the same compound API, its popup placed
+ * against the trigger in an OverlayModal. A press outside or Android's back
+ * button closes it; an item runs its action after the menu has gone. Native
+ * has no arrow keys or active descendant (Decision 6): each item is its own
+ * screen-reader stop.
+ */
+function Root({children, ...options}: RootProps) {
+  const {open, setOpen} = useMenuOpen(options)
+  const menuId = useId()
+  const triggerRef = useRef<unknown>(null)
+  const pendingRef = useRef<(() => void) | null>(null)
+
+  const runPending = useCallback(() => {
+    const pending = pendingRef.current
+    pendingRef.current = null
+    pending?.()
+  }, [])
+
+  const closeThen = useCallback(
+    (after?: () => void) => {
+      pendingRef.current = after ?? null
+      setOpen(false)
+    },
+    [setOpen],
+  )
+
+  // Focus back on the trigger once the menu is gone; Android has no Modal
+  // onDismiss, so a pending action runs on the next frame there.
+  const wasOpen = useRef(open)
+  useEffect(() => {
+    if (wasOpen.current && !open) {
+      focusForAccessibility(triggerRef.current, 'Menu')
+      if (Platform.OS !== 'ios') requestAnimationFrame(runPending)
+    }
+    wasOpen.current = open
+  }, [open, runPending])
+
+  const toggle = useCallback(() => setOpen(!open), [open, setOpen])
+
+  return (
+    <MenuContext.Provider value={{open, toggle, closeThen, menuId, triggerRef}}>
+      <PendingContext.Provider value={runPending}>
+        <html.div style={[styles.root, nativeStyles.nativeFlex]}>{children}</html.div>
+      </PendingContext.Provider>
+    </MenuContext.Provider>
+  )
+}
+
+/** iOS: run the pending item action once the Modal has dismissed. */
+const PendingContext = createContext<() => void>(() => {})
+
+export type MenuTriggerVariant = 'default' | 'ghost'
+
+interface TriggerProps {
+  children: ReactNode
+  /** Accessible name — required when the label is an icon only. */
+  'aria-label'?: string
+  /** `ghost`: no border or fill until hover, for toolbars. Default: `default`. */
+  variant?: MenuTriggerVariant
+  /** `small` matches a small Toggle or Button beside it. Default: `default`. */
+  size?: ControlSize
+  ref?: Ref<unknown>
+}
+
+/**
+ * The trigger is an RN Pressable host, so it carries an enclosing Tooltip's
+ * text as its own accessibility hint (RSD drops `accessibilityHint` on html.*).
+ *
+ * holds-until: react-strict-dom maps aria-description to accessibilityHint
+ * (https://github.com/react/react-strict-dom/issues/524).
+ */
+function Trigger({
+  children,
+  'aria-label': ariaLabel,
+  variant = 'default',
+  size = 'default',
+  ref,
+}: TriggerProps) {
+  const {open, toggle, triggerRef} = useMenu()
+  const hint = useTooltipHint()
+  return (
+    <Pressable
+      ref={mergeRefs(triggerRef, ref) as Ref<never>}
+      onPress={toggle}
+      accessibilityRole="button"
+      accessibilityLabel={ariaLabel}
+      accessibilityHint={hint}
+      accessibilityState={{expanded: open}}
+    >
+      <html.div
+        style={[
+          styles.trigger,
+          nativeStyles.nativeFlex,
+          variant === 'ghost'
+            ? [styles.triggerGhost, size === 'small' && styles.triggerGhostSmall]
+            : size === 'small' && styles.triggerSmall,
+        ]}
+      >
+        {children}
+      </html.div>
+    </Pressable>
+  )
+}
+
+interface PopupProps {
+  children: ReactNode
+  align?: 'start' | 'end'
+}
+
+function Popup({children, align = 'start'}: PopupProps) {
+  const {open, closeThen, menuId, triggerRef} = useMenu()
+  const runPending = useContext(PendingContext)
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <AnchoredOverlay
+      visible={open}
+      anchorRef={triggerRef}
+      side="bottom"
+      align={align}
+      onRequestClose={() => closeThen()}
+      onShow={() => focusForAccessibility(popupRef.current, 'Menu')}
+      onDismiss={runPending}
+    >
+      <html.div
+        ref={popupRef}
+        id={menuId}
+        role="menu"
+        style={[styles.popup, nativeStyles.popupInPlace]}
+      >
+        <ScrollView style={layout.scroll} bounces={false}>
+          <ControlContextBoundary>{children}</ControlContextBoundary>
+        </ScrollView>
+      </html.div>
+    </AnchoredOverlay>
+  )
+}
+
+// The popup's height cap, `sizes.listMaxH`, on the view that scrolls.
+const layout = StyleSheet.create({scroll: {maxHeight: SIZES_PX.listMaxH, flexGrow: 0}})
+
+interface ItemProps {
+  onClick?: () => void
+  children: ReactNode
+}
+
+function Item({onClick, children}: ItemProps) {
+  const {closeThen} = useMenu()
+  return (
+    <Pressable accessibilityRole="menuitem" onPress={() => closeThen(onClick)}>
+      {({pressed}) => (
+        <html.div style={[styles.item, pressed && nativeStyles.itemPressed]}>{children}</html.div>
+      )}
+    </Pressable>
+  )
+}
+
+interface LinkItemProps {
+  href: string
+  /**
+   * Called with the href when the item is pressed (ADR-0002). Call
+   * `event.preventDefault()` to navigate in-app; otherwise, and without it,
+   * the URL opens with the system (`Linking.openURL`).
+   */
+  onNavigate?: OnNavigate
+  children: ReactNode
+}
+
+function LinkItem({href, onNavigate, children}: LinkItemProps) {
+  const {closeThen} = useMenu()
+  const follow = () => {
+    let prevented = false
+    const event: LinkClickEvent = {
+      button: 0,
+      metaKey: false,
+      ctrlKey: false,
+      shiftKey: false,
+      altKey: false,
+      get defaultPrevented() {
+        return prevented
+      },
+      preventDefault() {
+        prevented = true
+      },
+    }
+    onNavigate?.(href, event)
+    if (!prevented) {
+      Linking.openURL(href).catch((error: unknown) => {
+        console.warn(`[duro] Menu.LinkItem: could not open ${href}: ${String(error)}`)
+      })
+    }
+  }
+  return (
+    <Pressable accessibilityRole="link" onPress={() => closeThen(follow)}>
+      {({pressed}) => (
+        <html.div style={[styles.item, pressed && nativeStyles.itemPressed]}>{children}</html.div>
+      )}
+    </Pressable>
+  )
+}
+
+function Separator() {
+  return <html.div role="separator" aria-orientation="horizontal" style={styles.separator} />
+}
+
+export const Menu = {
+  Root,
+  Trigger,
+  Popup,
+  Item,
+  LinkItem,
+  Separator,
+}

package/src/components/Menu/Menu.tsx

@@ -15,6 +15,7 @@ import {styles} from './styles.css'
 import {MenuContext, useMenu} from './MenuContext'
 import {useMenuRoot} from './useMenuRoot'
 import {devWarnOnce} from '../../shared/devWarnOnce'
+import {isPlainClick, type LinkClickEvent, type OnNavigate} from '../../shared/navigate'
 import type {ControlSize} from '../../shared/types'
 import {usePortalMount} from '../ThemeProvider/ThemeProvider'
 import {computePopoverPosition} from '../Popover/position'
@@ -222,10 +223,15 @@ function Item({onClick, children}: ItemProps) {
 // --- LinkItem ---
 interface LinkItemProps {
   href: string
+  /**
+   * Called for a plain primary click (ADR-0002): call `event.preventDefault()`,
+   * then your router's navigate. Without it the browser follows the link.
+   */
+  onNavigate?: OnNavigate
   children: ReactNode
 }
 
-function LinkItem({href, children}: LinkItemProps) {
+function LinkItem({href, onNavigate, children}: LinkItemProps) {
   const {close, highlightedId, setHighlightedId, registerItem} = useMenu()
   const id = useId()
   const ref = useRef<HTMLAnchorElement>(null)
@@ -242,7 +248,10 @@ function LinkItem({href, children}: LinkItemProps) {
       ref={ref}
       id={id}
       href={href}
-      onClick={() => close()}
+      onClick={(event: LinkClickEvent) => {
+        if (onNavigate && isPlainClick(event)) onNavigate(href, event)
+        close()
+      }}
       role="menuitem"
       onPointerEnter={() => setHighlightedId(id)}
       style={[styles.item, styles.linkItem, isHighlighted && styles.itemHighlighted]}

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

@@ -0,0 +1,18 @@
+import {css} from 'react-strict-dom'
+import {colors} from '@duro-app/tokens/tokens/colors.css'
+
+/** Native Menu additions to the shared styles. */
+export const nativeStyles = css.create({
+  // The AnchoredOverlay's view places the popup; it flows inside it.
+  // RSD on native lays out only display: flex, not the web's inline-flex.
+  nativeFlex: {
+    display: 'flex',
+  },
+  popupInPlace: {
+    position: 'relative',
+  },
+  // A press shows the highlight that hover and the arrow keys show on the web.
+  itemPressed: {
+    backgroundColor: colors.bgCardHover,
+  },
+})

package/src/components/Menu/useMenuOpen.ts

@@ -0,0 +1,33 @@
+import {useCallback, useRef, useState} from 'react'
+
+export interface MenuOpenOptions {
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+/**
+ * The menu's open state, controlled or not, shared by both platforms (plan
+ * N0, Decision 10). Focus, highlight and keys are each platform's adapter:
+ * `useMenuRoot` on the web, Menu.native on native.
+ */
+export function useMenuOpen({open: openProp, defaultOpen = false, onOpenChange}: MenuOpenOptions) {
+  const [inner, setInner] = useState(defaultOpen)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : inner
+  const openRef = useRef(open)
+  openRef.current = open
+  const onOpenChangeRef = useRef(onOpenChange)
+  onOpenChangeRef.current = onOpenChange
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (next === openRef.current) return
+      if (!controlled) setInner(next)
+      onOpenChangeRef.current?.(next)
+    },
+    [controlled],
+  )
+
+  return {open, openRef, setOpen}
+}