ionbase-ui 0.18.0 → 0.19.0

package/dist/meta/Toggle.json

@@ -4,6 +4,82 @@
   "propsType": "ToggleProps",
   "description": "Toggle is a checkbox with `role=\"switch\"`.\n\nNot a button with aria-pressed: a switch is a form value, and the checkbox\ngives form association and `:checked` for free. `role=\"switch\"` changes only\nhow it is announced — \"on/off\" rather than \"checked/unchecked\" — which is\nwhat Figma's On/Off states describe.\n\nThe visual difference from Checkbox is entirely in CSS; this component and\nCheckbox are near-identical by design rather than by accident, and are kept\napart because Figma models them as separate components with separate size\nramps.",
   "import": "import { Toggle } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A switch — a checkbox with role=\"switch\", announced as on/off.",
+  "useWhen": [
+    "the change takes effect immediately: a setting, a feature flag, a preference"
+  ],
+  "useInstead": [
+    {
+      "when": "the value is collected and submitted with a form",
+      "use": "Checkbox",
+      "why": "a switch reads as taking effect now; a checkbox reads as a value being gathered"
+    },
+    {
+      "when": "there are more than two states",
+      "use": "RadioGroup"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense settings rows and table filters"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent single settings"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "a setting with no positive or negative reading — display and layout preferences"
+      },
+      "danger": {
+        "use": "turning on something destructive or hard to undo"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the visible label; omit for a bare switch and supply `aria-label`"
+    }
+  },
+  "a11y": {
+    "role": "switch",
+    "guarantees": [
+      "a real <input type=\"checkbox\"> underneath, so form association, label clicking and `:checked` come from the platform",
+      "`role=\"switch\"` changes only the announcement — \"on/off\" rather than \"checked/unchecked\""
+    ],
+    "requires": [
+      "`children`, or `aria-label` when there is no visible label"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Toggle with a Save button beside it",
+      "why": "a switch says the change is already applied; if it needs saving it is a Checkbox"
+    },
+    {
+      "dont": "labelling a Toggle \"Enable dark mode?\" as a question",
+      "why": "a switch label names the thing being switched, not a question about it"
+    },
+    {
+      "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"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/toggle.css",
   "tokens": [
     "--border-disabled",

package/dist/meta/Tooltip.json

@@ -4,6 +4,80 @@
   "propsType": "TooltipProps",
   "description": "Tooltip — Figma `Tooltip` (801:1568).\n\nWraps its trigger rather than taking a ref, so the common case is one\nelement deep: `<Tooltip label=\"...\"><Button/></Tooltip>`.\n\nFOCUS OPENS IT, NOT JUST HOVER. A hover-only tooltip is invisible to keyboard\nand switch users, and `useTooltipTrigger` wires both plus Escape to dismiss.\nIt also enforces one open tooltip at a time and a shared warmup, so moving\nalong a row of icon buttons does not flash a tooltip per button.\n\nThe trigger is cloned with the interaction props and a ref, which means it\nmust forward both. Every component in this library does; a bare `<div>` does\ntoo. A function component that drops its ref will render, but the tooltip\nwill have nothing to position against.",
   "import": "import { Tooltip } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A text-only hint attached to a trigger. Opens on hover and on focus.",
+  "useWhen": [
+    "naming an icon-only control",
+    "adding a short clarification that is genuinely optional to read"
+  ],
+  "useInstead": [
+    {
+      "when": "the content has anything focusable in it — a link, a button, a field",
+      "use": "Popover",
+      "why": "a tooltip cannot be focused, cannot be scrolled, and closes the moment the pointer leaves"
+    },
+    {
+      "when": "the information is required to complete the field",
+      "use": "Input",
+      "why": "Input's helper text is always visible; a tooltip is not discoverable on touch"
+    }
+  ],
+  "variants": {
+    "placement": {
+      "top": {
+        "use": "above the trigger — the default reading position"
+      },
+      "bottom": {
+        "use": "below the trigger, for something near the top of the viewport"
+      },
+      "left": {
+        "use": "to the left of the trigger"
+      },
+      "right": {
+        "use": "to the right of the trigger"
+      }
+    }
+  },
+  "slots": {
+    "label": {
+      "accepts": "text",
+      "note": "the hint. Text only"
+    },
+    "title": {
+      "accepts": "text",
+      "note": "optional heading above the label"
+    },
+    "children": {
+      "accepts": "Button",
+      "note": "the trigger. Must forward both a ref and DOM props"
+    }
+  },
+  "a11y": {
+    "role": "tooltip",
+    "guarantees": [
+      "focus opens it, not only hover — a hover-only tooltip is invisible to keyboard and switch users",
+      "Escape dismisses it",
+      "one tooltip open at a time with a shared warmup, so moving along a row of icon buttons does not flash one per button",
+      "`placement` flips to the opposite side when there is no room"
+    ],
+    "requires": [
+      "a trigger that is already labelled for icon-only controls — Tooltip supplies the hint, not the trigger's name"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "putting a link or button inside `label`",
+      "why": "it cannot be reached — the tooltip closes when the pointer leaves the trigger"
+    },
+    {
+      "dont": "a tooltip as the only place information appears",
+      "why": "it is undiscoverable on touch, where there is no hover"
+    },
+    {
+      "dont": "a tooltip on a disabled Button",
+      "why": "a disabled button takes no focus and often no pointer events, so the hint never appears for a keyboard user"
+    }
+  ],
   "stylesheet": "src/styles/tooltip.css",
   "tokens": [
     "--font-family-sans",