@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.
Files changed (99) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +5 -0
  3. package/README.md +217 -2
  4. package/dist/CopySource.d.ts +4 -0
  5. package/dist/CopySource.d.ts.map +1 -0
  6. package/dist/CopySource.js +36 -0
  7. package/dist/CopySource.js.map +1 -0
  8. package/dist/DataTable.d.ts +61 -0
  9. package/dist/DataTable.d.ts.map +1 -0
  10. package/dist/DataTable.js +29 -0
  11. package/dist/DataTable.js.map +1 -0
  12. package/dist/ErrorBoundary.d.ts +68 -0
  13. package/dist/ErrorBoundary.d.ts.map +1 -0
  14. package/dist/ErrorBoundary.js +63 -0
  15. package/dist/ErrorBoundary.js.map +1 -0
  16. package/dist/LiveRegion.d.ts +35 -0
  17. package/dist/LiveRegion.d.ts.map +1 -0
  18. package/dist/LiveRegion.js +70 -0
  19. package/dist/LiveRegion.js.map +1 -0
  20. package/dist/Markdown.d.ts +18 -0
  21. package/dist/Markdown.d.ts.map +1 -0
  22. package/dist/Markdown.js +52 -0
  23. package/dist/Markdown.js.map +1 -0
  24. package/dist/MarkdownInline.d.ts +44 -0
  25. package/dist/MarkdownInline.d.ts.map +1 -0
  26. package/dist/MarkdownInline.js +144 -0
  27. package/dist/MarkdownInline.js.map +1 -0
  28. package/dist/MenuIcon.d.ts +54 -0
  29. package/dist/MenuIcon.d.ts.map +1 -0
  30. package/dist/MenuIcon.js +96 -0
  31. package/dist/MenuIcon.js.map +1 -0
  32. package/dist/Mermaid.d.ts +38 -0
  33. package/dist/Mermaid.d.ts.map +1 -0
  34. package/dist/Mermaid.js +119 -0
  35. package/dist/Mermaid.js.map +1 -0
  36. package/dist/Monogram.d.ts +42 -0
  37. package/dist/Monogram.d.ts.map +1 -0
  38. package/dist/Monogram.js +88 -0
  39. package/dist/Monogram.js.map +1 -0
  40. package/dist/OverflowMenu.d.ts +55 -0
  41. package/dist/OverflowMenu.d.ts.map +1 -0
  42. package/dist/OverflowMenu.js +141 -0
  43. package/dist/OverflowMenu.js.map +1 -0
  44. package/dist/Shell.d.ts +54 -0
  45. package/dist/Shell.d.ts.map +1 -0
  46. package/dist/Shell.js +31 -0
  47. package/dist/Shell.js.map +1 -0
  48. package/dist/Skeleton.d.ts +32 -0
  49. package/dist/Skeleton.d.ts.map +1 -0
  50. package/dist/Skeleton.js +26 -0
  51. package/dist/Skeleton.js.map +1 -0
  52. package/dist/Split.d.ts +66 -0
  53. package/dist/Split.d.ts.map +1 -0
  54. package/dist/Split.js +133 -0
  55. package/dist/Split.js.map +1 -0
  56. package/dist/Toast.d.ts +87 -0
  57. package/dist/Toast.d.ts.map +1 -0
  58. package/dist/Toast.js +118 -0
  59. package/dist/Toast.js.map +1 -0
  60. package/dist/Tooltip.d.ts +15 -0
  61. package/dist/Tooltip.d.ts.map +1 -0
  62. package/dist/Tooltip.js +144 -0
  63. package/dist/Tooltip.js.map +1 -0
  64. package/dist/cx.d.ts +3 -0
  65. package/dist/cx.d.ts.map +1 -0
  66. package/dist/cx.js +5 -0
  67. package/dist/cx.js.map +1 -0
  68. package/dist/fenceInfo.d.ts +23 -0
  69. package/dist/fenceInfo.d.ts.map +1 -0
  70. package/dist/fenceInfo.js +19 -0
  71. package/dist/fenceInfo.js.map +1 -0
  72. package/dist/index.d.ts +82 -0
  73. package/dist/index.d.ts.map +1 -0
  74. package/dist/index.js +82 -0
  75. package/dist/index.js.map +1 -0
  76. package/dist/primitives.d.ts +383 -0
  77. package/dist/primitives.d.ts.map +1 -0
  78. package/dist/primitives.js +340 -0
  79. package/dist/primitives.js.map +1 -0
  80. package/package.json +56 -4
  81. package/src/CopySource.tsx +52 -0
  82. package/src/DataTable.tsx +104 -0
  83. package/src/ErrorBoundary.tsx +102 -0
  84. package/src/LiveRegion.tsx +121 -0
  85. package/src/Markdown.tsx +71 -0
  86. package/src/MarkdownInline.tsx +164 -0
  87. package/src/MenuIcon.tsx +203 -0
  88. package/src/Mermaid.tsx +142 -0
  89. package/src/Monogram.tsx +103 -0
  90. package/src/OverflowMenu.tsx +352 -0
  91. package/src/Shell.tsx +86 -0
  92. package/src/Skeleton.tsx +68 -0
  93. package/src/Split.tsx +242 -0
  94. package/src/Toast.tsx +258 -0
  95. package/src/Tooltip.tsx +188 -0
  96. package/src/cx.ts +4 -0
  97. package/src/fenceInfo.ts +33 -0
  98. package/src/index.ts +153 -0
  99. package/src/primitives.tsx +887 -0
@@ -0,0 +1,188 @@
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.** Leaving both
13
+ * on gives two tooltips saying the same thing a second apart.
14
+ *
15
+ * **Focus shows it immediately; hover waits.** A pointer crossing a
16
+ * row of buttons on its way somewhere else should not leave a trail
17
+ * of popups, but a keyboard user arriving at a control has asked for
18
+ * it by arriving.
19
+ */
20
+ import { useCallback, useEffect, useId, useRef, useState } from "react";
21
+ import { createPortal } from "react-dom";
22
+
23
+ /** How long a pointer must rest before the word appears. */
24
+ const DWELL_MS = 350;
25
+
26
+ /** Gap between the control and the bubble. */
27
+ const OFFSET = 8;
28
+
29
+ /** Keeps the bubble off the window edges. */
30
+ const MARGIN = 8;
31
+
32
+ interface At {
33
+ left: number;
34
+ top: number;
35
+ /** Below the control, or above it when there is no room below. */
36
+ below: boolean;
37
+ }
38
+
39
+ /** What a {@link Tooltip} takes. */
40
+ export interface TooltipProps {
41
+ /** The word. Nothing is rendered when it is empty. */
42
+ text: string;
43
+ /** The control the word is about. */
44
+ children: React.ReactNode;
45
+ }
46
+
47
+ /**
48
+ * What an icon means, on hover and on focus.
49
+ *
50
+ * See the note at the top of this file. It replaces the browser's own
51
+ * `title` rather than sitting beside it.
52
+ */
53
+ export function Tooltip({ text, children }: TooltipProps) {
54
+ const wrap = useRef<HTMLSpanElement>(null);
55
+ const bubble = useRef<HTMLDivElement>(null);
56
+ const timer = useRef<number | null>(null);
57
+ const [at, setAt] = useState<At | null>(null);
58
+ const id = useId();
59
+
60
+ const hide = useCallback(() => {
61
+ if (timer.current !== null) window.clearTimeout(timer.current);
62
+ timer.current = null;
63
+ setAt(null);
64
+ }, []);
65
+
66
+ const place = useCallback(() => {
67
+ // The control, not the pointer. A bubble that follows the cursor
68
+ // is a bubble that covers the next control along.
69
+ const anchor = wrap.current?.firstElementChild ?? wrap.current;
70
+ const box = anchor?.getBoundingClientRect();
71
+ if (!box) return;
72
+ const below = box.bottom + OFFSET + 34 < window.innerHeight;
73
+ setAt({
74
+ left: box.left + box.width / 2,
75
+ top: below ? box.bottom + OFFSET : box.top - OFFSET,
76
+ below,
77
+ });
78
+ }, []);
79
+
80
+ const show = useCallback(
81
+ (immediately: boolean) => {
82
+ if (!text) return;
83
+ if (timer.current !== null) window.clearTimeout(timer.current);
84
+ if (immediately) {
85
+ place();
86
+ return;
87
+ }
88
+ timer.current = window.setTimeout(place, DWELL_MS);
89
+ },
90
+ [text, place],
91
+ );
92
+
93
+ useEffect(
94
+ () => () => {
95
+ if (timer.current !== null) window.clearTimeout(timer.current);
96
+ },
97
+ [],
98
+ );
99
+
100
+ // Escape closes it, and so does anything that scrolls it away from
101
+ // the control it belongs to.
102
+ useEffect(() => {
103
+ if (!at) return;
104
+ const onKey = (e: KeyboardEvent) => {
105
+ if (e.key === "Escape") hide();
106
+ };
107
+ window.addEventListener("keydown", onKey);
108
+ window.addEventListener("scroll", hide, true);
109
+ window.addEventListener("resize", hide);
110
+ return () => {
111
+ window.removeEventListener("keydown", onKey);
112
+ window.removeEventListener("scroll", hide, true);
113
+ window.removeEventListener("resize", hide);
114
+ };
115
+ }, [at, hide]);
116
+
117
+ // Nudged back inside the window once its width is known. Measured
118
+ // rather than guessed: the text is a sentence in some places and a
119
+ // word in others.
120
+ useEffect(() => {
121
+ const el = bubble.current;
122
+ if (!at || !el) return;
123
+ const box = el.getBoundingClientRect();
124
+ const over = box.right - (window.innerWidth - MARGIN);
125
+ const under = MARGIN - box.left;
126
+ if (over > 0)
127
+ el.style.transform = `translate(calc(-50% - ${over}px), ${at.below ? "0" : "-100%"})`;
128
+ else if (under > 0)
129
+ el.style.transform = `translate(calc(-50% + ${under}px), ${at.below ? "0" : "-100%"})`;
130
+ }, [at]);
131
+
132
+ // Listened for on the control itself, not on the wrapper.
133
+ //
134
+ // The wrapper is ``display: contents`` so it does not become a box
135
+ // in a flex row — every toolbar it is used in would otherwise gain
136
+ // a layer of spacing nobody designed. But an element with no box
137
+ // is an element the browser never hits with a pointer, so React's
138
+ // onPointerEnter on the wrapper fired in jsdom, where there is no
139
+ // hit-testing, and never once in a real browser. Focus worked the
140
+ // whole time, which is what made it look like a timing problem.
141
+ useEffect(() => {
142
+ const control = wrap.current?.firstElementChild;
143
+ if (!control) return;
144
+ const enter = () => show(false);
145
+ const now = () => show(true);
146
+ control.addEventListener("pointerenter", enter);
147
+ control.addEventListener("pointerleave", hide);
148
+ control.addEventListener("pointerdown", hide);
149
+ control.addEventListener("focus", now);
150
+ control.addEventListener("blur", hide);
151
+ return () => {
152
+ control.removeEventListener("pointerenter", enter);
153
+ control.removeEventListener("pointerleave", hide);
154
+ control.removeEventListener("pointerdown", hide);
155
+ control.removeEventListener("focus", now);
156
+ control.removeEventListener("blur", hide);
157
+ };
158
+ }, [show, hide]);
159
+
160
+ return (
161
+ <>
162
+ <span
163
+ ref={wrap}
164
+ className="tip-anchor"
165
+ aria-describedby={at ? id : undefined}
166
+ >
167
+ {children}
168
+ </span>
169
+ {at &&
170
+ createPortal(
171
+ <div
172
+ ref={bubble}
173
+ id={id}
174
+ role="tooltip"
175
+ className="tip"
176
+ style={{
177
+ left: at.left,
178
+ top: at.top,
179
+ transform: `translate(-50%, ${at.below ? "0" : "-100%"})`,
180
+ }}
181
+ >
182
+ {text}
183
+ </div>,
184
+ document.body,
185
+ )}
186
+ </>
187
+ );
188
+ }
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,33 @@
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`. */
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
+ export function fenceInfo(children: ReactNode): Fence | null {
26
+ const only = Array.isArray(children) ? children[0] : children;
27
+ if (!isValidElement(only)) return null;
28
+ const props = only.props as { className?: string; children?: ReactNode };
29
+ const match = /\blanguage-([\w-]+)\b/.exec(props.className ?? "");
30
+ if (!match) return null;
31
+ const source = typeof props.children === "string" ? props.children : "";
32
+ return { lang: match[1].toLowerCase(), source: source.replace(/\n$/, "") };
33
+ }
package/src/index.ts ADDED
@@ -0,0 +1,153 @@
1
+ /**
2
+ * @ignite-ember/ui-react — the components an extension is allowed to build on.
3
+ *
4
+ * This list is not a guess at what an extension might want. It is
5
+ * what the first two extensions actually import. CodeIndex needs
6
+ * none of it — its only app dependency is the client type, which is
7
+ * why porting its panel behind the bridge cost one line. Artifacts
8
+ * is 7,737 lines and imports exactly seven of the app's components,
9
+ * measured rather than estimated.
10
+ *
11
+ * Seven was never the whole floor, though. Artifacts also writes
12
+ * `className="btn btn-primary"` by hand, and so would every
13
+ * extension — the primitives existed as CSS and not as an API, which
14
+ * is no autocomplete, no way to learn a variant name short of
15
+ * reading `theme.css`, and nothing to stop `btn-primery` shipping as
16
+ * an invisible bug. `./primitives` closes that: thin typed wrappers
17
+ * over classes the app already uses.
18
+ *
19
+ * They are React, not web components, because six of the seven are
20
+ * worse as web components: `MarkdownInline` and `RichFences` are a
21
+ * react-markdown pipeline with remark and rehype plugins, and
22
+ * `Tooltip` and `OverflowMenu` are positioning behaviour that wants
23
+ * the light DOM. Rewriting those inside a shadow root would mean
24
+ * maintaining a second implementation of something the app already
25
+ * has — the drift this repository has been bitten by twice.
26
+ *
27
+ * An extension runs in its own frame and bundles its own React, so
28
+ * consuming a React package costs it nothing it was not already
29
+ * paying.
30
+ *
31
+ * **Everything exported here is under the compatibility floor.**
32
+ * Removing one, renaming it, or changing a prop's meaning is a
33
+ * breaking change under EXTENSIBILITY.md §8. Anything in the app
34
+ * that is not exported here stays ours to change — which is why this
35
+ * file is short and should be argued over before it grows.
36
+ *
37
+ * ## The two rules an export has to pass
38
+ *
39
+ * **It must render outside this repository.** A component whose CSS
40
+ * lives only in ``theme.css`` is unstyled in the one place it is
41
+ * promised for, because an extension runs on its own origin under
42
+ * ``default-src 'self'`` and cannot link ours. ``styled.test.ts``
43
+ * checks every class named here against ``clients/ui/igni-ui.css``
44
+ * and fails on the first one that is missing. This was not a
45
+ * hypothetical: seven components shipped under the floor naming
46
+ * thirty-two classes that no published stylesheet defined, and the
47
+ * reference extension did not catch it because it happens to import
48
+ * only from ``primitives``, which is the half that was covered.
49
+ *
50
+ * **It must not drag the app behind it.** ``boundary.test.ts``
51
+ * fails on an import — static or dynamic — that leaves this
52
+ * directory for anywhere but ``react`` and the published
53
+ * dependencies. ``SpecBlock`` left the floor for this reason: it
54
+ * loaded ``../components/JsonRenderView``, a path that does not
55
+ * exist in a published package, through a dynamic import that no
56
+ * compiler would flag. ``visualizationStream`` left for the same
57
+ * reason — it types its return as the app's ``ChatItem``, which
58
+ * would have put the chat model under the floor by transitivity.
59
+ *
60
+ * Helpers that only their own tests imported — ``closeOpenMarks``,
61
+ * ``dropEchoedTitle``, ``hexOf``, ``hueOf``, ``initialsOf`` — are
62
+ * gone from here too. They were exported to be tested, and tests in
63
+ * this repository can import them from their own module. Putting
64
+ * them here promised them to extensions for two releases.
65
+ */
66
+
67
+ export {
68
+ Actions,
69
+ Badge,
70
+ Button,
71
+ type ButtonProps,
72
+ type ButtonSize,
73
+ type ButtonVariant,
74
+ type BadgeProps,
75
+ Card,
76
+ Chip,
77
+ type ChipProps,
78
+ Dialog,
79
+ type DialogProps,
80
+ Empty,
81
+ type EmptyProps,
82
+ Input,
83
+ type InputProps,
84
+ Item,
85
+ List,
86
+ Row,
87
+ Checkbox,
88
+ type CheckboxProps,
89
+ Code,
90
+ Divider,
91
+ Field,
92
+ type FieldProps,
93
+ Heading,
94
+ type HeadingProps,
95
+ Progress,
96
+ type ProgressProps,
97
+ Radio,
98
+ type RadioProps,
99
+ Select,
100
+ type SelectProps,
101
+ Spinner,
102
+ type SpinnerProps,
103
+ Switch,
104
+ type SwitchProps,
105
+ Table,
106
+ TabPanel,
107
+ type TabPanelProps,
108
+ Tabs,
109
+ type TabsProps,
110
+ Text,
111
+ type TextProps,
112
+ type TextTone,
113
+ Textarea,
114
+ type TextareaProps,
115
+ type Tone,
116
+ Toolbar,
117
+ } from "./primitives.js";
118
+
119
+ export { AppShell, type AppShellProps, Scroll, type ScrollProps } from "./Shell.js";
120
+ export {
121
+ SortableTh,
122
+ type SortableThProps,
123
+ type SortDirection,
124
+ Status,
125
+ type StatusProps,
126
+ } from "./DataTable.js";
127
+ export { ErrorBoundary, type ErrorBoundaryProps } from "./ErrorBoundary.js";
128
+ export {
129
+ Banner,
130
+ type BannerProps,
131
+ type Toast,
132
+ type ToastApi,
133
+ ToastHost,
134
+ type ToastOptions,
135
+ useToast,
136
+ } from "./Toast.js";
137
+ export {
138
+ type Announcer,
139
+ LiveRegion,
140
+ type LiveRegionProps,
141
+ useAnnounce,
142
+ type Urgency,
143
+ } from "./LiveRegion.js";
144
+ export { Markdown, type MarkdownProps } from "./Markdown.js";
145
+ export { MarkdownInline } from "./MarkdownInline.js";
146
+ export { Split, type SplitProps } from "./Split.js";
147
+ export { MenuIcon, type MenuIconName, type MenuIconProps } from "./MenuIcon.js";
148
+ export { Monogram } from "./Monogram.js";
149
+ export { OverflowMenu, type OverflowAction } from "./OverflowMenu.js";
150
+ export { fenceInfo } from "./fenceInfo.js";
151
+ export { MermaidBlock, loadMermaid } from "./Mermaid.js";
152
+ export { Skeleton } from "./Skeleton.js";
153
+ export { Tooltip, type TooltipProps } from "./Tooltip.js";