@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/components/theme-palette/ThemePalette.tsx

@@ -0,0 +1,377 @@
+import { Palette, Search } from 'lucide-react'
+import { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
+import { Button as AriaButton, Dialog, Modal, ModalOverlay } from 'react-aria-components'
+import { presets, printThemePresets, type ThemeConfig } from '@datatechsolutions/tympan-tokens'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import { useTheme, type ThemeDensity, type ThemeMode } from '../../internal/theme'
+import { SegmentedControl } from '../segmented-control/SegmentedControl'
+
+/** One theme in the palette. `id` is the `data-ty-theme` value. */
+export interface ThemePaletteTheme {
+  id: string
+  label: string
+  /** Matched by the search but not shown. */
+  keywords?: string[]
+}
+
+export interface ThemePaletteGroup {
+  id: string
+  heading: string
+  themes: ThemePaletteTheme[]
+}
+
+export interface ThemePaletteProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  /** Theme groups; defaults to the built-in presets and every book style (`themePaletteGroups`). */
+  groups?: ThemePaletteGroup[]
+  /** Localised name of a theme id (defaults to the theme's own label). */
+  labelFor?: (id: string) => string
+  /** localStorage key of the recently applied themes; `null` turns the recent group off. */
+  recentKey?: string | null
+  className?: string
+}
+
+const RECENT_DEFAULT = 'ty-theme-palette-recent'
+
+/** Groups of every theme the tokens package ships: the UI presets, then the book styles. */
+export function themePaletteGroups(headings: { interface: string; print: string }): ThemePaletteGroup[] {
+  const toTheme = (p: ThemeConfig): ThemePaletteTheme => ({ id: p.name, label: p.label ?? p.name, keywords: [p.name] })
+  return [
+    { id: 'interface', heading: headings.interface, themes: presets.map(toTheme) },
+    { id: 'print', heading: headings.print, themes: printThemePresets.map(toTheme) },
+  ]
+}
+
+const fold = (s: string) => s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLocaleLowerCase()
+
+/**
+ * Fuzzy score of `text` for `query`: 0 when the query's characters do not all appear in order; higher
+ * for a prefix, a word start, then contiguous runs.
+ */
+export function fuzzyScore(text: string, query: string): number {
+  const t = fold(text)
+  const q = fold(query.trim())
+  if (!q) return 1
+  if (t.startsWith(q)) return 1000 - t.length
+  const at = t.indexOf(q)
+  if (at >= 0) return (/[\s\-(]/.test(t[at - 1] ?? ' ') ? 800 : 600) - at
+  let score = 0
+  let run = 0
+  let i = 0
+  for (const ch of q) {
+    const found = t.indexOf(ch, i)
+    if (found < 0) return 0
+    run = found === i ? run + 1 : 1
+    score += run * 2 + (/[\s\-(]/.test(t[found - 1] ?? ' ') ? 3 : 0)
+    i = found + 1
+  }
+  return score
+}
+
+function readRecent(key: string | null): string[] {
+  if (!key) return []
+  try {
+    const v = JSON.parse(localStorage.getItem(key) ?? '[]')
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+function writeRecent(key: string | null, id: string) {
+  if (!key) return
+  try {
+    localStorage.setItem(key, JSON.stringify([id, ...readRecent(key).filter((x) => x !== id)].slice(0, 5)))
+  } catch {
+    /* storage unavailable */
+  }
+}
+
+/** Paper, ink and accent of a theme, drawn by the theme's own tokens (a tiny theme scope). */
+export function ThemeSwatch({ theme, mode, className }: { theme: string; mode?: 'light' | 'dark'; className?: string }) {
+  return (
+    <span className={cx('ty-theme-swatch', className)} data-ty-theme={theme} data-ty-mode={mode} aria-hidden="true">
+      <span className="ty-theme-swatch__ink" />
+      <span className="ty-theme-swatch__accent" />
+    </span>
+  )
+}
+
+interface Row {
+  key: string
+  theme: ThemePaletteTheme
+  group: string
+}
+
+/**
+ * Command-palette theme picker (spec: this file). Moving the highlight previews the theme on the whole app;
+ * Enter applies it, Escape restores the theme the palette opened with. Mode and density sit below the list.
+ * Needs a ThemeProvider; book-style themes need `@datatechsolutions/tympan-tokens/print-themes.css`.
+ */
+export function ThemePalette(props: ThemePaletteProps) {
+  const copy = useMessages().themePalette
+  const th = useTheme()
+  const listId = useId()
+  const optionPrefix = useId()
+  const inputRef = useRef<HTMLInputElement>(null)
+  const recentKey = props.recentKey === undefined ? RECENT_DEFAULT : props.recentKey
+  const groups = useMemo(
+    () => props.groups ?? themePaletteGroups({ interface: copy.groupInterface, print: copy.groupPrint }),
+    [props.groups, copy.groupInterface, copy.groupPrint],
+  )
+  const label = (t: ThemePaletteTheme) => props.labelFor?.(t.id) ?? t.label
+  const [query, setQuery] = useState('')
+  const [cursor, setCursor] = useState(0)
+  const [recent, setRecent] = useState<string[]>([])
+  const [announce, setAnnounce] = useState('')
+  const initial = useRef<string | null>(null)
+  const applied = useRef(false)
+
+  // On open: remember the theme to restore, reset the search, put the highlight on the current theme.
+  useEffect(() => {
+    if (!props.open) return
+    initial.current = th.theme
+    applied.current = false
+    setQuery('')
+    setRecent(readRecent(recentKey))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [props.open])
+
+  const sections = useMemo(() => {
+    const all = groups.flatMap((g) => g.themes.map((theme) => ({ theme, group: g.id })))
+    const q = query.trim()
+    if (q) {
+      const hits = all
+        .map((r) => ({ ...r, score: Math.max(fuzzyScore(label(r.theme), q), ...(r.theme.keywords ?? []).map((k) => fuzzyScore(k, q) * 0.9)) }))
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+      return [{ id: 'results', heading: copy.results(hits.length), rows: hits.map((r) => ({ key: `r-${r.theme.id}`, theme: r.theme, group: r.group })) }]
+    }
+    const out: Array<{ id: string; heading: string; count?: number; rows: Row[] }> = []
+    const recents = recent.map((id) => all.find((r) => r.theme.id === id)).filter((r): r is (typeof all)[number] => !!r)
+    if (recents.length) out.push({ id: 'recent', heading: copy.recent, rows: recents.map((r) => ({ key: `recent-${r.theme.id}`, ...r })) })
+    for (const g of groups) out.push({ id: g.id, heading: g.heading, count: g.themes.length, rows: g.themes.map((theme) => ({ key: `${g.id}-${theme.id}`, theme, group: g.id })) })
+    return out
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [groups, query, recent, copy, props.labelFor])
+
+  const rows = sections.flatMap((s) => s.rows)
+  const at = rows.length ? Math.min(cursor, rows.length - 1) : -1
+  const current = rows[at]
+  const optionId = (r: Row) => `${optionPrefix}-${r.key}`.replace(/[^\w-]/g, '_')
+
+  // When the list changes (open, typing), point at the current theme if it is listed, else the first row.
+  useEffect(() => {
+    if (!props.open) return
+    const i = rows.findIndex((r) => r.theme.id === (initial.current ?? th.theme))
+    setCursor(query.trim() ? 0 : Math.max(0, i))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [props.open, query, sections])
+
+  useEffect(() => {
+    if (current) document.getElementById(optionId(current))?.scrollIntoView({ block: 'nearest' })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [current?.key])
+
+  const preview = (i: number) => {
+    const r = rows[i]
+    setCursor(i)
+    if (r && r.theme.id !== th.theme) th.setTheme(r.theme.id)
+  }
+
+  const apply = (r: Row | undefined) => {
+    if (!r) return
+    th.setTheme(r.theme.id)
+    applied.current = true
+    writeRecent(recentKey, r.theme.id)
+    setAnnounce(copy.applied(label(r.theme)))
+    props.onOpenChange(false)
+  }
+
+  const close = () => {
+    // Closing without applying (Escape, backdrop) restores the theme the palette opened with.
+    if (!applied.current && initial.current && th.theme !== initial.current) th.setTheme(initial.current)
+    props.onOpenChange(false)
+  }
+
+  const onKey = (e: KeyboardEvent<HTMLInputElement>) => {
+    const step = (to: number) => {
+      e.preventDefault()
+      if (rows.length) preview((to + rows.length) % rows.length)
+    }
+    switch (e.key) {
+      case 'ArrowDown':
+        return step(at + 1)
+      case 'ArrowUp':
+        return step(at - 1)
+      case 'PageDown':
+        return step(Math.min(rows.length - 1, at + 8))
+      case 'PageUp':
+        return step(Math.max(0, at - 8))
+      case 'Home':
+        if (e.ctrlKey || !query) return step(0)
+        return
+      case 'End':
+        if (e.ctrlKey || !query) return step(rows.length - 1)
+        return
+      case 'Enter':
+        e.preventDefault()
+        return apply(current)
+      case 'Escape':
+        e.preventDefault()
+        e.stopPropagation()
+        return close()
+    }
+  }
+
+  const modes: Array<{ value: ThemeMode; label: string }> = [
+    { value: 'system', label: copy.modeSystem },
+    { value: 'light', label: copy.modeLight },
+    { value: 'dark', label: copy.modeDark },
+  ]
+  const densities: Array<{ value: ThemeDensity; label: string }> = [
+    { value: 'compact', label: copy.densityCompact },
+    { value: 'default', label: copy.densityDefault },
+    { value: 'comfortable', label: copy.densityComfortable },
+  ]
+  const previewTheme = current?.theme.id ?? th.theme
+
+  return (
+    <>
+      <ModalOverlay isOpen={props.open} onOpenChange={(o) => !o && close()} isDismissable isKeyboardDismissDisabled className="ty-theme-palette__backdrop">
+        <Modal className={cx('ty-theme-palette', props.className)}>
+          <Dialog className="ty-theme-palette__dialog" aria-label={copy.label}>
+            <div className="ty-theme-palette__field">
+              <Search className="ty-theme-palette__icon" aria-hidden="true" />
+              <input
+                ref={inputRef}
+                className="ty-theme-palette__input"
+                role="combobox"
+                aria-label={copy.label}
+                aria-autocomplete="list"
+                aria-expanded={rows.length > 0}
+                aria-controls={listId}
+                aria-activedescendant={current ? optionId(current) : undefined}
+                placeholder={copy.placeholder}
+                value={query}
+                autoFocus
+                autoComplete="off"
+                spellCheck={false}
+                onChange={(e) => setQuery(e.target.value)}
+                onKeyDown={onKey}
+              />
+            </div>
+            <div className="ty-theme-palette__body">
+              <div id={listId} role="listbox" aria-label={copy.label} className="ty-theme-palette__list">
+                {sections.map((s) => (
+                  <div key={s.id} role="group" aria-labelledby={`${listId}-${s.id}`} className="ty-theme-palette__group">
+                    <div id={`${listId}-${s.id}`} className="ty-theme-palette__heading" role="presentation">
+                      <span>{s.heading}</span>
+                      {s.count !== undefined ? <span className="ty-theme-palette__count">{copy.count(s.count)}</span> : null}
+                    </div>
+                    {s.rows.map((r) => {
+                      const i = rows.indexOf(r)
+                      return (
+                        <div
+                          key={r.key}
+                          id={optionId(r)}
+                          role="option"
+                          aria-selected={i === at}
+                          aria-current={r.theme.id === initial.current ? 'true' : undefined}
+                          className="ty-theme-palette__option"
+                          onPointerMove={() => i !== at && preview(i)}
+                          onClick={() => apply(r)}
+                        >
+                          <ThemeSwatch theme={r.theme.id} mode={th.resolvedMode} />
+                          <span className="ty-theme-palette__name">{label(r.theme)}</span>
+                          <code className="ty-theme-palette__id">{r.theme.id}</code>
+                        </div>
+                      )
+                    })}
+                  </div>
+                ))}
+                {!rows.length ? <p className="ty-theme-palette__empty">{copy.noResults(query.trim())}</p> : null}
+              </div>
+              <aside className="ty-theme-palette__preview" aria-label={copy.preview} data-ty-theme={previewTheme} data-ty-mode={th.resolvedMode}>
+                <span className="ty-theme-palette__preview-eyebrow">{copy.preview}</span>
+                <span className="ty-theme-palette__preview-title">{current ? label(current.theme) : ''}</span>
+                <span className="ty-theme-palette__preview-body">{copy.sample}</span>
+                <span className="ty-theme-palette__preview-bar">
+                  <span />
+                  <span />
+                  <span />
+                </span>
+                <span className="ty-theme-palette__preview-button">Aa</span>
+              </aside>
+            </div>
+            <div className="ty-theme-palette__foot">
+              <SegmentedControl label={copy.mode} size="compact" options={modes} value={th.mode} onChange={(m) => th.setMode(m as ThemeMode)} />
+              <SegmentedControl label={copy.density} size="compact" options={densities} value={th.density} onChange={(d) => th.setDensity(d as ThemeDensity)} />
+              <span className="ty-theme-palette__hints" aria-hidden="true">
+                <kbd>↑↓</kbd> {copy.hints.move} <kbd>↵</kbd> {copy.hints.apply} <kbd>esc</kbd> {copy.hints.revert}
+              </span>
+            </div>
+            <div className="ty-visually-hidden" aria-live="polite">
+              {query.trim() ? (rows.length ? copy.results(rows.length) : copy.noResults(query.trim())) : ''}
+            </div>
+          </Dialog>
+        </Modal>
+      </ModalOverlay>
+      <div className="ty-visually-hidden" role="status" aria-live="polite">
+        {announce}
+      </div>
+    </>
+  )
+}
+
+export interface ThemePaletteTriggerProps extends Omit<ThemePaletteProps, 'open' | 'onOpenChange'> {
+  /** Also open with ⌘/Ctrl+Shift+P and, outside text fields, the T key. Default true. */
+  shortcut?: boolean
+  /** Hide the theme name (swatch only); the name stays the accessible label. */
+  compact?: boolean
+  children?: ReactNode
+}
+
+/** Button showing the current theme's swatch and name; opens the ThemePalette. */
+export function ThemePaletteTrigger({ shortcut = true, compact = false, className, ...rest }: ThemePaletteTriggerProps) {
+  const copy = useMessages().themePalette
+  const th = useTheme()
+  const [open, setOpen] = useState(false)
+  const all = useMemo(() => (rest.groups ?? themePaletteGroups({ interface: '', print: '' })).flatMap((g) => g.themes), [rest.groups])
+  const found = all.find((t) => t.id === th.theme)
+  const name = rest.labelFor?.(th.theme) ?? found?.label ?? th.theme
+
+  useEffect(() => {
+    if (!shortcut) return
+    const on = (e: globalThis.KeyboardEvent) => {
+      const typing = (e.target as HTMLElement | null)?.closest?.('input, textarea, select, [contenteditable="true"], [role="combobox"]')
+      if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key.toLowerCase() === 'p') {
+        e.preventDefault()
+        setOpen(true)
+      } else if (!typing && !e.metaKey && !e.ctrlKey && !e.altKey && (e.key === 't' || e.key === 'T')) {
+        setOpen(true)
+      }
+    }
+    addEventListener('keydown', on)
+    return () => removeEventListener('keydown', on)
+  }, [shortcut])
+
+  return (
+    <>
+      <AriaButton
+        className={cx('ty-theme-palette-trigger', className)}
+        data-compact={compact || undefined}
+        aria-label={copy.trigger(name)}
+        aria-keyshortcuts={shortcut ? 'Control+Shift+P Meta+Shift+P T' : undefined}
+        aria-haspopup="dialog"
+        onPress={() => setOpen(true)}
+      >
+        <ThemeSwatch theme={th.theme} mode={th.resolvedMode} />
+        {compact ? <Palette className="ty-icon" aria-hidden="true" /> : <span className="ty-theme-palette-trigger__name">{name}</span>}
+      </AriaButton>
+      <ThemePalette {...rest} open={open} onOpenChange={setOpen} />
+    </>
+  )
+}

package/src/components/theme-switcher/ThemeSwitcher.css

@@ -0,0 +1,159 @@
+/* ThemeSwitcher (spec: wave-2/theme-switcher.md; design direction §2.3, §2.6, §2.7, §2.10). */
+@layer tympan.components {
+  .ty-theme-switcher {
+    --ty-ts-track-w: 36px;
+    --ty-ts-track-h: 20px;
+    --ty-ts-knob: 16px;
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-2);
+    min-block-size: var(--ty-control-target);
+    padding: 0;
+    border: 0;
+    background: none;
+    color: var(--ty-ink-2);
+    font: inherit;
+    font-size: var(--ty-font-size-body);
+    cursor: pointer;
+    outline: none;
+  }
+
+  /* Compact: a 40 px round button whose hit area grows to 44 px. */
+  .ty-theme-switcher[data-variant='compact'] {
+    justify-content: center;
+    inline-size: var(--ty-control-height);
+    min-block-size: var(--ty-control-height);
+    border: 1px solid var(--ty-line-strong);
+    border-radius: var(--ty-radius-pill);
+    background: var(--ty-secondary);
+    color: var(--ty-ink-2);
+  }
+  .ty-theme-switcher[data-variant='compact']::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-theme-switcher[data-variant='compact'][data-hovered] {
+    border-color: var(--ty-ink-3);
+  }
+
+  .ty-theme-switcher__glyph {
+    display: inline-flex;
+    color: var(--ty-ink-3);
+    opacity: 0.6;
+    transition: opacity var(--ty-dur-quick) var(--ty-ease), color var(--ty-dur-quick) var(--ty-ease);
+  }
+  .ty-theme-switcher__glyph[data-active] {
+    color: var(--ty-ink);
+    opacity: 1;
+  }
+  .ty-theme-switcher__glyph > svg {
+    inline-size: 18px;
+    block-size: 18px;
+  }
+
+  .ty-theme-switcher__track {
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    inline-size: var(--ty-ts-track-w);
+    block-size: var(--ty-ts-track-h);
+    padding-inline: 1px;
+    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);
+  }
+  .ty-theme-switcher__knob {
+    display: inline-grid;
+    place-items: center;
+    inline-size: var(--ty-ts-knob);
+    block-size: var(--ty-ts-knob);
+    border-radius: var(--ty-radius-pill);
+    background: var(--ty-ink-3);
+    transition: translate var(--ty-dur-quick) var(--ty-ease);
+  }
+  .ty-theme-switcher__knob-check {
+    inline-size: 10px;
+    block-size: 10px;
+    visibility: hidden;
+  }
+  .ty-theme-switcher[data-selected] .ty-theme-switcher__track {
+    border-color: var(--ty-accent);
+    background: var(--ty-accent);
+  }
+  .ty-theme-switcher[data-selected] .ty-theme-switcher__knob {
+    background: var(--ty-accent-ink);
+    color: var(--ty-accent);
+    translate: calc(var(--ty-ts-track-w) - var(--ty-ts-knob) - 4px) 0;
+  }
+  /* The knob travels towards the inline end: leftwards in right-to-left. */
+  [dir='rtl'] .ty-theme-switcher[data-selected] .ty-theme-switcher__knob,
+  .ty-theme-switcher[data-selected] .ty-theme-switcher__knob:dir(rtl) {
+    translate: calc(-1 * (var(--ty-ts-track-w) - var(--ty-ts-knob) - 4px)) 0;
+  }
+  .ty-theme-switcher[data-selected] .ty-theme-switcher__knob-check {
+    visibility: visible;
+  }
+  .ty-theme-switcher__name {
+    color: var(--ty-ink);
+    font-weight: var(--ty-font-weight-semibold);
+  }
+
+  .ty-theme-switcher[data-focus-visible][data-variant='compact'],
+  .ty-theme-switcher[data-focus-visible] .ty-theme-switcher__track {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-theme-switcher[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ty-theme-switcher__glyph,
+    .ty-theme-switcher__track,
+    .ty-theme-switcher__knob {
+      transition: none;
+    }
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-theme-switcher[data-variant='compact'] {
+      background: var(--ty-surface-solid);
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-theme-switcher__track,
+    .ty-theme-switcher[data-variant='compact'] {
+      border: 1px solid ButtonText;
+      background: ButtonFace;
+      forced-color-adjust: none;
+    }
+    .ty-theme-switcher__knob {
+      background: ButtonText;
+      color: ButtonFace;
+    }
+    .ty-theme-switcher[data-selected] .ty-theme-switcher__track {
+      border-color: Highlight;
+      background: ButtonFace;
+    }
+    .ty-theme-switcher[data-selected] .ty-theme-switcher__knob {
+      background: Highlight;
+      color: HighlightText;
+    }
+    .ty-theme-switcher[data-focus-visible][data-variant='compact'],
+    .ty-theme-switcher[data-focus-visible] .ty-theme-switcher__track {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/components/theme-switcher/ThemeSwitcher.test.tsx

@@ -0,0 +1,71 @@
+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 { ThemeScope } from '../../internal/ThemeScope'
+import { ThemeSwitcher } from './ThemeSwitcher'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import * as rtlDom from '@testing-library/react'
+import { renderRtl } from '../../../test/rtl'
+
+describe('ThemeSwitcher', () => {
+  it('full variant: an unchecked switch named "Dark mode" in light mode', () => {
+    render(<ThemeSwitcher mode="light" onModeChange={() => {}} />)
+    expect(screen.getByRole('switch', { name: 'Dark mode' })).not.toBeChecked()
+  })
+
+  it('toggling the switch requests dark', async () => {
+    const onModeChange = vi.fn()
+    render(<ThemeSwitcher mode="light" onModeChange={onModeChange} />)
+    await userEvent.click(screen.getByRole('switch'))
+    expect(onModeChange).toHaveBeenCalledWith('dark')
+  })
+
+  it('keeps a stable name and reports checked in dark mode', () => {
+    render(<ThemeSwitcher mode="dark" onModeChange={() => {}} />)
+    expect(screen.getByRole('switch', { name: 'Dark mode' })).toBeChecked()
+  })
+
+  it('compact variant names the action and requests light', async () => {
+    const onModeChange = vi.fn()
+    render(<ThemeSwitcher mode="dark" variant="compact" onModeChange={onModeChange} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Switch to light mode' }))
+    expect(onModeChange).toHaveBeenCalledWith('light')
+  })
+
+  it('has no animation under reduced motion', () => {
+    const reduced = mediaBlock(cssOf('components/theme-switcher/ThemeSwitcher.css'), /\(prefers-reduced-motion:\s*reduce\)/)
+    expect(reduced).toMatch(/\.ty-theme-switcher__knob[\s\S]*transition:\s*none/)
+  })
+
+  it('keeps a 44 px hit area and system colours in forced-colors mode', () => {
+    const css = cssOf('components/theme-switcher/ThemeSwitcher.css')
+    expect(css).toMatch(/min-block-size:\s*var\(--ty-control-target\)/)
+    expect(css).toMatch(/inline-size:\s*max\(100%,\s*var\(--ty-control-target\)\)/)
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/Highlight/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <ThemeSwitcher mode={scheme} onModeChange={() => {}} />
+            <ThemeSwitcher mode={scheme} variant="compact" onModeChange={() => {}} />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('ThemeSwitcher in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<ThemeSwitcher mode="light" onModeChange={() => {}} />)
+    expect(rtlDom.screen.getByRole('switch')).toBeInTheDocument()
+    expect(cssOf('components/theme-switcher/ThemeSwitcher.css')).toMatch(/:dir\(rtl\)\s*\{[^}]*translate:\s*calc\(-1/)
+    await axeRtl(container)
+  })
+})

package/src/components/theme-switcher/ThemeSwitcher.tsx

@@ -0,0 +1,72 @@
+import { Check, Moon, Sun } from 'lucide-react'
+import { Button as AriaButton, Switch as AriaSwitch } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+
+export type ThemeSwitcherMode = 'light' | 'dark'
+
+export interface ThemeSwitcherProps {
+  /** Appearance in use; the host applies and persists it. */
+  mode: ThemeSwitcherMode
+  onModeChange: (mode: ThemeSwitcherMode) => void
+  variant?: 'full' | 'compact'
+  /** Constant name of the full switch. */
+  label?: string
+  toLightLabel?: string
+  toDarkLabel?: string
+  disabled?: boolean
+  className?: string
+}
+
+const flip = (m: ThemeSwitcherMode): ThemeSwitcherMode => (m === 'dark' ? 'light' : 'dark')
+
+function Glyph({ of, active }: { of: ThemeSwitcherMode; active?: boolean }) {
+  const Icon = of === 'dark' ? Moon : Sun
+  return (
+    <span className="ty-theme-switcher__glyph" data-glyph={of} data-active={active || undefined} aria-hidden="true">
+      <Icon focusable="false" />
+    </span>
+  )
+}
+
+/** Light/dark appearance control, as a switch or a compact button (spec: wave-2/theme-switcher.md). */
+export function ThemeSwitcher(props: ThemeSwitcherProps) {
+  const copy = useMessages().themeSwitcher
+  const next = flip(props.mode)
+  const shared = { 'data-mode': props.mode, isDisabled: props.disabled }
+
+  if (props.variant === 'compact') {
+    const name = next === 'light' ? (props.toLightLabel ?? copy.toLight) : (props.toDarkLabel ?? copy.toDark)
+    return (
+      <AriaButton
+        {...shared}
+        className={cx('ty-theme-switcher', props.className)}
+        data-variant="compact"
+        aria-label={name}
+        onPress={() => props.onModeChange(next)}
+      >
+        <Glyph of={next} active />
+      </AriaButton>
+    )
+  }
+
+  const name = props.label ?? copy.label
+  return (
+    <AriaSwitch
+      {...shared}
+      className={cx('ty-theme-switcher', props.className)}
+      data-variant="full"
+      isSelected={props.mode === 'dark'}
+      onChange={(on) => props.onModeChange(on ? 'dark' : 'light')}
+    >
+      <Glyph of="light" active={props.mode === 'light'} />
+      <span className="ty-theme-switcher__track" aria-hidden="true">
+        <span className="ty-theme-switcher__knob">
+          <Check className="ty-theme-switcher__knob-check" focusable="false" />
+        </span>
+      </span>
+      <Glyph of="dark" active={props.mode === 'dark'} />
+      <span className="ty-theme-switcher__name">{name}</span>
+    </AriaSwitch>
+  )
+}