@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/react/TyWheelPicker.ts

@@ -0,0 +1,60 @@
+// Generated by tools/elements/generate.mjs from packages/ui/src/elements/wheel-picker/definition.ts. Do not edit.
+import { createElement, forwardRef, useEffect, useId, useImperativeHandle, useRef } from 'react'
+import { defineTympanElements } from '../index.ts'
+
+if (typeof window !== 'undefined') defineTympanElements()
+
+const truthy = (v: unknown) => v !== undefined && v !== null && v !== false && v !== ''
+const text = (v: unknown) => (truthy(v) ? String(v) : undefined)
+
+/** Touch-friendly vertical scroller that picks one value from an ordered list by centring it in a selection band (drag or flick scrolls and snaps, a tap selects, the keyboard moves by row, page or ends). With `columns`, several wheels sit side by side for compound values (day, month, year), each with its own width share. */
+export interface TyWheelPickerProps {
+  /** JSON array of the ordered choices: plain strings, or { "value", "label" } objects when the shown text differs from the reported value. */
+  options?: string
+  /** Selected value. A value no option holds centres the first row and reports nothing until the wheel moves; programmatic changes animate the wheel to the new row. */
+  value?: string
+  /** Accessible name of the wheel; with `columns`, of the whole group. */
+  label?: string
+  /** Rows visible at once; an even number rounds up to the next odd one (minimum 3). Default: `5`. */
+  visibleRows?: number
+  /** Shown but not changeable: the wheel stays focusable, taps, scrolling and keys do not select. */
+  disabled?: boolean
+  /** Multi-column form: JSON array of { "label", "options", "value", "share"? }, one wheel per entry; `share` is its relative width. Wins over `options` and `value`. */
+  columns?: string
+  /** Test hook on the wheel (`data-testid`). */
+  testId?: string
+  /** The wheel settled on a new value, or a row was activated (tap, arrows, PageUp/PageDown, Home/End, typeahead). `value` is the option's value, not its label; `column` is the wheel's index (0 for a single wheel). */
+  onChange?: (detail: { value: string; column: number }) => void
+  id?: string
+  className?: string
+}
+
+const DEFAULTS = { visibleRows: 5 } as const
+
+export const TyWheelPicker = forwardRef<HTMLElement, TyWheelPickerProps>(function TyWheelPicker(props, ref) {
+  const generated = useId()
+  const instance = `ty${generated.replace(/[^a-zA-Z0-9_-]/g, '')}`
+  const handlers = useRef(props)
+  handlers.current = props
+  const host = useRef<HTMLElement>(null)
+  useImperativeHandle(ref, () => host.current as HTMLElement)
+  useEffect(() => {
+    const element = host.current
+    if (!element) return
+    const listeners: Array<[string, EventListener]> = [
+      ["ty-change", (event) => handlers.current.onChange?.((event as CustomEvent).detail)],
+    ]
+    for (const [type, listener] of listeners) element.addEventListener(type, listener)
+    return () => { for (const [type, listener] of listeners) element.removeEventListener(type, listener) }
+  }, [])
+  const p = {
+    options: props.options,
+    value: props.value,
+    label: props.label,
+    visibleRows: props.visibleRows ?? DEFAULTS.visibleRows,
+    disabled: props.disabled,
+    columns: props.columns,
+    testId: props.testId,
+  }
+  return createElement("ty-wheel-picker", { ref: host, id: props.id, className: props.className, 'data-ty-instance': instance, "options": text(p.options), "value": text(p.value), "label": text(p.label), "visible-rows": text(p.visibleRows), "disabled": truthy(p.disabled) ? true : undefined, "columns": text(p.columns), "test-id": text(p.testId) })
+})

package/src/elements/react/index.ts

@@ -0,0 +1,39 @@
+// Generated by tools/elements/generate.mjs from packages/ui/src/elements/*/definition.ts. Do not edit.
+export { TyActionMenu, type TyActionMenuProps } from './TyActionMenu.ts'
+export { TyAvatar, type TyAvatarProps } from './TyAvatar.ts'
+export { TyBrandWordmark, type TyBrandWordmarkProps } from './TyBrandWordmark.ts'
+export { TyBreadcrumbs, type TyBreadcrumbsProps } from './TyBreadcrumbs.ts'
+export { TyCommandPalette, type TyCommandPaletteProps } from './TyCommandPalette.ts'
+export { TyCurrencyField, type TyCurrencyFieldProps } from './TyCurrencyField.ts'
+export { TyDataTable, type TyDataTableProps } from './TyDataTable.ts'
+export { TyHeading, type TyHeadingProps } from './TyHeading.ts'
+export { TyMarkdownView, type TyMarkdownViewProps } from './TyMarkdownView.ts'
+export { TyNotificationCenter, type TyNotificationCenterProps } from './TyNotificationCenter.ts'
+export { TyPageHeader, type TyPageHeaderProps } from './TyPageHeader.ts'
+export { TyProgressBar, type TyProgressBarProps } from './TyProgressBar.ts'
+export { TySectionHeading, type TySectionHeadingProps } from './TySectionHeading.ts'
+export { TySegmentedControl, type TySegmentedControlProps } from './TySegmentedControl.ts'
+export { TySkipLink, type TySkipLinkProps } from './TySkipLink.ts'
+export { TyTabs, type TyTabsProps } from './TyTabs.ts'
+export { TyTagField, type TyTagFieldProps } from './TyTagField.ts'
+export { TyToast, type TyToastProps } from './TyToast.ts'
+export { TyWheelPicker, type TyWheelPickerProps } from './TyWheelPicker.ts'
+export { TyButton, type TyButtonProps } from './TyButton.ts'
+export { TyCheckbox, type TyCheckboxProps } from './TyCheckbox.ts'
+export { TyDrawer, type TyDrawerProps } from './TyDrawer.ts'
+export { TyGradientMark, type TyGradientMarkProps } from './TyGradientMark.ts'
+export { TyInlineNotice, type TyInlineNoticeProps } from './TyInlineNotice.ts'
+export { TyLink, type TyLinkProps } from './TyLink.ts'
+export { TyModal, type TyModalProps } from './TyModal.ts'
+export { TyNativeSelect, type TyNativeSelectProps } from './TyNativeSelect.ts'
+export { TyPopover, type TyPopoverProps } from './TyPopover.ts'
+export { TySeparator, type TySeparatorProps } from './TySeparator.ts'
+export { TySkeleton, type TySkeletonProps } from './TySkeleton.ts'
+export { TySpinner, type TySpinnerProps } from './TySpinner.ts'
+export { TyStatusPill, type TyStatusPillProps } from './TyStatusPill.ts'
+export { TySurface, type TySurfaceProps } from './TySurface.ts'
+export { TySwitch, type TySwitchProps } from './TySwitch.ts'
+export { TyTag, type TyTagProps } from './TyTag.ts'
+export { TyTextArea, type TyTextAreaProps } from './TyTextArea.ts'
+export { TyTextField, type TyTextFieldProps } from './TyTextField.ts'
+export { TyThemePalette, type TyThemePaletteProps } from './TyThemePalette.ts'

package/src/elements/register.ts

@@ -0,0 +1,7 @@
+// Side-effect entry: registers every Tympan custom element when loaded in a
+// browser. The standalone bundle (dist/elements.bundle.js) is this module.
+import { defineTympanElements } from './index.ts'
+
+defineTympanElements()
+
+export * from './index.ts'

package/src/elements/section-heading/definition.ts

@@ -0,0 +1,81 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+/** `<ty-section-heading>`: the SectionHeading's single source (spec: wave-1/section-heading.md). */
+export const sectionHeadingDefinition = {
+  tag: 'ty-section-heading',
+  name: 'TySectionHeading',
+  kind: 'enhancing',
+  doc: 'Heads a section inside a page or a sheet: the title at the section level (h2 by default, h3 or h4 inside a sheet), an optional subtitle line (plain meta text, not a heading), an optional decorative leading icon, and a `trailing` slot for the section\'s own actions, a count, a toggle or a link. The title wraps by default; `truncate` clips it to one line with the full text as a tooltip. The heading id (`heading-id`, generated otherwise) lets the enclosing section name itself with `aria-labelledby`.',
+  props: {
+    title: { type: 'string', attribute: 'title', doc: 'Section name; the heading text, and the tooltip when `truncate` clips it.' },
+    level: { type: 'enum', values: ['2', '3', '4'], default: '2', attribute: 'level', doc: 'Heading level (2, 3 or 4, as its attribute spelling); level 2 uses the h2 step, 3 and 4 the h3 step (§2.2).' },
+    subtitle: { type: 'string', attribute: 'subtitle', doc: 'Supporting line under the title; plain meta text in reading order, not a heading.' },
+    truncate: { type: 'boolean', attribute: 'truncate', doc: 'Clip the title to one line with an ellipsis; the full text stays accessible and becomes the tooltip. Wraps by default.' },
+    headingId: { type: 'string', attribute: 'heading-id', doc: 'Id of the heading element, so the enclosing section can be a region labelled by it; `<instance>-heading` when unset.' },
+  },
+  events: [],
+  slots: {
+    icon: { doc: 'A decorative leading icon (`aria-hidden`).' },
+    trailing: { doc: 'Section actions, a count, a toggle or a link; follows the title in DOM order and wraps under it when it does not fit.' },
+    default: { doc: 'Extra content under the heading row.' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-section-heading',
+    attrs: {
+      'data-level': { prop: 'level' },
+    },
+    children: [
+      {
+        tag: 'div',
+        class: 'ty-section-heading__row',
+        children: [
+          {
+            tag: 'span',
+            class: 'ty-section-heading__icon',
+            when: ['slot:icon'],
+            attrs: { 'aria-hidden': { value: 'true' } },
+            children: [{ slot: 'icon' }],
+          },
+          {
+            tag: 'div',
+            class: 'ty-section-heading__text',
+            children: [
+              ...([2, 3, 4] as const).map((n): ElementNode => ({
+                tag: `h${n}`,
+                class: 'ty-section-heading__title',
+                when: [`level:${n}`],
+                attrs: {
+                  id: { idref: 'heading', prop: 'headingId' },
+                  'data-truncate': { prop: 'truncate', kind: 'flag' },
+                  title: { prop: 'title', when: ['truncate'] },
+                },
+                children: [{ text: { prop: 'title' } }],
+              })),
+              { tag: 'p', class: 'ty-section-heading__subtitle', when: ['subtitle'], children: [{ text: { prop: 'subtitle' } }] },
+            ],
+          },
+          {
+            tag: 'div',
+            class: 'ty-section-heading__trailing',
+            when: ['slot:trailing'],
+            children: [{ slot: 'trailing' }],
+          },
+        ],
+      },
+      {
+        tag: 'div',
+        class: 'ty-section-heading__extra',
+        when: ['slot:default'],
+        children: [{ slot: 'default' }],
+      },
+    ],
+  },
+  examples: [
+    { name: 'title', props: { title: 'Members' }, slots: {} },
+    { name: 'level-3-subtitle', props: { title: 'API keys', level: '3', subtitle: 'Keys of every integration' }, slots: {} },
+    { name: 'icon-trailing', props: { title: 'Webhooks' }, slots: { icon: '⚡', trailing: 'Add' } },
+    { name: 'truncate', props: { title: 'A section name that runs well past the width of its container', truncate: true }, slots: {} },
+    { name: 'extra', props: { title: 'Filters' }, slots: { trailing: 'Clear all', default: 'Status: active' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/section-heading/element.ts

@@ -0,0 +1,15 @@
+import { TyElement } from '../base.ts'
+import { sectionHeadingDefinition } from './definition.ts'
+
+/**
+ * `<ty-section-heading>`. All presentation: the host framework renders the
+ * anatomy (the heading row with icon, title, subtitle and trailing slot,
+ * plus the extra slot under it) and the stylesheet lays it out — the row
+ * wraps, so the trailing slot lands under the title when it does not fit.
+ * Not a widget — no keyboard or events; the base class builds and patches
+ * the anatomy for plain-HTML use (swapping the heading tag when `level`
+ * changes) and keeps the bound attributes in step.
+ */
+export class TySectionHeadingElement extends TyElement {
+  static override definition = sectionHeadingDefinition
+}

package/src/elements/segmented-control/definition.ts

@@ -0,0 +1,72 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-segmented-control>`: the SegmentedControl's single source (spec:
+ * wave-1/segmented-control.md).
+ *
+ * APG Radio Group: one tab stop on the selected segment, the arrow keys move
+ * the selection and the focus (wrapping, direction following the reading
+ * direction), Home/End jump. No live region — the `aria-checked` state
+ * conveys the change.
+ *
+ * The anatomy is the track only (the labelled group with its size, width and
+ * disabled states); the segments are a dynamic repetition the declarative
+ * anatomy cannot express, so the element composes them from `options` on
+ * upgrade, the way the skeleton composes its presets. The segment nodes the
+ * element renders mirror the React SegmentedControl exactly (`.ty-segmented-
+ * control__segment` with `data-selected`, a `.ty-segmented-control__label`
+ * span, an optional lucide-style stroke icon) so the one component CSS
+ * covers every renderer. `options` is a JSON array — a string is both value
+ * and label, an object is `{ value, label, icon? }` with `icon` the `d` of a
+ * 24×24 stroke path.
+ */
+export const segmentedControlDefinition = {
+  tag: 'ty-segmented-control',
+  name: 'TySegmentedControl',
+  kind: 'enhancing',
+  doc: 'Exactly one of a small set (two to five) of mutually exclusive options, changed in place — a radio group painted as segments. The segments are composed by the element from `options` (JSON); selecting the selected segment again does nothing. With `value` the control is controlled (the host answers `ty-change`); without it the element keeps the selection and mirrors it into the `value` attribute.',
+  props: {
+    options: { type: 'string', attribute: 'options', doc: 'The segments as a JSON array of `string` (both value and label) or `{ "value", "label", "icon"? }`; `icon` is the `d` of a 24×24 stroke path (lucide style).' },
+    value: { type: 'string', attribute: 'value', doc: 'The selected value (controlled). Unset, the element keeps the selection itself and mirrors it here.' },
+    defaultValue: { type: 'string', attribute: 'default-value', doc: 'The initially selected value when uncontrolled; the first option when unset.' },
+    label: { type: 'string', attribute: 'label', doc: 'Accessible name of the group (required).' },
+    size: { type: 'enum', values: ['compact', 'regular', 'large'], default: 'regular', attribute: 'size', doc: 'Visible height; the hit area stays at least 44 px on every size.' },
+    fullWidth: { type: 'boolean', attribute: 'full-width', doc: 'The segments share the available width equally; labels truncate with the full label as the accessible name.' },
+    disabled: { type: 'boolean', attribute: 'disabled', doc: 'The whole control disabled; the group is exposed as disabled and nothing selects.' },
+    iconOnly: { type: 'boolean', attribute: 'icon-only', doc: 'Hide the labels visually; each label stays the segment\'s accessible name.' },
+  },
+  events: [
+    { type: 'ty-change', kind: 'custom', detail: { value: 'string' }, reactProp: 'onChange', doc: 'The selection changed; `value` is the new value. Only real changes fire it — re-selecting the selected segment does nothing.' },
+  ],
+  anatomy: {
+    tag: 'div',
+    class: 'ty-segmented-control',
+    attrs: {
+      role: { value: 'radiogroup' },
+      'aria-label': { prop: 'label' },
+      'aria-disabled': { prop: 'disabled', kind: 'bool' },
+      'data-size': { prop: 'size' },
+      'data-full-width': { prop: 'fullWidth', kind: 'flag' },
+      'data-icon-only': { prop: 'iconOnly', kind: 'flag' },
+      'data-disabled': { prop: 'disabled', kind: 'flag' },
+    },
+    // The segments are composed by the element from `options`.
+    children: [],
+  },
+  examples: [
+    { name: 'period-week', props: { label: 'Period', options: '["Day","Week","Month"]', value: 'Week' }, slots: {} },
+    { name: 'objects-compact', props: { label: 'View', size: 'compact', defaultValue: 'chart', options: '[{"value":"table","label":"Table"},{"value":"chart","label":"Chart"}]' }, slots: {} },
+    { name: 'full-width-large', props: { label: 'Mode', size: 'large', fullWidth: true, options: '["Preview","Code"]' }, slots: {} },
+    { name: 'disabled', props: { label: 'Period', disabled: true, value: 'Day', options: '["Day","Week"]' }, slots: {} },
+    {
+      name: 'icon-only',
+      props: {
+        label: 'Layout',
+        iconOnly: true,
+        value: 'grid',
+        options: '[{"value":"list","label":"List","icon":"M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"},{"value":"grid","label":"Grid","icon":"M3 3h7v7H3zM14 3h7v7h-7zM14 14h7v7h-7zM3 14h7v7H3z"}]',
+      },
+      slots: {},
+    },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/segmented-control/element.ts

@@ -0,0 +1,253 @@
+import { TyElement } from '../base.ts'
+import { segmentedControlDefinition } from './definition.ts'
+
+const SVG = 'http://www.w3.org/2000/svg'
+
+/** One segment of the control: a string option is both value and label. */
+interface Segment {
+  value: string
+  label: string
+  /** The `d` of a 24×24 stroke path (lucide style). */
+  icon?: string
+}
+
+/**
+ * `<ty-segmented-control>`. The track (the labelled radio group with its
+ * size, width and disabled states) is the anatomy, rendered by the host
+ * framework or built from plain HTML; the element composes the segments from
+ * the `options` JSON — a dynamic repetition the declarative anatomy cannot
+ * express, the skeleton-preset pattern — and adds the behaviour (spec:
+ * wave-1/segmented-control.md):
+ *
+ * - **Selection** — a press selects the segment; selecting the selected one
+ *   again does nothing. With `value` the control is controlled: the element
+ *   only emits `ty-change` and the host answers with a new `value`. Without
+ *   it the element keeps the selection (starting at `default-value`, else
+ *   the first option) and mirrors it into the `value` attribute.
+ * - **Keyboard** — one tab stop (the selected segment); the arrow keys move
+ *   the selection and the focus, wrapping, Left/Right following the reading
+ *   direction; Home/End jump to the ends.
+ *
+ * The composed segments are the element's own (the anatomy has no children),
+ * so they are recomposed freely; nodes keyed by `data-value` are reused, so
+ * a framework-rendered tree keeps a focused segment across re-renders.
+ */
+export class TySegmentedControlElement extends TyElement {
+  static override definition = segmentedControlDefinition
+
+  /** Controlled from birth: `value` present when the element connected. */
+  #controlled = false
+
+  override sync(): void {
+    // The base patch pass prunes what the anatomy does not list — the
+    // composed segments — so the focus a keyboard move just landed is
+    // captured here and restored once the segments are recomposed.
+    const active = document.activeElement
+    const refocus =
+      active instanceof HTMLElement && this.contains(active) ? active.getAttribute('data-value') : null
+    super.sync()
+    this.#compose()
+    if (refocus !== null) {
+      const now = document.activeElement
+      const stillOnSegment = now instanceof Element && now.closest('.ty-segmented-control__segment') !== null
+      if (!stillOnSegment) this.#segmentFor(refocus)?.focus()
+    }
+  }
+
+  protected override connected(): void {
+    this.#controlled = this.hasAttribute('value')
+    this.addEventListener('click', this.#onClick)
+    this.addEventListener('keydown', this.#onKeydown)
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('click', this.#onClick)
+    this.removeEventListener('keydown', this.#onKeydown)
+  }
+
+  /** The parsed `options` JSON; an invalid value warns and renders nothing. */
+  #options(): Segment[] {
+    const raw = this.getAttribute('options')
+    if (!raw) return []
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (!Array.isArray(parsed)) throw new Error('not an array')
+      return parsed.flatMap((entry): Segment[] => {
+        if (typeof entry === 'string') return entry ? [{ value: entry, label: entry }] : []
+        if (entry && typeof entry === 'object') {
+          const { value, label, icon } = entry as Segment
+          if (typeof value === 'string' && value && typeof label === 'string') {
+            return [{ value, label, ...(typeof icon === 'string' ? { icon } : {}) }]
+          }
+        }
+        return []
+      })
+    } catch {
+      console.warn('<ty-segmented-control>: options must be a JSON array of strings or { "value", "label", "icon"? } objects.')
+      return []
+    }
+  }
+
+  /** The selected value: the controlled `value`, else `default-value`, else the first option. */
+  #current(options: Segment[]): string {
+    return this.getAttribute('value') ?? this.getAttribute('default-value') ?? options[0]?.value ?? ''
+  }
+
+  #segmentFor(value: string): HTMLElement | null {
+    return this.querySelector(`.ty-segmented-control__segment[data-value="${CSS.escape(value)}"]`)
+  }
+
+  /**
+   * Select `next`: emit `ty-change` on a real change only. Uncontrolled, the
+   * element mirrors the selection into `value` (which re-renders through the
+   * attribute change); controlled, the host answers the event. `moveFocus`
+   * (the arrow keys) lands the focus after any re-render.
+   */
+  #commit(next: string, moveFocus = false): void {
+    if (this.hasAttribute('disabled')) return
+    const options = this.#options()
+    if (!options.some((o) => o.value === next)) return
+    if (next !== this.#current(options)) {
+      // A short tick on touch devices, the React component's requestHaptic('light'); called from a user gesture.
+      try {
+        ;(navigator as Navigator & { vibrate?: (pattern: number) => boolean }).vibrate?.(8)
+      } catch {
+        /* unsupported */
+      }
+      // Uncontrolled (no `value` at birth): mirror freely — a one-shot
+      // mirror would freeze the selection after the first keyboard move.
+      // Controlled: the host answers ty-change by writing the attribute.
+      if (!this.#controlled) this.setAttribute('value', next)
+      this.emit('ty-change', { value: next })
+    }
+    if (moveFocus) this.#segmentFor(next)?.focus()
+  }
+
+  #onClick = (event: MouseEvent): void => {
+    if (!(event.target instanceof Element)) return
+    const segment = event.target.closest('.ty-segmented-control__segment')
+    if (!segment || !this.contains(segment)) return
+    const value = segment.getAttribute('data-value')
+    if (value !== null) this.#commit(value)
+  }
+
+  #onKeydown = (event: KeyboardEvent): void => {
+    if (this.hasAttribute('disabled')) return
+    if (!(event.target instanceof Element) || !event.target.closest('.ty-segmented-control__segment')) return
+    const options = this.#options()
+    if (!options.length) return
+    const rtl = this.#rtl()
+    let delta: number | null = null
+    switch (event.key) {
+      case 'ArrowRight':
+        delta = rtl ? -1 : 1
+        break
+      case 'ArrowLeft':
+        delta = rtl ? 1 : -1
+        break
+      case 'ArrowDown':
+        delta = 1
+        break
+      case 'ArrowUp':
+        delta = -1
+        break
+    }
+    const current = this.#current(options)
+    const from = Math.max(0, options.findIndex((o) => o.value === current))
+    let to: number
+    if (event.key === 'Home') to = 0
+    else if (event.key === 'End') to = options.length - 1
+    else if (delta !== null) to = (from + delta + options.length) % options.length
+    else return
+    event.preventDefault()
+    this.#commit(options[to]!.value, true)
+  }
+
+  /** The reading direction, from a `dir` attribute up the tree or the computed style. */
+  #rtl(): boolean {
+    const dir = this.closest('[dir]')?.getAttribute('dir') ?? document.documentElement.getAttribute('dir')
+    if (dir) return dir.toLowerCase() === 'rtl'
+    return getComputedStyle(this).direction === 'rtl'
+  }
+
+  /** Compose the segments into the track, reusing the nodes keyed by `data-value`. */
+  #compose(): void {
+    const root = this.anatomyRoot()
+    if (!root) return
+    const options = this.#options()
+    const current = this.#current(options)
+    const disabled = this.hasAttribute('disabled')
+    const iconOnly = this.hasAttribute('icon-only')
+    const stretched = this.hasAttribute('full-width')
+    const used = new Set<Element>()
+    const wanted: HTMLElement[] = []
+    for (const option of options) {
+      const existing = Array.from(root.children).find((c) => !used.has(c) && c.getAttribute('data-value') === option.value)
+      const segment = existing instanceof HTMLElement ? existing : this.#segment()
+      used.add(segment)
+      this.#syncSegment(segment, option, current === option.value, disabled, iconOnly, stretched)
+      wanted.push(segment)
+    }
+    wanted.forEach((segment, index) => {
+      if (root.children[index] !== segment) root.insertBefore(segment, root.children[index] ?? null)
+    })
+    while (root.children.length > wanted.length) root.lastElementChild!.remove()
+  }
+
+  #segment(): HTMLElement {
+    const button = document.createElement('button')
+    button.type = 'button'
+    button.setAttribute('role', 'radio')
+    button.className = 'ty-segmented-control__segment'
+    return button
+  }
+
+  /** Bring one segment in step, touching only what changed (a focused segment keeps focus). */
+  #syncSegment(segment: HTMLElement, option: Segment, selected: boolean, disabled: boolean, iconOnly: boolean, stretched: boolean): void {
+    segment.setAttribute('data-value', option.value)
+    segment.setAttribute('aria-checked', String(selected))
+    segment.toggleAttribute('data-selected', selected)
+    if (disabled) {
+      segment.setAttribute('disabled', '')
+      segment.setAttribute('data-disabled', '')
+      segment.tabIndex = -1
+    } else {
+      segment.removeAttribute('disabled')
+      segment.removeAttribute('data-disabled')
+      segment.tabIndex = selected ? 0 : -1
+    }
+    if (stretched) segment.setAttribute('title', option.label)
+    else segment.removeAttribute('title')
+    if (iconOnly) segment.setAttribute('aria-label', option.label)
+    else segment.removeAttribute('aria-label')
+
+    let icon = segment.querySelector(':scope > svg.ty-icon')
+    if (option.icon) {
+      if (!icon) {
+        icon = document.createElementNS(SVG, 'svg')
+        icon.setAttribute('class', 'ty-icon')
+        icon.setAttribute('viewBox', '0 0 24 24')
+        icon.setAttribute('fill', 'none')
+        icon.setAttribute('stroke', 'currentColor')
+        icon.setAttribute('stroke-width', '2')
+        icon.setAttribute('stroke-linecap', 'round')
+        icon.setAttribute('stroke-linejoin', 'round')
+        icon.setAttribute('aria-hidden', 'true')
+        icon.setAttribute('focusable', 'false')
+        icon.append(document.createElementNS(SVG, 'path'))
+        segment.prepend(icon)
+      }
+      const path = icon.querySelector('path')!
+      if (path.getAttribute('d') !== option.icon) path.setAttribute('d', option.icon)
+    } else icon?.remove()
+
+    let label = segment.querySelector(':scope > span')
+    if (!label) {
+      label = document.createElement('span')
+      segment.append(label)
+    }
+    const labelClass = iconOnly ? 'ty-visually-hidden' : 'ty-segmented-control__label'
+    if (label.getAttribute('class') !== labelClass) label.setAttribute('class', labelClass)
+    if (label.textContent !== option.label) label.textContent = option.label
+  }
+}

package/src/elements/separator/definition.ts

@@ -0,0 +1,44 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-separator>`: the Separator's single source (spec: wave-1/separator.md). */
+export const separatorDefinition = {
+  tag: 'ty-separator',
+  name: 'TySeparator',
+  kind: 'enhancing',
+  doc: 'Thin rule between groups of content, optionally with a short caption centred on it ("or"). Decorative by default (`aria-hidden`); `semantic` exposes the non-focusable separator role. A captioned rule keeps the caption readable as plain text and the strokes decorative, so it never carries the role.',
+  props: {
+    orientation: { type: 'enum', values: ['horizontal', 'vertical'], default: 'horizontal', attribute: 'orientation', doc: 'Direction of the rule; vertical takes the height of its row.' },
+    emphasis: { type: 'enum', values: ['regular', 'soft'], default: 'regular', attribute: 'emphasis', doc: 'Line strength: `--ty-line` or the fainter `--ty-line-soft`.' },
+    semantic: { type: 'boolean', attribute: 'semantic', doc: 'Exposes the separator role (with `aria-orientation`); decorative otherwise.' },
+    spacing: { type: 'enum', values: ['none', 'regular', 'roomy'], default: 'regular', attribute: 'spacing', doc: 'Margin step from the spacing scale.' },
+  },
+  events: [],
+  slots: {
+    caption: { doc: 'Short text centred on the rule, such as "or"; readable plain text between the two decorative strokes.' },
+  },
+  anatomy: {
+    tag: 'div',
+    class: 'ty-separator',
+    attrs: {
+      role: { value: 'separator', when: ['semantic', '!slot:caption'] },
+      'aria-orientation': { prop: 'orientation', when: ['semantic', '!slot:caption'] },
+      'aria-hidden': { value: 'true', when: ['!semantic', '!slot:caption'] },
+      'data-orientation': { prop: 'orientation' },
+      'data-emphasis': { prop: 'emphasis' },
+      'data-spacing': { prop: 'spacing' },
+      'data-captioned': { value: '', when: ['slot:caption'] },
+    },
+    children: [
+      { tag: 'span', class: 'ty-separator__line', attrs: { 'aria-hidden': { value: 'true' } }, when: ['slot:caption'] },
+      { tag: 'span', class: 'ty-separator__caption', when: ['slot:caption'], children: [{ slot: 'caption' }] },
+      { tag: 'span', class: 'ty-separator__line', attrs: { 'aria-hidden': { value: 'true' } }, when: ['slot:caption'] },
+    ],
+  },
+  examples: [
+    { name: 'decorative', props: {}, slots: {} },
+    { name: 'semantic', props: { semantic: true }, slots: {} },
+    { name: 'semantic-vertical', props: { semantic: true, orientation: 'vertical' }, slots: {} },
+    { name: 'soft-roomy', props: { emphasis: 'soft', spacing: 'roomy' }, slots: {} },
+    { name: 'caption', props: {}, slots: { caption: 'or' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/separator/element.ts

@@ -0,0 +1,13 @@
+import { TyElement } from '../base.ts'
+import { separatorDefinition } from './definition.ts'
+
+/**
+ * `<ty-separator>`. All presentation: the host framework renders the anatomy
+ * (the rule, or two strokes around a readable caption) and the stylesheet
+ * draws it, including the forced-colours fallback. Not a widget — no
+ * keyboard or events; the base class builds and patches the anatomy for
+ * plain-HTML use and keeps the bound attributes in step.
+ */
+export class TySeparatorElement extends TyElement {
+  static override definition = separatorDefinition
+}