@ahrowe/ui 0.41.2 → 0.43.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/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

@@ -98,7 +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)
+- **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/FloorPlan.md

@@ -4,7 +4,7 @@
 
 **Keywords:** blueprint, cad, grundriss, apartment, building, storey, partition, area calculation, planar graph, half-edge, extrusion
 
-**Import:** `import { emptyFloorPlan, addWall, derivePlan } from '@ahrowe/ui'`
+**Import:** `import { emptyFloorPlan, addWall, derivePlan } from '@ahrowe/ui'`, or from `'@ahrowe/ui/floor-plan'` where there is no React
 **Types:** `import type { FloorPlan, PlanFloor, PlanNode, PlanWall, PlanOpening, PlanRoom, DerivedRoom, PlanPoint, PlanView, PlanSelection } from '@ahrowe/ui'`
 
 `PlanPoint`, `PlanView` and `PlanSelection` are the ones that also appear in `RoomDrawer` and `RoomViewer` props. Every exported function's own option and result types come with it — `WallAttrs`, `SplitWallResult`, `WallPathResult` and the rest.
@@ -80,7 +80,7 @@ const { floor: refreshed, rooms, issues } = derivePlan(floor);
 
 `derivePlan` extracts the faces and attaches stored metadata. It is pure and **never creates or deletes a `PlanRoom`**, so it is safe to call on every render. Memoise it on `plan.revision`, which every mutation bumps.
 
-`commitDerivation(floor)` mints a `PlanRoom` for each face that matched nothing — call it once per committed edit, not per render.
+`commitDerivation(floor, options?)` mints a `PlanRoom` for each face that matched nothing — call it once per committed edit, not per render. It names them `Room 1`, `Room 2`, … counting the floor's rooms and skipping any name already taken; `nameFor: (n, face) => string` replaces the name with the same numbering, so `` (n) => `Raum ${n}` `` gives `Raum 3` on a floor with two rooms. `addFloor` takes the same `nameFor` for `Floor 2`, `Floor 3`, …, and `duplicateFloor` a `label` in place of `<name> copy`.
 
 Each `DerivedRoom` carries the face (`outer`, `holes`, `area`, `perimeter`, `wallIds`), the matched `meta`, and an `anchor` guaranteed to be **inside** the polygon (an area centroid can fall outside a concave room, so it is computed, not averaged).
 
@@ -172,6 +172,22 @@ else if (issues.length) console.warn(issues);   // loaded, but repaired
 
 `revision` is bumped on load, since `derivePlan` memoises on it and the repaired plan is not the one the file described.
 
+### On a server
+
+`@ahrowe/ui/floor-plan` is the whole model, and only the model: every function and type on this page, with no React, react-dom or FontAwesome behind it and no `'use client'` in front of it. That is what lets a Node server check a plan with the same code the client drew it with, instead of storing whatever it was sent.
+
+```ts
+import { planFromJson, validatePlan } from '@ahrowe/ui/floor-plan';
+
+export function readPlan(json: string) {
+  const { plan, issues } = planFromJson(json);
+  if (!plan) throw new Error(issues.join('; '));
+  return { plan, repaired: issues, broken: plan.floors.flatMap((floor) => validatePlan(floor)) };
+}
+```
+
+`@ahrowe/ui` exports the same functions, so client code can keep importing from there.
+
 ## Snapping and pointer input
 
 ```tsx
@@ -195,18 +211,6 @@ const issues = validatePlan(floor); // O(walls²) — development and tests, not
 
 The invariant that matters: **no two walls may cross without a node at the intersection, and no node may sit on a wall's interior without that wall being split there.** Break either and the face walk silently merges two rooms into one figure-eight face with no error anywhere, which is why `UnsplitCrossing` and `UnsplitNodeOnWall` exist as explicit issue kinds. Everything built through `addWall` maintains this automatically.
 
-## Importing older plans
-
-```tsx
-import { planFromLegacySvg } from '@ahrowe/ui';
-
-// The old canvas was unitless; pick the factor that makes it millimetres.
-// A 400-unit-wide export meant to be a 12m house wants scale: 30.
-const plan = planFromLegacySvg(svgText, { scale: 30 });
-```
-
-Feeding every legacy polygon edge through `addWall` is what collapses the old duplicated walls: the second room's copy of a shared edge resolves to the same two nodes and is recognised as already walled. Room names carry across, and doors are recovered where the old swing-arc path is recognisable; anything that is not is skipped rather than guessed at.
-
 ## Ready for 3D
 
 `buildPlanMesh(floor, options?)` turns a storey into triangles: wall solids with their openings cut out, and a slab under each room.

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

@@ -246,7 +246,7 @@ ref.current?.deleteSelection();
 | `wallThickness` / `wallHeight` | `number` | Millimetres, applied to newly drawn walls |
 | `openingDefaults` | `Partial<Record<OpeningKind, { width?, sill?, head? }>>` | Size of newly placed openings |
 | `showMeasurements` | `boolean` | Live length, angle and area readouts while drawing (default `true`) |
-| `formatLength` / `formatArea` | `(mm) => string` | Override the readouts |
+| `formatLength` / `formatArea` / `formatAngle` / `formatZoom` | `(value) => string` | Override the readouts: millimetres, mm², degrees from -180 to 180, and zoom in screen px per mm. See [Localisation](#localisation) |
 | `showToolbar` / `showInspector` / `showHint` / `showHistoryControls` / `showFileControls` / `showFloorBar` | `boolean` | Hide parts of the chrome |
 | `floorId` / `defaultFloorId` / `onFloorChange` | `string` / `string` / `(id) => void` | Which storey is being edited |
 | `showUnderlay` | `boolean` | Trace the storey below behind this one (default `true`) |
@@ -258,7 +258,7 @@ ref.current?.deleteSelection();
 | `disabled` | `boolean` | No interaction at all |
 | `canvasHeight` | `string` | Any CSS length (default `'420px'`) |
 | `getRoomColor` / `renderRoomLabel` | | Per-room fill colour and label content |
-| `labels` / `icons` | `RoomDrawerLabels` / `RoomDrawerIcons` | Localise or re-icon the chrome |
+| `labels` / `icons` | `RoomDrawerLabels` / `RoomDrawerIcons` | Localise or re-icon the chrome, and name new rooms and floors |
 
 `RoomDrawerProps` extends the full native `div` attribute set plus `data-*`, so `id`, `title`, `aria-*` and the rest pass through to the root.
 
@@ -292,7 +292,7 @@ Floors are part of the plan document, so they survive a download and reopen with
 
 A bar under the canvas shows what is selected and what can be done with it: a name for a room, thickness for a wall, width and sill for an opening, and delete for any of them. It is **always there and always the same height**, including when nothing is selected — it used to appear on selection and size itself to its contents, which moved the canvas out from under the pointer by up to 116px as you clicked between a corner and a wall.
 
-Each selection is named on the left (`Room`, `Wall`, `Door`, `Corner`, `3 selected`), which is the whole content of the bar for a corner: a corner has nothing to edit that dragging it does not already do. Delete sits at the far end, apart from the fields, since it is the one action that applies to every kind of selection and the only destructive one. Override any of the names through `labels` (`selectedRoom`, `selectedWall`, `selectedCorner`, `selectedOpening`, `selectedCount`, `selectedNothing`), and hide the bar with `showInspector={false}`.
+Each selection is named on the left (`Room`, `Wall`, `Door`, `Corner`, `3 selected`), which is the whole content of the bar for a corner: a corner has nothing to edit that dragging it does not already do. Delete sits at the far end, apart from the fields, since it is the one action that applies to every kind of selection and the only destructive one. Override any of the names through `labels` (`selectedRoom`, `selectedWall`, `selectedCorner`, `selectedDoor`, `selectedWindow`, `selectedArchway`, `selectedGap`, `selectedCount`), and hide the bar with `showInspector={false}`.
 
 **Sill**, on an opening, is how far above the floor it starts: 0 for a door, around 900 for a window. It changes nothing in the plan, because a plan is a horizontal cut and every opening looks the same from above. It is stored so the same plan can drive a 3D view later without anyone having to supply the heights again — as are `head` (the top of the opening), `PlanWall.height` and `PlanFloor.elevation`.
 
@@ -358,20 +358,49 @@ Stated plainly: **a free-form drawing canvas cannot be fully operated from a key
 
 The root is `role="application"` (justified here, since single-letter keys are intercepted), the toolbar is a real `role="toolbar"` of `<button>`s with `aria-pressed`, and room labels render with a halo so they stay legible over any fill colour a consumer sets.
 
-## Global defaults
+## Localisation
 
-Adopts `ConfigProvider`, e.g. `defaultProps={{ RoomDrawer: { gridSize: 250, showGrid: false } }}`. See [ConfigProvider.md](ConfigProvider.md).
+Every string the drawer produces goes through `labels`, and every number it prints through a `format*` prop. Set them once, app-wide: labels merge per key, so an instance that overrides one string keeps the rest.
+
+Some of those strings end up **in the plan**, not only on screen: the names of the rooms and floors the drawer creates. A plan saved before they were translated keeps "Room 1" and "Ground floor" for good, so set them from the start.
 
-## Migration from the previous version
+```tsx
+const number = new Intl.NumberFormat('de-AT', { maximumFractionDigits: 1 });
+const percent = new Intl.NumberFormat('de-AT', { style: 'percent', maximumFractionDigits: 1 });
+
+<AhroweProvider
+  defaultProps={{
+    RoomDrawer: {
+      labels: {
+        newRoomName: (n) => `Raum ${n}`,
+        newFloorName: (n) => `Etage ${n}`,
+        copiedFloorName: (name) => `${name} (Kopie)`,
+        initialFloorName: 'Erdgeschoss',
+        angleLock: (angle) => `Auf ${angle}°-Schritte einrasten`,
+        selectedCount: (count) => `${count} ausgewählt`,
+        selectedDoor: 'Tür',
+        hintSelect: 'Ecke ziehen zum Umformen · …',
+        hintSelectSingle: 'Ecke ziehen zum Umformen · …',
+      },
+      formatLength: (mm) => `${number.format(mm / 1000)} m`,
+      formatArea: (mm2) => `${number.format(mm2 / 1e6)} m²`,
+      formatAngle: (degrees) => `${number.format(degrees)}°`,
+      formatZoom: (zoom) => percent.format(zoom),
+    },
+  }}
+>
+  <App />
+</AhroweProvider>
+```
 
-The previous `RoomDrawer` had no data contract at all: `RoomDrawerProps` was `{ className }`, and the only way data left the component was a browser file download. Everything below is new rather than changed, so the old usage still renders, it just starts empty.
+A label that carries a value is a function of it: `angleLock` gets `constrainAngle`, `selectedCount` the count, `copiedFloorName` the name of the floor being copied, and `newRoomName` and `newFloorName` the next number whose name is not taken yet. `hintSelect` is the hint with `multiSelect` on and `hintSelectSingle` the one with it off. `formatZoom` gets screen pixels per millimetre, which is the fraction `Intl`'s `percent` style expects.
 
-- `Tool`, `RoomData`, `DoorData`, `Point` are gone. Use `RoomDrawerTool` and the `FloorPlan` model.
-- `selection` is an array rather than a single entry, since the drawer supports multi-select. A single selection is `[entry]`, and nothing selected is `[]` rather than `null`.
-- The SVG download and upload buttons are gone. The plan JSON is the interchange format now. To read an SVG exported by the old version, use `planFromLegacySvg` (see [FloorPlan.md](FloorPlan.md)), which also collapses each duplicated room boundary into the single shared wall it should have been.
-- The `polygon` tool is now `wall`, which draws open chains as well as closed ones.
-- Removing a corner was a double-click, which was undiscoverable and impossible on touch. Select it and press `Delete` instead.
+Two texts are not in `labels`. The root's accessible name is the `aria-label` prop (default "Floor plan editor"), which `defaultProps` can set as well. The repair report after opening a file is `planFromJson`'s list of English sentences, shown as it comes; `onImport` receives it too, if you would rather show your own.
+
+## Global defaults
+
+Adopts `ConfigProvider`, e.g. `defaultProps={{ RoomDrawer: { gridSize: 250, showGrid: false } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `toolbar` `toolButton` `toolIcon` `viewControls` `viewButton` `zoomLabel` `canvasWrapper` `canvas` `grid` `rooms` `roomFill` `roomLabel` `walls` `wallBody` `openings` `opening` `overlay` `measureLine` `floorBar` `floorTab` `inspector` `inspectorLabel` `inspectorField` `hint`
 
-**Labels:** every string the drawer's own chrome renders, including `tools`, `storeyHeightHint` and `sillHeightHint`. Type: `RoomDrawerLabels`.
+**Labels:** every string the drawer's own chrome renders, including `tools`, `storeyHeightHint` and `sillHeightHint`, and the names it gives new rooms and floors. Type: `RoomDrawerLabels`.

package/docs/RoomViewer.md

@@ -72,7 +72,7 @@ Walls are drawn as mass rather than as ink: the body is `var(--text-color)` mixe
 | `getRoomColor` / `renderRoomLabel` / `getRoomLabel` / `formatArea` | functions | Colour, label and area rendering |
 | `height` | `number \| string` | Canvas height (default `360`) |
 | `emptyState` | `ReactNode` | Shown when there is no plan, or nothing in it |
-| `labels` / `icons` | objects | Every string and icon in the chrome |
+| `labels` / `icons` | objects | Every string and icon in the chrome. `selectedRoom` is `(name, area) => string`, and `unnamedRoom` stands in for a room with no name |
 
 **Imperative handle:** `fitToContent(options?)`, `getView()`, `setView(view)`, `zoomBy(factor)`, `select(roomId)`, `getFloorId()`, `setFloorId(id)`, `getSvgElement()`.
 
@@ -81,16 +81,3 @@ Walls are drawn as mass rather than as ink: the body is `var(--text-color)` mixe
 ## Accessibility, honestly
 
 A free-form plan cannot be fully keyboard operated, and this does not pretend otherwise. What it does give you: every room is a focusable `role="button"` with an accessible name, `Enter`/`Space` select, the floor tabs are real buttons, the zoom controls are real buttons, and the current selection is announced. Panning and zooming are pointer-only; the zoom buttons and `fitToContent()` are the keyboard path.
-
-## Migration from the previous version
-
-The old viewer took `data: { label, data: ReactNode }[]` — an array of **pre-rendered SVG elements** — and found rooms by looking for `id="room…"`, highlighting them by mutating `classList`. That is gone, and there is no shim: the old `data` was a React element rather than a string, so there is nothing to parse at runtime.
-
-| Before | Now |
-|--------|-----|
-| `data={[{ label, data: <svg/> }]}` | `plan={plan}` — one `FloorPlan`, floors and all |
-| `id="room12"` convention | `PlanRoom` ids in the model |
-| Highlighting via `classList` | `selectedRoomId` / `hoveredRoomId` |
-| No selection callback | `onSelect(roomId, room, floorId)` |
-
-To bring an old SVG across, run it through `planFromLegacySvg` once and keep the resulting plan. See [FloorPlan](./FloorPlan.md).

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;
 }
 ```