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

package/dist/docs/field.json

@@ -0,0 +1,528 @@
+{
+  "family": "field",
+  "ui": "field",
+  "binding": "react",
+  "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  Field,\n  FieldAction,\n  FieldControl,\n  FieldCounter,\n  FieldDefaultsProvider,\n  FieldDescription,\n  FieldError,\n  FieldHeader,\n  FieldHelp,\n  FieldIndicator,\n  FieldLabel,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "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": "div, or the element render returns",
+          "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. A field whose label stands alone writes the label on the root and no header."
+        },
+        {
+          "part": "label",
+          "element": "label",
+          "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, 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, fixed",
+          "required": false,
+          "purpose": "A circle-question button beside the label that shows the field’s help 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. 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": "span, or the element render returns",
+          "required": false,
+          "purpose": "What qualifies the field, such as Beta, Pro or New, as one or more Badges 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": "button type=\"button\", or the element render returns",
+          "required": false,
+          "purpose": "A link or a button at the end of the label row, such as Forgot password? or Generate. Its accent ink darkens by a third on hover, with the underline drawn, and by two thirds on press. The field does not disable it with the control."
+        },
+        {
+          "part": "control",
+          "element": "input, or the element render returns",
+          "required": false,
+          "purpose": "A control Slotted does not ship, wired by FieldControl. Slotted’s own controls read the field themselves and need no wrapper. The field gives the control an identifier, a description, aria-invalid, aria-required, disabled and readonly, and overwrites nothing the consumer stated."
+        },
+        {
+          "part": "counter",
+          "element": "span, or the element render returns",
+          "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 FieldCounter. 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": "Field",
+          "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": "Field",
+          "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": "Field",
+          "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": "Field",
+          "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": "Field",
+          "description": "Unset rather than false. Writes aria-required on the control, never the native required, which would turn on browser constraint validation and change how the form submits."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Field, FieldCounter",
+          "description": "On Field: unset rather than false; writes aria-invalid on the control and data-invalid on the field, and leaves the label’s colour unchanged. On FieldCounter: 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 provider",
+          "appliesTo": "Field, FieldDefaultsProvider",
+          "description": "Unset rather than false, so a field follows the FieldGroup 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 provider",
+          "appliesTo": "Field, FieldDefaultsProvider",
+          "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": "Field",
+          "description": "The base of every identifier the field derives: <id>-control, <id>-label, <id>-indicator, <id>-help, <id>-description, <id>-counter and <id>-error. Generated with useId when unset."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "FieldHelp",
+          "description": "The help text. Written once, it reaches the tooltip and the hidden node that describes the button and the control."
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "FieldHelp",
+          "description": "Whether the hint is showing, controlled. Pair it with onOpenChange; leave both unset and FieldHelp owns the state."
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "FieldHelp",
+          "description": "Whether the hint starts open, read once when FieldHelp owns the state."
+        },
+        {
+          "name": "side",
+          "type": "'top' | 'bottom' | 'inline-start' | 'inline-end' | 'left' | 'right'",
+          "defaultValue": "top",
+          "appliesTo": "FieldHelp",
+          "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": "FieldHelp",
+          "description": "The accessible name of the help button. Unset, it is the field’s help message; set, it applies to this button alone."
+        },
+        {
+          "name": "type",
+          "type": "'button' | 'submit' | 'reset'",
+          "defaultValue": "button",
+          "appliesTo": "FieldAction",
+          "description": "button by default, so the action never submits the form it sits in. A link rendered through render receives the props without it."
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "secondary on FieldDescription, danger on FieldError",
+          "appliesTo": "FieldDescription, FieldError",
+          "description": "Both messages are InlineMessage roots and take its five tones, so a warning that does not block submission is FieldError with tone=\"warning\"."
+        },
+        {
+          "name": "mark",
+          "type": "'glyph' | 'dot' | 'none'",
+          "defaultValue": "none",
+          "appliesTo": "FieldDescription, FieldError",
+          "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": "FieldDescription, FieldError",
+          "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": "FieldDescription, FieldError",
+          "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": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Field, FieldHeader, FieldLabel, FieldIndicator, FieldAction, FieldControl, FieldCounter",
+          "description": "Replaces the rendered element and hands it every attribute: a textarea as the control, an output as the counter, a link as the action, a fieldset as the field. The props are typed as HTMLAttributes<HTMLElement>, so they spread onto any element. FieldHelp has no render: its button carries the name, the description and the tooltip control, and all three belong to Field."
+        },
+        {
+          "name": "onClick and the pointer and focus handlers",
+          "type": "native",
+          "defaultValue": "—",
+          "appliesTo": "FieldHelp, FieldAction",
+          "description": "The consumer’s handler runs first and the field’s after it, unless the consumer called preventDefault."
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "any component inside a Field",
+          "description": "Returns the identifiers, the description and the four states, so a control Slotted does not ship wires itself without a wrapper. Returns undefined outside a field, so the same control also works alone."
+        },
+        {
+          "name": "FieldDefaultsProvider",
+          "type": "{ size, labelPlacement, necessity, disabled, readOnly }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The five decisions an application takes once for every field under it. FieldGroup renders one for the fields inside it, so a compact or disabled section is one prop instead of one per field."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the default element; on FieldHelp, the button. A part rendered through render is the consumer’s element, so the consumer attaches its ref there. There is no imperative handle: the one state Field holds, the hint, is controlled through open and onOpenChange."
+        }
+      ],
+      "events": [
+        {
+          "name": "onOpenChange",
+          "payload": "(open: boolean, request: TooltipChangeRequest)",
+          "when": "On FieldHelp, before the hint opens or closes, once per transition. request.reason is pointer for a hover or a press; keyboard for focus, Enter or Space; or escape, blur or programmatic. request.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.",
+        "Field 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: an explicit value on the control always wins. 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, and deriving the order from registration would make what a reader hears depend on when an effect ran. 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 InlineMessage 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 sets live=\"polite\", and the reader hears it once rather than on every render."
+      ]
+    }
+  },
+  "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": "tsx",
+      "source": "<Field required>\n  <FieldLabel>Email</FieldLabel>\n  <FieldControl type=\"email\" />\n  <FieldDescription>We will use this address for billing.</FieldDescription>\n</Field>;\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 axis an application sets once.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldNecessity() {\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldLabel>Company name</FieldLabel>\n        <TextField />\n      </Field>\n      <Field necessity=\"optional\">\n        <FieldLabel>Purchase order</FieldLabel>\n        <TextField />\n      </Field>\n      <Field necessity=\"words\" required>\n        <FieldLabel>Tax ID</FieldLabel>\n        <TextField />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldPlacement() {\n  return (\n    <Stack gap={4}>\n      <Field labelPlacement=\"side\" required>\n        <FieldLabel>Legal name</FieldLabel>\n        <TextField defaultValue=\"Northwind Traders Ltd.\" />\n      </Field>\n      <Field labelPlacement=\"side\" required>\n        <FieldLabel>Billing email</FieldLabel>\n        <TextField type=\"email\" defaultValue=\"billing@northwind.example\" />\n        <FieldDescription>Invoices and payment receipts are sent here.</FieldDescription>\n      </Field>\n      <Field labelPlacement=\"side\">\n        <FieldLabel>VAT number</FieldLabel>\n        <TextField defaultValue=\"GB 284 9113 07\" />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldSizes() {\n  return (\n    <Stack gap={5}>\n      <Field size=\"sm\">\n        <FieldLabel>SKU</FieldLabel>\n        <TextField defaultValue=\"NW-CHAI-24\" />\n      </Field>\n      <Field size=\"md\">\n        <FieldLabel>Product name</FieldLabel>\n        <TextField defaultValue=\"Chai tea, 24 bags\" />\n      </Field>\n      <Field size=\"lg\">\n        <FieldLabel>Shelf label</FieldLabel>\n        <TextField defaultValue=\"Chai — spiced black tea\" />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldStates() {\n  return (\n    <Stack gap={5}>\n      <Field invalid required>\n        <FieldLabel>Card number</FieldLabel>\n        <TextField inputMode=\"numeric\" defaultValue=\"4242 4242 42\" />\n        <FieldError>Six digits are missing.</FieldError>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Account ID</FieldLabel>\n        <TextField defaultValue=\"acct_9f2c41\" />\n        <FieldDescription>Quote this ID when you contact support.</FieldDescription>\n      </Field>\n      <Field disabled>\n        <FieldLabel>Workspace URL</FieldLabel>\n        <TextField defaultValue=\"northwind.slotted.app\" />\n        <FieldDescription>Only the workspace owner can change the URL.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "messages",
+      "title": "Help, errors, and the line held open for one",
+      "note": "Both messages are inline-message roots, so the error carries a clipped “Error:” a screen reader reads first. The right-hand column renders its error unconditionally with reserve, so the button below it does not move when the error arrives.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldMessages() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Purchase order</FieldLabel>\n        <TextField defaultValue=\"PO-20418\" />\n        <FieldDescription>\n          Printed on the invoice so your accounts team can match it.\n        </FieldDescription>\n      </Field>\n      <Field invalid>\n        <FieldLabel>Postal code</FieldLabel>\n        <TextField defaultValue=\"981\" />\n        <FieldDescription>Five digits, as on the shipping label.</FieldDescription>\n        <FieldError>Enter all five digits.</FieldError>\n      </Field>\n      <Field>\n        <FieldLabel>Discount</FieldLabel>\n        <TextField defaultValue=\"45%\" />\n        <FieldError tone=\"warning\">Above 40% the order waits for a manager's approval.</FieldError>\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { useState } from 'react';\nimport {\n  Field,\n  FieldCounter,\n  FieldDescription,\n  FieldHeader,\n  FieldLabel,\n} from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\nimport { Textarea } from '@slotted/react/textarea';\n\nconst MAX_TAGS = 5;\n\nexport default function FieldCounterExample() {\n  const [tags, setTags] = useState('tea, organic, fair trade');\n  const count = tags.split(',').filter((tag) => tag.trim() !== '').length;\n  const over = count > MAX_TAGS;\n\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Public description</FieldLabel>\n        <Textarea\n          autoSize\n          countMax={140}\n          showCount\n          defaultValue=\"Ships within two business days. Returns are free for thirty days.\"\n        />\n      </Field>\n      <Field invalid={over ? true : undefined}>\n        <FieldHeader>\n          <FieldLabel>Search tags</FieldLabel>\n          <FieldCounter invalid={over}>{`${count}/${MAX_TAGS} tags`}</FieldCounter>\n        </FieldHeader>\n        <TextField value={tags} onValueChange={setTags} />\n        <FieldDescription>Separate tags with commas.</FieldDescription>\n      </Field>\n    </Stack>\n  );\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": "tsx",
+      "source": "import { Badge } from '@slotted/react/badge';\nimport { Field, FieldAction, FieldHeader, FieldIndicator, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldHeaderExample() {\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldHeader>\n          <FieldLabel>Password</FieldLabel>\n          <FieldAction render={(props) => <a {...props} href=\"#reset-password\" />}>\n            Forgot password?\n          </FieldAction>\n        </FieldHeader>\n        <TextField type=\"password\" autoComplete=\"current-password\" />\n      </Field>\n      <Field>\n        <FieldHeader>\n          <FieldLabel>Webhook URL</FieldLabel>\n          <FieldIndicator>\n            <Badge size=\"sm\" tone=\"accent\" variant=\"soft\">\n              Beta\n            </Badge>\n          </FieldIndicator>\n          <FieldAction>Send test event</FieldAction>\n        </FieldHeader>\n        <TextField type=\"url\" defaultValue=\"https://hooks.northwind.example/orders\" />\n      </Field>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "<Field dir=\"rtl\" labelPlacement=\"side\" lang=\"ar\">\n  <FieldLabel>رقم التعريف الضريبي</FieldLabel>\n  <FieldControl />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "The provider sets the whole application’s fields once, render substitutes any part’s element, and useField lets a control this library does not own take the wiring without a wrapper around it.",
+      "language": "tsx",
+      "source": "<FieldDefaultsProvider necessity=\"words\" size=\"sm\">\n  <App />\n</FieldDefaultsProvider>;\n\n// A control the library does not own, wired without a wrapper.\nfunction MoneyInput() {\n  const field = useField();\n  return <input id={field?.ids.control} aria-describedby={field?.describedBy} />;\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": "tsx",
+      "source": "<div data-ui=\"field\" data-part=\"root\">\n  <div data-part=\"header\">\n    <label data-part=\"label\" for=\"cnpj-control\">\n      Tax ID\n      <span aria-hidden=\"true\" data-part=\"mark\">\n        *\n      </span>\n    </label>\n    <button aria-describedby=\"cnpj-help\" aria-label=\"More information\" data-part=\"help\">\n      <span data-part=\"help-text\" hidden id=\"cnpj-help\">\n        Numbers only.\n      </span>\n    </button>\n  </div>\n  <input\n    aria-describedby=\"cnpj-help cnpj-description cnpj-error\"\n    aria-invalid=\"true\"\n    aria-required=\"true\"\n    id=\"cnpj-control\"\n  />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldBasic() {\n  return (\n    <Field required>\n      <FieldLabel>Email</FieldLabel>\n      <TextField type=\"email\" autoComplete=\"email\" />\n      <FieldDescription>Invoices are sent to this address.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controls",
+      "title": "controls.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { DatePicker } from '@slotted/react/date-picker';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport {\n  Select,\n  SelectContent,\n  SelectItem,\n  type SelectOption,\n  SelectTrigger,\n  SelectValue,\n} from '@slotted/react/select';\nimport { Stack } from '@slotted/react/stack';\n\nconst TERMS: SelectOption[] = [\n  { value: 'net-15', label: 'Net 15' },\n  { value: 'net-30', label: 'Net 30' },\n  { value: 'net-60', label: 'Net 60' },\n];\n\nexport default function FieldControls() {\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldLabel>Payment terms</FieldLabel>\n        <Select defaultValue=\"net-30\" items={TERMS}>\n          <SelectTrigger>\n            <SelectValue placeholder=\"Choose terms\" />\n          </SelectTrigger>\n          <SelectContent>\n            {TERMS.map((term) => (\n              <SelectItem key={term.value} value={term.value}>\n                {term.label}\n              </SelectItem>\n            ))}\n          </SelectContent>\n        </Select>\n      </Field>\n      <Field required>\n        <FieldLabel>Quantity</FieldLabel>\n        <NumberField defaultValue={12} min={1} max={500} />\n        <FieldDescription>Cases of 24 bags.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Delivery date</FieldLabel>\n        <DatePicker locale=\"en-US\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "custom-control",
+      "title": "custom-control.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldControl, FieldDescription, FieldLabel } from '@slotted/react/field';\n\nexport default function FieldCustomControl() {\n  return (\n    <Field>\n      <FieldLabel>Brand colour</FieldLabel>\n      <FieldControl type=\"color\" defaultValue=\"#2f6fde\" />\n      <FieldDescription>Used on invoices and in the customer portal.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDefaultsProvider, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldDefaults() {\n  return (\n    <FieldDefaultsProvider size=\"sm\" labelPlacement=\"side\" necessity=\"optional\">\n      <Stack gap={3}>\n        <Field required>\n          <FieldLabel>Warehouse</FieldLabel>\n          <TextField defaultValue=\"Seattle — Pier 91\" />\n        </Field>\n        <Field required>\n          <FieldLabel>Bin location</FieldLabel>\n          <TextField defaultValue=\"A-14-03\" />\n        </Field>\n        <Field>\n          <FieldLabel>Picking note</FieldLabel>\n          <TextField />\n        </Field>\n      </Stack>\n    </FieldDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "help",
+      "title": "help.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldHeader, FieldHelp, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldHelpExample() {\n  return (\n    <Stack gap={5}>\n      <Field required>\n        <FieldHeader>\n          <FieldLabel>Cost centre</FieldLabel>\n          <FieldHelp>\n            The four-digit code finance assigns to your team. It appears on every invoice line.\n          </FieldHelp>\n        </FieldHeader>\n        <TextField inputMode=\"numeric\" defaultValue=\"4120\" />\n      </Field>\n      <Field disabled>\n        <FieldHeader>\n          <FieldLabel>Billing currency</FieldLabel>\n          <FieldHelp>Set when the workspace was created. Contact support to change it.</FieldHelp>\n        </FieldHeader>\n        <TextField defaultValue=\"USD — US dollar\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "narrow",
+      "title": "narrow.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Grid } from '@slotted/react/grid';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function FieldNarrow() {\n  return (\n    <Grid columns={2} minItemWidth=\"xs\" gap={4}>\n      <Field labelPlacement=\"side\">\n        <FieldLabel>City</FieldLabel>\n        <TextField defaultValue=\"Seattle\" />\n      </Field>\n      <Field labelPlacement=\"side\">\n        <FieldLabel>Postal code</FieldLabel>\n        <TextField defaultValue=\"98104\" />\n      </Field>\n    </Grid>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\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\nexport default function FieldValidation() {\n  const [email, setEmail] = useState('');\n  const [submitted, setSubmitted] = useState(false);\n  const [saved, setSaved] = useState(false);\n  const error = submitted ? emailError(email) : '';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    setSaved(emailError(email) === '');\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <Field required invalid={error !== '' ? true : undefined}>\n          <FieldLabel>Billing email</FieldLabel>\n          <TextField\n            type=\"email\"\n            value={email}\n            onValueChange={(value) => {\n              setEmail(value);\n              setSaved(false);\n            }}\n          />\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Save billing details</Button>\n          {saved ? <span role=\"status\">Saved.</span> : null}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}