@duro-app/ui 5.13.0 → 5.14.0

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,7 +2,7 @@ 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). 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. 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)',

package/src/components/Drawer/Drawer.native.tsx

@@ -33,6 +33,7 @@ import {ModalContext} from '../../shared/ModalContext'
 import {OverlayModal} from '../../shared/portal/OverlayModal'
 import {focusForAccessibility} from '../../shared/accessibilityFocus'
 import {useSafeAreaInsets} from '../../shared/safeArea'
+import {useKeyboardHeight} from '../../shared/useKeyboardHeight'
 import {withPress} from '../../shared/pressableChild'
 import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
 import {Icon} from '../Icon/Icon'
@@ -145,12 +146,17 @@ function Portal({children, size = 'md', grabberLabels = DEFAULT_GRABBER_LABELS}:
   } = useDrawer()
   const window = useWindowDimensions()
   const insets = useSafeAreaInsets()
+  // A bottom drawer rides above the on-screen keyboard: its detents measure
+  // from the keyboard's top edge, so a search field and its results stay seen.
+  const keyboard = useKeyboardHeight()
+  const lift = anchor === 'bottom' ? keyboard : 0
+  const availableHeight = window.height - lift
   const bottom = anchor === 'bottom'
   const snapping = snapPoints.length > 0
 
   const heights = useMemo(
-    () => snapPoints.map((p) => detentHeight(p, window.height, insets.top)),
-    [snapPoints, window.height, insets.top],
+    () => snapPoints.map((p) => detentHeight(p, availableHeight, insets.top)),
+    [snapPoints, availableHeight, insets.top],
   )
   const high = heights.length > 0 ? heights[heights.length - 1] : 0
   // Where the panel rests at its detent: its offset below its own full height.
@@ -316,11 +322,11 @@ function Portal({children, size = 'md', grabberLabels = DEFAULT_GRABBER_LABELS}:
 
   const placement = bottom
     ? snapping
-      ? [layout.bottom, {height: high + SNAP_MAX_OVERSHOOT, bottom: -SNAP_MAX_OVERSHOOT}]
-      : [layout.bottom, {maxHeight: window.height * CONTENT_SHEET_CAP}]
+      ? [layout.bottom, {height: high + SNAP_MAX_OVERSHOOT, bottom: lift - SNAP_MAX_OVERSHOOT}]
+      : [layout.bottom, {bottom: lift, maxHeight: availableHeight * CONTENT_SHEET_CAP}]
     : [layout.side, anchor === 'left' ? layout.left : layout.right, {maxWidth: PANEL_WIDTH[size]}]
   const padTop = bottom ? 0 : insets.top
-  const padBottom = insets.bottom + (snapping ? SNAP_MAX_OVERSHOOT : 0)
+  const padBottom = (lift > 0 ? 0 : insets.bottom) + (snapping ? SNAP_MAX_OVERSHOOT : 0)
 
   const nextIndex = cycleDetent(snapIndex, snapPoints.length)
   const onGrabberAction = (e: AccessibilityActionEvent) => {
@@ -420,7 +426,13 @@ const layout = StyleSheet.create({
  * overflow. In a bottom sheet the drag defers to it: the list scrolls, and
  * moves the sheet only from its top.
  */
-function Body({children}: {children: ReactNode}) {
+interface BodyProps {
+  children: ReactNode
+  /** No side padding: rows that run to the panel's edges, as a picker's list. */
+  flush?: boolean
+}
+
+function Body({children, flush = false}: BodyProps) {
   const sheet = useContext(SheetScrollContext)
   const {snapPoints} = useDrawer()
   if (!sheet) return null
@@ -431,9 +443,19 @@ function Body({children}: {children: ReactNode}) {
         onScroll={sheet.onScroll}
         scrollEventThrottle={16}
         bounces={false}
+        // Presses inside the sheet keep the keyboard up. A ScrollView above the
+        // sheet's Modal can still take the first touch, which is why picker
+        // rows use Gesture Handler's Pressable (Listbox.native).
+        keyboardShouldPersistTaps="handled"
         style={snapPoints.length > 0 ? layout.bodyFill : layout.body}
       >
-        <html.div style={[nativeStyles.bodyContent, nativeStyles.hiddenBelow(sheet.hiddenBelow)]}>
+        <html.div
+          style={[
+            nativeStyles.bodyContent,
+            flush && nativeStyles.bodyFlush,
+            nativeStyles.hiddenBelow(sheet.hiddenBelow),
+          ]}
+        >
           {children}
         </html.div>
       </Animated.ScrollView>

package/src/components/Drawer/Drawer.tsx

@@ -229,12 +229,21 @@ function Portal({children, size = 'md', grabberLabels = DEFAULT_GRABBER_LABELS}:
 
 // --- Body ---
 
-function Body({children}: {children: ReactNode}) {
+interface BodyProps {
+  children: ReactNode
+  /** No side padding: rows that run to the panel's edges, as a picker's list. */
+  flush?: boolean
+}
+
+function Body({children, flush = false}: BodyProps) {
   const {snapPoints} = useDrawer()
   // A snap sheet's Body is its scroll viewport: a drag there scrolls it, and
   // moves the sheet only from the top edge (or upward, below the largest detent).
   return (
-    <html.div style={styles.body} data-duro-scroll={snapPoints.length > 0 ? '' : undefined}>
+    <html.div
+      style={[styles.body, flush && styles.bodyFlush]}
+      data-duro-scroll={snapPoints.length > 0 ? '' : undefined}
+    >
       {children}
     </html.div>
   )

package/src/components/Drawer/DrawerSnap.stories.tsx

@@ -19,6 +19,7 @@ interface SheetArgs {
   snapPoints: SnapPoint[]
   defaultSnapPoint: SnapPoint
   titleAlign: 'start' | 'center'
+  flush: boolean
   onOpenChange?: (open: boolean) => void
 }
 
@@ -26,11 +27,15 @@ const DEFAULT_ARGS: SheetArgs = {
   snapPoints: ['medium', 'large'],
   defaultSnapPoint: 'medium',
   titleAlign: 'center',
+  flush: false,
 }
 
 /** The picked B0 direction (docs/mockups/native-sheet/Done.dc.html): grabber, centred title, a text Done. */
 function Sheet(props: Partial<SheetArgs>) {
-  const {snapPoints, defaultSnapPoint, titleAlign, onOpenChange} = {...DEFAULT_ARGS, ...props}
+  const {snapPoints, defaultSnapPoint, titleAlign, flush, onOpenChange} = {
+    ...DEFAULT_ARGS,
+    ...props,
+  }
   return (
     <Drawer.Root
       anchor="bottom"
@@ -46,7 +51,7 @@ function Sheet(props: Partial<SheetArgs>) {
             <Button variant="link">Done</Button>
           </Drawer.Close>
         </Drawer.Header>
-        <Drawer.Body>
+        <Drawer.Body flush={flush}>
           <List.Root aria-label="Sessions">
             {SESSIONS.map((s) => (
               <List.Item key={s}>
@@ -78,6 +83,11 @@ export const SnapSheet: StoryObj<SheetArgs> = {
       options: ['start', 'center'],
       description: 'Drawer.Header: the title at the start, or centred with the close at the end',
     },
+    flush: {
+      control: 'boolean',
+      description:
+        "Drawer.Body: no side padding, so rows run to the panel's edges (a picker's list)",
+    },
   },
   // Keyed by the opening detent: it seeds state on mount, so a change remounts the sheet.
   render: (args) => (
@@ -203,3 +213,13 @@ export const DoneCloses: Story = {
     await waitFor(() => expect(getDialog()).toBeNull())
   },
 }
+
+export const FlushBody: Story = {
+  render: () => <Sheet flush />,
+  play: async () => {
+    await waitFor(() => expect(getDialog()).not.toBeNull())
+    const body = getBody()
+    await expect(getComputedStyle(body).paddingLeft).toBe('0px')
+    await expect(getComputedStyle(body).paddingRight).toBe('0px')
+  },
+}

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

@@ -52,6 +52,10 @@ export const nativeStyles = css.create({
     paddingRight: spacing.lg,
     paddingBottom: spacing.lg,
   },
+  bodyFlush: {
+    paddingLeft: 0,
+    paddingRight: 0,
+  },
   // A snap sheet resting below its largest detent: its lower part is off
   // screen, so the list scrolls that far further to show its end.
   hiddenBelow: (height: number) => ({paddingBottom: height}),

package/src/components/Drawer/styles.css.ts

@@ -202,4 +202,8 @@ export const styles = css.create({
     overflowY: 'auto',
     flex: 1,
   },
+  bodyFlush: {
+    paddingLeft: 0,
+    paddingRight: 0,
+  },
 })

package/src/components/Form/Form.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Form wrapper with Effect Schema validation and react-hook-form integration. Provides FormContext to child Field components.',
+    'Form wrapper with Effect Schema validation and react-hook-form integration. Provides FormContext to child Field components. On React Native, @duro-app/ui/form resolves to a native Form (a view, not a <form>): a Button type="submit" inside it runs the validated submit, since there is no DOM submit event.',
   whenToUse: ['Any form that needs validation', 'Multi-field forms with submit handling'],
   whenNotToUse: [
     'Single standalone field without validation — use Field.Root directly',

package/src/components/Form/Form.native.tsx

@@ -0,0 +1,120 @@
+import {type ReactNode, useCallback, useEffect, useMemo, useRef} from 'react'
+import {css, html} from 'react-strict-dom'
+import {
+  useForm,
+  FormProvider,
+  type UseFormReturn,
+  type DefaultValues,
+  type FieldValues,
+  type FieldErrors,
+  type Path,
+} from 'react-hook-form'
+import {effectTsResolver} from '@hookform/resolvers/effect-ts'
+import type {Schema} from 'effect'
+import {FormContext, type LabelPosition, type NecessityIndicator} from './FormContext'
+import {FormSubmitContext} from './FormSubmitContext'
+
+export interface FormProps<T extends FieldValues> {
+  schema: Schema.Schema<T>
+  defaultValues: DefaultValues<T>
+  onSubmit: (data: T) => void | Promise<void>
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  necessityIndicator?: NecessityIndicator
+  validationErrors?: Partial<Record<Path<T>, string>>
+  children: ReactNode | ((methods: UseFormReturn<T>) => ReactNode)
+}
+
+const formStyles = css.create({
+  disabled: {
+    opacity: 0.5,
+    pointerEvents: 'none',
+  },
+})
+
+/**
+ * Native Form (plan N0, Slice C): the web Form's validation and server-error
+ * sync, in a view rather than a <form>. A `type="submit"` Button inside it
+ * submits through FormSubmitContext.
+ */
+export function Form<T extends FieldValues>({
+  schema,
+  defaultValues,
+  onSubmit,
+  disabled = false,
+  labelPosition = 'top',
+  necessityIndicator = false,
+  validationErrors,
+  children,
+}: FormProps<T>) {
+  const methods = useForm<T>({
+    resolver: effectTsResolver(schema),
+    defaultValues,
+    mode: 'onTouched',
+    reValidateMode: 'onChange',
+  })
+
+  // Sync server-side validation errors into RHF
+  const prevErrorKeysRef = useRef<string[]>([])
+  useEffect(() => {
+    const prevKeys = prevErrorKeysRef.current
+    const nextKeys = validationErrors ? Object.keys(validationErrors) : []
+
+    // Clear errors that were removed
+    for (const key of prevKeys) {
+      if (!nextKeys.includes(key)) {
+        methods.clearErrors(key as Path<T>)
+      }
+    }
+
+    // Set new errors
+    if (validationErrors) {
+      for (const [key, message] of Object.entries(validationErrors)) {
+        if (message) {
+          methods.setError(key as Path<T>, {type: 'server', message: message as string})
+        }
+      }
+    }
+
+    prevErrorKeysRef.current = nextKeys
+  }, [validationErrors, methods])
+
+  const onInvalid = useCallback(
+    (errors: FieldErrors<T>) => {
+      const firstField = Object.keys(errors)[0]
+      if (firstField) {
+        methods.setFocus(firstField as Path<T>)
+      }
+    },
+    [methods],
+  )
+
+  // Native has no submit event: a type="submit" Button calls this instead.
+  const submit = useCallback(() => {
+    // A rejected onSubmit reaches the app's global error handler, not silence.
+    methods
+      .handleSubmit(onSubmit, onInvalid)()
+      .catch((error: unknown) => {
+        setTimeout(() => {
+          throw error
+        })
+      })
+  }, [methods, onSubmit, onInvalid])
+
+  const formCtx = useMemo(
+    () => ({disabled, labelPosition, necessityIndicator}),
+    [disabled, labelPosition, necessityIndicator],
+  )
+
+  return (
+    <FormProvider {...methods}>
+      <FormContext.Provider value={formCtx}>
+        <FormSubmitContext.Provider value={disabled ? null : submit}>
+          <html.div aria-disabled={disabled || undefined} style={disabled && formStyles.disabled}>
+            {typeof children === 'function' ? children(methods) : children}
+          </html.div>
+        </FormSubmitContext.Provider>
+      </FormContext.Provider>
+    </FormProvider>
+  )
+}

package/src/components/Form/FormSubmitContext.ts

@@ -0,0 +1,12 @@
+import {createContext, useContext} from 'react'
+
+/**
+ * How a `type="submit"` Button submits its Form where there is no DOM submit
+ * event: on native, Form provides its validated submit here. The web Form
+ * provides nothing; the browser's form submission does it.
+ */
+export const FormSubmitContext = createContext<(() => void) | null>(null)
+
+export function useFormSubmit() {
+  return useContext(FormSubmitContext)
+}

package/src/components/Listbox/Listbox.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Popup list of options for an input that keeps focus — an editor typeahead (mentions, slash commands) or a custom combobox. The anchor owns focus and the keyboard: it sets the controlled highlightedId and spreads Listbox.getAnchorProps() for aria-controls / aria-expanded / aria-activedescendant. A press on an option never takes focus from the anchor. Portalled and placed against anchor() (an input rect or a caret rect), capped at a size-token maxHeight (default listMaxH).',
+    'Popup list of options for an input that keeps focus — an editor typeahead (mentions, slash commands) or a custom combobox. The anchor owns focus and the keyboard: it sets the controlled highlightedId and spreads Listbox.getAnchorProps() for aria-controls / aria-expanded / aria-activedescendant. A press on an option never takes focus from the anchor. Portalled and placed against anchor() (an input rect or a caret rect), capped at a size-token maxHeight (default listMaxH). On React Native it is a plain list laid out where it is rendered (inside a Select or Combobox sheet): nothing is anchored or highlighted, the selected option is filled with a trailing check, and a press calls onSelect.',
   whenToUse: [
     'Typeahead inside a rich-text editor, where focus must stay in the editor',
     'A custom combobox whose input is not Combobox.Input',