@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/RichText/engine/blockUnit.ts

@@ -0,0 +1,174 @@
+// blockUnit.ts — Layer D. Block-"unit" helpers + structural transforms. A unit is
+// a single block, except a list item, which carries its deeper descendant run
+// (the contiguous following items at greater effective depth). Pure + immutable.
+import type { RichDoc, Block, Range } from './model';
+import { createBlock, nextId, emptyDoc } from './model';
+import { isListItem, effectiveDepths } from './listDepths';
+import { findBlockIndex } from './position';
+
+function collapsed(blockId: string, offset = 0): Range {
+  return { anchor: { blockId, offset }, focus: { blockId, offset } };
+}
+
+/** Half-open index range `[start, end)` of the unit anchored at `index`. */
+export function blockUnitRange(blocks: Block[], index: number): { start: number; end: number } {
+  if (index < 0 || index >= blocks.length) return { start: index, end: index };
+  if (!isListItem(blocks[index])) return { start: index, end: index + 1 };
+  const eff = effectiveDepths(blocks);
+  const d = eff[index];
+  let end = index + 1;
+  while (end < blocks.length && isListItem(blocks[end]) && eff[end] > d) end += 1;
+  return { start: index, end };
+}
+
+/**
+ * Index of the previous sibling's anchor (same effective depth, same list run),
+ * or -1 when `index` is the first child / first block. Descendant blocks of an
+ * earlier sibling (greater depth) are skipped.
+ */
+export function prevSiblingAnchor(blocks: Block[], index: number): number {
+  const eff = effectiveDepths(blocks);
+  const d = eff[index];
+  for (let i = index - 1; i >= 0; i -= 1) {
+    if (eff[i] < d) return -1; // hit an ancestor (or a depth-0 boundary for d>0)
+    if (eff[i] === d && (d === 0 || isListItem(blocks[i]))) return i;
+    // eff[i] > d → descendant of an earlier sibling: keep skipping
+  }
+  return -1;
+}
+
+/**
+ * Swap the unit anchored at `blockId` with its adjacent SIBLING unit (`dir`: -1
+ * up / +1 down). Same-depth swap, so depths are preserved. No-op (returns the
+ * SAME doc reference) at an edge / when there is no sibling in that direction.
+ */
+export function moveBlockUnit(
+  doc: RichDoc,
+  blockId: string,
+  dir: -1 | 1,
+): { doc: RichDoc; selection: Range } {
+  const blocks = doc.blocks;
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return { doc, selection: collapsed(blockId) };
+  const u = blockUnitRange(blocks, idx);
+
+  if (dir < 0) {
+    const p = prevSiblingAnchor(blocks, idx);
+    if (p === -1) return { doc, selection: collapsed(blockId) };
+    const moving = blocks.slice(u.start, u.end);
+    const before = blocks.slice(p, u.start);
+    const next = [...blocks.slice(0, p), ...moving, ...before, ...blocks.slice(u.end)];
+    return { doc: { blocks: next }, selection: collapsed(blockId) };
+  }
+
+  const eff = effectiveDepths(blocks);
+  const d = eff[idx];
+  if (u.end >= blocks.length || eff[u.end] !== d) return { doc, selection: collapsed(blockId) };
+  const nextUnit = blockUnitRange(blocks, u.end);
+  const moving = blocks.slice(u.start, u.end);
+  const after = blocks.slice(u.end, nextUnit.end);
+  const next = [...blocks.slice(0, u.start), ...after, ...moving, ...blocks.slice(nextUnit.end)];
+  return { doc: { blocks: next }, selection: collapsed(blockId) };
+}
+
+/** Clone a block with a fresh id (inline runs copied so marks aren't shared). */
+function cloneBlock(b: Block): Block {
+  // `?? []` so duplicating a void block (an `attachment` carries no `inlines`)
+  // can't crash on undefined.
+  return {
+    ...b,
+    id: nextId(),
+    inlines: (b.inlines ?? []).map((r) => ({ ...r, marks: r.marks.slice() })),
+  };
+}
+
+/**
+ * Duplicate the unit anchored at `blockId`, inserting the clones immediately
+ * after the unit. Fresh ids; depths preserved. Caret lands on the clone's anchor.
+ */
+export function duplicateBlockUnit(
+  doc: RichDoc,
+  blockId: string,
+): { doc: RichDoc; selection: Range } {
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return { doc, selection: collapsed(blockId) };
+  const u = blockUnitRange(doc.blocks, idx);
+  const copies = doc.blocks.slice(u.start, u.end).map(cloneBlock);
+  const blocks = [...doc.blocks.slice(0, u.end), ...copies, ...doc.blocks.slice(u.end)];
+  return { doc: { blocks }, selection: collapsed(copies[0].id) };
+}
+
+/**
+ * Remove the unit anchored at `blockId`. Empties to a single empty paragraph if
+ * it was the whole document. Caret lands on the next surviving block, else the
+ * previous, else the new empty paragraph.
+ */
+export function removeBlockUnit(doc: RichDoc, blockId: string): { doc: RichDoc; selection: Range } {
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return { doc, selection: collapsed(blockId) };
+  const u = blockUnitRange(doc.blocks, idx);
+  const blocks = [...doc.blocks.slice(0, u.start), ...doc.blocks.slice(u.end)];
+  if (blocks.length === 0) {
+    const fresh = emptyDoc();
+    return { doc: fresh, selection: collapsed(fresh.blocks[0].id) };
+  }
+  const caretIdx = Math.min(u.start, blocks.length - 1);
+  return { doc: { blocks }, selection: collapsed(blocks[caretIdx].id) };
+}
+
+/** Insert an empty paragraph directly after the block unit anchored at `blockId`. */
+export function insertEmptyBlockBelow(
+  doc: RichDoc,
+  blockId: string,
+): { doc: RichDoc; selection: Range } {
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return { doc, selection: collapsed(blockId) };
+  const u = blockUnitRange(doc.blocks, idx);
+  const fresh = createBlock('paragraph');
+  const blocks = [...doc.blocks.slice(0, u.end), fresh, ...doc.blocks.slice(u.end)];
+  return { doc: { blocks }, selection: collapsed(fresh.id) };
+}
+
+/**
+ * Move the unit anchored at `blockId` so its first block lands at array index
+ * `target` (coordinates of the CURRENT array). The moved unit's top depth is
+ * clamped to a value valid for its new predecessor (`prevListDepth + 1`, else 0);
+ * descendants shift by the same delta. No-op when `target` falls inside the unit.
+ */
+export function moveBlockUnitToIndex(
+  doc: RichDoc,
+  blockId: string,
+  target: number,
+): { doc: RichDoc; selection: Range } {
+  const blocks = doc.blocks;
+  const idx = findBlockIndex(doc, blockId);
+  if (idx === -1) return { doc, selection: collapsed(blockId) };
+  const u = blockUnitRange(blocks, idx);
+  if (target > u.start && target < u.end) return { doc, selection: collapsed(blockId) };
+  const moving = blocks.slice(u.start, u.end);
+  const rest = [...blocks.slice(0, u.start), ...blocks.slice(u.end)];
+  let insertAt = target > u.start ? target - moving.length : target;
+  insertAt = Math.max(0, Math.min(insertAt, rest.length));
+  // No movement (dropped back onto its own slot) → same doc ref, like moveBlockUnit's no-ops.
+  if (insertAt === u.start) return { doc, selection: collapsed(blockId) };
+
+  let adjusted = moving;
+  if (isListItem(moving[0])) {
+    const prev = insertAt - 1;
+    // Clamp against the predecessor's EFFECTIVE depth (what the renderer shows),
+    // consistent with the rest of the engine's depth reasoning.
+    const effRest = effectiveDepths(rest);
+    const prevDepth = prev >= 0 && isListItem(rest[prev]) ? effRest[prev] : -1;
+    const maxDepth = prevDepth + 1;
+    const topRaw = moving[0].depth ?? 0;
+    const newTop = Math.max(0, Math.min(topRaw, maxDepth));
+    const delta = newTop - topRaw;
+    if (delta !== 0) {
+      adjusted = moving.map((b) =>
+        isListItem(b) ? { ...b, depth: Math.max(0, (b.depth ?? 0) + delta) } : b,
+      );
+    }
+  }
+  const next = [...rest.slice(0, insertAt), ...adjusted, ...rest.slice(insertAt)];
+  return { doc: { blocks: next }, selection: collapsed(blockId) };
+}

package/src/components/RichText/engine/colorMarks.ts

@@ -0,0 +1,85 @@
+// colorMarks.ts — token-backed palette for textColor/bgColor marks. Marks store a
+// KEY (e.g. 'red'); these resolve it to a CSS custom property so colors stay
+// theme-able/tokens-only. Shared by the renderer, serializers, and UI.
+//
+// The picker offers the DEFAULT brand colors first (gray + the semantic red/green/
+// amber/blue), then the rest of the design system's categorical palette. The four
+// palette hues that duplicate a default (red/green/amber/blue) are omitted so there
+// is a single canonical red, etc.
+import { PALETTE_COLORS, paletteTokens, type PaletteColor } from '../../../palette';
+
+const DEFAULT_KEYS = ['gray', 'red', 'green', 'amber', 'blue'] as const;
+type DefaultKey = (typeof DEFAULT_KEYS)[number];
+const DEFAULT_TEXT_VAR: Record<DefaultKey, string> = {
+  gray: '--color-fg-muted',
+  red: '--color-danger',
+  green: '--color-success',
+  // @contrast --color-warning on --color-bg = 2.14:1 light
+  // @contrast --color-warning on --color-warning-bg-subtle = 2.01:1 light
+  // @contrast --color-warning-strong on --color-bg = 5.95:1 light
+  // --color-warning-strong, not --color-warning: the bare amber is 2.14:1 as
+  // text on the editor surface and 2.01:1 on the swatch's own tinted chip,
+  // both LIGHT theme. red/green/blue are all legible as text; amber was the
+  // outlier. See #481.
+  amber: '--color-warning-strong',
+  blue: '--color-accent',
+};
+const DEFAULT_BG_VAR: Record<DefaultKey, string> = {
+  gray: '--color-bg-muted',
+  red: '--color-danger-bg-subtle',
+  green: '--color-success-bg-subtle',
+  amber: '--color-warning-bg-subtle',
+  blue: '--color-accent-bg-subtle',
+};
+// Derived (not hardcoded) so a change to DEFAULT_KEYS can't silently leave a
+// duplicate swatch: the palette extras are every palette color NOT already a default.
+const DEFAULT_OVERLAP = new Set<string>(DEFAULT_KEYS);
+const PALETTE_EXTRA = PALETTE_COLORS.filter((c) => !DEFAULT_OVERLAP.has(c));
+
+/** A palette key stored by `textColor`/`bgColor` marks (never a raw color). */
+export type ColorKey = DefaultKey | PaletteColor;
+/** Every offered key, in swatch-display order: the default colors first, then the palette. */
+export const COLOR_KEYS: readonly ColorKey[] = [...DEFAULT_KEYS, ...PALETTE_EXTRA];
+
+function isDefaultKey(s: string): s is DefaultKey {
+  return (DEFAULT_KEYS as readonly string[]).includes(s);
+}
+/** Type guard: is `s` one of the offered keys? */
+export function isColorKey(s: string): s is ColorKey {
+  return (COLOR_KEYS as readonly string[]).includes(s);
+}
+/** Resolve a text-color key to its token-backed `var(--…)`, or undefined if unknown. */
+export function textColorVar(key: string): string | undefined {
+  if (isDefaultKey(key)) return `var(${DEFAULT_TEXT_VAR[key]})`;
+  return isColorKey(key) ? paletteTokens(key as PaletteColor).fg : undefined;
+}
+/** Resolve a highlight (bg) key to its token-backed `var(--…)`, or undefined if unknown. */
+export function bgColorVar(key: string): string | undefined {
+  if (isDefaultKey(key)) return `var(${DEFAULT_BG_VAR[key]})`;
+  return isColorKey(key) ? paletteTokens(key as PaletteColor).bg : undefined;
+}
+
+// Parse a CSS value back to a key — recognizes our own var() output: the default
+// semantic tokens and the palette tokens (var(--color-palette-<key>-fg|bg)). A bare
+// token (no var()) also parses. Raw hex / unknown → undefined.
+function keyFromVar(css: string, suffix: 'fg' | 'bg'): ColorKey | undefined {
+  const c = css
+    .trim()
+    .toLowerCase()
+    .replace(/^var\(\s*/, '')
+    .replace(/\s*\)\s*$/, '');
+  for (const k of DEFAULT_KEYS) {
+    if (c === (suffix === 'fg' ? DEFAULT_TEXT_VAR[k] : DEFAULT_BG_VAR[k])) return k;
+  }
+  const m = c.match(/^--color-palette-([a-z]+)-(fg|bg)$/);
+  if (m && m[2] === suffix && isColorKey(m[1]) && !isDefaultKey(m[1])) return m[1];
+  return undefined;
+}
+/** Parse a CSS `color` value back to a text key (our var() output), or undefined. */
+export function textColorKeyFrom(css: string): ColorKey | undefined {
+  return keyFromVar(css, 'fg');
+}
+/** Parse a CSS `background-color` value back to a bg key (our var() output), or undefined. */
+export function bgColorKeyFrom(css: string): ColorKey | undefined {
+  return keyFromVar(css, 'bg');
+}

package/src/components/RichText/engine/escape.ts

@@ -0,0 +1,11 @@
+// escape.ts — HTML text/attribute escapers shared by the Markdown converter
+// (mdToHtml) and the HTML serializer (toHtml).
+const ESC: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;' };
+/** Escape text content: `&`, `<`, `>`. */
+export const escapeHtml = (s: string): string => s.replace(/[&<>]/g, (c) => ESC[c]);
+
+// Attribute context also needs the quotes escaped (a `"` in a URL would break out
+// of the href). Scheme safety is handled separately by safeHref.
+const ATTR_ESC: Record<string, string> = { ...ESC, '"': '&quot;', "'": '&#39;' };
+/** Escape an attribute value: text escapes plus quotes. */
+export const escapeAttr = (s: string): string => s.replace(/["'&<>]/g, (c) => ATTR_ESC[c]);

package/src/components/RichText/engine/fromHtml.ts

@@ -0,0 +1,353 @@
+// fromHtml.ts — parse an HTML string into the RichText model. Uses the browser's
+// built-in DOMParser (inert: scripts never run) and walks the DOM with a strict
+// allowlist — the walk IS the sanitizer, since it only extracts text + known
+// marks + safeHref-checked links and emits a plain model. Requires a DOM
+// environment (browser; jsdom in tests).
+import type { RichDoc, Block, Inline, Mark, BlockType } from './model';
+import { nextId, emptyDoc } from './model';
+import { normalizeInlines } from './inlines';
+import { safeHref } from './safeHref';
+import { withMark } from './marks';
+import { textColorKeyFrom, bgColorKeyFrom } from './colorMarks';
+
+const HEADING_LEVEL: Record<string, 1 | 2 | 3> = { H1: 1, H2: 2, H3: 3, H4: 3, H5: 3, H6: 3 };
+
+// Block-level tags that flush the loose-inline buffer and emit their own block(s).
+const BLOCK_TAGS = new Set([
+  'P',
+  'H1',
+  'H2',
+  'H3',
+  'H4',
+  'H5',
+  'H6',
+  'PRE',
+  'BLOCKQUOTE',
+  'UL',
+  'OL',
+  'LI',
+  'DIV',
+  'SECTION',
+  'ARTICLE',
+  'MAIN',
+  'HEADER',
+  'FOOTER',
+  'ASIDE',
+  'NAV',
+  'ADDRESS',
+  'DL',
+  'DT',
+  'DD',
+  'FIGCAPTION',
+]);
+
+// Tags whose entire subtree is dropped (no text extracted).
+const DROP_TAGS = new Set([
+  'SCRIPT',
+  'STYLE',
+  'HEAD',
+  'TITLE',
+  'NOSCRIPT',
+  'TEMPLATE',
+  'IMG',
+  'PICTURE',
+  'SVG',
+  'VIDEO',
+  'AUDIO',
+  'IFRAME',
+  'OBJECT',
+  'EMBED',
+  'CANVAS',
+  'TABLE',
+  'THEAD',
+  'TBODY',
+  'TFOOT',
+  'TR',
+  'TD',
+  'TH',
+  'COLGROUP',
+  'COL',
+  'HR',
+  'FORM',
+  'INPUT',
+  'SELECT',
+  'TEXTAREA',
+  'BUTTON',
+  'LABEL',
+  'FIGURE',
+]);
+
+const HTML_NS = 'http://www.w3.org/1999/xhtml';
+// Only HTML-namespace elements are walked; SVG/MathML foreign content (which has
+// lowercase tagNames the uppercase allowlists would miss) is dropped entirely.
+const isElement = (n: Node): n is HTMLElement =>
+  n.nodeType === 1 && (n as Element).namespaceURI === HTML_NS;
+const isText = (n: Node): n is Text => n.nodeType === 3;
+
+const collapseWs = (s: string): string => s.replace(/\s+/g, ' ');
+
+/** Marks active for the descendants of `el`: parent ∪ tag mark ∪ link ∪ inline CSS. */
+function marksFor(el: HTMLElement, parent: Mark[]): Mark[] {
+  let marks = parent;
+  switch (el.tagName) {
+    case 'STRONG':
+    case 'B':
+      marks = withMark(marks, { type: 'bold' });
+      break;
+    case 'EM':
+    case 'I':
+      marks = withMark(marks, { type: 'italic' });
+      break;
+    case 'U':
+      marks = withMark(marks, { type: 'underline' });
+      break;
+    case 'S':
+    case 'DEL':
+    case 'STRIKE':
+      marks = withMark(marks, { type: 'strike' });
+      break;
+    case 'CODE':
+      marks = withMark(marks, { type: 'code' });
+      break;
+    case 'A': {
+      const href = safeHref(el.getAttribute('href') ?? '');
+      if (href !== undefined) marks = withMark(marks, { type: 'link', href });
+      break;
+    }
+    case 'SPAN': {
+      const id = el.getAttribute('data-mention-id');
+      if (id) {
+        const label = el.getAttribute('data-mention-label') ?? el.textContent ?? '';
+        marks = withMark(marks, { type: 'mention', id, label });
+      }
+      break;
+    }
+  }
+  return applyCssMarks(el, marks);
+}
+
+/** Recover bold/italic/underline/strike from a small set of inline CSS props. */
+function applyCssMarks(el: HTMLElement, marks: Mark[]): Mark[] {
+  const style = el.getAttribute('style');
+  if (!style) return marks;
+  const s = style.toLowerCase();
+  const weight = /font-weight\s*:\s*(\d+|bold|bolder)/.exec(s);
+  if (weight && (weight[1] === 'bold' || weight[1] === 'bolder' || Number(weight[1]) >= 600)) {
+    marks = withMark(marks, { type: 'bold' });
+  }
+  if (/font-style\s*:\s*(italic|oblique)/.test(s)) marks = withMark(marks, { type: 'italic' });
+  const deco = /text-decoration(?:-line)?\s*:\s*([^;]+)/.exec(s);
+  if (deco) {
+    if (deco[1].includes('underline')) marks = withMark(marks, { type: 'underline' });
+    if (deco[1].includes('line-through')) marks = withMark(marks, { type: 'strike' });
+  }
+  // Recover text/background color marks. The `color` lookahead `(?:^|;|\s)` keeps it
+  // from matching the `-color` inside `background-color`. Only values that resolve to
+  // a palette key (our `var(--color-palette-…)` output) become a mark.
+  const color = /(?:^|;|\s)color\s*:\s*([^;]+)/.exec(s);
+  if (color) {
+    const key = textColorKeyFrom(color[1]);
+    if (key) marks = withMark(marks, { type: 'textColor', color: key });
+  }
+  const bg = /background-color\s*:\s*([^;]+)/.exec(s);
+  if (bg) {
+    const key = bgColorKeyFrom(bg[1]);
+    if (key) marks = withMark(marks, { type: 'bgColor', color: key });
+  }
+  return marks;
+}
+
+/** Walk inline content, appending runs to `segments` (last entry = current soft-line). */
+function walkInline(node: Node, marks: Mark[], segments: Inline[][]): void {
+  if (isText(node)) {
+    const t = collapseWs(node.nodeValue ?? '');
+    if (t) segments[segments.length - 1].push({ text: t, marks });
+    return;
+  }
+  if (!isElement(node)) return;
+  if (DROP_TAGS.has(node.tagName)) return;
+  if (node.tagName === 'BR') {
+    segments.push([]);
+    return;
+  }
+  const next = marksFor(node, marks);
+  for (const child of Array.from(node.childNodes)) walkInline(child, next, segments);
+}
+
+/** Trim leading whitespace of the first run and trailing whitespace of the last. */
+function trimSegment(seg: Inline[]): Inline[] {
+  if (seg.length === 0) return seg;
+  const out = seg.map((r) => ({ ...r }));
+  out[0] = { ...out[0], text: out[0].text.replace(/^\s+/, '') };
+  const last = out.length - 1;
+  out[last] = { ...out[last], text: out[last].text.replace(/\s+$/, '') };
+  return out;
+}
+
+function blockFrom(
+  type: BlockType,
+  inlines: Inline[],
+  attrs: { level?: 1 | 2 | 3; depth?: number } = {},
+): Block {
+  const norm = normalizeInlines(inlines);
+  const block: Block = { id: nextId(), type, inlines: norm };
+  if (attrs.level !== undefined) block.level = attrs.level;
+  if (attrs.depth !== undefined) block.depth = attrs.depth;
+  return block;
+}
+
+const isEmptySeg = (inlines: Inline[]): boolean => inlines.length === 1 && inlines[0].text === '';
+
+/** Emit an inline-only block (paragraph/heading), splitting at <br> into siblings. */
+function pushInlineBlocks(
+  el: HTMLElement,
+  type: BlockType,
+  out: Block[],
+  attrs: { level?: 1 | 2 | 3 },
+): void {
+  const segments: Inline[][] = [[]];
+  for (const child of Array.from(el.childNodes)) walkInline(child, [], segments);
+  let pushed = false;
+  for (const seg of segments) {
+    const inlines = normalizeInlines(trimSegment(seg));
+    if (segments.length > 1 && isEmptySeg(inlines)) continue;
+    out.push(blockFrom(type, inlines, attrs));
+    pushed = true;
+  }
+  if (!pushed) out.push(blockFrom(type, [{ text: '', marks: [] }], attrs));
+}
+
+function emitListItem(li: HTMLElement, itemType: BlockType, out: Block[], depth: number): void {
+  const segments: Inline[][] = [[]];
+  const nested: HTMLElement[] = [];
+  for (const child of Array.from(li.childNodes)) {
+    if (isElement(child) && (child.tagName === 'UL' || child.tagName === 'OL')) nested.push(child);
+    else walkInline(child, [], segments);
+  }
+  for (const seg of segments) {
+    const inlines = normalizeInlines(trimSegment(seg));
+    if (segments.length > 1 && isEmptySeg(inlines)) continue;
+    out.push({ id: nextId(), type: itemType, depth, inlines });
+  }
+  for (const sub of nested) emitBlock(sub, out, depth + 1);
+}
+
+function emitBlock(el: HTMLElement, out: Block[], listDepth: number): void {
+  const tag = el.tagName;
+  if (tag in HEADING_LEVEL) {
+    pushInlineBlocks(el, 'heading', out, { level: HEADING_LEVEL[tag] });
+    return;
+  }
+  if (tag === 'P') {
+    pushInlineBlocks(el, 'paragraph', out, {});
+    return;
+  }
+  if (tag === 'PRE') {
+    out.push(blockFrom('code_block', [{ text: el.textContent ?? '', marks: [] }]));
+    return;
+  }
+  if (tag === 'BLOCKQUOTE') {
+    const inner: Block[] = [];
+    collectBlocks(el, inner, listDepth);
+    // Hoist void blocks (e.g. an inner <img> → attachment) out as their own blocks
+    // rather than coercing them to a text-less `{type:'blockquote', inlines:[]}`,
+    // which would violate the "every text block holds ≥1 run" invariant.
+    for (const b of inner) {
+      if (b.type === 'attachment') out.push(b);
+      else out.push({ id: nextId(), type: 'blockquote', inlines: b.inlines });
+    }
+    return;
+  }
+  if (tag === 'UL' || tag === 'OL') {
+    const itemType: BlockType = tag === 'OL' ? 'ordered_item' : 'bullet_item';
+    for (const child of Array.from(el.children)) {
+      if (child.tagName === 'LI') emitListItem(child as HTMLElement, itemType, out, listDepth);
+    }
+    return;
+  }
+  if (tag === 'LI') {
+    emitListItem(el, 'bullet_item', out, listDepth);
+    return;
+  }
+  // Unknown block container → unwrap.
+  collectBlocks(el, out, listDepth);
+}
+
+function collectBlocks(parent: Node, out: Block[], listDepth: number): void {
+  let buffer: Inline[][] = [[]];
+  const flush = () => {
+    for (const seg of buffer) {
+      const inlines = normalizeInlines(trimSegment(seg));
+      if (isEmptySeg(inlines)) continue;
+      out.push(blockFrom('paragraph', inlines));
+    }
+    buffer = [[]];
+  };
+  for (const child of Array.from(parent.childNodes)) {
+    if (isText(child)) {
+      const t = collapseWs(child.nodeValue ?? '');
+      if (t) buffer[buffer.length - 1].push({ text: t, marks: [] });
+      continue;
+    }
+    if (!isElement(child)) continue;
+    // A block-level <img> (or a <figure> wrapping one) becomes a ready image
+    // attachment. Must run before DROP_TAGS, which drops IMG/FIGURE outright.
+    if (child.tagName === 'IMG' || (child.tagName === 'FIGURE' && child.querySelector('img'))) {
+      flush();
+      const img = (
+        child.tagName === 'IMG' ? child : child.querySelector('img')!
+      ) as HTMLImageElement;
+      const src = safeHref(img.getAttribute('src') ?? '');
+      if (src) {
+        const altAttr = img.getAttribute('alt') ?? '';
+        const fig = child.tagName === 'FIGURE' ? (child as HTMLElement) : null;
+        const ta = fig?.style.textAlign;
+        const align = ta === 'center' || ta === 'right' || ta === 'left' ? ta : undefined;
+        const w = Number(img.getAttribute('width'));
+        const h = Number(img.getAttribute('height'));
+        const block: Block = {
+          id: nextId(),
+          type: 'attachment',
+          inlines: [],
+          status: 'ready',
+          src,
+          mime: 'image/*',
+          alt: altAttr,
+          name: altAttr,
+        };
+        if (align) block.align = align;
+        if (Number.isFinite(w) && w > 0) block.width = w;
+        if (Number.isFinite(h) && h > 0) block.height = h;
+        out.push(block);
+      }
+      continue;
+    }
+    if (DROP_TAGS.has(child.tagName)) continue;
+    if (BLOCK_TAGS.has(child.tagName)) {
+      flush();
+      emitBlock(child, out, listDepth);
+    } else {
+      walkInline(child, [], buffer); // unknown inline element → into the buffer
+    }
+  }
+  flush();
+}
+
+/**
+ * Parse an HTML string into a `RichDoc`. Recognized tags map to blocks/marks; an
+ * inline-CSS subset (font-weight/style/text-decoration) recovers Word/Docs
+ * formatting; unknown containers unwrap (text kept); script/style/table/img/etc.
+ * are dropped. Hrefs are sanitized via `safeHref`. Requires a DOM environment.
+ *
+ * @example
+ * const doc = fromHtml('<h1>Title</h1><p>Hello <strong>world</strong></p>');
+ */
+export function fromHtml(html: string): RichDoc {
+  const parsed = new DOMParser().parseFromString(html, 'text/html');
+  // DOMParser disables scripting, so <noscript> children are promoted into the
+  // tree as real elements — remove them so their content isn't extracted.
+  parsed.body.querySelectorAll('noscript').forEach((el) => el.remove());
+  const blocks: Block[] = [];
+  collectBlocks(parsed.body, blocks, 0);
+  return blocks.length ? { blocks } : emptyDoc();
+}

package/src/components/RichText/engine/fromMarkdown.ts

@@ -0,0 +1,20 @@
+// fromMarkdown.ts — parse a Markdown string into the RichText model by routing
+// through HTML (mdToHtml) so the tag→model mapping + sanitization live in one
+// place (fromHtml). CommonMark + GFM strikethrough subset. Requires a DOM
+// environment (DOMParser, via fromHtml).
+import type { RichDoc } from './model';
+import { fromHtml } from './fromHtml';
+import { mdToHtml } from './mdToHtml';
+
+/**
+ * Parse a Markdown string into a `RichDoc`. Supports headings, bold/italic,
+ * strikethrough (`~~`), inline code, links, blockquotes, ordered/unordered
+ * (nested) lists, and fenced code blocks. Lossy by nature: Markdown has no
+ * underline syntax (never produced) and images/tables are not modeled.
+ *
+ * @example
+ * const doc = fromMarkdown('# Title\n\n- one\n- two');
+ */
+export function fromMarkdown(md: string): RichDoc {
+  return fromHtml(mdToHtml(md));
+}