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

package/dist/docs/text-field.json

@@ -0,0 +1,610 @@
+{
+  "family": "text-field",
+  "ui": "text-field",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Single-line text input."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ]
+  },
+  "members": {
+    "textField": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "mono": false,
+        "clearable": false,
+        "revealable": false,
+        "showCount": false,
+        "copyable": false,
+        "loading": false
+      },
+      "capabilities": [
+        "value",
+        "revealed",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring",
+        "loading"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly",
+        "loading",
+        "complete"
+      ],
+      "parts": [
+        "root",
+        "input",
+        "start",
+        "end",
+        "action",
+        "busy",
+        "caps-lock",
+        "clear",
+        "copy",
+        "reveal"
+      ]
+    }
+  },
+  "docs": {
+    "textField": {
+      "imports": {
+        "source": "import { TextField, TextFieldAction, TextFieldDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The frame. It carries data-ui=\"text-field\", data-size, data-variant and data-mono, and data-disabled, data-invalid, data-readonly and data-loading. It has no role: WAI-ARIA allows a textbox only non-interactive children, so the buttons sit beside the input inside a box that announces nothing. className and style reach this element."
+        },
+        {
+          "part": "input",
+          "element": "input",
+          "required": true,
+          "purpose": "The control. It holds the value and the identifier, and receives every native attribute you write: type, autoComplete, inputMode, enterKeyHint, pattern, maxLength, name, form and required. ref reaches it, so focus(), select() and setSelectionRange() are the element’s own."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "Content before the value in the reading direction, such as a currency, an icon or an @. It is its own bidirectional run, so R$ keeps its order in a right-to-left document, and an icon inside it takes the control’s icon size."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "Content after the value in the reading direction, such as a unit, a domain or a suffix."
+        },
+        {
+          "part": "action",
+          "element": "button (TextFieldAction), inside start or end",
+          "required": false,
+          "purpose": "A button you place inside the frame: a submit, a menu trigger or a tooltip trigger. It is square when named by aria-label and padded when named by its text. aria-expanded=\"true\" keeps it pressed while the menu it opened is open."
+        },
+        {
+          "part": "busy",
+          "element": "span[data-ui=\"spinner\"]",
+          "required": false,
+          "purpose": "The shared spinner, before the buttons, while loading is true. It is rendered whenever loading is set and hidden while loading is false, so it can leave with a transition. It is hidden from assistive technology; aria-busy on the input carries the state."
+        },
+        {
+          "part": "caps-lock",
+          "element": "span",
+          "required": false,
+          "purpose": "A mark in a password field while Caps Lock is on and the input has focus. It is hidden from assistive technology; the capsLock message is announced once when Caps Lock turns on."
+        },
+        {
+          "part": "clear",
+          "element": "button",
+          "required": false,
+          "purpose": "Empties the value with reason \"clear\" and returns focus to the input. It is rendered while clearable is set, hidden while the value is empty or cannot be changed, and never smaller than 24 CSS pixels."
+        },
+        {
+          "part": "copy",
+          "element": "button",
+          "required": false,
+          "purpose": "Writes the value to the clipboard, shows a check with data-complete for two seconds and announces the outcome. It stays on a read-only value and is hidden while the value is empty or the input is disabled."
+        },
+        {
+          "part": "reveal",
+          "element": "button",
+          "required": false,
+          "purpose": "Shows the password as characters and hides it again, keeping the caret where it was. Its name does not change with its state, which is the APG rule for a toggle button; aria-pressed carries the state."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Makes the value controlled for the life of the component. Without it the input keeps its own value, and a native form reset restores defaultValue."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "The value an uncontrolled text field starts from. It is read once and written to the input as the native attribute."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "TextField, TextFieldDefaultsProvider",
+          "description": "The step of the control scale. Without it the text field takes the size of the field around it, then the provider’s. Height, padding, type and icon size come from the control scales, which the theme restates for each density."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "TextField, TextFieldDefaultsProvider",
+          "description": "How much frame the control draws. plain draws no border at rest and keeps the same box, for a dense table cell."
+        },
+        {
+          "name": "mono",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField, TextFieldDefaultsProvider",
+          "description": "Sets the value in the monospaced font with tabular figures, for identifiers, hashes and keys."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField",
+          "description": "Draws a button that empties the value with reason \"clear\" and returns focus to the input. The button is withdrawn while the value is empty, disabled or read-only."
+        },
+        {
+          "name": "revealable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField",
+          "description": "Draws a toggle that shows a password as characters. It appears only on type=\"password\" and is withdrawn while the input is disabled."
+        },
+        {
+          "name": "copyable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField",
+          "description": "Draws a button that writes the value to the clipboard, shows a check for two seconds and announces the outcome. It is hidden while the value is empty or the input is disabled."
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField",
+          "description": "Draws the shared spinner before the buttons and sets aria-busy on the input; the value stays editable. Once loading is set, false included, the spinner keeps its place so it can leave with a transition."
+        },
+        {
+          "name": "revealed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Makes the password toggle controlled. defaultRevealed sets the uncontrolled starting state."
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "TextField",
+          "description": "Publishes the length of the value to the field around it, which draws the count at the end of its label row."
+        },
+        {
+          "name": "countMax",
+          "type": "number",
+          "defaultValue": "maxLength",
+          "appliesTo": "TextField",
+          "description": "The limit the count is measured against. Without maxLength it is a soft limit: the value can pass it, and the count turns to the danger tone before validation runs."
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Content before the value in the reading direction. It is its own bidirectional run, and an icon inside it takes the control’s icon size."
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Content after the value in the reading direction."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "TextField",
+          "description": "Unset by default, so the text field takes the state of the field around it. When set, it wins, and it is the native attribute: the input leaves the tab order and form submission."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "TextField",
+          "description": "Unset by default, so the text field takes the state of the field around it. It is the native readonly: the input stays focusable and selectable, and its value is submitted."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "TextField",
+          "description": "Unset by default, so the text field takes the state of the field around it. It sets aria-invalid on the input and data-invalid on the frame."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "The input’s own attribute, passed through unchanged; TextField never writes it. A field marks a required value with aria-required instead, because the native attribute turns on browser constraint validation."
+        },
+        {
+          "name": "type",
+          "type": "'text' | 'search' | 'email' | 'url' | 'tel' | 'password'",
+          "defaultValue": "text",
+          "appliesTo": "TextField",
+          "description": "The input’s own type. Any other string an input accepts still reaches the element."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TextFieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Replaces words of the active language, key by key. clear, reveal and copy name the buttons; reveal does not change with the state, because aria-pressed carries it. copied and copyFailed announce the outcome of a copy. capsLock is announced once when Caps Lock turns on in a focused password field."
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: TextFieldRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Renders the frame into another element and passes it every attribute. The props are typed against HTMLAttributes<HTMLElement>, so they can be spread onto a label or a fieldset. The input cannot be replaced, because it holds the value, the identifier and the wiring."
+        },
+        {
+          "name": "TextFieldAction",
+          "type": "ComponentPropsWithRef<\"button\"> & { render? }",
+          "defaultValue": "type=\"button\"",
+          "appliesTo": "start, end",
+          "description": "A button you place inside the frame. Every native prop reaches the button, and render replaces it. MenuTrigger, PopoverTrigger and TooltipTrigger pass their wiring to it through their own render."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Reaches the input. focus(), select() and setSelectionRange() are the element’s own, so TextField adds no imperative handle."
+        },
+        {
+          "name": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "TextField",
+          "description": "Reach the frame, because the frame is what a reader sees. Every other native prop reaches the input."
+        },
+        {
+          "name": "TextFieldDefaultsProvider",
+          "type": "{ size, variant, mono }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets size, variant and mono once for every text field under it. A field outranks it for size, so a text field inside a field takes the field’s size."
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What TextField reads from the field around it: the identifier, the description, the disabled, read-only, invalid and required states, and the channel it publishes its count on. A text field inside a field needs no wiring of its own."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: string, request: ChangeRequest<string>)",
+          "when": "Before the value changes. The request carries the new value, the value it replaces, the reason (\"keyboard\" for an edit in the input, \"clear\" for the clear button), the originating event, and cancel(), which refuses the change before it commits."
+        },
+        {
+          "name": "onRevealedChange",
+          "payload": "(revealed: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the password toggle changes, with reason \"pointer\" or \"keyboard\" read from the click. A form that hides the password again on blur controls revealed and listens here."
+        },
+        {
+          "name": "onValueCopy",
+          "payload": "({ copied, reason, source, value }: TextFieldCopyDetail)",
+          "when": "After the copy button has asked the clipboard. copied is false when the clipboard refused the value, and reason is \"pointer\" or \"keyboard\". onCopy remains the input’s native clipboard event."
+        },
+        {
+          "name": "onChange, onInput, onFocus, onBlur, onKeyDown, onKeyUp",
+          "payload": "the element’s own events",
+          "when": "Whenever the input fires them. TextField composes your handler with its own instead of replacing it: yours runs first, and always runs."
+        }
+      ],
+      "accessibility": [
+        "There is no WAI-ARIA Authoring Practices pattern for a text field: the APG lists thirty patterns, and none of them is a single-line text input. The sources are the HTML specification for the input element, the APG practice Providing Accessible Names and Descriptions (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for its name, and the ARIA textbox role for what may sit inside it.",
+        "The frame has no role. WAI-ARIA requires the children of a textbox to be non-interactive and presentational, so the clear and reveal buttons are siblings of the input inside a box that announces nothing.",
+        "The input takes its name from the field’s label, whose for attribute points at the identifier the field generates. The APG naming practice records that some combinations of browser and assistive technology compute no name from a label that wraps its control.",
+        "Inside a required field the input carries aria-required, never the native required, because the native attribute turns on browser constraint validation and changes how the form submits. Write required on the input to opt into the platform’s validation; TextField leaves it unchanged. disabled and readonly are the native attributes.",
+        "The clear and reveal buttons are native buttons with names you translate once through messages. Each is at least 24 CSS pixels wide at every size and density, which meets WCAG 2.2 success criterion 2.5.8. The reveal button keeps one name and carries its state in aria-pressed, which is the APG rule for a toggle button.",
+        "The copy button announces its outcome through the shared live announcer, Copied or Copy failed, because the check that replaces the copy mark is only visible. The Caps Lock mark is hidden from assistive technology; its message is announced once when Caps Lock turns on while the password field has focus.",
+        "loading sets aria-busy on the input and leaves it enabled, so the keyboard stays on the input while an asynchronous check runs. The spinner is hidden from assistive technology.",
+        "A menu inside the frame follows the APG menu button pattern (w3.org/WAI/ARIA/apg/patterns/menu-button/). The menu trigger on the action supplies aria-haspopup, aria-expanded, and Enter, Space and ArrowDown to open.",
+        "No key is bound to Escape. Some browsers clear a search input on Escape, and a text field that consumed the key inside a dialog would leave a keyboard user unable to close the dialog. WCAG success criterion 2.1.4 addresses the defects that single-key shortcuts cause.",
+        "The invalid state does not rely on colour alone: aria-invalid announces it, the field’s error states it in words, and the inline message writes a visually hidden “Error:” before the sentence. In the high-contrast scheme the border cannot carry the state, so nothing depends on it."
+      ]
+    }
+  },
+  "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-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-mono",
+    "--slotted-font-weight-medium",
+    "--slotted-radius-none",
+    "--slotted-radius-xs",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-field-action-active-background",
+    "--slotted-text-field-action-color",
+    "--slotted-text-field-action-hover-background",
+    "--slotted-text-field-action-label-color",
+    "--slotted-text-field-action-size",
+    "--slotted-text-field-adornment-color",
+    "--slotted-text-field-autofill-background",
+    "--slotted-text-field-background",
+    "--slotted-text-field-border-color",
+    "--slotted-text-field-caps-lock-color",
+    "--slotted-text-field-color",
+    "--slotted-text-field-copy-complete-color",
+    "--slotted-text-field-disabled-background",
+    "--slotted-text-field-disabled-border-color",
+    "--slotted-text-field-disabled-color",
+    "--slotted-text-field-hover-border-color",
+    "--slotted-text-field-icon-size-min",
+    "--slotted-text-field-invalid-border-color",
+    "--slotted-text-field-invalid-edge-width",
+    "--slotted-text-field-invalid-focus-ring-color",
+    "--slotted-text-field-placeholder-color",
+    "--slotted-text-field-plain-hover-background",
+    "--slotted-text-field-radius",
+    "--slotted-text-field-readonly-background",
+    "--slotted-text-field-shadow",
+    "--slotted-text-field-subtle-background",
+    "--slotted-text-field-subtle-border-color",
+    "--slotted-text-field-subtle-hover-background",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One control with every axis on it, driven by the controls below the canvas. Type into it: the clear button appears only once there is something to clear.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>E-mail</FieldLabel>\n  <TextField type=\"email\" placeholder=\"voce@empresa.com.br\" clearable />\n  <FieldDescription>Usaremos este endereço para a cobrança.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the control sits at",
+      "note": "Three steps, and inside a field the control takes the field’s rather than its own: a small field holding a medium control is a field and a control disagreeing about one row.",
+      "language": "tsx",
+      "source": "import { Glyph, Icon } from '@slotted/react/icon';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldSizes() {\n  return (\n    <Stack gap={4}>\n      <TextField\n        aria-label=\"Filter order lines\"\n        placeholder=\"Filter order lines\"\n        size=\"sm\"\n        start={\n          <Icon>\n            <Glyph name=\"search\" />\n          </Icon>\n        }\n        type=\"search\"\n      />\n      <TextField\n        aria-label=\"Search customers\"\n        placeholder=\"Search customers\"\n        size=\"md\"\n        start={\n          <Icon>\n            <Glyph name=\"search\" />\n          </Icon>\n        }\n        type=\"search\"\n      />\n      <TextField\n        aria-label=\"Search the catalog\"\n        placeholder=\"Search the catalog\"\n        size=\"lg\"\n        start={\n          <Icon>\n            <Glyph name=\"search\" />\n          </Icon>\n        }\n        type=\"search\"\n      />\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "variants",
+      "title": "How much frame the control shows",
+      "note": "outline takes the ground it is placed on, subtle sinks into the page, and plain shows nothing until the pointer or the caret arrives — which is what a dense table cell needs.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldVariants() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Customer</FieldLabel>\n        <TextField defaultValue=\"Northwind Traders\" variant=\"outline\" />\n      </Field>\n      <Field>\n        <FieldLabel>Purchase order</FieldLabel>\n        <TextField defaultValue=\"PO-2026-0412\" variant=\"subtle\" />\n      </Field>\n      <Field>\n        <FieldLabel>SKU</FieldLabel>\n        <TextField defaultValue=\"NW-TEA-1042\" mono variant=\"plain\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "adornments",
+      "title": "What sits inside the border",
+      "note": "start and end name the reading direction rather than a side, so the currency mark stays before the amount in Arabic as well. Neither of them is ever squeezed: the value gives up width first.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Glyph, Icon } from '@slotted/react/icon';\nimport { Kbd } from '@slotted/react/kbd';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldAdornments() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Unit price</FieldLabel>\n        <TextField defaultValue=\"24.90\" end=\"USD\" inputMode=\"decimal\" start=\"$\" />\n      </Field>\n      <Field>\n        <FieldLabel>Shipping weight</FieldLabel>\n        <TextField defaultValue=\"1.25\" end=\"kg\" inputMode=\"decimal\" />\n      </Field>\n      <Field>\n        <FieldLabel>Storefront address</FieldLabel>\n        <TextField defaultValue=\"shop.northwind.com\" start=\"https://\" />\n      </Field>\n      <TextField\n        aria-label=\"Search orders\"\n        end={<Kbd>/</Kbd>}\n        placeholder=\"Search orders\"\n        start={\n          <Icon>\n            <Glyph name=\"search\" />\n          </Icon>\n        }\n        type=\"search\"\n      />\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "actions",
+      "title": "The two buttons the family draws",
+      "note": "Both are real buttons inside the frame, both keep the caret, and both are held to the 24-pixel minimum. Tab into the field and press Tab again: the ring moves to the button rather than staying around the box.",
+      "language": "tsx",
+      "source": "// Emits onValueChange with reason \"clear\", then focuses the control.\n<TextField clearable defaultValue=\"nota fiscal 2026\" type=\"search\" />;\n\n// aria-pressed carries the state; the label never changes with it.\n<TextField revealable type=\"password\" autoComplete=\"current-password\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "menu",
+      "title": "A button of your own inside the frame",
+      "note": "A country code that opens a menu, a category beside a search, a submit named in words, an overflow mark: each is a real button in start or end. Open one — it stays pressed while its menu is open, and the value keeps its place beside it.",
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Glyph, Icon } from '@slotted/react/icon';\nimport { Menu, MenuContent, MenuRadioGroup, MenuRadioItem, MenuTrigger } from '@slotted/react/menu';\nimport { TextField, TextFieldAction } from '@slotted/react/text-field';\nimport { VisuallyHidden } from '@slotted/react/visually-hidden';\n\nexport default function TextFieldMenu() {\n  const [country, setCountry] = useState('+1');\n\n  return (\n    <Field>\n      <FieldLabel>Phone</FieldLabel>\n      <Menu>\n        <TextField\n          autoComplete=\"tel-national\"\n          defaultValue=\"206 555 0134\"\n          start={\n            <MenuTrigger\n              render={(props) => (\n                <TextFieldAction {...props}>\n                  <VisuallyHidden>Country code</VisuallyHidden>\n                  {country}\n                  <Icon>\n                    <Glyph name=\"chevron-down\" />\n                  </Icon>\n                </TextFieldAction>\n              )}\n            />\n          }\n          type=\"tel\"\n        />\n        <MenuContent>\n          <MenuRadioGroup value={country} onValueChange={setCountry}>\n            <MenuRadioItem value=\"+1\">United States +1</MenuRadioItem>\n            <MenuRadioItem value=\"+44\">United Kingdom +44</MenuRadioItem>\n            <MenuRadioItem value=\"+49\">Germany +49</MenuRadioItem>\n            <MenuRadioItem value=\"+81\">Japan +81</MenuRadioItem>\n          </MenuRadioGroup>\n        </MenuContent>\n      </Menu>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "copy",
+      "title": "Copying a value somebody has to paste elsewhere",
+      "note": "Press the copy button: the mark turns to a check in the success ink for two seconds and the outcome is announced. A clipboard that refuses — an insecure page, a denied permission — is announced as a failure and shows no check.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldCopy() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Invite link</FieldLabel>\n        <TextField copyable defaultValue=\"https://northwind.slotted.app/join/8f3a2c\" readOnly />\n        <FieldDescription>Anyone with the link joins as a viewer.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Webhook signing secret</FieldLabel>\n        <TextField copyable defaultValue=\"whsec_4f9c2a7e1b8d6350\" mono readOnly />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "password",
+      "title": "A password: showing it, and warning about Caps Lock",
+      "note": "Focus the password and turn Caps Lock on: the warning mark appears before the eye and is announced once. The eye swaps to a crossed eye and back, and the caret stays where it was.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Glyph, Icon } from '@slotted/react/icon';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldPassword() {\n  return (\n    <Field required>\n      <FieldLabel>New password</FieldLabel>\n      <TextField\n        autoComplete=\"new-password\"\n        minLength={12}\n        revealable\n        start={\n          <Icon>\n            <Glyph name=\"lock\" />\n          </Icon>\n        }\n        type=\"password\"\n      />\n      <FieldDescription>At least 12 characters.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "loading",
+      "title": "Checking the value while the reader keeps typing",
+      "note": "A user name checked against the server: the ring stands before the buttons and the input is aria-busy, but it stays editable. Toggle loading off and the ring shrinks out rather than vanishing.",
+      "language": "tsx",
+      "source": "import { useEffect, useRef, useState } from 'react';\nimport { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { TextField } from '@slotted/react/text-field';\n\n/** Stands in for the request that checks whether a handle is free. */\nconst TAKEN = new Set(['admin', 'northwind', 'support']);\n\nexport default function TextFieldLoading() {\n  const [handle, setHandle] = useState('northwind-ops');\n  const [checking, setChecking] = useState(false);\n  const [taken, setTaken] = useState(false);\n  const timer = useRef<ReturnType<typeof setTimeout>>(undefined);\n  useEffect(() => () => clearTimeout(timer.current), []);\n\n  const change = (next: string) => {\n    setHandle(next);\n    setTaken(false);\n    clearTimeout(timer.current);\n    setChecking(next !== '');\n    if (next === '') return;\n    timer.current = setTimeout(() => {\n      setChecking(false);\n      setTaken(TAKEN.has(next));\n    }, 900);\n  };\n\n  return (\n    <Field invalid={taken ? true : undefined}>\n      <FieldLabel>Handle</FieldLabel>\n      <TextField\n        autoComplete=\"username\"\n        clearable\n        loading={checking}\n        onValueChange={change}\n        spellCheck={false}\n        start=\"@\"\n        value={handle}\n      />\n      <FieldDescription>Lowercase letters, digits and hyphens.</FieldDescription>\n      <FieldError live=\"polite\" reserve>\n        {taken ? `@${handle} is already taken.` : ''}\n      </FieldError>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "The four states the frame paints",
+      "note": "Read-only keeps full-strength ink and only its ground changes, because the value is real and still submitted; disabled is muted to a measured colour rather than faded, so a disabled form still says what it holds.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldStates() {\n  return (\n    <Stack gap={5}>\n      <Field invalid>\n        <FieldLabel>VAT number</FieldLabel>\n        <TextField defaultValue=\"DE 81234\" />\n        <FieldError>A German VAT number has nine digits after DE.</FieldError>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Order number</FieldLabel>\n        <TextField defaultValue=\"SO-2026-00418\" mono />\n        <FieldDescription>Assigned when the order was placed.</FieldDescription>\n      </Field>\n      <Field disabled>\n        <FieldLabel>Currency</FieldLabel>\n        <TextField defaultValue=\"USD\" />\n        <FieldDescription>Set by the customer’s price list.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "count",
+      "title": "Counting what has been typed",
+      "note": "The control counts and the field places it, in the spare column of the label row. Pass countMax without maxLength and the limit becomes a soft one: the value may pass it, and the counter turns before validation runs.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldCount() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Email subject</FieldLabel>\n        <TextField defaultValue=\"Your order SO-2026-00418 has shipped\" maxLength={60} showCount />\n      </Field>\n      <Field>\n        <FieldLabel>SMS sender name</FieldLabel>\n        <TextField countMax={11} defaultValue=\"Northwind\" showCount />\n        <FieldDescription>Carriers cut sender names after 11 characters.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "types",
+      "title": "What kind of text this is",
+      "note": "type is the element’s own, and so is everything that travels with it. A phone field that offers the wrong keyboard on a phone is a field nobody fills in twice.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldTypes() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Work email</FieldLabel>\n        <TextField autoComplete=\"email\" placeholder=\"name@northwind.com\" type=\"email\" />\n      </Field>\n      <Field>\n        <FieldLabel>Phone</FieldLabel>\n        <TextField autoComplete=\"tel\" placeholder=\"+1 206 555 0134\" type=\"tel\" />\n      </Field>\n      <Field>\n        <FieldLabel>Website</FieldLabel>\n        <TextField autoComplete=\"url\" placeholder=\"https://northwind.com\" type=\"url\" />\n      </Field>\n      <Field>\n        <FieldLabel>ZIP code</FieldLabel>\n        <TextField autoComplete=\"postal-code\" inputMode=\"numeric\" placeholder=\"98101\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A value longer than the control ellipsises rather than clipping mid-glyph; an unbroken token scrolls, which is the platform’s answer; and at 240 pixels the value surrenders width while the adornments keep their target size.",
+      "language": "tsx",
+      "source": "<TextField defaultValue=\"Kraftfahrzeug-Haftpflichtversicherungsnummer-2026\" />;\n\n// Nothing is removed from the DOM: the whole value stays selectable,\n// copyable and reachable with the caret.\n<TextField dir=\"rtl\" defaultValue=\"مرحبا بالعالم\" clearable />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "The provider carries the decisions an application takes once; render substitutes the frame; ref reaches the element, which already has focus, select and setSelectionRange.",
+      "language": "tsx",
+      "source": "<TextFieldDefaultsProvider variant=\"subtle\">\n  <TextField clearable messages={{ clear: 'Limpar' }} />\n</TextFieldDefaultsProvider>;\n\nconst ref = useRef<HTMLInputElement>(null);\n<TextField ref={ref} onFocus={() => ref.current?.select()} />;\n\n// The frame becomes the consumer's own element, with every attribute.\n<TextField render={(props) => <label {...props} />} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and what it deliberately does not",
+      "note": "Tab reaches the value, then each button in turn. Nothing is bound to Escape: some user agents clear a search input on it, and a control that swallowed the key inside a dialog would be one a keyboard user cannot leave.",
+      "language": "tsx",
+      "source": "// Enter submits the form the element belongs to — the platform's\n// behaviour for a single-line control, left alone.\n<form onSubmit={onSubmit}>\n  <TextField name=\"q\" type=\"search\" clearable />\n</form>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "action",
+      "title": "action.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { TextField, TextFieldAction } from '@slotted/react/text-field';\n\nexport default function TextFieldActionExample() {\n  const [applied, setApplied] = useState('');\n\n  const apply = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    const code = new FormData(event.currentTarget).get('code');\n    setApplied(typeof code === 'string' ? code.trim().toUpperCase() : '');\n  };\n\n  return (\n    <form onSubmit={apply}>\n      <Field>\n        <FieldLabel>Discount code</FieldLabel>\n        <TextField\n          autoComplete=\"off\"\n          defaultValue=\"SPRING10\"\n          end={<TextFieldAction type=\"submit\">Apply</TextFieldAction>}\n          mono\n          name=\"code\"\n        />\n        <FieldDescription>\n          {applied === '' ? 'One code per order.' : `${applied} is applied to this order.`}\n        </FieldDescription>\n      </Field>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldBasic() {\n  return (\n    <Field required>\n      <FieldLabel>Company name</FieldLabel>\n      <TextField autoComplete=\"organization\" clearable defaultValue=\"Northwind Traders\" />\n      <FieldDescription>Printed on every invoice and packing slip.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "clearable",
+      "title": "clearable.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Glyph, Icon } from '@slotted/react/icon';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function TextFieldClearable() {\n  return (\n    <TextField\n      aria-label=\"Search invoices\"\n      clearable\n      defaultValue=\"invoice 2026\"\n      enterKeyHint=\"search\"\n      start={\n        <Icon>\n          <Glyph name=\"search\" />\n        </Icon>\n      }\n      type=\"search\"\n    />\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Grid } from '@slotted/react/grid';\nimport { TextField, TextFieldDefaultsProvider } from '@slotted/react/text-field';\n\nexport default function TextFieldDefaults() {\n  return (\n    <TextFieldDefaultsProvider size=\"sm\" variant=\"subtle\">\n      <Grid gap={2} minItemWidth=\"xs\">\n        <TextField aria-label=\"Customer\" clearable placeholder=\"Customer\" />\n        <TextField aria-label=\"Order number\" mono placeholder=\"Order number\" />\n        <TextField aria-label=\"Ship to city\" placeholder=\"Ship to city\" />\n      </Grid>\n    </TextFieldDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nexport default function TextFieldValidation() {\n  const [email, setEmail] = useState('');\n  const [submitted, setSubmitted] = useState(false);\n  const [sent, setSent] = useState(false);\n\n  const error = !submitted\n    ? ''\n    : email.trim() === ''\n      ? 'Enter the address the invoice goes to.'\n      : EMAIL.test(email)\n        ? ''\n        : 'Enter an address in the format name@company.com.';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    setSent(EMAIL.test(email));\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <Field required invalid={error !== '' ? true : undefined}>\n          <FieldLabel>Billing email</FieldLabel>\n          <TextField\n            autoComplete=\"email\"\n            onValueChange={(next) => {\n              setEmail(next);\n              setSent(false);\n            }}\n            type=\"email\"\n            value={email}\n          />\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Send invoice</Button>\n          {sent ? <span role=\"status\">Invoice sent.</span> : null}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}