taga11y 1.0.0

package/src/a11y.ts

@@ -0,0 +1,85 @@
+import { announce, ariaNotifySupported } from './dom/render.js';
+import { t } from './i18n.js';
+import type { I18nStrings, TagData } from './types.js';
+
+export function showError(
+  error: HTMLDivElement,
+  message: string,
+  errorChip?: HTMLElement,
+): void {
+  error.textContent = message;
+  error.hidden = false;
+  // role="alert" announces the set above; when absent (ariaNotify supported), notify instead.
+  if (ariaNotifySupported()) {
+    announce(error, message, 'high');
+  }
+  setTimeout(() => {
+    hideError(error);
+    errorChip?.remove();
+  }, 3000);
+}
+
+function hideError(error: HTMLDivElement): void {
+  error.textContent = '';
+  error.hidden = true;
+}
+
+export function announceTagAdded(
+  announcer: HTMLDivElement,
+  strings: I18nStrings,
+  locale: string,
+  label: string,
+): void {
+  announce(announcer, t(strings, locale, 'a11y.tagAdded', { label }));
+}
+
+export function announceTagRemoved(
+  announcer: HTMLDivElement,
+  strings: I18nStrings,
+  locale: string,
+  label: string,
+): void {
+  announce(announcer, t(strings, locale, 'a11y.tagRemoved', { label }));
+}
+
+export function announceTagsCleared(
+  announcer: HTMLDivElement,
+  strings: I18nStrings,
+  locale: string,
+): void {
+  announce(announcer, t(strings, locale, 'a11y.tagsCleared'));
+}
+
+export function announceTagsSummary(
+  announcer: HTMLDivElement,
+  strings: I18nStrings,
+  locale: string,
+  tags: TagData[],
+): void {
+  if (tags.length === 0) return;
+  const labels = new Intl.ListFormat(locale, {
+    type: 'conjunction',
+    style: 'long',
+  }).format(tags.map((tag) => tag.label));
+  announce(
+    announcer,
+    t(strings, locale, 'a11y.tagsSummary', { n: tags.length, labels }),
+  );
+}
+
+export function announceRejection(
+  error: HTMLDivElement,
+  strings: I18nStrings,
+  locale: string,
+  reason: 'duplicate' | 'max-reached' | 'not-in-list',
+  label: string,
+  errorChip?: HTMLElement,
+): void {
+  const message =
+    reason === 'duplicate'
+      ? t(strings, locale, 'error.duplicate', { label })
+      : reason === 'max-reached'
+        ? t(strings, locale, 'error.maxReached')
+        : t(strings, locale, 'error.notInList');
+  showError(error, message, errorChip);
+}

package/src/aria-notify.d.ts

@@ -0,0 +1,9 @@
+// Ambient declaration for the standards-track Document.ariaNotify() API
+// (ARIA ARIANotifyMixin), not yet present in TypeScript's lib.dom.d.ts.
+// Optional so feature detection typechecks and its absence (e.g. Safari) is valid.
+interface Document {
+  ariaNotify?(
+    message: string,
+    options?: { priority?: 'normal' | 'high' },
+  ): void;
+}

package/src/core/dropdown.ts

@@ -0,0 +1,331 @@
+import type { SuggestionItem, SuggestionsSource, I18nStrings } from '../types.js';
+import type { DerivedIds } from '../utils/id.js';
+import { filter as filterItems, getValue } from '../utils/filter.js';
+import { debounce, type DebouncedFn } from '../utils/debounce.js';
+import { updateListbox } from '../dom/listbox.js';
+import { t } from '../i18n.js';
+
+export class DropdownManager {
+  private readonly listbox: HTMLUListElement;
+  private readonly input: HTMLInputElement;
+  private readonly loading: HTMLLIElement;
+  private readonly wrapper: HTMLElement;
+  private readonly ids: DerivedIds;
+  private readonly strings: I18nStrings;
+  private readonly locale: string;
+  private maxSuggestions: number;
+  private source: SuggestionsSource | undefined;
+  private readonly getSelectedValues: () => string[];
+  private readonly onAnnounce: (message: string) => void;
+  private readonly onLoadError: (message: string) => void;
+  private readonly onOptionSelect: ((item: SuggestionItem) => void) | undefined;
+
+  isOpen = false;
+  private activeIndex = -1;
+  filteredSuggestions: SuggestionItem[] = [];
+  private isLoading = false;
+  private cachedItems: SuggestionItem[] | null = null;
+  private _isPrefetching = false;
+  private abortController: AbortController | null = null;
+  private debouncedQuery: DebouncedFn<[string]> | null = null;
+  private readonly resizeObserver: ResizeObserver;
+
+  constructor(
+    elements: {
+      listbox: HTMLUListElement;
+      input: HTMLInputElement;
+      loading: HTMLLIElement;
+      wrapper: HTMLElement;
+    },
+    options: {
+      suggestions?: SuggestionsSource;
+      debounceMs: number;
+      maxSuggestions: number;
+      getSelectedValues: () => string[];
+      ids: DerivedIds;
+      strings: I18nStrings;
+      locale: string;
+      onAnnounce?: (message: string) => void;
+      onLoadError?: (message: string) => void;
+      onOptionSelect?: (item: SuggestionItem) => void;
+    },
+  ) {
+    this.listbox = elements.listbox;
+    this.input = elements.input;
+    this.loading = elements.loading;
+    this.wrapper = elements.wrapper;
+    this.ids = options.ids;
+    this.strings = options.strings;
+    this.locale = options.locale;
+    this.maxSuggestions = options.maxSuggestions;
+    this.source = options.suggestions;
+    this.getSelectedValues = options.getSelectedValues;
+    this.onAnnounce = options.onAnnounce ?? (() => undefined);
+    this.onLoadError = options.onLoadError ?? (() => undefined);
+    this.onOptionSelect = options.onOptionSelect;
+
+    if (this.source && 'query' in this.source) {
+      const src = this.source;
+      this.debouncedQuery = debounce((query: string) => {
+        void this.executeDynamicQuery(src, query);
+      }, options.debounceMs);
+    }
+
+    if (this.source && 'once' in this.source) {
+      void this.startPrefetch(this.source);
+    }
+
+    this.resizeObserver = new ResizeObserver(() => {
+      // CSS (width:100% on .taga11y__listbox) keeps the listbox aligned;
+      // this hook exists for future JS-side overrides if needed.
+    });
+    this.resizeObserver.observe(this.wrapper);
+
+    this.listbox.addEventListener('mousedown', (e) => {
+      const target = (e.target as Element).closest('[role="option"]');
+      if (!target) return;
+      e.preventDefault();
+      const options = Array.from(this.listbox.querySelectorAll<HTMLElement>('[role="option"]'));
+      const index = options.indexOf(target as HTMLElement);
+      if (index === -1) return;
+      const item = this.filteredSuggestions[index];
+      if (item !== undefined) this.onOptionSelect?.(item);
+    });
+  }
+
+  private async startPrefetch(src: { once: () => Promise<SuggestionItem[]> }): Promise<void> {
+    this._isPrefetching = true;
+    try {
+      this.cachedItems = await src.once();
+      this._isPrefetching = false;
+      if (this.isLoading) {
+        // User opened dropdown while fetch was in flight — now render results.
+        this.setLoading(false);
+        this.filter(this.input.value);
+      }
+    } catch {
+      this._isPrefetching = false;
+      if (this.isLoading) this.setLoading(false);
+      this.onLoadError(t(this.strings, this.locale, 'error.loadError'));
+    }
+  }
+
+  private async executeDynamicQuery(
+    src: { query: (input: string, signal: AbortSignal) => Promise<SuggestionItem[]> },
+    query: string,
+  ): Promise<void> {
+    this.abortController?.abort();
+    this.abortController = new AbortController();
+    const { signal } = this.abortController;
+
+    this.setLoading(true);
+
+    try {
+      const results = await src.query(query, signal);
+      if (signal.aborted) return;
+
+      const selected = this.getSelectedValues();
+      const filtered = filterItems(results, query)
+        .filter((item) => !selected.includes(getValue(item)))
+        .slice(0, this.maxSuggestions);
+
+      this.filteredSuggestions = filtered;
+      this.setLoading(false);
+
+      if (filtered.length === 0) {
+        this.close();
+        this.onAnnounce(t(this.strings, this.locale, 'a11y.noResults'));
+      } else {
+        updateListbox(this.listbox, this.loading, this.input, filtered, false, this.ids);
+        if (!this.isOpen) this.open();
+        this.onAnnounce(
+          t(this.strings, this.locale, 'a11y.resultsCount', { n: filtered.length }),
+        );
+        this.highlightFirst();
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') return;
+      this.setLoading(false);
+      this.close();
+      this.onLoadError(t(this.strings, this.locale, 'error.loadError'));
+    }
+  }
+
+  open(): void {
+    this.listbox.hidden = false;
+    this.input.setAttribute('aria-expanded', 'true');
+    this.isOpen = true;
+  }
+
+  close(): void {
+    // Cancel any pending debounce + in-flight query so they can't reopen
+    // the dropdown asynchronously after this close gesture.
+    this.debouncedQuery?.cancel();
+    this.abortController?.abort();
+    this.listbox.hidden = true;
+    this.input.setAttribute('aria-expanded', 'false');
+    this.input.removeAttribute('aria-activedescendant');
+    this.activeIndex = -1;
+    this.loading.hidden = true;
+    this.isLoading = false;
+    this.isOpen = false;
+  }
+
+  toggle(): void {
+    if (this.isOpen) {
+      this.close();
+    } else {
+      this.open();
+    }
+  }
+
+  filter(query: string): void {
+    if (!this.source) return;
+
+    const trimmed = query.trim();
+
+    if ('query' in this.source) {
+      // Dynamic mode: only trigger on non-empty query
+      if (!trimmed) return;
+      this.debouncedQuery!(trimmed);
+      return;
+    }
+
+    if ('once' in this.source && this.cachedItems === null && this._isPrefetching) {
+      // Prefetch still in flight — show loading indicator and wait for completion.
+      this.setLoading(true);
+      return;
+    }
+
+    const baseItems: SuggestionItem[] = 'once' in this.source
+      ? (this.cachedItems ?? [])
+      : this.source;
+
+    const selected = this.getSelectedValues();
+    const filtered = filterItems(baseItems, trimmed)
+      .filter((item) => !selected.includes(getValue(item)))
+      .slice(0, this.maxSuggestions);
+
+    this.filteredSuggestions = filtered;
+    updateListbox(this.listbox, this.loading, this.input, filtered, false, this.ids);
+
+    if (filtered.length === 0) {
+      this.close();
+      this.onAnnounce(t(this.strings, this.locale, 'a11y.noResults'));
+    } else {
+      if (!this.isOpen) this.open();
+      this.onAnnounce(
+        t(this.strings, this.locale, 'a11y.resultsCount', { n: filtered.length }),
+      );
+      this.highlightFirst();
+    }
+  }
+
+  setActiveIndex(index: number): void {
+    const options = Array.from(this.listbox.querySelectorAll<HTMLElement>('[role="option"]'));
+
+    options.forEach((opt) => opt.setAttribute('aria-selected', 'false'));
+
+    if (index < 0 || index >= options.length) {
+      this.activeIndex = -1;
+      this.input.removeAttribute('aria-activedescendant');
+      return;
+    }
+
+    this.activeIndex = index;
+    const activeOpt = options[index];
+    if (activeOpt) {
+      activeOpt.setAttribute('aria-selected', 'true');
+      this.input.setAttribute('aria-activedescendant', activeOpt.id);
+    }
+  }
+
+  highlightFirst(): void {
+    this.setActiveIndex(0);
+  }
+
+  highlightPrev(): void {
+    const count = this.filteredSuggestions.length;
+    if (count === 0) return;
+    const prev = this.activeIndex <= 0 ? count - 1 : this.activeIndex - 1;
+    this.setActiveIndex(prev);
+  }
+
+  highlightNext(): void {
+    const count = this.filteredSuggestions.length;
+    if (count === 0) return;
+    const next = this.activeIndex >= count - 1 ? 0 : this.activeIndex + 1;
+    this.setActiveIndex(next);
+  }
+
+  highlightHome(): void {
+    this.setActiveIndex(0);
+  }
+
+  highlightEnd(): void {
+    this.setActiveIndex(this.filteredSuggestions.length - 1);
+  }
+
+  selectActive(): SuggestionItem | null {
+    if (this.activeIndex < 0) return null;
+    return this.filteredSuggestions[this.activeIndex] ?? null;
+  }
+
+  setLoading(value: boolean): void {
+    this.isLoading = value;
+    updateListbox(this.listbox, this.loading, this.input, this.filteredSuggestions, value, this.ids);
+    if (value) {
+      if (!this.isOpen) this.open();
+      this.onAnnounce(t(this.strings, this.locale, 'ui.loading'));
+    }
+  }
+
+  setSource(source: SuggestionsSource | undefined, debounceMs: number): void {
+    this.debouncedQuery?.cancel();
+    this.abortController?.abort();
+    this.abortController = null;
+    this.cachedItems = null;
+    this._isPrefetching = false;
+    this.source = source;
+
+    if (source && 'query' in source) {
+      const src = source;
+      this.debouncedQuery = debounce((query: string) => {
+        void this.executeDynamicQuery(src, query);
+      }, debounceMs);
+    } else {
+      this.debouncedQuery = null;
+    }
+
+    if (source && 'once' in source) {
+      void this.startPrefetch(source);
+    }
+  }
+
+  setDebounceMs(debounceMs: number): void {
+    if (!this.source || !('query' in this.source)) return;
+    const src = this.source;
+    this.debouncedQuery?.cancel();
+    this.debouncedQuery = debounce((query: string) => {
+      void this.executeDynamicQuery(src, query);
+    }, debounceMs);
+  }
+
+  setMaxSuggestions(maxSuggestions: number): void {
+    // Lazy: the new cap governs the next filter; an open dropdown is untouched.
+    this.maxSuggestions = maxSuggestions;
+  }
+
+  getAllSuggestions(): SuggestionItem[] {
+    if (!this.source) return [];
+    if (Array.isArray(this.source)) return this.source;
+    if ('once' in this.source) return this.cachedItems ?? [];
+    return this.filteredSuggestions;
+  }
+
+  destroy(): void {
+    this.debouncedQuery?.cancel();
+    this.abortController?.abort();
+    this.resizeObserver.disconnect();
+  }
+}

package/src/core/input.ts

@@ -0,0 +1,172 @@
+import type { SuggestionItem } from '../types.js';
+import { getLabel, getValue } from '../utils/filter.js';
+
+export class InputManager {
+  private readonly input: HTMLInputElement;
+  private readonly onInput: (value: string) => void;
+  private readonly onBlurCommit: (value: string) => void;
+  private readonly onBlurClose: () => void;
+  private readonly onFocus: (() => void) | undefined;
+  private readonly getDelimiters: () => string[];
+  private readonly isEnforceSuggestions: () => boolean;
+  private readonly getLoadedSuggestions: () => SuggestionItem[];
+  private readonly onCommit: (value: string) => void;
+  private readonly onCommitRejected: (value: string) => void;
+  private readonly onPaste: (chunks: string[]) => void;
+  private readonly onCloseDropdown: () => void;
+
+  private currentValue = '';
+  private blurTimer: ReturnType<typeof setTimeout> | undefined;
+
+  private readonly handleInput: () => void;
+  private readonly handleFocus: () => void;
+  private readonly handleBlur: () => void;
+  private readonly handlePaste: (e: ClipboardEvent) => void;
+
+  constructor(
+    input: HTMLInputElement,
+    callbacks: {
+      onInput: (value: string) => void;
+      onBlurCommit: (value: string) => void;
+      onBlurClose: () => void;
+      onFocus?: () => void;
+      getDelimiters?: () => string[];
+      isEnforceSuggestions?: () => boolean;
+      getLoadedSuggestions?: () => SuggestionItem[];
+      onCommit?: (value: string) => void;
+      onCommitRejected?: (value: string) => void;
+      onPaste?: (chunks: string[]) => void;
+      onCloseDropdown?: () => void;
+    },
+  ) {
+    this.input = input;
+    this.onInput = callbacks.onInput;
+    this.onBlurCommit = callbacks.onBlurCommit;
+    this.onBlurClose = callbacks.onBlurClose;
+    this.onFocus = callbacks.onFocus;
+    this.getDelimiters = callbacks.getDelimiters ?? (() => []);
+    this.isEnforceSuggestions = callbacks.isEnforceSuggestions ?? (() => false);
+    this.getLoadedSuggestions = callbacks.getLoadedSuggestions ?? (() => []);
+    this.onCommit = callbacks.onCommit ?? (() => undefined);
+    this.onCommitRejected = callbacks.onCommitRejected ?? (() => undefined);
+    this.onPaste = callbacks.onPaste ?? (() => undefined);
+    this.onCloseDropdown = callbacks.onCloseDropdown ?? (() => undefined);
+
+    this.handleInput = () => {
+      this.currentValue = this.input.value;
+      const charDelims = this.getCharDelimiters();
+      if (charDelims.length > 0 && this.containsAny(this.currentValue, charDelims)) {
+        this.extractAndCommit(charDelims);
+        return;
+      }
+      this.onInput(this.currentValue);
+    };
+
+    this.handleFocus = () => {
+      this.onFocus?.();
+    };
+
+    this.handleBlur = () => {
+      clearTimeout(this.blurTimer);
+      this.blurTimer = setTimeout(() => {
+        if (this.currentValue) {
+          this.onBlurCommit(this.currentValue);
+        }
+        this.onBlurClose();
+      }, 150);
+    };
+
+    this.handlePaste = (e: ClipboardEvent) => {
+      const text = e.clipboardData?.getData('text') ?? '';
+      if (!text) return;
+      const charDelims = this.getCharDelimiters();
+      if (charDelims.length === 0 || !this.containsAny(text, charDelims)) return;
+      e.preventDefault();
+      const pattern = new RegExp(`[${escapeForCharClass(charDelims.join(''))}]`);
+      const chunks = text.split(pattern).map((p) => p.trim()).filter((p) => p !== '');
+      this.input.value = '';
+      this.currentValue = '';
+      this.onPaste(chunks);
+      this.onCloseDropdown();
+    };
+
+    this.input.addEventListener('input', this.handleInput);
+    this.input.addEventListener('focus', this.handleFocus);
+    this.input.addEventListener('blur', this.handleBlur);
+    this.input.addEventListener('paste', this.handlePaste);
+  }
+
+  clearValue(): void {
+    this.input.value = '';
+    this.currentValue = '';
+  }
+
+  getValue(): string {
+    return this.currentValue;
+  }
+
+  destroy(): void {
+    clearTimeout(this.blurTimer);
+    this.input.removeEventListener('input', this.handleInput);
+    this.input.removeEventListener('focus', this.handleFocus);
+    this.input.removeEventListener('blur', this.handleBlur);
+    this.input.removeEventListener('paste', this.handlePaste);
+  }
+
+  private getCharDelimiters(): string[] {
+    return this.getDelimiters().filter((d) => d.length === 1);
+  }
+
+  private containsAny(value: string, chars: string[]): boolean {
+    for (const c of chars) {
+      if (value.indexOf(c) !== -1) return true;
+    }
+    return false;
+  }
+
+  private extractAndCommit(charDelims: string[]): void {
+    // Trim each split chunk independently, then treat the LAST chunk as the
+    // editable remainder (or terminating signal if it trims to empty). This
+    // correctly handles soft keyboards that autospace after punctuation —
+    // e.g. FUTO inserts ", " (comma + space) for a single comma tap, which
+    // means `input.value === "test, "` ends with a space, not a delimiter.
+    // The old "endsWithDelim = last char is delimiter" check missed this.
+    const value = this.currentValue;
+    const pattern = new RegExp(`[${escapeForCharClass(charDelims.join(''))}]`);
+    const trimmedParts = value.split(pattern).map((p) => p.trim());
+    const remainder = trimmedParts[trimmedParts.length - 1] ?? '';
+    const commits = trimmedParts.slice(0, -1).filter((p) => p !== '');
+
+    for (const chunk of commits) {
+      this.commitChunk(chunk);
+    }
+
+    this.input.value = remainder;
+    this.currentValue = remainder;
+    if (remainder) {
+      this.onInput(remainder);
+    } else {
+      this.onCloseDropdown();
+    }
+  }
+
+  private commitChunk(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);
+    }
+  }
+}
+
+function escapeForCharClass(chars: string): string {
+  return chars.replace(/[\\\]^-]/g, (m) => `\\${m}`);
+}