@cube-drone/marquee-react-renderer 0.4.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.
package/src/Marquee.ts ADDED
@@ -0,0 +1,356 @@
1
+ // <Marquee /> - the interactive renderer.
2
+ //
3
+ // It is the static renderer plus the three things a string of HTML cannot do,
4
+ // which are exactly the three things the spec's animation contract defers to
5
+ // "the interactive renderer":
6
+ //
7
+ // 1. animate on VISIBILITY, not on page load (IntersectionObserver)
8
+ // 2. the user can always SKIP (one gesture stills everything, whole)
9
+ // 3. scroll sync for side-by-side editors (source offset <-> element)
10
+ //
11
+ // All motion is still CSS - marquee.css is the shared artifact, and the
12
+ // mq-* class contract is what every renderer targets. JS never animates
13
+ // anything here; it decides when the CSS clock starts and when it stops.
14
+ // That is why there is no animation library in the dependency list: the
15
+ // effect vocabulary is closed, and CSS already speaks all of it.
16
+
17
+ import {
18
+ createElement as h,
19
+ forwardRef,
20
+ useCallback,
21
+ useEffect,
22
+ useImperativeHandle,
23
+ useLayoutEffect,
24
+ useMemo,
25
+ useRef,
26
+ useState,
27
+ type ReactNode,
28
+ } from "react";
29
+ import {
30
+ parse,
31
+ parseWithPositions,
32
+ UnsupportedVersionError,
33
+ type Node,
34
+ type Span,
35
+ } from "@cube-drone/marquee-parser";
36
+ import { bareWebProfile, type Profile } from "@cube-drone/marquee-html-renderer";
37
+ import { ANIM_CLASS, renderNode, type Ctx, type ReactHooks } from "./render.ts";
38
+ import { nodeAt as locateAt, nodeNear as locateNear } from "./locate.ts";
39
+
40
+ /** SSR-safe: layout effects only exist in the browser. The `mq-js` hold is
41
+ * applied here (before paint) rather than in the rendered markup, so a page
42
+ * that never hydrates animates normally instead of freezing - the hold only
43
+ * exists where JS is alive to release it. Never a hostage situation. */
44
+ const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
45
+
46
+ export interface MarqueeHandle {
47
+ /** The rendered root element. */
48
+ readonly root: HTMLElement | null;
49
+ /** The DOM element a node rendered to, if it is currently mounted. */
50
+ elementFor(node: Node): HTMLElement | null;
51
+ /** The element `scrollToSource(offset)` would scroll to: the nearest node
52
+ * to that offset that actually has an element (text nodes render as
53
+ * strings, so they have none). Handy for highlighting it too. */
54
+ elementNear(offset: number): HTMLElement | null;
55
+ /** The deepest node whose source span CONTAINS this offset (needs
56
+ * `source`). Exact, with holes: a cursor in the blank line between two
57
+ * paragraphs is contained by nothing smaller than their container. */
58
+ nodeAt(offset: number): Node | null;
59
+ /** The deepest node at or NEAREST this offset - the editor-shaped answer,
60
+ * and what `scrollToSource` uses. A cursor in the gap between two blocks
61
+ * finds the block beside it, not the container above it. */
62
+ nodeNear(offset: number): Node | null;
63
+ /** Scroll a node into view. Returns false if it isn't mounted. */
64
+ scrollToNode(node: Node, options?: ScrollIntoViewOptions): boolean;
65
+ /** Scroll to whatever the editor's cursor is sitting in: the side-by-side
66
+ * move. Centered by default, because "at the top edge" is not where a
67
+ * human looks. Returns false if the offset maps to nothing on screen. */
68
+ scrollToSource(offset: number, options?: ScrollIntoViewOptions): boolean;
69
+ /** Still every effect and show all text, whole - the skip gesture, fired
70
+ * programmatically (a toolbar button, a keystroke, a host policy). */
71
+ skip(): void;
72
+ /** Undo a skip and re-arm the visibility observer. */
73
+ replay(): void;
74
+ }
75
+
76
+ export interface MarqueeProps {
77
+ /** Marquee source. Parsed with positions, which is what enables the
78
+ * editor-sync half of the API. Ignored when `doc` is given. */
79
+ source?: string;
80
+ /** A pre-parsed document (no positions, so no source sync). */
81
+ doc?: Node;
82
+ /** Embedder policy: schemes, media, emoji, turbolinks, vocabulary.
83
+ * The SAME socket the static renderer uses - one policy, both renderers. */
84
+ profile?: Partial<Profile>;
85
+ /** React-returning versions of the rendering hooks. When given, the
86
+ * corresponding string-returning profile hook is not consulted (and no
87
+ * HTML string is ever injected). */
88
+ hooks?: ReactHooks;
89
+ /** `visible` (default): effects hold until scrolled into view.
90
+ * `immediate`: effects run from mount, like the static renderer.
91
+ * `never`: no motion at all (the reduced-motion posture, by choice). */
92
+ animate?: "visible" | "immediate" | "never";
93
+ /** A click anywhere in the document stills every effect (default true) -
94
+ * the spec's "animated text is a performance, never a hostage situation". */
95
+ skipOnClick?: boolean;
96
+ /** Extra classes on the root, beside `mq-doc`. */
97
+ className?: string;
98
+ /** Reverse sync: which node did the reader just click? Gives you the node
99
+ * and its source span, so the editor can move its cursor there. */
100
+ onNodeClick?: (node: Node, span: Span | null, event: React.MouseEvent) => void;
101
+ }
102
+
103
+ export const Marquee = forwardRef<MarqueeHandle, MarqueeProps>(function Marquee(props, ref) {
104
+ const {
105
+ source,
106
+ doc: docProp,
107
+ profile: profileOverrides,
108
+ hooks = {},
109
+ animate = "visible",
110
+ skipOnClick = true,
111
+ className,
112
+ onNodeClick,
113
+ } = props;
114
+
115
+ const rootRef = useRef<HTMLElement | null>(null);
116
+ const elements = useRef(new Map<Node, HTMLElement>()).current;
117
+ const nodesByElement = useRef(new WeakMap<HTMLElement, Node>()).current;
118
+ const [skipped, setSkipped] = useState(animate === "never");
119
+ const [generation, setGeneration] = useState(0);
120
+
121
+ // Parse once per source change. An unknown dialect version is the one
122
+ // refusal in the whole language - and the component's job is still to
123
+ // never eat content, so it shows the source rather than throwing.
124
+ const parsed = useMemo((): { doc: Node | null; spans: WeakMap<Node, Span> | null; error: Error | null } => {
125
+ try {
126
+ if (docProp !== undefined) {
127
+ return { doc: docProp, spans: null, error: null };
128
+ }
129
+ if (source === undefined) {
130
+ return { doc: null, spans: null, error: null };
131
+ }
132
+ const { doc, spans } = parseWithPositions(source);
133
+ return { doc, spans, error: null };
134
+ } catch (e) {
135
+ return { doc: null, spans: null, error: e as Error };
136
+ }
137
+ }, [source, docProp]);
138
+
139
+ const profile = useMemo(
140
+ (): Profile => ({ ...bareWebProfile, ...profileOverrides }),
141
+ [profileOverrides],
142
+ );
143
+
144
+ const register = useCallback(
145
+ (node: Node) => (el: HTMLElement | null) => {
146
+ if (el === null) {
147
+ const prev = elements.get(node);
148
+ if (prev !== undefined) {
149
+ elements.delete(node);
150
+ }
151
+ return;
152
+ }
153
+ elements.set(node, el);
154
+ nodesByElement.set(el, node);
155
+ },
156
+ [elements, nodesByElement],
157
+ );
158
+
159
+ // -- the visibility gate (contract rule 1). The hold is applied AFTER
160
+ // mount (mq-js), so markup that never hydrates animates instead of
161
+ // freezing; then each effect is released the first time it is seen.
162
+ useIsomorphicLayoutEffect(() => {
163
+ const root = rootRef.current;
164
+ if (root === null || parsed.doc === null) {
165
+ return;
166
+ }
167
+ if (animate !== "visible") {
168
+ root.classList.remove("mq-js");
169
+ return;
170
+ }
171
+ root.classList.add("mq-js");
172
+ const targets = Array.from(root.querySelectorAll<HTMLElement>(`.${ANIM_CLASS}`));
173
+ for (const el of targets) {
174
+ el.removeAttribute("data-mq-play");
175
+ }
176
+ if (typeof IntersectionObserver === "undefined") {
177
+ // No observer (old browser, test environment): release everything -
178
+ // the effect is worth less than the text being visible.
179
+ for (const el of targets) {
180
+ el.setAttribute("data-mq-play", "");
181
+ }
182
+ return;
183
+ }
184
+ const observer = new IntersectionObserver(
185
+ (entries) => {
186
+ for (const entry of entries) {
187
+ if (entry.isIntersecting) {
188
+ entry.target.setAttribute("data-mq-play", "");
189
+ observer.unobserve(entry.target); // one-shot: a performance, not a loop
190
+ }
191
+ }
192
+ },
193
+ { rootMargin: "0px 0px -10% 0px" },
194
+ );
195
+ for (const el of targets) {
196
+ observer.observe(el);
197
+ }
198
+ return () => observer.disconnect();
199
+ }, [parsed.doc, animate, generation]);
200
+
201
+ /** NEAREST, not "containing": a cursor in the whitespace between two
202
+ * blocks is contained only by their parent, and scrolling to the parent
203
+ * means scrolling to the middle of the whole group (or, on a blank line
204
+ * between top-level paragraphs, the middle of the whole document). Then
205
+ * walk out until something has an element: text nodes render as strings.
206
+ *
207
+ * But STOP below the document node. The document is registered too (it is
208
+ * the <div class="mq-doc">), so a cursor whose nearest node renders to
209
+ * nothing - the meta line, a comment, an invalid directive - would walk all
210
+ * the way up and "scroll to" the whole page. Better to not scroll at all
211
+ * (return null): leave the preview where the reader left it. */
212
+ const elementNear = useCallback(
213
+ (offset: number): HTMLElement | null => {
214
+ if (parsed.doc === null || parsed.spans === null) {
215
+ return null;
216
+ }
217
+ let node = locateNear(parsed.doc, parsed.spans, offset);
218
+ while (node !== null && node !== parsed.doc) {
219
+ const el = elements.get(node);
220
+ if (el !== undefined) {
221
+ return el;
222
+ }
223
+ node = parentOf(parsed.doc, node);
224
+ }
225
+ return null;
226
+ },
227
+ [parsed, elements],
228
+ );
229
+
230
+ const skip = useCallback(() => setSkipped(true), []);
231
+ const replay = useCallback(() => {
232
+ setSkipped(false);
233
+ setGeneration((g) => g + 1); // re-arm the observer
234
+ }, []);
235
+
236
+ useImperativeHandle(
237
+ ref,
238
+ (): MarqueeHandle => ({
239
+ get root() {
240
+ return rootRef.current;
241
+ },
242
+ elementFor: (node) => elements.get(node) ?? null,
243
+ nodeAt: (offset) =>
244
+ parsed.doc === null || parsed.spans === null
245
+ ? null
246
+ : locateAt(parsed.doc, parsed.spans, offset),
247
+ nodeNear: (offset) =>
248
+ parsed.doc === null || parsed.spans === null
249
+ ? null
250
+ : locateNear(parsed.doc, parsed.spans, offset),
251
+ scrollToNode: (node, options) => {
252
+ const el = elements.get(node);
253
+ if (el === undefined) {
254
+ return false;
255
+ }
256
+ el.scrollIntoView({ block: "center", behavior: "smooth", ...options });
257
+ return true;
258
+ },
259
+ elementNear: (offset) => elementNear(offset),
260
+ scrollToSource: (offset, options) => {
261
+ const el = elementNear(offset);
262
+ if (el === null) {
263
+ return false;
264
+ }
265
+ el.scrollIntoView({ block: "center", behavior: "smooth", ...options });
266
+ return true;
267
+ },
268
+ skip,
269
+ replay,
270
+ }),
271
+ [parsed, elements, elementNear, skip, replay],
272
+ );
273
+
274
+ const handleClick = useCallback(
275
+ (event: React.MouseEvent) => {
276
+ if (skipOnClick && !skipped) {
277
+ setSkipped(true);
278
+ }
279
+ if (onNodeClick !== undefined) {
280
+ const el = (event.target as HTMLElement).closest<HTMLElement>("[data-mq-start]");
281
+ const node = el === null ? undefined : nodesByElement.get(el);
282
+ if (node !== undefined) {
283
+ onNodeClick(node, parsed.spans?.get(node) ?? null, event);
284
+ }
285
+ }
286
+ },
287
+ [skipOnClick, skipped, onNodeClick, nodesByElement, parsed.spans],
288
+ );
289
+
290
+ if (parsed.error !== null) {
291
+ const message =
292
+ parsed.error instanceof UnsupportedVersionError
293
+ ? `This document declares Marquee version ${parsed.error.version}, which this renderer doesn't know.`
294
+ : String(parsed.error.message);
295
+ // Never eat content: show the refusal AND the words.
296
+ return h(
297
+ "div",
298
+ { className: `mq-doc mq-unsupported${className === undefined ? "" : ` ${className}`}` },
299
+ h("p", { className: "mq-invalid", "data-reason": "unsupported_version" }, message),
300
+ h("pre", { className: "mq-code" }, h("code", null, source ?? "")),
301
+ );
302
+ }
303
+
304
+ if (parsed.doc === null) {
305
+ return null;
306
+ }
307
+
308
+ const ctx: Ctx = {
309
+ profile,
310
+ hooks,
311
+ spans: parsed.spans,
312
+ register,
313
+ note: { n: 0, pending: [] },
314
+ };
315
+
316
+ const tree = renderNode(parsed.doc, ctx, "doc") as ReactNode;
317
+
318
+ // The root element the renderer produced is a <div class="mq-doc">; wrap
319
+ // it so the component owns the ref, the click gesture, and the skip flag
320
+ // without the renderer needing to know they exist.
321
+ return h(
322
+ "div",
323
+ {
324
+ ref: (el: HTMLDivElement | null) => {
325
+ rootRef.current = el;
326
+ },
327
+ className: `mq-root${className === undefined ? "" : ` ${className}`}`,
328
+ "data-mq-skip": skipped ? "" : undefined,
329
+ onClick: handleClick,
330
+ style: { display: "contents" },
331
+ },
332
+ tree,
333
+ );
334
+ });
335
+
336
+ function parentOf(doc: Node, target: Node): Node | null {
337
+ let found: Node | null = null;
338
+ const walk = (node: Node): void => {
339
+ if (found !== null || !("children" in node)) {
340
+ return;
341
+ }
342
+ for (const child of node.children) {
343
+ if (child === target) {
344
+ found = node;
345
+ return;
346
+ }
347
+ walk(child);
348
+ }
349
+ };
350
+ walk(doc);
351
+ return found;
352
+ }
353
+
354
+ /** Parse without positions - for callers who want to hold the AST
355
+ * themselves and pass it as `doc`. */
356
+ export { parse };
package/src/index.ts ADDED
@@ -0,0 +1,26 @@
1
+ // @cube-drone/marquee-react: the interactive renderer.
2
+ //
3
+ // Pair it with @cube-drone/marquee-css (the mq-* class contract, shared with
4
+ // the static renderer) and, optionally, @cube-drone/marquee-fonts. This
5
+ // package renders; it does not ship stylesheets, because the stylesheet is a
6
+ // shared artifact rather than this renderer's private business.
7
+
8
+ export { Marquee } from "./Marquee.ts";
9
+ export type { MarqueeHandle, MarqueeProps } from "./Marquee.ts";
10
+ export type { ReactHooks } from "./render.ts";
11
+ // Locating a cursor in the tree - pure, and useful to any host doing its
12
+ // own DOM work (the component uses exactly these).
13
+ export { nodeAt, nodeNear } from "./locate.ts";
14
+
15
+ // The toolbox underneath, re-exported: the same parser, the same Profile
16
+ // socket, so an embedder's policy is written once and honored by both
17
+ // renderers.
18
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
19
+ export type { Attrs, Node, Reason, Span } from "@cube-drone/marquee-parser";
20
+ export { bareWebProfile, FONTS } from "@cube-drone/marquee-html-renderer";
21
+ export type {
22
+ EmojiResolution,
23
+ MediaResolution,
24
+ Profile,
25
+ TurbolinkLevel,
26
+ } from "@cube-drone/marquee-html-renderer";
package/src/locate.ts ADDED
@@ -0,0 +1,76 @@
1
+ // Finding the node an editor's cursor is "in" - which is not as simple as
2
+ // containment, because containment has holes.
3
+ //
4
+ // A span covers a construct's source extent, and the gaps BETWEEN
5
+ // constructs (the blank line between two paragraphs, the newline between
6
+ // two list items) belong to no child at all - only to the container. So a
7
+ // cursor parked in a gap is, strictly, "inside" nothing smaller than the
8
+ // container: strict containment answers `document` for a cursor on a blank
9
+ // line, and scrolling to *that* means scrolling to the middle of the whole
10
+ // document. Correct, and useless.
11
+ //
12
+ // `nodeNear` is the editor-shaped answer: descend toward the nearest child
13
+ // at every level, so a cursor in the gap between two paragraphs finds the
14
+ // paragraph beside it rather than the container above it.
15
+
16
+ import type { Node, Span } from "@cube-drone/marquee-parser";
17
+
18
+ function childrenOf(node: Node): readonly Node[] {
19
+ return "children" in node ? node.children : [];
20
+ }
21
+
22
+ /** The deepest node whose span CONTAINS this offset. Exact, with holes: a
23
+ * cursor in the whitespace between blocks lands on their container. */
24
+ export function nodeAt(doc: Node, spans: WeakMap<Node, Span>, offset: number): Node | null {
25
+ const root = spans.get(doc);
26
+ if (root === undefined || offset < root.start || offset > root.end) {
27
+ return null;
28
+ }
29
+ let node = doc;
30
+ for (;;) {
31
+ const child = childrenOf(node).find((c) => {
32
+ const span = spans.get(c);
33
+ return span !== undefined && offset >= span.start && offset <= span.end;
34
+ });
35
+ if (child === undefined) {
36
+ return node;
37
+ }
38
+ node = child;
39
+ }
40
+ }
41
+
42
+ /** The deepest node AT or NEAREST this offset. Where a child contains the
43
+ * offset this agrees with `nodeAt`; where none does (a gap), it descends
44
+ * into the closest child by source distance instead of stopping at the
45
+ * container. Ties go to the earlier node. This is what an editor wants. */
46
+ export function nodeNear(doc: Node, spans: WeakMap<Node, Span>, offset: number): Node | null {
47
+ if (spans.get(doc) === undefined) {
48
+ return null;
49
+ }
50
+ let node = doc;
51
+ for (;;) {
52
+ const kids = childrenOf(node);
53
+ let chosen: Node | null = null;
54
+ let best = Infinity;
55
+ for (const child of kids) {
56
+ const span = spans.get(child);
57
+ if (span === undefined) {
58
+ continue;
59
+ }
60
+ if (offset >= span.start && offset <= span.end) {
61
+ chosen = child;
62
+ best = -1;
63
+ break; // containment always wins over proximity
64
+ }
65
+ const distance = offset < span.start ? span.start - offset : offset - span.end;
66
+ if (distance < best) {
67
+ best = distance;
68
+ chosen = child;
69
+ }
70
+ }
71
+ if (chosen === null) {
72
+ return node; // a leaf, or a container whose children carry no spans
73
+ }
74
+ node = chosen;
75
+ }
76
+ }