@ahrowe/ui 0.39.1 → 0.40.0

package/dist/types/common/themeProvider/theme.types.d.ts

@@ -205,6 +205,14 @@ export interface ThemeVariables {
     '--tree-selected-background'?: string;
     /** Selected row text. Falls back to --text-on-primary. */
     '--tree-selected-color'?: string;
+    /** Height of one hour in the week and day views. Pinching zooms from it. Falls back to 3em. */
+    '--calendar-hour-height'?: string;
+    /** Today's date marker. Falls back to --primary-color. */
+    '--calendar-today-color'?: string;
+    /** The current-time line. Falls back to --error-color. */
+    '--calendar-now-color'?: string;
+    /** Corner radius of an event. Falls back to 6px. */
+    '--calendar-event-radius'?: string;
     /** Page button size. Falls back to 36px. */
     '--pagination-size'?: string;
     /** Gap between page buttons. Falls back to 4px. */

package/dist/types/common/utils/day.d.ts

@@ -14,3 +14,11 @@ export declare function formatDay({ year, month, day }: DayParts): string;
 export declare function dateToDay(date: Date): string;
 /** The first moment of a `'YYYY-MM-DD'` day in the browser's time zone. An Invalid Date for anything else. */
 export declare function dayToDate(day: string): Date;
+/** The `'HH:MM'` of `date` in the browser's time zone, the value a TimeInput holds; `''` for an Invalid Date. */
+export declare function dateToTime(date: Date): string;
+/**
+ * The moment a `'YYYY-MM-DD'` day and an `'HH:MM'` time stand for in the browser's time zone,
+ * DatePicker's and TimeInput's values together. A time the clock skips that day resolves forwards
+ * (02:30 becomes 03:30), a repeated one to its first occurrence. An Invalid Date for anything else.
+ */
+export declare function dayTimeToDate(day: string, time: string): Date;

package/dist/types/common/virtualList/useColumns.d.ts

@@ -19,6 +19,8 @@ interface UseColumnsArgs<T> {
     containerHeight: number;
     /** Re-measure `fit` columns when the container width settles (e.g. after a route transition). */
     containerWidth: number;
+    /** Re-measure `fit` columns when rows replace the spinner under the same `items`. */
+    isLoading: boolean;
 }
 export interface UseColumnsResult<T> {
     hasColumns: boolean;
@@ -48,5 +50,5 @@ export interface UseColumnsResult<T> {
  * `fit`-column width measurement that pins one shared px track across the header
  * and every row grid so they stay aligned.
  */
-export declare function useColumns<T>({ columns, items, multiSelect, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, showColumnToggle, userWidths, isFrozen, rootRef, startIndex, endIndex, containerHeight, containerWidth, }: UseColumnsArgs<T>): UseColumnsResult<T>;
+export declare function useColumns<T>({ columns, items, multiSelect, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, showColumnToggle, userWidths, isFrozen, rootRef, startIndex, endIndex, containerHeight, containerWidth, isLoading, }: UseColumnsArgs<T>): UseColumnsResult<T>;
 export {};

package/dist/types/index.d.ts

@@ -21,6 +21,8 @@ export { default as Button } from './common/button/index.js';
 export * from './common/button/index.js';
 export { default as ButtonGroup } from './common/buttonGroup/index.js';
 export * from './common/buttonGroup/index.js';
+export { default as Calendar } from './common/calendar/index.js';
+export * from './common/calendar/index.js';
 export { default as Card } from './common/card/index.js';
 export * from './common/card/index.js';
 export { default as Carousel } from './common/carousel/index.js';

package/docs/CLAUDE.md

@@ -20,10 +20,11 @@ enums and slot names. Do not infer props from a component's name.
   RadioGroup, DatePicker, TimeInput, OtpInput, IconPicker) take `formValidator`, which then owns
   the value: `new FormValidator('', [Validators.required()])`. Whole forms use
   `useFormValidatorGroup`. See FormValidator.md and FormValidatorGroup.md.
-- **Days and times are strings**, never a `Date`: DatePicker holds `'YYYY-MM-DD'`, TimeInput
-  `'HH:MM'`. `dateToDay` and `dayToDate` convert in the browser's time zone; never use
-  `toISOString().slice(0, 10)`, which gives the UTC day. DatePicker.md shows how to turn a day
-  into a moment in a given time zone.
+- **Days and times are strings**, never a `Date`: DatePicker and Calendar's `date` hold
+  `'YYYY-MM-DD'`, TimeInput `'HH:MM'`. Calendar events are moments, so they stay `Date`s.
+  `dateToDay` and `dayToDate` convert a day in the browser's time zone, `dayTimeToDate(day, time)`
+  and `dateToTime` a day and a time together. Never use `toISOString().slice(0, 10)`, which gives
+  the UTC day. DatePicker.md shows how to turn a day into a moment in a given time zone.
 - **Styling.** `className` and `style` hit the root element; `classNames.<slot>` and `styles.<slot>`
   hit named inner elements. Slot names are on each doc's **Slots** line. Every native attribute of
   the root element passes through (`id`, `aria-*`, `data-*`, `on*`).
@@ -58,6 +59,7 @@ enums and slot names. Do not infer props from a component's name.
 | Breadcrumb.md | Breadcrumb | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
 | Button.md | Button, ButtonStyleType, ButtonSize, ButtonType | Primary interactive action trigger |
 | ButtonGroup.md | ButtonGroup, ButtonGroupOrientation | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
+| Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments, a team schedule |
 | Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
 | Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
 | Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
@@ -67,7 +69,7 @@ enums and slot names. Do not infer props from a component's name.
 | ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
 | ConfirmModal.md | ConfirmModal | Confirmation dialog before destructive or irreversible actions — delete, archive, send, overwrite |
 | CopyButton.md | CopyButton | Icon-only button that copies a value to the clipboard: an invoice number, an ID in a table row, an API key or share link inside an `Input` |
-| DatePicker.md | DatePicker, dateToDay, dayToDate | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
+| DatePicker.md | DatePicker, dateToDay, dayToDate, dateToTime, dayTimeToDate | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
 | Divider.md | Divider, DividerTextPosition, DividerOrientation | A rule that separates sections of content — horizontal by default, filling the width of its parent |
 | Drawer.md | Drawer | Inline horizontal panel that collapses and expands by animating its width — side panels, navigation rails, detail/filter panes that slide open beside the main content |
 | DropZone.md | DropZone, DropZoneReturnType, DropZoneStatus | Drag-and-drop file upload area, optionally click-to-open the native picker |

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/ConfigProvider.md

@@ -95,6 +95,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 +135,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 `ToastProvider` is already its app-wide configuration and carries `labels` itself.
 
 Each component's doc lists its own keys under **Labels:**.

package/docs/ConfirmModal.md

@@ -34,7 +34,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/Modal.md

@@ -48,7 +48,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 +92,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/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/package.json

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