ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/Combobox.json

@@ -0,0 +1,265 @@
+{
+  "name": "Combobox",
+  "source": "src/components/Combobox.tsx",
+  "propsType": "ComboboxProps",
+  "description": "Combobox — a text field that filters a list, with one selected value.\n\nDrawn in Figma as `Combobox` (1370:2359) — three sizes by seven states, the\nsame axes `Input` carries, because the field IS Input's box. The open list is\na second Figma component, `Combobox Menu`, with no React export behind it.\n\nWHY THIS IS NOT `Select` WITH A SEARCH BOX\n\n`Select` wraps a native `<select>`, whose list the browser owns: it cannot be\nfiltered, and its rows can only hold text. Everything above about twenty\noptions needs filtering, and `Select`'s own contract has pointed at \"a\ncombobox — not yet in this system\" since it was written. This is it.\n\nThe cost is that everything the native control gave away for free — keyboard\nhandling, the mobile picker, screen-reader semantics — now has to be built.\nReact Aria's `useComboBox` builds it: `role=\"combobox\"` with `aria-expanded`,\n`aria-controls` and `aria-activedescendant`, arrow keys that move a virtual\nfocus while the real focus stays in the input, and Escape that reverts.\n\nFILTERING IS LOCALE-AWARE, NOT `toLowerCase().includes()`\n\n`useFilter({ sensitivity: 'base' })` is `Intl.Collator` underneath, so\n\"resume\" matches \"résumé\" and Turkish dotted/dotless I behave the way a\nTurkish reader expects. The lowercase-and-includes version fails both, and\nfails them silently in exactly the locales least likely to be tested.",
+  "import": "import { Combobox } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A text field that filters a list of options down to one selected value.",
+  "useWhen": [
+    "the list is long enough that scanning it is worse than typing",
+    "the user picks exactly one value from a known set",
+    "the options carry a second line of context the native <select> cannot render"
+  ],
+  "useInstead": [
+    {
+      "when": "the list is short and fully scannable",
+      "use": "Select",
+      "why": "the native control brings keyboard handling and the mobile platform picker for free; this rebuilds all of it"
+    },
+    {
+      "when": "there are two or three mutually exclusive choices worth showing at once",
+      "use": "RadioGroup"
+    },
+    {
+      "when": "the value is free text and the list is only a convenience",
+      "use": "Input",
+      "why": "or set `allowsCustomValue`, which is the same decision made explicitly"
+    },
+    {
+      "when": "the rows are commands rather than values",
+      "use": "Menu",
+      "why": "options are selected and stay selected; menu items are invoked and the menu closes"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms, table filters"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "role=combobox with aria-expanded, aria-controls and aria-activedescendant, from react-aria's useComboBox",
+      "real focus never leaves the input; arrow keys move a virtual focus through the list, which is what keeps typing and browsing possible at once",
+      "the popover is non-modal, so the page behind stays readable and focus stays in the field",
+      "Escape reverts to the last committed value rather than clearing the field",
+      "filtering is Intl.Collator-based, so accents and locale-specific casing behave correctly",
+      "the empty message is a sibling of the listbox, not an option in it, so it is never counted, focused or selectable",
+      "the menu matches the field's width, clamped to the space right of it so a full-bleed field cannot push the menu past the viewport edge"
+    ],
+    "requires": [
+      "`label`, or an `aria-label` when no visible label is rendered",
+      "`emptyLabel` wording that says why nothing is listed, if the default is too terse"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "giving the disclosure button a tab stop",
+      "why": "the input already opens the list with ArrowDown. A second tab stop doubles the cost of tabbing past every combobox in a form and adds nothing"
+    },
+    {
+      "dont": "styling the focused option with :hover or :focus",
+      "why": "no option is ever either — focus is virtual. Use [data-focused], which react-aria sets for both pointer and keyboard"
+    },
+    {
+      "dont": "posting the input's text in a form",
+      "why": "the text is the label and the value is the key; pass `name` and the component posts the key in a hidden input"
+    },
+    {
+      "dont": "filtering with toLowerCase().includes()",
+      "why": "it fails on accents and on Turkish dotted/dotless I, silently, in the locales least likely to be tested"
+    },
+    {
+      "dont": "writing a width onto the menu from a ResizeObserver or any effect that runs while it is open",
+      "why": "a positioned popover that changes size feeds back into react-aria's positioning, and any scrollbar that results is read by useCloseOnScroll as a real scroll. The menu opens and closes within about a hundred milliseconds, which presents as a keyboard bug rather than a layout one"
+    }
+  ],
+  "slots": {
+    "emptyLabel": {
+      "expects": "what to show when the filter matches nothing"
+    }
+  },
+  "stylesheet": "src/styles/combobox.css",
+  "tokens": [
+    "--border-subtle",
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-disabled",
+    "--icon-secondary",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-input-icon-size",
+    "--ion-shadow-shadow-lg",
+    "--radius-md",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-hover",
+    "--surface-primary-subtle",
+    "--surface-raised",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "options": {
+      "type": "readonly ComboboxOption[]",
+      "required": true,
+      "origin": "own",
+      "description": "The full option list. Filtering happens here, against what is typed."
+    },
+    "label": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Field label. Required for a usable control — see `a11y.requires`."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Helper text below the field."
+    },
+    "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"
+    },
+    "isReadOnly": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "size": {
+      "type": "ComboboxSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "placeholder": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "selectedKey": {
+      "type": "string | null | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled selection. `null` means nothing is selected."
+    },
+    "defaultSelectedKey": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onSelectionChange": {
+      "type": "((key: string | null) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "inputValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled text. Usually only needed for async/remote filtering."
+    },
+    "defaultInputValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onInputChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "allowsCustomValue": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accept text that matches no option. Off by default: a combobox whose value\nis a free string is a text field with suggestions, and the caller should\nhave to say that is what they want."
+    },
+    "menuTrigger": {
+      "type": "\"focus\" | \"input\" | \"manual\" | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "What opens the list. `input` — react-aria's default and this one — opens it\non the first keystroke; the chevron opens it on demand. `focus` opens it\nthe moment the field is tabbed into, which is loud in a long form.",
+      "values": [
+        "focus",
+        "input",
+        "manual"
+      ]
+    },
+    "emptyLabel": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Shown in place of the list when nothing matches."
+    },
+    "buttonLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible label for the disclosure button."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Posts the selected value under this name, for an uncontrolled form."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 23,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/DatePicker.json

@@ -0,0 +1,270 @@
+{
+  "name": "DatePicker",
+  "source": "src/components/DatePicker.tsx",
+  "propsType": "DatePickerProps",
+  "description": "DatePicker — a segmented date field with a calendar attached.\n\nWHY NOT `<input type=\"date\">`\n\nThe native control is genuinely good on mobile and genuinely unusable as a\ndesign system component on desktop: its calendar cannot be styled at all, it\ncannot express an unavailable date that is not part of a continuous min/max\nrange, and Safari on macOS renders no calendar button whatsoever. A system\nwhose date field looks like a different control in every browser is not a\ndesign system, so this rebuilds it — and pays for that by having to rebuild\nthe keyboard handling and the screen-reader semantics the native control gave\naway for free. React Aria's `useDatePicker` is what builds them back.\n\nTHE VALUE IS A STRING, THE DISPLAY IS NOT\n\n`value` is always `YYYY-MM-DD` in the Gregorian calendar. What the user SEES\nis their own locale's field order and their own calendar system, resolved\nfrom `Intl` — so a German reader edits DD.MM.YYYY and the value still comes\nback as `2026-04-12`. See `iso-date.ts` for why the public type is not\nreact-aria's `CalendarDate`.\n\nTHE FIELD IS EDITABLE WITHOUT THE CALENDAR, AND THAT IS THE POINT\n\nTyping a date is faster than clicking one for anybody who knows the date they\nwant, and paging a calendar back to a birth year is miserable. The segments\ntake digits and arrow keys directly; the calendar is for the cases where the\ndate is being chosen rather than recalled.",
+  "import": "import { DatePicker } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A segmented date field with a calendar attached, taking and returning a YYYY-MM-DD string.",
+  "useWhen": [
+    "the user picks one calendar date — an event date, a due date, a birthday",
+    "the date has to be typed as well as clicked, because the user often already knows it",
+    "some dates must be refused individually rather than as a continuous range"
+  ],
+  "useInstead": [
+    {
+      "when": "the user picks a start and an end",
+      "use": "DateRangePicker",
+      "why": "two DatePickers cannot stop the end preceding the start, cannot show the days between them, and give the user two calendars to reconcile from memory"
+    },
+    {
+      "when": "the value is a month or a year rather than a day",
+      "use": "Select",
+      "why": "a calendar grid to choose 'March' is twelve options rendered as thirty-one"
+    },
+    {
+      "when": "the field is one of a short, known set of dates the product defines",
+      "use": "Select or RadioGroup",
+      "why": "picking from four delivery slots is a choice from a list, not a date"
+    },
+    {
+      "when": "a time of day is part of the value",
+      "use": "Input",
+      "why": "this picker is fixed to day granularity; a time picker is not yet in this system"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms, table filters"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "each editable segment is its own tab stop, as in Chrome's native <input type=date>; the locale's separators are not, and arrow keys move between segments as well, so neither convention has to be learned",
+      "the segments sit in one labelled group, so the field's name is announced once on entry rather than repeated per segment",
+      "each segment announces its own name, value and bounds, so 'month, 4, minimum 1, maximum 12' is heard rather than an opaque number",
+      "field order and separators come from Intl, so a German reader edits DD.MM.YYYY and a US reader MM/DD/YYYY from the same component and the same value",
+      "the calendar overlay is modal: focus moves into the grid, the rest of the page is hidden from assistive tech, Escape closes it and focus returns to the field",
+      "every day cell carries the full date as its accessible name in the reader's own language, so the narrow weekday headers are never load-bearing",
+      "unavailable and disabled days are distinguished visually and in the accessible name, not by colour alone",
+      "today is marked with a dot rather than a ring, so it cannot be mistaken for a second selected day",
+      "the selected fill and the segment focus box are redeclared under forced-colors, where background-color is discarded"
+    ],
+    "requires": [
+      "`label`, or an `aria-label` when no visible label is rendered",
+      "`calendarLabel` wording if 'Open calendar' is wrong for the context — it is the button's whole accessible name"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "passing a Date object, a timestamp, or a locale-formatted string as `value`",
+      "why": "the value is a calendar date with no time and no zone, spelled YYYY-MM-DD. `new Date('2026-04-12')` parses as UTC midnight and displays as the 11th for every reader west of Greenwich. A malformed value throws with the prop name rather than rendering an empty field"
+    },
+    {
+      "dont": "using `isDateUnavailable` to express a lower or upper bound",
+      "why": "`minValue` and `maxValue` also disable the navigation arrows past the bound, so the user cannot page into a month with nothing selectable in it. A predicate is for the holes inside the bounds"
+    },
+    {
+      "dont": "hiding the field and leaving only the calendar button",
+      "why": "typing a date is faster than clicking one for anyone who already knows it, and paging a calendar back to a birth year is the worst interaction in any form"
+    },
+    {
+      "dont": "styling a day cell with :hover for the keyboard highlight",
+      "why": "use [data-selected], [data-today], [data-disabled] and [data-unavailable]. Pointer hover and keyboard focus are different states here and a grid where they disagree has two apparent cursors"
+    },
+    {
+      "dont": "reading the posted form value from the segments",
+      "why": "they are spinbuttons with no name. Pass `name` and the component posts the ISO value in a hidden input"
+    },
+    {
+      "dont": "wrapping it in a <label>",
+      "why": "the group is a set of spinbuttons rather than one form control, so there is nothing for htmlFor to point at. Pass `label` and react-aria wires the name through aria-labelledby"
+    },
+    {
+      "dont": "adding a roving tabindex so the field becomes one tab stop",
+      "why": "it buys back two tabs per field and costs the ability to Tab straight to the year, which is the segment users most often fix on its own. It also diverges from the native date input, which is the convention they already have"
+    }
+  ],
+  "slots": {
+    "label": {
+      "expects": "what the date is for — 'Event starts', not 'Date'"
+    },
+    "description": {
+      "expects": "helper text under the field; replaced by `errorMessage` when `isInvalid`"
+    },
+    "errorMessage": {
+      "expects": "what is wrong and what would be right, shown only when `isInvalid`"
+    }
+  },
+  "stylesheet": "src/styles/date-picker.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-regular",
+    "--font-weight-semibold",
+    "--icon-disabled",
+    "--icon-interactive",
+    "--icon-on-color",
+    "--icon-primary",
+    "--icon-secondary",
+    "--icon-size-sm",
+    "--ion-calendar-day-size",
+    "--ion-input-icon-size",
+    "--ion-shadow-shadow-lg",
+    "--radius-2xs",
+    "--radius-full",
+    "--radius-md",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-2",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-hover",
+    "--surface-primary",
+    "--surface-raised",
+    "--text-default",
+    "--text-disabled",
+    "--text-on-color",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Field label. Required for a usable control — see `a11y.requires`."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Helper text below the field."
+    },
+    "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"
+    },
+    "isReadOnly": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isRequired": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "size": {
+      "type": "DatePickerSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "value": {
+      "type": "string | null | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The selected date as `YYYY-MM-DD`. `null` means nothing is selected.\n\nNot a `Date` and not a timestamp — a calendar date has no time and no\ntimezone, so it cannot shift across midnight the way `new Date('2026-04-12')`\ndoes for every reader west of Greenwich. A malformed value throws rather\nthan rendering an empty field."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The initial date as `YYYY-MM-DD`, for an uncontrolled picker."
+    },
+    "onChange": {
+      "type": "((value: IsoDate | null) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires with `YYYY-MM-DD`, or `null` when the field is cleared."
+    },
+    "minValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Earliest selectable date, `YYYY-MM-DD`. Earlier dates are unreachable."
+    },
+    "maxValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Latest selectable date, `YYYY-MM-DD`."
+    },
+    "isDateUnavailable": {
+      "type": "((date: IsoDate) => boolean) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Individual dates the calendar refuses — weekends, holidays, booked days.\nReceives `YYYY-MM-DD`. Use `minValue`/`maxValue` for a continuous bound;\nthis is for the holes inside it."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Posts the value under this name, for an uncontrolled form."
+    },
+    "calendarLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible label for the button that opens the calendar."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 19,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}