@izumisy/md-react-preview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IzumiSy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @izumisy/md-react-preview
+
+CLI and programmatic API for md-react-preview — a zero-config component previewer for React projects.
+
+Drop Markdown files into `docs/` with `` ```tsx preview `` fenced blocks and get a Vite-powered dev server with live component previews and syntax-highlighted source code.
+
+## Install
+
+```bash
+pnpm add -D @izumisy/md-react-preview
+```
+
+## CLI
+
+```bash
+npx mrp dev       # Start dev server (default port 3040)
+npx mrp build     # Build static output
+npx mrp preview   # Preview the production build locally
+```
+
+## Writing Previews
+
+Create a Markdown file under `docs/`:
+
+````md
+---
+title: Button
+description: A versatile button component.
+---
+
+## Default
+
+```tsx preview
+import { Button } from "./Button"
+
+<Button variant="default">Click me</Button>
+```
+````
+
+Each `` ```tsx preview `` block is rendered as a live component alongside collapsible, syntax-highlighted source code. Previews run in isolated iframes so host styles never leak.
+
+### Preview Modes
+
+| Mode | Syntax | Behavior |
+|------|--------|----------|
+| **inline** (default) | `` ```tsx preview `` | Rendered inline within the page |
+| **standalone** | `` ```tsx preview standalone `` | Rendered in a dedicated full-viewport page at `/__preview/{blockId}` |
+
+Standalone mode is useful for portal/overlay components (Dropdown, Sheet, Dialog) and full-page layouts that need the entire viewport.
+
+### Block Options
+
+Options can be set as `key="value"` pairs or boolean flags in the fence meta:
+
+````md
+```tsx preview wrap="row" height="200"
+<Button>A</Button>
+<Button>B</Button>
+```
+````
+
+| Option | Description |
+|--------|-------------|
+| `wrap` | Layout mode: `"row"` (horizontal with gap) or `"column"` (vertical with gap) |
+| `height` | Fixed iframe height (e.g. `"200"`) |
+| `standalone` | Boolean flag — render in a separate full-viewport page |
+
+### Frontmatter
+
+| Field | Description |
+|-------|-------------|
+| `title` | Display name in the sidebar and page header |
+| `description` | Short description shown below the title |
+
+## Configuration
+
+Create a `mrp.config.ts` at your project root:
+
+```ts
+import { defineConfig } from "@izumisy/md-react-preview";
+
+export default defineConfig({
+  title: "My Component Library",
+  glob: "docs/**/*.md",              // default
+  previewCss: "./src/globals.css",   // optional
+  vite: {
+    plugins: [],                     // extra Vite plugins
+  },
+});
+```
+
+| Option | Description |
+|--------|-------------|
+| `title` | Sidebar header and HTML `<title>` |
+| `glob` | Glob pattern for Markdown files (default `docs/**/*.md`) |
+| `previewCss` | CSS file imported into preview blocks (e.g. your design system's stylesheet) |
+| `vite.plugins` | Additional Vite plugins (e.g. `@tailwindcss/vite`) |
+
+## Programmatic API
+
+```ts
+import { startDev, runBuild, defineConfig, createPreviewerViteConfig } from "@izumisy/md-react-preview";
+```
+
+| Export | Description |
+|--------|-------------|
+| `defineConfig(config)` | Type helper for `mrp.config.ts` |
+| `startDev(options)` | Start the Vite dev server |
+| `runBuild(options)` | Run the production build |
+| `runPreview(options)` | Preview the production build |
+| `createPreviewerViteConfig(options)` | Generate the Vite `InlineConfig` used internally |
+| `extractPreviewBlocks(source)` | Parse `` ```tsx preview `` blocks from a Markdown string |
+
+## License
+
+MIT

package/app/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>md-react-preview</title>
+    <style>
+      *, *::before, *::after { box-sizing: border-box; margin: 0; }
+      html, html.light {
+        --ms-bg: #ffffff;
+        --ms-fg: #1a1a1a;
+        --ms-fg-muted: #888888;
+        --ms-border: #e5e5e5;
+        --ms-sidebar-active: #f0f0f0;
+        --ms-code-bg: #f5f5f5;
+      }
+      html.dark {
+        --ms-bg: #1a1a1a;
+        --ms-fg: #e5e5e5;
+        --ms-fg-muted: #777777;
+        --ms-border: #333333;
+        --ms-sidebar-active: #2a2a2a;
+        --ms-code-bg: #2a2a2a;
+      }
+      @media (prefers-color-scheme: dark) {
+        html:not(.light) {
+          --ms-bg: #1a1a1a;
+          --ms-fg: #e5e5e5;
+          --ms-fg-muted: #777777;
+          --ms-border: #333333;
+          --ms-sidebar-active: #2a2a2a;
+          --ms-code-bg: #2a2a2a;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/app/src/app.tsx

@@ -0,0 +1,219 @@
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { MDXProvider } from "@mdx-js/react";
+import { entries, type PreviewEntry } from "virtual:previewer-entries";
+import { mdxComponents } from "./mdx-components";
+import { ThemeProvider, useTheme } from "./theme";
+
+const title: string = __PREVIEWER_TITLE__;
+
+function getPathname() {
+  return decodeURIComponent(window.location.pathname).replace(/^\//, "");
+}
+
+function usePathname() {
+  const subscribe = useCallback((cb: () => void) => {
+    window.addEventListener("popstate", cb);
+    return () => window.removeEventListener("popstate", cb);
+  }, []);
+  return useSyncExternalStore(subscribe, getPathname);
+}
+
+function Sidebar({
+  entries: items,
+  selected,
+  onSelect,
+}: {
+  entries: PreviewEntry[];
+  selected: string | null;
+  onSelect: (name: string) => void;
+}) {
+  return (
+    <nav
+      style={{
+        width: 220,
+        borderRight: "1px solid var(--ms-border)",
+        padding: "12px 0",
+        overflowY: "auto",
+        flexShrink: 0,
+      }}
+    >
+      {items.map((entry) => (
+        <button
+          key={entry.name}
+          onClick={() => onSelect(entry.name)}
+          style={{
+            display: "block",
+            width: "100%",
+            textAlign: "left",
+            padding: "6px 16px",
+            fontSize: 14,
+            border: "none",
+            cursor: "pointer",
+            backgroundColor: selected === entry.name ? "var(--ms-sidebar-active)" : "transparent",
+            fontWeight: selected === entry.name ? 600 : 400,
+            color: "var(--ms-fg)",
+            fontFamily: "inherit",
+          }}
+        >
+          {entry.name}
+        </button>
+      ))}
+    </nav>
+  );
+}
+
+function PreviewContent({ entry }: { entry: PreviewEntry }) {
+  const { Component } = entry;
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    scrollRef.current?.scrollTo(0, 0);
+  }, [entry.name]);
+
+  return (
+    <div
+      ref={scrollRef}
+      style={{
+        flex: 1,
+        overflowY: "auto",
+        scrollbarWidth: "none",
+      }}
+    >
+      <div
+        style={{
+          maxWidth: 860,
+          margin: "0 auto",
+          padding: "24px 40px 80px",
+        }}
+      >
+        <Component />
+      </div>
+    </div>
+  );
+}
+
+function Header() {
+  const { colorScheme, toggle } = useTheme();
+  return (
+    <header
+      style={{
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        padding: "0 20px",
+        height: 48,
+        borderBottom: "1px solid var(--ms-border)",
+        flexShrink: 0,
+      }}
+    >
+      <span style={{ fontSize: 15, fontWeight: 700 }}>{title}</span>
+      <button
+        onClick={toggle}
+        aria-label={`Switch to ${colorScheme === "light" ? "dark" : "light"} theme`}
+        style={{
+          background: "none",
+          border: "none",
+          cursor: "pointer",
+          padding: 4,
+          color: "var(--ms-fg)",
+          display: "flex",
+          alignItems: "center",
+        }}
+      >
+        {colorScheme === "light" ? (
+          <svg
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+          </svg>
+        ) : (
+          <svg
+            width="18"
+            height="18"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          >
+            <circle cx="12" cy="12" r="5" />
+            <line x1="12" y1="1" x2="12" y2="3" />
+            <line x1="12" y1="21" x2="12" y2="23" />
+            <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+            <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+            <line x1="1" y1="12" x2="3" y2="12" />
+            <line x1="21" y1="12" x2="23" y2="12" />
+            <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+            <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+          </svg>
+        )}
+      </button>
+    </header>
+  );
+}
+
+export function App() {
+  const pathname = usePathname();
+  const selected = pathname || entries[0]?.name || null;
+  const current = entries.find((e: PreviewEntry) => e.name === selected);
+
+  // Redirect bare "/" to the first entry's path
+  useEffect(() => {
+    if (!pathname && entries[0]) {
+      history.replaceState(null, "", `/${encodeURIComponent(entries[0].name)}`);
+    }
+  }, [pathname]);
+
+  const setSelected = useCallback((name: string) => {
+    history.pushState(null, "", `/${encodeURIComponent(name)}`);
+    // pushState doesn't fire popstate, so dispatch one manually to trigger re-render
+    window.dispatchEvent(new PopStateEvent("popstate"));
+  }, []);
+
+  return (
+    <ThemeProvider>
+      <MDXProvider components={mdxComponents}>
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            height: "100vh",
+            fontFamily: "system-ui, sans-serif",
+            backgroundColor: "var(--ms-bg)",
+            color: "var(--ms-fg)",
+          }}
+        >
+          <Header />
+          <div style={{ display: "flex", flex: 1, overflow: "hidden" }}>
+            <Sidebar entries={entries} selected={selected} onSelect={setSelected} />
+            {current ? (
+              <PreviewContent entry={current} />
+            ) : (
+              <div
+                style={{
+                  flex: 1,
+                  display: "flex",
+                  alignItems: "center",
+                  justifyContent: "center",
+                  color: "var(--ms-fg-muted)",
+                }}
+              >
+                {entries.length === 0
+                  ? "No .md files found."
+                  : "Select a component from the sidebar."}
+              </div>
+            )}
+          </div>
+        </div>
+      </MDXProvider>
+    </ThemeProvider>
+  );
+}

package/app/src/code-block.tsx

@@ -0,0 +1,182 @@
+import { useCallback, useEffect, useState } from "react";
+import { createHighlighterCore, type HighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+import { useTheme } from "./theme";
+
+let highlighterPromise: Promise<HighlighterCore> | undefined;
+
+function getHighlighter(): Promise<HighlighterCore> {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighterCore({
+      themes: [import("@shikijs/themes/github-dark"), import("@shikijs/themes/github-light")],
+      langs: [
+        import("@shikijs/langs/tsx"),
+        import("@shikijs/langs/jsx"),
+        import("@shikijs/langs/typescript"),
+        import("@shikijs/langs/javascript"),
+        import("@shikijs/langs/css"),
+        import("@shikijs/langs/html"),
+        import("@shikijs/langs/json"),
+        import("@shikijs/langs/shellscript"),
+      ],
+      engine: createJavaScriptRegexEngine(),
+    });
+  }
+  return highlighterPromise;
+}
+
+function CopyButton({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(() => {
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  }, [text]);
+
+  return (
+    <button
+      onClick={handleCopy}
+      aria-label="Copy code"
+      style={{
+        position: "absolute",
+        top: 6,
+        right: 6,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: 24,
+        height: 24,
+        border: "1px solid var(--ms-border)",
+        borderRadius: 4,
+        backgroundColor: "var(--ms-bg)",
+        cursor: "pointer",
+        color: "var(--ms-fg-muted)",
+        opacity: 0.6,
+        transition: "opacity 0.15s",
+      }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.opacity = "1";
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.opacity = "0.6";
+      }}
+    >
+      {copied ? (
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 16 16"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M13.25 4.75l-6.5 6.5-3.5-3.5" />
+        </svg>
+      ) : (
+        <svg
+          width="14"
+          height="14"
+          viewBox="0 0 16 16"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <rect x="5.5" y="5.5" width="8" height="8" rx="1.5" />
+          <path d="M10.5 5.5V3a1.5 1.5 0 00-1.5-1.5H3A1.5 1.5 0 001.5 3v6A1.5 1.5 0 003 10.5h2.5" />
+        </svg>
+      )}
+    </button>
+  );
+}
+
+export function CodeBlock({
+  children,
+  className,
+  noBorderRadius,
+}: {
+  children: string;
+  className?: string;
+  noBorderRadius?: boolean;
+}) {
+  const lang = className?.replace("language-", "") ?? "";
+  const radius = noBorderRadius ? 0 : 8;
+  const border = noBorderRadius ? "none" : "1px solid var(--ms-border)";
+  const { colorScheme } = useTheme();
+  const [html, setHtml] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!lang) return;
+    let cancelled = false;
+    getHighlighter()
+      .then(async (highlighter) => {
+        if (!highlighter.getLoadedLanguages().includes(lang)) {
+          // Language not pre-loaded – fall back to plain text
+          return null;
+        }
+        return highlighter.codeToHtml(children, {
+          lang,
+          theme: colorScheme === "dark" ? "github-dark" : "github-light",
+          transformers: [
+            {
+              pre(node) {
+                node.properties.style = "margin:0;padding:10px";
+              },
+            },
+          ],
+        });
+      })
+      .then((result) => {
+        if (!cancelled && result) setHtml(result);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [children, lang, colorScheme]);
+
+  if (html) {
+    return (
+      <div
+        style={{
+          position: "relative",
+          background: "var(--ms-code-bg)",
+          borderRadius: radius,
+          overflowX: "auto",
+          overflowY: "hidden",
+          fontSize: 13,
+          lineHeight: 1.5,
+          border,
+        }}
+      >
+        <CopyButton text={children} />
+        <div dangerouslySetInnerHTML={{ __html: html }} />
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ position: "relative" }}>
+      <CopyButton text={children} />
+      <pre
+        style={{
+          background: "var(--ms-code-bg)",
+          padding: 10,
+          borderRadius: radius,
+          overflowX: "auto",
+          overflowY: "hidden",
+          fontSize: 13,
+          lineHeight: 1.5,
+          border,
+          margin: 0,
+        }}
+      >
+        <code data-language={lang}>{children}</code>
+      </pre>
+    </div>
+  );
+}

package/app/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/app/src/mdx-components.tsx

@@ -0,0 +1,103 @@
+import { type ReactNode, Children } from "react";
+import { CodeBlock } from "./code-block";
+import { PreviewBlock } from "./preview-block";
+
+function slugify(children: ReactNode): string {
+  const text = Children.toArray(children)
+    .map((child) => (typeof child === "string" ? child : ""))
+    .join("");
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\u3000-\u9fff]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export const mdxComponents = {
+  h1: ({ children }: { children?: ReactNode }) => (
+    <h1 style={{ fontSize: 28, fontWeight: 700, margin: "0 0 16px" }}>{children}</h1>
+  ),
+  h2: ({ children }: { children?: ReactNode }) => {
+    const id = slugify(children);
+    return (
+      <h2
+        id={id}
+        style={{
+          fontSize: 20,
+          fontWeight: 600,
+          margin: "24px 0 12px",
+          borderBottom: "1px solid var(--ms-border)",
+          paddingBottom: 8,
+        }}
+      >
+        {children}
+      </h2>
+    );
+  },
+  h3: ({ children }: { children?: ReactNode }) => {
+    const id = slugify(children);
+    return (
+      <h3 id={id} style={{ fontSize: 16, fontWeight: 600, margin: "20px 0 8px" }}>
+        {children}
+      </h3>
+    );
+  },
+  p: ({ children }: { children?: ReactNode }) => (
+    <p style={{ margin: "8px 0", lineHeight: 1.6 }}>{children}</p>
+  ),
+  pre: ({
+    children,
+  }: {
+    children?: React.ReactElement<{ children?: string; className?: string }>;
+  }) => {
+    const code = children?.props?.children ?? "";
+    const className = children?.props?.className ?? "";
+    return <CodeBlock className={className}>{code}</CodeBlock>;
+  },
+  table: ({ children }: { children?: ReactNode }) => (
+    <table
+      style={{
+        borderCollapse: "collapse",
+        width: "100%",
+        margin: "16px 0",
+        fontSize: 14,
+      }}
+    >
+      {children}
+    </table>
+  ),
+  thead: ({ children }: { children?: ReactNode }) => <thead>{children}</thead>,
+  tbody: ({ children }: { children?: ReactNode }) => <tbody>{children}</tbody>,
+  tr: ({ children }: { children?: ReactNode }) => (
+    <tr style={{ borderBottom: "1px solid var(--ms-border)" }}>{children}</tr>
+  ),
+  th: ({ children }: { children?: ReactNode }) => (
+    <th
+      style={{
+        background: "var(--ms-code-bg)",
+        padding: "8px 12px",
+        textAlign: "left" as const,
+        borderBottom: "2px solid var(--ms-border)",
+        fontWeight: 600,
+      }}
+    >
+      {children}
+    </th>
+  ),
+  td: ({ children }: { children?: ReactNode }) => (
+    <td style={{ padding: "8px 12px", verticalAlign: "top" as const }}>{children}</td>
+  ),
+  code: ({ children }: { children?: ReactNode }) => (
+    <code
+      style={{
+        background: "var(--ms-code-bg)",
+        padding: "2px 6px",
+        borderRadius: 4,
+        fontSize: 13,
+        fontFamily: "monospace",
+      }}
+    >
+      {children}
+    </code>
+  ),
+  PreviewBlock,
+};