@jimmy_harika/websitekit 0.3.1

package/README.md

@@ -0,0 +1,86 @@
+# @jimmy_harika/websitekit
+
+The Snow Labs website builder — **one shared, block-agnostic, curated-section
+engine** used by every Snow Labs app. Build it once here, and every app
+(photographer sites, author sites, and more) inherits it. New blocks and
+verticals land here and upgrade all consumers at once.
+
+This is the **single home** for the builder: the engine, a design-system-agnostic
+block library, and per-industry catalogs all live in this repo and ship as one
+private package.
+
+## Why custom (not Puck / GrapesJS)
+
+The engine is the product. Curated sections (not freeform grids) keep sites
+beautiful-by-default for non-designers, and the **same component renders in the
+editor canvas and in production** (an injected `edit` prop makes fields inline-
+editable; production omits it for a byte-identical static render) — an RSC + CDN
+perf moat heavy runtimes can't match.
+
+## Layers
+
+| Export | What |
+|---|---|
+| `@jimmy_harika/websitekit` | Core model · registry · theme (RSC-safe) |
+| `@jimmy_harika/websitekit/editor` | `<PageBuilder>` client editor |
+| `@jimmy_harika/websitekit/renderer` | `PageRenderer` / `PageFonts` (RSC-safe production render) |
+| `@jimmy_harika/websitekit/store` | zustand + zundo store |
+| `@jimmy_harika/websitekit/blocks` | Design-system-agnostic blocks — render off `--pb-*` theme tokens, no app-UI imports (this is what makes a block portable to every app) |
+| `@jimmy_harika/websitekit/catalogs/author` | Author-website catalog + templates |
+
+## The app contract
+
+A consuming app supplies only:
+
+1. **A catalog** (or use a shipped one from `./catalogs/*`).
+2. **A persistence adapter** — load → `PageDocument`, save, publish.
+3. **`uploadImage(file) => Promise<url>`**.
+4. **A data-source resolver** — pre-resolve "live" block props (e.g. an author's
+   real books) from the app's own backend before render. App-level transform; no
+   engine change. Keeps blocks presentational and portable.
+
+```tsx
+import { PageBuilder } from "@jimmy_harika/websitekit/editor";
+import { AUTHOR_CATALOG, AUTHOR_TEMPLATES } from "@jimmy_harika/websitekit/catalogs/author";
+
+<PageBuilder
+  catalog={AUTHOR_CATALOG}
+  templates={AUTHOR_TEMPLATES}
+  initialDocument={doc}
+  onChange={autosave}
+  onPublish={publish}
+  uploadImage={upload}
+/>;
+```
+
+```tsx
+// production (RSC)
+import { PageRenderer, PageFonts } from "@jimmy_harika/websitekit/renderer";
+import { AUTHOR_CATALOG } from "@jimmy_harika/websitekit/catalogs/author";
+
+<>
+  <PageFonts doc={doc} />
+  <PageRenderer doc={doc} catalog={AUTHOR_CATALOG} />
+</>;
+```
+
+## Consuming app notes
+
+- The package ships **raw TS/TSX** — add `@jimmy_harika/websitekit` to your Next
+  `transpilePackages`, and ensure a **single React copy** (dedupe via your
+  bundler's resolve alias).
+- `zod` is a peer (v3 or v4). Catalogs authored here use the repo's zod; apps on
+  a different major only need the `obj()` cast bridge if they author their own
+  catalog.
+- The **editor chrome** (`@jimmy_harika/websitekit/editor`) is styled with shadcn/ui
+  semantic utilities and reads the host's shadcn theme. If your app doesn't use
+  shadcn/ui, see **[PREREQUISITES.md](./PREREQUISITES.md)** for the required CSS
+  variables. Rendered sites and blocks are portable and do not depend on shadcn.
+
+## Roadmap
+
+- **Catalogs:** author (shipped) → photographer (migrate from pixbox) → driving
+  schools, etc. Each vertical is additive.
+- **Backend:** a companion Convex component (isolated tables + app-facing API) so
+  persistence is shared infra too.
+- **Edge:** Cloudflare-for-SaaS custom domains + wildcard subdomain serving.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jimmy_harika/websitekit",
+  "version": "0.3.1",
+  "description": "Snow Labs website builder engine. Block-agnostic, curated-section. One shared builder across every Snow Labs app \u2014 engine + design-system-agnostic blocks + per-industry catalogs (author, photographer, \u2026). Each app plugs in a catalog + theme + persistence adapter.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jimmyharika/websitekit.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./store": "./src/store.ts",
+    "./renderer": "./src/renderer/index.tsx",
+    "./editor": "./src/editor/index.tsx",
+    "./theme": "./src/theme.ts",
+    "./blocks": "./src/blocks/index.ts",
+    "./catalogs/author": "./src/catalogs/author/index.ts",
+    "./catalogs/publisher": "./src/catalogs/publisher/index.ts",
+    "./lib/cn": "./src/lib/cn.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@atlaskit/pragmatic-drag-and-drop": "^1.8.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.525.0",
+    "tailwind-merge": "^3.4.0",
+    "zundo": "^2.3.0",
+    "zustand": "^5.0.9"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.76"
+  }
+}

package/src/blocks/author-bio.tsx

@@ -0,0 +1,52 @@
+/** About-the-author — a portrait beside a story column. `flip` swaps sides. */
+import { renderImage, renderText, type EditPrimitives } from "../editable";
+import { BODY, Eyebrow, HEADING, MUTED, RADIUS, Section, TEXT } from "./primitives";
+
+export interface AuthorBioProps {
+  eyebrow?: string;
+  heading: string;
+  body: string;
+  portrait?: string;
+  flip?: boolean;
+  edit?: EditPrimitives;
+}
+
+export function AuthorBio({ eyebrow, heading, body, portrait, flip = false, edit }: AuthorBioProps) {
+  return (
+    <Section tint>
+      <div className="grid items-center gap-10 md:grid-cols-2 md:gap-16">
+        <div
+          className={`relative aspect-[4/5] w-full overflow-hidden ${flip ? "md:order-2" : ""}`}
+          style={{ borderRadius: RADIUS, background: MUTED }}
+        >
+          {renderImage(edit, {
+            field: "portrait",
+            src: portrait,
+            alt: heading,
+            className: "h-full w-full object-cover",
+          })}
+        </div>
+        <div className={flip ? "md:order-1" : ""}>
+          <Eyebrow>{eyebrow}</Eyebrow>
+          {renderText(edit, {
+            field: "heading",
+            value: heading,
+            as: "h2",
+            className: "text-[clamp(1.75rem,4vw,2.75rem)] font-light leading-tight",
+            style: { fontFamily: HEADING, color: TEXT },
+            placeholder: "About the author",
+          })}
+          {renderText(edit, {
+            field: "body",
+            value: body,
+            as: "div",
+            className: "mt-6 space-y-4 text-[1.0625rem] leading-relaxed whitespace-pre-wrap",
+            style: { fontFamily: BODY, color: MUTED },
+            placeholder: "Tell readers who you are, what you write, and why it matters.",
+            multiline: true,
+          })}
+        </div>
+      </div>
+    </Section>
+  );
+}

package/src/blocks/author-hero.tsx

@@ -0,0 +1,99 @@
+/** Author hero — name + tagline, over a portrait or as a tall type-only banner. */
+import { renderImage, renderText, type EditPrimitives } from "../editable";
+import { BODY, Eyebrow, HEADING, MUTED, Section, TEXT } from "./primitives";
+
+export interface AuthorHeroProps {
+  eyebrow?: string;
+  name: string;
+  tagline?: string;
+  portrait?: string;
+  align?: "center" | "left";
+  edit?: EditPrimitives;
+}
+
+export function AuthorHero({ eyebrow, name, tagline, portrait, align = "center", edit }: AuthorHeroProps) {
+  // Left layout: split — type beside a tall portrait.
+  if (align === "left") {
+    return (
+      <Section style={{ paddingBlock: "calc(var(--pb-spacing,1) * 5rem)" }}>
+        <div className="grid items-center gap-10 md:grid-cols-2 md:gap-16">
+          <div>
+            <Eyebrow>{eyebrow}</Eyebrow>
+            {renderText(edit, {
+              field: "name",
+              value: name,
+              as: "h1",
+              className: "text-[clamp(2.5rem,7vw,5rem)] font-light leading-[0.95]",
+              style: { fontFamily: HEADING, color: TEXT },
+              placeholder: "Author Name",
+            })}
+            {renderText(edit, {
+              field: "tagline",
+              value: tagline ?? "",
+              as: "p",
+              className: "mt-6 max-w-md text-lg leading-relaxed",
+              style: { fontFamily: BODY, color: MUTED },
+              placeholder: "A one-line tagline about your work.",
+              multiline: true,
+            })}
+          </div>
+          <div
+            className="relative aspect-[4/5] w-full overflow-hidden"
+            style={{ borderRadius: "var(--pb-radius, 4px)", background: MUTED }}
+          >
+            {renderImage(edit, {
+              field: "portrait",
+              src: portrait,
+              alt: name,
+              priority: true,
+              className: "h-full w-full object-cover",
+            })}
+          </div>
+        </div>
+      </Section>
+    );
+  }
+
+  // Center layout: full-bleed portrait with overlay, or tall type-only banner.
+  return (
+    <section className="relative flex min-h-[78vh] w-full items-center justify-center overflow-hidden px-6 text-center">
+      {portrait ? (
+        <>
+          <div className="absolute inset-0">
+            {renderImage(edit, {
+              field: "portrait",
+              src: portrait,
+              alt: name,
+              priority: true,
+              className: "h-full w-full object-cover",
+            })}
+          </div>
+          <div
+            className="absolute inset-0"
+            style={{ background: "linear-gradient(to bottom, rgba(0,0,0,0.35), rgba(0,0,0,0.6))" }}
+          />
+        </>
+      ) : null}
+      <div className="relative z-10 mx-auto max-w-3xl">
+        <Eyebrow>{eyebrow}</Eyebrow>
+        {renderText(edit, {
+          field: "name",
+          value: name,
+          as: "h1",
+          className: "text-[clamp(2.75rem,9vw,6.5rem)] font-light leading-[0.95]",
+          style: { fontFamily: HEADING, color: portrait ? "#ffffff" : TEXT },
+          placeholder: "Author Name",
+        })}
+        {renderText(edit, {
+          field: "tagline",
+          value: tagline ?? "",
+          as: "p",
+          className: "mx-auto mt-6 max-w-xl text-lg leading-relaxed",
+          style: { fontFamily: BODY, color: portrait ? "rgba(255,255,255,0.85)" : MUTED },
+          placeholder: "A one-line tagline about your work.",
+          multiline: true,
+        })}
+      </div>
+    </section>
+  );
+}

package/src/blocks/book-grid.tsx

@@ -0,0 +1,97 @@
+/**
+ * Book grid — the author's shelf. `items` is presentational; the app resolves
+ * the live list (e.g. published books) before render. Columns are responsive.
+ */
+import { renderText, type EditPrimitives } from "../editable";
+import {
+  BODY,
+  type BookItem,
+  Eyebrow,
+  HAIRLINE,
+  HEADING,
+  MUTED,
+  RADIUS,
+  Section,
+  TEXT,
+} from "./primitives";
+
+export interface BookGridProps {
+  eyebrow?: string;
+  heading?: string;
+  items?: BookItem[];
+  /** May arrive as a number or a string from the inspector select. */
+  columns?: 2 | 3 | 4 | string;
+  edit?: EditPrimitives;
+}
+
+const PLACEHOLDER: BookItem[] = [
+  { title: "First Title", subtitle: "Novel" },
+  { title: "Second Title", subtitle: "Novel" },
+  { title: "Third Title", subtitle: "Short Stories" },
+];
+
+const COLS: Record<number, string> = {
+  2: "grid-cols-2 sm:grid-cols-2",
+  3: "grid-cols-2 sm:grid-cols-3",
+  4: "grid-cols-2 sm:grid-cols-4",
+};
+
+export function BookGrid({ eyebrow, heading, items, columns = 3, edit }: BookGridProps) {
+  const books = items && items.length > 0 ? items : PLACEHOLDER;
+  return (
+    <Section>
+      <div className="mb-10 text-center">
+        <Eyebrow>{eyebrow}</Eyebrow>
+        {renderText(edit, {
+          field: "heading",
+          value: heading ?? "",
+          as: "h2",
+          className: "text-[clamp(1.75rem,4vw,2.75rem)] font-light",
+          style: { fontFamily: HEADING, color: TEXT },
+          placeholder: "Books",
+        })}
+      </div>
+      <div className={`grid gap-6 sm:gap-8 ${COLS[Number(columns)] ?? COLS[3]}`}>
+        {books.map((book, i) => {
+          const href = book.links?.[0]?.url;
+          const card = (
+            <>
+              <div
+                className="aspect-[2/3] w-full overflow-hidden shadow-md transition-transform duration-300 group-hover:-translate-y-1"
+                style={{ borderRadius: RADIUS, background: HAIRLINE }}
+              >
+                {book.coverUrl ? (
+                  <img src={book.coverUrl} alt={book.title} loading="lazy" className="h-full w-full object-cover" />
+                ) : (
+                  <div
+                    className="flex h-full w-full items-center justify-center p-4 text-center text-[13px]"
+                    style={{ color: MUTED, fontFamily: BODY }}
+                  >
+                    {book.title}
+                  </div>
+                )}
+              </div>
+              <p className="mt-3 text-[15px] leading-snug" style={{ fontFamily: HEADING, color: TEXT }}>
+                {book.title}
+              </p>
+              {book.subtitle ? (
+                <p className="text-[11px] uppercase tracking-[0.18em]" style={{ fontFamily: BODY, color: MUTED }}>
+                  {book.subtitle}
+                </p>
+              ) : null}
+            </>
+          );
+          return href ? (
+            <a key={i} href={href} target="_blank" rel="noopener noreferrer" className="group block">
+              {card}
+            </a>
+          ) : (
+            <div key={i} className="group block">
+              {card}
+            </div>
+          );
+        })}
+      </div>
+    </Section>
+  );
+}

package/src/blocks/book-spotlight.tsx

@@ -0,0 +1,109 @@
+/**
+ * Featured-book spotlight — large cover beside title, blurb, and buy links.
+ * `item` is presentational; the app resolves a real book into it (live data),
+ * so this same block works for any app with a "books" concept.
+ */
+import { renderText, type EditPrimitives } from "../editable";
+import {
+  AccentLink,
+  BODY,
+  type BookItem,
+  Eyebrow,
+  HAIRLINE,
+  HEADING,
+  MUTED,
+  RADIUS,
+  Section,
+  TEXT,
+} from "./primitives";
+
+export interface BookSpotlightProps {
+  eyebrow?: string;
+  heading?: string;
+  item?: BookItem;
+  layout?: "cover-left" | "cover-right";
+  edit?: EditPrimitives;
+}
+
+const PLACEHOLDER: BookItem = {
+  title: "Your Latest Book",
+  subtitle: "A Novel",
+  description:
+    "Drop in the blurb that makes a reader stop scrolling. One or two sentences of the hook, the stakes, the promise.",
+  links: [{ label: "Amazon", url: "#" }, { label: "Bookshop", url: "#" }],
+};
+
+export function BookSpotlight({
+  eyebrow,
+  heading,
+  item,
+  layout = "cover-left",
+  edit,
+}: BookSpotlightProps) {
+  const book = item && item.title ? item : PLACEHOLDER;
+  const coverRight = layout === "cover-right";
+  return (
+    <Section>
+      {(eyebrow || heading) && (
+        <div className="mb-10 text-center">
+          <Eyebrow>{eyebrow}</Eyebrow>
+          {heading
+            ? renderText(edit, {
+                field: "heading",
+                value: heading,
+                as: "h2",
+                className: "text-[clamp(1.75rem,4vw,2.75rem)] font-light",
+                style: { fontFamily: HEADING, color: TEXT },
+                placeholder: "Featured book",
+              })
+            : null}
+        </div>
+      )}
+      <div className="grid items-center gap-10 md:grid-cols-[0.8fr_1fr] md:gap-16">
+        <div
+          className={`mx-auto w-full max-w-[320px] ${coverRight ? "md:order-2" : ""}`}
+        >
+          <div
+            className="aspect-[2/3] w-full overflow-hidden shadow-xl"
+            style={{ borderRadius: RADIUS, background: MUTED }}
+          >
+            {book.coverUrl ? (
+              <img src={book.coverUrl} alt={book.title} loading="lazy" className="h-full w-full object-cover" />
+            ) : (
+              <div
+                className="flex h-full w-full items-center justify-center p-6 text-center text-sm"
+                style={{ color: MUTED, background: HAIRLINE, fontFamily: BODY }}
+              >
+                {book.title}
+              </div>
+            )}
+          </div>
+        </div>
+        <div className={coverRight ? "md:order-1" : ""}>
+          <h3 className="text-[clamp(1.5rem,3.5vw,2.25rem)] font-light leading-tight" style={{ fontFamily: HEADING, color: TEXT }}>
+            {book.title}
+          </h3>
+          {book.subtitle ? (
+            <p className="mt-1 text-sm uppercase tracking-[0.2em]" style={{ fontFamily: BODY, color: MUTED }}>
+              {book.subtitle}
+            </p>
+          ) : null}
+          {book.description ? (
+            <p className="mt-5 max-w-prose text-[1.0625rem] leading-relaxed" style={{ fontFamily: BODY, color: MUTED }}>
+              {book.description}
+            </p>
+          ) : null}
+          {book.links && book.links.length > 0 ? (
+            <div className="mt-7 flex flex-wrap gap-3">
+              {book.links.map((l, i) => (
+                <AccentLink key={i} href={l.url} solid={i === 0}>
+                  {l.label}
+                </AccentLink>
+              ))}
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </Section>
+  );
+}

package/src/blocks/contact.tsx

@@ -0,0 +1,64 @@
+/** Contact / footer — heading, a line, an email, and social links. */
+import { renderText, type EditPrimitives } from "../editable";
+import { ACCENT, BODY, Eyebrow, HEADING, MUTED, Section, TEXT } from "./primitives";
+
+export interface ContactProps {
+  eyebrow?: string;
+  heading?: string;
+  body?: string;
+  email?: string;
+  links?: { label: string; url: string }[];
+  edit?: EditPrimitives;
+}
+
+export function Contact({ eyebrow, heading = "Get in touch", body, email, links, edit }: ContactProps) {
+  return (
+    <Section narrow>
+      <div className="text-center">
+        <Eyebrow>{eyebrow}</Eyebrow>
+        {renderText(edit, {
+          field: "heading",
+          value: heading,
+          as: "h2",
+          className: "text-[clamp(1.75rem,4vw,2.75rem)] font-light",
+          style: { fontFamily: HEADING, color: TEXT },
+          placeholder: "Get in touch",
+        })}
+        {renderText(edit, {
+          field: "body",
+          value: body ?? "",
+          as: "p",
+          className: "mx-auto mt-4 max-w-md text-[1.0625rem] leading-relaxed",
+          style: { fontFamily: BODY, color: MUTED },
+          placeholder: "For rights, events, or just to say hello.",
+          multiline: true,
+        })}
+        {email ? (
+          <a
+            href={`mailto:${email}`}
+            className="mt-6 inline-block text-lg underline-offset-4 hover:underline"
+            style={{ fontFamily: HEADING, color: ACCENT }}
+          >
+            {email}
+          </a>
+        ) : null}
+        {links && links.length > 0 ? (
+          <div className="mt-8 flex flex-wrap items-center justify-center gap-x-6 gap-y-2">
+            {links.map((l, i) => (
+              <a
+                key={i}
+                href={l.url || "#"}
+                target={l.url?.startsWith("http") ? "_blank" : undefined}
+                rel={l.url?.startsWith("http") ? "noopener noreferrer" : undefined}
+                className="text-[13px] uppercase tracking-[0.2em] transition-opacity hover:opacity-70"
+                style={{ fontFamily: BODY, color: TEXT }}
+              >
+                {l.label}
+              </a>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </Section>
+  );
+}

package/src/blocks/faq.tsx

@@ -0,0 +1,65 @@
+/**
+ * FAQ — accordion. Items from a `list` field: `question | answer` per line.
+ * Uses native <details> so it's RSC-safe AND works without JS (progressive
+ * enhancement). Portable, edit-aware.
+ */
+import { renderText, type EditPrimitives } from "../editable";
+import { BODY, HEADING, MUTED, Section, TEXT } from "./primitives";
+
+export interface FaqProps {
+  heading?: string;
+  /** `question | answer` per line. */
+  items?: string;
+  edit?: EditPrimitives;
+}
+
+interface Qa {
+  q: string;
+  a: string;
+}
+
+function parseItems(raw?: string): Qa[] {
+  if (!raw) return [];
+  return raw
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((l) => {
+      const [q = "", a = ""] = l.split("|").map((s) => (s ?? "").trim());
+      return { q: q || "Question", a: a || "" };
+    });
+}
+
+export function Faq(props: FaqProps) {
+  const { heading, items, edit } = props;
+  const qa = parseItems(items);
+  return (
+    <Section narrow>
+      {heading &&
+        renderText(edit, {
+          field: "heading",
+          value: heading,
+          as: "h2",
+          placeholder: "FAQ",
+          className: "mb-8 text-center text-[clamp(1.6rem,4vw,2.5rem)] font-light",
+          style: { fontFamily: HEADING, color: TEXT },
+        })}
+      <div className="divide-y" style={{ borderColor: "color-mix(in srgb, currentColor 12%, transparent)" }}>
+        {qa.map((item, i) => (
+          <details key={i} className="group py-4">
+            <summary
+              className="flex cursor-pointer list-none items-center justify-between gap-4 text-[16px] font-medium"
+              style={{ fontFamily: BODY, color: TEXT }}
+            >
+              <span>{item.q}</span>
+              <span className="text-xl opacity-50 transition group-open:rotate-45">+</span>
+            </summary>
+            <p className="mt-3 text-[15px] leading-relaxed" style={{ fontFamily: BODY, color: MUTED }}>
+              {item.a}
+            </p>
+          </details>
+        ))}
+      </div>
+    </Section>
+  );
+}