taga11y 1.0.0

package/src/core/keyboard.ts

@@ -0,0 +1,200 @@
+import type { SuggestionsSource, SuggestionItem } from '../types.js';
+import type { DropdownManager } from './dropdown.js';
+import { getLabel, getValue } from '../utils/filter.js';
+
+export class KeyboardManager {
+  private readonly input: HTMLInputElement;
+  private readonly onCommit: (value: string) => void;
+  private readonly onCommitRejected: (value: string) => void;
+  private readonly onRemoveLast: () => void;
+  private readonly clearInput: () => void;
+  private readonly hasChips: () => boolean;
+  private readonly getDropdown: () => DropdownManager;
+  private readonly getDelimiters: () => string[];
+  private readonly isEnforceSuggestions: () => boolean;
+  private readonly getSuggestionSource: () => SuggestionsSource | undefined;
+  private readonly getLoadedSuggestions: () => SuggestionItem[];
+
+  private readonly handleKeydown: (e: KeyboardEvent) => void;
+
+  constructor(
+    input: HTMLInputElement,
+    callbacks: {
+      onCommit: (value: string) => void;
+      onCommitRejected: (value: string) => void;
+      onRemoveLast: () => void;
+      clearInput: () => void;
+      hasChips: () => boolean;
+      getDropdown: () => DropdownManager;
+      getDelimiters: () => string[];
+      isEnforceSuggestions: () => boolean;
+      getSuggestionSource: () => SuggestionsSource | undefined;
+      getLoadedSuggestions: () => SuggestionItem[];
+    },
+  ) {
+    this.input = input;
+    this.onCommit = callbacks.onCommit;
+    this.onCommitRejected = callbacks.onCommitRejected;
+    this.onRemoveLast = callbacks.onRemoveLast;
+    this.clearInput = callbacks.clearInput;
+    this.hasChips = callbacks.hasChips;
+    this.getDropdown = callbacks.getDropdown;
+    this.getDelimiters = callbacks.getDelimiters;
+    this.isEnforceSuggestions = callbacks.isEnforceSuggestions;
+    this.getSuggestionSource = callbacks.getSuggestionSource;
+    this.getLoadedSuggestions = callbacks.getLoadedSuggestions;
+
+    this.handleKeydown = (e: KeyboardEvent) => this.routeKey(e);
+    this.input.addEventListener('keydown', this.handleKeydown);
+  }
+
+  private routeKey(e: KeyboardEvent): void {
+    const dropdown = this.getDropdown();
+    const delimiters = this.getDelimiters();
+
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        this.handleArrowDown(dropdown);
+        break;
+
+      case 'ArrowUp':
+        e.preventDefault();
+        this.handleArrowUp(dropdown);
+        break;
+
+      case 'Home':
+        if (dropdown.isOpen) {
+          e.preventDefault();
+          dropdown.highlightHome();
+        }
+        break;
+
+      case 'End':
+        if (dropdown.isOpen) {
+          e.preventDefault();
+          dropdown.highlightEnd();
+        }
+        break;
+
+      case 'Enter':
+        this.handleEnter(dropdown, e);
+        break;
+
+      case 'Escape':
+        if (dropdown.isOpen) {
+          e.preventDefault();
+          dropdown.close();
+        }
+        break;
+
+      case 'Tab':
+        // never preventDefault() for Tab
+        this.handleTab(dropdown);
+        break;
+
+      case 'Backspace':
+        this.handleBackspace(e);
+        break;
+
+      default:
+        // delimiter key handling — excludes Enter and Tab (handled above)
+        if (e.key !== 'Enter' && e.key !== 'Tab' && delimiters.includes(e.key)) {
+          if (this.input.value) {
+            e.preventDefault();
+            this.commit(this.input.value);
+          }
+        }
+    }
+  }
+
+  private handleArrowDown(dropdown: DropdownManager): void {
+    if (dropdown.isOpen) {
+      dropdown.highlightNext();
+      return;
+    }
+
+    const source = this.getSuggestionSource();
+    const inputEmpty = !this.input.value;
+
+    if (inputEmpty && source && 'query' in source) {
+      // dynamic mode + empty input: do nothing
+      return;
+    }
+
+    // static/pre-fetched with empty input, or any mode with text → open + highlight first
+    if (inputEmpty && source) {
+      dropdown.filter('');
+    }
+    if (!dropdown.isOpen) dropdown.open();
+    dropdown.highlightFirst();
+  }
+
+  private handleArrowUp(dropdown: DropdownManager): void {
+    if (!dropdown.isOpen) return;
+    dropdown.highlightPrev();
+  }
+
+  private handleEnter(dropdown: DropdownManager, e: KeyboardEvent): void {
+    if (!dropdown.isOpen) {
+      // closed: treat as delimiter
+      e.preventDefault();
+      if (this.input.value) this.commit(this.input.value);
+      return;
+    }
+
+    e.preventDefault();
+    const selected = dropdown.selectActive();
+
+    if (selected !== null) {
+      // active suggestion selected
+      dropdown.close();
+      this.onCommit(getValue(selected));
+      this.clearInput();
+    } else {
+      // no active item — free-text commit
+      dropdown.close();
+      if (this.input.value) this.commit(this.input.value);
+    }
+  }
+
+  private handleTab(dropdown: DropdownManager): void {
+    const delimiters = this.getDelimiters();
+    if (delimiters.includes('Tab') && this.input.value) {
+      // commit and let browser move focus; blur fires on cleared input → no double-commit
+      this.commit(this.input.value);
+    }
+    // else: let browser handle Tab; blur-commit handles any pending text
+    dropdown.close();
+  }
+
+  private handleBackspace(e: KeyboardEvent): void {
+    if (this.input.value) return; // browser handles character deletion
+    if (this.hasChips()) {
+      e.preventDefault();
+      this.onRemoveLast();
+    }
+  }
+
+  private commit(rawValue: string): void {
+    if (this.isEnforceSuggestions()) {
+      const lower = rawValue.toLowerCase();
+      const match = this.getLoadedSuggestions().find(
+        (item) => getLabel(item).toLowerCase() === lower,
+      );
+      if (!match) {
+        this.onCommitRejected(rawValue);
+        return;
+      }
+      this.onCommit(getValue(match));
+    } else {
+      this.onCommit(rawValue);
+    }
+    this.clearInput();
+    this.getDropdown().close();
+  }
+
+  destroy(): void {
+    this.input.removeEventListener('keydown', this.handleKeydown);
+  }
+}

package/src/core/selection.ts

@@ -0,0 +1,78 @@
+import type { TagData, SuggestionItem } from '../types.js';
+import { getLabel, getValue } from '../utils/filter.js';
+
+export type AddTagResult =
+  | { ok: true; tag: TagData }
+  | { ok: false; reason: 'duplicate' | 'max-reached' };
+
+export class SelectionManager {
+  private tags: TagData[] = [];
+  private nextId = 0;
+  private readonly base: string;
+  private maxTags: number | undefined;
+
+  constructor(base: string, maxTags?: number) {
+    this.base = base;
+    this.maxTags = maxTags;
+  }
+
+  addTag(value: string, label?: string): AddTagResult {
+    if (this.maxTags !== undefined && this.tags.length >= this.maxTags) {
+      return { ok: false, reason: 'max-reached' };
+    }
+
+    const isDuplicate = this.tags.some((t) => t.value.toLowerCase() === value.toLowerCase());
+    if (isDuplicate) {
+      return { ok: false, reason: 'duplicate' };
+    }
+
+    const resolvedLabel = label ?? value;
+    const tag: TagData = {
+      id: `${this.base}-tag-${this.nextId++}`,
+      label: resolvedLabel,
+      value,
+    };
+    this.tags.push(tag);
+    return { ok: true, tag };
+  }
+
+  removeTag(id: string): TagData | null {
+    const index = this.tags.findIndex((t) => t.id === id);
+    if (index === -1) return null;
+    const [removed] = this.tags.splice(index, 1);
+    return removed ?? null;
+  }
+
+  clearTags(): TagData[] {
+    const cleared = [...this.tags];
+    this.tags = [];
+    this.nextId = 0;
+    return cleared;
+  }
+
+  getTags(): TagData[] {
+    return [...this.tags];
+  }
+
+  addTags(items: SuggestionItem[]): TagData[] {
+    const added: TagData[] = [];
+    for (const item of items) {
+      const result = this.addTag(getValue(item), getLabel(item));
+      if (result.ok) added.push(result.tag);
+    }
+    return added;
+  }
+
+  setTags(items: SuggestionItem[]): TagData[] {
+    this.clearTags();
+    return this.addTags(items);
+  }
+
+  isTagged(value: string): boolean {
+    return this.tags.some((t) => t.value.toLowerCase() === value.toLowerCase());
+  }
+
+  setMaxTags(maxTags: number | undefined): void {
+    this.maxTags = maxTags;
+  }
+}

package/src/dom/chips.ts

@@ -0,0 +1,80 @@
+import type { TagData, I18nStrings } from '../types.js';
+import { t } from '../i18n.js';
+
+export function createTagsContainer(): HTMLDivElement {
+  const div = document.createElement('div');
+  div.className = 'taga11y__tags';
+  return div;
+}
+
+export function createTagList(
+  strings: I18nStrings,
+  locale: string,
+): HTMLUListElement {
+  const ul = document.createElement('ul');
+  ul.className = 'taga11y__tag-list';
+  ul.setAttribute('aria-label', t(strings, locale, 'a11y.selectedTags'));
+  return ul;
+}
+
+function createChip(
+  tag: TagData,
+  onRemove: (id: string) => void,
+  strings: I18nStrings,
+  locale: string,
+  afterRemove?: () => void,
+): HTMLLIElement {
+  const li = document.createElement('li');
+  li.className = 'taga11y__tag';
+  li.dataset['tagId'] = tag.id;
+
+  const label = document.createElement('span');
+  label.className = 'taga11y__tag-label';
+  label.textContent = tag.label;
+
+  const btn = document.createElement('button');
+  btn.className = 'taga11y__tag-remove';
+  btn.type = 'button';
+  btn.setAttribute('aria-label', t(strings, locale, 'a11y.removeTag', { label: tag.label }));
+  btn.textContent = '×';
+  btn.addEventListener('click', () => {
+    onRemove(tag.id);
+    afterRemove?.();
+  });
+
+  li.appendChild(label);
+  li.appendChild(btn);
+  return li;
+}
+
+export function createErrorChip(text: string): HTMLLIElement {
+  const li = document.createElement('li');
+  li.className = 'taga11y__tag taga11y__tag--error';
+
+  const label = document.createElement('span');
+  label.className = 'taga11y__tag-label';
+  label.textContent = text;
+
+  li.appendChild(label);
+  return li;
+}
+
+export function updateChips(
+  tagList: HTMLUListElement,
+  tags: TagData[],
+  onRemove: (id: string) => void,
+  strings: I18nStrings,
+  locale: string,
+  errorChip?: HTMLLIElement,
+  afterRemove?: () => void,
+): void {
+  Array.from(tagList.children).forEach((child) => child.remove());
+
+  for (const tag of tags) {
+    tagList.appendChild(createChip(tag, onRemove, strings, locale, afterRemove));
+  }
+
+  if (errorChip) {
+    tagList.appendChild(errorChip);
+  }
+}

package/src/dom/listbox.ts

@@ -0,0 +1,49 @@
+import type { SuggestionItem } from '../types.js';
+import type { DerivedIds } from '../utils/id.js';
+import { getLabel } from '../utils/filter.js';
+
+export function createListbox(ids: DerivedIds): HTMLUListElement {
+  const ul = document.createElement('ul');
+  ul.className = 'taga11y__listbox';
+  ul.setAttribute('role', 'listbox');
+  ul.id = ids.listbox;
+  ul.hidden = true;
+  return ul;
+}
+
+function renderOptions(
+  listbox: HTMLUListElement,
+  items: SuggestionItem[],
+  ids: DerivedIds,
+): void {
+  listbox.innerHTML = '';
+  items.forEach((item, n) => {
+    const li = document.createElement('li');
+    li.className = 'taga11y__option';
+    li.setAttribute('role', 'option');
+    li.id = ids.option(n);
+    li.setAttribute('aria-selected', 'false');
+    li.textContent = getLabel(item);
+    listbox.appendChild(li);
+  });
+}
+
+export function updateListbox(
+  listbox: HTMLUListElement,
+  loading: HTMLLIElement,
+  input: HTMLInputElement,
+  items: SuggestionItem[],
+  isLoading: boolean,
+  ids: DerivedIds,
+): void {
+  listbox.querySelectorAll('.taga11y__option').forEach((el) => el.remove());
+  input.removeAttribute('aria-activedescendant');
+
+  if (isLoading) {
+    loading.hidden = false;
+    return;
+  }
+
+  loading.hidden = true;
+  renderOptions(listbox, items, ids);
+}

package/src/dom/render.ts

@@ -0,0 +1,154 @@
+import type { DerivedIds } from '../utils/id.js';
+import type { I18nStrings } from '../types.js';
+import { createTagsContainer, createTagList } from './chips.js';
+import { createListbox } from './listbox.js';
+import { t } from '../i18n.js';
+
+export interface DomElements {
+  wrapper: HTMLDivElement;
+  tagsContainer: HTMLDivElement;
+  tagList: HTMLUListElement;
+  listbox: HTMLUListElement;
+  loading: HTMLLIElement;
+  error: HTMLDivElement;
+  announcer: HTMLDivElement;
+  hiddenInput: HTMLInputElement;
+}
+
+function createLoadingIndicator(
+  strings: I18nStrings,
+  locale: string,
+): HTMLLIElement {
+  const li = document.createElement('li');
+  li.className = 'taga11y__loading';
+  li.setAttribute('aria-hidden', 'true');
+  li.hidden = true;
+
+  const spinner = document.createElement('span');
+  spinner.className = 'taga11y__loading-spinner';
+
+  const text = document.createElement('span');
+  text.className = 'taga11y__loading-text';
+  text.textContent = t(strings, locale, 'ui.loading');
+
+  li.appendChild(spinner);
+  li.appendChild(text);
+  return li;
+}
+
+function createErrorRegion(ids: DerivedIds): HTMLDivElement {
+  const div = document.createElement('div');
+  div.className = 'taga11y__error';
+  if (!ariaNotifySupported()) {
+    div.setAttribute('role', 'alert');
+  }
+  div.id = ids.error;
+  div.hidden = true;
+  return div;
+}
+
+function createAnnouncer(ids: DerivedIds): HTMLDivElement {
+  const div = document.createElement('div');
+  div.className = 'taga11y__announcer';
+  div.setAttribute('aria-live', 'polite');
+  div.setAttribute('aria-atomic', 'true');
+  div.id = ids.announcer;
+  return div;
+}
+
+export function setupCombobox(input: HTMLInputElement, ids: DerivedIds): void {
+  if (!input.id) {
+    input.id = ids.base;
+  }
+  input.classList.add('taga11y__input');
+  input.setAttribute('role', 'combobox');
+  input.setAttribute('aria-autocomplete', 'list');
+  input.setAttribute('aria-haspopup', 'listbox');
+  input.setAttribute('aria-expanded', 'false');
+  input.setAttribute('aria-controls', ids.listbox);
+  input.removeAttribute('aria-activedescendant');
+  input.setAttribute('autocomplete', 'off');
+  input.removeAttribute('name');
+}
+
+export function createHiddenInput(name: string, initialValue: string): HTMLInputElement {
+  const input = document.createElement('input');
+  input.type = 'hidden';
+  input.className = 'taga11y__hidden';
+  input.name = name;
+  input.value = initialValue;
+  return input;
+}
+
+export function ariaNotifySupported(): boolean {
+  return typeof document.ariaNotify === 'function';
+}
+
+export function announce(
+  region: HTMLDivElement,
+  message: string,
+  priority: 'normal' | 'high' = 'normal',
+): void {
+  if (ariaNotifySupported()) {
+    document.ariaNotify!(message, { priority });
+    return;
+  }
+  region.textContent = '';
+  setTimeout(() => {
+    region.textContent = message;
+  }, 0);
+}
+
+export function render(
+  input: HTMLInputElement,
+  ids: DerivedIds,
+  opts: {
+    label?: string;
+    name: string;
+    initialValue: string;
+    strings: I18nStrings;
+    locale: string;
+  },
+): DomElements {
+  const wrapper = document.createElement('div');
+  wrapper.className = 'taga11y';
+
+  if (opts.label) {
+    const labelEl = document.createElement('label');
+    labelEl.className = 'taga11y__label';
+    labelEl.htmlFor = input.id;
+    labelEl.textContent = opts.label;
+    wrapper.appendChild(labelEl);
+  }
+
+  const tagsContainer = createTagsContainer();
+  const tagList = createTagList(opts.strings, opts.locale);
+  tagsContainer.appendChild(tagList);
+  tagsContainer.appendChild(input);
+  wrapper.appendChild(tagsContainer);
+
+  const listbox = createListbox(ids);
+  const loading = createLoadingIndicator(opts.strings, opts.locale);
+  listbox.appendChild(loading);
+  wrapper.appendChild(listbox);
+
+  const error = createErrorRegion(ids);
+  wrapper.appendChild(error);
+
+  const announcer = createAnnouncer(ids);
+  wrapper.appendChild(announcer);
+
+  const hiddenInput = createHiddenInput(opts.name, opts.initialValue);
+  wrapper.appendChild(hiddenInput);
+
+  return {
+    wrapper,
+    tagsContainer,
+    tagList,
+    listbox,
+    loading,
+    error,
+    announcer,
+    hiddenInput,
+  };
+}

package/src/i18n.ts

@@ -0,0 +1,131 @@
+import type { I18nStrings, I18nKey, PluralForms } from './types.js';
+
+/**
+ * Built-in English defaults. Eleven plain strings plus the plural-shaped
+ * `a11y.resultsCount`. These are the fallback for any key not supplied
+ * via the `i18n.strings` option.
+ */
+export const EN: I18nStrings = {
+  'a11y.tagAdded': 'Tag added: {label}',
+  'a11y.tagRemoved': 'Tag removed: {label}',
+  'a11y.tagsCleared': 'Tags cleared',
+  'a11y.noResults': 'No results',
+  'a11y.resultsCount': {
+    one: '{n} result available',
+    other: '{n} results available',
+  },
+  'a11y.tagsSummary': {
+    one: '{n} tag selected: {labels}',
+    other: '{n} tags selected: {labels}',
+  },
+  'a11y.selectedTags': 'Selected tags',
+  'a11y.removeTag': 'Remove {label}',
+  'ui.loading': 'Loading suggestions…',
+  'error.duplicate': 'Already added: {label}',
+  'error.maxReached': 'Maximum tags reached',
+  'error.notInList': 'Not in the list',
+  'error.loadError': 'Failed to load suggestions',
+};
+
+const KEYS = Object.keys(EN) as I18nKey[];
+
+/**
+ * Merges a partial string map over the English defaults at the slot level
+ * (a supplied `a11y.resultsCount` wholly replaces the English default for
+ * that slot — there is no per-category merge). When `provided` is given,
+ * emits a single `console.warn` listing every key that fell back to
+ * English. The plural slot counts as satisfied when present (it must
+ * carry `other`); absent optional CLDR categories are not warned.
+ *
+ * @param provided - Partial overrides, or `undefined` for pure English.
+ */
+export function resolveStrings(provided?: Partial<I18nStrings>): I18nStrings {
+  if (!provided) return { ...EN };
+
+  const resolved = { ...EN, ...provided } as I18nStrings;
+
+  const missing = KEYS.filter((k) => !(k in provided));
+  if (missing.length > 0) {
+    // Dev signal only — never user-visible.
+    console.warn(
+      `taga11y: i18n strings missing ${missing.length} key(s), falling back to English: ${missing.join(', ')}`,
+    );
+  }
+
+  return resolved;
+}
+
+function isPluralForms(value: string | PluralForms): value is PluralForms {
+  return typeof value === 'object' && value !== null;
+}
+
+function interpolate(template: string, vars?: Record<string, string | number>): string {
+  if (!vars) return template;
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in vars ? String(vars[name]) : match,
+  );
+}
+
+/**
+ * Resolves a string slot for the given locale and interpolation vars.
+ *
+ * For the plural-shaped slot, when `vars.n` is present the CLDR category
+ * is selected via `Intl.PluralRules(locale).select(Number(vars.n))`,
+ * falling back to the required `other` form if that category is absent.
+ * Plain-string slots ignore `locale` and resolve placeholders directly.
+ *
+ * @param strings - Resolved string map (post `resolveStrings`).
+ * @param locale - Active widget locale (BCP 47).
+ * @param key - Dot-key slot to resolve.
+ * @param vars - Optional `{placeholder}` substitutions.
+ */
+export function t(
+  strings: I18nStrings,
+  locale: string,
+  key: I18nKey,
+  vars?: Record<string, string | number>,
+): string {
+  const value = strings[key];
+
+  if (isPluralForms(value)) {
+    if (vars && 'n' in vars) {
+      const category = new Intl.PluralRules(locale, { type: 'cardinal' }).select(
+        Number(vars.n),
+      );
+      const template = value[category as keyof PluralForms] ?? value.other;
+      return interpolate(template, vars);
+    }
+    return interpolate(value.other, vars);
+  }
+
+  return interpolate(value, vars);
+}
+
+/** Primary subtag of a BCP 47 tag (`"pt-BR"` → `"pt"`), lowercased. */
+function primarySubtag(tag: string): string {
+  return tag.split('-')[0]!.toLowerCase();
+}
+
+/**
+ * Stamps `lang` on the wrapper when the widget locale differs from the
+ * document's primary language subtag (or the document has no `lang`).
+ * Stamps `dir` only when explicitly provided — direction otherwise
+ * cascades from the parent hierarchy.
+ *
+ * @param wrapper - The widget wrapper element (already in the DOM).
+ * @param locale - Active widget locale.
+ * @param dir - Explicit direction, or `undefined` to inherit.
+ */
+export function applyLocale(
+  wrapper: HTMLElement,
+  locale: string,
+  dir?: 'ltr' | 'rtl',
+): void {
+  const docLang = document.documentElement.getAttribute('lang');
+  if (!docLang || primarySubtag(docLang) !== primarySubtag(locale)) {
+    wrapper.setAttribute('lang', locale);
+  }
+  if (dir) {
+    wrapper.setAttribute('dir', dir);
+  }
+}