@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/components/route-progress/RouteProgress.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useReducer } from 'react'
+import { useMessages } from '../../internal/provider'
+
+type Phase = 'idle' | 'waiting' | 'shown' | 'finishing'
+type Signal = 'start' | 'reveal' | 'settle' | 'done'
+
+// Transition table of the bar: waiting → shown after the delay; a navigation
+// that settles while still waiting never shows anything.
+const NEXT: Record<Phase, Partial<Record<Signal, Phase>>> = {
+  idle: { start: 'waiting' },
+  waiting: { reveal: 'shown', settle: 'idle' },
+  shown: { settle: 'finishing' },
+  finishing: { done: 'idle', start: 'shown' },
+}
+
+function step(phase: Phase, signal: Signal): Phase {
+  return NEXT[phase][signal] ?? phase
+}
+
+/** How long the completing bar lingers (matches --ty-dur-base). */
+const FINISH_MS = 240
+
+export interface RouteProgressProps {
+  /** A client-side navigation is in flight. */
+  pending: boolean
+  /** Navigations shorter than this (ms) show nothing. */
+  delay?: number
+  label?: string
+  className?: string
+}
+
+/** Thin top bar for pending client-side navigations (spec: wave-2/route-progress.md). */
+export function RouteProgress({ pending, delay = 200, label, className }: RouteProgressProps) {
+  const copy = useMessages().routeProgress
+  const text = label ?? copy.label
+  const [phase, send] = useReducer(step, 'idle')
+
+  useEffect(() => {
+    send(pending ? 'start' : 'settle')
+  }, [pending])
+
+  useEffect(() => {
+    if (phase === 'waiting') {
+      const t = setTimeout(() => send('reveal'), delay)
+      return () => clearTimeout(t)
+    }
+    if (phase === 'finishing') {
+      const t = setTimeout(() => send('done'), FINISH_MS)
+      return () => clearTimeout(t)
+    }
+    return undefined
+  }, [phase, delay])
+
+  const visible = phase === 'shown' || phase === 'finishing'
+  return (
+    <div className={className ? `ty-route-progress ${className}` : 'ty-route-progress'}>
+      {visible ? <div className="ty-route-progress__bar" data-phase={phase} aria-hidden="true" /> : null}
+      <span className="ty-visually-hidden" role="status" aria-live="polite">
+        {phase === 'shown' ? text : ''}
+      </span>
+    </div>
+  )
+}

package/src/components/ruled-grid/RuledGrid.css

@@ -0,0 +1,86 @@
+/* RuledGrid, RuledGridRow, RuledGridCell (spec: wave-4/ruled-grid.md; design direction §2.1, §2.5, §2.8). */
+@layer tympan.components {
+  .ty-ruled-grid {
+    --ty-ruled-mark: 9px;
+    position: relative;
+    display: flex;
+    flex-direction: column;
+  }
+  .ty-ruled-grid[data-outer] {
+    border-block: 1px solid var(--ty-line);
+  }
+
+  .ty-ruled-grid__row {
+    display: grid;
+    grid-template-columns: var(--ty-ruled-columns, repeat(auto-fit, minmax(12rem, 1fr)));
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .ty-ruled-grid__row + .ty-ruled-grid__row {
+    border-block-start: 1px solid var(--ty-line);
+  }
+
+  .ty-ruled-grid__cell {
+    position: relative;
+    min-inline-size: 0;
+    padding: var(--ty-space-5);
+  }
+  .ty-ruled-grid__cell + .ty-ruled-grid__cell {
+    border-inline-start: 1px solid var(--ty-line);
+  }
+  .ty-ruled-grid[data-outer] .ty-ruled-grid__cell:first-child {
+    border-inline-start: 1px solid var(--ty-line);
+  }
+  .ty-ruled-grid[data-outer] .ty-ruled-grid__cell:last-child {
+    border-inline-end: 1px solid var(--ty-line);
+  }
+
+  /* A small cross centred on each corner of a cell; shared corners overlap exactly. */
+  .ty-ruled-grid__mark {
+    position: absolute;
+    z-index: 1;
+    inline-size: var(--ty-ruled-mark);
+    block-size: var(--ty-ruled-mark);
+    background:
+      linear-gradient(var(--ty-line-strong), var(--ty-line-strong)) center / 100% 1px no-repeat,
+      linear-gradient(var(--ty-line-strong), var(--ty-line-strong)) center / 1px 100% no-repeat;
+    margin-block-start: calc(var(--ty-ruled-mark) / -2);
+    margin-inline-start: calc(var(--ty-ruled-mark) / -2);
+    pointer-events: none;
+  }
+  .ty-ruled-grid__mark[data-corner^='start'] {
+    inset-block-start: 0;
+  }
+  .ty-ruled-grid__mark[data-corner^='end'] {
+    inset-block-start: 100%;
+  }
+  .ty-ruled-grid__mark[data-corner$='-start'] {
+    inset-inline-start: 0;
+  }
+  .ty-ruled-grid__mark[data-corner$='-end'] {
+    inset-inline-start: 100%;
+  }
+
+  /* Phones: one column; vertical rules turn into horizontal rules between stacked cells. */
+  @media (max-width: 639.98px) {
+    .ty-ruled-grid__row {
+      grid-template-columns: minmax(0, 1fr);
+    }
+    .ty-ruled-grid__cell + .ty-ruled-grid__cell {
+      border-inline-start: 0;
+      border-block-start: 1px solid var(--ty-line);
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-ruled-grid[data-outer],
+    .ty-ruled-grid__row + .ty-ruled-grid__row,
+    .ty-ruled-grid__cell {
+      border-color: CanvasText;
+    }
+    .ty-ruled-grid__mark {
+      display: none;
+    }
+  }
+}

package/src/components/ruled-grid/RuledGrid.rtl.test.tsx

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { inRtl } from '../../../test/rtl-b'
+import { RuledGrid, RuledGridCell, RuledGridRow } from './RuledGrid'
+
+describe('RuledGrid in right-to-left locales', () => {
+  it('renders inside an Arabic (ar-EG) right-to-left subtree and passes axe', async () => {
+    const { container } = inRtl(<RuledGrid marks><RuledGridRow as="ul" columns={2}><RuledGridCell as="li">٩٤</RuledGridCell><RuledGridCell as="li">٥١٢</RuledGridCell></RuledGridRow></RuledGrid>, 'ar-EG')
+    expect(container.querySelector('[dir="rtl"]')).not.toBeNull()
+    expect(container.querySelectorAll('li')).toHaveLength(2)
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/ruled-grid/RuledGrid.test.tsx

@@ -0,0 +1,92 @@
+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 { ThemeScope } from '../../internal/ThemeScope'
+import { RuledGrid, RuledGridCell, RuledGridRow } from './RuledGrid'
+
+const css = () => cssOf('components/ruled-grid/RuledGrid.css')
+
+function TwoByThree({ marks = false }: { marks?: boolean }) {
+  return (
+    <RuledGrid marks={marks}>
+      {[0, 1].map((r) => (
+        <RuledGridRow key={r} columns={3}>
+          {[0, 1, 2].map((c) => (
+            <RuledGridCell key={c}>{`r${r}c${c}`}</RuledGridCell>
+          ))}
+        </RuledGridRow>
+      ))}
+    </RuledGrid>
+  )
+}
+
+describe('RuledGrid', () => {
+  it('separates rows and cells with rules and marks every intersection and corner', () => {
+    const { container } = render(<TwoByThree marks />)
+    expect(container.querySelectorAll('.ty-ruled-grid__row')).toHaveLength(2)
+    const cells = container.querySelectorAll('.ty-ruled-grid__cell')
+    for (const cell of cells) {
+      const corners = [...cell.querySelectorAll('.ty-ruled-grid__mark')].map((m) => m.getAttribute('data-corner'))
+      expect(corners).toEqual(['start-start', 'start-end', 'end-start', 'end-end'])
+    }
+    expect(container.querySelectorAll('.ty-ruled-grid__mark[aria-hidden="true"]')).toHaveLength(24)
+    expect(css()).toMatch(/\.ty-ruled-grid__row \+ \.ty-ruled-grid__row\s*\{[^}]*border-block-start:\s*1px solid var\(--ty-line\)/)
+    expect(css()).toMatch(/\.ty-ruled-grid__cell \+ \.ty-ruled-grid__cell\s*\{[^}]*border-inline-start:\s*1px solid var\(--ty-line\)/)
+    expect(container.querySelector('.ty-ruled-grid__row')).toHaveStyle({ '--ty-ruled-columns': 'repeat(3, minmax(0, 1fr))' })
+  })
+
+  it('draws no marks unless asked', () => {
+    const { container } = render(<TwoByThree />)
+    expect(container.querySelector('.ty-ruled-grid__mark')).toBeNull()
+  })
+
+  it('collapses to one column on phones with horizontal rules between stacked cells', () => {
+    const phone = mediaBlock(css(), /\(max-width:\s*639\.98px\)/)
+    expect(phone).toMatch(/\.ty-ruled-grid__row\s*\{[^}]*grid-template-columns:\s*minmax\(0,\s*1fr\)/)
+    expect(phone).toMatch(/border-block-start:\s*1px solid/)
+  })
+
+  it('offers list semantics through as', () => {
+    render(
+      <RuledGrid>
+        <RuledGridRow as="ul" columns={3}>
+          <RuledGridCell as="li">A</RuledGridCell>
+          <RuledGridCell as="li">B</RuledGridCell>
+          <RuledGridCell as="li">C</RuledGridCell>
+        </RuledGridRow>
+      </RuledGrid>,
+    )
+    expect(within(screen.getByRole('list')).getAllByRole('listitem')).toHaveLength(3)
+  })
+
+  it('keeps rules and drops marks in forced colours', () => {
+    const forced = mediaBlock(css(), /\(forced-colors:\s*active\)/)
+    expect(forced).toMatch(/border-color:\s*CanvasText/)
+    expect(forced).toMatch(/\.ty-ruled-grid__mark\s*\{[^}]*display:\s*none/)
+  })
+
+  it('omits outer rules when outerRules is false', () => {
+    const { container } = render(
+      <RuledGrid outerRules={false}>
+        <RuledGridRow>
+          <RuledGridCell>x</RuledGridCell>
+        </RuledGridRow>
+      </RuledGrid>,
+    )
+    expect(container.firstElementChild).not.toHaveAttribute('data-outer')
+  })
+
+  it('has no axe violations in light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((s) => (
+          <ThemeScope key={s} scheme={s}>
+            <TwoByThree marks />
+          </ThemeScope>
+        ))}
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/ruled-grid/RuledGrid.tsx

@@ -0,0 +1,73 @@
+import { createContext, useContext, type CSSProperties, type ReactNode } from 'react'
+import { cx } from '../../internal/cx'
+
+type RowTag = 'div' | 'ul' | 'ol'
+type CellTag = 'div' | 'li'
+
+export interface RuledGridProps {
+  /** Small crosses where rules meet, and at the outer corners. */
+  marks?: boolean
+  /** Rules along the outer edges too. */
+  outerRules?: boolean
+  children: ReactNode
+  className?: string
+}
+
+export interface RuledGridRowProps {
+  /** Column count or a full `grid-template-columns` value; auto-fit by default. */
+  columns?: number | string
+  /** `ul` / `ol` give the row list semantics (cells then use `li`). */
+  as?: RowTag
+  children: ReactNode
+  className?: string
+}
+
+export interface RuledGridCellProps {
+  as?: CellTag
+  children: ReactNode
+  className?: string
+}
+
+const MarksOn = createContext(false)
+const CORNERS = ['start-start', 'start-end', 'end-start', 'end-end'] as const
+
+/** Hairline-ruled layout grid for public pages (spec: wave-4/ruled-grid.md). */
+export function RuledGrid(props: RuledGridProps) {
+  const marks = props.marks === true
+  return (
+    <MarksOn.Provider value={marks}>
+      <div className={cx('ty-ruled-grid', props.className)} data-marks={marks || undefined} data-outer={props.outerRules === false ? undefined : true}>
+        {props.children}
+      </div>
+    </MarksOn.Provider>
+  )
+}
+
+function template(columns: RuledGridRowProps['columns']): string | undefined {
+  if (columns === undefined) return undefined
+  return typeof columns === 'number' ? `repeat(${columns}, minmax(0, 1fr))` : columns
+}
+
+/** One row of cells separated by vertical rules. */
+export function RuledGridRow(props: RuledGridRowProps) {
+  const Tag = props.as ?? 'div'
+  const cols = template(props.columns)
+  const style = cols ? ({ '--ty-ruled-columns': cols } as CSSProperties) : undefined
+  return (
+    <Tag className={cx('ty-ruled-grid__row', props.className)} style={style}>
+      {props.children}
+    </Tag>
+  )
+}
+
+/** One cell; draws its four corner marks when the grid asks for them (decorative). */
+export function RuledGridCell(props: RuledGridCellProps) {
+  const Tag = props.as ?? 'div'
+  const marks = useContext(MarksOn)
+  return (
+    <Tag className={cx('ty-ruled-grid__cell', props.className)}>
+      {marks && CORNERS.map((c) => <span key={c} className="ty-ruled-grid__mark" data-corner={c} aria-hidden="true" />)}
+      {props.children}
+    </Tag>
+  )
+}

package/src/components/safe-area-inset/SafeAreaInset.css

@@ -0,0 +1,65 @@
+/* SafeAreaInset (spec: wave-2/safe-area-inset.md; design direction §2.5, §2.6). */
+@layer tympan.components {
+  .ty-safe-area[data-layout='flex-column'] {
+    display: flex;
+    flex-direction: column;
+  }
+  .ty-safe-area[data-pad-top] {
+    padding-block-start: env(safe-area-inset-top, 0px);
+  }
+  .ty-safe-area[data-pad-bottom] {
+    padding-block-end: env(safe-area-inset-bottom, 0px);
+  }
+  .ty-safe-area[data-pad-left] {
+    /* physical: device safe-area insets are physical; the side is resolved in JS */
+    padding-left: env(safe-area-inset-left, 0px);
+  }
+  .ty-safe-area[data-pad-right] {
+    /* physical: device safe-area insets are physical; the side is resolved in JS */
+    padding-right: env(safe-area-inset-right, 0px);
+  }
+
+  .ty-safe-area-spacer[data-position='top'] {
+    block-size: env(safe-area-inset-top, 0px);
+  }
+  .ty-safe-area-spacer[data-position='bottom'] {
+    block-size: env(safe-area-inset-bottom, 0px);
+  }
+
+  .ty-safe-bottom-bar {
+    position: fixed;
+    inset-inline: 0;
+    inset-block-end: 0;
+    z-index: var(--ty-z-sticky);
+    padding-block-end: env(safe-area-inset-bottom, 0px);
+    padding-inline: max(var(--ty-space-4), env(safe-area-inset-left, 0px)) max(var(--ty-space-4), env(safe-area-inset-right, 0px));
+  }
+  /* Glass level 3 (§2.5). */
+  .ty-safe-bottom-bar[data-surface='glass'] {
+    border-block-start: 1px solid var(--ty-line);
+    background: var(--ty-surface-raised);
+    box-shadow: var(--ty-shadow-floating);
+    backdrop-filter: blur(var(--ty-glass-blur-floating));
+    -webkit-backdrop-filter: blur(var(--ty-glass-blur-floating));
+  }
+
+  /* Keep focused elements clear of the bar (WCAG 2.4.11). */
+  :root:has(.ty-safe-bottom-bar) {
+    scroll-padding-block-end: calc(var(--ty-safe-bottom-bar-size, 0px) + var(--ty-space-2));
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .ty-safe-bottom-bar[data-surface='glass'] {
+      background: var(--ty-surface-raised-solid);
+      backdrop-filter: none;
+      -webkit-backdrop-filter: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .ty-safe-bottom-bar {
+      border-block-start: 1px solid CanvasText;
+      background: Canvas;
+    }
+  }
+}

package/src/components/safe-area-inset/SafeAreaInset.rtl.test.tsx

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { inRtl } from '../../../test/rtl-b'
+import { SafeAreaInset } from './SafeAreaInset'
+
+describe('SafeAreaInset in right-to-left locales', () => {
+  it('maps the inline-start edge to the right side in RTL and passes axe', async () => {
+    const { container } = inRtl(
+      <SafeAreaInset edges={['start']}>
+        <p>محتوى</p>
+      </SafeAreaInset>,
+    )
+    const box = container.querySelector('.ty-safe-area')!
+    expect(box.hasAttribute('data-pad-right') || box.hasAttribute('data-pad-left')).toBe(true)
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/safe-area-inset/SafeAreaInset.test.tsx

@@ -0,0 +1,99 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { I18nProvider } from 'react-aria-components'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../../test/axe'
+import { cssOf, mediaBlock } from '../../../test/css'
+import { ThemeScope } from '../../internal/ThemeScope'
+import { SafeAreaBottomBar, SafeAreaInset, SafeAreaScreen, SafeAreaSpacer } from './SafeAreaInset'
+
+const css = cssOf('components/safe-area-inset/SafeAreaInset.css')
+
+describe('SafeAreaInset', () => {
+  it('pads exactly the chosen edges with the environment inset', () => {
+    render(<SafeAreaInset data-testid="box">x</SafeAreaInset>)
+    const box = screen.getByTestId('box')
+    expect(box).toHaveAttribute('data-pad-top')
+    expect(box).toHaveAttribute('data-pad-bottom')
+    expect(box).not.toHaveAttribute('data-pad-left')
+    expect(box).not.toHaveAttribute('data-pad-right')
+    expect(css).toMatch(/\[data-pad-top\]\s*\{[^}]*env\(safe-area-inset-top/)
+    expect(css).toMatch(/\[data-pad-bottom\]\s*\{[^}]*env\(safe-area-inset-bottom/)
+  })
+
+  it('pads the right side for the start edge in right-to-left', () => {
+    render(
+      <I18nProvider locale="ar-EG">
+        <SafeAreaInset edges={['start']} data-testid="box">
+          x
+        </SafeAreaInset>
+      </I18nProvider>,
+    )
+    expect(screen.getByTestId('box')).toHaveAttribute('data-pad-right')
+    expect(screen.getByTestId('box')).not.toHaveAttribute('data-pad-left')
+  })
+
+  it('pads all four edges in the full-screen view and sizes spacers by the inset', () => {
+    const { container } = render(
+      <>
+        <SafeAreaScreen data-testid="screen">x</SafeAreaScreen>
+        <SafeAreaSpacer position="bottom" />
+      </>,
+    )
+    const box = screen.getByTestId('screen')
+    for (const s of ['top', 'bottom', 'left', 'right']) expect(box).toHaveAttribute(`data-pad-${s}`)
+    expect(container.querySelector('.ty-safe-area-spacer')).toHaveAttribute('aria-hidden', 'true')
+    expect(css).toMatch(/spacer\[data-position='bottom'\]\s*\{[^}]*env\(safe-area-inset-bottom/)
+  })
+
+  it('falls back to zero when insets are unsupported (layout unchanged)', () => {
+    const envs = [...css.matchAll(/env\(safe-area-inset-[a-z]+(,\s*0px)?\)/g)]
+    expect(envs.length).toBeGreaterThan(0)
+    expect(envs.every((m) => m[1])).toBe(true)
+  })
+
+  it('scrolls a focused input under the bottom bar into view and reserves scroll padding', async () => {
+    const scrollBy = vi.fn()
+    window.scrollBy = scrollBy as typeof window.scrollBy
+    render(
+      <>
+        <input aria-label="Note" />
+        <SafeAreaBottomBar data-testid="bar">
+          <button type="button">Save</button>
+        </SafeAreaBottomBar>
+      </>,
+    )
+    const bar = screen.getByTestId('bar')
+    const input = screen.getByRole('textbox', { name: 'Note' })
+    bar.getBoundingClientRect = () => ({ top: 700, bottom: 760 }) as DOMRect
+    input.getBoundingClientRect = () => ({ top: 710, bottom: 750 }) as DOMRect
+    await userEvent.click(input)
+    expect(scrollBy).toHaveBeenCalledWith(expect.objectContaining({ top: 58 }))
+    expect(document.documentElement.style.getPropertyValue('--ty-safe-bottom-bar-size')).toMatch(/px$/)
+    expect(css).toMatch(/scroll-padding-block-end:\s*calc\(var\(--ty-safe-bottom-bar-size/)
+  })
+
+  it('is opaque under reduced transparency and bordered in forced colours', () => {
+    expect(mediaBlock(css, /\(prefers-reduced-transparency:\s*reduce\)/)).toMatch(/backdrop-filter:\s*none/)
+    expect(mediaBlock(css, /\(forced-colors:\s*active\)/)).toMatch(/CanvasText/)
+  })
+
+  it('has no axe violations, light and dark', async () => {
+    const { container } = render(
+      <>
+        {(['light', 'dark'] as const).map((scheme) => (
+          <ThemeScope key={scheme} scheme={scheme}>
+            <SafeAreaInset edges={['top', 'start']}>
+              <p>Content</p>
+            </SafeAreaInset>
+            <SafeAreaSpacer position="top" />
+          </ThemeScope>
+        ))}
+        <SafeAreaBottomBar>
+          <button type="button">Save</button>
+        </SafeAreaBottomBar>
+      </>,
+    )
+    await expectNoAxeViolations(container)
+  })
+})

package/src/components/safe-area-inset/SafeAreaInset.tsx

@@ -0,0 +1,101 @@
+// SafeAreaInset (spec: wave-2/safe-area-inset.md). Pads chosen edges by the
+// environment's safe-area insets. Logical edges (start/end) are resolved to
+// the physical side here, because env() insets are physical.
+import { useEffect, useRef, type HTMLAttributes, type ReactNode } from 'react'
+import { useLocale } from 'react-aria-components'
+import { cx } from '../../internal/cx'
+
+export type SafeEdge = 'top' | 'bottom' | 'start' | 'end'
+type Physical = 'top' | 'bottom' | 'left' | 'right'
+
+function useIsRtl(): boolean {
+  const aria = useLocale().direction === 'rtl'
+  const doc = typeof document !== 'undefined' && (document.documentElement.dir || document.dir) === 'rtl'
+  return aria || doc
+}
+
+function physicalSides(edges: readonly SafeEdge[], rtl: boolean): Set<Physical> {
+  const side = new Set<Physical>()
+  for (const e of edges) {
+    if (e === 'top' || e === 'bottom') side.add(e)
+    else side.add((e === 'start') !== rtl ? 'left' : 'right')
+  }
+  return side
+}
+
+function padAttributes(sides: Set<Physical>) {
+  const attrs: Record<string, true | undefined> = {}
+  for (const s of ['top', 'bottom', 'left', 'right'] as const) attrs[`data-pad-${s}`] = sides.has(s) || undefined
+  return attrs
+}
+
+export interface SafeAreaInsetProps extends HTMLAttributes<HTMLDivElement> {
+  edges?: SafeEdge[]
+  layout?: 'block' | 'flex-column'
+  children?: ReactNode
+}
+
+/** Wrapper that pads the selected edges by the device inset. */
+export function SafeAreaInset({ edges = ['top', 'bottom'], layout = 'block', className, children, ...rest }: SafeAreaInsetProps) {
+  const rtl = useIsRtl()
+  return (
+    <div {...rest} className={cx('ty-safe-area', className)} data-layout={layout} {...padAttributes(physicalSides(edges, rtl))}>
+      {children}
+    </div>
+  )
+}
+
+/** Full-screen view: all four edges padded. */
+export function SafeAreaScreen(props: Omit<SafeAreaInsetProps, 'edges'>) {
+  return <SafeAreaInset {...props} edges={['top', 'bottom', 'start', 'end']} />
+}
+
+/** Empty block as tall as the top or bottom inset. */
+export function SafeAreaSpacer({ position }: { position: 'top' | 'bottom' }) {
+  return <div className="ty-safe-area-spacer" data-position={position} aria-hidden="true" />
+}
+
+export interface SafeAreaBottomBarProps extends HTMLAttributes<HTMLDivElement> {
+  surface?: 'glass' | 'none'
+  children?: ReactNode
+}
+
+const BAR_SIZE = '--ty-safe-bottom-bar-size'
+
+/**
+ * Fixed bar at the bottom, padded by the bottom inset. While mounted it
+ * publishes its height so the page keeps focused elements above it (§2.6).
+ */
+export function SafeAreaBottomBar({ surface = 'glass', className, children, ...rest }: SafeAreaBottomBarProps) {
+  const bar = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const node = bar.current
+    if (!node || typeof document === 'undefined') return
+    const root = document.documentElement
+    const publish = () => root.style.setProperty(BAR_SIZE, `${node.offsetHeight}px`)
+    publish()
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(publish)
+    observer?.observe(node)
+
+    const keepVisible = (event: FocusEvent) => {
+      const target = event.target
+      if (!(target instanceof Element) || node.contains(target)) return
+      const barTop = node.getBoundingClientRect().top
+      const overlap = target.getBoundingClientRect().bottom - barTop
+      if (barTop > 0 && overlap > 0) window.scrollBy({ top: overlap + 8, behavior: 'auto' })
+    }
+    document.addEventListener('focusin', keepVisible)
+    return () => {
+      observer?.disconnect()
+      document.removeEventListener('focusin', keepVisible)
+      root.style.removeProperty(BAR_SIZE)
+    }
+  }, [])
+
+  return (
+    <div {...rest} ref={bar} className={cx('ty-safe-bottom-bar', className)} data-surface={surface}>
+      {children}
+    </div>
+  )
+}