@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/surface/definition.ts

@@ -0,0 +1,93 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-surface>`: the Surface's single source (spec: wave-1/surface.md). */
+export const surfaceDefinition = {
+  tag: 'ty-surface',
+  name: 'TySurface',
+  kind: 'enhancing',
+  doc: 'Bounded container at a chosen elevation. A titled surface is a region named by its title; a pressable one forwards presses anywhere on it to the single primary control in the title (a link with `href`, a button otherwise).',
+  props: {
+    elevation: { type: 'enum', values: ['sheet', 'raised', 'floating', 'flat'], default: 'sheet', attribute: 'elevation', doc: 'Level 1 (sheet glass), 2 (raised card), 3 (floating) or 0 (flat).' },
+    padding: { type: 'enum', values: ['none', 'regular', 'roomy'], default: 'regular', attribute: 'padding', doc: 'Internal padding step.' },
+    titleLevel: { type: 'enum', values: ['h2', 'h3', 'h4'], default: 'h3', attribute: 'title-level', doc: 'Heading level of the title.' },
+    pressable: { type: 'boolean', attribute: 'pressable', doc: 'The whole surface is one press target that forwards to the title\'s primary control; set it when `onclick` is wired. Implied by `href`.' },
+    href: { type: 'string', attribute: 'href', doc: 'Makes the surface a whole-card link: the title\'s primary control is an anchor and its hit area stretches over the card.' },
+    selected: { type: 'boolean', attribute: 'selected', doc: 'A chosen card (accent-soft state).' },
+    disabled: { type: 'boolean', attribute: 'disabled', doc: 'Pressable surfaces only: inert primary control, no forwarding.' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name of the region when there is no visible title.' },
+  },
+  events: [{ type: 'click', kind: 'native', reactProp: 'onClick', doc: 'A press of the primary control (directly, or forwarded from anywhere on the surface).' }],
+  slots: {
+    default: { doc: 'The body.' },
+    title: { doc: 'The header title (a heading). Required on a pressable surface: it holds the primary control.' },
+    description: { doc: 'A secondary line under the title.' },
+    footer: { doc: 'The footer region, usually actions.' },
+  },
+  anatomy: {
+    tag: 'section',
+    class: 'ty-surface',
+    attrs: {
+      'aria-labelledby': { idref: 'title', when: ['slot:title'] },
+      'aria-label': { prop: 'accessibleLabel', when: ['!slot:title'] },
+      'data-elevation': { prop: 'elevation' },
+      'data-padding': { prop: 'padding' },
+      'data-pressable': { value: '', when: ['pressable|href'] },
+      'data-selected': { prop: 'selected', kind: 'flag' },
+      'data-disabled': { value: '', when: ['pressable|href', 'disabled'] },
+    },
+    children: [
+      {
+        tag: 'header',
+        class: 'ty-surface__header',
+        when: ['slot:title|slot:description'],
+        children: [
+          {
+            tag: 'h2',
+            class: 'ty-surface__title',
+            attrs: { id: { idref: 'title' } },
+            when: ['slot:title', 'titleLevel:h2'],
+            children: [
+              { tag: 'a', class: 'ty-surface__primary', when: ['href'], attrs: { href: { prop: 'href', when: ['!disabled'] }, 'aria-disabled': { prop: 'disabled', kind: 'bool' } }, children: [{ slot: 'title' }] },
+              { tag: 'button', class: 'ty-surface__primary', when: ['!href', 'pressable'], attrs: { type: { value: 'button' }, disabled: { prop: 'disabled', kind: 'boolean-attr' } }, children: [{ slot: 'title' }] },
+              { slot: 'title', when: ['!href', '!pressable'] },
+            ],
+          },
+          {
+            tag: 'h3',
+            class: 'ty-surface__title',
+            attrs: { id: { idref: 'title' } },
+            when: ['slot:title', 'titleLevel:h3'],
+            children: [
+              { tag: 'a', class: 'ty-surface__primary', when: ['href'], attrs: { href: { prop: 'href', when: ['!disabled'] }, 'aria-disabled': { prop: 'disabled', kind: 'bool' } }, children: [{ slot: 'title' }] },
+              { tag: 'button', class: 'ty-surface__primary', when: ['!href', 'pressable'], attrs: { type: { value: 'button' }, disabled: { prop: 'disabled', kind: 'boolean-attr' } }, children: [{ slot: 'title' }] },
+              { slot: 'title', when: ['!href', '!pressable'] },
+            ],
+          },
+          {
+            tag: 'h4',
+            class: 'ty-surface__title',
+            attrs: { id: { idref: 'title' } },
+            when: ['slot:title', 'titleLevel:h4'],
+            children: [
+              { tag: 'a', class: 'ty-surface__primary', when: ['href'], attrs: { href: { prop: 'href', when: ['!disabled'] }, 'aria-disabled': { prop: 'disabled', kind: 'bool' } }, children: [{ slot: 'title' }] },
+              { tag: 'button', class: 'ty-surface__primary', when: ['!href', 'pressable'], attrs: { type: { value: 'button' }, disabled: { prop: 'disabled', kind: 'boolean-attr' } }, children: [{ slot: 'title' }] },
+              { slot: 'title', when: ['!href', '!pressable'] },
+            ],
+          },
+          { tag: 'div', class: 'ty-surface__description', when: ['slot:description'], children: [{ slot: 'description' }] },
+        ],
+      },
+      { tag: 'div', class: 'ty-surface__body', when: ['slot:default'], children: [{ slot: 'default' }] },
+      { tag: 'footer', class: 'ty-surface__footer', when: ['slot:footer'], children: [{ slot: 'footer' }] },
+    ],
+  },
+  examples: [
+    { name: 'sheet', props: {}, slots: { title: 'Runs', description: 'Last 24 hours', default: 'Body' } },
+    { name: 'raised-roomy', props: { elevation: 'raised', padding: 'roomy' }, slots: { default: 'Body' } },
+    { name: 'flat-none-footer', props: { elevation: 'flat', padding: 'none' }, slots: { default: 'Body', footer: 'Actions' } },
+    { name: 'pressable', props: { pressable: true }, slots: { title: 'Open workflow', default: 'Body' } },
+    { name: 'link-selected', props: { href: '/runs/1', selected: true }, slots: { title: 'Nightly sync', default: 'Body' } },
+    { name: 'pressable-disabled', props: { pressable: true, disabled: true }, slots: { title: 'Archived', default: 'Body' } },
+    { name: 'title-level', props: { titleLevel: 'h2' }, slots: { title: 'Settings' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/surface/element.ts

@@ -0,0 +1,42 @@
+import { TyElement } from '../base.ts'
+import { surfaceDefinition } from './definition.ts'
+
+const INTERACTIVE = 'a[href],button,input,select,textarea,summary,[role="button"],[role="link"],[role="checkbox"],[role="switch"],[tabindex]:not([tabindex="-1"])'
+
+/**
+ * `<ty-surface>`. The anatomy is purely presentational; the behaviour the
+ * element adds is the pressable card: a press anywhere on the surface,
+ * outside a nested control and outside a text selection, is forwarded to
+ * the title's primary control (the link with `href`, the button otherwise),
+ * so keyboard activation and context menus stay that control's own.
+ */
+export class TySurfaceElement extends TyElement {
+  static override definition = surfaceDefinition
+
+  get primary(): HTMLElement | null {
+    return this.querySelector('.ty-surface__primary')
+  }
+
+  #pressable(): boolean {
+    return this.hasAttribute('pressable') || this.hasAttribute('href')
+  }
+
+  #onClick = (event: MouseEvent) => {
+    const primary = this.primary
+    if (!this.#pressable() || this.hasAttribute('disabled') || !primary || !(event.target instanceof Element)) return
+    if (primary.contains(event.target)) return
+    const interactive = event.target.closest(INTERACTIVE)
+    if (interactive && this.contains(interactive)) return
+    if (typeof window !== 'undefined' && window.getSelection?.()?.toString()) return
+    primary.click()
+  }
+
+  protected override connected(): void {
+    if (this.#pressable() && !this.primary) console.warn('<ty-surface>: a pressable surface needs a title, which becomes its primary control.')
+    this.addEventListener('click', this.#onClick)
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('click', this.#onClick)
+  }
+}

package/src/elements/switch/definition.ts

@@ -0,0 +1,72 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-switch>`: the Switch's single source (spec: wave-1/switch.md). */
+export const switchDefinition = {
+  tag: 'ty-switch',
+  name: 'TySwitch',
+  kind: 'enhancing',
+  doc: 'On/off setting with immediate effect. A native checkbox with role="switch" inside a <label>, so labelling, keyboard and form participation are the platform\'s; Enter toggles as well as Space.',
+  props: {
+    checked: { type: 'boolean', attribute: 'checked', doc: 'On.' },
+    disabled: { type: 'boolean', attribute: 'disabled', doc: 'Native disabled.' },
+    readOnly: { type: 'boolean', attribute: 'read-only', doc: 'Shown but not changeable (`aria-readonly`).' },
+    name: { type: 'string', attribute: 'name', doc: 'Form field name; the value is sent while on.' },
+    value: { type: 'string', attribute: 'value', doc: 'Form value sent while on (the browser sends "on" without one).' },
+    size: { type: 'enum', values: ['small', 'regular', 'large'], default: 'regular', attribute: 'size', doc: 'Track size.' },
+    layout: { type: 'enum', values: ['inline', 'tile'], default: 'inline', attribute: 'layout', doc: '`tile`: text at the start, control at the end, the whole row is the target.' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name when there is no visible label.' },
+    testId: { type: 'string', attribute: 'test-id', doc: 'Test hook on the native checkbox (`data-testid`).' },
+  },
+  events: [{ type: 'change', kind: 'native', detail: { checked: 'boolean' }, reactProp: 'onChange', doc: 'The native change of the checkbox; `checked` is the new state.' }],
+  slots: {
+    default: { doc: 'The visible label.' },
+    description: { doc: 'A secondary line, announced as the description.' },
+  },
+  anatomy: {
+    tag: 'label',
+    class: 'ty-switch',
+    attrs: {
+      'data-layout': { prop: 'layout' },
+      'data-size': { prop: 'size' },
+      'data-selected': { prop: 'checked', kind: 'flag' },
+      'data-disabled': { prop: 'disabled', kind: 'flag' },
+      'data-readonly': { prop: 'readOnly', kind: 'flag' },
+    },
+    children: [
+      {
+        tag: 'input',
+        class: 'ty-visually-hidden',
+        attrs: {
+          type: { value: 'checkbox' },
+          role: { value: 'switch' },
+          name: { prop: 'name' },
+          value: { prop: 'value' },
+          checked: { prop: 'checked', kind: 'boolean-attr' },
+          disabled: { prop: 'disabled', kind: 'boolean-attr' },
+          'aria-readonly': { prop: 'readOnly', kind: 'bool' },
+          'aria-label': { prop: 'accessibleLabel', when: ['!slot:default'] },
+          'aria-labelledby': { idref: 'label', when: ['slot:default'] },
+          'aria-describedby': { idref: 'description', when: ['slot:description'] },
+          'data-testid': { prop: 'testId' },
+        },
+      },
+      { tag: 'span', class: 'ty-switch__track', attrs: { 'aria-hidden': { value: 'true' } }, children: [{ tag: 'span', class: 'ty-switch__thumb' }] },
+      {
+        tag: 'span',
+        class: 'ty-switch__text',
+        when: ['slot:default|slot:description'],
+        children: [
+          { tag: 'span', class: 'ty-switch__label', attrs: { id: { idref: 'label' } }, when: ['slot:default'], children: [{ slot: 'default' }] },
+          { tag: 'span', class: 'ty-switch__description', attrs: { id: { idref: 'description' } }, when: ['slot:description'], children: [{ slot: 'description' }] },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'off', props: {}, slots: { default: 'Autosave' } },
+    { name: 'on-with-description', props: { checked: true, name: 'autosave' }, slots: { default: 'Autosave', description: 'Save every change' } },
+    { name: 'tile-large', props: { layout: 'tile', size: 'large', value: 'yes', testId: 'notifications' }, slots: { default: 'Notifications' } },
+    { name: 'read-only', props: { checked: true, readOnly: true }, slots: { default: 'Managed by your organization' } },
+    { name: 'disabled-unlabelled', props: { disabled: true, accessibleLabel: 'Dark mode' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/switch/element.ts

@@ -0,0 +1,65 @@
+import { TyElement } from '../base.ts'
+import { switchDefinition } from './definition.ts'
+
+/**
+ * `<ty-switch>`. A native checkbox with `role="switch"` inside a `<label>`:
+ * the label names it, Space toggles it and forms submit it natively. The
+ * element adds Enter (parity with the React Switch), keeps it unchangeable
+ * while read-only, reflects the state to the `checked` attribute (and so to
+ * `data-selected`), and follows a form reset.
+ */
+export class TySwitchElement extends TyElement {
+  static override definition = switchDefinition
+
+  #form: HTMLFormElement | null = null
+
+  get input(): HTMLInputElement | null {
+    return this.querySelector('input[role="switch"]')
+  }
+
+  #locked(): boolean {
+    return this.hasAttribute('disabled') || this.hasAttribute('read-only')
+  }
+
+  #onKey = (event: KeyboardEvent) => {
+    const input = this.input
+    if (!input || event.key !== 'Enter' || event.target !== input || this.#locked()) return
+    event.preventDefault()
+    input.click()
+  }
+
+  #onClick = (event: Event) => {
+    if (event.target === this.input && this.hasAttribute('read-only')) event.preventDefault()
+  }
+
+  #onChange = (event: Event) => {
+    const input = this.input
+    if (event.target !== input || !input) return
+    this.toggleAttribute('checked', input.checked)
+  }
+
+  #onReset = () => {
+    // The reset runs after the event; read the restored state then.
+    setTimeout(() => {
+      const input = this.input
+      if (input) this.toggleAttribute('checked', input.checked)
+    })
+  }
+
+  protected override connected(): void {
+    this.addEventListener('keydown', this.#onKey)
+    this.addEventListener('click', this.#onClick)
+    this.addEventListener('change', this.#onChange)
+    this.#form = this.input?.form ?? null
+    this.#form?.addEventListener('reset', this.#onReset)
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('keydown', this.#onKey)
+    this.removeEventListener('click', this.#onClick)
+    this.removeEventListener('change', this.#onChange)
+    this.#form?.removeEventListener('reset', this.#onReset)
+    this.#form = null
+  }
+
+}

package/src/elements/tabs/definition.ts

@@ -0,0 +1,60 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-tabs>`: the Tabs' single source (spec: wave-1/tabs.md).
+ *
+ * The anatomy covers the shell: the root and the tab list. The tabs
+ * themselves repeat per entry of the `tabs` prop, which the declarative
+ * anatomy cannot express (no dynamic repetition), so the element composes
+ * them into the list on upgrade — as the skeleton composes its presets.
+ * Panels are the host's own children (the default slot), each keyed to a tab
+ * by `data-panel`; the element wires their role, id, `aria-labelledby` and
+ * visibility. Examples therefore show the shell only: the parity renderers
+ * could not produce the composed tabs or the wired panels.
+ */
+export const tabsDefinition = {
+  tag: 'ty-tabs',
+  name: 'TyTabs',
+  kind: 'enhancing',
+  doc: 'Sibling views of one object, one panel at a time (the APG tabs pattern). The tab list is one tab stop: the arrow keys move along the `orientation` axis, wrapping and skipping disabled tabs, Home and End jump, and Left/Right follow the reading direction. `activation` decides whether moving focus also selects. Selection is controlled with `selected-key` or uncontrolled from `default-selected-key` (the first enabled tab when neither is set); a different selection is reported with `ty-selection-change`.',
+  props: {
+    selectedKey: { type: 'string', attribute: 'selected-key', doc: 'Controlled selection: the selected tab\'s id. The element asks for a change with `ty-selection-change`; the host flips the attribute.' },
+    defaultSelectedKey: { type: 'string', attribute: 'default-selected-key', doc: 'Initial selection of an uncontrolled list; the first enabled tab when unset.' },
+    orientation: { type: 'enum', values: ['horizontal', 'vertical'], default: 'horizontal', attribute: 'orientation', doc: 'Layout of the list and the arrow-key axis: Left/Right (following the reading direction), or Up/Down when vertical.' },
+    activation: { type: 'enum', values: ['automatic', 'manual'], default: 'automatic', attribute: 'activation', doc: 'Automatic selects on focus; manual needs Enter or Space on the focused tab.' },
+    label: { type: 'string', attribute: 'label', doc: 'Accessible name of the tab list (required).' },
+    tabs: { type: 'string', attribute: 'tabs', doc: 'JSON array of the tabs: [{ "id", "label", "count"?, "disabled"? }]. The count follows the label and joins the accessible name; a disabled tab cannot be selected and the arrow keys skip it. (The React component\'s decorative icon has no attribute form.)' },
+    keepMounted: { type: 'boolean', attribute: 'keep-mounted', doc: 'Keep inactive panels in the DOM (hidden) to preserve their state. The element always keeps them — their nodes belong to the host — so the attribute only tells a wrapper it may unmount.' },
+  },
+  events: [
+    { type: 'ty-selection-change', kind: 'custom', detail: { key: 'string' }, reactProp: 'onSelectionChange', doc: 'A different tab was selected (a click, or the keyboard per `activation`). Uncontrolled, the element has already applied it; controlled (`selected-key`), the host flips the attribute.' },
+  ],
+  slots: {
+    default: { doc: 'The panels: one element per tab, keyed by `data-panel` (the tab\'s id). The element wires the role, id, `aria-labelledby` and visibility; only the selected panel shows.' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-tabs',
+    attrs: {
+      'data-orientation': { prop: 'orientation' },
+    },
+    children: [
+      {
+        tag: 'div',
+        class: 'ty-tabs__list',
+        attrs: {
+          role: { value: 'tablist' },
+          'aria-label': { prop: 'label' },
+          'aria-orientation': { prop: 'orientation' },
+          'data-orientation': { prop: 'orientation' },
+        },
+      },
+      { slot: 'default' },
+    ],
+  },
+  examples: [
+    { name: 'horizontal', props: { label: 'Run sections' }, slots: {} },
+    { name: 'vertical', props: { label: 'Run sections', orientation: 'vertical' }, slots: {} },
+    { name: 'manual', props: { label: 'Run sections', activation: 'manual' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/tabs/element.ts

@@ -0,0 +1,319 @@
+import { TyElement } from '../base.ts'
+import { tabsDefinition } from './definition.ts'
+
+/** One entry of the `tabs` JSON prop (the React TabItem, minus the icon component). */
+interface TabItem {
+  id: string
+  label: string
+  count?: number
+  disabled?: boolean
+}
+
+/** A key made safe for the id of an aria reference (a space would split an idrefs list). */
+const safe = (key: string) => key.replace(/[^a-zA-Z0-9_-]/g, '-')
+
+/** The label/count signature each composed tab button last rendered. */
+const rendered = new WeakMap<Element, string>()
+
+/**
+ * `<ty-tabs>`. The anatomy — rendered by the host framework or built from
+ * plain HTML — is the shell (the root and the tab list); the element adds
+ * what the declarative anatomy cannot express and the APG tabs behaviour
+ * (spec: wave-1/tabs.md):
+ *
+ * - **Composition** — a native `<button role="tab">` per entry of the
+ *   `tabs` JSON prop, composed into the list and kept in step with it
+ *   (reusing nodes by key, so a recompose does not disturb focus). The
+ *   count follows the label and joins the accessible name ("Runs 4").
+ * - **Panels** — the default slot's children, keyed by `data-panel`, get
+ *   the `tabpanel` role, an id the tab's `aria-controls` names, the tab's
+ *   `aria-labelledby`, and the `ty-tabs__panel` class; only the selected
+ *   panel shows (the rest stay mounted, `hidden` and `data-inert`, so their
+ *   state survives a switch).
+ * - **Selection** — controlled through `selected-key` (the element asks
+ *   with `ty-selection-change`, the host flips the attribute) or
+ *   uncontrolled from `default-selected-key`, falling back to the first
+ *   enabled tab.
+ * - **Keyboard** — one tab stop (roving tabindex on the focused, else the
+ *   selected tab); the arrow keys move along the orientation axis, wrapping
+ *   and skipping disabled tabs, Home and End jump, Left/Right follow the
+ *   reading direction. Automatic activation selects on focus; manual needs
+ *   Enter or Space (a native button press).
+ *
+ * Panels are the host's own children, which no host attribute reports, so a
+ * MutationObserver re-runs the reconcile for panel changes; the pass only
+ * writes differences, and settles after one extra run.
+ */
+export class TyTabsElement extends TyElement {
+  static override definition = tabsDefinition
+
+  /** Uncontrolled selection (controlled: the `selected-key` attribute). */
+  #selected: string | undefined
+  /** The tab holding DOM focus while the list has it (the roving tabindex). */
+  #focused: string | undefined
+  #observer: MutationObserver | null = null
+
+  protected override connected(): void {
+    this.addEventListener('click', this.#onClick)
+    this.addEventListener('keydown', this.#onKeydown)
+    this.addEventListener('focusin', this.#onFocusIn)
+    this.addEventListener('focusout', this.#onFocusOut)
+    this.#observer = new MutationObserver(() => this.#reconcile())
+    this.#observer.observe(this, { childList: true, subtree: true })
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('click', this.#onClick)
+    this.removeEventListener('keydown', this.#onKeydown)
+    this.removeEventListener('focusin', this.#onFocusIn)
+    this.removeEventListener('focusout', this.#onFocusOut)
+    this.#observer?.disconnect()
+    this.#observer = null
+  }
+
+  override sync(): void {
+    const active = document.activeElement
+    const refocus = active instanceof HTMLElement ? this.#keyOfTab(active) : undefined
+    super.sync()
+    this.#reconcile()
+    // Plain HTML re-renders the anatomy on every attribute change, which
+    // rebuilds the composed tabs; give the focus back to the tab that held it.
+    if (refocus && !this.contains(document.activeElement)) this.#tabButton(refocus)?.focus()
+  }
+
+  #items(): TabItem[] {
+    const raw = this.getAttribute('tabs')
+    if (!raw) return []
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (!Array.isArray(parsed)) throw new Error('not an array')
+      const items: TabItem[] = []
+      for (const entry of parsed) {
+        if (typeof entry !== 'object' || entry === null) continue
+        const { id, label, count, disabled } = entry as Record<string, unknown>
+        if (typeof id !== 'string' || !id || typeof label !== 'string') continue
+        items.push({ id, label, count: typeof count === 'number' ? count : undefined, disabled: disabled === true })
+      }
+      return items
+    } catch {
+      console.warn('ty-tabs: `tabs` must be a JSON array of { id, label, count?, disabled? }.')
+      return []
+    }
+  }
+
+  #reconcile(): void {
+    const root = this.anatomyRoot()
+    if (!root) return
+    const list = root.querySelector('.ty-tabs__list')
+    if (!(list instanceof HTMLElement)) return
+    const props = this.props
+    const items = this.#items()
+    const controlled = this.hasAttribute('selected-key')
+    if (!controlled && this.#selected === undefined) {
+      const wanted = props.defaultSelectedKey ? String(props.defaultSelectedKey) : undefined
+      this.#selected = wanted && items.some((i) => i.id === wanted) ? wanted : items.find((i) => !i.disabled)?.id
+    }
+    let selected = controlled && props.selectedKey !== undefined ? String(props.selectedKey) : this.#selected
+    if (selected !== undefined && !items.some((i) => i.id === selected)) {
+      selected = items.find((i) => !i.disabled)?.id
+      if (!controlled) this.#selected = selected
+    }
+
+    this.#compose(list, items)
+    const buttons = this.#buttons(list)
+    // Roving focus: the focused tab while the list has focus, else the
+    // selected one; a disabled tab never takes the tab stop.
+    const roving = this.#focused ?? selected
+    const rovingKey = items.some((i) => i.id === roving && !i.disabled) ? roving : selected
+    for (const button of buttons) {
+      const key = button.dataset.tabKey!
+      const item = items.find((i) => i.id === key)!
+      button.setAttribute('aria-selected', key === selected ? 'true' : 'false')
+      button.toggleAttribute('data-selected', key === selected)
+      button.disabled = item.disabled === true
+      button.toggleAttribute('data-disabled', item.disabled === true)
+      button.tabIndex = key === rovingKey && item.disabled !== true ? 0 : -1
+    }
+
+    const panels = new Map<string, HTMLElement>()
+    for (const child of Array.from(root.children)) {
+      if (child instanceof HTMLElement && child.hasAttribute('data-panel')) panels.set(child.getAttribute('data-panel')!, child)
+    }
+    for (const [key, panel] of panels) {
+      panel.classList.add('ty-tabs__panel')
+      panel.setAttribute('role', 'tabpanel')
+      if (!panel.id) panel.id = `${this.instanceId}-panel-${safe(key)}`
+      const tab = buttons.find((b) => b.dataset.tabKey === key)
+      if (tab) {
+        panel.setAttribute('aria-labelledby', tab.id)
+        tab.setAttribute('aria-controls', panel.id)
+      }
+      const shown = key === selected
+      panel.hidden = !shown
+      panel.toggleAttribute('data-inert', !shown)
+      // Tab from the list lands in the selected panel (spec: it is focusable).
+      if (shown) panel.setAttribute('tabindex', '0')
+      else panel.removeAttribute('tabindex')
+    }
+    for (const button of buttons) {
+      if (!panels.has(button.dataset.tabKey!)) button.removeAttribute('aria-controls')
+    }
+  }
+
+  /** One button per item, reused by key and reordered to match; leftovers go. */
+  #compose(list: HTMLElement, items: TabItem[]): void {
+    const existing = new Map<string, HTMLButtonElement>()
+    for (const child of Array.from(list.children)) {
+      if (child instanceof HTMLButtonElement && child.dataset.tabKey !== undefined) existing.set(child.dataset.tabKey, child)
+    }
+    const wanted: HTMLButtonElement[] = []
+    for (const item of items) {
+      let button = existing.get(item.id)
+      if (!button) {
+        button = document.createElement('button')
+        button.type = 'button'
+        button.className = 'ty-tabs__tab'
+        button.setAttribute('role', 'tab')
+        button.dataset.tabKey = item.id
+      }
+      existing.delete(item.id)
+      button.id = `${this.instanceId}-tab-${safe(item.id)}`
+      this.#fillTab(button, item)
+      wanted.push(button)
+    }
+    for (const leftover of existing.values()) leftover.remove()
+    wanted.forEach((button, index) => {
+      if (list.children[index] !== button) list.insertBefore(button, list.children[index] ?? null)
+    })
+  }
+
+  /** The label, and the count after a separating space so it joins the accessible name. */
+  #fillTab(button: HTMLButtonElement, item: TabItem): void {
+    const counted = typeof item.count === 'number'
+    const signature = `${item.label} ${counted ? item.count : ''}`
+    if (rendered.get(button) === signature) return
+    rendered.set(button, signature)
+    const label = document.createElement('span')
+    label.className = 'ty-tabs__label'
+    label.textContent = item.label
+    if (!counted) {
+      button.replaceChildren(label)
+      return
+    }
+    const count = document.createElement('span')
+    count.className = 'ty-tabs__count'
+    count.textContent = String(item.count)
+    button.replaceChildren(label, document.createTextNode(' '), count)
+  }
+
+  #buttons(list?: HTMLElement | null): HTMLButtonElement[] {
+    const scope = list ?? this.anatomyRoot()?.querySelector('.ty-tabs__list')
+    if (!(scope instanceof HTMLElement)) return []
+    return Array.from(scope.children).filter((c): c is HTMLButtonElement => c instanceof HTMLButtonElement && c.dataset.tabKey !== undefined)
+  }
+
+  #tabButton(key: string): HTMLButtonElement | undefined {
+    return this.#buttons().find((b) => b.dataset.tabKey === key)
+  }
+
+  /** The tab key an element belongs to, when it is a tab of this list. */
+  #keyOfTab(node: Element | null): string | undefined {
+    const tab = node?.closest('.ty-tabs__tab')
+    return tab instanceof HTMLElement && this.contains(tab) ? tab.dataset.tabKey : undefined
+  }
+
+  #rtl(): boolean {
+    let node: HTMLElement | null = this
+    while (node) {
+      const dir = node.getAttribute('dir')
+      if (dir) return dir.toLowerCase() === 'rtl'
+      node = node.parentElement
+    }
+    return getComputedStyle(this).direction === 'rtl'
+  }
+
+  /** Select a tab the user activated; a no-op for the current or a disabled tab. */
+  #select(key: string): void {
+    const item = this.#items().find((i) => i.id === key)
+    if (!item || item.disabled) return
+    const current = this.hasAttribute('selected-key') ? String(this.props.selectedKey ?? '') : this.#selected
+    if (key === current) return
+    if (this.hasAttribute('selected-key')) {
+      // Controlled: the host flips `selected-key`.
+      this.emit('ty-selection-change', { key })
+      return
+    }
+    this.#selected = key
+    this.#reconcile()
+    this.emit('ty-selection-change', { key })
+  }
+
+  #focusTab(key: string): void {
+    this.#focused = key
+    this.#reconcile()
+    const button = this.#tabButton(key)
+    button?.focus()
+    // An overflowing list scrolls the tab into view instead of wrapping.
+    button?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })
+  }
+
+  #onClick = (event: Event): void => {
+    const key = this.#keyOfTab(event.target as Element)
+    if (key) this.#select(key)
+  }
+
+  #onKeydown = (event: KeyboardEvent): void => {
+    const list = this.anatomyRoot()?.querySelector('.ty-tabs__list')
+    if (!(list instanceof HTMLElement) || !list.contains(event.target as Node)) return
+    const vertical = String(this.props.orientation) === 'vertical'
+    const rtl = this.#rtl()
+    let move: 'home' | 'end' | number | null = null
+    switch (event.key) {
+      case 'ArrowRight':
+        if (!vertical) move = rtl ? -1 : 1
+        break
+      case 'ArrowLeft':
+        if (!vertical) move = rtl ? 1 : -1
+        break
+      case 'ArrowDown':
+        if (vertical) move = 1
+        break
+      case 'ArrowUp':
+        if (vertical) move = -1
+        break
+      case 'Home':
+        move = 'home'
+        break
+      case 'End':
+        move = 'end'
+        break
+      default:
+        return
+    }
+    if (move === null) return
+    event.preventDefault()
+    const enabled = this.#items().filter((i) => !i.disabled)
+    if (!enabled.length) return
+    const current = this.#keyOfTab(document.activeElement as Element) ?? this.#selected
+    const index = Math.max(0, enabled.findIndex((i) => i.id === current))
+    const next = move === 'home' ? enabled[0]! : move === 'end' ? enabled[enabled.length - 1]! : enabled[(index + move + enabled.length) % enabled.length]!
+    this.#focusTab(next.id)
+    if (String(this.props.activation) === 'automatic') this.#select(next.id)
+  }
+
+  #onFocusIn = (event: FocusEvent): void => {
+    const key = this.#keyOfTab(event.target as Element)
+    if (!key || key === this.#focused) return
+    this.#focused = key
+    this.#reconcile()
+  }
+
+  #onFocusOut = (event: FocusEvent): void => {
+    const next = event.relatedTarget as Node | null
+    const list = this.anatomyRoot()?.querySelector('.ty-tabs__list')
+    if (next && list instanceof HTMLElement && list.contains(next)) return
+    if (this.#focused === undefined) return
+    this.#focused = undefined
+    this.#reconcile()
+  }
+}