@bitbaum/sitekit 0.3.0

package/dist/schema.js

@@ -0,0 +1,288 @@
+/**
+ * The content model: a site is pages, a page is sections, and sections come
+ * from a small CLOSED set of shapes.
+ *
+ * The closed set is the design, not a limitation. A generator emitting data
+ * against this schema is a task with a machine-checkable result; a generator
+ * emitting components is not. Per-site quality becomes a property of the
+ * renderers — fixing one renderer improves every site ever generated.
+ *
+ * Zod is the single source of truth here: every TypeScript type is inferred
+ * from its schema, never written twice. Extracted from substrata's
+ * `config/site-content.ts` (2026-08-26), which remains the reference consumer.
+ */
+import { z } from 'zod';
+import { provenanceSchema } from './provenance.js';
+// =====================================================================
+// SECTION PARTS
+// =====================================================================
+/** A stat worth putting at the top of a page. */
+export const siteStatSchema = z.object({
+    label: z.string().min(1),
+    value: z.string().min(1),
+    note: z.string().optional(),
+});
+export const siteCardSchema = z.object({
+    title: z.string().min(1),
+    body: z.string().min(1),
+    /** Short trailing line — a price, a status, a jurisdiction. */
+    meta: z.string().optional(),
+    /** Small decorative glyph above the title, e.g. an emoji. Rendered aria-hidden. */
+    icon: z.string().optional(),
+});
+export const siteDefinitionSchema = z.object({
+    term: z.string().min(1),
+    detail: z.string().min(1),
+});
+export const siteIndexEntrySchema = z.object({
+    label: z.string().min(1),
+    /** Small trailing figure — a count, a desk name. Rendered in mono. */
+    meta: z.string().optional(),
+    /** Fragment this entry jumps to; must match a section's `anchor` on the same page. */
+    anchor: z.string().min(1),
+});
+/** A call to action: what the button says and where it goes. */
+export const siteActionSchema = z.object({
+    label: z.string().min(1),
+    /** A path, a fragment ('#sortiment'), or a full URL. */
+    href: z.string().min(1),
+});
+export const siteImageSchema = z.object({
+    src: z.string().min(1),
+    /** Required — a generated site does not get to skip accessibility. */
+    alt: z.string(),
+});
+/**
+ * A physical place. These are exactly the fields the provenance rules exist
+ * to protect: a plausible-but-wrong address or opening time is the one detail
+ * that actively damages the business a site is about.
+ */
+export const siteLocationSchema = z.object({
+    name: z.string().min(1),
+    /** Eyebrow over the name — 'Sonntags geöffnet', 'Nur Take-away'. */
+    note: z.string().optional(),
+    address: z.string().min(1),
+    phone: z.string().optional(),
+    hours: z.array(z.string().min(1)).optional(),
+});
+export const siteFaqItemSchema = z.object({
+    question: z.string().min(1),
+    answer: z.string().min(1),
+});
+/** Fragment id shared by every section a reader can jump to. */
+const anchor = z.string().min(1).optional();
+// =====================================================================
+// SECTIONS
+// =====================================================================
+/**
+ * Opens a page in place of the standard title block. An eyebrow, one display
+ * statement, and the lead. Only ever the FIRST section of a page — the page
+ * schema enforces it, and the shell suppresses its own header when present so
+ * the two cannot both render.
+ */
+export const heroSectionSchema = z.object({
+    kind: z.literal('hero'),
+    eyebrow: z.string().optional(),
+    statement: z.string().min(1),
+    lead: z.array(z.string().min(1)),
+    /** CTAs. The first renders filled, the rest outlined. A publication has none; a bakery has two. */
+    actions: z.array(siteActionSchema).optional(),
+});
+export const proseSectionSchema = z.object({
+    kind: z.literal('prose'),
+    heading: z.string().optional(),
+    anchor,
+    paragraphs: z.array(z.string().min(1)).min(1),
+});
+export const statsSectionSchema = z.object({
+    kind: z.literal('stats'),
+    heading: z.string().optional(),
+    anchor,
+    stats: z.array(siteStatSchema).min(1),
+});
+/**
+ * One number that deserves a picture. The gap between `value` and `of` IS the
+ * message — an empty bar is the honest rendering of "nothing sourced yet",
+ * and it should look empty.
+ */
+export const meterSectionSchema = z.object({
+    kind: z.literal('meter'),
+    heading: z.string().optional(),
+    anchor,
+    label: z.string().min(1),
+    value: z.number().nonnegative(),
+    of: z.number().nonnegative(),
+    caption: z.string().optional(),
+});
+export const cardsSectionSchema = z.object({
+    kind: z.literal('cards'),
+    heading: z.string().optional(),
+    blurb: z.string().optional(),
+    anchor,
+    columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    cards: z.array(siteCardSchema).min(1),
+});
+export const definitionsSectionSchema = z.object({
+    kind: z.literal('definitions'),
+    heading: z.string().optional(),
+    blurb: z.string().optional(),
+    anchor,
+    items: z.array(siteDefinitionSchema).min(1),
+});
+/**
+ * A split: a figure (or just space) beside a story. The founder, the
+ * workshop, the thing that makes this business this business. The one
+ * section on a small-business site that is allowed to be personal.
+ */
+export const featureSectionSchema = z.object({
+    kind: z.literal('feature'),
+    heading: z.string().optional(),
+    anchor,
+    paragraphs: z.array(z.string().min(1)).min(1),
+    /** Set in quotation marks by the renderer — do not quote it yourself. */
+    quote: z.string().optional(),
+    cta: siteActionSchema.optional(),
+    image: siteImageSchema.optional(),
+});
+/** Where the business actually is. See `siteLocationSchema` on why this exists. */
+export const contactSectionSchema = z.object({
+    kind: z.literal('contact'),
+    heading: z.string().optional(),
+    blurb: z.string().optional(),
+    anchor,
+    locations: z.array(siteLocationSchema).min(1),
+});
+export const faqSectionSchema = z.object({
+    kind: z.literal('faq'),
+    heading: z.string().optional(),
+    anchor,
+    items: z.array(siteFaqItemSchema).min(1),
+});
+/** Jump list for a long page. Without one, fifteen tables is a scroll, not a document. */
+export const indexSectionSchema = z.object({
+    kind: z.literal('index'),
+    heading: z.string().optional(),
+    blurb: z.string().optional(),
+    entries: z.array(siteIndexEntrySchema).min(1),
+});
+export const tableSectionSchema = z.object({
+    kind: z.literal('table'),
+    heading: z.string().optional(),
+    blurb: z.string().optional(),
+    /** Fragment id, so an `index` entry can link straight here. */
+    anchor: z.string().optional(),
+    columns: z.array(z.string()).min(1),
+    rows: z.array(z.array(z.string())),
+    /** Column indices rendered in mono — codes, figures, statuses. */
+    monoColumns: z.array(z.number().int().nonnegative()).optional(),
+    /** Column index whose cell text is also a status keyword to dot-colour. */
+    statusColumn: z.number().int().nonnegative().optional(),
+    note: z.string().optional(),
+});
+export const siteSectionSchema = z.discriminatedUnion('kind', [
+    heroSectionSchema,
+    proseSectionSchema,
+    statsSectionSchema,
+    meterSectionSchema,
+    cardsSectionSchema,
+    definitionsSectionSchema,
+    featureSectionSchema,
+    contactSectionSchema,
+    faqSectionSchema,
+    indexSectionSchema,
+    tableSectionSchema,
+]);
+// =====================================================================
+// PAGES AND CHROME
+// =====================================================================
+export const sitePageSchema = z
+    .object({
+    /** '' is the home page; otherwise a single path segment, e.g. 'map'. */
+    path: z.string().regex(/^[a-z0-9-]*$/, 'a single lowercase path segment, or "" for home'),
+    /** Label in the site's own navigation. Omit to keep a page out of the nav. */
+    navLabel: z.string().optional(),
+    /** <title> and the page's h1. */
+    title: z.string().min(1),
+    /** One line under the h1. */
+    intro: z.string().optional(),
+    sections: z.array(siteSectionSchema).min(1),
+})
+    .superRefine((page, ctx) => {
+    page.sections.forEach((section, i) => {
+        if (section.kind === 'hero' && i > 0) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['sections', i],
+                message: 'a hero opens a page; it can only be the first section',
+            });
+        }
+    });
+});
+/** Everything the site chrome needs: the masthead, the nav, the footer. */
+export const siteChromeSchema = z.object({
+    name: z.string().min(1),
+    tagline: z.string().min(1),
+    /** Line in the footer — who runs this and under what rules. */
+    footerNote: z.string().min(1),
+    /** Canonical host shown in the footer, e.g. 'substrata.orangecat.ch'. */
+    host: z.string().optional(),
+});
+/**
+ * One object a generator emits: the whole site, plus (optionally) where every
+ * field of it came from. This is the machine-checkable boundary between "a
+ * model wrote something" and "a site we can stand behind".
+ */
+export const siteSpecSchema = z
+    .object({
+    chrome: siteChromeSchema,
+    pages: z.array(sitePageSchema).min(1),
+    provenance: provenanceSchema.optional(),
+})
+    .superRefine((spec, ctx) => {
+    const seen = new Set();
+    spec.pages.forEach((page, i) => {
+        if (seen.has(page.path)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['pages', i, 'path'],
+                message: `duplicate page path '${page.path || '(home)'}'`,
+            });
+        }
+        seen.add(page.path);
+        // An index entry that points at nothing is a dead link the reader will
+        // actually click — checked per page, where the fragments live. Hero
+        // actions get the same check when they point at a fragment.
+        const anchors = new Set(page.sections.flatMap((s) => ('anchor' in s && s.anchor ? [s.anchor] : [])));
+        page.sections.forEach((section, j) => {
+            if (section.kind !== 'hero' || !section.actions)
+                return;
+            section.actions.forEach((action, k) => {
+                if (action.href.startsWith('#') && !anchors.has(action.href.slice(1))) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['pages', i, 'sections', j, 'actions', k, 'href'],
+                        message: `action points at '${action.href}', but no section on this page carries that anchor`,
+                    });
+                }
+            });
+        });
+        page.sections.forEach((section, j) => {
+            if (section.kind !== 'index')
+                return;
+            section.entries.forEach((entry, k) => {
+                if (!anchors.has(entry.anchor)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        path: ['pages', i, 'sections', j, 'entries', k, 'anchor'],
+                        message: `index entry points at '#${entry.anchor}', but no section on this page carries that anchor`,
+                    });
+                }
+            });
+        });
+    });
+});
+/** Nav entry: a label and where it goes, nothing more. */
+export const siteNavItemSchema = z.object({
+    path: z.string(),
+    label: z.string().min(1),
+});

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@bitbaum/sitekit",
+  "version": "0.3.0",
+  "description": "A website as data: a closed union of section shapes validated at runtime, one set of React renderers, and per-field provenance so a generated site can prove it fabricated nothing.",
+  "license": "MIT",
+  "author": "Mao Nakamoto",
+  "homepage": "https://github.com/bitbaum/sitekit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitbaum/sitekit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bitbaum/sitekit/issues"
+  },
+  "keywords": [
+    "site-generator",
+    "content-model",
+    "sections",
+    "zod",
+    "react",
+    "headless-cms"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.4.1",
+    "@types/react": "^19.0.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.12.0",
+    "prettier": "3.9.6",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.69.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.js",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run build && pnpm test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}