@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/swipe-row/SwipeRow.tsx

@@ -0,0 +1,219 @@
+// SwipeRow (spec: wave-2/swipe-row.md). A row whose actions are revealed by a
+// horizontal swipe on touch screens, and always reachable from an actions
+// menu button (WCAG 2.5.1: the gesture is only a shortcut).
+import { Archive, Ellipsis, Pencil, Star, Trash2 } from 'lucide-react'
+import { useMemo, useRef, useState, type KeyboardEvent, type ReactNode, type TouchEvent } from 'react'
+import { useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { inertProps } from '../../internal/inert'
+import { useReducedMotion } from '../../internal/media'
+import { beginTrack, advanceTrack, firstTouch, type Track } from '../../internal/platform/touchTrack'
+import { useMessages } from '../../internal/provider'
+import { playHaptic } from '../../utilities/haptics/haptics'
+import { ActionMenu, type ActionMenuItem } from '../action-menu/ActionMenu'
+import { Button } from '../button/Button'
+
+export type SwipeTone = 'neutral' | 'danger' | 'pending' | 'positive'
+export type SwipeSide = 'none' | 'leading' | 'trailing'
+
+export interface SwipeAction {
+  label: string
+  icon?: ReactNode
+  tone: SwipeTone
+  onAction: () => void
+  /** The host offers undo, so a destructive full swipe needs no confirmation. */
+  undoable?: boolean
+}
+
+export interface SwipeRowProps {
+  children: ReactNode
+  /** Name of the row, used in the actions button name ("Actions for …"). */
+  label: string
+  leadingActions?: SwipeAction[]
+  trailingActions?: SwipeAction[]
+  fullSwipe?: boolean
+  /** Fraction of the row width past which the first action of a side fires. */
+  fullSwipeFraction?: number
+  /** Fraction of the row width the revealed actions occupy. */
+  revealFraction?: number
+  onRevealChange?: (side: SwipeSide) => void
+  /**
+   * Asked before a destructive full swipe fires (for example ConfirmService's
+   * confirm). Without it, and without `undoable`, a destructive full swipe
+   * only reveals the actions.
+   */
+  confirm?: (action: SwipeAction) => boolean | Promise<boolean>
+  className?: string
+}
+
+/** Localised preset actions: delete (danger), archive (pending), edit and favourite (neutral). */
+export function useSwipeActionPresets() {
+  const w = useMessages().swipeRow
+  return useMemo(
+    () => ({
+      delete: (onAction: () => void, extra: Partial<SwipeAction> = {}): SwipeAction => ({ label: w.delete, icon: <Trash2 />, tone: 'danger', onAction, ...extra }),
+      archive: (onAction: () => void, extra: Partial<SwipeAction> = {}): SwipeAction => ({ label: w.archive, icon: <Archive />, tone: 'pending', onAction, ...extra }),
+      edit: (onAction: () => void, extra: Partial<SwipeAction> = {}): SwipeAction => ({ label: w.edit, icon: <Pencil />, tone: 'neutral', onAction, ...extra }),
+      favourite: (onAction: () => void, extra: Partial<SwipeAction> = {}): SwipeAction => ({ label: w.favourite, icon: <Star />, tone: 'neutral', onAction, ...extra }),
+    }),
+    [w],
+  )
+}
+
+function ActionStrip({ side, actions, open, onPick }: { side: 'leading' | 'trailing'; actions: SwipeAction[]; open: boolean; onPick: (a: SwipeAction) => void }) {
+  if (actions.length === 0) return null
+  return (
+    <div className="ty-swipe-row__actions" data-side={side} aria-hidden={!open || undefined} {...inertProps(!open)}>
+      {actions.map((action) => (
+        <button key={action.label} type="button" className="ty-swipe-row__action" data-tone={action.tone} tabIndex={open ? undefined : -1} onClick={() => onPick(action)}>
+          {action.icon ? (
+            <span className="ty-swipe-row__action-icon" aria-hidden="true">
+              {action.icon}
+            </span>
+          ) : null}
+          <span className="ty-swipe-row__action-word">{action.label}</span>
+        </button>
+      ))}
+    </div>
+  )
+}
+
+export function SwipeRow(props: SwipeRowProps) {
+  const { leadingActions = [], trailingActions = [], fullSwipe = true, fullSwipeFraction = 0.6, revealFraction = 0.4 } = props
+  const copy = useMessages().swipeRow
+  const rtl = useLocale().direction === 'rtl'
+  const reduced = useReducedMotion()
+  const [side, setSide] = useState<SwipeSide>('none')
+  const [drag, setDragState] = useState<number | null>(null)
+  const dragNow = useRef<number | null>(null)
+  const setDrag = (v: number | null) => {
+    dragNow.current = v
+    setDragState(v)
+  }
+  const track = useRef<Track | null>(null)
+  const width = useRef(0)
+  const armed = useRef(false)
+  const surface = useRef<HTMLDivElement>(null)
+
+  const changeSide = (next: SwipeSide) => {
+    setSide(next)
+    if (next !== side) props.onRevealChange?.(next)
+  }
+
+  const commit = (action: SwipeAction) => {
+    action.onAction()
+    changeSide('none')
+  }
+
+  const fullSwipeFire = async (action: SwipeAction, towards: 'leading' | 'trailing') => {
+    if (action.tone === 'danger' && !action.undoable) {
+      if (!props.confirm) return changeSide(towards)
+      const ok = await props.confirm(action)
+      if (!ok) return changeSide('none')
+    }
+    commit(action)
+  }
+
+  // Positive distance along the reading direction reveals the leading side.
+  const along = (dx: number) => (rtl ? -dx : dx)
+
+  const onTouchStart = (e: TouchEvent) => {
+    const t = firstTouch(e.touches)
+    if (!t || e.touches.length > 1) return
+    track.current = beginTrack(t)
+    width.current = surface.current?.getBoundingClientRect().width || surface.current?.offsetWidth || 0
+    armed.current = false
+  }
+
+  const onTouchMove = (e: TouchEvent) => {
+    const t = firstTouch(e.touches)
+    if (!t || !track.current) return
+    const next = advanceTrack(track.current, t)
+    track.current = next
+    if (next.axis === 'y') {
+      // Vertical intent: the list scrolls and the row stays put.
+      track.current = null
+      setDrag(null)
+      return
+    }
+    if (next.axis !== 'x') return
+    const base = side === 'leading' ? width.current * revealFraction : side === 'trailing' ? -width.current * revealFraction : 0
+    let offset = base + along(next.dx)
+    if (offset > 0 && leadingActions.length === 0) offset = 0
+    if (offset < 0 && trailingActions.length === 0) offset = 0
+    offset = Math.max(-width.current, Math.min(width.current, offset))
+    const past = fullSwipe && width.current > 0 && Math.abs(offset) >= width.current * fullSwipeFraction
+    if (past && !armed.current) playHaptic('impact')
+    armed.current = past
+    setDrag(offset)
+  }
+
+  const onTouchEnd = () => {
+    const offset = dragNow.current
+    track.current = null
+    setDrag(null)
+    if (offset === null) return
+    const towards: 'leading' | 'trailing' = offset > 0 ? 'leading' : 'trailing'
+    const pool = towards === 'leading' ? leadingActions : trailingActions
+    const w = width.current
+    if (armed.current && pool[0]) {
+      armed.current = false
+      void fullSwipeFire(pool[0], towards)
+      return
+    }
+    const revealAt = (w * revealFraction) / Math.max(1, pool.length) / 2
+    changeSide(Math.abs(offset) >= revealAt && pool.length > 0 ? towards : 'none')
+  }
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && side !== 'none') {
+      e.stopPropagation()
+      changeSide('none')
+      surface.current?.focus()
+    }
+  }
+
+  const menuItems: ActionMenuItem[] = [...leadingActions, ...trailingActions].map((a, i) => ({
+    id: String(i),
+    label: a.label,
+    tone: a.tone === 'danger' ? 'danger' : 'default',
+  }))
+  const everyAction = [...leadingActions, ...trailingActions]
+
+  // The drag variable is physical (left/right), the offset logical.
+  const offsetValue = drag !== null ? `${rtl ? -drag : drag}px` : undefined
+  return (
+    <div
+      className={cx('ty-swipe-row', props.className)}
+      data-reveal={side}
+      data-dragging={drag !== null || undefined}
+      data-reduced={reduced || undefined}
+      data-dir={rtl ? 'rtl' : 'ltr'}
+      data-armed={drag !== null && armed.current ? true : undefined}
+      onKeyDown={onKeyDown}
+      style={{ '--ty-swipe-reveal': `${revealFraction * 100}%`, ...(offsetValue ? { '--ty-swipe-drag': offsetValue } : {}) } as React.CSSProperties}
+    >
+      <ActionStrip side="leading" actions={leadingActions} open={side === 'leading'} onPick={commit} />
+      <ActionStrip side="trailing" actions={trailingActions} open={side === 'trailing'} onPick={commit} />
+      <div
+        ref={surface}
+        className="ty-swipe-row__surface"
+        tabIndex={-1}
+        onTouchStart={onTouchStart}
+        onTouchMove={onTouchMove}
+        onTouchEnd={onTouchEnd}
+        onTouchCancel={onTouchEnd}
+      >
+        <div className="ty-swipe-row__content">{props.children}</div>
+        {everyAction.length > 0 ? (
+          <ActionMenu
+            label={copy.actionsFor(props.label)}
+            items={menuItems}
+            onAction={(id) => everyAction[Number(id)]?.onAction()}
+            trigger={<Button variant="quiet" iconOnly accessibleLabel={copy.actionsFor(props.label)} leadingIcon={<Ellipsis />} className="ty-swipe-row__menu" />}
+          />
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/src/components/switch/Switch.css

@@ -0,0 +1,182 @@
+/* Switch and SwitchGroup (spec: wave-1/switch.md; design direction §2.3, §2.6, §2.7). */
+@layer tympan.components {
+  .ty-switch {
+    --ty-switch-width: 36px;
+    --ty-switch-height: 20px;
+    --ty-switch-thumb: 14px;
+
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-3);
+    min-block-size: var(--ty-control-target);
+    color: var(--ty-ink-2);
+    cursor: pointer;
+    outline: none;
+  }
+
+  .ty-switch[data-size='small'] {
+    --ty-switch-width: 28px;
+    --ty-switch-height: 16px;
+    --ty-switch-thumb: 10px;
+  }
+
+  .ty-switch[data-size='large'] {
+    --ty-switch-width: 44px;
+    --ty-switch-height: 24px;
+    --ty-switch-thumb: 18px;
+  }
+
+  /* Tile: text on the start side, control at the end, whole row is the target. */
+  .ty-switch[data-layout='tile'] {
+    display: flex;
+    flex-direction: row-reverse;
+    justify-content: space-between;
+    padding: var(--ty-space-3) var(--ty-space-4);
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-control);
+    background: var(--ty-surface-solid);
+  }
+
+  .ty-switch__track {
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    inline-size: var(--ty-switch-width);
+    block-size: var(--ty-switch-height);
+    padding-inline: calc((var(--ty-switch-height) - var(--ty-switch-thumb)) / 2);
+    border: 1px solid var(--ty-line-strong);
+    border-radius: var(--ty-radius-pill);
+    background: var(--ty-surface-sunken);
+    transition: background-color var(--ty-dur-quick) var(--ty-ease);
+  }
+
+  /* Invisible hit area on the control alone: at least 44 px (§2.10). */
+  .ty-switch__track::before {
+    content: '';
+    position: absolute;
+    inset-block-start: 50%;
+    /* physical: centring with translate(-50%) is the same in both directions */
+    left: 50%;
+    inline-size: max(100%, var(--ty-control-target));
+    block-size: max(100%, var(--ty-control-target));
+    transform: translate(-50%, -50%);
+  }
+
+  .ty-switch__thumb {
+    inline-size: var(--ty-switch-thumb);
+    block-size: var(--ty-switch-thumb);
+    border-radius: var(--ty-radius-pill);
+    background: var(--ty-ink-3);
+    transition: transform var(--ty-dur-quick) var(--ty-ease), background-color var(--ty-dur-quick) var(--ty-ease);
+  }
+
+  .ty-switch[data-selected] .ty-switch__track {
+    border-color: var(--ty-accent);
+    background: var(--ty-accent);
+  }
+
+  .ty-switch[data-selected] .ty-switch__thumb {
+    background: var(--ty-accent-ink);
+    transform: translateX(calc(var(--ty-switch-width) - var(--ty-switch-height)));
+  }
+
+  .ty-switch[data-selected] .ty-switch__thumb:dir(rtl) {
+    transform: translateX(calc(-1 * (var(--ty-switch-width) - var(--ty-switch-height))));
+  }
+
+  .ty-switch[data-hovered]:not([data-disabled]) .ty-switch__track {
+    border-color: var(--ty-ink-3);
+  }
+
+  .ty-switch[data-pressed] .ty-switch__thumb {
+    opacity: 0.85;
+  }
+
+  .ty-switch[data-focus-visible] .ty-switch__track {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+
+  .ty-switch[data-disabled] {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  .ty-switch[data-readonly] {
+    cursor: default;
+  }
+
+  .ty-switch__text {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-1);
+  }
+
+  .ty-switch__label {
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-body);
+    line-height: var(--ty-font-line-height-body);
+  }
+
+  .ty-switch__description {
+    color: var(--ty-ink-3);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+
+  .ty-switch-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-2);
+  }
+
+  .ty-switch-group__label {
+    color: var(--ty-ink);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-label);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ty-switch__track,
+    .ty-switch__thumb {
+      transition: none;
+    }
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-switch__track {
+      background: var(--ty-surface-sunken);
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-switch__track {
+      border: 1px solid CanvasText;
+      background: Canvas;
+      forced-color-adjust: none;
+    }
+    .ty-switch__thumb {
+      box-sizing: border-box;
+      border: 2px solid CanvasText;
+      background: Canvas;
+    }
+    .ty-switch[data-selected] .ty-switch__track {
+      border-color: CanvasText;
+      background: Canvas;
+    }
+    .ty-switch[data-selected] .ty-switch__thumb {
+      background: CanvasText;
+    }
+    .ty-switch[data-focus-visible] .ty-switch__track {
+      outline-color: Highlight;
+    }
+    .ty-switch[data-layout='tile'] {
+      border: 1px solid CanvasText;
+    }
+  }
+}

package/src/components/switch/Switch.test.tsx

@@ -0,0 +1,112 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { Switch, SwitchGroup } from './Switch'
+
+import * as rtlDom from '@testing-library/react'
+import rtlUser from '@testing-library/user-event'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+describe('Switch', () => {
+  it('has role switch and starts unchecked', () => {
+    render(<Switch label="Notifications" />)
+    const sw = screen.getByRole('switch', { name: 'Notifications' })
+    expect(sw).not.toBeChecked()
+  })
+
+  it('calls onChange with true on click, also via its label', async () => {
+    const onChange = vi.fn()
+    render(<Switch label="Notifications" onChange={onChange} />)
+    await userEvent.click(screen.getByText('Notifications'))
+    expect(onChange).toHaveBeenCalledWith(true)
+    expect(screen.getByRole('switch')).toBeChecked()
+  })
+
+  it('toggles with Space and with Enter', async () => {
+    render(<Switch label="Dark mode" />)
+    await userEvent.tab()
+    await userEvent.keyboard(' ')
+    expect(screen.getByRole('switch')).toBeChecked()
+    await userEvent.keyboard('{Enter}')
+    expect(screen.getByRole('switch')).not.toBeChecked()
+  })
+
+  it('toggles uncontrolled from defaultSelected', async () => {
+    render(<Switch label="Sync" defaultSelected />)
+    expect(screen.getByRole('switch')).toBeChecked()
+    await userEvent.click(screen.getByRole('switch'))
+    expect(screen.getByRole('switch')).not.toBeChecked()
+  })
+
+  it('does not change when disabled', async () => {
+    const onChange = vi.fn()
+    render(<Switch label="Locked" disabled onChange={onChange} />)
+    await userEvent.click(screen.getByText('Locked'))
+    screen.getByRole('switch').focus()
+    await userEvent.keyboard(' ')
+    await userEvent.keyboard('{Enter}')
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('is focusable but unchangeable when readOnly', async () => {
+    const onChange = vi.fn()
+    render(<Switch label="Fixed" readOnly defaultSelected onChange={onChange} />)
+    await userEvent.tab()
+    expect(screen.getByRole('switch')).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.click(screen.getByRole('switch'))
+    expect(onChange).not.toHaveBeenCalled()
+    expect(screen.getByRole('switch')).toBeChecked()
+  })
+
+  it('puts the tile description in the accessible description', () => {
+    render(<Switch layout="tile" label="Weekly digest" description="Every Monday" />)
+    const sw = screen.getByRole('switch', { name: 'Weekly digest' })
+    expect(sw).toHaveAccessibleDescription('Every Monday')
+  })
+
+  it('uses accessibleLabel without a visible label', () => {
+    render(<Switch accessibleLabel="Enable row" />)
+    expect(screen.getByRole('switch', { name: 'Enable row' })).toBeInTheDocument()
+  })
+
+  it('keeps a 44 px hit area at the small size', () => {
+    const { container } = render(<Switch label="Small" size="small" />)
+    expect(container.querySelector('.ty-switch')).toHaveAttribute('data-size', 'small')
+    const css = cssOf('components/switch/Switch.css')
+    expect(css).toMatch(/\.ty-switch\s*\{[^}]*min-block-size:\s*var\(--ty-control-target\)/)
+    expect(css).toMatch(/\.ty-switch__track::before\s*\{[^}]*block-size:\s*max\(100%,\s*var\(--ty-control-target\)\)/)
+  })
+
+  it('runs no transition under reduced motion; forced colours outline the track', () => {
+    const css = cssOf('components/switch/Switch.css')
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/\.ty-switch__thumb\s*\{[^}]*transition:\s*none/)
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/CanvasText/)
+  })
+
+  it('groups rows under a label and has no axe violations', async () => {
+    const { container } = render(
+      <SwitchGroup label="Email">
+        <Switch label="Mentions" />
+        <Switch label="Digest" layout="tile" description="Weekly" defaultSelected />
+      </SwitchGroup>,
+    )
+    expect(screen.getByRole('group', { name: 'Email' })).toBeInTheDocument()
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('Switch in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<Switch label="الإشعارات" />)
+    const sw = rtlDom.screen.getByRole('switch', { name: 'الإشعارات' })
+    await rtlUser.click(sw)
+    expect(sw).toBeChecked()
+    // The thumb travels towards the inline end, which is the left in right-to-left.
+    expect(cssOf('components/switch/Switch.css')).toMatch(/:dir\(rtl\)\s*\{[^}]*translateX\(calc\(-1/)
+    await axeRtl(container)
+  })
+})

package/src/components/switch/Switch.tsx

@@ -0,0 +1,125 @@
+import { forwardRef, useId, useState, type ReactNode } from 'react'
+import { Switch as AriaSwitch, type SwitchProps as AriaSwitchProps } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { devWarning } from '../../internal/dev'
+
+export interface SwitchProps {
+  isSelected?: boolean
+  defaultSelected?: boolean
+  onChange?: (isSelected: boolean) => void
+  label?: string
+  /** Name when there is no visible label. */
+  accessibleLabel?: string
+  description?: ReactNode
+  /** Row (control then label) or setting tile (text start, control end). */
+  layout?: 'inline' | 'tile'
+  size?: 'small' | 'regular' | 'large'
+  disabled?: boolean
+  /** Focusable and announces its state, but cannot change. */
+  readOnly?: boolean
+  name?: string
+  value?: string
+  id?: string
+  className?: string
+}
+
+type KeyEvent = Parameters<NonNullable<AriaSwitchProps['onKeyDown']>>[0]
+
+/** On/off state that may be owned by the host (`isSelected`) or kept here. */
+function useOnOff(owned: boolean | undefined, start: boolean, report?: (on: boolean) => void) {
+  const [kept, keep] = useState(start)
+  const on = owned === undefined ? kept : owned
+  function flip(next: boolean) {
+    if (owned === undefined) keep(next)
+    if (report) report(next)
+  }
+  return { on, flip }
+}
+
+/** Visible text of the switch: label and description, each with its own id. */
+function Caption(p: { labelId?: string; label?: string; descId?: string; description?: ReactNode }) {
+  if (!p.label && p.description == null) return null
+  return (
+    <span className="ty-switch__text">
+      {p.label && (
+        <span id={p.labelId} className="ty-switch__label">
+          {p.label}
+        </span>
+      )}
+      {p.description != null && (
+        <span id={p.descId} className="ty-switch__description">
+          {p.description}
+        </span>
+      )}
+    </span>
+  )
+}
+
+/** On/off setting with immediate effect (spec: wave-1/switch.md). */
+export const Switch = forwardRef<HTMLLabelElement, SwitchProps>(function Switch(props, ref) {
+  devWarning(!props.label && !props.accessibleLabel, 'Switch: provide `label` or `accessibleLabel`.')
+  const stem = useId()
+  const ids = {
+    label: props.label ? `${stem}-label` : undefined,
+    desc: props.description != null ? `${stem}-desc` : undefined,
+  }
+  const state = useOnOff(props.isSelected, props.defaultSelected ?? false, props.onChange)
+  const locked = props.disabled === true || props.readOnly === true
+
+  // Enter toggles as well as Space (the spec asks for parity with the previous library).
+  function onKey(event: KeyEvent) {
+    if (event.key !== 'Enter' || locked) {
+      event.continuePropagation()
+      return
+    }
+    event.preventDefault()
+    state.flip(!state.on)
+  }
+
+  return (
+    <AriaSwitch
+      ref={ref}
+      id={props.id}
+      name={props.name}
+      value={props.value}
+      isSelected={state.on}
+      isDisabled={props.disabled ?? false}
+      isReadOnly={props.readOnly ?? false}
+      onChange={state.flip}
+      onKeyDown={onKey}
+      aria-label={props.label ? undefined : props.accessibleLabel}
+      aria-labelledby={ids.label}
+      aria-describedby={ids.desc}
+      className={cx('ty-switch', props.className)}
+      data-layout={props.layout ?? 'inline'}
+      data-size={props.size ?? 'regular'}
+    >
+      <span className="ty-switch__track" aria-hidden="true">
+        <span className="ty-switch__thumb" />
+      </span>
+      <Caption labelId={ids.label} label={props.label} descId={ids.desc} description={props.description} />
+    </AriaSwitch>
+  )
+})
+
+export interface SwitchGroupProps {
+  label?: string
+  children: ReactNode
+  className?: string
+}
+
+/** Vertical stack of switch rows with an optional group label. */
+export function SwitchGroup(props: SwitchGroupProps) {
+  const captionId = useId()
+  const named = Boolean(props.label)
+  return (
+    <div className={cx('ty-switch-group', props.className)} role="group" aria-labelledby={named ? captionId : undefined}>
+      {named && (
+        <span id={captionId} className="ty-switch-group__label">
+          {props.label}
+        </span>
+      )}
+      {props.children}
+    </div>
+  )
+}