@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/components/tone-tint/ToneTint.css

@@ -0,0 +1,74 @@
+/* ToneTint tokens and the tinted-glass rule (spec: wave-4/tone-tint-resolver.md; design direction §2.3, §2.5).
+   Tints reference the semantic and categorical tokens, and are re-declared on every
+   themed element so light and dark swap together with their source colours. */
+@layer tympan.tokens {
+  :root,
+  [data-ty-theme],
+  [data-ty-mode] {
+    --ty-tint-accent-rgb: var(--ty-accent);
+    --ty-tint-success-rgb: var(--ty-success);
+    --ty-tint-pending-rgb: var(--ty-warning);
+    --ty-tint-error-rgb: var(--ty-danger);
+    --ty-tint-neutral-rgb: var(--ty-neutral);
+    --ty-tint-categorical-1-rgb: var(--ty-categorical-1);
+    --ty-tint-categorical-2-rgb: var(--ty-categorical-2);
+    --ty-tint-categorical-3-rgb: var(--ty-categorical-3);
+    --ty-tint-categorical-4-rgb: var(--ty-categorical-4);
+    --ty-tint-categorical-5-rgb: var(--ty-categorical-5);
+    --ty-tint-categorical-6-rgb: var(--ty-categorical-6);
+    --ty-tint-categorical-7-rgb: var(--ty-categorical-7);
+    --ty-tint-categorical-8-rgb: var(--ty-categorical-8);
+
+    --ty-tint-accent-soft: color-mix(in oklab, var(--ty-tint-accent-rgb) 9%, transparent);
+    --ty-tint-success-soft: color-mix(in oklab, var(--ty-tint-success-rgb) 9%, transparent);
+    --ty-tint-pending-soft: color-mix(in oklab, var(--ty-tint-pending-rgb) 9%, transparent);
+    --ty-tint-error-soft: color-mix(in oklab, var(--ty-tint-error-rgb) 9%, transparent);
+    --ty-tint-neutral-soft: color-mix(in oklab, var(--ty-tint-neutral-rgb) 7%, transparent);
+    --ty-tint-categorical-1-soft: color-mix(in oklab, var(--ty-tint-categorical-1-rgb) 10%, transparent);
+    --ty-tint-categorical-2-soft: color-mix(in oklab, var(--ty-tint-categorical-2-rgb) 10%, transparent);
+    --ty-tint-categorical-3-soft: color-mix(in oklab, var(--ty-tint-categorical-3-rgb) 10%, transparent);
+    --ty-tint-categorical-4-soft: color-mix(in oklab, var(--ty-tint-categorical-4-rgb) 10%, transparent);
+    --ty-tint-categorical-5-soft: color-mix(in oklab, var(--ty-tint-categorical-5-rgb) 10%, transparent);
+    --ty-tint-categorical-6-soft: color-mix(in oklab, var(--ty-tint-categorical-6-rgb) 10%, transparent);
+    --ty-tint-categorical-7-soft: color-mix(in oklab, var(--ty-tint-categorical-7-rgb) 10%, transparent);
+    --ty-tint-categorical-8-soft: color-mix(in oklab, var(--ty-tint-categorical-8-rgb) 10%, transparent);
+
+    --ty-tint-accent-ring: color-mix(in oklab, var(--ty-tint-accent-rgb) 38%, transparent);
+    --ty-tint-success-ring: color-mix(in oklab, var(--ty-tint-success-rgb) 38%, transparent);
+    --ty-tint-pending-ring: color-mix(in oklab, var(--ty-tint-pending-rgb) 38%, transparent);
+    --ty-tint-error-ring: color-mix(in oklab, var(--ty-tint-error-rgb) 38%, transparent);
+    --ty-tint-neutral-ring: color-mix(in oklab, var(--ty-tint-neutral-rgb) 30%, transparent);
+    --ty-tint-categorical-1-ring: color-mix(in oklab, var(--ty-tint-categorical-1-rgb) 40%, transparent);
+    --ty-tint-categorical-2-ring: color-mix(in oklab, var(--ty-tint-categorical-2-rgb) 40%, transparent);
+    --ty-tint-categorical-3-ring: color-mix(in oklab, var(--ty-tint-categorical-3-rgb) 40%, transparent);
+    --ty-tint-categorical-4-ring: color-mix(in oklab, var(--ty-tint-categorical-4-rgb) 40%, transparent);
+    --ty-tint-categorical-5-ring: color-mix(in oklab, var(--ty-tint-categorical-5-rgb) 40%, transparent);
+    --ty-tint-categorical-6-ring: color-mix(in oklab, var(--ty-tint-categorical-6-rgb) 40%, transparent);
+    --ty-tint-categorical-7-ring: color-mix(in oklab, var(--ty-tint-categorical-7-rgb) 40%, transparent);
+    --ty-tint-categorical-8-ring: color-mix(in oklab, var(--ty-tint-categorical-8-rgb) 40%, transparent);
+  }
+}
+
+@layer tympan.components {
+  /* Any surface with data-ty-tinted reads the tint set inline by tintStyle(). */
+  [data-ty-tinted] {
+    --ty-surface-tint: transparent;
+    --ty-surface-tint-ring: var(--ty-line);
+    background-image: linear-gradient(var(--ty-surface-tint), var(--ty-surface-tint));
+    border-color: var(--ty-surface-tint-ring);
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    [data-ty-tinted] {
+      background-color: var(--ty-surface-solid);
+      background-image: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    [data-ty-tinted] {
+      background-image: none;
+      border-color: CanvasText;
+    }
+  }
+}

package/src/components/tone-tint/toneTint.test.tsx

@@ -0,0 +1,74 @@
+import { render } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { checkToneUsage, isToneName, resolveTint, tintStyle, toneNames } from './toneTint'
+
+const css = cssOf('components/tone-tint/ToneTint.css')
+
+describe('ToneTint resolver', () => {
+  it('references only --ty-tint-success-* properties and no literal colour', () => {
+    const t = resolveTint('success')
+    for (const value of Object.values(t)) {
+      expect(value).toMatch(/^var\(--ty-tint-success-(rgb|soft|ring)\)$/)
+      expect(value).not.toMatch(/#|rgb\(|oklch\(|hsl\(/)
+    }
+  })
+
+  it('returns the neutral set for an unknown tone, or the fallback when given', () => {
+    expect(resolveTint('violet')).toEqual(resolveTint('neutral'))
+    expect(resolveTint(undefined)).toEqual(resolveTint('neutral'))
+    expect(resolveTint('nope', 'accent').soft).toBe('var(--ty-tint-accent-soft)')
+  })
+
+  it('validates host input with isToneName', () => {
+    expect(isToneName('categorical-8')).toBe(true)
+    expect(isToneName('categorical-9')).toBe(false)
+    expect(isToneName(3)).toBe(false)
+    expect(toneNames).toHaveLength(13)
+  })
+
+  it('defines all three tokens for every tone, on the themed selectors (both themes)', () => {
+    const tokenBlock = css.slice(css.indexOf('@layer tympan.tokens'), css.indexOf('@layer tympan.components'))
+    expect(tokenBlock).toMatch(/\[data-ty-mode\]/)
+    expect(tokenBlock).toMatch(/\[data-ty-theme\]/)
+    for (const tone of toneNames) {
+      for (const part of ['rgb', 'soft', 'ring']) expect(tokenBlock).toContain(`--ty-tint-${tone}-${part}:`)
+    }
+    expect(tokenBlock).not.toMatch(/#[0-9a-f]{3,8}\b/i)
+  })
+
+  it('flags a categorical tone used on a table cell', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    expect(checkToneUsage('categorical-2', 'table-cell')).toMatch(/categorical/)
+    expect(checkToneUsage('categorical-2', 'map')).toBeNull()
+    expect(checkToneUsage('success', 'table-cell')).toBeNull()
+    expect(warn).toHaveBeenCalledTimes(1)
+    warn.mockRestore()
+  })
+
+  it('uses the opaque surface under reduced transparency and ignores the tint in forced colours', () => {
+    const reduced = mediaBlock(css, /\(prefers-reduced-transparency:\s*reduce\)/)
+    expect(reduced).toMatch(/background-color:\s*var\(--ty-surface-solid\)/)
+    expect(reduced).toMatch(/background-image:\s*none/)
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/background-image:\s*none/)
+  })
+
+  it('applies a tint through one inline custom property and stays accessible', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((s) => (
+          <ThemeScope key={s} scheme={s}>
+            <div data-ty-tinted="" style={tintStyle('pending')}>
+              <p>Pending review, 3 claims</p>
+            </div>
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    const el = container.querySelector('[data-ty-tinted]') as HTMLElement
+    expect(el.style.getPropertyValue('--ty-surface-tint')).toBe('var(--ty-tint-pending-soft)')
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/tone-tint/toneTint.ts

@@ -0,0 +1,57 @@
+// ToneTint: a faint wash of a named tone on a glass surface, by token name
+// only (spec: wave-4/tone-tint-resolver.md). No colour value lives here.
+import type { CSSProperties } from 'react'
+import { devWarning } from '../../internal/dev'
+
+const SEMANTIC = ['accent', 'success', 'pending', 'error', 'neutral'] as const
+const CATEGORICAL = ['categorical-1', 'categorical-2', 'categorical-3', 'categorical-4', 'categorical-5', 'categorical-6', 'categorical-7', 'categorical-8'] as const
+
+export type ToneName = (typeof SEMANTIC)[number] | (typeof CATEGORICAL)[number]
+
+/** Every tone, semantic first, in picker order. */
+export const toneNames: readonly ToneName[] = Object.freeze([...SEMANTIC, ...CATEGORICAL])
+
+export interface TintReferences {
+  /** The tone itself (solid); alpha is applied with `color-mix()`. */
+  rgb: string
+  /** Surface wash. */
+  soft: string
+  /** Border and focus-adjacent glow. */
+  ring: string
+}
+
+/** Where a tone is drawn; §2.3 allows categorical hues only in the first four. */
+export type ToneContext = 'map' | 'chart' | 'legend' | 'graph-node' | 'surface' | 'table-cell' | 'record' | 'control'
+const CATEGORY_CONTEXTS: ReadonlySet<ToneContext> = new Set(['map', 'chart', 'legend', 'graph-node'])
+
+export function isToneName(value: unknown): value is ToneName {
+  return typeof value === 'string' && (toneNames as readonly string[]).includes(value)
+}
+
+const ref = (tone: ToneName, part: 'rgb' | 'soft' | 'ring') => `var(--ty-tint-${tone}-${part})`
+
+/** Token references for a tone; unknown input falls back to `fallback`, then to neutral. */
+export function resolveTint(tone?: unknown, fallback?: ToneName): TintReferences {
+  const chosen: ToneName = isToneName(tone) ? tone : isToneName(fallback) ? fallback : 'neutral'
+  return { rgb: ref(chosen, 'rgb'), soft: ref(chosen, 'soft'), ring: ref(chosen, 'ring') }
+}
+
+/**
+ * Inline style for a tinted surface root: sets the one property the glass
+ * rule reads (`--ty-surface-tint`) plus its ring. Pair with `data-ty-tinted`.
+ */
+export function tintStyle(tone?: unknown, fallback?: ToneName): CSSProperties {
+  const t = resolveTint(tone, fallback)
+  return { ['--ty-surface-tint' as string]: t.soft, ['--ty-surface-tint-ring' as string]: t.ring } as CSSProperties
+}
+
+/**
+ * Library usage check: a categorical tone outside maps, charts, legends and
+ * graph nodes breaks §2.3. Returns the problem (and warns in development).
+ */
+export function checkToneUsage(tone: ToneName, context: ToneContext): string | null {
+  const categorical = tone.startsWith('categorical-')
+  const problem = categorical && !CATEGORY_CONTEXTS.has(context) ? `ToneTint: "${tone}" is a categorical tone and may not be used on a ${context} (design direction §2.3).` : null
+  devWarning(problem !== null, problem ?? '')
+  return problem
+}

package/src/components/toolbar-trigger/ToolbarTrigger.css

@@ -0,0 +1,104 @@
+/* ToolbarTrigger (spec: wave-2/toolbar-trigger.md; design direction §2.3, §2.6, §2.10). */
+@layer tympan.components {
+  .ty-toolbar-trigger {
+    --ty-tt-fill: transparent;
+    position: relative;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--ty-space-1);
+    min-inline-size: var(--ty-control-height);
+    block-size: var(--ty-control-height);
+    padding-inline: var(--ty-space-2);
+    border: 1px solid transparent;
+    border-radius: var(--ty-radius-control);
+    background: var(--ty-tt-fill);
+    color: var(--ty-ink-2);
+    font: inherit;
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    cursor: pointer;
+    outline: none;
+    transition: background-color var(--ty-dur-instant) var(--ty-ease);
+  }
+  .ty-toolbar-trigger::after {
+    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-toolbar-trigger__glyph {
+    display: inline-flex;
+  }
+  .ty-toolbar-trigger__glyph > svg {
+    inline-size: 1.25rem;
+    block-size: 1.25rem;
+  }
+  .ty-toolbar-trigger__caption {
+    font-family: var(--ty-font-sans);
+  }
+  /* Hover uses a neutral tint: accent-soft is reserved for the active item (§2.3). */
+  .ty-toolbar-trigger[data-hovered],
+  .ty-toolbar-trigger[data-expanded-state] {
+    --ty-tt-fill: var(--ty-surface-sunken);
+  }
+  .ty-toolbar-trigger[data-toggled] {
+    --ty-tt-fill: var(--ty-surface-sunken);
+    border-color: var(--ty-line-strong);
+    color: var(--ty-ink);
+  }
+  .ty-toolbar-trigger[data-pressed] {
+    opacity: 0.85;
+  }
+  .ty-toolbar-trigger[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-toolbar-trigger[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+  .ty-toolbar-trigger__tip {
+    padding: var(--ty-space-1) var(--ty-space-2);
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-control);
+    background: var(--ty-surface-raised-solid);
+    color: var(--ty-ink);
+    box-shadow: var(--ty-shadow-floating);
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+    z-index: var(--ty-z-popover);
+  }
+  @media (max-width: 1023.98px) {
+    .ty-toolbar-trigger {
+      min-inline-size: var(--ty-control-height-touch);
+      block-size: var(--ty-control-height-touch);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .ty-toolbar-trigger {
+      transition: none;
+    }
+  }
+  @media (forced-colors: active) {
+    .ty-toolbar-trigger {
+      color: ButtonText;
+      forced-color-adjust: none;
+    }
+    .ty-toolbar-trigger[data-toggled],
+    .ty-toolbar-trigger[data-expanded-state] {
+      border-color: Highlight;
+    }
+    .ty-toolbar-trigger[data-focus-visible] {
+      outline: 2px solid Highlight;
+    }
+    .ty-toolbar-trigger__tip {
+      border-color: CanvasText;
+    }
+  }
+}

package/src/components/toolbar-trigger/ToolbarTrigger.test.tsx

@@ -0,0 +1,75 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Bell, Languages } from 'lucide-react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { ToolbarTrigger } from './ToolbarTrigger'
+import * as rtlDom from '@testing-library/react'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+describe('ToolbarTrigger', () => {
+  it('names an icon-only trigger by its label and shows a tooltip on focus', async () => {
+    render(<ToolbarTrigger icon={<Bell />} label="Notifications" />)
+    await userEvent.tab()
+    expect(screen.getByRole('button', { name: 'Notifications' })).toHaveFocus()
+    expect(await screen.findByRole('tooltip')).toHaveTextContent('Notifications')
+  })
+
+  it('keeps a visible caption inside the accessible name', () => {
+    render(<ToolbarTrigger icon={<Languages />} label="Language" caption="EN" />)
+    const button = screen.getByRole('button')
+    expect(button.getAttribute('aria-label')).toContain('EN')
+    expect(button).toHaveTextContent('EN')
+  })
+
+  it('exposes popup and expanded state', () => {
+    render(<ToolbarTrigger icon={<Bell />} label="Account" controls="menu" expanded />)
+    const button = screen.getByRole('button', { name: 'Account' })
+    expect(button).toHaveAttribute('aria-haspopup', 'menu')
+    expect(button).toHaveAttribute('aria-expanded', 'true')
+  })
+
+  it('reports a toggle state and fires onPress with Enter and Space', async () => {
+    const onPress = vi.fn()
+    render(<ToolbarTrigger icon={<Bell />} label="Focus mode" pressed onPress={onPress} />)
+    const button = screen.getByRole('button', { name: 'Focus mode' })
+    expect(button).toHaveAttribute('aria-pressed', 'true')
+    button.focus()
+    await userEvent.keyboard('{Enter}')
+    await userEvent.keyboard(' ')
+    expect(onPress).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps a 44 px hit area and drops transitions under reduced motion', () => {
+    const css = cssOf('components/toolbar-trigger/ToolbarTrigger.css')
+    expect(css).toMatch(/::after\s*\{[^}]*inline-size:\s*max\(100%,\s*var\(--ty-control-target\)\)/)
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/transition:\s*none/)
+    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}>
+            <ToolbarTrigger icon={<Bell />} label="Notifications" />
+            <ToolbarTrigger icon={<Languages />} label="Language" caption="PT" controls="menu" expanded={false} />
+            <ToolbarTrigger icon={<Bell />} label="Muted" disabled />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('ToolbarTrigger in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<ToolbarTrigger icon={<span />} label="اللغة" caption="ع" />)
+    expect(rtlDom.screen.getByRole('button', { name: /اللغة/ })).toBeInTheDocument()
+    await axeRtl(container)
+  })
+})

package/src/components/toolbar-trigger/ToolbarTrigger.tsx

@@ -0,0 +1,70 @@
+import type { ReactNode } from 'react'
+import { Button as AriaButton, Tooltip, TooltipTrigger } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+
+export type ToolbarTriggerControls = 'menu' | 'dialog' | 'none'
+
+export interface ToolbarTriggerProps {
+  /** Decorative glyph. */
+  icon: ReactNode
+  /** Accessible name. When a caption is visible the name also carries it (WCAG 2.5.3). */
+  label: string
+  /** Very short visible text after the icon (a locale code, a word). */
+  caption?: string
+  onPress?: () => void
+  /** Kind of surface the trigger opens; sets `aria-haspopup`. */
+  controls?: ToolbarTriggerControls
+  expanded?: boolean
+  /** Toggle state for switch-like triggers (for example a focus mode). */
+  pressed?: boolean
+  disabled?: boolean
+  className?: string
+  id?: string
+}
+
+/** Label-in-name: keep the visible caption inside the accessible name. */
+function nameWithCaption(label: string, caption?: string): string {
+  if (!caption) return label
+  return label.toLocaleLowerCase().includes(caption.toLocaleLowerCase()) ? label : `${label}, ${caption}`
+}
+
+const popupFor: Record<ToolbarTriggerControls, 'menu' | 'dialog' | undefined> = { menu: 'menu', dialog: 'dialog', none: undefined }
+
+/** Compact bar button that opens a menu, drawer or flyout (spec: wave-2/toolbar-trigger.md). */
+export function ToolbarTrigger(props: ToolbarTriggerProps) {
+  const name = nameWithCaption(props.label, props.caption)
+  const control = (
+    <AriaButton
+      id={props.id}
+      className={cx('ty-toolbar-trigger', props.className)}
+      aria-label={name}
+      aria-haspopup={popupFor[props.controls ?? 'none']}
+      aria-expanded={props.expanded}
+      aria-pressed={props.pressed}
+      isDisabled={props.disabled}
+      onPress={() => props.onPress?.()}
+      data-captioned={props.caption ? true : undefined}
+      data-expanded-state={props.expanded ? true : undefined}
+      data-toggled={props.pressed ? true : undefined}
+    >
+      <span className="ty-toolbar-trigger__glyph" aria-hidden="true">
+        {props.icon}
+      </span>
+      {props.caption ? (
+        <span className="ty-toolbar-trigger__caption" aria-hidden="true">
+          {props.caption}
+        </span>
+      ) : null}
+    </AriaButton>
+  )
+  // Icon-only triggers show their name as a tooltip on hover and focus.
+  if (props.caption) return control
+  return (
+    <TooltipTrigger delay={400}>
+      {control}
+      <Tooltip className="ty-toolbar-trigger__tip" offset={6}>
+        {props.label}
+      </Tooltip>
+    </TooltipTrigger>
+  )
+}

package/src/components/tweened-number/TweenedNumber.css

@@ -0,0 +1,7 @@
+/* TweenedNumber (spec: wave-2/tweened-number.md; design direction §2.2, §2.7). */
+@layer tympan.components {
+  .ty-tweened-number {
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+  }
+}

package/src/components/tweened-number/TweenedNumber.rtl.test.tsx

@@ -0,0 +1,19 @@
+import { screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { inRtl } from '../../../test/rtl-b'
+import { TweenedNumber } from './TweenedNumber'
+
+describe('TweenedNumber in right-to-left locales', () => {
+  it('formats with the locale digits (Arabic-Indic in ar-EG) and passes axe', async () => {
+    const { container } = inRtl(<TweenedNumber value={1234} durationMs={0} />, 'ar-EG')
+    expect(container.querySelector('.ty-tweened-number')!.textContent).toBe(new Intl.NumberFormat('ar-EG').format(1234))
+    expect(container.textContent).toMatch(/[٠-٩]/)
+    await expectNoAxeViolations(container)
+  })
+
+  it('keeps fixed decimals in the locale (Devanagari digits in hi-IN-u-nu-deva)', () => {
+    inRtl(<TweenedNumber value={3.5} decimals={1} durationMs={0} />, 'hi-IN-u-nu-deva')
+    expect(screen.getByText(new Intl.NumberFormat('hi-IN-u-nu-deva', { minimumFractionDigits: 1 }).format(3.5))).toBeInTheDocument()
+  })
+})

package/src/components/tweened-number/TweenedNumber.test.tsx

@@ -0,0 +1,97 @@
+import { act, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { setMedia } from '../../../test/media'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { TweenedNumber } from './TweenedNumber'
+
+const text = (c: HTMLElement) => c.querySelector('.ty-tweened-number')!.textContent
+
+describe('TweenedNumber', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ toFake: ['requestAnimationFrame', 'cancelAnimationFrame', 'setTimeout', 'Date', 'performance'] })
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  const advance = (ms: number) => act(() => void vi.advanceTimersByTime(ms))
+
+  it('shows the target on the first frame under reduced motion', () => {
+    setMedia({ reducedMotion: true })
+    const { container } = render(<TweenedNumber value={1234} />)
+    expect(text(container)).toBe(new Intl.NumberFormat('en-US').format(1234))
+  })
+
+  it('jumps straight to a new value with duration 0', () => {
+    const { container, rerender } = render(<TweenedNumber value={10} durationMs={0} />)
+    expect(text(container)).toBe('10')
+    rerender(<TweenedNumber value={20} durationMs={0} />)
+    expect(text(container)).toBe('20')
+  })
+
+  it('lands exactly on the target once the duration has elapsed', () => {
+    const { container, rerender } = render(<TweenedNumber value={0} durationMs={200} />)
+    rerender(<TweenedNumber value={100} durationMs={200} />)
+    advance(64)
+    const mid = Number(text(container))
+    expect(mid).toBeGreaterThan(0)
+    expect(mid).toBeLessThan(100)
+    advance(400)
+    expect(text(container)).toBe('100')
+  })
+
+  it('starts a new tween from the number on screen when interrupted', () => {
+    const { container, rerender } = render(<TweenedNumber value={0} durationMs={1000} />)
+    rerender(<TweenedNumber value={100} durationMs={1000} />)
+    advance(160)
+    const at = Number(text(container))
+    expect(at).toBeGreaterThan(10)
+    rerender(<TweenedNumber value={0} durationMs={1000} />)
+    advance(32)
+    const next = Number(text(container))
+    expect(next).toBeLessThanOrEqual(at)
+    expect(next).toBeGreaterThan(0)
+    advance(2000)
+    expect(text(container)).toBe('0')
+  })
+
+  it('formats every frame with the given formatter', () => {
+    const money = (n: number) => new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(n)
+    const { container, rerender } = render(<TweenedNumber value={0} durationMs={300} format={money} />)
+    rerender(<TweenedNumber value={500} durationMs={300} format={money} />)
+    for (let i = 0; i < 6; i++) {
+      advance(40)
+      expect(text(container)).toMatch(/^R\$\s?[\d.]+,\d{2}$/)
+    }
+  })
+
+  it('does not update after unmount mid-tween', () => {
+    const errors = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { rerender, unmount } = render(<TweenedNumber value={0} durationMs={500} />)
+    rerender(<TweenedNumber value={80} durationMs={500} />)
+    advance(50)
+    unmount()
+    advance(1000)
+    expect(errors).not.toHaveBeenCalled()
+    expect(vi.getTimerCount()).toBe(0)
+    errors.mockRestore()
+  })
+
+  it('is not a live region and has no axe violations', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((s) => (
+          <ThemeScope key={s} scheme={s}>
+            <p>
+              Total <TweenedNumber value={42} durationMs={0} />
+            </p>
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    expect(container.querySelector('[aria-live]')).toBeNull()
+    vi.useRealTimers()
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/tweened-number/TweenedNumber.tsx

@@ -0,0 +1,70 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { TweenDriver } from '../../internal/data-b/tween'
+import { prefersReducedMotion } from '../../internal/media'
+
+/** `--ty-dur-base` of design direction §2.7, in milliseconds. */
+export const TWEEN_BASE_MS = 240
+
+export interface TweenedNumberProps {
+  value: number
+  /** One tween's length; 0 shows every value at once. */
+  durationMs?: number
+  /** Fixed decimals of the default formatter (Intl, in the provider's locale and numbering system). */
+  decimals?: number
+  /** Applied to every intermediate frame (currency, grouping). */
+  format?: (n: number) => string
+  className?: string
+}
+
+/** No movement for zero-length tweens or under reduced motion. */
+const jumps = (ms: number) => ms <= 0 || prefersReducedMotion()
+
+/**
+ * The figure on screen, easing towards `target`. One driver lives for the
+ * component's life; a hidden document lands it on the target at once.
+ */
+function useEasedFigure(target: number, ms: number): number {
+  const [figure, setFigure] = useState(() => (jumps(ms) ? target : 0))
+  const engine = useRef<TweenDriver>(null as unknown as TweenDriver)
+  if (!engine.current) {
+    engine.current = new TweenDriver(setFigure)
+    engine.current.current = figure
+  }
+
+  useEffect(() => {
+    const drive = engine.current
+    jumps(ms) ? drive.set(target) : drive.run(target, ms)
+    const onVisibility = () => {
+      if (document.visibilityState === 'hidden' && drive.running) drive.set(target)
+    }
+    document.addEventListener('visibilitychange', onVisibility)
+    return () => document.removeEventListener('visibilitychange', onVisibility)
+  }, [target, ms])
+
+  useEffect(() => () => engine.current.stop(), [])
+  return figure
+}
+
+/**
+ * A figure that eases from what is on screen to a new value (spec:
+ * wave-2/tweened-number.md). Not a live region: hosts announce the final
+ * value from the surrounding tile when they need to.
+ */
+export function TweenedNumber(props: TweenedNumberProps) {
+  const places = props.decimals ?? 0
+  const { locale } = useLocale()
+  const figure = useEasedFigure(props.value, props.durationMs ?? TWEEN_BASE_MS)
+  const writer = useMemo(() => {
+    if (props.format) return props.format
+    const nf = new Intl.NumberFormat(locale, { minimumFractionDigits: places, maximumFractionDigits: places })
+    return (n: number) => nf.format(Number(n.toFixed(places)))
+  }, [props.format, locale, places])
+
+  return (
+    <span className={cx('ty-tweened-number', props.className)} data-settled={figure === props.value || undefined}>
+      {writer(figure)}
+    </span>
+  )
+}