ionbase-ui 0.16.0 → 0.18.0

package/dist/meta/Button.json

@@ -0,0 +1,556 @@
+{
+  "name": "Button",
+  "source": "src/components/Button.tsx",
+  "propsType": "ButtonProps",
+  "import": "import { Button } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Triggers an action in place. Never navigates.",
+  "useWhen": [
+    "the interaction performs an action — submit, save, delete, open a dialog",
+    "the result stays on the current page"
+  ],
+  "useInstead": [
+    {
+      "when": "it navigates to a URL or changes route",
+      "use": "Link",
+      "why": "Link renders an <a>. Middle-click, cmd-click, copy-link-address and 'open in new tab' all work on an anchor and none of them work on a button."
+    },
+    {
+      "when": "it toggles a persistent boolean setting",
+      "use": "Toggle",
+      "why": "a toggle announces its on/off state; a button announces only its name"
+    }
+  ],
+  "variants": {
+    "variant": {
+      "primary-brand": {
+        "use": "the single most important action in a view",
+        "limit": "one per view or dialog"
+      },
+      "primary-neutral": {
+        "use": "a primary action that should not carry brand colour"
+      },
+      "primary-soft": {
+        "use": "a primary action on a dense or already-colourful surface"
+      },
+      "secondary": {
+        "use": "supporting actions shown alongside a primary one"
+      },
+      "tertiary": {
+        "use": "low-emphasis actions — Cancel, Back, inline row actions"
+      },
+      "destructive": {
+        "use": "irreversible actions",
+        "requires": "a Modal confirmation before the action runs"
+      },
+      "success": {
+        "use": "confirms the end of a flow. Rarely the right answer — prefer primary-brand."
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "table rows, toolbars, dense layouts"
+      },
+      "md": {
+        "use": "the default; forms and page-level actions"
+      },
+      "lg": {
+        "use": "prominent standalone actions"
+      },
+      "xl": {
+        "use": "marketing and empty-state calls to action"
+      }
+    }
+  },
+  "slots": {
+    "startIcon": {
+      "accepts": "Icon",
+      "note": "omit Icon's `label` — the Button's own text already names it, and a labelled icon is announced twice"
+    },
+    "endIcon": {
+      "accepts": "Icon",
+      "note": "same as startIcon"
+    }
+  },
+  "a11y": {
+    "role": "button",
+    "guarantees": [
+      "the focus ring appears for keyboard focus and not for a mouse click",
+      "hover does not latch on touch devices"
+    ],
+    "requires": [
+      "an accessible name — `children`, or `aria-label` when the button is icon-only"
+    ],
+    "knownIssues": [
+      {
+        "pairing": "--text-primary on --surface-primary-subtle-hover",
+        "mode": "Dark",
+        "ratio": 4.25,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "hover"
+        ],
+        "status": "known, not yet fixed",
+        "where": "Button variant=primary-soft, hover",
+        "appliesTo": {
+          "component": "Button",
+          "props": {
+            "variant": "primary-soft"
+          }
+        }
+      },
+      {
+        "pairing": "--text-primary on --surface-primary-tint",
+        "mode": "Dark",
+        "ratio": 4.25,
+        "required": 4.5,
+        "sc": "1.4.3",
+        "states": [
+          "pressed"
+        ],
+        "status": "known, not yet fixed",
+        "where": "Button variant=primary-soft, pressed",
+        "appliesTo": {
+          "component": "Button",
+          "props": {
+            "variant": "primary-soft"
+          }
+        }
+      }
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Button onPress={() => router.push('/settings')}>Settings</Button>",
+      "do": "<Link href=\"/settings\">Settings</Link>",
+      "why": "a button that navigates breaks middle-click, cmd-click and copy-link, and is announced as a button rather than a link"
+    },
+    {
+      "dont": "two variant=\"primary-brand\" buttons in the same dialog",
+      "do": "one primary-brand, the rest secondary or tertiary",
+      "why": "two primaries is the same as none — nothing indicates the expected action"
+    },
+    {
+      "dont": "<Button variant=\"destructive\" onPress={deleteAccount}>",
+      "do": "open a Modal first and put the destructive Button in its footer",
+      "why": "irreversible actions need a confirmation step"
+    },
+    {
+      "dont": "<Button><Icon as={Trash} /></Button>",
+      "do": "<Button aria-label=\"Delete\"><Icon as={Trash} /></Button>",
+      "why": "an icon-only button with no aria-label is announced as just 'button'"
+    },
+    {
+      "dont": "<Button onClick={...}>",
+      "do": "<Button onPress={...}>",
+      "why": "onPress is React Aria's unified pointer/keyboard/touch handler. onClick works but skips the touch and keyboard normalisation the rest of the system relies on."
+    }
+  ],
+  "deprecated": [
+    {
+      "prop": "disabled",
+      "replacement": "isDisabled",
+      "note": "still type-checks, so this will not fail loudly"
+    }
+  ],
+  "stylesheet": "src/styles/button.css",
+  "tokens": [
+    "--border-disabled",
+    "--border-error-strong",
+    "--border-inverse",
+    "--border-primary",
+    "--border-primary-strong",
+    "--border-primary-subtle",
+    "--border-strong",
+    "--border-stronger",
+    "--border-success-strong",
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-lg",
+    "--icon-size-md",
+    "--icon-size-xs",
+    "--ion-button-elevation",
+    "--ion-button-font-size",
+    "--ion-button-gap",
+    "--ion-button-icon-size",
+    "--ion-button-inset-flush",
+    "--ion-button-inset-lifted",
+    "--ion-button-line-height",
+    "--ion-button-padding-x",
+    "--ion-button-pressed",
+    "--ion-button-raised",
+    "--ion-button-ring",
+    "--ion-button-size",
+    "--ion-duration-base",
+    "--ion-duration-fast",
+    "--ion-ease-out",
+    "--ion-shadow-focus-md",
+    "--ion-shadow-inset-flush-lg",
+    "--ion-shadow-inset-flush-sm",
+    "--ion-shadow-inset-flush-xs",
+    "--ion-shadow-inset-lifted-lg",
+    "--ion-shadow-inset-lifted-sm",
+    "--ion-shadow-inset-lifted-xs",
+    "--ion-shadow-none",
+    "--ion-shadow-raised-lifted-lg",
+    "--ion-shadow-raised-lifted-sm",
+    "--ion-shadow-raised-lifted-xs",
+    "--radius-md",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-40",
+    "--spacing-48",
+    "--spacing-56",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-error",
+    "--surface-error-hover",
+    "--surface-error-pressed",
+    "--surface-inverse",
+    "--surface-inverse-subtle",
+    "--surface-muted",
+    "--surface-page",
+    "--surface-primary",
+    "--surface-primary-hover",
+    "--surface-primary-pressed",
+    "--surface-primary-subtle",
+    "--surface-primary-subtle-hover",
+    "--surface-primary-tint",
+    "--surface-success",
+    "--surface-success-hover",
+    "--surface-success-pressed",
+    "--text-disabled",
+    "--text-on-color",
+    "--text-primary",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-md",
+    "--type-body-md-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "variant": {
+      "type": "\"success\" | \"primary-brand\" | \"primary-neutral\" | \"primary-soft\" | \"secondary\" | \"tertiary\" | \"destructive\" | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The visual style variant of the button.",
+      "values": [
+        "success",
+        "primary-brand",
+        "primary-neutral",
+        "primary-soft",
+        "secondary",
+        "tertiary",
+        "destructive"
+      ],
+      "default": "primary-brand"
+    },
+    "size": {
+      "type": "\"sm\" | \"md\" | \"lg\" | \"xl\" | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The size of the button.",
+      "values": [
+        "sm",
+        "md",
+        "lg",
+        "xl"
+      ],
+      "default": "md"
+    },
+    "startIcon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Optional icon to render before the label."
+    },
+    "endIcon": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Optional icon to render after the label."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Additional CSS class names."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Children element to render inside the button."
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the button is disabled."
+    },
+    "onPress": {
+      "type": "((e: PressEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the press is released over the target."
+    },
+    "onPressStart": {
+      "type": "((e: PressEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a press interaction starts."
+    },
+    "onPressEnd": {
+      "type": "((e: PressEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a press interaction ends, either\nover the target or when the pointer leaves the target."
+    },
+    "onPressChange": {
+      "type": "((isPressed: boolean) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the press state changes."
+    },
+    "onPressUp": {
+      "type": "((e: PressEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a press is released over the target, regardless of\nwhether it started on the target or not."
+    },
+    "onClick": {
+      "type": "((e: MouseEvent<FocusableElement>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "**Not recommended – use `onPress` instead.** `onClick` is an alias for `onPress`\nprovided for compatibility with other libraries. `onPress` provides\nadditional event details for non-mouse interactions."
+    },
+    "autoFocus": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the element should receive focus on render."
+    },
+    "onFocus": {
+      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element receives focus."
+    },
+    "onBlur": {
+      "type": "((e: FocusEvent<Element, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element loses focus."
+    },
+    "onFocusChange": {
+      "type": "((isFocused: boolean) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element's focus status changes."
+    },
+    "onKeyDown": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is pressed."
+    },
+    "onKeyUp": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is released."
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A URL to link to if elementType=\"a\"."
+    },
+    "target": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The target window for the link."
+    },
+    "rel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
+    },
+    "elementType": {
+      "type": "JSXElementConstructor<any> | \"button\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The HTML element or React element used to render the button, e.g. 'div', 'a', or `RouterLink`.",
+      "tags": {
+        "default": "'button'"
+      }
+    },
+    "aria-disabled": {
+      "type": "boolean | \"true\" | \"false\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates whether the element is disabled to users of assistive technology."
+    },
+    "aria-expanded": {
+      "type": "boolean | \"true\" | \"false\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates whether the element, or another grouping element it controls, is currently expanded\nor collapsed."
+    },
+    "aria-haspopup": {
+      "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+    },
+    "aria-controls": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+    },
+    "aria-pressed": {
+      "type": "boolean | \"true\" | \"false\" | \"mixed\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates the current \"pressed\" state of toggle buttons."
+    },
+    "aria-current": {
+      "type": "boolean | \"true\" | \"false\" | \"page\" | \"step\" | \"location\" | \"date\" | \"time\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates whether this element represents the current item within a container or set of related\nelements."
+    },
+    "type": {
+      "type": "\"button\" | \"submit\" | \"reset\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The behavior of the button when used in an HTML form.",
+      "values": [
+        "button",
+        "submit",
+        "reset"
+      ],
+      "tags": {
+        "default": "'button'"
+      }
+    },
+    "preventFocusOnPress": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to prevent focus from moving to the button when pressing it.\n\nCaution, this can make the button inaccessible and should only be used when alternative\nkeyboard interaction is provided, such as ComboBox's MenuTrigger or a NumberField's\nincrement/decrement control."
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the button with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button#form)."
+    },
+    "formAction": {
+      "type": "string | ((formData: FormData) => void | Promise<void>) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The URL that processes the information submitted by the button.\nOverrides the action attribute of the button's form owner."
+    },
+    "formEncType": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates how to encode the form data that is submitted."
+    },
+    "formMethod": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates the HTTP method used to submit the form."
+    },
+    "formNoValidate": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates that the form is not to be validated when it is submitted."
+    },
+    "formTarget": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Overrides the target attribute of the button's form owner."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Submitted as a pair with the button's value as part of the form data."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The value associated with the button's name when it's submitted with the form data."
+    },
+    "excludeFromTabOrder": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Defines a string value that labels the current element."
+    },
+    "aria-labelledby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that labels the current element."
+    },
+    "aria-describedby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that describes the object."
+    },
+    "aria-details": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+    }
+  },
+  "propCounts": {
+    "own": 7,
+    "aria": 39,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/Checkbox.json

@@ -0,0 +1,113 @@
+{
+  "name": "Checkbox",
+  "source": "src/components/Checkbox.tsx",
+  "propsType": "CheckboxProps",
+  "description": "Checkbox wraps a native `<input type=\"checkbox\">` and hides it.\n\nThe native input is kept rather than replaced by a div with `role=checkbox`\nbecause it brings form association, the indeterminate property, label\nclicking, and correct announcement — none of which are free to reimplement,\nand all of which are easy to get subtly wrong.\n\n`indeterminate` is the reason for the effect below: HTML has no\n`indeterminate` attribute, only a DOM property, so React cannot set it\ndeclaratively and it must be written after every render.",
+  "import": "import { Checkbox } from 'ionbase-ui';",
+  "stylesheet": "src/styles/checkbox.css",
+  "tokens": [
+    "--border-disabled",
+    "--border-error-strong",
+    "--border-focus",
+    "--border-inverse",
+    "--border-primary-strong",
+    "--border-stronger",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--icon-disabled",
+    "--icon-on-color",
+    "--ion-checkbox-border",
+    "--ion-checkbox-fill",
+    "--ion-checkbox-font-size",
+    "--ion-checkbox-gap",
+    "--ion-checkbox-line-height",
+    "--ion-checkbox-mark",
+    "--ion-checkbox-radius",
+    "--ion-checkbox-raised",
+    "--ion-checkbox-size",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-shadow-raised-flush-lg",
+    "--ion-shadow-raised-flush-sm",
+    "--ion-shadow-raised-flush-xs",
+    "--radius-sm",
+    "--radius-xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-error",
+    "--surface-inverse",
+    "--surface-primary",
+    "--text-disabled",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "size": {
+      "type": "CheckboxSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "intent": {
+      "type": "CheckboxIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Color` variant: Brand, Neutral, Danger.",
+      "values": [
+        "neutral",
+        "brand",
+        "danger"
+      ],
+      "default": "brand"
+    },
+    "isIndeterminate": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Indeterminate` state. Not an HTML attribute — `indeterminate` is a\nDOM property only, so it has to be assigned after render.",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Whether the checkbox is disabled."
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Figma's `Show Label` + `Label`. Omit for a bare box."
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 304,
+    "other": 0
+  }
+}