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

package/docs/field.json

@@ -0,0 +1,528 @@
+{
+  "family": "field",
+  "ui": "field",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Label, control, help and error for one input."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "labelPlacement": [
+      "top",
+      "side"
+    ],
+    "necessity": [
+      "mark",
+      "optional",
+      "words",
+      "none"
+    ]
+  },
+  "members": {
+    "field": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "labelPlacement": "top",
+        "necessity": "mark"
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "placement",
+        "live",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "open",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "required",
+        "readonly",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "header",
+        "label",
+        "mark",
+        "help",
+        "indicator",
+        "action",
+        "counter",
+        "control"
+      ]
+    }
+  },
+  "docs": {
+    "field": {
+      "imports": {
+        "source": "import {\n  provideFieldDefaults,\n  SlField,\n  SlFieldAction,\n  SlFieldControl,\n  SlFieldCounter,\n  SlFieldDescription,\n  SlFieldError,\n  SlFieldHeader,\n  SlFieldHelp,\n  SlFieldIndicator,\n  SlFieldLabel,\n} from '@slotted/angular/field';",
+        "selector": "[slField]",
+        "exportAs": "slField"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slField, a div",
+          "required": true,
+          "purpose": "The field. It carries data-ui=\"field\", the three axes, and data-disabled, data-invalid, data-required and data-readonly. It is its own size container, so a side label reflows on the field’s width rather than the window’s."
+        },
+        {
+          "part": "header",
+          "element": "the element carrying slFieldHeader, a div",
+          "required": false,
+          "purpose": "The label row, written when the label has company: the help, an indicator, an action and the counter. It aligns them on the label’s first baseline, wraps when it runs out of room, and puts the action and the count at its end. When the page writes no counter, it draws the count the control published. A field whose label stands alone writes the label on the root and no header."
+        },
+        {
+          "part": "label",
+          "element": "label[slFieldLabel]",
+          "required": false,
+          "purpose": "Names the control through for, which points at the derived control identifier. The WAI-ARIA Authoring Practices name the explicit association as the one with the broadest support; some assistive technologies fail to treat the implicit one, a label wrapping its control, as a name."
+        },
+        {
+          "part": "mark",
+          "element": "span, drawn inside the label",
+          "required": false,
+          "purpose": "The necessity marker the label draws: an asterisk on a required field, (optional) on a field a reader may skip, or both words. The asterisk is aria-hidden because aria-required already states the fact; the words are read, because they carry information."
+        },
+        {
+          "part": "help",
+          "element": "button[slFieldHelp]",
+          "required": false,
+          "purpose": "A circle-question button beside the label that shows the directive’s value in a tooltip. It opens on hover and on keyboard focus, and a press keeps it open until a second press, Escape or a press elsewhere. SlTooltip and SlTooltipTrigger are composed on the button as host directives. A hidden node inside the button carries the same words, so the button and the control are described by the help whether the tooltip is open or not."
+        },
+        {
+          "part": "indicator",
+          "element": "the element carrying slFieldIndicator, a span",
+          "required": false,
+          "purpose": "What qualifies the field, such as Beta, Pro or New, as one or more slBadge elements after the label. It sits outside the label, so the necessity mark stays against the last word, and it joins the control’s description, so a reader on the control hears it."
+        },
+        {
+          "part": "action",
+          "element": "the a or button carrying slFieldAction",
+          "required": false,
+          "purpose": "A link or a button at the end of the label row, such as Forgot password? or Generate. On a button the directive writes type=\"button\" unless the page wrote a type; on a link it writes none. The field does not disable it with the control."
+        },
+        {
+          "part": "control",
+          "element": "the element carrying slFieldControl",
+          "required": false,
+          "purpose": "A control Slotted does not ship. Slotted’s own controls inject SlField and need no directive. The field gives the control an identifier, a description, aria-invalid, aria-required, disabled and readonly, and overwrites nothing the consumer wrote: each written value is read with HostAttributeToken before the binding is computed."
+        },
+        {
+          "part": "counter",
+          "element": "the element carrying slFieldCounter",
+          "required": false,
+          "purpose": "The count, at the end of the label row, where IBM Carbon also places it, and inside the header when there is one. A control with showCount publishes its count and the field draws it; a page that counts words or bytes writes its own slFieldCounter. The count joins the control’s description and carries its own data-invalid, because a count can pass its limit before validation runs."
+        }
+      ],
+      "api": [
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slField",
+          "description": "The type step, matching the control the field wraps. The label, the messages and the counter read the control type scale, which the theme restates per density."
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'top' | 'side'",
+          "defaultValue": "top",
+          "appliesTo": "slField",
+          "description": "Where the label sits. side reflows to top when the field’s own inline size is below 320 pixels; the query is a container query, not a viewport query."
+        },
+        {
+          "name": "necessity",
+          "type": "'mark' | 'optional' | 'words' | 'none'",
+          "defaultValue": "mark",
+          "appliesTo": "slField",
+          "description": "How necessity is written: an asterisk on a required field, (optional) on a field a reader may skip, both words, or nothing, for a form that says once that every field is required."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<FieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slField",
+          "description": "Words that replace the active language’s, key by key: the necessity words (optional, required) and the help button’s name (help)."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slField",
+          "description": "Unset rather than false. Reaches the control as aria-required, never as the native required, which would turn on browser constraint validation and change how the form submits."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slField, slFieldCounter",
+          "description": "On slField: unset rather than false; writes aria-invalid on the control and data-invalid on the field, and leaves the label’s colour unchanged. On slFieldCounter: the count has passed its limit, which can happen before validation runs, so it is the counter’s own state and defaults to false."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the group, then the token",
+          "appliesTo": "slField, provideFieldDefaults",
+          "description": "Unset rather than false, so a field follows the slFieldGroup around it. A stated value wins, and it reaches the control as the native attribute."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the group, then the token",
+          "appliesTo": "slField, provideFieldDefaults",
+          "description": "Unset rather than false. Reaches the control as the native readonly, which keeps the value focusable and copyable."
+        },
+        {
+          "name": "id",
+          "type": "string",
+          "defaultValue": "generated",
+          "appliesTo": "slField",
+          "description": "A static attribute, read with HostAttributeToken, that is the base of <id>-control, <id>-label, <id>-indicator, <id>-help, <id>-description, <id>-counter and <id>-error. When unset, an application-scoped factory generates it, so two applications in one server process do not collide."
+        },
+        {
+          "name": "slFieldHelp",
+          "type": "string",
+          "defaultValue": "''",
+          "appliesTo": "button[slFieldHelp]",
+          "description": "The help text, written once as the directive’s value. It reaches the tooltip and the hidden node that describes the button and the control."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "button[slFieldHelp]",
+          "description": "Whether the hint is showing. It is the composed SlTooltip’s model, exposed on the button, so [(open)] binds it both ways."
+        },
+        {
+          "name": "side",
+          "type": "'top' | 'bottom' | 'inline-start' | 'inline-end' | 'left' | 'right'",
+          "defaultValue": "top",
+          "appliesTo": "button[slFieldHelp]",
+          "description": "Where the hint opens. It flips to the opposite side when there is no room."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "messages.help",
+          "appliesTo": "button[slFieldHelp]",
+          "description": "The accessible name of the help button, read with HostAttributeToken. Unset, it is the field’s help message; written, it applies to this button alone."
+        },
+        {
+          "name": "type",
+          "type": "'button' | 'submit' | 'reset'",
+          "defaultValue": "button on a button",
+          "appliesTo": "[slFieldAction]",
+          "description": "Written on a button that states no type, so the action never submits the form it sits in. A link gets none."
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary on slFieldDescription, danger on slFieldError",
+          "appliesTo": "slFieldDescription, slFieldError",
+          "description": "Both messages are inline-message roots and take its five tones, so a warning that does not block submission is slFieldError with tone=\"warning\"."
+        },
+        {
+          "name": "mark",
+          "type": "'glyph' | 'dot' | 'none'",
+          "defaultValue": "none",
+          "appliesTo": "slFieldDescription, slFieldError",
+          "description": "The mark the message draws. A field’s messages draw none by default: an icon repeated under every control of a form reads as texture, and the ink and the sentence already state the tone. glyph draws the tone’s icon at the text size, and dot draws one neutral bullet."
+        },
+        {
+          "name": "live",
+          "type": "'off' | 'polite' | 'assertive'",
+          "defaultValue": "off",
+          "appliesTo": "slFieldDescription, slFieldError",
+          "description": "Whether the message announces itself. off by default, because a message present when the page loads is not announced whatever role it carries."
+        },
+        {
+          "name": "reserve",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slFieldDescription, slFieldError",
+          "description": "Keeps one line open whether or not there is a message, so a form that renders its error unconditionally does not move when the error appears."
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs=\"slFieldHelp\"",
+          "type": "SlFieldHelp",
+          "defaultValue": "—",
+          "appliesTo": "button[slFieldHelp]",
+          "description": "Hands the template the help button. Its state is the composed tooltip’s, bound through [(open)] and (openChangeRequest) rather than through a method."
+        },
+        {
+          "name": "exportAs=\"slField\"",
+          "type": "SlField",
+          "defaultValue": "—",
+          "appliesTo": "slField",
+          "description": "Hands the template the field instance, so a page can point its own element at ids().control, ids().description or ids().error without inventing an identifier, and read count() to draw a count of its own."
+        },
+        {
+          "name": "slFieldControl",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "any control element",
+          "description": "Wires a control Slotted does not ship, on the consumer’s own element. Slotted’s own controls inject SlField themselves and need no directive, so their wiring cannot be written wrong."
+        },
+        {
+          "name": "provideFieldDefaults()",
+          "type": "{ size, labelPlacement, necessity, disabled, readOnly }",
+          "defaultValue": "—",
+          "appliesTo": "an application, a route or a component",
+          "description": "The five decisions an application takes once for every field under the provider. slFieldGroup answers the same source for its own subtree, so a compact or disabled section is one attribute instead of one per field."
+        },
+        {
+          "name": "ng-content",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "slField",
+          "description": "The label or the header, the counter and the two message directives are selected by name; everything else, the control and anything beside it, is projected as written. slFieldHeader projects its content in the order the page wrote it."
+        }
+      ],
+      "events": [
+        {
+          "name": "(openChange)",
+          "payload": "boolean",
+          "when": "On button[slFieldHelp], after the hint opened or closed. It is the output half of [(open)]."
+        },
+        {
+          "name": "(openChangeRequest)",
+          "payload": "ChangeRequest<boolean>",
+          "when": "On button[slFieldHelp], before the hint opens or closes, once per transition. reason is pointer for a hover or a press; keyboard for focus, Enter or Space; or escape, blur or programmatic. cancel() refuses the change."
+        }
+      ],
+      "accessibility": [
+        "No WAI-ARIA Authoring Practices pattern covers a field. Four sources cover it together: the Authoring Practices’ Providing Accessible Names and Descriptions practice (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for the label and the description, the HTML specification for label[for] and fieldset[disabled], and WCAG 2.2 Understanding 3.3.1 Error Identification and 3.3.2 Labels or Instructions for the error and the help.",
+        "The label is associated explicitly. The naming practice records that some combinations of assistive technology and browser do not treat the implicit form, a label wrapping its control, as an accessible name, so the field derives an identifier and points for at it instead of nesting.",
+        "slField writes aria-required, never the native required. The native attribute turns on browser constraint validation and changes how the form submits, which describing a field must not do as a side effect. To get it, write required on the control: every written attribute is read with HostAttributeToken before the binding that would replace it. disabled and readonly are native, because taking a control out of the tab order and out of submission is what those attributes mean.",
+        "The accessible description is the indicator, the help, the description, the count and the error, in that order, whatever order the page writes them in. Each slot has one correct reading order, so the field states it instead of reading it from the DOM. The count is included so a counter is related to its control by identifier.",
+        "The help, the indicator and the action stand beside the label, never inside it. HTML forbids labelable content such as a button inside a label other than the control it labels, and a press on it would reach the label and move focus to the control instead of opening the hint.",
+        "The help is a toggletip. A tooltip alone opens on a touch screen only on a long press, because a tap triggers the element’s own action; the help button has no other action, so a press opens the hint and a second press closes it. The help text also sits in a hidden node inside the button, which describes the button and the control while the tooltip is closed, because a hidden element referenced directly still enters the description. The tooltip describes nothing, so the hint is never read twice.",
+        "A disabled field leaves its help and its action operable, because the help often explains why the field is disabled.",
+        "The necessity asterisk is hidden from assistive technology and the necessity words are not. A reader working through a form of twenty required fields does not need to hear “asterisk” twenty times, and aria-required already states the fact; (optional) is information no other attribute supplies.",
+        "The error is text in the page, as WCAG 2.2 SC 3.3.1 requires, never a tooltip. As an inline message it also carries the severity as visually hidden text, so a reader who cannot see the red ink hears “Error:” before the sentence.",
+        "live defaults to off, because a message present when the page finishes loading is not announced whatever role it carries. A form that shows the error after submit writes live=\"polite\", and the reader hears it once."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-foreground",
+    "--slotted-field-action-color",
+    "--slotted-field-action-color-active",
+    "--slotted-field-action-color-hover",
+    "--slotted-field-action-radius",
+    "--slotted-field-column-gap",
+    "--slotted-field-counter-color",
+    "--slotted-field-counter-invalid-color",
+    "--slotted-field-font-family",
+    "--slotted-field-header-gap",
+    "--slotted-field-help-color",
+    "--slotted-field-help-radius",
+    "--slotted-field-help-surface-active",
+    "--slotted-field-help-surface-hover",
+    "--slotted-field-icon-size-min",
+    "--slotted-field-label-color",
+    "--slotted-field-label-font-weight",
+    "--slotted-field-label-inline-size",
+    "--slotted-field-line-height",
+    "--slotted-field-mark-color",
+    "--slotted-field-mark-gap",
+    "--slotted-field-mark-text-color",
+    "--slotted-field-row-gap",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-line-height-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-5",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One field with every axis on it, driven by the controls below the canvas. Switch labelPlacement to side and narrow the window: below 320 pixels of its own width the field stacks again.",
+      "language": "html",
+      "source": "<div slField required>\n  <label slFieldLabel>Email</label>\n  <input slFieldControl type=\"email\" />\n  <span slFieldDescription>We will use this address for billing.</span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "necessity",
+      "title": "Saying which answers are required",
+      "note": "The asterisk is the convention. A form where most fields are required marks the exception instead — optional writes (optional) on the fields a reader may skip and nothing on the rest — and words names both sides. All four answers come from one input an application sets once.",
+      "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-field-necessity',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField required>\n        <label slFieldLabel>Company name</label>\n        <div slTextField><input slTextFieldInput /></div>\n      </div>\n      <div slField necessity=\"optional\">\n        <label slFieldLabel>Purchase order</label>\n        <div slTextField><input slTextFieldInput /></div>\n      </div>\n      <div slField necessity=\"words\" required>\n        <label slFieldLabel>Tax ID</label>\n        <div slTextField><input slTextFieldInput /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldNecessity {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "placement",
+      "title": "The label above the control, or beside it",
+      "note": "Drag the narrow column’s edge, or read it at 360 pixels: the side label stacks below 320 pixels of the field’s own width, so the same field reflows in a drawer and stays beside its control in a page grid.",
+      "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-field-placement',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slField labelPlacement=\"side\" required>\n        <label slFieldLabel>Legal name</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"Northwind Traders Ltd.\" /></div>\n      </div>\n      <div slField labelPlacement=\"side\" required>\n        <label slFieldLabel>Billing email</label>\n        <div slTextField>\n          <input slTextFieldInput type=\"email\" defaultValue=\"billing@northwind.example\" />\n        </div>\n        <span slFieldDescription>Invoices and payment receipts are sent here.</span>\n      </div>\n      <div slField labelPlacement=\"side\">\n        <label slFieldLabel>VAT number</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"GB 284 9113 07\" /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldPlacement {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the field sits at",
+      "note": "Three steps matching the control the field wraps, and every one of them reads the control type scale — set the toolbar to dense and the label, the message and the counter step down together.",
+      "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-field-sizes',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField size=\"sm\">\n        <label slFieldLabel>SKU</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"NW-CHAI-24\" /></div>\n      </div>\n      <div slField size=\"md\">\n        <label slFieldLabel>Product name</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"Chai tea, 24 bags\" /></div>\n      </div>\n      <div slField size=\"lg\">\n        <label slFieldLabel>Shelf label</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"Chai — spiced black tea\" /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldSizes {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "The four states a field can be in",
+      "note": "The label never turns red when the field is invalid: the error already says so in words and in colour, and a red marker on a red label is a marker nobody can see. Read-only stays legible and focusable; disabled is muted to a measured colour rather than faded.",
+      "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-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 required>\n        <label slFieldLabel>Card number</label>\n        <div slTextField>\n          <input slTextFieldInput inputmode=\"numeric\" defaultValue=\"4242 4242 42\" />\n        </div>\n        <span slFieldError>Six digits are missing.</span>\n      </div>\n      <div slField readOnly>\n        <label slFieldLabel>Account ID</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"acct_9f2c41\" /></div>\n        <span slFieldDescription>Quote this ID when you contact support.</span>\n      </div>\n      <div slField disabled>\n        <label slFieldLabel>Workspace URL</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"northwind.slotted.app\" /></div>\n        <span slFieldDescription>Only the workspace owner can change the URL.</span>\n      </div>\n    </div>\n  `,\n})\nexport class FieldStates {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "messages",
+      "title": "Help, errors, and the line held open for one",
+      "note": "Both messages are inline-message roots the field renders around what the page wrote, so the error carries a clipped “Error:” a screen reader reads first. The right-hand column keeps its line with reserve, so the button below does not move when the error arrives.",
+      "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-field-messages',\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>\n        <label slFieldLabel>Purchase order</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"PO-20418\" /></div>\n        <span slFieldDescription>Printed on the invoice so your accounts team can match it.</span>\n      </div>\n      <div slField invalid>\n        <label slFieldLabel>Postal code</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"981\" /></div>\n        <span slFieldDescription>Five digits, as on the shipping label.</span>\n        <span slFieldError>Enter all five digits.</span>\n      </div>\n      <div slField>\n        <label slFieldLabel>Discount</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"45%\" /></div>\n        <span slFieldError tone=\"warning\">Above 40% the order waits for a manager's approval.</span>\n      </div>\n    </div>\n  `,\n})\nexport class FieldMessages {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "counter",
+      "title": "Counting what the page is counting",
+      "note": "The count sits in the label row’s spare column, so it never shares a row with the error and never adds one. It turns at its own limit rather than at the field’s, because a count passes its maximum before validation runs.",
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport {\n  SlField,\n  SlFieldCounter,\n  SlFieldDescription,\n  SlFieldHeader,\n  SlFieldLabel,\n} from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextarea } from '@slotted/angular/textarea';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\nconst MAX_TAGS = 5;\n\n@Component({\n  selector: 'app-field-counter',\n  imports: [\n    SlField,\n    SlFieldCounter,\n    SlFieldDescription,\n    SlFieldHeader,\n    SlFieldLabel,\n    SlStack,\n    SlTextarea,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField>\n        <label slFieldLabel>Public description</label>\n        <textarea\n          slTextarea\n          autoSize\n          countMax=\"140\"\n          showCount\n          defaultValue=\"Ships within two business days. Returns are free for thirty days.\"\n        ></textarea>\n      </div>\n      <div slField [invalid]=\"over() ? true : undefined\">\n        <div slFieldHeader>\n          <label slFieldLabel>Search tags</label>\n          <span slFieldCounter [invalid]=\"over()\">{{ count() }}/{{ max }} tags</span>\n        </div>\n        <div slTextField>\n          <input slTextFieldInput [value]=\"tags()\" (valueChange)=\"tags.set($event.value)\" />\n        </div>\n        <span slFieldDescription>Separate tags with commas.</span>\n      </div>\n    </div>\n  `,\n})\nexport class FieldCounter {\n  readonly max = MAX_TAGS;\n  readonly tags = signal('tea, organic, fair trade');\n  readonly count = computed(\n    () =>\n      this.tags()\n        .split(',')\n        .filter((tag) => tag.trim() !== '').length,\n  );\n  readonly over = computed(() => this.count() > MAX_TAGS);\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "header",
+      "title": "The label row: help, indicator, action and count",
+      "note": "Hover the circle, or tab to it: the hint opens. Press it and it stays until a second press, which is what a finger needs. The row is as tall as the label with or without them, aligns on the label’s baseline, and in a narrow field sends the action and the count to a line of their own.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlBadge } from '@slotted/angular/badge';\nimport {\n  SlField,\n  SlFieldAction,\n  SlFieldHeader,\n  SlFieldIndicator,\n  SlFieldLabel,\n} from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-field-header',\n  imports: [\n    SlBadge,\n    SlField,\n    SlFieldAction,\n    SlFieldHeader,\n    SlFieldIndicator,\n    SlFieldLabel,\n    SlStack,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField required>\n        <div slFieldHeader>\n          <label slFieldLabel>Password</label>\n          <a slFieldAction href=\"#reset-password\">Forgot password?</a>\n        </div>\n        <div slTextField>\n          <input slTextFieldInput type=\"password\" autocomplete=\"current-password\" />\n        </div>\n      </div>\n      <div slField>\n        <div slFieldHeader>\n          <label slFieldLabel>Webhook URL</label>\n          <span slFieldIndicator>\n            <span slBadge size=\"sm\" tone=\"accent\" variant=\"soft\">Beta</span>\n          </span>\n          <button slFieldAction>Send test event</button>\n        </div>\n        <div slTextField>\n          <input\n            slTextFieldInput\n            type=\"url\"\n            defaultValue=\"https://hooks.northwind.example/orders\"\n          />\n        </div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldHeader {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "content",
+      "title": "Content the field did not choose",
+      "note": "A German compound with no break opportunity, a container digest in the description, and an Arabic field in a right-to-left document — the label breaks rather than sliding under the control, and the necessity word never breaks.",
+      "language": "html",
+      "source": "<div slField labelPlacement=\"side\" lang=\"ar\" dir=\"rtl\">\n  <label slFieldLabel>رقم التعريف الضريبي</label>\n  <input slFieldControl />\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "provideFieldDefaults sets the whole application’s fields once, exportAs hands a template the identifiers the field derived, and slFieldControl wires a control the library does not own without wrapping it in anything.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideFieldDefaults({ size: 'sm', necessity: 'words' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears, in order",
+      "note": "Turn a screen reader on and enter the control: the label, then “required”, then the indicator, the help behind the icon, the description, the count and the error — one name, one description in a fixed order, and no asterisk read aloud.",
+      "language": "html",
+      "source": "<div data-ui=\"field\" data-part=\"root\">\n  <div data-part=\"header\">\n    <label data-part=\"label\" for=\"cnpj-control\">\n      Tax ID<span aria-hidden=\"true\" data-part=\"mark\">*</span>\n    </label>\n    <button data-part=\"help\" aria-label=\"More information\" aria-describedby=\"cnpj-help\">\n      <span data-part=\"help-text\" id=\"cnpj-help\" hidden>Numbers only.</span>\n    </button>\n  </div>\n  <input\n    data-part=\"control\"\n    id=\"cnpj-control\"\n    aria-describedby=\"cnpj-help cnpj-description cnpj-error\"\n    aria-invalid=\"true\"\n    aria-required=\"true\"\n  />\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "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-field-basic',\n  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextField, SlTextFieldInput],\n  template: `\n    <div slField required>\n      <label slFieldLabel>Email</label>\n      <div slTextField>\n        <input slTextFieldInput type=\"email\" autocomplete=\"email\" />\n      </div>\n      <span slFieldDescription>Invoices are sent to this address.</span>\n    </div>\n  `,\n})\nexport class FieldBasic {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controls",
+      "title": "controls.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlDatePicker } from '@slotted/angular/date-picker';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\nimport { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';\nimport { SlSelect, SlSelectItem, type SelectOption } from '@slotted/angular/select';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-field-controls',\n  imports: [\n    SlDatePicker,\n    SlField,\n    SlFieldDescription,\n    SlFieldLabel,\n    SlNumberField,\n    SlNumberFieldInput,\n    SlSelect,\n    SlSelectItem,\n    SlStack,\n  ],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField required>\n        <label slFieldLabel>Payment terms</label>\n        <sl-select placeholder=\"Choose terms\" [items]=\"termOptions\" [(value)]=\"terms\">\n          @for (term of termOptions; track term.value) {\n            <sl-select-item [value]=\"term.value\">{{ term.label }}</sl-select-item>\n          }\n        </sl-select>\n      </div>\n      <div slField required>\n        <label slFieldLabel>Quantity</label>\n        <div slNumberField>\n          <input slNumberFieldInput defaultValue=\"12\" min=\"1\" max=\"500\" />\n        </div>\n        <span slFieldDescription>Cases of 24 bags.</span>\n      </div>\n      <div slField>\n        <label slFieldLabel>Delivery date</label>\n        <div slDatePicker locale=\"en-US\"></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldControls {\n  readonly termOptions: SelectOption[] = [\n    { value: 'net-15', label: 'Net 15' },\n    { value: 'net-30', label: 'Net 30' },\n    { value: 'net-60', label: 'Net 60' },\n  ];\n  readonly terms = signal<string | null>('net-30');\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "custom-control",
+      "title": "custom-control.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldControl, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\n\n@Component({\n  selector: 'app-field-custom-control',\n  imports: [SlField, SlFieldControl, SlFieldDescription, SlFieldLabel],\n  template: `\n    <div slField>\n      <label slFieldLabel>Brand colour</label>\n      <input slFieldControl type=\"color\" value=\"#2f6fde\" />\n      <span slFieldDescription>Used on invoices and in the customer portal.</span>\n    </div>\n  `,\n})\nexport class FieldCustomControl {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { provideFieldDefaults, 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-field-defaults',\n  imports: [SlField, SlFieldLabel, SlStack, SlTextField, SlTextFieldInput],\n  providers: [provideFieldDefaults({ size: 'sm', labelPlacement: 'side', necessity: 'optional' })],\n  template: `\n    <div slStack [gap]=\"3\">\n      <div slField required>\n        <label slFieldLabel>Warehouse</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"Seattle — Pier 91\" /></div>\n      </div>\n      <div slField required>\n        <label slFieldLabel>Bin location</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"A-14-03\" /></div>\n      </div>\n      <div slField>\n        <label slFieldLabel>Picking note</label>\n        <div slTextField><input slTextFieldInput /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldDefaults {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "help",
+      "title": "help.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldHeader, SlFieldHelp, 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-field-help',\n  imports: [\n    SlField,\n    SlFieldHeader,\n    SlFieldHelp,\n    SlFieldLabel,\n    SlStack,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <div slStack [gap]=\"5\">\n      <div slField required>\n        <div slFieldHeader>\n          <label slFieldLabel>Cost centre</label>\n          <button\n            slFieldHelp=\"The four-digit code finance assigns to your team. It appears on every invoice line.\"\n          ></button>\n        </div>\n        <div slTextField><input slTextFieldInput inputmode=\"numeric\" defaultValue=\"4120\" /></div>\n      </div>\n      <div slField disabled>\n        <div slFieldHeader>\n          <label slFieldLabel>Billing currency</label>\n          <button\n            slFieldHelp=\"Set when the workspace was created. Contact support to change it.\"\n          ></button>\n        </div>\n        <div slTextField><input slTextFieldInput defaultValue=\"USD — US dollar\" /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldHelp {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "narrow",
+      "title": "narrow.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlGrid } from '@slotted/angular/grid';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-field-narrow',\n  imports: [SlField, SlFieldLabel, SlGrid, SlTextField, SlTextFieldInput],\n  template: `\n    <div slGrid [columns]=\"2\" minItemWidth=\"xs\" [gap]=\"4\">\n      <div slField labelPlacement=\"side\">\n        <label slFieldLabel>City</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"Seattle\" /></div>\n      </div>\n      <div slField labelPlacement=\"side\">\n        <label slFieldLabel>Postal code</label>\n        <div slTextField><input slTextFieldInput defaultValue=\"98104\" /></div>\n      </div>\n    </div>\n  `,\n})\nexport class FieldNarrow {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\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\nfunction emailError(value: string): string {\n  if (value.trim() === '') return 'Enter the address invoices are sent to.';\n  if (!/^\\S+@\\S+\\.\\S+$/.test(value)) return 'Enter an address like billing@company.com.';\n  return '';\n}\n\n@Component({\n  selector: 'app-field-validation',\n  imports: [\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              [value]=\"email()\"\n              (valueChange)=\"edit($event.value)\"\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\">Save billing details</button>\n          @if (saved()) {\n            <span role=\"status\">Saved.</span>\n          }\n        </div>\n      </div>\n    </form>\n  `,\n})\nexport class FieldValidation {\n  readonly email = signal('');\n  readonly submitted = signal(false);\n  readonly saved = signal(false);\n  readonly error = computed(() => (this.submitted() ? emailError(this.email()) : ''));\n\n  edit(value: string): void {\n    this.email.set(value);\n    this.saved.set(false);\n  }\n\n  submit(event: Event): void {\n    event.preventDefault();\n    this.submitted.set(true);\n    this.saved.set(emailError(this.email()) === '');\n  }\n}\n",
+      "verdict": "example"
+    }
+  ]
+}