@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/elements/theme-palette/definition.ts

@@ -0,0 +1,52 @@
+import type { ElementDefinition } from '../definition.ts'
+
+const text = (attribute: string, fallback: string, doc: string) => ({ type: 'string', attribute, default: fallback, doc }) as const
+
+/**
+ * `<ty-theme-palette>`: a command palette over every Tympan theme, the
+ * colour mode and the density. Choosing a row applies it to the document
+ * (`data-ty-theme` / `data-ty-mode` / `data-ty-density` on `<html>`) and
+ * stores it under `storage-key` in the format ThemeProvider and
+ * `themeInitScript` read, so React and non-React hosts share one choice.
+ */
+export const themePaletteDefinition = {
+  tag: 'ty-theme-palette',
+  name: 'TyThemePalette',
+  kind: 'self-rendering',
+  doc: 'Theme, mode and density picker in the command palette\'s look; a native <dialog> in the top layer while open.',
+  props: {
+    open: { type: 'boolean', attribute: 'open', doc: 'Shown (a modal dialog in the top layer).' },
+    apply: { type: 'boolean', attribute: 'apply', doc: 'Apply the stored choice (or the defaults) to the document as soon as the element connects, and again when a default changes.' },
+    storageKey: text('storage-key', 'ty-theme', 'localStorage key of the choice ({ theme, mode, density } JSON, as ThemeProvider stores it).'),
+    defaultTheme: text('default-theme', 'tympan', 'Theme when nothing is stored (a host passes its organization default here).'),
+    defaultMode: { type: 'enum', values: ['system', 'light', 'dark'], default: 'system', attribute: 'default-mode', doc: 'Mode when nothing is stored.' },
+    defaultDensity: { type: 'enum', values: ['compact', 'default', 'comfortable'], default: 'default', attribute: 'default-density', doc: 'Density when nothing is stored.' },
+    themes: { type: 'string', attribute: 'themes', doc: 'Comma-separated theme names to offer; all of them when empty.' },
+    printStylesheet: { type: 'string', attribute: 'print-stylesheet', doc: 'URL of print-themes.css, linked while a print theme is applied.' },
+    loadFonts: { type: 'boolean', attribute: 'load-fonts', doc: 'Link the font stylesheet a theme names (off: no request to a font host).' },
+    themeLabels: { type: 'string', attribute: 'theme-labels', doc: 'JSON object of translated theme names, by theme name.' },
+    label: text('label', 'Appearance', 'Accessible name of the dialog and the field.'),
+    placeholder: text('placeholder', 'Search themes, modes and densities', 'Field placeholder.'),
+    emptyLabel: text('empty-label', 'No matches', 'Shown when nothing matches.'),
+    resultsLabel: text('results-label', '{count} results', 'Announced result count; {count} is replaced.'),
+    groupPresets: text('group-presets', 'Themes', 'Heading of the built-in themes.'),
+    groupPrint: text('group-print', 'Print styles', 'Heading of the print themes.'),
+    groupMode: text('group-mode', 'Mode', 'Heading of the colour modes.'),
+    groupDensity: text('group-density', 'Density', 'Heading of the densities.'),
+    modeSystem: text('mode-system', 'System', 'Label of the system colour mode.'),
+    modeLight: text('mode-light', 'Light', 'Label of the light mode.'),
+    modeDark: text('mode-dark', 'Dark', 'Label of the dark mode.'),
+    densityCompact: text('density-compact', 'Compact', 'Label of the compact density.'),
+    densityDefault: text('density-default', 'Default', 'Label of the default density.'),
+    densityComfortable: text('density-comfortable', 'Comfortable', 'Label of the comfortable density.'),
+    currentLabel: text('current-label', 'Current', 'Marks the row in use.'),
+    hintNavigate: text('hint-navigate', 'move', 'Footer hint beside ↑↓.'),
+    hintSelect: text('hint-select', 'choose', 'Footer hint beside ↵.'),
+    hintClose: text('hint-close', 'close', 'Footer hint beside esc.'),
+  },
+  events: [
+    { type: 'ty-theme-change', kind: 'custom', detail: { theme: 'string', mode: 'string', density: 'string' }, reactProp: 'onThemeChange', doc: 'A row was chosen and applied; the detail is the whole appearance.' },
+    { type: 'ty-close', kind: 'custom', reactProp: 'onClose', doc: 'The palette asks to close (Escape, a press outside, or after a choice). The element closes itself too.' },
+  ],
+  examples: [],
+} as const satisfies ElementDefinition

package/src/elements/theme-palette/element.ts

@@ -0,0 +1,372 @@
+import { TyElement } from '../base.ts'
+import { themePaletteDefinition } from './definition.ts'
+import { choose, DENSITIES, MODES, readStored, resolve, sections, THEMES, writeStored, type Appearance, type Density, type Mode, type Row, type RowLabels } from './model.ts'
+
+const PRINT_LINK_ID = 'ty-print-themes'
+const FONT_LINK_ID = 'ty-theme-fonts'
+const SVG = 'http://www.w3.org/2000/svg'
+
+function storage(): Storage | undefined {
+  try {
+    return window.localStorage
+  } catch {
+    return undefined
+  }
+}
+
+function el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  if (className) node.className = className
+  for (const [name, value] of Object.entries(attrs)) node.setAttribute(name, value)
+  return node
+}
+
+function searchIcon(): SVGSVGElement {
+  const svg = document.createElementNS(SVG, 'svg')
+  svg.setAttribute('class', 'ty-palette__search-icon')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '2')
+  svg.setAttribute('aria-hidden', 'true')
+  const circle = document.createElementNS(SVG, 'circle')
+  circle.setAttribute('cx', '11')
+  circle.setAttribute('cy', '11')
+  circle.setAttribute('r', '7')
+  const line = document.createElementNS(SVG, 'path')
+  line.setAttribute('d', 'm20 20-3.5-3.5')
+  svg.append(circle, line)
+  return svg
+}
+
+/**
+ * `<ty-theme-palette>`. While `open`, a native `<dialog>` (top layer: no
+ * ancestor can clip it, the rest of the page is inert, Escape cancels) holds
+ * the palette: a combobox field over a listbox of themes, modes and
+ * densities, navigated with the arrow keys, Home, End, Enter and Escape.
+ * Choosing applies and stores the appearance and closes.
+ */
+export class TyThemePaletteElement extends TyElement {
+  static override definition = themePaletteDefinition
+
+  #dialog: HTMLDialogElement | null = null
+  #input: HTMLInputElement | null = null
+  #list: HTMLElement | null = null
+  #status: HTMLElement | null = null
+  #empty: HTMLElement | null = null
+  #query = ''
+  #cursor = 0
+  #rows: Row[] = []
+  #appliedDefaults = ''
+
+  /** The appearance in use: the stored choice over the defaults. */
+  get appearance(): Appearance {
+    const p = this.props
+    return resolve(readStored(storage(), String(p.storageKey)), {
+      theme: String(p.defaultTheme),
+      mode: String(p.defaultMode) as Mode,
+      density: String(p.defaultDensity) as Density,
+    })
+  }
+
+  /**
+   * Store `choice` over what is stored (fields left out keep following
+   * the defaults, so an organization default still reaches a person who
+   * only picked a mode), apply the result and announce it.
+   */
+  select(choice: Partial<Appearance>): void {
+    const key = String(this.props.storageKey)
+    const stored = { ...readStored(storage(), key), ...choice }
+    writeStored(storage(), key, stored)
+    const appearance = this.appearance
+    this.#applyToDocument(appearance)
+    this.emit('ty-theme-change', { ...appearance })
+  }
+
+  protected override connected(): void {
+    this.#reconcile()
+  }
+
+  protected override disconnected(): void {
+    this.#close(false)
+  }
+
+  protected override changed(): void {
+    if (this.isConnected) this.#reconcile()
+  }
+
+  #reconcile(): void {
+    const p = this.props
+    if (p.apply) {
+      const defaults = `${p.defaultTheme}|${p.defaultMode}|${p.defaultDensity}|${p.storageKey}`
+      if (defaults !== this.#appliedDefaults) {
+        this.#appliedDefaults = defaults
+        this.#applyToDocument(this.appearance)
+      }
+    }
+    if (p.open && !this.#dialog) this.#open()
+    else if (!p.open && this.#dialog) this.#close(false)
+    else if (this.#dialog) this.#renderRows()
+  }
+
+  #applyToDocument(appearance: Appearance): void {
+    const root = document.documentElement
+    root.setAttribute('data-ty-theme', appearance.theme)
+    root.setAttribute('data-ty-mode', appearance.mode)
+    root.setAttribute('data-ty-density', appearance.density)
+    const entry = THEMES.find((t) => t.name === appearance.theme)
+    const href = this.getAttribute('print-stylesheet')
+    this.#link(PRINT_LINK_ID, entry?.kind === 'print' && href ? href : null)
+    this.#link(FONT_LINK_ID, this.hasAttribute('load-fonts') ? (entry?.fontsUrl ?? null) : null)
+  }
+
+  #link(id: string, href: string | null): void {
+    const existing = document.getElementById(id) as HTMLLinkElement | null
+    if (!href) {
+      existing?.remove()
+      return
+    }
+    if (existing) {
+      if (existing.getAttribute('href') !== href) existing.setAttribute('href', href)
+      return
+    }
+    const link = el('link', undefined, { id, rel: 'stylesheet', href })
+    document.head.append(link)
+  }
+
+  #labels(): RowLabels {
+    const p = this.props
+    let themes: Record<string, string> = {}
+    try {
+      themes = JSON.parse(String(p.themeLabels ?? '{}')) as Record<string, string>
+    } catch {
+      themes = {}
+    }
+    return {
+      groups: { preset: String(p.groupPresets), print: String(p.groupPrint), mode: String(p.groupMode), density: String(p.groupDensity) },
+      modes: { system: String(p.modeSystem), light: String(p.modeLight), dark: String(p.modeDark) },
+      densities: { compact: String(p.densityCompact), default: String(p.densityDefault), comfortable: String(p.densityComfortable) },
+      themes,
+    }
+  }
+
+  #offered(): ReadonlySet<string> | undefined {
+    const list = String(this.props.themes ?? '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean)
+    return list.length ? new Set(list) : undefined
+  }
+
+  #open(): void {
+    const p = this.props
+    const id = this.instanceId
+    const dialog = el('dialog', 'ty-palette', { 'aria-label': String(p.label), 'data-ty-palette': '' })
+    const body = el('div', 'ty-palette__dialog')
+    const field = el('div', 'ty-palette__field')
+    const input = el('input', 'ty-palette__input', {
+      role: 'combobox',
+      'aria-label': String(p.label),
+      'aria-autocomplete': 'list',
+      'aria-controls': `${id}-list`,
+      placeholder: String(p.placeholder),
+      autocomplete: 'off',
+      spellcheck: 'false',
+      type: 'text',
+    })
+    field.append(searchIcon(), input)
+    const main = el('div', 'ty-palette__main')
+    const results = el('div', 'ty-palette__results')
+    const list = el('div', 'ty-palette__list', { id: `${id}-list`, role: 'listbox', 'aria-label': String(p.label) })
+    const empty = el('p', 'ty-palette__empty')
+    empty.hidden = true
+    results.append(list, empty)
+    main.append(results)
+    const footer = el('div', 'ty-palette__footer', { 'aria-hidden': 'true' })
+    for (const [keys, hint] of [
+      ['↑↓', p.hintNavigate],
+      ['↵', p.hintSelect],
+      ['esc', p.hintClose],
+    ] as const) {
+      const span = el('span')
+      const kbd = el('kbd', 'ty-palette__kbd')
+      kbd.textContent = keys
+      span.append(kbd, ` ${String(hint)}`)
+      footer.append(span)
+    }
+    const status = el('span', 'ty-visually-hidden', { role: 'status' })
+    body.append(field, main, footer, status)
+    dialog.append(body)
+
+    input.addEventListener('input', () => {
+      this.#query = input.value
+      this.#cursor = 0
+      this.#renderRows()
+    })
+    input.addEventListener('keydown', (event) => this.#onKey(event))
+    dialog.addEventListener('cancel', (event) => {
+      event.preventDefault()
+      this.#close(true)
+    })
+    // A press on the dialog box itself (outside the palette's content) is a press outside.
+    dialog.addEventListener('click', (event) => {
+      if (event.target === dialog) this.#close(true)
+    })
+
+    this.#dialog = dialog
+    this.#input = input
+    this.#list = list
+    this.#empty = empty
+    this.#status = status
+    this.#query = ''
+    this.#cursor = 0
+    this.replaceChildren(dialog)
+    this.#renderRows()
+    if (typeof dialog.showModal === 'function') dialog.showModal()
+    else dialog.setAttribute('open', '')
+    input.focus()
+  }
+
+  #close(announce: boolean): void {
+    const dialog = this.#dialog
+    if (!dialog) return
+    this.#dialog = null
+    this.#input = null
+    this.#list = null
+    if (dialog.open && typeof dialog.close === 'function') dialog.close()
+    dialog.remove()
+    if (this.hasAttribute('open')) this.removeAttribute('open')
+    if (announce) this.emit('ty-close')
+  }
+
+  #onKey(event: KeyboardEvent): void {
+    const count = this.#rows.length
+    const step = (to: number) => {
+      event.preventDefault()
+      if (count) {
+        this.#cursor = (to + count) % count
+        this.#renderRows()
+      }
+    }
+    switch (event.key) {
+      case 'ArrowDown':
+        return step(this.#cursor + 1)
+      case 'ArrowUp':
+        return step(this.#cursor - 1)
+      case 'Home':
+        return step(0)
+      case 'End':
+        return step(count - 1)
+      case 'Enter': {
+        event.preventDefault()
+        const row = this.#rows[this.#cursor]
+        if (row) this.#run(row)
+        return
+      }
+      case 'Escape':
+        event.preventDefault()
+        event.stopPropagation()
+        if (this.#query) {
+          this.#query = ''
+          if (this.#input) this.#input.value = ''
+          this.#cursor = 0
+          this.#renderRows()
+        } else this.#close(true)
+        return
+    }
+  }
+
+  #run(row: Row): void {
+    this.select(choose(row))
+    this.#close(true)
+  }
+
+  #renderRows(): void {
+    const list = this.#list
+    const input = this.#input
+    if (!list || !input) return
+    const p = this.props
+    const id = this.instanceId
+    const current = this.appearance
+    const found = sections(this.#query, current, this.#labels(), this.#offered())
+    this.#rows = found.flatMap((s) => s.rows)
+    if (this.#cursor >= this.#rows.length) this.#cursor = Math.max(0, this.#rows.length - 1)
+    const active = this.#rows[this.#cursor]
+
+    list.replaceChildren(
+      ...found.map((section) => {
+        const group = el('div', 'ty-palette__group', { role: 'group', 'aria-labelledby': `${id}-${section.group}` })
+        const heading = el('div', 'ty-palette__heading', { id: `${id}-${section.group}`, role: 'presentation' })
+        heading.textContent = section.heading
+        group.append(heading)
+        for (const row of section.rows) {
+          const on = row === active
+          const option = el('div', 'ty-palette__option', {
+            id: `${id}-${row.key.replace(':', '-')}`,
+            role: 'option',
+            'aria-selected': String(on),
+            'data-kind': row.group,
+          })
+          if (on) option.setAttribute('data-highlighted', '')
+          if (row.current) option.setAttribute('data-current', '')
+          const icon = el('span', 'ty-palette__icon', { 'aria-hidden': 'true' })
+          const swatch = el('span', 'ty-palette__swatch')
+          if (row.group === 'preset' || row.group === 'print') swatch.setAttribute('data-ty-theme', row.value)
+          if (row.group === 'mode' && row.value !== 'system') swatch.setAttribute('data-ty-mode', row.value)
+          if (row.group === 'density') swatch.setAttribute('data-density-swatch', row.value)
+          icon.append(swatch)
+          const text = el('span', 'ty-palette__text')
+          const label = el('span', 'ty-palette__label')
+          appendMarked(label, row.label, row.marks)
+          text.append(label)
+          option.append(icon, text)
+          if (row.current) {
+            const hint = el('span', 'ty-palette__hint')
+            hint.textContent = String(p.currentLabel)
+            option.append(hint)
+          } else if (row.hint && row.hint !== row.label) {
+            const hint = el('span', 'ty-palette__hint')
+            hint.textContent = row.hint
+            option.append(hint)
+          }
+          option.addEventListener('pointermove', () => {
+            const index = this.#rows.indexOf(row)
+            if (index !== this.#cursor) {
+              this.#cursor = index
+              this.#renderRows()
+            }
+          })
+          option.addEventListener('mousedown', (event) => event.preventDefault())
+          option.addEventListener('click', () => this.#run(row))
+          group.append(option)
+        }
+        return group
+      }),
+    )
+    input.setAttribute('aria-expanded', String(this.#rows.length > 0))
+    if (active) input.setAttribute('aria-activedescendant', `${id}-${active.key.replace(':', '-')}`)
+    else input.removeAttribute('aria-activedescendant')
+    if (this.#empty) {
+      this.#empty.hidden = this.#rows.length > 0
+      this.#empty.textContent = String(p.emptyLabel)
+    }
+    if (this.#status) this.#status.textContent = this.#query.trim() ? String(p.resultsLabel).replace('{count}', String(this.#rows.length)) : ''
+    if (active) document.getElementById(`${id}-${active.key.replace(':', '-')}`)?.scrollIntoView?.({ block: 'nearest' })
+  }
+}
+
+function appendMarked(target: HTMLElement, text: string, marks: number[]): void {
+  if (!marks.length) {
+    target.textContent = text
+    return
+  }
+  const first = marks[0]!
+  const last = marks[marks.length - 1]! + 1
+  if (first > 0) target.append(text.slice(0, first))
+  const mark = el('mark', 'ty-palette__mark')
+  mark.textContent = text.slice(first, last)
+  target.append(mark)
+  if (last < text.length) target.append(text.slice(last))
+}
+
+export { MODES, DENSITIES }

package/src/elements/theme-palette/model.ts

@@ -0,0 +1,140 @@
+// The theme palette's logic without the DOM: the catalogue, the stored
+// choice, filtering and the rows. Shared by the element and its tests.
+
+import catalogue from '@datatechsolutions/tympan-tokens/themes.json'
+
+export type Mode = 'system' | 'light' | 'dark'
+export type Density = 'compact' | 'default' | 'comfortable'
+export const MODES: readonly Mode[] = ['system', 'light', 'dark']
+export const DENSITIES: readonly Density[] = ['compact', 'default', 'comfortable']
+
+export interface ThemeEntry {
+  name: string
+  label: string
+  kind: 'preset' | 'print'
+  fontsUrl: string | null
+}
+
+export const THEMES: readonly ThemeEntry[] = catalogue as ThemeEntry[]
+
+export interface Appearance {
+  theme: string
+  mode: Mode
+  density: Density
+}
+
+const isMode = (v: unknown): v is Mode => MODES.includes(v as Mode)
+const isDensity = (v: unknown): v is Density => DENSITIES.includes(v as Density)
+export const isTheme = (v: unknown): v is string => THEMES.some((t) => t.name === v)
+
+/** The stored choice (the ThemeProvider format); fields that are not valid are dropped. */
+export function readStored(storage: Pick<Storage, 'getItem'> | undefined, key: string): Partial<Appearance> {
+  try {
+    const raw = JSON.parse(storage?.getItem(key) ?? '{}') as Record<string, unknown>
+    const out: Partial<Appearance> = {}
+    if (isTheme(raw.theme)) out.theme = raw.theme
+    if (isMode(raw.mode)) out.mode = raw.mode
+    if (isDensity(raw.density)) out.density = raw.density
+    return out
+  } catch {
+    return {}
+  }
+}
+
+export function writeStored(storage: Pick<Storage, 'setItem'> | undefined, key: string, value: Partial<Appearance>): void {
+  try {
+    storage?.setItem(key, JSON.stringify(value))
+  } catch {
+    // Storage full or blocked: the choice still applies for this page.
+  }
+}
+
+export function resolve(stored: Partial<Appearance>, defaults: Appearance): Appearance {
+  return {
+    theme: stored.theme ?? (isTheme(defaults.theme) ? defaults.theme : 'tympan'),
+    mode: stored.mode ?? defaults.mode,
+    density: stored.density ?? defaults.density,
+  }
+}
+
+export type RowGroup = 'preset' | 'print' | 'mode' | 'density'
+
+export interface Row {
+  key: string
+  group: RowGroup
+  value: string
+  label: string
+  /** The theme's name (a code), shown beside a translated label. */
+  hint?: string
+  current: boolean
+  /** Character positions of the query in the label. */
+  marks: number[]
+}
+
+export interface Section {
+  group: RowGroup
+  heading: string
+  rows: Row[]
+}
+
+export interface RowLabels {
+  groups: Record<RowGroup, string>
+  modes: Record<Mode, string>
+  densities: Record<Density, string>
+  themes: Record<string, string>
+}
+
+const fold = (s: string) => s.toLocaleLowerCase().normalize('NFD').replace(/\p{Diacritic}/gu, '')
+
+/** Positions of `query` in `label` (case and accent blind); `null` when it is not there. */
+export function match(label: string, query: string, alsoIn: string[] = []): number[] | null {
+  const q = fold(query.trim())
+  if (!q) return []
+  const at = fold(label).indexOf(q)
+  if (at >= 0) return Array.from({ length: q.length }, (_, i) => at + i)
+  return alsoIn.some((extra) => fold(extra).includes(q)) ? [] : null
+}
+
+/** The sections for `query`, in menu order; empty sections are left out. */
+export function sections(query: string, current: Appearance, labels: RowLabels, offered?: ReadonlySet<string>): Section[] {
+  const out: Section[] = []
+  const push = (group: RowGroup, rows: Row[]) => {
+    if (rows.length) out.push({ group, heading: labels.groups[group], rows })
+  }
+  const themeRows = (kind: 'preset' | 'print'): Row[] =>
+    THEMES.filter((t) => t.kind === kind && (!offered || offered.has(t.name))).flatMap((t) => {
+      const label = labels.themes[t.name] ?? t.label
+      const marks = match(label, query, [t.name])
+      return marks ? [{ key: `theme:${t.name}`, group: kind, value: t.name, label, hint: t.name, current: t.name === current.theme, marks }] : []
+    })
+  push('preset', themeRows('preset'))
+  push('print', themeRows('print'))
+  push(
+    'mode',
+    MODES.flatMap((m) => {
+      const marks = match(labels.modes[m], query, [m])
+      return marks ? [{ key: `mode:${m}`, group: 'mode' as const, value: m, label: labels.modes[m], current: m === current.mode, marks }] : []
+    }),
+  )
+  push(
+    'density',
+    DENSITIES.flatMap((d) => {
+      const marks = match(labels.densities[d], query, [d])
+      return marks ? [{ key: `density:${d}`, group: 'density' as const, value: d, label: labels.densities[d], current: d === current.density, marks }] : []
+    }),
+  )
+  return out
+}
+
+/** The one field choosing `row` sets. */
+export function choose(row: Row): Partial<Appearance> {
+  switch (row.group) {
+    case 'preset':
+    case 'print':
+      return { theme: row.value }
+    case 'mode':
+      return { mode: row.value as Mode }
+    case 'density':
+      return { density: row.value as Density }
+  }
+}

package/src/elements/toast/definition.ts

@@ -0,0 +1,42 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-toast>`: the Toast's single source (spec: wave-1/toast.md).
+ *
+ * The element is the spec's provider and region in one: it owns the queue
+ * and the history and renders the fixed region itself, so it is
+ * self-rendering (like the theme palette) with no anatomy and no examples —
+ * the queue is runtime data no renderer can express up front. Toasts arrive
+ * through the element's imperative API, the hook's twin:
+ * `show({ tone, title, message, action, duration, id })`, the shortcuts
+ * `success` / `error` / `warning` / `info(title, options)`, `dismiss(id)`
+ * and the `history` getter. The generated React wrapper forwards the host
+ * element as its ref, so React consumers call the same API through it.
+ *
+ * The region is a landmark (a labelled `section`) holding two live-region
+ * lists, not nested: errors in an assertive `role="alert"` list, every other
+ * tone in a polite `role="status"` list. A toast never takes focus when
+ * shown; F6 moves focus into the region and back out, Escape inside a
+ * focused toast dismisses it, and when the last toast closes while focused,
+ * focus returns to where it was. The auto-dismiss timer pauses while the
+ * pointer is over the region, focus is inside it or the window is hidden.
+ * Errors and toasts with an action are persistent by default (WCAG 2.2.1).
+ */
+export const toastDefinition = {
+  tag: 'ty-toast',
+  name: 'TyToast',
+  kind: 'self-rendering',
+  doc: 'Brief, non-blocking confirmation or warning after an action, shown in a fixed landmark region with one live-region politeness per tone (errors assertive, the rest polite). The element owns the queue and the history; toasts arrive through its imperative API (`show`, `success`/`error`/`warning`/`info`, `dismiss`, `history`), reachable through the host ref. Auto-dismiss pauses on hover, focus and a hidden window; errors and toasts with an action stay until dismissed.',
+  props: {
+    placement: { type: 'enum', values: ['top-end', 'top-center', 'bottom-center'], default: 'top-end', attribute: 'placement', doc: 'Region position (`data-placement`); `bottom-center` is recommended below 640 px.' },
+    maxVisible: { type: 'number', default: 3, attribute: 'max-visible', doc: 'Toasts shown at once; the rest wait in the queue and appear as earlier ones dismiss.' },
+    historyLimit: { type: 'number', default: 50, attribute: 'history-limit', doc: 'How many past toasts the history keeps (newest first); feeds the notification history.' },
+    regionLabel: { type: 'string', default: 'Notifications', attribute: 'region-label', doc: 'Accessible name of the region landmark (the I18nAdapter\'s toast.region in React).' },
+    dismissLabel: { type: 'string', default: 'Dismiss notification', attribute: 'dismiss-label', doc: 'Accessible name of each toast\'s dismiss button.' },
+  },
+  events: [
+    { type: 'ty-toast-dismiss', kind: 'custom', detail: { id: 'string' }, reactProp: 'onDismiss', doc: 'A toast was dismissed — timeout, dismiss button, Escape, swipe, its action, or a `dismiss(id)` call; the detail carries its id (the spec\'s `onDismiss`).' },
+    { type: 'ty-toast-action', kind: 'custom', detail: { id: 'string' }, reactProp: 'onAction', doc: 'A toast\'s action was pressed; its `onPress` ran too and the toast dismissed itself. Lets hosts that cannot pass a callback still react to the action.' },
+  ],
+  examples: [],
+} as const satisfies ElementDefinition