@surflane/ui 0.7.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/code.js

@@ -74,7 +74,9 @@ export const CodeBlock = /* @__PURE__ */ React.forwardRef(function CodeBlock({ c
         }, copyFeedbackDuration);
     }
     const icon = state === 'copied' || state === 'failed' ? state : 'idle';
-    return (_jsxs("div", { ...props, ref: ref, "data-wrap": wrap || undefined, className: cx('pui-code-block', className), children: [_jsxs("div", { className: 'pui-code-toolbar', children: [_jsxs("span", { className: 'pui-code-label', children: [label, language && _jsx("span", { className: 'pui-code-language', children: language })] }), _jsxs(Button, { ref: button, type: 'button', variant: 'outline', size: 'sm', className: 'pui-code-copy', onClick: copy, disabled: state === 'busy', "aria-busy": state === 'busy' || undefined, "data-copy-state": icon === 'idle' ? undefined : icon, "data-copy-used": used || undefined, children: [_jsx(Icon, { name: copyIcons[icon], className: 'pui-code-copy-icon' }, icon), _jsx("span", { "aria-live": 'polite', children: _jsx("span", { className: 'pui-code-copy-label', children: state === 'copied'
+    return (_jsxs("div", { ...props, ref: ref, "data-wrap": wrap || undefined, className: cx('pui-code-block', className), children: [_jsxs("div", { className: 'pui-code-toolbar', children: [_jsxs("span", { className: 'pui-code-label', children: [label, language && _jsx("span", { className: 'pui-code-language', children: language })] }), _jsxs(Button, { ref: button, type: 'button', variant: 'outline', size: 'sm', className: 'pui-code-copy', onClick: copy, 
+                        // A pending copy blocks a second start but keeps focus on the button.
+                        disabled: state === 'busy', focusableWhenDisabled: true, "aria-busy": state === 'busy' || undefined, "data-copy-state": icon === 'idle' ? undefined : icon, "data-copy-used": used || undefined, children: [_jsx(Icon, { name: copyIcons[icon], className: 'pui-code-copy-icon' }, icon), _jsx("span", { "aria-live": 'polite', children: _jsx("span", { className: 'pui-code-copy-label', children: state === 'copied'
                                         ? copiedLabel
                                         : state === 'failed'
                                             ? copyErrorLabel

package/dist/css/rules/choice.css

@@ -81,9 +81,21 @@
   .pui-switch[data-readonly] {
     cursor: default;
   }
+  /* An invalid control keeps its edge through every hover, checked or not; hover
+     still tints the fill. Each selector matches the hover rule it must outrank. */
   :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid],
+  :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid]:hover,
+  :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid]:is(
+      [data-checked],
+      [data-indeterminate]
+    ):hover,
+  .pui-choice-label:hover
+    :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid],
   .pui-choice-label:hover
-    :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid] {
+    :is(.pui-checkbox, .pui-radio, .pui-switch)[data-invalid]:is(
+      [data-checked],
+      [data-indeterminate]
+    ) {
     border-color: var(--status-danger-fg);
   }
   @media (forced-colors: active) {

package/dist/css/rules/combobox.css

@@ -143,6 +143,10 @@
       outline: 1px solid CanvasText;
       outline-offset: -1px;
     }
+    /* The group draws the field's focus, so its input draws none of its own. */
+    .pui-combobox-group .pui-combobox-input:focus {
+      outline: none;
+    }
   }
   .pui-combobox-group > .pui-combobox-input,
   .pui-combobox-action {

package/dist/css/rules/date-picker.css

@@ -40,7 +40,13 @@
     border-color: var(--control-focus);
     box-shadow: 0 0 0 var(--control-focus-ring-size) var(--control-focus-ring);
   }
-  :is(.pui-date-picker, .pui-time-field)[data-invalid] .pui-date-group {
+  /* An invalid field keeps its edge while hovered; hover still tints the fill. */
+  :is(.pui-date-picker, .pui-time-field)[data-invalid] .pui-date-group,
+  :is(.pui-date-picker, .pui-time-field)[data-invalid]:not(
+      [data-disabled],
+      [data-readonly]
+    )
+    .pui-date-group:hover {
     border-color: var(--status-danger-fg);
   }
   :is(.pui-date-picker, .pui-time-field)[data-disabled] {

package/dist/css/rules/field-control.css

@@ -53,10 +53,21 @@
     cursor: not-allowed;
     background: var(--control-disabled-background);
   }
+  /* An invalid field keeps its edge while hovered; hover still tints the fill. */
   .pui-input[aria-invalid='true'],
-  .pui-select-trigger[aria-invalid='true'] {
+  .pui-input[aria-invalid='true']:hover,
+  .pui-select-trigger[aria-invalid='true'],
+  .pui-select-trigger[aria-invalid='true']:hover {
     border-color: var(--status-danger-fg);
   }
+  /* Forced colors drop the border color and the halo, so focus becomes an outline. */
+  @media (forced-colors: active) {
+    .pui-input:focus,
+    .pui-select-trigger:focus-visible {
+      outline: var(--focus-ring-width) solid Highlight;
+      outline-offset: var(--focus-ring-offset);
+    }
+  }
   @media (prefers-reduced-motion: reduce) {
     .pui-input,
     .pui-select-trigger {

package/dist/css/rules/file-upload.css

@@ -17,12 +17,13 @@
     clip-path: inset(50%);
     white-space: nowrap;
   }
+  /* One plane: the picker row, then a row per file. Rows meet at a line, and the
+     plane keeps one inset on every edge. */
   .pui-file-dropzone {
+    --file-inset: var(--space-5);
     display: flex;
-    flex-wrap: wrap;
-    align-items: center;
-    gap: var(--space-3);
-    padding: var(--space-5);
+    flex-direction: column;
+    padding-inline: var(--file-inset);
     border: 1px solid transparent;
     border-radius: var(--radius-lg);
     background: var(--surface);
@@ -31,6 +32,13 @@
   .pui-file-upload[data-dragging] .pui-file-dropzone {
     background: var(--selected);
   }
+  .pui-file-picker {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--space-3);
+    padding-block: var(--file-inset);
+  }
   .pui-file-trigger {
     flex-direction: row;
     width: fit-content;
@@ -74,18 +82,30 @@
   }
   .pui-file-list {
     display: grid;
-    gap: var(--space-2);
     list-style: none;
     padding: 0;
     margin: 0;
   }
+  /* The file's details lead its row and its actions end it, wrapping below when the
+     row is narrow. Progress and an upload error run under the whole row. */
   .pui-file-item {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--space-3) var(--space-4);
     min-width: 0;
-    padding: var(--space-4);
-    border-radius: var(--radius-md);
-    background: var(--surface);
+    padding-block: var(--space-3);
+    border-top: 1px solid var(--line);
+  }
+  .pui-file-item:last-child {
+    padding-block-end: var(--file-inset);
+  }
+  .pui-file-item > :not(.pui-file-info, .pui-file-actions) {
+    flex-basis: 100%;
   }
   .pui-file-info {
+    flex: 1 1 auto;
+    min-width: 0;
     display: flex;
     flex-wrap: wrap;
     align-items: center;
@@ -107,13 +127,9 @@
     display: flex;
     flex-wrap: wrap;
     gap: var(--space-2);
-    margin-top: var(--space-3);
-  }
-  .pui-file-item .pui-gauge {
-    margin-top: var(--space-3);
   }
   .pui-file-upload-error {
-    margin: var(--space-2) 0 0;
+    margin: 0;
     color: var(--status-danger-fg);
     font-size: var(--type-compact-size);
     line-height: var(--type-compact-leading);
@@ -126,7 +142,7 @@
   }
   @media (max-width: 760px) {
     .pui-file-dropzone {
-      padding: var(--space-4);
+      --file-inset: var(--space-4);
     }
   }
   @media (forced-colors: active) {
@@ -137,11 +153,6 @@
     .pui-file-upload[data-dragging] .pui-file-dropzone {
       border-color: Highlight;
     }
-    .pui-file-item {
-      border: 1px solid CanvasText;
-      background: Canvas;
-      color: CanvasText;
-    }
   }
   @media (prefers-reduced-motion: reduce) {
     .pui-file-dropzone {
@@ -151,6 +162,6 @@
 }
 @layer surflane.sizes {
   :where([data-ui-size], [data-ui-size] *).pui-file-dropzone {
-    padding: var(--ui-file-padding);
+    --file-inset: var(--ui-file-padding);
   }
 }

package/dist/css/rules/input-group.css

@@ -64,6 +64,13 @@
   }
   .pui-combobox-group[data-invalid],
   .pui-number-group[data-invalid] {
-    border-color: var(--status-danger-border);
+    border-color: var(--status-danger-fg);
+  }
+  @media (forced-colors: active) {
+    .pui-combobox-group:focus-within,
+    .pui-number-group:focus-within {
+      outline: var(--focus-ring-width) solid Highlight;
+      outline-offset: var(--focus-ring-offset);
+    }
   }
 }

package/dist/css/rules/scroll-area.css

@@ -12,6 +12,13 @@
     max-width: 100%;
     overscroll-behavior: auto;
     scrollbar-width: none !important;
+    outline: none;
+  }
+  /* A labeled scroller takes keyboard focus. Its root draws the shared ring, since
+     the viewport's edge fade would clip a ring drawn on the viewport itself. */
+  .pui-scroll-root:has(> .pui-scroll-viewport:focus-visible) {
+    outline: var(--focus-ring-width) solid var(--interaction-focus);
+    outline-offset: var(--focus-ring-offset);
   }
   .pui-scroll-viewport::-webkit-scrollbar {
     display: none;

package/dist/css/rules/select.css

@@ -55,6 +55,12 @@
   .pui-select-item[data-disabled] {
     opacity: var(--control-disabled-opacity);
   }
+  @media (forced-colors: active) {
+    .pui-select-item[data-highlighted] {
+      outline: 1px solid CanvasText;
+      outline-offset: -1px;
+    }
+  }
   .pui-select-check {
     position: absolute;
     inset-inline-start: var(--space-3);

package/dist/css/rules/slider.css

@@ -54,7 +54,8 @@
     border-radius: var(--radius-full);
     background: var(--canvas);
   }
-  .pui-slider-thumb:focus-within {
+  /* The thumb's input is focused on pointer use too; only keyboard focus rings. */
+  .pui-slider-thumb:has(:focus-visible) {
     outline: var(--focus-ring-width) solid var(--interaction-focus);
     outline-offset: var(--focus-ring-offset);
   }

package/dist/file-upload.js

@@ -296,51 +296,51 @@ export const FileUpload = /* @__PURE__ */ React.forwardRef(function FileUpload({
                         event.preventDefault();
                         select(Array.from(event.dataTransfer.files), 'drop');
                     }
-                }, children: [_jsx(Field.Control, { ref: input, id: inputId, name: name, form: form, type: 'file', accept: accept, capture: capture, multiple: multiple, required: required, disabled: disabled, className: 'pui-file-native', "aria-describedby": errorId, onKeyDown: (event) => {
-                            if (event.key === 'Enter')
-                                event.preventBaseUIHandler();
-                        }, onChange: (event) => {
-                            if (!notifying.current) {
-                                event.preventBaseUIHandler();
-                                select(Array.from(event.currentTarget.files ?? []), 'select');
-                            }
-                        } }), _jsxs("label", { htmlFor: inputId, className: 'pui-button pui-file-trigger', "data-variant": 'outline', "data-disabled": disabled || undefined, children: [_jsx(Icon, { name: 'upload' }), labels.choose] }), _jsx("p", { className: 'pui-file-drop-hint', children: labels.drop })] }), _jsx("div", { id: errorId, role: 'alert', className: 'pui-file-errors', children: rejections.length > 0 && (_jsx("ul", { children: rejections.map((rejection, index) => (_jsx("li", { children: labels.rejection(rejection) }, index))) })) }), _jsx(Field.Error, {}), files.length > 0 && (_jsx("ul", { className: 'pui-file-list', role: 'list', children: files.map((file) => {
-                    const state = metadata.get(file) ?? {
-                        status: 'ready',
-                        progress: null,
-                    };
-                    if (!identities.current.has(file))
-                        identities.current.set(file, `${uid}-${++nextId.current}`);
-                    const itemId = identities.current.get(file);
-                    return (_jsxs("li", { className: 'pui-file-item', children: [_jsxs("div", { className: 'pui-file-info', children: [_jsx("strong", { children: file.name }), _jsx("span", { children: sizeLabel(file.size) }), _jsx(StatusBadge, { tone: state.status === 'success'
-                                            ? 'success'
-                                            : state.status === 'error'
-                                                ? 'danger'
-                                                : state.status === 'uploading'
-                                                    ? 'progress'
-                                                    : 'neutral', children: labels.status[state.status] })] }), state.status === 'uploading' && (_jsx(Progress.Root, { value: state.progress, "aria-label": labels.progress(file), children: _jsx(Progress.Track, { children: _jsx(Progress.Indicator, {}) }) })), state.error && (_jsx("p", { id: `${itemId}-error`, className: 'pui-file-upload-error', children: state.error })), _jsxs("div", { className: 'pui-file-actions', children: [transport && state.status !== 'success' && (_jsx(Button, { ref: (node) => {
-                                            if (node)
-                                                primaryButtons.current.set(file, node);
-                                            else
-                                                primaryButtons.current.delete(file);
-                                        }, type: 'button', size: 'sm', variant: 'outline', disabled: disabled, "aria-describedby": state.error ? `${itemId}-error` : undefined, "aria-label": `${state.status === 'uploading' ? labels.cancel : state.status === 'ready' ? labels.upload : labels.retry} ${file.name}`, onClick: () => {
-                                            if (state.status === 'uploading')
-                                                cancel(file);
-                                            else
-                                                void upload(file);
-                                        }, children: state.status === 'uploading'
-                                            ? labels.cancel
-                                            : state.status === 'ready'
-                                                ? labels.upload
-                                                : labels.retry })), _jsx(Button, { type: 'button', size: 'sm', variant: 'ghost', ref: (node) => {
-                                            if (node)
-                                                removeButtons.current.set(file, node);
-                                            else
-                                                removeButtons.current.delete(file);
-                                        }, disabled: disabled, "aria-label": `${labels.remove} ${file.name}`, onClick: () => {
-                                            setRejections([]);
-                                            if (commit(files.filter((current) => current !== file), 'remove'))
-                                                focusPicker.current = file;
-                                        }, children: labels.remove })] })] }, itemId));
-                }) })), _jsx("span", { className: 'pui-visually-hidden', role: 'status', children: announcement })] }));
+                }, children: [_jsxs("div", { className: 'pui-file-picker', children: [_jsx(Field.Control, { ref: input, id: inputId, name: name, form: form, type: 'file', accept: accept, capture: capture, multiple: multiple, required: required, disabled: disabled, className: 'pui-file-native', "aria-describedby": errorId, onKeyDown: (event) => {
+                                    if (event.key === 'Enter')
+                                        event.preventBaseUIHandler();
+                                }, onChange: (event) => {
+                                    if (!notifying.current) {
+                                        event.preventBaseUIHandler();
+                                        select(Array.from(event.currentTarget.files ?? []), 'select');
+                                    }
+                                } }), _jsxs("label", { htmlFor: inputId, className: 'pui-button pui-file-trigger', "data-variant": 'outline', "data-disabled": disabled || undefined, children: [_jsx(Icon, { name: 'upload' }), labels.choose] }), _jsx("p", { className: 'pui-file-drop-hint', children: labels.drop })] }), files.length > 0 && (_jsx("ul", { className: 'pui-file-list', role: 'list', children: files.map((file) => {
+                            const state = metadata.get(file) ?? {
+                                status: 'ready',
+                                progress: null,
+                            };
+                            if (!identities.current.has(file))
+                                identities.current.set(file, `${uid}-${++nextId.current}`);
+                            const itemId = identities.current.get(file);
+                            return (_jsxs("li", { className: 'pui-file-item', children: [_jsxs("div", { className: 'pui-file-info', children: [_jsx("strong", { children: file.name }), _jsx("span", { children: sizeLabel(file.size) }), _jsx(StatusBadge, { tone: state.status === 'success'
+                                                    ? 'success'
+                                                    : state.status === 'error'
+                                                        ? 'danger'
+                                                        : state.status === 'uploading'
+                                                            ? 'progress'
+                                                            : 'neutral', children: labels.status[state.status] })] }), _jsxs("div", { className: 'pui-file-actions', children: [transport && state.status !== 'success' && (_jsx(Button, { ref: (node) => {
+                                                    if (node)
+                                                        primaryButtons.current.set(file, node);
+                                                    else
+                                                        primaryButtons.current.delete(file);
+                                                }, type: 'button', size: 'sm', variant: 'outline', disabled: disabled, "aria-describedby": state.error ? `${itemId}-error` : undefined, "aria-label": `${state.status === 'uploading' ? labels.cancel : state.status === 'ready' ? labels.upload : labels.retry} ${file.name}`, onClick: () => {
+                                                    if (state.status === 'uploading')
+                                                        cancel(file);
+                                                    else
+                                                        void upload(file);
+                                                }, children: state.status === 'uploading'
+                                                    ? labels.cancel
+                                                    : state.status === 'ready'
+                                                        ? labels.upload
+                                                        : labels.retry })), _jsx(Button, { type: 'button', size: 'sm', variant: 'ghost', ref: (node) => {
+                                                    if (node)
+                                                        removeButtons.current.set(file, node);
+                                                    else
+                                                        removeButtons.current.delete(file);
+                                                }, disabled: disabled, "aria-label": `${labels.remove} ${file.name}`, onClick: () => {
+                                                    setRejections([]);
+                                                    if (commit(files.filter((current) => current !== file), 'remove'))
+                                                        focusPicker.current = file;
+                                                }, children: labels.remove })] }), state.status === 'uploading' && (_jsx(Progress.Root, { value: state.progress, "aria-label": labels.progress(file), children: _jsx(Progress.Track, { children: _jsx(Progress.Indicator, {}) }) })), state.error && (_jsx("p", { id: `${itemId}-error`, className: 'pui-file-upload-error', children: state.error }))] }, itemId));
+                        }) }))] }), _jsx("div", { id: errorId, role: 'alert', className: 'pui-file-errors', children: rejections.length > 0 && (_jsx("ul", { children: rejections.map((rejection, index) => (_jsx("li", { children: labels.rejection(rejection) }, index))) })) }), _jsx(Field.Error, {}), _jsx("span", { className: 'pui-feedback-sr', role: 'status', children: announcement })] }));
 });

package/dist/pagination.js

@@ -32,8 +32,10 @@ export const Pagination = /* @__PURE__ */ React.forwardRef(function Pagination({
             'aria-label': name,
             'aria-current': currentPage ? 'page' : undefined,
         };
+        // An inactive page is a link with no destination: it keeps its name and reads as
+        // unavailable, as a disabled Button does. A plain span could carry neither.
         if (getPageHref)
-            return inactive ? (_jsx("span", { ...attributes, "aria-disabled": 'true', children: children })) : (_jsx("a", { ...attributes, href: getPageHref(target), children: children }));
+            return inactive ? (_jsx("a", { ...attributes, role: 'link', "aria-disabled": 'true', children: children })) : (_jsx("a", { ...attributes, href: getPageHref(target), children: children }));
         return (_jsx(Button, { ...attributes, variant: 'ghost', type: 'button', disabled: inactive, onClick: () => {
                 if (target !== current)
                     onPageChange?.(target);

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.7.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.7.0",
+    "@surflane/design-tokens": "^0.9.0",
     "@tanstack/react-virtual": "^3.14.21",
     "react": "^19.0.0",
     "react-aria-components": "^1.22.1",