ionbase-ui 0.51.0 → 0.59.0

package/dist/meta/ProgressBar.json

@@ -0,0 +1,166 @@
+{
+  "name": "ProgressBar",
+  "source": "src/components/ProgressBar.tsx",
+  "propsType": "ProgressBarProps",
+  "description": "ProgressBar — a determinate or indeterminate measure of work.\n\nDETERMINATE AND INDETERMINATE ARE THE SAME COMPONENT ON PURPOSE\n\nWork that starts unmeasurable and becomes measurable is the common case — a\nupload that does not know its size until the first chunk lands. Splitting\nthem into two components would make that transition a swap, which remounts\nthe node and loses the live region with it.\n\nOmitting `value` is what makes it indeterminate. `aria-valuenow` is then\nomitted too, which is exactly what the ARIA spec asks for and is the detail\nhand-rolled progress bars get wrong most often — a bar reporting\n`aria-valuenow=\"0\"` forever tells a screen reader the work is stuck at zero,\nnot that it is unmeasured.\n\nWHY `label` IS REQUIRED\n\n`role=\"progressbar\"` announces a number. Without a name the user hears \"42\npercent\" with no indication of what is at 42 percent, which is worse than\nsilence because it sounds like information.",
+  "import": "import { ProgressBar } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A determinate or indeterminate measure of work, with the name of the work attached. Omitting `value` is what makes it indeterminate.",
+  "useWhen": [
+    "work reports a fraction complete — an upload, an import, a multi-step job",
+    "work will become measurable but is not yet, and the bar should not remount when it does",
+    "a quota or usage figure is better read as a bar than a number"
+  ],
+  "useInstead": [
+    {
+      "when": "the wait is short and unmeasurable",
+      "use": "Spinner",
+      "why": "an indeterminate bar occupies a block of layout to say what a spinner says inline"
+    },
+    {
+      "when": "the region is being replaced by content",
+      "use": "Skeleton"
+    }
+  ],
+  "variants": {
+    "intent": {
+      "primary": {
+        "use": "the default — work proceeding normally"
+      },
+      "success": {
+        "use": "work that finished, where the bar stays on screen as a record"
+      },
+      "warning": {
+        "use": "a quota approaching its limit",
+        "note": "warning describes the VALUE, not a failure of the bar"
+      },
+      "error": {
+        "use": "a quota exceeded, or a job that failed part-way",
+        "note": "the bar is still reporting correctly — reserve this for the measured thing being bad"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "inside a row or a dense table cell"
+      },
+      "md": {
+        "use": "the default"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` — it is required, because role=\"progressbar\" announces a number and a number with no noun sounds like information while carrying none",
+      "`valueText` when a percentage is not what a person wants read aloud — \"3 of 12 files\""
+    ],
+    "notes": [
+      "indeterminate omits aria-valuenow entirely, as the ARIA spec asks; a bar reporting aria-valuenow=0 forever says the work is stuck rather than unmeasured",
+      "value is clamped to 0..max, so a caller cannot render a bar past its own end"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<ProgressBar label=\"Loading\" value={0} /> while the total is unknown",
+      "do": "<ProgressBar label=\"Loading\" />",
+      "why": "value={0} announces \"0 percent\" indefinitely. Omitting value is how you say \"not measurable yet\""
+    },
+    {
+      "dont": "swapping a Spinner for a ProgressBar once the size is known",
+      "do": "one ProgressBar, with `value` appearing when it becomes known",
+      "why": "the swap remounts the node and takes the live region with it, so the transition is silent to a screen reader"
+    },
+    {
+      "dont": "intent=\"error\" because the request failed",
+      "do": "leave the bar and put the failure in an Alert",
+      "why": "intent describes the value being measured. A failed request is not a red measurement, it is a different message"
+    }
+  ],
+  "stylesheet": "src/styles/progress-bar.css",
+  "tokens": [
+    "--border-width-default",
+    "--font-family-sans",
+    "--ion-duration-base",
+    "--ion-duration-slow",
+    "--ion-ease-in-out",
+    "--ion-ease-out",
+    "--ion-progress-bar-fill",
+    "--ion-progress-bar-height",
+    "--ion-progress-bar-pct",
+    "--radius-full",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-muted",
+    "--surface-primary",
+    "--surface-success",
+    "--surface-warning",
+    "--text-default",
+    "--text-secondary",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "What is progressing. Required — a bare bar announces a number and no noun."
+    },
+    "value": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "0 to `max`. Omit for an indeterminate bar."
+    },
+    "max": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Defaults to 100."
+    },
+    "intent": {
+      "type": "ProgressBarIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "primary",
+        "success",
+        "warning",
+        "error"
+      ]
+    },
+    "size": {
+      "type": "ProgressBarSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md"
+      ]
+    },
+    "isLabelVisible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show the label as text above the track."
+    },
+    "isValueVisible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show the percentage beside the label. Determinate bars only."
+    },
+    "valueText": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Spoken instead of the percentage — \"3 of 12 files\". A percentage is rarely\nthe thing a person wants read aloud."
+    }
+  },
+  "propCounts": {
+    "own": 8,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Select.json

@@ -13,7 +13,8 @@
   "useInstead": [
     {
       "when": "the list is long enough to need search or type-ahead beyond the native behaviour",
-      "use": "a combobox — not yet in this system"
+      "use": "Combobox",
+      "why": "a native <select> list is the browser's, and cannot be filtered"
     },
     {
       "when": "the rows need icons, avatars or two lines of text",
@@ -126,10 +127,10 @@
       "default": "md"
     },
     "options": {
-      "type": "SelectOption[] | undefined",
+      "type": "readonly SelectOption[] | undefined",
       "required": false,
       "origin": "own",
-      "description": "The options to render. Omit and pass `children` for grouped options."
+      "description": "The options to render. Omit and pass `children` for grouped options.\n\n`readonly` because an options list is almost always a module-level constant,\nand `as const` on one produces a readonly array that a mutable parameter\nrejects. The component only ever maps over it, so demanding a mutable array\nbought nothing and cost callers a spread or a cast."
     },
     "placeholder": {
       "type": "string | undefined",

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/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

package/dist/meta/Tooltip.json

@@ -113,10 +113,10 @@
       "origin": "own",
       "description": "Matches the Figma `Placement` variant, and names where the TOOLTIP sits —\nnot where the arrow points. `top` is above the trigger, with the arrow on\nthe tooltip's bottom edge.\n\nTreated as a preference, not a guarantee: it flips to the opposite side\nwhen there is no room, which is the behaviour Figma cannot draw.",
       "values": [
-        "right",
-        "left",
         "top",
-        "bottom"
+        "bottom",
+        "right",
+        "left"
       ]
     },
     "delay": {