@ignite-ember/ui-react 0.2.0 → 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 (127) hide show
  1. package/NOTICE +1 -1
  2. package/README.md +56 -13
  3. package/dist/CopySource.d.ts.map +1 -1
  4. package/dist/CopySource.js +16 -2
  5. package/dist/CopySource.js.map +1 -1
  6. package/dist/DataTable.d.ts +17 -1
  7. package/dist/DataTable.d.ts.map +1 -1
  8. package/dist/DataTable.js +17 -1
  9. package/dist/DataTable.js.map +1 -1
  10. package/dist/Dialog.d.ts +41 -0
  11. package/dist/Dialog.d.ts.map +1 -0
  12. package/dist/Dialog.js +94 -0
  13. package/dist/Dialog.js.map +1 -0
  14. package/dist/ErrorBoundary.d.ts +31 -2
  15. package/dist/ErrorBoundary.d.ts.map +1 -1
  16. package/dist/ErrorBoundary.js +38 -4
  17. package/dist/ErrorBoundary.js.map +1 -1
  18. package/dist/LiveRegion.d.ts +7 -1
  19. package/dist/LiveRegion.d.ts.map +1 -1
  20. package/dist/LiveRegion.js +7 -1
  21. package/dist/LiveRegion.js.map +1 -1
  22. package/dist/Markdown.d.ts +4 -0
  23. package/dist/Markdown.d.ts.map +1 -1
  24. package/dist/Markdown.js +4 -0
  25. package/dist/Markdown.js.map +1 -1
  26. package/dist/MarkdownInline.d.ts +13 -4
  27. package/dist/MarkdownInline.d.ts.map +1 -1
  28. package/dist/MarkdownInline.js +20 -5
  29. package/dist/MarkdownInline.js.map +1 -1
  30. package/dist/MenuIcon.d.ts +10 -4
  31. package/dist/MenuIcon.d.ts.map +1 -1
  32. package/dist/MenuIcon.js +8 -2
  33. package/dist/MenuIcon.js.map +1 -1
  34. package/dist/Mermaid.d.ts +2 -0
  35. package/dist/Mermaid.d.ts.map +1 -1
  36. package/dist/Mermaid.js +2 -0
  37. package/dist/Mermaid.js.map +1 -1
  38. package/dist/Monogram.d.ts +7 -3
  39. package/dist/Monogram.d.ts.map +1 -1
  40. package/dist/Monogram.js +14 -6
  41. package/dist/Monogram.js.map +1 -1
  42. package/dist/OverflowMenu.d.ts +6 -1
  43. package/dist/OverflowMenu.d.ts.map +1 -1
  44. package/dist/OverflowMenu.js +10 -2
  45. package/dist/OverflowMenu.js.map +1 -1
  46. package/dist/Shell.d.ts +13 -0
  47. package/dist/Shell.d.ts.map +1 -1
  48. package/dist/Shell.js +13 -0
  49. package/dist/Shell.js.map +1 -1
  50. package/dist/Skeleton.d.ts +30 -0
  51. package/dist/Skeleton.d.ts.map +1 -1
  52. package/dist/Skeleton.js +30 -0
  53. package/dist/Skeleton.js.map +1 -1
  54. package/dist/Split.d.ts +24 -5
  55. package/dist/Split.d.ts.map +1 -1
  56. package/dist/Split.js +27 -4
  57. package/dist/Split.js.map +1 -1
  58. package/dist/Tabs.d.ts +77 -0
  59. package/dist/Tabs.d.ts.map +1 -0
  60. package/dist/Tabs.js +91 -0
  61. package/dist/Tabs.js.map +1 -0
  62. package/dist/Toast.d.ts +12 -1
  63. package/dist/Toast.d.ts.map +1 -1
  64. package/dist/Toast.js +11 -0
  65. package/dist/Toast.js.map +1 -1
  66. package/dist/Tooltip.d.ts +12 -3
  67. package/dist/Tooltip.d.ts.map +1 -1
  68. package/dist/Tooltip.js +29 -7
  69. package/dist/Tooltip.js.map +1 -1
  70. package/dist/controls.d.ts +117 -0
  71. package/dist/controls.d.ts.map +1 -0
  72. package/dist/controls.js +59 -0
  73. package/dist/controls.js.map +1 -0
  74. package/dist/fenceInfo.d.ts +4 -1
  75. package/dist/fenceInfo.d.ts.map +1 -1
  76. package/dist/fenceInfo.js +4 -1
  77. package/dist/fenceInfo.js.map +1 -1
  78. package/dist/formControls.d.ts +143 -0
  79. package/dist/formControls.d.ts.map +1 -0
  80. package/dist/formControls.js +108 -0
  81. package/dist/formControls.js.map +1 -0
  82. package/dist/index.d.ts +5 -9
  83. package/dist/index.d.ts.map +1 -1
  84. package/dist/index.js +5 -9
  85. package/dist/index.js.map +1 -1
  86. package/dist/layout.d.ts +95 -0
  87. package/dist/layout.d.ts.map +1 -0
  88. package/dist/layout.js +93 -0
  89. package/dist/layout.js.map +1 -0
  90. package/dist/primitives.d.ts +10 -360
  91. package/dist/primitives.d.ts.map +1 -1
  92. package/dist/primitives.js +31 -338
  93. package/dist/primitives.js.map +1 -1
  94. package/dist/progress.d.ts +64 -0
  95. package/dist/progress.d.ts.map +1 -0
  96. package/dist/progress.js +51 -0
  97. package/dist/progress.js.map +1 -0
  98. package/dist/text.d.ts +63 -0
  99. package/dist/text.d.ts.map +1 -0
  100. package/dist/text.js +61 -0
  101. package/dist/text.js.map +1 -0
  102. package/package.json +4 -4
  103. package/src/CopySource.tsx +17 -2
  104. package/src/DataTable.tsx +17 -1
  105. package/src/Dialog.tsx +158 -0
  106. package/src/ErrorBoundary.tsx +39 -4
  107. package/src/LiveRegion.tsx +7 -1
  108. package/src/Markdown.tsx +4 -0
  109. package/src/MarkdownInline.tsx +20 -7
  110. package/src/MenuIcon.tsx +10 -4
  111. package/src/Mermaid.tsx +2 -0
  112. package/src/Monogram.tsx +14 -5
  113. package/src/OverflowMenu.tsx +9 -2
  114. package/src/Shell.tsx +13 -0
  115. package/src/Skeleton.tsx +30 -0
  116. package/src/Split.tsx +32 -7
  117. package/src/Tabs.tsx +194 -0
  118. package/src/Toast.tsx +12 -1
  119. package/src/Tooltip.tsx +33 -8
  120. package/src/controls.tsx +159 -0
  121. package/src/fenceInfo.ts +5 -2
  122. package/src/formControls.tsx +249 -0
  123. package/src/index.ts +5 -9
  124. package/src/layout.tsx +141 -0
  125. package/src/primitives.tsx +10 -864
  126. package/src/progress.tsx +129 -0
  127. package/src/text.tsx +99 -0
@@ -0,0 +1 @@
1
+ {"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.tsx"],"names":[],"mappings":";AASA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAAiC;IAC3E,OAAO,gBAAQ,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC,GAAI,CAAC;AAClE,CAAC;AAQD,MAAM,YAAY,GAAG;IACnB,CAAC,EAAE,iBAAiB;IACpB,CAAC,EAAE,gBAAgB;IACnB,CAAC,EAAE,gBAAgB;IACnB,CAAC,EAAE,gBAAgB;CACX,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CAAC,EACtB,KAAK,GAAG,CAAC,EACT,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACM;IACb,MAAM,GAAG,GAAG,IAAI,KAAK,EAA+B,CAAC;IACrD,OAAO,CACL,KAAC,GAAG,OACE,IAAI,EACR,SAAS,EAAE,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC,EACtC,KAAK,EAAE,EAAE,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,EAAE,GAClD,CACH,CAAC;AACJ,CAAC;AAWD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAa;IACtE,OAAO,eAAO,IAAI,eAAa,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,GAAI,CAAC;AAC/E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,EAA+B;IACtE,OAAO,kBAAU,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,GAAI,CAAC;AACjE,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignite-ember/ui-react",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "The React components an igni extension is allowed to build on. Everything exported here is under the compatibility floor.",
5
5
  "keywords": [
6
6
  "igni",
@@ -10,9 +10,9 @@
10
10
  "ui"
11
11
  ],
12
12
  "license": "Apache-2.0",
13
- "author": "Ignite Ember (https://ignite-ember.sh/)",
14
- "homepage": "https://ignite-ember.sh/docs/sdk/ui-react",
15
- "documentation": "https://ignite-ember.sh/docs/sdk/ui-react",
13
+ "author": "Ignite Ember (https://igni.sh/)",
14
+ "homepage": "https://igni.sh/docs/sdk/ui-react",
15
+ "documentation": "https://igni.sh/docs/sdk/ui-react",
16
16
  "bugs": {
17
17
  "url": "https://github.com/ignite-ember/igni-sdk/issues"
18
18
  },
@@ -9,7 +9,7 @@
9
9
  * appears to work and leaves nothing to paste is worse than one
10
10
  * that admits it failed.
11
11
  */
12
- import { useState } from "react";
12
+ import { useEffect, useRef, useState } from "react";
13
13
 
14
14
  import { MenuIcon } from "./MenuIcon.js";
15
15
 
@@ -27,6 +27,19 @@ const LABEL: Record<CopyState, string> = {
27
27
  export function CopySource({ source }: { source: string }) {
28
28
  const [state, setState] = useState<CopyState>("idle");
29
29
 
30
+ const timer = useRef<number | undefined>(undefined);
31
+
32
+ // A pending reset must not outlive the button, nor cut a later
33
+ // click's feedback short.
34
+ const alive = useRef(true);
35
+ useEffect(() => {
36
+ alive.current = true;
37
+ return () => {
38
+ alive.current = false;
39
+ window.clearTimeout(timer.current);
40
+ };
41
+ }, []);
42
+
30
43
  const copy = async () => {
31
44
  try {
32
45
  await navigator.clipboard.writeText(source);
@@ -34,7 +47,9 @@ export function CopySource({ source }: { source: string }) {
34
47
  } catch {
35
48
  setState("failed");
36
49
  }
37
- window.setTimeout(() => setState("idle"), FEEDBACK_MS);
50
+ if (!alive.current) return;
51
+ window.clearTimeout(timer.current);
52
+ timer.current = window.setTimeout(() => setState("idle"), FEEDBACK_MS);
38
53
  };
39
54
 
40
55
  return (
package/src/DataTable.tsx CHANGED
@@ -49,6 +49,16 @@ export interface SortableThProps
49
49
  *
50
50
  * The button fills the cell so the whole heading is the target
51
51
  * rather than a word inside it.
52
+ *
53
+ * @param children — the heading.
54
+ * @param direction — how this column is currently sorted, or
55
+ * `undefined` when the table is sorted by another column.
56
+ * @param onSort — asked to sort by this column; it gets the direction
57
+ * to go to.
58
+ * @param numeric — right-align the column and use tabular figures.
59
+ * @param className — added to the element's classes, beside the one the
60
+ * theme gives it.
61
+ * @param rest — the remaining props, spread onto the `th`.
52
62
  */
53
63
  export function SortableTh({
54
64
  children,
@@ -94,7 +104,13 @@ export interface StatusProps {
94
104
  children?: ReactNode;
95
105
  }
96
106
 
97
- /** A state, as a coloured dot and the word it stands for. */
107
+ /**
108
+ * A state, as a coloured dot and the word it stands for.
109
+ *
110
+ * @param state — the four states the health contract defines.
111
+ * @param children — what to show beside the dot; it defaults to the
112
+ * state itself.
113
+ */
98
114
  export function Status({ state, children }: StatusProps) {
99
115
  return (
100
116
  <span className="ui-status" data-state={state}>
package/src/Dialog.tsx ADDED
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The dialog: the one primitive that is behaviour rather than a box.
3
+ *
4
+ * Part of the primitives; see `primitives.tsx`. **Under the
5
+ * compatibility floor.**
6
+ */
7
+
8
+ import type { HTMLAttributes, KeyboardEvent, ReactNode } from "react";
9
+ import { useCallback, useEffect, useId, useRef } from "react";
10
+
11
+ import { cx } from "./cx.js";
12
+ import { Actions } from "./layout.js";
13
+
14
+ /** What a {@link Dialog} takes. */
15
+ export interface DialogProps extends Omit<
16
+ HTMLAttributes<HTMLDivElement>,
17
+ "title"
18
+ > {
19
+ /** Its title. Also the accessible name of the dialog. */
20
+ title: ReactNode;
21
+ /** Shown under the title. A sentence, not a paragraph. */
22
+ sub?: ReactNode;
23
+ /** The body. */
24
+ children?: ReactNode;
25
+ /** The buttons. Rendered in an `Actions` row at the foot. */
26
+ actions?: ReactNode;
27
+ /** Escape, or a click on the backdrop. */
28
+ onClose: () => void;
29
+ }
30
+
31
+ /**
32
+ * The one primitive here that is behaviour rather than a box.
33
+ *
34
+ * A dialog has to trap focus, close on Escape, restore focus to
35
+ * whatever opened it, and not let a click inside the panel count as a
36
+ * click on the backdrop. Every extension that built its own would get
37
+ * some of that wrong, and the ones they get wrong are the ones only
38
+ * keyboard and screen-reader users notice.
39
+ *
40
+ * @param title — its title, also the accessible name of the dialog.
41
+ * @param sub — shown under the title: a sentence, not a paragraph.
42
+ * @param children — the body.
43
+ * @param actions — the buttons, rendered in an `Actions` row at the
44
+ * foot.
45
+ * @param onClose — escape, or a click on the backdrop.
46
+ * @param className — added to the element's classes, beside the one the
47
+ * theme gives it.
48
+ * @param rest — the remaining props, spread onto the dialog panel.
49
+ */
50
+ export function Dialog({
51
+ title,
52
+ sub,
53
+ children,
54
+ actions,
55
+ onClose,
56
+ className,
57
+ ...rest
58
+ }: DialogProps) {
59
+ const panel = useRef<HTMLDivElement | null>(null);
60
+ const opener = useRef<Element | null>(null);
61
+ const titleId = useId();
62
+
63
+ useEffect(() => {
64
+ opener.current = document.activeElement;
65
+ // Focus the panel itself rather than the first control: reading
66
+ // the title before the buttons is the point of having one.
67
+ panel.current?.focus();
68
+ return () => {
69
+ // Only if it is still in the document: an opener that has
70
+ // unmounted drops focus to <body> silently, which is worse than
71
+ // leaving it where the closing action put it.
72
+ const back = opener.current;
73
+ if (back instanceof HTMLElement && back.isConnected) back.focus();
74
+ };
75
+ }, []);
76
+
77
+ const onKeyDown = useCallback(
78
+ (event: KeyboardEvent) => {
79
+ if (event.key === "Escape") {
80
+ event.stopPropagation();
81
+ onClose();
82
+ return;
83
+ }
84
+ if (event.key !== "Tab") return;
85
+ // `:not([disabled])` matters more than it looks: a modal whose
86
+ // confirm button is disabled until a field is typed is the
87
+ // commonest pattern there is, and without this the wrap targets
88
+ // a disabled element, preventDefault fires, focus() is a no-op
89
+ // and Tab appears dead. Dead Tab is worse than escaping Tab.
90
+ // `iframe` is here because an extension *is* one.
91
+ const focusable = panel.current?.querySelectorAll<HTMLElement>(
92
+ [
93
+ "button:not([disabled])",
94
+ "a[href]",
95
+ "input:not([disabled]):not([type=hidden])",
96
+ "select:not([disabled])",
97
+ "textarea:not([disabled])",
98
+ "iframe",
99
+ "summary",
100
+ "[contenteditable]",
101
+ '[tabindex]:not([tabindex="-1"])',
102
+ ].join(", "),
103
+ );
104
+ if (!focusable || focusable.length === 0) {
105
+ // Nothing to move to, so hold the focus here rather than let
106
+ // Tab walk into the page behind a modal with no way back.
107
+ event.preventDefault();
108
+ return;
109
+ }
110
+ const first = focusable[0];
111
+ const last = focusable[focusable.length - 1];
112
+ if (event.shiftKey && document.activeElement === first) {
113
+ event.preventDefault();
114
+ last.focus();
115
+ } else if (!event.shiftKey && document.activeElement === last) {
116
+ event.preventDefault();
117
+ first.focus();
118
+ }
119
+ },
120
+ [onClose],
121
+ );
122
+
123
+ return (
124
+ <div
125
+ className="overlay"
126
+ onMouseDown={(e) => {
127
+ // Primary button only, and only on the backdrop itself, so a
128
+ // right-click raising a context menu leaves the modal open.
129
+ if (e.button === 0 && e.target === e.currentTarget) onClose();
130
+ }}
131
+ >
132
+ <div
133
+ {...rest}
134
+ ref={panel}
135
+ className={cx("dialog", className)}
136
+ role="dialog"
137
+ aria-modal="true"
138
+ // The title is the dialog's accessible name; without it a
139
+ // screen reader announces "dialog" and nothing else.
140
+ aria-labelledby={titleId}
141
+ tabIndex={-1}
142
+ onKeyDown={onKeyDown}
143
+ // Without this a drag that starts inside and ends outside
144
+ // closes the dialog, which eats a selection.
145
+ onMouseDown={(e) => e.stopPropagation()}
146
+ >
147
+ <h2 className="dialog-title" id={titleId}>
148
+ {title}
149
+ </h2>
150
+ {sub ? <p className="dialog-sub">{sub}</p> : null}
151
+ {children}
152
+ {actions ? (
153
+ <Actions className="dialog-actions">{actions}</Actions>
154
+ ) : null}
155
+ </div>
156
+ </div>
157
+ );
158
+ }
@@ -53,6 +53,12 @@ interface State {
53
53
  error: Error | null;
54
54
  }
55
55
 
56
+ // Anything can be thrown. The fallback and `onError` are typed to get an
57
+ // Error, and `null` held as the error would read as "nothing thrown".
58
+ function toError(thrown: unknown): Error {
59
+ return thrown instanceof Error ? thrown : new Error(String(thrown));
60
+ }
61
+
56
62
  function changed(a: readonly unknown[], b: readonly unknown[]): boolean {
57
63
  return a.length !== b.length || a.some((value, i) => !Object.is(value, b[i]));
58
64
  }
@@ -60,20 +66,43 @@ function changed(a: readonly unknown[], b: readonly unknown[]): boolean {
60
66
  /**
61
67
  * What is shown where a subtree threw.
62
68
  *
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.
69
+ * It catches less than people expect: render, lifecycle and
70
+ * constructor throws in the subtree below it, and not event handlers,
71
+ * `setTimeout`, promise rejections or anything during SSR. The default
72
+ * fallback shows the error's message on purpose.
65
73
  */
66
74
  export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
75
+ /**
76
+ * The error the subtree threw, or null while nothing has thrown.
77
+ */
67
78
  state: State = { error: null };
68
79
 
80
+ /**
81
+ * The state the boundary holds after a throw.
82
+ *
83
+ * @param error — the error the subtree threw.
84
+ */
69
85
  static getDerivedStateFromError(error: Error): State {
70
- return { error };
86
+ return { error: toError(error) };
71
87
  }
72
88
 
89
+ /**
90
+ * Reports the error to whoever asked for it.
91
+ *
92
+ * @param error — the error the subtree threw.
93
+ * @param info — React's account of where it was thrown: the component
94
+ * stack.
95
+ */
73
96
  componentDidCatch(error: Error, info: ErrorInfo): void {
74
- this.props.onError?.(error, info);
97
+ this.props.onError?.(toError(error), info);
75
98
  }
76
99
 
100
+ /**
101
+ * Clears the boundary when the reset keys change.
102
+ *
103
+ * @param previous — the props from the previous render, whose
104
+ * `resetKeys` are compared with the new ones.
105
+ */
77
106
  componentDidUpdate(previous: ErrorBoundaryProps): void {
78
107
  if (this.state.error === null) return;
79
108
  const before = previous.resetKeys ?? [];
@@ -81,10 +110,16 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
81
110
  if (changed(before, now)) this.reset();
82
111
  }
83
112
 
113
+ /**
114
+ * Clears the error and renders the children again.
115
+ */
84
116
  reset = (): void => {
85
117
  this.setState({ error: null });
86
118
  };
87
119
 
120
+ /**
121
+ * The children, or the error page when the subtree threw.
122
+ */
88
123
  render(): ReactNode {
89
124
  const { error } = this.state;
90
125
  if (error === null) return this.props.children;
@@ -101,7 +101,13 @@ export interface LiveRegionProps {
101
101
  *
102
102
  * `<LiveRegion>{`${n} results`}</LiveRegion>` is the whole usage.
103
103
  * Mounted empty on the first render so the region exists before it
104
- * has anything to say — see note 1 above.
104
+ * has anything to say: a live region added to the page with its
105
+ * message already in it is frequently not announced.
106
+ *
107
+ * @param children — what to say; changing it announces, and clearing it
108
+ * says nothing.
109
+ * @param urgency — how insistently it is announced: politely, or
110
+ * assertively.
105
111
  */
106
112
  export function LiveRegion({ children = "", urgency = "polite" }: LiveRegionProps) {
107
113
  const [text, setText] = useState("");
package/src/Markdown.tsx CHANGED
@@ -59,6 +59,10 @@ export interface MarkdownProps {
59
59
  * enabled and will not be — `rehype-raw` in a surface that renders
60
60
  * text somebody else wrote is a script tag waiting to happen, and an
61
61
  * extension's frame has a CSP precisely so that it cannot.
62
+ *
63
+ * @param children — the source; rendered as a document, not flattened.
64
+ * @param className — added to the element's classes, beside the one the
65
+ * theme gives it.
62
66
  */
63
67
  export function Markdown({ children, className }: MarkdownProps) {
64
68
  return (
@@ -123,10 +123,19 @@ export function dropEchoedTitle(text: string, name: string): string {
123
123
  /**
124
124
  * Markdown rendered as one flowing line of text.
125
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.
126
+ * Every block becomes inline: headings keep their emphasis but not
127
+ * their size, list items are separated by middots, tables flatten to
128
+ * their cells, and links and images are dropped to their text or to
129
+ * nothing. `limit` bounds the work, not the appearance: the clamp is
130
+ * visual, and a document longer than `limit` is cut with an ellipsis,
131
+ * back to a word boundary when one falls in the last 40% of it.
132
+ *
133
+ * @param text — the markdown to render as one flowing line.
134
+ * @param name — the document's name, so a title echo can be dropped.
135
+ * @param limit — characters to keep; the clamp is visual, and this
136
+ * bounds the work.
137
+ * @param className — added to the element's classes, beside the one the
138
+ * theme gives it.
130
139
  */
131
140
  export function MarkdownInline({
132
141
  text,
@@ -147,9 +156,13 @@ export function MarkdownInline({
147
156
  // Cut back to a space so the preview does not end mid-word.
148
157
  const cut = body.slice(0, limit);
149
158
  const space = cut.lastIndexOf(" ");
150
- return (
151
- closeOpenMarks(space > limit * 0.6 ? cut.slice(0, space) : cut) + "…"
152
- );
159
+ const kept = space > limit * 0.6 ? cut.slice(0, space) : cut;
160
+ // Inside an unclosed fence the ellipsis goes in before the repair:
161
+ // after it, the closing fence would read "```…", which is not one.
162
+ if ((kept.match(/^```/gm) ?? []).length % 2 === 1) {
163
+ return closeOpenMarks(kept + "…");
164
+ }
165
+ return closeOpenMarks(kept) + "…";
153
166
  }, [text, name, limit]);
154
167
 
155
168
  if (!source.trim()) return null;
package/src/MenuIcon.tsx CHANGED
@@ -14,8 +14,8 @@
14
14
  * the single most obvious way to make a menu look assembled from
15
15
  * parts.
16
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
17
+ * Inline rather than a sprite or a font: these are small paths used
18
+ * in a few menus, and a build step, a network request or a font with
19
19
  * a flash of missing glyphs are all more machinery than the problem
20
20
  * has.
21
21
  */
@@ -179,10 +179,16 @@ export interface MenuIconProps {
179
179
  /**
180
180
  * One of igni's own icons, drawn on a 16×16 grid.
181
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
182
+ * Every icon is drawn in one grammar: 16×16, strokes of the same
183
+ * weight, `currentColor`. A name that is not in the set draws nothing, rather
184
184
  * than a broken box: the label says what the item does, and the icon
185
185
  * is only how it is found.
186
+ *
187
+ * @param name — one of igni's own icons.
188
+ * @param path — an SVG path, for an icon igni does not have; it is
189
+ * drawn on the same 16×16 grid, stroked rather than filled.
190
+ * @param className — added to the element's classes, beside the one the
191
+ * theme gives it.
186
192
  */
187
193
  export function MenuIcon({ name, path, className }: MenuIconProps) {
188
194
  const d = path ?? (name ? PATHS[name] : undefined);
package/src/Mermaid.tsx CHANGED
@@ -100,6 +100,8 @@ export async function loadMermaid(): Promise<MermaidLib> {
100
100
  * `source` is the text inside the fence. A diagram that does not
101
101
  * parse is shown as its own source rather than as a blank box: it is
102
102
  * usually a diagram somebody is halfway through writing.
103
+ *
104
+ * @param source — the text inside the fence.
103
105
  */
104
106
  export function MermaidBlock({ source }: { source: string }) {
105
107
  const frame = useRef<HTMLDivElement>(null);
package/src/Monogram.tsx CHANGED
@@ -23,8 +23,13 @@ export function initialsOf(name: string): string {
23
23
  const local = cleaned.includes("@") ? cleaned.split("@")[0] : cleaned;
24
24
  const words = local.split(/[\s._-]+/).filter(Boolean);
25
25
  if (words.length === 0) return "?";
26
- if (words.length === 1) return words[0].slice(0, 2).toUpperCase();
27
- return (words[0][0] + words[words.length - 1][0]).toUpperCase();
26
+ // By code point: slicing by UTF-16 unit cuts an emoji in half.
27
+ const letters = (word: string) => Array.from(word);
28
+ if (words.length === 1) {
29
+ return letters(words[0]).slice(0, 2).join("").toUpperCase();
30
+ }
31
+ const last = words[words.length - 1];
32
+ return (letters(words[0])[0] + letters(last)[0]).toUpperCase();
28
33
  }
29
34
 
30
35
  /** A stable hue for a name. Same person, same colour, every time. */
@@ -77,9 +82,13 @@ export function hexOf(
77
82
  /**
78
83
  * Two letters standing in for a face.
79
84
  *
80
- * See the note at the top of this file. The colour comes from the
81
- * name, so the same person is the same colour on every machine and
82
- * across restarts.
85
+ * Not an avatar: nothing stores an uploaded picture, so the two
86
+ * letters come from the name. The colour comes from the name too, so
87
+ * the same person is the same colour on every machine and across
88
+ * restarts.
89
+ *
90
+ * @param name — the name the initials and the colour are derived from.
91
+ * @param size — the width and height of the square, in pixels.
83
92
  */
84
93
  export function Monogram({ name, size = 18 }: { name: string; size?: number }) {
85
94
  const hue = hueOf(name);
@@ -70,9 +70,14 @@ function moveFocus(root: HTMLElement | null, key: string): boolean {
70
70
  /**
71
71
  * A row of actions collapsed behind one button.
72
72
  *
73
- * See the note at the top of this file. Everything that made the
73
+ * For actions that are real but secondary. Everything that made the
74
74
  * buttons usable as buttons survives the move: focus, the keyboard,
75
75
  * and the names screen readers announce.
76
+ *
77
+ * @param actions — the actions to offer; the destructive ones are set
78
+ * apart from the rest.
79
+ * @param label — what the trigger is called, for anyone who cannot see
80
+ * three dots.
76
81
  */
77
82
  export function OverflowMenu({
78
83
  actions,
@@ -222,7 +227,9 @@ function Submenu({
222
227
  // Hover opens it, the way a desktop menu does. `onMouseLeave`
223
228
  // rather than a timer: a submenu that lingers after the pointer
224
229
  // has gone covers the items below the one that opened it.
225
- onMouseEnter={() => setOpen(true)}
230
+ onMouseEnter={() => {
231
+ if (!action.disabled) setOpen(true);
232
+ }}
226
233
  onMouseLeave={() => setOpen(false)}
227
234
  >
228
235
  <button
package/src/Shell.tsx CHANGED
@@ -35,6 +35,13 @@ export interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
35
35
  *
36
36
  * The body is a flex column itself, so a `Scroll` placed directly
37
37
  * inside it fills what is left over rather than the whole frame.
38
+ *
39
+ * @param header — fixed at the top; a `Toolbar`, usually.
40
+ * @param footer — fixed at the bottom: status, or a form's actions.
41
+ * @param children — the body, the one part allowed to grow.
42
+ * @param className — added to the element's classes, beside the one the
43
+ * theme gives it.
44
+ * @param rest — the remaining props, spread onto the shell.
38
45
  */
39
46
  export function AppShell({
40
47
  header,
@@ -75,6 +82,12 @@ export interface ScrollProps extends HTMLAttributes<HTMLDivElement> {
75
82
  * `tabIndex={0}` when that is the case; doing it unconditionally
76
83
  * would put a stop in the tab order of every list that already has
77
84
  * buttons in it.
85
+ *
86
+ * @param axis — scroll sideways instead; for a wide table, not a long
87
+ * list.
88
+ * @param className — added to the element's classes, beside the one the
89
+ * theme gives it.
90
+ * @param rest — the remaining props, spread onto the element.
78
91
  */
79
92
  export function Scroll({ axis = "y", className, ...rest }: ScrollProps) {
80
93
  return (
package/src/Skeleton.tsx CHANGED
@@ -11,6 +11,14 @@ import type { CSSProperties } from "react";
11
11
  * <Skeleton.Circle size={48} />
12
12
  */
13
13
  export const Skeleton = {
14
+ /**
15
+ * A line of placeholder text, the size of the line it stands in for.
16
+ *
17
+ * @param width — how wide the line is, in pixels or as a CSS length.
18
+ * @param height — how tall the line is, in pixels or as a CSS length.
19
+ * @param style — the element's inline style, merged over the
20
+ * defaults.
21
+ */
14
22
  Line({
15
23
  width = "100%",
16
24
  height = 12,
@@ -27,6 +35,15 @@ export const Skeleton = {
27
35
  />
28
36
  );
29
37
  },
38
+ /**
39
+ * A block of placeholder content, the size of the content it stands in for.
40
+ *
41
+ * @param height — how tall the block is, in pixels or as a CSS
42
+ * length.
43
+ * @param width — how wide the block is, in pixels or as a CSS length.
44
+ * @param style — the element's inline style, merged over the
45
+ * defaults.
46
+ */
30
47
  Block({
31
48
  height = 64,
32
49
  width = "100%",
@@ -43,6 +60,13 @@ export const Skeleton = {
43
60
  />
44
61
  );
45
62
  },
63
+ /**
64
+ * A circle, the size of the thing it stands in for.
65
+ *
66
+ * @param size — the diameter of the circle, in pixels.
67
+ * @param style — the element's inline style, merged over the
68
+ * defaults.
69
+ */
46
70
  Circle({ size = 24, style }: { size?: number; style?: CSSProperties }) {
47
71
  return (
48
72
  <span
@@ -51,6 +75,12 @@ export const Skeleton = {
51
75
  />
52
76
  );
53
77
  },
78
+ /**
79
+ * Several lines of placeholder text, the shape of the list they stand in for.
80
+ *
81
+ * @param count — how many rows of text to draw.
82
+ * @param style — the stack's inline style, merged over the defaults.
83
+ */
54
84
  Rows({ count = 4, style }: { count?: number; style?: CSSProperties }) {
55
85
  return (
56
86
  <div
package/src/Split.tsx CHANGED
@@ -79,9 +79,11 @@ export interface SplitProps extends Omit<
79
79
  */
80
80
  label: string;
81
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.
82
+ * The width changed. Called on release, on each keypress and on a
83
+ * double-click back to `defaultWidth`, not on every pointer move.
84
+ *
85
+ * A handler that fires sixty times a second is a handler somebody
86
+ * writes a round trip into.
85
87
  */
86
88
  onResize?: (width: number) => void;
87
89
  }
@@ -89,8 +91,25 @@ export interface SplitProps extends Omit<
89
91
  /**
90
92
  * Two panes and a rule you can move.
91
93
  *
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
+ * It drives a CSS variable rather than React state, and it does not
95
+ * remember the width: `onResize` hands the width back, and an
96
+ * extension that wants it kept stores it somewhere that survives a
97
+ * restart (`bridge.setLocation`, or its own backend).
98
+ *
99
+ * @param aside — the fixed-width pane.
100
+ * @param children — the pane that takes what is left.
101
+ * @param side — which side `aside` is on; the left by default.
102
+ * @param defaultWidth — the starting width of `aside`, in pixels.
103
+ * @param min — the narrowest `aside` may be, in pixels.
104
+ * @param max — the widest `aside` may be, in pixels, and never more
105
+ * than 60% of the window.
106
+ * @param label — said to a screen reader, and shown on hover.
107
+ * @param onResize — the width changed; called on release, on each
108
+ * keypress and on a double-click back to `defaultWidth`, not on every
109
+ * pointer move.
110
+ * @param className — added to the element's classes, beside the one the
111
+ * theme gives it.
112
+ * @param rest — the remaining props, spread onto the element.
94
113
  */
95
114
  export function Split({
96
115
  aside,
@@ -184,7 +203,10 @@ export function Split({
184
203
  else if (event.key === "End") next = max;
185
204
  if (next === null) return;
186
205
  event.preventDefault();
187
- onResize?.(apply(next));
206
+ // Applied first: `onResize?.(apply(next))` skips the argument
207
+ // when there is no `onResize`, and the pane never moved.
208
+ const width = apply(next);
209
+ onResize?.(width);
188
210
  };
189
211
 
190
212
  const handle = (
@@ -206,7 +228,10 @@ export function Split({
206
228
  onKeyDown={onKeyDown}
207
229
  // Back to where it started. A pane dragged somewhere silly is
208
230
  // otherwise a slow drag back to a width nobody remembers.
209
- onDoubleClick={() => onResize?.(apply(defaultWidth))}
231
+ onDoubleClick={() => {
232
+ const width = apply(defaultWidth);
233
+ onResize?.(width);
234
+ }}
210
235
  />
211
236
  );
212
237