ionbase-ui 0.84.0 → 0.86.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useAgentRun",
@@ -3080,8 +3080,7 @@
       "summary": "A native checkbox with the system's styling, supporting an indeterminate state.",
       "useWhen": [
         "a single on/off choice inside a form that is submitted",
-        "selecting rows in a Table",
-        "several independent options where more than one may be picked"
+        "selecting rows in a Table"
       ],
       "useInstead": [
         {
@@ -3089,6 +3088,11 @@
           "use": "Toggle",
           "why": "a switch reads as a setting taking effect now; a checkbox reads as a value being collected"
         },
+        {
+          "when": "several options answer one question",
+          "use": "CheckboxGroup",
+          "why": "it announces the question with each option, carries the group's error, and can require at least one"
+        },
         {
           "when": "the options are mutually exclusive",
           "use": "RadioGroup"
@@ -3220,8 +3224,7 @@
             "sm",
             "md",
             "lg"
-          ],
-          "default": "md"
+          ]
         },
         "intent": {
           "type": "CheckboxIntent | undefined",
@@ -3232,8 +3235,7 @@
             "neutral",
             "danger",
             "brand"
-          ],
-          "default": "brand"
+          ]
         },
         "isIndeterminate": {
           "type": "boolean | undefined",
@@ -3282,6 +3284,274 @@
         "other": 0
       }
     },
+    "CheckboxGroup": {
+      "name": "CheckboxGroup",
+      "source": "src/components/Checkbox.tsx",
+      "propsType": "CheckboxGroupProps",
+      "description": "A set of checkboxes that answers one question — \"notify me when…\", \"which\nregions\". Owns the selected values, the group's label, help text and error,\nand \"select at least one\".\n\nA row of loose Checkboxes can do none of that accessibly: the question is\nnot announced with the options, an error has nothing to attach to, and\n\"at least one\" has no native expression at all. See the `required` note in\nCheckbox for how that last one is done.",
+      "import": "import { CheckboxGroup } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A set of checkboxes answering one question. Owns the selected values, the group's label, help and error, and \"select at least one\".",
+      "useWhen": [
+        "several options may be picked and they answer one question — \"notify me when\", \"regions\", \"columns to show\"",
+        "the group needs a rule of its own — at least one, or an error that belongs to the set rather than to an option"
+      ],
+      "useInstead": [
+        {
+          "when": "only one option may be picked",
+          "use": "RadioGroup"
+        },
+        {
+          "when": "the options are many, or space is tight",
+          "use": "Select",
+          "why": "past about seven options a list of boxes is longer than the form around it"
+        },
+        {
+          "when": "there is one on/off choice",
+          "use": "Checkbox",
+          "why": "a group of one announces a question and then its only answer"
+        },
+        {
+          "when": "each option takes effect immediately",
+          "use": "Toggle"
+        }
+      ],
+      "composition": {
+        "order": [
+          "CheckboxGroup",
+          "Checkbox"
+        ],
+        "note": "Give every Checkbox a `value`; the group's `onChange` receives the array of ticked values. Selection lives on the group — do not also set `isSelected` on the boxes.",
+        "example": "<CheckboxGroup label=\"Notify the team when\" isRequired value={notifyOn} onChange={setNotifyOn} isInvalid={!!error} errorMessage={error}><Checkbox value=\"failed\">A run fails</Checkbox><Checkbox value=\"approval\">A run needs approval</Checkbox></CheckboxGroup>"
+      },
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms and filter panels"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent choices"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "facts rather than approvals — the columns shown, the filters applied"
+          },
+          "danger": {
+            "use": "a set of destructive consents"
+          }
+        },
+        "orientation": {
+          "vertical": {
+            "use": "the default, and always when a label runs past a few words"
+          },
+          "horizontal": {
+            "use": "two to four one-word options — weekdays, regions. Wraps rather than overflows"
+          }
+        }
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "renders as the <legend> — the question the options answer"
+        },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "shown only while `isInvalid` is set"
+        },
+        "children": {
+          "accepts": "Checkbox"
+        }
+      },
+      "a11y": {
+        "role": "group, from <fieldset> and <legend>",
+        "guarantees": [
+          "the legend is announced as the group's name when focus enters any box",
+          "the description or error is on every box's `aria-describedby` as well as the fieldset's, so it is read on the box that takes focus",
+          "`isInvalid` sets `aria-invalid` on every box",
+          "`isRequired` sets native `required` on every box while none is ticked and on none once one is: the browser blocks the submit in its own language, and each box announces \"required\" exactly while the rule is unmet",
+          "`isDisabled` cascades to every Checkbox that has not set its own"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when the question is already visible elsewhere",
+          "a `value` on every Checkbox — the group tracks the selection by it"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "loose Checkboxes under a text label",
+          "why": "the question is not announced with the options, an error has nothing to attach to, and \"at least one\" cannot be expressed"
+        },
+        {
+          "dont": "`isSelected` or `checked` on a Checkbox inside a group",
+          "why": "the group owns the selection; the box's own value is ignored"
+        },
+        {
+          "dont": "`isRequired` on every Checkbox in the group",
+          "why": "that means every box must be ticked; `isRequired` on the group means at least one"
+        }
+      ],
+      "stylesheet": "src/styles/checkbox.css",
+      "tokens": [
+        "--border-disabled",
+        "--border-error-strong",
+        "--border-focus",
+        "--border-inverse",
+        "--border-primary-strong",
+        "--border-stronger",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--icon-disabled",
+        "--icon-on-color",
+        "--ion-checkbox-border",
+        "--ion-checkbox-fill",
+        "--ion-checkbox-font-size",
+        "--ion-checkbox-gap",
+        "--ion-checkbox-line-height",
+        "--ion-checkbox-mark",
+        "--ion-checkbox-radius",
+        "--ion-checkbox-raised",
+        "--ion-checkbox-size",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-shadow-raised-flush-lg",
+        "--ion-shadow-raised-flush-sm",
+        "--ion-shadow-raised-flush-xs",
+        "--radius-sm",
+        "--radius-xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-error",
+        "--surface-inverse",
+        "--surface-primary",
+        "--text-disabled",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The question the options answer. Renders as the `<legend>`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in the description's place while `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Marks every box invalid and shows `errorMessage`."
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "At least one option must be selected — enforced by native validation."
+        },
+        "value": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The selected values (controlled)."
+        },
+        "defaultValue": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The initially selected values (uncontrolled)."
+        },
+        "onChange": {
+          "type": "((value: string[]) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Receives the whole new selection, in the order the options were ticked."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Shared input name, so a form submits every ticked value under it."
+        },
+        "size": {
+          "type": "CheckboxSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "intent": {
+          "type": "CheckboxIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "neutral",
+            "danger",
+            "brand"
+          ]
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether every checkbox in the group is disabled."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "vertical",
+            "horizontal"
+          ]
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Checkboxes, each with a `value`."
+        }
+      },
+      "propCounts": {
+        "own": 14,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
     "Citation": {
       "name": "Citation",
       "source": "src/components/Citation.tsx",
@@ -4736,8 +5006,8 @@
           "origin": "own",
           "description": "Matches Figma's `Style` variant.",
           "values": [
-            "horizontal",
-            "vertical"
+            "vertical",
+            "horizontal"
           ]
         }
       },
@@ -5219,43 +5489,205 @@
         "other": 0
       }
     },
-    "FileUpload": {
-      "name": "FileUpload",
-      "source": "src/components/FileUpload.tsx",
-      "propsType": "FileUploadProps",
-      "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
-      "import": "import { FileUpload } from 'ionbase-ui';",
+    "Fieldset": {
+      "name": "Fieldset",
+      "source": "src/components/Fieldset.tsx",
+      "propsType": "FieldsetProps",
+      "description": "Groups related fields under one label, with one description and one error —\nan address, a date range typed as two fields, a set of limits.\n\nFor checkboxes use CheckboxGroup and for radios RadioGroup: both render this\nsame shell, and add the selection state it deliberately does not own.\n\nThere is no `isDisabled`. A native `disabled` fieldset does disable every\ncontrol inside, but Input, Select and the rest draw their disabled state from\ntheir own prop, so the fields would stop working while still looking live.\nDisable the fields themselves; the choice groups can cascade because their\ncheckboxes and radios style off `:disabled`.",
+      "import": "import { Fieldset } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
+      "summary": "A <fieldset>/<legend> that groups related fields under one label, one description and one error — an address, a pair of limits, a date typed as two fields.",
       "useWhen": [
-        "the user attaches one or more files to a form or a message",
-        "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
+        "several fields answer one question and a reader must hear the question with each of them — street, city and postcode under \"Billing address\"",
+        "one error belongs to the group rather than to a field — \"the minimum must be below the maximum\""
       ],
       "useInstead": [
         {
-          "when": "a single file is picked and no drop target or file list is wanted",
-          "use": "a plain <input type=\"file\">",
-          "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
+          "when": "the fields are checkboxes",
+          "use": "CheckboxGroup",
+          "why": "it renders this same shell and adds the selected values and \"select at least one\""
         },
         {
-          "when": "upload progress needs to be shown",
-          "use": "ProgressBar",
-          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+          "when": "the fields are radios",
+          "use": "RadioGroup",
+          "why": "it renders this same shell and adds the shared name and the selected value"
+        },
+        {
+          "when": "a single field needs a label and help text",
+          "use": "Input",
+          "why": "every field already renders its own label, description and error; a fieldset around one field announces the label twice"
+        },
+        {
+          "when": "the grouping is visual — a titled section of a settings page",
+          "use": "Card",
+          "why": "a fieldset is a form grouping that assistive technology announces on entry; a section of unrelated settings is not one question"
         }
       ],
+      "composition": {
+        "order": [
+          "Fieldset",
+          "Input"
+        ],
+        "note": "Each field keeps its own label — the legend names the group, not the fields. Put a group-level error in `errorMessage` with `isInvalid`, and keep field-level errors on the fields.",
+        "example": "<Fieldset label=\"Run limits\" description=\"Runs stop at whichever comes first.\" orientation=\"horizontal\"><NumberInput label=\"Max steps\" /><NumberInput label=\"Max minutes\" /></Fieldset>"
+      },
       "variants": {
-        "size": {
-          "sm": {
-            "use": "inside a dense form, or beside other fields"
+        "orientation": {
+          "vertical": {
+            "use": "the default — fields stacked, as a form reads"
           },
-          "md": {
-            "use": "the default — a standalone attachment area"
+          "horizontal": {
+            "use": "two or three short fields that read as one value — a range, a size, a city and postcode. Wraps rather than overflows"
           }
         }
       },
-      "a11y": {
-        "guarantees": [
-          "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "renders as the <legend> — the question the fields answer"
+        },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the fields; replaced by `errorMessage` while `isInvalid` is set, as Input's is"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "the group's error, shown only while `isInvalid` is set"
+        },
+        "children": {
+          "accepts": "Input, Select, NumberInput, DatePicker and other fields"
+        }
+      },
+      "a11y": {
+        "role": "group, from <fieldset> and <legend>",
+        "guarantees": [
+          "the legend is announced as the group's name when focus enters any field inside",
+          "`aria-describedby` on the fieldset points at whichever of the description or the error is showing"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when the question is already visible as a heading"
+        ],
+        "notes": [
+          "There is no `isDisabled`. A native disabled fieldset disables every control inside, but Input, Select and the rest draw their disabled look from their own prop — the fields would stop working while still looking live. Disable the fields themselves."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Fieldset around one field",
+          "why": "the field's label and the legend both announce, saying the same thing twice"
+        },
+        {
+          "dont": "a Fieldset of Checkboxes",
+          "do": "<CheckboxGroup label=\"Notify me when\">…</CheckboxGroup>",
+          "why": "it looks the same, but nothing owns the selected values or \"select at least one\""
+        },
+        {
+          "dont": "<fieldset disabled> around Inputs",
+          "why": "the fields stop accepting input while still drawn as enabled"
+        }
+      ],
+      "stylesheet": "src/styles/fieldset.css",
+      "tokens": [
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-regular",
+        "--ion-fieldset-gap",
+        "--ion-fieldset-inline-gap",
+        "--spacing-16",
+        "--spacing-6",
+        "--spacing-8",
+        "--text-error",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The question the fields answer. Renders as the `<legend>`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Help text beneath the fields. Replaced by `errorMessage` while invalid."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in the description's place while `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether the group as a whole fails validation."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "How the fields flow. Horizontal wraps rather than overflowing.",
+          "values": [
+            "vertical",
+            "horizontal"
+          ],
+          "default": "vertical"
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 279,
+        "other": 0
+      }
+    },
+    "FileUpload": {
+      "name": "FileUpload",
+      "source": "src/components/FileUpload.tsx",
+      "propsType": "FileUploadProps",
+      "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
+      "import": "import { FileUpload } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
+      "useWhen": [
+        "the user attaches one or more files to a form or a message",
+        "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
+      ],
+      "useInstead": [
+        {
+          "when": "a single file is picked and no drop target or file list is wanted",
+          "use": "a plain <input type=\"file\">",
+          "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
+        },
+        {
+          "when": "upload progress needs to be shown",
+          "use": "ProgressBar",
+          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "inside a dense form, or beside other fields"
+          },
+          "md": {
+            "use": "the default — a standalone attachment area"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
           "the zone is a <label> for that input, so clicking anywhere opens the picker without any script",
           "the input is clipped to 1px rather than display:none, which would remove it from the tab order and the accessibility tree",
           "the focus ring is drawn on the zone, where the user is looking, not on the clipped input",
@@ -10212,7 +10644,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -10304,10 +10735,10 @@
       "name": "RadioGroup",
       "source": "src/components/Radio.tsx",
       "propsType": "RadioGroupProps",
-      "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.",
+      "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.\n\nThe fieldset itself is Fieldset's shell, shared with CheckboxGroup, so the\ntwo choice groups take the same label, help, error and orientation props.",
       "import": "import { RadioGroup } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value.",
+      "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value, and the group's label, help and error.",
       "useWhen": [
         "exactly one choice from a small set, all worth showing at once",
         "the options need explaining — each one can carry its own label text"
@@ -10319,7 +10750,7 @@
         },
         {
           "when": "more than one may be picked",
-          "use": "Checkbox"
+          "use": "CheckboxGroup"
         },
         {
           "when": "there are exactly two states and the change is immediate",
@@ -10348,6 +10779,14 @@
           "danger": {
             "use": "a set where the options are destructive"
           }
+        },
+        "orientation": {
+          "vertical": {
+            "use": "the default, and always when a label runs past a few words"
+          },
+          "horizontal": {
+            "use": "two to four one-word options. Wraps rather than overflows"
+          }
         }
       },
       "slots": {
@@ -10355,6 +10794,14 @@
           "accepts": "text",
           "note": "renders as the <legend> — the question the options answer"
         },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "shown only while `isInvalid` is set"
+        },
         "children": {
           "accepts": "Radio"
         }
@@ -10364,7 +10811,10 @@
         "guarantees": [
           "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
           "`name` is generated when omitted, so two groups on one page never collide",
-          "`isDisabled` cascades to every Radio that has not set its own"
+          "`isDisabled` cascades to every Radio that has not set its own",
+          "the fieldset is Fieldset's shell, shared with CheckboxGroup — the same label, help, error and orientation props",
+          "the description or error is on every radio's `aria-describedby` as well as the fieldset's, so it is read on the radio that takes focus",
+          "`isRequired` is native `required` on the radios, which the platform already reads as \"one of this name\""
         ],
         "requires": [
           "`label`, or `aria-label` when the question is already visible elsewhere"
@@ -10401,7 +10851,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -10461,7 +10910,41 @@
         "label": {
           "type": "React.ReactNode",
           "required": false,
-          "origin": "own"
+          "origin": "own",
+          "description": "The question the options answer. Renders as the `<legend>`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in the description's place while `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Shows `errorMessage` in the description's place."
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "One option must be chosen before the form submits."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "vertical",
+            "horizontal"
+          ]
         },
         "size": {
           "type": "RadioSize | undefined",
@@ -10504,7 +10987,7 @@
         }
       },
       "propCounts": {
-        "own": 10,
+        "own": 15,
         "aria": 0,
         "dom": 276,
         "other": 0
@@ -10649,6 +11132,493 @@
         "other": 0
       }
     },
+    "SearchField": {
+      "name": "SearchField",
+      "source": "src/components/SearchField.tsx",
+      "propsType": "SearchFieldProps",
+      "description": "SearchField — a text field for a search query.\n\nNOT `<Input type=\"search\">`. That gets the right input type and nothing\nelse. `useSearchField` adds what a search box owes its user:\n\n  `role=\"searchbox\"`, so a screen reader announces a search field, not a\n  text field. Enter calls `onSubmit` with the query. Escape clears it — a\n  second Escape then reaches whatever the field sits in, so a search inside\n  a dialog clears first and closes second. A clear button appears once there\n  is something to clear, named in the user's language by React Aria.\n\nThe clear button is out of the tab order on purpose, as React Aria sets it:\nEscape is the keyboard's way to clear, and an extra tab stop in every search\nbox costs every keyboard user a keystroke. Pressing it puts focus back in the\nfield.\n\nThe box IS Input's — the component renders `.ion-input` and its size and\nstate classes, so a search field beside an Input in a toolbar matches it\nexactly and cannot drift. Same arrangement as NumberInput.",
+      "import": "import { SearchField } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A text field for a search query: role=\"searchbox\", Enter submits, Escape clears, and a clear button once there is something to clear. Input's box and sizes.",
+      "useWhen": [
+        "the user types to search or filter a list, a table or a page — the search above a DataTable, the filter at the top of a Sidebar",
+        "the query is free text that narrows what is shown, not a value chosen from a list"
+      ],
+      "useInstead": [
+        {
+          "when": "the typed text picks one value from a known list — an assignee, a country",
+          "use": "Combobox",
+          "why": "a combobox commits a choice and offers the options; a search field commits a query and offers nothing"
+        },
+        {
+          "when": "the user is looking for a page or an action anywhere in the product",
+          "use": "CommandPalette",
+          "why": "that is global and keyboard-first; a SearchField searches the content in front of it"
+        },
+        {
+          "when": "it is ordinary text entry — a name, an email — that happens to be used for lookup later",
+          "use": "Input",
+          "why": "announcing a searchbox promises search behaviour: Escape clears, Enter searches"
+        }
+      ],
+      "composition": {
+        "order": [
+          "SearchField"
+        ],
+        "note": "Filter as the user types with `onChange`, or search on Enter with `onSubmit` — pick one per field and say which in the placeholder or label. In a table toolbar, give it `aria-label` naming what it searches.",
+        "example": "<SearchField aria-label=\"Search agents\" placeholder=\"Search by name or purpose\" value={query} onChange={setQuery} />"
+      },
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "toolbars, table headers and Sidebar filters, beside small Buttons"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "a page whose main task is searching"
+          }
+        }
+      },
+      "a11y": {
+        "role": "searchbox",
+        "guarantees": [
+          "the input is role=\"searchbox\" and type=\"search\", so it is announced as a search field",
+          "Escape clears the query; a second Escape is left for whatever contains the field, so a search in a dialog clears before it closes",
+          "Enter calls onSubmit with the query",
+          "the clear button is named by React Aria in the user's language, appears only when there is something to clear, and returns focus to the field",
+          "the clear button is out of the tab order on purpose: Escape is the keyboard's way to clear, and an extra tab stop in every search box costs every keyboard user a keystroke",
+          "the browser's own cancel button is hidden, so there are never two"
+        ],
+        "requires": [
+          "`label`, or an `aria-label` naming what is searched when no visible label is rendered — \"Search\" alone does not say what"
+        ],
+        "notes": [
+          "When filtering as the user types, announce the result count with a polite live region near the results. The field cannot know how many results its query produced; the list does."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "<Input type=\"search\"> with a magnifier as leadingIcon",
+          "why": "it looks the same and has none of the behaviour: no searchbox role, no Escape to clear, no labelled clear button"
+        },
+        {
+          "dont": "placeholder as the only name",
+          "why": "a placeholder disappears once the user types, and is not a reliable accessible name. Pass `aria-label` or `label`"
+        },
+        {
+          "dont": "a separate Search button beside a field that already filters as you type",
+          "why": "it teaches the user that nothing happens until they press it, and it does nothing when they do"
+        }
+      ],
+      "stylesheet": "src/styles/search-field.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--icon-default",
+        "--icon-secondary",
+        "--ion-input-height",
+        "--ion-input-icon-size",
+        "--radius-sm",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-hover",
+        "--surface-pressed"
+      ],
+      "props": {
+        "size": {
+          "type": "SearchFieldSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Input's sizes: Small, Medium, Large.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the control box (`.ion-input`)."
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
+        },
+        "enterKeyHint": {
+          "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
+          "values": [
+            "done",
+            "enter",
+            "go",
+            "next",
+            "previous",
+            "search",
+            "send"
+          ]
+        },
+        "type": {
+          "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+          "tags": {
+            "default": "'search'"
+          }
+        },
+        "onSubmit": {
+          "type": "((value: string) => void) | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "Handler that is called when the SearchField is submitted."
+        },
+        "onClear": {
+          "type": "(() => void) | undefined",
+          "required": false,
+          "origin": "other",
+          "description": "Handler that is called when the clear button is pressed."
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input is disabled."
+        },
+        "isReadOnly": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input can be selected but not changed by the user."
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether user input is required on the input before form submission."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the input value is invalid."
+        },
+        "validationState": {
+          "type": "ValidationState | undefined",
+          "required": false,
+          "origin": "aria",
+          "values": [
+            "valid",
+            "invalid"
+          ],
+          "tags": {
+            "deprecated": "Use `isInvalid` instead."
+          }
+        },
+        "validationBehavior": {
+          "type": "\"aria\" | \"native\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to use native HTML form validation to prevent form submission\nwhen the value is missing or invalid, or mark the field as required\nor invalid via ARIA.",
+          "values": [
+            "aria",
+            "native"
+          ],
+          "tags": {
+            "default": "'aria'"
+          }
+        },
+        "validate": {
+          "type": "((value: string) => ValidationError | true | null | undefined) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A function that returns an error message if a given value is invalid.\nValidation errors are displayed to the user when the form is submitted\nif `validationBehavior=\"native\"`. For realtime validation, use the `isInvalid`\nprop instead."
+        },
+        "description": {
+          "type": "ReactNode",
+          "required": false,
+          "origin": "aria",
+          "description": "A description for the field. Provides a hint such as specific requirements for what to choose."
+        },
+        "errorMessage": {
+          "type": "ReactNode | ((v: ValidationResult) => ReactNode)",
+          "required": false,
+          "origin": "aria",
+          "description": "An error message for the field."
+        },
+        "autoFocus": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the element should receive focus on render."
+        },
+        "onFocus": {
+          "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element receives focus."
+        },
+        "onBlur": {
+          "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element loses focus."
+        },
+        "onFocusChange": {
+          "type": "((isFocused: boolean) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the element's focus status changes."
+        },
+        "onKeyDown": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a key is pressed."
+        },
+        "onKeyUp": {
+          "type": "((e: KeyboardEvent) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a key is released."
+        },
+        "placeholder": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Temporary text that occupies the text input when it is empty."
+        },
+        "value": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The current value (controlled)."
+        },
+        "defaultValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The default value (uncontrolled)."
+        },
+        "onChange": {
+          "type": "((value: string) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the value changes."
+        },
+        "label": {
+          "type": "ReactNode",
+          "required": false,
+          "origin": "aria",
+          "description": "The content to display as the label."
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+        },
+        "spellCheck": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An enumerated attribute that defines whether the element may be checked for spelling errors.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck)."
+        },
+        "autoCorrect": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An attribute that takes as its value a space-separated string that describes what, if any, type\nof autocomplete functionality the input should provide. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete)."
+        },
+        "inputMode": {
+          "type": "\"none\" | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"numeric\" | \"decimal\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Hints at the type of data that might be entered by the user while editing the element or its\ncontents. See\n[MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute).",
+          "values": [
+            "none",
+            "search",
+            "text",
+            "url",
+            "tel",
+            "email",
+            "numeric",
+            "decimal"
+          ]
+        },
+        "aria-activedescendant": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the currently active element when DOM focus is on a composite widget, textbox,\ngroup, or application."
+        },
+        "aria-autocomplete": {
+          "type": "\"inline\" | \"list\" | \"none\" | \"both\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates whether inputting text could trigger display of one or more predictions of the user's\nintended value for an input and specifies how predictions would be presented if they are made.",
+          "values": [
+            "inline",
+            "list",
+            "none",
+            "both"
+          ]
+        },
+        "aria-controls": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+        },
+        "aria-describedby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that describes the object."
+        },
+        "aria-details": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+        },
+        "aria-errormessage": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element that provides an error message for the object."
+        },
+        "aria-haspopup": {
+          "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+        },
+        "aria-label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Defines a string value that labels the current element."
+        },
+        "aria-labelledby": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Identifies the element (or elements) that labels the current element."
+        },
+        "onCopy": {
+          "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user copies text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy)."
+        },
+        "onCut": {
+          "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user cuts text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut)."
+        },
+        "onPaste": {
+          "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the user pastes text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste)."
+        },
+        "onCompositionEnd": {
+          "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a text composition system completes or cancels the current text\ncomposition session. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event)."
+        },
+        "onCompositionStart": {
+          "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a text composition system starts a new text composition session.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)."
+        },
+        "onCompositionUpdate": {
+          "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a new character is received in the current text composition\nsession. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event)."
+        },
+        "onBeforeInput": {
+          "type": "FormEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is about to be modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event)."
+        },
+        "onInput": {
+          "type": "FormEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)."
+        },
+        "onSelect": {
+          "type": "ReactEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
+        },
+        "form": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+        },
+        "autoComplete": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
+        },
+        "maxLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The maximum number of characters supported by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength)."
+        },
+        "minLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
+        },
+        "pattern": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Regex pattern that the value of the input must match to be valid. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern)."
+        },
+        "excludeFromTabOrder": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 51,
+        "dom": 264,
+        "other": 2
+      }
+    },
     "SegmentedControl": {
       "name": "SegmentedControl",
       "source": "src/components/SegmentedControl.tsx",
@@ -12339,8 +13309,8 @@
           "origin": "own",
           "description": "`horizontal` for a page-width header above the form, `vertical` for a side\nrail. Below 40rem a horizontal stepper hides every label but the current\none, so it does not need a second variant for mobile.",
           "values": [
-            "horizontal",
-            "vertical"
+            "vertical",
+            "horizontal"
           ]
         },
         "children": {
@@ -13467,13 +14437,13 @@
           "default": "md"
         },
         "orientation": {
-          "type": "\"horizontal\" | \"vertical\" | undefined",
+          "type": "\"vertical\" | \"horizontal\" | undefined",
           "required": false,
           "origin": "own",
           "description": "Drives both the arrow-key axis and the track layout.\n\n`vertical` is keyboard- and ARIA-complete — up/down move between tabs, and\nthe track stacks — but its *decoration* is not: the underline rule and the\npill track's padding are still written for the horizontal axis only. Those\nare Figma's to specify, not this file's to invent. See tabs.css.",
           "values": [
-            "horizontal",
-            "vertical"
+            "vertical",
+            "horizontal"
           ],
           "tags": {
             "default": "'horizontal'"