ionbase-ui 0.81.1 → 0.86.0

package/dist/meta/CheckboxGroup.json

@@ -0,0 +1,268 @@
+{
+  "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
+  }
+}

package/dist/meta/Divider.json

@@ -55,8 +55,8 @@
       "origin": "own",
       "description": "Matches Figma's `Style` variant.",
       "values": [
-        "horizontal",
-        "vertical"
+        "vertical",
+        "horizontal"
       ]
     }
   },

package/dist/meta/Fieldset.json

@@ -0,0 +1,162 @@
+{
+  "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 <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": [
+    "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": "the fields are checkboxes",
+      "use": "CheckboxGroup",
+      "why": "it renders this same shell and adds the selected values and \"select at least one\""
+    },
+    {
+      "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": {
+    "orientation": {
+      "vertical": {
+        "use": "the default — fields stacked, as a form reads"
+      },
+      "horizontal": {
+        "use": "two or three short fields that read as one value — a range, a size, a city and postcode. Wraps rather than overflows"
+      }
+    }
+  },
+  "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
+  }
+}