@duro-app/ui 5.11.0 → 5.13.0

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}
+}

package/src/components/Menu/useMenuRoot.ts

@@ -1,12 +1,9 @@
 import {useState, useCallback, useRef, useId, useEffect, useLayoutEffect} from 'react'
 import type {MenuContextValue} from './MenuContext'
 import {isOutsidePress} from '../Popover/outside'
+import {useMenuOpen, type MenuOpenOptions} from './useMenuOpen'
 
-export interface MenuRootOptions {
-  open?: boolean
-  defaultOpen?: boolean
-  onOpenChange?: (open: boolean) => void
-}
+export type MenuRootOptions = MenuOpenOptions
 
 /**
  * The menu-button pattern (WAI-ARIA APG): on open, focus moves to the
@@ -16,10 +13,8 @@ export interface MenuRootOptions {
  * elsewhere (an editor) are never intercepted, and Escape stops there so an
  * enclosing Popover or Dialog stays open.
  */
-export function useMenuRoot({open: openProp, defaultOpen = false, onOpenChange}: MenuRootOptions) {
-  const [inner, setInner] = useState(defaultOpen)
-  const controlled = openProp !== undefined
-  const open = controlled ? openProp : inner
+export function useMenuRoot(options: MenuRootOptions) {
+  const {open, openRef, setOpen} = useMenuOpen(options)
   const [highlightedId, setHighlightedId] = useState<string | null>(null)
   // Read by the keydown handler, so activating an item is not a side effect
   // inside a state updater (React may run updaters twice).
@@ -34,38 +29,24 @@ export function useMenuRoot({open: openProp, defaultOpen = false, onOpenChange}:
   const popupRef = useRef<HTMLDivElement | null>(null)
   const itemsRef = useRef(new Map<string, HTMLElement>())
   const orderRef = useRef<string[]>([])
-  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],
-  )
-
   // Closes and leaves focus where it is (a press elsewhere put it there).
   const dismiss = useCallback(() => {
     if (!openRef.current) return
     setOpen(false)
     setHighlightedId(null)
-  }, [setOpen])
+  }, [openRef, setOpen])
 
   // Closes and puts focus back on the trigger.
   const close = useCallback(() => {
     if (!openRef.current) return
     dismiss()
     triggerRef.current?.focus()
-  }, [dismiss])
+  }, [openRef, dismiss])
 
   const toggle = useCallback(() => {
     if (openRef.current) close()
     else setOpen(true)
-  }, [close, setOpen])
+  }, [openRef, close, setOpen])
 
   // On open: focus the menu and highlight the first item. Child effects (item
   // registration) run before this parent effect, so orderRef is populated.

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

@@ -8,6 +8,8 @@ export const styles = css.create({
   track: {
     position: 'relative',
     width: '100%',
+    // Native has no border-box reset (the web's global-reset.css); declare it.
+    boxSizing: 'border-box',
     height: sizes.meterH,
     borderRadius: radii.full,
     backgroundColor: colors.border,

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

@@ -6,9 +6,13 @@ import {sizes} from '@duro-app/tokens/tokens/sizes.css'
 export const styles = css.create({
   root: {
     width: '100%',
+    // Native has no border-box reset (the web's global-reset.css); declare it.
+    boxSizing: 'border-box',
   },
   container: {
     width: '100%',
+    // Native has no border-box reset (the web's global-reset.css); declare it.
+    boxSizing: 'border-box',
     marginLeft: 'auto',
     marginRight: 'auto',
   },

package/src/components/Popover/Popover.meta.ts

@@ -2,7 +2,7 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves. Popover.Trigger takes size="small" beside small Toggles. Popover.Popup raised draws it over another floating surface (floatingRaised, popoverRaised in a modal), never over a modal.',
+    'Non-modal anchored overlay for small interactive content. Compound component — Root is required (throws without it). Anchored to Popover.Trigger, or to a virtual anchor (a () => DOMRect) when there is no Trigger; call reposition() through a ref when the anchor moves. Popover.Trigger takes size="small" beside small Toggles. Popover.Popup raised draws it over another floating surface (floatingRaised, popoverRaised in a modal), never over a modal. On React Native the popup is modal: it is placed against Popover.Trigger in an overlay, a press outside or the Android back button closes it, and screen-reader focus moves in on open and back to the trigger on close; anchor, ignore and raised are web only.',
   whenToUse: [
     'A small form or controls tied to one element that stay open while you work in them',
     'Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor',

package/src/components/Popover/Popover.native.tsx

@@ -0,0 +1,205 @@
+import {
+  createContext,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
+import {Pressable} from 'react-native'
+import {html} from 'react-strict-dom'
+import {styles} from './styles.css'
+import {nativeStyles} from './native.css'
+import type {PopoverAlign, PopoverSide} from './position'
+import {AnchoredOverlay} from '../../shared/portal/AnchoredOverlay'
+import {focusForAccessibility} from '../../shared/accessibilityFocus'
+import {mergeRefs} from '../../shared/mergeRefs'
+import {ModalContext} from '../../shared/ModalContext'
+import type {ControlSize} from '../../shared/types'
+import {useTooltipHint} from '../Tooltip/TooltipHint'
+import {ControlContextBoundary} from '../Toolbar/ControlContextBoundary'
+
+interface PopoverContextValue {
+  open: boolean
+  setOpen: (open: boolean) => void
+  popoverId: string
+  side: PopoverSide
+  align: PopoverAlign
+  triggerRef: RefObject<unknown>
+  /** Bumped by `reposition()`: the popup measures its trigger again */
+  placement: number
+}
+
+const PopoverContext = createContext<PopoverContextValue | null>(null)
+
+function usePopover(part: string) {
+  const ctx = useContext(PopoverContext)
+  if (!ctx) throw new Error(`Popover.${part} must be used within Popover.Root`)
+  return ctx
+}
+
+export interface PopoverHandle {
+  /** Place the popup against its trigger again. */
+  reposition: () => void
+}
+
+interface RootProps {
+  children: ReactNode
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  side?: PopoverSide
+  align?: PopoverAlign
+  /** Web only: native places the popup against Popover.Trigger. */
+  anchor?: () => DOMRect
+  /** Web only: on native the popup is modal, so nothing outside it is pressed. */
+  ignore?: ReadonlyArray<unknown>
+  ref?: Ref<PopoverHandle>
+}
+
+/**
+ * Native Popover (plan N0, Slice B): the popup is placed against the trigger
+ * in an OverlayModal, so it is modal on native where the web's is not. A
+ * press outside or Android's back button closes it; the screen reader's
+ * focus moves into it on open and back to the trigger on close.
+ */
+function Root({
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  side = 'bottom',
+  align = 'start',
+  ref,
+}: RootProps) {
+  const [inner, setInner] = useState(defaultOpen)
+  const controlled = openProp !== undefined
+  const open = controlled ? openProp : inner
+  const popoverId = useId()
+  const triggerRef = useRef<unknown>(null)
+  const [placement, setPlacement] = useState(0)
+  const openRef = useRef(open)
+  openRef.current = open
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!controlled) setInner(next)
+      if (next !== openRef.current) onOpenChange?.(next)
+    },
+    [controlled, onOpenChange],
+  )
+
+  useImperativeHandle(ref, () => ({reposition: () => setPlacement((n) => n + 1)}), [])
+
+  const wasOpen = useRef(open)
+  useEffect(() => {
+    if (wasOpen.current && !open) focusForAccessibility(triggerRef.current, 'Popover')
+    wasOpen.current = open
+  }, [open])
+
+  return (
+    <PopoverContext.Provider value={{open, setOpen, popoverId, side, align, triggerRef, placement}}>
+      {children}
+    </PopoverContext.Provider>
+  )
+}
+
+interface TriggerProps {
+  children: ReactNode
+  /** Accessible name: required when the label is an icon only. */
+  'aria-label'?: string
+  /** `small` matches a small Toggle or Button beside it. Default: `default`. */
+  size?: ControlSize
+  /** The trigger's host, e.g. to measure it. */
+  ref?: Ref<unknown>
+}
+
+/**
+ * An RN Pressable host, so it carries an enclosing Tooltip's text as its hint.
+ *
+ * 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, size = 'default', ref}: TriggerProps) {
+  const {open, setOpen, triggerRef} = usePopover('Trigger')
+  const hint = useTooltipHint()
+  return (
+    <Pressable
+      ref={mergeRefs(triggerRef, ref) as Ref<never>}
+      onPress={() => setOpen(!open)}
+      accessibilityRole="button"
+      accessibilityLabel={ariaLabel}
+      accessibilityHint={hint}
+      accessibilityState={{expanded: open}}
+    >
+      <html.div
+        style={[styles.trigger, nativeStyles.nativeFlex, size === 'small' && styles.triggerSmall]}
+      >
+        {children}
+      </html.div>
+    </Pressable>
+  )
+}
+
+interface PopupProps {
+  children: ReactNode
+  /** Accessible name for the dialog. */
+  label: string
+  /** Web only: on native every popup is its own Modal, above what opened it. */
+  raised?: boolean
+}
+
+function Popup({children, label}: PopupProps) {
+  const {open, setOpen, popoverId, side, align, triggerRef, placement} = usePopover('Popup')
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <AnchoredOverlay
+      key={placement}
+      visible={open}
+      anchorRef={triggerRef}
+      side={side}
+      align={align}
+      onRequestClose={() => setOpen(false)}
+      onShow={() => focusForAccessibility(popupRef.current, 'Popover')}
+    >
+      <html.div
+        ref={popupRef}
+        id={popoverId}
+        role="dialog"
+        aria-modal
+        aria-label={label}
+        style={[styles.popup, nativeStyles.popupInPlace]}
+      >
+        {/* Modal on native: a Popover or Menu opened inside it stacks above it. */}
+        <ModalContext.Provider value={true}>
+          <ControlContextBoundary>{children}</ControlContextBoundary>
+        </ModalContext.Provider>
+      </html.div>
+    </AnchoredOverlay>
+  )
+}
+
+function Close({children}: {children: ReactNode}) {
+  const {setOpen} = usePopover('Close')
+  return (
+    <html.button
+      type="button"
+      onClick={() => setOpen(false)}
+      style={[styles.close, nativeStyles.nativeFlex]}
+    >
+      {children}
+    </html.button>
+  )
+}
+
+export const Popover = {
+  Root,
+  Trigger,
+  Popup,
+  Close,
+}

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

@@ -0,0 +1,13 @@
+import {css} from 'react-strict-dom'
+
+/** Native Popover 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',
+  },
+})

package/src/components/RadioGroup/RadioGroup.meta.ts

@@ -30,7 +30,7 @@ export const meta: ComponentMeta = {
         'RadioGroup for form single-select; ToggleGroup for segmented/toolbar single-select',
     },
   ],
-  example: `<RadioGroup.Root defaultValue="email" onValueChange={(v) => console.log(v)}>
+  example: `<RadioGroup.Root name="channel" defaultValue="email" onValueChange={(v) => console.log(v)}>
   <RadioGroup.Item value="email">Email</RadioGroup.Item>
   <RadioGroup.Item value="sms">SMS</RadioGroup.Item>
   <RadioGroup.Item value="push">Push notification</RadioGroup.Item>