@adia-ai/web-components 0.6.34 → 0.6.35

package/components/tags-input/tags-input.a2ui.json

@@ -0,0 +1,337 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/TagsInput.json",
+  "title": "TagsInput",
+  "description": "Free-form token input — type a value, press Enter (or the configured\ndelimiter) to commit it as a chip; Backspace from the empty inline\ninput removes the last chip. Distinct from <select-ui multiple>\n(SPEC-040), which is constrained to a fixed option list — tags-input\nis for OPEN sets (labels, email recipients, keyword inputs). Per\nADR-0025 the inline editor is a contenteditable surface (NO native\n`<input>` wrap). Form-bearing via UIFormElement + ElementInternals:\nthe form value is a JSON-serialized string array under `[name]`.\nEach rendered chip is a `<tag-ui removable>`; the `remove` event\ndelegates back to the host. Optional autocompletion: when\n`.suggestions` is non-empty, a popover renders below the field and\nthe host announces as a combobox per WAI-APG.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "required": {
+      "description": "Required for form validation. Empty array fails `:invalid`.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "TagsInput"
+    },
+    "delimiter": {
+      "description": "Inline character that commits the typed value as a chip. The\nsentinel `enter` disables in-line commit — only the Enter key\n(or programmatic `addToken`) commits. Default is `,`.",
+      "type": "string",
+      "default": ","
+    },
+    "disabled": {
+      "description": "Block all interaction; dim the field.",
+      "type": "boolean",
+      "default": false
+    },
+    "max": {
+      "description": "Maximum number of tokens. `0` (default) means unlimited.",
+      "type": "number",
+      "default": 0
+    },
+    "maxLength": {
+      "description": "Maximum per-token character count. `0` (default) means unlimited.",
+      "type": "number",
+      "default": 0
+    },
+    "min": {
+      "description": "Minimum required tokens for form validity.",
+      "type": "number",
+      "default": 0
+    },
+    "minLength": {
+      "description": "Minimum per-token character count after `transform` is applied.",
+      "type": "number",
+      "default": 1
+    },
+    "name": {
+      "description": "Form field name. Serializes the token list as JSON under this key.",
+      "type": "string",
+      "default": ""
+    },
+    "pasteSplit": {
+      "description": "Regex character-class fragment matched against pasted text to\nsplit it into multiple tokens. Default `,\\n` splits on commas\nand newlines. Use `\"\"` to disable paste-splitting entirely.",
+      "type": "string",
+      "default": ",\n"
+    },
+    "placeholder": {
+      "description": "Placeholder text for the inline input when no chips are committed.",
+      "type": "string",
+      "default": "Add tag…"
+    },
+    "readonly": {
+      "description": "Block edits; allow inspection (chips render without remove buttons).",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Sizing scale via universal `[size]` attribute system. Matches\nInput + Combobox sizing tokens so a TagsInput rendered alongside\neither feels coherent in a form row.",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "suggestions": {
+      "description": "Optional autocomplete strings rendered in a popover below the\nfield. Suggestions are hints, not gates — the typed value still\nwins on commit. JS property only (array reflection skipped).",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "transform": {
+      "description": "Normalize tokens on commit. `lowercase` lowercases, `trim` strips\nleading + trailing whitespace, `strip-spaces` removes all\nwhitespace, `\"\"` (default) preserves the typed value.",
+      "type": "string",
+      "enum": [
+        "",
+        "lowercase",
+        "trim",
+        "strip-spaces"
+      ],
+      "default": ""
+    },
+    "unique": {
+      "description": "Reject duplicate tokens silently (no `invalid` event for accidental dups).",
+      "type": "boolean",
+      "default": true
+    },
+    "validateFn": {
+      "description": "Per-token validator. Sync `(value, index) => boolean` rejects\nfalse synchronously; async `(value, index) => Promise<boolean>`\nflips the host into `[validating]` while pending. JS property\nonly — not serializable in A2UI JSON; wire post-mount.",
+      "type": "object",
+      "default": null
+    },
+    "value": {
+      "description": "Current token list (string array). Setting `.value = ['a','b']`\nreplaces the rendered chips. Reflection skipped — array values\ndo not round-trip through attribute strings.",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Select\", \"multiple\": true, \"options\": [{\"id\": \"a\", \"label\": \"A\"}]}\n",
+        "why": "TagsInput does NOT accept `options`. It is the OPEN-set primitive — any\ntyped string is valid. For closed option lists, use the multi-select\nprimitive with `multiple: true`.\n",
+        "wrong": "{\"component\": \"TagsInput\", \"options\": [{\"id\": \"a\", \"label\": \"A\"}]}\n"
+      },
+      {
+        "fix": "{\"component\": \"TagsInput\", \"value\": [\"bug\", \"high-priority\"]}\n",
+        "why": "Comma-separated string is invalid for `value`. The contract requires\na string array.\n",
+        "wrong": "{\"component\": \"TagsInput\", \"value\": \"bug,high-priority\"}\n"
+      },
+      {
+        "fix": "{\"component\": \"TagsInput\", \"value\": [\"Tag 1\"]}\n",
+        "why": "Chips are rendered automatically from `value`. Slotting Tag children\ndecouples the rendered DOM from the form value and breaks Backspace\nremoval + the `change` event payload.\n",
+        "wrong": "{\"component\": \"TagsInput\", \"children\": [\n  {\"component\": \"Tag\", \"text\": \"Tag 1\"}\n]}\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "tag-ui",
+      "icon-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired after `value` changes (token added or removed).",
+        "detail": {
+          "added": {
+            "description": "Tokens added by this change (`[]` when only removals occurred).",
+            "type": "array"
+          },
+          "removed": {
+            "description": "Tokens removed by this change (`[]` when only additions occurred).",
+            "type": "array"
+          },
+          "value": {
+            "description": "Current token list (string array).",
+            "type": "array"
+          }
+        }
+      },
+      "commit": {
+        "description": "Fired immediately before a token is committed. Call\n`event.preventDefault()` to reject the candidate token.",
+        "detail": {
+          "accepted": {
+            "description": "True unless the consumer calls `preventDefault()`.",
+            "type": "boolean"
+          },
+          "value": {
+            "description": "Candidate token text (post-transform).",
+            "type": "string"
+          }
+        }
+      },
+      "input": {
+        "description": "Fired on each keystroke in the inline input (pre-commit).",
+        "detail": {
+          "query": {
+            "description": "Current typed text in the inline input.",
+            "type": "string"
+          }
+        }
+      },
+      "invalid": {
+        "description": "Fired when a candidate token is rejected. Reasons cover all\nbuilt-in validators and the user-supplied `validateFn`.",
+        "detail": {
+          "reason": {
+            "description": "One of `duplicate` / `too-short` / `too-long` / `validator` / `max`.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Rejected token text.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Label input with lowercase normalization + max 10 tags + 2 pre-committed values.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"children\": [\"field\"]},\n  {\n    \"id\": \"field\",\n    \"component\": \"Field\",\n    \"label\": \"Labels\",\n    \"children\": [\"tags\"]\n  },\n  {\n    \"id\": \"tags\",\n    \"component\": \"TagsInput\",\n    \"name\": \"labels\",\n    \"placeholder\": \"Add a label, press Enter\",\n    \"transform\": \"lowercase\",\n    \"max\": 10,\n    \"value\": [\"bug\", \"high-priority\"]\n  }\n]",
+        "name": "canonical-labels"
+      },
+      {
+        "description": "Recipient picker with Enter-only commit (commas are legal in display names).",
+        "a2ui": "[\n  {\n    \"id\": \"to\",\n    \"component\": \"TagsInput\",\n    \"name\": \"to\",\n    \"placeholder\": \"Email…\",\n    \"delimiter\": \"enter\",\n    \"transform\": \"trim\"\n  }\n]",
+        "name": "email-recipients"
+      }
+    ],
+    "keywords": [
+      "tags-input",
+      "tag-input",
+      "token-input",
+      "chips-input",
+      "chip-input",
+      "labels",
+      "recipients",
+      "keywords",
+      "tags",
+      "email-input",
+      "multi-value-input"
+    ],
+    "name": "UITagsInput",
+    "related": [
+      "tag",
+      "select",
+      "combobox",
+      "field",
+      "input"
+    ],
+    "slots": {
+      "chip": {
+        "description": "Custom chip template — receives `{value, index}` per token.\nWhen absent, each token renders as a default\n`<tag-ui removable text=\"<value>\">`."
+      }
+    },
+    "states": [
+      {
+        "description": "No tokens; no typed text.",
+        "name": "idle"
+      },
+      {
+        "description": "One or more tokens committed.",
+        "attribute": "populated",
+        "name": "populated"
+      },
+      {
+        "description": "User is typing into the inline input.",
+        "attribute": "editing",
+        "name": "editing"
+      },
+      {
+        "description": "Suggestion popover is open.",
+        "attribute": "suggesting",
+        "name": "suggesting"
+      },
+      {
+        "description": "Async `validateFn` is in flight.",
+        "attribute": "validating",
+        "name": "validating"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "Read-only; chips render without remove affordance.",
+        "attribute": "readonly",
+        "name": "readonly"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "chips-input": [
+        "tags-input",
+        "chip-input",
+        "token-input"
+      ],
+      "labels": [
+        "tags",
+        "tag-input",
+        "labels-input"
+      ],
+      "recipients": [
+        "email-input",
+        "tags-input",
+        "to-field"
+      ],
+      "tags-input": [
+        "tag-input",
+        "chip-input",
+        "token-input",
+        "tokenizer"
+      ],
+      "token-input": [
+        "tags-input",
+        "chip-input",
+        "tokenizer"
+      ]
+    },
+    "tag": "tags-input-ui",
+    "tokens": {
+      "--tags-input-bg": {
+        "description": "Host background color."
+      },
+      "--tags-input-border": {
+        "description": "Host border color (idle)."
+      },
+      "--tags-input-border-hover": {
+        "description": "Host border color on hover."
+      },
+      "--tags-input-chip-bg-invalid": {
+        "description": "Chip background color when a chip is marked invalid (validator rejection echo)."
+      },
+      "--tags-input-fg": {
+        "description": "Host foreground (typed-text color)."
+      },
+      "--tags-input-focus-ring": {
+        "description": "Focus-ring box-shadow when the host is focus-within."
+      },
+      "--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-px": {
+        "description": "Horizontal padding inside the chip-cluster wrapper."
+      },
+      "--tags-input-py": {
+        "description": "Vertical padding inside the chip-cluster wrapper."
+      },
+      "--tags-input-radius": {
+        "description": "Host border radius."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}