@ignite-ember/ui-react 0.0.0-stage → 0.2.1

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 (134) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +5 -0
  3. package/README.md +260 -2
  4. package/dist/CopySource.d.ts +4 -0
  5. package/dist/CopySource.d.ts.map +1 -0
  6. package/dist/CopySource.js +50 -0
  7. package/dist/CopySource.js.map +1 -0
  8. package/dist/DataTable.d.ts +77 -0
  9. package/dist/DataTable.d.ts.map +1 -0
  10. package/dist/DataTable.js +45 -0
  11. package/dist/DataTable.js.map +1 -0
  12. package/dist/Dialog.d.ts +41 -0
  13. package/dist/Dialog.d.ts.map +1 -0
  14. package/dist/Dialog.js +94 -0
  15. package/dist/Dialog.js.map +1 -0
  16. package/dist/ErrorBoundary.d.ts +97 -0
  17. package/dist/ErrorBoundary.d.ts.map +1 -0
  18. package/dist/ErrorBoundary.js +97 -0
  19. package/dist/ErrorBoundary.js.map +1 -0
  20. package/dist/LiveRegion.d.ts +41 -0
  21. package/dist/LiveRegion.d.ts.map +1 -0
  22. package/dist/LiveRegion.js +76 -0
  23. package/dist/LiveRegion.js.map +1 -0
  24. package/dist/Markdown.d.ts +22 -0
  25. package/dist/Markdown.d.ts.map +1 -0
  26. package/dist/Markdown.js +56 -0
  27. package/dist/Markdown.js.map +1 -0
  28. package/dist/MarkdownInline.d.ts +53 -0
  29. package/dist/MarkdownInline.d.ts.map +1 -0
  30. package/dist/MarkdownInline.js +159 -0
  31. package/dist/MarkdownInline.js.map +1 -0
  32. package/dist/MenuIcon.d.ts +60 -0
  33. package/dist/MenuIcon.d.ts.map +1 -0
  34. package/dist/MenuIcon.js +102 -0
  35. package/dist/MenuIcon.js.map +1 -0
  36. package/dist/Mermaid.d.ts +40 -0
  37. package/dist/Mermaid.d.ts.map +1 -0
  38. package/dist/Mermaid.js +121 -0
  39. package/dist/Mermaid.js.map +1 -0
  40. package/dist/Monogram.d.ts +46 -0
  41. package/dist/Monogram.d.ts.map +1 -0
  42. package/dist/Monogram.js +96 -0
  43. package/dist/Monogram.js.map +1 -0
  44. package/dist/OverflowMenu.d.ts +60 -0
  45. package/dist/OverflowMenu.d.ts.map +1 -0
  46. package/dist/OverflowMenu.js +149 -0
  47. package/dist/OverflowMenu.js.map +1 -0
  48. package/dist/Shell.d.ts +67 -0
  49. package/dist/Shell.d.ts.map +1 -0
  50. package/dist/Shell.js +44 -0
  51. package/dist/Shell.js.map +1 -0
  52. package/dist/Skeleton.d.ts +62 -0
  53. package/dist/Skeleton.d.ts.map +1 -0
  54. package/dist/Skeleton.js +56 -0
  55. package/dist/Skeleton.js.map +1 -0
  56. package/dist/Split.d.ts +85 -0
  57. package/dist/Split.d.ts.map +1 -0
  58. package/dist/Split.js +156 -0
  59. package/dist/Split.js.map +1 -0
  60. package/dist/Tabs.d.ts +77 -0
  61. package/dist/Tabs.d.ts.map +1 -0
  62. package/dist/Tabs.js +91 -0
  63. package/dist/Tabs.js.map +1 -0
  64. package/dist/Toast.d.ts +98 -0
  65. package/dist/Toast.d.ts.map +1 -0
  66. package/dist/Toast.js +129 -0
  67. package/dist/Toast.js.map +1 -0
  68. package/dist/Tooltip.d.ts +24 -0
  69. package/dist/Tooltip.d.ts.map +1 -0
  70. package/dist/Tooltip.js +166 -0
  71. package/dist/Tooltip.js.map +1 -0
  72. package/dist/controls.d.ts +117 -0
  73. package/dist/controls.d.ts.map +1 -0
  74. package/dist/controls.js +59 -0
  75. package/dist/controls.js.map +1 -0
  76. package/dist/cx.d.ts +3 -0
  77. package/dist/cx.d.ts.map +1 -0
  78. package/dist/cx.js +5 -0
  79. package/dist/cx.js.map +1 -0
  80. package/dist/fenceInfo.d.ts +26 -0
  81. package/dist/fenceInfo.d.ts.map +1 -0
  82. package/dist/fenceInfo.js +22 -0
  83. package/dist/fenceInfo.js.map +1 -0
  84. package/dist/formControls.d.ts +143 -0
  85. package/dist/formControls.d.ts.map +1 -0
  86. package/dist/formControls.js +108 -0
  87. package/dist/formControls.js.map +1 -0
  88. package/dist/index.d.ts +78 -0
  89. package/dist/index.d.ts.map +1 -0
  90. package/dist/index.js +78 -0
  91. package/dist/index.js.map +1 -0
  92. package/dist/layout.d.ts +95 -0
  93. package/dist/layout.d.ts.map +1 -0
  94. package/dist/layout.js +93 -0
  95. package/dist/layout.js.map +1 -0
  96. package/dist/primitives.d.ts +33 -0
  97. package/dist/primitives.d.ts.map +1 -0
  98. package/dist/primitives.js +33 -0
  99. package/dist/primitives.js.map +1 -0
  100. package/dist/progress.d.ts +64 -0
  101. package/dist/progress.d.ts.map +1 -0
  102. package/dist/progress.js +51 -0
  103. package/dist/progress.js.map +1 -0
  104. package/dist/text.d.ts +63 -0
  105. package/dist/text.d.ts.map +1 -0
  106. package/dist/text.js +61 -0
  107. package/dist/text.js.map +1 -0
  108. package/package.json +56 -4
  109. package/src/CopySource.tsx +67 -0
  110. package/src/DataTable.tsx +120 -0
  111. package/src/Dialog.tsx +158 -0
  112. package/src/ErrorBoundary.tsx +137 -0
  113. package/src/LiveRegion.tsx +127 -0
  114. package/src/Markdown.tsx +75 -0
  115. package/src/MarkdownInline.tsx +177 -0
  116. package/src/MenuIcon.tsx +209 -0
  117. package/src/Mermaid.tsx +144 -0
  118. package/src/Monogram.tsx +112 -0
  119. package/src/OverflowMenu.tsx +359 -0
  120. package/src/Shell.tsx +99 -0
  121. package/src/Skeleton.tsx +98 -0
  122. package/src/Split.tsx +267 -0
  123. package/src/Tabs.tsx +194 -0
  124. package/src/Toast.tsx +269 -0
  125. package/src/Tooltip.tsx +213 -0
  126. package/src/controls.tsx +159 -0
  127. package/src/cx.ts +4 -0
  128. package/src/fenceInfo.ts +36 -0
  129. package/src/formControls.tsx +249 -0
  130. package/src/index.ts +149 -0
  131. package/src/layout.tsx +141 -0
  132. package/src/primitives.tsx +33 -0
  133. package/src/progress.tsx +129 -0
  134. package/src/text.tsx +99 -0
package/src/Toast.tsx ADDED
@@ -0,0 +1,269 @@
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 "./controls.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
+ * @param children — the part of the app that raises toasts.
91
+ */
92
+ export function ToastHost({ children }: { children: ReactNode }) {
93
+ const [toasts, setToasts] = useState<Toast[]>([]);
94
+ const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());
95
+
96
+ const dismiss = useCallback((id: string) => {
97
+ const timer = timers.current.get(id);
98
+ if (timer !== undefined) {
99
+ clearTimeout(timer);
100
+ timers.current.delete(id);
101
+ }
102
+ setToasts((current) => current.filter((t) => t.id !== id));
103
+ }, []);
104
+
105
+ const show = useCallback(
106
+ (message: ReactNode, options: ToastOptions = {}) => {
107
+ const id = `toast-${++counter}`;
108
+ // A toast with something to do stays until it is dealt with.
109
+ // Auto-dismissing it means the button can vanish mid-reach.
110
+ const duration =
111
+ options.duration !== undefined
112
+ ? options.duration
113
+ : options.action !== undefined
114
+ ? null
115
+ : DEFAULT_MS;
116
+
117
+ setToasts((current) =>
118
+ [...current, { ...options, id, message }].slice(-MAX_VISIBLE),
119
+ );
120
+
121
+ if (duration !== null) {
122
+ timers.current.set(
123
+ id,
124
+ setTimeout(() => dismiss(id), duration),
125
+ );
126
+ }
127
+ return id;
128
+ },
129
+ [dismiss],
130
+ );
131
+
132
+ const clear = useCallback(() => {
133
+ for (const timer of timers.current.values()) clearTimeout(timer);
134
+ timers.current.clear();
135
+ setToasts([]);
136
+ }, []);
137
+
138
+ // Timers outlive the component otherwise, and fire `setToasts` on
139
+ // something unmounted.
140
+ useEffect(() => {
141
+ const pending = timers.current;
142
+ return () => {
143
+ for (const timer of pending.values()) clearTimeout(timer);
144
+ pending.clear();
145
+ };
146
+ }, []);
147
+
148
+ const api = useMemo<ToastApi>(
149
+ () => ({ show, dismiss, clear }),
150
+ [show, dismiss, clear],
151
+ );
152
+
153
+ return (
154
+ <ToastContext.Provider value={api}>
155
+ {children}
156
+ <ToastList toasts={toasts} onDismiss={dismiss} />
157
+ </ToastContext.Provider>
158
+ );
159
+ }
160
+
161
+ function ToastList({
162
+ toasts,
163
+ onDismiss,
164
+ }: {
165
+ toasts: Toast[];
166
+ onDismiss: (id: string) => void;
167
+ }) {
168
+ return (
169
+ <div className="ui-toasts">
170
+ {toasts.map((toast) => (
171
+ <div
172
+ key={toast.id}
173
+ className="ui-toast"
174
+ data-tone={toast.tone ?? "neutral"}
175
+ // A failure interrupts; everything else waits for a pause.
176
+ role={toast.tone === "danger" ? "alert" : "status"}
177
+ aria-live={toast.tone === "danger" ? "assertive" : "polite"}
178
+ >
179
+ <div className="ui-toast-body">
180
+ {toast.message}
181
+ {toast.action}
182
+ </div>
183
+ <button
184
+ type="button"
185
+ className="ui-toast-dismiss"
186
+ // Named, because "×" is announced as "times" or as
187
+ // nothing, and a stack of them is unnavigable.
188
+ aria-label="Dismiss notification"
189
+ onClick={() => onDismiss(toast.id)}
190
+ >
191
+ ×
192
+ </button>
193
+ </div>
194
+ ))}
195
+ </div>
196
+ );
197
+ }
198
+
199
+ /**
200
+ * Raise a toast.
201
+ *
202
+ * Throws outside a {@link ToastHost} rather than returning a no-op.
203
+ * A silent no-op here means a save that reports success by showing
204
+ * nothing, which looks exactly like a save that did not happen.
205
+ */
206
+ export function useToast(): ToastApi {
207
+ const api = useContext(ToastContext);
208
+ if (api === null) {
209
+ throw new Error(
210
+ "useToast was called outside a <ToastHost>. Wrap your app in one — " +
211
+ "without it a toast would be silently dropped, which looks the " +
212
+ "same as the action never happening.",
213
+ );
214
+ }
215
+ return api;
216
+ }
217
+
218
+ /** What a {@link Banner} takes. */
219
+ export interface BannerProps extends HTMLAttributes<HTMLDivElement> {
220
+ /** How loud it is. */
221
+ tone?: Tone;
222
+ /** A dismiss affordance appears when this is given. */
223
+ onDismiss?: () => void;
224
+ }
225
+
226
+ /**
227
+ * A condition that is still true.
228
+ *
229
+ * Not a toast: a toast is about something that just happened and
230
+ * goes away, a banner is about a state — offline, read-only, licence
231
+ * expiring — and stays until the state does not.
232
+ *
233
+ * @param tone — how loud it is: `neutral` for a state nothing is wrong
234
+ * with, and the three that mean something.
235
+ * @param onDismiss — asked to dismiss the banner; the affordance
236
+ * appears when this is given.
237
+ * @param children — the message the banner says.
238
+ * @param className — added to the element's classes, beside the one the
239
+ * theme gives it.
240
+ * @param rest — the remaining props, spread onto the element.
241
+ */
242
+ export function Banner({
243
+ tone = "neutral",
244
+ onDismiss,
245
+ children,
246
+ className,
247
+ ...rest
248
+ }: BannerProps) {
249
+ return (
250
+ <div
251
+ {...rest}
252
+ className={cx("ui-banner", className)}
253
+ data-tone={tone}
254
+ role={tone === "danger" ? "alert" : "status"}
255
+ >
256
+ <div className="ui-banner-body">{children}</div>
257
+ {onDismiss === undefined ? null : (
258
+ <button
259
+ type="button"
260
+ className="ui-toast-dismiss"
261
+ aria-label="Dismiss message"
262
+ onClick={onDismiss}
263
+ >
264
+ ×
265
+ </button>
266
+ )}
267
+ </div>
268
+ );
269
+ }
@@ -0,0 +1,213 @@
1
+ /**
2
+ * What an icon means, on hover and on focus.
3
+ *
4
+ * A toolbar of glyphs is quicker to scan and slower to learn, and
5
+ * the moment somebody needs the word is the moment their pointer is
6
+ * already on the thing. The browser's own ``title`` does technically
7
+ * say it — after a second and a half, in the operating system's
8
+ * font, at the pointer rather than at the control, and never for
9
+ * somebody on a keyboard. That is not an explanation, it is a
10
+ * consolation prize.
11
+ *
12
+ * **It replaces ``title``, it does not sit beside it.** A ``title`` left
13
+ * on the control would give two tooltips saying the same thing a second
14
+ * apart, so the Tooltip takes it off the control while it is in charge,
15
+ * and says it itself when it was given no ``text``.
16
+ *
17
+ * **Focus shows it immediately; hover waits.** A pointer crossing a
18
+ * row of buttons on its way somewhere else should not leave a trail
19
+ * of popups, but a keyboard user arriving at a control has asked for
20
+ * it by arriving.
21
+ */
22
+ import { useCallback, useEffect, useId, useRef, useState } from "react";
23
+ import { createPortal } from "react-dom";
24
+
25
+ /** How long a pointer must rest before the word appears. */
26
+ const DWELL_MS = 350;
27
+
28
+ /** Gap between the control and the bubble. */
29
+ const OFFSET = 8;
30
+
31
+ /** Keeps the bubble off the window edges. */
32
+ const MARGIN = 8;
33
+
34
+ interface At {
35
+ left: number;
36
+ top: number;
37
+ /** Below the control, or above it when there is no room below. */
38
+ below: boolean;
39
+ }
40
+
41
+ /** What a {@link Tooltip} takes. */
42
+ export interface TooltipProps {
43
+ /**
44
+ * The word. When it is empty, the control's own `title` is used
45
+ * instead; nothing is rendered when there is neither.
46
+ */
47
+ text: string;
48
+ /** The control the word is about. */
49
+ children: React.ReactNode;
50
+ }
51
+
52
+ /**
53
+ * What an icon means, on hover and on focus.
54
+ *
55
+ * It replaces the browser's own `title` rather than sitting beside it:
56
+ * a `title` on the control is removed from it, so the browser never
57
+ * shows a second tooltip, and is the word when `text` is empty. Focus
58
+ * shows it at once; hover waits 350 ms.
59
+ *
60
+ * @param text — the word; when it is empty the control's `title` is
61
+ * used, and nothing is rendered when there is neither.
62
+ * @param children — the control the word is about.
63
+ */
64
+ export function Tooltip({ text, children }: TooltipProps) {
65
+ const [fromTitle, setFromTitle] = useState("");
66
+ const label = text || fromTitle;
67
+ const wrap = useRef<HTMLSpanElement>(null);
68
+ const bubble = useRef<HTMLDivElement>(null);
69
+ const timer = useRef<number | null>(null);
70
+ const [at, setAt] = useState<At | null>(null);
71
+ const id = useId();
72
+
73
+ // The control's own ``title`` is taken off it, and kept as the word
74
+ // for when none was given. Run after every render, because React
75
+ // writes the attribute back whenever the control's ``title`` prop
76
+ // changes.
77
+ useEffect(() => {
78
+ const control = wrap.current?.firstElementChild;
79
+ const title = control?.getAttribute("title");
80
+ if (title === null || title === undefined) return;
81
+ control?.removeAttribute("title");
82
+ setFromTitle(title);
83
+ });
84
+
85
+ const hide = useCallback(() => {
86
+ if (timer.current !== null) window.clearTimeout(timer.current);
87
+ timer.current = null;
88
+ setAt(null);
89
+ }, []);
90
+
91
+ const place = useCallback(() => {
92
+ // The control, not the pointer. A bubble that follows the cursor
93
+ // is a bubble that covers the next control along.
94
+ const anchor = wrap.current?.firstElementChild ?? wrap.current;
95
+ const box = anchor?.getBoundingClientRect();
96
+ if (!box) return;
97
+ const below = box.bottom + OFFSET + 34 < window.innerHeight;
98
+ setAt({
99
+ left: box.left + box.width / 2,
100
+ top: below ? box.bottom + OFFSET : box.top - OFFSET,
101
+ below,
102
+ });
103
+ }, []);
104
+
105
+ const show = useCallback(
106
+ (immediately: boolean) => {
107
+ if (!label) return;
108
+ if (timer.current !== null) window.clearTimeout(timer.current);
109
+ if (immediately) {
110
+ place();
111
+ return;
112
+ }
113
+ timer.current = window.setTimeout(place, DWELL_MS);
114
+ },
115
+ [label, place],
116
+ );
117
+
118
+ useEffect(
119
+ () => () => {
120
+ if (timer.current !== null) window.clearTimeout(timer.current);
121
+ },
122
+ [],
123
+ );
124
+
125
+ // Escape closes it, and so does anything that scrolls it away from
126
+ // the control it belongs to.
127
+ useEffect(() => {
128
+ if (!at) return;
129
+ const onKey = (e: KeyboardEvent) => {
130
+ if (e.key === "Escape") hide();
131
+ };
132
+ window.addEventListener("keydown", onKey);
133
+ window.addEventListener("scroll", hide, true);
134
+ window.addEventListener("resize", hide);
135
+ return () => {
136
+ window.removeEventListener("keydown", onKey);
137
+ window.removeEventListener("scroll", hide, true);
138
+ window.removeEventListener("resize", hide);
139
+ };
140
+ }, [at, hide]);
141
+
142
+ // Nudged back inside the window once its width is known. Measured
143
+ // rather than guessed: the text is a sentence in some places and a
144
+ // word in others.
145
+ useEffect(() => {
146
+ const el = bubble.current;
147
+ if (!at || !el) return;
148
+ const box = el.getBoundingClientRect();
149
+ const over = box.right - (window.innerWidth - MARGIN);
150
+ const under = MARGIN - box.left;
151
+ if (over > 0)
152
+ el.style.transform = `translate(calc(-50% - ${over}px), ${at.below ? "0" : "-100%"})`;
153
+ else if (under > 0)
154
+ el.style.transform = `translate(calc(-50% + ${under}px), ${at.below ? "0" : "-100%"})`;
155
+ }, [at]);
156
+
157
+ // Listened for on the control itself, not on the wrapper.
158
+ //
159
+ // The wrapper is ``display: contents`` so it does not become a box
160
+ // in a flex row — every toolbar it is used in would otherwise gain
161
+ // a layer of spacing nobody designed. But an element with no box
162
+ // is an element the browser never hits with a pointer, so React's
163
+ // onPointerEnter on the wrapper fired in jsdom, where there is no
164
+ // hit-testing, and never once in a real browser. Focus worked the
165
+ // whole time, which is what made it look like a timing problem.
166
+ useEffect(() => {
167
+ const control = wrap.current?.firstElementChild;
168
+ if (!control) return;
169
+ const enter = () => show(false);
170
+ const now = () => show(true);
171
+ control.addEventListener("pointerenter", enter);
172
+ control.addEventListener("pointerleave", hide);
173
+ control.addEventListener("pointerdown", hide);
174
+ control.addEventListener("focus", now);
175
+ control.addEventListener("blur", hide);
176
+ return () => {
177
+ control.removeEventListener("pointerenter", enter);
178
+ control.removeEventListener("pointerleave", hide);
179
+ control.removeEventListener("pointerdown", hide);
180
+ control.removeEventListener("focus", now);
181
+ control.removeEventListener("blur", hide);
182
+ };
183
+ }, [show, hide]);
184
+
185
+ return (
186
+ <>
187
+ <span
188
+ ref={wrap}
189
+ className="tip-anchor"
190
+ aria-describedby={at ? id : undefined}
191
+ >
192
+ {children}
193
+ </span>
194
+ {at &&
195
+ createPortal(
196
+ <div
197
+ ref={bubble}
198
+ id={id}
199
+ role="tooltip"
200
+ className="tip"
201
+ style={{
202
+ left: at.left,
203
+ top: at.top,
204
+ transform: `translate(-50%, ${at.below ? "0" : "-100%"})`,
205
+ }}
206
+ >
207
+ {label}
208
+ </div>,
209
+ document.body,
210
+ )}
211
+ </>
212
+ );
213
+ }
@@ -0,0 +1,159 @@
1
+ /**
2
+ * The controls a reader acts on or scans past: a button, a text field,
3
+ * a chip and a badge, and the tone the last two share.
4
+ *
5
+ * Part of the primitives; see `primitives.tsx`. **Under the
6
+ * compatibility floor.**
7
+ */
8
+
9
+ import type {
10
+ ButtonHTMLAttributes,
11
+ HTMLAttributes,
12
+ InputHTMLAttributes,
13
+ } from "react";
14
+
15
+ import { cx } from "./cx.js";
16
+
17
+ /**
18
+ * How a button reads.
19
+ *
20
+ * `default` is a plain button, `primary` is the one action on the
21
+ * panel, `danger` is the one that destroys something, `warn` says the
22
+ * action is not what it sounds like, and `quiet` is a button that
23
+ * should not be the first thing the eye lands on.
24
+ */
25
+ export type ButtonVariant = "default" | "primary" | "danger" | "warn" | "quiet";
26
+
27
+ /** `md` unless the row is dense, in which case `sm` or `xs`. */
28
+ export type ButtonSize = "md" | "sm" | "xs";
29
+
30
+ /** What a {@link Button} takes. */
31
+ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
32
+ /** How it reads. */
33
+ variant?: ButtonVariant;
34
+ /** Its size. */
35
+ size?: ButtonSize;
36
+ }
37
+
38
+ /**
39
+ * A button.
40
+ *
41
+ * The variant is a prop rather than a class name you spell:
42
+ * `btn-primery` is a typo that renders as a plain button and looks
43
+ * like nothing at all, which is exactly why the name is one the
44
+ * compiler checks.
45
+ *
46
+ * @param variant — how it reads: plain, the one action on the panel,
47
+ * the one that destroys something, a warning, or one that should not
48
+ * be the first thing the eye lands on.
49
+ * @param size — its size: `md` unless the row is dense, in which case
50
+ * `sm` or `xs`.
51
+ * @param className — added to the element's classes, beside the one the
52
+ * theme gives it.
53
+ * @param rest — the remaining props, spread onto the button.
54
+ */
55
+ export function Button({
56
+ variant = "default",
57
+ size = "md",
58
+ className,
59
+ ...rest
60
+ }: ButtonProps) {
61
+ return (
62
+ <button
63
+ type="button"
64
+ {...rest}
65
+ className={cx(
66
+ "btn",
67
+ variant !== "default" && `btn-${variant}`,
68
+ size !== "md" && `btn-${size}`,
69
+ className,
70
+ )}
71
+ />
72
+ );
73
+ }
74
+
75
+ /** What an {@link Input} takes. */
76
+ export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {}
77
+
78
+ /**
79
+ * A single-line text field.
80
+ *
81
+ * @param className — added to the element's classes, beside the one the
82
+ * theme gives it.
83
+ * @param rest — the remaining props, spread onto the input.
84
+ */
85
+ export function Input({ className, ...rest }: InputProps) {
86
+ return <input {...rest} className={cx("panel-input", className)} />;
87
+ }
88
+
89
+ /**
90
+ * How loud a status is.
91
+ *
92
+ * `neutral` for a state nothing is wrong with, and the three that
93
+ * mean something.
94
+ */
95
+ export type Tone = "neutral" | "success" | "warning" | "danger";
96
+
97
+ /**
98
+ * A tag the reader can scan past.
99
+ *
100
+ * Bordered, pill-shaped, muted, `--text-sm`. Use it for a filter, a
101
+ * label, a piece of metadata — something that describes the row it
102
+ * sits on.
103
+ *
104
+ * `Chip` and `Badge` take the same props and are not
105
+ * interchangeable. If the thing you are showing is a *state* that
106
+ * changes — ready, failed, three unread — it is a {@link Badge},
107
+ * which is filled by tone and bold so it is noticed. If it is a fact
108
+ * about the thing, it is a `Chip`.
109
+ */
110
+ export interface ChipProps extends HTMLAttributes<HTMLSpanElement> {
111
+ /** How loud it is. */
112
+ tone?: Tone;
113
+ }
114
+
115
+ /**
116
+ * A tag the reader can scan past. See {@link ChipProps} for when to
117
+ * reach for a chip and when for a badge.
118
+ *
119
+ * @param tone — how loud it is: `neutral` for a state nothing is wrong
120
+ * with, and the three that mean something.
121
+ * @param className — added to the element's classes, beside the one the
122
+ * theme gives it.
123
+ * @param rest — the remaining props, spread onto the span.
124
+ */
125
+ export function Chip({ tone = "neutral", className, ...rest }: ChipProps) {
126
+ return <span {...rest} data-tone={tone} className={cx("chip", className)} />;
127
+ }
128
+
129
+ /**
130
+ * A state the reader is meant to notice.
131
+ *
132
+ * Filled by tone, bold, `--text-xs`, no border. See {@link ChipProps}
133
+ * for which of the two to reach for.
134
+ *
135
+ * The tone is colour, and colour alone is not a message: put the
136
+ * state in the text too. "Failed" in a danger badge survives being
137
+ * read aloud and being looked at by somebody who cannot tell it from
138
+ * the success one; an empty red badge does not.
139
+ */
140
+ export interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
141
+ /** How loud it is. */
142
+ tone?: Tone;
143
+ }
144
+
145
+ /**
146
+ * A state the reader is meant to notice. See {@link BadgeProps} for
147
+ * what the tone does and does not say.
148
+ *
149
+ * @param tone — how loud it is: `neutral` for a state nothing is wrong
150
+ * with, and the three that mean something.
151
+ * @param className — added to the element's classes, beside the one the
152
+ * theme gives it.
153
+ * @param rest — the remaining props, spread onto the span.
154
+ */
155
+ export function Badge({ tone = "neutral", className, ...rest }: BadgeProps) {
156
+ return (
157
+ <span {...rest} data-tone={tone} className={cx("ui-badge", className)} />
158
+ );
159
+ }
package/src/cx.ts ADDED
@@ -0,0 +1,4 @@
1
+ /** Joins the class names that are set, skipping the ones that are not. */
2
+ export function cx(...parts: (string | false | null | undefined)[]): string {
3
+ return parts.filter(Boolean).join(" ");
4
+ }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The language on a fenced block, or null.
3
+ *
4
+ * ReactMarkdown hands a ``<pre>`` a single ``<code>`` child carrying
5
+ * ``className="language-mermaid"``; this reads that without
6
+ * assuming any particular child shape survives a plugin.
7
+ */
8
+ import type { ReactNode } from "react";
9
+ import { isValidElement } from "react";
10
+
11
+ /** The language on a fenced block, and the block's source. */
12
+ export interface Fence {
13
+ /** The language, lower-cased. `mermaid`, `ts`, `python`, `c++`. */
14
+ lang: string;
15
+ /** The text inside the fence. */
16
+ source: string;
17
+ }
18
+
19
+ /**
20
+ * The language on a fenced block, or null.
21
+ *
22
+ * Null when the child is not a code element, or carries no
23
+ * `language-` class — an unfenced block, or a fence with no language.
24
+ *
25
+ * @param children — the `<pre>` a fenced block renders as; its `<code>`
26
+ * child carries the language class.
27
+ */
28
+ export function fenceInfo(children: ReactNode): Fence | null {
29
+ const only = Array.isArray(children) ? children[0] : children;
30
+ if (!isValidElement(only)) return null;
31
+ const props = only.props as { className?: string; children?: ReactNode };
32
+ const match = /\blanguage-([\w+#.-]+)/.exec(props.className ?? "");
33
+ if (!match) return null;
34
+ const source = typeof props.children === "string" ? props.children : "";
35
+ return { lang: match[1].toLowerCase(), source: source.replace(/\n$/, "") };
36
+ }