@adia-ai/web-components 0.6.34 → 0.6.35

package/components/tags-input/tags-input.css

@@ -0,0 +1,201 @@
+@scope (tags-input-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --tags-input-min-h-default:           var(--a-size);
+    --tags-input-px-default:              var(--a-ui-px);
+    --tags-input-py-default:              calc(var(--a-space-1) / 2);
+    --tags-input-gap-default:             var(--a-space-1);
+    --tags-input-radius-default:          var(--a-radius);
+
+    /* ── Typography ── */
+    --tags-input-font-size-default:       var(--a-ui-size);
+
+    /* ── Colors — host ── */
+    --tags-input-bg-default:              var(--a-ui-bg);
+    --tags-input-bg-hover-default:        var(--a-ui-bg-hover);
+    --tags-input-fg-default:              var(--a-ui-text);
+    --tags-input-placeholder-fg-default:  var(--a-ui-text-placeholder);
+    --tags-input-border-default:          var(--a-ui-border);
+    --tags-input-border-hover-default:    var(--a-ui-border-hover);
+    --tags-input-focus-ring-default:      var(--a-focus-ring);
+    --tags-input-focus-ring-invalid-default: var(--a-focus-ring-invalid);
+
+    /* ── Transition ── */
+    --tags-input-duration-default:        var(--a-duration-fast);
+    --tags-input-easing-default:          var(--a-easing);
+
+    /* ── Chip overrides — cascaded into nested <tag-ui> ── */
+    --tags-input-chip-bg-invalid-default: var(--a-danger-muted);
+
+    /* ── Suggestions popover ── */
+    --tags-input-suggestions-bg-default:        var(--a-canvas-bright);
+    --tags-input-suggestions-border-default:    var(--a-ui-border);
+    --tags-input-suggestions-radius-default:    var(--a-radius);
+    --tags-input-suggestions-shadow-default:    var(--a-shadow-lg);
+    --tags-input-suggestion-bg-focus-default:   var(--a-ui-bg-hover);
+    --tags-input-suggestion-fg-focus-default:   var(--a-ui-text-hover);
+
+    text-align: start;  /* §text-align-reset — block ancestor centering */
+  }
+
+  :scope {
+    /* ── Base ── */
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--tags-input-gap, var(--tags-input-gap-default));
+    min-height: var(--tags-input-min-h, var(--tags-input-min-h-default));
+    padding: var(--tags-input-py, var(--tags-input-py-default))
+             var(--tags-input-px, var(--tags-input-px-default));
+    border: 1px solid var(--tags-input-border, var(--tags-input-border-default));
+    border-radius: var(--tags-input-radius, var(--tags-input-radius-default));
+    background: var(--tags-input-bg, var(--tags-input-bg-default));
+    color: var(--tags-input-fg, var(--tags-input-fg-default));
+    font-size: var(--tags-input-font-size, var(--tags-input-font-size-default));
+    cursor: text;
+    transition:
+      background  var(--tags-input-duration, var(--tags-input-duration-default)) var(--tags-input-easing, var(--tags-input-easing-default)),
+      border-color var(--tags-input-duration, var(--tags-input-duration-default)) var(--tags-input-easing, var(--tags-input-easing-default)),
+      box-shadow  var(--tags-input-duration, var(--tags-input-duration-default)) var(--tags-input-easing, var(--tags-input-easing-default));
+  }
+
+  :scope:not([disabled]):hover {
+    background: var(--tags-input-bg-hover, var(--tags-input-bg-hover-default));
+    border-color: var(--tags-input-border-hover, var(--tags-input-border-hover-default));
+  }
+
+  :scope:focus-within {
+    box-shadow: var(--tags-input-focus-ring, var(--tags-input-focus-ring-default));
+    border-color: transparent;
+  }
+
+  :scope[aria-invalid="true"]:focus-within,
+  :scope[error]:focus-within {
+    box-shadow: var(--tags-input-focus-ring-invalid, var(--tags-input-focus-ring-invalid-default));
+  }
+
+  :scope[disabled] {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+
+  /* ── Chip list ── */
+  [data-chip-list] {
+    display: contents;  /* chips become direct flex children of the host */
+  }
+
+  /* Chip styling — cascade host-scoped overrides into <tag-ui> internals. */
+  :scope tag-ui {
+    /* keep the chip subtle by default; consumer tokens can override. */
+  }
+
+  :scope tag-ui[data-invalid] {
+    --tag-bg-default: var(--tags-input-chip-bg-invalid, var(--tags-input-chip-bg-invalid-default));
+  }
+
+  /* ── Inline input ── */
+  [data-inline-input] {
+    flex: 1 1 8em;
+    min-width: 8em;
+    align-self: stretch;
+    display: inline-flex;
+    align-items: center;
+    outline: none;
+    background: transparent;
+    color: var(--tags-input-fg, var(--tags-input-fg-default));
+    font: inherit;
+    font-size: var(--tags-input-font-size, var(--tags-input-font-size-default));
+    line-height: 1.4;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    cursor: text;
+  }
+  /* Empty-state placeholder via ::before pseudo so the contenteditable
+     surface participates in inline layout (the same pattern the input-ui
+     + combobox-ui editable surfaces use). */
+  [data-inline-input][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--tags-input-placeholder-fg, var(--tags-input-placeholder-fg-default));
+    pointer-events: none;
+  }
+
+  /* ── Spinner (async validator) ── */
+  [data-spinner] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    --a-icon-size: 1em;
+    animation: tags-input-spin 800ms linear infinite;
+  }
+  [data-spinner][hidden] { display: none; }
+
+  /* ── Sizing — leverages universal [size] attribute ── */
+  :scope[size="sm"] {
+    --tags-input-font-size-default: var(--a-ui-sm);
+    --tags-input-min-h-default:     var(--a-size-sm);
+    --tags-input-gap-default:       calc(var(--a-space-1) / 1.25);
+  }
+  :scope[size="lg"] {
+    --tags-input-font-size-default: var(--a-ui-lg);
+    --tags-input-min-h-default:     var(--a-size-lg);
+    --tags-input-gap-default:       var(--a-space-2);
+  }
+}
+
+/* ── Suggestions popover ── */
+/* Host-scoped (not inside @scope) so the popover can render outside the
+   normal flow if a future revision opts into top-layer. Currently inlined. */
+
+tags-input-ui [data-suggestions] {
+  position: absolute;
+  left: 0;
+  top: calc(100% + var(--a-space-1));
+  width: 100%;
+  min-width: 12em;
+  max-height: 18rem;
+  margin: 0;
+  padding: var(--a-space-1);
+  border: 1px solid var(--a-ui-border);
+  border-radius: var(--a-radius);
+  background: var(--a-canvas-bright);
+  box-shadow: var(--a-shadow-lg);
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-ui-text);
+  overflow-y: auto;
+  z-index: 10;
+}
+
+tags-input-ui {
+  position: relative;
+}
+
+tags-input-ui [data-suggestions][hidden] { display: none; }
+
+tags-input-ui [data-suggestions] [role="option"] {
+  display: flex;
+  align-items: center;
+  padding: var(--a-space-1) var(--a-ui-px);
+  border-radius: var(--a-radius-sm);
+  white-space: nowrap;
+  color: var(--a-ui-text-subtle);
+  cursor: pointer;
+  transition:
+    background var(--a-duration-fast) var(--a-easing),
+    color      var(--a-duration-fast) var(--a-easing);
+}
+
+tags-input-ui [data-suggestions] [role="option"][data-active],
+tags-input-ui [data-suggestions] [role="option"]:hover {
+  background: var(--a-ui-bg-hover);
+  color: var(--a-ui-text-hover);
+}
+
+@keyframes tags-input-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  tags-input-ui [data-spinner] { animation: none; }
+}

package/components/tags-input/tags-input.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `<tags-input-ui>` — Free-form token input — type a value, press Enter (or the configured
+delimiter) to commit it as a chip; Backspace from the empty inline
+input removes the last chip. Distinct from <select-ui multiple>
+(SPEC-040), which is constrained to a fixed option list — tags-input
+is for OPEN sets (labels, email recipients, keyword inputs). Per
+ADR-0025 the inline editor is a contenteditable surface (NO native
+`<input>` wrap). Form-bearing via UIFormElement + ElementInternals:
+the form value is a JSON-serialized string array under `[name]`.
+Each rendered chip is a `<tag-ui removable>`; the `remove` event
+delegates back to the host. Optional autocompletion: when
+`.suggestions` is non-empty, a popover renders below the field and
+the host announces as a combobox per WAI-APG.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/tags-input
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export interface TagsInputChangeEventDetail {
+  /** Tokens added by this change (`[]` when only removals occurred). */
+  added: unknown[];
+  /** Tokens removed by this change (`[]` when only additions occurred). */
+  removed: unknown[];
+  /** Current token list (string array). */
+  value: unknown[];
+}
+
+export type TagsInputChangeEvent = CustomEvent<TagsInputChangeEventDetail>;
+export interface TagsInputCommitEventDetail {
+  /** True unless the consumer calls `preventDefault()`. */
+  accepted: boolean;
+  /** Candidate token text (post-transform). */
+  value: string;
+}
+
+export type TagsInputCommitEvent = CustomEvent<TagsInputCommitEventDetail>;
+export interface TagsInputInputEventDetail {
+  /** Current typed text in the inline input. */
+  query: string;
+}
+
+export type TagsInputInputEvent = CustomEvent<TagsInputInputEventDetail>;
+export interface TagsInputInvalidEventDetail {
+  /** One of `duplicate` / `too-short` / `too-long` / `validator` / `max`. */
+  reason: string;
+  /** Rejected token text. */
+  value: string;
+}
+
+export type TagsInputInvalidEvent = CustomEvent<TagsInputInvalidEventDetail>;
+
+export class UITagsInput extends UIElement {
+  /** Required for form validation. Empty array fails `:invalid`. */
+  required: boolean;
+  /** Inline character that commits the typed value as a chip. The
+sentinel `enter` disables in-line commit — only the Enter key
+(or programmatic `addToken`) commits. Default is `,`. */
+  delimiter: string;
+  /** Block all interaction; dim the field. */
+  disabled: boolean;
+  /** Maximum number of tokens. `0` (default) means unlimited. */
+  max: number;
+  /** Maximum per-token character count. `0` (default) means unlimited. */
+  maxLength: number;
+  /** Minimum required tokens for form validity. */
+  min: number;
+  /** Minimum per-token character count after `transform` is applied. */
+  minLength: number;
+  /** Form field name. Serializes the token list as JSON under this key. */
+  name: string;
+  /** Regex character-class fragment matched against pasted text to
+split it into multiple tokens. Default `,\n` splits on commas
+and newlines. Use `""` to disable paste-splitting entirely. */
+  pasteSplit: string;
+  /** Placeholder text for the inline input when no chips are committed. */
+  placeholder: string;
+  /** Block edits; allow inspection (chips render without remove buttons). */
+  readonly: boolean;
+  /** Sizing scale via universal `[size]` attribute system. Matches
+Input + Combobox sizing tokens so a TagsInput rendered alongside
+either feels coherent in a form row. */
+  size: 'sm' | 'md' | 'lg';
+  /** Optional autocomplete strings rendered in a popover below the
+field. Suggestions are hints, not gates — the typed value still
+wins on commit. JS property only (array reflection skipped). */
+  suggestions: string;
+  /** Normalize tokens on commit. `lowercase` lowercases, `trim` strips
+leading + trailing whitespace, `strip-spaces` removes all
+whitespace, `""` (default) preserves the typed value. */
+  transform: '' | 'lowercase' | 'trim' | 'strip-spaces';
+  /** Reject duplicate tokens silently (no `invalid` event for accidental dups). */
+  unique: boolean;
+  /** Per-token validator. Sync `(value, index) => boolean` rejects
+false synchronously; async `(value, index) => Promise<boolean>`
+flips the host into `[validating]` while pending. JS property
+only — not serializable in A2UI JSON; wire post-mount. */
+  validateFn: Record<string, unknown>;
+  /** Current token list (string array). Setting `.value = ['a','b']`
+replaces the rendered chips. Reflection skipped — array values
+do not round-trip through attribute strings. */
+  value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITagsInput, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: TagsInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'commit', listener: (ev: TagsInputCommitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: TagsInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: TagsInputInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/tags-input/tags-input.examples.md

@@ -0,0 +1,92 @@
+# tags-input — Examples
+
+## basic
+
+```html
+<field-ui label="Labels">
+  <tags-input-ui name="labels" placeholder="Add a label, press Enter"></tags-input-ui>
+</field-ui>
+```
+
+Type a value + press Enter (or comma) to commit a chip. Backspace from the
+empty inline input removes the last chip.
+
+## pre-populated
+
+```html
+<tags-input-ui name="tags" value='["bug","high-priority","needs-triage"]'></tags-input-ui>
+```
+
+The `value` attribute accepts JSON — `["a","b","c"]`. The form value
+under `name` serializes back to the same JSON string.
+
+## transform="lowercase"
+
+```html
+<tags-input-ui transform="lowercase"></tags-input-ui>
+```
+
+Tokens are lowercased on commit. Available values:
+`""` (preserve), `"lowercase"`, `"trim"`, `"strip-spaces"`.
+
+## max — count cap
+
+```html
+<tags-input-ui name="tags" max="3"></tags-input-ui>
+```
+
+Once 3 tokens have been added, further commits fire
+`invalid` with `detail.reason === "max"`.
+
+## delimiter="enter"
+
+```html
+<tags-input-ui delimiter="enter"></tags-input-ui>
+```
+
+Disables in-line character commits when the token grammar legitimately
+contains the default `,` (e.g. display names like "Doe, Jane"). Only
+Enter (or programmatic `addToken`) commits.
+
+## validateFn — email-format gate
+
+```html
+<tags-input-ui id="to" name="to" placeholder="Email…"></tags-input-ui>
+<script>
+  const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  document.getElementById('to').validateFn = (value) => EMAIL_RE.test(value);
+</script>
+```
+
+`validateFn` may return a `Promise<boolean>` — the host flips into
+`[validating]` until the promise settles.
+
+## paste-split — bulk entry
+
+```html
+<tags-input-ui name="domains" paste-split=",\n"></tags-input-ui>
+```
+
+Pasting `"example.com, foo.com\nbar.com"` commits three chips.
+
+## suggestions — autocomplete hints
+
+```html
+<tags-input-ui id="tags" name="tags"></tags-input-ui>
+<script>
+  document.getElementById('tags').suggestions = ['bug', 'feature', 'chore'];
+</script>
+```
+
+Suggestions are hints, not gates — the typed value still wins. When
+non-empty, the host announces as `role="combobox"` with the popover
+listed below the field.
+
+## readonly chip display
+
+```html
+<tags-input-ui readonly value='["bug","urgent"]'></tags-input-ui>
+```
+
+Readonly hides the remove affordance on each chip + blocks the inline
+input.

package/components/tags-input/tags-input.js

@@ -0,0 +1,17 @@
+/**
+ * `<tags-input-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UITagsInput } from '@adia-ai/web-components/components/tags-input/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UITagsInput } from './tags-input.class.js';
+
+defineIfFree('tags-input-ui', UITagsInput);
+
+export { UITagsInput };