@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/tags-input.json

@@ -0,0 +1,738 @@
+{
+  "family": "tags-input",
+  "ui": "tags-input",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Text input that collects values as tags."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "overflow": [
+      "wrap",
+      "collapse"
+    ],
+    "invalidValues": [
+      "keep",
+      "refuse"
+    ],
+    "pendingOnBlur": [
+      "commit",
+      "keep",
+      "discard"
+    ],
+    "editable": [
+      true,
+      false
+    ],
+    "reorderable": [
+      true,
+      false
+    ],
+    "allowDuplicates": [
+      true,
+      false
+    ],
+    "addOnPaste": [
+      true,
+      false
+    ],
+    "clearable": [
+      true,
+      false
+    ],
+    "fullWidth": [
+      true,
+      false
+    ],
+    "disabled": [
+      true,
+      false
+    ],
+    "readOnly": [
+      true,
+      false
+    ],
+    "required": [
+      true,
+      false
+    ],
+    "invalid": [
+      true,
+      false
+    ]
+  },
+  "members": {
+    "tags-input": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "overflow": "wrap",
+        "invalidValues": "keep",
+        "pendingOnBlur": "commit",
+        "editable": false,
+        "reorderable": false,
+        "allowDuplicates": false,
+        "addOnPaste": true,
+        "clearable": true,
+        "fullWidth": true,
+        "disabled": false,
+        "readOnly": false,
+        "required": false,
+        "invalid": false,
+        "max": null,
+        "delimiters": [
+          ","
+        ]
+      },
+      "capabilities": [
+        "value",
+        "overflow",
+        "copyable",
+        "size",
+        "appearance",
+        "fullWidth",
+        "disabled",
+        "readOnly",
+        "required",
+        "invalid",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "required",
+        "current",
+        "complete",
+        "expanded"
+      ],
+      "parts": [
+        "root",
+        "control",
+        "chips",
+        "field",
+        "input",
+        "message",
+        "counter",
+        "clear",
+        "hint"
+      ]
+    }
+  },
+  "docs": {
+    "tags-input": {
+      "imports": {
+        "source": "import { TagsInput, TagsInputDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "The frame, carrying data-ui=\"tags-input\". It draws the border, the shadow, the focus ring and every state, and it grows by whole rows of chips to three, then scrolls. Under overflow=\"collapse\" it carries data-expanded while focus is inside it."
+        },
+        {
+          "part": "control",
+          "element": "div with role=\"grid\"",
+          "required": true,
+          "purpose": "The layout grid the chips and the field live in. The APG names this exact control — \"a list of recipients for a message may be a grid where each cell contains a link that represents a recipient\" — and one element of a layout grid is in the page tab sequence."
+        },
+        {
+          "part": "chips",
+          "element": "div with role=\"row\"",
+          "required": true,
+          "purpose": "One DOM row, however many lines it draws. The wrap is CSS, so the reading order stays linear. Each value in it is a tag worn as a gridcell; an invalid one wears the danger tone and the alert mark. The row names the hint as its description."
+        },
+        {
+          "part": "field",
+          "element": "span with role=\"gridcell\"",
+          "required": true,
+          "purpose": "The last cell of the row, holding the caret. It wraps with the chips rather than being pushed to a line of its own, and it asks for a word of width while keeping a floor of two characters."
+        },
+        {
+          "part": "input",
+          "element": "input, with no role",
+          "required": true,
+          "purpose": "A real text box that opens nothing, so every text-editing key, the caret, IME, autofill, a datalist named by list, and constraint validation stay the browser's. It is the control's one tab stop, and it carries the list's verdict as its custom validity."
+        },
+        {
+          "part": "message",
+          "element": "span, visually hidden",
+          "required": false,
+          "purpose": "Why a value is wrong, inside its chip: the consumer's reason, the browser's own validationMessage, or the generic invalidLabel. The chip names it as its description and repeats it as its title."
+        },
+        {
+          "part": "counter",
+          "element": "span",
+          "required": false,
+          "purpose": "How many values are held against the limit that holds them. Drawn only where it answers something — while max is set, or while the frame is too narrow for a chip."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": false,
+          "purpose": "Takes every value the reader may remove out at once, under the reason clear. Present only while clearable is set and the control holds something removable."
+        },
+        {
+          "part": "hint",
+          "element": "span, visually hidden",
+          "required": true,
+          "purpose": "What the row answers to, for a reader who cannot see the remove buttons: Delete removes a value, and — while editable — Enter edits it. The row names it as its description."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The values, in the order the reader gave them. Controlled."
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The list an unbound control starts from, read once."
+        },
+        {
+          "name": "inputValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The characters in the field. Controlled; it is emptied whenever a value is committed."
+        },
+        {
+          "name": "defaultInputValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The text an unbound field starts from, read once."
+        },
+        {
+          "name": "type",
+          "type": "'text' | 'email' | 'url' | 'tel' | 'search'",
+          "defaultValue": "text",
+          "appliesTo": "TagsInput",
+          "description": "The input’s own type, and — with no validate — the grammar each value is judged against."
+        },
+        {
+          "name": "validate",
+          "type": "(text: string) => boolean | string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Whether a text may be a value: true, false with the generic label, or a string saying why not. Absent, the input’s type, pattern, minLength and maxLength judge."
+        },
+        {
+          "name": "invalidValues",
+          "type": "'keep' | 'refuse'",
+          "defaultValue": "keep",
+          "appliesTo": "TagsInput",
+          "description": "What becomes of a value that fails: a chip in the danger tone with its reason, or a report through onValueRefuse."
+        },
+        {
+          "name": "normalize",
+          "type": "(text: string) => string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Runs before a value is judged. Trim by default; an email field lowercases here."
+        },
+        {
+          "name": "split",
+          "type": "(text: string) => readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "How a paste is split. The default splits on the delimiters and on every line break."
+        },
+        {
+          "name": "formatLabel",
+          "type": "(value: string) => string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The chip’s text for a value, for a value that is an address and a label that is a name."
+        },
+        {
+          "name": "lockedValues",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The values the reader may not remove. Their chips carry data-disabled and draw no remove control."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "BCP 47, for the comparison the duplicate rule makes. The language in force when absent."
+        },
+        {
+          "name": "max",
+          "type": "number | null",
+          "defaultValue": "null",
+          "appliesTo": "TagsInput",
+          "description": "The most values the list may hold."
+        },
+        {
+          "name": "delimiters",
+          "type": "readonly string[]",
+          "defaultValue": ",",
+          "appliesTo": "TagsInput",
+          "description": "The characters that commit the typed text and split a paste. Line breaks split a paste whatever this says."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "TagsInput",
+          "description": "The type step, and the frame’s height when empty."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "TagsInput",
+          "description": "An edge, a ground, or neither."
+        },
+        {
+          "name": "overflow",
+          "type": "'wrap' | 'collapse'",
+          "defaultValue": "wrap",
+          "appliesTo": "TagsInput",
+          "description": "Whether the row wraps to three lines and scrolls, or stays one line and opens while focus is inside."
+        },
+        {
+          "name": "pendingOnBlur",
+          "type": "'commit' | 'keep' | 'discard'",
+          "defaultValue": "commit",
+          "appliesTo": "TagsInput",
+          "description": "What leaving the control does with the text in the field."
+        },
+        {
+          "name": "editable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether Enter or a double click on a chip opens it for editing."
+        },
+        {
+          "name": "reorderable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether Alt with an arrow moves the focused chip."
+        },
+        {
+          "name": "allowDuplicates",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether the same value may stand twice."
+        },
+        {
+          "name": "addOnPaste",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "TagsInput",
+          "description": "Whether a paste with several values becomes several chips."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "TagsInput",
+          "description": "Whether the clear button is drawn while the control holds something."
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "TagsInput",
+          "description": "Whether the frame fills its container."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Unstated, the control asks the field around it."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether the values may be read and copied but not changed."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether an empty list is a validity error. Written on the input only while the list is empty."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TagsInput",
+          "description": "Whether the control is drawn in error, in addition to any value that failed."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TagsInputMessages>",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Words laid over the language in force, key by key: added, addedInvalid, clear, copied, count, countNamed, counter, duplicate, editHint, hint, invalid, remove, removed, reorder"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Replaces the frame around the control, keeping the ref the width gate measures."
+        },
+        {
+          "name": "handleRef",
+          "type": "Ref<TagsInputHandle>",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The imperative handle: focus(), clear() and setValue(values, reason). ref is the input."
+        }
+      ],
+      "composition": [
+        {
+          "name": "TagsInputDefaultsProvider",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Provider",
+          "description": "Sets every axis once for a subtree; the words come from the language in force (SlottedProvider). A prop on a control wins over it."
+        },
+        {
+          "name": "render",
+          "type": "(props: TagsInputRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Replaces the frame. Spread the props: they carry the ref the width gate and Backspace read."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "The input itself, as text-field exposes it."
+        },
+        {
+          "name": "native props",
+          "type": "ComponentPropsWithRef<\"input\">",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "placeholder, pattern, minLength, maxLength, list, inputMode, enterKeyHint, autoComplete, name, form, every aria-* and every handler reach the input; className and style reach the frame."
+        },
+        {
+          "name": "onKeyDown, onPaste, onBlur, onChange",
+          "type": "handler",
+          "defaultValue": "—",
+          "appliesTo": "TagsInput",
+          "description": "Composed, never replaced: the family’s handler runs after the consumer’s and does nothing when the event was defaultPrevented."
+        },
+        {
+          "name": "Field",
+          "type": "component",
+          "defaultValue": "—",
+          "appliesTo": "Field",
+          "description": "A control inside a field takes its id, its description, its error and its states from the field without being wrapped."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: readonly string[], request: ChangeRequest<readonly string[]>)",
+          "when": "The list moved. The request carries the reason: submit from typed text, a paste, a blur or an edit; remove from one value leaving; clear from all of them; keyboard from a reorder; programmatic from the handle."
+        },
+        {
+          "name": "onInputValueChange",
+          "payload": "(value: string, request: ChangeRequest<string>)",
+          "when": "The text in the field moved: keyboard while typing, submit when a commit empties it, clear from Escape or the clear button, blur when leaving discards it."
+        },
+        {
+          "name": "onValueRefuse",
+          "payload": "(values: readonly string[], details: { cause: \"duplicate\" | \"limit\" | \"invalid\" })",
+          "when": "One or more values did not get in. It holds no state and cancels nothing — the values never entered the list. invalid arrives only under invalidValues=\"refuse\"."
+        },
+        {
+          "name": "onValueCopy",
+          "payload": "(values: readonly string[], outcome: 'api' | 'command' | 'refused')",
+          "when": "The reader copied a chip or the whole list with the keyboard, and the text either reached the clipboard by one of the two ways or was refused."
+        }
+      ],
+      "accessibility": [
+        "The control is a layout grid with one row: the chips are cells and the field is the last cell, so one Tab reaches the input and the arrows walk the row. The input carries no role, because it opens nothing.",
+        "Focus is set on a chip cell rather than on the remove button inside it, which is tabindex=\"-1\"; Delete and Backspace do what the button does, and the row’s hint says so. React Aria and Angular Material resolve the grid pattern’s text-plus-widget cell the same way.",
+        "An invalid value is said three ways — the danger tone, the alert mark, and a description carrying the reason — because colour alone is not a message. The same reason is the input’s custom validity, so a native submit is refused with the browser’s bubble.",
+        "Every change is announced once, politely: a value added with the count now held and its reason if it failed, a value removed with the count that is left, a move with its new position, a duplicate with the chip that holds it, and a copy with the count copied.",
+        "After a removal focus goes to the chip that took the removed one’s index, then the previous one, then the input — it is never lost to the document body."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-sm",
+    "--slotted-radius-none",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-surface-sunken",
+    "--slotted-tags-input-action-active-background",
+    "--slotted-tags-input-action-color",
+    "--slotted-tags-input-action-hover-background",
+    "--slotted-tags-input-action-size",
+    "--slotted-tags-input-autofill-background",
+    "--slotted-tags-input-background",
+    "--slotted-tags-input-border-color",
+    "--slotted-tags-input-color",
+    "--slotted-tags-input-counter-color",
+    "--slotted-tags-input-counter-complete-color",
+    "--slotted-tags-input-current-border-color",
+    "--slotted-tags-input-disabled-background",
+    "--slotted-tags-input-disabled-border-color",
+    "--slotted-tags-input-disabled-color",
+    "--slotted-tags-input-field-basis",
+    "--slotted-tags-input-field-min",
+    "--slotted-tags-input-hover-border-color",
+    "--slotted-tags-input-icon-size-min",
+    "--slotted-tags-input-invalid-border-color",
+    "--slotted-tags-input-invalid-edge-width",
+    "--slotted-tags-input-invalid-focus-ring-color",
+    "--slotted-tags-input-placeholder-color",
+    "--slotted-tags-input-plain-hover-background",
+    "--slotted-tags-input-radius",
+    "--slotted-tags-input-readonly-background",
+    "--slotted-tags-input-shadow",
+    "--slotted-tags-input-subtle-background",
+    "--slotted-tags-input-subtle-border-color",
+    "--slotted-tags-input-subtle-hover-background",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One control with every axis on it, driven by the controls under the canvas. Type an address and press Enter or a comma; type one without an @ and watch it stay, marked, instead of vanishing.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"To\"\n  defaultValue={['ana.pereira@example.com']}\n  placeholder=\"Add a recipient\"\n  type=\"email\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "recipients",
+      "title": "The recipients of a message",
+      "note": "The value is a list of texts and the text is the label. formatLabel draws the chip from the address — a name where the value is an address — and the value a form receives stays the address.",
+      "language": "tsx",
+      "source": "const [to, setTo] = useState<readonly string[]>(['ana.pereira@example.com']);\n\n<TagsInput\n  aria-label=\"To\"\n  formatLabel={(address) => contacts.get(address) ?? address}\n  onValueChange={setTo}\n  type=\"email\"\n  value={to}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "validity",
+      "title": "A value that fails is held, not dropped",
+      "note": "jhon.company stays where the reader can see it: the chip takes the danger tone and the alert mark, its reason is its description and its title, the frame is invalid, and a native submit is refused with the browser’s bubble on the control. Under invalidValues=\"refuse\" the same value is reported instead.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"To\"\n  validate={(text) => (text.includes('@') ? true : 'Needs an @ and a domain')}\n/>;\n\n<TagsInput\n  aria-label=\"SKUs\"\n  invalidValues=\"refuse\"\n  onValueRefuse={(values, { cause }) => report(cause, values)}\n  validate={(text) => /^[A-Z]{3}-\\d{4}$/.test(text)}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "platform-validation",
+      "title": "The browser validates, in the reader’s language",
+      "note": "With no validate given, type=\"email\" and pattern judge each value the way the platform judges a single one, and the chip’s reason is the browser’s own validationMessage — already translated, and already the sentence the reader has seen on every other form.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" type=\"email\" />;\n\n<TagsInput aria-label=\"Order numbers\" pattern=\"ORD-\\d{6}\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "limit",
+      "title": "A limit that is counted, and refused past it",
+      "note": "The counter is drawn only because max is set, takes the accent once the list is full, and the root carries data-complete. What arrives past the limit is reported with the values rather than dropped — a paste of six into a list of three says which three did not fit.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"Reviewers\"\n  max={3}\n  onValueRefuse={(values, { cause }) => cause === 'limit' && show(values)}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "duplicates",
+      "title": "Duplicates",
+      "note": "The comparison is locale-sensitive, so typing ANA.PEREIRA@EXAMPLE.COM finds the address already held; focus goes to that chip and its edge takes the accent for one long step, rather than nothing happening. allowDuplicates lets the same value stand twice.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" locale=\"pt-BR\" />;\n\n<TagsInput aria-label=\"Line items\" allowDuplicates />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "paste",
+      "title": "Pasting many values at once",
+      "note": "A paste splits on the delimiters and on every line break — a column copied out of a spreadsheet arrives one value per line. split replaces the rule for a clipboard the family cannot guess, such as addresses with quoted names in them.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"Cc\" delimiters={[',', ';']} type=\"email\" />;\n\n<TagsInput\n  aria-label=\"To\"\n  split={(text) => text.match(/[^\\s@,\"]+@[^\\s,>\"]+/g) ?? []}\n  type=\"email\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "blur",
+      "title": "What leaving does with the pending text",
+      "note": "Three answers, one word each: commit turns the text into a value, keep leaves it in the box, discard empties it. A recipients field commits; a filter operand keeps; a chat box discards.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" pendingOnBlur=\"commit\" />;\n<TagsInput aria-label=\"Filter\" pendingOnBlur=\"keep\" />;\n<TagsInput aria-label=\"Tags\" pendingOnBlur=\"discard\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "editing",
+      "title": "Editing a chip in place",
+      "note": "Enter on a chip — or a double click — turns its cell into a text field holding the value. Enter commits, Escape reverts, and the edit is judged like any other value: an edit into an address already held is refused and the chip that holds it takes focus.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" editable type=\"email\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reorder",
+      "title": "Reorder, by keyboard first",
+      "note": "Alt with an arrow moves the focused chip one place along the row, following the writing direction; Alt+Home and Alt+End move it to either end. The request carries keyboard and nothing else, so a consumer persisting an order listens for exactly that.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"Approvers, in order\"\n  onValueChange={(next, { reason }) => reason === 'keyboard' && saveOrder(next)}\n  reorderable\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locked",
+      "title": "A value the reader may not remove",
+      "note": "lockedValues keeps a mandatory recipient in the list: its chip carries data-disabled, draws no remove control, is skipped by Backspace and by the clear button, and is still reachable by arrow — because the reader still has to be able to read it.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"Cc\"\n  defaultValue={['support@example.com', 'ana.pereira@example.com']}\n  lockedValues={['support@example.com']}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "copy",
+      "title": "The list on the clipboard",
+      "note": "Ctrl+C on a chip copies its value; Ctrl+X copies it and removes it. Ctrl+C on the empty field copies the whole list, joined by the first delimiter and a space — the shape a paste into another instance of this family reads back.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"Cc\"\n  onValueCopy={(values, outcome) => outcome === 'refused' && warn(values)}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "overflow",
+      "title": "Overflow, and access to the whole list",
+      "note": "wrap grows the frame by whole rows to three and scrolls past them, and nothing leaves the DOM. collapse keeps one line and a +N at rest — for a filter bar or a table cell — and shows every chip while focus is inside the control, because there is no popup to hold them and no need for one.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"Cc\" overflow=\"wrap\" />;\n<TagsInput aria-label=\"Cc\" overflow=\"collapse\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Sizes",
+      "note": "The frame takes the control height of its step, so an empty control is exactly the height of a text field beside it; the chips keep the small step at every size, because a chip is a chip and not a control.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" size=\"sm\" />;\n<TagsInput aria-label=\"To\" size=\"md\" />;\n<TagsInput aria-label=\"To\" size=\"lg\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "Variants",
+      "note": "outline for a form, subtle for a panel that already has a ground, and plain for a table cell — where an edge and a resting shadow would draw a cell that is not there.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" variant=\"outline\" />;\n<TagsInput aria-label=\"To\" variant=\"subtle\" />;\n<TagsInput aria-label=\"To\" variant=\"plain\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "States",
+      "note": "disabled answers nothing and keeps its values legible; readOnly keeps the caret, the copy and the chips at full ink, and withholds every remove control; invalid retints the border and the focus ring together; required is the platform’s own, written on the input only while the list is empty.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" disabled />;\n<TagsInput aria-label=\"To\" readOnly />;\n<TagsInput aria-label=\"To\" invalid required />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "long-content",
+      "title": "Content the family did not choose",
+      "note": "A sixty-character address truncates inside its chip and stays whole in the accessibility tree; the row wraps rather than pushing the frame wider; and under 120 pixels there is no chip at all and the counter answers instead.",
+      "language": "tsx",
+      "source": "<TagsInput\n  aria-label=\"To\"\n  defaultValue={['quality-assurance-and-release-management@subsidiary.example.com']}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Tab reaches the field once. Backspace from an empty field moves to the last chip and removes nothing; a second press removes it. Delete takes the focused chip out, the arrows walk the row and mirror under rtl, Escape clears the text and never the list, and a printable character sends the reader back to the field.",
+      "language": "tsx",
+      "source": "<TagsInput aria-label=\"To\" defaultValue={['ana.pereira@example.com']} editable reorderable />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "form",
+      "title": "In a form",
+      "note": "One hidden input per value under the name to, so a plain FormData receives all of them under one key; required is written on the visible input only while the list is empty; and an invalid value blocks the native submit through setCustomValidity. The field carries the label, the description and the error by ID.",
+      "language": "tsx",
+      "source": "<Field required>\n  <FieldLabel>To</FieldLabel>\n  <FieldDescription>Everyone who should see this message.</FieldDescription>\n  <TagsInput name=\"to\" type=\"email\" />\n  <FieldError>Name at least one recipient</FieldError>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "The provider carries every axis, the words come from the language in force, and a prop on one control still wins over it. render replaces the frame, ref reaches the input, handleRef reaches focus, clear and setValue, and list passes through to a datalist for the browser’s own completion.",
+      "language": "tsx",
+      "source": "<TagsInputDefaultsProvider delimiters={[',', ';']}>\n  <TagsInput aria-label=\"To\" handleRef={handle} list=\"contacts\" type=\"email\" />\n  <datalist id=\"contacts\">\n    <option value=\"ana.pereira@example.com\" />\n  </datalist>\n</TagsInputDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}