ionbase-ui 0.51.0 → 0.59.0

package/dist/meta/Drawer.json

@@ -0,0 +1,234 @@
+{
+  "name": "Drawer",
+  "source": "src/components/Drawer.tsx",
+  "propsType": "DrawerProps",
+  "description": "Drawer — a modal panel anchored to an edge.\n\nWHY IT IS A MODAL AND NOT A SIDEBAR\n\nIt takes focus, traps it, closes on Escape and on an outside click, and marks\nthe rest of the page inert — all of `Modal`'s behaviour, differing only in\nwhere the panel sits and how it enters. A persistent side panel that does not\ndo those things is layout, not a drawer, and belongs in the page rather than\nin an overlay.\n\nWHEN TO REACH FOR MODAL INSTEAD\n\nA drawer suits work that is long or list-shaped — filters, a record's detail,\na sequence of settings — because an edge panel can be tall without becoming a\nsquare that fights the viewport. A decision, especially a destructive one,\nbelongs in a Modal: it is centred, it is smaller, and it does not invite\nscrolling past the thing being confirmed.\n\nRENDERS NOTHING WHEN CLOSED, and portals when open, for the reasons recorded\non Modal: a closed overlay left in the tree is still keyboard-focusable, and\nan inline one inherits whatever `overflow` and stacking context surrounds it.",
+  "import": "import { Drawer } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A modal panel anchored to an edge. Modal behaviour — focus trap, Escape, scrim — with the shape of a side panel.",
+  "useWhen": [
+    "work that is long or list-shaped: filters, a record's detail, a run of settings",
+    "the page behind should stay visible as context while a task is done beside it",
+    "a form long enough that a centred dialog would scroll its own actions off screen"
+  ],
+  "useInstead": [
+    {
+      "when": "the user is making a decision, especially a destructive one",
+      "use": "Modal",
+      "why": "a modal is centred and small enough that the thing being confirmed cannot be scrolled past"
+    },
+    {
+      "when": "the panel should stay open while the user works elsewhere",
+      "use": "page layout",
+      "why": "a drawer traps focus and marks the rest of the page inert. A panel that does not do those things is layout, not an overlay"
+    },
+    {
+      "when": "the content is a short menu of actions",
+      "use": "Popover or Menu"
+    }
+  ],
+  "variants": {
+    "placement": {
+      "start": {
+        "use": "navigation and hierarchy, which readers expect at the leading edge"
+      },
+      "end": {
+        "use": "the default — detail and editing beside the record that opened it"
+      },
+      "top": {
+        "use": "rare: a global search or command surface"
+      },
+      "bottom": {
+        "use": "touch-first layouts, where the bottom edge is the reachable one"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "a short form or a filter list"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a record detail with its own sections"
+      }
+    }
+  },
+  "slots": {
+    "title": {
+      "accepts": "text",
+      "note": "required — it is the dialog's accessible name"
+    },
+    "description": {
+      "accepts": "text"
+    },
+    "children": {
+      "accepts": "any content",
+      "note": "the only scrolling region"
+    },
+    "footer": {
+      "accepts": "Button",
+      "note": "pinned to the bottom edge, so actions stay reachable in a long panel"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`title`, which becomes the dialog's accessible name via aria-labelledby"
+    ],
+    "notes": [
+      "start and end follow writing direction, so a right-hand drawer in English is a left-hand one in Arabic with no second variant",
+      "renders nothing when closed and portals when open: a closed overlay left in the tree is still keyboard-focusable",
+      "only the body scrolls, so the title stays on screen — the one piece of context a user needs while working down a long list"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Drawer that stays open while the user edits the page behind it",
+      "do": "a layout panel",
+      "why": "it traps focus and marks the rest inert; a keyboard user cannot reach the page behind it"
+    },
+    {
+      "dont": "<Drawer> for a delete confirmation",
+      "do": "<Modal>",
+      "why": "an edge panel is tall, so the confirm button can sit below the fold — the one control that must never be missed"
+    }
+  ],
+  "stylesheet": "src/styles/drawer.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-semibold",
+    "--icon-secondary",
+    "--icon-size-md",
+    "--ion-drawer-size",
+    "--radius-lg",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-hover",
+    "--surface-raised",
+    "--surface-scrim",
+    "--text-default",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-h5",
+    "--type-h5-line-height"
+  ],
+  "props": {
+    "isOpen": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Whether the drawer is shown."
+    },
+    "onOpenChange": {
+      "type": "((isOpen: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Called with the next open state — `false` when the drawer asks to close."
+    },
+    "placement": {
+      "type": "DrawerPlacement | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Which edge it enters from. `start` and `end` follow writing direction, so\na right-hand drawer in English is a left-hand one in Arabic without a\nsecond variant.",
+      "values": [
+        "start",
+        "end",
+        "top",
+        "bottom"
+      ],
+      "default": "end"
+    },
+    "size": {
+      "type": "DrawerSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "title": {
+      "type": "React.ReactNode",
+      "required": true,
+      "origin": "own",
+      "description": "Required: the dialog's accessible name, wired via `aria-labelledby`."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Supporting copy under the title."
+    },
+    "footer": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Action row, pinned to the bottom edge."
+    },
+    "showClose": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "default": true
+    },
+    "closeLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "default": "Close drawer"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isDismissable": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to close the modal when the user interacts outside it.",
+      "tags": {
+        "default": "false"
+      }
+    },
+    "isKeyboardDismissDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether pressing the escape key to close the modal should be disabled.",
+      "tags": {
+        "default": "false"
+      }
+    },
+    "shouldCloseOnInteractOutside": {
+      "type": "((element: Element) => boolean) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "When user interacts with the argument element outside of the overlay ref,\nreturn true if onClose should be called.  This gives you a chance to filter\nout interaction with elements that should not dismiss the overlay.\nBy default, onClose will always be called on interaction outside the overlay ref."
+    }
+  },
+  "propCounts": {
+    "own": 11,
+    "aria": 3,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/EmptyState.json

@@ -130,7 +130,7 @@
   "stylesheet": "src/styles/empty-state.css",
   "tokens": [
     "--font-family-sans",
-    "--font-weight-medium",
+    "--font-weight-semibold",
     "--icon-error",
     "--icon-primary",
     "--icon-size-md",

package/dist/meta/FileUpload.json

@@ -0,0 +1,246 @@
+{
+  "name": "FileUpload",
+  "source": "src/components/FileUpload.tsx",
+  "propsType": "FileUploadProps",
+  "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
+  "import": "import { FileUpload } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
+  "useWhen": [
+    "the user attaches one or more files to a form or a message",
+    "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
+  ],
+  "useInstead": [
+    {
+      "when": "a single file is picked and no drop target or file list is wanted",
+      "use": "a plain <input type=\"file\">",
+      "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
+    },
+    {
+      "when": "upload progress needs to be shown",
+      "use": "ProgressBar",
+      "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "inside a dense form, or beside other fields"
+      },
+      "md": {
+        "use": "the default — a standalone attachment area"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
+      "the zone is a <label> for that input, so clicking anywhere opens the picker without any script",
+      "the input is clipped to 1px rather than display:none, which would remove it from the tab order and the accessibility tree",
+      "the focus ring is drawn on the zone, where the user is looking, not on the clipped input",
+      "a polite live region announces the number of files held, because a drop changes nothing near the user's focus",
+      "dragging is signalled by a solid border as well as a colour, so it is not conveyed by colour alone (WCAG 1.4.1)",
+      "each remove button is a 24px target with a name that includes the file (WCAG 2.5.8)"
+    ],
+    "requires": [
+      "`label`, or an `aria-label` — an unnamed file input announces only as \"button\"",
+      "`hint` describing the accepted types and size limit, since `accept` itself is never announced"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "treating `accept` or `maxSize` as validation",
+      "why": "both are client-side and advisory. A browser does not enforce `accept` on drop, and every platform picker offers an \"All files\" escape. The server must check again"
+    },
+    {
+      "dont": "rebuilding this as a div with onClick={() => inputRef.current.click()}",
+      "why": "that version has no accessible name, no tab stop, no form participation and no keyboard path — it is the usual build of this component and the usual defect"
+    },
+    {
+      "dont": "putting the file list inside the drop zone",
+      "why": "the zone is a label, so every row in it — including each remove button — would also open the file picker"
+    },
+    {
+      "dont": "using `onChange` as a delta",
+      "why": "it fires with the complete list after every add and every remove, never with what changed"
+    }
+  ],
+  "slots": {
+    "prompt": {
+      "expects": "the call to action inside the zone"
+    },
+    "hint": {
+      "expects": "the constraints in words — \"PNG or JPG, up to 5 MB\""
+    }
+  },
+  "stylesheet": "src/styles/file-upload.css",
+  "tokens": [
+    "--border-default",
+    "--border-disabled",
+    "--border-error",
+    "--border-focus",
+    "--border-strong",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-default",
+    "--icon-disabled",
+    "--icon-secondary",
+    "--icon-size-lg",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-file-upload-gap",
+    "--ion-file-upload-icon-size",
+    "--ion-file-upload-padding",
+    "--radius-md",
+    "--radius-sm",
+    "--ring-focus",
+    "--spacing-12",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-hover",
+    "--surface-primary-subtle",
+    "--surface-subtle",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Field label. Also the accessible name of the file input."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Helper text below the control."
+    },
+    "errorMessage": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Replaces the helper text when `isInvalid` is set."
+    },
+    "isInvalid": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "size": {
+      "type": "FileUploadSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches the Figma `Size` variant when drawn. Height of the drop target.",
+      "values": [
+        "sm",
+        "md"
+      ]
+    },
+    "accept": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Native `accept` — a comma-separated list of extensions or MIME types."
+    },
+    "multiple": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Allow more than one file."
+    },
+    "maxSize": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Reject anything larger, in bytes."
+    },
+    "maxFiles": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Reject once this many files are held. Only meaningful with `multiple`."
+    },
+    "files": {
+      "type": "readonly File[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The files held. Pass it to control the list; omit and the component keeps\nits own. A controlled list is the usual case, because the caller is the\nonly thing that knows which uploads have since succeeded or failed."
+    },
+    "onChange": {
+      "type": "((files: File[]) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires with the full list after every add or remove, never with a delta."
+    },
+    "onReject": {
+      "type": "((rejected: RejectedFile[]) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires with anything refused by `accept`, `maxSize` or `maxFiles`."
+    },
+    "prompt": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Call-to-action inside the drop target."
+    },
+    "hint": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Second line inside the drop target — the constraints, in words."
+    },
+    "removeLabel": {
+      "type": "((name: string) => string) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible label for each file's remove button. Receives the file name."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 20,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/PhoneInput.json

@@ -122,41 +122,11 @@
       "origin": "own",
       "description": "Spread onto the dial-code `<button>`. This is how a country picker gets\nattached — see the note on scope below."
     },
-    "type": {
-      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
-      "tags": {
-        "default": "'text'"
-      },
-      "default": "tel"
-    },
-    "disabled": {
-      "type": "boolean | undefined",
-      "required": false,
-      "origin": "own",
-      "tags": {
-        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-      }
-    },
-    "form": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The `<form>` element to associate the input 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/input#form)."
-    },
-    "name": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
-    },
-    "value": {
-      "type": "string | undefined",
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
       "required": false,
       "origin": "aria",
-      "description": "The current value (controlled)."
+      "description": "Handler that is called when the value changes."
     },
     "defaultValue": {
       "type": "string | undefined",
@@ -347,12 +317,6 @@
       "origin": "aria",
       "description": "Handler that is called when the element loses focus."
     },
-    "onChange": {
-      "type": "((value: string) => void) | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "Handler that is called when the value changes."
-    },
     "onBeforeInput": {
       "type": "FormEventHandler<HTMLInputElement> | undefined",
       "required": false,
@@ -383,6 +347,42 @@
       "origin": "aria",
       "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
     },
+    "type": {
+      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+      "tags": {
+        "default": "'text'"
+      },
+      "default": "tel"
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the input 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/input#form)."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
     "size": {
       "type": "InputSize | undefined",
       "required": false,

package/dist/meta/Popover.json

@@ -157,10 +157,10 @@
       "origin": "own",
       "description": "Matches the Figma `Placement` variant, and names where the POPOVER sits —\nnot where the arrow points. A preference, not a guarantee: it flips when\nthere is no room, and the arrow follows.",
       "values": [
-        "right",
-        "left",
         "top",
-        "bottom"
+        "bottom",
+        "right",
+        "left"
       ]
     },
     "size": {