@datatechsolutions/tympan 0.3.0 → 0.3.1

package/src/elements/skeleton/definition.ts

@@ -0,0 +1,91 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-skeleton>`: the Skeleton's single source (spec: wave-1/skeleton.md).
+ *
+ * Accessibility mirrors the React Skeleton and PageLoadingState: the blocks
+ * are decorative, so the anatomy hides them (`aria-hidden` on the content,
+ * which the React component carries on the root — here the root also holds
+ * the announcement, so the hidden subtree moves one level down). With
+ * `label`, the root is `aria-busy` and the label is announced once in a
+ * visually-hidden `role="status"`, the PageLoadingState pattern; without it
+ * the skeleton is purely decorative and the host announces the loading
+ * region itself.
+ *
+ * The anatomy covers the block level (a single shape, and the stacked-lines
+ * container with its first line). The composed `preset`s repeat per `count`
+ * and `columns`, which the declarative anatomy cannot express (no dynamic
+ * repetition), so the element composes them into the `ty-skeleton-preset`
+ * container on upgrade — self-rendering for the preset case, as the theme
+ * palette self-renders its composite. For the same reason the element (not
+ * the anatomy) repeats stacked lines beyond the first and resolves a custom
+ * CSS `width` to `data-width="custom"` plus an inline size. Preset, repeated
+ * and custom-width examples therefore stay out of `examples` (the parity
+ * renderers could not produce them).
+ */
+export const skeletonDefinition = {
+  tag: 'ty-skeleton',
+  name: 'TySkeleton',
+  kind: 'enhancing',
+  doc: 'Content-shaped placeholder, hidden from assistive technology; with `label`, one polite status announces the loading and the region is marked busy. Presets (stats, cards, section-heading, filters, analysis) are composed by the element on upgrade.',
+  props: {
+    shape: { type: 'enum', values: ['line', 'heading', 'circle', 'rect'], default: 'line', attribute: 'shape', doc: 'Block form: a text line, a heading line, a circle (avatar) or a rectangle (media, a chart).' },
+    width: { type: 'string', attribute: 'width', doc: 'Named width (`short`, `medium`, `long`, `full`) or any CSS length; full width when unset. A custom length resolves on upgrade (`data-width="custom"` and an inline size).' },
+    lines: { type: 'number', default: 1, attribute: 'lines', doc: 'Stacked text lines for the `line` and `heading` shapes, widths varied automatically (the last is short).' },
+    preset: { type: 'enum', values: ['stats', 'cards', 'section-heading', 'filters', 'analysis'], attribute: 'preset', doc: 'A composed skeleton instead of blocks; the element composes it on upgrade.' },
+    count: { type: 'number', attribute: 'count', doc: 'Repetitions of the preset (tiles, pills, items); the preset\'s default when unset.' },
+    columns: { type: 'number', attribute: 'columns', doc: 'Grid columns of a tiled preset (1 to 4); the preset\'s default when unset.' },
+    label: { type: 'string', attribute: 'label', doc: 'Announced once in a visually-hidden status while loading, the region marked `aria-busy` (the PageLoadingState pattern); unset, the skeleton is purely decorative and the host announces.' },
+  },
+  events: [],
+  anatomy: {
+    tag: 'span',
+    class: 'ty-skeleton-root',
+    attrs: {
+      'aria-busy': { prop: 'label', kind: 'bool' },
+    },
+    children: [
+      {
+        tag: 'span',
+        class: 'ty-skeleton-content',
+        attrs: { 'aria-hidden': { value: 'true' } },
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-skeleton-lines',
+            when: ['!preset', 'shape:line|shape:heading'],
+            children: [
+              { tag: 'span', class: 'ty-skeleton', attrs: { 'data-shape': { prop: 'shape' }, 'data-width': { prop: 'width' } } },
+            ],
+          },
+          {
+            tag: 'span',
+            class: 'ty-skeleton',
+            when: ['!preset', 'shape:circle|shape:rect'],
+            attrs: { 'data-shape': { prop: 'shape' }, 'data-width': { prop: 'width' } },
+          },
+          {
+            tag: 'span',
+            class: 'ty-skeleton-preset',
+            when: ['preset'],
+            attrs: { 'data-preset': { prop: 'preset' } },
+          },
+        ],
+      },
+      {
+        tag: 'span',
+        class: 'ty-visually-hidden',
+        attrs: { role: { value: 'status' } },
+        when: ['label'],
+        children: [{ text: { prop: 'label' } }],
+      },
+    ],
+  },
+  examples: [
+    { name: 'line', props: {}, slots: {} },
+    { name: 'heading-short', props: { shape: 'heading', width: 'short' }, slots: {} },
+    { name: 'circle', props: { shape: 'circle' }, slots: {} },
+    { name: 'rect-medium', props: { shape: 'rect', width: 'medium' }, slots: {} },
+    { name: 'announced', props: { label: 'Loading the catalogue' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/skeleton/element.ts

@@ -0,0 +1,175 @@
+import { TyElement } from '../base.ts'
+import { skeletonDefinition } from './definition.ts'
+
+const NAMED_WIDTHS = new Set(['short', 'medium', 'long', 'full'])
+/** Widths of stacked lines, the React Skeleton's `lineCycle`; the last line is always short. */
+const LINE_CYCLE = ['long', 'full', 'medium']
+
+function el(tag: string, className: string, attrs: Record<string, string> = {}): HTMLElement {
+  const node = document.createElement(tag)
+  node.className = className
+  for (const [name, value] of Object.entries(attrs)) node.setAttribute(name, value)
+  return node
+}
+
+const repetitions = (count: number | undefined, fallback: number): number => Math.max(0, Math.floor(count ?? fallback))
+
+/**
+ * `<ty-skeleton>`. All presentation: the stylesheet draws and pulses the
+ * blocks (stopping under reduced motion), and the anatomy — rendered by the
+ * host framework or built from plain HTML — carries the single block, the
+ * first stacked line and the announcement. The element adds what the
+ * declarative anatomy cannot: it repeats stacked lines beyond the first,
+ * resolves a custom CSS `width` (`data-width="custom"` plus an inline size)
+ * and composes the `preset`s (stats, cards, section-heading, filters,
+ * analysis), which repeat per `count`/`columns`.
+ *
+ * Composition fills containers the anatomy rendered empty or with one
+ * template block; the anatomy's own nodes are reused, never moved or
+ * replaced, so a framework-rendered tree keeps its nodes. Everything the
+ * element composes is inside the `aria-hidden` content: the only announced
+ * part is the optional visually-hidden status.
+ */
+export class TySkeletonElement extends TyElement {
+  static override definition = skeletonDefinition
+
+  override sync(): void {
+    super.sync()
+    const root = this.anatomyRoot()
+    if (!root) return
+    const props = this.props
+    const preset = props.preset ? String(props.preset) : undefined
+    if (preset) {
+      const container = root.querySelector('.ty-skeleton-preset')
+      // The container's children are all the element's; recompose freely.
+      if (container) container.replaceChildren(...this.#preset(preset, num(props.count), num(props.columns)))
+      return
+    }
+    const width = props.width ? String(props.width) : undefined
+    const shape = String(props.shape)
+    if (shape === 'line' || shape === 'heading') {
+      const container = root.querySelector('.ty-skeleton-lines')
+      if (!container) return
+      const lines = repetitions(num(props.lines), 1) || 1
+      if (lines > 1) this.#fillLines(container, lines)
+      else {
+        // One line: the anatomy's block stays (a framework owns it); drop
+        // only the lines the element added.
+        while (container.children.length > 1) container.lastElementChild!.remove()
+        const block = container.firstElementChild
+        if (block instanceof HTMLElement) this.#customWidth(block, width)
+      }
+    } else {
+      const block = root.querySelector('.ty-skeleton-content > .ty-skeleton')
+      if (block instanceof HTMLElement) this.#customWidth(block, width)
+    }
+  }
+
+  /** A custom CSS width on an anatomy-rendered block; named widths stay `data-width` only. */
+  #customWidth(block: HTMLElement, width: string | undefined): void {
+    if (width && !NAMED_WIDTHS.has(width)) {
+      block.setAttribute('data-width', 'custom')
+      block.style.inlineSize = width
+    } else if (block.style.inlineSize) {
+      block.style.inlineSize = ''
+    }
+  }
+
+  /** `lines` blocks in the container, reusing the anatomy's first block. */
+  #fillLines(container: Element, lines: number): void {
+    for (let i = 0; i < lines; i++) {
+      const width = i === lines - 1 ? 'short' : LINE_CYCLE[i % LINE_CYCLE.length]!
+      let block = container.children[i]
+      if (!(block instanceof HTMLElement) || !block.classList.contains('ty-skeleton')) {
+        block = el('span', 'ty-skeleton')
+        container.append(block)
+      }
+      block.setAttribute('data-shape', 'line')
+      block.setAttribute('data-width', width)
+      if (block instanceof HTMLElement) block.style.inlineSize = ''
+    }
+    while (container.children.length > lines) container.lastElementChild!.remove()
+  }
+
+  #lines(lines: number): HTMLElement {
+    const container = el('span', 'ty-skeleton-lines')
+    this.#fillLines(container, lines)
+    return container
+  }
+
+  /** A composed block (the React Skeleton's `Block`: full width when unset). */
+  #block(shape: string, width = 'full'): HTMLElement {
+    const block = el('span', 'ty-skeleton', { 'data-shape': shape })
+    if (NAMED_WIDTHS.has(width)) block.setAttribute('data-width', width)
+    else {
+      block.setAttribute('data-width', 'custom')
+      block.style.inlineSize = width
+    }
+    return block
+  }
+
+  #grid(kind: string, columns: number): HTMLElement {
+    const grid = el('span', 'ty-skeleton-grid', { 'data-preset': kind })
+    grid.style.setProperty('--ty-skeleton-columns', String(columns))
+    return grid
+  }
+
+  /** The preset's subtree, mirroring the React Skeleton's `Preset`. */
+  #preset(preset: string, count: number | undefined, columns: number | undefined): HTMLElement[] {
+    switch (preset) {
+      case 'stats': {
+        const n = repetitions(count, 4)
+        const grid = this.#grid('stats', columns ?? n)
+        for (let i = 0; i < n; i++) {
+          const tile = el('span', 'ty-skeleton-tile', { 'data-part': 'stat' })
+          tile.append(this.#block('circle'), this.#block('heading', 'medium'), this.#block('line', 'short'))
+          grid.append(tile)
+        }
+        return [grid]
+      }
+      case 'cards': {
+        const n = repetitions(count, 6)
+        const grid = this.#grid('cards', columns ?? 3)
+        for (let i = 0; i < n; i++) {
+          const tile = el('span', 'ty-skeleton-tile', { 'data-part': 'card' })
+          tile.append(this.#block('heading', 'long'), this.#lines(2), this.#block('line', 'short'))
+          grid.append(tile)
+        }
+        return [grid]
+      }
+      case 'section-heading': {
+        const row = el('span', 'ty-skeleton-row', { 'data-preset': 'section-heading' })
+        const lines = el('span', 'ty-skeleton-lines')
+        lines.append(this.#block('heading', 'medium'), this.#block('line', 'long'))
+        row.append(this.#block('circle'), lines)
+        return [row]
+      }
+      case 'filters': {
+        const n = repetitions(count, 5)
+        const row = el('span', 'ty-skeleton-row', { 'data-preset': 'filters' })
+        for (let i = 0; i < n; i++) row.append(el('span', 'ty-skeleton ty-skeleton--pill', { 'data-shape': 'pill' }))
+        return [row]
+      }
+      case 'analysis': {
+        const n = repetitions(count, 3)
+        const tile = el('span', 'ty-skeleton-tile', { 'data-preset': 'analysis' })
+        tile.append(this.#block('heading', 'medium'))
+        for (let i = 0; i < n; i++) {
+          const row = el('span', 'ty-skeleton-row', { 'data-part': 'item' })
+          row.append(this.#block('circle'), this.#lines(2))
+          tile.append(row)
+        }
+        return [tile]
+      }
+      default:
+        console.warn(`ty-skeleton: unknown preset "${preset}".`)
+        return []
+    }
+  }
+}
+
+function num(value: unknown): number | undefined {
+  if (value === undefined || value === false || value === '') return undefined
+  const n = Number(value)
+  return Number.isFinite(n) ? n : undefined
+}

package/src/elements/skip-link/definition.ts

@@ -0,0 +1,26 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-skip-link>`: the SkipLink's single source (spec: wave-1/skip-link.md). */
+export const skipLinkDefinition = {
+  tag: 'ty-skip-link',
+  name: 'TySkipLink',
+  kind: 'enhancing',
+  doc: 'First focusable element of the page: jumps past the navigation straight to the main content (WCAG 2.4.1 Bypass Blocks). A native anchor to the target\'s fragment, visually hidden until focused — never `display: none`, so it stays in the accessibility tree. On activation the element moves focus to the target (a temporary negative tabindex when the target is not natively focusable) and scrolls it clear of the sticky top bar.',
+  props: {
+    targetId: { type: 'string', default: 'main-content', attribute: 'target-id', doc: 'Id of the main content element; the anchor\'s href is its fragment (`#main-content`).' },
+    label: { type: 'string', default: 'Skip to main content', attribute: 'label', doc: 'Link text (the I18n adapter\'s default); translate through this attribute.' },
+  },
+  events: [{ type: 'click', kind: 'native', reactProp: 'onClick', doc: 'The native click of the anchor, before the focus move.' }],
+  anatomy: {
+    tag: 'a',
+    class: 'ty-skip-link',
+    // No href binding: the fragment (`#` + targetId) is derived, which the
+    // definition language cannot express; the element applies it on upgrade.
+    attrs: {},
+    children: [{ text: { prop: 'label' } }],
+  },
+  examples: [
+    { name: 'default', props: {}, slots: {} },
+    { name: 'translated', props: { targetId: 'conteudo', label: 'Ir para o conteúdo' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/skip-link/element.ts

@@ -0,0 +1,75 @@
+import { TyElement } from '../base.ts'
+import { skipLinkDefinition } from './definition.ts'
+
+/**
+ * `<ty-skip-link>`. A native anchor to the target's fragment, so keyboard
+ * activation and the accessibility tree are the platform's; the stylesheet
+ * hides it until focus (never `display: none`) and raises it above every
+ * layer when visible. The element adds what markup cannot (mirroring the
+ * React SkipLink's `focusSkipTarget`):
+ *
+ * - the derived `href` (`#` + `target-id`), applied after the first paint so
+ *   the upgrade never rewrites the rendered anatomy (see <ty-text-field>);
+ * - the activation behaviour: focus moves to the target — a temporary
+ *   negative tabindex when the target is not natively focusable, removed on
+ *   blur, so the next Tab continues from there — and the target scrolls to
+ *   the start, where the document's `scroll-padding-top` keeps it clear of
+ *   the sticky top bar (§2.6). The address bar's fragment is updated without
+ *   a history entry.
+ */
+export class TySkipLinkElement extends TyElement {
+  static override definition = skipLinkDefinition
+
+  /** False until the first paint: the derived href is not applied during the upgrade the parity renderers compare. */
+  #ready = false
+
+  override sync(): void {
+    super.sync()
+    if (this.#ready) this.#applyTarget()
+  }
+
+  protected override connected(): void {
+    this.addEventListener('click', this.#onClick)
+    requestAnimationFrame(() => {
+      if (!this.isConnected) return
+      this.#ready = true
+      this.#applyTarget()
+    })
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('click', this.#onClick)
+  }
+
+  /** The anchor points at the target's fragment. */
+  #applyTarget(): void {
+    const link = this.querySelector('a')
+    const href = `#${String(this.props.targetId)}`
+    if (link && link.getAttribute('href') !== href) link.setAttribute('href', href)
+  }
+
+  #onClick = (event: Event): void => {
+    const target = event.target as Element | null
+    const anchor = target && typeof target.closest === 'function' ? target.closest('a') : null
+    if (!anchor || !this.contains(anchor)) return
+    const targetId = String(this.props.targetId)
+    if (!focusSkipTarget(targetId)) return
+    event.preventDefault()
+    if (typeof history !== 'undefined' && history.replaceState) history.replaceState(history.state, '', `#${targetId}`)
+  }
+}
+
+/** Moves focus to `targetId`, making it programmatically focusable when needed (the React SkipLink's `focusSkipTarget`). */
+export function focusSkipTarget(targetId: string): boolean {
+  const target = document.getElementById(targetId)
+  if (!target) return false
+  const needsTabIndex = !target.hasAttribute('tabindex') && target.tabIndex < 0
+  if (needsTabIndex) {
+    target.setAttribute('tabindex', '-1')
+    target.addEventListener('blur', () => target.removeAttribute('tabindex'), { once: true })
+  }
+  target.focus({ preventScroll: true })
+  // scroll-padding-top on the document keeps the target clear of the sticky top bar (§2.6).
+  target.scrollIntoView?.({ block: 'start' })
+  return true
+}

package/src/elements/spinner/definition.ts

@@ -0,0 +1,52 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-spinner>`: the Spinner's single source (spec: wave-1/spinner.md). */
+export const spinnerDefinition = {
+  tag: 'ty-spinner',
+  name: 'TySpinner',
+  kind: 'enhancing',
+  doc: 'Indeterminate work indicator: an indeterminate progressbar named by `label`, drawn as a CSS ring or three pulsing dots (never announced). Under reduced motion the animation stops (the stylesheet) and the element reveals the label as text.',
+  props: {
+    label: { type: 'string', default: 'Loading', attribute: 'label', doc: 'Accessible name; the visible caption should say the same.' },
+    size: { type: 'enum', values: ['small', 'medium', 'large'], default: 'medium', attribute: 'size', doc: 'Diameter step (`small` follows the text size).' },
+    shape: { type: 'enum', values: ['ring', 'dots'], default: 'ring', attribute: 'shape', doc: 'The drawing: a border-arc ring or three pulsing dots.' },
+    tone: { type: 'enum', values: ['inherit', 'accent', 'on-accent', 'neutral'], default: 'inherit', attribute: 'tone', doc: 'Colour; `inherit` takes the current text colour.' },
+  },
+  events: [],
+  slots: {
+    default: { doc: 'The visible label next to the indicator (keep it the same text as `label`; it is decorative, the progressbar is named by `label`).' },
+  },
+  anatomy: {
+    tag: 'span',
+    class: 'ty-spinner',
+    attrs: {
+      role: { value: 'progressbar' },
+      'aria-label': { prop: 'label' },
+      'data-size': { prop: 'size' },
+      'data-shape': { prop: 'shape' },
+      'data-tone': { prop: 'tone' },
+    },
+    children: [
+      { tag: 'span', class: 'ty-spinner__ring', attrs: { 'aria-hidden': { value: 'true' } }, when: ['shape:ring'] },
+      {
+        tag: 'span',
+        class: 'ty-spinner__dots',
+        attrs: { 'aria-hidden': { value: 'true' } },
+        when: ['shape:dots'],
+        children: [
+          { tag: 'span', class: 'ty-spinner__dot' },
+          { tag: 'span', class: 'ty-spinner__dot' },
+          { tag: 'span', class: 'ty-spinner__dot' },
+        ],
+      },
+      { tag: 'span', class: 'ty-spinner__label', attrs: { 'aria-hidden': { value: 'true' } }, when: ['slot:default'], children: [{ slot: 'default' }] },
+    ],
+  },
+  examples: [
+    { name: 'ring', props: {}, slots: {} },
+    { name: 'dots-labelled', props: { shape: 'dots', label: 'Saving' }, slots: { default: 'Saving' } },
+    { name: 'large-accent', props: { size: 'large', tone: 'accent', label: 'Indexing' }, slots: {} },
+    { name: 'small-on-accent', props: { size: 'small', tone: 'on-accent', label: 'Uploading' }, slots: {} },
+    { name: 'dots-neutral', props: { shape: 'dots', tone: 'neutral' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/spinner/element.ts

@@ -0,0 +1,58 @@
+import { TyElement } from '../base.ts'
+import { spinnerDefinition } from './definition.ts'
+
+/**
+ * `<ty-spinner>`. All presentation: the host framework renders the anatomy
+ * (an indeterminate progressbar and its glyph) and the stylesheet draws and
+ * animates it. The element adds what markup cannot: it follows
+ * `prefers-reduced-motion`, reflecting `data-reduced-motion` on the anatomy
+ * root, and — a still indicator says nothing by itself — reveals the label
+ * as text while motion is reduced. For an anatomy it built itself (plain
+ * HTML) it adds the caption node; a framework-rendered one shows the label
+ * through the default slot, so the element never creates a node a framework
+ * owns.
+ */
+export class TySpinnerElement extends TyElement {
+  static override definition = spinnerDefinition
+
+  #media: MediaQueryList | null = null
+  #caption: HTMLElement | null = null
+
+  #onMedia = () => this.#reflectMotion()
+
+  protected override connected(): void {
+    this.#media = typeof matchMedia === 'undefined' ? null : matchMedia('(prefers-reduced-motion: reduce)')
+    this.#media?.addEventListener('change', this.#onMedia)
+    this.#reflectMotion()
+  }
+
+  protected override disconnected(): void {
+    this.#media?.removeEventListener('change', this.#onMedia)
+    this.#media = null
+  }
+
+  protected override changed(): void {
+    this.#reflectMotion()
+  }
+
+  #reflectMotion(): void {
+    const root = this.anatomyRoot()
+    if (!root) return
+    const reduced = this.#media?.matches ?? false
+    root.toggleAttribute('data-reduced-motion', reduced)
+    if (!this.owned) return
+    const labelled = root.querySelector(':scope > .ty-spinner__label') !== null
+    if (reduced && !labelled) {
+      if (!this.#caption?.isConnected) {
+        this.#caption = document.createElement('span')
+        this.#caption.className = 'ty-spinner__label'
+        this.#caption.setAttribute('aria-hidden', 'true')
+      }
+      this.#caption.textContent = String(this.props.label ?? '')
+      root.append(this.#caption)
+    } else if (!reduced && this.#caption) {
+      this.#caption.remove()
+      this.#caption = null
+    }
+  }
+}

package/src/elements/status-pill/definition.ts

@@ -0,0 +1,48 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-status-pill>`: the StatusPill's single source (spec: wave-1/status-pill.md). */
+export const statusPillDefinition = {
+  tag: 'ty-status-pill',
+  name: 'TyStatusPill',
+  kind: 'enhancing',
+  doc: 'Current state of an item as icon, word and semantic tone. Nothing interactive inside; a known `status` takes its tone and busy state from the element\'s status map unless `tone` overrides.',
+  props: {
+    status: { type: 'string', attribute: 'status', doc: 'The status key (`data-status`); the built-in map colours the common ones (`pending`, `approved`, `processing`, …) while `tone` is absent.' },
+    tone: { type: 'enum', values: ['neutral', 'info', 'success', 'warning', 'danger'], attribute: 'tone', doc: 'The semantic tone (`data-tone`); left out, the status map decides (server renderings pass it themselves).' },
+    size: { type: 'enum', values: ['small', 'regular'], default: 'regular', attribute: 'size', doc: 'Pill size.' },
+    busy: { type: 'boolean', attribute: 'busy', doc: 'In-progress: the icon spins (static under reduced motion).' },
+    announce: { type: 'boolean', attribute: 'announce', doc: 'Announce changes politely (`role="status"`); off by default, so tables of pills create no live regions.' },
+    label: { type: 'string', attribute: 'label', doc: 'Plain-HTML label text; the default slot (what frameworks render) wins, then the status map\'s label, then the status key.' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name of the pill (`aria-label`), e.g. "Status: Running" on an announced badge.' },
+    testId: { type: 'string', attribute: 'test-id', doc: 'Test hook on the pill (`data-testid`).' },
+  },
+  events: [],
+  slots: {
+    default: { doc: 'The status word.' },
+    icon: { doc: 'The status icon (decorative); spins while busy.' },
+  },
+  anatomy: {
+    tag: 'span',
+    class: 'ty-status',
+    attrs: {
+      role: { value: 'status', when: ['announce'] },
+      'aria-label': { prop: 'accessibleLabel' },
+      'data-tone': { prop: 'tone' },
+      'data-size': { prop: 'size' },
+      'data-busy': { prop: 'busy', kind: 'flag' },
+      'data-status': { prop: 'status' },
+      'data-testid': { prop: 'testId' },
+    },
+    children: [
+      { tag: 'span', class: 'ty-status__icon', attrs: { 'aria-hidden': { value: 'true' } }, when: ['slot:icon'], children: [{ slot: 'icon' }] },
+      { tag: 'span', class: 'ty-status__label', children: [{ slot: 'default' }] },
+    ],
+  },
+  examples: [
+    { name: 'success', props: { status: 'active', tone: 'success' }, slots: { default: 'Active', icon: '✓' } },
+    { name: 'busy-info', props: { status: 'processing', tone: 'info', busy: true }, slots: { default: 'Processing', icon: '↻' } },
+    { name: 'small-warning', props: { status: 'pending', tone: 'warning', size: 'small' }, slots: { default: 'Pending' } },
+    { name: 'announced-danger', props: { status: 'error', tone: 'danger', announce: true, accessibleLabel: 'Status: Error', testId: 'status-badge-error' }, slots: { default: 'Error' } },
+    { name: 'unknown-neutral', props: { status: 'archived' }, slots: { default: 'archived' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/status-pill/element.ts

@@ -0,0 +1,50 @@
+import { TyElement } from '../base.ts'
+import { statusPillDefinition } from './definition.ts'
+
+/**
+ * The tone, busy state and English default label of each common status —
+ * the React StatusPill's `builtInStatusMap` (whose labels come from the
+ * messages catalogue). The map is runtime behaviour: a server rendering
+ * (React SSR) passes `tone` and the label itself, and the map
+ * only fills in what the host left out.
+ */
+const STATUS_MAP: Record<string, { tone: string; busy?: boolean; label: string }> = {
+  pending: { tone: 'warning', label: 'Pending' },
+  approved: { tone: 'success', label: 'Approved' },
+  rejected: { tone: 'danger', label: 'Rejected' },
+  active: { tone: 'success', label: 'Active' },
+  inactive: { tone: 'neutral', label: 'Inactive' },
+  processing: { tone: 'info', busy: true, label: 'Processing' },
+  error: { tone: 'danger', label: 'Error' },
+  success: { tone: 'success', label: 'Success' },
+}
+
+/**
+ * `<ty-status-pill>`. Nothing interactive: the element applies the status
+ * map to what the host left out (an explicit `tone` or `busy` wins) and,
+ * built from plain HTML, fills an empty label from the `label` attribute,
+ * the map's label or the status key. A framework-rendered label is never
+ * touched — the framework owns it.
+ */
+export class TyStatusPillElement extends TyElement {
+  static override definition = statusPillDefinition
+
+  override sync(): void {
+    super.sync()
+    const root = this.anatomyRoot()
+    if (!root) return
+    const status = this.getAttribute('status') ?? ''
+    const entry = STATUS_MAP[status]
+    if (entry && !this.hasAttribute('tone')) root.setAttribute('data-tone', entry.tone)
+    if (entry?.busy) root.setAttribute('data-busy', '')
+    if (!entry && status && !this.hasAttribute('label')) {
+      console.warn(`ty-status-pill: unknown status "${status}"; showing it as a neutral pill.`)
+    }
+    if (this.owned) {
+      const label = root.querySelector('.ty-status__label')
+      if (label && !(label.textContent ?? '').trim()) {
+        label.textContent = this.getAttribute('label') || entry?.label || status
+      }
+    }
+  }
+}