@duro-app/ui 5.11.0 → 5.13.0

package/src/shared/ButtonHost.native.tsx

@@ -0,0 +1,70 @@
+import {Children, type ComponentProps, type ReactNode, type Ref} from 'react'
+import {Pressable} from 'react-native'
+import {html} from 'react-strict-dom'
+import {useTooltipHint} from '../components/Tooltip/TooltipHint'
+
+export type ButtonHostProps = ComponentProps<typeof html.button>
+
+/**
+ * The host element of Button and Toggle on native. Inside a Tooltip it is an
+ * RN Pressable, which carries the Tooltip's text as its own accessibility hint
+ * (plan N0, Decision 5: RSD drops `accessibilityHint` on html.*); the visual
+ * styles move to a div inside it. Elsewhere it is RSD's button, as before.
+ *
+ * holds-until: react-strict-dom maps aria-description to accessibilityHint
+ * (https://github.com/react/react-strict-dom/issues/524); then html.button
+ * carries the hint itself and this swap goes.
+ */
+export function ButtonHost(props: ButtonHostProps) {
+  const hint = useTooltipHint()
+  const content = textInSpans(props.children)
+  if (!hint) {
+    return (
+      <html.button {...props} style={props.style}>
+        {content}
+      </html.button>
+    )
+  }
+  const {
+    ref,
+    style,
+    disabled,
+    onClick,
+    'aria-label': label,
+    'aria-pressed': pressed,
+    'aria-expanded': expanded,
+  } = props
+  return (
+    <Pressable
+      ref={ref as Ref<never>}
+      onPress={disabled ? undefined : () => onClick?.(undefined as never)}
+      disabled={disabled}
+      accessibilityRole="button"
+      accessibilityLabel={label ?? undefined}
+      accessibilityHint={hint}
+      accessibilityState={{
+        disabled: !!disabled,
+        ...(pressed !== undefined ? {checked: !!pressed} : {}),
+        ...(expanded !== undefined ? {expanded: !!expanded} : {}),
+      }}
+    >
+      <html.div style={style}>{content}</html.div>
+    </Pressable>
+  )
+}
+
+/**
+ * A label beside an icon (`<Icon/> Menu`): RSD wraps a button's text only
+ * when it is the sole child, and React Native refuses bare text in a view.
+ */
+function textInSpans(children: ReactNode): ReactNode {
+  const items = Children.toArray(children)
+  if (items.length < 2) return children
+  return items.map((child, i) =>
+    typeof child === 'string' || typeof child === 'number' ? (
+      <html.span key={i}>{child}</html.span>
+    ) : (
+      child
+    ),
+  )
+}

package/src/shared/ButtonHost.tsx

@@ -0,0 +1,12 @@
+import type {ComponentProps} from 'react'
+import {html} from 'react-strict-dom'
+
+export type ButtonHostProps = ComponentProps<typeof html.button>
+
+/**
+ * The host element of Button and Toggle. On the web it is the <button>
+ * itself, with no component in between (a wrapper changed what a Form's
+ * submit focuses); the native variant (ButtonHost.native.tsx) can swap in an
+ * RN Pressable to carry a Tooltip's accessibility hint.
+ */
+export const ButtonHost: typeof html.button = html.button

package/src/shared/accessibilityFocus.native.ts

@@ -0,0 +1,23 @@
+import {AccessibilityInfo} from 'react-native'
+
+const reported = new Set<string>()
+
+type FocusTarget = Parameters<typeof AccessibilityInfo.sendAccessibilityEvent>[0]
+
+/**
+ * Moves the screen reader's focus to `target` (a host view, or a
+ * react-strict-dom element ref). Native overlays call it on open and, for the
+ * trigger, on close: the screen-reader contract that stands in for the web's
+ * DOM focus (plan N0, Decision 6). A target the platform refuses is logged
+ * once per caller, in release builds too, rather than dropped.
+ */
+export function focusForAccessibility(target: unknown, from: string): void {
+  if (target == null) return
+  try {
+    AccessibilityInfo.sendAccessibilityEvent(target as FocusTarget, 'focus')
+  } catch (error) {
+    if (reported.has(from)) return
+    reported.add(from)
+    console.warn(`[duro] ${from}: could not move accessibility focus: ${String(error)}`)
+  }
+}

package/src/shared/portal/AnchoredOverlay.native.tsx

@@ -0,0 +1,117 @@
+import {type ReactNode, type RefObject, useEffect, useState} from 'react'
+import {
+  type LayoutChangeEvent,
+  Pressable,
+  StyleSheet,
+  useWindowDimensions,
+  View,
+} from 'react-native'
+import {SPACING_PX} from '@duro-app/tokens/keys'
+import {
+  computePopoverPosition,
+  type PopoverAlign,
+  type PopoverRect,
+  type PopoverSide,
+  type PopoverSize,
+} from '../../components/Popover/position'
+import {OverlayModal} from './OverlayModal'
+
+interface Measurable {
+  measureInWindow?: (cb: (x: number, y: number, width: number, height: number) => void) => void
+}
+
+interface AnchoredOverlayProps {
+  visible: boolean
+  /** The trigger's host: it is measured in window coordinates when the overlay opens */
+  anchorRef: RefObject<unknown>
+  side: PopoverSide
+  align: PopoverAlign
+  /** A backdrop press or Android's back button */
+  onRequestClose: () => void
+  /** The Modal has been presented: move accessibility focus in */
+  onShow?: () => void
+  /** iOS: the Modal has finished dismissing */
+  onDismiss?: () => void
+  children: ReactNode
+}
+
+/**
+ * A popup placed against its trigger on native (plan N0, Decision 3): the
+ * trigger is measured with `measureInWindow`, the popup with `onLayout`, and
+ * `computePopoverPosition` places it exactly as on the web. The OverlayModal
+ * is transparent and translucent, so its coordinates are window coordinates.
+ * Until both are measured the popup is laid out but not shown.
+ */
+export function AnchoredOverlay({
+  visible,
+  anchorRef,
+  side,
+  align,
+  onRequestClose,
+  onShow,
+  onDismiss,
+  children,
+}: AnchoredOverlayProps) {
+  const window = useWindowDimensions()
+  const [anchor, setAnchor] = useState<PopoverRect | null>(null)
+  const [size, setSize] = useState<PopoverSize | null>(null)
+
+  useEffect(() => {
+    if (!visible) {
+      setAnchor(null)
+      setSize(null)
+      return
+    }
+    const host = anchorRef.current as Measurable | null
+    host?.measureInWindow?.((left, top, width, height) => setAnchor({top, left, width, height}))
+  }, [visible, anchorRef, window.width, window.height])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    const {width, height} = e.nativeEvent.layout
+    setSize((prev) => (prev?.width === width && prev.height === height ? prev : {width, height}))
+  }
+
+  const position =
+    anchor && size
+      ? computePopoverPosition({
+          anchor,
+          popup: size,
+          viewport: {width: window.width, height: window.height},
+          side,
+          align,
+          offset: SPACING_PX.xs,
+        })
+      : null
+
+  return (
+    <OverlayModal
+      visible={visible}
+      onRequestClose={onRequestClose}
+      onShow={onShow}
+      onDismiss={onDismiss}
+    >
+      <Pressable
+        style={StyleSheet.absoluteFill}
+        onPress={onRequestClose}
+        accessible={false}
+        importantForAccessibility="no"
+      />
+      <View
+        onLayout={onLayout}
+        style={[
+          layout.popup,
+          {maxWidth: window.width - 2 * SPACING_PX.sm},
+          position ? {top: position.top, left: position.left} : layout.unplaced,
+        ]}
+      >
+        {children}
+      </View>
+    </OverlayModal>
+  )
+}
+
+// Layout-only: where the popup sits, and hidden until it has been placed.
+const layout = StyleSheet.create({
+  popup: {position: 'absolute'},
+  unplaced: {top: 0, left: 0, opacity: 0},
+})

package/src/shared/portal/OverlayModal.native.tsx

@@ -0,0 +1,51 @@
+import type {ReactNode} from 'react'
+import {Modal, StyleSheet} from 'react-native'
+import {GestureHandlerRootView} from 'react-native-gesture-handler'
+import {PortalHost} from './PortalHost'
+
+interface OverlayModalProps {
+  visible: boolean
+  /** Android back button: the dismissal Escape is on the web. */
+  onRequestClose: () => void
+  /** The Modal has been presented: move accessibility focus in. */
+  onShow?: () => void
+  /** iOS: the Modal has finished dismissing (presenting another one is safe). */
+  onDismiss?: () => void
+  children: ReactNode
+}
+
+/**
+ * The window every interactive native overlay renders in (plan N0,
+ * Decision 2). RN `Modal` is a React portal, so the app's contexts reach the
+ * content, and it presents above natively presented routes. Duro draws its own
+ * backdrop and motion, so the Modal's own animation is off.
+ *
+ * Content gets its own GestureHandlerRootView: on Android a Modal is a
+ * separate window that the app's root view does not cover. A PortalHost on
+ * top lets toasts raised while it is open draw above it.
+ */
+export function OverlayModal({
+  visible,
+  onRequestClose,
+  onShow,
+  onDismiss,
+  children,
+}: OverlayModalProps) {
+  return (
+    <Modal
+      visible={visible}
+      transparent
+      statusBarTranslucent
+      navigationBarTranslucent
+      animationType="none"
+      onRequestClose={onRequestClose}
+      onShow={onShow}
+      onDismiss={onDismiss}
+    >
+      <GestureHandlerRootView style={StyleSheet.absoluteFill}>
+        {children}
+        <PortalHost />
+      </GestureHandlerRootView>
+    </Modal>
+  )
+}

package/src/shared/portal/PortalHost.native.tsx

@@ -0,0 +1,102 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useSyncExternalStore,
+} from 'react'
+import {StyleSheet, View} from 'react-native'
+import {css, html} from 'react-strict-dom'
+import type {HostRegistry} from './hostRegistry'
+import {ResolvedColorsContext, ThemeScopeContext} from './themeScope'
+
+/** The registry the outermost ThemeProvider owns; null outside every provider. */
+export const HostRegistryContext = createContext<HostRegistry | null>(null)
+
+function useHostRegistry(component: string): HostRegistry {
+  const registry = useContext(HostRegistryContext)
+  if (!registry) throw new Error(`${component} must be rendered inside a Duro ThemeProvider`)
+  return registry
+}
+
+const styles = css.create({
+  // An entry covers its host without taking touches the entry does not draw on.
+  entry: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    pointerEvents: 'box-none',
+  },
+})
+
+type DivStyle = Parameters<typeof html.div>[0]['style']
+
+interface PortalHostProps {
+  /**
+   * `base`: the app root, always below every other host (the ThemeProvider
+   * draws it). `presented` (the default): a natively presented route, which
+   * a consumer mounts in that route's layout so toasts draw above it.
+   */
+  placement?: 'base' | 'presented'
+}
+
+/**
+ * Where passive overlays (toasts) draw on native. The ThemeProvider draws the
+ * root host and each open Duro Modal draws its own; mount one inside a
+ * natively presented route (`presentation: 'modal'`), or toasts raised there
+ * draw behind it.
+ */
+export function PortalHost({placement = 'presented'}: PortalHostProps) {
+  const registry = useHostRegistry('PortalHost')
+  const id = useId()
+  useLayoutEffect(() => registry.addHost(id, placement), [registry, id, placement])
+  const {topHost, entries} = useSyncExternalStore(registry.subscribe, registry.getSnapshot)
+  if (topHost !== id) return null
+  return (
+    <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
+      {entries.map((entry) => (
+        <View key={entry.key} style={StyleSheet.absoluteFill} pointerEvents="box-none">
+          {entry.node}
+        </View>
+      ))}
+    </View>
+  )
+}
+
+interface PortalProps {
+  /** Numeric layer from `LAYERS` in `@duro-app/tokens/keys`. */
+  layer: number
+  children: ReactNode
+}
+
+/**
+ * Draws its children in the top host, above the app and every open Duro
+ * Modal. The children keep the source's theme and resolved colours; no other
+ * context crosses, so pass data, not components that read the app's contexts.
+ */
+export function Portal({layer, children}: PortalProps) {
+  const registry = useHostRegistry('Portal')
+  const key = useId()
+  const scope = useContext(ThemeScopeContext)
+  const resolvedColors = useContext(ResolvedColorsContext)
+
+  useLayoutEffect(() => {
+    registry.setEntry({
+      key,
+      layer,
+      node: (
+        <ThemeScopeContext.Provider value={scope}>
+          <ResolvedColorsContext.Provider value={resolvedColors}>
+            <html.div style={[...scope.styles, styles.entry] as DivStyle}>{children}</html.div>
+          </ResolvedColorsContext.Provider>
+        </ThemeScopeContext.Provider>
+      ),
+    })
+  })
+  useEffect(() => () => registry.removeEntry(key), [registry, key])
+  return null
+}

package/src/shared/portal/hostRegistry.ts

@@ -0,0 +1,76 @@
+import type {ReactNode} from 'react'
+
+/** One passive surface (a toast region) waiting for a host to draw it. */
+export interface PortalEntry {
+  readonly key: string
+  /** Numeric layer from `LAYERS` in `@duro-app/tokens/keys`; higher draws on top. */
+  readonly layer: number
+  readonly node: ReactNode
+}
+
+export interface HostRegistrySnapshot {
+  /** The host that draws every entry: the last one presented, else the root. */
+  readonly topHost: string | undefined
+  /** Entries ordered by layer, lowest first (equal layers keep insertion order). */
+  readonly entries: readonly PortalEntry[]
+}
+
+/**
+ * The hosts that passive surfaces draw into, on native: the app root, each
+ * open Duro Modal and each `PortalHost` a consumer mounts in a natively
+ * presented route. Entries render in the top host only, so a toast raised
+ * under an open Dialog draws above it.
+ *
+ * A plain store (subscribe / getSnapshot) for `useSyncExternalStore`; it holds
+ * no React state and imports nothing from React Native.
+ */
+export interface HostRegistry {
+  /** Adds a host. A `base` host (the app root) always sits below the others. */
+  addHost(id: string, placement: 'base' | 'presented'): () => void
+  setEntry(entry: PortalEntry): void
+  removeEntry(key: string): void
+  getSnapshot(): HostRegistrySnapshot
+  subscribe(listener: () => void): () => void
+}
+
+export function createHostRegistry(): HostRegistry {
+  let hosts: readonly string[] = []
+  let entries: readonly PortalEntry[] = []
+  let snapshot: HostRegistrySnapshot = {topHost: undefined, entries}
+  const listeners = new Set<() => void>()
+
+  const publish = () => {
+    snapshot = {topHost: hosts[hosts.length - 1], entries}
+    for (const listener of listeners) listener()
+  }
+
+  return {
+    addHost(id, placement) {
+      hosts = placement === 'base' ? [id, ...hosts] : [...hosts, id]
+      publish()
+      return () => {
+        hosts = hosts.filter((host) => host !== id)
+        publish()
+      }
+    },
+    setEntry(entry) {
+      const others = entries.filter((existing) => existing.key !== entry.key)
+      const at = others.findIndex((existing) => existing.layer > entry.layer)
+      entries =
+        at === -1 ? [...others, entry] : [...others.slice(0, at), entry, ...others.slice(at)]
+      publish()
+    },
+    removeEntry(key) {
+      if (!entries.some((entry) => entry.key === key)) return
+      entries = entries.filter((entry) => entry.key !== key)
+      publish()
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}

package/src/shared/portal/themeScope.native.ts

@@ -0,0 +1,18 @@
+import {createContext} from 'react'
+import type {ColorToken} from '@duro-app/tokens/keys'
+import {darkColors} from '@duro-app/tokens/raw'
+
+/**
+ * The theme styles in force where a component renders: every enclosing
+ * ThemeProvider's createTheme objects, outermost first. A native Portal
+ * re-applies them around its entry, because the host it draws into sits
+ * outside the source's ThemeProviders.
+ */
+export interface ThemeScope {
+  readonly styles: readonly unknown[]
+}
+
+export const ThemeScopeContext = createContext<ThemeScope>({styles: []})
+
+/** The nearest ThemeProvider's palette as colour strings (native). */
+export const ResolvedColorsContext = createContext<Record<ColorToken, string>>(darkColors)

package/src/shared/pressableChild.ts

@@ -0,0 +1,33 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react'
+import {mergeRefs} from './mergeRefs'
+
+interface PressableChildProps {
+  onClick?: () => void
+  ref?: Ref<unknown>
+}
+
+/**
+ * Native overlay triggers and closes: native presses do not bubble to a
+ * wrapper as web clicks do, so the one child (a Button) gets the handler
+ * itself, after its own. `ref` also receives the child's host, where focus
+ * returns when the overlay closes.
+ */
+export function withPress(children: ReactNode, onPress: () => void, ref?: Ref<unknown>) {
+  const child = Children.only(children)
+  if (!isValidElement<PressableChildProps>(child)) return null
+  const own = child.props.onClick
+  return cloneElement(child as ReactElement<PressableChildProps>, {
+    ...(ref ? {ref: mergeRefs(child.props.ref, ref)} : {}),
+    onClick: () => {
+      own?.()
+      onPress()
+    },
+  })
+}

package/src/shared/safeArea.native.ts

@@ -0,0 +1,22 @@
+import {useContext} from 'react'
+import {SafeAreaInsetsContext, type EdgeInsets} from 'react-native-safe-area-context'
+import {devWarnOnce} from './devWarnOnce'
+
+const NO_INSETS: EdgeInsets = {top: 0, right: 0, bottom: 0, left: 0}
+
+/**
+ * The window's safe-area insets from the app's SafeAreaProvider (expo-router
+ * mounts one). Modal content is a React portal, so overlays inside an
+ * OverlayModal read the same insets. Without a provider, no insets, and a
+ * development warning names the missing provider.
+ */
+export function useSafeAreaInsets(): EdgeInsets {
+  const insets = useContext(SafeAreaInsetsContext)
+  if (insets) return insets
+  devWarnOnce(
+    'safeArea',
+    'no-provider',
+    'No SafeAreaProvider above this Duro overlay: it draws without safe-area insets. Wrap the app in react-native-safe-area-context’s SafeAreaProvider.',
+  )
+  return NO_INSETS
+}

package/src/shared/useKeyboardHeight.native.ts

@@ -0,0 +1,18 @@
+import {useEffect, useState} from 'react'
+import {Keyboard, Platform} from 'react-native'
+
+/** The on-screen keyboard's height while it is shown, else 0. */
+export function useKeyboardHeight(): number {
+  const [height, setHeight] = useState(0)
+  useEffect(() => {
+    // iOS announces the keyboard before it moves, Android only after.
+    const show = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow'
+    const hide = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide'
+    const subs = [
+      Keyboard.addListener(show, (e) => setHeight(e.endCoordinates.height)),
+      Keyboard.addListener(hide, () => setHeight(0)),
+    ]
+    return () => subs.forEach((s) => s.remove())
+  }, [])
+  return height
+}

package/src/shared/useOverlayOpenState.ts

@@ -0,0 +1,128 @@
+import {useCallback, useEffect, useRef, useState} from 'react'
+import {DURATION_MS, type DurationToken} from '@duro-app/tokens/keys'
+
+/**
+ * When the owner hears that the overlay closed.
+ * - `after-exit`: once the exit animation has played (Dialog, Drawer): the
+ *   overlay stays logically open while it animates out.
+ * - `at-once`: as soon as the close is asked for (DetailPanel); the panel
+ *   still animates out while `present`.
+ */
+export type CloseNotice = 'after-exit' | 'at-once'
+
+interface Options {
+  /** Controlled open state. */
+  open: boolean | undefined
+  /** Initial open state when uncontrolled. */
+  defaultOpen: boolean
+  onOpenChange: ((open: boolean) => void) | undefined
+  /** Motion token the exit animation lasts. */
+  exitDuration: DurationToken
+  closeNotice: CloseNotice
+}
+
+export interface OverlayOpenState {
+  /** Logically open (what `open` / the uncontrolled state says). */
+  open: boolean
+  /** Rendered: open, or animating out. */
+  present: boolean
+  /** Playing the exit animation. */
+  closing: boolean
+  requestOpen: () => void
+  /** Animated close. Does nothing while a close is already playing. */
+  requestClose: () => void
+  /** Close without the exit animation (a swipe that already moved the panel out). */
+  closeNow: () => void
+}
+
+/**
+ * Open, presence and exit-animation state shared by Dialog, Drawer and
+ * DetailPanel on both platforms. A controlled `open` that turns false from
+ * outside plays the exit animation too.
+ */
+export function useOverlayOpenState({
+  open: controlledOpen,
+  defaultOpen,
+  onOpenChange,
+  exitDuration,
+  closeNotice,
+}: Options): OverlayOpenState {
+  const isControlled = controlledOpen !== undefined
+  const [internalOpen, setInternalOpen] = useState(defaultOpen)
+  const open = isControlled ? controlledOpen : internalOpen
+  const [present, setPresent] = useState(open)
+  const [closing, setClosing] = useState(false)
+  const closingRef = useRef(false)
+  // The playing exit was started by the owner's `open` turning false (not by
+  // requestClose), so an `open` turning true again cancels it.
+  const outsideExitRef = useRef(false)
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const cancelExit = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current)
+    timerRef.current = null
+    closingRef.current = false
+    outsideExitRef.current = false
+    setClosing(false)
+  }, [])
+
+  const playExit = useCallback(
+    (afterExit?: () => void) => {
+      closingRef.current = true
+      outsideExitRef.current = afterExit === undefined
+      setClosing(true)
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null
+        closingRef.current = false
+        outsideExitRef.current = false
+        setClosing(false)
+        setPresent(false)
+        afterExit?.()
+      }, DURATION_MS[exitDuration])
+    },
+    [exitDuration],
+  )
+
+  const notifyClosed = useCallback(() => {
+    if (!isControlled) setInternalOpen(false)
+    onOpenChange?.(false)
+  }, [isControlled, onOpenChange])
+
+  const requestOpen = useCallback(() => {
+    cancelExit()
+    setPresent(true)
+    if (!isControlled) setInternalOpen(true)
+    onOpenChange?.(true)
+  }, [cancelExit, isControlled, onOpenChange])
+
+  const requestClose = useCallback(() => {
+    if (closingRef.current) return
+    if (closeNotice === 'after-exit') playExit(notifyClosed)
+    else notifyClosed()
+  }, [closeNotice, playExit, notifyClosed])
+
+  const closeNow = useCallback(() => {
+    cancelExit()
+    setPresent(false)
+    notifyClosed()
+  }, [cancelExit, notifyClosed])
+
+  // Presence follows the logical state: an open from outside shows the
+  // overlay, a close from outside (or an `at-once` close) animates it out.
+  useEffect(() => {
+    if (open && outsideExitRef.current) cancelExit()
+    else if (open && !present && !closingRef.current) setPresent(true)
+    else if (!open && present && !closingRef.current) playExit()
+  }, [open, present, playExit, cancelExit])
+
+  useEffect(
+    () => () => {
+      if (timerRef.current) clearTimeout(timerRef.current)
+    },
+    [],
+  )
+
+  // An open is rendered in the same commit (a consumer's effect on `open` can
+  // already reach the overlay's content); the state catches up in the effect.
+  return {open, present: open || present, closing, requestOpen, requestClose, closeNow}
+}