@surflane/ui 0.8.0 → 0.9.0

package/README.md

@@ -55,7 +55,7 @@ Chart, DatePicker, Markdown, Tree and syntax highlighting have their own entry p
 | `Tree` from `@surflane/ui/tree`                                                                    | `@headless-tree/core @headless-tree/react @tanstack/react-virtual` |
 | `SyntaxHighlighting` from `@surflane/ui/syntax-highlighting`                                       | `shiki`                                                            |
 
-`CodeBlock` and `SyntaxHighlighter` render plain text until a `<SyntaxHighlighting>` provider wraps them.
+`CodeBlock` and `SyntaxHighlighter` render plain text until a `<SyntaxHighlighting>` provider wraps them. With `<SyntaxHighlighting suspense>`, a server render waits for the tokens and writes highlighted HTML.
 
 ## Frameworks
 

package/dist/syntax-context.d.ts

@@ -3,5 +3,14 @@ import type { SyntaxToken } from './syntax-engine.js';
 export type SyntaxEngine = {
     highlightCode(code: string, language: string): Promise<SyntaxToken[][] | null>;
 };
-/** Loads the highlighting engine. Without a provider, code renders as plain text. */
-export declare const SyntaxEngineContext: React.Context<(() => Promise<SyntaxEngine>) | null>;
+/**
+ * Loads the highlighting engine, and says whether code waits for its tokens inside
+ * Suspense. Without a provider, code renders as plain text.
+ */
+export declare const SyntaxEngineContext: React.Context<{
+    load: () => Promise<SyntaxEngine>;
+    suspense: boolean;
+} | null>;
+export declare function requestTokens(load: () => Promise<SyntaxEngine>, code: string, language: string): Promise<SyntaxToken[][] | null>;
+/** Records tokens already known, such as those a server render wrote. */
+export declare function provideTokens(code: string, language: string, tokens: SyntaxToken[][]): void;

package/dist/syntax-context.js

@@ -1,4 +1,37 @@
 'use client';
 import * as React from 'react';
-/** Loads the highlighting engine. Without a provider, code renders as plain text. */
+/**
+ * Loads the highlighting engine, and says whether code waits for its tokens inside
+ * Suspense. Without a provider, code renders as plain text.
+ */
 export const SyntaxEngineContext = /* @__PURE__ */ React.createContext(null);
+// One request per language and code, so a render that suspended finds its tokens again.
+// A settled request carries React's status and value, so use() reads it at once.
+const requests = new Map();
+export function requestTokens(load, code, language) {
+    const key = `${language}\n${code}`;
+    let pending = requests.get(key);
+    if (!pending) {
+        const request = load()
+            .then((engine) => engine.highlightCode(code, language))
+            .catch(() => null);
+        void request.then((tokens) => Object.assign(request, { status: 'fulfilled', value: tokens }));
+        pending = request;
+        remember(key, pending);
+    }
+    return pending;
+}
+/** Records tokens already known, such as those a server render wrote. */
+export function provideTokens(code, language, tokens) {
+    const key = `${language}\n${code}`;
+    if (!requests.has(key))
+        remember(key, Object.assign(Promise.resolve(tokens), {
+            status: 'fulfilled',
+            value: tokens,
+        }));
+}
+function remember(key, request) {
+    requests.set(key, request);
+    if (requests.size > 500)
+        requests.delete(requests.keys().next().value);
+}

package/dist/syntax-highlighter.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
 import { ScrollArea } from './scroll-area.js';
-import { SyntaxEngineContext } from './syntax-context.js';
+import { SyntaxEngineContext, requestTokens } from './syntax-context.js';
 import { cx } from './parts.js';
 export const syntaxLanguages = [
     'tsx',
@@ -31,41 +31,52 @@ const aliases = {
     plaintext: 'text',
     txt: 'text',
 };
+function Highlighted({ tokens, render, }) {
+    return render(React.use(tokens));
+}
 /**
  * Rendering remains selectable React text; it never inserts executable HTML. Tokens are
  * colored inside a SyntaxHighlighting provider; without one, the code renders plain.
  */
 export const SyntaxHighlighter = /* @__PURE__ */ React.forwardRef(function SyntaxHighlighter({ code, language = 'text', inline = false, label = 'Highlighted source', wrap = false, className, ...props }, ref) {
-    const load = React.useContext(SyntaxEngineContext);
+    const source = React.useContext(SyntaxEngineContext);
     const name = language.trim().toLowerCase();
     const lang = aliases[name] ?? name;
+    const highlightable = source !== null &&
+        lang !== 'text' &&
+        syntaxLanguages.includes(lang) &&
+        code.length <= 50000;
+    // Without suspense, code shows plain until an effect brings its tokens.
     const [result, setResult] = React.useState();
+    // A block waits only for the code it mounted with. Code that changes later is
+    // highlighted in place, so a boundary never hides shown code behind its fallback.
+    const [first] = React.useState(() => ({ code, lang }));
+    const suspense = highlightable &&
+        source.suspense &&
+        first.code === code &&
+        first.lang === lang;
     React.useEffect(() => {
-        let current = true;
-        if (!load ||
-            lang === 'text' ||
-            !syntaxLanguages.includes(lang) ||
-            code.length > 50000)
+        if (!highlightable || suspense)
             return;
-        load()
-            .then((engine) => engine.highlightCode(code, lang))
-            .then((tokens) => {
-            if (current)
+        let live = true;
+        void requestTokens(source.load, code, lang).then((tokens) => {
+            if (live)
                 setResult({ code, language: lang, tokens });
-        })
-            .catch(() => {
-            if (current)
-                setResult({ code, language: lang, tokens: null });
         });
         return () => {
-            current = false;
+            live = false;
         };
-    }, [code, lang, load]);
-    const tokens = result?.code === code && result.language === lang ? result.tokens : null;
-    const eols = code.match(/\r\n|\n|\r/g) ?? [];
-    const valid = tokens && tokens.length === eols.length + 1;
-    const element = (_jsx("code", { ...props, ref: ref, className: cx('pui-syntax', className), "data-language": lang, "data-highlighted": valid ? 'true' : 'false', children: valid
-            ? tokens.map((line, i) => (_jsxs(React.Fragment, { children: [line.map((token, j) => (_jsx("span", { "data-syntax": token.role, children: token.content }, j))), eols[i] ?? ''] }, i)))
-            : code }));
+    }, [code, lang, source, highlightable, suspense]);
+    const render = (tokens) => {
+        const eols = code.match(/\r\n|\n|\r/g) ?? [];
+        const valid = tokens && tokens.length === eols.length + 1;
+        return (_jsx("code", { ...props, ref: ref, className: cx('pui-syntax', className), "data-language": lang, "data-highlighted": valid ? 'true' : 'false', children: valid
+                ? tokens.map((line, i) => (_jsxs(React.Fragment, { children: [line.map((token, j) => (_jsx("span", { "data-syntax": token.role, children: token.content }, j))), eols[i] ?? ''] }, i)))
+                : code }));
+    };
+    // With suspense, the block waits for its tokens behind its own boundary, plain
+    // meanwhile: a server render writes it highlighted and hydration keeps that HTML,
+    // while a block that appears later never suspends anything around it.
+    const element = suspense ? (_jsx(React.Suspense, { fallback: render(null), children: _jsx(Highlighted, { tokens: requestTokens(source.load, code, lang), render: render }) })) : (render(result?.code === code && result.language === lang ? result.tokens : null));
     return inline ? (element) : (_jsx(ScrollArea, { label: label, orientation: 'horizontal', rootClassName: 'pui-syntax-scroll', children: _jsx("pre", { className: 'pui-syntax-pre', "data-wrap": wrap || undefined, children: element }) }));
 });

package/dist/syntax-highlighting.d.ts

@@ -2,7 +2,20 @@ import * as React from 'react';
 /**
  * Turns on syntax highlighting for CodeBlock, SyntaxHighlighter and Markdown inside it.
  * Requires the optional `shiki` package; without this provider, code renders as plain text.
+ * Code shows as plain text until its tokens arrive. With `suspense`, each block waits
+ * for them behind its own Suspense boundary instead, so a server render writes it
+ * highlighted and hydration keeps that HTML. Nothing around a block suspends.
  */
-export declare function SyntaxHighlighting({ children, }: {
+export declare function SyntaxHighlighting({ children, suspense, }: {
     children?: React.ReactNode;
+    suspense?: boolean;
 }): React.JSX.Element;
+/**
+ * Reads the tokens of the server-rendered code under `root` from its HTML, so
+ * hydration needs neither the engine nor a grammar. With `suspense`, await it before
+ * `hydrateRoot`: every block then hydrates at once, so no boundary is left waiting for
+ * its tokens, where a context change above it would make React drop the highlighted
+ * HTML for the plain fallback. A block whose HTML doesn't read back as its code is
+ * highlighted again.
+ */
+export declare function preloadSyntaxHighlighting(root?: ParentNode): Promise<undefined>;

package/dist/syntax-highlighting.js

@@ -1,12 +1,63 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { SyntaxEngineContext } from './syntax-context.js';
+import { SyntaxEngineContext, provideTokens, requestTokens, } from './syntax-context.js';
 // The engine and each grammar load on first use, in their own chunks.
 const load = () => import('./syntax-engine.js');
+const sources = {
+    plain: { load, suspense: false },
+    suspense: { load, suspense: true },
+};
 /**
  * Turns on syntax highlighting for CodeBlock, SyntaxHighlighter and Markdown inside it.
  * Requires the optional `shiki` package; without this provider, code renders as plain text.
+ * Code shows as plain text until its tokens arrive. With `suspense`, each block waits
+ * for them behind its own Suspense boundary instead, so a server render writes it
+ * highlighted and hydration keeps that HTML. Nothing around a block suspends.
  */
-export function SyntaxHighlighting({ children, }) {
-    return (_jsx(SyntaxEngineContext.Provider, { value: load, children: children }));
+export function SyntaxHighlighting({ children, suspense = false, }) {
+    return (_jsx(SyntaxEngineContext.Provider, { value: suspense ? sources.suspense : sources.plain, children: children }));
+}
+/**
+ * Reads the tokens of the server-rendered code under `root` from its HTML, so
+ * hydration needs neither the engine nor a grammar. With `suspense`, await it before
+ * `hydrateRoot`: every block then hydrates at once, so no boundary is left waiting for
+ * its tokens, where a context change above it would make React drop the highlighted
+ * HTML for the plain fallback. A block whose HTML doesn't read back as its code is
+ * highlighted again.
+ */
+export function preloadSyntaxHighlighting(root = document) {
+    return Promise.all(Array.from(root.querySelectorAll('code.pui-syntax[data-highlighted="true"]'), (code) => {
+        const text = code.textContent ?? '';
+        const language = code.dataset.language;
+        const tokens = readTokens(code, text);
+        if (tokens)
+            provideTokens(text, language, tokens);
+        else
+            return requestTokens(load, text, language);
+    })).then(() => undefined);
+}
+// SyntaxHighlighter writes a line's tokens as spans and ends it with its line break.
+function readTokens(code, text) {
+    const lines = [[]];
+    let read = '';
+    for (const node of code.childNodes) {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            const content = node.textContent ?? '';
+            lines[lines.length - 1].push({
+                content,
+                role: node.dataset.syntax ?? '',
+            });
+            read += content;
+        }
+        else if (node.nodeType === Node.TEXT_NODE) {
+            const breaks = node.textContent ?? '';
+            if (!/^(\r\n|\n|\r)*$/.test(breaks))
+                return null;
+            const count = breaks.match(/\r\n|\n|\r/g)?.length ?? 0;
+            for (let line = 0; line < count; line++)
+                lines.push([]);
+            read += breaks;
+        }
+    }
+    return read === text ? lines : null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surflane/ui",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Surflane React components built on Base UI, with data, chart, code and Markdown components.",
   "keywords": [
     "design-system",
@@ -407,7 +407,7 @@
   "peerDependencies": {
     "@headless-tree/core": "^1.8.0",
     "@headless-tree/react": "^1.8.0",
-    "@surflane/design-tokens": "^0.8.0",
+    "@surflane/design-tokens": "^0.9.0",
     "@tanstack/react-virtual": "^3.14.21",
     "react": "^19.0.0",
     "react-aria-components": "^1.22.1",