@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/components/cascade-grid/CascadeGrid.test.tsx

@@ -0,0 +1,126 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { renderToString } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { setMedia } from '../../../test/media'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { DecorativeMotion } from '../../utilities/motion-foundation/motion'
+import { CascadeGrid, entranceSchedule } from './CascadeGrid'
+
+const items = (n: number) => Array.from({ length: n }, (_, i) => <p key={`i${i}`}>Item {i + 1}</p>)
+const css = cssOf('components/cascade-grid/CascadeGrid.css')
+
+describe('CascadeGrid', () => {
+  it('renders a plain grid by default', () => {
+    const { container } = render(
+      <CascadeGrid cascade role="list" aria-label="Features">
+        {items(3)}
+      </CascadeGrid>,
+    )
+    const plain = render(
+      <div className="ty-cascade-grid" role="list" aria-label="Features">
+        {items(3)}
+      </div>,
+    )
+    expect(container.firstElementChild!.isEqualNode(plain.container.firstElementChild)).toBe(true)
+    expect(container.querySelector('[data-entering]')).toBeNull()
+  })
+
+  it('starts entrances in document order when both switches are on', () => {
+    const { container } = render(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>{items(4)}</CascadeGrid>
+      </DecorativeMotion>,
+    )
+    const cells = [...container.querySelectorAll<HTMLElement>('.ty-cascade-grid__cell')]
+    expect(cells.every((c) => c.hasAttribute('data-entering'))).toBe(true)
+    const delays = cells.map((c) => parseFloat(c.style.getPropertyValue('--ty-cascade-delay')))
+    expect(delays).toEqual([...delays].sort((a, b) => a - b))
+    expect(delays[0]).toBe(0)
+    expect(delays[3]).toBeGreaterThan(delays[1]!)
+  })
+
+  it('starts the last of twenty items within maxTotalMs', () => {
+    expect(entranceSchedule(20, 90, 240).at(-1)).toBeLessThanOrEqual(240)
+    const { container } = render(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade maxTotalMs={240}>
+          {items(20)}
+        </CascadeGrid>
+      </DecorativeMotion>,
+    )
+    const last = [...container.querySelectorAll<HTMLElement>('.ty-cascade-grid__cell')].at(-1)!
+    expect(parseFloat(last.style.getPropertyValue('--ty-cascade-delay'))).toBeLessThanOrEqual(240)
+  })
+
+  it('runs no animation under reduced motion', () => {
+    setMedia({ reducedMotion: true })
+    const { container } = render(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>{items(3)}</CascadeGrid>
+      </DecorativeMotion>,
+    )
+    expect(container.querySelector('[data-entering]')).toBeNull()
+    expect(mediaBlock(css, /\(prefers-reduced-motion:\s*reduce\)/)).toMatch(/animation:\s*none/)
+  })
+
+  it('shows children added after mount without animation', () => {
+    const { container, rerender } = render(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>{items(2)}</CascadeGrid>
+      </DecorativeMotion>,
+    )
+    rerender(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>{items(3)}</CascadeGrid>
+      </DecorativeMotion>,
+    )
+    const cells = container.querySelectorAll('.ty-cascade-grid__cell')
+    expect(cells).toHaveLength(3)
+    expect(cells[2]).not.toHaveAttribute('data-entering')
+  })
+
+  it('lets Tab reach a child during the cascade', async () => {
+    render(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>
+          <button type="button">Open</button>
+          <p>Other</p>
+        </CascadeGrid>
+      </DecorativeMotion>,
+    )
+    await userEvent.tab()
+    expect(screen.getByRole('button', { name: 'Open' })).toHaveFocus()
+  })
+
+  it('renders visible items on the server and uses opacity and translate only', () => {
+    const html = renderToString(
+      <DecorativeMotion enabled>
+        <CascadeGrid cascade>{items(2)}</CascadeGrid>
+      </DecorativeMotion>,
+    )
+    expect(html).not.toMatch(/data-entering/)
+    expect(css).not.toMatch(/scale|spring/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <DecorativeMotion enabled>
+              <CascadeGrid cascade role="list" aria-label={`Grid ${scheme}`}>
+                <div role="listitem">One</div>
+                <div role="listitem">Two</div>
+              </CascadeGrid>
+            </DecorativeMotion>
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    // Wrappers are role="none", so list semantics pass straight through them.
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/cascade-grid/CascadeGrid.tsx

@@ -0,0 +1,98 @@
+// CascadeGrid (spec: wave-4/cascade-grid.md).
+//
+// A grid whose first children fade in one after another, once, on first
+// mount. Three switches must all agree: the instance's `cascade`, the global
+// `decorativeMotion` flag, and no reduced-motion preference. Otherwise the
+// component is a plain grid. Public pages only (§2.7).
+import { Children, useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+import { prefersReducedMotion } from '../../internal/media'
+import { duration, useDecorativeMotion } from '../../utilities/motion-foundation/motion'
+
+const useBeforePaint = typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+export interface CascadeGridProps {
+  children: ReactNode
+  /** Per-instance opt-in; also needs the global decorativeMotion switch. */
+  cascade?: boolean
+  stepMs?: number
+  maxTotalMs?: number
+  distance?: 'none' | 'small'
+  role?: string
+  'aria-label'?: string
+  'data-testid'?: string
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Start offsets (ms) for `count` entrants: evenly spaced by `gap`, but
+ * squeezed so the last one starts no later than `limit`.
+ */
+export function entranceSchedule(count: number, gap: number, limit: number): number[] {
+  const offsets: number[] = []
+  const spacing = count < 2 ? 0 : Math.min(gap, limit / (count - 1))
+  for (let n = 0; n < count; n += 1) offsets.push(Math.round(n * spacing))
+  return offsets
+}
+
+/**
+ * Decides, once, whether this mount plays the entrance. Returns the schedule
+ * while it plays and `null` otherwise. The entrant count is frozen at mount,
+ * so children added later never replay it.
+ */
+function useEntrance(enabled: boolean, count: number, gap: number, limit: number): number[] | null {
+  const frozen = useRef<number[] | null>(null)
+  const [playing, setPlaying] = useState(false)
+  useBeforePaint(() => {
+    if (!enabled || frozen.current) return
+    frozen.current = entranceSchedule(count, gap, limit)
+    if (prefersReducedMotion()) return
+    setPlaying(true)
+    const lastStart = frozen.current[frozen.current.length - 1] ?? 0
+    const timer = window.setTimeout(() => setPlaying(false), lastStart + duration.ms.base * 2)
+    return () => window.clearTimeout(timer)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+  return playing ? frozen.current : null
+}
+
+function Entrant({ offset, children }: { offset: number | undefined; children: ReactNode }) {
+  const moving = offset !== undefined
+  return (
+    <div
+      role="none"
+      className="ty-cascade-grid__cell"
+      data-entering={moving || undefined}
+      style={moving ? ({ '--ty-cascade-delay': `${offset}ms` } as CSSProperties) : undefined}
+    >
+      {children}
+    </div>
+  )
+}
+
+export function CascadeGrid(props: CascadeGridProps) {
+  const decorativeOn = useDecorativeMotion()
+  const enabled = Boolean(props.cascade) && decorativeOn
+  const kids = Children.toArray(props.children)
+  const schedule = useEntrance(enabled, kids.length, props.stepMs ?? duration.ms.instant, props.maxTotalMs ?? duration.ms.base)
+
+  const host = {
+    role: props.role,
+    'aria-label': props['aria-label'],
+    'data-testid': props['data-testid'],
+    className: cx('ty-cascade-grid', props.className),
+    style: props.style,
+  }
+  if (!enabled) return <div {...host}>{props.children}</div>
+
+  return (
+    <div {...host} data-distance={props.distance ?? 'small'} data-cascading={schedule ? true : undefined}>
+      {kids.map((kid, place) => (
+        <Entrant key={(kid as { key?: string | null }).key ?? place} offset={schedule?.[place]}>
+          {kid}
+        </Entrant>
+      ))}
+    </div>
+  )
+}

package/src/components/category-tabs/CategoryTabs.css

@@ -0,0 +1,108 @@
+/* CategoryTabs and CategoryLabel (spec: wave-2/category-tabs.md; design direction §2.3, §2.6, §2.10). */
+@layer tympan.components {
+  .ty-category-tabs {
+    position: relative;
+    min-inline-size: 0;
+  }
+  .ty-category-tabs__row {
+    display: flex;
+    gap: var(--ty-space-2);
+    overflow-x: auto;
+    padding: var(--ty-space-1);
+    scrollbar-width: thin;
+  }
+  .ty-category-tabs__item {
+    --ty-category-marker: var(--ty-ink-3);
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    gap: var(--ty-space-2);
+    min-block-size: var(--ty-control-target);
+    padding-inline: var(--ty-space-3);
+    border: 1px solid transparent;
+    border-radius: var(--ty-radius-control);
+    background: transparent;
+    color: var(--ty-ink-3);
+    font: inherit;
+    font-size: var(--ty-font-size-body);
+    white-space: nowrap;
+    cursor: pointer;
+    outline: none;
+    transition:
+      color var(--ty-dur-instant) var(--ty-ease),
+      border-color var(--ty-dur-instant) var(--ty-ease),
+      background-color var(--ty-dur-instant) var(--ty-ease);
+  }
+  .ty-category-tabs__item[data-hovered] {
+    color: var(--ty-ink-2);
+    background: var(--ty-surface-sunken);
+  }
+  .ty-category-tabs__item[data-selected] {
+    border-color: var(--ty-line-strong);
+    background: var(--ty-surface-solid);
+    color: var(--ty-ink);
+  }
+  .ty-category-tabs__item[data-focus-visible] {
+    outline: var(--ty-focus-width) solid var(--ty-focus-ring);
+    outline-offset: 2px;
+  }
+  .ty-category-tabs__item[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+  .ty-category-tabs__marker {
+    flex: none;
+    inline-size: var(--ty-space-2);
+    block-size: var(--ty-space-2);
+    border-radius: 2px;
+    background: var(--ty-category-marker);
+    visibility: hidden;
+  }
+  .ty-category-tabs__item[data-selected] .ty-category-tabs__marker,
+  .ty-category-label .ty-category-tabs__marker {
+    visibility: visible;
+  }
+  .ty-category-tabs__code {
+    font-weight: var(--ty-font-weight-semibold);
+  }
+
+  .ty-category-label {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--ty-space-1);
+    color: var(--ty-ink-2);
+    font-size: var(--ty-font-size-label);
+    font-weight: var(--ty-font-weight-semibold);
+    line-height: var(--ty-font-line-height-label);
+  }
+  .ty-category-label[data-size='small'] {
+    font-size: var(--ty-font-size-meta);
+    line-height: var(--ty-font-line-height-meta);
+  }
+
+  /* Phones: horizontal scroll with a visible edge fade. */
+  @media (max-width: 639.98px) {
+    .ty-category-tabs__row {
+      mask-image: linear-gradient(to right, transparent, #000 var(--ty-space-4), #000 calc(100% - var(--ty-space-5)), transparent);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .ty-category-tabs__item {
+      transition: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-category-tabs__item {
+      border: 1px solid ButtonText;
+    }
+    .ty-category-tabs__item[data-selected] {
+      border: 2px solid Highlight;
+    }
+    .ty-category-tabs__marker {
+      forced-color-adjust: none;
+    }
+  }
+}

package/src/components/category-tabs/CategoryTabs.test.tsx

@@ -0,0 +1,118 @@
+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 { CategoryLabel, CategoryTabs, type CategoryItem } from './CategoryTabs'
+import * as rtlDom from '@testing-library/react'
+import { expectNoAxeViolations as axeRtl } from '../../../test/axe'
+import { renderRtl } from '../../../test/rtl'
+
+const items: CategoryItem[] = [
+  { key: 'pt', value: 'pt-v', code: 'PT', name: 'PT Portugal', marker: 1 },
+  { key: 'br', code: 'BR', name: 'Brasil', marker: 2 },
+  { key: 'ee', code: 'EE', name: 'EE', marker: 3 },
+]
+
+describe('CategoryTabs', () => {
+  it('shows the code and the name without the code', () => {
+    render(<CategoryTabs label="Country" items={items} selected={null} onSelect={() => {}} />)
+    const pt = screen.getByRole('radio', { name: /PT/ })
+    expect(pt).toHaveTextContent('PT')
+    expect(pt.querySelector('.ty-category-tabs__name')).toHaveTextContent(/^Portugal$/)
+  })
+
+  it('keeps the full name when removing the code leaves nothing', () => {
+    render(<CategoryTabs label="Country" items={items} selected={null} onSelect={() => {}} />)
+    const ee = screen.getAllByRole('radio')[2]!
+    expect(ee.querySelector('.ty-category-tabs__name')).toHaveTextContent(/^EE$/)
+  })
+
+  it('reports the value (not the key) and shows it selected', async () => {
+    const onSelect = vi.fn()
+    const { rerender } = render(<CategoryTabs label="Country" items={items} selected={null} onSelect={onSelect} />)
+    await userEvent.click(screen.getByRole('radio', { name: /Portugal/ }))
+    expect(onSelect).toHaveBeenCalledWith('pt-v')
+    rerender(<CategoryTabs label="Country" items={items} selected="pt-v" onSelect={onSelect} />)
+    expect(screen.getByRole('radio', { name: /Portugal/ })).toHaveAttribute('aria-checked', 'true')
+  })
+
+  it('does not bubble activation to an enclosing clickable card', async () => {
+    const onCard = vi.fn()
+    const onSelect = vi.fn()
+    render(
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events
+      <div onClick={onCard}>
+        <CategoryTabs label="Country" items={items} selected={null} onSelect={onSelect} />
+      </div>,
+    )
+    await userEvent.click(screen.getByRole('radio', { name: /Brasil/ }))
+    expect(onSelect).toHaveBeenCalledWith('br')
+    expect(onCard).not.toHaveBeenCalled()
+  })
+
+  it('clears with allowNone and keeps the filter otherwise', async () => {
+    const onSelect = vi.fn()
+    const { rerender } = render(<CategoryTabs label="Country" items={items} selected="br" onSelect={onSelect} allowNone />)
+    await userEvent.click(screen.getByRole('radio', { name: /Brasil/ }))
+    expect(onSelect).toHaveBeenLastCalledWith(null)
+    onSelect.mockClear()
+    rerender(<CategoryTabs label="Country" items={items} selected="br" onSelect={onSelect} />)
+    await userEvent.click(screen.getByRole('radio', { name: /Brasil/ }))
+    expect(onSelect).not.toHaveBeenCalled()
+  })
+
+  it('moves between categories with arrow keys', async () => {
+    const onSelect = vi.fn()
+    render(<CategoryTabs label="Country" items={items} selected="br" onSelect={onSelect} />)
+    await userEvent.tab()
+    const radios = screen.getAllByRole('radio')
+    const start = radios.indexOf(document.activeElement as HTMLElement)
+    expect(start).toBeGreaterThanOrEqual(0)
+    await userEvent.keyboard('{ArrowRight}')
+    expect(radios[start + 1]).toHaveFocus()
+  })
+
+  it('CategoryLabel shows the same content in both sizes, named by the full name', () => {
+    render(
+      <>
+        <CategoryLabel code="PT" name="Portugal" marker={1} size="small" />
+        <CategoryLabel code="PT" name="Portugal" marker={1} />
+      </>,
+    )
+    const labels = document.querySelectorAll('.ty-category-label')
+    expect(labels[0]!.textContent).toBe(labels[1]!.textContent)
+    expect(labels[0]).toHaveAttribute('data-size', 'small')
+    expect(screen.getAllByText('Portugal')).toHaveLength(2)
+  })
+
+  it('scrolls with an edge fade on phones and outlines the selection in forced colours', () => {
+    const css = cssOf('components/category-tabs/CategoryTabs.css')
+    expect(css).toMatch(/overflow-x:\s*auto/)
+    expect(mediaBlock(css, /\(max-width:\s*639\.98px\)/)).toMatch(/mask-image/)
+    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}>
+            <CategoryTabs label={`Country ${scheme}`} items={items} selected="br" onSelect={() => {}} />
+            <CategoryLabel code="PT" name="Portugal" marker={1} />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('CategoryTabs in right-to-left (ar)', () => {
+  it('renders mirrored where directional and passes axe', async () => {
+    const { container } = renderRtl(<CategoryTabs label="الدولة" items={[{ key: 'eg', code: 'EG', name: 'مصر', marker: 1 }, { key: 'sa', code: 'SA', name: 'السعودية', marker: 3 }]} selected="eg" onSelect={() => {}} />)
+    expect(rtlDom.screen.getByRole('radio', { name: /مصر/ })).toBeInTheDocument()
+    await axeRtl(container)
+  })
+})

package/src/components/category-tabs/CategoryTabs.tsx

@@ -0,0 +1,94 @@
+import type { CSSProperties } from 'react'
+import { ToggleButton, ToggleButtonGroup, type Key } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+
+/** Index into the categorical palette (`--ty-categorical-1` … `-8`), §2.3. */
+export type CategoryMarker = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
+
+export interface CategoryItem {
+  key: string
+  /** Reported selection; defaults to `key`. */
+  value?: string
+  code: string
+  name: string
+  marker: CategoryMarker
+  disabled?: boolean
+}
+
+export interface CategoryTabsProps {
+  items: CategoryItem[]
+  selected: string | null
+  /** Receives the item's value (or key); null when `allowNone` clears the filter. */
+  onSelect: (value: string | null) => void
+  label: string
+  allowNone?: boolean
+  className?: string
+}
+
+const markerStyle = (marker: CategoryMarker) => ({ '--ty-category-marker': `var(--ty-categorical-${marker})` }) as CSSProperties
+
+/** Name without its leading code ("PT Portugal" → "Portugal"); the full name when nothing is left. */
+function nameWithoutCode(code: string, name: string): string {
+  const trimmed = name.trim()
+  const after = trimmed.slice(code.length)
+  // Only a whole leading code counts: "PT Portugal" yes, "Brasil" for "BR" no.
+  if (!trimmed.startsWith(code) || /^[\p{L}\p{N}]/u.test(after)) return trimmed
+  return after.replace(/^[\s:·,-]+/, '') || trimmed
+}
+
+const reportedValue = (item: CategoryItem) => item.value ?? item.key
+
+/**
+ * Filter chooser as a single-choice group of toggle buttons (APG Radio Group
+ * semantics through RAC ToggleButtonGroup), spec: wave-2/category-tabs.md.
+ */
+export function CategoryTabs({ items, selected, onSelect, label, allowNone = false, className }: CategoryTabsProps) {
+  const change = (keys: Set<Key>) => {
+    const next = [...keys][0]
+    if (next != null) {
+      if (String(next) !== selected) onSelect(String(next))
+    }
+    else if (allowNone) onSelect(null)
+  }
+  return (
+    // Activation stays inside the row: an enclosing clickable card never sees it.
+    <div className={cx('ty-category-tabs', className)} onClick={(e) => e.stopPropagation()} onKeyDown={(e) => e.stopPropagation()}>
+      <ToggleButtonGroup
+        aria-label={label}
+        className="ty-category-tabs__row"
+        selectionMode="single"
+        disallowEmptySelection={!allowNone}
+        selectedKeys={selected == null ? [] : [selected]}
+        onSelectionChange={change}
+      >
+        {items.map((item) => (
+          <ToggleButton key={item.key} id={reportedValue(item)} isDisabled={item.disabled} className="ty-category-tabs__item" style={markerStyle(item.marker)}>
+            <span className="ty-category-tabs__marker" aria-hidden="true" />
+            <strong className="ty-category-tabs__code">{item.code}</strong>{" "}
+            <span className="ty-category-tabs__name">{nameWithoutCode(item.code, item.name)}</span>
+          </ToggleButton>
+        ))}
+      </ToggleButtonGroup>
+    </div>
+  )
+}
+
+export interface CategoryLabelProps {
+  code: string
+  /** Full name; becomes the accessible name. */
+  name?: string
+  marker: CategoryMarker
+  size?: 'small' | 'medium'
+  className?: string
+}
+
+/** Static colour marker plus code. */
+export function CategoryLabel({ code, name, marker, size = 'medium', className }: CategoryLabelProps) {
+  return (
+    <span className={cx('ty-category-label', className)} data-size={size} style={markerStyle(marker)}>
+      <span className="ty-category-tabs__marker" aria-hidden="true" />
+      <span aria-hidden={name ? true : undefined}>{code}</span>
+      {name ? <span className="ty-visually-hidden">{name}</span> : null}
+    </span>
+  )
+}