taga11y 1.0.0

package/src/index.ts

@@ -0,0 +1,900 @@
+import './styles/index.css';
+
+import type {
+  TagData,
+  Taga11yOptions,
+  SuggestionItem,
+  SuggestionsSource,
+  I18nOptions,
+  I18nStrings,
+  Taga11yEventMap,
+} from './types.js';
+import { resolveStrings, applyLocale } from './i18n.js';
+import { deriveBaseId, buildIds, type DerivedIds } from './utils/id.js';
+import { getLabel, getValue } from './utils/filter.js';
+import { SelectionManager } from './core/selection.js';
+import { DropdownManager } from './core/dropdown.js';
+import { InputManager } from './core/input.js';
+import { KeyboardManager } from './core/keyboard.js';
+import { render, setupCombobox, announce, type DomElements } from './dom/render.js';
+import { updateChips, createErrorChip } from './dom/chips.js';
+import {
+  announceTagAdded,
+  announceTagRemoved,
+  announceTagsCleared,
+  announceTagsSummary,
+  announceRejection,
+  showError,
+} from './a11y.js';
+
+export type {
+  TagData,
+  Taga11yOptions,
+  SuggestionItem,
+  SuggestionsSource,
+  I18nOptions,
+  I18nStrings,
+};
+export type { PluralForms, I18nKey } from './types.js';
+export type {
+  Taga11yEventMap,
+  Taga11yAddDetail,
+  Taga11yRemoveDetail,
+  Taga11yClearDetail,
+  Taga11yChangeDetail,
+  Taga11yPasteDetail,
+  Taga11yDestroyDetail,
+} from './types.js';
+
+interface ResolvedOptions {
+  suggestions: SuggestionsSource | undefined;
+  maxTags: number | undefined;
+  maxSuggestions: number;
+  delimiter: string[];
+  enforceSuggestions: boolean;
+  name: string;
+  label: string | undefined;
+  disabled: boolean;
+  theme: 'dark' | 'light' | null;
+  serialize: (tags: TagData[]) => string;
+  deserialize: (raw: string) => SuggestionItem[];
+  debounceMs: number;
+  i18n: I18nOptions | undefined;
+}
+
+/**
+ * Accessibility-first tagging / multi-select input component.
+ *
+ * Wraps a native `<input>` element in an accessible combobox widget
+ * with inline chips, a keyboard-navigable listbox popup, screen reader
+ * announcements, and form integration via a hidden input.
+ *
+ * ```ts
+ * const widget = new Taga11y(inputEl, {
+ *   suggestions: ['JavaScript', 'TypeScript', 'Rust'],
+ *   maxTags: 10,
+ *   enforceSuggestions: false,
+ * });
+ *
+ * widget.addTag('Rust');
+ * console.log(widget.tags); // [{ id: '…', label: 'Rust', value: 'Rust' }]
+ * ```
+ *
+ * ## Custom events
+ *
+ * Dispatched on the original input element. All bubble and are not
+ * cancelable. Subscribe via {@link Taga11y.on} or
+ * `inputEl.addEventListener`.
+ *
+ * - `taga11y:add` — detail `{ tag: TagData }`. Fired per tag added,
+ *   including each chunk of a delimited paste.
+ * - `taga11y:remove` — detail `{ tag: TagData }`.
+ * - `taga11y:clear` — detail `{ tags: TagData[] }`. The tags that were
+ *   removed.
+ * - `taga11y:change` — detail `{ tags: TagData[] }`. Final tag set
+ *   after any mutation. Fired once after `addTags`, `setTags`, or a
+ *   delimited paste.
+ * - `taga11y:paste` — detail `{ added: TagData[], skipped: string[] }`.
+ *   Fired once after a paste gesture that contained a configured
+ *   single-character delimiter. `skipped` lists chunks rejected by
+ *   whitelist mode, duplicate detection, or `maxTags`. Not fired for
+ *   paste of text containing no delimiter.
+ * - `taga11y:destroy` — detail `{}`.
+ *
+ * See [docs/guides/events.md](../guides/events.md) for the full
+ * reference and examples.
+ */
+function resolveTheme(value: unknown): 'dark' | 'light' | null {
+  if (value == null) return null;
+  if (value === 'dark' || value === 'light') return value;
+  throw new TypeError(`taga11y: theme must be "dark", "light", or null — received "${value}"`);
+}
+
+export class Taga11y {
+  private readonly _input: HTMLInputElement;
+  private readonly _ids: DerivedIds;
+  private readonly _originalName: string;
+  private readonly _originalId: string;
+  private readonly _originalValue: string;
+  private readonly _originalParent: ParentNode | null;
+  private readonly _originalNextSibling: ChildNode | null;
+
+  private _dom!: DomElements;
+  private _selection!: SelectionManager;
+  private _dropdown!: DropdownManager;
+  private _inputMgr!: InputManager;
+  private _keyboard!: KeyboardManager;
+  private _opts: ResolvedOptions;
+  private readonly _strings: I18nStrings;
+  private readonly _locale: string;
+  private _initialSnapshot: SuggestionItem[] = [];
+  private _formResetHandler: (() => void) | null = null;
+
+  /**
+   * Creates a new taga11y instance and immediately initialises it.
+   *
+   * @param input - The native `<input>` element to enhance.
+   * @param options - Configuration options for the widget.
+   * @throws If `suggestions` defines both `once` and `query` keys.
+   */
+  constructor(input: HTMLInputElement, options: Taga11yOptions = {}) {
+    this._input = input;
+    this._originalName = input.name;
+    this._originalId = input.id;
+    this._originalValue = input.value;
+    this._originalParent = input.parentNode;
+    this._originalNextSibling = input.nextSibling;
+    this._ids = buildIds(deriveBaseId(input));
+    this._opts = this._parseOptions(options);
+    this._strings = resolveStrings(this._opts.i18n?.strings);
+    this._locale = this._opts.i18n?.locale ?? 'en';
+    this.init();
+  }
+
+  // ── 10.3  init ──────────────────────────────────────────────
+
+  /**
+   * Initialises the widget: builds the DOM structure, wires up managers,
+   * pre-populates tags from the original input value, and sets up form
+   * reset handling.
+   *
+   * Called automatically by the constructor. Invoke again after
+   * {@link destroy} to re-initialise.
+   */
+  init(): void {
+    this._initialSnapshot = this._opts.deserialize(this._input.value);
+    // Chips are the sole visible representation; clear both the current
+    // value and the HTML default so native form.reset() doesn't repopulate
+    // the raw serialized string into the combobox.
+    this._input.value = '';
+    this._input.defaultValue = '';
+
+    setupCombobox(this._input, this._ids);
+
+    this._dom = render(this._input, this._ids, {
+      ...(this._opts.label !== undefined ? { label: this._opts.label } : {}),
+      name: this._opts.name,
+      initialValue: '',
+      strings: this._strings,
+      locale: this._locale,
+    });
+
+    if (this._opts.theme) {
+      this._dom.wrapper.setAttribute('data-theme', this._opts.theme);
+    }
+    if (this._opts.disabled) {
+      this._dom.wrapper.classList.add('taga11y--disabled');
+      this._input.disabled = true;
+      this._dom.hiddenInput.disabled = true;
+    }
+
+    // Insert wrapper into DOM where the input was
+    if (this._originalParent) {
+      this._originalParent.insertBefore(this._dom.wrapper, this._originalNextSibling);
+    }
+
+    if (this._opts.i18n) {
+      applyLocale(this._dom.wrapper, this._opts.i18n.locale, this._opts.i18n.dir);
+    }
+
+    this._selection = new SelectionManager(this._ids.base, this._opts.maxTags);
+
+    this._dropdown = new DropdownManager(
+      {
+        listbox: this._dom.listbox,
+        input: this._input,
+        loading: this._dom.loading,
+        wrapper: this._dom.wrapper,
+      },
+      {
+        ...(this._opts.suggestions !== undefined ? { suggestions: this._opts.suggestions } : {}),
+        debounceMs: this._opts.debounceMs,
+        maxSuggestions: this._opts.maxSuggestions,
+        getSelectedValues: () => this._selection.getTags().map((t) => t.value),
+        ids: this._ids,
+        strings: this._strings,
+        locale: this._locale,
+        onOptionSelect: (item) => {
+          this._dropdown.close();
+          this._handleCommit(getValue(item));
+          this._inputMgr.clearValue();
+        },
+        onAnnounce: (msg) => announce(this._dom.announcer, msg),
+        onLoadError: (msg) => showError(this._dom.error, msg),
+      },
+    );
+
+    this._inputMgr = new InputManager(this._input, {
+      onInput: (value) => this._dropdown.filter(value),
+      onBlurCommit: (value) => this._handleBlurCommit(value),
+      onBlurClose: () => this._dropdown.close(),
+      onFocus: () => this._announceTagsSummary(),
+      getDelimiters: () => this._opts.delimiter,
+      isEnforceSuggestions: () => this._opts.enforceSuggestions,
+      getLoadedSuggestions: () => this._dropdown.getAllSuggestions(),
+      onCommit: (value) => this._handleCommit(value),
+      onCommitRejected: (value) => this._showRejection(value, 'not-in-list'),
+      onPaste: (chunks) => this._handlePaste(chunks),
+      onCloseDropdown: () => this._dropdown.close(),
+    });
+
+    this._keyboard = new KeyboardManager(this._input, {
+      onCommit: (value) => this._handleCommit(value),
+      onCommitRejected: (value) => this._showRejection(value, 'not-in-list'),
+      onRemoveLast: () => this._handleRemoveLast(),
+      clearInput: () => this._inputMgr.clearValue(),
+      hasChips: () => this._selection.getTags().length > 0,
+      getDropdown: () => this._dropdown,
+      getDelimiters: () => this._opts.delimiter,
+      isEnforceSuggestions: () => this._opts.enforceSuggestions,
+      getSuggestionSource: () => this._opts.suggestions,
+      getLoadedSuggestions: () => this._dropdown.getAllSuggestions(),
+    });
+
+    // Pre-populate from original input value
+    for (const item of this._initialSnapshot) {
+      const value = getValue(item);
+      const label =
+        typeof item === 'string' ? this._resolveLabelFromAll(value) : getLabel(item);
+      this._selection.addTag(value, label);
+    }
+    this._syncChips();
+    this._syncHiddenInput();
+
+    // Form reset
+    const form = this._input.closest('form');
+    if (form) {
+      this._formResetHandler = () => this._handleFormReset();
+      form.addEventListener('reset', this._formResetHandler);
+    }
+  }
+
+  // ── 10.4  destroy ──────────────────────────────────────────
+
+  /**
+   * Tears down the widget: removes the injected DOM, detaches all event
+   * listeners, restores the original input's attributes, and moves it
+   * back to its original DOM position.
+   *
+   * Fires a `taga11y:destroy` event on the original input.
+   */
+  destroy(): void {
+    this._keyboard.destroy();
+    this._inputMgr.destroy();
+    this._dropdown.destroy();
+
+    const form = this._input.closest('form');
+    if (form && this._formResetHandler) {
+      form.removeEventListener('reset', this._formResetHandler);
+      this._formResetHandler = null;
+    }
+
+    // Move input back to original position
+    if (this._originalParent) {
+      this._originalParent.insertBefore(this._input, this._originalNextSibling);
+    }
+
+    // Restore original attributes
+    if (this._originalName) this._input.setAttribute('name', this._originalName);
+    if (!this._originalId) {
+      this._input.removeAttribute('id');
+    }
+    this._input.value = this._originalValue;
+    this._input.defaultValue = this._originalValue;
+    this._input.removeAttribute('role');
+    this._input.removeAttribute('aria-autocomplete');
+    this._input.removeAttribute('aria-haspopup');
+    this._input.removeAttribute('aria-expanded');
+    this._input.removeAttribute('aria-controls');
+    this._input.removeAttribute('aria-activedescendant');
+    this._input.disabled = false;
+
+    this._dom.wrapper.remove();
+    this.emit('taga11y:destroy', {});
+  }
+
+  // ── 10.5  addTag ───────────────────────────────────────────
+
+  /**
+   * Adds a single tag by value.
+   *
+   * Resolves the display label from loaded suggestions (matching on
+   * `value`), falling back to `label === value` if no match exists.
+   *
+   * @param value - The tag value to add.
+   * @returns `true` if the tag was added; `false` if rejected
+   *          (duplicate or max reached).
+   *
+   * Fires `taga11y:add` and `taga11y:change` on success.
+   * Fires no events on rejection (shows error chip + region instead).
+   */
+  addTag(value: string): boolean {
+    const label = this._resolveLabelFromAll(value);
+    const result = this._selection.addTag(value, label);
+    if (result.ok) {
+      this._syncChips();
+      this._syncHiddenInput();
+      this.emit('taga11y:add', { tag: result.tag });
+      this.emit('taga11y:change', { tags: this._selection.getTags() });
+      announceTagAdded(this._dom.announcer, this._strings, this._locale, result.tag.label);
+      return true;
+    }
+    this._showRejection(value, result.reason);
+    return false;
+  }
+
+  // ── 10.6  removeTag ────────────────────────────────────────
+
+  /**
+   * Removes a single tag by value.
+   *
+   * @param value - The tag value to remove.
+   * @returns The removed `TagData`, or `null` if no tag with that
+   *          value exists.
+   *
+   * Fires `taga11y:remove` and `taga11y:change`. Returns focus to
+   * the combobox input after removal.
+   */
+  removeTag(value: string): TagData | null {
+    const tag = this._selection.getTags().find((t) => t.value === value);
+    if (!tag) return null;
+    const removed = this._selection.removeTag(tag.id);
+    if (!removed) return null;
+    this._syncChips();
+    this._syncHiddenInput();
+    this.emit('taga11y:remove', { tag: removed });
+    this.emit('taga11y:change', { tags: this._selection.getTags() });
+    announceTagRemoved(this._dom.announcer, this._strings, this._locale, removed.label);
+    this._input.focus();
+    return removed;
+  }
+
+  // ── 10.7  clearTags ────────────────────────────────────────
+
+  /**
+   * Removes all tags at once.
+   *
+   * Fires `taga11y:clear` (detail: `{ tags: TagData[] }`) and
+   * `taga11y:change` (detail: `{ tags: [] }`).
+   */
+  clearTags(): void {
+    const cleared = this._selection.clearTags();
+    this._syncChips();
+    this._syncHiddenInput();
+    this.emit('taga11y:clear', { tags: cleared });
+    this.emit('taga11y:change', { tags: [] });
+    announceTagsCleared(this._dom.announcer, this._strings, this._locale);
+  }
+
+  // ── 10.8  getTags ──────────────────────────────────────────
+
+  /**
+   * Returns a defensive copy of the current tag array.
+   *
+   * @returns Array of `TagData` objects representing selected tags.
+   */
+  getTags(): TagData[] {
+    return this._selection.getTags();
+  }
+
+  // ── 10.9  addTags ──────────────────────────────────────────
+
+  /**
+   * Batch-adds multiple tags. Duplicates are skipped silently.
+   *
+   * Fires `taga11y:add` per successfully added tag and a single
+   * `taga11y:change` after all additions with the final tag set.
+   *
+   * @param items - Suggestion items to add.
+   */
+  addTags(items: SuggestionItem[]): void {
+    let anyAdded = false;
+    for (const item of items) {
+      const value = getValue(item);
+      const label = this._resolveLabelFromAll(value) || getLabel(item);
+      const result = this._selection.addTag(value, label);
+      if (result.ok) {
+        anyAdded = true;
+        this.emit('taga11y:add', { tag: result.tag });
+      }
+    }
+    if (anyAdded) {
+      this._syncChips();
+      this._syncHiddenInput();
+      this.emit('taga11y:change', { tags: this._selection.getTags() });
+    }
+  }
+
+  // ── 10.10  setTags ─────────────────────────────────────────
+
+  /**
+   *Fully replaces all tags with the given items.
+   *
+   * Fires `taga11y:clear` with the previously selected tags, then
+   * `taga11y:add` per newly added tag, and finally a single
+   * `taga11y:change` with the final tag set.
+   *
+   * @param items - Suggestion items to set as the new tag set.
+   */
+  setTags(items: SuggestionItem[]): void {
+    const cleared = this._selection.clearTags();
+    this.emit('taga11y:clear', { tags: cleared });
+
+    for (const item of items) {
+      const value = getValue(item);
+      const label = this._resolveLabelFromAll(value) || getLabel(item);
+      const result = this._selection.addTag(value, label);
+      if (result.ok) {
+        this.emit('taga11y:add', { tag: result.tag });
+      }
+    }
+    this._syncChips();
+    this._syncHiddenInput();
+    this.emit('taga11y:change', { tags: this._selection.getTags() });
+  }
+
+  // ── 10.11  isTagged ────────────────────────────────────────
+
+  /**
+   * Checks whether a tag with the given value is currently selected.
+   *
+   * @param value - The tag value to check.
+   * @returns `true` if a tag with the matching value exists.
+   */
+  isTagged(value: string): boolean {
+    return this._selection.isTagged(value);
+  }
+
+  // ── 10.12 / 10.13  open / close ────────────────────────────
+
+  /**
+   * Opens the suggestion dropdown. No-op if already open or disabled.
+   */
+  open(): void {
+    if (this._opts.disabled) return;
+    if (!this._dropdown.isOpen) this._dropdown.open();
+  }
+
+  /**
+   * Closes the suggestion dropdown. No-op if already closed.
+   */
+  close(): void {
+    if (this._dropdown.isOpen) this._dropdown.close();
+  }
+
+  // ── 10.14 / 10.15  focus / blur ────────────────────────────
+
+  /**
+   * Focuses the combobox input element.
+   */
+  focus(): void {
+    this._input.focus();
+  }
+
+  /**
+   * Blurs the combobox input element.
+   */
+  blur(): void {
+    this._input.blur();
+  }
+
+  // ── 10.16  settings ────────────────────────────────────────
+
+  /**
+   * Updates one or more runtime options after initialisation.
+   *
+   * Only the provided keys are applied; unprovided keys retain their
+   * current values. Each option triggers specific side effects:
+   *
+   * - `disabled` — enables/disables the input, hidden input, and chip
+   *   remove buttons; toggles `.taga11y--disabled` class.
+   * - `theme` — sets or removes `data-theme` on the wrapper.
+   * - `maxTags` — updates the selection manager's limit.
+   * - `maxSuggestions` — updates the dropdown display cap; takes effect on the
+   *   next filter (does not re-render an already-open dropdown).
+   * - `delimiter` — updates delimiter characters.
+   * - `enforceSuggestions` — toggles whitelist mode.
+   * - `label` — creates, updates, or removes the visible label element.
+   * - `suggestions` — replaces the suggestion source.
+   * - `debounceMs` — updates the debounce delay for dynamic mode.
+   * - `serialize` — updates the hidden input serializer.
+   * - `deserialize` — updates the initial-value parser; takes effect on the
+   *   next form reset (does not retroactively re-parse current tags).
+   * - `name` — updates the hidden input's name attribute.
+   *
+   * @param newOptions - Partial options object with keys to update.
+   */
+  settings(newOptions: Partial<Taga11yOptions>): void {
+    if ('i18n' in newOptions) {
+      console.warn(
+        'taga11y: i18n is init-only and cannot be changed via settings(); ' +
+          'use destroy() + new Taga11y() to switch locale. Ignoring i18n; ' +
+          'other provided keys are still applied.',
+      );
+    }
+
+    if ('disabled' in newOptions) {
+      const disabled = newOptions.disabled ?? false;
+      this._opts.disabled = disabled;
+      this._input.disabled = disabled;
+      this._dom.hiddenInput.disabled = disabled;
+      this._dom.tagList
+        .querySelectorAll<HTMLButtonElement>('.taga11y__tag-remove')
+        .forEach((btn) => { btn.hidden = disabled; });
+      this._dom.wrapper.classList.toggle('taga11y--disabled', disabled);
+    }
+
+    if ('theme' in newOptions) {
+      const theme = resolveTheme(newOptions.theme);
+      this._opts.theme = theme;
+      if (theme) {
+        this._dom.wrapper.setAttribute('data-theme', theme);
+      } else {
+        this._dom.wrapper.removeAttribute('data-theme');
+      }
+    }
+
+    if ('maxTags' in newOptions) {
+      this._opts.maxTags = newOptions.maxTags;
+      this._selection.setMaxTags(newOptions.maxTags);
+    }
+
+    if ('maxSuggestions' in newOptions) {
+      this._opts.maxSuggestions = Math.max(0, newOptions.maxSuggestions ?? 10);
+      this._dropdown.setMaxSuggestions(this._opts.maxSuggestions);
+    }
+
+    if ('delimiter' in newOptions) {
+      const d = newOptions.delimiter;
+      this._opts.delimiter = Array.isArray(d) ? d : d ? [d] : [',', 'Enter'];
+    }
+
+    if ('enforceSuggestions' in newOptions) {
+      this._opts.enforceSuggestions = newOptions.enforceSuggestions ?? false;
+    }
+
+    if ('label' in newOptions) {
+      const labelText = newOptions.label ?? null;
+      let labelEl = this._dom.wrapper.querySelector<HTMLLabelElement>('.taga11y__label');
+      if (labelText == null) {
+        labelEl?.remove();
+      } else {
+        if (!labelEl) {
+          labelEl = document.createElement('label');
+          labelEl.className = 'taga11y__label';
+          labelEl.htmlFor = this._input.id;
+          this._dom.wrapper.insertBefore(labelEl, this._dom.wrapper.firstChild);
+        }
+        labelEl.textContent = labelText;
+      }
+      this._opts.label = labelText ?? undefined;
+    }
+
+    if ('suggestions' in newOptions) {
+      this._opts.suggestions = newOptions.suggestions;
+      this._dropdown.setSource(newOptions.suggestions, this._opts.debounceMs);
+    }
+
+    if ('debounceMs' in newOptions) {
+      this._opts.debounceMs = Math.max(0, newOptions.debounceMs ?? 200);
+      this._dropdown.setDebounceMs(this._opts.debounceMs);
+    }
+
+    if ('serialize' in newOptions && newOptions.serialize) {
+      this._opts.serialize = newOptions.serialize;
+      this._syncHiddenInput();
+    }
+
+    if ('deserialize' in newOptions && newOptions.deserialize) {
+      this._opts.deserialize = newOptions.deserialize;
+    }
+
+    if ('name' in newOptions) {
+      const name = newOptions.name ?? '';
+      this._opts.name = name;
+      this._dom.hiddenInput.name = name;
+    }
+  }
+
+  // ── 10.17 / 10.18  on / off ────────────────────────────────
+
+  /**
+   * Registers a listener for a taga11y custom event on the original
+   * input element.
+   *
+   * @param event - Event name. One of `"taga11y:add"`,
+   *   `"taga11y:remove"`, `"taga11y:clear"`, `"taga11y:change"`,
+   *   `"taga11y:paste"`, or `"taga11y:destroy"`. A known event name infers
+   *   the handler's `CustomEvent` detail; any other string is also accepted.
+   * @param handler - Event listener callback.
+   */
+  on<K extends keyof Taga11yEventMap>(
+    event: K,
+    handler: (event: CustomEvent<Taga11yEventMap[K]>) => void,
+  ): void;
+  on(event: string, handler: EventListener): void;
+  on(event: string, handler: (event: CustomEvent<never>) => void): void {
+    this._input.addEventListener(event, handler as EventListener);
+  }
+
+  /**
+   * Removes a previously registered event listener.
+   *
+   * @param event - Event name. Typed identically to {@link Taga11y.on}, so the
+   *   same typed handler reference can be passed to both.
+   * @param handler - The handler to remove.
+   */
+  off<K extends keyof Taga11yEventMap>(
+    event: K,
+    handler: (event: CustomEvent<Taga11yEventMap[K]>) => void,
+  ): void;
+  off(event: string, handler: EventListener): void;
+  off(event: string, handler: (event: CustomEvent<never>) => void): void {
+    this._input.removeEventListener(event, handler as EventListener);
+  }
+
+  // ── 10.19  emit ────────────────────────────────────────────
+
+  /**
+   * Dispatches a custom event on the original input element.
+   *
+   * All events bubble and are not cancelable.
+   *
+   * @param event - Event name.
+   * @param data - Event detail payload.
+   */
+  emit(event: string, data: Record<string, unknown>): void {
+    this._input.dispatchEvent(
+      new CustomEvent(event, { detail: data, bubbles: true, cancelable: false }),
+    );
+  }
+
+  // ── 10.20  Computed getters ────────────────────────────────
+
+  /**
+   * Read-only property returning the current tag array (defensive copy).
+   * Equivalent to `getTags()`.
+   */
+  get tags(): TagData[] {
+    return this._selection.getTags();
+  }
+
+  /**
+   * Read-only property indicating whether the suggestion dropdown
+   * is currently visible.
+   */
+  get isOpen(): boolean {
+    return this._dropdown.isOpen;
+  }
+
+  /**
+   * Read-only property indicating whether the maximum tag count
+   * has been reached (when `maxTags` is configured).
+   */
+  get maxTagsReached(): boolean {
+    if (this._opts.maxTags === undefined) return false;
+    return this._selection.getTags().length >= this._opts.maxTags;
+  }
+
+  // ── Private helpers ────────────────────────────────────────
+
+  private _parseOptions(options: Taga11yOptions): ResolvedOptions {
+    if (options.suggestions && !Array.isArray(options.suggestions)) {
+      const src = options.suggestions as Record<string, unknown>;
+      if ('once' in src && 'query' in src) {
+        throw new Error("suggestions source cannot define both 'once' and 'query'");
+      }
+    }
+
+    const delimiter = options.delimiter;
+    return {
+      suggestions: options.suggestions,
+      maxTags: options.maxTags,
+      maxSuggestions: Math.max(0, options.maxSuggestions ?? 10),
+      delimiter: Array.isArray(delimiter)
+        ? delimiter
+        : delimiter
+          ? [delimiter]
+          : [',', 'Enter'],
+      enforceSuggestions: options.enforceSuggestions ?? false,
+      name: options.name ?? this._originalName,
+      label: options.label,
+      disabled: options.disabled ?? false,
+      theme: resolveTheme(options.theme),
+      serialize: options.serialize ?? ((tags) => tags.map((t) => t.value).join(',')),
+      deserialize:
+        options.deserialize ??
+        ((raw) => (raw ? raw.split(',').map((v) => v.trim()).filter(Boolean) : [])),
+      debounceMs: Math.max(0, options.debounceMs ?? 200),
+      i18n: options.i18n,
+    };
+  }
+
+  private _handleCommit(value: string): void {
+    // Value arrives here after whitelist check already passed in KeyboardManager
+    const label = this._resolveLabelFromAll(value);
+    const result = this._selection.addTag(value, label);
+    if (result.ok) {
+      this._syncChips();
+      this._syncHiddenInput();
+      this.emit('taga11y:add', { tag: result.tag });
+      this.emit('taga11y:change', { tags: this._selection.getTags() });
+      announceTagAdded(this._dom.announcer, this._strings, this._locale, result.tag.label);
+    } else {
+      this._showRejection(value, result.reason);
+    }
+  }
+
+  private _handlePaste(chunks: string[]): void {
+    const added: TagData[] = [];
+    const skipped: string[] = [];
+
+    for (const chunk of chunks) {
+      let value: string;
+      let label: string;
+      if (this._opts.enforceSuggestions) {
+        const lower = chunk.toLowerCase();
+        const match = this._dropdown.getAllSuggestions().find(
+          (item) => getLabel(item).toLowerCase() === lower,
+        );
+        if (!match) {
+          skipped.push(chunk);
+          continue;
+        }
+        value = getValue(match);
+        label = getLabel(match);
+      } else {
+        value = chunk;
+        label = chunk;
+      }
+      const result = this._selection.addTag(value, label);
+      if (result.ok) {
+        added.push(result.tag);
+        this.emit('taga11y:add', { tag: result.tag });
+      } else {
+        skipped.push(chunk);
+      }
+    }
+
+    if (added.length > 0) {
+      this._syncChips();
+      this._syncHiddenInput();
+      this.emit('taga11y:change', { tags: this._selection.getTags() });
+    }
+    this.emit('taga11y:paste', { added, skipped });
+  }
+
+  private _handleBlurCommit(value: string): void {
+    if (this._opts.enforceSuggestions) {
+      const lower = value.toLowerCase();
+      const match = this._dropdown.getAllSuggestions().find(
+        (item) => getLabel(item).toLowerCase() === lower,
+      );
+      if (!match) {
+        this._showRejection(value, 'not-in-list');
+        this._inputMgr.clearValue();
+        return;
+      }
+      const result = this._selection.addTag(getValue(match), getLabel(match));
+      if (result.ok) {
+        this._syncChips();
+        this._syncHiddenInput();
+        this.emit('taga11y:add', { tag: result.tag });
+        this.emit('taga11y:change', { tags: this._selection.getTags() });
+        announceTagAdded(this._dom.announcer, this._strings, this._locale, result.tag.label);
+      } else {
+        this._showRejection(value, result.reason);
+      }
+    } else {
+      const result = this._selection.addTag(value, value);
+      if (result.ok) {
+        this._syncChips();
+        this._syncHiddenInput();
+        this.emit('taga11y:add', { tag: result.tag });
+        this.emit('taga11y:change', { tags: this._selection.getTags() });
+        announceTagAdded(this._dom.announcer, this._strings, this._locale, result.tag.label);
+      } else {
+        this._showRejection(value, result.reason);
+      }
+    }
+    this._inputMgr.clearValue();
+  }
+
+  private _handleRemove(id: string): void {
+    const removed = this._selection.removeTag(id);
+    if (!removed) return;
+    this._syncChips();
+    this._syncHiddenInput();
+    this.emit('taga11y:remove', { tag: removed });
+    this.emit('taga11y:change', { tags: this._selection.getTags() });
+    announceTagRemoved(this._dom.announcer, this._strings, this._locale, removed.label);
+  }
+
+  private _handleRemoveLast(): void {
+    const tags = this._selection.getTags();
+    if (tags.length === 0) return;
+    this._handleRemove(tags[tags.length - 1]!.id);
+  }
+
+  private _handleFormReset(): void {
+    const cleared = this._selection.clearTags();
+    this.emit('taga11y:clear', { tags: cleared });
+    for (const item of this._initialSnapshot) {
+      const value = getValue(item);
+      const label =
+        typeof item === 'string' ? this._resolveLabelFromAll(value) : getLabel(item);
+      const result = this._selection.addTag(value, label);
+      if (result.ok) this.emit('taga11y:add', { tag: result.tag });
+    }
+    this._syncChips();
+    this._syncHiddenInput();
+    this.emit('taga11y:change', { tags: this._selection.getTags() });
+  }
+
+  private _showRejection(
+    text: string,
+    reason: 'duplicate' | 'max-reached' | 'not-in-list',
+  ): void {
+    this._dom.tagList.querySelector('.taga11y__tag--error')?.remove();
+    const chip = createErrorChip(text);
+    this._dom.tagList.appendChild(chip);
+    announceRejection(this._dom.error, this._strings, this._locale, reason, text, chip);
+  }
+
+  private _syncChips(): void {
+    const errorChip =
+      this._dom.tagList.querySelector<HTMLLIElement>('.taga11y__tag--error') ?? undefined;
+    updateChips(
+      this._dom.tagList,
+      this._selection.getTags(),
+      (id) => this._handleRemove(id),
+      this._strings,
+      this._locale,
+      errorChip,
+      () => this._input.focus(),
+    );
+    if (this._opts.disabled) {
+      this._dom.tagList
+        .querySelectorAll<HTMLButtonElement>('.taga11y__tag-remove')
+        .forEach((btn) => { btn.hidden = true; });
+    }
+  }
+
+  private _announceTagsSummary(): void {
+    announceTagsSummary(
+      this._dom.announcer,
+      this._strings,
+      this._locale,
+      this._selection.getTags(),
+    );
+  }
+
+  private _syncHiddenInput(): void {
+    this._dom.hiddenInput.value = this._opts.serialize(this._selection.getTags());
+  }
+
+  private _resolveLabelFromAll(value: string): string {
+    const match = this._dropdown.getAllSuggestions().find((item) => getValue(item) === value);
+    return match ? getLabel(match) : value;
+  }
+}