ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/DateRangePicker.json

@@ -0,0 +1,284 @@
+{
+  "name": "DateRangePicker",
+  "source": "src/components/DateRangePicker.tsx",
+  "propsType": "DateRangePickerProps",
+  "description": "DateRangePicker — two segmented date fields with one calendar between them.\n\nNOT TWO `DatePicker`s SIDE BY SIDE, and the difference is the whole reason\nthis exists. Two independent pickers cannot stop the end date being before\nthe start, cannot show the days between them as a band, and give the user two\ncalendars to reconcile by memory. `useDateRangePicker` owns both ends: the\nsecond click completes the range in whichever order the two dates fall, the\nband follows the pointer while it is being dragged out, and a range cannot be\nmade to run backwards.\n\nTHE VALUE COMMITS LIVE. THERE IS NO APPLY BUTTON.\n\n`onChange` fires the moment the second end lands, and the calendar closes.\nThe reference designs this was drawn from put Clear and Apply under the grid,\nwhich is a draft model: the popover holds a pending range and only Apply\npromotes it. That was considered and rejected. Escape and an outside click\nwould then silently discard a selection the user watched themselves make —\nand there is no way to tell those two gestures apart from \"I am done\". A\nbutton labelled Apply beside a value that already applied is worse still.\n\nClear stays, because clearing is a real action with no other affordance.\n\nBOTH ENDS OR NEITHER\n\n`value` has no half-open form. A range with a start and no end is a state the\ncalendar passes THROUGH between the two clicks; it is never a value the\ncaller is handed, because \"everything after March\" and \"March to today\" are\ndifferent questions and a `null` end cannot say which one was meant. A caller\nwho wants an open end passes a sentinel of their own choosing as `maxValue`.",
+  "import": "import { DateRangePicker } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Two segmented date fields sharing one calendar, returning an inclusive { start, end } of YYYY-MM-DD strings.",
+  "useWhen": [
+    "the user picks a period — a report window, a stay, a filter over time",
+    "the range commonly crosses a month boundary, so both ends need to be visible at once",
+    "there are conventional periods worth offering as shortcuts: last 7 days, month to date, year to date"
+  ],
+  "useInstead": [
+    {
+      "when": "the user picks one date",
+      "use": "DatePicker"
+    },
+    {
+      "when": "the choice is really a named period and the exact dates are incidental",
+      "use": "Select",
+      "why": "if 'Last 30 days' is the answer rather than a shortcut to one, a calendar is scaffolding around a list of five options"
+    },
+    {
+      "when": "one end is open — everything before, or everything since",
+      "use": "DatePicker",
+      "why": "with the open end expressed as minValue or maxValue. This component has no half-open value on purpose; see antiPatterns"
+    }
+  ],
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms, table filters, dashboard toolbars"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "both fields sit in one labelled group; each announces its own name, so 'Start Date' and 'End Date' are heard without a visible sublabel, and each editable segment is its own tab stop as it is in DatePicker",
+      "the dash between them is aria-hidden — the fields have already said what they are, and a spoken dash adds nothing",
+      "the calendar is modal: focus enters the grid, the page behind is hidden from assistive tech, Escape closes and focus returns",
+      "a range cannot be made to run backwards, in either direction of selection, and cannot be dragged across an unavailable day",
+      "preset rows are buttons in a labelled group carrying aria-pressed, so 'which shortcut is active' is answerable without seeing the tint",
+      "the selected preset is marked by weight as well as by background, so it does not rely on colour alone",
+      "range endpoints and the band between them keep their fill under forced-colors, where background-color is otherwise discarded",
+      "the rail stacks above the grids below 32rem rather than being hidden, because shortcuts matter most on the device where dragging across two months is worst"
+    ],
+    "requires": [
+      "`label`, or an `aria-label` when no visible label is rendered",
+      "`presetsLabel` wording if the default is wrong for the context — it names the whole shortcut group",
+      "preset labels that say what period they select, since the label is the button's entire accessible name"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "expecting an Apply button, or adding one",
+      "why": "the value commits when the second end lands and the calendar closes. A draft model makes Escape and an outside click silently discard a selection the user watched themselves make, and there is no way to tell those gestures apart from 'I am done'. Clear exists because clearing has no other affordance"
+    },
+    {
+      "dont": "passing a range with only one end, or reading one back",
+      "why": "a start with no end is a state the calendar passes through between the two clicks, never a value the caller is handed. 'Everything after March' and 'March to today' are different questions and a null end cannot say which was meant"
+    },
+    {
+      "dont": "writing a relative preset as a literal object",
+      "why": "`value: { start: '…', end: '…' }` is evaluated once, when the module is first imported. 'Last 7 days' is then seven days before whenever the tab was opened. Pass a function; it is re-run each time the calendar opens"
+    },
+    {
+      "dont": "composing this out of two DatePickers",
+      "why": "two independent pickers cannot stop the end preceding the start, cannot draw the band between the ends, and make the user reconcile two calendars from memory"
+    },
+    {
+      "dont": "setting visibleMonths to 1 for a filter that usually spans weeks",
+      "why": "the user then pages back and forth to see both ends of their own selection. One month is for ranges that genuinely sit inside one"
+    },
+    {
+      "dont": "treating `end` as exclusive",
+      "why": "the range is closed. A stay of 3 nights from the 1st ends on the 4th in checkout terms and on the 3rd here; convert at your boundary, not in the picker"
+    }
+  ],
+  "slots": {
+    "label": {
+      "expects": "what the period is for — 'Reporting period', not 'Dates'"
+    },
+    "presets": {
+      "expects": "conventional periods for this screen, longest-lived first: today, last 7 days, month to date, year to date"
+    },
+    "description": {
+      "expects": "helper text under the fields; replaced by `errorMessage` when `isInvalid`"
+    },
+    "errorMessage": {
+      "expects": "what is wrong with the range and what would be right, shown only when `isInvalid`"
+    }
+  },
+  "stylesheet": "src/styles/date-range-picker.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-regular",
+    "--icon-disabled",
+    "--icon-interactive",
+    "--ion-input-icon-size",
+    "--radius-2xs",
+    "--radius-full",
+    "--radius-none",
+    "--radius-sm",
+    "--spacing-12",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-hover",
+    "--surface-primary",
+    "--surface-primary-subtle",
+    "--surface-primary-subtle-hover",
+    "--surface-raised",
+    "--text-default",
+    "--text-disabled",
+    "--text-interactive",
+    "--text-interactive-hover",
+    "--text-on-color",
+    "--text-primary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-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": "DateRangePickerSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "value": {
+      "type": "DateRange | null | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The selected range, both ends as `YYYY-MM-DD`. `null` means no range.\nA half-open range is not representable on purpose — see `antiPatterns`."
+    },
+    "defaultValue": {
+      "type": "DateRange | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The initial range, for an uncontrolled picker."
+    },
+    "onChange": {
+      "type": "((value: DateRange | null) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires with both ends, or `null` when the range is cleared."
+    },
+    "minValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Earliest selectable date, `YYYY-MM-DD`."
+    },
+    "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. Receives `YYYY-MM-DD`.\n\nA range may not be dragged ACROSS one of these — react-aria stops the\nselection at the first unavailable day, which is what makes \"book a room\nfor these nights\" correct rather than merely styled."
+    },
+    "presets": {
+      "type": "readonly DateRangePreset[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Shortcut rows beside the calendar. Omitted, no rail is rendered."
+    },
+    "visibleMonths": {
+      "type": "2 | 3 | 1 | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "How many months the calendar shows at once. Two by default: a range that\ncrosses a month boundary is the common case, and a one-month calendar\nmakes the user page back and forth to see both ends of their own selection."
+    },
+    "isClearable": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show a Clear button under the calendar. Defaults to `true`."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Posts `<name>-start` and `<name>-end` for an uncontrolled form."
+    },
+    "calendarLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible label for the button that opens the calendar."
+    },
+    "clearLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "presetsLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "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": 24,
+    "aria": 0,
+    "dom": 0,
+    "other": 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",