@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,102 @@
1
+ /**
2
+ * What is shown where a subtree threw.
3
+ *
4
+ * EXTENSIBILITY §7 promises "UI throws → its own error boundary" and
5
+ * nothing provided one. The iframe does protect the *host*: igni's
6
+ * shell survives whatever an extension does. It does not protect the
7
+ * extension from itself. A React tree that throws unmounts, so what
8
+ * an author actually shipped was a blank frame inside a working app —
9
+ * the worst-looking failure available, and the one a partner demo
10
+ * finds.
11
+ *
12
+ * A class, because `componentDidCatch` and
13
+ * `getDerivedStateFromError` have no hook equivalent. This is the
14
+ * only class component under the floor and it is not a style
15
+ * preference.
16
+ *
17
+ * **It catches less than people expect**, and saying so is part of
18
+ * the contract: render, lifecycle and constructor throws, in the
19
+ * subtree below it. Not event handlers, not `setTimeout`, not
20
+ * promise rejections, not anything during SSR. An extension still
21
+ * needs to handle its own async failures — the reference extension's
22
+ * `ScannerClient` is what that looks like.
23
+ */
24
+ import { Component, type ErrorInfo, type ReactNode } from "react";
25
+
26
+ /** What an {@link ErrorBoundary} takes. */
27
+ export interface ErrorBoundaryProps {
28
+ /** The subtree this boundary guards. */
29
+ children: ReactNode;
30
+ /**
31
+ * Shown instead of the subtree. Receives the error and a function
32
+ * that clears the boundary and remounts the children.
33
+ *
34
+ * The default is deliberately plain and deliberately shows the
35
+ * message: the reader is an extension's user, and "something went
36
+ * wrong" has never once helped anybody report a bug.
37
+ */
38
+ fallback?: (error: Error, reset: () => void) => ReactNode;
39
+ /** Somewhere to send this — a logger, telemetry, a toast. */
40
+ onError?: (error: Error, info: ErrorInfo) => void;
41
+ /**
42
+ * Changing any of these clears the boundary.
43
+ *
44
+ * Without it a boundary that has caught once stays caught forever,
45
+ * so navigating away from the thing that broke shows the error
46
+ * page for the thing that works. Compared by identity, in order,
47
+ * like a hook dependency array.
48
+ */
49
+ resetKeys?: readonly unknown[];
50
+ }
51
+
52
+ interface State {
53
+ error: Error | null;
54
+ }
55
+
56
+ function changed(a: readonly unknown[], b: readonly unknown[]): boolean {
57
+ return a.length !== b.length || a.some((value, i) => !Object.is(value, b[i]));
58
+ }
59
+
60
+ /**
61
+ * What is shown where a subtree threw.
62
+ *
63
+ * See the note at the top of this file: it catches less than people
64
+ * expect, and the default fallback shows the message on purpose.
65
+ */
66
+ export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
67
+ state: State = { error: null };
68
+
69
+ static getDerivedStateFromError(error: Error): State {
70
+ return { error };
71
+ }
72
+
73
+ componentDidCatch(error: Error, info: ErrorInfo): void {
74
+ this.props.onError?.(error, info);
75
+ }
76
+
77
+ componentDidUpdate(previous: ErrorBoundaryProps): void {
78
+ if (this.state.error === null) return;
79
+ const before = previous.resetKeys ?? [];
80
+ const now = this.props.resetKeys ?? [];
81
+ if (changed(before, now)) this.reset();
82
+ }
83
+
84
+ reset = (): void => {
85
+ this.setState({ error: null });
86
+ };
87
+
88
+ render(): ReactNode {
89
+ const { error } = this.state;
90
+ if (error === null) return this.props.children;
91
+ if (this.props.fallback) return this.props.fallback(error, this.reset);
92
+ return (
93
+ <div className="ui-crash" role="alert">
94
+ <p className="ui-text">Something in this view stopped working.</p>
95
+ <pre className="ui-crash-detail">{error.message}</pre>
96
+ <button type="button" className="btn" onClick={this.reset}>
97
+ Try again
98
+ </button>
99
+ </div>
100
+ );
101
+ }
102
+ }
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Saying what changed, to somebody who cannot see it change.
3
+ *
4
+ * A filtered count, a finished scan, a saved draft: all of them move
5
+ * nothing and focus nothing, so a screen reader is told none of it.
6
+ * The reference extension hand-rolled an `aria-live` paragraph with
7
+ * `ui-visually-hidden`, which is the right shape and the wrong place
8
+ * — every extension would write it, and most would get one of the
9
+ * three details wrong.
10
+ *
11
+ * The three details:
12
+ *
13
+ * 1. **The region must exist before the text does.** A live region
14
+ * added to the DOM with its message already in it is frequently
15
+ * not announced at all — the assistive technology has nothing to
16
+ * observe a change against. So this renders an empty element and
17
+ * fills it afterwards.
18
+ * 2. **The same message twice is not a change.** Scanning 40 files
19
+ * and then scanning 40 files again is silence, because the text
20
+ * never differed. A zero-width space is toggled on repeats.
21
+ * 3. **Polite waits, assertive interrupts.** Almost everything is
22
+ * polite. Assertive is for something the user must act on, and
23
+ * using it for a count makes the product unusable by the people
24
+ * it is meant to help.
25
+ */
26
+ import { useCallback, useEffect, useRef, useState } from "react";
27
+
28
+ /** Which way to say it. */
29
+ export type Urgency = "polite" | "assertive";
30
+
31
+ /** A live region and the function that speaks into it. */
32
+ export interface Announcer {
33
+ /** Say something. Re-saying the same thing still announces. */
34
+ announce: (message: string, urgency?: Urgency) => void;
35
+ /** Render this. It must be in the tree before anything is said. */
36
+ region: React.ReactElement;
37
+ }
38
+
39
+ /**
40
+ * A live region and the function that speaks into it.
41
+ *
42
+ * Two regions are rendered, not one. A single region whose
43
+ * `aria-live` value changes is unreliable: the attribute is read
44
+ * when the region is observed, so flipping it at the same moment the
45
+ * text changes races, and the announcement comes out at whichever
46
+ * urgency the implementation noticed first.
47
+ */
48
+ export function useAnnounce(): Announcer {
49
+ const [polite, setPolite] = useState("");
50
+ const [assertive, setAssertive] = useState("");
51
+ const last = useRef({ polite: "", assertive: "" });
52
+
53
+ const announce = useCallback(
54
+ (message: string, urgency: Urgency = "polite") => {
55
+ // Identical consecutive text is not a mutation, so nothing is
56
+ // announced. A zero-width space makes it one, and is not read
57
+ // aloud.
58
+ const previous = last.current[urgency];
59
+ const text = message === previous ? `${message}​` : message;
60
+ last.current[urgency] = text;
61
+ if (urgency === "assertive") setAssertive(text);
62
+ else setPolite(text);
63
+ },
64
+ [],
65
+ );
66
+
67
+ const region = (
68
+ <>
69
+ <div
70
+ className="ui-visually-hidden"
71
+ role="status"
72
+ aria-live="polite"
73
+ aria-atomic="true"
74
+ >
75
+ {polite}
76
+ </div>
77
+ <div
78
+ className="ui-visually-hidden"
79
+ role="alert"
80
+ aria-live="assertive"
81
+ aria-atomic="true"
82
+ >
83
+ {assertive}
84
+ </div>
85
+ </>
86
+ );
87
+
88
+ return { announce, region };
89
+ }
90
+
91
+ /** What a {@link LiveRegion} takes. */
92
+ export interface LiveRegionProps {
93
+ /** What to say. Changing it announces; clearing it says nothing. */
94
+ children?: string;
95
+ /** How insistently it is announced: politely, or assertively. */
96
+ urgency?: Urgency;
97
+ }
98
+
99
+ /**
100
+ * The declarative form, for a value that already lives in state.
101
+ *
102
+ * `<LiveRegion>{`${n} results`}</LiveRegion>` is the whole usage.
103
+ * Mounted empty on the first render so the region exists before it
104
+ * has anything to say — see note 1 above.
105
+ */
106
+ export function LiveRegion({ children = "", urgency = "polite" }: LiveRegionProps) {
107
+ const [text, setText] = useState("");
108
+ useEffect(() => {
109
+ setText(children);
110
+ }, [children]);
111
+ return (
112
+ <div
113
+ className="ui-visually-hidden"
114
+ role={urgency === "assertive" ? "alert" : "status"}
115
+ aria-live={urgency}
116
+ aria-atomic="true"
117
+ >
118
+ {text}
119
+ </div>
120
+ );
121
+ }
@@ -0,0 +1,71 @@
1
+ /**
2
+ * Markdown with its block structure intact.
3
+ *
4
+ * The floor published exactly one markdown component and it was
5
+ * `MarkdownInline`, which is *designed* to destroy block structure:
6
+ * headings lose their size, lists become middots, images return
7
+ * null. That is right for a two-line preview and exactly wrong for a
8
+ * document, so an extension with prose in it bundled its own
9
+ * renderer — and then had nothing to style it against, because
10
+ * igni's prose rules live in `theme.css` and were not published
11
+ * either.
12
+ *
13
+ * `examples/release-notes` hand-rolls a deliberately small subset
14
+ * and says so. This is what that was missing.
15
+ *
16
+ * **Not a configurable pipeline.** No plugin prop, no component
17
+ * overrides. The value here is that prose in an extension looks like
18
+ * prose in igni, and every escape hatch is a way for that to stop
19
+ * being true. An extension that needs a different pipeline should
20
+ * bundle react-markdown directly — it is a peer dependency it
21
+ * already has — and wrap the result in `.ui-prose`.
22
+ */
23
+ import ReactMarkdown, { type Components } from "react-markdown";
24
+ import remarkGfm from "remark-gfm";
25
+
26
+ function cx(...parts: (string | false | null | undefined)[]): string {
27
+ return parts.filter(Boolean).join(" ");
28
+ }
29
+
30
+ /**
31
+ * Links open where they point, safely.
32
+ *
33
+ * A document can arrive from a colleague, so the href is somebody
34
+ * else's. `noopener` is the one that matters: without it the opened
35
+ * page gets a handle on this frame through `window.opener` and can
36
+ * navigate it somewhere else.
37
+ */
38
+ const COMPONENTS: Components = {
39
+ a: ({ href, children, ...rest }) => (
40
+ <a {...rest} href={href} target="_blank" rel="noopener noreferrer">
41
+ {children}
42
+ </a>
43
+ ),
44
+ };
45
+
46
+ /** What a {@link Markdown} takes. */
47
+ export interface MarkdownProps {
48
+ /** The source. Rendered as a document, not flattened. */
49
+ children: string;
50
+ /** Added to the element's classes, beside the one the theme gives it. */
51
+ className?: string;
52
+ }
53
+
54
+ /**
55
+ * Render markdown as prose.
56
+ *
57
+ * GitHub-flavoured, because that is what people write: tables,
58
+ * strikethrough, task lists and autolinks. Raw HTML is **not**
59
+ * enabled and will not be — `rehype-raw` in a surface that renders
60
+ * text somebody else wrote is a script tag waiting to happen, and an
61
+ * extension's frame has a CSP precisely so that it cannot.
62
+ */
63
+ export function Markdown({ children, className }: MarkdownProps) {
64
+ return (
65
+ <div className={cx("ui-prose", className)}>
66
+ <ReactMarkdown remarkPlugins={[remarkGfm]} components={COMPONENTS}>
67
+ {children}
68
+ </ReactMarkdown>
69
+ </div>
70
+ );
71
+ }
@@ -0,0 +1,164 @@
1
+ import { useMemo } from "react";
2
+ import ReactMarkdown, { type Components } from "react-markdown";
3
+ import remarkGfm from "remark-gfm";
4
+
5
+ /**
6
+ * Markdown rendered as one flowing line of text.
7
+ *
8
+ * For previews: a list row, a snippet, anywhere a document has to be
9
+ * recognisable in two lines. Showing the raw source there leaks `##`
10
+ * and `**` into prose; rendering it normally is worse, because a
11
+ * heading at heading size in a 11.5px row is a heading, and a bullet
12
+ * list becomes four lines where there was room for two.
13
+ *
14
+ * So every block becomes inline. Headings keep their emphasis but not
15
+ * their size, list items are separated by middots rather than laid
16
+ * out, and code keeps its face. The result reads as the sentence the
17
+ * author wrote, which is what a preview is for.
18
+ *
19
+ * Two constraints are load-bearing, both from where this gets used:
20
+ *
21
+ * - **Nothing interactive.** These previews sit inside a `<button>`
22
+ * that opens the document. A link inside a button is invalid, and
23
+ * worse, it is a second click target inside the first.
24
+ * - **Nothing that loads.** An image in a preview is a network
25
+ * request to render two lines of text, and a broken one is an icon
26
+ * where a sentence should be.
27
+ */
28
+
29
+ /** Blocks flow inline, so a preview is one sentence rather than a page. */
30
+ const INLINE_COMPONENTS: Components = {
31
+ // Emphasis without the size. A document whose first line is a
32
+ // heading should read as its first line, not as a title.
33
+ h1: ({ children }) => <strong className="mdi-heading">{children}</strong>,
34
+ h2: ({ children }) => <strong className="mdi-heading">{children}</strong>,
35
+ h3: ({ children }) => <strong className="mdi-heading">{children}</strong>,
36
+ h4: ({ children }) => <strong className="mdi-heading">{children}</strong>,
37
+ h5: ({ children }) => <strong className="mdi-heading">{children}</strong>,
38
+ h6: ({ children }) => <strong className="mdi-heading">{children}</strong>,
39
+
40
+ p: ({ children }) => <span className="mdi-block">{children}</span>,
41
+ blockquote: ({ children }) => <span className="mdi-block">{children}</span>,
42
+
43
+ ul: ({ children }) => <span className="mdi-block">{children}</span>,
44
+ ol: ({ children }) => <span className="mdi-block">{children}</span>,
45
+ li: ({ children }) => <span className="mdi-item">{children}</span>,
46
+
47
+ // A fenced block and an inline span both become inline code: the
48
+ // point of showing code in a preview is that it is code.
49
+ pre: ({ children }) => <span className="mdi-block">{children}</span>,
50
+ code: ({ children }) => <code className="mdi-code">{children}</code>,
51
+
52
+ // Text only. The row itself is the link.
53
+ a: ({ children }) => <span>{children}</span>,
54
+
55
+ img: () => null,
56
+ hr: () => null,
57
+ br: () => <span> </span>,
58
+
59
+ // Tables flatten to their cells. A preview of a table is not a
60
+ // table, and rendering one inside two clamped lines produces a
61
+ // column of single characters.
62
+ table: ({ children }) => <span className="mdi-block">{children}</span>,
63
+ thead: () => null,
64
+ tbody: ({ children }) => <span>{children}</span>,
65
+ tr: ({ children }) => <span className="mdi-item">{children}</span>,
66
+ td: ({ children }) => <span className="mdi-cell">{children}</span>,
67
+ th: ({ children }) => <span className="mdi-cell">{children}</span>,
68
+ };
69
+
70
+ /**
71
+ * Repair markdown cut mid-syntax.
72
+ *
73
+ * Previews arrive pre-truncated, and the cut lands wherever it lands
74
+ * — often inside `**bold` or an unclosed backtick. Rendered as-is the
75
+ * marker shows up literally, which is the thing this component
76
+ * exists to stop. Closing what was left open is cheaper than asking
77
+ * every producer of a preview to cut carefully.
78
+ */
79
+ export function closeOpenMarks(text: string): string {
80
+ let out = text;
81
+ // Fences first: an unclosed one swallows everything after it.
82
+ if ((out.match(/^```/gm) ?? []).length % 2 === 1) out += "\n```";
83
+ // Then inline runs, longest marker first so `**` is not read as two
84
+ // single `*`.
85
+ for (const mark of ["**", "`", "*", "_"]) {
86
+ const count = out.split(mark).length - 1;
87
+ if (count % 2 === 1) out += mark;
88
+ }
89
+ return out;
90
+ }
91
+
92
+ /**
93
+ * Drop a leading line that only repeats the document's name.
94
+ *
95
+ * Most documents open with their own title. In a list the name is
96
+ * already the row's first line, so rendering it again spends the
97
+ * preview — the two lines somebody reads to tell this document from
98
+ * the next one — saying what they just read.
99
+ *
100
+ * Heading or plain line: the duplication is the same either way, and
101
+ * whether the author marked it up is not the reader's problem. The
102
+ * line has to *be* the name, though, not merely open with it —
103
+ * "Session handling is a signed JWT flow" is the first sentence of
104
+ * the document and belongs in the preview.
105
+ */
106
+ export function dropEchoedTitle(text: string, name: string): string {
107
+ const title = name.trim().toLowerCase();
108
+ if (!title) return text;
109
+ const lines = text.split("\n");
110
+ let i = 0;
111
+ while (i < lines.length && !lines[i].trim()) i++;
112
+ const first = lines[i]?.trim() ?? "";
113
+ const heading = first.replace(/^#{1,6}\s+/, "").trim();
114
+ // Only when it *is* the title, not when it merely starts with it —
115
+ // "Session handling in detail" is a different heading.
116
+ if (heading.toLowerCase() !== title) return text;
117
+ return lines
118
+ .slice(i + 1)
119
+ .join("\n")
120
+ .trimStart();
121
+ }
122
+
123
+ /**
124
+ * Markdown rendered as one flowing line of text.
125
+ *
126
+ * See the note at the top of this file for what it does to blocks and
127
+ * why. `limit` bounds the work, not the appearance: the clamp is
128
+ * visual, and a document longer than `limit` is cut at a word
129
+ * boundary with an ellipsis.
130
+ */
131
+ export function MarkdownInline({
132
+ text,
133
+ /** The document's name, so a title echo can be dropped. */
134
+ name = "",
135
+ /** Characters to keep. The clamp is visual; this bounds the work. */
136
+ limit = 320,
137
+ className = "",
138
+ }: {
139
+ text: string;
140
+ name?: string;
141
+ limit?: number;
142
+ className?: string;
143
+ }) {
144
+ const source = useMemo(() => {
145
+ const body = dropEchoedTitle(String(text || ""), name);
146
+ if (body.length <= limit) return closeOpenMarks(body);
147
+ // Cut back to a space so the preview does not end mid-word.
148
+ const cut = body.slice(0, limit);
149
+ const space = cut.lastIndexOf(" ");
150
+ return (
151
+ closeOpenMarks(space > limit * 0.6 ? cut.slice(0, space) : cut) + "…"
152
+ );
153
+ }, [text, name, limit]);
154
+
155
+ if (!source.trim()) return null;
156
+
157
+ return (
158
+ <span className={className ? `mdi ${className}` : "mdi"}>
159
+ <ReactMarkdown remarkPlugins={[remarkGfm]} components={INLINE_COMPONENTS}>
160
+ {source}
161
+ </ReactMarkdown>
162
+ </span>
163
+ );
164
+ }
@@ -0,0 +1,203 @@
1
+ /**
2
+ * The small glyphs beside a menu item.
3
+ *
4
+ * A menu of five verbs reads as five equal options, and picking the
5
+ * wrong one of Archive and Remove costs quite differently. An icon is
6
+ * what makes a list scannable: the shape is recognised before the
7
+ * word is read, so the item somebody wants is found by looking rather
8
+ * than by reading the list from the top each time.
9
+ *
10
+ * **One set, one grammar.** All of them are 16×16, drawn in strokes
11
+ * of the same weight on the same grid, and coloured ``currentColor``
12
+ * so a disabled item's icon dims with its label and a destructive
13
+ * one turns red with it. Mixing a filled glyph into a stroked set is
14
+ * the single most obvious way to make a menu look assembled from
15
+ * parts.
16
+ *
17
+ * Inline rather than a sprite or a font: these are a dozen paths used
18
+ * in three menus, and a build step, a network request or a font with
19
+ * a flash of missing glyphs are all more machinery than the problem
20
+ * has.
21
+ */
22
+
23
+ export type MenuIconName =
24
+ | "open"
25
+ | "rename"
26
+ | "export"
27
+ | "share"
28
+ | "archive"
29
+ | "restore"
30
+ | "remove"
31
+ | "document"
32
+ | "document-add"
33
+ | "folder"
34
+ | "folder-add"
35
+ | "outdent"
36
+ | "compare"
37
+ | "lineage"
38
+ // Formatting. Drawn in the same grammar as the rest so the
39
+ // editor's bar and the document's menus look like one product.
40
+ | "code"
41
+ | "list-bullet"
42
+ | "list-ordered"
43
+ | "list-task"
44
+ | "quote"
45
+ | "code-block"
46
+ | "table"
47
+ | "divider"
48
+ | "link"
49
+ | "image"
50
+ | "undo"
51
+ | "redo"
52
+ | "resolve"
53
+ | "reopen"
54
+ | "lock"
55
+ | "unlock"
56
+ | "bell"
57
+ // A diagram's copy button, before and after.
58
+ | "copy"
59
+ | "check";
60
+
61
+ /** The drawing for each name, on a 16×16 grid. */
62
+ const PATHS: Record<MenuIconName, string> = {
63
+ // A page with a corner turned.
64
+ open: "M9 1.5H4.5A1.5 1.5 0 0 0 3 3v10a1.5 1.5 0 0 0 1.5 1.5h7A1.5 1.5 0 0 0 13 13V5.5zM9 1.5V5.5h4",
65
+ // A pencil across a line.
66
+ rename: "M11.2 2.3 13.7 4.8 6.2 12.3 3 13l.7-3.2zM2.5 14.5h11",
67
+ // Out of a tray, downwards — the file leaves.
68
+ export:
69
+ "M8 2v7m0 0 2.8-2.8M8 9 5.2 6.2M2.8 10.5v2.2a1 1 0 0 0 1 1h8.4a1 1 0 0 0 1-1v-2.2",
70
+ // Two nodes joined to a third: one thing, several people.
71
+ share:
72
+ "M5.6 9.3 10.4 12M10.4 4 5.6 6.7M12 2.2a1.8 1.8 0 1 1 0 3.6 1.8 1.8 0 0 1 0-3.6zM4 6.2a1.8 1.8 0 1 1 0 3.6 1.8 1.8 0 0 1 0-3.6zM12 10.2a1.8 1.8 0 1 1 0 3.6 1.8 1.8 0 0 1 0-3.6z",
73
+ // A box with a lid, and a handle on the drawer.
74
+ archive:
75
+ "M2 3.2h12v2.6H2zM3 5.8v7a.8.8 0 0 0 .8.8h8.4a.8.8 0 0 0 .8-.8v-7M6.4 8.4h3.2",
76
+ // The same box, with the arrow coming back up out of it.
77
+ restore:
78
+ "M2 3.2h12v2.6H2zM3 5.8v7a.8.8 0 0 0 .8.8h8.4a.8.8 0 0 0 .8-.8v-7M8 11.6V7.4m0 0L6.2 9.2M8 7.4l1.8 1.8",
79
+ // A bin. Deliberately the least like the archive of any of these.
80
+ remove:
81
+ "M2.8 4.3h10.4M6.4 4.3V2.9a.7.7 0 0 1 .7-.7h1.8a.7.7 0 0 1 .7.7v1.4M4.2 4.3l.6 8.5a.9.9 0 0 0 .9.8h4.6a.9.9 0 0 0 .9-.8l.6-8.5M6.7 6.8v4.2M9.3 6.8v4.2",
82
+ // A page. The same shape as ``open`` without the action.
83
+ document:
84
+ "M9 1.5H4.5A1.5 1.5 0 0 0 3 3v10a1.5 1.5 0 0 0 1.5 1.5h7A1.5 1.5 0 0 0 13 13V5.5zM9 1.5V5.5h4M5.5 8.5h5M5.5 11h3",
85
+ // The same page and folder, with the plus that makes one. Drawn
86
+ // from the same outlines rather than new shapes: "new document"
87
+ // and "document" should be recognisably the same noun.
88
+ "document-add":
89
+ "M8.4 1.5H4.5A1.5 1.5 0 0 0 3 3v10a1.5 1.5 0 0 0 1.5 1.5h3.2M8.4 1.5V5.5h3.6M11.8 8.8v4.6M9.5 11.1h4.6",
90
+ folder:
91
+ "M1.8 4.2a1 1 0 0 1 1-1h3.1l1.4 1.6h5.9a1 1 0 0 1 1 1v6.4a1 1 0 0 1-1 1H2.8a1 1 0 0 1-1-1z",
92
+ "folder-add":
93
+ "M1.8 4.2a1 1 0 0 1 1-1h3.1l1.4 1.6h5.9a1 1 0 0 1 1 1v1.5M1.8 4.2v8.4a1 1 0 0 0 1 1h4.9M11.4 8.8v4.6M9.1 11.1h4.6",
94
+ // Up and to the left: out of where it is, to the level above.
95
+ outdent: "M13 4H6M13 8H8.5M13 12H6M4.5 5.5 2 8l2.5 2.5",
96
+ // Two columns, side by side.
97
+ compare: "M6.4 2.5v11M9.6 2.5v11M2 2.5h12v11H2zM2 2.5",
98
+ // Chevrons, the way code is written about.
99
+ code: "M5.8 4.6 1.8 8l4 3.4M10.2 4.6 14.2 8l-4 3.4",
100
+ // Three dots with three lines. The dots are round rather than
101
+ // square so a bullet list and a checklist are not the same
102
+ // silhouette at a glance.
103
+ "list-bullet":
104
+ "M6.2 4.2h7.6M6.2 8h7.6M6.2 11.8h7.6M2.6 3.6a.6.6 0 1 1 0 1.2.6.6 0 0 1 0-1.2zM2.6 7.4a.6.6 0 1 1 0 1.2.6.6 0 0 1 0-1.2zM2.6 11.2a.6.6 0 1 1 0 1.2.6.6 0 0 1 0-1.2z",
105
+ "list-ordered":
106
+ "M6.4 4.2h7.4M6.4 8h7.4M6.4 11.8h7.4M2 3.2h1v2.4M1.7 5.6h1.8M1.7 9.6h2l-2 2.6h2.2",
107
+ // A tick in a box, against the bullet list's round dots.
108
+ "list-task":
109
+ "M6.6 4.2h7.2M6.6 11.8h7.2M1.4 2.7h3.4v3.4H1.4zM1.4 10.3h3.4v3.4H1.4zM2.1 11.9l.9.9 1.4-1.6",
110
+ // The bar a quote is set behind, with the lines it holds.
111
+ quote: "M2.6 3.4v9.2M5.8 5h8M5.8 8h8M5.8 11h5.4",
112
+ // A fence: the chevrons again, boxed.
113
+ "code-block":
114
+ "M1.8 3.2h12.4v9.6H1.8zM6.2 6.4 4.4 8l1.8 1.6M9.8 6.4 11.6 8l-1.8 1.6",
115
+ // A grid with its header row set apart, which is what makes a
116
+ // table a table rather than a box with lines in it.
117
+ table: "M1.8 3.2h12.4v9.6H1.8zM1.8 6.4h12.4M6.4 6.4v6.4M10.2 6.4v6.4",
118
+ divider: "M2 8h12",
119
+ // A chain of two links, at an angle.
120
+ link: "M6.6 9.4 9.4 6.6M6.9 4.6 8.4 3.1a2.6 2.6 0 0 1 3.7 3.7l-1.5 1.5M9.1 11.4l-1.5 1.5a2.6 2.6 0 0 1-3.7-3.7l1.5-1.5",
121
+ // A frame with a horizon and a sun: recognisable at this size in
122
+ // a way a literal photograph is not.
123
+ image:
124
+ "M1.8 3.2h12.4v9.6H1.8zM1.8 10.4l3.4-3.2 3 2.8 2.2-2 3.8 3.4M10.6 5.6a.9.9 0 1 1 0 1.8.9.9 0 0 1 0-1.8z",
125
+ // A tick in a circle: settled, and closed. The checklist glyph
126
+ // was standing in for this and said the wrong thing — a checklist
127
+ // is a kind of list, not a ruling on a conversation.
128
+ resolve:
129
+ "M8 1.6a6.4 6.4 0 1 1 0 12.8A6.4 6.4 0 0 1 8 1.6zM5.2 8.2l1.9 1.9 3.7-4",
130
+ // The same circle, opened again: an arrow coming back round.
131
+ reopen: "M13.4 8a5.4 5.4 0 1 1-1.9-4.1M13.6 2.4v3.4h-3.4",
132
+ // A padlock, shackle closed. Shown beside a colleague who cannot
133
+ // open the document — a state, not an action, which is why it is
134
+ // the only icon here that is never on a button of its own.
135
+ lock: "M4.2 7.2h7.6a.8.8 0 0 1 .8.8v5a.8.8 0 0 1-.8.8H4.2a.8.8 0 0 1-.8-.8V8a.8.8 0 0 1 .8-.8zM5.6 7.2V4.9a2.4 2.4 0 0 1 4.8 0v2.3",
136
+ // The same padlock with the shackle swung open. Drawn from the
137
+ // same body so the two read as one object in two states rather
138
+ // than as two icons — the whole point is noticing that it changed.
139
+ unlock:
140
+ "M4.2 7.2h7.6a.8.8 0 0 1 .8.8v5a.8.8 0 0 1-.8.8H4.2a.8.8 0 0 1-.8-.8V8a.8.8 0 0 1 .8-.8zM5.6 7.2V4.9a2.4 2.4 0 0 1 4.8 0",
141
+ undo: "M4.2 6.6H10a3.4 3.4 0 0 1 0 6.8H6.6M4.2 6.6l2.6-2.6M4.2 6.6l2.6 2.6",
142
+ redo: "M11.8 6.6H6a3.4 3.4 0 0 0 0 6.8h3.4M11.8 6.6 9.2 4M11.8 6.6 9.2 9.2",
143
+ // A node with two feeding into it: what this was built on.
144
+ // A bell, drawn at the same weight as the rest: the clapper is a
145
+ // separate stroke so it reads at 14px, where a single outline
146
+ // closes up into a blob.
147
+ bell: "M8 2.2a3.8 3.8 0 0 0-3.8 3.8c0 3-1.1 4-1.1 4h9.8s-1.1-1-1.1-4A3.8 3.8 0 0 0 8 2.2zM9.3 12.2a1.5 1.5 0 0 1-2.6 0",
148
+ // Two pages, one over the other: the source, duplicated.
149
+ copy: "M5.6 5.6h7a.8.8 0 0 1 .8.8v7a.8.8 0 0 1-.8.8h-7a.8.8 0 0 1-.8-.8v-7a.8.8 0 0 1 .8-.8zM3.2 10.4h-.4a.8.8 0 0 1-.8-.8v-7a.8.8 0 0 1 .8-.8h7a.8.8 0 0 1 .8.8v.4",
150
+ // The tick on its own, without the circle ``resolve`` draws it in.
151
+ check: "M3 8.4l3.2 3.2L13 4.8",
152
+ lineage:
153
+ "M3.6 4.2h3.1a2 2 0 0 1 2 2v3.6a2 2 0 0 0 2 2h1.7M3.6 11.8h3.1M1.4 2.8a1.4 1.4 0 1 1 0 2.8 1.4 1.4 0 0 1 0-2.8zM1.4 10.4a1.4 1.4 0 1 1 0 2.8 1.4 1.4 0 0 1 0-2.8zM13.2 10.4a1.4 1.4 0 1 1 0 2.8 1.4 1.4 0 0 1 0-2.8z",
154
+ };
155
+
156
+ /** What a {@link MenuIcon} takes. */
157
+ export interface MenuIconProps {
158
+ /** One of igni's own icons. */
159
+ name?: MenuIconName;
160
+ /**
161
+ * An SVG path, for an icon igni does not have.
162
+ *
163
+ * Here because the alternative is a closed union, and an extension
164
+ * cannot add a member to one. `PageKind` had the same problem and
165
+ * was opened for the same reason: what exists is decided at install
166
+ * time by what an administrator put on the machine, not at compile
167
+ * time by us.
168
+ *
169
+ * Drawn on a 16×16 grid, stroked rather than filled, to match. A
170
+ * path that assumes a different viewBox will look like it belongs
171
+ * to a different application, which is the one thing this whole
172
+ * package exists to prevent.
173
+ */
174
+ path?: string;
175
+ /** Added to the element's classes, beside the one the theme gives it. */
176
+ className?: string;
177
+ }
178
+
179
+ /**
180
+ * One of igni's own icons, drawn on a 16×16 grid.
181
+ *
182
+ * See the note at the top of this file for why there is one set and
183
+ * one grammar. A name that is not in the set draws nothing, rather
184
+ * than a broken box: the label says what the item does, and the icon
185
+ * is only how it is found.
186
+ */
187
+ export function MenuIcon({ name, path, className }: MenuIconProps) {
188
+ const d = path ?? (name ? PATHS[name] : undefined);
189
+ // An unknown name draws nothing rather than a broken box. The
190
+ // label is the thing that says what the item does; the icon is how
191
+ // it is found again.
192
+ if (!d) return null;
193
+ return (
194
+ <svg
195
+ className={className ? `menu-icon ${className}` : "menu-icon"}
196
+ viewBox="0 0 16 16"
197
+ aria-hidden="true"
198
+ focusable="false"
199
+ >
200
+ <path d={d} />
201
+ </svg>
202
+ );
203
+ }