@ahrowe/ui 0.43.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +3 -2
  3. package/dist/cjs-types/common/configProvider/configProvider.types.d.ts +4 -0
  4. package/dist/cjs-types/common/loader/index.d.ts +2 -0
  5. package/dist/cjs-types/common/loader/loader.d.ts +4 -0
  6. package/dist/cjs-types/common/loader/loader.types.d.ts +31 -0
  7. package/dist/cjs-types/common/loadingOverlay/index.d.ts +2 -0
  8. package/dist/cjs-types/common/loadingOverlay/loadingOverlay.d.ts +4 -0
  9. package/dist/cjs-types/common/loadingOverlay/loadingOverlay.types.d.ts +21 -0
  10. package/dist/cjs-types/common/themeProvider/theme.types.d.ts +4 -0
  11. package/dist/cjs-types/index.d.ts +4 -1
  12. package/dist/esm/common/button/button.mjs +1 -1
  13. package/dist/esm/common/button/button.mjs.map +1 -1
  14. package/dist/esm/common/button/button.module.mjs +1 -1
  15. package/dist/esm/common/button/button.module.mjs.map +1 -1
  16. package/dist/esm/common/checkbox/checkbox.mjs +1 -1
  17. package/dist/esm/common/checkbox/checkbox.mjs.map +1 -1
  18. package/dist/esm/common/checkbox/checkbox.module.mjs +1 -1
  19. package/dist/esm/common/checkbox/checkbox.module.mjs.map +1 -1
  20. package/dist/esm/common/dropdown/dropdown.mjs +1 -1
  21. package/dist/esm/common/dropdown/dropdown.mjs.map +1 -1
  22. package/dist/esm/common/dropdown/dropdown.module.mjs +1 -1
  23. package/dist/esm/common/dropdown/dropdown.module.mjs.map +1 -1
  24. package/dist/esm/common/kanbanBoard/KanbanColumn.mjs +1 -1
  25. package/dist/esm/common/kanbanBoard/KanbanColumn.mjs.map +1 -1
  26. package/dist/esm/common/kanbanBoard/kanbanBoard.module.mjs +1 -1
  27. package/dist/esm/common/kanbanBoard/kanbanBoard.module.mjs.map +1 -1
  28. package/dist/esm/common/loader/loader.mjs +2 -0
  29. package/dist/esm/common/loader/loader.mjs.map +1 -0
  30. package/dist/esm/common/loader/loader.module.mjs +2 -0
  31. package/dist/esm/common/loader/loader.module.mjs.map +1 -0
  32. package/dist/esm/common/loader/loader.types.mjs +2 -0
  33. package/dist/esm/common/loader/loader.types.mjs.map +1 -0
  34. package/dist/esm/common/loadingOverlay/loadingOverlay.mjs +2 -0
  35. package/dist/esm/common/loadingOverlay/loadingOverlay.mjs.map +1 -0
  36. package/dist/esm/common/loadingOverlay/loadingOverlay.module.mjs +2 -0
  37. package/dist/esm/common/loadingOverlay/loadingOverlay.module.mjs.map +1 -0
  38. package/dist/esm/common/virtualList/virtualList.mjs +1 -1
  39. package/dist/esm/common/virtualList/virtualList.mjs.map +1 -1
  40. package/dist/esm/common/virtualList/virtualList.module.mjs +1 -1
  41. package/dist/esm/common/virtualList/virtualList.module.mjs.map +1 -1
  42. package/dist/esm/index.mjs +1 -1
  43. package/dist/index.cjs +3 -3
  44. package/dist/index.cjs.map +1 -1
  45. package/dist/style.css +1 -1
  46. package/dist/types/common/configProvider/configProvider.types.d.ts +4 -0
  47. package/dist/types/common/loader/index.d.ts +2 -0
  48. package/dist/types/common/loader/loader.d.ts +4 -0
  49. package/dist/types/common/loader/loader.types.d.ts +31 -0
  50. package/dist/types/common/loadingOverlay/index.d.ts +2 -0
  51. package/dist/types/common/loadingOverlay/loadingOverlay.d.ts +4 -0
  52. package/dist/types/common/loadingOverlay/loadingOverlay.types.d.ts +21 -0
  53. package/dist/types/common/themeProvider/theme.types.d.ts +4 -0
  54. package/dist/types/index.d.ts +4 -1
  55. package/docs/Button.md +1 -1
  56. package/docs/CLAUDE.md +3 -2
  57. package/docs/Checkbox.md +1 -1
  58. package/docs/ConfigProvider.md +1 -1
  59. package/docs/Loader.md +95 -0
  60. package/docs/LoadingOverlay.md +85 -0
  61. package/docs/Skeleton.md +1 -1
  62. package/docs/ThemeColor.md +1 -1
  63. package/package.json +1 -1
  64. package/dist/cjs-types/common/loading/index.d.ts +0 -1
  65. package/dist/cjs-types/common/loading/spinnerLoading/index.d.ts +0 -2
  66. package/dist/cjs-types/common/loading/spinnerLoading/spinnerLoading.d.ts +0 -6
  67. package/dist/esm/common/loading/spinnerLoading/index.mjs +0 -2
  68. package/dist/esm/common/loading/spinnerLoading/index.mjs.map +0 -1
  69. package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs +0 -2
  70. package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs.map +0 -1
  71. package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs +0 -2
  72. package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs.map +0 -1
  73. package/dist/types/common/loading/index.d.ts +0 -1
  74. package/dist/types/common/loading/spinnerLoading/index.d.ts +0 -2
  75. package/dist/types/common/loading/spinnerLoading/spinnerLoading.d.ts +0 -6
  76. package/docs/Loading.md +0 -68
@@ -26,6 +26,8 @@ import { ChipProps } from '../chip/chip.types.js';
26
26
  import { CardProps } from '../card/card.types.js';
27
27
  import { SectionHeaderProps } from '../sectionHeader/sectionHeader.types.js';
28
28
  import { SkeletonProps } from '../skeleton/skeleton.types.js';
29
+ import { LoaderProps } from '../loader/loader.types.js';
30
+ import { LoadingOverlayProps } from '../loadingOverlay/loadingOverlay.types.js';
29
31
  import { AccordionProps } from '../accordion/accordion.types.js';
30
32
  import { DividerProps } from '../divider/divider.types.js';
31
33
  import { AlertProps } from '../alert/alert.types.js';
@@ -105,6 +107,8 @@ export interface ComponentDefaults {
105
107
  Card?: Partial<CardProps>;
106
108
  SectionHeader?: Partial<SectionHeaderProps>;
107
109
  Skeleton?: Partial<SkeletonProps>;
110
+ Loader?: Partial<LoaderProps>;
111
+ LoadingOverlay?: Partial<LoadingOverlayProps>;
108
112
  Accordion?: Partial<AccordionProps>;
109
113
  Divider?: Partial<DividerProps>;
110
114
  Alert?: Partial<AlertProps>;
@@ -0,0 +1,2 @@
1
+ export { default } from './loader.js';
2
+ export * from './loader.types.js';
@@ -0,0 +1,4 @@
1
+ import { ReactElement } from 'react';
2
+ import { LoaderProps } from './loader.types.js';
3
+ declare function Loader(props: LoaderProps): ReactElement;
4
+ export default Loader;
@@ -0,0 +1,31 @@
1
+ import { CSSProperties } from 'react';
2
+ import { HtmlProps } from '../types/slots.types.js';
3
+ import { ColorValue } from '../themeProvider/color.types.js';
4
+ export declare enum LoaderType {
5
+ /** An arc that grows and shrinks on a faint track. The default, and the one that reads at any size. */
6
+ Spinner = "spinner",
7
+ /** A glowing head trailing a fading tail round a ring. For a hero spot: a page, a panel, an overlay. */
8
+ Comet = "comet",
9
+ /** Three dots in a wave. For a line of text or a chat reply being written. */
10
+ Dots = "dots",
11
+ /** Bars rising and falling like an equaliser. For media, uploads and data being processed. */
12
+ Bars = "bars",
13
+ /** Rings rippling out from a core. For waiting on something outside the app: a device, a connection, a search. */
14
+ Pulse = "pulse"
15
+ }
16
+ export interface LoaderLabels {
17
+ /** The loader's accessible name. */
18
+ loading?: string;
19
+ }
20
+ export interface LoaderProps extends HtmlProps<HTMLSpanElement> {
21
+ /** The animation. Defaults to `LoaderType.Spinner`. */
22
+ type?: LoaderType;
23
+ /** Width and height: any CSS length, or a number of pixels. Defaults to `'2.5em'`, so it follows the font size around it. */
24
+ size?: number | string;
25
+ /** A `ThemeColor` or any CSS colour. Defaults to `ThemeColor.Primary`; `ThemeColor.Neutral` takes the colour of the text around it. */
26
+ color?: ColorValue;
27
+ /** Text the loader produces itself. See `LoaderLabels`. */
28
+ labels?: LoaderLabels;
29
+ className?: string;
30
+ style?: CSSProperties;
31
+ }
@@ -0,0 +1,2 @@
1
+ export { default } from './loadingOverlay.js';
2
+ export * from './loadingOverlay.types.js';
@@ -0,0 +1,4 @@
1
+ import { ReactElement } from 'react';
2
+ import { LoadingOverlayProps } from './loadingOverlay.types.js';
3
+ declare function LoadingOverlay(props: LoadingOverlayProps): ReactElement;
4
+ export default LoadingOverlay;
@@ -0,0 +1,21 @@
1
+ import { CSSProperties, ReactNode } from 'react';
2
+ import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
3
+ export type LoadingOverlaySlots = 'content' | 'backdrop' | 'panel' | 'message';
4
+ export interface LoadingOverlayProps extends HtmlProps<HTMLDivElement> {
5
+ /** Covers the content, blocks the pointer and marks it `aria-busy`. Defaults to `false`. */
6
+ isLoading?: boolean;
7
+ /** What the overlay covers. */
8
+ children?: ReactNode;
9
+ /** Shown in place of the default `Loader`: a `Loader` of another type, an `AnimatedLogo`, anything. */
10
+ loader?: ReactNode;
11
+ /** Text under the loader, with a highlight sweeping across it. Also the default loader's accessible name. */
12
+ message?: ReactNode;
13
+ /** 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`. */
14
+ delay?: number;
15
+ className?: string;
16
+ style?: CSSProperties;
17
+ /** Classes for the inner elements. See `LoadingOverlaySlots`. */
18
+ classNames?: SlotClassNames<LoadingOverlaySlots>;
19
+ /** Inline styles for the inner elements. See `LoadingOverlaySlots`. */
20
+ styles?: SlotStyles<LoadingOverlaySlots>;
21
+ }
@@ -232,6 +232,10 @@ export interface ThemeVariables {
232
232
  /** Width a column collapses to once it has no cards (see `collapseEmptyColumns`). Falls back to 140px. */
233
233
  '--kanban-empty-column-width'?: string;
234
234
  '--option-picker-padding'?: string;
235
+ /** Veil over the content while it loads. Falls back to --background at 50%. */
236
+ '--loading-overlay-background'?: string;
237
+ /** How far the content under the veil is blurred. Falls back to 4px; 0px turns the blur off. */
238
+ '--loading-overlay-blur'?: string;
235
239
  /** Track (unfilled) background colour. Falls back to --background-accent. */
236
240
  '--progress-bar-track-color'?: string;
237
241
  /** Canvas behind the plan. Falls back to --background. */
@@ -76,7 +76,10 @@ export { default as KanbanBoard } from './common/kanbanBoard/index.js';
76
76
  export * from './common/kanbanBoard/index.js';
77
77
  export { default as KlipyPicker } from './common/klipyPicker/index.js';
78
78
  export * from './common/klipyPicker/index.js';
79
- export * from './common/loading/index.js';
79
+ export { default as Loader } from './common/loader/index.js';
80
+ export * from './common/loader/index.js';
81
+ export { default as LoadingOverlay } from './common/loadingOverlay/index.js';
82
+ export * from './common/loadingOverlay/index.js';
80
83
  export { default as Menu } from './common/menu/index.js';
81
84
  export * from './common/menu/index.js';
82
85
  export { default as Modal } from './common/modal/index.js';
package/docs/Button.md CHANGED
@@ -81,7 +81,7 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
81
81
  | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
82
82
  | `type` | `ButtonType` | HTML button type |
83
83
  | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
84
- | `isLoading` | `boolean` | Replaces content with a spinner. Blocks clicks like `disabled` but keeps full colour |
84
+ | `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
85
85
  | `disabled` | `boolean` | Fades the button to half opacity |
86
86
  | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
87
87
 
package/docs/CLAUDE.md CHANGED
@@ -103,7 +103,8 @@ enums and slot names. Do not infer props from a component's name.
103
103
  | InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
104
104
  | KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
105
105
  | KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
106
- | Loading.md | SpinnerLoading | A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes |
106
+ | Loader.md | Loader, LoaderType, ThemeColor | A loading indicator for something in progress with no known end: a fetch, a save, a connection |
107
+ | LoadingOverlay.md | LoadingOverlay, Loader, LoaderType | Covering content while it reloads: a table refreshing, a form saving, a panel fetching its next page |
107
108
  | 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 |
108
109
  | Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
109
110
  | MultiSelect.md | MultiSelect | Pick several options from a list |
@@ -124,7 +125,7 @@ enums and slot names. Do not infer props from a component's name.
124
125
  | ScrollbarProvider.md | ScrollbarProvider | Applies custom scrollbar styling to a scrollable region — use to keep scrollbar appearance consistent with the theme |
125
126
  | SearchInput.md | SearchInput | Search field with built-in debouncing and an optional result count line — list filters, search-as-you-type pages |
126
127
  | 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 |
127
- | 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) |
128
+ | 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) |
128
129
  | 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 |
129
130
  | 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" |
130
131
  | Stepper.md | Stepper | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
package/docs/Checkbox.md CHANGED
@@ -33,7 +33,7 @@ const agreedValidator = new FormValidator(false, [Validators.required()]);
33
33
  | `onToggle` | `(isToggled: boolean, event?) => void` | Change handler |
34
34
  | `formValidator` | `FormValidator` | Connects to form validation |
35
35
  | `disabled` | `boolean` | |
36
- | `isLoading` | `boolean` | Shows skeleton state |
36
+ | `isLoading` | `boolean` | Shows a [Loader](Loader.md) in place of the box and ignores clicks |
37
37
  | `children` | `ReactNode` | Custom label content |
38
38
  | `cursorDefault` | `boolean` | Use default cursor instead of pointer |
39
39
  | `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
@@ -95,7 +95,7 @@ A nested provider inherits it unless it sets its own, the same way `defaultProps
95
95
  Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
96
96
 
97
97
  - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
98
- - **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
98
+ - **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Loader` · `LoadingOverlay` · `Accordion` · `Divider` · `Timer` · `WeatherIcon`
99
99
  - **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
100
100
  - **Editors:** `RoomDrawer`, `RoomViewer`
101
101
  - **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` only (see below)
package/docs/Loader.md ADDED
@@ -0,0 +1,95 @@
1
+ # Loader
2
+
3
+ **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).
4
+
5
+ **Keywords:** busy, waiting, activity indicator, throbber, async, fetching, typing indicator, equalizer, radar, ripple
6
+
7
+ **Import:** `import { Loader, LoaderType, ThemeColor } from '@ahrowe/ui'`
8
+ **Types:** `import type { LoaderProps, LoaderLabels } from '@ahrowe/ui'`
9
+
10
+ **Enums:** `LoaderType.Spinner` (default) | `LoaderType.Comet` | `LoaderType.Dots` | `LoaderType.Bars` | `LoaderType.Pulse`
11
+
12
+ - `Spinner`: an arc that grows and shrinks on a faint track. Reads at any size, down to 16px
13
+ - `Comet`: a glowing head trailing a tapering tail round a ring. For a hero spot: a page, a panel, an overlay
14
+ - `Dots`: three dots in a wave. For a line of text or a reply being written
15
+ - `Bars`: bars rising and falling like an equaliser. For media, uploads and data being processed
16
+ - `Pulse`: rings rippling out from a core. For waiting on something outside the app: a device, a connection, a search
17
+
18
+ ```tsx
19
+ import { Loader, LoaderType, ThemeColor } from '@ahrowe/ui';
20
+
21
+ // Default: a Spinner in --primary-color, 2.5em square
22
+ {isLoading && <Loader />}
23
+
24
+ <Loader type={LoaderType.Comet} size='4em' />
25
+ <Loader type={LoaderType.Pulse} color={ThemeColor.Success} />
26
+ <Loader type={LoaderType.Bars} color='#e879f9' size={24} />
27
+
28
+ // In a line of text: Neutral takes the text's own colour, 1em its size. Dots rest on the
29
+ // baseline like an ellipsis; the round types sit centred on the text like an icon
30
+ <p>Ava is typing <Loader type={LoaderType.Dots} size='1em' color={ThemeColor.Neutral} /></p>
31
+ ```
32
+
33
+ **Sizing:** `size` sets width and height, which are always equal. It is `2.5em` by default, so a
34
+ loader follows the font size of what it sits in; pass any CSS length, or a number of pixels. Size it
35
+ with `size` rather than a `width` in a class: the stylesheet reads `size`, and a class would tie with
36
+ it on specificity.
37
+
38
+ **Colour:** `color` takes a `ThemeColor` (default `Primary`) or any CSS colour, see
39
+ [ThemeColor.md](ThemeColor.md). `ThemeColor.Neutral` takes the colour of the text around it, which
40
+ is what a loader on a coloured surface wants.
41
+
42
+ ## One type for the whole app
43
+
44
+ Every component with a loading state draws it with this `Loader`: `Button` (and so `SplitButton`,
45
+ `ActionButtons` and `ConfirmModal`), `Checkbox`, `VirtualList`, `Dropdown`, `KanbanBoard` and
46
+ `LoadingOverlay`. A default set once reaches all of them:
47
+
48
+ ```tsx
49
+ <AhroweProvider defaultProps={{ Loader: { type: LoaderType.Dots } }}>
50
+ <App />
51
+ </AhroweProvider>
52
+ ```
53
+
54
+ An app-wide `type` and `labels` reach all of them. `color` reaches all but Button's, which keeps
55
+ the button's text colour. `size` reaches only `LoadingOverlay`'s default loader and the ones you
56
+ place yourself; the others size theirs to fit.
57
+
58
+ **Accessibility:** the root is a `role="progressbar"` with no value, which is how an indeterminate
59
+ progress indicator is announced, named "Loading" (`labels.loading`). Pass `aria-labelledby` to name
60
+ it after visible text instead, as `LoadingOverlay` does with its `message`. Inside something whose
61
+ name comes from its content (a custom checkbox) or that may only hold its own items (a list), pass
62
+ `aria-hidden` and mark the container `aria-busy` instead, as `Checkbox` and `VirtualList` do.
63
+
64
+ **Note:** a loader keeps moving under `prefers-reduced-motion`. One that stands still says the app
65
+ has hung, which is the opposite of what it is there to say.
66
+
67
+ **Key props:**
68
+
69
+ | Prop | Type | Description |
70
+ |------|------|-------------|
71
+ | `type` | `LoaderType` | The animation (default `Spinner`) |
72
+ | `size` | `number \| string` | Width and height, any CSS length or a number of pixels (default `'2.5em'`) |
73
+ | `color` | `ColorValue` | A `ThemeColor` or any CSS colour (default `ThemeColor.Primary`) |
74
+ | `labels` | `LoaderLabels` | Text the loader produces itself, see below |
75
+ | `className` / `style` | | Root `span` |
76
+
77
+ **Labels:** `loading`, the accessible name. Pass `labels` to override it, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `LoaderLabels`.
78
+
79
+ ## Migration from `SpinnerLoading`
80
+
81
+ `SpinnerLoading` was removed in favour of `Loader`, whose default type is the same kind of spinner.
82
+
83
+ ```tsx
84
+ // Before
85
+ <SpinnerLoading className="my-spinner" /> // .my-spinner { width: 24px; height: 24px }
86
+
87
+ // After
88
+ <Loader size={24} />
89
+ ```
90
+
91
+ It used to be 70px by default and is `2.5em` now (40px at a 16px base), and it is a `span` rather
92
+ than an `svg`. It is announced as a progressbar named "Loading", where `SpinnerLoading` was not
93
+ announced at all.
94
+
95
+ **Slots:** none. The root `span` takes `className` and `style`.
@@ -0,0 +1,85 @@
1
+ # LoadingOverlay
2
+
3
+ **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).
4
+
5
+ **Keywords:** spinner, frosted glass, scrim, dim, disable interaction, pending, mask
6
+
7
+ **Import:** `import { LoadingOverlay, Loader, LoaderType } from '@ahrowe/ui'`
8
+ **Types:** `import type { LoadingOverlayProps } from '@ahrowe/ui'`
9
+
10
+ ```tsx
11
+ import { LoadingOverlay, Loader, LoaderType, AnimatedLogo, ThemeColor } from '@ahrowe/ui';
12
+
13
+ // Wrap what is loading. It needs no positioned parent: it is one
14
+ <LoadingOverlay isLoading={isFetching}>
15
+ <InvoiceTable rows={rows} />
16
+ </LoadingOverlay>
17
+
18
+ // A message under the loader, with a highlight sweeping across it
19
+ <LoadingOverlay isLoading={isSaving} message="Saving changes…">
20
+ <ProfileForm />
21
+ </LoadingOverlay>
22
+
23
+ // Any loader in place of the default one
24
+ <LoadingOverlay
25
+ isLoading={isConnecting}
26
+ message="Connecting to the printer…"
27
+ loader={<Loader type={LoaderType.Pulse} color={ThemeColor.Success} size="3.5em" />}
28
+ >
29
+ <PrinterPanel />
30
+ </LoadingOverlay>
31
+
32
+ // A branded one
33
+ <LoadingOverlay isLoading={isBooting} loader={<AnimatedLogo size="4em" />}>
34
+ <Dashboard />
35
+ </LoadingOverlay>
36
+ ```
37
+
38
+ ## Timing
39
+
40
+ The overlay waits `delay` (200ms) after `isLoading` turns true before it shows, so a load that
41
+ finishes faster never flashes it. Once shown it stays at least 400ms, so one that finishes just
42
+ after it appeared does not flash it either, then fades out. Loading again while it fades brings it
43
+ straight back. `delay={0}` shows it at once, from the first render on.
44
+
45
+ The content is marked `aria-busy` the moment `isLoading` is true, delay or not.
46
+
47
+ ## What it blocks
48
+
49
+ The backdrop takes every pointer event over the content and shows a `progress` cursor. It does not
50
+ take the focus or block the keyboard: making the content `inert` would drop the focus of whoever
51
+ pressed the button that started the load. An action that must not run twice should still check its
52
+ own loading state.
53
+
54
+ **Wrapping:** the root is a `div` with `position: relative`, and the content sits in a `div` of its
55
+ own, so anything inside with a `z-index` (a sticky header) stays under the backdrop. The backdrop
56
+ takes the root's `border-radius`, so a `className` that rounds the root rounds the overlay too.
57
+ Content taller than the screen keeps the loader in view rather than at its middle.
58
+
59
+ **Scrolling content:** give the scrolling to `classNames.content` (its `overflow` and its height
60
+ limit), not to the root. The backdrop covers the root's box, so in a root that scrolls it would
61
+ scroll away with the content and leave the rest uncovered.
62
+
63
+ **Theme variables:** `--loading-overlay-background` (the veil, default `--background` at 50%) and
64
+ `--loading-overlay-blur` (default `4px`, `0px` turns the blur off). See
65
+ [ThemeProvider.md](ThemeProvider.md).
66
+
67
+ **App-wide:** `LoadingOverlay` takes `defaultProps` like any other component, so one
68
+ `AhroweProvider` can give every overlay the same `loader` or `delay`. Its default loader is a
69
+ `Loader`, which follows `defaultProps.Loader` as well.
70
+
71
+ **Key props:**
72
+
73
+ | Prop | Type | Description |
74
+ |------|------|-------------|
75
+ | `isLoading` | `boolean` | Covers the content, blocks the pointer and marks it `aria-busy` (default `false`) |
76
+ | `children` | `ReactNode` | What the overlay covers |
77
+ | `message` | `ReactNode` | Text under the loader. Also the default loader's accessible name |
78
+ | `loader` | `ReactNode` | Shown in place of the default `<Loader />` |
79
+ | `delay` | `number` | Milliseconds before it shows (default `200`) |
80
+ | `className` / `style` | | Root `div` |
81
+
82
+ **Note:** under `prefers-reduced-motion` the panel fades in without rising and the message stands
83
+ still. The loader itself keeps moving, see [Loader.md](Loader.md).
84
+
85
+ **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 CHANGED
@@ -1,6 +1,6 @@
1
1
  # Skeleton
2
2
 
3
- **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.
3
+ **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.
4
4
 
5
5
  **Keywords:** shimmer placeholder, content placeholder
6
6
 
@@ -38,7 +38,7 @@ showToast('Saved', { color: ThemeColor.Success });
38
38
 
39
39
  **Where it applies:** Button, ActionIcon, CopyButton, SplitButton, ActionButtons (`submitButtonColor`,
40
40
  `cancelButtonColor`), Card and its actions, Badge, Chip, Accordion, Alert, Toast, Timeline items, Calendar
41
- events, ProgressBar segments and AnimatedLogo.
41
+ events, ProgressBar segments, Loader and AnimatedLogo.
42
42
 
43
43
  **Styles share their names:** where two components offer the same look, it has the same name in
44
44
  each one's own `styleType` enum. Each component offers only the ones it can draw.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ahrowe/ui",
3
- "version": "0.43.0",
3
+ "version": "0.44.0",
4
4
  "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
5
5
  "keywords": [
6
6
  "agent",
@@ -1 +0,0 @@
1
- export { default as SpinnerLoading } from './spinnerLoading/index.js';
@@ -1,2 +0,0 @@
1
- import { default as SpinnerLoading } from './spinnerLoading.js';
2
- export default SpinnerLoading;
@@ -1,6 +0,0 @@
1
- import { ReactElement } from 'react';
2
- interface Properties {
3
- className?: string | undefined;
4
- }
5
- declare function SpinnerLoading({ className }: Properties): ReactElement;
6
- export default SpinnerLoading;
@@ -1,2 +0,0 @@
1
- "use client";import e from"./spinnerLoading.mjs";var t=e;export{t as default};
2
- //# sourceMappingURL=index.mjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/index.ts"],"sourcesContent":["import SpinnerLoading from './spinnerLoading';\n\nexport default SpinnerLoading;\n"],"mappings":"iDAEA,IAAA,EAAe"}
@@ -1,2 +0,0 @@
1
- "use client";import e from"./spinnerLoading.module.mjs";import t from"classnames";import{jsx as n}from"react/jsx-runtime";function r({className:r}){return n(`svg`,{"data-testid":`spinner`,className:t(e.spinnerLoading,r),xmlns:`http://www.w3.org/2000/svg`,viewBox:`0 0 100 100`,fill:`none`,stroke:`var(--primary-color)`,children:n(`circle`,{cx:`50`,cy:`50`,r:`45`,strokeWidth:`10`})})}export{r as default};
2
- //# sourceMappingURL=spinnerLoading.mjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"spinnerLoading.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/spinnerLoading.tsx"],"sourcesContent":["import type { ReactElement } from 'react';\nimport cx from 'classnames';\n\nimport styles from './spinnerLoading.module.pcss';\n\ninterface Properties {\n className?: string | undefined;\n}\n\nfunction SpinnerLoading({ className }: Properties): ReactElement {\n return (\n <svg\n data-testid='spinner'\n className={cx(styles.spinnerLoading, className)}\n xmlns='http://www.w3.org/2000/svg'\n viewBox='0 0 100 100'\n fill='none'\n stroke='var(--primary-color)'\n >\n <circle cx='50' cy='50' r='45' strokeWidth='10' />\n </svg>\n );\n}\n\nexport default SpinnerLoading;\n"],"mappings":"0HASA,SAAS,EAAe,CAAE,aAAuC,CAC/D,OACE,EAAC,MAAD,CACE,cAAY,UACZ,UAAW,EAAG,EAAO,eAAgB,CAAS,EAC9C,MAAM,6BACN,QAAQ,cACR,KAAK,OACL,OAAO,uBAEP,SAAA,EAAC,SAAD,CAAQ,GAAG,KAAK,GAAG,KAAK,EAAE,KAAK,YAAY,IAAM,CAAA,CAC9C,CAAA,CAET"}
@@ -1,2 +0,0 @@
1
- "use client";var e=`spinner-loading_qbxX-`,t=`animate-spinner_6HoVF`,n=`spin_axdh6`,r={"spinner-loading":`spinner-loading_qbxX-`,spinnerLoading:e,"animate-spinner":`animate-spinner_6HoVF`,animateSpinner:t,spin:n};export{t as animateSpinner,r as default,n as spin,e as spinnerLoading};
2
- //# sourceMappingURL=spinnerLoading.module.mjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"spinnerLoading.module.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/spinnerLoading.module.pcss"],"sourcesContent":[".spinner-loading {\n width: 70px;\n height: 70px;\n\n circle {\n stroke-dasharray: 283;\n stroke-dashoffset: 281;\n stroke-linecap: round;\n animation:\n animate-spinner 2s cubic-bezier(0.89, 0.01, 0.12, 1) infinite,\n spin 3s linear infinite;\n transform-origin: center;\n }\n\n @keyframes animate-spinner {\n 0% {\n stroke-dashoffset: 281;\n }\n\n 50% {\n stroke-dashoffset: 0;\n }\n\n 100% {\n stroke-dashoffset: -281;\n }\n }\n\n @keyframes spin {\n 0% {\n transform: rotate(0deg);\n }\n\n 100% {\n transform: rotate(360deg);\n }\n }\n}\n"],"mappings":""}
@@ -1 +0,0 @@
1
- export { default as SpinnerLoading } from './spinnerLoading/index.js';
@@ -1,2 +0,0 @@
1
- import { default as SpinnerLoading } from './spinnerLoading.js';
2
- export default SpinnerLoading;
@@ -1,6 +0,0 @@
1
- import { ReactElement } from 'react';
2
- interface Properties {
3
- className?: string | undefined;
4
- }
5
- declare function SpinnerLoading({ className }: Properties): ReactElement;
6
- export default SpinnerLoading;
package/docs/Loading.md DELETED
@@ -1,68 +0,0 @@
1
- # Loading (SpinnerLoading)
2
-
3
- **When to use:** A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes. For a button use `Button`'s built-in `isLoading`, and for placeholder content that mirrors the shape of what is coming use [Skeleton.md](Skeleton.md).
4
-
5
- **Keywords:** busy, waiting, activity indicator, throbber, progress, async, fetching, overlay
6
-
7
- **Import:** `import { SpinnerLoading } from '@ahrowe/ui'`
8
-
9
- ```tsx
10
- import { SpinnerLoading } from '@ahrowe/ui';
11
-
12
- // Default: a 70x70 circular spinner stroked in var(--primary-color)
13
- {isLoading && <SpinnerLoading />}
14
-
15
- // Sized through className
16
- <SpinnerLoading className="my-spinner" />
17
- ```
18
-
19
- ```css
20
- .my-spinner {
21
- width: 24px;
22
- height: 24px;
23
- }
24
- ```
25
-
26
- **Key props:**
27
-
28
- | Prop | Type | Description |
29
- |------|------|-------------|
30
- | `className` | `string` | Root `svg` element. This is also how you size it |
31
-
32
- ## Covering a region while it loads
33
-
34
- `SpinnerLoading` is the indicator only. To overlay it on content, centre it in a positioned parent:
35
-
36
- ```tsx
37
- <div className="panel">
38
- <YourContent />
39
- {isLoading && (
40
- <div className="panel-overlay">
41
- <SpinnerLoading className="my-spinner" />
42
- </div>
43
- )}
44
- </div>
45
- ```
46
-
47
- ```css
48
- .panel {
49
- position: relative;
50
- }
51
-
52
- .panel-overlay {
53
- position: absolute;
54
- inset: 0;
55
- display: flex;
56
- align-items: center;
57
- justify-content: center;
58
- pointer-events: none;
59
- }
60
- ```
61
-
62
- Drop the `pointer-events: none` if the overlay should also block interaction with what is underneath, and add a translucent `background` if it should dim it.
63
-
64
- For a branded loading screen rather than a generic spinner, [AnimatedLogo.md](AnimatedLogo.md) draws an SVG mark and sits in the same overlay.
65
-
66
- **Note:** the spinner animates continuously even under `prefers-reduced-motion`. A frozen spinner would say the app has hung, which is the opposite of what it is there to communicate.
67
-
68
- **Slots:** none. The root `svg` takes `className`.