npm - tutuca - Versions diffs - 0.9.83 → 0.9.84 - Mend

tutuca 0.9.83 → 0.9.84

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +2 -0
package/dist/tutuca-cli.js +384 -52
package/dist/tutuca-storybook.js +283 -0
package/package.json +3 -1
package/skill/tutuca/core.md +11 -0

package/README.md CHANGED Viewed

@@ -68,6 +68,8 @@ Tutuca ships a single-file CLI (`dist/tutuca-cli.js`) for inspecting, linting,
 documenting, and rendering components defined in an ES module. The module just
 needs to export `getComponents()` and, for render-time commands, `getExamples()`
 in the storybook shape `{ title, description?, items: [{ title, description?, value, view? }] }` (a single section, or an array of sections).
+Expose **all** of your app's components through `getComponents()` — components
+left out are invisible to `lint`/`render`/`test` and silently lose coverage.
 ### Setup

package/dist/tutuca-cli.js CHANGED Viewed

@@ -15629,6 +15629,356 @@ var init_install_skill = __esm(() => {
   ];
 });
+// tools/cli/env.js
+import { JSDOM, VirtualConsole } from "jsdom";
+async function createNodeEnv() {
+  const virtualConsole = new VirtualConsole;
+  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
+  virtualConsole.on("jsdomError", (err) => {
+    if (err?.message?.includes("Could not parse CSS stylesheet"))
+      return;
+    console.error(err.message);
+  });
+  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
+    virtualConsole
+  });
+  const { document: document2, Text, Comment } = dom.window;
+  globalThis.document = document2;
+  class HeadlessParseContext extends ParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
+  }
+  class HeadlessLintParseContext extends LintParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
+  }
+  return {
+    document: dom.window.document,
+    ParseContext: HeadlessParseContext,
+    LintParseContext: HeadlessLintParseContext
+  };
+}
+var init_env2 = __esm(() => {
+  init_anode();
+  init_lint_check();
+});
+// tools/cli/commands/storybook.js
+var exports_storybook = {};
+__export(exports_storybook, {
+  run: () => run4,
+  describe: () => describe4
+});
+import {
+  createReadStream,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync3,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { createServer } from "node:http";
+import { dirname as dirname4, join, normalize, relative as relative2, resolve as resolve4, sep } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { parseArgs as parseArgs3 } from "node:util";
+function findDevModules(root, dir, acc) {
+  for (const e of readdirSync2(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") || e.name === "node_modules")
+      continue;
+    const full = resolve4(dir, e.name);
+    if (e.isDirectory()) {
+      findDevModules(root, full, acc);
+    } else if (e.isFile() && e.name.endsWith(".dev.js")) {
+      acc.push(`/${relative2(root, full).split(sep).join("/")}`);
+    }
+  }
+  return acc;
+}
+function findSelf() {
+  const here = dirname4(fileURLToPath4(import.meta.url));
+  const pkgCandidates = [
+    resolve4(here, "..", "..", "..", "package.json"),
+    resolve4(here, "..", "package.json")
+  ];
+  const pkgPath = pkgCandidates.find(existsSync4);
+  const version = pkgPath ? JSON.parse(readFileSync3(pkgPath, "utf8")).version : "latest";
+  const distCandidates = [resolve4(here, "..", "..", "..", "dist"), resolve4(here, ".")];
+  const distRoot = distCandidates.find((d) => existsSync4(resolve4(d, "tutuca-storybook.js"))) ?? null;
+  return { version, distRoot };
+}
+function resolveTutucaBase(projectDir, self, forCdn) {
+  if (forCdn)
+    return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
+  const nm = resolve4(projectDir, "node_modules", "tutuca", "dist");
+  if (existsSync4(resolve4(nm, "tutuca-dev.js"))) {
+    return { base: "/node_modules/tutuca/dist", serveDist: null };
+  }
+  if (self.distRoot)
+    return { base: DIST_PREFIX.replace(/\/$/, ""), serveDist: self.distRoot };
+  return { base: `https://cdn.jsdelivr.net/npm/tutuca@${self.version}/dist`, serveDist: null };
+}
+function buildImports(base, { margaui }) {
+  const dev = `${base}/tutuca-dev.js`;
+  const imports = {
+    tutuca: dev,
+    "tutuca/extra": dev,
+    "tutuca/dev": dev,
+    "tutuca/storybook": `${base}/tutuca-storybook.js`
+  };
+  if (margaui)
+    imports.margaui = MARGAUI_CDN;
+  return imports;
+}
+function renderIndexHtml(imports, { margaui, bootstrapUrl }) {
+  const theme = margaui ? `
+    <link rel="stylesheet" href="${MARGAUI_THEME}" />` : "";
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Storybook</title>${theme}
+    <script type="importmap">
+${JSON.stringify({ imports }, null, 6)}
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="${bootstrapUrl}"></script>
+  </body>
+</html>
+`;
+}
+function renderBootstrap(devModuleUrls, { margaui, check }) {
+  const lines = ['import { mountStorybook } from "tutuca/storybook";'];
+  if (margaui) {
+    lines.push('import { compileClassesToStyleText } from "tutuca/extra";');
+    lines.push('import { compile } from "margaui";');
+  }
+  if (check)
+    lines.push('import { check } from "tutuca/dev";');
+  devModuleUrls.forEach((url, i) => {
+    lines.push(`import * as m${i} from ${JSON.stringify(url)};`);
+  });
+  const modules = devModuleUrls.map((_, i) => `m${i}`).join(", ");
+  const opts = margaui ? "{ compileCss: (app) => compileClassesToStyleText(app, compile) }" : "{}";
+  lines.push("");
+  lines.push(`const app = await mountStorybook("#app", [${modules}], ${opts});`);
+  if (check)
+    lines.push("check(app);");
+  lines.push("");
+  return lines.join(`
+`);
+}
+async function runDevTests(projectDir, devModuleUrls) {
+  await createNodeEnv();
+  let totalTests = 0;
+  let failedTests = 0;
+  let withTests = 0;
+  const failures = [];
+  const importErrors = [];
+  for (const url of devModuleUrls) {
+    const abs = resolve4(projectDir, url.slice(1));
+    let mod;
+    try {
+      mod = await import(abs);
+    } catch (e) {
+      importErrors.push({ url, message: e.message });
+      continue;
+    }
+    if (typeof mod.getTests !== "function")
+      continue;
+    withTests++;
+    const { normalized } = normalizeModule(mod, { path: abs });
+    const report = await runTests({
+      getTests: mod.getTests,
+      components: normalized.components,
+      path: abs,
+      expect
+    });
+    const m = report.modules[0];
+    totalTests += m.counts.total;
+    failedTests += m.counts.fail;
+    for (const suite of m.suites)
+      collectFailures(suite, failures);
+  }
+  return { totalTests, failedTests, withTests, failures, importErrors };
+}
+function collectFailures(node, acc) {
+  if (node.children) {
+    for (const child of node.children)
+      collectFailures(child, acc);
+  } else if (node.status === "fail") {
+    acc.push(node);
+  }
+}
+function safeJoin(rootDir, urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0]);
+  const p = normalize(join(rootDir, decoded));
+  if (p !== rootDir && !p.startsWith(rootDir + sep))
+    return null;
+  return p;
+}
+function serveFile(res, filePath) {
+  if (!filePath || !existsSync4(filePath) || statSync(filePath).isDirectory()) {
+    res.writeHead(404);
+    res.end("Not found");
+    return;
+  }
+  const dot = filePath.lastIndexOf(".");
+  const ext = dot >= 0 ? filePath.slice(dot) : "";
+  res.setHeader("Content-Type", MIME[ext] ?? "application/octet-stream");
+  createReadStream(filePath).pipe(res);
+}
+async function run4(argv, opts = {}) {
+  const parsed = parseArgs3({
+    args: argv,
+    options: {
+      port: { type: "string" },
+      out: { type: "string" },
+      "no-margaui": { type: "boolean", default: false },
+      "no-check": { type: "boolean", default: false },
+      "no-tests": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: true
+  });
+  if (parsed.values.help) {
+    process.stdout.write(`tutuca storybook [dir] [--port <n>] [--out <dir>]
+                 [--no-margaui] [--no-check] [--no-tests]
+  Auto-discovers co-located *.dev.js modules (recursively, skipping
+  node_modules/dotdirs) and serves a live storybook that mounts them via
+  the tutuca/storybook library. Zero setup.
+  [dir]          project root to scan and serve (default: cwd)
+  --port <n>     preferred port (default 4321; falls back to a free port)
+  --out <dir>    write a static index.html + bootstrap (CDN import map)
+                 instead of serving; host it from the project root
+  --no-margaui   skip margaui styling (renders functional but unstyled)
+  --no-check     skip the in-browser check(app) dev validation
+  --no-tests     skip running the modules' getTests() before serving
+`);
+    return;
+  }
+  const projectDir = resolve4(parsed.positionals[0] ?? process.cwd());
+  if (!existsSync4(projectDir) || !statSync(projectDir).isDirectory()) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_ARGUMENT,
+      message: `not a directory: ${projectDir}`,
+      hint: "Pass a project directory to scan, or omit it to use the current directory."
+    });
+  }
+  const devModuleUrls = findDevModules(projectDir, projectDir, []);
+  if (devModuleUrls.length === 0) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_ARGUMENT,
+      message: `no *.dev.js modules found under ${projectDir}`,
+      hint: "Create a co-located <name>.dev.js exporting getComponents() and getExamples()."
+    });
+  }
+  const margaui = !parsed.values["no-margaui"];
+  const check = !parsed.values["no-check"];
+  const self = findSelf();
+  if (parsed.values.out) {
+    const outDir = resolve4(parsed.values.out);
+    mkdirSync3(outDir, { recursive: true });
+    const { base: base2 } = resolveTutucaBase(projectDir, self, true);
+    const imports2 = buildImports(base2, { margaui });
+    const bootstrapName = "tutuca-storybook.bootstrap.js";
+    writeFileSync(resolve4(outDir, "index.html"), renderIndexHtml(imports2, { margaui, bootstrapUrl: `./${bootstrapName}` }));
+    writeFileSync(resolve4(outDir, bootstrapName), renderBootstrap(devModuleUrls, { margaui, check }));
+    process.stdout.write(`wrote static storybook → ${relative2(process.cwd(), outDir) || "."}/
+  index.html + ${bootstrapName} (${devModuleUrls.length} dev modules, CDN import map)
+  Host it from the project root so /*.dev.js paths resolve.
+`);
+    return;
+  }
+  if (!parsed.values["no-tests"]) {
+    const r = await runDevTests(projectDir, devModuleUrls);
+    for (const ie of r.importErrors) {
+      process.stdout.write(`  ! skipped tests for ${ie.url}: ${ie.message}
+`);
+    }
+    if (r.withTests === 0) {
+      process.stdout.write(`tests: no getTests() in any dev module
+`);
+    } else {
+      process.stdout.write(`tests: ${r.totalTests - r.failedTests}/${r.totalTests} passed across ${r.withTests} module(s)
+`);
+      for (const f of r.failures) {
+        process.stdout.write(`  ✗ ${f.fullPath}: ${f.error?.message ?? "failed"}
+`);
+      }
+    }
+  }
+  const { base, serveDist } = resolveTutucaBase(projectDir, self, false);
+  const imports = buildImports(base, { margaui });
+  const indexHtml = renderIndexHtml(imports, { margaui, bootstrapUrl: BOOTSTRAP_URL });
+  const bootstrapJs = renderBootstrap(devModuleUrls, { margaui, check });
+  const server = createServer((req, res) => {
+    const path = req.url.split("?")[0];
+    if (path === "/" || path === "/index.html") {
+      res.setHeader("Content-Type", MIME[".html"]);
+      res.end(indexHtml);
+      return;
+    }
+    if (path === BOOTSTRAP_URL) {
+      res.setHeader("Content-Type", MIME[".js"]);
+      res.end(bootstrapJs);
+      return;
+    }
+    if (serveDist && path.startsWith(DIST_PREFIX)) {
+      serveFile(res, safeJoin(serveDist, `/${path.slice(DIST_PREFIX.length)}`));
+      return;
+    }
+    serveFile(res, safeJoin(projectDir, path));
+  });
+  const preferred = Number.parseInt(parsed.values.port ?? "4321", 10);
+  server.on("error", (e) => {
+    if (e.code === "EADDRINUSE") {
+      server.listen(0);
+    } else {
+      throw e;
+    }
+  });
+  server.on("listening", () => {
+    const actual = server.address().port;
+    const where = base.startsWith("http") ? "CDN" : base.startsWith("/node_modules") ? "node_modules" : "local dist";
+    process.stdout.write(`tutuca storybook: http://localhost:${actual}/  (${devModuleUrls.length} dev modules, tutuca from ${where})
+`);
+  });
+  server.listen(preferred);
+}
+var describe4 = "Serve a storybook for the project's co-located *.dev.js modules (auto-discovered).", BOOTSTRAP_URL = "/__tutuca_storybook__.js", DIST_PREFIX = "/__tutuca__/", MIME, MARGAUI_CDN = "https://cdn.jsdelivr.net/npm/margaui/+esm", MARGAUI_THEME = "https://marianoguerra.github.io/margaui/themes/theme.css";
+var init_storybook = __esm(() => {
+  init_chai2();
+  init_test();
+  init_env2();
+  init_errors();
+  MIME = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css",
+    ".html": "text/html; charset=utf-8",
+    ".json": "application/json",
+    ".wasm": "application/wasm",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".ico": "image/x-icon",
+    ".map": "application/json"
+  };
+});
 // tools/tutuca.js
 init__registry();
@@ -15854,10 +16204,10 @@ init_feedback();
 init_chai_jest();
 var exports_help = {};
 __export(exports_help, {
-  run: () => run4,
-  describe: () => describe4
+  run: () => run5,
+  describe: () => describe5
 });
-var describe4 = "Show usage. `help <command>` for per-command detail.";
+var describe5 = "Show usage. `help <command>` for per-command detail.";
 var OVERVIEW = `tutuca — CLI for inspecting, documenting, linting and rendering tutuca
 components defined in an ES module.
@@ -15874,8 +16224,8 @@ INVOCATION SHAPE
     components; pass it to operate on exactly one (e.g. \`show Button\`).
   - Per-command flags follow the module path; global flags can appear
     anywhere. Unknown flags are rejected by the subcommand's parser.
-  - \`help\`, \`feedback\`, \`install-skill\`, \`agent-context\` do NOT take a
-    module path.
+  - \`help\`, \`feedback\`, \`install-skill\`, \`storybook\`, \`agent-context\` do NOT
+    take a module path.
 MODULE CONVENTION
   A module passed to tutuca must export one or more of:
@@ -15962,6 +16312,20 @@ COMMANDS (no module required)
       or suggestions about the CLI, skills, docs, or the library.
       Message comes from the positional arg or piped stdin.
+  storybook [dir] [--port <n>] [--out <dir>] [--no-margaui] [--no-check] [--no-tests]
+      Serve a live storybook for the project. Recursively auto-discovers
+      co-located *.dev.js modules (dev-only modules holding stories + tests
+      + helpers, never shipped) and mounts them via the tutuca/storybook
+      library — zero setup. By default also runs their getTests() in the
+      terminal and wires margaui styling + an in-browser check(app).
+        [dir]         project root to scan/serve (default: cwd)
+        --port <n>    preferred port (default 4321; else a free port)
+        --out <dir>   write a static index.html + bootstrap (CDN import map)
+                      instead of serving; host from the project root
+        --no-margaui  render unstyled (skip margaui)
+        --no-check    skip the in-browser check(app)
+        --no-tests    skip the pre-serve getTests() run
   agent-context
       Print a machine-readable schema of every command, flag, exit code,
       and error code as JSON on stdout. Use this once to teach an agent the
@@ -16027,21 +16391,22 @@ EXAMPLES
   tutuca lint ./src/components.js
   tutuca render ./src/components.js --title "Disabled state"
 `;
-async function run4(argv, opts = {}) {
+async function run5(argv, opts = {}) {
   const target = argv?.[0];
   if (!target) {
     process.stdout.write(OVERVIEW);
     return;
   }
   if (target === "help") {
-    process.stdout.write(`help: ${describe4}
+    process.stdout.write(`help: ${describe5}
 `);
     return;
   }
   const { COMMANDS: COMMANDS2 } = await Promise.resolve().then(() => (init__registry(), exports__registry));
   const noModule = {
     feedback: await Promise.resolve().then(() => (init_feedback(), exports_feedback)),
-    "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill))
+    "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill)),
+    storybook: await Promise.resolve().then(() => (init_storybook(), exports_storybook))
   };
   const cmd = COMMANDS2[target] ?? noModule[target];
   if (!cmd) {
@@ -16084,58 +16449,24 @@ ${group}
 // tools/tutuca.js
 init_install_skill();
+init_storybook();
 init_errors();
 // tools/cli/with-module.js
-import { parseArgs as parseArgs3 } from "node:util";
-// tools/cli/env.js
-init_anode();
-init_lint_check();
-import { JSDOM, VirtualConsole } from "jsdom";
-async function createNodeEnv() {
-  const virtualConsole = new VirtualConsole;
-  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
-  virtualConsole.on("jsdomError", (err) => {
-    if (err?.message?.includes("Could not parse CSS stylesheet"))
-      return;
-    console.error(err.message);
-  });
-  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
-    virtualConsole
-  });
-  const { document: document2, Text, Comment } = dom.window;
-  globalThis.document = document2;
-  class HeadlessParseContext extends ParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-  class HeadlessLintParseContext extends LintParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-  return {
-    document: dom.window.document,
-    ParseContext: HeadlessParseContext,
-    LintParseContext: HeadlessLintParseContext
-  };
-}
+init_env2();
+import { parseArgs as parseArgs4 } from "node:util";
 // tools/cli/load.js
-import { resolve as resolve4 } from "node:path";
+import { resolve as resolve5 } from "node:path";
 async function loadAndNormalize(modulePath) {
-  const abs = resolve4(modulePath);
+  const abs = resolve5(modulePath);
   const mod = await import(abs);
   const { normalized } = normalizeModule(mod, { path: abs });
   return normalized;
 }
 // tools/cli/output.js
-import { writeFileSync } from "node:fs";
+import { writeFileSync as writeFileSync2 } from "node:fs";
 // tools/format/cli.js
 var exports_cli = {};
@@ -16621,7 +16952,7 @@ async function formatResult(formatName, result, options = {}) {
 async function emit(result, { format: format5, pretty, output }) {
   const text = await formatResult(format5, result, { pretty });
   if (output) {
-    writeFileSync(output, text);
+    writeFileSync2(output, text);
   } else {
     process.stdout.write(text);
     if (!text.endsWith(`
@@ -16633,7 +16964,7 @@ async function emit(result, { format: format5, pretty, output }) {
 // tools/cli/with-module.js
 async function runCommand(cmd, argv, globalOpts) {
-  const parsed = parseArgs3({
+  const parsed = parseArgs4({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
@@ -16658,6 +16989,7 @@ var NO_MODULE_COMMANDS = {
   help: exports_help,
   feedback: exports_feedback,
   "install-skill": exports_install_skill,
+  storybook: exports_storybook,
   "agent-context": exports_agent_context
 };
 var VALID_FORMATS = ["cli", "md", "json", "html"];
@@ -16711,7 +17043,7 @@ function dispatchKnownCommands() {
 async function main() {
   const { opts, rest } = extractGlobals(process.argv.slice(2));
   if (rest.length === 0) {
-    await run4([], opts);
+    await run5([], opts);
     return;
   }
   const command = rest[0];
@@ -16722,7 +17054,7 @@ async function main() {
     return;
   }
   if (opts.help) {
-    await run4([command], opts);
+    await run5([command], opts);
     return;
   }
   const cmd = COMMANDS[command];

package/dist/tutuca-storybook.js ADDED Viewed

@@ -0,0 +1,283 @@
+// src/storybook.js
+import { component, html, injectCss, tutuca } from "tutuca";
+var Storybook = component({
+  name: "Storybook",
+  fields: {
+    selectedSectionIndex: 0,
+    sections: [],
+    filter: "",
+    sectionId: null,
+    exampleId: null,
+    focusExample: null
+  },
+  methods: {
+    selectSectionAtIndex(index) {
+      if (this.sections.size === 0)
+        return this;
+      const safeIndex = index >= 0 && index < this.sections.size ? index : 0;
+      const sections = this.sections.map((s, i) => s.setSelected(i === safeIndex));
+      return this.setSelectedSectionIndex(safeIndex).setSections(sections);
+    },
+    selectSectionWithId(id) {
+      if (!id)
+        return this.selectSectionAtIndex(this.selectedSectionIndex);
+      const index = this.sections.findIndex((s) => s.id === id);
+      return this.selectSectionAtIndex(index);
+    },
+    focusExampleByIds(sectionId, exampleId) {
+      if (!sectionId || !exampleId) {
+        return this;
+      }
+      const section = this.sections.find((s) => s.id === sectionId);
+      const example = section?.items.find((e) => e.id === exampleId);
+      if (!example) {
+        return this;
+      }
+      return this.setSectionId(sectionId).setExampleId(exampleId).setFocusExample(example.value);
+    }
+  },
+  input: {
+    onApplyFilter(value, ctx) {
+      ctx.request("persistState", [{ key: "sectionFilter", value }]);
+      return this.setFilter(value);
+    },
+    onClearFilter(ctx) {
+      ctx.request("persistState", [{ key: "sectionFilter", value: "" }]);
+      return this.resetFilter();
+    },
+    onFocusClose(ctx) {
+      ctx.request("persistState", [{ key: "sectionId", value: "" }]);
+      ctx.request("persistState", [{ key: "exampleId", value: "" }]);
+      return this.setSectionId(null).setExampleId(null).setFocusExample(null);
+    }
+  },
+  alter: {
+    filterSection(_key, section) {
+      return this.filter === "" || fuzzyMatch(this.filter, `${section.title} ${section.description}`);
+    }
+  },
+  bubble: {
+    sectionSelected(section, ctx) {
+      ctx.stopPropagation();
+      ctx.request("persistState", [{ key: "section", value: section.id }]);
+      return this.selectSectionAtIndex(this.sections.indexOf(section));
+    },
+    exampleFocusRequested(example, ctx) {
+      ctx.stopPropagation();
+      const section = this.sections.get(this.selectedSectionIndex);
+      const sectionId = section?.id ?? null;
+      ctx.request("persistState", [{ key: "sectionId", value: sectionId }]);
+      ctx.request("persistState", [{ key: "exampleId", value: example.id }]);
+      return this.setSectionId(sectionId).setExampleId(example.id).setFocusExample(example.value);
+    }
+  },
+  view: html`<div>
+    <div class="flex flex-col gap-3 p-3 h-screen" @show="truthy? .focusExample">
+      <div class="flex justify-end">
+        <button class="btn btn-ghost btn-sm" @on.click="onFocusClose">
+          close
+        </button>
+      </div>
+      <div class="flex-1 overflow-y-auto">
+        <x render=".focusExample"></x>
+      </div>
+    </div>
+    <div class="flex gap-3 p-3 h-screen" @hide="truthy? .focusExample">
+      <div
+        class="w-1/4 flex flex-col gap-3 bg-base-100 shadow-md h-full overflow-hidden"
+      >
+        <input
+          class="input w-full outline-0 focus:bg-base-200"
+          type="search"
+          placeholder="Filter sections"
+          :value=".filter"
+          @on.input="onApplyFilter value"
+          @on.keydown.cancel="onClearFilter"
+        />
+        <div class="list h-full flex-1 overflow-y-auto">
+          <x render-each=".sections" as="listEntry" when="filterSection"></x>
+        </div>
+      </div>
+      <div class="w-full h-full overflow-y-auto">
+        <x render=".sections[.selectedSectionIndex]"></x>
+      </div>
+    </div>
+  </div>`
+});
+var Section = component({
+  name: "Section",
+  fields: {
+    id: "?",
+    title: "No Title Section",
+    description: "",
+    items: [],
+    filter: "",
+    selected: false
+  },
+  statics: {
+    fromData({ id, title = "???", description = "", items = [] }) {
+      id ??= slugify(title);
+      return this.make({
+        id,
+        title,
+        description,
+        items: items.map((v) => Example.Class.fromData(v))
+      });
+    }
+  },
+  alter: {
+    filterItem(_key, item) {
+      return this.filter === "" || fuzzyMatch(this.filter, `${item.title} ${item.description}`);
+    }
+  },
+  input: {
+    onApplyFilter(value, ctx) {
+      ctx.request("persistState", [{ key: "exampleFilter", value }]);
+      return this.setFilter(value);
+    },
+    onClearFilter(ctx) {
+      ctx.request("persistState", [{ key: "exampleFilter", value: "" }]);
+      return this.resetFilter();
+    },
+    onListItemClick(ctx) {
+      ctx.bubble("sectionSelected", [this]);
+      return this;
+    }
+  },
+  view: html`<section class="flex flex-col gap-3">
+    <div class="sticky top-0 z-10 bg-base-100 pt-1 pb-2 shadow-sm">
+      <h2 class="text-lg font-bold" @text=".title"></h2>
+      <p class="text-md italic opacity-60" @text=".description"></p>
+    </div>
+    <input
+      class="input w-full outline-0 focus:bg-base-200"
+      type="search"
+      placeholder="Filter examples"
+      :value=".filter"
+      @on.input="onApplyFilter value"
+      @on.keydown.cancel="onClearFilter"
+    />
+    <div class="flex flex-col gap-3">
+      <x render-each=".items" when="filterItem"></x>
+    </div>
+  </section>`,
+  views: {
+    listEntry: html`<div
+      @if.class=".selected"
+      @then="'list-row cursor-pointer text-blue-400 hover:text-blue-500 font-semibold'"
+      @else="'list-row cursor-pointer hover:bg-base-200'"
+      :title=".description"
+      @on.click="onListItemClick"
+    >
+      <div @text=".title" class="list-col-grow"></div>
+      <p
+        class="text-xs opacity-60 list-col-wrap truncate"
+        @text=".description"
+      ></p>
+    </div> `
+  }
+});
+var Example = component({
+  name: "Example",
+  fields: { id: "?", title: "?", description: "", value: null, view: "main" },
+  statics: {
+    fromData({ id, title = "No Title Example", description = "", value = null, view = "main" }) {
+      id ??= slugify(title);
+      return this.make({
+        id,
+        title,
+        description,
+        value,
+        view
+      });
+    }
+  },
+  input: {
+    onLogSelected() {
+      console.log(this.value);
+      return this;
+    },
+    onFocusSelected(ctx) {
+      ctx.bubble("exampleFocusRequested", [this]);
+      return this;
+    }
+  },
+  view: html`<div class="card card-border bg-base-100 shadow-md">
+    <div class="card-body">
+      <h2 class="card-title flex justify-between">
+        <a :href="$'#example-{.id}'" :id="$'example-{.id}'" @text=".title"></a>
+        <div class="flex gap-2">
+          <button class="btn btn-ghost btn-sm" @on.click="onFocusSelected">
+            focus
+          </button>
+          <button class="btn btn-ghost btn-sm" @on.click="onLogSelected">
+            log
+          </button>
+        </div>
+      </h2>
+      <p class="text-md italic opacity-60" @text=".description"></p>
+      <div class="bg-base-100 p-3" @push-view=".view">
+        <x render=".value"></x>
+      </div>
+    </div>
+  </div>`
+});
+function fuzzyMatch(query, target) {
+  const q = query.toLowerCase(), t = target.toLowerCase();
+  let qi = 0;
+  for (let ti = 0;ti < t.length && qi < q.length; ti++) {
+    if (t[ti] === q[qi])
+      qi++;
+  }
+  return qi === q.length;
+}
+function slugify(str) {
+  return String(str).normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function buildStorybook(modules) {
+  const sections = modules.map((m) => Section.Class.fromData(m.getExamples())).sort((a, b) => a.title.localeCompare(b.title));
+  const components = new Set([Storybook, Section, Example]);
+  const macros = {};
+  const requestHandlers = {};
+  for (const m of modules) {
+    for (const c of m.getComponents?.() ?? []) {
+      components.add(c);
+    }
+    if (m.getMacros)
+      Object.assign(macros, m.getMacros());
+    if (m.getRequestHandlers)
+      Object.assign(requestHandlers, m.getRequestHandlers());
+  }
+  return {
+    root: Storybook.make({ sections }),
+    components: [...components],
+    macros,
+    requestHandlers
+  };
+}
+async function mountStorybook(selector, modules, { compileCss, root } = {}) {
+  const app = tutuca(selector);
+  const built = buildStorybook(modules);
+  app.state.set(root ?? built.root);
+  const scope = app.registerComponents(built.components);
+  scope.registerMacros(built.macros);
+  scope.registerRequestHandlers(built.requestHandlers);
+  if (compileCss) {
+    injectCss("tutuca-storybook", await compileCss(app));
+  }
+  app.start();
+  return app;
+}
+function getComponents() {
+  return [Storybook, Section, Example];
+}
+export {
+  slugify,
+  mountStorybook,
+  getComponents,
+  fuzzyMatch,
+  buildStorybook,
+  Storybook,
+  Section,
+  Example
+};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.83",
+  "version": "0.9.84",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -13,6 +13,7 @@
     "./ext": "./dist/tutuca.ext.js",
     "./extra-ext": "./dist/tutuca-extra.ext.js",
     "./dev-ext": "./dist/tutuca-dev.ext.js",
+    "./storybook": "./dist/tutuca-storybook.js",
     "./immutable": "./dist/immutable.js",
     "./chai": "./dist/chai.js",
     "./package.json": "./package.json"
@@ -54,6 +55,7 @@
     "dist/tutuca.ext.js",
     "dist/tutuca-extra.ext.js",
     "dist/tutuca-dev.ext.js",
+    "dist/tutuca-storybook.js",
     "dist/immutable.js",
     "dist/chai.js",
     "skill"

package/skill/tutuca/core.md CHANGED Viewed

@@ -977,6 +977,17 @@ export function getExamples()         {
 export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```
+Best practice: have `getComponents()` return **every** component the module
+defines — child and helper components included — and give each one at least
+one item in `getExamples()`. A component left out of `getComponents()` is
+invisible to `tutuca lint`/`render`/`test`, so it silently loses linting and
+render coverage. If your components already live behind a differently named
+export, alias it instead of teaching tools a new name:
+```js
+export { allMyComponents as getComponents } from "./app.js";
+```
 ## See also
 - [component-design.md](./component-design.md) — design judgment for shaping a