ionbase-ui 0.16.0 → 0.17.0

package/README.md

@@ -172,13 +172,40 @@ icon sit correctly inside a Button.
 
 ## Entry points
 
-| Import                | What it is                                     |
-| --------------------- | ---------------------------------------------- |
-| `ionbase-ui`          | Components, `Icon`, and the `tokens` object    |
-| `ionbase-ui/styles`   | Everything: tokens + typography + components   |
-| `ionbase-ui/styles/*` | One component stylesheet, e.g. `button.css`    |
-| `ionbase-ui/tokens`   | Token custom properties only, no component CSS |
-| `ionbase-ui/tokens/*` | One token layer, e.g. `theme-dark.css`         |
+| Import                  | What it is                                          |
+| ----------------------- | --------------------------------------------------- |
+| `ionbase-ui`            | Components, `Icon`, and the `tokens` object         |
+| `ionbase-ui/styles`     | Everything: tokens + typography + components        |
+| `ionbase-ui/styles/*`   | One component stylesheet, e.g. `button.css`         |
+| `ionbase-ui/tokens`     | Token custom properties only, no component CSS      |
+| `ionbase-ui/tokens/*`   | One token layer, e.g. `theme-dark.css`              |
+| `ionbase-ui/meta/index` | Component index — names, summaries, variants (12KB) |
+| `ionbase-ui/meta`       | Every component's full contract in one file (180KB) |
+| `ionbase-ui/meta/*`     | One component's contract, e.g. `Button.json`        |
+
+## Machine-readable component contracts
+
+Every component ships a JSON contract describing not just its API but when to
+use it, what to use instead, and what tends to go wrong:
+
+```ts
+import index from 'ionbase-ui/meta/index' with { type: 'json' };
+import button from 'ionbase-ui/meta/Button.json' with { type: 'json' };
+```
+
+Each contract carries `summary`, `useWhen`, `useInstead`, `variants` with
+per-value guidance, `slots`, `a11y`, `antiPatterns`, `deprecated`, the generated
+`props` table, and the tokens its stylesheet consumes.
+
+This exists because the thing consuming a design system is increasingly a coding
+agent rather than a person reading documentation. **Start from
+`ionbase-ui/meta/index`** — 12KB, every component with its variants — then load
+the single contract you need. Loading all of them costs 180KB to answer a
+question the index already answered.
+
+Six components carry full intent today (`Button`, `Input`, `Select`, `Modal`,
+`Table`, `Alert`). The rest ship the generated API plus their source
+documentation, and are being filled in.
 
 Token values are also available as JavaScript, as `var(--…)` references:
 

package/dist/meta/Alert.json

@@ -0,0 +1,248 @@
+{
+  "name": "Alert",
+  "source": "src/components/Alert.tsx",
+  "propsType": "AlertProps",
+  "description": "Alert — Figma `Alert` (812:1902).\n\n`Intent` x `Emphasis` x `Layout`, with the parts as props rather than\nvariants. Intents match `Badge` exactly, so a status mapped to one can be\npassed to the other.\n\nROLE IS CHOSEN BY INTENT, NOT PASSED IN. `error` and `warning` render\n`role=\"alert\"`, which interrupts a screen reader; the rest render\n`role=\"status\"`, which waits for a pause. Getting this backwards is the\ncommon failure — a page of `role=\"alert\"` status messages talks over the\nuser, and an error announced as a status is missed.\n\nThe icon is decorative: it repeats what the intent's colour and copy already\nsay, so it is `aria-hidden` and the live region carries the text alone.",
+  "import": "import { Alert } from 'ionbase-ui';",
+  "status": "stable",
+  "since": "0.13.1",
+  "summary": "A persistent, in-page status message. Intent picks the ARIA role for you.",
+  "useWhen": [
+    "the message belongs to the page and should stay until the condition clears",
+    "form-level validation summaries, permission notices, degraded-state banners"
+  ],
+  "useInstead": [
+    {
+      "when": "the message is transient and self-dismissing",
+      "use": "Toast",
+      "why": "an Alert stays in the layout; a Toast does not"
+    },
+    {
+      "when": "it labels a value inline rather than telling the user something",
+      "use": "Badge",
+      "why": "Badge shares Alert's intent vocabulary exactly, so a status mapped to one passes to the other"
+    }
+  ],
+  "variants": {
+    "intent": {
+      "error": {
+        "use": "something failed and the user must act",
+        "aria": "role=alert — interrupts the screen reader"
+      },
+      "warning": {
+        "use": "something may fail or has degraded",
+        "aria": "role=alert — interrupts the screen reader"
+      },
+      "success": {
+        "use": "an operation completed",
+        "aria": "role=status"
+      },
+      "information": {
+        "use": "neutral context the user did not ask for",
+        "aria": "role=status"
+      },
+      "primary": {
+        "use": "product announcements and promotions",
+        "aria": "role=status"
+      },
+      "neutral": {
+        "use": "low-emphasis context",
+        "aria": "role=status"
+      }
+    },
+    "emphasis": {
+      "subtle": {
+        "use": "the default — tinted surface, readable in long pages"
+      },
+      "solid": {
+        "use": "reserve for a single high-stakes banner; it dominates the layout"
+      }
+    },
+    "layout": {
+      "inline": {
+        "use": "inside a form or card, in the flow of content"
+      },
+      "banner": {
+        "use": "full-bleed at the top of a page or region"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the role follows the intent — error and warning are role=alert, everything else role=status",
+      "the icon is aria-hidden, so the live region announces the text once and not the glyph"
+    ],
+    "requires": [
+      "`dismissLabel` when `onDismiss` is set and the surrounding copy does not name the action"
+    ],
+    "notes": [
+      "role=alert interrupts whatever the screen reader is saying; role=status waits for a pause. This is why the role is not a prop."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "using intent=\"error\" for a message that is merely informational",
+      "why": "error renders role=alert, which interrupts the screen reader. A page of interrupting status messages talks over the user."
+    },
+    {
+      "dont": "using intent=\"information\" for a genuine failure",
+      "why": "role=status waits for a pause, so a real error can be missed entirely"
+    },
+    {
+      "dont": "rendering an Alert conditionally for a transient confirmation",
+      "do": "useToast",
+      "why": "an Alert that appears and disappears shifts the layout under the user"
+    }
+  ],
+  "stylesheet": "src/styles/alert.css",
+  "tokens": [
+    "--border-default",
+    "--border-error-strong",
+    "--border-error-subtle",
+    "--border-information-strong",
+    "--border-information-subtle",
+    "--border-inverse",
+    "--border-primary-strong",
+    "--border-primary-subtle",
+    "--border-success-strong",
+    "--border-success-subtle",
+    "--border-warning-strong",
+    "--border-warning-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-regular",
+    "--icon-error",
+    "--icon-information",
+    "--icon-on-color",
+    "--icon-primary",
+    "--icon-secondary",
+    "--icon-size-md",
+    "--icon-success",
+    "--icon-warning",
+    "--ion-alert-border",
+    "--ion-alert-icon",
+    "--ion-alert-surface",
+    "--ion-alert-text",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-md",
+    "--radius-sm",
+    "--ring-focus",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-32",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-error-subtle",
+    "--surface-hover",
+    "--surface-information",
+    "--surface-information-subtle",
+    "--surface-inverse",
+    "--surface-muted",
+    "--surface-primary",
+    "--surface-primary-subtle",
+    "--surface-success",
+    "--surface-success-subtle",
+    "--surface-warning",
+    "--surface-warning-subtle",
+    "--text-error",
+    "--text-information",
+    "--text-link",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-success",
+    "--text-warning",
+    "--type-body",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "intent": {
+      "type": "AlertIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Intent` variant. Same vocabulary as `Badge`.",
+      "values": [
+        "neutral",
+        "primary",
+        "success",
+        "warning",
+        "error",
+        "information"
+      ],
+      "default": "information"
+    },
+    "emphasis": {
+      "type": "AlertEmphasis | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Emphasis` variant.",
+      "values": [
+        "subtle",
+        "solid"
+      ],
+      "default": "subtle"
+    },
+    "layout": {
+      "type": "AlertLayout | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Layout` variant.",
+      "values": [
+        "inline",
+        "banner"
+      ],
+      "default": "inline"
+    },
+    "title": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Optional heading above the message."
+    },
+    "hideIcon": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Hide the leading icon. Shown by default."
+    },
+    "icon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Replace the intent's glyph."
+    },
+    "actions": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Action buttons, rendered under the message."
+    },
+    "onDismiss": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Called when the dismiss button is pressed. Omit for no dismiss button."
+    },
+    "dismissLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible name for the dismiss button.",
+      "default": "Dismiss"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "The message."
+    }
+  },
+  "propCounts": {
+    "own": 10,
+    "aria": 0,
+    "dom": 276,
+    "other": 0
+  }
+}

package/dist/meta/Avatar.json

@@ -0,0 +1,97 @@
+{
+  "name": "Avatar",
+  "source": "src/components/Avatar.tsx",
+  "propsType": "AvatarProps",
+  "description": "Avatar picks its content the way Figma's `Type` variant does, but by\nprecedence rather than by a prop: image, then initials, then icon. A caller\npassing `src` and `initials` gets the image with the initials as its alt\nfallback, which is what you want when the image 404s.\n\nA failed `src` falls through to initials (then icon) rather than leaving the\nbrowser's broken-image glyph — that is why initials exist alongside `src`.\n\nIt is a `<span>`, not a `<div>`, so it can sit inline beside text without the\ncaller fighting a block element.",
+  "import": "import { Avatar } from 'ionbase-ui';",
+  "stylesheet": "src/styles/avatar.css",
+  "tokens": [
+    "--border-strong",
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-2xs",
+    "--icon-size-lg",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--icon-tertiary",
+    "--ion-avatar-font-size",
+    "--ion-avatar-group-overlap",
+    "--ion-avatar-icon",
+    "--ion-avatar-line-height",
+    "--ion-avatar-radius",
+    "--ion-avatar-size",
+    "--radius-full",
+    "--radius-md",
+    "--radius-sm",
+    "--radius-xs",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-40",
+    "--spacing-48",
+    "--surface-muted",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height",
+    "--type-h5",
+    "--type-h5-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "AvatarSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Size` variant: Mini 24, Small 32, Medium 40, Large 48.",
+      "values": [
+        "mini",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "shape": {
+      "type": "AvatarShape | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Shape` variant.",
+      "values": [
+        "circle",
+        "square"
+      ]
+    },
+    "src": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Image source. Figma's `Type=Image`."
+    },
+    "alt": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Describes the person, not the picture. Falls back to `initials` so the\navatar is never announced as an unlabelled image."
+    },
+    "initials": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Type=Character`. Rendered when there is no `src`, or when `src`\nfails to load."
+    },
+    "icon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Type=Icon`. Rendered when there is neither `src` nor `initials`."
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 278,
+    "other": 0
+  }
+}

package/dist/meta/AvatarGroup.json

@@ -0,0 +1,82 @@
+{
+  "name": "AvatarGroup",
+  "source": "src/components/Avatar.tsx",
+  "propsType": "AvatarGroupProps",
+  "description": "AvatarGroup overlaps its children by a quarter of the avatar size, matching\nFigma's -6 / -8 / -10 / -12 gaps at Mini / Small / Medium / Large.\n\nGroup defaults fill in `size` / `shape` only when a child Avatar has not set\nthem itself — an explicit child prop wins. Non-Avatar children are left\nalone so `size`/`shape` are never pushed onto arbitrary DOM nodes.\n\nChildren render in source order because that is Figma's stacking: each avatar\npaints over the one before it, so the `+N` overflow ends up on top. Later\nsiblings paint later, so this needs no z-index.",
+  "import": "import { AvatarGroup } from 'ionbase-ui';",
+  "stylesheet": "src/styles/avatar.css",
+  "tokens": [
+    "--border-strong",
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-2xs",
+    "--icon-size-lg",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--icon-tertiary",
+    "--ion-avatar-font-size",
+    "--ion-avatar-group-overlap",
+    "--ion-avatar-icon",
+    "--ion-avatar-line-height",
+    "--ion-avatar-radius",
+    "--ion-avatar-size",
+    "--radius-full",
+    "--radius-md",
+    "--radius-sm",
+    "--radius-xs",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-40",
+    "--spacing-48",
+    "--surface-muted",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height",
+    "--type-h5",
+    "--type-h5-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "AvatarSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "mini",
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "max": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Cap on avatars shown; the remainder becomes a `+N` overflow avatar."
+    },
+    "shape": {
+      "type": "AvatarShape | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "circle",
+        "square"
+      ]
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Badge.json

@@ -0,0 +1,83 @@
+{
+  "name": "Badge",
+  "source": "src/components/Badge.tsx",
+  "propsType": "BadgeProps",
+  "description": "Badge is presentational — no role, no interaction. React Aria has nothing to\noffer here, so this is a plain span rather than a hook wrapper for its own\nsake.\n\nIt carries no `status` or `alert` role on purpose: a badge is a label on\nsomething else, and announcing it as a live region would interrupt screen\nreader users on every render. Wrap it yourself if the value genuinely changes\nand matters.",
+  "import": "import { Badge } from 'ionbase-ui';",
+  "stylesheet": "src/styles/badge.css",
+  "tokens": [
+    "--border-default",
+    "--border-error-subtle",
+    "--border-information-subtle",
+    "--border-primary-subtle",
+    "--border-success-subtle",
+    "--border-warning-subtle",
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-error",
+    "--icon-information",
+    "--icon-primary",
+    "--icon-secondary",
+    "--icon-success",
+    "--icon-warning",
+    "--radius-full",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-error-subtle",
+    "--surface-information-subtle",
+    "--surface-muted",
+    "--surface-primary-subtle",
+    "--surface-success-subtle",
+    "--surface-warning-subtle",
+    "--text-error",
+    "--text-information",
+    "--text-link",
+    "--text-secondary",
+    "--text-success",
+    "--text-warning",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "intent": {
+      "type": "BadgeIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Intent` variant.",
+      "values": [
+        "neutral",
+        "primary",
+        "success",
+        "warning",
+        "error",
+        "information"
+      ]
+    },
+    "dot": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show the leading dot marker. Figma's `Show Dot` boolean.\nThe dot inherits the intent's foreground colour, so it needs no prop."
+    },
+    "icon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Leading icon. Figma's `Show Icon` + `Icon` swap. Mutually exclusive with `dot`."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}