taga11y 1.0.0

package/src/types.ts

@@ -0,0 +1,224 @@
+/**
+ * A single suggestion item. Can be a plain string (label equals value)
+ * or an object with a display `label` and a form `value`.
+ */
+export type SuggestionItem = string | { label: string; value: string };
+
+/**
+ * Static suggestion source — a plain array of suggestions evaluated once
+ * at initialisation and filtered in memory thereafter.
+ */
+export type StaticSource = SuggestionItem[];
+
+/**
+ * Pre-fetched suggestion source — a single async call that returns all
+ * suggestions upfront. Results are cached and filtered in memory for
+ * every subsequent filter cycle.
+ */
+export type PrefetchSource = { once: () => Promise<SuggestionItem[]> };
+
+/**
+ * Dynamic suggestion source — an async callback invoked on every keystroke
+ * (debounced). Receives the current input text and an `AbortSignal` that
+ * fires when a newer request supersedes this one.
+ */
+export type DynamicSource = {
+  query: (input: string, signal: AbortSignal) => Promise<SuggestionItem[]>;
+};
+
+/**
+ * The shape accepted by the `suggestions` option. One of:
+ * - `StaticSource` — plain array
+ * - `PrefetchSource` — `{ once }` object
+ * - `DynamicSource` — `{ query }` object
+ *
+ * Defining both `once` and `query` on the same object throws.
+ */
+export type SuggestionsSource = StaticSource | PrefetchSource | DynamicSource;
+
+/**
+ * A single selected tag as stored internally and emitted in event payloads.
+ */
+export interface TagData {
+  /** Unique internal identifier (e.g. `"taga11y-tags-tag-0"`). */
+  id: string;
+  /** Human-readable label displayed in the chip. */
+  label: string;
+  /** Form value committed to the hidden input. */
+  value: string;
+}
+
+/**
+ * CLDR plural-forms value. `other` is always required (every locale has an
+ * `other` category; it is the universal fallback). The remaining categories
+ * are optional and fall back to `other` at resolution time.
+ */
+export type PluralForms = { other: string } & Partial<
+  Record<'zero' | 'one' | 'two' | 'few' | 'many', string>
+>;
+
+/**
+ * Typed map of every user-facing string slot. Eleven slots are plain
+ * strings; `a11y.resultsCount` and `a11y.tagsSummary` are
+ * {@link PluralForms} objects resolved per-locale via `Intl.PluralRules`.
+ * All values are plain JSON.
+ */
+export interface I18nStrings {
+  'a11y.tagAdded': string;
+  'a11y.tagRemoved': string;
+  'a11y.tagsCleared': string;
+  'a11y.noResults': string;
+  'a11y.resultsCount': PluralForms;
+  'a11y.tagsSummary': PluralForms;
+  'a11y.selectedTags': string;
+  'a11y.removeTag': string;
+  'ui.loading': string;
+  'error.duplicate': string;
+  'error.maxReached': string;
+  'error.notInList': string;
+  'error.loadError': string;
+}
+
+/** Dot-key identifying a single {@link I18nStrings} slot. */
+export type I18nKey = keyof I18nStrings;
+
+/**
+ * Internationalisation option. Init-only — not accepted by `settings()`.
+ * Runtime locale change requires `destroy()` + `new Taga11y()`.
+ */
+export interface I18nOptions {
+  /** BCP 47 locale tag, e.g. `"pt"`, `"ar"`, `"pt-BR"`. */
+  locale: string;
+  /**
+   * Explicit text direction stamped on the wrapper. Omit to inherit
+   * direction from the parent cascade (the common case).
+   */
+  dir?: 'ltr' | 'rtl';
+  /**
+   * Partial override of the built-in English strings. Missing keys fall
+   * back to English; a supplied `a11y.resultsCount` wholly replaces the
+   * English default for that slot and must include `other`.
+   */
+  strings?: Partial<I18nStrings>;
+}
+
+export interface Taga11yOptions {
+  /**
+   * Suggestion source: static array, pre-fetched async, or dynamic callback.
+   * Omit for free-text mode with no suggestions.
+   */
+  suggestions?: SuggestionsSource;
+
+  /** Maximum number of tags the user can select. Undefined means no limit. */
+  maxTags?: number;
+
+  /**
+   * Maximum number of suggestions rendered in the dropdown at once.
+   * Defaults to 10. `0` shows no suggestions; to show all matches pass a
+   * large number (e.g. `9999999`). Negative values are clamped to 0.
+   * Live-updatable via `settings()`; a new value takes effect on the next
+   * filter and does not re-render an already-open dropdown.
+   */
+  maxSuggestions?: number;
+
+  /**
+   * Characters that trigger tag commit when typed. Defaults to `[, Enter]`.
+   * Accepts a single character/string or an array.
+   */
+  delimiter?: string | string[];
+
+  /**
+   * When true, only suggestions from the source can be committed.
+   * Free-text entry is rejected with an error.
+   */
+  enforceSuggestions?: boolean;
+
+  /**
+   * Name attribute for the hidden form input. Defaults to the original
+   * input's `name` attribute.
+   */
+  name?: string;
+
+  /** Optional visible label rendered above the component. */
+  label?: string;
+
+  /** When true, the component is rendered in a disabled state. */
+  disabled?: boolean;
+
+  /**
+   * Forced theme override. `null` (default) follows the OS preference.
+   * Use `"dark"` or `"light"` to override regardless of OS setting.
+   */
+  theme?: 'dark' | 'light' | null;
+
+  /**
+   * Custom serializer for the hidden input value. Receives the current
+   * tag array and returns a string. Defaults to comma-joining values.
+   */
+  serialize?: (tags: TagData[]) => string;
+
+  /**
+   * Custom deserializer for the original input's `value` on init and on
+   * form reset. Pairs with `serialize` to enable round-tripping a custom
+   * format. Returns the same `SuggestionItem` shape `suggestions` accepts:
+   * plain strings resolve labels from loaded suggestions (falling back to
+   * label === value); `{ label, value }` objects are used as-is. Defaults
+   * to splitting on `","`, trimming, and dropping empties.
+   */
+  deserialize?: (raw: string) => SuggestionItem[];
+
+  /**
+   * Debounce delay in milliseconds for dynamic suggestion requests.
+   * Default: 200. Only applies to dynamic (`{ query }`) mode.
+   */
+  debounceMs?: number;
+
+  /**
+   * Internationalisation: locale, optional direction, and partial string
+   * overrides. Init-only — ignored by `settings()`. Omit for built-in
+   * English with no `lang`/`dir` on the wrapper.
+   */
+  i18n?: I18nOptions;
+}
+
+/** Detail payload for the `taga11y:add` event. */
+export interface Taga11yAddDetail {
+  tag: TagData;
+}
+
+/** Detail payload for the `taga11y:remove` event. */
+export interface Taga11yRemoveDetail {
+  tag: TagData;
+}
+
+/** Detail payload for the `taga11y:clear` event — the tags that were cleared. */
+export interface Taga11yClearDetail {
+  tags: TagData[];
+}
+
+/** Detail payload for the `taga11y:change` event — the current tag set. */
+export interface Taga11yChangeDetail {
+  tags: TagData[];
+}
+
+/**
+ * Detail payload for the `taga11y:paste` event. `added` lists committed tags
+ * in commit order; `skipped` lists trimmed chunk strings that were rejected.
+ */
+export interface Taga11yPasteDetail {
+  added: TagData[];
+  skipped: string[];
+}
+
+/** Detail payload for the `taga11y:destroy` event (no fields). */
+export type Taga11yDestroyDetail = Record<string, never>;
+
+/** Maps each taga11y custom event name to its `CustomEvent` detail type. */
+export interface Taga11yEventMap {
+  'taga11y:add': Taga11yAddDetail;
+  'taga11y:remove': Taga11yRemoveDetail;
+  'taga11y:clear': Taga11yClearDetail;
+  'taga11y:change': Taga11yChangeDetail;
+  'taga11y:paste': Taga11yPasteDetail;
+  'taga11y:destroy': Taga11yDestroyDetail;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,27 @@
+export type DebouncedFn<T extends unknown[]> = ((...args: T) => void) & {
+  cancel: () => void;
+};
+
+export function debounce<T extends unknown[]>(
+  fn: (...args: T) => void,
+  ms: number,
+): DebouncedFn<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const debounced = (...args: T): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      fn(...args);
+    }, ms);
+  };
+
+  debounced.cancel = (): void => {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+
+  return debounced;
+}

package/src/utils/filter.ts

@@ -0,0 +1,14 @@
+import type { SuggestionItem } from '../types.js';
+
+export function getLabel(item: SuggestionItem): string {
+  return typeof item === 'string' ? item : item.label;
+}
+
+export function getValue(item: SuggestionItem): string {
+  return typeof item === 'string' ? item : item.value;
+}
+
+export function filter(items: SuggestionItem[], query: string): SuggestionItem[] {
+  const lower = query.toLowerCase();
+  return items.filter((item) => getLabel(item).toLowerCase().includes(lower));
+}

package/src/utils/id.ts

@@ -0,0 +1,30 @@
+function randomSuffix(): string {
+  const buf = new Uint8Array(4);
+  crypto.getRandomValues(buf);
+  return Array.from(buf, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export function deriveBaseId(input: HTMLInputElement): string {
+  const existingId = input.id.trim();
+  return existingId ? `taga11y-${existingId}` : `taga11y-${randomSuffix()}`;
+}
+
+export interface DerivedIds {
+  base: string;
+  label: string;
+  listbox: string;
+  option: (n: number) => string;
+  error: string;
+  announcer: string;
+}
+
+export function buildIds(base: string): DerivedIds {
+  return {
+    base,
+    label: `${base}-label`,
+    listbox: `${base}-listbox`,
+    option: (n: number) => `${base}-option-${n}`,
+    error: `${base}-error`,
+    announcer: `${base}-announcer`,
+  };
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/vue/index.ts

@@ -0,0 +1,145 @@
+import {
+  defineComponent,
+  h,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  watch,
+  type PropType,
+} from 'vue';
+import {
+  Taga11y,
+  type Taga11yOptions,
+  type SuggestionsSource,
+  type SuggestionItem,
+  type TagData,
+} from 'taga11y';
+
+const OPTION_KEYS = [
+  'suggestions',
+  'maxTags',
+  'delimiter',
+  'enforceSuggestions',
+  'name',
+  'label',
+  'disabled',
+  'theme',
+  'serialize',
+  'deserialize',
+  'debounceMs',
+  'i18n',
+] as const satisfies readonly (keyof Taga11yOptions)[];
+
+function valuesEqual(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+
+/**
+ * Accessibility-first tagging input for Vue 3.
+ *
+ * A render-function component (no SFC) wrapping the vanilla {@link Taga11y}
+ * class. Supports `v-model` (controlled) and `defaultValue` (uncontrolled);
+ * emits every core event; exposes the instance via `expose()`. Mounts
+ * client-only so the document-touching constructor is SSR-safe.
+ */
+export const Taga11yInput = defineComponent({
+  name: 'Taga11yInput',
+  props: {
+    /** Controlled tag values (v-model). When provided, the parent owns state. */
+    modelValue: { type: Array as PropType<string[]>, default: undefined },
+    /** Uncontrolled initial tag values. */
+    defaultValue: { type: Array as PropType<string[]>, default: undefined },
+    suggestions: { type: [Array, Object] as PropType<SuggestionsSource>, default: undefined },
+    maxTags: { type: Number, default: undefined },
+    delimiter: { type: [String, Array] as PropType<string | string[]>, default: undefined },
+    enforceSuggestions: { type: Boolean, default: undefined },
+    name: { type: String, default: undefined },
+    label: { type: String, default: undefined },
+    disabled: { type: Boolean, default: undefined },
+    theme: { type: String as PropType<'dark' | 'light' | null>, default: undefined },
+    serialize: { type: Function as PropType<(tags: TagData[]) => string>, default: undefined },
+    deserialize: {
+      type: Function as PropType<(raw: string) => SuggestionItem[]>,
+      default: undefined,
+    },
+    debounceMs: { type: Number, default: undefined },
+    i18n: { type: Object as PropType<Taga11yOptions['i18n']>, default: undefined },
+  },
+  emits: ['update:modelValue', 'add', 'remove', 'clear', 'change', 'paste', 'destroy'],
+  setup(props, { emit, expose }) {
+    const elRef = ref<HTMLInputElement | null>(null);
+    const instance = shallowRef<Taga11y | null>(null);
+
+    function buildOptions(): Taga11yOptions {
+      const options: Taga11yOptions = {};
+      for (const key of OPTION_KEYS) {
+        const value = props[key];
+        if (value !== undefined) (options as Record<string, unknown>)[key] = value;
+      }
+      return options;
+    }
+
+    onMounted(() => {
+      const el = elRef.value;
+      if (!el) return;
+      const inst = new Taga11y(el, buildOptions());
+      instance.value = inst;
+
+      // Apply initial value before listeners attach → no spurious change emit.
+      const initial = props.modelValue ?? props.defaultValue;
+      if (initial && initial.length > 0) inst.setTags(initial);
+
+      inst.on('taga11y:change', (event) => {
+        emit('change', event.detail);
+        emit(
+          'update:modelValue',
+          event.detail.tags.map((t) => t.value),
+        );
+      });
+      inst.on('taga11y:add', (event) => emit('add', event.detail));
+      inst.on('taga11y:remove', (event) => emit('remove', event.detail));
+      inst.on('taga11y:clear', (event) => emit('clear', event.detail));
+      inst.on('taga11y:paste', (event) => emit('paste', event.detail));
+      inst.on('taga11y:destroy', (event) => emit('destroy', event.detail));
+    });
+
+    onBeforeUnmount(() => {
+      instance.value?.destroy(); // fires taga11y:destroy → emits 'destroy'
+      instance.value = null;
+    });
+
+    // Controlled value reconciliation, guarded against feedback loops.
+    watch(
+      () => props.modelValue,
+      (val) => {
+        const inst = instance.value;
+        if (val === undefined || !inst) return;
+        const current = inst.getTags().map((t) => t.value);
+        if (!valuesEqual(current, val)) inst.setTags(val);
+      },
+    );
+
+    // Forward changed option props via settings() without reconstructing.
+    const prev: Partial<Record<keyof Taga11yOptions, unknown>> = {};
+    for (const key of OPTION_KEYS) prev[key] = props[key];
+    watch(
+      () => OPTION_KEYS.map((key) => props[key]),
+      () => {
+        const inst = instance.value;
+        if (!inst) return;
+        const changed: Partial<Taga11yOptions> = {};
+        for (const key of OPTION_KEYS) {
+          if (key === 'i18n') continue; // init-only; settings() warns + ignores
+          if (props[key] !== prev[key]) (changed as Record<string, unknown>)[key] = props[key];
+          prev[key] = props[key];
+        }
+        if (Object.keys(changed).length > 0) inst.settings(changed);
+      },
+    );
+
+    expose({ instance });
+
+    return () => h('input', { ref: elRef });
+  },
+});