@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.
- package/CHANGELOG.md +12 -0
- package/README.md +3 -2
- package/dist/cjs-types/common/configProvider/configProvider.types.d.ts +4 -0
- package/dist/cjs-types/common/loader/index.d.ts +2 -0
- package/dist/cjs-types/common/loader/loader.d.ts +4 -0
- package/dist/cjs-types/common/loader/loader.types.d.ts +31 -0
- package/dist/cjs-types/common/loadingOverlay/index.d.ts +2 -0
- package/dist/cjs-types/common/loadingOverlay/loadingOverlay.d.ts +4 -0
- package/dist/cjs-types/common/loadingOverlay/loadingOverlay.types.d.ts +21 -0
- package/dist/cjs-types/common/themeProvider/theme.types.d.ts +4 -0
- package/dist/cjs-types/index.d.ts +4 -1
- package/dist/esm/common/button/button.mjs +1 -1
- package/dist/esm/common/button/button.mjs.map +1 -1
- package/dist/esm/common/button/button.module.mjs +1 -1
- package/dist/esm/common/button/button.module.mjs.map +1 -1
- package/dist/esm/common/checkbox/checkbox.mjs +1 -1
- package/dist/esm/common/checkbox/checkbox.mjs.map +1 -1
- package/dist/esm/common/checkbox/checkbox.module.mjs +1 -1
- package/dist/esm/common/checkbox/checkbox.module.mjs.map +1 -1
- package/dist/esm/common/dropdown/dropdown.mjs +1 -1
- package/dist/esm/common/dropdown/dropdown.mjs.map +1 -1
- package/dist/esm/common/dropdown/dropdown.module.mjs +1 -1
- package/dist/esm/common/dropdown/dropdown.module.mjs.map +1 -1
- package/dist/esm/common/kanbanBoard/KanbanColumn.mjs +1 -1
- package/dist/esm/common/kanbanBoard/KanbanColumn.mjs.map +1 -1
- package/dist/esm/common/kanbanBoard/kanbanBoard.module.mjs +1 -1
- package/dist/esm/common/kanbanBoard/kanbanBoard.module.mjs.map +1 -1
- package/dist/esm/common/loader/loader.mjs +2 -0
- package/dist/esm/common/loader/loader.mjs.map +1 -0
- package/dist/esm/common/loader/loader.module.mjs +2 -0
- package/dist/esm/common/loader/loader.module.mjs.map +1 -0
- package/dist/esm/common/loader/loader.types.mjs +2 -0
- package/dist/esm/common/loader/loader.types.mjs.map +1 -0
- package/dist/esm/common/loadingOverlay/loadingOverlay.mjs +2 -0
- package/dist/esm/common/loadingOverlay/loadingOverlay.mjs.map +1 -0
- package/dist/esm/common/loadingOverlay/loadingOverlay.module.mjs +2 -0
- package/dist/esm/common/loadingOverlay/loadingOverlay.module.mjs.map +1 -0
- package/dist/esm/common/virtualList/virtualList.mjs +1 -1
- package/dist/esm/common/virtualList/virtualList.mjs.map +1 -1
- package/dist/esm/common/virtualList/virtualList.module.mjs +1 -1
- package/dist/esm/common/virtualList/virtualList.module.mjs.map +1 -1
- package/dist/esm/index.mjs +1 -1
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/style.css +1 -1
- package/dist/types/common/configProvider/configProvider.types.d.ts +4 -0
- package/dist/types/common/loader/index.d.ts +2 -0
- package/dist/types/common/loader/loader.d.ts +4 -0
- package/dist/types/common/loader/loader.types.d.ts +31 -0
- package/dist/types/common/loadingOverlay/index.d.ts +2 -0
- package/dist/types/common/loadingOverlay/loadingOverlay.d.ts +4 -0
- package/dist/types/common/loadingOverlay/loadingOverlay.types.d.ts +21 -0
- package/dist/types/common/themeProvider/theme.types.d.ts +4 -0
- package/dist/types/index.d.ts +4 -1
- package/docs/Button.md +1 -1
- package/docs/CLAUDE.md +3 -2
- package/docs/Checkbox.md +1 -1
- package/docs/ConfigProvider.md +1 -1
- package/docs/Loader.md +95 -0
- package/docs/LoadingOverlay.md +85 -0
- package/docs/Skeleton.md +1 -1
- package/docs/ThemeColor.md +1 -1
- package/package.json +1 -1
- package/dist/cjs-types/common/loading/index.d.ts +0 -1
- package/dist/cjs-types/common/loading/spinnerLoading/index.d.ts +0 -2
- package/dist/cjs-types/common/loading/spinnerLoading/spinnerLoading.d.ts +0 -6
- package/dist/esm/common/loading/spinnerLoading/index.mjs +0 -2
- package/dist/esm/common/loading/spinnerLoading/index.mjs.map +0 -1
- package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs +0 -2
- package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs.map +0 -1
- package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs +0 -2
- package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs.map +0 -1
- package/dist/types/common/loading/index.d.ts +0 -1
- package/dist/types/common/loading/spinnerLoading/index.d.ts +0 -2
- package/dist/types/common/loading/spinnerLoading/spinnerLoading.d.ts +0 -6
- 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,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,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. */
|
package/dist/types/index.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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 |
|
package/docs/ConfigProvider.md
CHANGED
|
@@ -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
|
|
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
|
|
package/docs/ThemeColor.md
CHANGED
|
@@ -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 +0,0 @@
|
|
|
1
|
-
export { default as SpinnerLoading } from './spinnerLoading/index.js';
|
|
@@ -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';
|
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`.
|