@ahrowe/ui 0.42.0 → 0.44.0

package/docs/Calendar.md

@@ -1,8 +1,8 @@
 # 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).
+**When to use:** Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments. 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
+**Keywords:** schedule, scheduler, planner, appointments, booking, meetings, week view, month view, drag and drop, events, business hours, opening hours, calendar week, KW
 
 **Import:** `import { Calendar, CalendarView } from '@ahrowe/ui'`  
 **Types:** `import type { CalendarProps, CalendarEvent, CalendarRange, CalendarEventChange, CalendarEventContext, CalendarSlot, CalendarLabels, CalendarWeekday, CalendarWeekStart, CalendarSlots, CalendarDefaults } from '@ahrowe/ui'`
@@ -49,8 +49,8 @@ const [editing, setEditing] = useState<{ booking: Booking | CalendarSlot; anchor
 // 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} />
+// A working week, 08:00 to 17:00, with the rest of the day shaded
+<Calendar events={events} defaultView={CalendarView.Week} hiddenDays={[0, 6]} workingHours={[8, 17]} />
 ```
 
 **Enums:** `CalendarView`: `Month`, `Week`, `Day`, `Agenda`
@@ -59,28 +59,38 @@ const [editing, setEditing] = useState<{ booking: Booking | CalendarSlot; anchor
 
 **Events** are plain objects: `{ id, title, start, end, allDay?, color?, readOnly? }`.
 
+- `id` is **unique among `events`**. Each occurrence of a recurring series needs its own, such as `` `${seriesId}-${day}` ``: two events with one id are drawn with one React key, and a drag picks up the first of them.
 - `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.
+- `color` is a `ThemeColor` (`color: ThemeColor.Success`) or any CSS colour, see [ThemeColor.md](ThemeColor.md). 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[]>([]);
+const latest = useRef<CalendarRange | null>(null);
 
 <Calendar
   events={events}
-  onRangeChange={async ({ start, end }) => setEvents(await api.events(start, end))}
+  onRangeChange={async (range) => {
+    latest.current = range;
+    const loaded = await api.events(range.start, range.end);
+    // Paged on while this loaded: a later range's answer is the one to show.
+    if (latest.current === range) setEvents(loaded);
+  }}
 />
 ```
 
 **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 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).
+- **Whole days** are created and moved the same way in the month view and in the all-day row of the week and day views: a click creates an all-day slot on that day, a drag across days creates one over all of them, and dragging an event moves it by days.
 - 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.
+- The header's **New event** button (shown when `onSlotCreate` is set) creates on the selected day: in the week and day views the hour from the next full hour of the clock (23:00 at the latest, so it stays on that day), elsewhere the whole day. It is the keyboard's way to create.
+- A click on empty time that closes a `Popover` of this library, such as your editor, only closes it; the next click creates. A click on another event still opens that one.
 - 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
@@ -123,7 +133,11 @@ The example also:
 
 **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.
+**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; the header's **New event** button creates an all-day slot on it. 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.
+
+The week view of a narrow calendar shows **three days** from the selected one and pages by three, as seven columns at phone width leave no room for a title. The switcher still calls it Week, and `onRangeChange` reports those three days and their neighbours.
+
+**Working hours and week numbers:** `workingHours={[8, 17]}` shades the hours before 08:00 and from 17:00 in the week and day views, and makes 08:00 the hour they open at when today is not shown. `[22, 6]` is an overnight shift, shaded from 06:00 to 22:00. `showWeekNumbers` labels each row of the month view and the corner of the week and day views with its **ISO 8601** week, the numbering used across most of Europe; a week that starts on another day than Monday shows the ISO week holding most of its days. The month of a narrow calendar has no room for them and leaves them out. `labels.weekNumber` words it: ``(week) => `KW ${week}` `` in German.
 
 **Key props:**
 
@@ -131,30 +145,33 @@ The example also:
 |------|------|-------------|
 | `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`) |
+| `view` / `defaultView` / `onViewChange` | `CalendarView` | Shown view, controlled or uncontrolled (default the first of `views`) |
 | `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`) |
+| `scrollToHour` | `number` | Hour the week and day views open at, such as `6` (default an hour before now while today is shown, otherwise the start of `workingHours`, or `7`) |
+| `workingHours` | `[start, end]` | Hours of working time in the week and day views, `[8, 17]`, or `[22, 6]` overnight; the rest is shaded |
+| `showWeekNumbers` | `boolean` | ISO 8601 week numbers on the month's rows and in the week and day views' corner (default `false`) |
 | `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` |
+| `onSlotCreate` | `(slot: CalendarSlot, anchor: HTMLElement) => void` | Empty time clicked or dragged over, or the header's **New event** pressed. Setting it enables creating. `anchor` is ready for `Popover`'s `anchor`: the first day's cell in the month view, the first day's header for the all-day row, an invisible box over the new slot in the time grid, and the button itself from the header |
 | `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 |
+| `eventClassName` | `(event: E) => string \| undefined` | A class for one event's element in every view, next to `classNames.event`: a tentative, cancelled or selected event |
 | `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.
+**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. The header's **New event** button creates in every view; opened from it with the keyboard, a `Popover` editor takes the focus.
 
 **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.
+- **Dragging needs a single-pointer alternative (WCAG 2.5.7).** Creating has one, a click, and the header's button. 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`:
 
@@ -164,21 +181,22 @@ Give the calendar a height. It is `40em` tall by default and scrolls inside itse
 | `--calendar-today-color` | `var(--primary-color)` |
 | `--calendar-now-color` | `var(--error-color)` |
 | `--calendar-event-radius` | `6px` |
+| `--calendar-off-hours-color` | `var(--background-accent)` (the hours outside `workingHours`) |
 
-**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).
+**Global defaults:** `ConfigProvider` sets `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` 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`.
+**Labels:** `previous` `next` `today` `viewSwitcher` `month` `week` `day` `agenda` `allDay` `more` `eventCount` `noEvents` `newEvent` `weekNumber`: the text this component renders of its own. `more` and `eventCount` are functions of a count, `weekNumber` of the week's number. 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.
+- **One time zone, the browser's.** Every day boundary and clock time is worked out from the local `Date` fields. Showing another zone would mean routing each of them through `Intl` offset lookups, which the calendar does not do.
 - **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 resource columns.** A column per person or room, as a team schedule has, is not a view of its own.
 - **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/Card.md

@@ -4,26 +4,46 @@
 
 **Keywords:** panel, box
 
-**Import:** `import { Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions } from '@ahrowe/ui'`
+**Import:** `import { Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions, ThemeColor } from '@ahrowe/ui'`
 
-**Style variants:** `CardStyleType.Elevated` (default) | `CardStyleType.Outlined` | `CardStyleType.Filled`
+**Styles:** `Outlined` and `Light` mean what they mean on Button, Badge and Chip; `color` is the
+colour they use (a `ThemeColor`, default `Neutral`, or any CSS colour, see
+[ThemeColor.md](ThemeColor.md)). Text inside stays the page's text colour in every style. There
+is no `Filled`: body text on a solid colour reads badly.
+
+- `CardStyleType.Elevated` (default): a raised surface with a shadow, always neutral
+- `CardStyleType.Outlined`: a border in the colour, no fill. In a colour it marks one card among its neighbours, such as the current plan. Say what the mark means in text as well (a subtitle or a Badge): the colour alone is not read out
+- `CardStyleType.Light`: a flat tint of the colour, no border. In a colour it sets one card apart by a colour of its own, such as the recommended plan or a category
+
+A message about something that happened (saved, failed, almost full) is not a coloured card but an
+[Alert](Alert.md), which brings the icon, the screen-reader role and the dismiss button.
 
 ```tsx
-import { Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions } from '@ahrowe/ui';
+import { Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions, ThemeColor } from '@ahrowe/ui';
 
-// Elevated (default) — accent fill + shadow
+// Elevated (default): fill and shadow
 <Card>
-  <CardHeader title="Elevated" subTitle="Fill + shadow" />
+  <CardHeader title="Elevated" subTitle="Fill and shadow" />
 </Card>
 
-// Outlined — transparent, defined by a border, no shadow
+// Outlined: transparent, defined by a border, no shadow
 <Card styleType={CardStyleType.Outlined}>
   <CardHeader title="Outlined" />
 </Card>
 
-// Filled — flat accent fill, no shadow
-<Card styleType={CardStyleType.Filled}>
-  <CardHeader title="Filled" />
+// Light: flat fill, no shadow
+<Card styleType={CardStyleType.Light}>
+  <CardHeader title="Light" />
+</Card>
+
+// The selected plan, bordered in the primary colour
+<Card styleType={CardStyleType.Outlined} color={ThemeColor.Primary}>
+  <CardHeader title="Pro" subTitle="Your current plan" />
+</Card>
+
+// The recommended plan, tinted
+<Card styleType={CardStyleType.Light} color={ThemeColor.Primary}>
+  <CardHeader title="Team" subTitle="Recommended for 5 people or more" />
 </Card>
 
 <Card hoverEffect onClick={handleClick}>
@@ -39,7 +59,7 @@ import { Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions }
   <CardActions
     actions={[
       { id: 'edit', label: 'Edit', onClick: handleEdit },
-      { id: 'delete', label: 'Delete', styleType: ButtonStyleType.Delete, onClick: handleDelete },
+      { id: 'delete', label: 'Delete', color: ThemeColor.Error, onClick: handleDelete },
     ]}
   />
 </Card>
@@ -49,15 +69,16 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 
 **Enums:**
 
-- `CardStyleType`: `Elevated` (default) | `Outlined` | `Filled`
+- `CardStyleType`: `Elevated` (default) | `Outlined` | `Light`
 
 **CardProps:**
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `styleType` | `CardStyleType` | Surface variant — `Elevated` (fill + shadow), `Outlined` (transparent + border), `Filled` (flat fill) |
+| `styleType` | `CardStyleType` | `Elevated` (default, fill and shadow), `Outlined` (a border) or `Light` (a flat fill) |
+| `color` | `ColorValue` | The border of `Outlined` and the tint of `Light`: a `ThemeColor` (default `Neutral`, the theme's card surfaces) or any CSS colour. `Elevated` ignores it |
 | `onClick` | `() => void` | Makes the card clickable, by pointer and by Enter/Space. A click or key on a control inside the card (a field, a link, a button, anything with an interactive `role`) is that control's, and neither fires this nor ripples |
-| `hoverEffect` | `boolean` | Adds hover elevation |
+| `hoverEffect` | `boolean` | Lifts the card on hover and tints it in its text colour, over whatever its style and colour paint |
 | `tabIndex` | `number \| null` | For keyboard navigation |
 | `autoGap` | `boolean` | Space stacked sub-components apart with a shared gap (default `true`); set `false` to space them yourself |
 | `clip` | `boolean` | Clip content to the rounded corners (`overflow: hidden`, default `false`). Set `true` for full-bleed `CardMedia` or a clipped hover/ripple effect. Safe to enable even when the card holds a `Dropdown`/`Popover`/`Tooltip` — those popovers are portaled and always escape the card regardless of this setting |
@@ -75,7 +96,7 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `actions` | `CardAction[]` | Array of `{ id, label, styleType, onClick }` renders Buttons |
+| `actions` | `CardAction[]` | Array of `{ id, label, styleType, color, onClick }` renders Buttons (`Outlined` `Primary` unless set) |
 | `children` | `ReactNode` | Custom content instead of `actions` |
 
 ## Sizing
@@ -85,3 +106,21 @@ Card is spaced by its font: the padding, the header's gap and thumbnail, the gap
 `CardMedia` bleeds to the card's edges with a negative margin that has to stay equal to the padding, so change the two together.
 
 **Slots:** `root` `content`
+
+## Migration from `Filled`
+
+Before 0.43 the flat style was called `Filled`. It is `Light` now, the name the library's other
+components use for the same look. TypeScript points at each use:
+
+| Before | After |
+|--------|-------|
+| `styleType={CardStyleType.Filled}` | `styleType={CardStyleType.Light}` |
+
+`defaultTheme` and `lightTheme` still draw it in `Neutral` in `--background-accent`, through
+`--background-card-filled`. A theme that does not set that variable now gets the see-through tint
+of the text colour that every other `Light` uses, where it used to get `--background-accent`. On a
+dark theme that tint is about as light as `Elevated`, so set the variable there to keep the two
+apart.
+
+A card with `hoverEffect` no longer turns `--background-accent` on hover: it keeps its own surface
+and gets a light tint in its text colour over it, so a coloured card keeps its colour.

package/docs/Checkbox.md

@@ -33,7 +33,7 @@ const agreedValidator = new FormValidator(false, [Validators.required()]);
 | `onToggle` | `(isToggled: boolean, event?) => void` | Change handler |
 | `formValidator` | `FormValidator` | Connects to form validation |
 | `disabled` | `boolean` | |
-| `isLoading` | `boolean` | Shows skeleton state |
+| `isLoading` | `boolean` | Shows a [Loader](Loader.md) in place of the box and ignores clicks |
 | `children` | `ReactNode` | Custom label content |
 | `cursorDefault` | `boolean` | Use default cursor instead of pointer |
 | `ref` | `Ref<HTMLDivElement>` | Ref to the root element |

package/docs/Chip.md

@@ -4,20 +4,22 @@
 
 **Keywords:** pill
 
-**Import:** `import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui'`
+**Import:** `import { Chip, ChipContainer, ChipStyleType, ThemeColor } from '@ahrowe/ui'`
 
-**Style variants:** `ChipStyleType.Default` (default) | `ChipStyleType.Primary` | `ChipStyleType.Info` | `ChipStyleType.Warn` | `ChipStyleType.Error`
+**Styles:** `ChipStyleType.Light` (default) | `ChipStyleType.Filled` | `ChipStyleType.Outlined`, in any `color`: a `ThemeColor` (default `Neutral`) or any CSS colour, see [ThemeColor.md](ThemeColor.md).
 
 ```tsx
-import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui';
+import { Chip, ChipContainer, ChipStyleType, ThemeColor } from '@ahrowe/ui';
 
 // Basic chip
 <Chip text="React" />
 
-// Coloured variants
-<Chip text="Primary" styleType={ChipStyleType.Primary} />
-<Chip text="Warning" styleType={ChipStyleType.Warn} />
-<Chip text="Error" styleType={ChipStyleType.Error} />
+// Colours: a light tint by default
+<Chip text="Warning" color={ThemeColor.Warn} />
+<Chip text="Error" color={ThemeColor.Error} />
+
+// A selected filter: filled in the primary colour
+<Chip text="Active" styleType={ChipStyleType.Filled} color={ThemeColor.Primary} onClick={toggle} />
 
 // Removable chip
 <Chip
@@ -47,14 +49,15 @@ import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui';
 
 **Enums:**
 
-- `ChipStyleType`: `Default` (default) | `Primary` | `Info` | `Warn` | `Error`
+- `ChipStyleType`: `Light` (default) | `Filled` | `Outlined`
 
 **ChipProps:**
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `text` | `string` | Chip label |
-| `styleType` | `ChipStyleType` | Colour variant (default `Default`) |
+| `styleType` | `ChipStyleType` | `Light` (default), `Filled` or `Outlined` |
+| `color` | `ColorValue` | A `ThemeColor` (default `Neutral`) or any CSS colour |
 | `thumbnail` | `string` | Avatar image URL |
 | `labels.remove` | `string` | Accessible name for the remove button. Default: `'Remove'` |
 | `showRemoveIcon` | `boolean` | Show × icon |
@@ -70,3 +73,15 @@ import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui';
 **Labels:** `remove` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `ChipLabels`.
 
 **Slots:** `root` `inner` `thumbnail` `text` `removeIcon`
+
+## Migration from colour styles
+
+Before 0.43, `ChipStyleType` was a colour, and `Primary` was filled while the others were a light
+tint. Style and colour are now separate props. The old members are gone and TypeScript points at
+each:
+
+| Before | After |
+|--------|-------|
+| `styleType={ChipStyleType.Default}` | nothing: `Light` `Neutral` is the default |
+| `styleType={ChipStyleType.Primary}` | `styleType={ChipStyleType.Filled} color={ThemeColor.Primary}` |
+| `styleType={ChipStyleType.Info}` (and `Warn`, `Error`) | `color={ThemeColor.Info}` |

package/docs/ConfigProvider.md

@@ -95,10 +95,10 @@ A nested provider inherits it unless it sets its own, the same way `defaultProps
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
-- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
+- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Loader` · `LoadingOverlay` · `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)
+- **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` only (see below)
 
 ```tsx
 <ConfigProvider
@@ -106,7 +106,7 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
     Input: { alwaysFloatLabel: true },
     Dropdown: { useMatLabelStyle: true },
     NumberInput: { decimalScale: 2, thousandSeparator: '.' },
-    Button: { styleType: ButtonStyleType.Primary },
+    Button: { styleType: ButtonStyleType.Filled },
     Card: { styleType: CardStyleType.Outlined },
     Skeleton: { animation: SkeletonAnimation.Pulse },
   }}
@@ -138,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. `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.
+`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`, `scrollToHour`, `workingHours` and `showWeekNumbers`. `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/CopyButton.md

@@ -8,7 +8,7 @@
 **Types:** `import type { CopyButtonProps, CopyButtonLabels } from '@ahrowe/ui'`
 
 ```tsx
-import { CopyButton, Input } from '@ahrowe/ui';
+import { CopyButton, Input, ThemeColor, showToast } from '@ahrowe/ui';
 
 <span>
   {invoice.number} <CopyButton value={invoice.number} />
@@ -18,10 +18,10 @@ import { CopyButton, Input } from '@ahrowe/ui';
 <Input label='API key' value={apiKey} readOnly suffix={<CopyButton value={apiKey} />} />
 
 // a toast on success, where the button is not where the user is looking
-<CopyButton value={url} onCopy={() => showToast('Link copied', { type: 'success' })} />
+<CopyButton value={url} onCopy={() => showToast('Link copied', { color: ThemeColor.Success })} />
 ```
 
-After a click the icon rotates into a check (through `AnimatedIcon`, held still under `prefers-reduced-motion`) for `timeout` ms, the accessible name and tooltip read "Copied", and a polite live region announces it, because a swapped icon or a changed `aria-label` alone is not read out. A refused write (an insecure context, a blocked iframe) announces "Could not copy" and calls `onError`; the icon stays as it was. `CopyButton` shows no toast of its own: pass one through `onCopy` / `onError` if you want it.
+It is an [ActionIcon](ActionIcon.md), so it takes the same `styleType` and `color`, and turns `Success` while copied. After a click the icon rotates into a check (through `AnimatedIcon`, held still under `prefers-reduced-motion`) for `timeout` ms, the accessible name and tooltip read "Copied", and a polite live region announces it, because a swapped icon or a changed `aria-label` alone is not read out. A refused write (an insecure context, a blocked iframe) announces "Could not copy" and calls `onError`; the icon stays as it was. `CopyButton` shows no toast of its own: pass one through `onCopy` / `onError` if you want it.
 
 The live region is rendered as a sibling of the button, so `CopyButton` returns two elements. It is visually hidden and takes no space.
 
@@ -35,8 +35,9 @@ The live region is rendered as a sibling of the button, so `CopyButton` returns
 | `copiedIcon` | `IconDefinition \| ReactElement` | Icon while copied (default `faCheck`) |
 | `onCopy` | `(value: string) => void` | Called after a successful copy |
 | `onError` | `() => void` | Called when the clipboard refuses the write. `useClipboard` returns the reason |
-| `onClick` | `(event: MouseEvent) => void` | Called on every click, before the copy |
-| `ref` | `Ref<HTMLDivElement>` | Ref to the button |
+| `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | Called on every click, before the copy |
+| `color` | `ColorValue` | Its colour at rest (default `Neutral`); `Success` while copied |
+| `ref` | `Ref<HTMLButtonElement>` | Ref to the button |
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ CopyButton: { timeout: 1500 } }}`. See [ConfigProvider.md](ConfigProvider.md).
 

package/docs/Loader.md

@@ -0,0 +1,95 @@
+# Loader
+
+**When to use:** A loading indicator for something in progress with no known end: a fetch, a save, a connection. To cover content while it reloads use [LoadingOverlay.md](LoadingOverlay.md), for a button use `Button`'s own `isLoading`, and for content not there yet a [Skeleton.md](Skeleton.md) in its shape reads better. For progress you can measure, use [ProgressBar.md](ProgressBar.md).
+
+**Keywords:** busy, waiting, activity indicator, throbber, async, fetching, typing indicator, equalizer, radar, ripple
+
+**Import:** `import { Loader, LoaderType, ThemeColor } from '@ahrowe/ui'`  
+**Types:** `import type { LoaderProps, LoaderLabels } from '@ahrowe/ui'`
+
+**Enums:** `LoaderType.Spinner` (default) | `LoaderType.Comet` | `LoaderType.Dots` | `LoaderType.Bars` | `LoaderType.Pulse`
+
+- `Spinner`: an arc that grows and shrinks on a faint track. Reads at any size, down to 16px
+- `Comet`: a glowing head trailing a tapering tail round a ring. For a hero spot: a page, a panel, an overlay
+- `Dots`: three dots in a wave. For a line of text or a reply being written
+- `Bars`: bars rising and falling like an equaliser. For media, uploads and data being processed
+- `Pulse`: rings rippling out from a core. For waiting on something outside the app: a device, a connection, a search
+
+```tsx
+import { Loader, LoaderType, ThemeColor } from '@ahrowe/ui';
+
+// Default: a Spinner in --primary-color, 2.5em square
+{isLoading && <Loader />}
+
+<Loader type={LoaderType.Comet} size='4em' />
+<Loader type={LoaderType.Pulse} color={ThemeColor.Success} />
+<Loader type={LoaderType.Bars} color='#e879f9' size={24} />
+
+// In a line of text: Neutral takes the text's own colour, 1em its size. Dots rest on the
+// baseline like an ellipsis; the round types sit centred on the text like an icon
+<p>Ava is typing <Loader type={LoaderType.Dots} size='1em' color={ThemeColor.Neutral} /></p>
+```
+
+**Sizing:** `size` sets width and height, which are always equal. It is `2.5em` by default, so a
+loader follows the font size of what it sits in; pass any CSS length, or a number of pixels. Size it
+with `size` rather than a `width` in a class: the stylesheet reads `size`, and a class would tie with
+it on specificity.
+
+**Colour:** `color` takes a `ThemeColor` (default `Primary`) or any CSS colour, see
+[ThemeColor.md](ThemeColor.md). `ThemeColor.Neutral` takes the colour of the text around it, which
+is what a loader on a coloured surface wants.
+
+## One type for the whole app
+
+Every component with a loading state draws it with this `Loader`: `Button` (and so `SplitButton`,
+`ActionButtons` and `ConfirmModal`), `Checkbox`, `VirtualList`, `Dropdown`, `KanbanBoard` and
+`LoadingOverlay`. A default set once reaches all of them:
+
+```tsx
+<AhroweProvider defaultProps={{ Loader: { type: LoaderType.Dots } }}>
+  <App />
+</AhroweProvider>
+```
+
+An app-wide `type` and `labels` reach all of them. `color` reaches all but Button's, which keeps
+the button's text colour. `size` reaches only `LoadingOverlay`'s default loader and the ones you
+place yourself; the others size theirs to fit.
+
+**Accessibility:** the root is a `role="progressbar"` with no value, which is how an indeterminate
+progress indicator is announced, named "Loading" (`labels.loading`). Pass `aria-labelledby` to name
+it after visible text instead, as `LoadingOverlay` does with its `message`. Inside something whose
+name comes from its content (a custom checkbox) or that may only hold its own items (a list), pass
+`aria-hidden` and mark the container `aria-busy` instead, as `Checkbox` and `VirtualList` do.
+
+**Note:** a loader keeps moving under `prefers-reduced-motion`. One that stands still says the app
+has hung, which is the opposite of what it is there to say.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `type` | `LoaderType` | The animation (default `Spinner`) |
+| `size` | `number \| string` | Width and height, any CSS length or a number of pixels (default `'2.5em'`) |
+| `color` | `ColorValue` | A `ThemeColor` or any CSS colour (default `ThemeColor.Primary`) |
+| `labels` | `LoaderLabels` | Text the loader produces itself, see below |
+| `className` / `style` | | Root `span` |
+
+**Labels:** `loading`, the accessible name. Pass `labels` to override it, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `LoaderLabels`.
+
+## Migration from `SpinnerLoading`
+
+`SpinnerLoading` was removed in favour of `Loader`, whose default type is the same kind of spinner.
+
+```tsx
+// Before
+<SpinnerLoading className="my-spinner" />   // .my-spinner { width: 24px; height: 24px }
+
+// After
+<Loader size={24} />
+```
+
+It used to be 70px by default and is `2.5em` now (40px at a 16px base), and it is a `span` rather
+than an `svg`. It is announced as a progressbar named "Loading", where `SpinnerLoading` was not
+announced at all.
+
+**Slots:** none. The root `span` takes `className` and `style`.

package/docs/LoadingOverlay.md

@@ -0,0 +1,85 @@
+# LoadingOverlay
+
+**When to use:** Covering content while it reloads: a table refreshing, a form saving, a panel fetching its next page. It frosts over what it wraps and keeps its shape in view. For content not there yet a [Skeleton.md](Skeleton.md) in its shape reads better, and a lone indicator with nothing to cover is a [Loader.md](Loader.md).
+
+**Keywords:** spinner, frosted glass, scrim, dim, disable interaction, pending, mask
+
+**Import:** `import { LoadingOverlay, Loader, LoaderType } from '@ahrowe/ui'`  
+**Types:** `import type { LoadingOverlayProps } from '@ahrowe/ui'`
+
+```tsx
+import { LoadingOverlay, Loader, LoaderType, AnimatedLogo, ThemeColor } from '@ahrowe/ui';
+
+// Wrap what is loading. It needs no positioned parent: it is one
+<LoadingOverlay isLoading={isFetching}>
+  <InvoiceTable rows={rows} />
+</LoadingOverlay>
+
+// A message under the loader, with a highlight sweeping across it
+<LoadingOverlay isLoading={isSaving} message="Saving changes…">
+  <ProfileForm />
+</LoadingOverlay>
+
+// Any loader in place of the default one
+<LoadingOverlay
+  isLoading={isConnecting}
+  message="Connecting to the printer…"
+  loader={<Loader type={LoaderType.Pulse} color={ThemeColor.Success} size="3.5em" />}
+>
+  <PrinterPanel />
+</LoadingOverlay>
+
+// A branded one
+<LoadingOverlay isLoading={isBooting} loader={<AnimatedLogo size="4em" />}>
+  <Dashboard />
+</LoadingOverlay>
+```
+
+## Timing
+
+The overlay waits `delay` (200ms) after `isLoading` turns true before it shows, so a load that
+finishes faster never flashes it. Once shown it stays at least 400ms, so one that finishes just
+after it appeared does not flash it either, then fades out. Loading again while it fades brings it
+straight back. `delay={0}` shows it at once, from the first render on.
+
+The content is marked `aria-busy` the moment `isLoading` is true, delay or not.
+
+## What it blocks
+
+The backdrop takes every pointer event over the content and shows a `progress` cursor. It does not
+take the focus or block the keyboard: making the content `inert` would drop the focus of whoever
+pressed the button that started the load. An action that must not run twice should still check its
+own loading state.
+
+**Wrapping:** the root is a `div` with `position: relative`, and the content sits in a `div` of its
+own, so anything inside with a `z-index` (a sticky header) stays under the backdrop. The backdrop
+takes the root's `border-radius`, so a `className` that rounds the root rounds the overlay too.
+Content taller than the screen keeps the loader in view rather than at its middle.
+
+**Scrolling content:** give the scrolling to `classNames.content` (its `overflow` and its height
+limit), not to the root. The backdrop covers the root's box, so in a root that scrolls it would
+scroll away with the content and leave the rest uncovered.
+
+**Theme variables:** `--loading-overlay-background` (the veil, default `--background` at 50%) and
+`--loading-overlay-blur` (default `4px`, `0px` turns the blur off). See
+[ThemeProvider.md](ThemeProvider.md).
+
+**App-wide:** `LoadingOverlay` takes `defaultProps` like any other component, so one
+`AhroweProvider` can give every overlay the same `loader` or `delay`. Its default loader is a
+`Loader`, which follows `defaultProps.Loader` as well.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `isLoading` | `boolean` | Covers the content, blocks the pointer and marks it `aria-busy` (default `false`) |
+| `children` | `ReactNode` | What the overlay covers |
+| `message` | `ReactNode` | Text under the loader. Also the default loader's accessible name |
+| `loader` | `ReactNode` | Shown in place of the default `<Loader />` |
+| `delay` | `number` | Milliseconds before it shows (default `200`) |
+| `className` / `style` | | Root `div` |
+
+**Note:** under `prefers-reduced-motion` the panel fades in without rising and the message stands
+still. The loader itself keeps moving, see [Loader.md](Loader.md).
+
+**Slots:** `content` (the `div` around `children`) `backdrop` (the veil over it) `panel` (the column holding the loader and the message, for a card behind them) `message`

package/docs/ProgressBar.md

@@ -7,15 +7,15 @@
 **Import:** `import { ProgressBar } from '@ahrowe/ui'`
 
 ```tsx
-import { ProgressBar } from '@ahrowe/ui';
+import { ProgressBar, ThemeColor } from '@ahrowe/ui';
 
 // Simple percentage
 <ProgressBar progress={75} total={100} />
 
-// Single progress with label and custom colour
+// Single progress with label, in a theme colour
 <ProgressBar
   total={100}
-  progress={{ amount: 60, label: 'Used', color: '#6200ea' }}
+  progress={{ amount: 60, label: 'Used', color: ThemeColor.Warn }}
 />
 
 // Stacked / segmented bar
@@ -39,9 +39,12 @@ import { ProgressBar } from '@ahrowe/ui';
 **Progress object:**
 
 ```ts
-{ amount: number; label?: string; color?: string; class?: string }
+{ amount: number; label?: string; color?: ColorValue; class?: string }
 ```
 
+`color` is a `ThemeColor` or any CSS colour (see [ThemeColor.md](ThemeColor.md)), `--primary-color`
+when unset. A label on a coloured segment is black or white, whichever reads on it.
+
 **Theming:** override theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`; falls back to a built-in default when unset:
 
 | Variable | Falls back to |

package/docs/SectionHeader.md

@@ -77,7 +77,7 @@ import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
 interface SectionHeaderAction {
   title?: string;
   icon: IconDefinition | ReactElement;
-  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
 }
 ```