@codepress/design-kit 0.1.0 → 0.1.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@codepress/design-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Capture your Storybook and real app pages as a static design kit, and compose self-contained mockups from it",
   "type": "module",
   "bin": {
-    "design-kit": "./bin/design-kit.mjs"
+    "design-kit": "bin/design-kit.mjs"
   },
   "main": "./src/index.mjs",
   "types": "./src/index.d.ts",
@@ -13,7 +13,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.mjs"
     },
-    "./kit": "./src/kit.mjs",
+    "./kit": {
+      "types": "./src/kit.d.ts",
+      "default": "./src/kit.mjs"
+    },
     "./schema.json": "./schema/design-kit.config.schema.json",
     "./package.json": "./package.json"
   },

package/src/kit.d.ts

@@ -0,0 +1,81 @@
+/** Types for `@codepress/design-kit/kit`, the kit tool's functions. */
+
+/** One row of `index.json` (stories) or `routes.json` (pages). */
+export interface KitRow {
+  id: string;
+  kind?: "story" | "route";
+  title?: string;
+  component?: string;
+  file: string;
+  width?: number;
+  height?: number;
+  bytes?: number;
+  slots?: string[];
+  source_file?: string;
+  body_class?: string;
+  html_attrs?: Record<string, string>;
+  body_attrs?: Record<string, string>;
+}
+
+export interface KitManifest {
+  kit_version?: number;
+  sha?: string;
+  built_at?: string;
+  [key: string]: unknown;
+}
+
+/** A loaded kit: its folder, manifest and rows, sorted and by id. */
+export interface Kit {
+  dir: string;
+  manifest: KitManifest | null;
+  rows: KitRow[];
+  byId: Map<string, KitRow>;
+}
+
+export function loadKit(dir: string): Kit;
+
+/** Rows whose id, title, component or source file holds every word. */
+export function find(kit: Kit, query: string): KitRow[];
+
+/** Up to five candidates, closest first. */
+export function nearMatches(wanted: string, candidates: string[]): string[];
+
+/** A markup outline of at most `limit` bytes. */
+export function outline(
+  html: string,
+  limit?: number,
+): { lines: string[]; truncated: boolean };
+
+/**
+ * One self-contained page. Throws an Error whose message starts with
+ * `unknown ` (and names near matches) for an unknown frame, slot or snippet,
+ * and with `too large: ` when snippets grow the page past `maxBytes`.
+ */
+export function compose(
+  kit: Kit,
+  options: {
+    frame: string;
+    slots?: { name: string; content: string }[];
+    theme?: "light" | "dark";
+    showNew?: boolean;
+    /** Bytes of markup the page may grow to through snippets. */
+    maxBytes?: number;
+  },
+): string;
+
+/** The default `maxBytes` of `compose`: 32 MB. */
+export const COMPOSE_MAX_BYTES: number;
+
+export function sanitizeMarkup(html: string): string;
+export function sanitizeCss(css: string): string;
+
+/** Runs one command line; returns the exit code. */
+export function run(
+  argv: string[],
+  io?: { out(text: string): void; err(text: string): void },
+  env?: Record<string, string | undefined>,
+  defaultDir?: string,
+): number;
+
+/** Whether this file is the script node was started with. */
+export function isMain(moduleUrl?: string, script?: string): boolean;

package/src/kit.mjs

@@ -19,6 +19,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const FIND_LIMIT = 30;
 const SHOW_LIMIT = 2048;
 const SNIPPET_DEPTH = 8;
+/**
+ * Bytes of markup one compose may read through <kit-snippet>s. Nesting is
+ * capped, but a file of many placeholders pointing at large rows would
+ * otherwise grow the page exponentially.
+ */
+export const COMPOSE_MAX_BYTES = 32 * 1024 * 1024;
 
 class KitError extends Error {}
 
@@ -672,7 +678,7 @@ export function inlineAssets(kit, css, cssDir = join(kit.dir, "css")) {
 
 // ── compose ─────────────────────────────────────────────────────────────────
 
-function expandSnippets(kit, html, used, depth = 0) {
+function expandSnippets(kit, html, used, budget, depth = 0) {
   const found = elements(html).filter((e) => e.name === "kit-snippet");
   if (!found.length) return html;
   if (depth >= SNIPPET_DEPTH) {
@@ -689,10 +695,16 @@ function expandSnippets(kit, html, used, depth = 0) {
     const row = requireRow(kit, id, "<kit-snippet id>");
     used.add(rowSource(row));
     let markup = readSnippet(kit, row);
+    budget.left -= markup.length;
+    if (budget.left < 0) {
+      throw new KitError(
+        `too large: the page grows past ${budget.max} bytes while expanding <kit-snippet> elements; use fewer or smaller snippets.`,
+      );
+    }
     if (rowSource(row) === "stories") markup = unwrapStoryRoot(markup);
     out +=
       html.slice(i, element.start) +
-      expandSnippets(kit, markup, used, depth + 1);
+      expandSnippets(kit, markup, used, budget, depth + 1);
     i = element.end;
   }
   return out + html.slice(i);
@@ -815,7 +827,13 @@ function attributes(captured, extraClass, theme, choice, target, fixed) {
  */
 export function compose(
   kit,
-  { frame, slots = [], theme = "light", showNew = false },
+  {
+    frame,
+    slots = [],
+    theme = "light",
+    showNew = false,
+    maxBytes = COMPOSE_MAX_BYTES,
+  },
 ) {
   const row = requireRow(kit, frame, "frame");
   if (theme !== "light" && theme !== "dark") {
@@ -823,7 +841,10 @@ export function compose(
   }
   const used = new Set([rowSource(row)]);
   const filled = fillSlots(kit, row, readSnippet(kit, row), slots);
-  const body = expandSnippets(kit, filled, used);
+  const body = expandSnippets(kit, filled, used, {
+    left: maxBytes - filled.length,
+    max: maxBytes,
+  });
 
   const css = ["stories", "routes"]
     .filter((source) => used.has(source))
@@ -1069,16 +1090,27 @@ export function run(
   }
 }
 
-/** Whether this file is the script node was started with (symlinks resolved). */
-function isMain() {
-  if (!process.argv[1]) return false;
+/**
+ * Whether this file is the script node was started with (symlinks resolved).
+ * Only a file named `kit.mjs` can be: a bundler that inlines this module into
+ * another program keeps `import.meta.url` pointing at that program, which is
+ * also the script node started, and the program would then run the kit's
+ * command line on its own arguments.
+ */
+export function isMain(moduleUrl = import.meta.url, script = process.argv[1]) {
+  if (!script) return false;
+  let self;
   try {
-    return (
-      realpathSync(fileURLToPath(import.meta.url)) ===
-      realpathSync(resolve(process.argv[1]))
-    );
+    self = fileURLToPath(moduleUrl);
+  } catch {
+    // Not a file URL: an evaluated bundle, never the script node started.
+    return false;
+  }
+  if (basename(self) !== "kit.mjs") return false;
+  try {
+    return realpathSync(self) === realpathSync(resolve(script));
   } catch {
-    return import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+    return moduleUrl === pathToFileURL(resolve(script)).href;
   }
 }