@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/components/attention-list/AttentionList.tsx

@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react'
+import { Link as AriaLink } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { useMessages } from '../../internal/provider'
+import { VisuallyHidden } from '../../internal/VisuallyHidden'
+import { Button } from '../button/Button'
+import { ProofBadge, type ProofState } from '../proof-badge/ProofBadge'
+
+export interface AttentionAction {
+  label: string
+  href?: string
+  onPress?: () => void
+}
+
+export interface AttentionItem {
+  id: string
+  proof: ProofState | 'none'
+  title: string
+  detail?: string
+  action?: AttentionAction
+}
+
+export interface AttentionListProps {
+  items: AttentionItem[]
+  /** Name of the list. */
+  label: string
+  /** Visible heading above the list. */
+  heading?: ReactNode
+  emptyText?: string
+  maxRows?: number
+  seeAllHref?: string
+  seeAllLabel?: string
+  className?: string
+}
+
+function RowAction({ action, title, suffix }: { action: AttentionAction; title: string; suffix: (title: string) => string }) {
+  // Visible label stays short; the hidden suffix makes the name unique ("Verify: TAMM").
+  const label = (
+    <>
+      {action.label}
+      <VisuallyHidden>{suffix(title)}</VisuallyHidden>
+    </>
+  )
+  return (
+    <Button variant="quiet" size="compact" href={action.href} onPress={action.onPress} className="ty-attention__action">
+      {label}
+    </Button>
+  )
+}
+
+/** What needs the person now: proof state, title, detail, one action (spec: wave-4/attention-list.md). */
+export function AttentionList(props: AttentionListProps) {
+  const words = useMessages().attentionList
+  const rows = props.maxRows !== undefined ? props.items.slice(0, props.maxRows) : props.items
+  const truncated = rows.length < props.items.length
+  return (
+    <div className={cx('ty-attention', props.className)}>
+      {props.heading ? <div className="ty-attention__heading">{props.heading}</div> : null}
+      {rows.length === 0 ? (
+        <p className="ty-attention__empty">{props.emptyText ?? words.empty}</p>
+      ) : (
+        <ul className="ty-attention__list" aria-label={props.label}>
+          {rows.map((row) => (
+            <li key={row.id} className="ty-attention__row">
+              <ProofBadge state={row.proof === 'none' ? null : row.proof} className="ty-attention__proof" />
+              <div className="ty-attention__text">
+                <span className="ty-attention__title" dir="auto">{row.title}</span>
+                {row.detail ? <span className="ty-attention__detail" dir="auto">{row.detail}</span> : null}
+              </div>
+              {row.action ? <RowAction action={row.action} title={row.title} suffix={words.actionTarget} /> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+      {props.seeAllHref && (truncated || props.maxRows === undefined) ? (
+        <AriaLink className="ty-attention__more" href={props.seeAllHref}>
+          {props.seeAllLabel ?? words.seeAll}
+        </AriaLink>
+      ) : null}
+    </div>
+  )
+}

package/src/components/auth-frame/AuthFrame.css

@@ -0,0 +1,85 @@
+/* AuthFrame (spec: wave-2/auth-frame.md; design direction §2.1, §2.5, §3.3). */
+@layer tympan.components {
+  .ty-auth-frame {
+    position: relative;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    min-block-size: 100dvh;
+    background: var(--ty-bg);
+    color: var(--ty-ink-2);
+  }
+  .ty-auth-frame[data-split] {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .ty-auth-frame__brand,
+  .ty-auth-frame__form-side {
+    position: relative;
+    z-index: 1;
+  }
+  .ty-auth-frame__form-side {
+    display: grid;
+    place-items: center;
+    padding: var(--ty-space-6) var(--ty-space-4);
+    overflow-y: auto;
+    outline: none;
+  }
+  .ty-auth-frame__column {
+    display: flex;
+    flex-direction: column;
+    gap: var(--ty-space-5);
+    inline-size: 100%;
+    max-inline-size: 400px;
+  }
+  .ty-auth-frame__column[data-width='narrow'] {
+    max-inline-size: 340px;
+  }
+  .ty-auth-frame__column[data-width='wide'] {
+    max-inline-size: 520px;
+  }
+  .ty-auth-frame__mark {
+    display: flex;
+    justify-content: center;
+  }
+  .ty-auth-frame__sheet {
+    box-sizing: border-box;
+    min-inline-size: 0;
+    padding: var(--ty-space-5);
+    border: 1px solid var(--ty-line);
+    border-radius: var(--ty-radius-sheet);
+    background: var(--ty-surface);
+    box-shadow: var(--ty-shadow-sheet);
+    backdrop-filter: blur(var(--ty-glass-blur-sheet)) saturate(var(--ty-glass-saturate));
+    -webkit-backdrop-filter: blur(var(--ty-glass-blur-sheet)) saturate(var(--ty-glass-saturate));
+  }
+  /* The page title of this frame uses the display step (§2.2). */
+  .ty-auth-frame__sheet :where(h1) {
+    margin: 0 0 var(--ty-space-4);
+    color: var(--ty-ink);
+    font-family: var(--ty-font-serif);
+    font-size: var(--ty-font-size-display);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-display);
+  }
+
+  @media (min-width: 768px) {
+    .ty-auth-frame__form-side {
+      padding-inline: var(--ty-space-6);
+    }
+    .ty-auth-frame__sheet {
+      padding: var(--ty-space-6);
+    }
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-auth-frame__sheet {
+      background: var(--ty-surface-solid);
+      backdrop-filter: none;
+      -webkit-backdrop-filter: none;
+    }
+  }
+  @media (forced-colors: active) {
+    .ty-auth-frame__sheet {
+      border: 1px solid CanvasText;
+    }
+  }
+}

package/src/components/auth-frame/AuthFrame.rtl.test.tsx

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { inRtl } from '../../../test/rtl-b'
+import { AuthFrame } from './AuthFrame'
+import { BrandMark } from '../brand-mark/BrandMark'
+
+describe('AuthFrame in right-to-left locales', () => {
+  it('renders inside an Arabic right-to-left subtree and passes axe', async () => {
+    const { container } = inRtl(<AuthFrame mainLabel="تسجيل الدخول" mark={<BrandMark />} brandPanel={{ mark: <BrandMark showWordmark={false} />, title: 'الدليل قبل الرأي', subtitle: 'منضدة هادئة', figures: [{ value: '٩٤', label: 'حالة' }] }}><h1>تسجيل الدخول</h1></AuthFrame>)
+    expect(container.querySelector('[dir="rtl"]')).not.toBeNull()
+    expect(container.textContent).toContain('تسجيل الدخول')
+    await expectNoAxeViolations(document.body, ['region'])
+  })
+})

package/src/components/auth-frame/AuthFrame.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen, within } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { setViewportWidth } from '../../../test/media'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { BrandMark } from '../brand-mark/BrandMark'
+import { AuthFrame } from './AuthFrame'
+
+const panel = { mark: <BrandMark />, title: 'Evidence first', subtitle: 'Research workbench.', figures: [{ value: '94', label: 'cases' }] }
+const form = (
+  <form aria-label="Sign in">
+    <h1>Sign in</h1>
+    <label>
+      E-mail <input />
+    </label>
+    <button type="submit">Enter</button>
+  </form>
+)
+const css = cssOf('components/auth-frame/AuthFrame.css')
+
+describe('AuthFrame', () => {
+  it('shows two columns at 1440 px with the form inside main', () => {
+    setViewportWidth(1440)
+    const { container } = render(<AuthFrame brandPanel={panel}>{form}</AuthFrame>)
+    expect(container.firstElementChild).toHaveAttribute('data-split')
+    expect(screen.getByRole('complementary', { name: 'Evidence first' })).toBeInTheDocument()
+    expect(within(screen.getByRole('main')).getByRole('form', { name: 'Sign in' })).toBeInTheDocument()
+  })
+
+  it('drops the brand side entirely at 375 px; the form fills the width minus 16 px gutters', () => {
+    setViewportWidth(375)
+    const { container } = render(<AuthFrame brandPanel={panel}>{form}</AuthFrame>)
+    expect(screen.queryByRole('complementary')).toBeNull()
+    expect(container.textContent).not.toContain('Evidence first')
+    expect(css).toMatch(/\.ty-auth-frame__form-side\s*\{[^}]*padding:\s*var\(--ty-space-6\)\s+var\(--ty-space-4\)/)
+    expect(css).toMatch(/\.ty-auth-frame__column\s*\{[^}]*inline-size:\s*100%/)
+  })
+
+  it('centres the surface without a brand panel', () => {
+    const { container } = render(<AuthFrame>{form}</AuthFrame>)
+    expect(container.firstElementChild).not.toHaveAttribute('data-split')
+    expect(css).toMatch(/\.ty-auth-frame__form-side\s*\{[^}]*place-items:\s*center/)
+  })
+
+  it('narrow is narrower than regular', () => {
+    const { container } = render(<AuthFrame width="narrow">{form}</AuthFrame>)
+    expect(container.querySelector('.ty-auth-frame__column')).toHaveAttribute('data-width', 'narrow')
+    const px = (sel: string) => Number(new RegExp(`${sel}\\s*\\{[^}]*max-inline-size:\\s*(\\d+)px`).exec(css)?.[1])
+    expect(px("\\.ty-auth-frame__column\\[data-width='narrow'\\]")).toBeLessThan(px('\\.ty-auth-frame__column'))
+  })
+
+  it('puts the mark before the form surface in reading order', () => {
+    const { container } = render(<AuthFrame mark={<BrandMark />}>{form}</AuthFrame>)
+    const mark = container.querySelector('.ty-auth-frame__mark')!
+    const sheet = container.querySelector('.ty-auth-frame__sheet')!
+    expect(mark.compareDocumentPosition(sheet) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy()
+  })
+
+  it('scrolls when taller than the viewport, so every field stays reachable', () => {
+    expect(css).toMatch(/\.ty-auth-frame__form-side\s*\{[^}]*overflow-y:\s*auto/)
+    expect(css).toMatch(/min-block-size:\s*100dvh/)
+    expect(css).not.toMatch(/\.ty-auth-frame[^{]*\{[^}]*overflow:\s*hidden/)
+  })
+
+  it('keeps a system border and becomes opaque when asked', () => {
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/border:\s*1px solid CanvasText/)
+    expect(mediaBlock(css, /\(prefers-reduced-transparency:\s*reduce\)/)).toMatch(/backdrop-filter:\s*none/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    setViewportWidth(1440)
+    const { container } = render(
+      <>
+        <ThemeScope scheme="light">
+          <AuthFrame brandPanel={panel} mark={<BrandMark />} mainLabel="Sign in, light">
+            <p>Light</p>
+          </AuthFrame>
+        </ThemeScope>
+        <ThemeScope scheme="dark">
+          <AuthFrame mainLabel="Sign in, dark">
+            <p>Dark</p>
+          </AuthFrame>
+        </ThemeScope>
+      </>,
+    )
+    await expectNoAxeViolations(container, ['landmark-no-duplicate-main', 'landmark-one-main', 'landmark-complementary-is-top-level', 'landmark-main-is-top-level', 'landmark-unique'])
+  })
+})

package/src/components/auth-frame/AuthFrame.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react'
+import { breakpoints, useMinWidth } from '../../internal/media'
+import { AmbientBackdrop } from '../ambient-backdrop/AmbientBackdrop'
+import { BrandPanel, type BrandPanelProps } from '../brand-panel/BrandPanel'
+
+export type AuthFrameWidth = 'narrow' | 'regular' | 'wide'
+
+export interface AuthFrameProps {
+  children: ReactNode
+  /** Renders the brand side on wide screens (never below 1024 px). */
+  brandPanel?: BrandPanelProps
+  width?: AuthFrameWidth
+  /** Product mark shown above the form surface. */
+  mark?: ReactNode
+  mainLabel?: string
+  className?: string
+}
+
+/** Frame of sign-in and recovery screens (spec: wave-2/auth-frame.md). */
+export function AuthFrame({ brandPanel, mark, mainLabel, width = 'regular', className, children }: AuthFrameProps) {
+  const wide = useMinWidth(breakpoints.lg)
+  const brandSide = brandPanel && wide ? <BrandPanel {...brandPanel} className="ty-auth-frame__brand" /> : null
+  return (
+    <div className={className ? `ty-auth-frame ${className}` : 'ty-auth-frame'} data-split={brandSide ? '' : undefined}>
+      <AmbientBackdrop />
+      {brandSide}
+      <main className="ty-auth-frame__form-side" aria-label={mainLabel}>
+        <div className="ty-auth-frame__column" data-width={width}>
+          {mark ? <div className="ty-auth-frame__mark">{mark}</div> : null}
+          <div className="ty-auth-frame__sheet">{children}</div>
+        </div>
+      </main>
+    </div>
+  )
+}

package/src/components/avatar/Avatar.css

@@ -0,0 +1,134 @@
+/* Avatar (spec: wave-1/avatar.md; design direction §2.3, §2.11). */
+@layer tympan.components {
+  /* <ty-avatar>'s anatomy root and its fallback wrapper add no box: the
+     frame or the control is the layout child. */
+  .ty-avatar-root,
+  .ty-avatar__fallback {
+    display: contents;
+  }
+  .ty-avatar__fallback[hidden] {
+    display: none;
+  }
+
+  .ty-avatar {
+    --ty-avatar-size: calc(var(--ty-space-6) + var(--ty-space-2));
+    box-sizing: border-box;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--ty-avatar-size);
+    block-size: var(--ty-avatar-size);
+    overflow: hidden;
+    border-radius: 50%;
+    border: 1px solid transparent;
+    background: var(--ty-accent-soft);
+    color: var(--ty-on-accent-soft);
+    font-family: var(--ty-font-sans);
+    font-weight: var(--ty-font-weight-semibold);
+    font-size: max(12px, calc(var(--ty-avatar-size) * 0.4));
+    line-height: 1;
+    user-select: none;
+  }
+
+  .ty-avatar[data-size='xsmall'] {
+    --ty-avatar-size: var(--ty-space-5);
+  }
+  .ty-avatar[data-size='small'] {
+    --ty-avatar-size: var(--ty-space-6);
+  }
+  .ty-avatar[data-size='large'] {
+    --ty-avatar-size: calc(var(--ty-space-7) + var(--ty-space-2));
+  }
+
+  .ty-avatar[data-tint='neutral'] {
+    background: var(--ty-surface-sunken);
+    color: var(--ty-on-surface-sunken);
+  }
+
+  /* Agents: rounded square, dashed border, never initials (§2.11). */
+  .ty-avatar[data-kind='agent'] {
+    border-radius: var(--ty-radius-agent);
+    border: 1px dashed var(--ty-line-strong);
+    background: var(--ty-actor-agent-soft);
+    color: var(--ty-actor-agent);
+  }
+
+  .ty-avatar[data-image] {
+    background: var(--ty-surface-sunken);
+  }
+  .ty-avatar__image {
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+  /* Artwork (a generated avatar or the host's own SVG) fills the frame; the frame clips it. */
+  .ty-avatar[data-artwork] {
+    background: var(--ty-surface-sunken);
+  }
+  .ty-avatar__artwork,
+  .ty-avatar__artwork > svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+  .ty-avatar__icon {
+    inline-size: 60%;
+    block-size: 60%;
+  }
+  /* Initials are shown as given: case is the host's (and the script's) business. */
+  .ty-avatar__initials {
+    line-height: 1;
+  }
+
+  /* Pressable wrapper: 44 x 44 px hit area at every size; hover changes fill only. */
+  .ty-avatar-control {
+    all: unset;
+    position: relative;
+    display: inline-flex;
+    border-radius: 50%;
+    cursor: pointer;
+  }
+  .ty-avatar-control::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%);
+  }
+  /* The data-* states are the React (react-aria) rendering; the custom
+     element's native <a>/<button> uses the platform pseudo-classes. */
+  .ty-avatar-control[data-hovered] .ty-avatar,
+  .ty-avatar-control:hover .ty-avatar {
+    background: var(--ty-accent-soft);
+    border-color: var(--ty-accent);
+  }
+  .ty-avatar-control[data-focus-visible],
+  .ty-avatar-control:focus-visible {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-avatar-control[data-pressed] .ty-avatar,
+  .ty-avatar-control:active .ty-avatar {
+    opacity: 0.85;
+  }
+
+  @media (forced-colors: active) {
+    .ty-avatar {
+      border: 1px solid CanvasText;
+      color: CanvasText;
+      forced-color-adjust: none;
+      background: Canvas;
+    }
+    .ty-avatar[data-kind='agent'] {
+      border-style: dashed;
+    }
+    .ty-avatar-control[data-focus-visible],
+    .ty-avatar-control:focus-visible {
+      outline: 2px solid Highlight;
+    }
+  }
+}

package/src/components/avatar/Avatar.test.tsx

@@ -0,0 +1,98 @@
+import { fireEvent, 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 } from '../../../test/css'
+import { Avatar } from './Avatar'
+
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+describe('Avatar', () => {
+  it('shows an image whose alternative text is the name', () => {
+    render(<Avatar src="/a.png" name="Júlia Andrade" />)
+    expect(screen.getByRole('img', { name: 'Júlia Andrade' }).tagName).toBe('IMG')
+  })
+
+  it('shows the fallback when the image fails', () => {
+    render(<Avatar src="/broken.png" name="Júlia Andrade" fallbackText="JA" />)
+    fireEvent.error(screen.getByRole('img'))
+    expect(screen.getByText('JA')).toBeInTheDocument()
+  })
+
+  it('announces the name, not the initials', () => {
+    render(<Avatar fallbackText="JA" name="Júlia Andrade" />)
+    const img = screen.getByRole('img')
+    expect(img).toHaveAccessibleName('Júlia Andrade')
+    expect(screen.getByText('JA')).toHaveAttribute('aria-hidden', 'true')
+  })
+
+  it('draws an agent as a rounded square with a bot icon and no initials', () => {
+    const { container } = render(<Avatar actorKind="agent" name="limit-counter" fallbackText="LC" />)
+    const frame = container.querySelector('.ty-avatar')!
+    expect(frame).toHaveAttribute('data-kind', 'agent')
+    expect(frame.querySelector('svg')).not.toBeNull()
+    expect(screen.queryByText('LC')).toBeNull()
+    const css = cssOf('components/avatar/Avatar.css')
+    expect(css).toMatch(/\[data-kind='agent'\]\s*\{[^}]*border-radius:\s*var\(--ty-radius-agent\)[^}]*dashed/)
+  })
+
+  it('draws artwork instead of the initials and keeps the name on the frame', () => {
+    const { container } = render(<Avatar name="Rosa Alvim" fallbackText="RA" artwork={<svg data-testid="art" aria-hidden="true" />} />)
+    expect(screen.getByRole('img', { name: 'Rosa Alvim' })).toHaveAttribute('data-artwork')
+    expect(screen.getByTestId('art')).toBeInTheDocument()
+    expect(screen.queryByText('RA')).toBeNull()
+    expect(container.querySelector('.ty-avatar__icon')).toBeNull()
+  })
+
+  it('prefers the image over the artwork and falls back to initials when the artwork is null', () => {
+    const { rerender } = render(<Avatar src="/a.png" name="Rosa Alvim" artwork={<svg data-testid="art" />} />)
+    expect(screen.queryByTestId('art')).toBeNull()
+    rerender(<Avatar name="Rosa Alvim" fallbackText="RA" artwork={null} />)
+    expect(screen.getByText('RA')).toBeInTheDocument()
+  })
+
+  it('is hidden from assistive tech when decorative', () => {
+    const { container } = render(<Avatar decorative fallbackText="JA" />)
+    expect(container.firstElementChild).toHaveAttribute('aria-hidden', 'true')
+    expect(screen.queryByRole('img')).toBeNull()
+  })
+
+  it('fires onPress on Enter', async () => {
+    const onPress = vi.fn()
+    render(<Avatar name="Júlia" fallbackText="J" onPress={onPress} />)
+    await userEvent.tab()
+    expect(screen.getByRole('button', { name: 'Open profile of Júlia' })).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    expect(onPress).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps a 44 x 44 hit area when xsmall and pressable', () => {
+    render(<Avatar size="xsmall" name="N" onPress={() => {}} />)
+    expect(screen.getByRole('button')).toHaveClass('ty-avatar-control')
+    expect(cssOf('components/avatar/Avatar.css')).toMatch(/\.ty-avatar-control::before\s*\{[^}]*inline-size:\s*max\(100%,\s*var\(--ty-control-target\)\)[^}]*block-size:\s*max\(100%,\s*var\(--ty-control-target\)\)/)
+  })
+
+  it('has no axe violations', async () => {
+    const { container } = render(
+      <div>
+        <Avatar name="Ana" fallbackText="A" />
+        <Avatar name="Bot" actorKind="agent" />
+        <Avatar decorative fallbackText="C" tint="neutral" />
+        <Avatar name="Dora" onPress={() => {}} />
+      </div>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('Avatar in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<><Avatar name="نور الهدى" fallbackText="نه" /><Avatar name="Núria" fallbackText={'Nu\u0301r'} /></>)
+    const initials = container.querySelectorAll('.ty-avatar__initials')
+    expect(initials[0]).toHaveTextContent('نه')
+    // Two grapheme clusters: the combining accent stays with its letter.
+    expect(initials[1]!.textContent).toBe('Nu\u0301')
+    await axeRtl(container)
+  })
+})

package/src/components/avatar/Avatar.tsx

@@ -0,0 +1,114 @@
+import { Bot, User } from 'lucide-react'
+import { useEffect, useState, type ReactNode } from 'react'
+import { Button as AriaButton, Link as AriaLink, type PressEvent } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+import { devWarning } from '../../internal/dev'
+import { useMessages } from '../../internal/provider'
+
+/** The first `count` user-perceived characters (grapheme clusters), so marks and emoji stay whole. */
+function leadingGraphemes(text: string, count: number): string {
+  const Segmenter = (Intl as { Segmenter?: typeof Intl.Segmenter }).Segmenter
+  if (!Segmenter) return Array.from(text).slice(0, count).join('')
+  let out = ''
+  let taken = 0
+  for (const { segment } of new Segmenter(undefined, { granularity: 'grapheme' }).segment(text)) {
+    if (taken === count) break
+    out += segment
+    taken += 1
+  }
+  return out
+}
+
+export type AvatarSize = 'xsmall' | 'small' | 'regular' | 'large'
+
+export interface AvatarProps {
+  /** Image URL; on load error the fallback shows. */
+  src?: string | null
+  /** One or two characters shown without an image (derived by the host from a name). */
+  fallbackText?: string
+  /** Accessible name; required unless `decorative`. */
+  name?: string
+  /** Hides the avatar from assistive tech when the name is shown next to it. */
+  decorative?: boolean
+  /** Person: circle with initials. Agent: rounded square, bot icon, dashed border, never initials (§2.11). */
+  actorKind?: 'person' | 'agent'
+  size?: AvatarSize
+  /** Fallback background: accent-soft or neutral. */
+  tint?: 'accent' | 'neutral'
+  /**
+   * Artwork drawn when there is no image (or the image fails): a generated
+   * avatar (`@datatechsolutions/tympan/avatars`) or the host's own. It replaces
+   * the initials and the agent bot icon and is always decorative; the frame
+   * carries the name. Without it (or when it is null) the fallback shows.
+   */
+  artwork?: ReactNode
+  /** Makes the avatar a button. */
+  onPress?: (e: PressEvent) => void
+  /** Makes the avatar a link (router adapter). */
+  href?: string
+  className?: string
+}
+
+/** Person or agent picture with fallback (spec: wave-1/avatar.md; design direction §2.11). */
+export function Avatar({ src, fallbackText, name, decorative = false, actorKind = 'person', size = 'regular', tint = 'accent', artwork, onPress, href, className }: AvatarProps) {
+  const messages = useMessages()
+  const [failed, setFailed] = useState(false)
+  useEffect(() => setFailed(false), [src])
+  const pressable = !!(onPress || href)
+  devWarning(!decorative && !name, 'Avatar: `name` is required unless `decorative`.')
+
+  const isAgent = actorKind === 'agent'
+  const showImage = !!src && !failed
+  const showArtwork = !showImage && artwork != null
+  // Inside a pressable wrapper the visual is decorative: the control carries the name.
+  const hidden = decorative || pressable
+
+  let inner
+  if (showImage) {
+    inner = <img className="ty-avatar__image" src={src ?? undefined} alt={hidden ? '' : (name ?? '')} onError={() => setFailed(true)} />
+  } else if (showArtwork) {
+    inner = artwork
+  } else if (isAgent) {
+    inner = <Bot className="ty-avatar__icon" aria-hidden="true" focusable="false" />
+  } else if (fallbackText) {
+    inner = (
+      <span className="ty-avatar__initials" aria-hidden="true">
+        {leadingGraphemes(fallbackText, 2)}
+      </span>
+    )
+  } else {
+    inner = <User className="ty-avatar__icon" aria-hidden="true" focusable="false" />
+  }
+
+  const visual = (
+    <span
+      className={cx('ty-avatar', !pressable && className)}
+      data-kind={actorKind}
+      data-size={size}
+      data-tint={tint}
+      data-image={showImage || undefined}
+      data-artwork={showArtwork || undefined}
+      aria-hidden={hidden ? true : undefined}
+      role={!hidden && !showImage ? 'img' : undefined}
+      aria-label={!hidden && !showImage ? name : undefined}
+    >
+      {inner}
+    </span>
+  )
+
+  if (!pressable) return visual
+
+  const label = name ? messages.avatar.open(name) : undefined
+  if (href) {
+    return (
+      <AriaLink href={href} onPress={onPress} aria-label={label} className={cx('ty-avatar-control', className)} data-size={size}>
+        {visual}
+      </AriaLink>
+    )
+  }
+  return (
+    <AriaButton onPress={onPress} aria-label={label} className={cx('ty-avatar-control', className)} data-size={size}>
+      {visual}
+    </AriaButton>
+  )
+}