@c9up/nebula 0.2.1 → 0.2.2

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 (40) hide show
  1. package/README.md +11 -9
  2. package/dist/atoms/AccessibleIcon.d.ts +24 -0
  3. package/dist/atoms/AccessibleIcon.js +27 -0
  4. package/dist/atoms/VisuallyHidden.d.ts +30 -0
  5. package/dist/atoms/VisuallyHidden.js +35 -0
  6. package/dist/atoms/index.d.ts +2 -0
  7. package/dist/atoms/index.js +2 -0
  8. package/dist/index.d.ts +7 -4
  9. package/dist/index.js +7 -4
  10. package/dist/molecules/Toolbar.d.ts +50 -0
  11. package/dist/molecules/Toolbar.js +70 -0
  12. package/dist/molecules/index.d.ts +7 -5
  13. package/dist/molecules/index.js +7 -5
  14. package/dist/organisms/Toaster.d.ts +78 -10
  15. package/dist/organisms/Toaster.js +146 -20
  16. package/dist/organisms/index.d.ts +1 -1
  17. package/dist/primitives/direction.d.ts +38 -0
  18. package/dist/primitives/direction.js +57 -0
  19. package/dist/primitives/floating.js +1 -12
  20. package/dist/primitives/focusable.d.ts +10 -0
  21. package/dist/primitives/focusable.js +10 -1
  22. package/dist/primitives/index.d.ts +2 -1
  23. package/dist/primitives/index.js +2 -1
  24. package/dist/primitives/rovingFocus.js +14 -7
  25. package/nebula.css +1 -1
  26. package/package.json +1 -1
  27. package/registry.json +63 -0
  28. package/src/atoms/AccessibleIcon.ts +39 -0
  29. package/src/atoms/VisuallyHidden.ts +45 -0
  30. package/src/atoms/index.ts +8 -0
  31. package/src/index.ts +7 -4
  32. package/src/molecules/Toolbar.ts +100 -0
  33. package/src/molecules/index.ts +14 -5
  34. package/src/organisms/Toaster.ts +207 -33
  35. package/src/organisms/index.ts +2 -0
  36. package/src/primitives/direction.ts +61 -0
  37. package/src/primitives/floating.ts +2 -12
  38. package/src/primitives/focusable.ts +10 -1
  39. package/src/primitives/index.ts +7 -0
  40. package/src/primitives/rovingFocus.ts +18 -5
@@ -0,0 +1,39 @@
1
+ /**
2
+ * AccessibleIcon — an icon with a name only a screen reader hears.
3
+ *
4
+ * An icon on its own is a picture of a word. Sighted users read the picture;
5
+ * a screen reader reads nothing at all, because an `<svg>` with no label is
6
+ * announced as nothing — which is how a delete button becomes an unlabelled
7
+ * button in the middle of a row of unlabelled buttons.
8
+ *
9
+ * Two halves, and both matter. The icon is marked `aria-hidden` so its own
10
+ * internals — a `<title>`, a stray `<text>` — are not announced on top of the
11
+ * label; the label is visually hidden text beside it. `aria-label` on the
12
+ * parent would do for a plain string, but it does not survive translation
13
+ * tooling the way real text does, and it cannot carry markup.
14
+ */
15
+
16
+ import { component, html } from "@c9up/aurora";
17
+ import { type Slot, slot } from "../lib/children.js";
18
+ import { cn } from "../lib/cn.js";
19
+ import { type Reactive, read } from "../lib/props.js";
20
+ import { VisuallyHidden } from "./VisuallyHidden.js";
21
+
22
+ export interface AccessibleIconProps {
23
+ /** The icon. Hidden from the accessibility tree. */
24
+ children?: Slot;
25
+ /** What the icon means, in words. */
26
+ label: Reactive<string>;
27
+ class?: Reactive<string>;
28
+ }
29
+
30
+ export const AccessibleIcon = component<AccessibleIconProps>((props) => {
31
+ return html`<span
32
+ data-slot="accessible-icon"
33
+ class="${() => cn("contents", read(props.class))}"
34
+ ><span aria-hidden="true" class="contents">${slot(props.children)}</span>${VisuallyHidden(
35
+ {
36
+ children: () => read(props.label),
37
+ },
38
+ )}</span>`;
39
+ });
@@ -0,0 +1,45 @@
1
+ /**
2
+ * VisuallyHidden — text for a screen reader and nothing else.
3
+ *
4
+ * Not `display: none`, which removes it from the accessibility tree as well,
5
+ * and not `opacity: 0`, which keeps it taking space. The clip rectangle is the
6
+ * one technique that leaves the node announced and unrendered, and it is
7
+ * fiddly enough that hand-writing it in each component is how one of them ends
8
+ * up subtly wrong.
9
+ *
10
+ * Its main job is the label a sighted user does not need: a dialog whose title
11
+ * is a logo, an icon button, a table caption. `aria-label` covers some of
12
+ * those, but not the ones where the content is real markup — a heading that a
13
+ * `aria-labelledby` has to point at, for instance.
14
+ *
15
+ * `focusable` keeps it hidden until it is tabbed to, which is what a skip link
16
+ * needs: invisible in the layout, and visible the moment it has focus.
17
+ *
18
+ * Always a `<span>`. Radix takes an `asChild` here so a hidden heading can be
19
+ * a real `<h2>`; aurora's template parser fixes the tag at compile time, so
20
+ * the equivalent is to put this inside the heading rather than to become one.
21
+ */
22
+
23
+ import { component, html } from "@c9up/aurora";
24
+ import { type Slot, slot } from "../lib/children.js";
25
+ import { cn } from "../lib/cn.js";
26
+ import { type Reactive, read } from "../lib/props.js";
27
+
28
+ export interface VisuallyHiddenProps {
29
+ children?: Slot;
30
+ /** Reveal it once focused — for a skip link. Default `false`. */
31
+ focusable?: boolean;
32
+ class?: Reactive<string>;
33
+ }
34
+
35
+ /** Tailwind's own `sr-only`, plus its counterpart for the focusable case. */
36
+ const HIDDEN = "sr-only";
37
+ const FOCUSABLE = "sr-only focus-within:not-sr-only focus:not-sr-only";
38
+
39
+ export const VisuallyHidden = component<VisuallyHiddenProps>((props) => {
40
+ const base = props.focusable === true ? FOCUSABLE : HIDDEN;
41
+ return html`<span
42
+ data-slot="visually-hidden"
43
+ class="${() => cn(base, read(props.class))}"
44
+ >${slot(props.children)}</span>`;
45
+ });
@@ -12,6 +12,10 @@
12
12
  * Slider is an atom despite being interactive, because it is one input.
13
13
  */
14
14
 
15
+ export {
16
+ AccessibleIcon,
17
+ type AccessibleIconProps,
18
+ } from "./AccessibleIcon.js";
15
19
  export { AspectRatio, type AspectRatioProps } from "./AspectRatio.js";
16
20
  export {
17
21
  Avatar,
@@ -82,3 +86,7 @@ export {
82
86
  type ToggleVariants,
83
87
  toggleVariants,
84
88
  } from "./Toggle.js";
89
+ export {
90
+ VisuallyHidden,
91
+ type VisuallyHiddenProps,
92
+ } from "./VisuallyHidden.js";
package/src/index.ts CHANGED
@@ -13,10 +13,13 @@
13
13
  * icons are inlined, and the date maths is `Date` and `Intl`.
14
14
  *
15
15
  * **Compound components take data, not children.** shadcn composes through
16
- * React context — `<Tabs><TabsList><TabsTrigger>`. Aurora has no context, and
17
- * the workarounds are worse than the problem, so those components take an
18
- * `items` array and named slots. The rendered markup is unchanged, which means
19
- * shadcn's CSS and its examples still read across.
16
+ * React context — `<Tabs><TabsList><TabsTrigger>`. Aurora has context too, and
17
+ * these components use it; what they do not do is take their parts as children.
18
+ * Context here lives on a stack during a component's SETUP, so a part handed in
19
+ * as a `Slot` thunk is built later, once that frame has popped, and reads
20
+ * nothing. An `items` array and named slots keep every part built while the
21
+ * context is still there. The rendered markup is unchanged, which means shadcn's
22
+ * CSS and its examples still read across.
20
23
  *
21
24
  * **The atomic layer is a property of the component.** An atom renders its own
22
25
  * markup and composes nothing from nebula; a molecule assembles atoms or owns
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Toolbar — a row of controls that behaves as one tab stop.
3
+ *
4
+ * Radix ships this as a primitive and shadcn styles no equivalent, which is
5
+ * why it is easy to miss: a page builds a `<div class="flex gap-2">` full of
6
+ * buttons and it looks right. What it is not is navigable. Eleven buttons in a
7
+ * formatting bar are eleven presses of Tab to get past, and a keyboard user
8
+ * reaching the content below pays for every one of them.
9
+ *
10
+ * The WAI-ARIA toolbar pattern says: one tab stop, arrows move inside it. That
11
+ * is `rovingFocus`, which nebula already owns for menus and tab lists — the
12
+ * only thing a toolbar adds is `role="toolbar"`, the orientation, and a
13
+ * separator that is announced as one.
14
+ *
15
+ * The items are whatever the caller puts in — `Button`, `Toggle`, a `Select`
16
+ * trigger, a plain `<a>` — found by the same tabbable selector the focus trap
17
+ * uses. No marker attribute to remember: a control that a keyboard could
18
+ * reach on its own is a control the arrows reach here, and one that could not
19
+ * was never in the tab order to begin with.
20
+ */
21
+
22
+ import { component, html, onMount, onUnmount, uid } from "@c9up/aurora";
23
+ import { Button, type ButtonProps } from "../atoms/Button.js";
24
+ import { Separator } from "../atoms/Separator.js";
25
+ import { type Slot, slot } from "../lib/children.js";
26
+ import { cn } from "../lib/cn.js";
27
+ import { type Reactive, read } from "../lib/props.js";
28
+ import { FOCUSABLE_SELECTOR } from "../primitives/focusable.js";
29
+ import { type RovingFocus, rovingFocus } from "../primitives/rovingFocus.js";
30
+
31
+ export interface ToolbarProps {
32
+ children?: Slot;
33
+ /** Which arrows move focus. Default `"horizontal"`, as a toolbar reads. */
34
+ orientation?: "horizontal" | "vertical";
35
+ /** Wrap from the last control back to the first. Default `true`. */
36
+ loop?: boolean;
37
+ /** Announced name — a page with two toolbars needs to tell them apart. */
38
+ label?: Reactive<string>;
39
+ class?: Reactive<string>;
40
+ }
41
+
42
+ export const Toolbar = component<ToolbarProps>((props) => {
43
+ const orientation = props.orientation ?? "horizontal";
44
+ const barId = uid("toolbar");
45
+ let group: RovingFocus | undefined;
46
+
47
+ onMount(() => {
48
+ group = rovingFocus({
49
+ container: () => document.getElementById(barId),
50
+ itemSelector: FOCUSABLE_SELECTOR,
51
+ orientation,
52
+ loop: props.loop !== false,
53
+ });
54
+ // The controls exist by now; without this none of them carries
55
+ // `tabindex="0"` and the bar cannot be reached by Tab at all.
56
+ group.sync();
57
+ });
58
+ onUnmount(() => group?.destroy());
59
+
60
+ return html`<div
61
+ data-slot="toolbar"
62
+ id="${barId}"
63
+ role="toolbar"
64
+ aria-orientation="${orientation}"
65
+ aria-label="${() => read(props.label) ?? ""}"
66
+ class="${() =>
67
+ cn(
68
+ "flex items-center gap-1",
69
+ orientation === "vertical" ? "flex-col" : "flex-row",
70
+ read(props.class),
71
+ )}"
72
+ >${slot(props.children)}</div>`;
73
+ });
74
+
75
+ export interface ToolbarButtonProps extends ButtonProps {}
76
+
77
+ /**
78
+ * A control inside the bar.
79
+ *
80
+ * `Button` with the defaults a toolbar wants — ghost, small — so a row of them
81
+ * reads as a bar rather than as six primary actions competing for attention.
82
+ * Nothing else: a plain `Button` dropped in the bar navigates identically,
83
+ * which is the point of finding items by focusability.
84
+ */
85
+ export const ToolbarButton = component<ToolbarButtonProps>((props) =>
86
+ Button({ variant: "ghost", size: "sm", ...props }),
87
+ );
88
+
89
+ export interface ToolbarSeparatorProps {
90
+ class?: Reactive<string>;
91
+ }
92
+
93
+ /** A boundary between groups of controls, announced as one. */
94
+ export const ToolbarSeparator = component<ToolbarSeparatorProps>((props) => {
95
+ return Separator({
96
+ orientation: "vertical",
97
+ decorative: false,
98
+ class: () => cn("mx-1 h-6 self-center", read(props.class)),
99
+ });
100
+ });
@@ -8,11 +8,12 @@
8
8
  * organisms.
9
9
  *
10
10
  * Compound components are data-driven — `Accordion({ items: [...] })`, not
11
- * `<Accordion><AccordionItem>`. shadcn's compound API is a React-context
12
- * artifact; Aurora has no context, and the alternatives (a factory returning
13
- * bound parts, a handle threaded through props) are more machinery for less
14
- * clarity. The rendered markup is unchanged, so shadcn's CSS and its examples
15
- * still read across.
11
+ * `<Accordion><AccordionItem>`. Not for want of context: Aurora has it and these
12
+ * components use it. It lives on a stack during SETUP, so a part passed as a
13
+ * `Slot` thunk is built after that frame has popped and has nothing to read —
14
+ * which is exactly the shape `<Accordion><AccordionItem>` would need. Data keeps
15
+ * every part built while the context is there. The rendered markup is unchanged,
16
+ * so shadcn's CSS and its examples still read across.
16
17
  */
17
18
 
18
19
  export {
@@ -206,6 +207,14 @@ export {
206
207
  type ToggleGroupItemProps,
207
208
  type ToggleGroupProps,
208
209
  } from "./ToggleGroup.js";
210
+ export {
211
+ Toolbar,
212
+ ToolbarButton,
213
+ type ToolbarButtonProps,
214
+ type ToolbarProps,
215
+ ToolbarSeparator,
216
+ type ToolbarSeparatorProps,
217
+ } from "./Toolbar.js";
209
218
  export {
210
219
  Blockquote,
211
220
  H1,
@@ -1,9 +1,23 @@
1
1
  /**
2
2
  * Toaster — transient notifications.
3
3
  *
4
- * shadcn delegates this to `sonner`. nebula keeps it in-house, and the shape
5
- * is the same: one region mounted once near the app root, and a `toast()`
6
- * function callable from anywhere with no reference to it.
4
+ * shadcn ships two: `sonner`, which wraps a third-party library, and `toast`,
5
+ * its own, built on Base UI. nebula keeps it in-house with zero dependencies
6
+ * and follows the SECOND — the shape is the same: one region mounted once near
7
+ * the app root, and a `toast` object callable from anywhere with no reference
8
+ * to it.
9
+ *
10
+ * NAMED DEVIATIONS from Base UI's manager, all deliberate:
11
+ *
12
+ * - `show` / `dismiss` / `variant` / `duration` rather than `add` / `close` /
13
+ * `type` / `timeout`. `variant` is what every other nebula component calls
14
+ * this (Button, Alert, Badge), and renaming it here alone would make the
15
+ * package less consistent with itself than with Base UI.
16
+ * - `variant` keeps `warning`, which Base UI's `type` does not have.
17
+ * - No `priority` (display ordering), `data` (typed payload for a React render
18
+ * prop — a `Child` already covers it) or `positionerProps` (anchored toasts).
19
+ * - No `updateKey`. It exists to make React replay an animation without
20
+ * remounting; `update` here replaces the entry, and aurora re-renders it.
7
21
  *
8
22
  * That decoupling is the whole design. A queue in module state, a signal the
9
23
  * region subscribes to, and `toast.error(…)` works from a route handler's
@@ -25,50 +39,100 @@
25
39
  import { component, html, signal } from "@c9up/aurora";
26
40
  import type { Child } from "../lib/children.js";
27
41
  import { cn } from "../lib/cn.js";
28
- import { XIcon } from "../lib/icons.js";
42
+ import { LoaderIcon, XIcon } from "../lib/icons.js";
29
43
  import { fadeInOut } from "../lib/motion.js";
30
44
  import { type Reactive, read } from "../lib/props.js";
31
45
 
32
- export type ToastVariant = "default" | "success" | "error" | "warning";
46
+ export type ToastVariant =
47
+ | "default"
48
+ | "success"
49
+ | "error"
50
+ | "warning"
51
+ | "loading";
52
+
53
+ /**
54
+ * A toast's identity. A number when `show` minted it, a string when the caller
55
+ * supplied one — which is what makes `update` and deduplication possible, and
56
+ * how {@link toast.promise} turns one toast from loading into its outcome.
57
+ */
58
+ export type ToastId = number | string;
33
59
 
34
60
  export interface ToastOptions {
35
61
  title: Child;
36
62
  description?: Child;
37
63
  variant?: ToastVariant;
38
- /** Milliseconds on screen. `0` keeps it until dismissed. */
64
+ /**
65
+ * Milliseconds on screen. `0` keeps it until dismissed.
66
+ *
67
+ * Left out, it comes from the variant: an error stays twice as long because
68
+ * the user has to read it and often act on it, and a `loading` toast does not
69
+ * leave on its own at all — it is waiting for an outcome.
70
+ */
39
71
  duration?: number;
40
72
  action?: { label: string; onClick: () => void };
73
+ /**
74
+ * A stable id. Showing a toast under an id that is already on screen UPDATES
75
+ * it instead of stacking another — so "you are offline", raised on every
76
+ * failed request, is one toast rather than nine.
77
+ */
78
+ id?: string;
79
+ /** Called once the toast leaves, however it left. */
80
+ onClose?: () => void;
41
81
  }
42
82
 
43
- interface ActiveToast extends ToastOptions {
44
- readonly id: number;
83
+ interface ActiveToast extends Omit<ToastOptions, "id"> {
84
+ readonly id: ToastId;
45
85
  readonly variant: ToastVariant;
46
86
  }
47
87
 
48
88
  const DEFAULT_DURATION_MS = 5000;
49
89
 
90
+ /** How long a variant stays when the caller did not say. */
91
+ function defaultDuration(variant: ToastVariant): number {
92
+ if (variant === "loading") return 0;
93
+ return variant === "error" ? DEFAULT_DURATION_MS * 2 : DEFAULT_DURATION_MS;
94
+ }
95
+
50
96
  const queue = signal<readonly ActiveToast[]>([]);
51
- const timers = new Map<number, ReturnType<typeof setTimeout>>();
97
+ const timers = new Map<ToastId, ReturnType<typeof setTimeout>>();
52
98
  /** When each toast is due to disappear, as an epoch timestamp. */
53
- const deadlines = new Map<number, number>();
99
+ const deadlines = new Map<ToastId, number>();
54
100
  /** Time each toast had left when the pointer entered the region. */
55
- const remainders = new Map<number, number>();
101
+ const remainders = new Map<ToastId, number>();
56
102
  let nextId = 0;
57
103
 
58
- function dismiss(id: number): void {
104
+ function dismiss(id: ToastId): void {
105
+ const leaving = queue().find((entry) => entry.id === id);
59
106
  clearTimer(id);
60
107
  deadlines.delete(id);
61
108
  remainders.delete(id);
62
109
  queue(queue().filter((entry) => entry.id !== id));
110
+ notifyClosed(leaving);
111
+ }
112
+
113
+ /**
114
+ * Run a toast's `onClose`, without letting it take the caller down.
115
+ *
116
+ * The callback belongs to application code and runs from a timer, a click and
117
+ * `clear()` alike. One that throws would otherwise break whichever of those
118
+ * happened to be running — a dismissal that leaves the queue half-updated.
119
+ */
120
+ function notifyClosed(entry: ActiveToast | undefined): void {
121
+ if (entry?.onClose === undefined) return;
122
+ try {
123
+ entry.onClose();
124
+ } catch (error) {
125
+ console.error("[nebula] a toast onClose callback threw", error);
126
+ }
63
127
  }
64
128
 
65
- function clearTimer(id: number): void {
129
+ function clearTimer(id: ToastId): void {
66
130
  const timer = timers.get(id);
67
131
  if (timer !== undefined) clearTimeout(timer);
68
132
  timers.delete(id);
69
133
  }
70
134
 
71
- function schedule(id: number, duration: number): void {
135
+ function schedule(id: ToastId, duration: number): void {
72
136
  // A duration of zero means "stays until dismissed", so no timer and no
73
137
  // deadline — which is also what keeps pause/resume from resurrecting one.
74
138
  if (duration <= 0) return;
@@ -103,19 +167,79 @@ function resumeAll(minimumMs: number): void {
103
167
  remainders.clear();
104
168
  }
105
169
 
106
- function show(options: ToastOptions): number {
107
- nextId += 1;
108
- const id = nextId;
109
- const entry: ActiveToast = {
110
- ...options,
111
- id,
112
- variant: options.variant ?? "default",
113
- };
170
+ function show(options: ToastOptions): ToastId {
171
+ // A supplied id that is already on screen updates rather than stacks.
172
+ if (options.id !== undefined && has(options.id)) {
173
+ update(options.id, options);
174
+ return options.id;
175
+ }
176
+ let id: ToastId;
177
+ if (options.id === undefined) {
178
+ nextId += 1;
179
+ id = nextId;
180
+ } else {
181
+ id = options.id;
182
+ }
183
+ const variant = options.variant ?? "default";
184
+ const entry: ActiveToast = { ...options, id, variant };
114
185
  queue([...queue(), entry]);
115
- schedule(id, options.duration ?? DEFAULT_DURATION_MS);
186
+ schedule(id, options.duration ?? defaultDuration(variant));
116
187
  return id;
117
188
  }
118
189
 
190
+ function has(id: ToastId): boolean {
191
+ return queue().some((entry) => entry.id === id);
192
+ }
193
+
194
+ /**
195
+ * Change a toast that is already on screen. No-op if it has gone.
196
+ *
197
+ * The countdown is recomputed, because that is the part a caller would not
198
+ * think to ask for and always wants: a `loading` toast has no timer at all, so
199
+ * turning it into a success without rescheduling would leave it on screen for
200
+ * good. Which is exactly what {@link toast.promise} does to it.
201
+ */
202
+ function update(id: ToastId, patch: Partial<ToastOptions>): void {
203
+ const current = queue().find((entry) => entry.id === id);
204
+ if (current === undefined) return;
205
+ const variant = patch.variant ?? current.variant;
206
+ const next: ActiveToast = { ...current, ...patch, id, variant };
207
+ queue(queue().map((entry) => (entry.id === id ? next : entry)));
208
+ clearTimer(id);
209
+ deadlines.delete(id);
210
+ remainders.delete(id);
211
+ schedule(id, patch.duration ?? next.duration ?? defaultDuration(variant));
212
+ }
213
+
214
+ /** What a `promise` stage says: just a title, or the whole toast. */
215
+ export type ToastMessage = Child | Omit<ToastOptions, "id" | "variant">;
216
+
217
+ function optionsOf(message: ToastMessage): Omit<ToastOptions, "id"> {
218
+ // A plain object with a `title` is the options form; anything else — a
219
+ // string, a number, a template — is the title itself. Checked on `title`
220
+ // rather than on the shape in general, because a template result IS an
221
+ // object and would otherwise be mistaken for options.
222
+ if (
223
+ typeof message === "object" &&
224
+ message !== null &&
225
+ "title" in message &&
226
+ !Array.isArray(message)
227
+ ) {
228
+ return message;
229
+ }
230
+ return { title: message };
231
+ }
232
+
233
+ function resolveMessage<T>(
234
+ message: ToastMessage | ((value: T) => ToastMessage),
235
+ value: T,
236
+ ): Omit<ToastOptions, "id"> {
237
+ if (typeof message === "function") {
238
+ return optionsOf((message as (v: T) => ToastMessage)(value));
239
+ }
240
+ return optionsOf(message);
241
+ }
242
+
119
243
  /**
120
244
  * Raise a toast. Returns its id, which `dismiss` accepts.
121
245
  *
@@ -123,31 +247,76 @@ function show(options: ToastOptions): number {
123
247
  */
124
248
  export const toast = {
125
249
  show,
250
+ update,
126
251
  dismiss,
127
- success: (title: Child, description?: Child): number =>
252
+ success: (title: Child, description?: Child): ToastId =>
128
253
  show({ title, description, variant: "success" }),
129
- error: (title: Child, description?: Child): number =>
130
- // Errors stay twice as long: the user has to read them, and often act.
131
- show({
132
- title,
133
- description,
134
- variant: "error",
135
- duration: DEFAULT_DURATION_MS * 2,
136
- }),
137
- warning: (title: Child, description?: Child): number =>
254
+ error: (title: Child, description?: Child): ToastId =>
255
+ show({ title, description, variant: "error" }),
256
+ warning: (title: Child, description?: Child): ToastId =>
138
257
  show({ title, description, variant: "warning" }),
258
+ loading: (title: Child, description?: Child): ToastId =>
259
+ show({ title, description, variant: "loading" }),
260
+ /**
261
+ * One toast for the whole life of an async call: waiting, then the outcome.
262
+ *
263
+ * ```ts
264
+ * await toast.promise(save(form), {
265
+ * loading: 'Saving…',
266
+ * success: (saved) => `Saved ${saved.name}`,
267
+ * error: (reason) => ({ title: 'Could not save', description: String(reason) }),
268
+ * })
269
+ * ```
270
+ *
271
+ * Returns the SAME promise it was given, rejection included. It reports, it
272
+ * does not handle: swallowing the rejection here would turn a failed call
273
+ * into a red toast and nothing else, with the caller's own error path never
274
+ * running.
275
+ */
276
+ promise<T>(
277
+ work: Promise<T>,
278
+ messages: {
279
+ loading: ToastMessage;
280
+ success: ToastMessage | ((value: T) => ToastMessage);
281
+ error: ToastMessage | ((reason: unknown) => ToastMessage);
282
+ },
283
+ ): Promise<T> {
284
+ const id = show({ ...optionsOf(messages.loading), variant: "loading" });
285
+ // A separate chain, whose own rejection IS handled — so reporting the
286
+ // failure never adds an unhandled rejection of its own.
287
+ work.then(
288
+ (value) => {
289
+ update(id, {
290
+ ...resolveMessage(messages.success, value),
291
+ variant: "success",
292
+ });
293
+ },
294
+ (reason: unknown) => {
295
+ update(id, {
296
+ ...resolveMessage(messages.error, reason),
297
+ variant: "error",
298
+ });
299
+ },
300
+ );
301
+ return work;
302
+ },
139
303
  /** Clear everything — on navigation, say. */
140
304
  clear(): void {
141
305
  for (const timer of timers.values()) clearTimeout(timer);
142
306
  timers.clear();
143
307
  deadlines.clear();
144
308
  remainders.clear();
309
+ const leaving = queue();
145
310
  queue([]);
311
+ // After the queue is empty, so a callback that raises a toast of its own
312
+ // is not swept away by the clear that called it.
313
+ for (const entry of leaving) notifyClosed(entry);
146
314
  },
147
315
  };
148
316
 
149
317
  const variantClasses: Record<ToastVariant, string> = {
150
318
  default: "bg-popover text-popover-foreground border",
319
+ loading: "bg-popover text-muted-foreground border",
151
320
  success:
152
321
  "bg-popover text-popover-foreground border-l-4 border-l-primary border",
153
322
  error: "bg-popover text-destructive border-l-4 border-l-destructive border",
@@ -216,6 +385,11 @@ function renderToast(entry: ActiveToast): Child {
216
385
  fadeInOut,
217
386
  )}"
218
387
  >
388
+ ${
389
+ entry.variant === "loading"
390
+ ? LoaderIcon({ class: "size-4 mt-0.5 shrink-0 animate-spin" })
391
+ : null
392
+ }
219
393
  <div class="flex-1 text-sm">
220
394
  <div class="font-medium">${entry.title}</div>
221
395
  ${
@@ -388,6 +388,8 @@ export {
388
388
  export {
389
389
  Toaster,
390
390
  type ToasterProps,
391
+ type ToastId,
392
+ type ToastMessage,
391
393
  type ToastOptions,
392
394
  type ToastVariant,
393
395
  toast,
@@ -0,0 +1,61 @@
1
+ /// <reference lib="dom" />
2
+ /**
3
+ * Reading direction — the one place that answers "which way is forward?".
4
+ *
5
+ * Radix ships a `DirectionProvider` and threads the answer through React
6
+ * context. Aurora has a context, but a provider would be the wrong mechanism
7
+ * here: the direction is already on the page. `<html dir="rtl">`, a `dir`
8
+ * attribute on one panel, a stylesheet setting `direction` — all of them are
9
+ * answered by the computed style, and none of them requires the application to
10
+ * remember to wrap anything. A provider would be a second source of truth that
11
+ * silently disagrees with the first.
12
+ *
13
+ * The distinction that matters to callers is PHYSICAL versus LOGICAL. An arrow
14
+ * key is physical: ArrowRight means the key to the right, always. "The next
15
+ * item" is logical, and in a right-to-left list the next item is to the LEFT.
16
+ * `forward()` converts one into the other, and is the whole of this module's
17
+ * job.
18
+ */
19
+
20
+ export type Direction = "ltr" | "rtl";
21
+
22
+ /**
23
+ * The direction this element is laid out in.
24
+ *
25
+ * The computed style rather than the `dir` attribute, so an element inheriting
26
+ * from `<html dir="rtl">` answers correctly without every anchor carrying the
27
+ * attribute itself. `ltr` wherever there is no layout to ask — a server
28
+ * render, a jsdom without styles — which is also the correct default.
29
+ */
30
+ export function directionOf(element: Element | null | undefined): Direction {
31
+ if (element === null || element === undefined) return "ltr";
32
+ if (typeof getComputedStyle !== "function") return "ltr";
33
+ try {
34
+ return getComputedStyle(element).direction === "rtl" ? "rtl" : "ltr";
35
+ } catch {
36
+ // A detached node in some environments. Not a reason to fail a keypress.
37
+ return "ltr";
38
+ }
39
+ }
40
+
41
+ /** Shorthand for the check that reads better at a call site than `=== "rtl"`. */
42
+ export function isRightToLeft(element: Element | null | undefined): boolean {
43
+ return directionOf(element) === "rtl";
44
+ }
45
+
46
+ /**
47
+ * Which way a horizontal arrow key actually moves.
48
+ *
49
+ * `+1` for the next item, `-1` for the previous. ArrowRight is `+1` in a
50
+ * left-to-right widget and `-1` in a right-to-left one — that mirroring is the
51
+ * entire reason this exists, and getting it wrong makes every menu, tab list
52
+ * and toolbar navigate backwards for half the world's readers.
53
+ */
54
+ export function forward(
55
+ key: "ArrowLeft" | "ArrowRight",
56
+ element: Element | null | undefined,
57
+ ): -1 | 1 {
58
+ const rightIsForward = !isRightToLeft(element);
59
+ if (key === "ArrowRight") return rightIsForward ? 1 : -1;
60
+ return rightIsForward ? -1 : 1;
61
+ }