taga11y 1.0.0

package/src/react/index.tsx

@@ -0,0 +1,223 @@
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import type { ComponentPropsWithoutRef, ReactElement, Ref, RefObject } from 'react';
+import {
+  Taga11y,
+  type Taga11yOptions,
+  type Taga11yAddDetail,
+  type Taga11yRemoveDetail,
+  type Taga11yClearDetail,
+  type Taga11yChangeDetail,
+  type Taga11yPasteDetail,
+  type Taga11yDestroyDetail,
+} from 'taga11y';
+
+/** `useLayoutEffect` on the client, `useEffect` on the server — dodges React's SSR warning. */
+const useIsomorphicLayoutEffect =
+  typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+const OPTION_KEYS = [
+  'suggestions',
+  'maxTags',
+  'delimiter',
+  'enforceSuggestions',
+  'name',
+  'label',
+  'disabled',
+  'theme',
+  'serialize',
+  'deserialize',
+  'debounceMs',
+  'i18n',
+] as const satisfies readonly (keyof Taga11yOptions)[];
+
+interface Taga11yHandlers {
+  /** Fired when a tag is successfully added. */
+  onAdd?: (event: CustomEvent<Taga11yAddDetail>) => void;
+  /** Fired when a tag is removed. */
+  onRemove?: (event: CustomEvent<Taga11yRemoveDetail>) => void;
+  /** Fired when all tags are cleared. */
+  onClear?: (event: CustomEvent<Taga11yClearDetail>) => void;
+  /** Fired after every mutation, with the current values and raw event. */
+  onChange?: (values: string[], event: CustomEvent<Taga11yChangeDetail>) => void;
+  /** Fired after a bulk-import paste gesture. */
+  onPaste?: (event: CustomEvent<Taga11yPasteDetail>) => void;
+  /**
+   * Fired when the widget is destroyed (on unmount). The component's own
+   * unmount lifecycle is the idiomatic place for teardown; this exists for
+   * 1:1 parity with the core event surface.
+   */
+  onDestroy?: (event: CustomEvent) => void;
+}
+
+type InputPassthrough = Omit<
+  ComponentPropsWithoutRef<'input'>,
+  keyof Taga11yOptions | keyof Taga11yHandlers | 'value' | 'defaultValue'
+>;
+
+export interface Taga11yInputProps extends Taga11yOptions, Taga11yHandlers, InputPassthrough {
+  /** Controlled tag values. When provided, the consumer owns tag state. */
+  value?: string[];
+  /** Uncontrolled initial tag values. */
+  defaultValue?: string[];
+  /** Receives the live {@link Taga11y} instance after mount (escape hatch). */
+  instanceRef?: RefObject<Taga11y | null>;
+  /**
+   * Standard React ref, resolving to the underlying `<input>` element (not the
+   * `Taga11y` instance — use {@link instanceRef} for that). Enables form
+   * libraries (e.g. react-hook-form's `{...field}`) to focus the field.
+   */
+  ref?: Ref<HTMLInputElement>;
+}
+
+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 React 19.
+ *
+ * Wraps the vanilla {@link Taga11y} class. Supports controlled (`value` +
+ * `onChange`) and uncontrolled (`defaultValue`) usage; forwards every core
+ * event as a callback; exposes the instance via `instanceRef`. Client-only
+ * mount keeps it SSR-safe.
+ */
+export function Taga11yInput(props: Taga11yInputProps): ReactElement {
+  const {
+    value,
+    defaultValue,
+    instanceRef,
+    ref,
+    onAdd,
+    onRemove,
+    onClear,
+    onChange,
+    onPaste,
+    onDestroy,
+    ...rest
+  } = props;
+
+  const elRef = useRef<HTMLInputElement>(null);
+  const instRef = useRef<Taga11y | null>(null);
+
+  // Merge the internal element ref with the consumer's `ref`: keeps `elRef`
+  // valid for mount (so an incoming `ref` never clobbers it) while forwarding
+  // the node to the consumer. Stable across renders unless `ref` changes.
+  const setElement = useCallback(
+    (node: HTMLInputElement | null): void => {
+      elRef.current = node;
+      if (typeof ref === 'function') ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref],
+  );
+
+  // Split remaining props into Taga11y options vs. native <input> attributes.
+  const options: Taga11yOptions = {};
+  const domProps: Record<string, unknown> = {};
+  const optionKeys = new Set<string>(OPTION_KEYS);
+  for (const key of Object.keys(rest)) {
+    const source = rest as Record<string, unknown>;
+    if (optionKeys.has(key)) (options as Record<string, unknown>)[key] = source[key];
+    else domProps[key] = source[key];
+  }
+
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const onDestroyRef = useRef(onDestroy);
+  onDestroyRef.current = onDestroy;
+
+  // Mount once. Layout timing (not useEffect) so the teardown — which restores
+  // the input Taga11y moved into its wrapper — runs in the commit phase before
+  // React removes host nodes; otherwise React's removeChild can't find the input.
+  // Via the isomorphic shim so it's a no-op useEffect on the server (SSR-safe).
+  useIsomorphicLayoutEffect(() => {
+    const el = elRef.current;
+    if (!el) return;
+    const inst = new Taga11y(el, optionsRef.current);
+    instRef.current = inst;
+    if (instanceRef) instanceRef.current = inst;
+
+    // Apply initial value before listeners attach → no spurious onChange on mount.
+    const initial = value ?? defaultValue;
+    if (initial && initial.length > 0) inst.setTags(initial);
+
+    const destroyHandler = (event: CustomEvent<Taga11yDestroyDetail>): void => {
+      onDestroyRef.current?.(event);
+    };
+    inst.on('taga11y:destroy', destroyHandler);
+
+    return () => {
+      inst.destroy(); // fires taga11y:destroy while destroyHandler is still attached
+      inst.off('taga11y:destroy', destroyHandler);
+      instRef.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // Mount-once: later prop changes are handled by the effects below.
+  }, []);
+
+  // Forward changed option props via settings() without reconstructing.
+  const prevOptions = useRef<Taga11yOptions>(options);
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst) return;
+    const changed: Partial<Taga11yOptions> = {};
+    for (const key of OPTION_KEYS) {
+      if (key === 'i18n') continue; // init-only; settings() warns + ignores
+      if (optionsRef.current[key] !== prevOptions.current[key]) {
+        (changed as Record<string, unknown>)[key] = optionsRef.current[key];
+      }
+    }
+    if (Object.keys(changed).length > 0) inst.settings(changed);
+    prevOptions.current = optionsRef.current;
+  });
+
+  // Controlled value reconciliation, guarded against feedback loops.
+  useEffect(() => {
+    if (value === undefined) return; // uncontrolled
+    const inst = instRef.current;
+    if (!inst) return;
+    const current = inst.getTags().map((t) => t.value);
+    if (!valuesEqual(current, value)) inst.setTags(value);
+  }, [value]);
+
+  // Per-callback event forwarding — rebinds on identity change, no remount.
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst || !onChange) return;
+    const h = (event: CustomEvent<Taga11yChangeDetail>): void => {
+      onChange(event.detail.tags.map((t) => t.value), event);
+    };
+    inst.on('taga11y:change', h);
+    return () => inst.off('taga11y:change', h);
+  }, [onChange]);
+
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst || !onAdd) return;
+    inst.on('taga11y:add', onAdd);
+    return () => inst.off('taga11y:add', onAdd);
+  }, [onAdd]);
+
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst || !onRemove) return;
+    inst.on('taga11y:remove', onRemove);
+    return () => inst.off('taga11y:remove', onRemove);
+  }, [onRemove]);
+
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst || !onClear) return;
+    inst.on('taga11y:clear', onClear);
+    return () => inst.off('taga11y:clear', onClear);
+  }, [onClear]);
+
+  useEffect(() => {
+    const inst = instRef.current;
+    if (!inst || !onPaste) return;
+    inst.on('taga11y:paste', onPaste);
+    return () => inst.off('taga11y:paste', onPaste);
+  }, [onPaste]);
+
+  return <input ref={setElement} {...(domProps as InputPassthrough)} />;
+}

package/src/styles/index.css

@@ -0,0 +1,367 @@
+/* ============================================================
+   taga11y — BEM component styles
+   ============================================================ */
+
+/* ── Scoped box-sizing reset (component subtree only) ─────── */
+.taga11y,
+.taga11y *,
+.taga11y *::before,
+.taga11y *::after {
+  box-sizing: border-box;
+}
+
+/* ── 9.2 / 9.3  Light-mode custom properties (defaults) ───── */
+.taga11y {
+  /* Base (independent) tokens */
+  --taga11y-color-bg: #ffffff;
+  --taga11y-color-text: #000000;
+  --taga11y-color-border: #767676;
+  --taga11y-color-border-focus: #0060df;
+  --taga11y-color-tag-bg: #efefef;
+  --taga11y-color-error-border: #c62828;
+
+  /* Derived tokens — track their base via var(); literal is a resilience
+     fallback only (base tokens are always defined). Declared once here;
+     resolves against the cascaded base value in every theme.
+     End user can override these as he pleases */
+  --taga11y-color-tag-text: var(--taga11y-color-text, #000000);
+  --taga11y-color-tag-border: var(--taga11y-color-tag-text, #000000);
+  --taga11y-color-tag-remove-hover: var(--taga11y-color-border-focus, #0060df);
+  --taga11y-color-suggestion-bg: var(--taga11y-color-bg, #ffffff);
+  --taga11y-color-suggestion-active-bg: var(--taga11y-color-border-focus, #0060df);
+  --taga11y-color-suggestion-active-text: var(--taga11y-color-bg, #ffffff);
+  --taga11y-color-suggestion-border: var(--taga11y-color-border-focus, #0060df);
+  --taga11y-color-error-bg: var(--taga11y-color-bg, #ffffff);
+  --taga11y-color-error-text: var(--taga11y-color-text, #000000);
+  --taga11y-color-spinner: var(--taga11y-color-border-focus, #0060df);
+
+  /* Shape / typography tokens */
+  --taga11y-radius: 2px;
+  --taga11y-border-width: 1px;
+  --taga11y-outline-width: 2px;
+  --taga11y-shadow: none;
+  --taga11y-font-family: inherit;
+  --taga11y-font-size: 1em;
+  --taga11y-spacing: 1px 2px;
+  --taga11y-tag-padding-block: 1px;
+  --taga11y-tag-padding-inline: 4px;
+  --taga11y-tag-label-gap: 2px;
+
+  position: relative;
+  display: block;
+  font-family: var(--taga11y-font-family);
+  font-size: var(--taga11y-font-size);
+}
+
+/* ── 9.4  Dark mode — OS preference ─────────────────────────── */
+@media (prefers-color-scheme: dark) {
+  .taga11y {
+    /* Only the 6 independent tokens; derived tokens resolve through their
+       single .taga11y declaration against these cascaded base values. */
+    --taga11y-color-bg: #000000;
+    --taga11y-color-text: #ffffff;
+    --taga11y-color-border: #898989;
+    --taga11y-color-border-focus: #5fb3f5;
+    --taga11y-color-tag-bg: #101010;
+    --taga11y-color-error-border: #ef9a9a;
+  }
+}
+
+/* ── 9.4  data-theme="dark" — forced dark regardless of OS ─── */
+.taga11y[data-theme="dark"] {
+  /* Only the 6 independent tokens; derived tokens resolve through their
+     single .taga11y declaration against these cascaded base values. */
+  --taga11y-color-bg: #000000;
+  --taga11y-color-text: #ffffff;
+  --taga11y-color-border: #898989;
+  --taga11y-color-border-focus: #5fb3f5;
+  --taga11y-color-tag-bg: #101010;
+  --taga11y-color-error-border: #ef9a9a;
+}
+
+/* ── 9.4  data-theme="light" — forced light regardless of OS ── */
+.taga11y[data-theme="light"] {
+  /* Only the 6 independent tokens; derived tokens resolve through their
+     single .taga11y declaration against these cascaded base values. */
+  --taga11y-color-bg: #ffffff;
+  --taga11y-color-text: #000000;
+  --taga11y-color-border: #767676;
+  --taga11y-color-border-focus: #0060df;
+  --taga11y-color-tag-bg: #efefef;
+  --taga11y-color-error-border: #c62828;
+}
+
+/* ── 9.1  Label ─────────────────────────────────────────────── */
+.taga11y__label {
+  display: block;
+  margin-bottom: 4px;
+  color: var(--taga11y-color-text);
+  font-size: var(--taga11y-font-size);
+  font-family: var(--taga11y-font-family);
+}
+
+/* ── 9.1 / 9.13  Chip + input flex row ─────────────────────── */
+.taga11y__tags {
+  /* Anchor for the listbox's viewport-flip enhancement (see @supports below). */
+  anchor-name: --taga11y-anchor;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px;
+  padding: var(--taga11y-spacing);
+  background: var(--taga11y-color-bg);
+  border: var(--taga11y-border-width) solid var(--taga11y-color-border);
+  border-radius: var(--taga11y-radius);
+  box-shadow: var(--taga11y-shadow);
+  cursor: text;
+}
+
+.taga11y__tags:focus-within {
+  outline: var(--taga11y-outline-width) solid var(--taga11y-color-border-focus);
+  outline-offset: calc(-1 * var(--taga11y-border-width));
+}
+
+/* RTL: input moves to the right (reading start), chips grow leftward. */
+.taga11y__tags:dir(rtl) { flex-direction: row-reverse; }
+
+.taga11y__tag-list { display: contents; list-style: none; padding: 0; margin: 0; }
+
+/* ── 9.1  Combobox input ────────────────────────────────────── */
+.taga11y__input {
+  flex: 1 1 4ch;
+  min-width: 4ch;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--taga11y-color-text);
+  font-family: var(--taga11y-font-family);
+  font-size: var(--taga11y-font-size);
+  padding-block: var(--taga11y-tag-padding-block);
+  padding-inline: 0;
+}
+
+/* ── 9.13  Listbox positioning ──────────────────────────────── */
+.taga11y__listbox {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  width: 100%;
+  z-index: 100;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  background: var(--taga11y-color-suggestion-bg);
+  border-width: var(--taga11y-outline-width);
+  border-style: solid;
+  border-color: var(--taga11y-color-suggestion-border);
+  border-radius: var(--taga11y-radius);
+  box-shadow: 0 4px 8px rgb(0 0 0 / 0.12);
+  max-height: 240px;
+  overflow-y: auto;
+}
+
+/* ── 9.13  Listbox viewport-flip (progressive enhancement) ──── */
+/* Flip the listbox above the input when it would be clipped below the viewport;
+   unsupported browsers keep the position:absolute rules above. fixed (not
+   absolute) so overflow is measured against the viewport, not the relative
+   wrapper. Gate needs anchor-scope too, which isolates instances. */
+@supports (anchor-name: --a) and (anchor-scope: --a) {
+  .taga11y {
+    anchor-scope: --taga11y-anchor;
+  }
+
+  .taga11y__listbox {
+    position: fixed;
+    position-anchor: --taga11y-anchor;
+    top: anchor(bottom);
+    left: anchor(left);
+    width: anchor-size(width);
+    position-try-fallbacks: flip-block;
+  }
+}
+
+/* ── 9.5 / 9.7  Listbox option ─────────────────────────────── */
+.taga11y__option {
+  padding: var(--taga11y-spacing);
+  color: var(--taga11y-color-text);
+  cursor: pointer;
+  user-select: none;
+}
+
+/* Hover highlight only on hover-capable devices — touch browsers emulate
+   :hover on the last-tapped element until something else is hovered,
+   which would render alongside the aria-activedescendant highlight. */
+@media (hover: hover) {
+  .taga11y__option:hover {
+    background: var(--taga11y-color-suggestion-active-bg);
+    color: var(--taga11y-color-suggestion-active-text);
+  }
+}
+
+/* Press feedback: fires while a finger/mouse is held, clears on lift. */
+.taga11y__option:active {
+  background: var(--taga11y-color-suggestion-active-bg);
+  color: var(--taga11y-color-suggestion-active-text);
+}
+
+/* ── 9.7  Suggestion active state (keyboard highlight) ──────── */
+.taga11y__option[aria-selected="true"] {
+  background: var(--taga11y-color-suggestion-active-bg);
+  color: var(--taga11y-color-suggestion-active-text);
+}
+
+/* ── 9.8  Chip (normal) ─────────────────────────────────────── */
+.taga11y__tag {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--taga11y-tag-label-gap);
+  padding: var(--taga11y-tag-padding-block) var(--taga11y-tag-padding-inline);
+  background: var(--taga11y-color-tag-bg);
+  color: var(--taga11y-color-tag-text);
+  border-radius: var(--taga11y-radius);
+  box-shadow: inset 0 0 0 1px var(--taga11y-color-tag-border);
+  font-size: var(--taga11y-font-size);
+  max-width: 100%;
+}
+
+/* RTL: the remove (x) button renders before the label within each chip. */
+.taga11y__tag:dir(rtl) { flex-direction: row-reverse; }
+
+.taga11y__tag-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ── 9.8  Chip remove button ────────────────────────────────── */
+.taga11y__tag-remove {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: none;
+  padding: 0 2px;
+  cursor: pointer;
+  color: inherit;
+  font-size: var(--taga11y-font-size);
+  border-radius: var(--taga11y-radius);
+  line-height: 1;
+}
+
+.taga11y__tag-remove::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  min-width: 24px;
+  min-height: 24px;
+}
+
+.taga11y__tag-remove:hover {
+  color: var(--taga11y-color-tag-remove-hover);
+}
+
+/* ── 9.6  Focus ring on remove button ───────────────────────── */
+.taga11y__tag-remove:focus {
+  outline: 2px solid var(--taga11y-color-border-focus);
+  outline-offset: 1px;
+}
+
+/* ── 9.8  Error chip ────────────────────────────────────────── */
+.taga11y__tag--error {
+  background: var(--taga11y-color-error-bg);
+  color: var(--taga11y-color-error-text);
+  box-shadow: inset 0 0 0 1px var(--taga11y-color-error-border);
+}
+
+/* ── 9.11  Loading indicator ────────────────────────────────── */
+.taga11y__loading {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: var(--taga11y-spacing);
+  color: var(--taga11y-color-text);
+}
+
+.taga11y__loading[hidden] {
+  display: none;
+}
+
+.taga11y__loading-spinner {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  border: 2px solid transparent;
+  border-top-color: var(--taga11y-color-spinner);
+  border-radius: 50%;
+  animation: taga11y-spin 0.7s linear infinite;
+  flex-shrink: 0;
+}
+
+@keyframes taga11y-spin {
+  to { transform: rotate(360deg); }
+}
+
+.taga11y__loading-text {
+  font-size: var(--taga11y-font-size);
+}
+
+/* ── 9.10  Error region ─────────────────────────────────────── */
+.taga11y__error {
+  margin-top: 2px;
+  padding: 2px 4px;
+  color: var(--taga11y-color-error-text);
+  border: var(--taga11y-border-width) solid var(--taga11y-color-error-border);
+  border-radius: var(--taga11y-radius);
+  background: var(--taga11y-color-error-bg);
+  font-size: 0.875em;
+}
+
+/* ── 9.12  Visually-hidden announcer (stays in a11y tree) ───── */
+.taga11y__announcer {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ── 9.1  Hidden form input ─────────────────────────────────── */
+.taga11y__hidden {
+  display: none;
+}
+
+/* ── 9.9  Disabled state ────────────────────────────────────── */
+.taga11y--disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.taga11y--disabled .taga11y__tags,
+.taga11y--disabled .taga11y__input {
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+/* ── 9.14  Reduced motion ───────────────────────────────────── */
+@media (prefers-reduced-motion: reduce) {
+  .taga11y__loading-spinner {
+    animation: none;
+    border-top-color: transparent;
+    border-color: var(--taga11y-color-spinner);
+  }
+
+  .taga11y__tag,
+  .taga11y__error,
+  .taga11y__listbox,
+  .taga11y__option {
+    transition: none;
+    animation: none;
+  }
+}