@ahrowe/ui 0.43.0 → 0.45.0

package/dist/types/common/button/button.types.d.ts

@@ -14,8 +14,8 @@ export declare enum ButtonStyleType {
     Plain = "plain"
 }
 export declare enum ButtonSize {
-    Default = "default",
     Small = "small",
+    /** The default. */
     Medium = "medium",
     Large = "large",
     /** Square, padding-free button for a lone icon. Give it its own width/height. */

package/dist/types/common/configProvider/configProvider.types.d.ts

@@ -26,6 +26,8 @@ import { ChipProps } from '../chip/chip.types.js';
 import { CardProps } from '../card/card.types.js';
 import { SectionHeaderProps } from '../sectionHeader/sectionHeader.types.js';
 import { SkeletonProps } from '../skeleton/skeleton.types.js';
+import { LoaderProps } from '../loader/loader.types.js';
+import { LoadingOverlayProps } from '../loadingOverlay/loadingOverlay.types.js';
 import { AccordionProps } from '../accordion/accordion.types.js';
 import { DividerProps } from '../divider/divider.types.js';
 import { AlertProps } from '../alert/alert.types.js';
@@ -46,6 +48,7 @@ import { RoomDrawerProps } from '../roomDrawer/roomDrawer.types.js';
 import { RoomViewerProps } from '../roomViewer/roomViewer.types.js';
 import { PopoverProps } from '../popover/popover.types.js';
 import { ModalProps } from '../modal/modal.types.js';
+import { StepperProps } from '../stepper/stepper.types.js';
 import { Presentation } from '../configProvider/presentation.types.js';
 /**
  * Global default props keyed by component name.
@@ -105,6 +108,8 @@ export interface ComponentDefaults {
     Card?: Partial<CardProps>;
     SectionHeader?: Partial<SectionHeaderProps>;
     Skeleton?: Partial<SkeletonProps>;
+    Loader?: Partial<LoaderProps>;
+    LoadingOverlay?: Partial<LoadingOverlayProps>;
     Accordion?: Partial<AccordionProps>;
     Divider?: Partial<DividerProps>;
     Alert?: Partial<AlertProps>;
@@ -127,6 +132,7 @@ export interface ComponentDefaults {
     Modal?: Partial<ModalProps>;
     CommandPalette?: Partial<CommandPaletteProps>;
     WeatherIcon?: Partial<WeatherIconProps>;
+    Stepper?: Partial<StepperProps>;
 }
 export interface ConfigProviderProps {
     children: React.ReactNode;

package/dist/types/common/loader/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './loader.js';
+export * from './loader.types.js';

package/dist/types/common/loader/loader.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { LoaderProps } from './loader.types.js';
+declare function Loader(props: LoaderProps): ReactElement;
+export default Loader;

package/dist/types/common/loader/loader.types.d.ts

@@ -0,0 +1,31 @@
+import { CSSProperties } from 'react';
+import { HtmlProps } from '../types/slots.types.js';
+import { ColorValue } from '../themeProvider/color.types.js';
+export declare enum LoaderType {
+    /** An arc that grows and shrinks on a faint track. The default, and the one that reads at any size. */
+    Spinner = "spinner",
+    /** A glowing head trailing a fading tail round a ring. For a hero spot: a page, a panel, an overlay. */
+    Comet = "comet",
+    /** Three dots in a wave. For a line of text or a chat reply being written. */
+    Dots = "dots",
+    /** Bars rising and falling like an equaliser. For media, uploads and data being processed. */
+    Bars = "bars",
+    /** Rings rippling out from a core. For waiting on something outside the app: a device, a connection, a search. */
+    Pulse = "pulse"
+}
+export interface LoaderLabels {
+    /** The loader's accessible name. */
+    loading?: string;
+}
+export interface LoaderProps extends HtmlProps<HTMLSpanElement> {
+    /** The animation. Defaults to `LoaderType.Spinner`. */
+    type?: LoaderType;
+    /** Width and height: any CSS length, or a number of pixels. Defaults to `'2.5em'`, so it follows the font size around it. */
+    size?: number | string;
+    /** A `ThemeColor` or any CSS colour. Defaults to `ThemeColor.Primary`; `ThemeColor.Neutral` takes the colour of the text around it. */
+    color?: ColorValue;
+    /** Text the loader produces itself. See `LoaderLabels`. */
+    labels?: LoaderLabels;
+    className?: string;
+    style?: CSSProperties;
+}

package/dist/types/common/loadingOverlay/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './loadingOverlay.js';
+export * from './loadingOverlay.types.js';

package/dist/types/common/loadingOverlay/loadingOverlay.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { LoadingOverlayProps } from './loadingOverlay.types.js';
+declare function LoadingOverlay(props: LoadingOverlayProps): ReactElement;
+export default LoadingOverlay;

package/dist/types/common/loadingOverlay/loadingOverlay.types.d.ts

@@ -0,0 +1,21 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type LoadingOverlaySlots = 'content' | 'backdrop' | 'panel' | 'message';
+export interface LoadingOverlayProps extends HtmlProps<HTMLDivElement> {
+    /** Covers the content, blocks the pointer and marks it `aria-busy`. Defaults to `false`. */
+    isLoading?: boolean;
+    /** What the overlay covers. */
+    children?: ReactNode;
+    /** Shown in place of the default `Loader`: a `Loader` of another type, an `AnimatedLogo`, anything. */
+    loader?: ReactNode;
+    /** Text under the loader, with a highlight sweeping across it. Also the default loader's accessible name. */
+    message?: ReactNode;
+    /** Milliseconds `isLoading` has to stay true before the overlay shows, so a fast load never flashes it. Once shown, it stays at least 400ms. Defaults to `200`. */
+    delay?: number;
+    className?: string;
+    style?: CSSProperties;
+    /** Classes for the inner elements. See `LoadingOverlaySlots`. */
+    classNames?: SlotClassNames<LoadingOverlaySlots>;
+    /** Inline styles for the inner elements. See `LoadingOverlaySlots`. */
+    styles?: SlotStyles<LoadingOverlaySlots>;
+}

package/dist/types/common/stepper/stepper.d.ts

@@ -1,3 +1,3 @@
 import { default as React } from 'react';
 import { StepperProps } from './stepper.types.js';
-export default function Stepper({ steps, currentStep, alignment, onStepClicked, nonLinear, hideLabels, styleType, collapse, labelPlacement, className, style, classNames, styles: slotStyles, ...rest }: StepperProps): React.JSX.Element;
+export default function Stepper(props: StepperProps): React.JSX.Element;

package/dist/types/common/stepper/stepper.types.d.ts

@@ -1,16 +1,17 @@
 import { default as React } from 'react';
 import { IconContent } from '../types/icon.types.js';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
-/** Layout direction of the stepper. */
-export declare enum StepperAlignment {
+import { ColorValue } from '../themeProvider/color.types.js';
+/** Direction the steps run in. */
+export declare enum StepperOrientation {
     Horizontal = "horizontal",
     Vertical = "vertical"
 }
-/** Visual preset for the step markers and connectors. */
+/** How the step markers are drawn. */
 export declare enum StepperStyleType {
-    /** Numbered markers, filled solid on completion (the default look). */
-    Default = "default",
-    /** Numbered markers that stay ringed when completed (a coloured check, no solid fill). */
+    /** Numbered markers, filled solid on completion. The default. */
+    Filled = "filled",
+    /** Numbered markers that stay ringed when completed, with a check in the colour. */
     Outlined = "outlined",
     /** Minimal dots without numbers, for a compact onboarding or carousel style. */
     Dots = "dots"
@@ -39,6 +40,16 @@ export declare enum StepperLabelPlacement {
     Right = "right"
 }
 export type StepperSlots = 'root' | 'entry' | 'entryNumber' | 'entryLabel' | 'connector' | 'description' | 'content' | 'optional' | 'icon';
+export interface StepperLabels {
+    /** Hint under the label of a step with `optional: true`. */
+    optional?: string;
+    /** Status of a completed step, read out by screen readers. */
+    completed?: string;
+    /** Status of a step not reached yet, read out by screen readers. */
+    notCompleted?: string;
+    /** Status of a step with `error`, read out by screen readers. */
+    error?: string;
+}
 export interface StepperStep {
     /** Primary label for the step. */
     label: React.ReactNode;
@@ -48,28 +59,33 @@ export interface StepperStep {
     content?: React.ReactNode;
     /** Icon shown in the marker instead of the step number — a FontAwesome icon or any node. */
     icon?: IconContent;
-    /** Marks the step as errored, recolouring the marker with `--stepper-error-color`. */
+    /** Marks the step as errored, drawing its marker in the theme's `--error-color`. */
     error?: boolean;
-    /** `true` renders an "Optional" hint; a node renders custom hint text. */
+    /** `true` renders the `optional` label as a hint; a node renders custom hint text. */
     optional?: boolean | React.ReactNode;
     /** Disables this step: never clickable, dimmed. */
     disabled?: boolean;
 }
-export interface StepperProps extends HtmlProps {
+export interface StepperProps extends HtmlProps<HTMLOListElement> {
     steps?: StepperStep[];
+    /** Zero-based index of the current step. `steps.length` marks every step completed. */
     currentStep?: number;
-    alignment?: StepperAlignment | 'horizontal' | 'vertical';
+    /** Direction the steps run in (default `Horizontal`). */
+    orientation?: StepperOrientation;
     onStepClicked?: ((index: number) => void) | null;
     /** Allow clicking any step, not just completed ones. */
     nonLinear?: boolean;
-    /** Hide the label text (and description) beneath each step entry. */
+    /** Hide each step's label, description and hint visually. Screen readers still read them. */
     hideLabels?: boolean;
-    /** Visual preset for markers and connectors (default `Default`). */
+    /** How the markers are drawn (default `Filled`). */
     styleType?: StepperStyleType;
+    /** A `ThemeColor` (default `Primary`) or any CSS colour, such as `'var(--brand)'`. */
+    color?: ColorValue;
     /** Which step bodies are expanded. Vertical `content` only (default `None`). */
     collapse?: StepperCollapse;
     /** Label position relative to the marker (default: horizontal `Bottom`, vertical `Right`). */
     labelPlacement?: StepperLabelPlacement;
+    labels?: StepperLabels;
     className?: string;
     style?: React.CSSProperties;
     classNames?: SlotClassNames<StepperSlots>;

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

@@ -125,24 +125,12 @@ export interface ThemeVariables {
     '--stepper-marker-size'?: string;
     /** Step marker corner radius. Falls back to --default-border-radius. */
     '--stepper-marker-radius'?: string;
-    /** Idle (upcoming) marker/connector colour. Falls back to --primary-lighter. */
-    '--stepper-idle-color'?: string;
-    /** Current-step marker colour. Falls back to --primary-color. */
-    '--stepper-active-color'?: string;
-    /** Completed-step marker fill/colour. Falls back to --primary-color. */
-    '--stepper-done-color'?: string;
-    /** Errored-step marker colour. Falls back to --error-color. */
-    '--stepper-error-color'?: string;
-    /** Completed connector colour. Falls back to --primary-color. */
-    '--stepper-connector-color'?: string;
     /** Completed connector thickness. Falls back to 3px. */
     '--stepper-connector-thickness'?: string;
     /** Not-yet-reached connector thickness. Falls back to 1px. */
     '--stepper-connector-idle-thickness'?: string;
     /** Gap between marker and label, and grid column gap. Falls back to 12px. */
     '--stepper-gap'?: string;
-    /** Text/check colour on a filled marker. Falls back to --text-on-primary. */
-    '--stepper-text-on-marker'?: string;
     /** Timer ring track (unfilled) colour. Falls back to --background-accent-light. */
     '--timer-track-color'?: string;
     /** Timer ring progress (remaining time) colour. Falls back to --primary-color. */
@@ -232,6 +220,10 @@ export interface ThemeVariables {
     /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
     '--kanban-empty-column-width'?: string;
     '--option-picker-padding'?: string;
+    /** Veil over the content while it loads. Falls back to --background at 50%. */
+    '--loading-overlay-background'?: string;
+    /** How far the content under the veil is blurred. Falls back to 4px; 0px turns the blur off. */
+    '--loading-overlay-blur'?: string;
     /** Track (unfilled) background colour. Falls back to --background-accent. */
     '--progress-bar-track-color'?: string;
     /** Canvas behind the plan. Falls back to --background. */

package/dist/types/index.d.ts

@@ -76,7 +76,10 @@ export { default as KanbanBoard } from './common/kanbanBoard/index.js';
 export * from './common/kanbanBoard/index.js';
 export { default as KlipyPicker } from './common/klipyPicker/index.js';
 export * from './common/klipyPicker/index.js';
-export * from './common/loading/index.js';
+export { default as Loader } from './common/loader/index.js';
+export * from './common/loader/index.js';
+export { default as LoadingOverlay } from './common/loadingOverlay/index.js';
+export * from './common/loadingOverlay/index.js';
 export { default as Menu } from './common/menu/index.js';
 export * from './common/menu/index.js';
 export { default as Modal } from './common/modal/index.js';

package/docs/Button.md

@@ -69,7 +69,7 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 
 - `ButtonStyleType`: `Filled` | `Light` | `Outlined` (default) | `Plain`
 - `ThemeColor`: `Primary` (default) | `Neutral` | `Success` | `Info` | `Warn` | `Error`
-- `ButtonSize`: `Default` | `Small` | `Medium` | `Large` | `Icon`
+- `ButtonSize`: `Small` | `Medium` (default) | `Large` | `Icon`
 - `ButtonType`: `Button` | `Reset` | `Submit`
 
 **Key props:**
@@ -81,7 +81,7 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 | `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. Blocks clicks like `disabled` but keeps full colour |
+| `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
 | `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
 
@@ -119,10 +119,16 @@ so an icon is never cut off by a flexible sibling. A multi-word label still wrap
 
 ## Sizing
 
-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.
+A Button is sized by its font. `--default-font-size` is the base, `Medium` is that size, 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 medium 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 `ButtonSize.Default`
+
+Before 0.45, `ButtonSize.Default` was a second name for `Medium`, which is now the default. Replace
+`size={ButtonSize.Default}` with `size={ButtonSize.Medium}`, or leave the prop out. The look does
+not change.
+
 ## Migration from `Primary`, `Default` and `Delete`
 
 Before 0.43, `styleType` set emphasis and colour in one value. `Primary`, `Default` and `Delete` no

package/docs/CLAUDE.md

@@ -103,7 +103,8 @@ enums and slot names. Do not infer props from a component's name.
 | InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
 | KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
 | KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
-| Loading.md | SpinnerLoading | A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes |
+| Loader.md | Loader, LoaderType, ThemeColor | A loading indicator for something in progress with no known end: a fetch, a save, a connection |
+| LoadingOverlay.md | LoadingOverlay, Loader, LoaderType | Covering content while it reloads: a table refreshing, a form saving, a panel fetching its next page |
 | Menu.md | Menu, menuHotkeys | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
 | Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
 | MultiSelect.md | MultiSelect | Pick several options from a list |
@@ -124,10 +125,10 @@ enums and slot names. Do not infer props from a component's name.
 | ScrollbarProvider.md | ScrollbarProvider | Applies custom scrollbar styling to a scrollable region — use to keep scrollbar appearance consistent with the theme |
 | SearchInput.md | SearchInput | Search field with built-in debouncing and an optional result count line — list filters, search-as-you-type pages |
 | SectionHeader.md | SectionHeader, SectionHeaderSize | A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area |
-| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers) |
+| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a Loader for content-heavy pages (lists, cards, profile headers) |
 | Slider.md | Slider | Let the user pick a number from a continuous or stepped range by dragging a thumb: volume, brightness, price ranges, zoom, quality presets |
 | SplitButton.md | SplitButton | A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close" |
-| Stepper.md | Stepper | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
+| Stepper.md | Stepper, StepperOrientation, StepperStyleType, StepperCollapse, StepperLabelPlacement, ThemeColor | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
 | Sticky.md | Sticky | Pin a piece of content to the top of the viewport once the page scrolls past it — section headers, toolbars, filter bars, table headers |
 | 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 |

package/docs/Checkbox.md

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

package/docs/ConfigProvider.md

@@ -95,7 +95,7 @@ A nested provider inherits it unless it sets its own, the same way `defaultProps
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
-- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
+- **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Loader` · `LoadingOverlay` · `Accordion` · `Divider` · `Timer` · `WeatherIcon` · `Stepper`
 - **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 - **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` only (see below)

package/docs/Loader.md

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

package/docs/LoadingOverlay.md

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

package/docs/Skeleton.md

@@ -1,6 +1,6 @@
 # Skeleton
 
-**When to use:** Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers). Pick the `variant` that matches the shape of what's loading.
+**When to use:** Content-shaped loading placeholder, shown while real content is being fetched — more polished than a [Loader](Loader.md) for content-heavy pages (lists, cards, profile headers). Pick the `variant` that matches the shape of what's loading.
 
 **Keywords:** shimmer placeholder, content placeholder
 

package/docs/SplitButton.md

@@ -70,7 +70,7 @@ import { ButtonStyleType } from '@ahrowe/ui';
 | `actions` | `SplitButtonAction[]` | Secondary actions shown in the dropdown |
 | `styleType` | `ButtonStyleType` | Shared by both the primary and trigger button (default `Filled`) |
 | `color` | `ColorValue` | Shared by both buttons (default `Primary`); or any CSS colour, as on Button |
-| `size` | `ButtonSize` | Size variant, shared by both buttons |
+| `size` | `ButtonSize` | Size variant, shared by both buttons (default `Medium`) |
 | `disabled` | `boolean` | Disables both the primary and trigger button |
 | `isLoading` | `boolean` | Shows a spinner on the primary button (same as `Button`'s own `isLoading`) |
 | `align` | `PopoverAlign` | Which edge of the group the menu lines up with (default `End`, the chevron's side). The menu is a [Menu](Menu.md), hence `Popover`'s enum |