radiant-docs 0.1.16 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.16",
+  "version": "0.1.20",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {
@@ -10,8 +10,8 @@
     "bundle-template": "node scripts/bundle-template.js",
     "build": "tsup src/index.ts --format esm --clean && npm run bundle-template",
     "dev": "tsup src/index.ts --format esm --watch",
-    "prepublishOnly": "npm run build && npm version patch",
-    "publish": "npm publish"
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm publish"
   },
   "dependencies": {
     "chokidar": "^4.0.3",

package/template/src/components/user/CodeBlock.astro

@@ -340,61 +340,60 @@ const renderedCodeLinesHtml = normalizedTokenLines
       </div>
     </div>
   </div>
-</div>
-
-<script is:inline>
-  (() => {
-    const script = document.currentScript;
-    if (!(script instanceof HTMLScriptElement)) return;
-
-    const root = script.previousElementSibling;
-    if (!(root instanceof HTMLElement)) return;
-
-    const copyButtons = root.querySelectorAll("[data-rd-copy-trigger='true']");
-    if (copyButtons.length === 0) return;
-
-    const setCopiedState = (button, copied) => {
-      const copyIcon = button.querySelector("[data-rd-copy-icon]");
-      const checkIcon = button.querySelector("[data-rd-copy-check]");
+  <script is:inline>
+    (() => {
+      const script = document.currentScript;
+      if (!(script instanceof HTMLScriptElement)) return;
 
-      if (!copyIcon || !checkIcon) return;
+      const root = script.closest("[data-rd-code-block-root='true']");
+      if (!(root instanceof HTMLElement)) return;
 
-      if (copied) {
-        copyIcon.classList.add("scale-50", "opacity-0", "-rotate-6");
-        copyIcon.classList.remove("scale-100", "opacity-100", "rotate-0");
+      const copyButtons = root.querySelectorAll("[data-rd-copy-trigger='true']");
+      if (copyButtons.length === 0) return;
 
-        checkIcon.classList.remove("scale-50", "opacity-0", "rotate-6");
-        checkIcon.classList.add("scale-110", "opacity-100", "rotate-0");
-        return;
-      }
-
-      copyIcon.classList.remove("scale-50", "opacity-0", "-rotate-6");
-      copyIcon.classList.add("scale-100", "opacity-100", "rotate-0");
+      const setCopiedState = (button, copied) => {
+        const copyIcon = button.querySelector("[data-rd-copy-icon]");
+        const checkIcon = button.querySelector("[data-rd-copy-check]");
 
-      checkIcon.classList.remove("scale-110", "opacity-100", "rotate-0");
-      checkIcon.classList.add("scale-50", "opacity-0", "rotate-6");
-    };
+        if (!copyIcon || !checkIcon) return;
 
-    copyButtons.forEach((button) => {
-      let timeoutId = null;
-      button.addEventListener("click", async () => {
-        const encodedCopyValue =
-          button.getAttribute("data-rd-copy-content") ?? "";
-        const copyValue = decodeURIComponent(encodedCopyValue);
+        if (copied) {
+          copyIcon.classList.add("scale-50", "opacity-0", "-rotate-6");
+          copyIcon.classList.remove("scale-100", "opacity-100", "rotate-0");
 
-        try {
-          await navigator.clipboard.writeText(copyValue);
-          setCopiedState(button, true);
+          checkIcon.classList.remove("scale-50", "opacity-0", "rotate-6");
+          checkIcon.classList.add("scale-110", "opacity-100", "rotate-0");
+          return;
+        }
 
-          if (timeoutId) window.clearTimeout(timeoutId);
-          timeoutId = window.setTimeout(() => {
+        copyIcon.classList.remove("scale-50", "opacity-0", "-rotate-6");
+        copyIcon.classList.add("scale-100", "opacity-100", "rotate-0");
+
+        checkIcon.classList.remove("scale-110", "opacity-100", "rotate-0");
+        checkIcon.classList.add("scale-50", "opacity-0", "rotate-6");
+      };
+
+      copyButtons.forEach((button) => {
+        let timeoutId = null;
+        button.addEventListener("click", async () => {
+          const encodedCopyValue =
+            button.getAttribute("data-rd-copy-content") ?? "";
+          const copyValue = decodeURIComponent(encodedCopyValue);
+
+          try {
+            await navigator.clipboard.writeText(copyValue);
+            setCopiedState(button, true);
+
+            if (timeoutId) window.clearTimeout(timeoutId);
+            timeoutId = window.setTimeout(() => {
+              setCopiedState(button, false);
+              timeoutId = null;
+            }, 1200);
+          } catch {
             setCopiedState(button, false);
-            timeoutId = null;
-          }, 1200);
-        } catch {
-          setCopiedState(button, false);
-        }
+          }
+        });
       });
-    });
-  })();
-</script>
+    })();
+  </script>
+</div>

package/template/src/components/user/ComponentPreviewBlock.astro

@@ -100,19 +100,53 @@ const isInitiallyExpanded = shouldShowAllCode || totalLineCount <= visibleLines;
 </div>
 
 <style>
-  .rd-component-preview :global(.group\/prose-code) {
+  .rd-component-preview :global([data-rd-preview-heading="true"]) {
+    color: var(--tw-prose-headings, currentColor);
+    font-weight: 600;
+  }
+
+  .rd-component-preview :global([data-rd-preview-heading-level="2"]) {
+    font-size: 1.5em;
+    line-height: 1.3333333;
+    margin-top: 2em;
+    margin-bottom: 1em;
+  }
+
+  .rd-component-preview :global([data-rd-preview-heading-level="3"]) {
+    font-size: 1.25em;
+    line-height: 1.6;
+    margin-top: 1.6em;
+    margin-bottom: 0.6em;
+  }
+
+  .rd-component-preview :global([data-rd-preview-heading-level="4"]) {
+    font-size: 1em;
+    line-height: 1.5;
+    margin-top: 1.5em;
+    margin-bottom: 0.5em;
+  }
+
+  .rd-component-preview :global([data-rd-preview-heading-level="5"]),
+  .rd-component-preview :global([data-rd-preview-heading-level="6"]) {
+    font-size: 0.875em;
+    line-height: 1.5714286;
+    margin-top: 1.4285714em;
+    margin-bottom: 0.5714286em;
+  }
+
+  .rd-component-preview__code :global(.group\/prose-code) {
     margin-top: 0 !important;
     margin-bottom: 0 !important;
   }
 
-  .rd-component-preview :global(.group\/prose-code > div) {
+  .rd-component-preview__code :global(.group\/prose-code > div) {
     background-color: var(--color-neutral-50) !important;
     border-top-left-radius: 0 !important;
     border-top-right-radius: 0 !important;
   }
 
-  .rd-component-preview :global(.group\/prose-code pre),
-  .rd-component-preview :global(.group\/prose-code code) {
+  .rd-component-preview__code :global(.group\/prose-code pre),
+  .rd-component-preview__code :global(.group\/prose-code code) {
     background-color: var(--color-neutral-50) !important;
   }
 

package/template/src/lib/mdx/remark-code-block-component.ts

@@ -56,6 +56,17 @@ type MdxJsxTextElementNode = {
   children?: unknown[];
 };
 
+type HeadingNode = {
+  type: "heading";
+  depth?: number;
+  children?: unknown[];
+};
+
+type NodeWithChildren = {
+  type?: string;
+  children?: unknown[];
+};
+
 const COMPONENT_PREVIEW_NAME = "ComponentPreview";
 const COMPONENT_PREVIEW_BLOCK_NAME = "ComponentPreviewBlock";
 const COMPONENT_PREVIEW_LANGUAGES = new Set(["jsx", "tsx", "mdx"]);
@@ -192,44 +203,83 @@ function readBooleanAttribute(
   return parseBooleanAttributeValue(attribute.value);
 }
 
-function parseComponentPreviewChildren(rawCode: string): unknown[] {
-  const parsedTree = fromMarkdown(rawCode, {
-    extensions: [gfm(), mdxjs()],
-    mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
-  }) as Root;
+function normalizePreviewHeadingDepth(depth: number | undefined): number {
+  if (depth === 1) return 2;
+  if (depth === 2 || depth === 3 || depth === 4 || depth === 5 || depth === 6) {
+    return depth;
+  }
+  return 2;
+}
 
-  const children = Array.isArray(parsedTree.children) ? parsedTree.children : [];
+function transformPreviewChildren(children: unknown[] | undefined): unknown[] {
+  if (!Array.isArray(children)) return [];
+  return children.map((child) => transformPreviewNode(child));
+}
 
+function transformPreviewNode(node: unknown): unknown {
   // Promote a single inline MDX JSX node into flow-level JSX so the preview
   // renders block components (e.g. <Callout />) as expected.
-  return children.map((node) => {
-    const paragraphNode = node as ParagraphNode;
-    if (
-      paragraphNode.type !== "paragraph" ||
-      !Array.isArray(paragraphNode.children) ||
-      paragraphNode.children.length !== 1
-    ) {
-      return node;
-    }
+  const headingNode = node as HeadingNode;
+  if (headingNode.type === "heading") {
+    const depth = normalizePreviewHeadingDepth(headingNode.depth);
+    return {
+      type: "mdxJsxFlowElement",
+      name: "div",
+      attributes: [
+        createAttribute("data-rd-preview-heading", "true"),
+        createAttribute("data-rd-preview-heading-level", String(depth)),
+        createAttribute("role", "heading"),
+        createAttribute("aria-level", String(depth)),
+      ],
+      children: transformPreviewChildren(headingNode.children),
+    };
+  }
 
+  const paragraphNode = node as ParagraphNode;
+  if (
+    paragraphNode.type === "paragraph" &&
+    Array.isArray(paragraphNode.children) &&
+    paragraphNode.children.length === 1
+  ) {
     const onlyChild = paragraphNode.children[0] as MdxJsxTextElementNode;
     if (
-      onlyChild.type !== "mdxJsxTextElement" ||
-      typeof onlyChild.name !== "string" ||
-      onlyChild.name.trim().length === 0
+      onlyChild.type === "mdxJsxTextElement" &&
+      typeof onlyChild.name === "string" &&
+      onlyChild.name.trim().length > 0
     ) {
-      return node;
+      return {
+        type: "mdxJsxFlowElement",
+        name: onlyChild.name,
+        attributes: Array.isArray(onlyChild.attributes)
+          ? onlyChild.attributes
+          : [],
+        children: transformPreviewChildren(onlyChild.children),
+      };
     }
+  }
 
+  const nodeWithChildren = node as NodeWithChildren;
+  if (Array.isArray(nodeWithChildren.children)) {
     return {
-      type: "mdxJsxFlowElement",
-      name: onlyChild.name,
-      attributes: Array.isArray(onlyChild.attributes)
-        ? onlyChild.attributes
-        : [],
-      children: Array.isArray(onlyChild.children) ? onlyChild.children : [],
+      ...nodeWithChildren,
+      children: transformPreviewChildren(nodeWithChildren.children),
     };
-  });
+  }
+
+  return node;
+}
+
+function parseComponentPreviewChildren(rawCode: string): unknown[] {
+  const parsedTree = fromMarkdown(rawCode, {
+    extensions: [gfm(), mdxjs()],
+    mdastExtensions: [gfmFromMarkdown(), mdxFromMarkdown()],
+  }) as Root;
+
+  transformCodeBlockNodes(parsedTree);
+
+  return transformPreviewChildren(
+    Array.isArray(parsedTree.children) ? parsedTree.children : [],
+  );
 }
 
 function getNearestMdxJsxFlowElementName(
@@ -274,135 +324,139 @@ function buildDefaultCodeGroupFileName(
   return `file-name-${codeIndexInGroup + 1}.${extension}`;
 }
 
-export const remarkCodeBlockComponent: Plugin<[], Root> = () => {
-  return (tree) => {
-    visitParents(tree, "code", (node, ancestors) => {
-      const codeNode = node as CodeNode;
-      const parent = ancestors[ancestors.length - 1] as ParentNode | undefined;
-      const siblings = parent?.children;
-      if (!siblings) return;
+function transformCodeBlockNodes(tree: Root): void {
+  visitParents(tree, "code", (node, ancestors) => {
+    const codeNode = node as CodeNode;
+    const parent = ancestors[ancestors.length - 1] as ParentNode | undefined;
+    const siblings = parent?.children;
+    if (!siblings) return;
+
+    const currentIndex = siblings.indexOf(node);
+    if (currentIndex < 0) return;
+
+    const nearestMdxFlowElementName = getNearestMdxJsxFlowElementName(
+      ancestors,
+    );
+    const isInsideCodeGroup = nearestMdxFlowElementName === "CodeGroup";
+    const isInsideComponentPreview =
+      nearestMdxFlowElementName === COMPONENT_PREVIEW_NAME;
+    const componentPreviewNode = isInsideComponentPreview
+      ? getNearestMdxJsxFlowElement(ancestors, COMPONENT_PREVIEW_NAME)
+      : null;
+    const isInsideInlineMdx = isInsideMdxJsxTextElement(ancestors);
+    if (isInsideInlineMdx) return;
+
+    const meta = readMetaString(codeNode.meta);
+    const parsedMeta = parseParsedCodeMeta(meta);
+    const language =
+      typeof codeNode.lang === "string" && codeNode.lang.trim().length > 0
+        ? codeNode.lang.trim()
+        : "plaintext";
+    const normalizedLanguage = language.trim().toLowerCase();
+    const rawCode = typeof codeNode.value === "string" ? codeNode.value : "";
+    const codeIndexInGroup = isInsideCodeGroup
+      ? siblings
+          .slice(0, currentIndex)
+          .filter(
+            (sibling) => (sibling as { type?: string }).type === "code",
+          ).length
+      : 0;
+    const fileName =
+      parsedMeta.filename.length > 0
+        ? parsedMeta.filename
+        : isInsideCodeGroup
+          ? buildDefaultCodeGroupFileName(language, codeIndexInGroup)
+          : "";
+    const showFilename = isInsideCodeGroup || fileName.length > 0;
+
+    const attributes: MdxJsxAttributeNode[] = [
+      createAttribute("language", language),
+      createAttribute("raw", rawCode),
+      createAttribute("showFilename", showFilename ? "true" : "false"),
+      createAttribute(
+        "showLineNumbers",
+        parsedMeta.showLineNumbers ? "true" : "false",
+      ),
+    ];
+
+    if (parsedMeta.hideLanguageIcon) {
+      attributes.push(createAttribute("hideLanguageIcon", "true"));
+    }
 
-      const currentIndex = siblings.indexOf(node);
-      if (currentIndex < 0) return;
+    if (showFilename) {
+      attributes.push(createAttribute("filename", fileName));
+    }
 
-      const nearestMdxFlowElementName = getNearestMdxJsxFlowElementName(
-        ancestors,
-      );
-      const isInsideCodeGroup = nearestMdxFlowElementName === "CodeGroup";
-      const isInsideComponentPreview =
-        nearestMdxFlowElementName === COMPONENT_PREVIEW_NAME;
-      const componentPreviewNode = isInsideComponentPreview
-        ? getNearestMdxJsxFlowElement(ancestors, COMPONENT_PREVIEW_NAME)
-        : null;
-      const isInsideInlineMdx = isInsideMdxJsxTextElement(ancestors);
-      if (isInsideInlineMdx) return;
-
-      const meta = readMetaString(codeNode.meta);
-      const parsedMeta = parseParsedCodeMeta(meta);
-      const language =
-        typeof codeNode.lang === "string" && codeNode.lang.trim().length > 0
-          ? codeNode.lang.trim()
-          : "plaintext";
-      const normalizedLanguage = language.trim().toLowerCase();
-      const rawCode = typeof codeNode.value === "string" ? codeNode.value : "";
-      const codeIndexInGroup = isInsideCodeGroup
-        ? siblings
-            .slice(0, currentIndex)
-            .filter(
-              (sibling) => (sibling as { type?: string }).type === "code",
-            ).length
-        : 0;
-      const fileName =
-        parsedMeta.filename.length > 0
-          ? parsedMeta.filename
-          : isInsideCodeGroup
-            ? buildDefaultCodeGroupFileName(language, codeIndexInGroup)
-            : "";
-      const showFilename = isInsideCodeGroup || fileName.length > 0;
-
-      const attributes: MdxJsxAttributeNode[] = [
-        createAttribute("language", language),
-        createAttribute("raw", rawCode),
-        createAttribute("showFilename", showFilename ? "true" : "false"),
-        createAttribute(
-          "showLineNumbers",
-          parsedMeta.showLineNumbers ? "true" : "false",
-        ),
-      ];
-
-      if (parsedMeta.hideLanguageIcon) {
-        attributes.push(createAttribute("hideLanguageIcon", "true"));
-      }
+    if (isInsideCodeGroup) {
+      attributes.push(createAttribute("inCodeGroup", "true"));
+    }
 
-      if (showFilename) {
-        attributes.push(createAttribute("filename", fileName));
-      }
+    if (parsedMeta.highlightedLines.length > 0) {
+      attributes.push(
+        createAttribute("highlightedLines", parsedMeta.highlightedLines),
+      );
+    }
 
-      if (isInsideCodeGroup) {
-        attributes.push(createAttribute("inCodeGroup", "true"));
-      }
+    if (parsedMeta.collapsedLines.length > 0) {
+      attributes.push(
+        createAttribute("collapsedLines", parsedMeta.collapsedLines),
+      );
+    }
 
-      if (parsedMeta.highlightedLines.length > 0) {
-        attributes.push(
-          createAttribute("highlightedLines", parsedMeta.highlightedLines),
+    if (isInsideComponentPreview) {
+      if (!COMPONENT_PREVIEW_LANGUAGES.has(normalizedLanguage)) {
+        throw new Error(
+          `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Fenced code blocks must use jsx, tsx, or mdx language (received "${language}")`,
         );
       }
 
-      if (parsedMeta.collapsedLines.length > 0) {
-        attributes.push(
-          createAttribute("collapsedLines", parsedMeta.collapsedLines),
+      let previewChildren: unknown[] = [];
+      try {
+        previewChildren = parseComponentPreviewChildren(rawCode);
+      } catch (error) {
+        const reason =
+          error instanceof Error && error.message.trim().length > 0
+            ? ` -> ${error.message}`
+            : "";
+        throw new Error(
+          `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Failed to parse fenced code block as MDX content${reason}`,
         );
       }
 
-      if (isInsideComponentPreview) {
-        if (!COMPONENT_PREVIEW_LANGUAGES.has(normalizedLanguage)) {
-          throw new Error(
-            `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Fenced code blocks must use jsx, tsx, or mdx language (received "${language}")`,
-          );
-        }
-
-        let previewChildren: unknown[] = [];
-        try {
-          previewChildren = parseComponentPreviewChildren(rawCode);
-        } catch (error) {
-          const reason =
-            error instanceof Error && error.message.trim().length > 0
-              ? ` -> ${error.message}`
-              : "";
-          throw new Error(
-            `[USER_ERROR]: <${COMPONENT_PREVIEW_NAME}>: Failed to parse fenced code block as MDX content${reason}`,
-          );
-        }
-
-        const previewAttributes = attributes.filter(
-          (attribute) => attribute.name !== "inCodeGroup",
-        );
-        const showAllCode = readBooleanAttribute(
-          componentPreviewNode?.attributes,
-          "showAllCode",
-        );
-        if (showAllCode) {
-          previewAttributes.push(createAttribute("showAllCode", "true"));
-        }
-        const previewNode: MdxJsxFlowElementNode = {
-          type: "mdxJsxFlowElement",
-          name: COMPONENT_PREVIEW_BLOCK_NAME,
-          attributes: previewAttributes,
-          children: previewChildren,
-        };
-        siblings[currentIndex] = previewNode;
-        return;
+      const previewAttributes = attributes.filter(
+        (attribute) => attribute.name !== "inCodeGroup",
+      );
+      const showAllCode = readBooleanAttribute(
+        componentPreviewNode?.attributes,
+        "showAllCode",
+      );
+      if (showAllCode) {
+        previewAttributes.push(createAttribute("showAllCode", "true"));
       }
-
-      const replacementNode: MdxJsxFlowElementNode = {
+      const previewNode: MdxJsxFlowElementNode = {
         type: "mdxJsxFlowElement",
-        name: INTERNAL_CODE_BLOCK_NAME,
-        attributes,
-        children: [],
+        name: COMPONENT_PREVIEW_BLOCK_NAME,
+        attributes: previewAttributes,
+        children: previewChildren,
       };
+      siblings[currentIndex] = previewNode;
+      return;
+    }
 
-      siblings[currentIndex] = replacementNode;
-    });
+    const replacementNode: MdxJsxFlowElementNode = {
+      type: "mdxJsxFlowElement",
+      name: INTERNAL_CODE_BLOCK_NAME,
+      attributes,
+      children: [],
+    };
+
+    siblings[currentIndex] = replacementNode;
+  });
+}
+
+export const remarkCodeBlockComponent: Plugin<[], Root> = () => {
+  return (tree) => {
+    transformCodeBlockNodes(tree);
   };
 };
 

package/template/src/styles/global.css

@@ -145,6 +145,15 @@
   @apply px-1 py-px bg-neutral-100/90 text-neutral-600 rounded-md font-mono font-medium border border-neutral-200/80 after:hidden before:hidden;
 }
 
+/* Keep nested blockquote content flush with the quote container edges */
+:is(.prose, .prose-rules) blockquote > :first-child {
+  margin-top: 0;
+}
+
+:is(.prose, .prose-rules) blockquote > :last-child {
+  margin-bottom: 0;
+}
+
 /* <ol> numbers */
 .prose :where(ol > li)::marker {
   @apply font-medium;