@canofold/vite 0.3.0-rc.0

package/README.md

@@ -0,0 +1,18 @@
+# @canofold/vite
+
+The official React + Vite Demo Engine for Canofold. It reuses the component project's Vite configuration, plugins, aliases, and CSS dependency graph to provide live previews, HMR, and production bundles for component examples in ordinary Markdown. The current release supports React 18 and React 19.
+
+```ts
+import { defineConfig } from 'canofold'
+import { vite } from '@canofold/vite'
+
+export default defineConfig({
+  demos: {
+    engine: vite()
+  }
+})
+```
+
+Run `canofold dev`; Vite is mounted on the same development server and port.
+
+Demos render inline by default. `sandbox="iframe"` places trusted local demo code in a restricted iframe for DOM and global-style isolation; it is not a security boundary for untrusted code.

package/README.zh-CN.md

@@ -0,0 +1,16 @@
+# @canofold/vite
+
+Canofold 官方 React + Vite Demo Engine。它复用组件项目已有的 Vite 配置、插件、别名和 CSS 依赖图，为普通 Markdown 中的组件示例提供开发预览、HMR 与生产构建。当前版本支持 React 18 和 React 19。
+
+```ts
+import { defineConfig } from 'canofold'
+import { vite } from '@canofold/vite'
+
+export default defineConfig({
+  demos: {
+    engine: vite()
+  }
+})
+```
+
+Demo 默认渲染在文档页面中。`sandbox="iframe"` 会把可信的本地 Demo 放进受限 iframe，隔离 DOM 与全局样式；它不是运行不可信代码的安全边界。

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { CanofoldDemoEngine } from 'canofold/demo-engine';
+
+interface CanofoldViteOptions {
+    /** Project root passed to Vite. Defaults to the Canofold project root. */
+    root?: string;
+    /** Vite config file. Use false to disable config discovery. */
+    configFile?: string | false;
+}
+declare function vite(options?: CanofoldViteOptions): CanofoldDemoEngine;
+
+export { type CanofoldViteOptions, vite as default, vite };

package/dist/index.js

@@ -0,0 +1,471 @@
+// src/index.ts
+import { realpathSync } from "fs";
+import { readFile, writeFile } from "fs/promises";
+import { extname, isAbsolute, join, relative, resolve, sep } from "path";
+import {
+  build as viteBuild,
+  createServer as createViteServer,
+  loadConfigFromFile,
+  mergeConfig,
+  normalizePath
+} from "vite";
+
+// src/runtime.ts
+function demoRuntimeSource(registryEntries, setupImport, styleUrls = []) {
+  const imports = registryEntries.join("\n");
+  const setup = setupImport ?? "const CanofoldDemoSetup = null;";
+  return `${imports}
+${setup}
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+const registry = new Map(CANOFOLD_DEMO_REGISTRY);
+const iframeStyleUrls = ${JSON.stringify(styleUrls)};
+const roots = new Set();
+const frameObservers = new Set();
+let eventController;
+
+class DemoBoundary extends React.Component {
+  constructor(props) { super(props); this.state = { error: null }; }
+  static getDerivedStateFromError(error) { return { error }; }
+  render() {
+    if (!this.state.error) return this.props.children;
+    return React.createElement('div', { className: 'cf-demo-error', role: 'alert' }, this.props.message);
+  }
+}
+
+function componentFor(id) {
+  const value = registry.get(id);
+  const component = value && (value.default || value.Demo);
+  if (!component) throw new Error('Demo module ' + id + ' must export a default React component.');
+  return component;
+}
+
+export function mountDemo(element, id, failedLabel) {
+  const Demo = componentFor(id);
+  const content = React.createElement(Demo);
+  const wrapped = CanofoldDemoSetup ? React.createElement(CanofoldDemoSetup, null, content) : content;
+  const root = createRoot(element);
+  roots.add(root);
+  root.render(React.createElement(DemoBoundary, { message: failedLabel }, wrapped));
+  return root;
+}
+
+function iframeDocument(id, failedLabel) {
+  const script = \`import(\${JSON.stringify(import.meta.url)}).then(({ mountDemo }) => mountDemo(document.getElementById('root'),\${JSON.stringify(id)},\${JSON.stringify(failedLabel)})).catch((error) => { console.error('[Canofold demo iframe]', error); const root = document.getElementById('root'); root.setAttribute('role', 'alert'); root.textContent = \${JSON.stringify(failedLabel)}; });\`;
+  const styles = iframeStyleUrls.map((href) => '<link rel="stylesheet" href="' + href.replace(/&/g, '&amp;').replace(/"/g, '&quot;') + '">').join('');
+  return '<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">' + styles + '<style>html,body,#root{min-height:100%;margin:0}body{display:grid;place-items:center;padding:24px;box-sizing:border-box;font-family:system-ui,sans-serif}</style></head><body><div id="root"></div><script type="module">' + script.replace(/<\\/script/gi, '<\\\\/script') + '<\\/script></body></html>';
+}
+
+function fitFrame(frame) {
+  const frameDocument = frame.contentDocument;
+  if (!frameDocument) return;
+  const update = () => {
+    frame.style.height = Math.max(192, Math.ceil(frameDocument.documentElement.scrollHeight)) + 'px';
+  };
+  update();
+  if (typeof ResizeObserver === 'undefined') return;
+  const observer = new ResizeObserver(update);
+  observer.observe(frameDocument.documentElement);
+  frameObservers.add(observer);
+}
+
+function bindSourceToggle(button, signal) {
+  const sourceId = button.getAttribute('aria-controls');
+  const source = sourceId && document.getElementById(sourceId);
+  if (!source) return;
+  const setExpanded = (expanded) => {
+    const label = button.getAttribute(expanded ? 'data-cf-demo-hide-label' : 'data-cf-demo-show-label') || '';
+    button.setAttribute('aria-expanded', String(expanded));
+    button.setAttribute('aria-label', label);
+    source.hidden = !expanded;
+    const tooltip = button.querySelector('[data-cf-demo-tooltip]');
+    if (tooltip) tooltip.textContent = label;
+  };
+  setExpanded(button.getAttribute('aria-expanded') === 'true');
+  button.addEventListener('click', () => setExpanded(button.getAttribute('aria-expanded') !== 'true'), { signal });
+}
+
+function standaloneDemo() {
+  const id = new URL(window.location.href).searchParams.get('canofold-demo');
+  if (!id || !registry.has(id)) return false;
+  const preview = Array.from(document.querySelectorAll('[data-cf-demo-preview]')).find(
+    (element) => element.getAttribute('data-cf-demo-id') === id
+  );
+  const failed = preview?.getAttribute('data-cf-demo-failed-label') || 'This example could not be loaded.';
+  const root = document.createElement('main');
+  root.className = 'cf-demo-standalone';
+  root.setAttribute('data-cf-demo-id', id);
+  document.documentElement.setAttribute('data-cf-demo-standalone', '');
+  document.body.replaceChildren(root);
+  mountDemo(root, id, failed);
+  return true;
+}
+
+export async function bootstrapDemos() {
+  window.__canofoldDemoDispose?.();
+  if (standaloneDemo()) {
+    window.__canofoldDemoDispose = () => {
+      roots.forEach((root) => root.unmount());
+      roots.clear();
+      document.documentElement.removeAttribute('data-cf-demo-standalone');
+    };
+    return;
+  }
+  document.documentElement.removeAttribute('data-cf-demo-standalone');
+  eventController = new AbortController();
+  document.querySelectorAll('[data-cf-demo-source-toggle]').forEach((button) => bindSourceToggle(button, eventController.signal));
+  document.querySelectorAll('[data-cf-demo-preview]').forEach((preview) => {
+    const id = preview.getAttribute('data-cf-demo-id');
+    if (!id) return;
+    const loading = preview.getAttribute('data-cf-demo-loading-label') || 'Loading example\u2026';
+    const failed = preview.getAttribute('data-cf-demo-failed-label') || 'This example could not be loaded.';
+    preview.textContent = loading;
+    try {
+      const card = preview.closest('[data-cf-component="demo"]');
+      if (card?.getAttribute('data-cf-demo-sandbox') === 'iframe') {
+        const frame = document.createElement('iframe');
+        frame.className = 'cf-demo-frame';
+        frame.title = card.querySelector('.cf-demo-title')?.textContent || 'Component example';
+        frame.loading = 'lazy';
+        frame.referrerPolicy = 'no-referrer';
+        frame.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+        frame.addEventListener('load', () => fitFrame(frame), { once: true });
+        frame.srcdoc = iframeDocument(id, failed);
+        preview.replaceChildren(frame);
+      } else {
+        preview.textContent = '';
+        mountDemo(preview, id, failed);
+      }
+    } catch (error) {
+      console.error('[Canofold demo]', error);
+      preview.textContent = failed;
+      preview.setAttribute('data-cf-demo-error', '');
+    }
+  });
+  window.__canofoldDemoDispose = () => {
+    eventController?.abort();
+    eventController = undefined;
+    frameObservers.forEach((observer) => observer.disconnect());
+    frameObservers.clear();
+    roots.forEach((root) => root.unmount());
+    roots.clear();
+  };
+}
+
+window.__canofoldBootstrapDemos = bootstrapDemos;
+void bootstrapDemos();
+
+if (import.meta.hot) {
+  import.meta.hot.accept(() => void bootstrapDemos());
+}
+`;
+}
+
+// src/index.ts
+var PUBLIC_CLIENT_ID = "virtual:canofold-demo-client";
+var RESOLVED_CLIENT_ID = `\0${PUBLIC_CLIENT_ID}`;
+function baseUrl(basePath, path) {
+  const prefix = basePath === "/" ? "" : basePath.replace(/\/$/, "");
+  return `${prefix}/${path.replace(/^\//, "")}`;
+}
+function languageFor(path) {
+  const extension = extname(path).toLowerCase();
+  if (extension === ".tsx") return "tsx";
+  if (extension === ".jsx") return "jsx";
+  if (extension === ".js" || extension === ".mjs" || extension === ".cjs") return "js";
+  return "ts";
+}
+function filePathFromResolvedId(id) {
+  const clean = id.replace(/[?#].*$/, "");
+  if (clean.startsWith("/@fs/")) return clean.slice("/@fs".length);
+  return clean;
+}
+function importerFor(reference) {
+  return normalizePath(reference.pageSourcePath);
+}
+function canonicalPath(path) {
+  try {
+    return realpathSync.native(resolve(path));
+  } catch {
+    return resolve(path);
+  }
+}
+function isProjectSource(cwd, path) {
+  const projectRelative = relative(canonicalPath(cwd), canonicalPath(path));
+  return projectRelative !== ".." && !projectRelative.startsWith(`..${sep}`) && !isAbsolute(projectRelative) && !projectRelative.split(sep).some((segment) => segment === "node_modules" || segment === ".canofold");
+}
+function moduleRequestUrl(server, modulePath) {
+  const rootRelative = relative(canonicalPath(server.config.root), canonicalPath(modulePath));
+  if (rootRelative !== ".." && !rootRelative.startsWith(`..${sep}`) && !isAbsolute(rootRelative)) {
+    return `/${normalizePath(rootRelative)}`;
+  }
+  return `/@fs/${normalizePath(modulePath)}`;
+}
+async function collectLocalDependencies(server, modulePath, cwd) {
+  await server.transformRequest(moduleRequestUrl(server, modulePath));
+  const first = server.moduleGraph.getModuleById(normalizePath(modulePath)) ?? server.moduleGraph.getModulesByFile(modulePath)?.values().next().value;
+  const visited = /* @__PURE__ */ new Set();
+  const dependencies = /* @__PURE__ */ new Set();
+  async function visit(module) {
+    if (!module) return;
+    const key = module.id ?? module.url;
+    if (visited.has(key)) return;
+    visited.add(key);
+    if (!module.file || !isProjectSource(cwd, module.file)) return;
+    dependencies.add(canonicalPath(module.file));
+    await server.transformRequest(module.url);
+    await Promise.all([...module.importedModules].map((dependency) => visit(dependency)));
+  }
+  await visit(first);
+  return [...dependencies].sort();
+}
+async function resolveDemo(server, reference, cwd) {
+  const resolved = await server.pluginContainer.resolveId(reference.specifier, importerFor(reference));
+  if (!resolved || resolved.external || resolved.id.startsWith("\0")) {
+    throw new Error(
+      `Vite could not resolve demo ${JSON.stringify(reference.specifier)} in ${reference.pageSourceRelativePath}`
+    );
+  }
+  const modulePath = filePathFromResolvedId(resolved.id);
+  if (!isAbsolute(modulePath)) {
+    throw new Error(
+      `Demo ${JSON.stringify(reference.specifier)} must resolve to a local source file, got ${JSON.stringify(resolved.id)}`
+    );
+  }
+  if (!isProjectSource(cwd, modulePath)) {
+    throw new Error(
+      `Demo ${JSON.stringify(reference.specifier)} must resolve inside the Canofold project root`
+    );
+  }
+  let source;
+  try {
+    source = await readFile(modulePath, "utf8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not read demo source ${modulePath}: ${message}`);
+  }
+  return {
+    ...reference,
+    modulePath,
+    moduleUrl: normalizePath(resolved.id),
+    dependencyPaths: await collectLocalDependencies(server, modulePath, cwd),
+    source,
+    language: languageFor(modulePath)
+  };
+}
+async function resolvedSetup(server, setup, cwd) {
+  if (!setup) return void 0;
+  const importer = normalizePath(join(cwd, "canofold.config.ts"));
+  const resolved = await server.pluginContainer.resolveId(setup, importer);
+  if (!resolved || resolved.external || resolved.id.startsWith("\0")) {
+    throw new Error(`Vite could not resolve demos.setup ${JSON.stringify(setup)}`);
+  }
+  const modulePath = filePathFromResolvedId(resolved.id);
+  if (!isAbsolute(modulePath)) {
+    throw new Error(`demos.setup must resolve to a local source file, got ${JSON.stringify(resolved.id)}`);
+  }
+  if (!isProjectSource(cwd, modulePath)) {
+    throw new Error(`demos.setup ${JSON.stringify(setup)} must resolve inside the Canofold project root`);
+  }
+  return {
+    id: normalizePath(resolved.id),
+    dependencyPaths: await collectLocalDependencies(server, modulePath, cwd)
+  };
+}
+function virtualClientPlugin({
+  getDemos,
+  getSetup,
+  styleUrls = []
+}) {
+  return {
+    name: "canofold-demo-client",
+    enforce: "post",
+    resolveId(id) {
+      return id === PUBLIC_CLIENT_ID ? RESOLVED_CLIENT_ID : void 0;
+    },
+    load(id) {
+      if (id !== RESOLVED_CLIENT_ID) return void 0;
+      const entries = [];
+      const registry = [];
+      getDemos().forEach((demo, index) => {
+        const binding = `CanofoldDemo${index}`;
+        entries.push(`import * as ${binding} from ${JSON.stringify(normalizePath(demo.modulePath))};`);
+        registry.push(`[${JSON.stringify(demo.id)}, ${binding}]`);
+      });
+      entries.push(`const CANOFOLD_DEMO_REGISTRY = [${registry.join(",")}];`);
+      const setup = getSetup();
+      const setupImport = setup ? `import CanofoldDemoSetup from ${JSON.stringify(setup)};` : void 0;
+      return demoRuntimeSource(entries, setupImport, styleUrls);
+    }
+  };
+}
+function inlineConfig(cwd, basePath, options, plugins) {
+  const configFile = options.configFile === false ? false : options.configFile ? resolve(cwd, options.configFile) : void 0;
+  return {
+    root: canonicalPath(options.root ? resolve(cwd, options.root) : cwd),
+    configFile,
+    base: basePath,
+    appType: "custom",
+    plugins: Array.isArray(plugins) ? plugins : [plugins],
+    resolve: { dedupe: ["react", "react-dom"] }
+  };
+}
+function demoBuildOptions(context) {
+  return {
+    // The project may itself be a Vite library. Demos are a browser app and
+    // must not inherit library externals or output conventions.
+    lib: false,
+    minify: "esbuild",
+    outDir: join(context.outputRoot, "assets/canofold-demos"),
+    emptyOutDir: true,
+    copyPublicDir: false,
+    cssCodeSplit: false,
+    rollupOptions: {
+      external: () => false,
+      input: PUBLIC_CLIENT_ID,
+      output: {
+        format: "es",
+        inlineDynamicImports: true,
+        entryFileNames: "index.js",
+        assetFileNames: (asset) => asset.names?.some((name) => name.endsWith(".css")) ? "styles.css" : "[name][extname]"
+      }
+    }
+  };
+}
+async function isolatedBuildConfig(context, options, plugin, build) {
+  const root = canonicalPath(options.root ? resolve(context.cwd, options.root) : context.cwd);
+  const configFile = options.configFile ? resolve(context.cwd, options.configFile) : void 0;
+  const loaded = options.configFile === false ? void 0 : await loadConfigFromFile(
+    { command: "build", mode: "production", isSsrBuild: false, isPreview: false },
+    configFile,
+    root
+  );
+  const sharedConfig = { ...loaded?.config ?? {} };
+  delete sharedConfig.build;
+  delete sharedConfig.server;
+  delete sharedConfig.preview;
+  const engineConfig = {
+    ...inlineConfig(context.cwd, context.basePath, { ...options, configFile: false }, plugin),
+    mode: "production",
+    define: {
+      "process.env.NODE_ENV": JSON.stringify("production")
+    },
+    esbuild: {
+      jsxDev: false
+    },
+    build
+  };
+  return mergeConfig(sharedConfig, engineConfig);
+}
+async function prepareDemos(context, options) {
+  let demos = [];
+  let setup;
+  const plugin = virtualClientPlugin({
+    getDemos: () => demos,
+    getSetup: () => setup,
+    styleUrls: context.mode === "build" ? [baseUrl(context.basePath, "/assets/canofold-demos/styles.css")] : []
+  });
+  const server = await createViteServer({
+    ...inlineConfig(context.cwd, context.basePath, options, plugin),
+    // This server only resolves source files and walks Vite's module graph.
+    // Dependency pre-bundling belongs to the long-lived dev server below; when
+    // started here it can keep server.close() waiting after the analysis is done.
+    optimizeDeps: { noDiscovery: true },
+    server: { middlewareMode: true, hmr: false, ws: false }
+  });
+  try {
+    demos = await Promise.all(context.demos.map((reference) => resolveDemo(server, reference, context.cwd)));
+    const resolved = await resolvedSetup(server, context.setup, context.cwd);
+    setup = resolved?.id;
+    return {
+      demos,
+      setup,
+      dependencyPaths: [
+        .../* @__PURE__ */ new Set([
+          ...server.config.configFileDependencies.map((path) => canonicalPath(path)),
+          ...resolved?.dependencyPaths ?? []
+        ])
+      ],
+      plugin
+    };
+  } finally {
+    await server.close();
+  }
+}
+function vite(options = {}) {
+  return {
+    id: "@canofold/vite",
+    version: "2",
+    cacheKey: {
+      root: options.root ?? null,
+      configFile: options.configFile ?? null
+    },
+    async prepare(context) {
+      const prepared = await prepareDemos(context, options);
+      if (context.mode === "build") {
+        const build = demoBuildOptions(context);
+        await viteBuild(await isolatedBuildConfig(context, options, prepared.plugin, build));
+        await writeFile(join(context.outputRoot, "assets/canofold-demos/styles.css"), "", {
+          flag: "a"
+        });
+      }
+      return {
+        clientUrl: context.mode === "build" ? baseUrl(context.basePath, "/assets/canofold-demos/index.js") : baseUrl(context.basePath, `/@id/__x00__${PUBLIC_CLIENT_ID}`),
+        ...context.mode === "build" ? { styleUrls: [baseUrl(context.basePath, "/assets/canofold-demos/styles.css")] } : {},
+        demos: Object.fromEntries(prepared.demos.map((demo) => [demo.id, demo])),
+        dependencyPaths: prepared.dependencyPaths,
+        ...context.mode === "build" ? {
+          outputPaths: ["assets/canofold-demos/index.js", "assets/canofold-demos/styles.css"]
+        } : {}
+      };
+    },
+    async startDev(context) {
+      const currentDemos = () => context.getDemos();
+      let setup;
+      const plugin = virtualClientPlugin({ getDemos: currentDemos, getSetup: () => setup });
+      const server = await createViteServer({
+        ...inlineConfig(context.cwd, context.basePath, options, plugin),
+        server: {
+          middlewareMode: true,
+          hmr: { server: context.server },
+          watch: { ignored: (path) => context.shouldIgnorePath(path) }
+        }
+      });
+      setup = (await resolvedSetup(server, context.setup, context.cwd))?.id;
+      let demoSignature = JSON.stringify(
+        currentDemos().map((demo) => [demo.id, normalizePath(demo.modulePath)])
+      );
+      return {
+        middleware(request, response, next) {
+          server.middlewares(request, response, next);
+        },
+        handlesFile(path) {
+          const absolutePath = canonicalPath(path);
+          const isEntry = currentDemos().some((demo) => canonicalPath(demo.modulePath) === absolutePath);
+          if (isEntry || setup && canonicalPath(filePathFromResolvedId(setup)) === absolutePath) {
+            return false;
+          }
+          return Boolean(server.moduleGraph.getModulesByFile(absolutePath)?.size);
+        },
+        update() {
+          const nextSignature = JSON.stringify(
+            currentDemos().map((demo) => [demo.id, normalizePath(demo.modulePath)])
+          );
+          if (nextSignature === demoSignature) return;
+          demoSignature = nextSignature;
+          const module = server.moduleGraph.getModuleById(RESOLVED_CLIENT_ID);
+          if (module) server.moduleGraph.invalidateModule(module);
+          server.ws.send({ type: "full-reload" });
+        },
+        close: () => server.close()
+      };
+    }
+  };
+}
+var src_default = vite;
+export {
+  src_default as default,
+  vite
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@canofold/vite",
+  "version": "0.3.0-rc.0",
+  "description": "Official Vite demo engine for interactive Canofold component documentation.",
+  "license": "MIT",
+  "author": "Canofold Contributors",
+  "homepage": "https://canofold.dev/guide/writing/component-demos/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/canofold/canofold.git",
+    "directory": "packages/vite"
+  },
+  "bugs": {
+    "url": "https://github.com/canofold/canofold/issues"
+  },
+  "keywords": [
+    "canofold",
+    "vite",
+    "documentation",
+    "components",
+    "demos"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../.. packages/vite"
+  },
+  "peerDependencies": {
+    "canofold": "^0.3.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "canofold": "workspace:*",
+    "tsup": "^8.3.5",
+    "typescript": "^6.0.3",
+    "vite": "^6.4.3",
+    "vitest": "^4.1.11"
+  }
+}