@vojtaholik/static-kit-core 1.0.7 → 2.0.0

package/package.json

@@ -1,62 +1,27 @@
 {
   "name": "@vojtaholik/static-kit-core",
-  "version": "1.0.7",
-  "description": "Core library for Static Kit - simple static site framework",
+  "version": "2.0.0",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./vite": {
-      "types": "./dist/vite-config.d.ts",
-      "import": "./dist/vite-config.js"
-    },
-    "./plugins": {
-      "types": "./dist/plugins/index.d.ts",
-      "import": "./dist/plugins/index.js"
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
     }
   },
-  "files": [
-    "dist/",
-    "templates/"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist"
+  "files": ["src"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vojtaholik/module-kit",
+    "directory": "packages/core"
   },
-  "peerDependencies": {
-    "vite": "^7.0.0"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "fast-glob": "^3.3.3",
-    "svgo": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.2.1",
-    "typescript": "~5.9.2",
-    "vite": "^7.1.1"
+    "parse5": "^8.0.0",
+    "zod": "^4.1.13"
   },
-  "keywords": [
-    "static-site",
-    "vite",
-    "html",
-    "scss",
-    "typescript",
-    "components"
-  ],
-  "author": "Vojta Holik <vojta@holik.dev>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vojtaholik/static-kit.git",
-    "directory": "packages/static-kit-core"
-  },
-  "homepage": "https://github.com/vojtaholik/static-kit#readme",
-  "bugs": {
-    "url": "https://github.com/vojtaholik/static-kit/issues"
+  "peerDependencies": {
+    "typescript": "^5"
   }
 }

package/src/block-registry.ts

@@ -0,0 +1,196 @@
+import { z } from "zod/v4";
+import type { LayoutProps } from "./layout.ts";
+import type { SchemaAddress } from "./schema-address.ts";
+
+/**
+ * Context passed to block render functions
+ */
+export interface RenderContext {
+  /** Current page ID */
+  pageId: string;
+  /** Base URL for assets */
+  assetBase: string;
+  /** Whether we're in dev mode */
+  isDev: boolean;
+  /** Layout props for styling context */
+  layout: LayoutProps;
+}
+
+/**
+ * Input to block render function
+ */
+export interface RenderBlockInput<T extends z.ZodType = z.ZodType> {
+  /** Validated block props */
+  props: z.infer<T>;
+  /** Render context */
+  ctx: RenderContext;
+  /** Schema address for CMS editing */
+  addr: SchemaAddress;
+}
+
+/**
+ * Block definition - ties together type, schema, and render function
+ */
+export interface BlockDefinition<T extends z.ZodType = z.ZodType> {
+  type: string;
+  propsSchema: T;
+  renderHtml: (input: RenderBlockInput<T>) => string;
+  /** Source file path (for dev inspector) - pass import.meta.url */
+  sourceFile?: string;
+}
+
+/**
+ * Define a block with type-safe props
+ * Pass `sourceFile: import.meta.url` to enable click-to-open in dev inspector
+ */
+export function defineBlock<T extends z.ZodType>(config: {
+  type: string;
+  propsSchema: T;
+  renderHtml: (input: RenderBlockInput<T>) => string;
+  /** Source file path - pass import.meta.url */
+  sourceFile?: string;
+}): BlockDefinition<T> {
+  return {
+    type: config.type,
+    propsSchema: config.propsSchema,
+    renderHtml: config.renderHtml,
+    sourceFile: config.sourceFile,
+  };
+}
+
+/**
+ * Registry of all block definitions
+ */
+export class BlockRegistry {
+  private blocks = new Map<string, BlockDefinition>();
+
+  register<T extends z.ZodType>(definition: BlockDefinition<T>): void {
+    if (this.blocks.has(definition.type)) {
+      throw new Error(`Block type "${definition.type}" is already registered`);
+    }
+    this.blocks.set(definition.type, definition as BlockDefinition);
+  }
+
+  get(type: string): BlockDefinition | undefined {
+    return this.blocks.get(type);
+  }
+
+  getOrThrow(type: string): BlockDefinition {
+    const block = this.blocks.get(type);
+    if (!block) {
+      throw new Error(`Unknown block type: "${type}"`);
+    }
+    return block;
+  }
+
+  has(type: string): boolean {
+    return this.blocks.has(type);
+  }
+
+  all(): BlockDefinition[] {
+    return Array.from(this.blocks.values());
+  }
+
+  types(): string[] {
+    return Array.from(this.blocks.keys());
+  }
+
+  clear(): void {
+    this.blocks.clear();
+  }
+}
+
+/**
+ * Global block registry instance
+ */
+export const blockRegistry = new BlockRegistry();
+
+/**
+ * HTML escape helper for templates
+ */
+export function escapeHtml(str: unknown): string {
+  if (str === null || str === undefined) return "";
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Escape for use in HTML attributes
+ */
+export function escapeAttr(str: unknown): string {
+  return escapeHtml(str);
+}
+
+/**
+ * Format a slot error for dev overlay display
+ */
+function formatSlotError(
+  type: "not-found" | "validation",
+  blockType: string,
+  addr: SchemaAddress,
+  details?: string
+): string {
+  const errorData = JSON.stringify({
+    type,
+    blockType,
+    addr,
+    details,
+  });
+  // Hidden element that dev overlay will pick up
+  return `<script type="application/json" data-slot-error>${escapeHtml(
+    errorData
+  )}</script>`;
+}
+
+/**
+ * Render a slot with optional block delegation
+ *
+ * If blockType is provided and valid, renders that block with slotProps.
+ * Otherwise, renders the fallback content.
+ *
+ * @param blockType - Block type string to delegate rendering to (optional)
+ * @param slotProps - Props to pass to the delegated block
+ * @param ctx - Render context
+ * @param addr - Schema address for CMS editing
+ * @param fallback - Function that returns fallback HTML if no block specified
+ */
+export function renderSlot(
+  blockType: string | undefined,
+  slotProps: Record<string, unknown>,
+  ctx: RenderContext,
+  addr: SchemaAddress,
+  fallback: () => string
+): string {
+  if (!blockType) return fallback();
+
+  const block = blockRegistry.get(blockType);
+  if (!block) {
+    const msg = `renderSlot: Unknown block type "${blockType}", using fallback`;
+    console.warn(msg);
+    const errorHtml = ctx.isDev
+      ? formatSlotError("not-found", blockType, addr)
+      : "";
+    return errorHtml + fallback();
+  }
+
+  const result = block.propsSchema.safeParse(slotProps);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `${i.path.join(".")}: ${i.message}`)
+      .join("; ");
+    console.warn(
+      `renderSlot: Props validation failed for "${blockType}", using fallback:`,
+      issues
+    );
+    const errorHtml = ctx.isDev
+      ? formatSlotError("validation", blockType, addr, issues)
+      : "";
+    return errorHtml + fallback();
+  }
+
+  return block.renderHtml({ props: result.data, ctx, addr });
+}

package/src/config.ts

@@ -0,0 +1,32 @@
+import { z } from "zod/v4";
+
+/**
+ * Static Kit configuration schema
+ */
+export const configSchema = z.object({
+  /** Directory containing block definitions and templates */
+  blocksDir: z.string().default("blocks"),
+  /** Directory containing page configs and templates */
+  pagesDir: z.string().default("site/pages"),
+  /** Source directory for public assets (css, js, images) - structure mirrors output */
+  publicDir: z.string().default("public"),
+  /** Output directory for built site */
+  outDir: z.string().default("dist"),
+  /** URL path prefix where public assets are served */
+  publicPath: z.string().default("/public"),
+  /** Dev server port */
+  devPort: z.number().default(3000),
+  /** Path to cms-blocks file (relative to project root) */
+  cmsBlocksFile: z.string().optional(),
+});
+
+export type StaticKitConfig = z.infer<typeof configSchema>;
+
+/**
+ * Define a Static Kit configuration with type-safe defaults
+ */
+export function defineConfig(
+  config: z.input<typeof configSchema> = {}
+): StaticKitConfig {
+  return configSchema.parse(config);
+}

package/src/html-renderer.ts

@@ -0,0 +1,288 @@
+import * as parse5 from "parse5";
+import type { LayoutProps } from "./layout.ts";
+import { layoutPropsSchema } from "./layout.ts";
+import { blockRegistry, type RenderContext } from "./block-registry.ts";
+import type { SchemaAddress } from "./schema-address.ts";
+
+/**
+ * Block instance in a page config
+ */
+export interface BlockInstance {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  layout?: Partial<LayoutProps>;
+}
+
+/**
+ * Region config - blocks in a named region
+ */
+export interface RegionConfig {
+  blocks: BlockInstance[];
+}
+
+/**
+ * Page configuration
+ */
+export interface PageConfig {
+  id: string;
+  path: string;
+  title: string;
+  template: string;
+  density?: "compact" | "comfortable" | "relaxed";
+  regions: Record<string, RegionConfig>;
+  meta?: Record<string, string>;
+}
+
+interface Element {
+  nodeName: string;
+  tagName?: string;
+  attrs?: Array<{ name: string; value: string }>;
+  childNodes?: Node[];
+  value?: string;
+  data?: string;
+  parentNode?: Node;
+}
+
+type Node = Element;
+
+/**
+ * Options for rendering a page
+ */
+export interface RenderPageOptions {
+  /** Directory containing page templates */
+  templateDir: string;
+  /** Whether we're in dev mode (injects dev overlay) */
+  isDev?: boolean;
+  /** Base URL for assets */
+  assetBase?: string;
+  /** Function to read template file content */
+  readFile?: (path: string) => Promise<string>;
+}
+
+/**
+ * Render a page from its config
+ */
+export async function renderPage(
+  page: PageConfig,
+  options: RenderPageOptions
+): Promise<string> {
+  const templatePath = `${options.templateDir}/${page.template}`;
+
+  // Use provided readFile or default to Bun.file
+  const readFile =
+    options.readFile ?? (async (path: string) => await Bun.file(path).text());
+  const templateHtml = await readFile(templatePath);
+
+  // Parse the template
+  const document = parse5.parse(templateHtml) as Element;
+
+  // Track regions and their rendered content
+  const regionContent: Record<string, string> = {};
+
+  // Find and update elements
+  walkTree(document, (node) => {
+    // Update <title>
+    if (node.nodeName === "title") {
+      const textNode = node.childNodes?.[0];
+      if (textNode && textNode.nodeName === "#text") {
+        textNode.value = page.title;
+      }
+    }
+
+    // Update <html> attributes
+    if (node.nodeName === "html") {
+      setAttr(node, "data-page-id", page.id);
+      // if (page.density) {
+      //   setAttr(node, "data-density", page.density);
+      // }
+    }
+
+    // Process regions - inject a marker that we'll replace after serialization
+    const regionName = getAttr(node, "data-region");
+    if (regionName) {
+      const regionConfig = page.regions[regionName];
+      if (regionConfig) {
+        // Render blocks for this region
+        regionContent[regionName] = renderRegionBlocks(regionConfig, {
+          pageId: page.id,
+          region: regionName,
+          isDev: options.isDev ?? false,
+          assetBase: options.assetBase ?? "/",
+        });
+
+        // Insert a marker that won't get escaped
+        node.childNodes = [
+          {
+            nodeName: "#comment",
+            data: `__REGION_CONTENT_${regionName}__`,
+          } as Node,
+        ];
+      }
+    }
+  });
+
+  // Serialize to HTML
+  let html = parse5.serialize(
+    document as unknown as parse5.DefaultTreeAdapterMap["parentNode"]
+  );
+
+  // Replace markers with actual region content
+  for (const [regionName, content] of Object.entries(regionContent)) {
+    const marker = `<!--__REGION_CONTENT_${regionName}__-->`;
+    html = html.replace(marker, content);
+  }
+
+  // Inject dev overlay if in dev mode
+  if (options.isDev) {
+    html = injectDevOverlay(html);
+  }
+
+  return html;
+}
+
+/**
+ * Render all blocks in a region
+ */
+function renderRegionBlocks(
+  region: RegionConfig,
+  context: {
+    pageId: string;
+    region: string;
+    isDev: boolean;
+    assetBase: string;
+  }
+): string {
+  let html = "";
+
+  for (const block of region.blocks) {
+    const definition = blockRegistry.get(block.type);
+    if (!definition) {
+      console.warn(`Unknown block type: ${block.type}`);
+      continue;
+    }
+
+    // Validate and parse props
+    const propsResult = definition.propsSchema.safeParse(block.props);
+    if (!propsResult.success) {
+      const issues = propsResult.error.issues
+        .map((i) => `${i.path.join(".")}: ${i.message}`)
+        .join("; ");
+      console.warn(`Invalid props for block ${block.id}: ${issues}`);
+      continue;
+    }
+
+    // Build layout props
+    const layout = layoutPropsSchema.parse(block.layout ?? {});
+
+    // Build render context
+    const ctx: RenderContext = {
+      pageId: context.pageId,
+      assetBase: context.assetBase,
+      isDev: context.isDev,
+      layout,
+    };
+
+    // Build schema address
+    const addr: SchemaAddress = {
+      pageId: context.pageId,
+      region: context.region,
+      blockId: block.id,
+    };
+
+    // Render the block
+    html += definition.renderHtml({
+      props: propsResult.data,
+      ctx,
+      addr,
+    });
+  }
+
+  return html;
+}
+
+/**
+ * Walk the parse5 tree
+ */
+function walkTree(node: Node, callback: (node: Node) => void): void {
+  callback(node);
+  if (node.childNodes) {
+    for (const child of node.childNodes) {
+      walkTree(child, callback);
+    }
+  }
+}
+
+/**
+ * Get attribute value
+ */
+function getAttr(node: Node, name: string): string | undefined {
+  const element = node as Element;
+  const attr = element.attrs?.find((a) => a.name === name);
+  return attr?.value;
+}
+
+/**
+ * Set attribute value
+ */
+function setAttr(node: Node, name: string, value: string): void {
+  const element = node as Element;
+  if (!element.attrs) {
+    element.attrs = [];
+  }
+  const existing = element.attrs.find((a) => a.name === name);
+  if (existing) {
+    existing.value = value;
+  } else {
+    element.attrs.push({ name, value });
+  }
+}
+
+/**
+ * Inject dev overlay script
+ */
+function injectDevOverlay(html: string): string {
+  const script = `<script src="/__dev-overlay.js"></script>`;
+  return html.replace("</body>", `${script}</body>`);
+}
+
+/**
+ * Render a standalone block (for API/preview)
+ */
+export function renderBlock(
+  block: BlockInstance,
+  context: {
+    pageId: string;
+    region: string;
+    isDev: boolean;
+    assetBase: string;
+  }
+): string {
+  const definition = blockRegistry.getOrThrow(block.type);
+
+  const propsResult = definition.propsSchema.safeParse(block.props);
+  if (!propsResult.success) {
+    throw new Error(`Invalid props: ${propsResult.error.message}`);
+  }
+
+  const layout = layoutPropsSchema.parse(block.layout ?? {});
+
+  const ctx: RenderContext = {
+    pageId: context.pageId,
+    assetBase: context.assetBase,
+    isDev: context.isDev,
+    layout,
+  };
+
+  const addr: SchemaAddress = {
+    pageId: context.pageId,
+    region: context.region,
+    blockId: block.id,
+  };
+
+  return definition.renderHtml({
+    props: propsResult.data,
+    ctx,
+    addr,
+  });
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+// Layout schemas and types
+export {
+  toneEnum,
+  contentAlignEnum,
+  densityEnum,
+  contentWidthEnum,
+  layoutPropsSchema,
+  type Tone,
+  type ContentAlign,
+  type Density,
+  type ContentWidth,
+  type LayoutProps,
+} from "./layout.ts";
+
+// Schema address utilities
+export {
+  schemaAddressSchema,
+  encodeSchemaAddress,
+  decodeSchemaAddress,
+  withPropPath,
+  isSameBlock,
+  type SchemaAddress,
+} from "./schema-address.ts";
+
+// CMS schema utilities
+export {
+  cmsFieldTypeEnum,
+  cmsFieldSchema,
+  cmsBlockSchemaMapSchema,
+  createSchemaFromCmsFields,
+  createSchemaFromCmsBlocks,
+  type CmsFieldType,
+  type CmsField,
+  type CmsBlockSchema,
+  type CmsBlockSchemaMap,
+} from "./schema.ts";
+
+// Block registry
+export {
+  defineBlock,
+  BlockRegistry,
+  blockRegistry,
+  escapeHtml,
+  escapeAttr,
+  renderSlot,
+  type RenderContext,
+  type RenderBlockInput,
+  type BlockDefinition,
+} from "./block-registry.ts";
+
+// HTML renderer
+export {
+  renderPage,
+  renderBlock,
+  type BlockInstance,
+  type RegionConfig,
+  type PageConfig,
+  type RenderPageOptions,
+} from "./html-renderer.ts";
+
+// Template compiler
+export {
+  compileBlockTemplates,
+  compileTemplateFile,
+  compileTemplate,
+  type CompileOptions,
+} from "./template-compiler.ts";
+
+// Configuration
+export { configSchema, defineConfig, type StaticKitConfig } from "./config.ts";

package/src/layout.ts

@@ -0,0 +1,27 @@
+import { z } from "zod/v4";
+
+// Layout enums - design system tokens for blocks
+export const toneEnum = z.enum(["surface", "raised", "accent", "inverted"]);
+export const contentAlignEnum = z.enum([
+  "left",
+  "center",
+  "right",
+  "split-start",
+  "split-end",
+]);
+export const densityEnum = z.enum(["compact", "comfortable", "relaxed"]);
+export const contentWidthEnum = z.enum(["narrow", "default", "wide"]);
+
+// Combined layout props schema for block rendering context
+export const layoutPropsSchema = z.object({
+  tone: toneEnum.default("surface"),
+  contentAlign: contentAlignEnum.default("left"),
+  density: densityEnum.default("comfortable"),
+  contentWidth: contentWidthEnum.default("default"),
+});
+
+export type Tone = z.infer<typeof toneEnum>;
+export type ContentAlign = z.infer<typeof contentAlignEnum>;
+export type Density = z.infer<typeof densityEnum>;
+export type ContentWidth = z.infer<typeof contentWidthEnum>;
+export type LayoutProps = z.infer<typeof layoutPropsSchema>;