@frontlit/text-editor 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/docs.js

@@ -1,13 +1,18 @@
-import { getSchema, Node } from '@tiptap/core';
+import { Extension, getSchema, Node } from '@tiptap/core';
 import StarterKit from '@tiptap/starter-kit';
+import CodeBlock from '@tiptap/extension-code-block';
 import Image from '@tiptap/extension-image';
 import Link from '@tiptap/extension-link';
 import { TableRow, Table, TableCell, TableHeader } from '@tiptap/extension-table';
+import Code from '@tiptap/extension-code';
 import { parseDocument, stringify } from 'yaml';
 import { unified } from 'unified';
 import remarkParse from 'remark-parse';
 import remarkGfm from 'remark-gfm';
 import remarkStringify from 'remark-stringify';
+import { mdxJsx } from 'micromark-extension-mdx-jsx';
+import { mdxJsxFromMarkdown, mdxJsxToMarkdown } from 'mdast-util-mdx-jsx';
+import { parseExpressionAt } from 'acorn';
 
 // src/docs/diagnostics.ts
 function diagnostic(code, message, location = {}) {
@@ -68,11 +73,112 @@ function isSafeDocsUrl(value, image = false) {
     return false;
   }
 }
+var CALLOUT_TYPES = ["note", "tip", "info", "warning", "danger"];
+function attr(name, fallback = null) {
+  return {
+    [name]: {
+      default: fallback,
+      parseHTML: (element) => {
+        const value = element.getAttribute(`data-${name}`);
+        if (value === null) return fallback;
+        try {
+          return JSON.parse(value);
+        } catch {
+          return fallback;
+        }
+      },
+      renderHTML: (attributes2) => attributes2[name] === null || attributes2[name] === void 0 ? {} : { [`data-${name}`]: JSON.stringify(attributes2[name]) }
+    }
+  };
+}
+function block(name, spec) {
+  const tag = `div[data-docs-block="${name}"]`;
+  return Node.create({
+    name,
+    group: spec.group,
+    content: spec.content,
+    atom: spec.atom,
+    defining: true,
+    isolating: true,
+    addAttributes() {
+      return Object.assign(
+        {},
+        ...Object.entries(spec.attrs ?? {}).map(([key, value]) => attr(key, value))
+      );
+    },
+    parseHTML() {
+      return [{ tag }];
+    },
+    renderHTML({ HTMLAttributes }) {
+      return spec.atom ? ["div", { ...HTMLAttributes, "data-docs-block": name }] : ["div", { ...HTMLAttributes, "data-docs-block": name }, 0];
+    }
+  });
+}
+var DocsCode = Code.extend({ excludes: "" });
+function createDocsBlockExtensions() {
+  return [
+    DocsCode,
+    block("callout", {
+      group: "block",
+      content: "block+",
+      attrs: { type: null, title: null }
+    }),
+    block("tabs", { group: "block", content: "tab+" }),
+    block("tab", { content: "block+", attrs: { label: "" } }),
+    block("steps", { group: "block", content: "step+" }),
+    block("step", { content: "block+" }),
+    block("cards", { group: "block", content: "card+" }),
+    block("card", {
+      content: "block*",
+      attrs: { title: "", href: null, icon: null }
+    }),
+    block("accordions", {
+      group: "block",
+      content: "accordion+",
+      attrs: { type: null }
+    }),
+    block("accordion", { content: "block+", attrs: { title: "" } }),
+    block("codeGroup", { group: "block", content: "codeBlock+" }),
+    block("typeTable", { group: "block", atom: true, attrs: { rows: [] } })
+  ];
+}
+var DOCS_BLOCK_COMPONENTS = {
+  Callout: "callout",
+  Tabs: "tabs",
+  Tab: "tab",
+  Steps: "steps",
+  Step: "step",
+  Cards: "cards",
+  Card: "card",
+  Accordions: "accordions",
+  Accordion: "accordion",
+  CodeGroup: "codeGroup",
+  TypeTable: "typeTable"
+};
+var CodeBlockTitle = Extension.create({
+  name: "codeBlockTitle",
+  addGlobalAttributes() {
+    return [
+      {
+        types: ["codeBlock"],
+        attributes: {
+          title: {
+            default: null,
+            parseHTML: (element) => element.getAttribute("data-title"),
+            renderHTML: (attributes2) => attributes2.title ? { "data-title": attributes2.title } : {}
+          }
+        }
+      }
+    ];
+  }
+});
 
 // src/docs/extensions.ts
 function createDocsExtensions() {
   return [
     StarterKit.configure({
+      code: false,
+      codeBlock: false,
       document: false,
       underline: false,
       link: false,
@@ -90,7 +196,10 @@ function createDocsExtensions() {
     Table.configure({ resizable: false }),
     TableRow,
     TableCell.extend({ content: "paragraph" }),
-    TableHeader.extend({ content: "paragraph" })
+    TableHeader.extend({ content: "paragraph" }),
+    CodeBlock,
+    CodeBlockTitle,
+    ...createDocsBlockExtensions()
   ];
 }
 var docsSchema = getSchema(createDocsExtensions());
@@ -137,6 +246,11 @@ var DOCS_LIMITS = {
 };
 var record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
 var nullableString = (v) => v === null || typeof v === "string";
+var label = (v) => typeof v === "string";
+var nullableLabel = nullableString;
+var typeTableRow = (v) => record(v) && Object.keys(v).every(
+  (key) => ["name", "type", "default", "description", "required"].includes(key)
+) && label(v.name) && typeof v.type === "string" && nullableString(v.default) && nullableString(v.description) && typeof v.required === "boolean";
 var attributes = {
   heading: { level: (v) => Number.isInteger(v) && Number(v) >= 1 && Number(v) <= 6 },
   orderedList: {
@@ -144,7 +258,23 @@ var attributes = {
     type: (v) => v === null
   },
   codeBlock: {
-    language: (v) => v === null || typeof v === "string" && /^[\w+-]+$/.test(v)
+    language: (v) => v === null || typeof v === "string" && /^[\w+-]+$/.test(v),
+    title: nullableLabel
+  },
+  callout: {
+    type: (v) => v === null || CALLOUT_TYPES.includes(v),
+    title: nullableLabel
+  },
+  tab: { label },
+  card: {
+    title: label,
+    href: nullableString,
+    icon: (v) => v === null || typeof v === "string" && /^[A-Za-z][\w-]*$/.test(v)
+  },
+  accordions: { type: (v) => v === null || v === "single" || v === "multiple" },
+  accordion: { title: label },
+  typeTable: {
+    rows: (v) => Array.isArray(v) && v.every(typeTableRow) && new Set(v.map((row) => row.name)).size === v.length
   },
   image: {
     src: (v) => typeof v === "string",
@@ -257,16 +387,12 @@ function validateDocsContent(input) {
           if (mark.type === "link" && (!record(mark.attrs) || !isSafeDocsUrl(mark.attrs.href)))
             add("UNSAFE_URL", "Link URL is unsafe.", `${mp}.attrs.href`);
         });
-        if (seen.has("code") && seen.size > 1)
-          add(
-            "INVALID_DOCUMENT",
-            "Inline code cannot carry other marks.",
-            `${path}.marks`
-          );
       }
     }
     if (node.type === "image" && (!record(node.attrs) || !isSafeDocsUrl(node.attrs.src, true)))
       add("UNSAFE_URL", "Images require a stable HTTPS URL.", `${path}.attrs.src`);
+    if (node.type === "card" && record(node.attrs) && typeof node.attrs.href === "string" && !isSafeDocsUrl(node.attrs.href))
+      add("UNSAFE_URL", "Card link URL is unsafe.", `${path}.attrs.href`);
     if (node.type === "heading" && (!record(node.attrs) || !Number.isInteger(node.attrs.level)))
       add("INVALID_DOCUMENT", "Heading level is required.", `${path}.attrs.level`);
     if (node.content !== void 0) {
@@ -310,6 +436,18 @@ function validateDocsContent(input) {
   const normalize = (node) => ({
     ...node,
     ...node.type === "image" ? { attrs: { ...node.attrs, alt: node.attrs?.alt ?? "" } } : {},
+    // Type table rows are one attribute value; give them a fixed key order.
+    ...node.type === "typeTable" ? {
+      attrs: {
+        rows: (node.attrs?.rows ?? []).map((row) => ({
+          name: row.name,
+          type: row.type,
+          default: row.default,
+          description: row.description,
+          required: row.required
+        }))
+      }
+    } : {},
     ...node.content ? { content: node.content.map(normalize) } : {}
   });
   const content = normalize(docsSchema.nodeFromJSON(input).toJSON());
@@ -546,15 +684,160 @@ ${stringify(requireDocsFrontmatter(meta), { sortMapEntries: true, aliasDuplicate
 
 `;
 }
-var DOCS_PARSER_VERSION = 1;
+var DOCS_PARSER_VERSION = 2;
+function jsxTags() {
+  const data = this.data();
+  data.micromarkExtensions = [...data.micromarkExtensions ?? [], mdxJsx()];
+  data.fromMarkdownExtensions = [
+    ...data.fromMarkdownExtensions ?? [],
+    mdxJsxFromMarkdown()
+  ];
+  data.toMarkdownExtensions = [
+    ...data.toMarkdownExtensions ?? [],
+    mdxJsxToMarkdown(),
+    {
+      // The stock handler indents children, which turns nested fences into indented code.
+      handlers: { mdxJsxFlowElement: writeComponent }
+    }
+  ];
+}
+function writeComponent(node, _parent, state, info) {
+  const props = node.attributes.map((attribute) => {
+    const { name, value } = attribute;
+    if (value === null || value === void 0) return name;
+    if (typeof value === "string")
+      return `${name}="${value.replace(/&/g, "&amp;").replace(/"/g, "&quot;")}"`;
+    return `${name}={${value.value}}`;
+  });
+  const multiline = props.some((item) => item.includes("\n"));
+  const open = multiline ? `<${node.name}
+${props.map((item) => `  ${item}`).join("\n")}
+` : `<${node.name}${props.map((item) => ` ${item}`).join("")}`;
+  if (!node.children.length) return `${open}${multiline ? "" : " "}/>`;
+  const body = state.containerFlow(node, info);
+  return `${open}>
+
+${body}
+
+</${node.name}>`;
+}
+function noIndentedCode() {
+  const data = this.data();
+  data.micromarkExtensions = [
+    ...data.micromarkExtensions ?? [],
+    { disable: { null: ["codeIndented"] } }
+  ];
+}
 var parser = unified().use(remarkParse).use(remarkGfm);
-var writer = unified().use(remarkGfm).use(remarkStringify, {
+var componentParser = unified().use(remarkParse).use(remarkGfm).use(jsxTags).use(noIndentedCode);
+var writer = unified().use(remarkGfm).use(jsxTags).use(remarkStringify, {
   bullet: "-",
   emphasis: "*",
   strong: "*",
   fences: true,
-  incrementListMarker: true
+  incrementListMarker: true,
+  resourceLink: true
 });
+var COMPONENT_TAG = new RegExp(
+  `<\\/?(?:${Object.keys(DOCS_BLOCK_COMPONENTS).join("|")})\\b`
+);
+var CODE_TITLE = /^title=(?:"([^"\n]+)"|'([^'\n]+)')$/;
+var IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+var ICON = /^[A-Za-z][\w-]*$/;
+var PROPS = {
+  Callout: ["type", "title"],
+  Tabs: ["items"],
+  Tab: ["value"],
+  Steps: [],
+  Step: [],
+  Cards: [],
+  Card: ["title", "href", "icon"],
+  Accordions: ["type"],
+  Accordion: ["title"],
+  CodeGroup: [],
+  TypeTable: ["type"]
+};
+var CHILD = {
+  Tabs: "Tab",
+  Steps: "Step",
+  Cards: "Card",
+  Accordions: "Accordion"
+};
+var TYPE_TABLE_FIELDS = ["type", "default", "description", "required"];
+function parseTree(body, fail) {
+  if (!COMPONENT_TAG.test(body)) return parser.parse(body);
+  try {
+    return componentParser.parse(body);
+  } catch (cause) {
+    const {
+      line,
+      column,
+      reason = String(cause)
+    } = cause;
+    const place = /\((\d+):(\d+)-/.exec(reason);
+    return fail(
+      line ? { line, column: column ?? 1 } : place ? { line: Number(place[1]), column: Number(place[2]) } : void 0,
+      `Invalid component syntax: ${reason}`
+    );
+  }
+}
+function literal(source) {
+  const expression = parseExpressionAt(source, 0, { ecmaVersion: "latest" });
+  if (source.slice(expression.end).trim()) throw new Error("Unexpected input.");
+  return evaluate(expression);
+}
+function evaluate(node) {
+  switch (node.type) {
+    case "Literal":
+      if (node.value === null || ["string", "number", "boolean"].includes(typeof node.value))
+        return node.value;
+      break;
+    case "TemplateLiteral":
+      if (!node.expressions.length) return node.quasis[0].value.cooked;
+      break;
+    case "UnaryExpression":
+      if (node.operator === "-" && node.argument.type === "Literal" && typeof node.argument.value === "number")
+        return -node.argument.value;
+      break;
+    case "ArrayExpression":
+      return node.elements.map((element) => {
+        if (!element || element.type === "SpreadElement")
+          throw new Error("Not literal.");
+        return evaluate(element);
+      });
+    case "ObjectExpression": {
+      const output = {};
+      for (const property of node.properties) {
+        if (property.type !== "Property" || property.kind !== "init" || property.computed || property.method || property.shorthand)
+          throw new Error("Not literal.");
+        const key = property.key.type === "Identifier" ? property.key.name : property.key.type === "Literal" && typeof property.key.value === "string" ? property.key.value : void 0;
+        if (key === void 0 || key === "__proto__" || Object.hasOwn(output, key))
+          throw new Error("Not literal.");
+        output[key] = evaluate(property.value);
+      }
+      return output;
+    }
+  }
+  throw new Error("Not literal.");
+}
+function quote(value) {
+  return value.includes('"') && !/['\\\n]/.test(value) ? `'${value}'` : JSON.stringify(value);
+}
+function formatRows(rows) {
+  const lines = rows.map((row) => {
+    const fields = [
+      `type: ${quote(row.type)}`,
+      ...row.default === null ? [] : [`default: ${quote(row.default)}`],
+      ...row.description === null ? [] : [`description: ${quote(row.description)}`],
+      ...row.required ? ["required: true"] : []
+    ];
+    const key = IDENTIFIER.test(row.name) ? row.name : JSON.stringify(row.name);
+    return `    ${key}: { ${fields.join(", ")} },`;
+  });
+  return `{
+${lines.join("\n")}
+  }`;
+}
 function parseDocsMarkdown(markdown, options = {}) {
   if (typeof markdown !== "string" || new TextEncoder().encode(markdown).length > DOCS_LIMITS.bytes)
     throw new DocsContentError([
@@ -567,7 +850,15 @@ function parseDocsMarkdown(markdown, options = {}) {
     lineOffset: 0,
     frontmatter: void 0
   } : splitDocsFrontmatter(markdown, options.file);
-  const tree = parser.parse(source.body);
+  const tree = parseTree(source.body, (place, message) => {
+    throw new DocsContentError([
+      diagnostic("UNSUPPORTED_NODE", message, {
+        file: options.file,
+        line: place ? place.line + source.lineOffset : void 0,
+        column: place?.column
+      })
+    ]);
+  });
   const definitions = /* @__PURE__ */ new Map();
   function error(node, message, code = "UNSUPPORTED_NODE") {
     throw new DocsContentError([
@@ -617,8 +908,9 @@ function parseDocsMarkdown(markdown, options = {}) {
         case "delete":
           return inline(node.children, [...marks, { type: "strike" }]);
         case "inlineCode":
-          if (marks.length) error(node, "Inline code cannot carry other marks.");
-          return [{ type: "text", text: node.value, marks: [{ type: "code" }] }];
+          return [
+            { type: "text", text: node.value, marks: [...marks, { type: "code" }] }
+          ];
         case "break":
           if (marks.length) error(node, "Marked line breaks are unsupported.");
           return [{ type: "hardBreak" }];
@@ -641,6 +933,11 @@ function parseDocsMarkdown(markdown, options = {}) {
             }
           ]);
         }
+        case "mdxJsxTextElement":
+          return error(
+            node,
+            `Inline <${node.name ?? ""}> is unsupported. Put the component on its own lines.`
+          );
         default:
           return error(node, `Unsupported inline construct: ${node.type}.`);
       }
@@ -658,11 +955,196 @@ function parseDocsMarkdown(markdown, options = {}) {
       }
     };
   }
-  function block(node) {
+  function props(node) {
+    const name = node.name ?? "";
+    const output = {};
+    for (const attribute of node.attributes) {
+      if (attribute.type === "mdxJsxExpressionAttribute")
+        error(node, "Spread props are unsupported.", "UNSUPPORTED_ATTRIBUTE");
+      if (!PROPS[name].includes(attribute.name))
+        error(
+          node,
+          `Unsupported <${name}> prop: ${attribute.name}.`,
+          "UNSUPPORTED_ATTRIBUTE"
+        );
+      const value = attribute.value;
+      const icon = name === "Card" && attribute.name === "icon" && typeof value === "object" && value ? /^\s*<([A-Za-z][\w-]*)\s*\/>\s*$/.exec(value.value) : null;
+      if (value === null || value === void 0) output[attribute.name] = true;
+      else if (typeof value === "string") output[attribute.name] = value;
+      else if (icon) output.icon = icon[1];
+      else
+        try {
+          output[attribute.name] = literal(value.value);
+        } catch {
+          error(
+            node,
+            `<${name}> prop ${attribute.name} must be a literal value.`,
+            "UNSUPPORTED_ATTRIBUTE"
+          );
+        }
+    }
+    return output;
+  }
+  function component(node, children, parent) {
+    const name = node.name ?? "";
+    if (!Object.hasOwn(PROPS, name))
+      error(
+        node,
+        `Unknown component <${name}>. Use a supported block or plain Markdown.`
+      );
+    const container = Object.keys(CHILD).find((key) => CHILD[key] === name);
+    if (container && parent !== container)
+      error(node, `<${name}> must be inside <${container}>.`);
+    const p = props(node);
+    const label2 = (prop, required) => {
+      const value = p[prop];
+      if (value === void 0 && !required) return null;
+      if (typeof value !== "string")
+        error(node, `<${name}> needs a text ${prop} prop.`, "INVALID_DOCUMENT");
+      return value;
+    };
+    const content2 = (optional = false) => {
+      const output = children.flatMap(block2);
+      return output.length || optional ? output : [{ type: "paragraph" }];
+    };
+    const items = () => {
+      const output = children.filter((child) => child.type !== "definition").map((child) => {
+        if (child.type !== "mdxJsxFlowElement" || child.name !== CHILD[name])
+          error(child, `<${name}> can only contain <${CHILD[name]}>.`);
+        return child;
+      });
+      if (!output.length)
+        error(
+          node,
+          `<${name}> needs at least one <${CHILD[name]}>.`,
+          "INVALID_DOCUMENT"
+        );
+      return output;
+    };
+    const nested = () => items().map((child) => component(child, child.children, name));
+    switch (name) {
+      case "Callout": {
+        const type = p.type ?? null;
+        if (type !== null && !CALLOUT_TYPES.includes(type))
+          error(
+            node,
+            `Callout type must be one of: ${CALLOUT_TYPES.join(", ")}.`,
+            "UNSUPPORTED_ATTRIBUTE"
+          );
+        return {
+          type: "callout",
+          attrs: { type, title: label2("title", false) },
+          content: content2()
+        };
+      }
+      case "Tabs": {
+        const listed = p.items;
+        if (listed !== void 0 && !(Array.isArray(listed) && listed.every((item) => typeof item === "string")))
+          error(
+            node,
+            "<Tabs> items must be a list of strings.",
+            "UNSUPPORTED_ATTRIBUTE"
+          );
+        const tabs = nested().map((tab, i) => {
+          const value = tab.attrs.label ?? listed?.[i] ?? "";
+          if (listed && !listed.includes(value))
+            error(
+              node,
+              `Tab value "${value}" is not listed in items.`,
+              "INVALID_DOCUMENT"
+            );
+          return { ...tab, attrs: { label: value } };
+        });
+        return { type: "tabs", content: tabs };
+      }
+      case "Tab":
+        return {
+          type: "tab",
+          attrs: { label: label2("value", false) },
+          content: content2()
+        };
+      case "Steps":
+        return { type: "steps", content: nested() };
+      case "Step":
+        return { type: "step", content: content2() };
+      case "Cards":
+        return { type: "cards", content: nested() };
+      case "Card": {
+        const href = label2("href", false);
+        if (href !== null && !isSafeDocsUrl(href))
+          error(node, "Card link URL is unsafe.", "UNSAFE_URL");
+        const icon = label2("icon", false);
+        if (icon !== null && !ICON.test(icon))
+          error(node, "Card icon must be an icon name.", "UNSUPPORTED_ATTRIBUTE");
+        const body = content2(true);
+        return {
+          type: "card",
+          attrs: { title: label2("title", true), href, icon },
+          ...body.length ? { content: body } : {}
+        };
+      }
+      case "Accordions": {
+        const type = p.type ?? null;
+        if (type !== null && type !== "single" && type !== "multiple")
+          error(
+            node,
+            'Accordions type must be "single" or "multiple".',
+            "UNSUPPORTED_ATTRIBUTE"
+          );
+        return { type: "accordions", attrs: { type }, content: nested() };
+      }
+      case "Accordion":
+        return {
+          type: "accordion",
+          attrs: { title: label2("title", true) },
+          content: content2()
+        };
+      case "CodeGroup": {
+        for (const child of children)
+          if (child.type !== "code")
+            error(child, "<CodeGroup> can only contain code blocks.");
+        return { type: "codeGroup", content: content2() };
+      }
+      default: {
+        if (children.length) error(node, "<TypeTable> cannot have children.");
+        const type = p.type;
+        if (!type || typeof type !== "object" || Array.isArray(type))
+          error(node, "<TypeTable> needs a type={{ \u2026 }} prop.", "INVALID_DOCUMENT");
+        const rows = Object.entries(type).map(
+          ([field, entry]) => {
+            const value = entry;
+            if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.type !== "string" || Object.keys(value).some((key) => !TYPE_TABLE_FIELDS.includes(key)) || !["string", "undefined"].includes(typeof value.default) || !["string", "undefined"].includes(typeof value.description) || !["boolean", "undefined"].includes(typeof value.required))
+              error(
+                node,
+                `<TypeTable> field ${field} needs a string type and only string default/description and boolean required.`,
+                "UNSUPPORTED_ATTRIBUTE"
+              );
+            return {
+              name: field,
+              type: value.type,
+              default: value.default ?? null,
+              description: value.description ?? null,
+              required: value.required ?? false
+            };
+          }
+        );
+        return { type: "typeTable", attrs: { rows } };
+      }
+    }
+  }
+  function block2(node) {
     switch (node.type) {
       case "definition":
         return [];
       case "paragraph": {
+        const only = node.children.length === 1 ? node.children[0] : void 0;
+        if (only?.type === "mdxJsxTextElement")
+          return [
+            component(
+              only,
+              only.children.length ? [{ type: "paragraph", children: only.children }] : []
+            )
+          ];
         if (node.children.length === 1 && ["image", "imageReference"].includes(node.children[0].type))
           return [
             image(
@@ -680,19 +1162,40 @@ function parseDocsMarkdown(markdown, options = {}) {
           }
         ];
       case "blockquote":
-        return [{ type: "blockquote", content: node.children.flatMap(block) }];
+        return [{ type: "blockquote", content: node.children.flatMap(block2) }];
       case "thematicBreak":
         return [{ type: "horizontalRule" }];
-      case "code":
-        if (node.meta)
-          error(node, "Code fence metadata is unsupported.", "UNSUPPORTED_ATTRIBUTE");
+      case "code": {
+        const untitled = node.lang?.startsWith("title=");
+        const meta = untitled ? [node.lang, node.meta].filter(Boolean).join(" ") : node.meta;
+        const lang = untitled ? null : node.lang;
+        const title = meta ? CODE_TITLE.exec(meta.trim()) : null;
+        if (meta && !title)
+          error(
+            node,
+            'Code fence metadata other than title="\u2026" is unsupported.',
+            "UNSUPPORTED_ATTRIBUTE"
+          );
         return [
           {
             type: "codeBlock",
-            attrs: { language: node.lang ?? null },
+            attrs: {
+              language: lang ?? null,
+              ...title ? { title: title[1] ?? title[2] } : {}
+            },
             content: node.value ? [{ type: "text", text: node.value }] : []
           }
         ];
+      }
+      case "mdxJsxFlowElement":
+        return [component(node, node.children)];
+      case "html": {
+        const tag = /^<([A-Z][\w.]*)/.exec(node.value);
+        return error(
+          node,
+          tag ? `Unknown component <${tag[1]}>. Use a supported block or plain Markdown.` : "Raw HTML is unsupported."
+        );
+      }
       case "list":
         return [
           {
@@ -701,7 +1204,7 @@ function parseDocsMarkdown(markdown, options = {}) {
             content: node.children.map((item) => {
               if (item.checked !== null && item.checked !== void 0)
                 error(item, "Task lists are unsupported.");
-              const content2 = item.children.flatMap(block);
+              const content2 = item.children.flatMap(block2);
               return {
                 type: "listItem",
                 content: content2.length ? content2 : [{ type: "paragraph" }]
@@ -730,7 +1233,7 @@ function parseDocsMarkdown(markdown, options = {}) {
   }
   const content = requireDocsContent({
     type: "doc",
-    content: tree.children.flatMap(block)
+    content: tree.children.flatMap(block2)
   });
   return { content, frontmatter: source.frontmatter };
 }
@@ -790,7 +1293,20 @@ function toInline(children) {
 }
 function serializeDocsMarkdown(input, frontmatter) {
   const content = requireDocsContent(input);
-  function block(node) {
+  const prop = (name, value, expression = false) => value === null || value === void 0 ? void 0 : {
+    type: "mdxJsxAttribute",
+    name,
+    value: expression ? { type: "mdxJsxAttributeValueExpression", value } : value
+  };
+  function element(name, attributes2, content2, nested) {
+    return {
+      type: "mdxJsxFlowElement",
+      name,
+      attributes: attributes2.filter((item) => item !== void 0),
+      children: nested ? nested() : content2.map(block2)
+    };
+  }
+  function block2(node) {
     const children = node.content ?? [];
     switch (node.type) {
       case "paragraph":
@@ -815,16 +1331,83 @@ function serializeDocsMarkdown(input, frontmatter) {
             }
           ]
         };
-      case "codeBlock":
+      case "codeBlock": {
+        const title = node.attrs?.title ?? null;
+        const language = node.attrs?.language ?? null;
+        const meta = title ? title.includes('"') ? `title='${title}'` : `title="${title}"` : null;
         return {
           type: "code",
-          lang: node.attrs?.language ?? null,
+          lang: language ?? meta,
+          meta: language ? meta : null,
           value: children.map((child) => child.text ?? "").join("")
         };
+      }
+      case "callout":
+        return element(
+          "Callout",
+          [prop("type", node.attrs?.type), prop("title", node.attrs?.title)],
+          children
+        );
+      case "tabs": {
+        const labels = children.map((tab) => quote(tab.attrs.label));
+        return element(
+          "Tabs",
+          [prop("items", `[${labels.join(", ")}]`, true)],
+          [],
+          () => children.map(
+            (tab) => element("Tab", [prop("value", tab.attrs.label)], tab.content ?? [])
+          )
+        );
+      }
+      case "steps":
+        return element(
+          "Steps",
+          [],
+          [],
+          () => children.map((step) => element("Step", [], step.content ?? []))
+        );
+      case "cards":
+        return element(
+          "Cards",
+          [],
+          [],
+          () => children.map(
+            (card) => element(
+              "Card",
+              [
+                prop("title", card.attrs.title),
+                prop("href", card.attrs?.href),
+                prop("icon", card.attrs?.icon ? `<${card.attrs.icon} />` : null, true)
+              ],
+              card.content ?? []
+            )
+          )
+        );
+      case "accordions":
+        return element(
+          "Accordions",
+          [prop("type", node.attrs?.type)],
+          [],
+          () => children.map(
+            (item) => element(
+              "Accordion",
+              [prop("title", item.attrs.title)],
+              item.content ?? []
+            )
+          )
+        );
+      case "codeGroup":
+        return element("CodeGroup", [], children);
+      case "typeTable":
+        return element(
+          "TypeTable",
+          [prop("type", formatRows(node.attrs?.rows ?? []), true)],
+          []
+        );
       case "blockquote":
         return {
           type: "blockquote",
-          children: children.map(block)
+          children: children.map(block2)
         };
       case "bulletList":
       case "orderedList":
@@ -836,7 +1419,7 @@ function serializeDocsMarkdown(input, frontmatter) {
           children: children.map((item) => ({
             type: "listItem",
             spread: true,
-            children: (item.content ?? []).map(block)
+            children: (item.content ?? []).map(block2)
           }))
         };
       case "table":
@@ -856,15 +1439,18 @@ function serializeDocsMarkdown(input, frontmatter) {
         ]);
     }
   }
-  const tree = { type: "root", children: (content.content ?? []).map(block) };
+  const tree = { type: "root", children: (content.content ?? []).map(block2) };
   const markdown = writer.stringify(tree);
   const roundtrip = parseDocsMarkdown(markdown, { frontmatter: false }).content;
-  const semantic = (doc) => ({
-    ...doc,
-    content: doc.content?.filter(
-      (node) => node.type !== "paragraph" || node.content?.length
-    ) ?? []
-  });
+  const semantic = (node) => {
+    if (!node.content) return node;
+    const children = node.content.filter((child) => child.type !== "paragraph" || child.content?.length).map(semantic);
+    const required = node.type !== "doc" && !docsSchema.nodes[node.type].contentMatch.validEnd;
+    if (children.length) return { ...node, content: children };
+    if (required) return { ...node, content: [{ type: "paragraph" }] };
+    const { content: _empty, ...rest } = node;
+    return node.type === "doc" ? { ...rest, content: [] } : rest;
+  };
   if (JSON.stringify(semantic(roundtrip)) !== JSON.stringify(semantic(content)))
     throw new DocsContentError([
       diagnostic(