ionbase-ui 0.18.0 → 0.19.0

package/dist/meta/Link.json

@@ -4,6 +4,73 @@
   "propsType": "LinkProps",
   "description": "Link — Figma `Link` (774:1516).\n\nRenders an `<a>` when given an `href` and a `<button>` otherwise, the same\njudgment `NavItem` makes: the element follows what the caller is actually\nbuilding rather than a separate `as` prop. A link that does not navigate is\na button, and shipping one as an anchor breaks middle-click, \"open in new\ntab\" and the screen-reader announcement all at once.\n\nNO SIZE PROP, DELIBERATELY. A link is an inline element and inherits its\ntype from the text around it — `font-size: inherit` in the stylesheet, and\nicons sized in `em` so they scale with it. Figma has to draw its variants at\nsome concrete size (16/24, `type/body`), but that is one sample of an\ninheriting element, not a specification. Do not add a size ladder to match\nthe drawing.",
   "import": "import { Link } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Navigation to somewhere else. Renders an <a> when given `href`, a <button> otherwise.",
+  "useWhen": [
+    "the interaction takes the user to a different page, view or resource",
+    "the destination should support middle-click, open-in-new-tab and copy-link"
+  ],
+  "useInstead": [
+    {
+      "when": "the interaction changes something rather than going somewhere",
+      "use": "Button",
+      "why": "a link that does not navigate breaks middle-click, open-in-new-tab and the screen-reader announcement all at once"
+    },
+    {
+      "when": "it is a primary navigation destination in a header or sidebar",
+      "use": "NavItem"
+    }
+  ],
+  "variants": {
+    "variant": {
+      "inline": {
+        "use": "the default — a link inside a paragraph. Underlined in every state, because a link in body copy must not rely on colour alone (WCAG 1.4.1)"
+      },
+      "standalone": {
+        "use": "a link that already reads as interactive from its position — a card footer, an action row. Underlines on hover only"
+      }
+    }
+  },
+  "slots": {
+    "startIcon": {
+      "accepts": "Icon",
+      "note": "omit Icon's `label` — the link text already names it"
+    },
+    "endIcon": {
+      "accepts": "Icon",
+      "note": "the external-link or arrow affordance; same rule about `label`"
+    }
+  },
+  "a11y": {
+    "role": "link when `href` is set, button when it is not",
+    "guarantees": [
+      "the rendered element follows what the caller is actually building, so the announcement is always honest",
+      "`inline` stays underlined in every state, so it never depends on colour alone"
+    ],
+    "requires": [
+      "link text that makes sense read on its own — screen-reader users navigate by a list of links"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "\"click here\" or \"read more\" as the whole link text",
+      "why": "out of context in a links list it names nothing"
+    },
+    {
+      "dont": "adding a size prop or wrapper to scale it",
+      "why": "a link is inline and inherits its type from the text around it, by design — icons are sized in `em` to follow"
+    },
+    {
+      "dont": "`target=\"_blank\"` with no warning in the text or endIcon",
+      "why": "an unannounced new tab disorients screen-reader and low-vision users"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/link.css",
   "tokens": [
     "--border-width-thick",

package/dist/meta/Logo.json

@@ -4,6 +4,55 @@
   "propsType": "LogoProps",
   "description": "The full lockup: mark + wordmark, matching Figma's `Logo-Ionbase`\n(52:21369).\n\nFigma also has a `Property=Name` axis — wordmark only, no mark — but both\nof its variants currently render the placeholder text \"raza\" rather than\n\"IonBase\", in an unbound raw colour. That is leftover debug content, not a\nreal asset, so it is not implemented here. Reproducing it would ship a\nstranger's name into a design system; extending `LogoMark` alone already\ncovers \"no wordmark\" for the cases that are real.",
   "import": "import { Logo } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The full IonBase lockup — mark plus wordmark.",
+  "useWhen": [
+    "the product needs to identify itself: header, sign-in page, empty state, marketing surface"
+  ],
+  "useInstead": [
+    {
+      "when": "space is tight, or a wordmark already appears nearby",
+      "use": "LogoMark"
+    },
+    {
+      "when": "you need any graphic that is not the brand",
+      "use": "Icon"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "the default — a 24px mark, which is what a header bar wants"
+      },
+      "lg": {
+        "use": "a 32px mark — sign-in, splash, or anywhere the brand is the subject"
+      }
+    },
+    "wordmark": {
+      "vector": {
+        "use": "the default and the safe choice — Figma's serif logotype as frozen artwork, immune to font substitution and visually distinct from the UI type"
+      },
+      "text": {
+        "use": "live, selectable Host Grotesk at `text/tertiary` — for surfaces where the name should behave like text (copyable, searchable) rather than like a mark"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the wordmark carries the accessible name, so the mark beside it is not announced twice",
+      "artwork uses `currentColor` rather than Figma's baked hex, so it themes with the rest of the icon layer"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "recolouring the lockup with your own fill",
+      "why": "it inherits `icon/default`; overriding it is how a brand mark ends up failing contrast in one theme"
+    },
+    {
+      "dont": "putting the Logo inside a Link with its own text \"IonBase\"",
+      "why": "the name is announced twice; label the link, not both"
+    }
+  ],
   "stylesheet": "src/styles/logo.css",
   "tokens": [
     "--font-family-sans",

package/dist/meta/LogoMark.json

@@ -4,6 +4,44 @@
   "propsType": "LogoMarkProps",
   "description": "The bare icon glyph, no wordmark — what `Header` actually uses.\n\nColour comes from the `.ion-logo__mark` class (`icon/default`), not the SVG\nitself, so it themes the same way every other icon in the system does.",
   "import": "import { LogoMark } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The bare mark, no wordmark — what Header uses.",
+  "useWhen": [
+    "a wordmark is already visible nearby, or the bar is too narrow for the lockup",
+    "a favicon-scale identity marker inside the product"
+  ],
+  "useInstead": [
+    {
+      "when": "this is the only place the product names itself",
+      "use": "Logo",
+      "why": "a mark alone identifies nothing to someone who has not learned it yet"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "the default, 24px — header bars"
+      },
+      "lg": {
+        "use": "32px — sign-in and other brand-forward surfaces"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` when the mark stands alone — it is the only thing naming it"
+    ],
+    "notes": [
+      "Omit `label` when a visible wordmark sits beside it; that text already carries the name."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`label=\"logo\"`",
+      "do": "`label=\"IonBase\"`",
+      "why": "the name of the brand is the useful announcement; the word \"logo\" is not"
+    }
+  ],
   "stylesheet": "src/styles/logo.css",
   "tokens": [
     "--font-family-sans",

package/dist/meta/Menu.json

@@ -4,6 +4,60 @@
   "propsType": "MenuProps",
   "description": "Menu is the list surface, not a popover.\n\nFigma models the list alone — there is no trigger, anchor or open state in\nthe design — so this renders the surface and nothing else. Positioning it\nagainst a button is the caller's job until Figma has a component that says\nhow. Building a popover here would be inventing design, and it would be the\nhard half to unpick later.\n\n`role=\"menu\"` is deliberately NOT set. A real ARIA menu owes the user\nroving-tabindex arrow navigation, typeahead and focus containment; claiming\nthe role without them is worse for a screen-reader user than an honest list,\nbecause it promises interactions that are not there. When the popover exists,\nthe role comes with it.",
   "import": "import { Menu } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "The list surface only — no trigger, no anchor, no open state. Positioning it is the caller's job.",
+  "useWhen": [
+    "rendering a list of actions or options as a surface you have already positioned",
+    "the rows need icons, a selected check, or two lines — more than a native <select> can hold"
+  ],
+  "useInstead": [
+    {
+      "when": "you want a self-contained dropdown with a trigger and open state",
+      "use": "Popover",
+      "why": "Menu is the surface alone; Popover owns the trigger, positioning, focus containment and Escape"
+    },
+    {
+      "when": "one value is picked from a modest list of plain text options",
+      "use": "Select",
+      "why": "the native picker brings keyboard handling, type-ahead and the mobile platform picker for free"
+    },
+    {
+      "when": "it is primary navigation rather than a dropdown",
+      "use": "NavItem"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Menu",
+      "MenuItem"
+    ],
+    "example": "<Menu><MenuItem icon={<Icon as={Copy} />}>Duplicate</MenuItem><MenuItem isSelected>Archive</MenuItem></Menu>"
+  },
+  "slots": {
+    "children": {
+      "accepts": "MenuItem"
+    }
+  },
+  "a11y": {
+    "role": "none — it is a plain <ul>",
+    "guarantees": [
+      "no `role=\"menu\"`, deliberately: a real ARIA menu owes the user roving tabindex, arrow-key navigation and typeahead, and claiming the role without them promises interactions that are not there"
+    ],
+    "notes": [
+      "Each MenuItem is a real <button>, so Tab reaches every row. That is honest, and it is not the same as arrow-key menu navigation.",
+      "The role arrives when the popover that owns it does."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "adding `role=\"menu\"` yourself",
+      "why": "the keyboard behaviour that role promises is not implemented; an honest list is better for a screen-reader user than a lying menu"
+    },
+    {
+      "dont": "using Menu as a dropdown without positioning it",
+      "why": "it renders in flow — it has no anchor logic of its own"
+    }
+  ],
   "stylesheet": "src/styles/menu.css",
   "tokens": [
     "--border-focus",

package/dist/meta/MenuItem.json

@@ -3,6 +3,57 @@
   "source": "src/components/Menu.tsx",
   "propsType": "MenuItemProps",
   "import": "import { MenuItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+  "useWhen": [
+    "a row in a Menu surface"
+  ],
+  "useInstead": [
+    {
+      "when": "it is a top-level navigation destination",
+      "use": "NavItem"
+    },
+    {
+      "when": "it is a standalone action outside a list",
+      "use": "Button"
+    }
+  ],
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "leading icon; omit its `label` — the row's text names it"
+    },
+    "children": {
+      "accepts": "text",
+      "note": "the row label"
+    }
+  },
+  "a11y": {
+    "role": "button",
+    "guarantees": [
+      "`isSelected` sets `aria-pressed`, so the selected state is announced and not only drawn",
+      "the check glyph always occupies its slot, so rows never reflow as the selection moves"
+    ],
+    "requires": [
+      "a text label in `children`"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "using MenuItem outside a Menu",
+      "why": "it renders an <li>, which is only valid inside a list"
+    },
+    {
+      "dont": "an icon-only MenuItem with no children",
+      "why": "the row announces nothing"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/menu.css",
   "tokens": [
     "--border-focus",

package/dist/meta/NavItem.json

@@ -4,6 +4,59 @@
   "propsType": "NavItemProps",
   "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
   "import": "import { NavItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
+  "useWhen": [
+    "building a header nav bar, a sidebar or a section switcher",
+    "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
+  ],
+  "useInstead": [
+    {
+      "when": "the link sits inside body copy or a content block",
+      "use": "Link"
+    },
+    {
+      "when": "it is a row in a dropdown list rather than a top-level destination",
+      "use": "MenuItem"
+    }
+  ],
+  "slots": {
+    "icon": {
+      "accepts": "Icon",
+      "note": "leading icon; omit its `label` — the item's text names it"
+    }
+  },
+  "a11y": {
+    "role": "link when `href` is set, button when it is not",
+    "guarantees": [
+      "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
+      "the focus ring shows for keyboard navigation only",
+      "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React"
+    ],
+    "requires": [
+      "an accessible name — `children`, or `aria-label` on an icon-only item"
+    ],
+    "notes": [
+      "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "`showChevron` on a plain link that navigates",
+      "why": "the chevron promises a menu; nothing opens"
+    },
+    {
+      "dont": "marking the current page with colour only",
+      "do": "`aria-current=\"page\"`",
+      "why": "a screen-reader user is otherwise never told where they are"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/nav-item.css",
   "tokens": [
     "--border-focus",

package/dist/meta/PhoneInput.json

@@ -4,6 +4,66 @@
   "propsType": "PhoneInputProps",
   "description": "PhoneInput — Figma `Input/Phone` (80:372).\n\nA dial-code block butted against an Input, sharing one outline: the block\ncarries the left radii and the control the right, so the seam is square on\nboth sides and reads as a single control. Both keep their full 1px border,\nwhich is what Figma draws — the 2px seam is the two strokes meeting, not an\naccident.\n\nThree sizes, no State axis. Every interaction state is the Input's, reached\nthrough the ordinary props, because Figma composes this from the same `Input`\ninstance rather than redrawing it.\n\nWHAT THIS DELIBERATELY DOES NOT DO\n\nIt does not pick countries. The chevron implies a menu and Figma specifies no\nopen state for it — no list, no flags, no search, no selected state. Country\ndata and the picker are application concerns with real editorial weight (which\nterritories, which names, which order), and inventing them here would be\ndesigning rather than implementing.\n\nSo the trigger is a real `<button>` with an accessible name, and\n`countryButtonProps` is how you wire it to a `Menu`, a popover or your own\nlistbox — including the `aria-haspopup` and `aria-expanded` that only the\nthing owning the popup can set honestly.",
   "import": "import { PhoneInput } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A dial-code block butted against an Input, sharing one outline. It does not pick countries.",
+  "useWhen": [
+    "collecting a phone number where the country calling code matters"
+  ],
+  "useInstead": [
+    {
+      "when": "the number is free-form and the code does not matter",
+      "use": "Input"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "slots": {
+    "trailingIcon": {
+      "accepts": "Icon",
+      "note": "passed through to the Input"
+    },
+    "countryButtonProps": {
+      "accepts": "button props",
+      "note": "how a country picker is attached — spread your trigger's props here, including the `aria-haspopup` and `aria-expanded` only the thing owning the popup can set honestly"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the dial-code trigger is a real <button> with an accessible name",
+      "every interaction state is the Input's, reached through the ordinary Input props"
+    ],
+    "requires": [
+      "`label`, or `aria-label` when no visible label is rendered",
+      "`countryLabel` if you change the default — the trigger shows only `+1`, which names a value rather than an action"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "expecting the chevron to open a country list",
+      "why": "the picker is deliberately not implemented — country data and ordering are editorial application decisions, and Figma specifies no open state. Wire your own through `countryButtonProps`"
+    },
+    {
+      "dont": "wrapping it in your own bordered container",
+      "why": "the block and the control already share one outline; a second border reads as two controls"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/phone-input.css",
   "tokens": [
     "--border-default",

package/dist/meta/Popover.json

@@ -4,6 +4,98 @@
   "propsType": "PopoverProps",
   "description": "Popover — Figma `Popover` (825:1853).\n\nSITS BETWEEN TOOLTIP AND MODAL. A tooltip is a hint that cannot hold\nfocusable content; a modal is a task that takes over the page. A popover\nholds interactive content but stays attached to the control that opened it.\n\n`usePopover` contains focus, closes on Escape or an outside click, and hides\nthe rest of the page from assistive tech while open — the same guarantees\nModal gives. What differs is the framing, and it is deliberate: no visible\nscrim, anchored to its trigger, and `surface/raised` rather than Modal's\n`surface/overlay`. It reads as attached to the page rather than replacing it.",
   "import": "import { Popover } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "An anchored panel that holds interactive content. Sits between Tooltip and Modal.",
+  "useWhen": [
+    "the content is interactive — a form, a filter, a list of actions — but should stay attached to the control that opened it",
+    "the surrounding page should stay visible and in context"
+  ],
+  "useInstead": [
+    {
+      "when": "the content is a short hint with nothing focusable in it",
+      "use": "Tooltip",
+      "why": "a tooltip cannot be focused or scrolled and closes when the pointer leaves"
+    },
+    {
+      "when": "the task takes over the page or must be completed before anything else",
+      "use": "Modal"
+    },
+    {
+      "when": "you only need the list surface and will position it yourself",
+      "use": "Menu"
+    }
+  ],
+  "variants": {
+    "placement": {
+      "top": {
+        "use": "above the trigger"
+      },
+      "bottom": {
+        "use": "below the trigger — the usual choice for a control in a header"
+      },
+      "left": {
+        "use": "to the left of the trigger"
+      },
+      "right": {
+        "use": "to the right of the trigger"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "a couple of actions or one short field"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a small form or a filter panel"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "Button",
+      "note": "the trigger. Must forward both a ref and DOM props — every component in this library does"
+    },
+    "content": {
+      "accepts": "any"
+    },
+    "title": {
+      "accepts": "text",
+      "note": "also gives the dialog its accessible name"
+    },
+    "footer": {
+      "accepts": "Button",
+      "note": "action row, right-aligned"
+    }
+  },
+  "a11y": {
+    "role": "dialog",
+    "guarantees": [
+      "focus is contained while open, Escape and outside clicks close it, and the rest of the page is hidden from assistive tech",
+      "`placement` is a preference, not a guarantee — it flips when there is no room, and the arrow follows"
+    ],
+    "requires": [
+      "`title`, or `aria-label` on the popover — a dialog with no name announces nothing about what opened"
+    ],
+    "notes": [
+      "`placement` names where the POPOVER sits, not where the arrow points."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a function-component trigger that drops its ref",
+      "why": "it renders, but the popover has nothing to position against"
+    },
+    {
+      "dont": "using a Popover where a Modal belongs",
+      "why": "a popover closes on an outside click; a task that must be finished should not be dismissible by a stray click"
+    },
+    {
+      "dont": "nesting a Popover inside another Popover",
+      "why": "two overlapping focus containments, and dismissing the outer one takes the inner one with it"
+    }
+  ],
   "stylesheet": "src/styles/popover.css",
   "tokens": [
     "--border-subtle",

package/dist/meta/Radio.json

@@ -3,6 +3,83 @@
   "source": "src/components/Radio.tsx",
   "propsType": "RadioProps",
   "import": "import { Radio } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One option inside a RadioGroup. Meaningless on its own — the group owns the name and the selected value.",
+  "useWhen": [
+    "a child of RadioGroup"
+  ],
+  "useInstead": [
+    {
+      "when": "the user may pick more than one",
+      "use": "Checkbox"
+    },
+    {
+      "when": "there are more than about five options",
+      "use": "Select",
+      "why": "a long radio list costs vertical space no one reads"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "touch targets and prominent choices"
+      }
+    },
+    "intent": {
+      "brand": {
+        "use": "the default"
+      },
+      "neutral": {
+        "use": "a choice with no positive reading — sort order, display mode"
+      },
+      "danger": {
+        "use": "selecting a destructive option"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the option's visible label"
+    }
+  },
+  "a11y": {
+    "role": "radio",
+    "guarantees": [
+      "`name` and the selected value come from the group's context, so no Radio has to repeat them",
+      "`isDisabled` falls back to the group's"
+    ],
+    "requires": [
+      "a `value` unique within the group",
+      "a text label in `children`"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Radio outside a RadioGroup",
+      "why": "it has no name and no siblings, so it can be selected but never unselected"
+    },
+    {
+      "dont": "wiring `checked`/`onChange` on each Radio",
+      "why": "the group owns selection; per-option wiring is what the context exists to remove"
+    },
+    {
+      "dont": "a group of one radio",
+      "why": "a single radio cannot be cleared once chosen — that is a Checkbox"
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled"
+    }
+  ],
   "stylesheet": "src/styles/radio.css",
   "tokens": [
     "--border-disabled",