flowbook 0.1.0

package/src/client/components/MermaidRenderer.tsx

@@ -0,0 +1,104 @@
+import { useEffect, useRef, useState, useId } from "react";
+import mermaid from "mermaid";
+
+let initialized = false;
+
+function ensureInit() {
+  if (initialized) return;
+  mermaid.initialize({
+    startOnLoad: false,
+    theme: "dark",
+    securityLevel: "loose",
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, monospace",
+    themeVariables: {
+      darkMode: true,
+      background: "#18181b",
+      mainBkg: "#27272a",
+      primaryColor: "#7c3aed",
+      primaryTextColor: "#f4f4f5",
+      primaryBorderColor: "#6d28d9",
+      secondaryColor: "#3f3f46",
+      secondaryTextColor: "#d4d4d8",
+      secondaryBorderColor: "#52525b",
+      tertiaryColor: "#27272a",
+      tertiaryTextColor: "#a1a1aa",
+      tertiaryBorderColor: "#3f3f46",
+      lineColor: "#71717a",
+      textColor: "#e4e4e7",
+      nodeTextColor: "#f4f4f5",
+    },
+  });
+  initialized = true;
+}
+
+interface Props {
+  code: string;
+  className?: string;
+}
+
+export function MermaidRenderer({ code, className }: Props) {
+  const [svg, setSvg] = useState("");
+  const [error, setError] = useState("");
+  const containerRef = useRef<HTMLDivElement>(null);
+  const rawId = useId();
+  const safeId = "mermaid" + rawId.replace(/:/g, "-");
+
+  useEffect(() => {
+    ensureInit();
+
+    let cancelled = false;
+
+    mermaid
+      .render(safeId, code)
+      .then(({ svg: rendered }) => {
+        if (!cancelled) {
+          setSvg(rendered);
+          setError("");
+        }
+      })
+      .catch((err: Error) => {
+        if (!cancelled) {
+          setError(err.message ?? "Failed to render diagram");
+          setSvg("");
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [code, safeId]);
+
+  if (error) {
+    return (
+      <div
+        className={`bg-red-500/10 border border-red-500/20 rounded-lg p-4 ${className ?? ""}`}
+      >
+        <p className="text-red-400 text-sm font-medium mb-2">
+          Render error
+        </p>
+        <p className="text-red-300/70 text-xs font-mono mb-3">{error}</p>
+        <pre className="text-xs text-zinc-500 overflow-x-auto whitespace-pre-wrap">
+          {code}
+        </pre>
+      </div>
+    );
+  }
+
+  if (!svg) {
+    return (
+      <div
+        className={`flex items-center justify-center py-12 ${className ?? ""}`}
+      >
+        <div className="w-5 h-5 border-2 border-violet-500/30 border-t-violet-500 rounded-full animate-spin" />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={`flowbook-mermaid overflow-x-auto ${className ?? ""}`}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/src/client/components/Sidebar.tsx

@@ -0,0 +1,88 @@
+import { useMemo, useState } from "react";
+import type { FlowEntry } from "../../types";
+
+interface SidebarProps {
+  flows: FlowEntry[];
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+}
+
+export function Sidebar({ flows, selectedId, onSelect }: SidebarProps) {
+  const [collapsedCategories, setCollapsedCategories] = useState<Set<string>>(
+    new Set(),
+  );
+
+  const categories = useMemo(() => {
+    const map = new Map<string, FlowEntry[]>();
+    for (const flow of flows) {
+      const cat = flow.category;
+      if (!map.has(cat)) map.set(cat, []);
+      map.get(cat)!.push(flow);
+    }
+    return Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
+  }, [flows]);
+
+  function toggleCategory(cat: string) {
+    setCollapsedCategories((prev) => {
+      const next = new Set(prev);
+      if (next.has(cat)) next.delete(cat);
+      else next.add(cat);
+      return next;
+    });
+  }
+
+  return (
+    <aside className="w-64 border-r border-zinc-800 overflow-y-auto shrink-0 bg-zinc-950/50">
+      <nav className="p-3 space-y-1">
+        {categories.map(([category, items]) => {
+          const isCollapsed = collapsedCategories.has(category);
+
+          return (
+            <div key={category}>
+              <button
+                onClick={() => toggleCategory(category)}
+                className="w-full flex items-center gap-1.5 px-2 py-1.5 text-xs font-semibold text-zinc-400 uppercase tracking-wider hover:text-zinc-300 transition-colors"
+              >
+                <svg
+                  className={`w-3 h-3 transition-transform ${isCollapsed ? "" : "rotate-90"}`}
+                  viewBox="0 0 24 24"
+                  fill="currentColor"
+                >
+                  <path d="M8 5l8 7-8 7z" />
+                </svg>
+                {category}
+                <span className="ml-auto text-zinc-600 font-normal normal-case">
+                  {items.length}
+                </span>
+              </button>
+              {!isCollapsed && (
+                <ul className="ml-2 space-y-0.5">
+                  {items.map((flow) => (
+                    <li key={flow.id}>
+                      <button
+                        onClick={() => onSelect(flow.id)}
+                        className={`w-full text-left px-3 py-1.5 rounded-md text-sm transition-colors truncate ${
+                          selectedId === flow.id
+                            ? "bg-violet-500/15 text-violet-300 font-medium"
+                            : "text-zinc-400 hover:bg-zinc-800/60 hover:text-zinc-200"
+                        }`}
+                        title={flow.title}
+                      >
+                        {flow.title}
+                      </button>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          );
+        })}
+        {categories.length === 0 && (
+          <p className="text-sm text-zinc-600 px-2 py-4 text-center">
+            No flows match your search
+          </p>
+        )}
+      </nav>
+    </aside>
+  );
+}

package/src/client/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📊</text></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Flowbook</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/src/client/main.tsx

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

package/src/client/styles/globals.css

@@ -0,0 +1,39 @@
+@import "tailwindcss";
+
+:root {
+  color-scheme: dark;
+}
+
+body {
+  margin: 0;
+  font-family:
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+    Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Mermaid SVG sizing */
+.flowbook-mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #3f3f46;
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #52525b;
+}

package/src/client/vite-env.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="vite/client" />
+
+declare module "virtual:flowbook-data" {
+  interface FlowEntry {
+    id: string;
+    title: string;
+    category: string;
+    tags: string[];
+    description: string;
+    order: number;
+    filePath: string;
+    mermaidBlocks: string[];
+  }
+
+  interface FlowbookData {
+    flows: FlowEntry[];
+  }
+
+  const data: FlowbookData;
+  export default data;
+}

package/src/node/cli.ts

@@ -0,0 +1,59 @@
+import { initFlowbook } from "./init";
+import { startDevServer, buildStatic } from "./server";
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  switch (command) {
+    case "init":
+      await initFlowbook();
+      break;
+
+    case "dev": {
+      const port = Number(getFlag(args, "--port", "6200"));
+      await startDevServer({ port });
+      break;
+    }
+
+    case "build": {
+      const outDir = String(getFlag(args, "--out-dir", "flowbook-static"));
+      await buildStatic({ outDir });
+      break;
+    }
+
+    default:
+      printUsage();
+      break;
+  }
+}
+
+function getFlag(
+  args: string[],
+  flag: string,
+  fallback: string,
+): string {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return fallback;
+  return args[idx + 1];
+}
+
+function printUsage() {
+  console.log(`
+  flowbook — Storybook for flowcharts
+
+  Usage:
+    flowbook init                Set up Flowbook in your project
+    flowbook dev  [--port 6200]  Start the dev server
+    flowbook build [--out-dir d] Build a static site
+
+  Options:
+    --port <number>    Dev server port (default: 6200)
+    --out-dir <path>   Build output directory (default: flowbook-static)
+`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/node/discovery.ts

@@ -0,0 +1,16 @@
+import fg from "fast-glob";
+import type { FlowbookPluginOptions } from "../types";
+
+export async function discoverFlowFiles(
+  options: FlowbookPluginOptions,
+): Promise<string[]> {
+  const patterns = options.include ?? ["**/*.flow.md", "**/*.flowchart.md"];
+  const ignore = options.ignore ?? [
+    "node_modules/**",
+    ".git/**",
+    "dist/**",
+  ];
+  const cwd = options.cwd ?? process.cwd();
+
+  return fg(patterns, { cwd, ignore, absolute: true });
+}

package/src/node/init.ts

@@ -0,0 +1,71 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+const EXAMPLE_FLOW = `---
+title: Example Flow
+category: Getting Started
+tags: [example]
+order: 1
+description: An example flowchart to get you started
+---
+
+\`\`\`mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action A]
+    B -->|No| D[Action B]
+    C --> E[End]
+    D --> E
+\`\`\`
+`;
+
+export async function initFlowbook() {
+  const cwd = process.cwd();
+  const pkgPath = resolve(cwd, "package.json");
+
+  if (!existsSync(pkgPath)) {
+    console.error("  No package.json found. Run 'npm init' first.");
+    process.exit(1);
+  }
+
+  // 1. Add scripts to package.json
+  const raw = readFileSync(pkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  pkg.scripts = pkg.scripts ?? {};
+
+  let scriptsAdded = false;
+
+  if (!pkg.scripts.flowbook) {
+    pkg.scripts.flowbook = "flowbook dev";
+    scriptsAdded = true;
+  }
+  if (!pkg.scripts["build-flowbook"]) {
+    pkg.scripts["build-flowbook"] = "flowbook build";
+    scriptsAdded = true;
+  }
+
+  if (scriptsAdded) {
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log('  ✓ Added "flowbook" and "build-flowbook" scripts to package.json');
+  } else {
+    console.log("  ✓ Scripts already exist in package.json");
+  }
+
+  // 2. Create example flow file
+  const flowsDir = resolve(cwd, "flows");
+  const examplePath = resolve(flowsDir, "example.flow.md");
+
+  if (!existsSync(examplePath)) {
+    mkdirSync(flowsDir, { recursive: true });
+    writeFileSync(examplePath, EXAMPLE_FLOW);
+    console.log("  ✓ Created flows/example.flow.md");
+  } else {
+    console.log("  ✓ Example flow already exists");
+  }
+
+  console.log("");
+  console.log("  Next steps:");
+  console.log("    npm run flowbook       Start the dev server");
+  console.log("    npm run build-flowbook  Build static site");
+  console.log("");
+}

package/src/node/parser.ts

@@ -0,0 +1,41 @@
+import matter from "gray-matter";
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import type { FlowEntry } from "../types";
+
+const MERMAID_BLOCK_RE = /```mermaid\n([\s\S]*?)```/g;
+
+export function parseFlowFile(filePath: string, cwd: string): FlowEntry {
+  const raw = readFileSync(filePath, "utf-8");
+  const { data, content } = matter(raw);
+
+  const mermaidBlocks: string[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = MERMAID_BLOCK_RE.exec(content)) !== null) {
+    mermaidBlocks.push(match[1].trim());
+  }
+  // Reset regex lastIndex for next call
+  MERMAID_BLOCK_RE.lastIndex = 0;
+
+  const relPath = relative(cwd, filePath);
+  const id = relPath
+    .replace(/[/\\]/g, "-")
+    .replace(/\.flow(chart)?\.md$/, "");
+
+  const fileName = relPath
+    .replace(/\.flow(chart)?\.md$/, "")
+    .split("/")
+    .pop();
+
+  return {
+    id,
+    title: typeof data.title === "string" ? data.title : fileName ?? "Untitled",
+    category:
+      typeof data.category === "string" ? data.category : "Uncategorized",
+    tags: Array.isArray(data.tags) ? data.tags : [],
+    description: typeof data.description === "string" ? data.description : "",
+    order: typeof data.order === "number" ? data.order : 999,
+    filePath: relPath,
+    mermaidBlocks,
+  };
+}

package/src/node/plugin.ts

@@ -0,0 +1,53 @@
+import type { Plugin } from "vite";
+import { discoverFlowFiles } from "./discovery";
+import { parseFlowFile } from "./parser";
+import type { FlowbookPluginOptions, FlowbookData } from "../types";
+
+const VIRTUAL_MODULE_ID = "virtual:flowbook-data";
+const RESOLVED_ID = "\0" + VIRTUAL_MODULE_ID;
+
+export function flowbookPlugin(options: FlowbookPluginOptions = {}): Plugin {
+  const cwd = options.cwd ?? process.cwd();
+
+  async function loadFlows(): Promise<FlowbookData> {
+    const files = await discoverFlowFiles({ ...options, cwd });
+    const flows = files.map((f) => parseFlowFile(f, cwd));
+    flows.sort((a, b) => {
+      if (a.category !== b.category)
+        return a.category.localeCompare(b.category);
+      return a.order - b.order;
+    });
+    return { flows };
+  }
+
+  return {
+    name: "flowbook",
+
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) return RESOLVED_ID;
+    },
+
+    async load(id) {
+      if (id === RESOLVED_ID) {
+        const data = await loadFlows();
+        return `export default ${JSON.stringify(data)}`;
+      }
+    },
+
+    handleHotUpdate({ file, server }) {
+      if (file.endsWith(".flow.md") || file.endsWith(".flowchart.md")) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({ type: "full-reload" });
+        }
+      }
+    },
+
+    configureServer(server) {
+      if (cwd !== process.cwd()) {
+        server.watcher.add(cwd);
+      }
+    },
+  };
+}

package/src/node/server.ts

@@ -0,0 +1,56 @@
+import { createServer, build, type InlineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { flowbookPlugin } from "./plugin";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getClientDir(): string {
+  // dist/cli.js  →  ../src/client
+  return resolve(__dirname, "..", "src", "client");
+}
+
+function createConfig(options: {
+  port?: number;
+  cwd?: string;
+  outDir?: string;
+}): InlineConfig {
+  const cwd = options.cwd ?? process.cwd();
+  const clientDir = getClientDir();
+
+  return {
+    configFile: false,
+    root: clientDir,
+    plugins: [
+      react(),
+      tailwindcss(),
+      flowbookPlugin({
+        include: ["**/*.flow.md", "**/*.flowchart.md"],
+        ignore: ["node_modules/**", ".git/**", "dist/**"],
+        cwd,
+      }),
+    ],
+    server: {
+      port: options.port ?? 6200,
+    },
+    build: {
+      outDir: resolve(cwd, options.outDir ?? "flowbook-static"),
+      emptyOutDir: true,
+    },
+  };
+}
+
+export async function startDevServer(options: { port?: number }) {
+  const config = createConfig({ port: options.port });
+  const server = await createServer(config);
+  await server.listen();
+  server.printUrls();
+}
+
+export async function buildStatic(options: { outDir?: string }) {
+  const config = createConfig({ outDir: options.outDir });
+  await build(config);
+  console.log(`\n  Static site built to ${options.outDir ?? "flowbook-static"}/\n`);
+}

package/src/types.ts

@@ -0,0 +1,20 @@
+export interface FlowEntry {
+  id: string;
+  title: string;
+  category: string;
+  tags: string[];
+  description: string;
+  order: number;
+  filePath: string;
+  mermaidBlocks: string[];
+}
+
+export interface FlowbookData {
+  flows: FlowEntry[];
+}
+
+export interface FlowbookPluginOptions {
+  include?: string[];
+  ignore?: string[];
+  cwd?: string;
+}