ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/Skeleton.json

@@ -0,0 +1,120 @@
+{
+  "name": "Skeleton",
+  "source": "src/components/Skeleton.tsx",
+  "propsType": "SkeletonProps",
+  "description": "Skeleton — the shape of content that has not arrived.\n\nIT IS HIDDEN FROM ASSISTIVE TECHNOLOGY, ALWAYS, AND THAT IS THE WHOLE POINT\n\nA skeleton is a picture of content, and a screen reader cannot use a picture\nof content. Announcing it produces a stream of empty boxes between the user\nand the thing they asked for. So every skeleton is `aria-hidden`, with no way\nto opt out — a prop for that would only ever be used by mistake.\n\nWHICH MEANS THE CALLER OWES THE ANNOUNCEMENT, AND THIS COMPONENT CANNOT DO IT\n\nHiding the placeholder is only half an answer: something still has to tell a\nscreen-reader user that the region is loading. That belongs on the region\nbeing replaced — `aria-busy=\"true\"` while it loads — because only the caller\nknows where that region starts and ends. `Spinner` is the other half when the\nwait deserves an announcement of its own.\n\n  <section aria-busy={isLoading}>\n    {isLoading ? <Skeleton lines={3} /> : <Rows data={data} />}\n  </section>\n\nThis is the one component in the system whose correct use REQUIRES something\nof the caller that the type system cannot check, which is why it is stated\nhere, in the contract, and in the story.",
+  "import": "import { Skeleton } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The shape of content that has not arrived. Always hidden from assistive technology — the caller owns the announcement.",
+  "useWhen": [
+    "a region will be replaced by content whose shape is known in advance",
+    "the layout would otherwise jump when the content lands",
+    "several regions load independently and a single page spinner would hide that"
+  ],
+  "useInstead": [
+    {
+      "when": "the shape of what is coming is not known",
+      "use": "Spinner",
+      "why": "a skeleton that does not match what replaces it is a worse promise than no promise"
+    },
+    {
+      "when": "the region is empty because there is nothing to show",
+      "use": "EmptyState",
+      "why": "a skeleton that never resolves is how an empty list looks like a broken one"
+    }
+  ],
+  "variants": {
+    "variant": {
+      "text": {
+        "use": "lines of copy",
+        "note": "height comes from the line box, so the block occupies what the real paragraph will. With `lines`, the last is drawn short because real paragraphs end mid-measure"
+      },
+      "circle": {
+        "use": "an avatar or an icon slot"
+      },
+      "rect": {
+        "use": "a card, a thumbnail, a chart"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`aria-busy=\"true\"` on the region being replaced, set by the CALLER — this component cannot do it, because only the caller knows where the region starts and ends"
+    ],
+    "notes": [
+      "every skeleton is aria-hidden with no opt-out: a screen reader cannot use a picture of content, and announcing it puts a stream of empty boxes between the user and what they asked for",
+      "prefers-reduced-motion stops the pulse outright, unlike Spinner and ProgressBar — a skeleton conveys nothing a static block does not, so there is no signal to preserve"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Skeleton /> inside a region with no aria-busy",
+      "do": "<section aria-busy={isLoading}>{isLoading ? <Skeleton lines={3} /> : <Rows />}</section>",
+      "why": "the skeleton is hidden, so without aria-busy a screen-reader user is told nothing at all — the region simply reads as empty"
+    },
+    {
+      "dont": "a skeleton whose shape does not match the content that replaces it",
+      "do": "match the line count and block sizes to the real thing",
+      "why": "the entire benefit is that the layout does not move; a mismatched skeleton pays the cost and keeps the jump"
+    },
+    {
+      "dont": "leaving skeletons on screen when a request fails",
+      "do": "render EmptyState with reason=\"error\"",
+      "why": "a skeleton that never resolves is indistinguishable from a hung page"
+    }
+  ],
+  "stylesheet": "src/styles/skeleton.css",
+  "tokens": [
+    "--border-width-default",
+    "--icon-size-lg",
+    "--ion-duration-slow",
+    "--ion-ease-in-out",
+    "--ion-skeleton-height",
+    "--ion-skeleton-radius",
+    "--ion-skeleton-width",
+    "--radius-full",
+    "--radius-md",
+    "--radius-sm",
+    "--spacing-16",
+    "--spacing-64",
+    "--spacing-8",
+    "--surface-muted",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "variant": {
+      "type": "SkeletonVariant | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "circle",
+        "text",
+        "rect"
+      ]
+    },
+    "width": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Any CSS length. Defaults to filling the width available."
+    },
+    "height": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Any CSS length. `text` derives its height from the line box instead."
+    },
+    "lines": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "`text` only: how many lines to draw. The last is drawn short."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Spinner.json

@@ -0,0 +1,123 @@
+{
+  "name": "Spinner",
+  "source": "src/components/Spinner.tsx",
+  "propsType": "SpinnerProps",
+  "description": "Spinner — an indeterminate wait, announced once.\n\nWHY THIS IS NOT A DIV WITH A CSS ANIMATION\n\nThe obvious implementation is inaccessible in a specific and common way: a\nspinning graphic with no text is silence to a screen reader, so the user is\ntold nothing happened. Generated code in this repo's own eval corpus reached\nfor a bare `role=\"status\"` in 48 files, which is the right instinct and only\nhalf the job — the role creates a live region, but an empty one announces\nnothing at all.\n\nSo the default carries a label. It is visually hidden, it lives inside the\nlive region, and it is what makes \"Loading\" reach the user who cannot see the\nring.\n\n`isDecorative` exists because the opposite mistake is just as easy. A spinner\ninside a button whose label already changed to \"Saving…\" would announce\ntwice, and two live regions racing is worse than one. Decorative renders no\nrole at all rather than `aria-hidden` on a live region, which browsers treat\ninconsistently.\n\nMOTION\n\n`prefers-reduced-motion` slows the rotation rather than stopping it. A\nstationary spinner is not a calmer spinner — it is a broken one, and it\nremoves the only signal a sighted user has that the wait is still live.",
+  "import": "import { Spinner } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "An indeterminate wait, announced once. A ring plus a politely-announced label, sized off the icon ramp.",
+  "useWhen": [
+    "work is in flight and its duration cannot be measured",
+    "a control has started something and must show it is working",
+    "a small region is waiting and a skeleton would be more scaffolding than content"
+  ],
+  "useInstead": [
+    {
+      "when": "the work has a measurable fraction complete",
+      "use": "ProgressBar",
+      "why": "a spinner over measurable work discards information the user wants — a spinner and a 90%-complete upload look identical"
+    },
+    {
+      "when": "a region is being replaced by content with a known shape",
+      "use": "Skeleton",
+      "why": "a skeleton holds the layout so it does not jump when content lands; a spinner leaves a hole that then reflows"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "inside a control, or beside a line of text"
+      },
+      "md": {
+        "use": "the default — a panel or a section"
+      },
+      "lg": {
+        "use": "a whole route or a full-page wait"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "a `label` naming what is loading — it is announced politely and is the only thing a screen-reader user receives",
+      "`isDecorative` when something else already announces the wait, so two live regions do not race"
+    ],
+    "notes": [
+      "the ring is aria-hidden; the label carries the meaning",
+      "prefers-reduced-motion slows the rotation rather than stopping it — a stationary spinner is indistinguishable from a hung one"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<div className=\"spinner\" role=\"status\" />",
+      "do": "<Spinner label=\"Loading invoices\" />",
+      "why": "role=\"status\" creates a live region; an EMPTY live region announces nothing. This exact half-measure appeared in 48 files of this repo's eval corpus"
+    },
+    {
+      "dont": "<Button isDisabled>Saving… <Spinner /></Button>",
+      "do": "<Button isDisabled>Saving… <Spinner isDecorative /></Button>",
+      "why": "the button label already says it. Two live regions announcing the same wait talk over each other"
+    },
+    {
+      "dont": "a Spinner for an upload that reports bytes transferred",
+      "do": "ProgressBar with value",
+      "why": "throwing away a known percentage makes a finite wait feel unbounded"
+    }
+  ],
+  "stylesheet": "src/styles/spinner.css",
+  "tokens": [
+    "--border-primary-strong",
+    "--border-subtle",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--icon-size-lg",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--ion-duration-slow",
+    "--ion-ease-linear",
+    "--ion-spinner-head",
+    "--ion-spinner-size",
+    "--ion-spinner-track",
+    "--radius-full",
+    "--spacing-8",
+    "--text-secondary",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "SpinnerSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the icon size ramp: sm, md, lg.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "What is loading. Announced politely; visible only with `isLabelVisible`."
+    },
+    "isLabelVisible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Render the label as text beside the ring as well as announcing it."
+    },
+    "isDecorative": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The spinner conveys nothing on its own — something else already says the\nregion is busy. Renders inert: no role, no live region, hidden from AT."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Stepper.json

@@ -0,0 +1,135 @@
+{
+  "name": "Stepper",
+  "source": "src/components/Stepper.tsx",
+  "propsType": "StepperProps",
+  "description": "Stepper — where the user is in a task that has an order.\n\nWHY NOT TABS\n\nThe `tablist` role announces peers that can be visited in any order, which is\nthe opposite of a wizard. This is an ordered list: the steps are a sequence,\nand `ol` says so. Nothing here is a tab, and arrow keys do nothing.\n\nPOSITION AND STATUS ARE TEXT, NOT ONLY DRAWING\n\nEvery step renders \"Step 2 of 5\" and its status as visually hidden text. The\nnumber in the circle is for the eye; a screen reader cannot be relied on to\nannounce list position, and a coloured ring carries nothing in forced-colours\nmode. The complete and error glyphs also differ in SHAPE — a check and an\nexclamation — so the states survive greyscale, which WCAG 1.4.1 requires.\n\nONLY VISITED STEPS ARE LINKS\n\n`href` / `onPress` are honoured on `complete` and `error` steps that are not\ncurrent. An `incomplete` step renders as text even when given one, because\njumping forward past unanswered steps is exactly what a wizard exists to\nprevent — and a link that is there but should not be followed is worse than\nno link. The current step is text for the same reason Breadcrumb's is: a link\nto where you already are is a dead control.\n\nIT DOES NOT ANNOUNCE STEP CHANGES\n\nThe Wizard pattern moves focus to the new step's heading, which announces it.\nA live region here as well would say the same thing twice, on every step.",
+  "import": "import { Stepper } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Where the user is in a task that has an order. An ordered list of steps, each stating its position and status in text.",
+  "useWhen": [
+    "a Wizard — later steps depend on earlier answers and the user needs to see what is left",
+    "a multi-page flow such as checkout or onboarding, where the steps are fixed and known in advance"
+  ],
+  "useInstead": [
+    {
+      "when": "the sections can be visited in any order",
+      "use": "Tabs",
+      "why": "tabs promise peers; a stepper promises a sequence, and using one for the other misleads in both directions"
+    },
+    {
+      "when": "the progress is a quantity with no named stages — an upload, an import",
+      "use": "ProgressBar",
+      "why": "a stepper with no meaningful step names is a progress bar drawn in circles"
+    },
+    {
+      "when": "the steps are an agent's actions rather than the user's",
+      "use": "AgentActivity",
+      "why": "the user is not moving through those steps; they are supervising them"
+    }
+  ],
+  "variants": {
+    "orientation": {
+      "horizontal": {
+        "use": "the default — a header above the step's form. Below 40rem it keeps only the current label visible"
+      },
+      "vertical": {
+        "use": "a side rail beside the form, or when step names or descriptions are long"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "StepperStep",
+      "note": "first step first, and exactly one with isCurrent"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` naming the task when a page carries more than one stepper — it defaults to \"Progress\""
+    ],
+    "guarantees": [
+      "every step renders \"Step N of M\" and its status as visually hidden text, derived from the children rather than passed in",
+      "the current step carries aria-current=\"step\"",
+      "connectors are CSS and never enter the accessibility tree"
+    ],
+    "notes": [
+      "it does not announce step changes. The Wizard pattern moves focus to the new step's heading, which announces it; a live region here would say it twice"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Tabs> as a wizard's step indicator",
+      "do": "<Stepper>",
+      "why": "the tablist role announces peers that can be visited in any order, which is the opposite of a wizard"
+    },
+    {
+      "dont": "more than about seven steps",
+      "why": "a stepper that has to scroll or wrap no longer shows what is left, which is the only thing it is for — group the steps instead"
+    }
+  ],
+  "stylesheet": "src/styles/stepper.css",
+  "tokens": [
+    "--border-default",
+    "--border-error",
+    "--border-focus",
+    "--border-primary",
+    "--border-strong",
+    "--border-width-thick",
+    "--border-width-thicker",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--icon-error",
+    "--icon-primary",
+    "--icon-size-lg",
+    "--icon-size-sm",
+    "--radius-full",
+    "--radius-xs",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-primary",
+    "--text-default",
+    "--text-error",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the list. Defaults to \"Progress\"; give it the task's name when a page\ncarries more than one — \"Checkout progress\"."
+    },
+    "orientation": {
+      "type": "StepperOrientation | undefined",
+      "required": false,
+      "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"
+      ]
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`StepperStep` elements, first step first."
+    }
+  },
+  "propCounts": {
+    "own": 3,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/StepperStep.json

@@ -0,0 +1,148 @@
+{
+  "name": "StepperStep",
+  "source": "src/components/Stepper.tsx",
+  "propsType": "StepperStepProps",
+  "import": "import { StepperStep } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One step in a Stepper: a numbered indicator, a name, and a status carried by shape and text as well as colour.",
+  "useWhen": [
+    "inside a Stepper, once per step"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a step an agent is running",
+      "use": "AgentActivityStep"
+    }
+  ],
+  "variants": {
+    "status": {
+      "incomplete": {
+        "use": "the default — not yet answered. Never a link, even with href"
+      },
+      "complete": {
+        "use": "answers accepted by the server, not merely filled in"
+      },
+      "error": {
+        "use": "the step's answers were rejected. Put the reason on the step's fields, not here"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the step's name, short — \"Shipping\", not \"Enter your shipping details\""
+    },
+    "description": {
+      "accepts": "text",
+      "note": "what the step asks for, or a summary of the answer once complete"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the current step and incomplete steps render as text, never as links, whatever href or onPress say",
+      "complete and error use different glyphs — a check and an exclamation — so status survives greyscale and forced-colours mode"
+    ],
+    "notes": [
+      "status and isCurrent are separate on purpose: a user who goes Back to step 1 is on a step that is both current and complete"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "status=\"complete\" as soon as the fields are filled",
+      "do": "mark it complete when the server accepts the step",
+      "why": "a green check on answers that are later rejected sends the user back through a step they were told was finished"
+    },
+    {
+      "dont": "href on every step so users can jump ahead",
+      "why": "incomplete steps ignore it; skipping unanswered steps is what a wizard exists to prevent"
+    },
+    {
+      "dont": "using it outside Stepper",
+      "why": "it renders an <li> and reads its position from the Stepper, and throws without one"
+    }
+  ],
+  "stylesheet": "src/styles/stepper.css",
+  "tokens": [
+    "--border-default",
+    "--border-error",
+    "--border-focus",
+    "--border-primary",
+    "--border-strong",
+    "--border-width-thick",
+    "--border-width-thicker",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--icon-error",
+    "--icon-primary",
+    "--icon-size-lg",
+    "--icon-size-sm",
+    "--radius-full",
+    "--radius-xs",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-primary",
+    "--text-default",
+    "--text-error",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "The step's name, in the user's language."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "A short second line — what the step asks for, or a summary of the answer."
+    },
+    "status": {
+      "type": "StepperStepStatus | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Whether the step's answers have been accepted. Orthogonal to `isCurrent`:\na user who goes Back to step 1 is on a step that is both current and\ncomplete.",
+      "values": [
+        "error",
+        "incomplete",
+        "complete"
+      ]
+    },
+    "isCurrent": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The step the user is on. Marked `aria-current=\"step\"`."
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Makes a visited step a link back to it. Ignored on the current step and on\n`incomplete` steps — see the component's comment for why."
+    },
+    "onPress": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "As `href`, for a wizard that changes step without a route."
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Tabs.json

@@ -20,6 +20,11 @@
       "use": "Divider",
       "why": "tabs hide everything but the active panel, including from Ctrl-F"
     },
+    {
+      "when": "the options set a value — a view mode, a range, a unit — and no panel belongs to each",
+      "use": "SegmentedControl",
+      "why": "it looks like the pill type and is a radiogroup: a tab with no panel announces a relationship that does not exist"
+    },
     {
       "when": "it is navigation between pages rather than panels within one",
       "use": "NavItem"

package/dist/meta/Toggle.json

@@ -72,6 +72,11 @@
     {
       "dont": "a button with `aria-pressed` for a setting",
       "why": "a switch is a form value; the checkbox gives form association and `:checked` for free"
+    },
+    {
+      "dont": "<Toggle isSelected={on} onChange={(isSelected) => setOn(isSelected)} />",
+      "do": "<Toggle isSelected={on} onSelectionChange={setOn} />",
+      "why": "as Checkbox: `isSelected` pairs with `onSelectionChange` and `checked` pairs with `onChange(event)`. Toggle extends the input element, so `onChange` keeps the DOM signature it has always had."
     }
   ],
   "deprecated": [
@@ -167,10 +172,22 @@
       "type": "React.ReactNode",
       "required": false,
       "origin": "own"
+    },
+    "isSelected": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "React Aria's name for `checked`. Wins when both are passed."
+    },
+    "onSelectionChange": {
+      "type": "((isSelected: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Receives the new selection state rather than the change event."
     }
   },
   "propCounts": {
-    "own": 5,
+    "own": 7,
     "aria": 0,
     "dom": 304,
     "other": 0