@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/LICENSE +373 -0
- package/README.md +163 -0
- package/dist/Marquee.d.ts +62 -0
- package/dist/Marquee.js +224 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +15 -0
- package/dist/locate.d.ts +9 -0
- package/dist/locate.js +71 -0
- package/dist/render.d.ts +28 -0
- package/dist/render.js +593 -0
- package/package.json +56 -0
- package/src/Marquee.ts +356 -0
- package/src/index.ts +26 -0
- package/src/locate.ts +76 -0
- package/src/render.ts +782 -0
package/dist/Marquee.js
ADDED
|
@@ -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 };
|
package/dist/index.d.ts
ADDED
|
@@ -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";
|
package/dist/locate.d.ts
ADDED
|
@@ -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
|
+
}
|
package/dist/render.d.ts
ADDED
|
@@ -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 };
|