@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.
@@ -0,0 +1,224 @@
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
+ import { createElement as h, forwardRef, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from "react";
17
+ import { parse, parseWithPositions, UnsupportedVersionError, } from "@cube-drone/marquee-parser";
18
+ import { bareWebProfile } from "@cube-drone/marquee-html-renderer";
19
+ import { ANIM_CLASS, renderNode } from "./render.js";
20
+ import { nodeAt as locateAt, nodeNear as locateNear } from "./locate.js";
21
+ /** SSR-safe: layout effects only exist in the browser. The `mq-js` hold is
22
+ * applied here (before paint) rather than in the rendered markup, so a page
23
+ * that never hydrates animates normally instead of freezing - the hold only
24
+ * exists where JS is alive to release it. Never a hostage situation. */
25
+ const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
26
+ export const Marquee = forwardRef(function Marquee(props, ref) {
27
+ const { source, doc: docProp, profile: profileOverrides, hooks = {}, animate = "visible", skipOnClick = true, className, onNodeClick, } = props;
28
+ const rootRef = useRef(null);
29
+ const elements = useRef(new Map()).current;
30
+ const nodesByElement = useRef(new WeakMap()).current;
31
+ const [skipped, setSkipped] = useState(animate === "never");
32
+ const [generation, setGeneration] = useState(0);
33
+ // Parse once per source change. An unknown dialect version is the one
34
+ // refusal in the whole language - and the component's job is still to
35
+ // never eat content, so it shows the source rather than throwing.
36
+ const parsed = useMemo(() => {
37
+ try {
38
+ if (docProp !== undefined) {
39
+ return { doc: docProp, spans: null, error: null };
40
+ }
41
+ if (source === undefined) {
42
+ return { doc: null, spans: null, error: null };
43
+ }
44
+ const { doc, spans } = parseWithPositions(source);
45
+ return { doc, spans, error: null };
46
+ }
47
+ catch (e) {
48
+ return { doc: null, spans: null, error: e };
49
+ }
50
+ }, [source, docProp]);
51
+ const profile = useMemo(() => ({ ...bareWebProfile, ...profileOverrides }), [profileOverrides]);
52
+ const register = useCallback((node) => (el) => {
53
+ if (el === null) {
54
+ const prev = elements.get(node);
55
+ if (prev !== undefined) {
56
+ elements.delete(node);
57
+ }
58
+ return;
59
+ }
60
+ elements.set(node, el);
61
+ nodesByElement.set(el, node);
62
+ }, [elements, nodesByElement]);
63
+ // -- the visibility gate (contract rule 1). The hold is applied AFTER
64
+ // mount (mq-js), so markup that never hydrates animates instead of
65
+ // freezing; then each effect is released the first time it is seen.
66
+ useIsomorphicLayoutEffect(() => {
67
+ const root = rootRef.current;
68
+ if (root === null || parsed.doc === null) {
69
+ return;
70
+ }
71
+ if (animate !== "visible") {
72
+ root.classList.remove("mq-js");
73
+ return;
74
+ }
75
+ root.classList.add("mq-js");
76
+ const targets = Array.from(root.querySelectorAll(`.${ANIM_CLASS}`));
77
+ for (const el of targets) {
78
+ el.removeAttribute("data-mq-play");
79
+ }
80
+ if (typeof IntersectionObserver === "undefined") {
81
+ // No observer (old browser, test environment): release everything -
82
+ // the effect is worth less than the text being visible.
83
+ for (const el of targets) {
84
+ el.setAttribute("data-mq-play", "");
85
+ }
86
+ return;
87
+ }
88
+ const observer = new IntersectionObserver((entries) => {
89
+ for (const entry of entries) {
90
+ if (entry.isIntersecting) {
91
+ entry.target.setAttribute("data-mq-play", "");
92
+ observer.unobserve(entry.target); // one-shot: a performance, not a loop
93
+ }
94
+ }
95
+ }, { rootMargin: "0px 0px -10% 0px" });
96
+ for (const el of targets) {
97
+ observer.observe(el);
98
+ }
99
+ return () => observer.disconnect();
100
+ }, [parsed.doc, animate, generation]);
101
+ /** NEAREST, not "containing": a cursor in the whitespace between two
102
+ * blocks is contained only by their parent, and scrolling to the parent
103
+ * means scrolling to the middle of the whole group (or, on a blank line
104
+ * between top-level paragraphs, the middle of the whole document). Then
105
+ * walk out until something has an element: text nodes render as strings.
106
+ *
107
+ * But STOP below the document node. The document is registered too (it is
108
+ * the <div class="mq-doc">), so a cursor whose nearest node renders to
109
+ * nothing - the meta line, a comment, an invalid directive - would walk all
110
+ * the way up and "scroll to" the whole page. Better to not scroll at all
111
+ * (return null): leave the preview where the reader left it. */
112
+ const elementNear = useCallback((offset) => {
113
+ if (parsed.doc === null || parsed.spans === null) {
114
+ return null;
115
+ }
116
+ let node = locateNear(parsed.doc, parsed.spans, offset);
117
+ while (node !== null && node !== parsed.doc) {
118
+ const el = elements.get(node);
119
+ if (el !== undefined) {
120
+ return el;
121
+ }
122
+ node = parentOf(parsed.doc, node);
123
+ }
124
+ return null;
125
+ }, [parsed, elements]);
126
+ const skip = useCallback(() => setSkipped(true), []);
127
+ const replay = useCallback(() => {
128
+ setSkipped(false);
129
+ setGeneration((g) => g + 1); // re-arm the observer
130
+ }, []);
131
+ useImperativeHandle(ref, () => ({
132
+ get root() {
133
+ return rootRef.current;
134
+ },
135
+ elementFor: (node) => elements.get(node) ?? null,
136
+ nodeAt: (offset) => parsed.doc === null || parsed.spans === null
137
+ ? null
138
+ : locateAt(parsed.doc, parsed.spans, offset),
139
+ nodeNear: (offset) => parsed.doc === null || parsed.spans === null
140
+ ? null
141
+ : locateNear(parsed.doc, parsed.spans, offset),
142
+ scrollToNode: (node, options) => {
143
+ const el = elements.get(node);
144
+ if (el === undefined) {
145
+ return false;
146
+ }
147
+ el.scrollIntoView({ block: "center", behavior: "smooth", ...options });
148
+ return true;
149
+ },
150
+ elementNear: (offset) => elementNear(offset),
151
+ scrollToSource: (offset, options) => {
152
+ const el = elementNear(offset);
153
+ if (el === null) {
154
+ return false;
155
+ }
156
+ el.scrollIntoView({ block: "center", behavior: "smooth", ...options });
157
+ return true;
158
+ },
159
+ skip,
160
+ replay,
161
+ }), [parsed, elements, elementNear, skip, replay]);
162
+ const handleClick = useCallback((event) => {
163
+ if (skipOnClick && !skipped) {
164
+ setSkipped(true);
165
+ }
166
+ if (onNodeClick !== undefined) {
167
+ const el = event.target.closest("[data-mq-start]");
168
+ const node = el === null ? undefined : nodesByElement.get(el);
169
+ if (node !== undefined) {
170
+ onNodeClick(node, parsed.spans?.get(node) ?? null, event);
171
+ }
172
+ }
173
+ }, [skipOnClick, skipped, onNodeClick, nodesByElement, parsed.spans]);
174
+ if (parsed.error !== null) {
175
+ const message = parsed.error instanceof UnsupportedVersionError
176
+ ? `This document declares Marquee version ${parsed.error.version}, which this renderer doesn't know.`
177
+ : String(parsed.error.message);
178
+ // Never eat content: show the refusal AND the words.
179
+ return h("div", { className: `mq-doc mq-unsupported${className === undefined ? "" : ` ${className}`}` }, h("p", { className: "mq-invalid", "data-reason": "unsupported_version" }, message), h("pre", { className: "mq-code" }, h("code", null, source ?? "")));
180
+ }
181
+ if (parsed.doc === null) {
182
+ return null;
183
+ }
184
+ const ctx = {
185
+ profile,
186
+ hooks,
187
+ spans: parsed.spans,
188
+ register,
189
+ note: { n: 0, pending: [] },
190
+ };
191
+ const tree = renderNode(parsed.doc, ctx, "doc");
192
+ // The root element the renderer produced is a <div class="mq-doc">; wrap
193
+ // it so the component owns the ref, the click gesture, and the skip flag
194
+ // without the renderer needing to know they exist.
195
+ return h("div", {
196
+ ref: (el) => {
197
+ rootRef.current = el;
198
+ },
199
+ className: `mq-root${className === undefined ? "" : ` ${className}`}`,
200
+ "data-mq-skip": skipped ? "" : undefined,
201
+ onClick: handleClick,
202
+ style: { display: "contents" },
203
+ }, tree);
204
+ });
205
+ function parentOf(doc, target) {
206
+ let found = null;
207
+ const walk = (node) => {
208
+ if (found !== null || !("children" in node)) {
209
+ return;
210
+ }
211
+ for (const child of node.children) {
212
+ if (child === target) {
213
+ found = node;
214
+ return;
215
+ }
216
+ walk(child);
217
+ }
218
+ };
219
+ walk(doc);
220
+ return found;
221
+ }
222
+ /** Parse without positions - for callers who want to hold the AST
223
+ * themselves and pass it as `doc`. */
224
+ export { parse };
@@ -0,0 +1,8 @@
1
+ export { Marquee } from "./Marquee.ts";
2
+ export type { MarqueeHandle, MarqueeProps } from "./Marquee.ts";
3
+ export type { ReactHooks } from "./render.ts";
4
+ export { nodeAt, nodeNear } from "./locate.ts";
5
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
6
+ export type { Attrs, Node, Reason, Span } from "@cube-drone/marquee-parser";
7
+ export { bareWebProfile, FONTS } from "@cube-drone/marquee-html-renderer";
8
+ export type { EmojiResolution, MediaResolution, Profile, TurbolinkLevel, } from "@cube-drone/marquee-html-renderer";
package/dist/index.js ADDED
@@ -0,0 +1,15 @@
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
+ export { Marquee } from "./Marquee.js";
8
+ // Locating a cursor in the tree - pure, and useful to any host doing its
9
+ // own DOM work (the component uses exactly these).
10
+ export { nodeAt, nodeNear } from "./locate.js";
11
+ // The toolbox underneath, re-exported: the same parser, the same Profile
12
+ // socket, so an embedder's policy is written once and honored by both
13
+ // renderers.
14
+ export { parse, parseWithPositions, UnsupportedVersionError } from "@cube-drone/marquee-parser";
15
+ export { bareWebProfile, FONTS } from "@cube-drone/marquee-html-renderer";
@@ -0,0 +1,9 @@
1
+ import type { Node, Span } from "@cube-drone/marquee-parser";
2
+ /** The deepest node whose span CONTAINS this offset. Exact, with holes: a
3
+ * cursor in the whitespace between blocks lands on their container. */
4
+ export declare function nodeAt(doc: Node, spans: WeakMap<Node, Span>, offset: number): Node | null;
5
+ /** The deepest node AT or NEAREST this offset. Where a child contains the
6
+ * offset this agrees with `nodeAt`; where none does (a gap), it descends
7
+ * into the closest child by source distance instead of stopping at the
8
+ * container. Ties go to the earlier node. This is what an editor wants. */
9
+ export declare function nodeNear(doc: Node, spans: WeakMap<Node, Span>, offset: number): Node | null;
package/dist/locate.js ADDED
@@ -0,0 +1,71 @@
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
+ function childrenOf(node) {
16
+ return "children" in node ? node.children : [];
17
+ }
18
+ /** The deepest node whose span CONTAINS this offset. Exact, with holes: a
19
+ * cursor in the whitespace between blocks lands on their container. */
20
+ export function nodeAt(doc, spans, offset) {
21
+ const root = spans.get(doc);
22
+ if (root === undefined || offset < root.start || offset > root.end) {
23
+ return null;
24
+ }
25
+ let node = doc;
26
+ for (;;) {
27
+ const child = childrenOf(node).find((c) => {
28
+ const span = spans.get(c);
29
+ return span !== undefined && offset >= span.start && offset <= span.end;
30
+ });
31
+ if (child === undefined) {
32
+ return node;
33
+ }
34
+ node = child;
35
+ }
36
+ }
37
+ /** The deepest node AT or NEAREST this offset. Where a child contains the
38
+ * offset this agrees with `nodeAt`; where none does (a gap), it descends
39
+ * into the closest child by source distance instead of stopping at the
40
+ * container. Ties go to the earlier node. This is what an editor wants. */
41
+ export function nodeNear(doc, spans, offset) {
42
+ if (spans.get(doc) === undefined) {
43
+ return null;
44
+ }
45
+ let node = doc;
46
+ for (;;) {
47
+ const kids = childrenOf(node);
48
+ let chosen = null;
49
+ let best = Infinity;
50
+ for (const child of kids) {
51
+ const span = spans.get(child);
52
+ if (span === undefined) {
53
+ continue;
54
+ }
55
+ if (offset >= span.start && offset <= span.end) {
56
+ chosen = child;
57
+ best = -1;
58
+ break; // containment always wins over proximity
59
+ }
60
+ const distance = offset < span.start ? span.start - offset : offset - span.end;
61
+ if (distance < best) {
62
+ best = distance;
63
+ chosen = child;
64
+ }
65
+ }
66
+ if (chosen === null) {
67
+ return node; // a leaf, or a container whose children carry no spans
68
+ }
69
+ node = chosen;
70
+ }
71
+ }
@@ -0,0 +1,28 @@
1
+ import { type ReactNode } from "react";
2
+ import type { Attrs, Node, Span } from "@cube-drone/marquee-parser";
3
+ import { type Profile, type TurbolinkLevel } from "@cube-drone/marquee-html-renderer";
4
+ /** React-returning versions of the rendering hooks. When present these win
5
+ * over the string-returning `Profile` hooks (no innerHTML at all). */
6
+ export interface ReactHooks {
7
+ turbolink?(target: string, level: TurbolinkLevel): ReactNode | null;
8
+ directive?(name: string, attrs: Attrs, children: ReactNode): ReactNode | null;
9
+ span?(name: string, attrs: Attrs, children: ReactNode): ReactNode | null;
10
+ }
11
+ export interface Ctx {
12
+ profile: Profile;
13
+ hooks: ReactHooks;
14
+ spans: WeakMap<Node, Span> | null;
15
+ /** Registers a node's DOM element (scroll sync, reverse sync). */
16
+ register: (node: Node) => (el: HTMLElement | null) => void;
17
+ note: {
18
+ n: number;
19
+ pending: ReactNode[];
20
+ };
21
+ }
22
+ /** Effects whose elements the visibility observer watches, and which the
23
+ * skip gesture stills. Named, closed: the vocabulary decides, not the DOM. */
24
+ declare const ANIMATED: Set<string>;
25
+ export declare const ANIM_CLASS = "mq-anim";
26
+ export declare function renderChildren(nodes: Node[], ctx: Ctx): ReactNode[];
27
+ export declare function renderNode(node: Node, ctx: Ctx, key: string): ReactNode;
28
+ export { ANIMATED };