@ahrowe/ui 0.42.0 → 0.43.0

package/docs/Button.md

@@ -1,37 +1,57 @@
 # Button
 
-**When to use:** Primary interactive action trigger. Supports loading state, icon, multiple visual styles and sizes.
+**When to use:** Primary interactive action trigger. Supports loading state, icon, four styles in any colour, and sizes.
 
-**Keywords:** cta, action button
+**Keywords:** cta, action button, ghost, text button, borderless, subtle, variant, danger, destructive, secondary
 
-**Import:** `import { Button, ButtonStyleType, ButtonSize, ButtonType } from '@ahrowe/ui'`
+**Import:** `import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui'`
+
+A button has a **style** (how much it stands out) and a **color**, set independently: any style
+works with any colour. The colours are the library-wide `ThemeColor`s or any CSS colour, see
+[ThemeColor.md](ThemeColor.md).
 
 ```tsx
-import { Button, ButtonStyleType, ButtonSize } from '@ahrowe/ui';
-import { faSave } from '@fortawesome/free-solid-svg-icons';
+import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui';
+import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
-// Primary
-<Button styleType={ButtonStyleType.Primary} onClick={handleSave}>Save</Button>
+// The main action
+<Button styleType={ButtonStyleType.Filled} onClick={handleSave}>Save</Button>
 
-// With icon + loading state
+// Secondary: Outlined is the default style, Primary the default colour
+<Button onClick={handleCancel}>Cancel</Button>
+<Button color={ThemeColor.Neutral} onClick={handleCancel}>Cancel</Button>
+
+// Destructive
+<Button styleType={ButtonStyleType.Filled} color={ThemeColor.Error} onClick={handleDelete}>Delete</Button>
+
+// A trash icon in a table row
 <Button
-  styleType={ButtonStyleType.Primary}
-  icon={faSave}
-  isLoading={isSaving}
-  onClick={handleSave}
->
+  styleType={ButtonStyleType.Plain}
+  color={ThemeColor.Error}
+  size={ButtonSize.Icon}
+  icon={faTrash}
+  aria-label="Delete row"
+  style={{ width: 32, height: 32 }}
+/>
+
+// A close button: Neutral takes the text colour of whatever it sits on
+<Button
+  styleType={ButtonStyleType.Plain}
+  color={ThemeColor.Neutral}
+  size={ButtonSize.Icon}
+  icon={faXmark}
+  aria-label="Close"
+  style={{ width: 32, height: 32 }}
+/>
+
+// With icon + loading state
+<Button styleType={ButtonStyleType.Filled} icon={faSave} isLoading={isSaving} onClick={handleSave}>
   Save
 </Button>
 
-// Delete / danger
-<Button styleType={ButtonStyleType.Delete} onClick={handleDelete}>Delete</Button>
-
 // Small
 <Button size={ButtonSize.Small}>Cancel</Button>
 
-// Icon-only — padding-free and square; give it the box size you want
-<Button size={ButtonSize.Icon} icon={faPlus} aria-label="Add" style={{ width: 44, height: 44 }} />
-
 // Press-and-hold: act on press rather than release
 <Button
   icon={faPlus}
@@ -42,12 +62,13 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 />
 
 // Submit button in a form
-<Button type={ButtonType.Submit} styleType={ButtonStyleType.Primary}>Submit</Button>
+<Button type={ButtonType.Submit} styleType={ButtonStyleType.Filled}>Submit</Button>
 ```
 
 **Enums:**
 
-- `ButtonStyleType`: `Primary` | `Default` | `Delete`
+- `ButtonStyleType`: `Filled` | `Light` | `Outlined` (default) | `Plain`
+- `ThemeColor`: `Primary` (default) | `Neutral` | `Success` | `Info` | `Warn` | `Error`
 - `ButtonSize`: `Default` | `Small` | `Medium` | `Large` | `Icon`
 - `ButtonType`: `Button` | `Reset` | `Submit`
 
@@ -55,41 +76,42 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `styleType` | `ButtonStyleType` | Visual variant |
+| `styleType` | `ButtonStyleType` | `Filled`: solid fill, for the one main action. `Light`: a tint of the colour behind text in the colour. `Outlined` (default): border and text in the colour. `Plain`: text in the colour, no fill or border, for toolbar, icon and close buttons |
+| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour. `Neutral` takes the surrounding text colour, with a `--border-color` outline; `Error` is for destructive actions. See [ThemeColor.md](ThemeColor.md) |
 | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
 | `type` | `ButtonType` | HTML button type |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
-| `isLoading` | `boolean` | Replaces content with a spinner |
-| `disabled` | `boolean` | |
+| `isLoading` | `boolean` | Replaces content with a spinner. Blocks clicks like `disabled` but keeps full colour |
+| `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
 
 `ButtonProps` extends `React.ButtonHTMLAttributes<HTMLButtonElement>`, so every native `<button>`
 attribute is accepted and forwarded — pointer handlers (`onPointerDown` and friends, for
 press-and-hold controls that act on press rather than release), `onContextMenu`, `tabIndex`,
 `name`, `value`, `form`, `autoFocus`, and the rest. `type` and `onClick` are narrowed: `type`
-takes the `ButtonType` enum, and `onClick` may return a promise.
+takes the `ButtonType` enum, and `onClick` may return a promise. `color` is Button's own prop, not
+the obsolete HTML attribute.
 
-**Theming (default style):** the `Default` style is transparent text-coloured by default. Override it theme-wide (or per button via `style`) without touching `Primary`/`Delete`:
+**Theming:** each colour reads the theme variables listed in [ThemeColor.md](ThemeColor.md). The
+`Filled` `Primary` button also paints `--primary-gradient` when the theme sets one. See
+[ThemeProvider.md](ThemeProvider.md).
 
-- `--button-default-background` — fill (default transparent)
-- `--button-default-color` — text colour (default `var(--text-color)`)
-- `--button-default-border` — full `border` shorthand, e.g. `1px solid var(--border-color)` (default a transparent `1px` border)
+## Custom colours and presets
 
-Every button reserves a transparent `1px` border, so switching `--button-default-border` on never shifts layout or changes button height. See [ThemeProvider.md](ThemeProvider.md).
+`color` takes any CSS colour as well as a `ThemeColor`; the text on a `Filled` button is picked
+for contrast. Presets are a component in your app, and a section or the whole app takes a default
+through `ConfigProvider`. All three are in [ThemeColor.md](ThemeColor.md).
 
 ```tsx
-// Outlined default buttons across the app
-const theme: Theme = {
-  id: 'brand',
-  variables: { '--button-default-border': '1px solid var(--border-color)' },
-};
-
-// Or one-off via style
-<Button style={{ '--button-default-border': '1px solid var(--border-color)' } as React.CSSProperties}>
-  Cancel
-</Button>
+<Button styleType={ButtonStyleType.Filled} color="var(--brand)">Upgrade</Button>
 ```
 
+**States:** hover and press lay a tint of the button's own text colour over the whole button, so
+every style, colour and theme gets them with no variables of their own. The keyboard focus ring
+sits inside the edge, in `--focus-border-color`, or in the text colour on a `Filled` button. The
+ripple is in the text colour too. Every button reserves a `1px` border, so switching style never
+shifts layout or changes its height.
+
 **Slots:** `background` `content` `loadingContainer` `label`
 
 **Sizing in a flex row:** a Button never shrinks below its own content (`min-width: min-content`),
@@ -100,3 +122,39 @@ so an icon is never cut off by a flexible sibling. A multi-word label still wrap
 A Button is sized by its font. `--default-font-size` is the base, and `Small` and `Large` are multiples of it (0.75x and 1.25x), so a theme with a smaller base font gets proportionally smaller controls everywhere. Padding and the icon gap are in `em`, so the whole box grows with the label rather than a large button wearing a default button's padding.
 
 `ButtonSize.Icon` is the exception: it inherits the surrounding text size and has no padding at all, because the caller sets the box.
+
+## Migration from `Primary`, `Default` and `Delete`
+
+Before 0.43, `styleType` set emphasis and colour in one value. `Primary`, `Default` and `Delete` no
+longer exist, so TypeScript points at every place that names them:
+
+| Before | After |
+|--------|-------|
+| `styleType={ButtonStyleType.Primary}` | `styleType={ButtonStyleType.Filled}` |
+| `styleType={ButtonStyleType.Default}` | nothing: `Outlined` is the default |
+| `styleType={ButtonStyleType.Delete}` | `styleType={ButtonStyleType.Filled} color={ThemeColor.Error}` |
+| ActionButtons `submitButtonStyle={ButtonStyleType.Delete}` | `submitButtonColor={ThemeColor.Error}` |
+| SplitButton `styleType={ButtonStyleType.Delete}` | `color={ThemeColor.Error}` (`Filled` is its default) |
+| Card action `styleType: ButtonStyleType.Delete` | `styleType: ButtonStyleType.Filled, color: ThemeColor.Error` |
+| `defaultProps={{ Button: { styleType: ButtonStyleType.Primary } }}` | `defaultProps={{ Button: { styleType: ButtonStyleType.Filled } }}` |
+
+Two things compile unchanged and need a look of their own:
+
+**A Button with no `styleType`.** It was transparent text in `--text-color` unless the theme set
+`--button-default-*`; the built-in `defaultTheme` made it an outline in `--primary-color`, which
+is now the default everywhere. To keep the old look where you want it, use
+`styleType={ButtonStyleType.Plain} color={ThemeColor.Neutral}`.
+
+**`--button-default-background`, `--button-default-color` and `--button-default-border` in a
+theme.** They are gone, and since a theme accepts any variable they still compile and do nothing.
+What they styled is now the default `color`, set once on `AhroweProvider`:
+
+| Theme set | Instead |
+|-----------|---------|
+| `--button-default-color: var(--text-color)` and a `--border-color` border | `defaultProps={{ Button: { color: ThemeColor.Neutral } }}` |
+| another colour | `defaultProps={{ Button: { color: 'var(--your-colour)' } }}` |
+| a fill in `--button-default-background` | also `styleType: ButtonStyleType.Filled`; `ThemeColor.Neutral` fills with a mix of the text colour |
+
+A default prop does not change with the theme. Where each theme had its own default button, give
+each theme a variable of your own, `'--app-button': '…'`, and set
+`defaultProps={{ Button: { color: 'var(--app-button)' } }}` once: the variable follows the theme.

package/docs/ButtonGroup.md

@@ -13,23 +13,23 @@ import { ButtonGroup, ButtonGroupOrientation, Button, ButtonStyleType } from '@a
 
 // Segmented toggle
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Default}>Day</Button>
-  <Button styleType={ButtonStyleType.Default}>Week</Button>
-  <Button styleType={ButtonStyleType.Default}>Month</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Day</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Week</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Month</Button>
 </ButtonGroup>
 
 // Icon toolbar
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
-  <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
-  <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faBold} aria-label="Bold" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faItalic} aria-label="Italic" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faUnderline} aria-label="Underline" />
 </ButtonGroup>
 
 // Vertical
 <ButtonGroup orientation={ButtonGroupOrientation.Vertical}>
-  <Button styleType={ButtonStyleType.Default}>Bold</Button>
-  <Button styleType={ButtonStyleType.Default}>Italic</Button>
-  <Button styleType={ButtonStyleType.Default}>Underline</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Bold</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Italic</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Underline</Button>
 </ButtonGroup>
 
 // With a separator — filled styles (Primary/Delete) have no border of their own to merge,
@@ -37,23 +37,23 @@ import { ButtonGroup, ButtonGroupOrientation, Button, ButtonStyleType } from '@a
 import { Divider, DividerOrientation } from '@ahrowe/ui';
 
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Primary}>Save</Button>
+  <Button styleType={ButtonStyleType.Filled}>Save</Button>
   <Divider orientation={DividerOrientation.Vertical} />
-  <Button styleType={ButtonStyleType.Primary}>Save & new</Button>
+  <Button styleType={ButtonStyleType.Filled}>Save & new</Button>
 </ButtonGroup>
 
 // Nested groups — a toolbar made of two self-contained sub-groups, spaced apart rather
 // than merged into one continuous strip
 <ButtonGroup>
   <ButtonGroup>
-    <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
-    <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
-    <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faBold} aria-label="Bold" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faItalic} aria-label="Italic" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faUnderline} aria-label="Underline" />
   </ButtonGroup>
   <ButtonGroup>
-    <Button styleType={ButtonStyleType.Default} icon={faAlignLeft} aria-label="Align left" />
-    <Button styleType={ButtonStyleType.Default} icon={faAlignCenter} aria-label="Align center" />
-    <Button styleType={ButtonStyleType.Default} icon={faAlignRight} aria-label="Align right" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignLeft} aria-label="Align left" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignCenter} aria-label="Align center" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignRight} aria-label="Align right" />
   </ButtonGroup>
 </ButtonGroup>
 
@@ -64,7 +64,7 @@ import { Input } from '@ahrowe/ui';
 
 <ButtonGroup>
   <Input placeholder="Search…" value={search} onChange={setSearch} />
-  <Button styleType={ButtonStyleType.Primary} icon={faMagnifyingGlass} aria-label="Search" />
+  <Button styleType={ButtonStyleType.Filled} icon={faMagnifyingGlass} aria-label="Search" />
 </ButtonGroup>
 ```
 

package/docs/CLAUDE.md

@@ -32,8 +32,13 @@ enums and slot names. Do not infer props from a component's name.
 - **Text a component renders itself** (close buttons, empty messages, page labels) is set with its
   `labels` prop. App-wide defaults for any prop go through `AhroweProvider`'s `defaultProps`
   (ConfigProvider.md).
-- **Variants are enums**, not strings: `ButtonStyleType.Primary`, `ButtonSize.Small`. Each doc lists
+- **Variants are enums**, not strings: `ButtonStyleType.Filled`, `ButtonSize.Small`. Each doc lists
   them under **Enums**.
+- **Colours are one vocabulary.** Every `color` prop takes a `ThemeColor` (`Primary`, `Neutral`,
+  `Success`, `Info`, `Warn`, `Error`) or any CSS colour, and a separate `styleType` sets how much
+  the component stands out, so any style works in any colour (ThemeColor.md). Pick the style by
+  emphasis, the same way everywhere: `Filled` for the one main action of a region (at most one),
+  `Light` for status and selection, `Outlined` for secondary actions, `Plain` for tertiary ones.
 - **`icon` props** take a FontAwesome `IconDefinition` or any React element.
 - **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
   Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`. Timer, Flip, Tilt,
@@ -44,6 +49,10 @@ enums and slot names. Do not infer props from a component's name.
   or validates a plan. No right-to-left support.
   `prefers-reduced-motion` is honoured. Built for Chrome and Edge 111, Firefox 114, Safari 16.4
   and newer, with no polyfills. The package is 0.x: a minor can break, a patch cannot.
+- **Upgrading.** Every breaking change has a `## Migration from …` section, an old-to-new table,
+  in the doc of the component it changed. When TypeScript reports a name as missing after an
+  update, search the docs for that name. `CHANGELOG.md` beside `docs/` lists every change by
+  version and names the section to read.
 
 ## Components
 
@@ -51,24 +60,24 @@ enums and slot names. Do not infer props from a component's name.
 
 | Doc | Exports | When to use |
 |-----|---------|-------------|
-| Accordion.md | Accordion | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
+| Accordion.md | Accordion, AccordionStyleType, ThemeColor | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
 | ActionButtons.md | ActionButtons | Standardised Submit / Cancel button pair for forms, dialogs, and drawer footers |
-| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, icon-only controls |
+| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, close buttons, icon-only controls |
 | AhroweProvider.md | AhroweProvider | The one wrapper an app needs, at its root: it applies the theme, sets default props for every component, shows toasts and renders the element that Modal, Tooltip, Popover, Menu and Toast portal into |
-| Alert.md | Alert, AlertStyleType | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
+| Alert.md | Alert, ThemeColor | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
 | AnimatedLogo.md | AnimatedLogo | A self-drawing SVG mark for splash/loading screens, empty states, or anywhere a brand or icon mark should feel alive rather than static |
 | AnimatedText.md | AnimatedText, AnimatedTextVariant, AnimatedTextUnit | Decorative text entrance or emphasis effect, for hero headlines, empty-state messages, "premium"/"new" callouts, loading/decoding states |
 | Avatar.md | Avatar, AvatarGroup | User or entity image — profile pictures, comment authors, member lists |
-| Badge.md | Badge, BadgeStyleType, BadgePosition | Small count or status indicator — unread counts, notification dots, "new" markers |
+| Badge.md | Badge, BadgeStyleType, BadgePosition, ThemeColor | Small count or status indicator — unread counts, notification dots, "new" markers |
 | BodyEnd.md | BodyEnd | Renders children through a React portal, to the end of the app |
 | Breadcrumb.md | Breadcrumb | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
-| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType | Primary interactive action trigger |
+| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor | Primary interactive action trigger |
 | ButtonGroup.md | ButtonGroup, ButtonGroupOrientation | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
-| Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments, a team schedule |
-| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
+| Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments |
+| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions, ThemeColor | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
 | Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
 | Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
-| Chip.md | Chip, ChipContainer, ChipStyleType | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
+| Chip.md | Chip, ChipContainer, ChipStyleType, ThemeColor | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
 | ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |
 | CommandPalette.md | CommandPalette | A search-first dialog for running any command or jumping anywhere in the app from the keyboard, usually opened with ⌘K / Ctrl+K |
 | ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
@@ -123,12 +132,13 @@ enums and slot names. Do not infer props from a component's name.
 | Switch.md | Switch | Sliding boolean toggle — settings panels, feature flags, preference lists |
 | TabHeader.md | TabHeader | A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages |
 | Textarea.md | Textarea | Multiline text input — comments, descriptions, notes, code snippets, long-form content |
+| ThemeColor.md | ThemeColor | The `color` prop of every component that takes one: the theme's named colours, or any CSS colour of your own |
 | ThemeProvider.md | ThemeProvider | Applies a theme to its subtree, injecting its CSS custom properties as inline styles so every component inside can use them |
 | Tilt.md | Tilt, TiltGroup | Wrap content that should tilt toward the cursor in 3D |
 | TimeInput.md | TimeInput | Time-of-day selection — appointment times, opening hours, shift starts, reminders |
-| Timeline.md | Timeline, TimelineAlignment, TimelineItemStatus | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
+| Timeline.md | Timeline, TimelineAlignment, ThemeColor | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
 | Timer.md | Timer | A countdown timer with a depleting ring, add/remove-time and pause/cancel controls, and an imperative ref API |
-| Toast.md | showToast | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
+| Toast.md | showToast, ThemeColor | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
 | Tooltip.md | Tooltip | Contextual help, info icons, field explanations, error pointers |
 | Tree.md | Tree, flattenTree | A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts |
 | VirtualList.md | VirtualList | Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM |

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.