@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/avatar/definition.ts

@@ -0,0 +1,161 @@
+import type { ElementDefinition, ElementNode } from '../definition.ts'
+
+/** A lucide glyph (ISC, THIRD_PARTY_NOTICES): every child carries a class so the element's patch pass can match it. */
+const glyph = (tag: string, attrs: Record<string, string>): ElementNode => ({
+  tag,
+  class: 'ty-avatar__glyph',
+  attrs: Object.fromEntries(Object.entries(attrs).map(([name, value]) => [name, { value }])),
+})
+
+/** A decorative fallback icon (lucide strokes), sized by the frame's `.ty-avatar__icon` rule. */
+const icon = (children: ElementNode[], when: string[]): ElementNode => ({
+  tag: 'svg',
+  class: 'ty-avatar__icon',
+  when,
+  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,
+})
+
+/**
+ * The picture and the fallback it covers, shared by the static frame and
+ * the two pressable controls. The fallback is `hidden` while the picture
+ * holds; the element swaps them when the picture fails.
+ */
+const content = (): ElementNode[] => [
+  // The picture. Decorative, or inside a named control: no text of its own.
+  {
+    tag: 'img',
+    class: 'ty-avatar__image',
+    when: ['src', 'decorative|pressable|href'],
+    attrs: { src: { prop: 'src' }, alt: { value: '' } },
+  },
+  {
+    tag: 'img',
+    class: 'ty-avatar__image',
+    when: ['src', '!decorative', '!pressable', '!href'],
+    attrs: { src: { prop: 'src' }, alt: { prop: 'name' } },
+  },
+  {
+    tag: 'span',
+    class: 'ty-avatar__fallback',
+    attrs: { hidden: { value: '', when: ['src'] } },
+    children: [
+      // Agents: a bot mark, never initials (§2.11).
+      icon(
+        [
+          glyph('path', { d: 'M12 8V4H8' }),
+          glyph('rect', { width: '16', height: '12', x: '4', y: '8', rx: '2' }),
+          glyph('path', { d: 'M2 14h2' }),
+          glyph('path', { d: 'M20 14h2' }),
+          glyph('path', { d: 'M15 13v2' }),
+          glyph('path', { d: 'M9 13v2' }),
+        ],
+        ['actorKind:agent'],
+      ),
+      {
+        tag: 'span',
+        class: 'ty-avatar__initials',
+        when: ['actorKind:person', 'fallbackText'],
+        attrs: { 'aria-hidden': { value: 'true' } },
+        children: [{ text: { prop: 'fallbackText' } }],
+      },
+      icon(
+        [
+          glyph('path', { d: 'M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2' }),
+          glyph('circle', { cx: '12', cy: '7', r: '4' }),
+        ],
+        ['actorKind:person', '!fallbackText'],
+      ),
+    ],
+  },
+]
+
+/** The frame (circle or agent square); the static one carries the img role and the name. */
+const frame = (when: string[], pressable: boolean): ElementNode => ({
+  tag: 'span',
+  class: 'ty-avatar',
+  when: when.length ? when : undefined,
+  attrs: pressable
+    ? {
+        'data-kind': { prop: 'actorKind' },
+        'data-size': { prop: 'size' },
+        'data-tint': { prop: 'tint' },
+        'data-image': { value: '', when: ['src'] },
+        // Inside a named control the visual is decorative.
+        'aria-hidden': { value: 'true' },
+      }
+    : {
+        'data-kind': { prop: 'actorKind' },
+        'data-size': { prop: 'size' },
+        'data-tint': { prop: 'tint' },
+        'data-image': { value: '', when: ['src'] },
+        'aria-hidden': { value: 'true', when: ['decorative'] },
+        role: { value: 'img', when: ['!decorative', '!src'] },
+        'aria-label': { prop: 'name', when: ['!decorative', '!src'] },
+      },
+  children: content(),
+})
+
+/** `<ty-avatar>`: the Avatar's single source (spec: wave-1/avatar.md). */
+export const avatarDefinition = {
+  tag: 'ty-avatar',
+  name: 'TyAvatar',
+  kind: 'enhancing',
+  doc: 'Represents a person or an agent with a picture or fallback initials, optionally as a pressable control. Static, the frame is an image role named by `name` (hidden when `decorative`); pressable, it is a link (`href`) or a button (`pressable`) named by `actionLabel`, with a 44 px hit area at every size. The fallback (initials for a person, a bot mark for an agent, a user mark otherwise) shows while there is no picture and when the picture fails to load.',
+  props: {
+    src: { type: 'string', attribute: 'src', doc: 'Image URL; on load error the fallback shows.' },
+    fallbackText: { type: 'string', attribute: 'fallback-text', doc: 'One or two characters shown when there is no image (derived by the host from a name); the element keeps the first two grapheme clusters.' },
+    name: { type: 'string', attribute: 'name', doc: 'Accessible name; required unless `decorative`. Initials are never read as letters while it is set.' },
+    decorative: { type: 'boolean', attribute: 'decorative', doc: 'Hides the avatar from assistive tech when the name is already shown next to it.' },
+    actorKind: { type: 'enum', values: ['person', 'agent'], default: 'person', attribute: 'actor-kind', doc: '`person`: circle with initials. `agent`: rounded square with a bot icon and a dashed border, never initials (§2.11).' },
+    size: { type: 'enum', values: ['xsmall', 'small', 'regular', 'large'], default: 'regular', attribute: 'size', doc: 'Size step.' },
+    tint: { type: 'enum', values: ['accent', 'neutral'], default: 'accent', attribute: 'tint', doc: 'Fallback background: accent-soft or neutral (§2.3).' },
+    pressable: { type: 'boolean', attribute: 'pressable', doc: 'The avatar is one press target (a button); set it when `onPress` is wired. Implied by `href`.' },
+    href: { type: 'string', attribute: 'href', doc: 'Makes the avatar a link to this destination (wins over `pressable`).' },
+    actionLabel: { type: 'string', default: 'Open profile of {name}', attribute: 'action-label', doc: 'Accessible name of a pressable avatar; `{name}` is filled in. Translate through this attribute.' },
+  },
+  events: [{ type: 'click', kind: 'native', reactProp: 'onPress', doc: 'The native click of the pressable avatar (its link or button).' }],
+  anatomy: {
+    // A boxless root (display: contents): the static frame and the two
+    // pressable controls are mutually exclusive alternatives (the surface's
+    // link-or-button precedent); only one renders at a time.
+    tag: 'span',
+    class: 'ty-avatar-root',
+    attrs: {},
+    children: [
+      frame(['!pressable', '!href'], false),
+      {
+        tag: 'a',
+        class: 'ty-avatar-control',
+        when: ['href'],
+        attrs: { href: { prop: 'href' }, 'data-size': { prop: 'size' } },
+        children: [frame([], true)],
+      },
+      {
+        tag: 'button',
+        class: 'ty-avatar-control',
+        when: ['!href', 'pressable'],
+        attrs: { type: { value: 'button' }, 'data-size': { prop: 'size' } },
+        children: [frame([], true)],
+      },
+    ],
+  },
+  examples: [
+    { name: 'initials', props: { name: 'Natália Mesquita', fallbackText: 'NM' }, slots: {} },
+    { name: 'image', props: { src: '/avatars/natalia.png', name: 'Natália Mesquita', fallbackText: 'NM' }, slots: {} },
+    { name: 'agent', props: { actorKind: 'agent', name: 'stage-counter', size: 'small' }, slots: {} },
+    { name: 'decorative-neutral', props: { decorative: true, fallbackText: 'NM', tint: 'neutral' }, slots: {} },
+    { name: 'pressable', props: { pressable: true, name: 'Natália Mesquita', fallbackText: 'NM' }, slots: {} },
+    { name: 'link', props: { href: '/users/natalia', name: 'Natália Mesquita', src: '/avatars/natalia.png' }, slots: {} },
+    { name: 'translated-action', props: { pressable: true, name: 'Natália Mesquita', fallbackText: 'NM', actionLabel: 'Abrir perfil de {name}' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/avatar/element.ts

@@ -0,0 +1,112 @@
+import { TyElement } from '../base.ts'
+import { avatarDefinition } from './definition.ts'
+
+/** The first `count` user-perceived characters (grapheme clusters), so marks and emoji stay whole. */
+function leadingGraphemes(text: string, count: number): string {
+  const Segmenter = (Intl as { Segmenter?: typeof Intl.Segmenter }).Segmenter
+  if (!Segmenter) return Array.from(text).slice(0, count).join('')
+  let out = ''
+  let taken = 0
+  for (const { segment } of new Segmenter(undefined, { granularity: 'grapheme' }).segment(text)) {
+    if (taken === count) break
+    out += segment
+    taken += 1
+  }
+  return out
+}
+
+/**
+ * `<ty-avatar>`. The anatomy (the frame with its picture and fallback, or a
+ * link/button control around it) is purely presentational; the element adds
+ * what load state and naming need (spec: wave-1/avatar.md):
+ *
+ * - **Image failure** — an `error` from the picture swaps it for the
+ *   fallback (both are always rendered; `hidden` picks the visible one),
+ *   drops `data-image`, and a static frame takes `role="img"` with the
+ *   name, exactly as if no `src` were given. A new `src` resets.
+ * - **Naming** — a pressable control is named from `action-label` with
+ *   `{name}` filled in ("Open profile of {name}"); the frame inside stays
+ *   `aria-hidden`, so the initials are never read as letters.
+ * - **Initials** — the fallback text is kept to two grapheme clusters.
+ */
+export class TyAvatarElement extends TyElement {
+  static override definition = avatarDefinition
+
+  /** The src whose picture failed to load; a different src resets. */
+  #failedFor: string | null = null
+
+  #onError = (event: Event) => {
+    const target = event.target
+    if (!(target instanceof HTMLImageElement) || !this.contains(target)) return
+    this.#failedFor = target.getAttribute('src')
+    this.#applyImageState()
+  }
+
+  /** Picture vs fallback, `data-image`, and the static frame's img role after a failure. */
+  #applyImageState = () => {
+    const src = this.getAttribute('src')
+    const failed = src !== null && src === this.#failedFor
+    const decorative = this.hasAttribute('decorative')
+    const pressable = this.hasAttribute('pressable') || this.hasAttribute('href')
+    for (const frame of this.querySelectorAll('.ty-avatar')) {
+      const image = frame.querySelector('img')
+      if (image) {
+        image.toggleAttribute('hidden', failed)
+        // The anatomy leaves `alt` out only when there is no name to give.
+        if (!image.hasAttribute('alt')) image.setAttribute('alt', '')
+      }
+      frame.querySelector('.ty-avatar__fallback')?.toggleAttribute('hidden', src !== null && !failed)
+      frame.toggleAttribute('data-image', src !== null && !failed)
+      if (!decorative && !pressable && (src === null || failed)) {
+        frame.setAttribute('role', 'img')
+        const name = this.getAttribute('name')
+        if (name) frame.setAttribute('aria-label', name)
+      } else if (src !== null && !failed) {
+        frame.removeAttribute('role')
+        frame.removeAttribute('aria-label')
+      }
+    }
+  }
+
+  /** The control's accessible name: the action label with the name filled in. */
+  #applyLabel = () => {
+    const control = this.querySelector('.ty-avatar-control')
+    if (!control) return
+    const label = String(this.props.actionLabel ?? '')
+      .replaceAll('{name}', this.getAttribute('name') ?? '')
+      .trim()
+    if (label) control.setAttribute('aria-label', label)
+    else control.removeAttribute('aria-label')
+  }
+
+  /** Initials are one or two grapheme clusters, however long the attribute. */
+  #applyInitials = () => {
+    const text = this.getAttribute('fallback-text')
+    if (text === null) return
+    const short = leadingGraphemes(text, 2)
+    for (const initials of this.querySelectorAll('.ty-avatar__initials')) {
+      if (initials.textContent !== short) initials.textContent = short
+    }
+  }
+
+  protected override connected(): void {
+    if (!this.hasAttribute('decorative') && !this.hasAttribute('name')) {
+      console.warn('<ty-avatar>: `name` is required unless `decorative`.')
+    }
+    this.addEventListener('error', this.#onError, { capture: true })
+    this.#applyImageState()
+    this.#applyLabel()
+    this.#applyInitials()
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('error', this.#onError, { capture: true })
+  }
+
+  protected override changed(): void {
+    if (!this.isConnected) return
+    this.#applyImageState()
+    this.#applyLabel()
+    this.#applyInitials()
+  }
+}

package/src/elements/base.ts

@@ -0,0 +1,244 @@
+// Base class of every Tympan custom element (light DOM, no shadow root).
+//
+// An *enhancing* element finds its anatomy already rendered by the host
+// framework (from the same definition, through a generated wrapper) and only
+// keeps the bound attributes in step and adds behaviour: it never moves or
+// replaces a node the framework owns. Used from plain HTML with just its
+// content (`<ty-button variant="primary">Save</ty-button>`), it builds the
+// anatomy itself once, moving its children into the slots, and from then on
+// re-renders it on every attribute change.
+//
+// A *self-rendering* element owns its whole subtree; frameworks render an
+// empty host and pass data as attributes.
+
+import { bindingValue, holds, withDefaults, type ElementDefinition, type ElementNode, type AnatomyNode, type Props } from './definition.ts'
+
+let instances = 0
+
+// Outside a browser (server rendering, the generator) there is no
+// HTMLElement to extend; the classes still load, and are never defined.
+const ElementBase = (typeof HTMLElement === 'undefined' ? class {} : HTMLElement) as typeof HTMLElement
+
+const firstClass = (node: ElementNode) => (node.class ?? '').split(/\s+/)[0] ?? ''
+
+export abstract class TyElement extends ElementBase {
+  static definition: ElementDefinition
+
+  static get observedAttributes(): string[] {
+    return [...Object.values(this.definition.props).map((p) => p.attribute), 'data-ty-instance']
+  }
+
+  #instance: string | undefined
+  #owned = false
+  #slots = new Map<string, Node[]>()
+
+  get definition(): ElementDefinition {
+    return (this.constructor as typeof TyElement).definition
+  }
+
+  /** Suffix base of the ids the anatomy needs (`aria-describedby`); wrappers pass theirs as `data-ty-instance`. */
+  get instanceId(): string {
+    return this.getAttribute('data-ty-instance') || this.id || (this.#instance ??= `ty-${++instances}`)
+  }
+
+  /** The current props, read from the host attributes, defaults applied. */
+  get props(): Props {
+    const out: Props = {}
+    for (const [name, prop] of Object.entries(this.definition.props)) {
+      if (prop.type === 'boolean') out[name] = this.hasAttribute(prop.attribute)
+      else {
+        const raw = this.getAttribute(prop.attribute)
+        if (raw !== null) out[name] = prop.type === 'number' ? Number(raw) : raw
+      }
+    }
+    return withDefaults(this.definition, out)
+  }
+
+  /** Whether this element built its own anatomy (plain HTML use). */
+  get owned(): boolean {
+    return this.#owned
+  }
+
+  connectedCallback(): void {
+    if (this.definition.kind === 'enhancing' && this.definition.anatomy) {
+      if (!this.anatomyRoot()) this.#adopt()
+      this.sync()
+    }
+    this.connected()
+  }
+
+  disconnectedCallback(): void {
+    this.disconnected()
+  }
+
+  attributeChangedCallback(): void {
+    if (this.isConnected && this.definition.kind === 'enhancing') this.sync()
+    this.changed()
+  }
+
+  /** Hooks for subclasses. */
+  protected connected(): void {}
+  protected disconnected(): void {}
+  protected changed(): void {}
+
+  /** The anatomy's root element, when it is rendered. */
+  anatomyRoot(): HTMLElement | null {
+    const anatomy = this.definition.anatomy
+    if (!anatomy) return null
+    for (const child of Array.from(this.children)) if (child.classList.contains(firstClass(anatomy))) return child as HTMLElement
+    return null
+  }
+
+  /** Bring the anatomy in step with the props. */
+  sync(): void {
+    const anatomy = this.definition.anatomy
+    if (!anatomy) return
+    if (this.#owned) {
+      this.#patch(anatomy)
+      return
+    }
+    // Framework-rendered: only the attributes of the parts that exist.
+    const props = this.props
+    const filled = this.#filledSlots()
+    const visit = (node: ElementNode, element: Element) => {
+      for (const [name, binding] of Object.entries(node.attrs ?? {})) {
+        // A control's live state belongs to the framework that renders it.
+        if (LIVE.has(name) && 'kind' in binding && binding.kind === 'boolean-attr') continue
+        const value = bindingValue(binding, props, filled, this.instanceId)
+        if (value === undefined) element.removeAttribute(name)
+        else if (element.getAttribute(name) !== value) element.setAttribute(name, value)
+      }
+      // Same-class siblings (an icon's glyphs) each match their own
+      // counterpart; `used` keeps the second path off the first.
+      const used = new Set<Element>()
+      for (const child of node.children ?? []) {
+        if (!('tag' in child) || !child.class) continue
+        const match = Array.from(element.children).find((c) => !used.has(c) && c.classList.contains(firstClass(child)))
+        if (match) {
+          used.add(match)
+          visit(child, match)
+        }
+      }
+    }
+    const root = this.anatomyRoot()
+    if (root) visit(anatomy, root)
+  }
+
+  /** Dispatch a bubbling, composed CustomEvent. */
+  protected emit(type: string, detail?: unknown): boolean {
+    return this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true, cancelable: true }))
+  }
+
+  #filledSlots(): Set<string> {
+    if (this.#owned) return new Set([...this.#slots].filter(([, nodes]) => nodes.some(isContent)).map(([name]) => name))
+    // Framework-rendered: a slot is filled when its part is rendered with content.
+    const filled = new Set<string>()
+    const walk = (node: AnatomyNode, element: Element | null) => {
+      if ('slot' in node) {
+        if (element && Array.from(element.childNodes).some(isContent)) filled.add(node.slot)
+        return
+      }
+      if (!('tag' in node)) return
+      for (const child of node.children ?? []) {
+        if ('slot' in child) walk(child, element)
+        else if (element && 'tag' in child && child.class) walk(child, Array.from(element.children).find((c) => c.classList.contains(firstClass(child))) ?? null)
+      }
+    }
+    if (this.definition.anatomy) walk(this.definition.anatomy, this.anatomyRoot())
+    return filled
+  }
+
+  /** Plain HTML: take the children as slot content and build the anatomy. */
+  #adopt(): void {
+    for (const node of Array.from(this.childNodes)) {
+      const slot = node instanceof Element && node.hasAttribute('slot') ? node.getAttribute('slot')! : 'default'
+      const list = this.#slots.get(slot) ?? []
+      list.push(node)
+      this.#slots.set(slot, list)
+    }
+    this.#owned = true
+  }
+
+  /**
+   * Plain HTML: render the anatomy into this element, reusing every node
+   * that is still wanted (matched by class) so a focused control keeps
+   * focus, and moving only what changed.
+   */
+  #patch(anatomy: ElementNode): void {
+    const props = this.props
+    const filled = this.#filledSlots()
+    const render = (node: AnatomyNode, existing: Element | null, svg: boolean): Node[] => {
+      if (!holds(node.when, props, filled)) return []
+      if ('slot' in node) return this.#slots.get(node.slot) ?? []
+      if ('text' in node) {
+        const value = props[node.text.prop]
+        return value === undefined || value === false || value === '' ? [] : [document.createTextNode(String(value))]
+      }
+      const inSvg = svg || node.tag === 'svg'
+      const element = existing ?? (inSvg ? document.createElementNS(SVG_NS, node.tag) : document.createElement(node.tag))
+      if (!existing && node.class) element.setAttribute('class', node.class)
+      for (const [name, binding] of Object.entries(node.attrs ?? {})) {
+        const value = bindingValue(binding, props, filled, this.instanceId)
+        // After the first render a control's state is its property: the
+        // attribute stays the initial state a form reset returns to.
+        if (existing && LIVE.has(name) && 'kind' in binding && binding.kind === 'boolean-attr') {
+          ;(element as unknown as Record<string, boolean>)[name] = value !== undefined
+          continue
+        }
+        if (value === undefined) element.removeAttribute(name)
+        else if (element.getAttribute(name) !== value) element.setAttribute(name, value)
+      }
+      const used = new Set<Element>()
+      const wanted: Node[] = []
+      for (const child of node.children ?? []) {
+        if ('slot' in child || 'text' in child) {
+          wanted.push(...render(child, null, inSvg))
+          continue
+        }
+        const match = Array.from(element.children).find((c) => !used.has(c) && c.localName === child.tag && c.classList.contains(firstClass(child))) ?? null
+        if (match) used.add(match)
+        wanted.push(...render(child, match, inSvg))
+      }
+      wanted.forEach((child, index) => {
+        if (element.childNodes[index] !== child) element.insertBefore(child, element.childNodes[index] ?? null)
+      })
+      while (element.childNodes.length > wanted.length) element.lastChild!.remove()
+      return [element]
+    }
+    const root = this.anatomyRoot()
+    const built = render(anatomy, root, false)[0]
+    if (built && built !== root) this.replaceChildren(built)
+  }
+}
+
+/** Attributes whose live value is a property (`checked`), not the attribute. */
+const LIVE = new Set(['checked', 'selected'])
+
+/** Anatomy in the SVG namespace (icons): created with `createElementNS` so plain-HTML use renders it. */
+const SVG_NS = 'http://www.w3.org/2000/svg'
+
+const isContent = (node: Node) => node.nodeType !== Node.TEXT_NODE || (node.textContent ?? '').trim() !== ''
+
+/** Define `cls` under its tag, with a property accessor per definition prop. Idempotent. */
+export function defineTympanElement(cls: typeof TyElement & (new () => TyElement)): void {
+  const def = cls.definition
+  if (typeof customElements === 'undefined' || customElements.get(def.tag)) return
+  for (const [name, prop] of Object.entries(def.props)) {
+    if (Object.prototype.hasOwnProperty.call(cls.prototype, name)) continue
+    Object.defineProperty(cls.prototype, name, {
+      configurable: true,
+      get(this: HTMLElement) {
+        if (prop.type === 'boolean') return this.hasAttribute(prop.attribute)
+        const raw = this.getAttribute(prop.attribute)
+        if (raw === null) return prop.default
+        return prop.type === 'number' ? Number(raw) : raw
+      },
+      set(this: HTMLElement, value: unknown) {
+        if (prop.type === 'boolean') this.toggleAttribute(prop.attribute, Boolean(value))
+        else if (value === null || value === undefined) this.removeAttribute(prop.attribute)
+        else this.setAttribute(prop.attribute, String(value))
+      },
+    })
+  }
+  customElements.define(def.tag, cls)
+}

package/src/elements/brand-wordmark/definition.ts

@@ -0,0 +1,37 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-brand-wordmark>`: the BrandWordmark's single source (element-first; see docs/design/single-source-components.md). */
+export const brandWordmarkDefinition = {
+  tag: 'ty-brand-wordmark',
+  name: 'TyBrandWordmark',
+  kind: 'enhancing',
+  doc: 'Two-tone product wordmark: the plain part (`text`) in ink and the accent part (`accent`) in the brand gradient (`background-clip: text`). Plain text for assistive tech as-is; `label` turns it into an img role with that name (a logo lockup).',
+  props: {
+    text: { type: 'string', attribute: 'text', doc: 'The plain part of the wordmark, in ink.' },
+    accent: { type: 'string', attribute: 'accent', doc: 'The accent part of the wordmark, in the brand gradient; rendered right after `text`.' },
+    size: { type: 'enum', values: ['small', 'medium', 'large'], default: 'medium', attribute: 'size', doc: 'Type step of the wordmark.' },
+    label: { type: 'string', attribute: 'label', doc: 'Accessible name as an img role (a logo lockup); left out, the wordmark is plain text read as-is.' },
+    testId: { type: 'string', attribute: 'test-id', doc: 'Test hook on the wordmark (`data-testid`).' },
+  },
+  events: [],
+  anatomy: {
+    tag: 'span',
+    class: 'ty-brand-wordmark',
+    attrs: {
+      role: { value: 'img', when: ['label'] },
+      'aria-label': { prop: 'label' },
+      'data-size': { prop: 'size' },
+      'data-testid': { prop: 'testId' },
+    },
+    children: [
+      { tag: 'span', class: 'ty-brand-wordmark__text', when: ['text'], children: [{ text: { prop: 'text' } }] },
+      { tag: 'span', class: 'ty-brand-wordmark__accent', when: ['accent'], children: [{ text: { prop: 'accent' } }] },
+    ],
+  },
+  examples: [
+    { name: 'default', props: { text: 'North', accent: 'star' }, slots: {} },
+    { name: 'small', props: { text: 'North', accent: 'star', size: 'small' }, slots: {} },
+    { name: 'large-labelled', props: { text: 'North', accent: 'star', size: 'large', label: 'Northstar' }, slots: {} },
+    { name: 'accent-only', props: { accent: 'Solo' }, slots: {} },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/brand-wordmark/element.ts

@@ -0,0 +1,13 @@
+import { TyElement } from '../base.ts'
+import { brandWordmarkDefinition } from './definition.ts'
+
+/**
+ * `<ty-brand-wordmark>`. All presentation: the host framework renders the
+ * anatomy (ink text, gradient accent) 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 TyBrandWordmarkElement extends TyElement {
+  static override definition = brandWordmarkDefinition
+}

package/src/elements/breadcrumbs/definition.ts

@@ -0,0 +1,85 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-breadcrumbs>`: the Breadcrumbs' single source (spec: wave-1/breadcrumbs.md).
+ *
+ * The anatomy is the chrome both modes share: the labelled navigation
+ * landmark, the trail's ordered list and the compact bar with its slots.
+ * The element composes what the definition language cannot express (the
+ * skeleton preset precedent): the trail items from the JSON `items`, the
+ * collapsed overflow menu (`maxVisible`), the compact back link and title,
+ * and the resolution of `mode="auto"` against the 640 px breakpoint (§2.8).
+ * Examples therefore carry no `items` — the composed items could not be
+ * produced by the parity renderers.
+ */
+export const breadcrumbsDefinition = {
+  tag: 'ty-breadcrumbs',
+  name: 'TyBreadcrumbs',
+  kind: 'enhancing',
+  doc: 'Shows where the current page sits in the hierarchy and goes up one or more levels. A trail at 640 px and above, a compact back link (with optional centred title and trailing actions) below. The last item is the current page — static text marked `aria-current="page"`, never a link; separators are decorative. Long labels truncate with an ellipsis, the full label kept in `title` and as the accessible name. Activating a link emits a cancelable `ty-navigate`: a host with a client-side router prevents the default and navigates through its adapter.',
+  props: {
+    items: { type: 'string', attribute: 'items', doc: 'JSON array of `{ "label": string, "href": string }`, ancestors first and the current page last. Composed by the element on upgrade (the theme palette\'s `theme-labels` precedent).' },
+    label: { type: 'string', default: 'Breadcrumb', attribute: 'label', doc: 'Accessible name of the navigation landmark (the I18n adapter\'s default); translate through this attribute.' },
+    mode: { type: 'enum', values: ['trail', 'compact', 'auto'], default: 'auto', attribute: 'mode', doc: '`auto` shows the trail at 640 px and above, the compact bar below; the element resolves it live.' },
+    rootHref: { type: 'string', attribute: 'root-href', doc: 'Parent href of the compact back link when there is only one item.' },
+    rootLabel: { type: 'string', attribute: 'root-label', doc: 'Parent label of the compact back link when there is only one item (with `rootHref`).' },
+    maxVisible: { type: 'number', attribute: 'max-visible', doc: 'Collapses middle items into an overflow menu when the trail exceeds this many entries (the first and the last `maxVisible - 1` stay visible).' },
+    backLabel: { type: 'string', default: 'Back to {parent}', attribute: 'back-label', doc: 'Accessible-name template of the compact back link; `{parent}` is filled with the parent\'s label.' },
+    overflowLabel: { type: 'string', default: 'Show hidden levels', attribute: 'overflow-label', doc: 'Accessible name of the overflow menu\'s toggle; translate through this attribute.' },
+  },
+  events: [
+    { type: 'ty-navigate', kind: 'custom', detail: { href: 'string' }, reactProp: 'onNavigate', doc: 'A trail, overflow or back link was activated; `href` is its destination. Cancelable: a host with a client-side router calls `preventDefault()` and navigates through its adapter; uncanceled, the native anchor navigates.' },
+  ],
+  slots: {
+    center: { doc: 'Replaces the centred title of the compact bar (the current page\'s label when empty).' },
+    actions: { doc: 'Trailing actions of the compact bar (narrow screens use it as a top bar).' },
+  },
+  anatomy: {
+    tag: 'nav',
+    class: 'ty-breadcrumbs',
+    attrs: {
+      'aria-label': { prop: 'label' },
+      // The raw mode; the element resolves `auto` into `trail`/`compact` on upgrade.
+      'data-mode': { prop: 'mode' },
+    },
+    children: [
+      // The trail's list: the element composes the items into it. Rendered
+      // for `trail` and `auto`; `auto` below 640 px hides it on upgrade.
+      { tag: 'ol', class: 'ty-breadcrumbs__list', when: ['!mode:compact'] },
+      // The compact bar: the element composes the back link and the title.
+      {
+        tag: 'div',
+        class: 'ty-breadcrumbs__bar',
+        when: ['mode:compact|mode:auto'],
+        children: [
+          { tag: 'div', class: 'ty-breadcrumbs__back' },
+          {
+            tag: 'div',
+            class: 'ty-breadcrumbs__center',
+            when: ['slot:center|slot:actions'],
+            children: [
+              { slot: 'center', when: ['slot:center'] },
+              {
+                tag: 'span',
+                class: 'ty-breadcrumbs__title',
+                when: ['!slot:center'],
+                attrs: { 'aria-current': { value: 'page' } },
+              },
+            ],
+          },
+          {
+            tag: 'div',
+            class: 'ty-breadcrumbs__actions',
+            when: ['slot:actions'],
+            children: [{ slot: 'actions' }],
+          },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'auto-empty', props: {}, slots: {} },
+    { name: 'trail-empty', props: { mode: 'trail' }, slots: {} },
+    { name: 'compact-bar', props: { mode: 'compact' }, slots: { center: 'Sources', actions: 'Share' } },
+  ],
+} as const satisfies ElementDefinition