@stackbox/cms 0.0.2

package/src/pages.ts

@@ -0,0 +1,198 @@
+import type { SiteConfig } from "./site.js";
+import type { Stackbox } from "./stackbox/context.js";
+import {
+  isTemplate,
+  type SlotDefinition,
+  type SlotNamesFrom,
+  type RequiredSlotNamesFrom,
+  type TemplateDescriptor,
+} from "./templates.js";
+import {
+  type DefaultSlotContent,
+  type PageSlotsInput,
+  slotHasContent,
+  SlotContentValidationError,
+  validateSlotContentItem,
+} from "./slot-content.js";
+
+export type PageMeta = {
+  description?: string;
+  robots?: string;
+  canonical?: string;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+  twitterCard?: string;
+};
+
+export type RenderContext = {
+  siteConfig: SiteConfig;
+  ctx?: Stackbox.Context;
+};
+
+export type Page<
+  Slots extends string = string,
+  RequiredSlots extends Slots = never,
+  Definitions extends readonly SlotDefinition[] = readonly SlotDefinition[],
+> = {
+  readonly __kind: "page";
+  path: string;
+  template: TemplateDescriptor<Slots, RequiredSlots, Definitions>;
+  title: string;
+  meta?: PageMeta;
+  slots: PageSlotsInput<Definitions, RequiredSlots>;
+};
+
+/** Widened page type for site builds mixing templates and required slots. */
+export type SitePage = {
+  readonly __kind: "page";
+  path: string;
+  template: TemplateDescriptor<string, string>;
+  title: string;
+  meta?: PageMeta;
+  slots: Partial<Record<string, DefaultSlotContent[]>>;
+};
+
+/** Page fields passed to template render (slot content lives on `slots`). */
+export type PageRenderView = Omit<Page, "template" | "slots">;
+
+export function toPageRenderView({
+  template: _template,
+  slots: _slots,
+  ...view
+}: SitePage): PageRenderView {
+  return view;
+}
+
+export function isPage(value: unknown): value is Page {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Page).__kind === "page" &&
+    typeof (value as Page).path === "string" &&
+    (value as Page).path.length > 0 &&
+    isTemplate((value as Page).template) &&
+    typeof (value as Page).title === "string" &&
+    (value as Page).title.length > 0 &&
+    typeof (value as Page).slots === "object" &&
+    (value as Page).slots !== null
+  );
+}
+
+export class PageValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PageValidationError";
+  }
+}
+
+function validatePagePath(path: string): void {
+  if (!path || !path.startsWith("/")) {
+    throw new PageValidationError('path must start with "/"');
+  }
+  if (path.includes("..")) {
+    throw new PageValidationError("path must not contain '..'");
+  }
+  const lastSegment = path.split("/").pop() ?? "";
+  if (lastSegment.includes(".")) {
+    throw new PageValidationError("path must not include a file extension");
+  }
+}
+
+function validatePageSlotContent(
+  template: TemplateDescriptor<string, string>,
+  slots: Partial<Record<string, DefaultSlotContent[]>>,
+): void {
+  const templateSlotNames = new Set(Object.keys(template.slots));
+
+  for (const key of Object.keys(slots)) {
+    if (!templateSlotNames.has(key)) {
+      throw new PageValidationError(`unknown slot "${key}" for this template`);
+    }
+
+    const items = slots[key];
+    if (!Array.isArray(items)) {
+      throw new PageValidationError(
+        `slot "${key}" must be an array of content items`,
+      );
+    }
+
+    const schema = template.slots[key]?.schema;
+    for (const item of items) {
+      try {
+        validateSlotContentItem(key, item, schema);
+      } catch (err) {
+        if (err instanceof SlotContentValidationError) {
+          throw new PageValidationError(err.message);
+        }
+        throw err;
+      }
+    }
+  }
+}
+
+export function createPage(
+  template: TemplateDescriptor<string, string>,
+  def: {
+    path: string;
+    title: string;
+    meta?: PageMeta;
+    slots: Partial<Record<string, DefaultSlotContent[]>>;
+  },
+): SitePage;
+export function createPage<const S extends readonly SlotDefinition[]>(
+  template: TemplateDescriptor<
+    SlotNamesFrom<S>,
+    RequiredSlotNamesFrom<S>,
+    S
+  >,
+  def: {
+    path: string;
+    title: string;
+    meta?: PageMeta;
+    slots: PageSlotsInput<S, RequiredSlotNamesFrom<S>>;
+  },
+): Page<SlotNamesFrom<S>, RequiredSlotNamesFrom<S>, S>;
+export function createPage(
+  template: TemplateDescriptor<string, string>,
+  def: {
+    path: string;
+    title: string;
+    meta?: PageMeta;
+    slots: Partial<Record<string, DefaultSlotContent[]>>;
+  },
+): SitePage {
+  if (!isTemplate(template)) {
+    throw new PageValidationError(
+      "template must be created with createTemplate()",
+    );
+  }
+
+  validatePagePath(def.path);
+
+  if (!def.title || def.title.trim().length === 0) {
+    throw new PageValidationError("title is required");
+  }
+
+  validatePageSlotContent(template, def.slots);
+
+  for (const required of template.requiredSlots) {
+    const items = def.slots[required as keyof typeof def.slots];
+    if (!items || items.length === 0 || !slotHasContent(items)) {
+      throw new PageValidationError(
+        `required slot "${required}" must have at least one module or non-empty HTML string`,
+      );
+    }
+  }
+
+  return {
+    __kind: "page" as const,
+    path: def.path,
+    template,
+    title: def.title,
+    meta: def.meta,
+    slots: def.slots,
+  };
+}
+
+export { validateSlotContentItem } from "./slot-content.js";

package/src/render-head.ts

@@ -0,0 +1,32 @@
+import { html, type HSHtml } from "@hyperspan/html";
+import type { PageMeta } from "./pages.js";
+
+export function renderStandardHead(input: {
+  title: string;
+  meta?: PageMeta;
+}): HSHtml {
+  const { title, meta = {} } = input;
+  const ogTitle = meta.ogTitle ?? title;
+  const ogDescription = meta.ogDescription ?? meta.description;
+
+  return html`<meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  ${meta.description
+    ? html`<meta name="description" content="${meta.description}">`
+    : ""}
+  ${meta.robots ? html`<meta name="robots" content="${meta.robots}">` : ""}
+  ${meta.canonical
+    ? html`<link rel="canonical" href="${meta.canonical}">`
+    : ""}
+  <meta property="og:title" content="${ogTitle}">
+  ${ogDescription
+    ? html`<meta property="og:description" content="${ogDescription}">`
+    : ""}
+  ${meta.ogImage
+    ? html`<meta property="og:image" content="${meta.ogImage}">`
+    : ""}
+  ${meta.twitterCard
+    ? html`<meta name="twitter:card" content="${meta.twitterCard}">`
+    : ""}`;
+}

package/src/render-page.ts

@@ -0,0 +1,51 @@
+import { renderAsync } from "@hyperspan/html";
+import {
+  type SitePage,
+  type RenderContext,
+  toPageRenderView,
+  PageValidationError,
+} from "./pages.js";
+import type { SiteConfig } from "./site.js";
+import type { Stackbox } from "./stackbox/context.js";
+import { slotHasContent } from "./slot-content.js";
+import { buildPageSlots, RenderError } from "./slot-handle.js";
+import { renderStandardHead } from "./render-head.js";
+
+export { RenderError } from "./slot-handle.js";
+
+function validateRequiredSlots(page: SitePage): void {
+  for (const required of page.template.requiredSlots) {
+    const items = page.slots[required as keyof typeof page.slots];
+    if (!items || items.length === 0 || !slotHasContent(items)) {
+      throw new PageValidationError(
+        `required slot "${required}" must have at least one module or non-empty HTML string`,
+      );
+    }
+  }
+}
+
+export async function renderPage(
+  page: SitePage,
+  siteConfig: SiteConfig,
+  ctx?: Stackbox.Context,
+): Promise<string> {
+  validateRequiredSlots(page);
+
+  const renderCtx: RenderContext = { siteConfig, ctx };
+
+  const slots = buildPageSlots(page, renderCtx);
+
+  const head = renderStandardHead({
+    title: page.template.formatPageTitle(page.title),
+    meta: page.meta,
+  });
+
+  return renderAsync(
+    page.template.render({
+      head,
+      siteConfig,
+      page: toPageRenderView(page),
+      slots,
+    }),
+  );
+}

package/src/routing.ts

@@ -0,0 +1,14 @@
+export function normalizePathname(pathname: string): string {
+  if (pathname === "" || pathname === "/") {
+    return "/";
+  }
+  const trimmed = pathname.replace(/\/+$/, "");
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export function matchPagePath(
+  pathname: string,
+  pagePath: string,
+): boolean {
+  return normalizePathname(pathname) === normalizePathname(pagePath);
+}

package/src/site.ts

@@ -0,0 +1,153 @@
+import type { SitePage } from "./pages.js";
+import { isPage } from "./pages.js";
+import { renderPage } from "./render-page.js";
+import { normalizePathname } from "./routing.js";
+import { createContext } from "./stackbox/context.js";
+
+export type SiteConfig<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  readonly __kind: "siteConfig";
+  readonly config: T;
+};
+
+export type Site<
+  T extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  readonly __kind: "site";
+  readonly siteConfig: SiteConfig<T>;
+  readonly pages: readonly SitePage[];
+  fetch(
+    request: globalThis.Request,
+    env?: Record<string, unknown>,
+  ): Promise<globalThis.Response>;
+};
+
+export class SiteError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SiteError";
+  }
+}
+
+function validateConfigObject(config: unknown, label: string): void {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new SiteError(`${label}: config must be a non-null object`);
+  }
+  if (Object.keys(config).length === 0) {
+    throw new SiteError(`${label}: config must not be empty`);
+  }
+}
+
+export function createSiteConfig<T extends Record<string, unknown>>(
+  config: T,
+): SiteConfig<T> {
+  validateConfigObject(config, "createSiteConfig(config)");
+  return {
+    __kind: "siteConfig" as const,
+    config,
+  };
+}
+
+export function isSiteConfig(value: unknown): value is SiteConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as SiteConfig).__kind === "siteConfig" &&
+    typeof (value as SiteConfig).config === "object" &&
+    (value as SiteConfig).config !== null &&
+    !Array.isArray((value as SiteConfig).config)
+  );
+}
+
+function assertUniquePaths(pages: SitePage[]): void {
+  const seen = new Map<string, string>();
+
+  for (const page of pages) {
+    const existing = seen.get(page.path);
+    if (existing) {
+      throw new SiteError(
+        `duplicate page path "${page.path}" (${existing} and ${page.title})`,
+      );
+    }
+    seen.set(page.path, page.title);
+  }
+}
+
+function buildPageMap(pages: readonly SitePage[]): Map<string, SitePage> {
+  const map = new Map<string, SitePage>();
+  for (const page of pages) {
+    map.set(normalizePathname(page.path), page);
+  }
+  return map;
+}
+
+export function createSite<T extends Record<string, unknown>>(
+  siteConfig: SiteConfig<T>,
+  options: { pages: [SitePage, ...SitePage[]] },
+): Site<T> {
+  if (!isSiteConfig(siteConfig)) {
+    throw new SiteError(
+      "createSite(siteConfig, options): siteConfig must be from createSiteConfig()",
+    );
+  }
+
+  const { pages } = options;
+  if (!Array.isArray(pages) || pages.length === 0) {
+    throw new SiteError(
+      "createSite(siteConfig, options): pages must be a non-empty array",
+    );
+  }
+
+  for (const page of pages) {
+    if (!isPage(page)) {
+      throw new SiteError(
+        "createSite(siteConfig, options): every page must be from createPage()",
+      );
+    }
+  }
+
+  assertUniquePaths(pages);
+
+  const pageMap = buildPageMap(pages);
+
+  return {
+    __kind: "site" as const,
+    siteConfig,
+    pages,
+    async fetch(request, env = {}) {
+      const ctx = createContext(request, env);
+      const method = ctx.req.method;
+
+      if (method !== "GET" && method !== "HEAD") {
+        return ctx.res.text("Method Not Allowed", { status: 405 });
+      }
+
+      const pathname = normalizePathname(ctx.req.url.pathname);
+      const page = pageMap.get(pathname);
+
+      if (!page) {
+        return ctx.res.notFound();
+      }
+
+      const html = await renderPage(page, siteConfig, ctx);
+
+      if (method === "HEAD") {
+        return ctx.res.html("", { status: 200 });
+      }
+
+      return ctx.res.html(html);
+    },
+  };
+}
+
+export function isSite(value: unknown): value is Site {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Site).__kind === "site" &&
+    isSiteConfig((value as Site).siteConfig) &&
+    Array.isArray((value as Site).pages) &&
+    typeof (value as Site).fetch === "function"
+  );
+}

package/src/slot-content.ts

@@ -0,0 +1,77 @@
+import type { z } from "zod";
+import { z as zod } from "zod";
+import { isModule, type Module } from "./modules.js";
+import type { SlotDefinition, SlotNamesFrom } from "./templates.js";
+
+export type DefaultSlotContent = Module | string;
+
+/** Accepts any module or HTML string (default slot content). */
+export const anySlotContentSchema: z.ZodType<DefaultSlotContent> = zod.union([
+  zod.string(),
+  zod.custom<Module>((value) => isModule(value)),
+]);
+
+/** Accepts only HTML strings. */
+export const stringSlotContentSchema = zod.string();
+
+/** Accepts only CMS modules. */
+export const moduleSlotContentSchema: z.ZodType<Module> = zod.custom<Module>(
+  (value) => isModule(value),
+);
+
+export type SlotContentFromDefinition<D extends SlotDefinition> =
+  D extends { options: { schema: infer Schema extends z.ZodTypeAny } }
+    ? z.input<Schema>
+    : DefaultSlotContent;
+
+export type PageSlotsInput<
+  S extends readonly SlotDefinition[],
+  Required extends string,
+> = {
+  [K in Required]: SlotContentFromDefinition<
+    Extract<S[number], { name: K }>
+  >[];
+} & Partial<{
+  [K in Exclude<SlotNamesFrom<S>, Required>]: SlotContentFromDefinition<
+    Extract<S[number], { name: K }>
+  >[];
+}>;
+
+export function validateSlotContentItem(
+  slotName: string,
+  item: unknown,
+  schema: z.ZodTypeAny | undefined,
+): void {
+  if (schema) {
+    const result = schema.safeParse(item);
+    if (!result.success) {
+      throw new SlotContentValidationError(
+        slotName,
+        result.error.message,
+      );
+    }
+    return;
+  }
+
+  if (typeof item !== "string" && !isModule(item)) {
+    throw new SlotContentValidationError(
+      slotName,
+      "expected module or HTML string",
+    );
+  }
+}
+
+export class SlotContentValidationError extends Error {
+  constructor(slotName: string, message: string) {
+    super(`slot "${slotName}" content failed validation: ${message}`);
+    this.name = "SlotContentValidationError";
+  }
+}
+
+export function slotHasContent(items: unknown[]): boolean {
+  return items.some(
+    (item) =>
+      isModule(item) ||
+      (typeof item === "string" && item.trim().length > 0),
+  );
+}

package/src/slot-handle.ts

@@ -0,0 +1,131 @@
+import { html, type HSHtml } from "@hyperspan/html";
+import type { z } from "zod";
+import { isModule } from "./modules.js";
+import type { SitePage, RenderContext } from "./pages.js";
+import {
+  type DefaultSlotContent,
+  type SlotContentFromDefinition,
+  validateSlotContentItem,
+} from "./slot-content.js";
+import type { SlotDefinition, SlotNamesFrom } from "./templates.js";
+
+export class RenderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RenderError";
+  }
+}
+
+export const SLOT_SENTINEL_PREFIX = "<!--__STACKBOX_SLOT__:";
+
+export function slotSentinel(name: string): string {
+  return `${SLOT_SENTINEL_PREFIX}${name}-->`;
+}
+
+type HtmlSafe = ReturnType<typeof html.raw>;
+export type { HSHtml } from "@hyperspan/html";
+export type SlotRenderValue = HSHtml | HtmlSafe | Promise<HSHtml>;
+
+export type Slot<
+  TContent = DefaultSlotContent,
+  D extends SlotDefinition = SlotDefinition,
+> = {
+  readonly name: D["name"];
+  readonly definition: D;
+  readonly content: readonly TContent[];
+  render(): SlotRenderValue;
+};
+
+export type TemplateSlotsFrom<S extends readonly SlotDefinition[]> = {
+  [K in SlotNamesFrom<S>]: Slot<
+    SlotContentFromDefinition<Extract<S[number], { name: K }>>,
+    Extract<S[number], { name: K }>
+  >;
+};
+
+export function renderSlotContent(
+  slotName: string,
+  items: readonly unknown[],
+  ctx: RenderContext,
+  schema: z.ZodTypeAny | undefined,
+): Promise<HSHtml> {
+  return Promise.all(
+    items.map(async (item) => {
+      try {
+        validateSlotContentItem(slotName, item, schema);
+      } catch (err) {
+        throw new RenderError(
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+
+      if (typeof item === "string") {
+        return html.raw(item);
+      }
+      if (isModule(item)) {
+        return item.render(ctx);
+      }
+      throw new RenderError(
+        "invalid slot content; expected module or HTML string",
+      );
+    }),
+  ).then((chunks) => html`${chunks}`);
+}
+
+export function createStubSlot<
+  D extends SlotDefinition,
+>(definition: D): Slot<DefaultSlotContent, D> {
+  return {
+    name: definition.name,
+    definition,
+    content: [],
+    render() {
+      return html.raw(slotSentinel(definition.name));
+    },
+  };
+}
+
+export function createPageSlot<
+  D extends SlotDefinition,
+>(
+  definition: D,
+  content: readonly SlotContentFromDefinition<D>[],
+  ctx: RenderContext,
+): Slot<SlotContentFromDefinition<D>, D> {
+  const schema = definition.options?.schema;
+  return {
+    name: definition.name,
+    definition,
+    content,
+    render() {
+      return renderSlotContent(definition.name, content, ctx, schema);
+    },
+  };
+}
+
+export function buildStubSlots<S extends readonly SlotDefinition[]>(
+  definitions: S,
+): TemplateSlotsFrom<S> {
+  const slots = {} as TemplateSlotsFrom<S>;
+  for (const def of definitions) {
+    slots[def.name as SlotNamesFrom<S>] = createStubSlot(
+      def,
+    ) as TemplateSlotsFrom<S>[SlotNamesFrom<S>];
+  }
+  return slots;
+}
+
+export function buildPageSlots(
+  page: SitePage,
+  ctx: RenderContext,
+): Record<string, Slot> {
+  const slots: Record<string, Slot> = {};
+  const definitions = page.template.__definitions ?? [];
+
+  for (const def of definitions) {
+    const content = page.slots[def.name] ?? [];
+    slots[def.name] = createPageSlot(def, content, ctx);
+  }
+
+  return slots;
+}