tungsten 0.3.3 → 0.3.4

package/dist/components/library/RichTextEditor/RichTextEditor.js

@@ -0,0 +1,458 @@
+function _defineProperty(e, r, t) {
+  return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+    value: t,
+    enumerable: !0,
+    configurable: !0,
+    writable: !0
+  }) : e[r] = t, e;
+}
+function _toPropertyKey(t) {
+  var i = _toPrimitive(t, "string");
+  return "symbol" == typeof i ? i : i + "";
+}
+function _toPrimitive(t, r) {
+  if ("object" != typeof t || !t) return t;
+  var e = t[Symbol.toPrimitive];
+  if (void 0 !== e) {
+    var i = e.call(t, r || "default");
+    if ("object" != typeof i) return i;
+    throw new TypeError("@@toPrimitive must return a primitive value.");
+  }
+  return ("string" === r ? String : Number)(t);
+}
+import { TungstenStatefulComponent } from "../../../Components.js";
+import { createElementRef } from "../../../createRef.js";
+import { combineClassNames } from "../../../helpers/combineClassNames.js";
+import { parseHtml } from "../../../rawHtml/parseHtml.js";
+import { safeHtmlAllowList } from "../../../rawHtml/safeHtmlAllowList.js";
+import { activeFormatsAt } from "./activeFormats.js";
+import { serializeContentTree } from "./contentTree.js";
+import { sanitizeAuthoredHtml } from "./sanitizeAuthoredHtml.js";
+import { jsx as _jsx, jsxs as _jsxs } from "tungsten/jsxRuntime.js";
+const formatBlockOptions = [
+// Applying this produces a <p> which the sanitizer then flattens back to
+// inline content — the way out of a heading or quote, and the state plain
+// text reports as.
+{
+  value: 'p',
+  text: 'Normal text'
+}, {
+  value: 'h2',
+  text: 'Heading 2'
+}, {
+  value: 'h3',
+  text: 'Heading 3'
+}, {
+  value: 'h4',
+  text: 'Heading 4'
+}, {
+  value: 'blockquote',
+  text: 'Quote'
+}];
+// The blocks the menu can actually display. A caret inside anything else —
+// contentEditable's own bare <div> wrappers, say — shows the placeholder
+// rather than silently misreporting the format.
+const knownBlocks = new Set(formatBlockOptions.map(option => option.value));
+// Commands whose active state at the cursor is reflected on the toolbar.
+const trackedCommands = ['bold', 'italic', 'underline', 'strikeThrough', 'subscript', 'superscript', 'insertUnorderedList', 'insertOrderedList'];
+// `mark` names the styling each label carries, so the icon demonstrates the
+// formatting it applies: a bold B, an underlined U, a struck-through S.
+const formattingButtons = [{
+  command: 'bold',
+  label: 'B',
+  title: 'Bold',
+  mark: 'bold'
+}, {
+  command: 'italic',
+  label: 'I',
+  title: 'Italic',
+  mark: 'italic'
+}, {
+  command: 'underline',
+  label: 'U',
+  title: 'Underline',
+  mark: 'underline'
+}, {
+  command: 'strikeThrough',
+  label: 'S',
+  title: 'Strikethrough',
+  mark: 'strike'
+}, {
+  command: 'superscript',
+  label: 'x²',
+  title: 'Superscript',
+  mark: 'plain'
+}, {
+  command: 'subscript',
+  label: 'x₂',
+  title: 'Subscript',
+  mark: 'plain'
+}];
+const listButtons = [{
+  command: 'insertUnorderedList',
+  label: '•≡',
+  title: 'Bulleted list'
+}, {
+  command: 'insertOrderedList',
+  label: '1≡',
+  title: 'Numbered list'
+}];
+const escapeHtml = text => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\n/g, '<br>');
+const readHtmlValue = bind => {
+  const value = bind[0][bind[1]];
+  return typeof value === 'string' ? value : '';
+};
+const writeHtmlValue = (bind, html) => {
+  // TypedBindVariable doesn't constrain O[K] to string, so this assumes the
+  // caller binds htmlBind to a string-valued field.
+  // eslint-disable-next-line no-type-assertion/no-type-assertion
+  bind[0][bind[1]] = html;
+};
+const writeTreeValue = (bind, tree) => {
+  // As writeHtmlValue above: assumes treeBind targets a
+  // StoredContentNode-typed field.
+  // eslint-disable-next-line no-type-assertion/no-type-assertion
+  bind[0][bind[1]] = tree;
+};
+export class RichTextEditor extends TungstenStatefulComponent {
+  constructor(...args) {
+    super(...args);
+    _defineProperty(this, "state", {
+      initialHtml: readHtmlValue(this.props.htmlBind),
+      sourceMode: false,
+      sourceDraft: '',
+      active: new Set(),
+      blockFormat: 'p',
+      loadedRecordKey: this.props.recordKey
+    });
+    _defineProperty(this, "surfaceRef", createElementRef());
+    _defineProperty(this, "sourceRef", createElementRef());
+    // Re-seeds the surface when the page points this editor at a different
+    // record. `initialHtml` is otherwise captured once and left alone (see
+    // State), which is what keeps the reconciler away from the live DOM — but
+    // that same stability means a record swap would leave the previous
+    // record's content on screen, and the next keystroke would commit it over
+    // the newly selected record. Writing innerHTML directly as well as
+    // updating initialHtml covers the case where the two records happen to
+    // share the stored string but the DOM has since been edited.
+    _defineProperty(this, "componentDidUpdate", () => {
+      const {
+        recordKey
+      } = this.props;
+      if (recordKey === this.state.loadedRecordKey) return;
+      const html = readHtmlValue(this.props.htmlBind);
+      this.state.loadedRecordKey = recordKey;
+      this.state.initialHtml = html;
+      this.state.sourceMode = false;
+      this.state.sourceDraft = '';
+      this.state.active = new Set();
+      if (this.surfaceRef.current !== null) this.surfaceRef.current.innerHTML = html;
+    });
+    // Derives the owning document from whichever host element is currently
+    // mounted, rather than the ambient global `document` — the global is
+    // only ever correct by accident of a real browser having exactly one,
+    // and a test harness (or a future iframe/multi-window use) may not
+    // define it at all.
+    _defineProperty(this, "ownerDocument", () => this.surfaceRef.current?.ownerDocument ?? this.sourceRef.current?.ownerDocument ?? null);
+    // Reads the surface as a string snapshot — the live editing DOM is never
+    // mutated here — then derives the tree from the *sanitized* string rather
+    // than from the raw one, so the two stored representations always describe
+    // the same content.
+    //
+    // Deriving them independently looked appealing (each through its own
+    // hardened pipeline) but is wrong: removing an element splits the text
+    // around it, so raw `<p>New <script>x</script>text</p>` parses to adjacent
+    // text nodes `['New ', 'text']`, while the sanitized string is the merged
+    // `<p>New text</p>`. Those render alike, but re-parsing the stored HTML
+    // would then disagree with the stored tree — and worse, a tree with
+    // adjacent text nodes renders to markup the browser re-parses as one text
+    // node, which is exactly the server/client shape mismatch that breaks
+    // hydration. Parsing the sanitized string keeps both allow-list passes
+    // (defence in depth) and yields one normalized text node.
+    _defineProperty(this, "commitSurface", () => {
+      const surface = this.surfaceRef.current;
+      if (surface === null) return;
+      const cleaned = sanitizeAuthoredHtml(surface.innerHTML, surface.ownerDocument);
+      writeHtmlValue(this.props.htmlBind, cleaned);
+      writeTreeValue(this.props.treeBind, serializeContentTree(parseHtml(cleaned, {
+        allowList: safeHtmlAllowList
+      })));
+    });
+    // The caret/selection last seen inside the surface. Toolbar controls that
+    // must take focus to work at all — the format <select> — necessarily blur
+    // the editable area first, and execCommand acts on whatever is selected
+    // when it runs, so the range is remembered here and put back before the
+    // command. Refocusing alone is not dependable enough to rely on.
+    _defineProperty(this, "savedRange", null);
+    _defineProperty(this, "captureSelection", () => {
+      const surface = this.surfaceRef.current;
+      const selection = this.ownerDocument()?.defaultView?.getSelection();
+      if (surface === null || selection === undefined || selection === null) return;
+      if (selection.rangeCount === 0) return;
+      const range = selection.getRangeAt(0);
+      // Ignore selections outside this editor, so an unrelated click
+      // elsewhere on the page cannot redirect a later command.
+      if (!surface.contains(range.commonAncestorContainer)) return;
+      this.savedRange = range.cloneRange();
+    });
+    _defineProperty(this, "restoreSelection", () => {
+      const selection = this.ownerDocument()?.defaultView?.getSelection();
+      if (this.savedRange === null || selection === undefined || selection === null) return;
+      selection.removeAllRanges();
+      selection.addRange(this.savedRange);
+    });
+    // Wired to the surface's keyup/mouseup/focus: both jobs want the same
+    // moments, whenever the caret may have moved.
+    _defineProperty(this, "selectionChanged", () => {
+      this.captureSelection();
+      this.refreshFormatState();
+    });
+    // Reflects the formatting at the caret onto the toolbar: which marks are
+    // lit, and which block the format menu shows.
+    //
+    // Read from the element ancestry (activeFormatsAt), not
+    // document.queryCommandState, which answers from computed style and so
+    // reports bold inside any heading.
+    _defineProperty(this, "refreshFormatState", () => {
+      const surface = this.surfaceRef.current;
+      const selection = this.ownerDocument()?.defaultView?.getSelection();
+      if (surface === null) return;
+      const at = selection === undefined || selection === null ? null : selection.focusNode;
+      const {
+        block,
+        marks
+      } = activeFormatsAt(at, surface);
+      this.state.active = new Set(trackedCommands.filter(command => marks.has(command)));
+      // Anything the menu has no option for — bare text, or a <div> the
+      // browser made — is Normal text, which is what it would become on save.
+      this.state.blockFormat = block !== null && knownBlocks.has(block) ? block : 'p';
+    });
+    _defineProperty(this, "exec", (command, value) => {
+      const doc = this.ownerDocument();
+      if (doc === null) return;
+      this.surfaceRef.current?.focus();
+      this.restoreSelection();
+      doc.execCommand(command, false, value);
+      this.captureSelection();
+      this.commitSurface();
+      this.refreshFormatState();
+    });
+    // Buttons take focus on click, which would drop the surface's selection
+    // before the click handler runs; preventing the mousedown keeps it.
+    //
+    // This must NOT go on the format <select>: opening the dropdown *is* that
+    // element's default mousedown action, so preventing it makes the control
+    // completely dead to the mouse. The select instead relies on
+    // saveRange/restoreSelection around exec().
+    _defineProperty(this, "preventFocusLoss", event => {
+      event.preventDefault();
+    });
+    _defineProperty(this, "changeFormatBlock", event => {
+      const tag = event.currentTarget.value;
+      if (tag === '') return;
+      // No reset afterwards: exec() ends in refreshFormatState(), which sets
+      // the menu from the caret's actual block, so it now shows the applied
+      // format the way a format menu is expected to.
+      this.exec('formatBlock', `<${tag}>`);
+    });
+    _defineProperty(this, "insertLink", () => {
+      // Via the surface's own window rather than the ambient global, for the
+      // same reason ownerDocument() exists.
+      const url = this.ownerDocument()?.defaultView?.prompt('Link URL');
+      if (url === undefined || url === null || url.trim() === '') return;
+      this.exec('createLink', url.trim());
+    });
+    _defineProperty(this, "removeLink", () => this.exec('unlink'));
+    _defineProperty(this, "clearFormatting", () => this.exec('removeFormat'));
+    _defineProperty(this, "undo", () => this.exec('undo'));
+    _defineProperty(this, "redo", () => this.exec('redo'));
+    // Enter inserts a line break instead of letting the browser open a new
+    // block. Browsers disagree over whether that block is a <p> or a <div>,
+    // and leave empty ones behind as content is edited — the markup this
+    // editor produces stays inline, with deliberate blocks (headings, quotes,
+    // lists) applied explicitly from the toolbar. Shift+Enter already means
+    // "line break", so it is left to the browser.
+    _defineProperty(this, "handleKeyDown", event => {
+      if (event.key !== 'Enter' || event.shiftKey) return;
+      const doc = this.ownerDocument();
+      if (doc === null) return;
+      event.preventDefault();
+      doc.execCommand('insertLineBreak');
+      this.commitSurface();
+      this.selectionChanged();
+    });
+    _defineProperty(this, "handlePaste", event => {
+      event.preventDefault();
+      const doc = event.currentTarget.ownerDocument;
+      const rawHtml = event.clipboardData.getData('text/html');
+      const cleaned = rawHtml !== '' ? sanitizeAuthoredHtml(rawHtml, doc) : escapeHtml(event.clipboardData.getData('text/plain'));
+      doc.execCommand('insertHTML', false, cleaned);
+      this.commitSurface();
+    });
+    _defineProperty(this, "toggleSource", () => {
+      if (this.state.sourceMode) {
+        const cleaned = sanitizeAuthoredHtml(this.state.sourceDraft, this.ownerDocument() ?? undefined);
+        this.state.initialHtml = cleaned;
+        this.state.sourceMode = false;
+        writeHtmlValue(this.props.htmlBind, cleaned);
+        const cleanedTree = parseHtml(cleaned, {
+          allowList: safeHtmlAllowList
+        });
+        writeTreeValue(this.props.treeBind, serializeContentTree(cleanedTree));
+      } else {
+        const current = this.surfaceRef.current?.innerHTML ?? readHtmlValue(this.props.htmlBind);
+        this.state.sourceDraft = current;
+        this.state.sourceMode = true;
+      }
+    });
+    _defineProperty(this, "changeSourceDraft", event => {
+      this.state.sourceDraft = event.currentTarget.value;
+    });
+    _defineProperty(this, "content", ({
+      className,
+      name,
+      placeholder
+    }, state) => _jsxs("div", {
+      className: combineClassNames(className, 'editor'),
+      children: [_jsxs("div", {
+        className: "toolbar",
+        role: "toolbar",
+        children: [_jsx("select", {
+          className: "format-block",
+          value: state.blockFormat,
+          onChange: this.changeFormatBlock,
+          disabled: state.sourceMode,
+          "aria-label": "Paragraph style",
+          children: formatBlockOptions.map(option => _jsx("option", {
+            value: option.value,
+            children: option.text
+          }, option.value))
+        }), _jsx("span", {
+          className: "group",
+          children: formattingButtons.map(item => _jsx("button", {
+            type: "button",
+            title: item.title,
+            className: combineClassNames('tool', item.mark, state.active.has(item.command) && 'active'),
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: () => this.exec(item.command),
+            children: item.label
+          }, item.command))
+        }), _jsx("span", {
+          className: "group",
+          children: listButtons.map(item => _jsx("button", {
+            type: "button",
+            title: item.title,
+            className: combineClassNames('tool', state.active.has(item.command) && 'active'),
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: () => this.exec(item.command),
+            children: item.label
+          }, item.command))
+        }), _jsxs("span", {
+          className: "group",
+          children: [_jsx("button", {
+            type: "button",
+            title: "Insert link",
+            className: "tool",
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: this.insertLink,
+            children: "Link"
+          }), _jsx("button", {
+            type: "button",
+            title: "Remove link",
+            className: "tool",
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: this.removeLink,
+            children: "Unlink"
+          })]
+        }), _jsxs("span", {
+          className: "group",
+          children: [_jsx("button", {
+            type: "button",
+            title: "Clear formatting",
+            className: "tool",
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: this.clearFormatting,
+            children: "Clear"
+          }), _jsx("button", {
+            type: "button",
+            title: "Undo",
+            className: "tool",
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: this.undo,
+            children: "\u21B6"
+          }), _jsx("button", {
+            type: "button",
+            title: "Redo",
+            className: "tool",
+            disabled: state.sourceMode,
+            onMouseDown: this.preventFocusLoss,
+            onClick: this.redo,
+            children: "\u21B7"
+          })]
+        }), _jsx("button", {
+          type: "button",
+          title: "View HTML source",
+          className: combineClassNames('tool', 'source-toggle', state.sourceMode && 'active'),
+          onMouseDown: this.preventFocusLoss,
+          onClick: this.toggleSource,
+          children: "HTML"
+        })]
+      }), state.sourceMode ? _jsx("textarea", {
+        className: "source",
+        name: name,
+        ref: this.sourceRef,
+        value: state.sourceDraft,
+        onInput: this.changeSourceDraft
+      })
+      // The explicit string rather than a bare/boolean prop. Tungsten
+      // now renders either as `contenteditable="true"`, so this is no
+      // longer working around anything — it just states the value of
+      // a three-state enumerated attribute (true/false/inherit)
+      // rather than leaving it to a boolean-prop convention.
+      : _jsx("div", {
+        className: "surface",
+        id: name,
+        ref: this.surfaceRef,
+        contentEditable: "true",
+        "data-placeholder": placeholder ?? '',
+        dangerouslySetInnerHTML: {
+          __html: state.initialHtml
+        },
+        onInput: this.commitSurface,
+        onPaste: this.handlePaste,
+        onKeyDown: this.handleKeyDown,
+        onKeyUp: this.selectionChanged,
+        onMouseUp: this.selectionChanged,
+        onFocus: this.selectionChanged
+      })]
+    }));
+    _defineProperty(this, "style", {
+      "moduleName": "T#-components-library-RichTextEditor-RichTextEditor",
+      "tags": {
+        "select": "T#-components-library-RichTextEditor-RichTextEditor_#_select"
+      },
+      "classes": {
+        "editor": "T#-components-library-RichTextEditor-RichTextEditor_editor",
+        "toolbar": "T#-components-library-RichTextEditor-RichTextEditor_toolbar",
+        "group": "T#-components-library-RichTextEditor-RichTextEditor_group",
+        "format-block": "T#-components-library-RichTextEditor-RichTextEditor_format-block",
+        "tool": "T#-components-library-RichTextEditor-RichTextEditor_tool",
+        "active": "T#-components-library-RichTextEditor-RichTextEditor_active",
+        "bold": "T#-components-library-RichTextEditor-RichTextEditor_bold",
+        "italic": "T#-components-library-RichTextEditor-RichTextEditor_italic",
+        "underline": "T#-components-library-RichTextEditor-RichTextEditor_underline",
+        "strike": "T#-components-library-RichTextEditor-RichTextEditor_strike",
+        "source-toggle": "T#-components-library-RichTextEditor-RichTextEditor_source-toggle",
+        "surface": "T#-components-library-RichTextEditor-RichTextEditor_surface",
+        "source": "T#-components-library-RichTextEditor-RichTextEditor_source"
+      }
+    });
+  }
+  static $stylesheet = "i/T-components-library-RichTextEditor-RichTextEditor.css";
+}

package/dist/components/library/RichTextEditor/StoredContentNode.d.ts

@@ -0,0 +1,5 @@
+export type StoredContentNode = string | number | null | StoredContentNode[] | {
+    tag: string;
+    props: Record<string, unknown>;
+};
+//# sourceMappingURL=StoredContentNode.d.ts.map

package/dist/components/library/RichTextEditor/StoredContentNode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoredContentNode.d.ts","sourceRoot":"","sources":["../../../../src/components/library/RichTextEditor/StoredContentNode.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,iBAAiB,GACvB,MAAM,GACN,MAAM,GACN,IAAI,GACJ,iBAAiB,EAAE,GACnB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA"}

package/dist/components/library/RichTextEditor/StoredContentNode.js

@@ -0,0 +1 @@
+export {};

package/dist/components/library/RichTextEditor/activeFormats.d.ts

@@ -0,0 +1,20 @@
+export type ActiveFormats = {
+    /** Tag of the nearest block element inside the surface, or null. */
+    block: string | null;
+    /** execCommand names for the inline marks in force at this point. */
+    marks: ReadonlySet<string>;
+};
+/**
+ * The formatting in force at a point in the editable surface, read from the
+ * element ancestry rather than `document.queryCommandState`.
+ *
+ * queryCommandState answers from computed style, so it reports `bold` as true
+ * anywhere inside a heading — headings render bold — which lights up the Bold
+ * button misleadingly and invites a redundant `<strong>` inside an `<h2>`.
+ * Walking the ancestors instead means only real markup counts.
+ *
+ * The walk stops at `root` so formatting *around* the editor cannot leak into
+ * its toolbar state.
+ */
+export declare function activeFormatsAt(node: Node | null, root: Element): ActiveFormats;
+//# sourceMappingURL=activeFormats.d.ts.map

package/dist/components/library/RichTextEditor/activeFormats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activeFormats.d.ts","sourceRoot":"","sources":["../../../../src/components/library/RichTextEditor/activeFormats.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,aAAa,GAAG;IACxB,oEAAoE;IACpE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qEAAqE;IACrE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC7B,CAAA;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,CAe/E"}

package/dist/components/library/RichTextEditor/activeFormats.js

@@ -0,0 +1,48 @@
+// Tag to the execCommand that produces it. Several tags map to one command
+// because browsers differ over which they emit (`b`/`strong`, `s`/`strike`/`del`).
+const markCommands = {
+  b: 'bold',
+  strong: 'bold',
+  i: 'italic',
+  em: 'italic',
+  u: 'underline',
+  s: 'strikeThrough',
+  strike: 'strikeThrough',
+  del: 'strikeThrough',
+  sub: 'subscript',
+  sup: 'superscript',
+  ul: 'insertUnorderedList',
+  ol: 'insertOrderedList'
+};
+const blockTags = new Set(['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'div']);
+function NodeIsElement(node) {
+  return node.nodeType === 1;
+}
+/**
+ * The formatting in force at a point in the editable surface, read from the
+ * element ancestry rather than `document.queryCommandState`.
+ *
+ * queryCommandState answers from computed style, so it reports `bold` as true
+ * anywhere inside a heading — headings render bold — which lights up the Bold
+ * button misleadingly and invites a redundant `<strong>` inside an `<h2>`.
+ * Walking the ancestors instead means only real markup counts.
+ *
+ * The walk stops at `root` so formatting *around* the editor cannot leak into
+ * its toolbar state.
+ */
+export function activeFormatsAt(node, root) {
+  const marks = new Set();
+  let block = null;
+  for (let current = node; current !== null && current !== root; current = current.parentNode) {
+    if (!NodeIsElement(current)) continue;
+    const tag = current.tagName.toLowerCase();
+    const command = markCommands[tag];
+    if (command !== undefined) marks.add(command);
+    // nearest block wins, so only take the first one met on the way up
+    if (block === null && blockTags.has(tag)) block = tag;
+  }
+  return {
+    block,
+    marks
+  };
+}

package/dist/components/library/RichTextEditor/contentTree.d.ts

@@ -0,0 +1,30 @@
+import type { ContentNode } from '../../../ContentNode.js';
+import type { HtmlAllowList } from '../../../rawHtml/HtmlAllowList.js';
+import type { StoredContentNode } from './StoredContentNode.js';
+/**
+ * Converts a Tungsten content tree into the JSON-safe StoredContentNode shape
+ * for persistence/transport. Only host HTML nodes are supported — the shape
+ * `parseHtml` produces — never component elements, which have no meaningful
+ * serialized form.
+ */
+export declare function serializeContentTree(node: ContentNode): StoredContentNode;
+/**
+ * Rebuilds a Tungsten content tree from stored JSON, filtered against the
+ * allow list.
+ *
+ * Filtering on *read* is deliberate and not redundant with the write side.
+ * Storing a pre-parsed tree is what makes rendering cheap — no re-parse per
+ * render — but it also means the stored value is handed to the renderer
+ * without passing back through `parseHtml`, which is where `<RawHtml safe>`
+ * would otherwise re-apply the allow list every time. Anything that ever put
+ * an unfiltered tree in the column (an endpoint bug, a hand-edited row) would
+ * then render unchecked, including `on*` props that Tungsten binds as event
+ * listeners.
+ *
+ * The rules themselves are Tungsten's `filterContentNode`, which makes the same
+ * decisions `parseHtml` makes while parsing — so the stored-tree path, the
+ * editor's write path and `<RawHtml safe>` all agree by construction rather
+ * than by three implementations being kept in step.
+ */
+export declare function deserializeContentTree(stored: StoredContentNode, allowList?: HtmlAllowList): ContentNode;
+//# sourceMappingURL=contentTree.d.ts.map

package/dist/components/library/RichTextEditor/contentTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contentTree.d.ts","sourceRoot":"","sources":["../../../../src/components/library/RichTextEditor/contentTree.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,yBAAyB,CAAA;AAGtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAA;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAE/D;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,iBAAiB,CAezE;AA6BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,iBAAiB,EAAE,SAAS,GAAE,aAAiC,GACxE,WAAW,CAEb"}

package/dist/components/library/RichTextEditor/contentTree.js

@@ -0,0 +1,81 @@
+import { $props, $type } from "../../../contentNodeSymbols.js";
+import { ContentNodeIsArray, ContentNodeIsHtml, ContentNodeIsLiteral, ContentNodeIsNonRendered } from "../../../ContentNode.js";
+import { filterContentNode } from "../../../rawHtml/filterContentNode.js";
+import { safeHtmlAllowList } from "../../../rawHtml/safeHtmlAllowList.js";
+/**
+ * Converts a Tungsten content tree into the JSON-safe StoredContentNode shape
+ * for persistence/transport. Only host HTML nodes are supported — the shape
+ * `parseHtml` produces — never component elements, which have no meaningful
+ * serialized form.
+ */
+export function serializeContentTree(node) {
+  if (ContentNodeIsNonRendered(node)) return null;
+  if (ContentNodeIsArray(node)) return node.map(serializeContentTree);
+  if (ContentNodeIsLiteral(node)) return node;
+  if (!ContentNodeIsHtml(node)) {
+    throw new Error('serializeContentTree only supports host HTML nodes (e.g. from parseHtml), not component elements.');
+  }
+  const {
+    children,
+    ...attributes
+  } = node[$props];
+  return {
+    tag: node[$type],
+    props: children === undefined ? attributes : {
+      ...attributes,
+      children: serializeContentTree(children)
+    }
+  };
+}
+/**
+ * Rebuilds the tree's shape from stored JSON, and nothing else. Whatever is in
+ * the column is reproduced faithfully, including markup that must not survive
+ * to a render — filtering is `deserializeContentTree`'s job, in one pass over
+ * the finished tree, so that this stays a plain structural inverse of
+ * `serializeContentTree`.
+ */
+function rebuildContentTree(stored) {
+  if (stored === null) return null;
+  if (Array.isArray(stored)) return stored.map(rebuildContentTree);
+  if (typeof stored !== 'object') return stored;
+  const {
+    children,
+    ...attributes
+  } = stored.props;
+  const props = {
+    ...attributes
+  };
+  if (children !== undefined) {
+    // Storage round-trip boundary: `children` holds whatever
+    // serializeContentTree put there.
+    // eslint-disable-next-line no-type-assertion/no-type-assertion
+    props.children = rebuildContentTree(children);
+  }
+  // Lowercased to match what parseHtml produces, so a hand-edited row cannot
+  // present a tag the allow list would then fail to recognise.
+  return {
+    [$type]: stored.tag.toLowerCase(),
+    [$props]: props
+  };
+}
+/**
+ * Rebuilds a Tungsten content tree from stored JSON, filtered against the
+ * allow list.
+ *
+ * Filtering on *read* is deliberate and not redundant with the write side.
+ * Storing a pre-parsed tree is what makes rendering cheap — no re-parse per
+ * render — but it also means the stored value is handed to the renderer
+ * without passing back through `parseHtml`, which is where `<RawHtml safe>`
+ * would otherwise re-apply the allow list every time. Anything that ever put
+ * an unfiltered tree in the column (an endpoint bug, a hand-edited row) would
+ * then render unchecked, including `on*` props that Tungsten binds as event
+ * listeners.
+ *
+ * The rules themselves are Tungsten's `filterContentNode`, which makes the same
+ * decisions `parseHtml` makes while parsing — so the stored-tree path, the
+ * editor's write path and `<RawHtml safe>` all agree by construction rather
+ * than by three implementations being kept in step.
+ */
+export function deserializeContentTree(stored, allowList = safeHtmlAllowList) {
+  return filterContentNode(rebuildContentTree(stored), allowList);
+}