@ignite-ember/ui-react 0.0.0-stage → 0.2.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/LICENSE +202 -0
- package/NOTICE +5 -0
- package/README.md +217 -2
- package/dist/CopySource.d.ts +4 -0
- package/dist/CopySource.d.ts.map +1 -0
- package/dist/CopySource.js +36 -0
- package/dist/CopySource.js.map +1 -0
- package/dist/DataTable.d.ts +61 -0
- package/dist/DataTable.d.ts.map +1 -0
- package/dist/DataTable.js +29 -0
- package/dist/DataTable.js.map +1 -0
- package/dist/ErrorBoundary.d.ts +68 -0
- package/dist/ErrorBoundary.d.ts.map +1 -0
- package/dist/ErrorBoundary.js +63 -0
- package/dist/ErrorBoundary.js.map +1 -0
- package/dist/LiveRegion.d.ts +35 -0
- package/dist/LiveRegion.d.ts.map +1 -0
- package/dist/LiveRegion.js +70 -0
- package/dist/LiveRegion.js.map +1 -0
- package/dist/Markdown.d.ts +18 -0
- package/dist/Markdown.d.ts.map +1 -0
- package/dist/Markdown.js +52 -0
- package/dist/Markdown.js.map +1 -0
- package/dist/MarkdownInline.d.ts +44 -0
- package/dist/MarkdownInline.d.ts.map +1 -0
- package/dist/MarkdownInline.js +144 -0
- package/dist/MarkdownInline.js.map +1 -0
- package/dist/MenuIcon.d.ts +54 -0
- package/dist/MenuIcon.d.ts.map +1 -0
- package/dist/MenuIcon.js +96 -0
- package/dist/MenuIcon.js.map +1 -0
- package/dist/Mermaid.d.ts +38 -0
- package/dist/Mermaid.d.ts.map +1 -0
- package/dist/Mermaid.js +119 -0
- package/dist/Mermaid.js.map +1 -0
- package/dist/Monogram.d.ts +42 -0
- package/dist/Monogram.d.ts.map +1 -0
- package/dist/Monogram.js +88 -0
- package/dist/Monogram.js.map +1 -0
- package/dist/OverflowMenu.d.ts +55 -0
- package/dist/OverflowMenu.d.ts.map +1 -0
- package/dist/OverflowMenu.js +141 -0
- package/dist/OverflowMenu.js.map +1 -0
- package/dist/Shell.d.ts +54 -0
- package/dist/Shell.d.ts.map +1 -0
- package/dist/Shell.js +31 -0
- package/dist/Shell.js.map +1 -0
- package/dist/Skeleton.d.ts +32 -0
- package/dist/Skeleton.d.ts.map +1 -0
- package/dist/Skeleton.js +26 -0
- package/dist/Skeleton.js.map +1 -0
- package/dist/Split.d.ts +66 -0
- package/dist/Split.d.ts.map +1 -0
- package/dist/Split.js +133 -0
- package/dist/Split.js.map +1 -0
- package/dist/Toast.d.ts +87 -0
- package/dist/Toast.d.ts.map +1 -0
- package/dist/Toast.js +118 -0
- package/dist/Toast.js.map +1 -0
- package/dist/Tooltip.d.ts +15 -0
- package/dist/Tooltip.d.ts.map +1 -0
- package/dist/Tooltip.js +144 -0
- package/dist/Tooltip.js.map +1 -0
- package/dist/cx.d.ts +3 -0
- package/dist/cx.d.ts.map +1 -0
- package/dist/cx.js +5 -0
- package/dist/cx.js.map +1 -0
- package/dist/fenceInfo.d.ts +23 -0
- package/dist/fenceInfo.d.ts.map +1 -0
- package/dist/fenceInfo.js +19 -0
- package/dist/fenceInfo.js.map +1 -0
- package/dist/index.d.ts +82 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +82 -0
- package/dist/index.js.map +1 -0
- package/dist/primitives.d.ts +383 -0
- package/dist/primitives.d.ts.map +1 -0
- package/dist/primitives.js +340 -0
- package/dist/primitives.js.map +1 -0
- package/package.json +56 -4
- package/src/CopySource.tsx +52 -0
- package/src/DataTable.tsx +104 -0
- package/src/ErrorBoundary.tsx +102 -0
- package/src/LiveRegion.tsx +121 -0
- package/src/Markdown.tsx +71 -0
- package/src/MarkdownInline.tsx +164 -0
- package/src/MenuIcon.tsx +203 -0
- package/src/Mermaid.tsx +142 -0
- package/src/Monogram.tsx +103 -0
- package/src/OverflowMenu.tsx +352 -0
- package/src/Shell.tsx +86 -0
- package/src/Skeleton.tsx +68 -0
- package/src/Split.tsx +242 -0
- package/src/Toast.tsx +258 -0
- package/src/Tooltip.tsx +188 -0
- package/src/cx.ts +4 -0
- package/src/fenceInfo.ts +33 -0
- package/src/index.ts +153 -0
- package/src/primitives.tsx +887 -0
package/src/Skeleton.tsx
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { CSSProperties } from "react";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Animated placeholder block. Render at the same approximate size
|
|
5
|
+
* and rhythm as the eventual content so the layout doesn't jump
|
|
6
|
+
* when async data lands.
|
|
7
|
+
*
|
|
8
|
+
* Usage:
|
|
9
|
+
* <Skeleton.Line width="60%" />
|
|
10
|
+
* <Skeleton.Block height={64} />
|
|
11
|
+
* <Skeleton.Circle size={48} />
|
|
12
|
+
*/
|
|
13
|
+
export const Skeleton = {
|
|
14
|
+
Line({
|
|
15
|
+
width = "100%",
|
|
16
|
+
height = 12,
|
|
17
|
+
style,
|
|
18
|
+
}: {
|
|
19
|
+
width?: number | string;
|
|
20
|
+
height?: number | string;
|
|
21
|
+
style?: CSSProperties;
|
|
22
|
+
}) {
|
|
23
|
+
return (
|
|
24
|
+
<span
|
|
25
|
+
className="skeleton skeleton-text"
|
|
26
|
+
style={{ display: "block", width, height, ...style }}
|
|
27
|
+
/>
|
|
28
|
+
);
|
|
29
|
+
},
|
|
30
|
+
Block({
|
|
31
|
+
height = 64,
|
|
32
|
+
width = "100%",
|
|
33
|
+
style,
|
|
34
|
+
}: {
|
|
35
|
+
height?: number | string;
|
|
36
|
+
width?: number | string;
|
|
37
|
+
style?: CSSProperties;
|
|
38
|
+
}) {
|
|
39
|
+
return (
|
|
40
|
+
<span
|
|
41
|
+
className="skeleton skeleton-block"
|
|
42
|
+
style={{ display: "block", height, width, ...style }}
|
|
43
|
+
/>
|
|
44
|
+
);
|
|
45
|
+
},
|
|
46
|
+
Circle({ size = 24, style }: { size?: number; style?: CSSProperties }) {
|
|
47
|
+
return (
|
|
48
|
+
<span
|
|
49
|
+
className="skeleton skeleton-circle"
|
|
50
|
+
style={{ display: "inline-block", width: size, height: size, ...style }}
|
|
51
|
+
/>
|
|
52
|
+
);
|
|
53
|
+
},
|
|
54
|
+
Rows({ count = 4, style }: { count?: number; style?: CSSProperties }) {
|
|
55
|
+
return (
|
|
56
|
+
<div
|
|
57
|
+
style={{ display: "flex", flexDirection: "column", gap: 12, ...style }}
|
|
58
|
+
>
|
|
59
|
+
{Array.from({ length: count }).map((_, i) => (
|
|
60
|
+
<div key={i}>
|
|
61
|
+
<Skeleton.Line width="40%" height={11} />
|
|
62
|
+
<Skeleton.Line width="100%" />
|
|
63
|
+
</div>
|
|
64
|
+
))}
|
|
65
|
+
</div>
|
|
66
|
+
);
|
|
67
|
+
},
|
|
68
|
+
};
|
package/src/Split.tsx
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Two panes and a rule you can move.
|
|
3
|
+
*
|
|
4
|
+
* Both extensions built against this floor wanted one and neither
|
|
5
|
+
* could have it: `ColumnHandle` is 180 lines in the app, does exactly
|
|
6
|
+
* this, and was not published. `examples/release-notes` hand-rolls
|
|
7
|
+
* the grid, the pointer capture, the clamping and the separator, and
|
|
8
|
+
* says so in its README. Every two-pane extension would write that
|
|
9
|
+
* again, differently — which is how two panels in one product end up
|
|
10
|
+
* resizing differently.
|
|
11
|
+
*
|
|
12
|
+
* **It drives a CSS variable, not React state.** A `pointermove`
|
|
13
|
+
* handler that re-rendered would re-render the whole document on
|
|
14
|
+
* every frame of the drag, and would stutter on exactly the documents
|
|
15
|
+
* busy enough to be worth resizing. Writing the variable lets the
|
|
16
|
+
* browser reflow and leaves the tree alone.
|
|
17
|
+
*
|
|
18
|
+
* **It does not remember the width**, and that is the deliberate
|
|
19
|
+
* difference from the app's version. An extension is served from an
|
|
20
|
+
* ephemeral port, a port is part of an origin, so its `localStorage`
|
|
21
|
+
* is wiped whenever the backend restarts — persisting there would be
|
|
22
|
+
* a promise this cannot keep. `onResize` hands the width back
|
|
23
|
+
* instead, and an extension that wants it remembered puts it
|
|
24
|
+
* somewhere that survives: `bridge.setLocation`, or its own backend.
|
|
25
|
+
*
|
|
26
|
+
* The other difference is `aria-valuenow`. A focusable `separator`
|
|
27
|
+
* that never says where it is tells a screen-reader user that
|
|
28
|
+
* something is adjustable and not what it is adjusted to.
|
|
29
|
+
*/
|
|
30
|
+
import {
|
|
31
|
+
useCallback,
|
|
32
|
+
useId,
|
|
33
|
+
useRef,
|
|
34
|
+
useState,
|
|
35
|
+
type CSSProperties,
|
|
36
|
+
type HTMLAttributes,
|
|
37
|
+
type PointerEvent as ReactPointerEvent,
|
|
38
|
+
type KeyboardEvent as ReactKeyboardEvent,
|
|
39
|
+
type ReactNode,
|
|
40
|
+
} from "react";
|
|
41
|
+
|
|
42
|
+
import { cx } from "./cx.js";
|
|
43
|
+
|
|
44
|
+
/** Keyboard step, and the larger one with Shift held. */
|
|
45
|
+
const STEP = 12;
|
|
46
|
+
const BIG_STEP = 48;
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* How much of the window one pane may take, whatever `max` says.
|
|
50
|
+
*
|
|
51
|
+
* A pane dragged wide on a narrow laptop otherwise leaves the other
|
|
52
|
+
* a few characters across — a state the reader has to drag their way
|
|
53
|
+
* back out of.
|
|
54
|
+
*/
|
|
55
|
+
const MOST_OF_WINDOW = 0.6;
|
|
56
|
+
|
|
57
|
+
/** What a {@link Split} takes. */
|
|
58
|
+
export interface SplitProps extends Omit<
|
|
59
|
+
HTMLAttributes<HTMLDivElement>,
|
|
60
|
+
"onResize"
|
|
61
|
+
> {
|
|
62
|
+
/** The fixed-width pane. */
|
|
63
|
+
aside: ReactNode;
|
|
64
|
+
/** The pane that takes what is left. */
|
|
65
|
+
children: ReactNode;
|
|
66
|
+
/** Which side `aside` is on. Defaults to the left. */
|
|
67
|
+
side?: "start" | "end";
|
|
68
|
+
/** Starting width of `aside`, in pixels. */
|
|
69
|
+
defaultWidth?: number;
|
|
70
|
+
/** The narrowest `aside` may be, in pixels. */
|
|
71
|
+
min?: number;
|
|
72
|
+
/** The widest `aside` may be, in pixels — and never more than 60% of the window. */
|
|
73
|
+
max?: number;
|
|
74
|
+
/**
|
|
75
|
+
* Said to a screen reader, and shown on hover.
|
|
76
|
+
*
|
|
77
|
+
* Required: "separator" is what the role already announces, and a
|
|
78
|
+
* page with two of them needs to say which is which.
|
|
79
|
+
*/
|
|
80
|
+
label: string;
|
|
81
|
+
/**
|
|
82
|
+
* The width changed. Called on release and on each keypress, not
|
|
83
|
+
* on every pointer move — a handler that fires sixty times a second
|
|
84
|
+
* is a handler somebody writes a round trip into.
|
|
85
|
+
*/
|
|
86
|
+
onResize?: (width: number) => void;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Two panes and a rule you can move.
|
|
91
|
+
*
|
|
92
|
+
* See the note at the top of this file: it drives a CSS variable
|
|
93
|
+
* rather than React state, and it does not remember the width.
|
|
94
|
+
*/
|
|
95
|
+
export function Split({
|
|
96
|
+
aside,
|
|
97
|
+
children,
|
|
98
|
+
side = "start",
|
|
99
|
+
defaultWidth = 280,
|
|
100
|
+
min = 160,
|
|
101
|
+
max = 640,
|
|
102
|
+
label,
|
|
103
|
+
onResize,
|
|
104
|
+
className,
|
|
105
|
+
...rest
|
|
106
|
+
}: SplitProps) {
|
|
107
|
+
// Scoped to this instance, so two splits on one page do not fight
|
|
108
|
+
// over one custom property.
|
|
109
|
+
const variable = `--ui-split-${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
|
|
110
|
+
const root = useRef<HTMLDivElement | null>(null);
|
|
111
|
+
// The aside itself, not "the first child": with `side="end"` the
|
|
112
|
+
// first child is the main pane.
|
|
113
|
+
const asidePane = useRef<HTMLDivElement | null>(null);
|
|
114
|
+
const drag = useRef<{ startX: number; startWidth: number } | null>(null);
|
|
115
|
+
// Mirrored into state only so `aria-valuenow` is right. The layout
|
|
116
|
+
// itself never reads this.
|
|
117
|
+
const [announced, setAnnounced] = useState(defaultWidth);
|
|
118
|
+
|
|
119
|
+
const clamp = useCallback(
|
|
120
|
+
(px: number) => {
|
|
121
|
+
const ceiling = Math.min(
|
|
122
|
+
max,
|
|
123
|
+
Math.round(
|
|
124
|
+
(typeof window === "undefined" ? max : window.innerWidth) *
|
|
125
|
+
MOST_OF_WINDOW,
|
|
126
|
+
),
|
|
127
|
+
);
|
|
128
|
+
// `min` wins over the ceiling on a very narrow window: a pane
|
|
129
|
+
// below its minimum is unreadable, and unreadable is worse
|
|
130
|
+
// than wide.
|
|
131
|
+
return Math.round(Math.max(min, Math.min(px, Math.max(min, ceiling))));
|
|
132
|
+
},
|
|
133
|
+
[min, max],
|
|
134
|
+
);
|
|
135
|
+
|
|
136
|
+
const apply = useCallback(
|
|
137
|
+
(px: number) => {
|
|
138
|
+
const width = clamp(px);
|
|
139
|
+
root.current?.style.setProperty(variable, `${width}px`);
|
|
140
|
+
setAnnounced(width);
|
|
141
|
+
return width;
|
|
142
|
+
},
|
|
143
|
+
[clamp, variable],
|
|
144
|
+
);
|
|
145
|
+
|
|
146
|
+
const currentWidth = () =>
|
|
147
|
+
asidePane.current?.getBoundingClientRect().width ?? defaultWidth;
|
|
148
|
+
|
|
149
|
+
const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
|
|
150
|
+
event.preventDefault();
|
|
151
|
+
event.currentTarget.setPointerCapture(event.pointerId);
|
|
152
|
+
drag.current = { startX: event.clientX, startWidth: currentWidth() };
|
|
153
|
+
// On the root rather than the strip, so it survives the pointer
|
|
154
|
+
// leaving — which it does on any drag faster than the reflow.
|
|
155
|
+
root.current?.classList.add("ui-split-resizing");
|
|
156
|
+
};
|
|
157
|
+
|
|
158
|
+
const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
|
|
159
|
+
const from = drag.current;
|
|
160
|
+
if (from === null) return;
|
|
161
|
+
const travelled = event.clientX - from.startX;
|
|
162
|
+
apply(from.startWidth + (side === "start" ? travelled : -travelled));
|
|
163
|
+
};
|
|
164
|
+
|
|
165
|
+
const finish = (event: ReactPointerEvent<HTMLDivElement>) => {
|
|
166
|
+
if (drag.current === null) return;
|
|
167
|
+
drag.current = null;
|
|
168
|
+
root.current?.classList.remove("ui-split-resizing");
|
|
169
|
+
event.currentTarget.releasePointerCapture?.(event.pointerId);
|
|
170
|
+
onResize?.(clamp(currentWidth()));
|
|
171
|
+
};
|
|
172
|
+
|
|
173
|
+
const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
|
|
174
|
+
// A 5px strip is a hard target with a trackpad and an impossible
|
|
175
|
+
// one without a pointer, and this is the only way to move a pane
|
|
176
|
+
// that is otherwise fixed.
|
|
177
|
+
const step = event.shiftKey ? BIG_STEP : STEP;
|
|
178
|
+
const wider = side === "start" ? "ArrowRight" : "ArrowLeft";
|
|
179
|
+
const narrower = side === "start" ? "ArrowLeft" : "ArrowRight";
|
|
180
|
+
let next: number | null = null;
|
|
181
|
+
if (event.key === wider) next = currentWidth() + step;
|
|
182
|
+
else if (event.key === narrower) next = currentWidth() - step;
|
|
183
|
+
else if (event.key === "Home") next = min;
|
|
184
|
+
else if (event.key === "End") next = max;
|
|
185
|
+
if (next === null) return;
|
|
186
|
+
event.preventDefault();
|
|
187
|
+
onResize?.(apply(next));
|
|
188
|
+
};
|
|
189
|
+
|
|
190
|
+
const handle = (
|
|
191
|
+
<div
|
|
192
|
+
key="handle"
|
|
193
|
+
className="ui-split-handle"
|
|
194
|
+
role="separator"
|
|
195
|
+
aria-orientation="vertical"
|
|
196
|
+
aria-label={label}
|
|
197
|
+
title={label}
|
|
198
|
+
aria-valuenow={announced}
|
|
199
|
+
aria-valuemin={min}
|
|
200
|
+
aria-valuemax={max}
|
|
201
|
+
tabIndex={0}
|
|
202
|
+
onPointerDown={onPointerDown}
|
|
203
|
+
onPointerMove={onPointerMove}
|
|
204
|
+
onPointerUp={finish}
|
|
205
|
+
onPointerCancel={finish}
|
|
206
|
+
onKeyDown={onKeyDown}
|
|
207
|
+
// Back to where it started. A pane dragged somewhere silly is
|
|
208
|
+
// otherwise a slow drag back to a width nobody remembers.
|
|
209
|
+
onDoubleClick={() => onResize?.(apply(defaultWidth))}
|
|
210
|
+
/>
|
|
211
|
+
);
|
|
212
|
+
|
|
213
|
+
const asideElement = (
|
|
214
|
+
<div key="aside" ref={asidePane} className="ui-split-aside">
|
|
215
|
+
{aside}
|
|
216
|
+
</div>
|
|
217
|
+
);
|
|
218
|
+
const mainElement = (
|
|
219
|
+
<div key="main" className="ui-split-main">
|
|
220
|
+
{children}
|
|
221
|
+
</div>
|
|
222
|
+
);
|
|
223
|
+
// Keyed, so flipping `side` reorders the panes instead of remounting them.
|
|
224
|
+
const panes =
|
|
225
|
+
side === "start"
|
|
226
|
+
? [asideElement, handle, mainElement]
|
|
227
|
+
: [mainElement, handle, asideElement];
|
|
228
|
+
|
|
229
|
+
return (
|
|
230
|
+
<div
|
|
231
|
+
{...rest}
|
|
232
|
+
ref={root}
|
|
233
|
+
className={cx("ui-split", side === "end" && "ui-split-end", className)}
|
|
234
|
+
style={
|
|
235
|
+
{ [variable]: `${defaultWidth}px`, ...rest.style } as CSSProperties
|
|
236
|
+
}
|
|
237
|
+
data-split-var={variable}
|
|
238
|
+
>
|
|
239
|
+
{panes}
|
|
240
|
+
</div>
|
|
241
|
+
);
|
|
242
|
+
}
|
package/src/Toast.tsx
ADDED
|
@@ -0,0 +1,258 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* "It saved." — the message every extension needs and none had.
|
|
3
|
+
*
|
|
4
|
+
* EXTENSIBILITY §5 names `notify` in the list of bridge APIs that do
|
|
5
|
+
* not exist. A specified-and-absent API is worse than a missing one,
|
|
6
|
+
* because a partner designs against it and finds out on demo day.
|
|
7
|
+
*
|
|
8
|
+
* This is the in-frame half: an extension's own toasts, in its own
|
|
9
|
+
* frame. It is not `bridge.notify` — that would put a message in
|
|
10
|
+
* igni's chrome, outside the frame, and needs a host envelope that
|
|
11
|
+
* does not exist yet. The distinction matters because they are not
|
|
12
|
+
* interchangeable: a toast about something inside this panel belongs
|
|
13
|
+
* inside this panel, and only something the user must see after
|
|
14
|
+
* navigating away belongs to the host.
|
|
15
|
+
*
|
|
16
|
+
* **Announced, not just drawn.** The stack is a polite live region,
|
|
17
|
+
* so a toast reaches somebody who is not looking at that corner. A
|
|
18
|
+
* `danger` toast is assertive instead: it is the one case where
|
|
19
|
+
* interrupting is correct.
|
|
20
|
+
*
|
|
21
|
+
* Toasts do not stack indefinitely and do not auto-dismiss when they
|
|
22
|
+
* carry an action — a message that disappears while you are reaching
|
|
23
|
+
* for its button is a message that was never actionable.
|
|
24
|
+
*/
|
|
25
|
+
import {
|
|
26
|
+
createContext,
|
|
27
|
+
useCallback,
|
|
28
|
+
useContext,
|
|
29
|
+
useEffect,
|
|
30
|
+
useMemo,
|
|
31
|
+
useRef,
|
|
32
|
+
useState,
|
|
33
|
+
type HTMLAttributes,
|
|
34
|
+
type ReactNode,
|
|
35
|
+
} from "react";
|
|
36
|
+
|
|
37
|
+
import type { Tone } from "./primitives.js";
|
|
38
|
+
|
|
39
|
+
function cx(...parts: (string | false | null | undefined)[]): string {
|
|
40
|
+
return parts.filter(Boolean).join(" ");
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** How long a toast stays, when it stays at all. */
|
|
44
|
+
const DEFAULT_MS = 5_000;
|
|
45
|
+
|
|
46
|
+
/** Beyond this, the oldest goes. A wall of toasts is not a message. */
|
|
47
|
+
const MAX_VISIBLE = 4;
|
|
48
|
+
|
|
49
|
+
/** What a toast says and how long it stays. */
|
|
50
|
+
export interface ToastOptions {
|
|
51
|
+
/** How loud it is. `danger` interrupts; the rest wait for a pause. */
|
|
52
|
+
tone?: Tone;
|
|
53
|
+
/**
|
|
54
|
+
* Milliseconds before it goes. `null` keeps it until dismissed,
|
|
55
|
+
* which is the default when there is an `action`.
|
|
56
|
+
*/
|
|
57
|
+
duration?: number | null;
|
|
58
|
+
/** One thing to do about it. Keeps the toast until dismissed. */
|
|
59
|
+
action?: ReactNode;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** A toast that is on screen. */
|
|
63
|
+
export interface Toast extends ToastOptions {
|
|
64
|
+
/** Its id, so it can be dismissed early. */
|
|
65
|
+
id: string;
|
|
66
|
+
/** What it says. */
|
|
67
|
+
message: ReactNode;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** How to raise and dismiss toasts. */
|
|
71
|
+
export interface ToastApi {
|
|
72
|
+
/** Show one. Returns its id, so it can be dismissed early. */
|
|
73
|
+
show: (message: ReactNode, options?: ToastOptions) => string;
|
|
74
|
+
/** Take one away before its time is up. */
|
|
75
|
+
dismiss: (id: string) => void;
|
|
76
|
+
/** Take every one away. */
|
|
77
|
+
clear: () => void;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
const ToastContext = createContext<ToastApi | null>(null);
|
|
81
|
+
|
|
82
|
+
let counter = 0;
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Wrap the part of the app that raises toasts.
|
|
86
|
+
*
|
|
87
|
+
* Renders the stack itself, so there is nothing to place and no way
|
|
88
|
+
* to forget to place it.
|
|
89
|
+
*/
|
|
90
|
+
export function ToastHost({ children }: { children: ReactNode }) {
|
|
91
|
+
const [toasts, setToasts] = useState<Toast[]>([]);
|
|
92
|
+
const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());
|
|
93
|
+
|
|
94
|
+
const dismiss = useCallback((id: string) => {
|
|
95
|
+
const timer = timers.current.get(id);
|
|
96
|
+
if (timer !== undefined) {
|
|
97
|
+
clearTimeout(timer);
|
|
98
|
+
timers.current.delete(id);
|
|
99
|
+
}
|
|
100
|
+
setToasts((current) => current.filter((t) => t.id !== id));
|
|
101
|
+
}, []);
|
|
102
|
+
|
|
103
|
+
const show = useCallback(
|
|
104
|
+
(message: ReactNode, options: ToastOptions = {}) => {
|
|
105
|
+
const id = `toast-${++counter}`;
|
|
106
|
+
// A toast with something to do stays until it is dealt with.
|
|
107
|
+
// Auto-dismissing it means the button can vanish mid-reach.
|
|
108
|
+
const duration =
|
|
109
|
+
options.duration !== undefined
|
|
110
|
+
? options.duration
|
|
111
|
+
: options.action !== undefined
|
|
112
|
+
? null
|
|
113
|
+
: DEFAULT_MS;
|
|
114
|
+
|
|
115
|
+
setToasts((current) =>
|
|
116
|
+
[...current, { ...options, id, message }].slice(-MAX_VISIBLE),
|
|
117
|
+
);
|
|
118
|
+
|
|
119
|
+
if (duration !== null) {
|
|
120
|
+
timers.current.set(
|
|
121
|
+
id,
|
|
122
|
+
setTimeout(() => dismiss(id), duration),
|
|
123
|
+
);
|
|
124
|
+
}
|
|
125
|
+
return id;
|
|
126
|
+
},
|
|
127
|
+
[dismiss],
|
|
128
|
+
);
|
|
129
|
+
|
|
130
|
+
const clear = useCallback(() => {
|
|
131
|
+
for (const timer of timers.current.values()) clearTimeout(timer);
|
|
132
|
+
timers.current.clear();
|
|
133
|
+
setToasts([]);
|
|
134
|
+
}, []);
|
|
135
|
+
|
|
136
|
+
// Timers outlive the component otherwise, and fire `setToasts` on
|
|
137
|
+
// something unmounted.
|
|
138
|
+
useEffect(() => {
|
|
139
|
+
const pending = timers.current;
|
|
140
|
+
return () => {
|
|
141
|
+
for (const timer of pending.values()) clearTimeout(timer);
|
|
142
|
+
pending.clear();
|
|
143
|
+
};
|
|
144
|
+
}, []);
|
|
145
|
+
|
|
146
|
+
const api = useMemo<ToastApi>(
|
|
147
|
+
() => ({ show, dismiss, clear }),
|
|
148
|
+
[show, dismiss, clear],
|
|
149
|
+
);
|
|
150
|
+
|
|
151
|
+
return (
|
|
152
|
+
<ToastContext.Provider value={api}>
|
|
153
|
+
{children}
|
|
154
|
+
<ToastList toasts={toasts} onDismiss={dismiss} />
|
|
155
|
+
</ToastContext.Provider>
|
|
156
|
+
);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function ToastList({
|
|
160
|
+
toasts,
|
|
161
|
+
onDismiss,
|
|
162
|
+
}: {
|
|
163
|
+
toasts: Toast[];
|
|
164
|
+
onDismiss: (id: string) => void;
|
|
165
|
+
}) {
|
|
166
|
+
return (
|
|
167
|
+
<div className="ui-toasts">
|
|
168
|
+
{toasts.map((toast) => (
|
|
169
|
+
<div
|
|
170
|
+
key={toast.id}
|
|
171
|
+
className="ui-toast"
|
|
172
|
+
data-tone={toast.tone ?? "neutral"}
|
|
173
|
+
// A failure interrupts; everything else waits for a pause.
|
|
174
|
+
role={toast.tone === "danger" ? "alert" : "status"}
|
|
175
|
+
aria-live={toast.tone === "danger" ? "assertive" : "polite"}
|
|
176
|
+
>
|
|
177
|
+
<div className="ui-toast-body">
|
|
178
|
+
{toast.message}
|
|
179
|
+
{toast.action}
|
|
180
|
+
</div>
|
|
181
|
+
<button
|
|
182
|
+
type="button"
|
|
183
|
+
className="ui-toast-dismiss"
|
|
184
|
+
// Named, because "×" is announced as "times" or as
|
|
185
|
+
// nothing, and a stack of them is unnavigable.
|
|
186
|
+
aria-label="Dismiss notification"
|
|
187
|
+
onClick={() => onDismiss(toast.id)}
|
|
188
|
+
>
|
|
189
|
+
×
|
|
190
|
+
</button>
|
|
191
|
+
</div>
|
|
192
|
+
))}
|
|
193
|
+
</div>
|
|
194
|
+
);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Raise a toast.
|
|
199
|
+
*
|
|
200
|
+
* Throws outside a {@link ToastHost} rather than returning a no-op.
|
|
201
|
+
* A silent no-op here means a save that reports success by showing
|
|
202
|
+
* nothing, which looks exactly like a save that did not happen.
|
|
203
|
+
*/
|
|
204
|
+
export function useToast(): ToastApi {
|
|
205
|
+
const api = useContext(ToastContext);
|
|
206
|
+
if (api === null) {
|
|
207
|
+
throw new Error(
|
|
208
|
+
"useToast was called outside a <ToastHost>. Wrap your app in one — " +
|
|
209
|
+
"without it a toast would be silently dropped, which looks the " +
|
|
210
|
+
"same as the action never happening.",
|
|
211
|
+
);
|
|
212
|
+
}
|
|
213
|
+
return api;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/** What a {@link Banner} takes. */
|
|
217
|
+
export interface BannerProps extends HTMLAttributes<HTMLDivElement> {
|
|
218
|
+
/** How loud it is. */
|
|
219
|
+
tone?: Tone;
|
|
220
|
+
/** A dismiss affordance appears when this is given. */
|
|
221
|
+
onDismiss?: () => void;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* A condition that is still true.
|
|
226
|
+
*
|
|
227
|
+
* Not a toast: a toast is about something that just happened and
|
|
228
|
+
* goes away, a banner is about a state — offline, read-only, licence
|
|
229
|
+
* expiring — and stays until the state does not.
|
|
230
|
+
*/
|
|
231
|
+
export function Banner({
|
|
232
|
+
tone = "neutral",
|
|
233
|
+
onDismiss,
|
|
234
|
+
children,
|
|
235
|
+
className,
|
|
236
|
+
...rest
|
|
237
|
+
}: BannerProps) {
|
|
238
|
+
return (
|
|
239
|
+
<div
|
|
240
|
+
{...rest}
|
|
241
|
+
className={cx("ui-banner", className)}
|
|
242
|
+
data-tone={tone}
|
|
243
|
+
role={tone === "danger" ? "alert" : "status"}
|
|
244
|
+
>
|
|
245
|
+
<div className="ui-banner-body">{children}</div>
|
|
246
|
+
{onDismiss === undefined ? null : (
|
|
247
|
+
<button
|
|
248
|
+
type="button"
|
|
249
|
+
className="ui-toast-dismiss"
|
|
250
|
+
aria-label="Dismiss message"
|
|
251
|
+
onClick={onDismiss}
|
|
252
|
+
>
|
|
253
|
+
×
|
|
254
|
+
</button>
|
|
255
|
+
)}
|
|
256
|
+
</div>
|
|
257
|
+
);
|
|
258
|
+
}
|