@eunomia/elements 1.0.0-beta.3 → 1.0.0-beta.4

package/dist/index.js

@@ -25,6 +25,9 @@
 // alongside them, composing the others and writing the result onto
 // `document.documentElement`, exported so a consumer doesn't have to
 // reassemble that composition themselves just to apply a custom brand.
+// `buildThemeCss` is its pure counterpart, returning the same tokens as a
+// stylesheet so an SSR app can ship the brand in the HTML itself instead
+// of flashing the base theme until `initializeTheme` runs after hydration.
 // `EUNOMIA_BREAKPOINTS` is exported so a consumer's own responsive layout
 // code can switch at the exact same pixel widths the components already
 // react to internally, instead of guessing or duplicating those numbers.
@@ -103,8 +106,8 @@ export { debounce, throttle } from "./utils/time.utils.js";
 export { createDragReorder } from "./utils/drag-drop.utils.js";
 export { EUNOMIA_BREAKPOINTS } from "./breakpoints.js";
 export { setDefaultLocale, getDefaultLocale } from "./i18n/index.js";
-export { buildPalette, buildTints, initializeTheme, } from "./utils/theme-generator.utils.js";
-export { findRichTextColor, formatRichText, getPlainTextLength, joinAlign, RICH_TEXT_COLORS, splitAlign, } from "./utils/rich-text.utils.js";
+export { buildPalette, buildTints, buildThemeCss, initializeTheme, } from "./utils/theme-generator.utils.js";
+export { findRichTextColor, formatRichText, getPlainTextLength, joinAlign, parseInlineNodes, RICH_TEXT_COLORS, splitAlign, toHtml, toPlainText, } from "./utils/rich-text.utils.js";
 export { LoadMoreEvent } from "./events/loadmore.event.js";
 export { PageChangeEvent } from "./events/pagechange.event.js";
 export { PageSizeChangeEvent } from "./events/pagesizechange.event.js";

package/dist/jsx.d.ts

@@ -20,14 +20,27 @@
  * erased, so importing it (`import type {} from "@eunomia/elements/jsx"`)
  * never calls `customElements.define(...)` and carries none of the SSR
  * risk a value import of a component does. `react`'s types describe
- * `DOMAttributes`/`Ref` here, but only as a type dependency: this package
- * still doesn't depend on React at runtime, so a non-React consumer never
- * resolves this module at all.
+ * `HTMLAttributes`/`Key`/`Ref` here, but only as a type dependency: this
+ * package still doesn't depend on React at runtime, so a non-React
+ * consumer never resolves this module at all.
  */
-import type { DOMAttributes, Ref } from "react";
+import type { HTMLAttributes, Key, Ref } from "react";
 type EunomiaTagName = Extract<keyof HTMLElementTagNameMap, `eun-${string}`>;
-type EunomiaElementProps<T> = Partial<Omit<T, keyof HTMLElement>> & DOMAttributes<T> & {
+type EunomiaOwnProps<T> = Partial<Omit<T, keyof HTMLElement | keyof HTMLOrSVGElement>>;
+/**
+ * Props allowed on a `<eun-*>` tag in TSX: the element's own reactive
+ * properties, plus every standard HTML/ARIA attribute and event handler
+ * React already knows about (id, style, title, tabIndex, aria-*, onClick,
+ * ...). `className` is deliberately excluded: React only rewrites it to
+ * the `class` attribute for elements it recognizes, not arbitrary custom
+ * elements — `class` is the one that actually works here. Custom events
+ * (`eunnavigate`, `eunchange`, ...) aren't included — those are typed and
+ * wired per-component with a ref, when that component is migrated.
+ */
+type EunomiaElementProps<T> = EunomiaOwnProps<T> & Omit<HTMLAttributes<T>, "className" | keyof EunomiaOwnProps<T>> & {
     ref?: Ref<T>;
+    key?: Key | null;
+    class?: string;
 };
 type EunomiaJSXElements = {
     [K in EunomiaTagName]: EunomiaElementProps<HTMLElementTagNameMap[K]>;

package/dist/mixins/button.mixin.d.ts

@@ -41,6 +41,7 @@ export type EunomiaButtonAppearance = EunomiaAppearance;
 export declare class ButtonMixinInterface {
     type?: ButtonType;
     variant?: ButtonVariant;
+    fixedColor?: boolean;
     size?: ButtonSize;
     rounded?: boolean;
     slide?: boolean;

package/dist/mixins/button.mixin.js

@@ -26,6 +26,13 @@ export const ButtonMixin = (superClass) => {
              * @default "button"
              */
             this.type = "button";
+            /**
+             * Keeps a `light` or `dark` button white or black in every theme.
+             * Without it, they follow the grey scale, which flips with the active
+             * theme. Has no effect on the other variants.
+             * @default false
+             */
+            this.fixedColor = false;
             /**
              * The button size.
              * @default "m"
@@ -152,6 +159,9 @@ export const ButtonMixin = (superClass) => {
     __decorate([
         property({ reflect: true })
     ], ButtonMixinClass.prototype, "variant", void 0);
+    __decorate([
+        property({ type: Boolean, reflect: true, attribute: "fixed-color" })
+    ], ButtonMixinClass.prototype, "fixedColor", void 0);
     __decorate([
         property({ reflect: true })
     ], ButtonMixinClass.prototype, "size", void 0);

package/dist/mixins/check.mixin.d.ts

@@ -21,4 +21,4 @@ export declare class CheckMixinInterface {
  * @template T A LitElement class extended with other mixins (Disabled, Readonly, Validators, Form).
  * @returns A class extending the provided superclass with checkable behavior.
  */
-export declare const CheckMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface & FormMixinInterface<string>>>(superClass: T) => Constructor<CheckMixinInterface> & T;
+export declare const CheckMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface<unknown> & FormMixinInterface<string>>>(superClass: T) => Constructor<CheckMixinInterface> & T;

package/dist/mixins/editable.mixin.d.ts

@@ -29,4 +29,4 @@ export declare class EditableMixinInterface {
  * shape (e.g. `string` for a single-value field, `string[]` for a multi-value one).
  * @returns A class extending the provided superclass with editable behavior.
  */
-export declare const EditableMixin: <U, T extends Constructor<LitElement & DisabledMixinInterface & ValidatorsMixinInterface & FormMixinInterface<U>>>(superClass: T) => Constructor<EditableMixinInterface> & T;
+export declare const EditableMixin: <U, T extends Constructor<LitElement & DisabledMixinInterface & ValidatorsMixinInterface<unknown> & FormMixinInterface<U>>>(superClass: T) => Constructor<EditableMixinInterface> & T;

package/dist/mixins/form.mixin.d.ts

@@ -13,12 +13,14 @@ export declare class FormMixinInterface<T> {
     setFormValue(value?: T): void;
     renderDescription(): typeof nothing | TemplateResult;
     name?: string;
+    hint?: string;
     description?: string | string[] | undefined;
     valueState?: T;
     hideError?: boolean;
     form: HTMLFormElement | null;
     dirty: boolean;
     touched: boolean;
+    controlled: boolean;
     get pristine(): boolean;
     get untouched(): boolean;
     get value(): T;
@@ -32,4 +34,6 @@ export declare class FormMixinInterface<T> {
  * @param superClass - Base class to extend.
  * @returns A class extending the provided base with form capabilities.
  */
-export declare const FormMixin: <T extends Constructor<LitElement & ValidatorsMixinInterface & DisabledMixinInterface>, U>(superClass: T) => Constructor<FormMixinInterface<U>> & T;
+type ValidatorsMixinShape = Omit<ValidatorsMixinInterface, "validators">;
+export declare const FormMixin: <T extends Constructor<LitElement & ValidatorsMixinShape & DisabledMixinInterface>, U>(superClass: T) => Constructor<FormMixinInterface<U>> & T;
+export {};

package/dist/mixins/form.mixin.js

@@ -13,13 +13,6 @@ import { html, nothing } from "lit";
 import { property, state } from "lit/decorators.js";
 import { when } from "lit/directives/when.js";
 import { ChangeEvent } from "../events/change.event.js";
-/**
- * Mixin that adds form-related behavior and value management.
- *
- * @template U - Type of the form field value.
- * @param superClass - Base class to extend.
- * @returns A class extending the provided base with form capabilities.
- */
 export const FormMixin = (superClass) => {
     var _FormMixinClass_markDirty, _FormMixinClass_markTouched;
     class FormMixinClass extends superClass {
@@ -60,6 +53,23 @@ export const FormMixin = (superClass) => {
              * @default false
              */
             this.touched = false;
+            /**
+             * Opts this field out of the native reset algorithm's value wipe: when
+             * `true`, `formResetCallback` leaves `value`/`checked` untouched.
+             *
+             * Exists for consumers who drive `value` as a controlled React prop
+             * (or equivalent in another framework): a browser-native `form.reset()`
+             * cannot be observed by React's reconciler unless a prop actually
+             * changes, so a native input only "survives" a stray reset (e.g. the
+             * unconditional one `useActionState` triggers via `requestFormReset` on
+             * every `<form action={fn}>` submission, success or not) because
+             * react-dom force-resyncs its `.value` on every commit — a defense
+             * custom elements don't get. Setting `controlled` makes the field's own
+             * app state the sole source of truth for `value`: the app decides when
+             * to clear it, the same way it already decides what to display it as.
+             * @default false
+             */
+            this.controlled = false;
             /**
              * Marks the field dirty on its own `eunchange` — dispatched only from a
              * genuine user-interaction handler, never from the `value`/`checked`
@@ -255,13 +265,20 @@ export const FormMixin = (superClass) => {
          * `value` attribute. Skipping the assignment there (as an earlier
          * version of this method did) left a typed-in value stuck after
          * `form.reset()`.
+         *
+         * Skips that assignment entirely when {@link controlled} is set: the
+         * consuming app owns `value` in that mode, so this callback only clears
+         * {@link dirty}/{@link touched}, leaving the value itself for the app
+         * to update (or not) on its own terms.
          */
         formResetCallback() {
-            if (this.checkable) {
-                this.checked = false;
-            }
-            else {
-                this.value = this.defaultValue;
+            if (!this.controlled) {
+                if (this.checkable) {
+                    this.checked = false;
+                }
+                else {
+                    this.value = this.defaultValue;
+                }
             }
             this.dirty = false;
             this.touched = false;
@@ -326,6 +343,9 @@ export const FormMixin = (superClass) => {
     __decorate([
         state()
     ], FormMixinClass.prototype, "touched", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], FormMixinClass.prototype, "controlled", void 0);
     __decorate([
         property({
             attribute: "default-value",

package/dist/mixins/overflow-navigation.mixin.js

@@ -77,9 +77,10 @@ export const NavigationOverflowMixin = (superClass) => {
         }
         /**
          * Determines if the scrollable element is currently overflowing.
+         * Overridable, for content that isn't all in the `navigation` slot.
          *
          * @returns true if on overflow, false otherwise.
-         * @private
+         * @protected
          */
         isOnOverflow() {
             const slot = this.shadowRoot?.querySelector('slot[name="navigation"]');

package/dist/mixins/radio.mixin.d.ts

@@ -28,4 +28,4 @@ export declare class RadioMixinInterface {
  * @template T A LitElement class extended with other mixins (Disabled, Readonly, Validators, Form).
  * @returns A class extending the provided superclass with radio behavior.
  */
-export declare const RadioMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface & FormMixinInterface<string>>>(superClass: T) => Constructor<RadioMixinInterface> & T;
+export declare const RadioMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface<unknown> & FormMixinInterface<string>>>(superClass: T) => Constructor<RadioMixinInterface> & T;

package/dist/mixins/validators.mixin.d.ts

@@ -1,5 +1,5 @@
 import { LitElement } from "lit";
-import { Mutable } from "../types/form-validators.type.js";
+import { Mutable, Validators } from "../types/form-validators.type.js";
 import { Constructor } from "../utils/constructor.type.js";
 /**
  * Defines a Validity object.
@@ -11,8 +11,13 @@ export interface Validity {
 /**
  * Interface defining the contract for components using `ValidatorsMixin`.
  * Provides integration with the native form lifecycle,
+ *
+ * @template U Type of value being validated — same as the type parameter
+ * passed to `ValidatorsMixin` itself, kept in sync by hand at each call
+ * site since it can't be inferred from `ValidatorsMixin(superClass)`'s own
+ * single argument.
  */
-export declare class ValidatorsMixinInterface {
+export declare class ValidatorsMixinInterface<U = unknown> {
     checkLocalValidators: () => Validity;
     buildCommonValidators: () => Validity;
     checkValidity: (dataToCheck: any) => boolean;
@@ -21,6 +26,7 @@ export declare class ValidatorsMixinInterface {
     required: boolean;
     errorMessages: string[];
     validationMessage: string | string[];
+    validators?: Validators<U>[];
 }
 /**
  * Mixin that adds validation capabilities to a LitElement.
@@ -28,4 +34,4 @@ export declare class ValidatorsMixinInterface {
  * @template U Type of value being validated.
  * @param superClass Base class to extend.
  */
-export declare const ValidatorsMixin: <T extends Constructor<LitElement>, U>(superClass: T) => Constructor<ValidatorsMixinInterface> & T;
+export declare const ValidatorsMixin: <T extends Constructor<LitElement>, U>(superClass: T) => Constructor<ValidatorsMixinInterface<U>> & T;

package/dist/utils/rich-text.utils.d.ts

@@ -146,6 +146,39 @@ export declare function renderInline(nodes: InlineNode[]): TemplateResult;
  * @returns the formatted template.
  */
 export declare function formatRichText(text: string): TemplateResult;
+/**
+ * Strips every Markdown-lite marker from a value and returns what a reader
+ * actually sees, as a plain string : the `[align:...]` directive, `**`,
+ * `{color=name}`, link URLs and so on are removed (a link keeps its label),
+ * and one newline is kept between lines. Needs no DOM, so it runs anywhere,
+ * including on the server, unlike {@link formatRichText}.
+ *
+ * Always consistent with {@link getPlainTextLength} :
+ * `toPlainText(text).length === getPlainTextLength(text)`. Handy for
+ * structured data (JSON-LD), meta descriptions, search indexes or
+ * notifications.
+ *
+ * @param text the raw Markdown-lite string.
+ * @returns the plain text.
+ */
+export declare function toPlainText(text: string): string;
+/**
+ * Converts a Markdown-lite string into an HTML string, with the same markup
+ * as {@link formatRichText} (`<p>`, `<ul>`, `<strong>`, ...). Needs no DOM
+ * and no Lit, so it fits server rendering (a Next.js Server Component, an
+ * email, an RSS feed) where {@link formatRichText}'s template can't be used.
+ *
+ * Every piece of text and every attribute is escaped, and a link whose URL
+ * uses anything other than a relative path, a fragment, `http`, `https`,
+ * `mailto` or `tel` (such as `javascript:`) is rendered as its plain label,
+ * so the result is safe to inject with `innerHTML` or React's
+ * `dangerouslySetInnerHTML`. The `[align:...]` directive is stripped, read
+ * it with {@link splitAlign} if you need it.
+ *
+ * @param text the raw Markdown-lite string.
+ * @returns the HTML string.
+ */
+export declare function toHtml(text: string): string;
 /**
  * Populates a contenteditable root with the given Markdown-lite value,
  * replacing its entire content — used both for the `formatting` toolbar's

package/dist/utils/rich-text.utils.js

@@ -126,15 +126,6 @@ export function parseInlineNodes(text) {
                 continue;
             }
         }
-        // `***text***` : bold and italic together produce adjacent `**`+`*`
-        // delimiters at both ends (from nesting `<strong><em>`/`</em></strong>`),
-        // which the plain `**` check below can't tell apart from "close bold,
-        // then a stray, unmatched italic `*`" — it greedily consumes the first
-        // two of the three as bold's own closer, leaving the third orphaned
-        // with no closer of its own within the once-was-italic content, and
-        // the italic wrapping is silently lost on reparse. Handling the
-        // three-character run as one atomic unit first — same convention real
-        // Markdown uses for `***bold italic***` — avoids that ambiguity.
         if (text.startsWith("***", i)) {
             const closeIndex = text.indexOf("***", i + 3);
             if (closeIndex !== -1) {
@@ -266,6 +257,39 @@ function renderInlineNode(node) {
             return html `<a href=${node.href}>${renderInline(node.children)}</a>`;
     }
 }
+/**
+ * Splits a Markdown-lite body (without its `[align:...]` directive) into
+ * blocks : consecutive `- ` lines become one list, other non-empty lines
+ * become paragraphs, and empty lines are dropped. Shared by every output
+ * format ({@link formatRichText}, {@link toHtml}, {@link toPlainText}) so
+ * they can never disagree on what counts as a paragraph or a list.
+ *
+ * @param body the Markdown-lite body.
+ * @returns the blocks, in order.
+ */
+function splitBlocks(body) {
+    const blocks = [];
+    let list = [];
+    const flushList = () => {
+        if (list.length) {
+            blocks.push({ type: "list", items: list });
+            list = [];
+        }
+    };
+    body.split("\n").forEach((line) => {
+        const trimmed = line.trim();
+        if (trimmed.startsWith("- ")) {
+            list.push(trimmed.slice(2));
+            return;
+        }
+        flushList();
+        if (trimmed) {
+            blocks.push({ type: "paragraph", text: trimmed });
+        }
+    });
+    flushList();
+    return blocks;
+}
 /**
  * Converts a multi-line Markdown-lite string into a Lit template — see
  * {@link parseInlineNodes} for the supported inline syntax.
@@ -284,30 +308,115 @@ function renderInlineNode(node) {
  */
 export function formatRichText(text) {
     const { body } = splitAlign(text);
-    const blocks = [];
-    let listBuffer = [];
-    const flushList = () => {
-        if (!listBuffer.length) {
-            return;
-        }
-        blocks.push(html `<ul>
-        ${listBuffer.map((item) => html `<li>${renderInline(parseInlineNodes(item))}</li>`)}
-      </ul>`);
-        listBuffer = [];
-    };
-    body.split("\n").forEach((line) => {
-        const trimmed = line.trim();
-        if (trimmed.startsWith("- ")) {
-            listBuffer.push(trimmed.slice(2));
-            return;
+    return html `${splitBlocks(body).map((block) => block.type === "list"
+        ? html `<ul>
+          ${block.items.map((item) => html `<li>${renderInline(parseInlineNodes(item))}</li>`)}
+        </ul>`
+        : html `<p>${renderInline(parseInlineNodes(block.text))}</p>`)}`;
+}
+function inlineToPlainText(nodes) {
+    return nodes
+        .map((node) => node.type === "text" ? node.value : inlineToPlainText(node.children))
+        .join("");
+}
+/**
+ * Strips every Markdown-lite marker from a value and returns what a reader
+ * actually sees, as a plain string : the `[align:...]` directive, `**`,
+ * `{color=name}`, link URLs and so on are removed (a link keeps its label),
+ * and one newline is kept between lines. Needs no DOM, so it runs anywhere,
+ * including on the server, unlike {@link formatRichText}.
+ *
+ * Always consistent with {@link getPlainTextLength} :
+ * `toPlainText(text).length === getPlainTextLength(text)`. Handy for
+ * structured data (JSON-LD), meta descriptions, search indexes or
+ * notifications.
+ *
+ * @param text the raw Markdown-lite string.
+ * @returns the plain text.
+ */
+export function toPlainText(text) {
+    const { body } = splitAlign(text);
+    const lines = body.length ? body.split("\n") : [""];
+    return lines
+        .map((line) => inlineToPlainText(parseInlineNodes(line)))
+        .join("\n");
+}
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+}
+const SAFE_URL_SCHEMES = new Set(["http:", "https:", "mailto:", "tel:"]);
+/**
+ * Whether a link destination is safe to put in an `href` : relative URLs,
+ * fragments and the `http`, `https`, `mailto` and `tel` schemes. Anything
+ * else (`javascript:`, `data:`, ...) is refused.
+ *
+ * @param href the raw destination.
+ * @returns `true` when it can be emitted as an `href`.
+ */
+function isSafeHref(href) {
+    const normalized = href.replace(/[\u0000-\u0020]/g, "");
+    const scheme = /^([a-z][a-z0-9+.-]*:)/i.exec(normalized);
+    return !scheme || SAFE_URL_SCHEMES.has(scheme[1].toLowerCase());
+}
+function inlineToHtml(nodes) {
+    return nodes.map(inlineNodeToHtml).join("");
+}
+function inlineNodeToHtml(node) {
+    switch (node.type) {
+        case "text":
+            return escapeHtml(node.value);
+        case "bold":
+            return `<strong>${inlineToHtml(node.children)}</strong>`;
+        case "italic":
+            return `<em>${inlineToHtml(node.children)}</em>`;
+        case "underline":
+            return `<u>${inlineToHtml(node.children)}</u>`;
+        case "color": {
+            const color = findRichTextColor(node.color);
+            return `<span data-color="${escapeHtml(node.color)}" style="color: ${color?.text ?? "inherit"}">${inlineToHtml(node.children)}</span>`;
         }
-        flushList();
-        if (trimmed) {
-            blocks.push(html `<p>${renderInline(parseInlineNodes(trimmed))}</p>`);
+        case "highlight": {
+            const color = findRichTextColor(node.color);
+            return `<span data-highlight="${escapeHtml(node.color)}" style="background-color: ${color?.highlight ?? "transparent"}">${inlineToHtml(node.children)}</span>`;
         }
-    });
-    flushList();
-    return html `${blocks}`;
+        case "link":
+            return isSafeHref(node.href)
+                ? `<a href="${escapeHtml(node.href)}">${inlineToHtml(node.children)}</a>`
+                : inlineToHtml(node.children);
+    }
+}
+/**
+ * Converts a Markdown-lite string into an HTML string, with the same markup
+ * as {@link formatRichText} (`<p>`, `<ul>`, `<strong>`, ...). Needs no DOM
+ * and no Lit, so it fits server rendering (a Next.js Server Component, an
+ * email, an RSS feed) where {@link formatRichText}'s template can't be used.
+ *
+ * Every piece of text and every attribute is escaped, and a link whose URL
+ * uses anything other than a relative path, a fragment, `http`, `https`,
+ * `mailto` or `tel` (such as `javascript:`) is rendered as its plain label,
+ * so the result is safe to inject with `innerHTML` or React's
+ * `dangerouslySetInnerHTML`. The `[align:...]` directive is stripped, read
+ * it with {@link splitAlign} if you need it.
+ *
+ * @param text the raw Markdown-lite string.
+ * @returns the HTML string.
+ */
+export function toHtml(text) {
+    const { body } = splitAlign(text);
+    return splitBlocks(body)
+        .map((block) => block.type === "list"
+        ? `<ul>${block.items
+            .map((item) => `<li>${inlineToHtml(parseInlineNodes(item))}</li>`)
+            .join("")}</ul>`
+        : `<p>${inlineToHtml(parseInlineNodes(block.text))}</p>`)
+        .join("");
 }
 /**
  * Builds one `<p>` per line of `body`, each with its inline Markdown-lite
@@ -351,13 +460,6 @@ function buildParagraphs(body) {
     render(html `${lines.map((line) => html `<p>${renderInline(parseInlineNodes(line))}</p>`)}`, scratch);
     stripComments(scratch);
     const paragraphs = Array.from(scratch.children);
-    // A genuinely empty <p> (an empty line, most commonly the sole paragraph
-    // of an otherwise-empty field) has no content a browser can anchor a
-    // caret inside — clicking into it then often places the caret at the
-    // *root* level instead, right before the <p>, so anything typed lands
-    // there as a stray text node the block-based serializer never sees
-    // (value silently stays empty forever). A <br> gives every empty
-    // paragraph a real caret position of its own.
     paragraphs.forEach((paragraph) => {
         if (!paragraph.hasChildNodes()) {
             paragraph.appendChild(document.createElement("br"));
@@ -394,20 +496,9 @@ const INLINE_TAG_MARKERS = {
 };
 function serializeInlineNode(node) {
     if (node.nodeType === Node.TEXT_NODE) {
-        // U+200B (zero-width space) : the textarea's own toolbar uses it as an
-        // invisible caret anchor for a "pending" mark toggled with nothing
-        // selected (see textarea.ts's `PENDING_CARET_TEXT`) ; a real character
-        // a browser can place a caret next to inside an otherwise-empty inline
-        // element, but never meant to be real content, so it never survives
-        // into `value`.
         return (node.textContent ?? "").replace(/\u200B/g, "");
     }
     if (node.nodeName === "BR") {
-        // The editor only ever inserts a `<br>` as an empty paragraph's sole
-        // child (so it stays focusable/visible) — never as a mid-paragraph soft
-        // break — so it always serializes to nothing, not a newline (block
-        // boundaries already produce one `\n` per paragraph in
-        // `serializeEditableRoot`).
         return "";
     }
     if (!(node instanceof HTMLElement)) {

package/dist/utils/theme-generator.utils.d.ts

@@ -5,11 +5,12 @@
  * theme" widget run; see Theming > Custom theme for how it works and why
  * each step is shaped the way it is.
  *
- * Only `buildPalette`, `buildTints`, and `initializeTheme` (plus the
- * types their signatures need) are exported from `index.ts`. Everything
+ * Only `buildPalette`, `buildTints`, `initializeTheme`, and
+ * `buildThemeCss` (plus the types their signatures need) are exported
+ * from `index.ts`. Everything
  * else below, the raw color math, the shade/tint step definitions, is
  * kept file-private on purpose: none of it is meant to be reached on its
- * own, it exists to be composed by those three, and every extra export
+ * own, it exists to be composed by those four, and every extra export
  * is a promise to a consumer that constrains how this file can change
  * later. If a real need for one of these on its own ever comes up, it's
  * a one-line change to export it.
@@ -60,6 +61,26 @@ export declare function buildTints(primaryHex: EunomiaHexColor, isDark: boolean)
  *
  * Client-side only: call it once the DOM exists (after mount, not during
  * an SSR render), since it writes directly to `document.documentElement`.
+ * Because it only runs after the page has painted, the base theme shows
+ * for a frame first; `buildThemeCss` below avoids that flash.
  */
 export declare function initializeTheme(primary: EunomiaHexColor, secondary: EunomiaHexColor, isDark?: boolean, surfaceColor?: EunomiaHexColor, darkSurfaceColor?: EunomiaHexColor, fontFamily?: string): void;
+export interface EunomiaThemeCssOptions {
+    surfaceColor?: EunomiaHexColor;
+    darkSurfaceColor?: EunomiaHexColor;
+    fontFamily?: string;
+    brand?: string;
+}
+/**
+ * The pure, stylesheet counterpart of `initializeTheme`: the same tokens,
+ * for both light and dark mode, returned as a CSS string instead of being
+ * written onto the DOM. Render it in a `<style>` in the document `<head>`
+ * (during SSR, or at build time) and the custom brand is there on first
+ * paint, with no flash of the base theme while the app hydrates.
+ *
+ * The rules are prefixed with `:root` so they outrank the prebuilt
+ * `[data-brand][data-theme]` rules whatever the stylesheet order, and
+ * switching mode is just a `data-theme` change, no regeneration needed.
+ */
+export declare function buildThemeCss(primary: EunomiaHexColor, secondary: EunomiaHexColor, options?: EunomiaThemeCssOptions): string;
 export {};