@datatechsolutions/tympan 0.3.0 → 0.4.0

package/src/elements/tag/definition.ts

@@ -0,0 +1,69 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/** `<ty-tag>`: the Tag's single source (spec: wave-1/tag.md). */
+export const tagDefinition = {
+  tag: 'ty-tag',
+  name: 'TyTag',
+  kind: 'enhancing',
+  doc: 'Small label for static metadata (a badge or chip), optionally removable; the remove button is a native <button>. An interactive tag (pressable or a link) is a plain styled native — <button class="ty-tag" data-interactive> or <a class="ty-tag" href> — not this element (see docs/html-contract.md).',
+  props: {
+    tone: { type: 'enum', values: ['neutral', 'accent'], default: 'neutral', attribute: 'tone', doc: '`accent` fills with the theme accent.' },
+    categoryIndex: { type: 'number', attribute: 'category-index', doc: 'A categorical token (1 to 8) shown as a small colour square; normalised into range on upgrade.' },
+    size: { type: 'enum', values: ['small', 'regular', 'large'], default: 'regular', attribute: 'size', doc: 'Text step; `small` never goes below the meta size.' },
+    removable: { type: 'boolean', attribute: 'removable', doc: 'Shows the remove button at the end.' },
+    removeLabel: { type: 'string', attribute: 'remove-label', doc: 'Accessible name of the remove button; must include the tag text (defaults to "Remove <text>" on upgrade).' },
+    live: { type: 'boolean', attribute: 'live', doc: 'A polite live region (`role="status"`) for a tag whose text updates dynamically.' },
+    testId: { type: 'string', attribute: 'test-id', doc: 'Test hook on the tag (`data-testid`).' },
+  },
+  events: [{ type: 'click', kind: 'native', reactProp: 'onClick', doc: 'The remove button\'s native click (wired on that button).' }],
+  slots: {
+    default: { doc: 'The text; truncates with an ellipsis.' },
+    icon: { doc: 'A leading icon (decorative); wins over the category square.' },
+  },
+  anatomy: {
+    tag: 'span',
+    class: 'ty-tag',
+    attrs: {
+      role: { value: 'status', when: ['live'] },
+      'aria-live': { value: 'polite', when: ['live'] },
+      'data-tone': { prop: 'tone' },
+      'data-size': { prop: 'size' },
+      'data-removable': { prop: 'removable', kind: 'flag' },
+      'data-testid': { prop: 'testId' },
+    },
+    children: [
+      { tag: 'span', class: 'ty-tag__icon', attrs: { 'aria-hidden': { value: 'true' } }, when: ['slot:icon'], children: [{ slot: 'icon' }] },
+      { tag: 'span', class: 'ty-tag__swatch', attrs: { 'aria-hidden': { value: 'true' }, 'data-category': { prop: 'categoryIndex' } }, when: ['!slot:icon', 'categoryIndex'] },
+      { tag: 'span', class: 'ty-tag__text', children: [{ slot: 'default' }] },
+      {
+        tag: 'button',
+        class: 'ty-tag__remove',
+        attrs: { type: { value: 'button' }, 'aria-label': { prop: 'removeLabel' } },
+        when: ['removable'],
+        children: [
+          {
+            tag: 'svg',
+            class: 'ty-icon',
+            attrs: {
+              'aria-hidden': { value: 'true' },
+              focusable: { value: 'false' },
+              viewBox: { value: '0 0 12 12' },
+              fill: { value: 'none' },
+              stroke: { value: 'currentColor' },
+              'stroke-width': { value: '1.5' },
+              'stroke-linecap': { value: 'round' },
+            },
+            children: [{ tag: 'path', attrs: { d: { value: 'M2.5 2.5l7 7M9.5 2.5l-7 7' } } }],
+          },
+        ],
+      },
+    ],
+  },
+  examples: [
+    { name: 'neutral', props: {}, slots: { default: 'postgres' } },
+    { name: 'accent-small-icon', props: { tone: 'accent', size: 'small', testId: 'env' }, slots: { default: 'production', icon: '◆' } },
+    { name: 'category', props: { categoryIndex: 3 }, slots: { default: 'Stage 3' } },
+    { name: 'removable', props: { removable: true, removeLabel: 'Remove São Paulo' }, slots: { default: 'São Paulo' } },
+    { name: 'live-large', props: { live: true, size: 'large' }, slots: { default: 'Running' } },
+  ],
+} as const satisfies ElementDefinition

package/src/elements/tag/element.ts

@@ -0,0 +1,35 @@
+import { TyElement } from '../base.ts'
+import { tagDefinition } from './definition.ts'
+
+/**
+ * `<ty-tag>`. A static pill with a text, an optional leading icon or
+ * category square, and an optional native remove button (wired by the
+ * wrappers through its native click). The element adds what the markup
+ * cannot: it names an unlabelled remove button "Remove <text>" (the host
+ * passes a translated `remove-label` to override) and normalises
+ * `category-index` into the 1–8 categorical tokens.
+ */
+export class TyTagElement extends TyElement {
+  static override definition = tagDefinition
+
+  override sync(): void {
+    super.sync()
+    const button = this.querySelector('.ty-tag__remove')
+    if (button && !button.hasAttribute('aria-label')) {
+      const text = this.querySelector('.ty-tag__text')?.textContent?.trim() ?? ''
+      button.setAttribute('aria-label', `Remove ${text}`.trim())
+    }
+  }
+
+  protected override changed(): void {
+    const raw = this.getAttribute('category-index')
+    if (raw === null) return
+    const n = Number(raw)
+    if (!Number.isFinite(n)) {
+      this.removeAttribute('category-index')
+      return
+    }
+    const normalized = String(((Math.max(1, Math.round(n)) - 1) % 8) + 1)
+    if (normalized !== raw) this.setAttribute('category-index', normalized)
+  }
+}

package/src/elements/tag-field/definition.ts

@@ -0,0 +1,51 @@
+import type { ElementDefinition } from '../definition.ts'
+
+/**
+ * `<ty-tag-field>`: the TagField's single source (spec: wave-2/tag-field.md).
+ *
+ * Self-rendering like the theme palette: the field is data-driven (the pills
+ * repeat per committed value, the suggestion popup per matching option) and
+ * stateful (the draft, the popup, the highlight), which the declarative
+ * anatomy cannot express, so the element owns its whole subtree and wrappers
+ * render an empty host. Collections cross the attribute boundary as JSON
+ * (`value`, `suggestions`, `suggestion-labels`), the `theme-labels`
+ * precedent; the committed list stays controlled — the element asks for
+ * changes with `ty-change` and never writes its own `value`.
+ *
+ * `validate` (normalise or reject an entry) is a function, so it cannot be an
+ * attribute: hosts assign it as a property on the element. The remove
+ * control's name is the `remove-label` template (`{value}` filled with the
+ * pill's display text).
+ *
+ * Examples stay empty: the parity renderers could only produce the empty
+ * host of a self-rendering element (the theme-palette precedent).
+ */
+export const tagFieldDefinition = {
+  tag: 'ty-tag-field',
+  name: 'TyTagField',
+  kind: 'self-rendering',
+  doc: 'Short values typed into removable pills, optionally assisted by (or restricted to) a suggestion list. Enter or comma commits the draft (or the highlighted suggestion), Backspace on an empty entry removes the last pill; duplicates (case-insensitive), values past `max` and — with `allow-free-text="false"` — values outside `suggestions` are refused. With suggestions the entry is an APG combobox with list autocomplete (active descendant, wrap-around arrows).',
+  props: {
+    value: { type: 'string', attribute: 'value', doc: 'JSON array of the committed values (controlled); the element asks for changes with `ty-change`, it never writes its own.' },
+    suggestions: { type: 'string', attribute: 'suggestions', doc: 'JSON array of known values; turns the entry into a combobox.' },
+    suggestionLabels: { type: 'string', attribute: 'suggestion-labels', doc: 'JSON object of display text per value, used in the popup and on the pills.' },
+    allowFreeText: { type: 'string', attribute: 'allow-free-text', doc: '`true` or `false`; unset: free text is allowed. `false`: only values present in `suggestions` are accepted (the `show-arrow` precedent for a default-true switch).' },
+    max: { type: 'number', attribute: 'max', doc: 'Maximum pills; the entry is disabled at the limit and re-enabled when one is removed.' },
+    disabled: { type: 'boolean', attribute: 'disabled', doc: 'Disables the entry and every remove control.' },
+    tone: { type: 'enum', values: ['neutral', 'accent'], default: 'neutral', attribute: 'tone', doc: 'Pill tint; `accent` fills with the theme accent.' },
+    categoryIndex: { type: 'number', attribute: 'category-index', doc: 'A categorical token (1 to 8) as the pill tint, shown as a small colour square; normalised into range on upgrade, wins over `tone`.' },
+    label: { type: 'string', attribute: 'label', doc: 'Visible label above the field, targeting the entry; if absent, `accessibleLabel` is required.' },
+    accessibleLabel: { type: 'string', attribute: 'accessible-label', doc: 'Accessible name of the entry when there is no visible label.' },
+    placeholder: { type: 'string', attribute: 'placeholder', doc: 'Hint in the entry.' },
+    helperText: { type: 'string', attribute: 'helper-text', doc: 'Help text below the field, linked as the entry\'s description.' },
+    errorText: { type: 'string', attribute: 'error-text', doc: 'Marks the field invalid; shown below the helper text and linked as description.' },
+    removeLabel: { type: 'string', default: 'Remove {value}', attribute: 'remove-label', doc: 'Accessible name template of each remove control; `{value}` is the pill\'s display text.' },
+    chosenLabel: { type: 'string', default: '{field}: chosen values', attribute: 'chosen-label', doc: 'Accessible name template of the pill list; `{field}` is the label (or accessible label).' },
+    suggestionsLabel: { type: 'string', default: 'Suggestions', attribute: 'suggestions-label', doc: 'Accessible name of the suggestion popup.' },
+    testId: { type: 'string', attribute: 'test-id', doc: 'Test hook on the root (`data-testid`).' },
+  },
+  events: [
+    { type: 'ty-change', kind: 'custom', detail: { value: 'string' }, reactProp: 'onChange', doc: 'A value was added or removed; `value` is the next list as a JSON array. Controlled: the host writes it back to the `value` attribute.' },
+  ],
+  examples: [],
+} as const satisfies ElementDefinition

package/src/elements/tag-field/element.ts

@@ -0,0 +1,461 @@
+import { TyElement } from '../base.ts'
+import { tagFieldDefinition } from './definition.ts'
+
+const SVG_NS = 'http://www.w3.org/2000/svg'
+
+/** Case-insensitive (accent-keeping) equality, the React TagField's `same`. */
+const same = (a: string, b: string) => a.localeCompare(b, undefined, { sensitivity: 'accent' }) === 0
+
+function el(tag: string, className: string, attrs: Record<string, string> = {}): HTMLElement {
+  const node = document.createElement(tag)
+  node.className = className
+  for (const [name, value] of Object.entries(attrs)) node.setAttribute(name, value)
+  return node
+}
+
+/** The remove control's × (lucide strokes, ISC, THIRD_PARTY_NOTICES). */
+function xIcon(): SVGElement {
+  const svg = document.createElementNS(SVG_NS, 'svg')
+  svg.setAttribute('class', 'ty-icon')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '2')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
+  svg.setAttribute('aria-hidden', 'true')
+  svg.setAttribute('focusable', 'false')
+  for (const d of ['M18 6 6 18', 'm6 6 12 12']) {
+    const path = document.createElementNS(SVG_NS, 'path')
+    path.setAttribute('d', d)
+    svg.append(path)
+  }
+  return svg
+}
+
+/**
+ * `<ty-tag-field>`. Self-rendering: the field is data-driven (a pill per
+ * committed value, an option per matching suggestion) and stateful (the
+ * draft, the popup, the highlight), so the element owns its whole subtree —
+ * built once on connect, then kept in step with the attributes and the
+ * field's own state. The DOM mirrors the React TagField's parts
+ * (`ty-tag-field__well`, `__chip`, `__drop`, `__menu-layer`, …) so the
+ * shared TagField.css paints both.
+ *
+ * The value is controlled: committing (Enter, comma, an option press) or
+ * removing (a remove control, Backspace on an empty entry) only emits
+ * `ty-change` with the next list as JSON; the host writes it back to the
+ * `value` attribute. Every entry passes the React gate in order: trim,
+ * `validate` (a property — functions cannot be attributes), then the
+ * refusals (blank, invalid, duplicate ignoring case, past `max`, unlisted
+ * with `allow-free-text="false"`).
+ *
+ * With suggestions the entry is an APG combobox: focus stays in the input,
+ * the highlight is `aria-activedescendant`, ArrowDown/ArrowUp move it with
+ * wrap-around, Enter commits the highlighted option, Escape closes without
+ * committing, and options commit on mousedown with the default prevented so
+ * the input never loses focus.
+ */
+export class TyTagFieldElement extends TyElement {
+  static override definition = tagFieldDefinition
+
+  /** Normalises an entry (after trimming) or rejects it with null. Assigned by the host, not an attribute. */
+  validate?: (raw: string) => string | null
+
+  #draft = ''
+  #open = false
+  #active: number | null = null
+  /** Signatures of the last render, so a sync rebuilds only what changed. */
+  #chipsKey = ''
+  #menuKey = ''
+
+  #root: HTMLElement | null = null
+  #caption: HTMLLabelElement | null = null
+  #well: HTMLElement | null = null
+  #chipList: HTMLElement | null = null
+  #input: HTMLInputElement | null = null
+  #menuLayer: HTMLElement | null = null
+  #menu: HTMLElement | null = null
+  #note: HTMLElement | null = null
+  #fault: HTMLElement | null = null
+
+  get field(): HTMLInputElement | null {
+    return this.#input
+  }
+
+  /* ------------------------------------------------------------ data -- */
+
+  #json<T>(raw: unknown, fallback: T): T {
+    if (typeof raw !== 'string' || raw === '') return fallback
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      return (parsed ?? fallback) as T
+    } catch {
+      return fallback
+    }
+  }
+
+  /** The committed values (controlled, from the `value` attribute). */
+  held(): string[] {
+    const list = this.#json<unknown>(this.props.value, [])
+    return Array.isArray(list) ? list.filter((v): v is string => typeof v === 'string') : []
+  }
+
+  #suggestions(): string[] {
+    const list = this.#json<unknown>(this.props.suggestions, [])
+    return Array.isArray(list) ? list.filter((v): v is string => typeof v === 'string') : []
+  }
+
+  #labels(): Record<string, string> {
+    const map = this.#json<unknown>(this.props.suggestionLabels, {})
+    if (typeof map !== 'object' || map === null || Array.isArray(map)) return {}
+    return Object.fromEntries(Object.entries(map).filter(([, v]) => typeof v === 'string')) as Record<string, string>
+  }
+
+  #freeText(): boolean {
+    return String(this.props.allowFreeText ?? 'true') !== 'false'
+  }
+
+  #disabled(): boolean {
+    return Boolean(this.props.disabled)
+  }
+
+  #atMax(held: readonly string[]): boolean {
+    const max = this.props.max
+    return max !== undefined && held.length >= Number(max)
+  }
+
+  /** Suggestions not yet chosen, matching the draft against value and display text. */
+  #offers(): Array<{ id: string; text: string }> {
+    const held = this.held()
+    const labels = this.#labels()
+    const query = this.#draft.trim().toLocaleLowerCase()
+    return this.#suggestions().flatMap((s) => {
+      if (held.some((h) => same(h, s))) return []
+      const text = labels[s] ?? s
+      const hit = !query || s.toLocaleLowerCase().includes(query) || text.toLocaleLowerCase().includes(query)
+      return hit ? [{ id: s, text }] : []
+    })
+  }
+
+  /** The gate every entry passes (the React TagField's `judge`): the value to commit, or null to refuse. */
+  #judge(raw: string): string | null {
+    const bare = raw.trim()
+    if (bare === '') return null
+    const shaped = this.validate ? this.validate(bare) : bare
+    if (!shaped) return null
+    const held = this.held()
+    if (held.some((h) => same(h, shaped))) return null
+    if (this.#atMax(held)) return null
+    const suggestions = this.#suggestions()
+    if (suggestions.length > 0 && !this.#freeText() && !suggestions.includes(shaped)) return null
+    return shaped
+  }
+
+  /* ------------------------------------------------------------ tree -- */
+
+  #build(): void {
+    const instance = this.instanceId
+    this.#caption = el('label', 'ty-tag-field__caption') as HTMLLabelElement
+    this.#well = el('div', 'ty-tag-field__well')
+    const chips = el('span', 'ty-tag-field__chips')
+    this.#chipList = el('span', 'ty-tag-field__chip-list', { role: 'list' })
+    chips.append(this.#chipList)
+    this.#input = el('input', 'ty-tag-field__typing', { id: `${instance}-input`, type: 'text', autocomplete: 'off' }) as HTMLInputElement
+    const typingHost = el('span', 'ty-tag-field__typing-host')
+    typingHost.append(this.#input)
+    this.#well.append(chips, typingHost)
+    this.#menu = el('ul', 'ty-tag-field__menu', { id: `${instance}-listbox`, role: 'listbox' })
+    this.#menuLayer = el('div', 'ty-tag-field__menu-layer', { hidden: '' })
+    this.#menuLayer.append(this.#menu)
+    const frame = el('div', 'ty-tag-field__frame')
+    frame.append(this.#well, this.#menuLayer)
+    this.#note = el('p', 'ty-tag-field__note', { id: `${instance}-note`, hidden: '' })
+    this.#fault = el('p', 'ty-tag-field__fault', { id: `${instance}-fault`, hidden: '' })
+    this.#root = el('div', 'ty-tag-field')
+    this.#root.append(this.#caption, frame, this.#note, this.#fault)
+    this.replaceChildren(this.#root)
+  }
+
+  /** Bring the tree in step with the attributes and the field state. */
+  #sync(): void {
+    this.#normaliseCategory()
+    const { props } = this
+    const root = this.#root
+    const input = this.#input
+    if (!root || !input || !this.#caption || !this.#well || !this.#chipList || !this.#menuLayer || !this.#menu || !this.#note || !this.#fault) return
+    const instance = this.instanceId
+    const held = this.held()
+    const labels = this.#labels()
+    const shown = (v: string) => labels[v] ?? v
+    const disabled = this.#disabled()
+    const atMax = this.#atMax(held)
+    const suggestions = this.#suggestions()
+    const hasSuggestions = suggestions.length > 0
+    const error = props.errorText ? String(props.errorText) : ''
+    const helper = props.helperText ? String(props.helperText) : ''
+    const label = props.label ? String(props.label) : ''
+
+    // Category wins over tone; the tint travels as the same custom property
+    // the React component sets.
+    const category = props.categoryIndex !== undefined && Number.isFinite(Number(props.categoryIndex)) ? Number(props.categoryIndex) : undefined
+    root.setAttribute('data-tone', category !== undefined ? 'category' : String(props.tone))
+    root.style.setProperty('--ty-tag-field-tint', category !== undefined ? `var(--ty-categorical-${category})` : '')
+    root.toggleAttribute('data-invalid', Boolean(error))
+    if (props.testId) root.setAttribute('data-testid', String(props.testId))
+    else root.removeAttribute('data-testid')
+
+    this.#caption.hidden = !label
+    this.#caption.textContent = label
+    this.#caption.htmlFor = `${instance}-input`
+    this.#well.toggleAttribute('data-disabled', disabled)
+
+    input.id = `${instance}-input`
+    input.placeholder = props.placeholder ? String(props.placeholder) : ''
+    input.disabled = disabled || atMax
+    if (error) input.setAttribute('aria-invalid', 'true')
+    else input.removeAttribute('aria-invalid')
+    if (!label && props.accessibleLabel) input.setAttribute('aria-label', String(props.accessibleLabel))
+    else input.removeAttribute('aria-label')
+    input.setAttribute('aria-describedby', [helper && `${instance}-note`, error && `${instance}-fault`].filter(Boolean).join(' ') || '')
+    if (!input.getAttribute('aria-describedby')) input.removeAttribute('aria-describedby')
+
+    const offers = this.#offers()
+    const listOpen = hasSuggestions && this.#open && offers.length > 0
+    if (hasSuggestions) {
+      input.setAttribute('role', 'combobox')
+      input.setAttribute('aria-expanded', listOpen ? 'true' : 'false')
+      input.setAttribute('aria-controls', `${instance}-listbox`)
+      input.setAttribute('aria-autocomplete', 'list')
+      if (listOpen && this.#active !== null && offers[this.#active]) input.setAttribute('aria-activedescendant', `${instance}-option-${this.#active}`)
+      else input.removeAttribute('aria-activedescendant')
+    } else {
+      for (const name of ['role', 'aria-expanded', 'aria-controls', 'aria-autocomplete', 'aria-activedescendant']) input.removeAttribute(name)
+    }
+
+    this.#note.hidden = !helper
+    this.#note.textContent = helper
+    this.#note.id = `${instance}-note`
+    this.#fault.hidden = !error
+    this.#fault.textContent = error
+    this.#fault.id = `${instance}-fault`
+    this.#menu.id = `${instance}-listbox`
+    this.#menu.setAttribute('aria-label', String(props.suggestionsLabel))
+
+    // The pills rebuild only when they changed (a focused remove control
+    // keeps its node while the draft moves).
+    const chipsKey = JSON.stringify([held, labels, disabled, props.removeLabel, props.chosenLabel, label, props.accessibleLabel, instance])
+    if (chipsKey !== this.#chipsKey) {
+      this.#chipsKey = chipsKey
+      const field = label || String(props.accessibleLabel ?? '')
+      const chosen = String(props.chosenLabel).replaceAll('{field}', field)
+      this.#chipList.setAttribute('aria-label', field ? chosen : chosen.replace(/^:\s*/, ''))
+      const template = String(props.removeLabel)
+      this.#chipList.replaceChildren(
+        ...held.map((value) => {
+          const chip = el('span', 'ty-tag-field__chip', { role: 'listitem' })
+          const text = el('span', 'ty-tag-field__chip-text')
+          text.textContent = shown(value)
+          const drop = el('button', 'ty-tag-field__drop', { type: 'button', 'aria-label': template.replaceAll('{value}', shown(value)), 'data-value': value }) as HTMLButtonElement
+          drop.disabled = disabled
+          drop.append(xIcon())
+          chip.append(text, drop)
+          return chip
+        }),
+      )
+    }
+
+    // The options are keyed by position and REUSED (attributes and text in
+    // place), never rebuilt: a highlight move must land on the same node
+    // the page (and a test) is holding.
+    const menuKey = listOpen ? JSON.stringify([offers, instance]) : ''
+    if (menuKey !== this.#menuKey) {
+      this.#menuKey = menuKey
+      this.#menu.replaceChildren(
+        ...(!listOpen
+          ? []
+          : offers.map((offer) => {
+              const option = el('li', 'ty-tag-field__choice', { role: 'option', 'data-value': offer.id })
+              option.textContent = offer.text
+              return option
+            })),
+      )
+    }
+    Array.from(this.#menu.children).forEach((node, index) => {
+      const option = node as HTMLElement
+      if (!option.id) option.id = `${instance}-option-${index}`
+      option.setAttribute('aria-selected', this.#active === index ? 'true' : 'false')
+      option.toggleAttribute('data-focused', this.#active === index)
+    })
+    this.#menuLayer.hidden = !listOpen
+  }
+
+  /* --------------------------------------------------------- behaviour -- */
+
+  /** Ask the host for the next list (controlled). */
+  #request(next: string[]): void {
+    this.emit('ty-change', { value: JSON.stringify(next) })
+  }
+
+  /** A successful commit also resets the draft and closes the popup. */
+  #commit(raw: string): void {
+    const take = this.#judge(raw)
+    if (take === null) return
+    this.#request([...this.held(), take])
+    this.#draft = ''
+    if (this.#input) this.#input.value = ''
+    this.#open = false
+    this.#active = null
+    this.#sync()
+  }
+
+  #drop(value: string): void {
+    if (this.#disabled()) return
+    const held = this.held()
+    if (!held.includes(value)) return
+    this.#request(held.filter((v) => v !== value))
+    this.#input?.focus()
+  }
+
+  #onKeydown = (event: KeyboardEvent): void => {
+    if (event.target !== this.#input || this.#disabled()) return
+    const input = this.#input!
+    const offers = this.#offers()
+    switch (event.key) {
+      case 'Enter':
+      case ',': {
+        // The commit keys are always ours (a comma never reaches the text).
+        event.preventDefault()
+        const picked = this.#open && this.#active !== null ? offers[this.#active] : undefined
+        this.#commit(picked ? picked.id : input.value)
+        return
+      }
+      case 'Backspace': {
+        if (input.value !== '') return
+        const held = this.held()
+        if (!held.length) return
+        event.preventDefault()
+        this.#request(held.slice(0, -1))
+        return
+      }
+      case 'ArrowDown':
+      case 'ArrowUp': {
+        if (!this.#suggestions().length || !offers.length) return
+        event.preventDefault()
+        const count = offers.length
+        this.#active =
+          event.key === 'ArrowDown'
+            ? this.#active === null
+              ? 0
+              : (this.#active + 1) % count
+            : this.#active === null || this.#active === 0
+              ? count - 1
+              : this.#active - 1
+        this.#open = true
+        this.#sync()
+        const option = this.#menu?.children[this.#active]
+        if (typeof (option as HTMLElement | undefined)?.scrollIntoView === 'function') (option as HTMLElement).scrollIntoView({ block: 'nearest' })
+        return
+      }
+      case 'Escape': {
+        if (!this.#open) return
+        event.preventDefault()
+        this.#open = false
+        this.#active = null
+        this.#sync()
+      }
+    }
+  }
+
+  #onInput = (event: Event): void => {
+    if (event.target !== this.#input) return
+    this.#draft = this.#input!.value
+    if (this.#suggestions().length) this.#open = true
+    // The first offer is highlighted while typing (RAC's combobox), so
+    // Enter commits the filtered match without an arrow key first.
+    this.#active = this.#offers().length ? 0 : null
+    this.#sync()
+  }
+
+  #onFocus = (event: FocusEvent): void => {
+    if (event.target !== this.#input || !this.#suggestions().length) return
+    this.#open = true
+    this.#active = this.#active ?? (this.#offers().length ? 0 : null)
+    this.#sync()
+  }
+
+  /** The popup closes when focus leaves the field. */
+  #onFocusOut = (event: FocusEvent): void => {
+    const next = event.relatedTarget as Node | null
+    if (next && this.contains(next)) return
+    if (!this.#open) return
+    this.#open = false
+    this.#active = null
+    this.#sync()
+  }
+
+  #onClick = (event: Event): void => {
+    const target = event.target as Element | null
+    if (!target || typeof target.closest !== 'function') return
+    const drop = target.closest('.ty-tag-field__drop')
+    if (drop && this.contains(drop) && !(drop as HTMLButtonElement).disabled) this.#drop(drop.getAttribute('data-value') ?? '')
+    // A click on the entry re-opens the suggestions: focusin alone does not
+    // re-fire on an input that never lost focus.
+    if (this.#input && this.#suggestions().length && target.closest('.ty-tag-field__well') && !this.#open) {
+      this.#open = true
+      this.#active = this.#active ?? (this.#offers().length ? 0 : null)
+      this.#sync()
+    }
+  }
+
+  /** Options commit on mousedown with the default prevented, so the entry never loses focus. */
+  #onOptionPress = (event: Event): void => {
+    const target = event.target as Element | null
+    if (!target || typeof target.closest !== 'function') return
+    const option = target.closest('.ty-tag-field__choice')
+    if (!option || !this.contains(option)) return
+    event.preventDefault()
+    this.#commit(option.getAttribute('data-value') ?? '')
+  }
+
+  protected override connected(): void {
+    this.#build()
+    this.#sync()
+    this.addEventListener('keydown', this.#onKeydown)
+    this.addEventListener('input', this.#onInput)
+    this.addEventListener('focusin', this.#onFocus)
+    this.addEventListener('focusout', this.#onFocusOut)
+    this.addEventListener('click', this.#onClick)
+    this.addEventListener('mousedown', this.#onOptionPress)
+  }
+
+  protected override disconnected(): void {
+    this.removeEventListener('keydown', this.#onKeydown)
+    this.removeEventListener('input', this.#onInput)
+    this.removeEventListener('focusin', this.#onFocus)
+    this.removeEventListener('focusout', this.#onFocusOut)
+    this.removeEventListener('click', this.#onClick)
+    this.removeEventListener('mousedown', this.#onOptionPress)
+  }
+
+  protected override changed(): void {
+    if (!this.isConnected || !this.#root) return
+    // Normalise `category-index` into the 1–8 categorical tokens (as
+    // <ty-tag>). Attributes present BEFORE the upgrade never reach
+    // attributeChangedCallback, so the pass also runs from `#sync`.
+    this.#normaliseCategory()
+    this.#sync()
+  }
+
+  #normaliseCategory(): void {
+    const raw = this.getAttribute('category-index')
+    if (raw === null) return
+    const n = Number(raw)
+    if (!Number.isFinite(n)) {
+      this.removeAttribute('category-index')
+      return
+    }
+    const normalized = String(((Math.max(1, Math.round(n)) - 1) % 8) + 1)
+    if (normalized !== raw) this.setAttribute('category-index', normalized)
+  }
+}