@adia-ai/web-components 0.6.34 → 0.6.35

package/components/tags-input/tags-input.yaml

@@ -0,0 +1,367 @@
+# Hand-authored — SPEC-042 (2026-05-24).
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITagsInput
+tag: tags-input-ui
+status: experimental
+component: TagsInput
+category: input
+version: 1
+description: |
+  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.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - tag-ui                # rendered per committed token
+  - icon-ui               # spinner glyph for async validators
+props:
+  name:
+    description: Form field name. Serializes the token list as JSON under this key.
+    type: string
+    default: ""
+    reflect: true
+  value:
+    description: |-
+      Current token list (string array). Setting `.value = ['a','b']`
+      replaces the rendered chips. Reflection skipped — array values
+      do not round-trip through attribute strings.
+    type: array
+    default: []
+    dynamic: true
+  placeholder:
+    description: Placeholder text for the inline input when no chips are committed.
+    type: string
+    default: Add tag…
+    reflect: true
+  delimiter:
+    description: |-
+      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 `,`.
+    type: string
+    default: ","
+    reflect: true
+  pasteSplit:
+    description: |-
+      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.
+    type: string
+    default: ",\n"
+    attribute: paste-split
+    reflect: true
+  max:
+    description: Maximum number of tokens. `0` (default) means unlimited.
+    type: number
+    default: 0
+    reflect: true
+  min:
+    description: Minimum required tokens for form validity.
+    type: number
+    default: 0
+    reflect: true
+  minLength:
+    description: Minimum per-token character count after `transform` is applied.
+    type: number
+    default: 1
+    attribute: min-length
+    reflect: true
+  maxLength:
+    description: Maximum per-token character count. `0` (default) means unlimited.
+    type: number
+    default: 0
+    attribute: max-length
+    reflect: true
+  unique:
+    description: Reject duplicate tokens silently (no `invalid` event for accidental dups).
+    type: boolean
+    default: true
+    reflect: true
+  transform:
+    description: |-
+      Normalize tokens on commit. `lowercase` lowercases, `trim` strips
+      leading + trailing whitespace, `strip-spaces` removes all
+      whitespace, `""` (default) preserves the typed value.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - lowercase
+      - trim
+      - strip-spaces
+    reflect: true
+  suggestions:
+    description: |-
+      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).
+    type: array
+    default: []
+    dynamic: true
+  validateFn:
+    description: |-
+      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.
+    type: object
+    default: null
+    dynamic: true
+  disabled:
+    description: Block all interaction; dim the field.
+    type: boolean
+    default: false
+    reflect: true
+  readonly:
+    description: Block edits; allow inspection (chips render without remove buttons).
+    type: boolean
+    default: false
+    reflect: true
+  required:
+    description: Required for form validation. Empty array fails `:invalid`.
+    type: boolean
+    default: false
+    reflect: true
+  size:
+    description: |-
+      Sizing scale via universal `[size]` attribute system. Matches
+      Input + Combobox sizing tokens so a TagsInput rendered alongside
+      either feels coherent in a form row.
+    type: string
+    default: md
+    enum: [sm, md, lg]
+    reflect: true
+events:
+  change:
+    description: Fired after `value` changes (token added or removed).
+    detail:
+      value:
+        type: array
+        description: Current token list (string array).
+      added:
+        type: array
+        description: Tokens added by this change (`[]` when only removals occurred).
+      removed:
+        type: array
+        description: Tokens removed by this change (`[]` when only additions occurred).
+  input:
+    description: Fired on each keystroke in the inline input (pre-commit).
+    detail:
+      query:
+        type: string
+        description: Current typed text in the inline input.
+  commit:
+    description: |-
+      Fired immediately before a token is committed. Call
+      `event.preventDefault()` to reject the candidate token.
+    detail:
+      value:
+        type: string
+        description: Candidate token text (post-transform).
+      accepted:
+        type: boolean
+        description: True unless the consumer calls `preventDefault()`.
+  invalid:
+    description: |-
+      Fired when a candidate token is rejected. Reasons cover all
+      built-in validators and the user-supplied `validateFn`.
+    detail:
+      value:
+        type: string
+        description: Rejected token text.
+      reason:
+        type: string
+        description: One of `duplicate` / `too-short` / `too-long` / `validator` / `max`.
+slots:
+  chip:
+    description: |-
+      Custom chip template — receives `{value, index}` per token.
+      When absent, each token renders as a default
+      `<tag-ui removable text="<value>">`.
+states:
+  - name: idle
+    description: No tokens; no typed text.
+  - name: populated
+    description: One or more tokens committed.
+    attribute: populated
+  - name: editing
+    description: User is typing into the inline input.
+    attribute: editing
+  - name: suggesting
+    description: Suggestion popover is open.
+    attribute: suggesting
+  - name: validating
+    description: Async `validateFn` is in flight.
+    attribute: validating
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+  - name: readonly
+    description: Read-only; chips render without remove affordance.
+    attribute: readonly
+traits: []
+tokens:
+  --tags-input-bg:
+    description: Host background color.
+  --tags-input-fg:
+    description: Host foreground (typed-text color).
+  --tags-input-border:
+    description: Host border color (idle).
+  --tags-input-border-hover:
+    description: Host border color on hover.
+  --tags-input-radius:
+    description: Host border radius.
+  --tags-input-px:
+    description: Horizontal padding inside the chip-cluster wrapper.
+  --tags-input-py:
+    description: Vertical padding inside the chip-cluster wrapper.
+  --tags-input-gap:
+    description: Gap between chips and the inline input.
+  --tags-input-placeholder-fg:
+    description: Placeholder color for the empty inline input.
+  --tags-input-focus-ring:
+    description: Focus-ring box-shadow when the host is focus-within.
+  --tags-input-chip-bg-invalid:
+    description: Chip background color when a chip is marked invalid (validator rejection echo).
+requiredIcons:
+  - circle-notch
+a2ui:
+  rules:
+    - >-
+      Use <tags-input-ui> for OPEN-SET free-form token entry — labels,
+      keywords, email recipients, comma-separated lists. For CLOSED
+      option sets (pick N from a fixed list), use <select-ui multiple>
+      (SPEC-040) — that primitive gates the value against `options[]`.
+    - >-
+      `TagsInput.value` MUST be a string array. Pass `["a","b"]`, not
+      the comma-joined string `"a,b"`. The host parses string-form
+      `value` attributes as JSON; non-array shapes throw `invalid`.
+    - >-
+      `delimiter: "enter"` disables in-line character commits; only
+      the Enter key (or programmatic `addToken`) commits. Use this
+      when the token grammar legitimately includes the default `,`.
+    - >-
+      `unique: true` (default) silently coalesces accidental duplicate
+      adds. Do NOT emit `invalid` for those — the contract specifies
+      silent dedup for ergonomic typing.
+    - >-
+      `validateFn` is a JS property, NOT serializable in A2UI JSON.
+      Wire validators post-mount via DOM scripting; A2UI authors
+      should not expect to declare a validator in the JSON payload.
+    - >-
+      Chips are rendered automatically from `value`. Do NOT slot
+      individual <tag-ui> children manually — that decouples the
+      rendered DOM from the form value and breaks Backspace removal.
+anti_patterns:
+  - wrong: |
+      {"component": "TagsInput", "options": [{"id": "a", "label": "A"}]}
+    why: |
+      TagsInput does NOT accept `options`. It is the OPEN-set primitive — any
+      typed string is valid. For closed option lists, use the multi-select
+      primitive with `multiple: true`.
+    fix: |
+      {"component": "Select", "multiple": true, "options": [{"id": "a", "label": "A"}]}
+  - wrong: |
+      {"component": "TagsInput", "value": "bug,high-priority"}
+    why: |
+      Comma-separated string is invalid for `value`. The contract requires
+      a string array.
+    fix: |
+      {"component": "TagsInput", "value": ["bug", "high-priority"]}
+  - wrong: |
+      {"component": "TagsInput", "children": [
+        {"component": "Tag", "text": "Tag 1"}
+      ]}
+    why: |
+      Chips are rendered automatically from `value`. Slotting Tag children
+      decouples the rendered DOM from the form value and breaks Backspace
+      removal + the `change` event payload.
+    fix: |
+      {"component": "TagsInput", "value": ["Tag 1"]}
+examples:
+  - name: canonical-labels
+    description: Label input with lowercase normalization + max 10 tags + 2 pre-committed values.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Card", "children": ["sec"]},
+        {"id": "sec", "component": "Section", "children": ["field"]},
+        {
+          "id": "field",
+          "component": "Field",
+          "label": "Labels",
+          "children": ["tags"]
+        },
+        {
+          "id": "tags",
+          "component": "TagsInput",
+          "name": "labels",
+          "placeholder": "Add a label, press Enter",
+          "transform": "lowercase",
+          "max": 10,
+          "value": ["bug", "high-priority"]
+        }
+      ]
+  - name: email-recipients
+    description: Recipient picker with Enter-only commit (commas are legal in display names).
+    a2ui: >-
+      [
+        {
+          "id": "to",
+          "component": "TagsInput",
+          "name": "to",
+          "placeholder": "Email…",
+          "delimiter": "enter",
+          "transform": "trim"
+        }
+      ]
+keywords:
+  - tags-input
+  - tag-input
+  - token-input
+  - chips-input
+  - chip-input
+  - labels
+  - recipients
+  - keywords
+  - tags
+  - email-input
+  - multi-value-input
+synonyms:
+  tags-input:
+    - tag-input
+    - chip-input
+    - token-input
+    - tokenizer
+  token-input:
+    - tags-input
+    - chip-input
+    - tokenizer
+  chips-input:
+    - tags-input
+    - chip-input
+    - token-input
+  labels:
+    - tags
+    - tag-input
+    - labels-input
+  recipients:
+    - email-input
+    - tags-input
+    - to-field
+related:
+  - tag
+  - select
+  - combobox
+  - field
+  - input

package/components/text/text.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIText } from './class.js';
+import { UIText } from './text.class.js';
 
 defineIfFree('text-ui', UIText);
 

package/components/textarea/textarea.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Textarea.json",
   "title": "Textarea",
-  "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter inserts a newline — does NOT fire `submit` (for\nEnter-to-send composers use <chat-input-ui submit-on-enter> inside\n<chat-composer>). Wrap in <field-ui label=\"…\"> for the canonical\nlabeled stack.\n",
+  "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter (without Shift) dispatches a bubbling `submit`\nevent — Shift+Enter inserts a newline. This is unconditional;\nthere is no opt-in/opt-out attribute. For Enter-to-send composers\nuse <chat-input-ui> inside <chat-composer>. Wrap in <field-ui\nlabel=\"…\"> for the canonical labeled stack.\n",
   "type": "object",
   "allOf": [
     {

package/components/textarea/textarea.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UITextarea } from './class.js';
+import { UITextarea } from './textarea.class.js';
 
 defineIfFree('textarea-ui', UITextarea);
 

package/components/textarea/textarea.yaml

@@ -12,10 +12,11 @@ description: |
   surface (per ADR-0025, no native <textarea> wrapped underneath).
   Form-bearing via UIFormElement: [name], [value], [required],
   [disabled], [readonly], fires `change` on blur and `input` per
-  keystroke. Enter inserts a newline — does NOT fire `submit` (for
-  Enter-to-send composers use <chat-input-ui submit-on-enter> inside
-  <chat-composer>). Wrap in <field-ui label="…"> for the canonical
-  labeled stack.
+  keystroke. Enter (without Shift) dispatches a bubbling `submit`
+  event — Shift+Enter inserts a newline. This is unconditional;
+  there is no opt-in/opt-out attribute. For Enter-to-send composers
+  use <chat-input-ui> inside <chat-composer>. Wrap in <field-ui
+  label="…"> for the canonical labeled stack.
 props:
   disabled:
     description: Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.
@@ -116,10 +117,12 @@ a2ui:
       control user resize. Never substitute a native <textarea> just
       to get rows / resize.
     - >-
-      Enter inserts a newline — <textarea-ui> does NOT emit a `submit`
-      event. For Enter-to-send multi-line composers, use
-      <chat-input-ui submit-on-enter> inside <chat-composer>, not
-      textarea-ui.
+      Enter (without Shift) dispatches a bubbling `submit` event;
+      Shift+Enter inserts a newline. This is unconditional — there
+      is no opt-in/opt-out attribute. For chat composer surfaces
+      wrap inside <chat-composer> + <chat-input-ui> (which adds the
+      send button + model picker + paste-to-attach plumbing on top
+      of the same Enter→submit semantics).
 anti_patterns: []
 examples:
   - name: basic-textarea

package/components/time-picker/time-picker.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UITimePicker } from './class.js';
+import { UITimePicker } from './time-picker.class.js';
 
 defineIfFree('time-picker-ui', UITimePicker);
 

package/components/timeline/timeline-item.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's timeline.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/timeline/{class.js → timeline.class.js}

@@ -88,7 +88,7 @@ export class UITimelineItem extends UIElement {
   };
 
   // §205 (v0.5.7): dynamic chevron icons stamped on expanded-state ternary
-  // (class.js:167). Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
+  // (timeline.class.js:167). Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
   // Note: `this.icon` consumer-supplied — not declared here.
   static requiredIcons = ['caret-down', 'caret-right'];
 

package/components/timeline/timeline.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UITimeline, UITimelineItem } from './class.js';
+import { UITimeline, UITimelineItem } from './timeline.class.js';
 
 defineIfFree('timeline-ui', UITimeline);
 defineIfFree('timeline-item-ui', UITimelineItem);

package/components/toast/toast.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIToast } from './class.js';
+import { UIToast } from './toast.class.js';
 
 defineIfFree('toast-ui', UIToast);
 

package/components/toggle-group/toggle-group.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIToggleOption, UIToggleGroup } from './class.js';
+import { UIToggleOption, UIToggleGroup } from './toggle-group.class.js';
 
 defineIfFree('toggle-option-ui', UIToggleOption);
 defineIfFree('toggle-group-ui', UIToggleGroup);

package/components/toggle-group/toggle-option.yaml

@@ -1,7 +1,7 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
-# drift for UIToggleOption. Ships as a sibling class in toggle-group/class.js
+# drift for UIToggleOption. Ships as a sibling class in toggle-group/toggle-group.class.js
 # + is registered alongside UIToggleGroup.
 
 # Child component of <toggle-group-ui>. Surface only inside that parent.

package/components/toggle-scheme/toggle-scheme.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIToggleScheme } from './class.js';
+import { UIToggleScheme } from './toggle-scheme.class.js';
 
 defineIfFree('toggle-scheme-ui', UIToggleScheme);
 

package/components/toolbar/toolbar-group.yaml

@@ -1,7 +1,7 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
-# drift for UIToolbarGroup. Ships as a sibling class in toolbar/class.js
+# drift for UIToolbarGroup. Ships as a sibling class in toolbar/toolbar.class.js
 # + is registered alongside UIToolbar.
 
 # Child component of <toolbar-ui>. Groups a set of action buttons inside

package/components/toolbar/toolbar.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIToolbar, UIToolbarGroup } from './class.js';
+import { UIToolbar, UIToolbarGroup } from './toolbar.class.js';
 
 defineIfFree('toolbar-ui', UIToolbar);
 defineIfFree('toolbar-group-ui', UIToolbarGroup);

package/components/tooltip/tooltip.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UITooltip } from './class.js';
+import { UITooltip } from './tooltip.class.js';
 
 defineIfFree('tooltip-ui', UITooltip);
 

package/components/tree/tree-item.yaml

@@ -2,7 +2,7 @@
 #
 # §184 (v0.5.5): authored to close FEEDBACK-08 §1 — tree-item-ui badge
 # attribute + general orphan-class catalog gap. tree-item-ui has shipped
-# since v0.0.x co-located in tree/class.js (UITreeItem) but never had its
+# since v0.0.x co-located in tree/tree.class.js (UITreeItem) but never had its
 # own catalog entry. With §172 sibling-yaml scanner, this file is picked
 # up next to the parent yaml. Mirrors the v0.5.5 §176 sibling-yaml
 # baseline-orphan closure pattern.

package/components/tree/tree.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UITree, UITreeItem } from './class.js';
+import { UITree, UITreeItem } from './tree.class.js';
 
 defineIfFree('tree-ui', UITree);
 defineIfFree('tree-item-ui', UITreeItem);

package/components/upload/upload.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIUpload } from './class.js';
+import { UIUpload } from './upload.class.js';
 
 defineIfFree('upload-ui', UIUpload);