@ahrowe/ui 0.39.1 → 0.41.0

package/docs/Calendar.md

@@ -0,0 +1,184 @@
+# Calendar
+
+**When to use:** Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments, a team schedule. To let a user pick one date, use [DatePicker](DatePicker.md); for a sequence of past steps, use [Timeline](Timeline.md).
+
+**Keywords:** schedule, scheduler, planner, appointments, booking, meetings, week view, month view, drag and drop, events
+
+**Import:** `import { Calendar, CalendarView } from '@ahrowe/ui'`  
+**Types:** `import type { CalendarProps, CalendarEvent, CalendarRange, CalendarEventChange, CalendarEventContext, CalendarSlot, CalendarLabels, CalendarWeekday, CalendarWeekStart, CalendarSlots, CalendarDefaults } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Calendar, CalendarView, Popover, PopoverPlacement, Presentation } from '@ahrowe/ui';
+import type { CalendarEvent, CalendarSlot } from '@ahrowe/ui';
+
+// Your own event type: the calendar hands the same objects back in every callback.
+interface Booking extends CalendarEvent {
+  room: string;
+}
+
+const [bookings, setBookings] = useState<Booking[]>(initial);
+// A clicked event, or a new slot that has no id yet.
+const [editing, setEditing] = useState<{ booking: Booking | CalendarSlot; anchor: HTMLElement } | null>(null);
+
+<Calendar<Booking>
+  events={bookings}
+  defaultView={CalendarView.Week}
+  // Setting a callback is what switches the interaction on.
+  onEventClick={(booking, anchor) => setEditing({ booking, anchor })}
+  onSlotCreate={(slot, anchor) => setEditing({ booking: slot, anchor })}
+  onEventChange={({ event, start, end }) =>
+    setBookings((all) => all.map((b) => (b.id === event.id ? { ...b, start, end } : b)))
+  }
+  // One line in a short event or a month row; a second line where there is room for it.
+  renderEvent={(booking, { singleLine }) =>
+    singleLine ? booking.title : <>{booking.title}<small className='room'>{booking.room}</small></>
+  }
+/>
+
+// The editor is yours: next to the event on a desktop, a bottom sheet on a phone.
+<Popover
+  anchor={editing?.anchor ?? null}
+  isOpen={editing !== null}
+  onOpenChange={(isOpen) => !isOpen && setEditing(null)}
+  placement={PopoverPlacement.Right}
+  presentation={Presentation.Auto}
+  content={editing && <BookingEditor booking={editing.booking} onDone={() => setEditing(null)} />}
+/>
+
+// Read-only month and agenda
+<Calendar events={events} views={[CalendarView.Month, CalendarView.Agenda]} />
+
+// A working week that opens at 06:00
+<Calendar events={events} defaultView={CalendarView.Week} hiddenDays={[0, 6]} scrollToHour={6} />
+```
+
+**Enums:** `CalendarView`: `Month`, `Week`, `Day`, `Agenda`
+
+**Days and moments:** the selected day (`date`) is a `'YYYY-MM-DD'` string, like DatePicker's, and is the same day wherever the calendar is opened. Events are moments, so their `start` and `end` are `Date`s, shown in the browser's time zone. `dayTimeToDate` and `dateToTime` turn one into the other; see "When a day stands for a moment" in [DatePicker.md](DatePicker.md), also for a zone other than the browser's.
+
+**Events** are plain objects: `{ id, title, start, end, allDay?, color?, readOnly? }`.
+
+- `end` is **exclusive**, for timed and all-day events alike. A one-day all-day event on the 26th runs from midnight on the 26th to midnight on the 27th. A timed event ending at midnight does not show on the next day.
+- Timed events of 24 hours or more are drawn in the all-day row, not stretched down the time grid.
+- A timed event is drawn exactly as long as it lasts. One under 15 minutes has no room for its title, so it is a bar of its real length with the title on a line beneath it, and the next event in its column leaves that line free. Zoomed in far enough, the bar holds its title like any other event.
+- `color` is any CSS colour, `var(--success-color)` included. The event is tinted from it against the page background, so any colour reads in both light and dark themes.
+- `readOnly` events can still be clicked, but not moved or resized.
+
+**Loading events and recurring series.** `onRangeChange` fires on mount and whenever the shown period changes, with that period **and one either side of it**, because swiping reveals the neighbours before it pages. Fetch events for that range, and expand recurring series into it yourself: the calendar has no recurrence rules of its own.
+
+```tsx
+const [events, setEvents] = useState<CalendarEvent[]>([]);
+
+<Calendar
+  events={events}
+  onRangeChange={async ({ start, end }) => setEvents(await api.events(start, end))}
+/>
+```
+
+**Editing:**
+
+- With a **mouse**, drag on empty time to create, drag an event to move it, and drag its bottom edge to resize it. A plain click on empty time creates an hour (or `slotMinutes`, if longer); in the month view it creates an all-day slot.
+- With **touch**, press and hold for 400ms to pick up, then drag. A tap does what a click does. On a coarse pointer the resize grip is always visible.
+- Moving and resizing snap to `slotMinutes`. A live time label follows the drag, and `Escape` cancels it.
+- Update `events` in the same render as `onEventChange`, or **return a promise**: the event then stays where it was dropped until the promise settles, and is drawn from `events` again after that. So update `events` before it resolves, and reject to put the event back:
+
+```tsx
+onEventChange={async ({ event, start, end }) => {
+  await api.save(event.id, { start, end }); // rejects when saving fails: the event goes back
+  setBookings((all) => all.map((b) => (b.id === event.id ? { ...b, start, end } : b)));
+}}
+```
+
+**An event editor.** The calendar has none of its own, because what an event holds and how it is saved are yours. The Editing example on the [demo page](https://ahrowe.com/packages/ui/demo/#calendar) is one to copy, built from `Input`, `DatePicker`, `TimeInput`, `Checkbox` and `ActionButtons`; its **Code** tab has all of it. The part that is easy to get wrong is the conversion, because the fields hold days and times and the event holds moments:
+
+```tsx
+import { dateToDay, dateToTime, dayTimeToDate, dayToDate } from '@ahrowe/ui';
+import type { CalendarEvent, CalendarSlot } from '@ahrowe/ui';
+
+// What the editor's DatePickers and TimeInputs hold.
+interface Draft { startDay: string; startTime: string; endDay: string; endTime: string; allDay: boolean }
+
+function toDraft({ start, end, allDay = false }: Pick<CalendarEvent, 'start' | 'end' | 'allDay'>): Draft {
+  // `end` is exclusive, so an all-day event ends at midnight after its last day. Show the last day.
+  const lastDay = allDay ? new Date(end.getTime() - 1) : end;
+  return { allDay, startDay: dateToDay(start), startTime: dateToTime(start), endDay: dateToDay(lastDay), endTime: dateToTime(end) };
+}
+
+function fromDraft({ startDay, startTime, endDay, endTime, allDay }: Draft): CalendarSlot {
+  if (!allDay) return { allDay, start: dayTimeToDate(startDay, startTime), end: dayTimeToDate(endDay, endTime) };
+  const end = dayToDate(endDay);
+  end.setDate(end.getDate() + 1);
+  return { allDay, start: dayToDate(startDay), end };
+}
+```
+
+The example also:
+
+- **keeps the length when the start changes**, as calendar apps do, counting whole days for an all-day event, since a day the clocks change on is 23 or 25 hours long;
+- **shows a placeholder while a new event is written**: it adds the draft to `events` as a `readOnly` event, and Cancel drops it;
+- **disables Save** until the title is filled in and the end is after the start.
+
+**Hiding days:** `hiddenDays` leaves weekdays out of every view, `[0, 6]` being the weekend. The week and month grids close up without them, the day view and its arrows step over them, and a selected day that is hidden shows as the next one after it. An event on hidden days only is not drawn; one that runs into them is drawn on its shown days.
+
+**Navigating:** the header's arrows, **Today** and the view switcher. In the month, week and day views a horizontal swipe on touch pages to the next or previous period, with its events already in view while you swipe; the agenda is a list and pages with the arrows only. Pinch the week or day view, or hold Ctrl and use the wheel or trackpad, to zoom the hours; the zoom is kept when switching views. Clicking a day number, or a weekday in the week view, opens that day.
+
+**On a narrow calendar** (under 600px of its own width, not the viewport's) the month view becomes a grid with coloured dots above the selected day's events. Tapping a day selects it rather than opening it, and with `onSlotCreate` set, a **New event** button above the list creates an all-day slot on the selected day. Scrolling the list folds the month up into the selected week; swiping then pages by week instead of by month. Under `prefers-reduced-motion: reduce` the month folds in one step, once the list has scrolled the whole way, instead of following the scroll.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `events` | `E[]` | The events to show, `E extends CalendarEvent` |
+| `date` / `defaultDate` / `onDateChange` | `string` | Selected day, `'YYYY-MM-DD'`, controlled or uncontrolled: the same value a [DatePicker](DatePicker.md) holds, so the two can share state |
+| `view` / `defaultView` / `onViewChange` | `CalendarView` | Shown view, controlled or uncontrolled (default `Month`) |
+| `views` | `CalendarView[]` | Views in the switcher, in order; hidden when there is one (default all four) |
+| `locale` | `string` | BCP 47 tag for dates, times and the week start (default the browser's) |
+| `weekStartsOn` | `0` to `6` | First day of the week, `0` being Sunday (default the locale's, else Monday) |
+| `slotMinutes` | `number` | What creating, moving and resizing snap to (default `15`) |
+| `hiddenDays` | `CalendarWeekday[]` | Weekdays left out of every view, `0` being Sunday: `[0, 6]` hides the weekend |
+| `scrollToHour` | `number` | Hour the week and day views open at, such as `6` (default an hour before now while today is shown, otherwise `7`) |
+| `onRangeChange` | `(range: CalendarRange) => void` | The shown period plus one on either side |
+| `onEventClick` | `(event: E, anchor: HTMLElement) => void` | An event was clicked; `anchor` is its element, ready for `Popover`'s `anchor` |
+| `onEventChange` | `(change: CalendarEventChange<E>) => void \| Promise<unknown>` | Moved or resized. Setting it makes events draggable. A returned promise keeps the event in place until it settles |
+| `onSlotCreate` | `(slot: CalendarSlot, anchor: HTMLElement) => void` | Empty time clicked or dragged over. Setting it enables creating. `anchor` is the day's cell in the month view (the **New event** button in a narrow one) and an invisible box over the new slot in the week and day views, ready for `Popover`'s `anchor` |
+| `renderEvent` | `(event: E, context: CalendarEventContext) => ReactNode` | Content of an event in place of its title. No interactive elements. `context.singleLine` is set where it has one line: an event under 45 minutes, an all-day bar, a month row. Keep to the title there |
+| `ref` | `Ref<HTMLDivElement>` | The root element |
+
+Give the calendar a height. It is `40em` tall by default and scrolls inside itself; `style={{ height: '100dvh' }}` or a class sets another.
+
+**Keyboard:** in the month view the days are a grid with one tab stop on the selected day: `←`/`→` move a day, `↑`/`↓` a week, `Home`/`End` go to the start and end of the week, `PageUp`/`PageDown` a month. `Enter` or `Space` opens a list of that day's events, with a **New event** button when `onSlotCreate` is set. In the week and day views every event is a button, in time order.
+
+**Accessibility:**
+
+- The period title is a polite live region, so paging is announced.
+- Days carry their full date and event count as their name, and today has `aria-current="date"`.
+- Each day column of the time grid is a group named by its date.
+- **Dragging needs a single-pointer alternative (WCAG 2.5.7).** Creating has one, a click. For moving and resizing it has to be your `onEventClick` dialog, so let it edit the start and end.
+
+**Theming:** these are theme variables (typed on `ThemeVariables`). Set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--calendar-hour-height` | `3em` (the height of one hour; pinching zooms from it) |
+| `--calendar-today-color` | `var(--primary-color)` |
+| `--calendar-now-color` | `var(--error-color)` |
+| `--calendar-event-radius` | `6px` |
+
+**Global defaults:** `ConfigProvider` sets `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays` and `scrollToHour` for every calendar, e.g. `defaultProps={{ Calendar: { locale: 'de-AT', weekStartsOn: 1 } }}`. The other props depend on your event type, so they are set per instance. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `header` `dayHeader` `cell` `event`
+
+**Labels:** `previous` `next` `today` `viewSwitcher` `month` `week` `day` `agenda` `allDay` `more` `eventCount` `noEvents` `newEvent`: the text this component renders of its own. `more` and `eventCount` are functions of a count. Dates and times come from `locale`, not from here. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `CalendarLabels`.
+
+**Limits:**
+
+- **One time zone, the browser's.** A `timeZone` prop would need `Temporal`, which iOS Safari does not ship yet.
+- **No recurrence rules.** Expand series for the range `onRangeChange` reports.
+- **Moving stays within the shown period**, and between days or times of the same kind: an event cannot be dragged from the time grid into the all-day row.
+- **No right-to-left layout.**
+- **Safari on macOS** sends a trackpad pinch as a gesture event rather than a Ctrl+wheel, so there it zooms the page as usual; pinching on a touch screen zooms the hours in every browser.
+- **A controlled `date` must update in the same render as `onDateChange`.** After a swipe, the calendar shows the new period's panes straight away; a parent that updates later makes it jump back and forth.
+- **A tap outside your own popover also reaches the calendar.** `Popover` closes on pointer release and lets the click through, so a tap on empty time closes it and creates a slot: an editor opened from `onSlotCreate` moves to the new slot.
+
+HTML attributes such as `id`, `aria-label` and `data-*` are passed to the root element.

package/docs/CommandPalette.md

@@ -7,8 +7,6 @@
 **Import:** `import { CommandPalette } from '@ahrowe/ui'`  
 **Types:** `import type { CommandPaletteProps, CommandPaletteLabels } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your app: the palette is a [Modal](Modal.md) and portals there.
-
 ```tsx
 import { CommandPalette, menuHotkeys, useHotkeys } from '@ahrowe/ui';
 import type { MenuEntry } from '@ahrowe/ui';

package/docs/ConfigProvider.md

@@ -7,16 +7,19 @@
 **Import:** `import { ConfigProvider } from '@ahrowe/ui'`
 **Types:** `import type { ComponentDefaults, ConfigProviderProps } from '@ahrowe/ui'`
 
-Place it inside `ThemeProvider` (it's a separate concern from theming — theme = CSS variables, config = default props):
+At the app root, pass `defaultProps` and `presentation` to [AhroweProvider](AhroweProvider.md), which includes a ConfigProvider. Use ConfigProvider on its own for a section with defaults of its own:
 
 ```tsx
-import { ThemeProvider, ConfigProvider } from '@ahrowe/ui';
+import { AhroweProvider, ConfigProvider } from '@ahrowe/ui';
 
-<ThemeProvider>
-  <ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: true } }}>
-    <App />
-  </ConfigProvider>
-</ThemeProvider>
+<AhroweProvider defaultProps={{ Input: { alwaysFloatLabel: true } }}>
+  <App />
+</AhroweProvider>
+
+// Inside App: one form that wants different defaults
+<ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: false } }}>
+  <SignupForm />
+</ConfigProvider>
 ```
 
 ## How defaults resolve
@@ -95,6 +98,7 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
 - **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
 - **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
 - **Editors:** `RoomDrawer`, `RoomViewer`
+- **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays` and `scrollToHour` only (see below)
 
 ```tsx
 <ConfigProvider
@@ -134,6 +138,6 @@ Every string a component renders of its own is set through its `labels` prop, an
 
 **Labels merge per key**, unlike every other default here. An instance that overrides one string keeps the provider's translations for the rest, so `<Alert labels={{ dismiss: 'Weg damit' }} />` under the provider above does not lose anything else Alert might have been given. Anything the component does not produce itself, a `title`, a column `label`, a button's children, is already yours and never appears in `labels`.
 
-`ColorPicker` and `VirtualList` appear in `ComponentDefaults` with their labels only: the first is configured elsewhere, the second has generic props that a per-key default map cannot express. `Toast` is not there at all, because `ToastProvider` is already its app-wide configuration and carries `labels` itself.
+`ColorPicker` and `VirtualList` appear in `ComponentDefaults` with their labels only: the first is configured elsewhere, the second has generic props that a per-key default map cannot express. `Calendar` is generic too, so its entry is the props that do not depend on the event type: `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays` and `scrollToHour`. `Toast` is not there at all, because `AhroweProvider`'s `toast` prop is already its app-wide configuration and carries `labels` itself.
 
 Each component's doc lists its own keys under **Labels:**.

package/docs/ConfirmModal.md

@@ -6,8 +6,6 @@
 
 **Import:** `import { ConfirmModal } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML (renders via portal).
-
 ```tsx
 import { ConfirmModal } from '@ahrowe/ui';
 
@@ -34,7 +32,7 @@ const [isOpen, setIsOpen] = useState(false);
 | Prop | Type | Description |
 |------|------|-------------|
 | `isOpen` | `boolean` | Controls visibility |
-| `title` | `string` | Dialog heading |
+| `title` | `ReactNode` | Dialog heading |
 | `content` | `ReactNode` | Dialog body |
 | `onConfirm` | `() => void \| Promise<void>` | Called when user confirms |
 | `onClose` | `(didSubmit: boolean) => void` | Called on both confirm and cancel |

package/docs/DatePicker.md

@@ -6,7 +6,7 @@
 
 **Keyboard:** the day grid uses a roving tab stop (the selected day, or today, or the 1st — one Tab reaches it, not every day individually); arrow keys move by day (`←`/`→`) or by week (`↑`/`↓`), crossing into the adjacent month automatically when they run past the edge, and Enter/Space selects the focused day.
 
-**Import:** `import { DatePicker, dateToDay, dayToDate } from '@ahrowe/ui'`  
+**Import:** `import { DatePicker, dateToDay, dayToDate, dateToTime, dayTimeToDate } from '@ahrowe/ui'`  
 **Types:** `import type { DatePickerProps } from '@ahrowe/ui'`
 
 ```tsx
@@ -93,7 +93,14 @@ const closesAt = DateTime.fromISO(day, { zone: 'Europe/Vienna' }).endOf('day').t
 const shown = DateTime.fromJSDate(closesAt, { zone: 'Europe/Vienna' }).toISODate();
 ```
 
-With a [TimeInput](TimeInput.md) next to it, which holds `'HH:MM'`, the two make a moment the same way: ``DateTime.fromISO(`${day}T${time}`, { zone })``, or, in the user's own zone, `dayToDate(day)` followed by `setHours(hours, minutes)`.
+With a [TimeInput](TimeInput.md) next to it, which holds `'HH:MM'`, the two make one moment. In the user's own zone:
+
+```ts
+const start = dayTimeToDate(day, time); // an Invalid Date unless both are complete
+const [shownDay, shownTime] = [dateToDay(start), dateToTime(start)]; // and back, for the two inputs
+```
+
+On the day the clocks go forward a time can be missing (02:30 in Vienna on the last Sunday of March); `dayTimeToDate` moves it on by the gap, to 03:30. On the day they go back a time happens twice, and it takes the first. In a given zone the same comes from Luxon: ``DateTime.fromISO(`${day}T${time}`, { zone })``.
 
 ## Migration from Date values
 

package/docs/ErrorBoundary.md

@@ -65,7 +65,9 @@ import { ErrorBoundary } from '@ahrowe/ui';
 </ErrorBoundary>
 ```
 
-The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a `CopyButton` that also fires a `Toast` confirmation if `ToastProvider` is mounted), and a `Button` for "Try again".
+The default fallback is a centered card with a tinted icon badge, an `Accordion` for the collapsible stack trace (with a `CopyButton` that also fires a `Toast` confirmation when the boundary is inside `AhroweProvider`), and a `Button` for "Try again".
+
+Put an app-wide boundary inside `AhroweProvider`, not around it. Around it, the error has unmounted the provider by the time the fallback shows, so the fallback renders unthemed and its copy confirmation never appears.
 
 **Key props:**
 
@@ -89,7 +91,7 @@ The default fallback is a centered card with a tinted icon badge, an `Accordion`
 | `copy` | `"Copy"` | Copy button tooltip and accessible name before copying |
 | `copied` | `"Copied"` | Copy button tooltip and accessible name right after a successful copy |
 | `reset` | `"Try again"` | Reset button label |
-| `copySuccessToast` | `"Stack trace copied to clipboard"` | Toast shown after a successful copy (only visible if `ToastProvider` is mounted) |
-| `copyErrorToast` | `"Could not copy stack trace"` | Toast shown if the copy fails |
+| `copySuccessToast` | `"Stack trace copied to clipboard"` | Toast shown after a successful copy, inside `AhroweProvider` only |
+| `copyErrorToast` | `"Could not copy stack trace"` | Toast shown if the copy fails, inside `AhroweProvider` only |
 
 **Slots:** `root` `header` `badge` `icon` `title` `description` `stack` `stackHeader` `stackLabel` `stackTrace` `copyButton` `actions` `resetButton`

package/docs/FormValidatorGroup.md

@@ -71,7 +71,7 @@ const editForm = useFormValidatorGroup(fields, { initialValues: user, onSubmit:
 5. Otherwise calls `onSubmit(values, group)`. If it throws, the error is passed to `parseError(err, true)` to surface field-level or generic errors.
 6. Sets `isSubmitting` false.
 
-By default `onSubmitError` shows the first error as an error **toast** (requires a `ToastProvider` in the tree — see `Toast`). Override it via `options.onSubmitError`.
+By default `onSubmitError` shows the first error as an error **toast** (see `Toast`). Override it via `options.onSubmitError`.
 
 ## Options
 

package/docs/KlipyPicker.md

@@ -6,7 +6,7 @@
 
 **Import:** `import { KlipyPicker } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token, passed as the `token` prop. There is no built-in key: without one the picker renders but every request fails.
+**Requires:** a Klipy API token, passed as the `token` prop. There is no built-in key: without one the picker renders but every request fails.
 
 ```tsx
 import { KlipyPicker } from '@ahrowe/ui';

package/docs/Menu.md

@@ -7,8 +7,6 @@
 **Import:** `import { Menu, menuHotkeys } from '@ahrowe/ui'`  
 **Types:** `import type { MenuProps, MenuEntry, MenuAction } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your app: the menu is portalled there, like every other anchored panel in the library.
-
 ```tsx
 import { Menu } from '@ahrowe/ui';
 import type { MenuEntry } from '@ahrowe/ui';

package/docs/Modal.md

@@ -6,8 +6,6 @@
 
 **Import:** `import { Modal } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML (renders via portal).
-
 The panel itself never scrolls: the header is fixed and the children scroll inside the `body` slot, so the title and close button stay visible no matter how long the content is. Pass `footer` for anything that should stay put below the content, typically the action buttons.
 
 While open, the modal traps focus (focus moves into the panel and returns to whatever was focused before on close), locks scrolling on the page behind it, and closes on Escape. Modals nest correctly: Escape closes only the topmost one, and the page stays locked until the last one closes. The same applies to anything opened from inside a modal — a `Menu`, `Dropdown` or `Popover` counts as the layer above it, so Escape closes that first, and the modal's focus trap leaves focus alone while it's open (all three render through the same portal, so their DOM sits beside the modal's panel rather than inside it).
@@ -48,7 +46,7 @@ const [isOpen, setIsOpen] = useState(false);
 | Prop | Type | Description |
 |------|------|-------------|
 | `isOpen` | `boolean` | Controls visibility |
-| `title` | `string` | Header title |
+| `title` | `ReactNode` | Header title, also the dialog's accessible name |
 | `onClose` | `() => void` | Called when the backdrop is clicked, the close button is pressed, or Escape is pressed |
 | `footer` | `ReactNode` | Pinned below the scrolling body, e.g. action buttons. Nothing renders when omitted |
 | `hideHeader` | `boolean` | Removes the header bar |
@@ -92,7 +90,7 @@ To switch it off and go back to a hard edge, set `--modal-scroll-fade: 0px`, per
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Modal: { presentation: Presentation.Auto } }}` — which also covers `DatePicker`, `TimeInput` and `KlipyPicker` when they open in a Modal via their own `isModal`. `presentation={Presentation.Auto}` on the provider itself sets every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
 
-The panel also takes the full native `div` attribute set (`id`, `role`, `aria-*`, `data-*`, …). Pass `aria-label` when using `hideHeader`, since there is then no title to label the dialog with.
+The panel also takes the full native `div` attribute set (`id`, `role`, `aria-*`, `data-*`, …). The title's text names the dialog for screen readers. Pass `aria-label` when using `hideHeader`, or when the title has no text of its own (an icon alone): it then takes over from the title.
 
 **Slots:** `container` `backdrop` `modal` `header` `title` `closeButton` `body` `footer`
 

package/docs/MultiSelect.md

@@ -7,8 +7,6 @@
 **Import:** `import { MultiSelect } from '@ahrowe/ui'`  
 **Types:** `import type { MultiSelectProps, MultiSelectItem, MultiSelectValue } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your app — the panel renders through a portal.
-
 ```tsx
 import { useState } from 'react';
 import { MultiSelect } from '@ahrowe/ui';

package/docs/OtpInput.md

@@ -6,8 +6,6 @@
 
 **Import:** `import { OtpInput, OtpInputCharset } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML (the error message renders via `Tooltip`, which portals).
-
 **Charset:** `OtpInputCharset.Numeric` (default) | `OtpInputCharset.Alphanumeric`
 
 ```tsx

package/docs/Popover.md

@@ -88,8 +88,6 @@ Only a `Click` trigger presents as a sheet. `Hover` and `Focus` open something s
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Popover: { presentation: Presentation.Auto } }}`, or `presentation={Presentation.Auto}` on the provider itself to set every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
 
-Requires a `<div id="bodyEnd"></div>` at the app root — the panel is portaled there, same as `Tooltip` and `Menu`.
-
 **Scrolling:** where the browser supports CSS anchor positioning, including the trigger's transforms, the panel is anchored to the trigger in CSS, so it moves with a scrolling trigger in the same frame instead of catching up a frame later. Firefox resolves anchors without transforms, so it keeps the pixel positioning. While it is open the trigger carries an inline `anchor-name`, added to any inline one it already has; an `anchor-name` your stylesheet gives the trigger is overridden for that time.
 
 **Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content and the keyboard opened it (Enter or Space on the trigger, or ArrowDown/ArrowUp), focus moves to the first focusable element and the panel gets `role="dialog"`; a pointer click leaves the focus where it already is. `focusOnOpen` forces either. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. This is non-modal: focus is not trapped, and hover/focus triggers don't steal focus. Escape closes only the innermost open layer, so a popover inside a `Modal` closes on the first press and leaves the modal open. Popovers with only static content don't manage focus or claim the dialog role.

package/docs/RadioGroup.md

@@ -71,7 +71,7 @@ interface RadioOption {
 | `errorMessage` | `string` | Manual error message (when not using a `formValidator`) |
 | `isValid` | `boolean` | Manual valid state (default `true`) |
 
-**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces only after the field is *touched* (focus leaves the group), then on focus or hover; requires `<div id="bodyEnd"></div>` at the app root for the tooltip portal.
+**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces only after the field is *touched* (focus leaves the group), then on focus or hover.
 
 **Global defaults:** adopts `ConfigProvider` — e.g. `defaultProps={{ RadioGroup: { orientation: RadioGroupOrientation.Horizontal } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

package/docs/ScrollbarProvider.md

@@ -20,3 +20,7 @@ import { ScrollbarProvider } from '@ahrowe/ui';
 |------|------|-------------|
 | `className` | `string` | Additional class on the wrapper |
 | `children` | `ReactNode` | Scrollable content |
+
+**Your own rules win.** Its rules have zero specificity, so any scrollbar rule of a component's or of yours, on an element inside it, takes precedence.
+
+**The whole app:** `AhroweProvider` already styles every scrollbar in the app, portalled panels included, unless it is given `scrollbars={false}`. Use `ScrollbarProvider` for one region in an app that turned that off.

package/docs/SplitButton.md

@@ -8,8 +8,6 @@
 **Types:** `import type { SplitButtonAction, SplitButtonProps } from '@ahrowe/ui'`  
 **Enums:** `import { PopoverAlign } from '@ahrowe/ui'` for `align`.
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML (the actions menu is a `Menu`, which portals).
-
 ```tsx
 import { SplitButton } from '@ahrowe/ui';
 import type { SplitButtonAction } from '@ahrowe/ui';

package/docs/ThemeProvider.md

@@ -1,11 +1,11 @@
 # ThemeProvider
 
-**When to use:** Required wrapper for the entire component library. Injects all CSS custom properties as inline styles so every component inside can use theme variables. Place it at or near the root of your app.
+**When to use:** Applies a theme to its subtree, injecting its CSS custom properties as inline styles so every component inside can use them. [AhroweProvider](AhroweProvider.md) includes one and takes the same `themes` and `currentThemeId`: use that at the app root, and ThemeProvider on its own for a section with a different theme.
 
 **Keywords:** theming, dark mode, gradient
 
 **Import:** `import { ThemeProvider } from '@ahrowe/ui'`  
-**Types:** `import type { Theme, ThemeVariables } from '@ahrowe/ui'`  
+**Types:** `import type { Theme, ThemeVariables, ThemeProviderProps } from '@ahrowe/ui'`  
 **Built-in themes:** `import { defaultTheme, lightTheme } from '@ahrowe/ui'`
 
 ```tsx
@@ -58,18 +58,21 @@ no `themes` at all. `lightTheme` is its light sibling: same brand colour, invert
 both to let the user choose.
 
 ```tsx
-import { ThemeProvider, defaultTheme, lightTheme, useTheme } from '@ahrowe/ui';
+import { AhroweProvider, defaultTheme, lightTheme, useTheme } from '@ahrowe/ui';
 
-function App() {
+// A new array on every render reads as a theme change, so keep it at module scope.
+const THEMES = [defaultTheme, lightTheme];
+
+function Root() {
   const { currentThemeId, setCurrentThemeId } = useTheme(defaultTheme.id);
 
   return (
-    <ThemeProvider themes={[defaultTheme, lightTheme]} currentThemeId={currentThemeId}>
+    <AhroweProvider themes={THEMES} currentThemeId={currentThemeId}>
       <button onClick={() => setCurrentThemeId(currentThemeId === 'light' ? 'default' : 'light')}>
         Toggle theme
       </button>
       <App />
-    </ThemeProvider>
+    </AhroweProvider>
   );
 }
 ```
@@ -116,9 +119,9 @@ interface Theme {
 | `themes` | `Theme[]` | Theme definitions — defaults to built-in default theme |
 | `currentThemeId` | `string` | Active theme id — must match one of the `themes[].id` values |
 
-**Note:** Without `ThemeProvider`, all CSS variables are undefined and components will be unstyled.
+**Note:** Without a `ThemeProvider` or `AhroweProvider` above them, all CSS variables are undefined and components will be unstyled.
 
-**Base typography:** The wrapper also sets `font-family`, `font-size`, `font-weight`, and `color` from the theme's `--default-font`, `--default-font-size`, `--default-font-weight`, and `--text-color`, so everything inside — including content portaled into a `#bodyEnd` placed within the provider — inherits the theme's base text style without each component having to set it.
+**Base typography:** The wrapper also sets `font-family`, `font-size`, `font-weight`, and `color` from the theme's `--default-font`, `--default-font-size`, `--default-font-weight`, and `--text-color`, so everything inside — including what `AhroweProvider` portals — inherits the theme's base text style without each component having to set it.
 
 ## Gradient primary
 
@@ -202,7 +205,7 @@ through its own variable (`--slider-range-color`, `--pagination-active-backgroun
 
 ## Nested providers and portals
 
-Providers nest: an inner one overrides the variables it declares and inherits the rest, so a differently-themed panel inside a themed app works without restating the whole theme.
+Providers nest: an inner one overrides the variables it declares and inherits the rest, so a differently-themed panel inside a themed app works without restating the whole theme. Only the outermost one sets the page's `<meta name="theme-color">` to its `--primary-color`; an inner one themes its section, not the browser.
 
-A portal breaks that by default, because theme variables travel by CSS inheritance and a portal escapes the subtree. Anything rendered through `BodyEnd` — `Tooltip`, `Dropdown`, `InputDropdown`, `ColorPicker`, `Menu`, `Popover`, `Modal`, `Toast` — therefore carries the nearest provider's variables with it, so an open panel matches the panel that opened it rather than whatever wraps `#bodyEnd`.
+A portal breaks that by default, because theme variables travel by CSS inheritance and a portal escapes the subtree. Anything rendered through `BodyEnd` — `Tooltip`, `Dropdown`, `InputDropdown`, `ColorPicker`, `Menu`, `Popover`, `Modal`, `Toast` — therefore carries the nearest provider's variables with it, so an open panel matches the panel that opened it rather than whatever wraps the element it portals into.
 

package/docs/TimeInput.md

@@ -8,6 +8,8 @@
 
 The value is a `"HH:MM"` 24-hour string (e.g. `"09:30"`) everywhere — also when `use24Hour={false}` is set (that flag only changes the dial UI, not the stored value).
 
+With a [DatePicker](DatePicker.md) beside it, `dayTimeToDate(day, time)` makes the two one `Date`, and `dateToTime(date)` gives a `Date`'s time back for the field. See "When a day stands for a moment" there.
+
 ```tsx
 import { TimeInput, FormValidator } from '@ahrowe/ui';
 

package/docs/Toast.md

@@ -4,21 +4,21 @@
 
 **Keywords:** snackbar, notification popup
 
-**Import:** `import { ToastProvider, showToast } from '@ahrowe/ui'`  
-**Types:** `import type { ToastOptions, ToastType, ToastPosition } from '@ahrowe/ui'`
+**Import:** `import { showToast } from '@ahrowe/ui'`  
+**Types:** `import type { ToastOptions, ToastContextConfig, ToastLabels, ToastType, ToastPosition } from '@ahrowe/ui'`
 
-**Setup:** Wrap your app with `ToastProvider` (inside `ThemeProvider`):
+**Setup:** [AhroweProvider](AhroweProvider.md) shows the toasts. Its `toast` prop sets the defaults for all of them:
 
 ```tsx
-import { ThemeProvider, ToastProvider } from '@ahrowe/ui';
+import { AhroweProvider } from '@ahrowe/ui';
 
-<ThemeProvider>
-  <ToastProvider position="bottom-right" duration={3000}>
-    <App />
-  </ToastProvider>
-</ThemeProvider>
+<AhroweProvider toast={{ position: 'bottom-right', duration: 3000 }}>
+  <App />
+</AhroweProvider>
 ```
 
+`ToastProvider` was removed in 0.41. It took the same settings as props: move them into `toast`.
+
 **Usage:** Call `showToast` anywhere — no component hierarchy required:
 
 ```tsx
@@ -56,16 +56,17 @@ showToast('Done', {
 });
 ```
 
-**ToastProviderProps** (default config for all toasts):
+**ToastContextConfig**, the `toast` prop. Every key but `allowStacking` can also be passed to a single `showToast`:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `position` | `ToastPosition` | `'bottom-right'` | Screen position |
-| `duration` | `number` | `3000` | Auto-dismiss delay in ms; `0` = persistent |
-| `showRemainingTime` | `boolean` | `false` | Show a progress bar draining to zero |
-| `showCloseButton` | `boolean` | `false` | Show × button |
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `position` | `ToastPosition` | `'top-right'` | Screen position |
+| `duration` | `number` | `4000` | Auto-dismiss delay in ms; `0` = persistent |
+| `showRemainingTime` | `boolean` | `true` | Show a progress bar draining to zero |
+| `showCloseButton` | `boolean` | `true` | Show × button |
 | `allowStacking` | `boolean` | `true` | Allow multiple toasts simultaneously |
 | `pauseOnHover` | `boolean` | `true` | Pause the auto-dismiss timer while the toast is hovered or focused |
+| `labels` | `ToastLabels` | | See **Labels** |
 
 **Swipe to dismiss:** on touch devices, every toast can be dragged away to dismiss it, on top of the close button and auto-dismiss timer. A fast flick dismisses even without dragging far; dragging pauses the auto-dismiss timer for the duration of the gesture (regardless of `pauseOnHover`) and a vertical drag is left alone so it doesn't fight the page's own scrolling. It's gated to coarse (touch) pointers only — on mouse/trackpad devices the close button and auto-dismiss already cover it, and a drag there is more likely to be a text selection than an intentional dismiss.
 
@@ -75,7 +76,7 @@ showToast('Done', {
 
 **Slots:** `root` `icon` `content` `closeButton` `progressBar`
 
-**Labels:** `close` — the dismiss button's screen-reader name. Set it on `ToastProvider` for the whole app (`labels={{ close: 'Schließen' }}`), or per toast through the `showToast` options. Type: `ToastLabels`.
+**Labels:** `close`, the dismiss button's screen-reader name. Set it for the whole app in `AhroweProvider`'s `toast={{ labels: { close: 'Schließen' } }}`, or per toast with `showToast('Saved', { labels: { close: 'Schließen' } })`. Type: `ToastLabels`.
 
 ## Sizing
 

package/docs/Tooltip.md

@@ -77,4 +77,4 @@ The default bubble is an **inverse of the page** rather than a fixed colour: it
 
 The bubble, its arrow, the `details` badge and the error variant all scale with the theme's text. The bubble's `max-width` is `em`, so it bounds a line measure rather than a pixel count as the text grows.
 
-The badge derives its size from `--default-font-size` directly rather than from `em`. It renders inline wherever you put it, so an `em` would measure the surrounding text instead of the theme; the bubble can use `em` because it is portaled to `#bodyEnd` and always lands on the theme's own size.
+The badge derives its size from `--default-font-size` directly rather than from `em`. It renders inline wherever you put it, so an `em` would measure the surrounding text instead of the theme; the bubble can use `em` because it is portalled to the end of the app and always lands on the theme's own size.

package/docs/VirtualList.md

@@ -7,8 +7,6 @@
 **Import:** `import { VirtualList } from '@ahrowe/ui'`  
 **Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle, VirtualListSort } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your app **only if** you use the column-visibility toggle (the gear menu) — its popover is a `Popover` that renders via portal. Lists without columns, or with `showColumnToggle={false}`, don't need it.
-
 ```tsx
 import { VirtualList } from '@ahrowe/ui';
 import type { VirtualListColumn } from '@ahrowe/ui';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.39.1",
+  "version": "0.41.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",

package/dist/cjs-types/common/toast/toastProvider.d.ts

@@ -1,8 +0,0 @@
-import { default as React, ReactNode } from 'react';
-import { ToastContextConfig } from './toast.types.js';
-interface ToastProviderProps extends ToastContextConfig {
-    children: ReactNode;
-}
-declare function ToastProvider({ children, position, duration, showRemainingTime, showCloseButton, allowStacking, pauseOnHover, labels, }: ToastProviderProps): React.JSX.Element;
-export default ToastProvider;
-export type { ToastProviderProps };

package/dist/esm/common/toast/toastProvider.mjs

@@ -1,2 +0,0 @@
-"use client";import e from"../bodyEnd/bodyEnd.mjs";import t from"./toast.module.mjs";import n from"./toast.mjs";import{_registerToastHandler as r,_unregisterToastHandler as i}from"./toastService.mjs";import{useCallback as a,useEffect as o,useRef as s,useState as c}from"react";import l from"classnames";import{Fragment as u,jsx as d,jsxs as f}from"react/jsx-runtime";var p={position:`top-right`,duration:4e3,showRemainingTime:!0,showCloseButton:!0,allowStacking:!0,pauseOnHover:!0,labels:{close:`Close`}},m=220;function h(e){return t[`container-${e}`]}function g({children:g,position:_=p.position,duration:v=p.duration,showRemainingTime:y=p.showRemainingTime,showCloseButton:b=p.showCloseButton,allowStacking:x=p.allowStacking,pauseOnHover:S=p.pauseOnHover,labels:C}){let[w,T]=c([]),E=s(0),D=a(e=>{T(t=>t.map(t=>t.id===e?{...t,dismissing:!0}:t)),setTimeout(()=>{T(t=>t.filter(t=>t.id!==e))},m)},[]),O=a((e,t)=>{let n={position:t?.position??_,duration:t?.duration??v,showRemainingTime:t?.showRemainingTime??y,showCloseButton:t?.showCloseButton??b,pauseOnHover:t?.pauseOnHover??S,type:t?.type??`default`,classNames:t?.classNames,styles:t?.styles};E.current+=1;let r={id:`toast-${E.current}`,content:e,options:n,dismissing:!1};T(e=>!x&&e.length>0?(setTimeout(()=>{T([r])},m),e.map(e=>({...e,dismissing:!0}))):[...e,r])},[_,v,y,b,x,S]);o(()=>(r(O),()=>i()),[O]);let k=w.reduce((e,t)=>{let n=t.options.position;return e[n]||(e[n]=[]),e[n].push(t),e},{});return f(u,{children:[g,d(e,{children:Object.entries(k).map(([e,r])=>d(`div`,{className:l(t.container,h(e)),children:r.map(t=>d(n,{item:t,isBottom:e.startsWith(`bottom`),onDismiss:D,labels:{...p.labels,...C,...t.labels}},t.id))},e))})]})}export{g as default};
-//# sourceMappingURL=toastProvider.mjs.map