@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/text-field.json

@@ -0,0 +1,604 @@
+{
+  "family": "text-field",
+  "ui": "text-field",
+  "binding": "angular",
+  "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 {\n  provideTextFieldDefaults,\n  SlTextField,\n  SlTextFieldAction,\n  SlTextFieldEnd,\n  SlTextFieldInput,\n  SlTextFieldStart,\n} from '@slotted/angular/text-field';",
+        "selector": "[slTextField]",
+        "exportAs": "slTextField"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slTextField",
+          "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."
+        },
+        {
+          "part": "input",
+          "element": "input[slTextFieldInput]",
+          "required": true,
+          "purpose": "The control. It holds the value and the identifier, and keeps every native attribute you write: type, autocomplete, inputmode, enterkeyhint, pattern, maxlength, name and required. Each is read before the host bindings compute, so none is overwritten. It is a ControlValueAccessor, so a reactive or template-driven form binds to it directly."
+        },
+        {
+          "part": "start",
+          "element": "any element carrying slTextFieldStart",
+          "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": "any element carrying slTextFieldEnd",
+          "required": false,
+          "purpose": "Content after the value in the reading direction, such as a unit, a domain or a suffix."
+        },
+        {
+          "part": "action",
+          "element": "button[slTextFieldAction], inside slTextFieldStart or slTextFieldEnd",
+          "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 its menu is open. slMenuTriggerFor can sit on the same element."
+        },
+        {
+          "part": "busy",
+          "element": "span[data-ui=\"spinner\"], rendered by the frame",
+          "required": false,
+          "purpose": "The shared spinner, before the buttons, while [loading] is true. It is rendered whenever loading is bound 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, rendered by the frame",
+          "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, rendered by the frame",
+          "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, rendered by the frame",
+          "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, rendered by the frame",
+          "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": "slTextFieldInput",
+          "description": "Makes the value controlled. It is written to the input the way a form control’s value is. Without it the input keeps its own value."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slTextFieldInput",
+          "description": "The value the input starts from when nothing else writes one. It is read once the inputs are bound."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slTextField, provideTextFieldDefaults",
+          "description": "The step of the control scale. Without it the text field takes the size of the field around it, then the one provideTextFieldDefaults sets. 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": "slTextField, provideTextFieldDefaults",
+          "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": "slTextField, provideTextFieldDefaults",
+          "description": "Sets the value in the monospaced font with tabular figures, for identifiers, hashes and keys."
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextField",
+          "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": "slTextField",
+          "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": "revealed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slTextFieldInput",
+          "description": "Makes the password toggle controlled. defaultRevealed sets the uncontrolled starting state."
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextFieldInput",
+          "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": "slTextFieldInput",
+          "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": "slTextFieldStart",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "Content before the value in the reading direction, on your own element, which keeps its own semantics."
+        },
+        {
+          "name": "end",
+          "type": "slTextFieldEnd",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "Content after the value in the reading direction."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextFieldInput",
+          "description": "Unset by default, so the input takes the state of the field around it and of a disabled form control. When set, it wins, and it is the native attribute."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextFieldInput",
+          "description": "Unset by default, so the input takes the state of the field around it. It is the native readonly: the input stays focusable and selectable, and its value is submitted. A static readonly attribute you write is read before the binding computes."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "slTextFieldInput",
+          "description": "Unset by default, so the input 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": "the input element",
+          "description": "The input’s own attribute; slTextFieldInput 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": "the input element",
+          "description": "The input’s own type, written as a static attribute. It is read before the host binding computes, so the reveal toggle can swap it and restore what you wrote."
+        },
+        {
+          "name": "copyable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slTextField",
+          "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": "slTextField",
+          "description": "Draws the shared spinner before the buttons and sets aria-busy on the input; the value stays editable. Once loading is bound, false included, the spinner keeps its place so it can leave with a transition."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<TextFieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slTextField",
+          "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": "button[slTextFieldAction]",
+          "type": "directive",
+          "defaultValue": "type=\"button\"",
+          "appliesTo": "inside slTextFieldStart or slTextFieldEnd",
+          "description": "A button you place inside the frame. slMenuTriggerFor, slTooltipTrigger or a popover trigger can sit on the same element. The part attribute is written back after the first render, because slMenuTriggerFor binds data-part to null. Its exportAs is slTextFieldAction."
+        },
+        {
+          "name": "the directives themselves",
+          "type": "slTextField, slTextFieldInput, slTextFieldStart, slTextFieldEnd",
+          "defaultValue": "—",
+          "appliesTo": "your own elements",
+          "description": "Every part except the buttons and marks the frame renders is a directive on an element you write, so each keeps its own semantics, attributes and listeners."
+        },
+        {
+          "name": "exportAs",
+          "type": "'slTextField' / 'slTextFieldInput'",
+          "defaultValue": "—",
+          "appliesTo": "a template",
+          "description": "Reaches the instance from a template. inputElement on slTextFieldInput is the native input, with focus(), select() and setSelectionRange()."
+        },
+        {
+          "name": "provideTextFieldDefaults()",
+          "type": "{ size, variant, mono }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets size, variant and mono once for every text field in the injector. A field outranks it for size, so a text field inside a field takes the field’s size."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "type": "formControl, formControlName, ngModel",
+          "defaultValue": "—",
+          "appliesTo": "slTextFieldInput",
+          "description": "slTextFieldInput works with reactive and template-driven forms as it is. It provides no validator: the form owns validity."
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<string>",
+          "when": "Emitted by slTextFieldInput 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": "(revealedChange)",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Emitted by slTextFieldInput before the password toggle changes, with reason \"pointer\" or \"keyboard\" read from the click. A form that hides the password again on blur binds [revealed] and listens here."
+        },
+        {
+          "name": "(valueCopy)",
+          "payload": "TextFieldCopyDetail — { copied, reason, source, value }",
+          "when": "Emitted by slTextField after the copy button has asked the clipboard. copied is false when the clipboard refused the value, and reason is \"pointer\" or \"keyboard\"."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "payload": "the form’s own value and touched state",
+          "when": "The form receives the value whenever it changes and the request was not cancelled, and the touched state on blur. There is no [(value)], because a two-way binding carries only the value, neither the reason nor cancel()."
+        }
+      ],
+      "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. In Angular a host binding overrides a static attribute, so every attribute you write that slTextFieldInput also binds (id, aria-describedby, aria-invalid, aria-required, readonly and type) is read before the binding computes and is never overwritten.",
+        "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/). slMenuTriggerFor 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."
+      ]
+    }
+  },
+  "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": "html",
+      "source": "<div slField>\n  <label slFieldLabel>E-mail</label>\n  <div slTextField clearable>\n    <input slTextFieldInput type=\"email\" placeholder=\"voce@empresa.com.br\" />\n  </div>\n  <span slFieldDescription>Usaremos este endereço para a cobrança.</span>\n</div>\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlGlyph, SlIcon } from '@slotted/angular/icon';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput, SlTextFieldStart } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-sizes',\n  imports: [SlGlyph, SlIcon, SlStack, SlTextField, SlTextFieldInput, SlTextFieldStart],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slTextField size=\"sm\">\n        <span slTextFieldStart>\n          <span slIcon><svg slGlyph name=\"search\"></svg></span>\n        </span>\n        <input\n          slTextFieldInput\n          type=\"search\"\n          aria-label=\"Filter order lines\"\n          placeholder=\"Filter order lines\"\n        />\n      </div>\n      <div slTextField size=\"md\">\n        <span slTextFieldStart>\n          <span slIcon><svg slGlyph name=\"search\"></svg></span>\n        </span>\n        <input\n          slTextFieldInput\n          type=\"search\"\n          aria-label=\"Search customers\"\n          placeholder=\"Search customers\"\n        />\n      </div>\n      <div slTextField size=\"lg\">\n        <span slTextFieldStart>\n          <span slIcon><svg slGlyph name=\"search\"></svg></span>\n        </span>\n        <input\n          slTextFieldInput\n          type=\"search\"\n          aria-label=\"Search the catalog\"\n          placeholder=\"Search the catalog\"\n        />\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldSizes {}\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-variants',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slField>\n        <label slFieldLabel>Customer</label>\n        <div slTextField variant=\"outline\">\n          <input slTextFieldInput defaultValue=\"Northwind Traders\" />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Purchase order</label>\n        <div slTextField variant=\"subtle\">\n          <input slTextFieldInput defaultValue=\"PO-2026-0412\" />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>SKU</label>\n        <div slTextField variant=\"plain\" mono>\n          <input slTextFieldInput defaultValue=\"NW-TEA-1042\" />\n        </div>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldVariants {}\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlGlyph, SlIcon } from '@slotted/angular/icon';\nimport { SlKbd } from '@slotted/angular/kbd';\nimport { SlStack } from '@slotted/angular/stack';\nimport {\n  SlTextField,\n  SlTextFieldEnd,\n  SlTextFieldInput,\n  SlTextFieldStart,\n} from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-adornments',\n  imports: [\n    SlField,\n    SlFieldLabel,\n    SlGlyph,\n    SlIcon,\n    SlKbd,\n    SlStack,\n    SlTextField,\n    SlTextFieldEnd,\n    SlTextFieldInput,\n    SlTextFieldStart,\n  ],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slField>\n        <label slFieldLabel>Unit price</label>\n        <div slTextField>\n          <span slTextFieldStart>$</span>\n          <input slTextFieldInput inputmode=\"decimal\" defaultValue=\"24.90\" />\n          <span slTextFieldEnd>USD</span>\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Shipping weight</label>\n        <div slTextField>\n          <input slTextFieldInput inputmode=\"decimal\" defaultValue=\"1.25\" />\n          <span slTextFieldEnd>kg</span>\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Storefront address</label>\n        <div slTextField>\n          <span slTextFieldStart>https://</span>\n          <input slTextFieldInput defaultValue=\"shop.northwind.com\" />\n        </div>\n      </div>\n      <div slTextField>\n        <span slTextFieldStart>\n          <span slIcon><svg slGlyph name=\"search\"></svg></span>\n        </span>\n        <input\n          slTextFieldInput\n          type=\"search\"\n          aria-label=\"Search orders\"\n          placeholder=\"Search orders\"\n        />\n        <span slTextFieldEnd><kbd slKbd>/</kbd></span>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldAdornments {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "actions",
+      "title": "The two buttons the frame 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": "html",
+      "source": "<div slTextField clearable>\n  <input slTextFieldInput type=\"search\" defaultValue=\"nota fiscal 2026\" />\n</div>\n\n<div slTextField revealable>\n  <input slTextFieldInput type=\"password\" autocomplete=\"current-password\" />\n</div>\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": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlGlyph, SlIcon } from '@slotted/angular/icon';\nimport { SlMenu, SlMenuItem, SlMenuRadioGroup, SlMenuTrigger } from '@slotted/angular/menu';\nimport {\n  SlTextField,\n  SlTextFieldAction,\n  SlTextFieldInput,\n  SlTextFieldStart,\n} from '@slotted/angular/text-field';\nimport { SlVisuallyHidden } from '@slotted/angular/visually-hidden';\n\n@Component({\n  selector: 'app-text-field-menu',\n  imports: [\n    SlField,\n    SlFieldLabel,\n    SlGlyph,\n    SlIcon,\n    SlMenu,\n    SlMenuItem,\n    SlMenuRadioGroup,\n    SlMenuTrigger,\n    SlTextField,\n    SlTextFieldAction,\n    SlTextFieldInput,\n    SlTextFieldStart,\n    SlVisuallyHidden,\n  ],\n  template: `\n    <div slField>\n      <label slFieldLabel>Phone</label>\n      <div slTextField>\n        <span slTextFieldStart>\n          <button slTextFieldAction [slMenuTriggerFor]=\"countries\">\n            <span slVisuallyHidden>Country code</span>{{ country() }}\n            <span slIcon><svg slGlyph name=\"chevron-down\"></svg></span>\n          </button>\n        </span>\n        <input\n          slTextFieldInput\n          type=\"tel\"\n          autocomplete=\"tel-national\"\n          defaultValue=\"206 555 0134\"\n        />\n      </div>\n      <sl-menu #countries>\n        <sl-menu-radio-group [(value)]=\"country\">\n          <button slMenuRadioItem value=\"+1\">United States +1</button>\n          <button slMenuRadioItem value=\"+44\">United Kingdom +44</button>\n          <button slMenuRadioItem value=\"+49\">Germany +49</button>\n          <button slMenuRadioItem value=\"+81\">Japan +81</button>\n        </sl-menu-radio-group>\n      </sl-menu>\n    </div>\n  `,\n})\nexport class TextFieldMenu {\n  protected readonly country = signal('+1');\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-copy',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Invite link</label>\n        <div slTextField copyable>\n          <input\n            slTextFieldInput\n            readonly\n            defaultValue=\"https://northwind.slotted.app/join/8f3a2c\"\n          />\n        </div>\n        <span slFieldDescription>Anyone with the link joins as a viewer.</span>\n      </div>\n      <div slField>\n        <label slFieldLabel>Webhook signing secret</label>\n        <div slTextField copyable mono>\n          <input slTextFieldInput readonly defaultValue=\"whsec_4f9c2a7e1b8d6350\" />\n        </div>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldCopy {}\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlGlyph, SlIcon } from '@slotted/angular/icon';\nimport { SlTextField, SlTextFieldInput, SlTextFieldStart } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-password',\n  imports: [\n    SlField,\n    SlFieldDescription,\n    SlFieldLabel,\n    SlGlyph,\n    SlIcon,\n    SlTextField,\n    SlTextFieldInput,\n    SlTextFieldStart,\n  ],\n  template: `\n    <div slField required>\n      <label slFieldLabel>New password</label>\n      <div slTextField revealable>\n        <span slTextFieldStart>\n          <span slIcon><svg slGlyph name=\"lock\"></svg></span>\n        </span>\n        <input slTextFieldInput type=\"password\" autocomplete=\"new-password\" minlength=\"12\" />\n      </div>\n      <span slFieldDescription>At least 12 characters.</span>\n    </div>\n  `,\n})\nexport class TextFieldPassword {}\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. Turn loading off and the ring shrinks out rather than vanishing.",
+      "language": "ts",
+      "source": "import { Component, DestroyRef, inject, signal } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextField, SlTextFieldInput, SlTextFieldStart } from '@slotted/angular/text-field';\n\n/** Stands in for the request that checks whether a handle is free. */\nconst TAKEN = new Set(['admin', 'northwind', 'support']);\n\n@Component({\n  selector: 'app-text-field-loading',\n  imports: [\n    SlField,\n    SlFieldDescription,\n    SlFieldError,\n    SlFieldLabel,\n    SlTextField,\n    SlTextFieldInput,\n    SlTextFieldStart,\n  ],\n  template: `\n    <div slField [invalid]=\"taken() ? true : undefined\">\n      <label slFieldLabel>Handle</label>\n      <div slTextField clearable [loading]=\"checking()\">\n        <span slTextFieldStart>&#64;</span>\n        <input\n          slTextFieldInput\n          autocomplete=\"username\"\n          spellcheck=\"false\"\n          [value]=\"handle()\"\n          (valueChange)=\"change($event.value)\"\n        />\n      </div>\n      <span slFieldDescription>Lowercase letters, digits and hyphens.</span>\n      <span slFieldError live=\"polite\" reserve>\n        {{ taken() ? '@' + handle() + ' is already taken.' : '' }}\n      </span>\n    </div>\n  `,\n})\nexport class TextFieldLoading {\n  protected readonly handle = signal('northwind-ops');\n  protected readonly checking = signal(false);\n  protected readonly taken = signal(false);\n  private timer: ReturnType<typeof setTimeout> | undefined;\n\n  constructor() {\n    inject(DestroyRef).onDestroy(() => clearTimeout(this.timer));\n  }\n\n  protected change(next: string) {\n    this.handle.set(next);\n    this.taken.set(false);\n    clearTimeout(this.timer);\n    this.checking.set(next !== '');\n    if (next === '') return;\n    this.timer = setTimeout(() => {\n      this.checking.set(false);\n      this.taken.set(TAKEN.has(next));\n    }, 900);\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-states',\n  imports: [\n    SlField,\n    SlFieldDescription,\n    SlFieldError,\n    SlFieldLabel,\n    SlStack,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField invalid>\n        <label slFieldLabel>VAT number</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"DE 81234\" /></div>\n        <span slFieldError>A German VAT number has nine digits after DE.</span>\n      </div>\n      <div slField readOnly>\n        <label slFieldLabel>Order number</label>\n        <div slTextField mono><input slTextFieldInput defaultValue=\"SO-2026-00418\" /></div>\n        <span slFieldDescription>Assigned when the order was placed.</span>\n      </div>\n      <div slField disabled>\n        <label slFieldLabel>Currency</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"USD\" /></div>\n        <span slFieldDescription>Set by the customer’s price list.</span>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldStates {}\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-count',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Email subject</label>\n        <div slTextField>\n          <input\n            slTextFieldInput\n            showCount\n            maxlength=\"60\"\n            defaultValue=\"Your order SO-2026-00418 has shipped\"\n          />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>SMS sender name</label>\n        <div slTextField>\n          <input slTextFieldInput showCount countMax=\"11\" defaultValue=\"Northwind\" />\n        </div>\n        <span slFieldDescription>Carriers cut sender names after 11 characters.</span>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldCount {}\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": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-types',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slField>\n        <label slFieldLabel>Work email</label>\n        <div slTextField>\n          <input\n            slTextFieldInput\n            type=\"email\"\n            autocomplete=\"email\"\n            placeholder=\"name@northwind.com\"\n          />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Phone</label>\n        <div slTextField>\n          <input slTextFieldInput type=\"tel\" autocomplete=\"tel\" placeholder=\"+1 206 555 0134\" />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Website</label>\n        <div slTextField>\n          <input\n            slTextFieldInput\n            type=\"url\"\n            autocomplete=\"url\"\n            placeholder=\"https://northwind.com\"\n          />\n        </div>\n      </div>\n      <div slField>\n        <label slFieldLabel>ZIP code</label>\n        <div slTextField>\n          <input\n            slTextFieldInput\n            autocomplete=\"postal-code\"\n            inputmode=\"numeric\"\n            placeholder=\"98101\"\n          />\n        </div>\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldTypes {}\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": "html",
+      "source": "<div slTextField>\n  <input slTextFieldInput defaultValue=\"Kraftfahrzeug-Haftpflichtversicherungsnummer\" />\n</div>\n\n<!-- Nothing is removed from the DOM: the whole value stays selectable. -->\n<div slTextField clearable>\n  <input slTextFieldInput dir=\"rtl\" defaultValue=\"مرحبا بالعالم\" />\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "provideTextFieldDefaults carries the decisions an application takes once; exportAs reaches the instance, and inputElement is the native element with focus, select and setSelectionRange already on it.",
+      "language": "html",
+      "source": "<!-- ControlValueAccessor: the control belongs in a form as it stands. -->\n<div slTextField clearable>\n  <input slTextFieldInput [formControl]=\"email\" type=\"email\" />\n</div>\n\n<!-- exportAs, for the element the template has to reach. -->\n<div slTextField>\n  <input slTextFieldInput #campo=\"slTextFieldInput\" />\n  <span slTextFieldEnd>\n    <button slTextFieldAction (click)=\"campo.inputElement.select()\">Selecionar</button>\n  </span>\n</div>\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": "html",
+      "source": "<form (ngSubmit)=\"buscar()\">\n  <div slTextField clearable>\n    <input slTextFieldInput type=\"search\" name=\"q\" [(ngModel)]=\"q\" />\n  </div>\n</form>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "action",
+      "title": "action.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport {\n  SlTextField,\n  SlTextFieldAction,\n  SlTextFieldEnd,\n  SlTextFieldInput,\n} from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-action',\n  imports: [\n    SlField,\n    SlFieldDescription,\n    SlFieldLabel,\n    SlTextField,\n    SlTextFieldAction,\n    SlTextFieldEnd,\n    SlTextFieldInput,\n  ],\n  template: `\n    <form (submit)=\"apply($event)\">\n      <div slField>\n        <label slFieldLabel>Discount code</label>\n        <div slTextField mono>\n          <input slTextFieldInput name=\"code\" autocomplete=\"off\" defaultValue=\"SPRING10\" />\n          <span slTextFieldEnd><button slTextFieldAction type=\"submit\">Apply</button></span>\n        </div>\n        <span slFieldDescription>\n          {{ applied() === '' ? 'One code per order.' : applied() + ' is applied to this order.' }}\n        </span>\n      </div>\n    </form>\n  `,\n})\nexport class TextFieldActionExample {\n  protected readonly applied = signal('');\n\n  protected apply(event: SubmitEvent) {\n    event.preventDefault();\n    const code = new FormData(event.target as HTMLFormElement).get('code');\n    this.applied.set(typeof code === 'string' ? code.trim().toUpperCase() : '');\n  }\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "basic",
+      "title": "basic.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-basic',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextField, SlTextFieldInput],\n  template: `\n    <div slField required>\n      <label slFieldLabel>Company name</label>\n      <div slTextField clearable>\n        <input slTextFieldInput autocomplete=\"organization\" defaultValue=\"Northwind Traders\" />\n      </div>\n      <span slFieldDescription>Printed on every invoice and packing slip.</span>\n    </div>\n  `,\n})\nexport class TextFieldBasic {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "clearable",
+      "title": "clearable.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlGlyph, SlIcon } from '@slotted/angular/icon';\nimport { SlTextField, SlTextFieldInput, SlTextFieldStart } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-clearable',\n  imports: [SlGlyph, SlIcon, SlTextField, SlTextFieldInput, SlTextFieldStart],\n  template: `\n    <div slTextField clearable>\n      <span slTextFieldStart>\n        <span slIcon><svg slGlyph name=\"search\"></svg></span>\n      </span>\n      <input\n        slTextFieldInput\n        type=\"search\"\n        aria-label=\"Search invoices\"\n        enterkeyhint=\"search\"\n        defaultValue=\"invoice 2026\"\n      />\n    </div>\n  `,\n})\nexport class TextFieldClearable {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlGrid } from '@slotted/angular/grid';\nimport {\n  provideTextFieldDefaults,\n  SlTextField,\n  SlTextFieldInput,\n} from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-text-field-defaults',\n  imports: [SlGrid, SlTextField, SlTextFieldInput],\n  providers: [provideTextFieldDefaults({ size: 'sm', variant: 'subtle' })],\n  template: `\n    <div slGrid [gap]=\"2\" minItemWidth=\"xs\">\n      <div slTextField clearable>\n        <input slTextFieldInput aria-label=\"Customer\" placeholder=\"Customer\" />\n      </div>\n      <div slTextField mono>\n        <input slTextFieldInput aria-label=\"Order number\" placeholder=\"Order number\" />\n      </div>\n      <div slTextField>\n        <input slTextFieldInput aria-label=\"Ship to city\" placeholder=\"Ship to city\" />\n      </div>\n    </div>\n  `,\n})\nexport class TextFieldDefaults {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport { toSignal } from '@angular/core/rxjs-interop';\nimport { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\n@Component({\n  selector: 'app-text-field-validation',\n  imports: [\n    ReactiveFormsModule,\n    SlButton,\n    SlField,\n    SlFieldError,\n    SlFieldLabel,\n    SlInline,\n    SlStack,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <form novalidate (submit)=\"submit($event)\">\n      <div slStack [gap]=\"4\">\n        <div slField required [invalid]=\"error() !== '' ? true : undefined\">\n          <label slFieldLabel>Billing email</label>\n          <div slTextField>\n            <input\n              slTextFieldInput\n              type=\"email\"\n              autocomplete=\"email\"\n              [formControl]=\"email\"\n              (valueChange)=\"sent.set(false)\"\n            />\n          </div>\n          <span slFieldError live=\"polite\" reserve>{{ error() }}</span>\n        </div>\n        <div slInline [gap]=\"3\" align=\"center\">\n          <button slButton type=\"submit\">Send invoice</button>\n          @if (sent()) {\n            <span role=\"status\">Invoice sent.</span>\n          }\n        </div>\n      </div>\n    </form>\n  `,\n})\nexport class TextFieldValidation {\n  readonly email = new FormControl('', {\n    nonNullable: true,\n    validators: [Validators.required, Validators.pattern(EMAIL)],\n  });\n  readonly value = toSignal(this.email.valueChanges, { initialValue: this.email.value });\n  readonly submitted = signal(false);\n  readonly sent = signal(false);\n  readonly error = computed(() => {\n    if (!this.submitted()) return '';\n    if (this.value().trim() === '') return 'Enter the address the invoice goes to.';\n    return EMAIL.test(this.value()) ? '' : 'Enter an address in the format name@company.com.';\n  });\n\n  submit(event: Event): void {\n    event.preventDefault();\n    this.submitted.set(true);\n    this.sent.set(this.email.valid);\n  }\n}\n",
+      "verdict": "example"
+    }
+  ]
+}