react-cheminfo 0.127.0 → 0.129.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 (151) hide show
  1. package/README.md +79 -43
  2. package/lib/drawing/core/camera.d.ts +22 -0
  3. package/lib/drawing/core/camera.d.ts.map +1 -1
  4. package/lib/drawing/core/camera.js +37 -0
  5. package/lib/drawing/core/camera.js.map +1 -1
  6. package/lib/drawing/core/graphics.d.ts.map +1 -1
  7. package/lib/drawing/core/graphics.js +2 -10
  8. package/lib/drawing/core/graphics.js.map +1 -1
  9. package/lib/drawing/core/groupFiles.d.ts +22 -0
  10. package/lib/drawing/core/groupFiles.d.ts.map +1 -0
  11. package/lib/drawing/core/groupFiles.js +51 -0
  12. package/lib/drawing/core/groupFiles.js.map +1 -0
  13. package/lib/drawing/core/groups.d.ts +76 -0
  14. package/lib/drawing/core/groups.d.ts.map +1 -0
  15. package/lib/drawing/core/groups.js +190 -0
  16. package/lib/drawing/core/groups.js.map +1 -0
  17. package/lib/drawing/core/index.d.ts +7 -2
  18. package/lib/drawing/core/index.d.ts.map +1 -1
  19. package/lib/drawing/core/index.js +5 -2
  20. package/lib/drawing/core/index.js.map +1 -1
  21. package/lib/drawing/core/selectionFrame.d.ts +70 -0
  22. package/lib/drawing/core/selectionFrame.d.ts.map +1 -0
  23. package/lib/drawing/core/selectionFrame.js +156 -0
  24. package/lib/drawing/core/selectionFrame.js.map +1 -0
  25. package/lib/drawing/core/transform.d.ts +30 -0
  26. package/lib/drawing/core/transform.d.ts.map +1 -1
  27. package/lib/drawing/core/transform.js +59 -0
  28. package/lib/drawing/core/transform.js.map +1 -1
  29. package/lib/drawing/ui/FrameMarks.d.ts +30 -0
  30. package/lib/drawing/ui/FrameMarks.d.ts.map +1 -0
  31. package/lib/drawing/ui/FrameMarks.js +19 -0
  32. package/lib/drawing/ui/FrameMarks.js.map +1 -0
  33. package/lib/drawing/ui/curveHandleMarks.d.ts +10 -0
  34. package/lib/drawing/ui/curveHandleMarks.d.ts.map +1 -1
  35. package/lib/drawing/ui/curveHandleMarks.js +20 -2
  36. package/lib/drawing/ui/curveHandleMarks.js.map +1 -1
  37. package/lib/drawing/ui/index.d.ts +5 -1
  38. package/lib/drawing/ui/index.d.ts.map +1 -1
  39. package/lib/drawing/ui/index.js +3 -1
  40. package/lib/drawing/ui/index.js.map +1 -1
  41. package/lib/drawing/ui/useCanvasNavigation.d.ts +35 -0
  42. package/lib/drawing/ui/useCanvasNavigation.d.ts.map +1 -0
  43. package/lib/drawing/ui/useCanvasNavigation.js +95 -0
  44. package/lib/drawing/ui/useCanvasNavigation.js.map +1 -0
  45. package/lib/i18n/core/chromeCatalog.d.ts +1 -1
  46. package/lib/i18n/core/chromeCatalog.d.ts.map +1 -1
  47. package/lib/ir/ui/BandsPanel.d.ts +3 -3
  48. package/lib/ir/ui/BandsPanel.d.ts.map +1 -1
  49. package/lib/ir/ui/BandsPanel.js +7 -7
  50. package/lib/ir/ui/BandsPanel.js.map +1 -1
  51. package/lib/ir/ui/BandsToolbar.d.ts.map +1 -1
  52. package/lib/ir/ui/BandsToolbar.js +2 -4
  53. package/lib/ir/ui/BandsToolbar.js.map +1 -1
  54. package/lib/ir/ui/IrEditor.d.ts +7 -0
  55. package/lib/ir/ui/IrEditor.d.ts.map +1 -1
  56. package/lib/ir/ui/IrEditor.js.map +1 -1
  57. package/lib/ir/ui/IrShell.d.ts.map +1 -1
  58. package/lib/ir/ui/IrShell.js +3 -2
  59. package/lib/ir/ui/IrShell.js.map +1 -1
  60. package/lib/ir/ui/IrStatusBar.js +2 -2
  61. package/lib/ir/ui/IrStatusBar.js.map +1 -1
  62. package/lib/ir/ui/IrToolbar.js +2 -2
  63. package/lib/ir/ui/IrToolbar.js.map +1 -1
  64. package/lib/ir/ui/VibrationalEditor.d.ts +7 -0
  65. package/lib/ir/ui/VibrationalEditor.d.ts.map +1 -1
  66. package/lib/ir/ui/VibrationalEditor.js +2 -1
  67. package/lib/ir/ui/VibrationalEditor.js.map +1 -1
  68. package/lib/ir/ui/useIrEditor.d.ts +12 -0
  69. package/lib/ir/ui/useIrEditor.d.ts.map +1 -1
  70. package/lib/ir/ui/useIrEditor.js +10 -3
  71. package/lib/ir/ui/useIrEditor.js.map +1 -1
  72. package/lib/locales/de.json +9 -0
  73. package/lib/locales/en.json +9 -0
  74. package/lib/locales/es.json +9 -0
  75. package/lib/locales/fr.json +9 -0
  76. package/lib/locales/it.json +9 -0
  77. package/lib/pedagogy/ui/ExerciseActions.d.ts +10 -2
  78. package/lib/pedagogy/ui/ExerciseActions.d.ts.map +1 -1
  79. package/lib/pedagogy/ui/ExerciseActions.js +7 -5
  80. package/lib/pedagogy/ui/ExerciseActions.js.map +1 -1
  81. package/lib/share/core/exampleMark.d.ts +31 -0
  82. package/lib/share/core/exampleMark.d.ts.map +1 -0
  83. package/lib/share/core/exampleMark.js +31 -0
  84. package/lib/share/core/exampleMark.js.map +1 -0
  85. package/lib/share/core/index.d.ts +5 -0
  86. package/lib/share/core/index.d.ts.map +1 -1
  87. package/lib/share/core/index.js +3 -0
  88. package/lib/share/core/index.js.map +1 -1
  89. package/lib/share/core/linkBytes.d.ts +29 -0
  90. package/lib/share/core/linkBytes.d.ts.map +1 -0
  91. package/lib/share/core/linkBytes.js +70 -0
  92. package/lib/share/core/linkBytes.js.map +1 -0
  93. package/lib/share/core/linkValue.d.ts +34 -0
  94. package/lib/share/core/linkValue.d.ts.map +1 -0
  95. package/lib/share/core/linkValue.js +58 -0
  96. package/lib/share/core/linkValue.js.map +1 -0
  97. package/lib/share/core/opensOn.d.ts +133 -0
  98. package/lib/share/core/opensOn.d.ts.map +1 -0
  99. package/lib/share/core/opensOn.js +82 -0
  100. package/lib/share/core/opensOn.js.map +1 -0
  101. package/lib/share/core/seal.d.ts.map +1 -1
  102. package/lib/share/core/seal.js +3 -32
  103. package/lib/share/core/seal.js.map +1 -1
  104. package/lib/share/ui/ShareOpensOn.d.ts +32 -0
  105. package/lib/share/ui/ShareOpensOn.d.ts.map +1 -0
  106. package/lib/share/ui/ShareOpensOn.js +49 -0
  107. package/lib/share/ui/ShareOpensOn.js.map +1 -0
  108. package/lib/share/ui/index.d.ts +4 -0
  109. package/lib/share/ui/index.d.ts.map +1 -1
  110. package/lib/share/ui/index.js +2 -0
  111. package/lib/share/ui/index.js.map +1 -1
  112. package/lib/share/ui/useOpensOnShare.d.ts +65 -0
  113. package/lib/share/ui/useOpensOnShare.d.ts.map +1 -0
  114. package/lib/share/ui/useOpensOnShare.js +60 -0
  115. package/lib/share/ui/useOpensOnShare.js.map +1 -0
  116. package/package.json +1 -1
  117. package/src/drawing/core/camera.ts +45 -0
  118. package/src/drawing/core/graphics.ts +2 -12
  119. package/src/drawing/core/groupFiles.ts +55 -0
  120. package/src/drawing/core/groups.ts +221 -0
  121. package/src/drawing/core/index.ts +29 -1
  122. package/src/drawing/core/selectionFrame.ts +192 -0
  123. package/src/drawing/core/transform.ts +80 -0
  124. package/src/drawing/ui/FrameMarks.tsx +57 -0
  125. package/src/drawing/ui/curveHandleMarks.tsx +43 -10
  126. package/src/drawing/ui/index.ts +8 -1
  127. package/src/drawing/ui/useCanvasNavigation.ts +120 -0
  128. package/src/ir/ui/BandsPanel.tsx +15 -10
  129. package/src/ir/ui/BandsToolbar.tsx +2 -4
  130. package/src/ir/ui/IrEditor.tsx +7 -0
  131. package/src/ir/ui/IrShell.tsx +4 -2
  132. package/src/ir/ui/IrStatusBar.tsx +2 -2
  133. package/src/ir/ui/IrToolbar.tsx +2 -2
  134. package/src/ir/ui/VibrationalEditor.tsx +9 -0
  135. package/src/ir/ui/useIrEditor.ts +23 -4
  136. package/src/locales/de.json +9 -0
  137. package/src/locales/en.json +9 -0
  138. package/src/locales/es.json +9 -0
  139. package/src/locales/fr.json +9 -0
  140. package/src/locales/it.json +9 -0
  141. package/src/pedagogy/ui/ExerciseActions.tsx +22 -7
  142. package/src/share/core/exampleMark.ts +52 -0
  143. package/src/share/core/index.ts +25 -0
  144. package/src/share/core/linkBytes.ts +75 -0
  145. package/src/share/core/linkValue.ts +66 -0
  146. package/src/share/core/opensOn.ts +203 -0
  147. package/src/share/core/seal.ts +3 -36
  148. package/src/share/ui/ShareOpensOn.tsx +169 -0
  149. package/src/share/ui/index.ts +7 -0
  150. package/src/share/ui/useOpensOnShare.tsx +152 -0
  151. package/styles/chrome.css +18 -0
@@ -0,0 +1,203 @@
1
+ /**
2
+ * What a link to a page holding a document opens on: what is on screen, one
3
+ * of the examples the site comes with, or the page alone. A site whose folder
4
+ * panel lists examples lets its Share dialog hand out any of them, so a link
5
+ * to an example can always be made, whatever is on screen.
6
+ */
7
+
8
+ import type { QueryEntry } from '../../router/core/query.ts';
9
+ import {
10
+ formatQueryEntries,
11
+ parseQueryEntries,
12
+ } from '../../router/core/query.ts';
13
+
14
+ /** The parameter naming the example a link opens on, on every site. */
15
+ export const EXAMPLE_PARAM = 'example';
16
+
17
+ /** What a link opens the page on. */
18
+ export type OpensOnTarget = 'screen' | 'example' | 'none';
19
+
20
+ /** An example a link can open on, as the folder panel lists it. */
21
+ export interface ShareExample {
22
+ /** Its identifier. */
23
+ id: string;
24
+ /** Its name. */
25
+ name: string;
26
+ /**
27
+ * What it shows, in a few words.
28
+ * @default undefined — its name alone
29
+ */
30
+ description?: string;
31
+ /**
32
+ * The group the picker lists it under: its field, its family.
33
+ * @default undefined — no group
34
+ */
35
+ group?: string;
36
+ }
37
+
38
+ /** Where a link goes, beyond the parameters the page keeps. */
39
+ export interface ShareAddress {
40
+ /** The parameters it adds. */
41
+ entries: readonly QueryEntry[];
42
+ /**
43
+ * The page it opens, as a path from the origin.
44
+ * @default undefined — the page on screen
45
+ */
46
+ path?: string;
47
+ }
48
+
49
+ /** What is on screen, as a link carries it, or why it cannot. */
50
+ export type ScreenLink = ShareAddress | 'too-large';
51
+
52
+ /** How a site writes a link to an example, and to the page alone. */
53
+ export interface OpensOnAddresses {
54
+ /**
55
+ * The link to an example.
56
+ * @default `?example=<id>` on the page on screen
57
+ */
58
+ example?: (id: string) => ShareAddress;
59
+ /**
60
+ * The link to the page alone.
61
+ * @default the page on screen, with nothing added
62
+ */
63
+ alone?: ShareAddress;
64
+ }
65
+
66
+ /** What is on screen as the Share dialog opens. */
67
+ export interface ShareOnScreen {
68
+ /**
69
+ * The example the page opened on, changed since or not.
70
+ * @default null — none
71
+ */
72
+ example?: string | null;
73
+ /**
74
+ * Whether what is on screen has changed since that example opened.
75
+ * @default false
76
+ */
77
+ changed?: boolean;
78
+ /**
79
+ * What is on screen, as a link carries it.
80
+ * @default undefined — nothing is on screen, or the site writes no
81
+ * document into its links
82
+ */
83
+ screen?: ScreenLink;
84
+ }
85
+
86
+ /** What the Share dialog can hand out for the page on screen. */
87
+ export interface OpensOnLinks {
88
+ /** The page's own query string, what it opened on left out. */
89
+ search: string;
90
+ /** The example the page opened on, or `null`. */
91
+ example: string | null;
92
+ /** Whether what is on screen has changed since that example opened. */
93
+ changed: boolean;
94
+ /**
95
+ * What is on screen, as a link carries it: `undefined` when nothing is,
96
+ * and for an example still as it opened, which the link names instead.
97
+ */
98
+ screen: ScreenLink | undefined;
99
+ }
100
+
101
+ /** What the link opens on, and which example. */
102
+ export interface OpensOnChoice {
103
+ /** What the link opens the page on. */
104
+ opensOn: OpensOnTarget;
105
+ /** The example the link names when it opens on one. */
106
+ example: string;
107
+ }
108
+
109
+ /**
110
+ * What the Share dialog can hand out for the page on screen.
111
+ * @param search - The query string of the page.
112
+ * @param openedOn - The parameters naming what a page opens on, which a link
113
+ * replaces: the example, and whatever carries a document.
114
+ * @param onScreen - What is on screen.
115
+ * @returns The links.
116
+ */
117
+ export function opensOnLinks(
118
+ search: string,
119
+ openedOn: readonly string[],
120
+ onScreen: ShareOnScreen,
121
+ ): OpensOnLinks {
122
+ const kept = parseQueryEntries(search).filter(
123
+ ([key]) => !openedOn.includes(key),
124
+ );
125
+ const example = onScreen.example ?? null;
126
+ const changed = example !== null && (onScreen.changed ?? false);
127
+ return {
128
+ search: formatQueryEntries(kept),
129
+ example,
130
+ changed,
131
+ screen: example !== null && !changed ? undefined : onScreen.screen,
132
+ };
133
+ }
134
+
135
+ /**
136
+ * What the dialog opens on: the example on screen while it is as it opened,
137
+ * else what is on screen when a link can carry it, else the example it was
138
+ * changed from, else the page alone.
139
+ * @param links - What the dialog can hand out.
140
+ * @param examples - The examples a link can open on, in the order they are
141
+ * listed.
142
+ * @returns The choice.
143
+ */
144
+ export function defaultOpensOn(
145
+ links: OpensOnLinks,
146
+ examples: readonly ShareExample[],
147
+ ): OpensOnChoice {
148
+ const listed =
149
+ links.example !== null &&
150
+ examples.some((example) => example.id === links.example);
151
+ const example = listed ? (links.example ?? '') : (examples[0]?.id ?? '');
152
+ if (listed && !links.changed) return { opensOn: 'example', example };
153
+ if (carriedScreen(links.screen)) return { opensOn: 'screen', example };
154
+ return { opensOn: listed ? 'example' : 'none', example };
155
+ }
156
+
157
+ /**
158
+ * The address of a link: the query string, and the page when it is not the
159
+ * page on screen.
160
+ * @param links - What the dialog can hand out.
161
+ * @param choice - What the link opens on.
162
+ * @param addresses - How the site writes a link to an example, and to the
163
+ * page alone.
164
+ * @default {} — `?example=<id>` and the page on screen
165
+ * @returns The query string, and the path or `undefined`.
166
+ */
167
+ export function opensOnAddress(
168
+ links: OpensOnLinks,
169
+ choice: OpensOnChoice,
170
+ addresses: OpensOnAddresses = {},
171
+ ): { search: string; path: string | undefined } {
172
+ const added = addressOf(links, choice, addresses);
173
+ const entries = [...parseQueryEntries(links.search), ...added.entries];
174
+ return { search: formatQueryEntries(entries), path: added.path };
175
+ }
176
+
177
+ /**
178
+ * What is on screen, when a link can carry it.
179
+ * @param screen - What is on screen, as a link carries it.
180
+ * @returns The address, or `undefined` when there is nothing a link carries.
181
+ */
182
+ export function carriedScreen(
183
+ screen: ScreenLink | undefined,
184
+ ): ShareAddress | undefined {
185
+ return screen === undefined || screen === 'too-large' ? undefined : screen;
186
+ }
187
+
188
+ function addressOf(
189
+ links: OpensOnLinks,
190
+ choice: OpensOnChoice,
191
+ addresses: OpensOnAddresses,
192
+ ): ShareAddress {
193
+ const alone = addresses.alone ?? { entries: [] };
194
+ if (choice.opensOn === 'screen') return carriedScreen(links.screen) ?? alone;
195
+ if (choice.opensOn === 'example' && choice.example !== '') {
196
+ return (
197
+ addresses.example?.(choice.example) ?? {
198
+ entries: [[EXAMPLE_PARAM, choice.example]],
199
+ }
200
+ );
201
+ }
202
+ return alone;
203
+ }
@@ -1,4 +1,5 @@
1
1
  import { EMBED_PARAM } from './config.ts';
2
+ import { fromBase64Url, pipeBytes, toBase64Url } from './linkBytes.ts';
2
3
  import { firstValues, parseQuery, serializeQuery } from './query.ts';
3
4
 
4
5
  /** The query parameter a sealed link carries, and the only one it carries. */
@@ -44,7 +45,7 @@ const keys = new Map<string, Promise<SealKeys>>();
44
45
  */
45
46
  export async function sealQuery(query: string): Promise<string> {
46
47
  const plain = new TextEncoder().encode(query);
47
- const packed = await transform(plain, new CompressionStream('deflate-raw'));
48
+ const packed = await pipeBytes(plain, new CompressionStream('deflate-raw'));
48
49
  const compressed = packed.length < plain.length;
49
50
  const body = compressed ? packed : plain;
50
51
  const message = new Uint8Array(1 + body.length);
@@ -93,7 +94,7 @@ export async function unsealQuery(token: string): Promise<UnsealResult> {
93
94
  try {
94
95
  const plain =
95
96
  flags === COMPRESSED
96
- ? await transform(body, new DecompressionStream('deflate-raw'))
97
+ ? await pipeBytes(body, new DecompressionStream('deflate-raw'))
97
98
  : body;
98
99
  const query = new TextDecoder('utf-8', { fatal: true }).decode(plain);
99
100
  return { ok: true, query };
@@ -197,37 +198,3 @@ function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
197
198
  }
198
199
  return difference === 0;
199
200
  }
200
-
201
- async function transform(
202
- bytes: Uint8Array<ArrayBuffer>,
203
- stream: CompressionStream | DecompressionStream,
204
- ): Promise<Uint8Array<ArrayBuffer>> {
205
- const source = new ReadableStream<Uint8Array<ArrayBuffer>>({
206
- start(controller) {
207
- controller.enqueue(bytes);
208
- controller.close();
209
- },
210
- });
211
- const output = await new Response(source.pipeThrough(stream)).arrayBuffer();
212
- return new Uint8Array(output);
213
- }
214
-
215
- function toBase64Url(bytes: Uint8Array): string {
216
- let binary = '';
217
- for (const byte of bytes) binary += String.fromCodePoint(byte);
218
- return btoa(binary)
219
- .replaceAll('+', '-')
220
- .replaceAll('/', '_')
221
- .replace(/[=]+$/, '');
222
- }
223
-
224
- function fromBase64Url(text: string): Uint8Array<ArrayBuffer> | null {
225
- if (!/^[\w-]*$/.test(text) || text.length % 4 === 1) return null;
226
- const base64 = text.replaceAll('-', '+').replaceAll('_', '/');
227
- const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='));
228
- const bytes = new Uint8Array(binary.length);
229
- for (let index = 0; index < binary.length; index++) {
230
- bytes[index] = binary.codePointAt(index) ?? 0;
231
- }
232
- return bytes;
233
- }
@@ -0,0 +1,169 @@
1
+ import { H6, HTMLSelect, Radio } from '@blueprintjs/core';
2
+ import type { ReactElement, ReactNode } from 'react';
3
+ import { useId } from 'react';
4
+
5
+ import { useChromeT } from '../../i18n/ui/useT.ts';
6
+ import type {
7
+ OpensOnChoice,
8
+ OpensOnLinks,
9
+ OpensOnTarget,
10
+ ShareExample,
11
+ } from '../core/opensOn.ts';
12
+
13
+ /** Props of {@link ShareOpensOn}. */
14
+ export interface ShareOpensOnProps {
15
+ /** What the dialog can hand out for the page on screen. */
16
+ links: OpensOnLinks;
17
+ /** What the link opens on. */
18
+ choice: OpensOnChoice;
19
+ /** Called with the choice the reader makes. */
20
+ onChange: (choice: OpensOnChoice) => void;
21
+ /** The examples a link can open on, in the order they are listed. */
22
+ examples: readonly ShareExample[];
23
+ /**
24
+ * What the site calls what is on screen: "This circuit", "This drawing".
25
+ * @default the chrome's own words
26
+ */
27
+ screenLabel?: string;
28
+ /**
29
+ * What a site adds under the choice: the style a link sets, say.
30
+ * @default undefined — nothing
31
+ */
32
+ children?: ReactNode;
33
+ }
34
+
35
+ /**
36
+ * The section of the Share dialog saying what the link opens on: what is on
37
+ * screen, when a link can carry it; any of the examples, whatever is on
38
+ * screen; or the page alone.
39
+ * @param props - See {@link ShareOpensOnProps}.
40
+ * @returns The section's content.
41
+ */
42
+ export function ShareOpensOn(props: ShareOpensOnProps): ReactElement {
43
+ const { links, choice, onChange, examples, screenLabel, children } = props;
44
+ const t = useChromeT();
45
+ const group = useId();
46
+ const select = (opensOn: OpensOnTarget) => () => {
47
+ onChange({ ...choice, opensOn });
48
+ };
49
+ const tooLarge = links.screen === 'too-large';
50
+ const shown = examples.find((example) => example.id === choice.example);
51
+ const changed = links.changed && choice.example === links.example;
52
+ return (
53
+ <div
54
+ role="radiogroup"
55
+ aria-label={t('share.opensOn')}
56
+ className="share-opens-on"
57
+ >
58
+ <H6>{t('share.opensOn')}</H6>
59
+ {links.screen === undefined ? null : (
60
+ <Radio
61
+ name={group}
62
+ value="screen"
63
+ checked={choice.opensOn === 'screen'}
64
+ disabled={tooLarge}
65
+ onChange={select('screen')}
66
+ labelElement={
67
+ <Option
68
+ title={screenLabel ?? t('share.opensOnScreen')}
69
+ note={
70
+ tooLarge
71
+ ? t('share.opensOnTooLarge')
72
+ : t('share.opensOnScreenNote')
73
+ }
74
+ />
75
+ }
76
+ />
77
+ )}
78
+ {examples.length === 0 ? null : (
79
+ <>
80
+ <Radio
81
+ name={group}
82
+ value="example"
83
+ checked={choice.opensOn === 'example'}
84
+ onChange={select('example')}
85
+ label={t('share.opensOnExample')}
86
+ />
87
+ <div className="share-opens-on__under">
88
+ <HTMLSelect
89
+ fill
90
+ aria-label={t('share.opensOnExampleLabel')}
91
+ value={choice.example}
92
+ onChange={(event) => {
93
+ onChange({ opensOn: 'example', example: event.target.value });
94
+ }}
95
+ >
96
+ <ExampleOptions examples={examples} />
97
+ </HTMLSelect>
98
+ {shown?.description ? (
99
+ <span className="share-opens-on__note">{shown.description}</span>
100
+ ) : null}
101
+ {changed ? (
102
+ <span className="share-opens-on__note">
103
+ {t('share.opensOnChanged')}
104
+ </span>
105
+ ) : null}
106
+ </div>
107
+ </>
108
+ )}
109
+ <Radio
110
+ name={group}
111
+ value="none"
112
+ checked={choice.opensOn === 'none'}
113
+ onChange={select('none')}
114
+ labelElement={
115
+ <Option
116
+ title={t('share.opensOnNone')}
117
+ note={t('share.opensOnNoneNote')}
118
+ />
119
+ }
120
+ />
121
+ {children}
122
+ </div>
123
+ );
124
+ }
125
+
126
+ // The title in a span of its own, so it is what a click on the words finds.
127
+ function Option(props: { title: string; note: string }): ReactElement {
128
+ return (
129
+ <>
130
+ <span className="share-opens-on__title">{props.title}</span>
131
+ <span className="share-opens-on__note">{props.note}</span>
132
+ </>
133
+ );
134
+ }
135
+
136
+ // Listed under their groups when they have any, in the order they come.
137
+ function ExampleOptions(props: {
138
+ examples: readonly ShareExample[];
139
+ }): ReactElement {
140
+ const groups = new Map<string, ShareExample[]>();
141
+ const loose: ShareExample[] = [];
142
+ for (const example of props.examples) {
143
+ if (example.group === undefined) {
144
+ loose.push(example);
145
+ continue;
146
+ }
147
+ const group = groups.get(example.group);
148
+ if (group) group.push(example);
149
+ else groups.set(example.group, [example]);
150
+ }
151
+ return (
152
+ <>
153
+ {loose.map((example) => (
154
+ <option key={example.id} value={example.id}>
155
+ {example.name}
156
+ </option>
157
+ ))}
158
+ {[...groups].map(([label, members]) => (
159
+ <optgroup key={label} label={label}>
160
+ {members.map((example) => (
161
+ <option key={example.id} value={example.id}>
162
+ {example.name}
163
+ </option>
164
+ ))}
165
+ </optgroup>
166
+ ))}
167
+ </>
168
+ );
169
+ }
@@ -9,6 +9,13 @@ export type { ShareButtonProps, ShareButtonVariant } from './ShareButton.tsx';
9
9
  export { ShareButton } from './ShareButton.tsx';
10
10
  export type { ShareDialogProps } from './ShareDialog.tsx';
11
11
  export type { SharePartDescriptions } from './SharePartRow.tsx';
12
+ export type { ShareOpensOnProps } from './ShareOpensOn.tsx';
13
+ export { ShareOpensOn } from './ShareOpensOn.tsx';
12
14
  export type { ShareQrCodeProps } from './ShareQrCode.tsx';
13
15
  export { ShareQrCode } from './ShareQrCode.tsx';
14
16
  export { ShareDialog } from './ShareDialog.tsx';
17
+ export type {
18
+ OpensOnShareOptions,
19
+ OpensOnShareProps,
20
+ } from './useOpensOnShare.tsx';
21
+ export { useOpensOnShare } from './useOpensOnShare.tsx';
@@ -0,0 +1,152 @@
1
+ import type { ReactNode } from 'react';
2
+ import { useRef, useState } from 'react';
3
+
4
+ import type {
5
+ OpensOnChoice,
6
+ OpensOnLinks,
7
+ ShareAddress,
8
+ ShareExample,
9
+ ShareOnScreen,
10
+ } from '../core/opensOn.ts';
11
+ import {
12
+ EXAMPLE_PARAM,
13
+ defaultOpensOn,
14
+ opensOnAddress,
15
+ opensOnLinks,
16
+ } from '../core/opensOn.ts';
17
+
18
+ import { ShareOpensOn } from './ShareOpensOn.tsx';
19
+
20
+ /** What {@link useOpensOnShare} is told of the page. */
21
+ export interface OpensOnShareOptions {
22
+ /**
23
+ * Whether the page holding the document is the page on show. Any other page
24
+ * hands out its own address.
25
+ */
26
+ active: boolean;
27
+ /** The examples a link can open on, in the order the folder lists them. */
28
+ examples: readonly ShareExample[];
29
+ /**
30
+ * What is on screen, read as the dialog opens. A promise when writing it
31
+ * into a link takes a moment: the dialog then opens once it is written.
32
+ */
33
+ onScreen: () => ShareOnScreen | Promise<ShareOnScreen>;
34
+ /**
35
+ * The parameters naming what a page opens on, besides `example`, which a
36
+ * link replaces: the one carrying a document, say.
37
+ * @default [] — `example` alone
38
+ */
39
+ openedOn?: readonly string[];
40
+ /**
41
+ * The link to an example.
42
+ * @default `?example=<id>` on the page on screen
43
+ */
44
+ exampleAddress?: (id: string) => ShareAddress;
45
+ /**
46
+ * The link to the page alone.
47
+ * @default the page on screen, with nothing added
48
+ */
49
+ aloneAddress?: ShareAddress;
50
+ /**
51
+ * What the site calls what is on screen: "This circuit", "This drawing".
52
+ * @default the chrome's own words
53
+ */
54
+ screenLabel?: string;
55
+ /**
56
+ * What a site adds under the choice: the style a link sets, say.
57
+ * @default undefined — nothing
58
+ */
59
+ children?: ReactNode;
60
+ }
61
+
62
+ /** What the header's Share control is told, beyond what every page shares. */
63
+ export interface OpensOnShareProps {
64
+ /** Whether the dialog is open. */
65
+ open: boolean;
66
+ /** Called when the dialog opens or closes. */
67
+ onOpenChange: (open: boolean) => void;
68
+ /** The query string the link is built from. */
69
+ search: string | undefined;
70
+ /** The page the link opens, when it is not the page on screen. */
71
+ baseUrl: string | undefined;
72
+ /** The section saying what the link opens on. */
73
+ children: ReactNode;
74
+ }
75
+
76
+ /**
77
+ * The Share dialog of a page holding a document says what the link opens on:
78
+ * what is on screen, any of the examples the site comes with, or the page
79
+ * alone. Spread it into the header's `share` prop.
80
+ * @param options - See {@link OpensOnShareOptions}.
81
+ * @returns What the header's Share control is told.
82
+ */
83
+ export function useOpensOnShare(
84
+ options: OpensOnShareOptions,
85
+ ): OpensOnShareProps {
86
+ const {
87
+ active,
88
+ examples,
89
+ onScreen,
90
+ exampleAddress,
91
+ aloneAddress,
92
+ screenLabel,
93
+ children,
94
+ } = options;
95
+ const openedOn = [EXAMPLE_PARAM, ...(options.openedOn ?? [])];
96
+ const [shared, setShared] = useState<OpensOnLinks | string | null>(null);
97
+ const [choice, setChoice] = useState<OpensOnChoice | null>(null);
98
+ // A dialog closed before what is on screen was written stays closed.
99
+ const asked = useRef(0);
100
+
101
+ function onOpenChange(open: boolean): void {
102
+ const request = ++asked.current;
103
+ if (!open) {
104
+ setShared(null);
105
+ return;
106
+ }
107
+ const { search } = globalThis.location;
108
+ if (!active) {
109
+ setShared(search);
110
+ return;
111
+ }
112
+ const show = (screen: ShareOnScreen) => {
113
+ if (request !== asked.current) return;
114
+ const links = opensOnLinks(search, openedOn, screen);
115
+ setChoice(defaultOpensOn(links, examples));
116
+ setShared(links);
117
+ };
118
+ const read = onScreen();
119
+ if (read instanceof Promise) void read.then(show);
120
+ else show(read);
121
+ }
122
+
123
+ const links = typeof shared === 'string' ? null : shared;
124
+ const address =
125
+ links === null || choice === null
126
+ ? undefined
127
+ : opensOnAddress(links, choice, {
128
+ example: exampleAddress,
129
+ alone: aloneAddress,
130
+ });
131
+ return {
132
+ open: shared !== null,
133
+ onOpenChange,
134
+ search: typeof shared === 'string' ? shared : address?.search,
135
+ baseUrl:
136
+ address?.path === undefined
137
+ ? undefined
138
+ : new URL(address.path, globalThis.location.href).href,
139
+ children:
140
+ links === null || choice === null ? undefined : (
141
+ <ShareOpensOn
142
+ links={links}
143
+ choice={choice}
144
+ onChange={setChoice}
145
+ examples={examples}
146
+ screenLabel={screenLabel}
147
+ >
148
+ {children}
149
+ </ShareOpensOn>
150
+ ),
151
+ };
152
+ }
package/styles/chrome.css CHANGED
@@ -796,6 +796,24 @@ a.source-badge:hover {
796
796
  line-height: 1.45;
797
797
  }
798
798
 
799
+ /* What a link opens on: one choice to a line, what it hands out under its
800
+ label, and the example picker under the radio it belongs to. */
801
+ .share-opens-on .bp6-control.bp6-radio {
802
+ margin-bottom: 6px;
803
+ }
804
+
805
+ .share-opens-on__note {
806
+ display: block;
807
+ margin-top: 2px;
808
+ color: var(--text-muted);
809
+ font-size: 12px;
810
+ line-height: 1.45;
811
+ }
812
+
813
+ .share-opens-on__under {
814
+ margin: -2px 0 10px 26px;
815
+ }
816
+
799
817
  /* The live page, laid out at the screen picked and scaled into the pane. */
800
818
  .share-preview {
801
819
  display: flex;