@multiplatform.one/markdown 6.1.0 → 6.4.0

package/src/mdxComponents.spec.tsx

@@ -0,0 +1,185 @@
+/**
+ * mdxComponents mapping specs — the HTML-tag → Tamagui component table MDX
+ * documents render through. Locks down real DOM semantics per tag (headings
+ * with data-heading anchors, inline strong/em/del, list/table structure) and
+ * the `code` dual mode (inline CodeInline without className vs block).
+ *
+ * The `a` mapping is not covered here: it renders through the router Link,
+ * which needs a live router host.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { mdxComponents } from "./mdxComponents";
+
+function C(tag: keyof typeof mdxComponents): any {
+  const component = mdxComponents[tag];
+  expect(component, `mdxComponents.${tag}`).toBeTruthy();
+  return component;
+}
+
+describe("mdxComponents — headings", () => {
+  it("renders h1 as a real h1", () => {
+    const H1 = C("h1");
+    const { container } = renderWithProviders(<H1>Top</H1>);
+    expect(container.querySelector("h1")?.textContent).toBe("Top");
+  });
+
+  it("renders h2 with the data-heading marker used by TOC scrapers", () => {
+    const H2 = C("h2");
+    const { container } = renderWithProviders(<H2>Section</H2>);
+    const h2 = container.querySelector("h2");
+    expect(h2?.textContent).toBe("Section");
+    expect(h2?.hasAttribute("data-heading")).toBe(true);
+  });
+
+  it("renders h3 as a self-linking anchor heading with its id", () => {
+    const H3 = C("h3");
+    const { container } = renderWithProviders(<H3 id="install">Install</H3>);
+    const anchor = container.querySelector('a[href="#install"]');
+    expect(anchor).toBeTruthy();
+    expect(anchor!.getAttribute("id")).toBe("install");
+    expect(anchor!.textContent).toContain("Install");
+    expect(container.querySelector("h3")).toBeTruthy();
+  });
+
+  it("renders h4/h5/h6 at their own levels", () => {
+    const H4 = C("h4");
+    const H5 = C("h5");
+    const H6 = C("h6");
+    const { container } = renderWithProviders(
+      <>
+        <H4>four</H4>
+        <H5>five</H5>
+        <H6>six</H6>
+      </>,
+    );
+    expect(container.querySelector("h4")?.textContent).toBe("four");
+    expect(container.querySelector("h5")?.textContent).toBe("five");
+    expect(container.querySelector("h6")?.textContent).toBe("six");
+  });
+});
+
+describe("mdxComponents — inline and block text", () => {
+  it("renders p as a real paragraph element", () => {
+    const P = C("p");
+    const { container } = renderWithProviders(<P>body copy</P>);
+    expect(container.querySelector("p")?.textContent).toBe("body copy");
+  });
+
+  it("renders strong/em/del with their native semantics", () => {
+    const Strong = C("strong");
+    const Em = C("em");
+    const Del = C("del");
+    const { container } = renderWithProviders(
+      <>
+        <Strong>bold</Strong>
+        <Em>slanted</Em>
+        <Del>removed</Del>
+      </>,
+    );
+    expect(container.querySelector("strong")?.textContent).toBe("bold");
+    expect(container.querySelector("em")?.textContent).toBe("slanted");
+    expect(container.querySelector("del")?.textContent).toBe("removed");
+  });
+
+  it("renders blockquote content through the quote treatment", () => {
+    const Blockquote = C("blockquote");
+    const { container } = renderWithProviders(<Blockquote>quoted wisdom</Blockquote>);
+    expect(container.textContent).toContain("quoted wisdom");
+  });
+
+  it("renders hr without crashing", () => {
+    const Hr = C("hr");
+    const { container } = renderWithProviders(<Hr />);
+    expect(container.firstChild).toBeTruthy();
+  });
+});
+
+describe("mdxComponents — code", () => {
+  it("renders inline code (no className) as a real <code> element", () => {
+    const Code = C("code");
+    const { container } = renderWithProviders(<Code>npm i tamagui</Code>);
+    const code = container.querySelector("code");
+    expect(code).toBeTruthy();
+    expect(code!.textContent).toBe("npm i tamagui");
+  });
+});
+
+describe("mdxComponents — lists", () => {
+  it("renders ul > li structure and strips stray string children", () => {
+    const Ul = C("ul");
+    const Li = C("li");
+    const { container } = renderWithProviders(
+      <Ul>
+        {"\n"}
+        <Li>first</Li>
+        {"\n"}
+        <Li>second</Li>
+      </Ul>,
+    );
+    const ul = container.querySelector("ul");
+    expect(ul).toBeTruthy();
+    const items = ul!.querySelectorAll("li");
+    expect(items).toHaveLength(2);
+    expect(ul!.textContent).not.toContain("\n");
+  });
+
+  it("renders ol as a real ordered list", () => {
+    const Ol = C("ol");
+    const Li = C("li");
+    const { container } = renderWithProviders(
+      <Ol>
+        <Li>one</Li>
+      </Ol>,
+    );
+    expect(container.querySelector("ol")).toBeTruthy();
+    expect(container.querySelector("ol li")?.textContent).toContain("one");
+  });
+});
+
+describe("mdxComponents — media and tables", () => {
+  it("renders img nested in a span wrapper with forwarded src/alt", () => {
+    const Img = C("img");
+    const { container } = renderWithProviders(
+      <Img src="https://example.com/x.png" alt="diagram" />,
+    );
+    const img = container.querySelector("img");
+    expect(img).toBeTruthy();
+    expect(img!.getAttribute("src")).toBe("https://example.com/x.png");
+    expect(img!.getAttribute("alt")).toBe("diagram");
+  });
+
+  it("renders the full table family into table/thead/tbody/tr/th/td", () => {
+    const Table = C("table");
+    const Thead = C("thead");
+    const Tbody = C("tbody");
+    const Tr = C("tr");
+    const Th = C("th");
+    const Td = C("td");
+    const { container } = renderWithProviders(
+      <Table>
+        <Thead>
+          <Tr>
+            <Th>Header</Th>
+          </Tr>
+        </Thead>
+        <Tbody>
+          <Tr>
+            <Td>Data</Td>
+          </Tr>
+        </Tbody>
+      </Table>,
+    );
+    expect(container.querySelector("table")).toBeTruthy();
+    expect(container.querySelector("thead th")?.textContent).toBe("Header");
+    expect(container.querySelector("tbody td")?.textContent).toBe("Data");
+  });
+
+  it("pre passes children through unchanged (code block owns the chrome)", () => {
+    const Pre = C("pre");
+    const { container } = renderWithProviders(<Pre>inner text</Pre>);
+    expect(container.textContent).toContain("inner text");
+    expect(container.querySelector("pre")).toBeNull();
+  });
+});

package/src/mdxComponents.tsx

@@ -4,7 +4,7 @@ import { Link } from "@multiplatform.one/router";
 import type { MDXComponents } from "mdx/types";
 import { Children } from "react";
 import type { XStackProps } from "tamagui";
-import { H1, H2, H3, H4, H5, H6, Paragraph, Text, XStack, YStack, styled } from "tamagui";
+import { H1, H2, H3, H4, H5, H6, Paragraph, Text, XStack, YStack, isWeb, styled } from "tamagui";
 import { ExternalIcon } from "./ExternalIcon";
 import { HR } from "./Hr";
 import { LinkIcon } from "./icons";
@@ -61,8 +61,17 @@ function MdxBlockquote({ children, ...props }: any) {
     <YStack
       marginVertical="$4"
       paddingHorizontal={knobProps.panelPadding.padding}
-      style={{ marginLeft: 12 }}
-      borderLeftWidth={1}
+      // Logical start rail so the quote mirrors in RTL; tamagui
+      // borderStartWidth does not compile to working CSS on web (SB-M-1215)
+      {...(isWeb
+        ? {
+            style: {
+              marginInlineStart: 12,
+              borderInlineStartWidth: 1,
+              borderInlineStartStyle: "solid",
+            } as any,
+          }
+        : { style: { marginInlineStart: 12 }, borderStartWidth: 1 })}
       borderColor="$borderColor"
       justifyContent="center"
       {...props}
@@ -105,7 +114,6 @@ export const mdxComponents: MDXComponents = {
         maxWidth="100%"
         position="relative"
         width={"fit-content" as any}
-        nativeID={id}
         size="$8"
         color="$color11"
         fontWeight="600"
@@ -136,7 +144,8 @@ export const mdxComponents: MDXComponents = {
     return (
       <Link href={href}>
         <Paragraph
-          render="a"
+          // the router Link already renders the anchor; a nested <a> is invalid
+          render="span"
           fontSize="inherit"
           display="inline"
           cursor="pointer"

package/src/mermaid/MermaidBlock.native.tsx

@@ -0,0 +1,15 @@
+/**
+ * Native fallback for mermaid blocks: the engine needs a DOM, so the
+ * diagram source renders as a plain highlighted code block.
+ */
+
+import { CodeBlock } from "../components";
+
+export interface MermaidBlockProps {
+  /** Mermaid diagram source */
+  children: string;
+}
+
+export function MermaidBlock({ children }: MermaidBlockProps) {
+  return <CodeBlock lang="mermaid">{children}</CodeBlock>;
+}

package/src/mermaid/MermaidBlock.tsx

@@ -0,0 +1,88 @@
+/**
+ * Read-only mermaid diagram block for rendered markdown (web).
+ *
+ * Fenced ```mermaid code renders as a live SVG diagram (GitLab behavior).
+ * The engine is lazy-loaded on first render via the canonical
+ * `renderMermaidDiagram` helper; while loading the raw source shows as a
+ * plain code block, and invalid source shows the parse error above the
+ * source (Axiom 6: show the error, never blank).
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { Text, View, useThemeName } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { markdownCodeColors } from "../shared/colorRamps";
+import { CodeBlock } from "../components";
+import { mountDiagramSvg } from "./mountDiagramSvg";
+import { renderMermaidDiagram } from "./renderMermaidDiagram";
+
+export interface MermaidBlockProps {
+  /** Mermaid diagram source */
+  children: string;
+}
+
+type MermaidState =
+  | { status: "loading" }
+  | { status: "ok"; svg: string }
+  | { status: "error"; error: string };
+
+export function MermaidBlock({ children }: MermaidBlockProps) {
+  const { knobProps } = useResolvedKnobs();
+  const themeName = useThemeName();
+  const scheme = String(themeName).startsWith("dark") ? "dark" : "light";
+  const [state, setState] = useState<MermaidState>({ status: "loading" });
+  const svgHostRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setState({ status: "loading" });
+    renderMermaidDiagram(children, { scheme }).then((result) => {
+      if (cancelled) return;
+      setState(
+        result.ok ? { status: "ok", svg: result.svg } : { status: "error", error: result.error },
+      );
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [children, scheme]);
+
+  useEffect(() => {
+    if (state.status !== "ok" || !svgHostRef.current) return;
+    mountDiagramSvg(svgHostRef.current, state.svg);
+  }, [state]);
+
+  if (state.status === "ok") {
+    return (
+      <View
+        {...(knobProps.borderRadiusOuter ?? { borderRadius: "$4" })}
+        backgroundColor={markdownCodeColors.background.base}
+        borderWidth={1}
+        borderColor={markdownCodeColors.border.base}
+        paddingHorizontal={16}
+        paddingVertical={12}
+        marginVertical="$2"
+        overflow="hidden"
+      >
+        <div
+          ref={svgHostRef}
+          role="img"
+          aria-label="Mermaid diagram"
+          data-mermaid-diagram="true"
+          style={{ display: "flex", justifyContent: "center", overflowX: "auto" }}
+        />
+      </View>
+    );
+  }
+
+  return (
+    <View>
+      {state.status === "error" ? (
+        <Text color="$red11" fontSize={13} marginTop="$2" role="alert">
+          {`Mermaid: ${state.error}`}
+        </Text>
+      ) : null}
+      <CodeBlock lang="mermaid">{children}</CodeBlock>
+    </View>
+  );
+}

package/src/mermaid/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Dedicated `@multiplatform.one/markdown/mermaid` entry (LC-16 canonical
+ * mermaid renderer) for lazy consumers like the rich-text editor.
+ *
+ * Deliberately free of static dependencies: importing the package BARREL
+ * from another package makes the barrel's whole static closure (shiki,
+ * the MDX compiler, remark…) graph-reachable, and app chunk-group tests
+ * pin reachable node_modules eager. This entry keeps the editor's dynamic
+ * import surgical — the only heavy module behind it is `mermaid` itself,
+ * loaded through renderMermaidDiagram's own dynamic import.
+ *
+ * The read-only `MermaidBlock` component intentionally does NOT export
+ * from here (it pulls react/tamagui); the package barrel exports it from
+ * `./MermaidBlock` directly.
+ */
+
+export { mountDiagramSvg } from "./mountDiagramSvg";
+export {
+  renderMermaidDiagram,
+  resetMermaidForTesting,
+  type MermaidRenderOptions,
+  type MermaidRenderResult,
+} from "./renderMermaidDiagram";

package/src/mermaid/mountDiagramSvg.ts

@@ -0,0 +1,49 @@
+/**
+ * Mounts a mermaid SVG string into a container as real DOM nodes.
+ *
+ * mermaid already sanitizes its output at securityLevel "strict" (it runs
+ * DOMPurify internally); this helper adds defense in depth: the markup is
+ * parsed inert (scripts never execute during HTML parsing), executable
+ * elements and on* handlers are stripped, and only the <svg> element is
+ * imported into the live document.
+ */
+
+const EXECUTABLE_SELECTOR = "script, iframe, object, embed";
+
+/**
+ * XML parse first (faithful SVG namespaces for importNode), lenient HTML
+ * parse as fallback for markup that is not well-formed XML (e.g. html
+ * labels inside foreignObject).
+ */
+function parseSvgElement(svg: string): Element | null {
+  try {
+    const xml = new DOMParser().parseFromString(svg, "image/svg+xml");
+    const root = xml.documentElement;
+    if (root?.tagName.toLowerCase() === "svg" && !xml.querySelector("parsererror")) {
+      return root;
+    }
+  } catch {
+    // fall through to HTML parsing
+  }
+  const html = new DOMParser().parseFromString(svg, "text/html");
+  return html.body.querySelector("svg");
+}
+
+export function mountDiagramSvg(container: HTMLElement, svg: string): boolean {
+  const root = parseSvgElement(svg);
+  if (!root) return false;
+  for (const el of Array.from(root.querySelectorAll(EXECUTABLE_SELECTOR))) el.remove();
+  for (const el of [root, ...Array.from(root.querySelectorAll("*"))]) {
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (
+        name.startsWith("on") ||
+        (name === "href" && attr.value.trim().toLowerCase().startsWith("javascript:"))
+      ) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+  container.replaceChildren(document.importNode(root, true));
+  return true;
+}

package/src/mermaid/renderMermaidDiagram.spec.ts

@@ -0,0 +1,89 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const initialize = vi.fn();
+const parse = vi.fn();
+const render = vi.fn();
+
+vi.mock("mermaid", () => ({
+  default: { initialize, parse, render },
+}));
+
+import { renderMermaidDiagram, resetMermaidForTesting } from "./renderMermaidDiagram";
+import { mountDiagramSvg } from "./mountDiagramSvg";
+
+beforeEach(() => {
+  resetMermaidForTesting();
+  initialize.mockClear();
+  parse.mockReset().mockResolvedValue(undefined);
+  render.mockReset().mockResolvedValue({ svg: "<svg><g>ok</g></svg>" });
+});
+
+describe("renderMermaidDiagram", () => {
+  it("renders valid source to svg through the lazy engine", async () => {
+    const result = await renderMermaidDiagram("graph TD\n A-->B");
+    expect(result).toEqual({ ok: true, svg: "<svg><g>ok</g></svg>" });
+    expect(parse).toHaveBeenCalledWith("graph TD\n A-->B");
+  });
+
+  it("passes the dark scheme to mermaid theme config", async () => {
+    await renderMermaidDiagram("graph TD\n A-->B", { scheme: "dark" });
+    expect(initialize).toHaveBeenCalledWith(
+      expect.objectContaining({ theme: "dark", securityLevel: "strict", startOnLoad: false }),
+    );
+  });
+
+  it("defaults to the light theme and re-initializes only on scheme change", async () => {
+    await renderMermaidDiagram("a");
+    await renderMermaidDiagram("b");
+    expect(initialize).toHaveBeenCalledTimes(1);
+    expect(initialize).toHaveBeenCalledWith(expect.objectContaining({ theme: "default" }));
+    await renderMermaidDiagram("c", { scheme: "dark" });
+    expect(initialize).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns the parse error for invalid source (Axiom 6: never blank)", async () => {
+    parse.mockRejectedValue(new Error("Parse error on line 2: unexpected token"));
+    const result = await renderMermaidDiagram("graph TD\n A--");
+    expect(result).toEqual({
+      ok: false,
+      error: "Parse error on line 2: unexpected token",
+    });
+    expect(render).not.toHaveBeenCalled();
+  });
+
+  it("returns render failures as errors too", async () => {
+    render.mockRejectedValue(new Error("boom"));
+    const result = await renderMermaidDiagram("graph TD\n A-->B");
+    expect(result).toEqual({ ok: false, error: "boom" });
+  });
+});
+
+describe("mountDiagramSvg", () => {
+  it("mounts the svg element as real nodes", () => {
+    const container = document.createElement("div");
+    expect(mountDiagramSvg(container, "<svg><g><text>hi</text></g></svg>")).toBe(true);
+    expect(container.querySelector("svg g text")?.textContent).toBe("hi");
+  });
+
+  it("strips executable content and handlers (defense in depth)", () => {
+    const container = document.createElement("div");
+    mountDiagramSvg(
+      container,
+      '<svg onload="alert(1)"><script>alert(2)</script>' +
+        '<g onclick="x()"><text>t</text></g>' +
+        '<image href="javascript:alert(3)"></image></svg>',
+    );
+    expect(container.querySelector("script")).toBeNull();
+    expect(container.querySelector("svg")?.getAttribute("onload")).toBeNull();
+    expect(container.querySelector("g")?.getAttribute("onclick")).toBeNull();
+    expect(container.querySelector("image")?.getAttribute("href")).toBeNull();
+    // the safe content survives
+    expect(container.querySelector("text")?.textContent).toBe("t");
+  });
+
+  it("returns false for non-svg payloads", () => {
+    const container = document.createElement("div");
+    expect(mountDiagramSvg(container, "<div>nope</div>")).toBe(false);
+    expect(container.childNodes.length).toBe(0);
+  });
+});

package/src/mermaid/renderMermaidDiagram.ts

@@ -0,0 +1,78 @@
+/**
+ * Canonical lazy mermaid renderer (LC-16: one implementation).
+ *
+ * Consumed by this package's read-only `MermaidBlock` and by the
+ * `@multiplatform.one/rich-text` editor's live code-block preview. The
+ * mermaid engine (~500 KB raw) is NEVER in an eager chunk: it is
+ * dynamically imported on the first diagram render and cached.
+ *
+ * The result contract is Axiom 6 friendly — invalid diagram source returns
+ * `{ ok: false, error }` with mermaid's parse message so callers can show
+ * the error instead of a blank box.
+ */
+
+export interface MermaidRenderOptions {
+  /** Color scheme for mermaid's built-in theming (default "light") */
+  scheme?: "light" | "dark";
+  /** Font family passed to mermaid's theme config */
+  fontFamily?: string;
+}
+
+export type MermaidRenderResult = { ok: true; svg: string } | { ok: false; error: string };
+
+type MermaidModule = typeof import("mermaid").default;
+
+let mermaidPromise: Promise<MermaidModule> | null = null;
+let idCounter = 0;
+let lastInitKey: string | null = null;
+
+function loadMermaid(): Promise<MermaidModule> {
+  if (!mermaidPromise) {
+    mermaidPromise = import("mermaid").then((mod: any) => mod.default ?? mod);
+  }
+  return mermaidPromise;
+}
+
+/**
+ * Renders mermaid source to an isolated SVG string. Re-initializes the
+ * engine only when the scheme/font changes (mermaid config is global).
+ */
+export async function renderMermaidDiagram(
+  code: string,
+  options: MermaidRenderOptions = {},
+): Promise<MermaidRenderResult> {
+  if (typeof document === "undefined") {
+    return { ok: false, error: "Mermaid diagrams require a DOM environment" };
+  }
+  const id = `mpo-mermaid-${++idCounter}`;
+  try {
+    const mermaid = await loadMermaid();
+    const initKey = `${options.scheme ?? "light"}|${options.fontFamily ?? ""}`;
+    if (initKey !== lastInitKey) {
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: options.scheme === "dark" ? "dark" : "default",
+        ...(options.fontFamily ? { fontFamily: options.fontFamily } : {}),
+      });
+      lastInitKey = initKey;
+    }
+    // parse() first: it throws a clean syntax error without leaving the
+    // error bomb SVG that render() can inject into the document
+    await mermaid.parse(code);
+    const { svg } = await mermaid.render(id, code);
+    return { ok: true, svg };
+  } catch (err) {
+    // render() can orphan its temp element on failure — clean it up
+    document.getElementById(`d${id}`)?.remove();
+    document.getElementById(id)?.remove();
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: message };
+  }
+}
+
+/** Test seam: reset engine cache/init state */
+export function resetMermaidForTesting(): void {
+  mermaidPromise = null;
+  lastInitKey = null;
+}