@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/page-header/element.ts

@@ -0,0 +1,37 @@
+import { TyElement } from '../base.ts'
+import { pageHeaderDefinition } from './definition.ts'
+
+/**
+ * `<ty-page-header>`. Almost all presentation: the host framework renders
+ * the anatomy (breadcrumbs, the row of icon, text and actions, the extra
+ * slot) and the stylesheet lays it out, including the below-640px stacking
+ * of the actions. The element adds the one dynamic part: with `editable`,
+ * it mirrors the `value` attribute into the title input — a no-op while
+ * the user types, so the caret stays put (the live value is the input's
+ * own; typing is reported as the native `input` event).
+ */
+export class TyPageHeaderElement extends TyElement {
+  static override definition = pageHeaderDefinition
+
+  /** The editable title's input, when rendered. */
+  get titleInput(): HTMLInputElement | null {
+    return this.querySelector('.ty-page-header__title-input')
+  }
+
+  /** Controlled text in, without disturbing the caret while typing. */
+  #applyValue = () => {
+    const input = this.titleInput
+    if (!input) return
+    const value = this.getAttribute('value')
+    if (value !== null && input.value !== value) input.value = value
+  }
+
+  protected override connected(): void {
+    this.#applyValue()
+  }
+
+  protected override changed(): void {
+    if (!this.isConnected) return
+    this.#applyValue()
+  }
+}

package/src/elements/popover/definition.ts

@@ -0,0 +1,137 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+/** A lucide glyph (ISC, THIRD_PARTY_NOTICES). */
+const glyph = (tag: string, attrs: Record<string, string>): ElementNode => ({
+  tag,
+  class: 'ty-popover__glyph',
+  attrs: Object.fromEntries(Object.entries(attrs).map(([name, value]) => [name, { value }])),
+})
+
+/** The built-in info trigger's "i" (lucide strokes), used only when the trigger slot is empty. */
+const infoIcon: ElementNode = {
+  tag: 'svg',
+  class: 'ty-icon',
+  attrs: {
+    viewBox: { value: '0 0 24 24' },
+    fill: { value: 'none' },
+    stroke: { value: 'currentColor' },
+    'stroke-width': { value: '2' },
+    'stroke-linecap': { value: 'round' },
+    'stroke-linejoin': { value: 'round' },
+    'aria-hidden': { value: 'true' },
+    focusable: { value: 'false' },
+  },
+  children: [
+    glyph('circle', { cx: '12', cy: '12', r: '10' }),
+    glyph('path', { d: 'M12 16v-4' }),
+    glyph('path', { d: 'M12 8h.01' }),
+  ],
+}
+
+/**
+ * The built-in trigger (only when the trigger slot is empty): a quiet,
+ * compact, icon-only button carrying the info glyph — exactly the chrome
+ * Popover.tsx composes.
+ */
+/** `<ty-popover>`: the Popover's single source (spec: wave-1/popover.md). */
+export const popoverDefinition = {
+  tag: 'ty-popover',
+  name: 'TyPopover',
+  kind: 'enhancing',
+  doc: 'Non-modal floating panel anchored to a trigger, for short explanations or arbitrary small content (help text, a mini form, a brand menu). The trigger is the host\'s own focusable element in the trigger slot — or the built-in info button when the slot is empty and `triggerLabel` names it. The element wires aria-expanded on the trigger, places the panel with the shared placement model (side preference, collision flip, viewport clamp, arrow inset), and asks to close with `ty-open-change` on Escape, an outside press, or focus leaving the panel; the host flips `open`. Not a focus trap — content that needs one is a dialog, not a popover.',
+  props: {
+    open: { type: 'boolean', attribute: 'open', doc: 'Shown (controlled). The anatomy stays mounted but `hidden` while closed, so nothing reaches the accessibility tree.' },
+    triggerLabel: { type: 'string', attribute: 'trigger-label', doc: 'Accessible name of the built-in info trigger (required when the trigger slot is empty).' },
+    title: { type: 'string', attribute: 'title', doc: 'Heading at the top of the panel; also its accessible name.' },
+    placement: { type: 'enum', values: ['top', 'end', 'bottom', 'start'], default: 'bottom', attribute: 'placement', doc: 'Preferred side; `start`/`end` follow the reading direction. Flips when there is no room.' },
+    align: { type: 'enum', values: ['start', 'center', 'end'], default: 'center', attribute: 'align', doc: 'Alignment along the chosen side.' },
+    offset: { type: 'string', default: '2', attribute: 'offset', doc: 'Gap between trigger and panel as a step of the spacing scale (0–9); the arrow\'s inset is added to it.' },
+    showArrow: { type: 'string', attribute: 'show-arrow', doc: '`true` or `false`; unset: the arrow shows.' },
+    panelTestId: { type: 'string', attribute: 'panel-test-id', doc: 'Test hook on the panel (`data-testid`).' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name of the panel when `title` is empty.' },
+  },
+  events: [
+    { type: 'ty-open-change', kind: 'custom', detail: { open: 'boolean' }, reactProp: 'onOpenChange', doc: 'The element asks the host to change visibility — `open: false` on Escape, an outside press or focus leaving the panel, `open: true` on a trigger activation. Controlled: the element does not toggle itself; the host flips `open`.' },
+  ],
+  slots: {
+    trigger: { doc: 'The host\'s own toggle — any single focusable element; wired to the panel (aria-expanded, activation). Empty: the built-in info button.' },
+    default: { doc: 'The panel body.' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-popover__anchor',
+    attrs: {},
+    children: [
+      // The trigger slot projects the host\'s control; the built-in info
+      // button stands in when it is empty.
+      {
+        tag: 'button',
+        class: 'ty-button ty-popover__trigger',
+        when: ['!slot:trigger'],
+        attrs: {
+          type: { value: 'button' },
+          'aria-label': { prop: 'triggerLabel' },
+          'aria-haspopup': { value: 'dialog' },
+          'data-variant': { value: 'quiet' },
+          'data-size': { value: 'compact' },
+          'data-shape': { value: 'circle' },
+          'data-icon-only': { value: '' },
+        },
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-button__icon',
+            attrs: { 'aria-hidden': { value: 'true' } },
+            children: [infoIcon],
+          },
+        ],
+      },
+      { slot: 'trigger', when: ['slot:trigger'] },
+      {
+        tag: 'div',
+        class: 'ty-popover',
+        // Always rendered (a framework's closed popover has an anatomy to
+        // find); `hidden` while closed, so nothing reaches the tree.
+        attrs: {
+          hidden: { value: '', when: ['!open'] },
+          role: { value: 'dialog' },
+          'data-placement': { prop: 'placement' },
+          'data-testid': { prop: 'panelTestId' },
+        },
+        children: [
+          {
+            tag: 'div',
+            class: 'ty-popover__arrow',
+            when: ['!showArrow:false'],
+            attrs: { 'aria-hidden': { value: 'true' } },
+          },
+          {
+            tag: 'div',
+            class: 'ty-popover__dialog',
+            children: [
+              {
+                tag: 'h3',
+                class: 'ty-popover__title',
+                when: ['title'],
+                children: [{ text: { prop: 'title' } }],
+              },
+              {
+                tag: 'div',
+                class: 'ty-popover__content',
+                when: ['slot:default'],
+                children: [{ slot: 'default' }],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'closed', props: { triggerLabel: 'Details' }, slots: {} },
+    { name: 'info-open', props: { open: true, triggerLabel: 'About this', title: 'What this means' }, slots: { default: 'A short explanation.' } },
+    { name: 'own-trigger', props: { open: true, placement: 'top', align: 'start' }, slots: { trigger: 'Open', default: 'Anchored above, aligned to the start.' } },
+    { name: 'no-arrow', props: { open: true, triggerLabel: 'Where', title: 'Somewhere', showArrow: 'false' }, slots: { default: 'Without a pointer.' } },
+    { name: 'offset-4', props: { open: true, triggerLabel: 'Gap', title: 'Further away', offset: '4' }, slots: { default: 'A wider gap.' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/popover/element.ts

@@ -0,0 +1,196 @@
+import { TyElement } from '../base.ts'
+import { popoverDefinition } from './definition.ts'
+import { physicalSide, place, offsetPx, type Rect, type Size } from './model.ts'
+
+/**
+ * `<ty-popover>`. The host framework renders the anatomy (trigger or its
+ * slot, panel with arrow/title/body) from the definition; the element adds
+ * the behaviour (spec: wave-1/popover.md):
+ *
+ * - **Trigger wiring** — the trigger slot's first element (or the built-in
+ *   info button) gets `aria-haspopup="dialog"` and reflects `open` in
+ *   `aria-expanded`; activating it asks the host to toggle
+ *   (`ty-open-change`).
+ * - **Placement** — the panel is `position: fixed` at the geometry the
+ *   shared placement model computes from the trigger's rectangle (side
+ *   preference, collision flip, viewport clamp, arrow inset), recomputed
+ *   on open, on resize and on scroll.
+ * - **Dismissal** — Escape and a press outside ask to close; focus leaving
+ *   the panel (a Tab past its last control) does too. Not a focus trap:
+ *   content that needs one is a dialog.
+ */
+export class TyPopoverElement extends TyElement {
+  static override definition = popoverDefinition
+
+  /** Observed outside-press/focus listeners, for a clean disconnect. */
+  #outsideController: AbortController | null = null
+  /** The panel's fixed position is recomputed while open. */
+  #raf = 0
+
+  override connected(): void {
+    super.connected?.()
+    this.addEventListener('click', this.#onActivate)
+    this.addEventListener('keydown', this.#onKeydown)
+    if (this.props.open) this.#activate()
+  }
+
+  override disconnected(): void {
+    super.disconnected?.()
+    this.removeEventListener('click', this.#onActivate)
+    this.removeEventListener('keydown', this.#onKeydown)
+    this.#teardown()
+  }
+
+  protected override changed(): void {
+    if (!this.isConnected) return
+    this.#wireTrigger()
+    if (this.props.open) this.#activate()
+    else this.#teardown()
+  }
+
+  /** The control that toggles the panel: the trigger slot's first element, else the built-in info button. */
+  #trigger(): HTMLElement | null {
+    const slot = this.querySelector<HTMLSlotElement>('slot[name="trigger"]')
+    const fromSlot = slot?.assignedElements({ flatten: true })[0]
+    const trigger = fromSlot ?? this.querySelector('.ty-popover__trigger')
+    return trigger instanceof HTMLElement ? trigger : null
+  }
+
+  #panel(): HTMLElement | null {
+    return this.querySelector('.ty-popover')
+  }
+
+  /** The trigger reflects open state; the panel's name comes from title or accessibleLabel. */
+  #wireTrigger(): void {
+    const trigger = this.#trigger()
+    const panel = this.#panel()
+    if (!trigger || !panel) return
+    trigger.setAttribute('aria-haspopup', 'dialog')
+    trigger.setAttribute('aria-expanded', this.props.open ? 'true' : 'false')
+    if (!panel.getAttribute('aria-label')) {
+      const label = String(this.props.title || this.props.accessibleLabel || '')
+      if (label) panel.setAttribute('aria-label', label)
+    }
+    // The panel is controlled by the trigger it belongs to.
+    const id = panel.id || (panel.id = `ty-popover-panel-${crypto.randomUUID().slice(0, 8)}`)
+    trigger.setAttribute('aria-controls', id)
+  }
+
+  #onActivate = (event: Event): void => {
+    const trigger = this.#trigger()
+    if (!trigger || !this.#contains(event.target as Node, trigger)) return
+    // The host's own button already handles its activation semantics; the
+    // element only asks for the toggle.
+    event.preventDefault()
+    this.requestOpen(!this.props.open)
+  }
+
+  #onKeydown = (event: KeyboardEvent): void => {
+    if (event.key !== 'Escape' || !this.props.open) return
+    event.stopPropagation()
+    this.requestOpen(false)
+  }
+
+  /** Ask the host to change visibility (controlled). */
+  requestOpen(open: boolean): void {
+    this.emit('ty-open-change', { open })
+  }
+
+  #activate(): void {
+    if (this.#outsideController) return
+    const controller = new AbortController()
+    this.#outsideController = controller
+    // A press that starts outside closes; one that starts inside (selecting
+    // text) does not.
+    document.addEventListener(
+      'pointerdown',
+      (event) => {
+        if (this.contains(event.target as Node)) return
+        this.requestOpen(false)
+      },
+      { signal: controller.signal },
+    )
+    // Focus leaving the panel (and not entering the trigger) closes.
+    this.addEventListener(
+      'focusout',
+      (event: FocusEvent) => {
+        const next = event.relatedTarget as Node | null
+        if (next && this.contains(next)) return
+        this.requestOpen(false)
+      },
+      { signal: controller.signal },
+    )
+    const reposition = () => this.#place()
+    window.addEventListener('resize', reposition, { signal: controller.signal })
+    window.addEventListener('scroll', reposition, { capture: true, passive: true, signal: controller.signal })
+    // Place after the anatomy has had its frame (a framework commits
+    // children and host attributes separately).
+    requestAnimationFrame(() => {
+      if (!this.isConnected || !this.props.open) return
+      this.#place()
+      const panel = this.#panel()
+      if (panel) {
+        panel.setAttribute('data-entering', '')
+        panel.addEventListener('animationend', () => panel.removeAttribute('data-entering'), { once: true })
+      }
+    })
+  }
+
+  #teardown(): void {
+    this.#outsideController?.abort()
+    this.#outsideController = null
+    if (this.#raf) cancelAnimationFrame(this.#raf)
+    this.#raf = 0
+    const panel = this.#panel()
+    if (panel) panel.style.removeProperty('inset')
+  }
+
+  #place(): void {
+    const trigger = this.#trigger()
+    const panel = this.#panel()
+    if (!trigger || !panel) return
+    const rect = trigger.getBoundingClientRect()
+    const anchor: Rect = { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+    // The panel measures itself at its natural size before placement.
+    const style = getComputedStyle(panel)
+    const size: Size = {
+      width: panel.offsetWidth + Number.parseFloat(style.marginLeft || '0') + Number.parseFloat(style.marginRight || '0'),
+      height: panel.offsetHeight + Number.parseFloat(style.marginTop || '0') + Number.parseFloat(style.marginBottom || '0'),
+    }
+    const viewport: Size = { width: document.documentElement.clientWidth, height: window.innerHeight }
+    const rtl = getComputedStyle(this).direction === 'rtl'
+    const side = physicalSide(String(this.props.placement || 'bottom'), rtl)
+    const offset = offsetPx(Number(this.props.offset ?? 2), this.getAttribute('show-arrow') !== 'false')
+    const placed = place(
+      anchor,
+      size,
+      viewport,
+      side,
+      String(this.props.align || 'center') as 'start' | 'center' | 'end',
+      offset,
+    )
+    this.#raf = requestAnimationFrame(() => {
+      panel.style.position = 'fixed'
+      panel.style.left = `${Math.round(placed.x)}px`
+      panel.style.top = `${Math.round(placed.y)}px`
+      panel.style.maxWidth = `${Math.max(0, viewport.width - 32)}px`
+      const arrow = panel.querySelector<HTMLElement>('.ty-popover__arrow')
+      if (arrow) arrow.dataset.side = placed.side
+      panel.dataset.side = placed.side
+    })
+  }
+
+  #contains(node: Node | null, scope: HTMLElement): boolean {
+    let current: Node | null = node
+    while (current) {
+      if (current === scope) return true
+      current = current.parentElement ?? (current instanceof HTMLSlotElement ? null : null)
+      if (!current && node instanceof Node) {
+        // Slotted light DOM resolves through its slot's host.
+        const slot = (node as Element).assignedSlot
+        if (slot) current = slot
+      }
+    }
+    return false
+  }
+}

package/src/elements/popover/model.ts

@@ -0,0 +1,141 @@
+// Anchored placement for `<ty-popover>`: where a panel of a known size goes
+// next to a trigger rectangle so it stays inside the viewport. Pure
+// geometry in CSS pixels (what getBoundingClientRect reports and
+// position:fixed consumes), so the rules are unit-tested without layout.
+// Mirrors components/placement.rs on the Astrlabe side: preferred side,
+// flip on collision, viewport clamp, arrow offset.
+
+/** An axis-aligned rectangle in viewport pixels. */
+export interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** A width and height in pixels. */
+export interface Size {
+  width: number
+  height: number
+}
+
+/** The physical side of the trigger the panel sits on. */
+export type Side = 'top' | 'bottom' | 'left' | 'right'
+
+/** Alignment along the chosen side. */
+export type Align = 'start' | 'center' | 'end'
+
+export interface Placed {
+  x: number
+  y: number
+  /** The side actually used — the preferred one or its opposite after a flip. */
+  side: Side
+  /** Distance from the panel's left (vertical sides) or top (horizontal sides) edge to the arrow's centre. */
+  arrow: number
+}
+
+/** Pixels kept between the panel and every viewport edge (the spec's 16 px gutter; RAC's containerPadding). */
+export const VIEWPORT_MARGIN = 16
+/** Least distance between the arrow's centre and a panel corner, so it never sits on the rounding. */
+export const ARROW_INSET = 14
+
+/** Spacing scale steps in px (the `offset` prop is a step index), as Popover.tsx maps them. */
+export const SPACE_STEPS = [0, 4, 8, 12, 16, 24, 32, 48, 64, 96]
+
+/** The gap in px for an `offset` step; the arrow adds 6 px (Popover.tsx). */
+export function offsetPx(step: number, showArrow: boolean): number {
+  return (SPACE_STEPS[Math.trunc(step)] ?? 8) + (showArrow ? 6 : 0)
+}
+
+/** The logical `placement` as a physical side in the current reading direction. */
+export function physicalSide(placement: string, rtl: boolean): Side {
+  switch (placement) {
+    case 'top':
+      return 'top'
+    case 'end':
+      return rtl ? 'left' : 'right'
+    case 'start':
+      return rtl ? 'right' : 'left'
+    default:
+      return 'bottom'
+  }
+}
+
+const OPPOSITE: Record<Side, Side> = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' }
+const VERTICAL = new Set<Side>(['top', 'bottom'])
+
+/** Free space between the anchor and the viewport edge on `side`, after the margin. */
+function space(anchor: Rect, viewport: Size, side: Side): number {
+  switch (side) {
+    case 'top':
+      return anchor.y - VIEWPORT_MARGIN
+    case 'bottom':
+      return viewport.height - (anchor.y + anchor.height) - VIEWPORT_MARGIN
+    case 'left':
+      return anchor.x - VIEWPORT_MARGIN
+    case 'right':
+      return viewport.width - (anchor.x + anchor.width) - VIEWPORT_MARGIN
+  }
+}
+
+/** The preferred side when the panel fits, the opposite when it has more room, else the preferred. */
+export function resolveSide(anchor: Rect, panel: Size, viewport: Size, preferred: Side, offset: number): Side {
+  const needed = offset + (VERTICAL.has(preferred) ? panel.height : panel.width)
+  const preferredSpace = space(anchor, viewport, preferred)
+  if (preferredSpace >= needed) return preferred
+  const opposite = OPPOSITE[preferred]
+  return space(anchor, viewport, opposite) > preferredSpace ? opposite : preferred
+}
+
+function crossStart(anchorStart: number, anchorLen: number, panelLen: number, align: Align): number {
+  switch (align) {
+    case 'start':
+      return anchorStart
+    case 'end':
+      return anchorStart + anchorLen - panelLen
+    default:
+      return anchorStart + (anchorLen - panelLen) / 2
+  }
+}
+
+/** Keep the panel `VIEWPORT_MARGIN` from the edges; a panel larger than the viewport pins to the leading margin. */
+function clampAxis(start: number, panelLen: number, viewportLen: number): number {
+  const max = viewportLen - VIEWPORT_MARGIN - panelLen
+  return Math.min(Math.max(start, VIEWPORT_MARGIN), Math.max(max, VIEWPORT_MARGIN))
+}
+
+/** The arrow's centre along the panel edge facing the anchor, kept off the rounded corners. */
+function arrowOffset(anchorCentre: number, panelLen: number): number {
+  return Math.min(Math.max(anchorCentre, ARROW_INSET), Math.max(panelLen - ARROW_INSET, ARROW_INSET))
+}
+
+/** Place `panel` next to `anchor` inside `viewport` — see the module doc. */
+export function place(anchor: Rect, panel: Size, viewport: Size, preferred: Side, align: Align, offset: number): Placed {
+  const side = resolveSide(anchor, panel, viewport, preferred, offset)
+  let rawX: number
+  let rawY: number
+  switch (side) {
+    case 'top':
+      rawX = crossStart(anchor.x, anchor.width, panel.width, align)
+      rawY = anchor.y - offset - panel.height
+      break
+    case 'bottom':
+      rawX = crossStart(anchor.x, anchor.width, panel.width, align)
+      rawY = anchor.y + anchor.height + offset
+      break
+    case 'left':
+      rawX = anchor.x - offset - panel.width
+      rawY = crossStart(anchor.y, anchor.height, panel.height, align)
+      break
+    case 'right':
+      rawX = anchor.x + anchor.width + offset
+      rawY = crossStart(anchor.y, anchor.height, panel.height, align)
+      break
+  }
+  const x = clampAxis(rawX, panel.width, viewport.width)
+  const y = clampAxis(rawY, panel.height, viewport.height)
+  const arrow = VERTICAL.has(side)
+    ? arrowOffset(anchor.x + anchor.width / 2 - x, panel.width)
+    : arrowOffset(anchor.y + anchor.height / 2 - y, panel.height)
+  return { x, y, side, arrow }
+}

package/src/elements/progress-bar/definition.ts

@@ -0,0 +1,84 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-progress-bar>`: the ProgressBar's single source (spec: wave-1/progress-bar.md).
+ *
+ * The anatomy carries everything declarative: the `progressbar` role, its
+ * name (the visible label by `aria-labelledby`, `accessibleLabel` without
+ * one), the range and the in-range value, the tone/size/indeterminate
+ * states. The element adds what the definition language cannot compute: the
+ * clamped value outside the range, the percentage value text (visible and
+ * `aria-valuetext`), the "in progress" text of an indeterminate bar, the
+ * complete state and the fill's inline size. `showValue` is a string like
+ * the popover's `showArrow`: `'true'` or `'false'`, unset shows the value.
+ */
+export const progressBarDefinition = {
+  tag: 'ty-progress-bar',
+  name: 'TyProgressBar',
+  kind: 'enhancing',
+  doc: 'Determinate or indeterminate task progress (upload, batch run, profile completion). Not focusable; the host announces completion through a Toast or status message, not through the bar. Values outside the range are clamped on upgrade; the fill width changes with `--ty-dur-quick`, instantly under reduced motion, where the indeterminate sweep becomes a static partial fill with the label still stating "in progress".',
+  props: {
+    value: { type: 'number', default: 0, attribute: 'value', doc: 'Current value; clamped into the range on upgrade.' },
+    minValue: { type: 'number', default: 0, attribute: 'min-value', doc: 'Start of the range.' },
+    maxValue: { type: 'number', default: 100, attribute: 'max-value', doc: 'End of the range; reaching it is the complete state.' },
+    label: { type: 'string', attribute: 'label', doc: 'Visible and accessible name (required unless `accessibleLabel` is given).' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name when there is no visible label (`aria-label`).' },
+    valueLabel: { type: 'string', attribute: 'value-label', doc: 'Custom value text, such as "3 of 8 steps"; the computed percentage when unset.' },
+    showValue: { type: 'string', attribute: 'show-value', doc: '`true` or `false`; unset: the value text shows. An indeterminate bar always shows its "in progress" text.' },
+    indeterminate: { type: 'boolean', attribute: 'indeterminate', doc: 'Unknown progress: no `aria-valuenow` and no percentage, the value text states "in progress".' },
+    inProgressLabel: { type: 'string', default: 'In progress', attribute: 'in-progress-label', doc: 'Value text of an indeterminate bar; translate through this attribute.' },
+    tone: { type: 'enum', values: ['accent', 'success', 'warning', 'danger'], default: 'accent', attribute: 'tone', doc: 'Semantic tone of the fill; never the only signal (pair with value text or a status word).' },
+    size: { type: 'enum', values: ['thin', 'regular'], default: 'regular', attribute: 'size', doc: 'Track thickness.' },
+  },
+  events: [],
+  anatomy: {
+    tag: 'div',
+    class: 'ty-progress',
+    attrs: {
+      role: { value: 'progressbar' },
+      'aria-labelledby': { idref: 'label', when: ['label'] },
+      'aria-label': { prop: 'accessibleLabel', when: ['!label'] },
+      'aria-valuemin': { prop: 'minValue' },
+      'aria-valuemax': { prop: 'maxValue' },
+      'aria-valuenow': { prop: 'value', when: ['!indeterminate'] },
+      'aria-valuetext': { prop: 'valueLabel', when: ['!indeterminate'] },
+      'data-tone': { prop: 'tone' },
+      'data-size': { prop: 'size' },
+      'data-indeterminate': { prop: 'indeterminate', kind: 'flag' },
+    },
+    children: [
+      {
+        tag: 'div',
+        class: 'ty-progress__header',
+        when: ['label|indeterminate|!showValue:false'],
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-progress__label',
+            when: ['label'],
+            attrs: { id: { idref: 'label' } },
+            children: [{ text: { prop: 'label' } }],
+          },
+          {
+            tag: 'span',
+            class: 'ty-progress__value',
+            when: ['indeterminate|!showValue:false'],
+          },
+        ],
+      },
+      {
+        tag: 'div',
+        class: 'ty-progress__track',
+        attrs: { 'aria-hidden': { value: 'true' } },
+        children: [{ tag: 'div', class: 'ty-progress__fill' }],
+      },
+    ],
+  },
+  examples: [
+    { name: 'determinate', props: { value: 40, label: 'Upload' }, slots: {} },
+    { name: 'custom-value-label', props: { value: 3, maxValue: 8, valueLabel: '3 of 8 steps', label: 'Setup' }, slots: {} },
+    { name: 'indeterminate', props: { indeterminate: true, label: 'Import' }, slots: {} },
+    { name: 'complete-success-thin', props: { value: 100, label: 'Upload', tone: 'success', size: 'thin' }, slots: {} },
+    { name: 'unlabelled-hidden-value', props: { value: 20, accessibleLabel: 'Storage used', showValue: 'false' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/progress-bar/element.ts

@@ -0,0 +1,82 @@
+import { TyElement } from '../base.ts'
+import { progressBarDefinition } from './definition.ts'
+
+/**
+ * `<ty-progress-bar>`. The anatomy (rendered by the host framework, or built
+ * from plain HTML) carries the progressbar role, its name, the range and an
+ * in-range value; the stylesheet draws the track and fill, including the
+ * indeterminate sweep and its reduced-motion and forced-colours fallbacks.
+ * The element adds the computed state the definition language cannot
+ * express (mirroring the React ProgressBar, which gets it from React Aria):
+ *
+ * - **clamping** — a value outside the range is pulled back in
+ *   (`aria-valuenow`); in-range values never touch the rendered attribute;
+ * - **value text** — the visible text and `aria-valuetext`: `valueLabel`
+ *   when given, the rounded percentage otherwise; an indeterminate bar
+ *   states `inProgressLabel` instead;
+ * - **complete** — `data-complete` while a determinate value reaches the
+ *   maximum;
+ * - **the fill's inline size** — the percentage of the range (an
+ *   indeterminate fill is sized and animated by the stylesheet).
+ *
+ * The first pass runs after the first paint, so the upgrade never rewrites
+ * the rendered anatomy (see <ty-text-field>); attribute changes apply at
+ * once.
+ */
+export class TyProgressBarElement extends TyElement {
+  static override definition = progressBarDefinition
+
+  /** False until the first paint: the computed state is not applied during the upgrade the parity renderers compare. */
+  #ready = false
+
+  override sync(): void {
+    super.sync()
+    if (this.#ready) this.#update()
+  }
+
+  protected override connected(): void {
+    requestAnimationFrame(() => {
+      if (!this.isConnected) return
+      this.#ready = true
+      this.#update()
+    })
+  }
+
+  #update(): void {
+    const root = this.anatomyRoot()
+    if (!root) return
+    const props = this.props
+    const indeterminate = Boolean(props.indeterminate)
+    const min = Number(props.minValue ?? 0)
+    const max = Number(props.maxValue ?? 100)
+    const clamped = Math.min(Math.max(Number(props.value ?? 0), min), max)
+    const range = max - min
+    const percentage = range > 0 ? Math.round(((clamped - min) / range) * 100) : 100
+
+    if (indeterminate) root.removeAttribute('aria-valuenow')
+    else {
+      // super.sync() bound the raw value; only an out-of-range one needs the clamp.
+      const now = String(clamped)
+      if (root.getAttribute('aria-valuenow') !== now) root.setAttribute('aria-valuenow', now)
+      const valueText = props.valueLabel !== undefined && props.valueLabel !== '' ? String(props.valueLabel) : `${percentage}%`
+      if (root.getAttribute('aria-valuetext') !== valueText) root.setAttribute('aria-valuetext', valueText)
+    }
+    root.toggleAttribute('data-complete', !indeterminate && clamped >= max)
+
+    const value = root.querySelector('.ty-progress__value')
+    if (value) {
+      const text = indeterminate
+        ? String(props.inProgressLabel ?? 'In progress')
+        : props.valueLabel !== undefined && props.valueLabel !== ''
+          ? String(props.valueLabel)
+          : `${percentage}%`
+      if (value.textContent !== text) value.textContent = text
+    }
+
+    const fill = root.querySelector<HTMLElement>('.ty-progress__fill')
+    if (fill) {
+      const size = indeterminate ? '' : `${percentage}%`
+      if (fill.style.inlineSize !== size) fill.style.inlineSize = size
+    }
+  }
+}