@jimmy_harika/websitekit 0.3.1

package/src/model.ts

@@ -0,0 +1,116 @@
+/**
+ * Page-builder document model — the single source of truth the engine edits and
+ * renders. A `PageDocument` is one page: an ordered list of sections plus the
+ * (site-wide) theme. Persistence adapters map this to/from app storage (Convex
+ * `storefrontPages` + `storefrontSections` for pixbox; anything else elsewhere).
+ *
+ * Block-agnostic by design: a `Section` is just `{ type, variant?, props }`.
+ * What each `type` means lives in the app's catalog, never here.
+ */
+
+export type ThemeRadius = "none" | "sm" | "md" | "lg";
+export type ThemeSpacing = "tight" | "normal" | "roomy";
+
+/** Responsive breakpoints a section can be hidden on. mobile <640, tablet
+ *  640–1024, desktop ≥1024 (Tailwind sm / lg boundaries). */
+export type Breakpoint = "mobile" | "tablet" | "desktop";
+
+export interface ThemePalette {
+  bg: string;
+  text: string;
+  primary: string;
+  accent: string;
+  muted: string;
+}
+
+export interface ThemeTokens {
+  /** Google font family name for headings, e.g. "Cormorant Garamond". */
+  fontHeading: string;
+  /** Google font family name for body text, e.g. "Jost". */
+  fontBody: string;
+  colors: ThemePalette;
+  radius: ThemeRadius;
+  spacing: ThemeSpacing;
+}
+
+export interface Section {
+  /** Stable per-section id (survives reorder). */
+  id: string;
+  /** Registry key — resolved against the app catalog at render time. */
+  type: string;
+  /** Optional layout variant within the type (e.g. "split-right", "3-up"). */
+  variant?: string;
+  /** Validated against the type's zod schema by the engine. */
+  props: Record<string, unknown>;
+  /** Responsive visibility — hide the section on these breakpoints in production. */
+  hideOn?: Breakpoint[];
+}
+
+/**
+ * Tailwind visibility classes for a `hideOn` set. Emits a base + sm: + lg: token
+ * so every combination (including ranges like "hide on tablet only") resolves.
+ * Returns "" when nothing is hidden so sections render with no extra wrapper.
+ */
+export function hideOnClasses(hideOn?: Breakpoint[]): string {
+  if (!hideOn || hideOn.length === 0) return "";
+  const m = hideOn.includes("mobile");
+  const t = hideOn.includes("tablet");
+  const d = hideOn.includes("desktop");
+  if (!m && !t && !d) return "";
+  return `${m ? "hidden" : "block"} sm:${t ? "hidden" : "block"} lg:${d ? "hidden" : "block"}`;
+}
+
+export interface PageDocument {
+  sections: Section[];
+  theme: ThemeTokens;
+}
+
+/**
+ * Metadata for a starter template shown in the editor's TemplateGallery.
+ * Lives in the model (not the editor) so catalog data modules can import it
+ * without dragging the client editor bundle into an RSC graph.
+ */
+export interface TemplateMeta {
+  id: string;
+  name: string;
+  category: string;
+  description?: string;
+  thumb?: string;
+  build: () => PageDocument;
+}
+
+export const DEFAULT_THEME: ThemeTokens = {
+  fontHeading: "Cormorant Garamond",
+  fontBody: "Jost",
+  colors: {
+    bg: "#ffffff",
+    text: "#1a1a1a",
+    primary: "#1a1a1a",
+    accent: "#9a7b4f",
+    muted: "#6b6b6b",
+  },
+  radius: "sm",
+  spacing: "normal",
+};
+
+let _seq = 0;
+/**
+ * Compact unique id for new sections. Not cryptographic — only needs to be
+ * unique within a document and stable across a session. Avoids any timestamp so
+ * it is safe to call in any runtime.
+ */
+export function createSectionId(prefix = "sec"): string {
+  const rnd = Math.random().toString(36).slice(2, 9);
+  return `${prefix}_${rnd}${(_seq++).toString(36)}`;
+}
+
+/** Deep-ish clone of a section with a fresh id (for duplicate). */
+export function cloneSection(section: Section): Section {
+  return {
+    id: createSectionId(),
+    type: section.type,
+    variant: section.variant,
+    props: structuredClone(section.props),
+    ...(section.hideOn ? { hideOn: [...section.hideOn] } : {}),
+  };
+}

package/src/registry.ts

@@ -0,0 +1,138 @@
+/**
+ * Section registry — the extension point that makes the engine block-agnostic.
+ *
+ * An app builds a `Catalog` from `defineSection(...)` definitions. The SAME
+ * `Component` is used by the renderer (production) and the editor canvas (so
+ * what you edit is exactly what ships). `schema` (zod) gives typed props, an
+ * auto-generated inspector form for non-inline fields, and template validation.
+ */
+import type { ComponentType } from "react";
+import type { ZodType } from "zod";
+
+/** How a prop is edited directly on the canvas (vs. in the right-rail inspector). */
+export type InlineFieldKind = "text" | "richtext" | "image";
+
+export interface SectionVariant {
+  id: string;
+  label: string;
+  /** Props merged over `defaults` when this variant is chosen. */
+  props?: Record<string, unknown>;
+}
+
+/**
+ * Inspector field descriptor — drives the right-rail form. Explicit (not zod
+ * introspection) so labels/widgets are reliable; zod stays purely for
+ * validation. Props marked `inline` are edited on the canvas instead.
+ */
+export type FieldDescriptor =
+  | {
+      key: string;
+      label: string;
+      widget: "text" | "textarea" | "url";
+      placeholder?: string;
+      help?: string;
+    }
+  | { key: string; label: string; widget: "number"; min?: number; max?: number; help?: string }
+  | {
+      key: string;
+      label: string;
+      widget: "select";
+      options: { value: string; label: string }[];
+      help?: string;
+    }
+  | {
+      key: string;
+      label: string;
+      widget: "list";
+      /** Format hint shown under the textarea, e.g. "Title | Description". */
+      help?: string;
+    }
+  | {
+      key: string;
+      label: string;
+      widget: "image";
+      /** Sibling prop key holding the alt text (e.g. key:"portrait" → altKey:"portraitAlt"). */
+      altKey?: string;
+      placeholder?: string;
+      help?: string;
+    };
+
+export interface SectionDefinition<
+  P extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Registry key, e.g. "hero", "gallery", "newsletter". */
+  type: string;
+  /** Human label shown in the block library. */
+  label: string;
+  /** Library grouping, e.g. "Banners", "Images", "Newsletter". */
+  category: string;
+  description?: string;
+  /** Zod schema for `props` — typed props + inspector form + template validation. */
+  schema: ZodType;
+  /** Props for a freshly inserted section (a variant's `props` merge over this). */
+  defaults: P;
+  /** Layout variants surfaced in the block library + "Change Layout". */
+  variants?: SectionVariant[];
+  /** Props inline-editable on the canvas, and how. Others go to the inspector. */
+  inline?: Partial<Record<keyof P & string, InlineFieldKind>>;
+  /** Right-rail inspector fields (for props not edited inline on the canvas). */
+  fields?: FieldDescriptor[];
+  /** Renderer used in BOTH editor canvas and production. Must be pure/SSR-safe. */
+  Component: ComponentType<P>;
+}
+
+export interface Catalog {
+  sections: Record<string, SectionDefinition>;
+  /** Category display order for the block library. */
+  categories: string[];
+}
+
+/** Identity helper that preserves the prop generic for inference at call sites. */
+export function defineSection<P extends Record<string, unknown>>(
+  def: SectionDefinition<P>,
+): SectionDefinition<P> {
+  return def;
+}
+
+export function buildCatalog(defs: SectionDefinition[]): Catalog {
+  const sections: Record<string, SectionDefinition> = {};
+  const categories: string[] = [];
+  for (const d of defs) {
+    sections[d.type] = d;
+    if (!categories.includes(d.category)) categories.push(d.category);
+  }
+  return { sections, categories };
+}
+
+/** Look up a definition; undefined for unknown types (renderer shows a stub). */
+export function getDefinition(
+  catalog: Catalog,
+  type: string,
+): SectionDefinition | undefined {
+  return catalog.sections[type];
+}
+
+/**
+ * Validate + coerce a section's props against its schema. On failure (e.g. an
+ * old document missing a new required field) returns the definition defaults so
+ * the canvas never crashes on bad data — the editor surfaces the mismatch.
+ */
+export function resolveProps(
+  def: SectionDefinition,
+  props: unknown,
+): Record<string, unknown> {
+  const res = def.schema.safeParse(props ?? {});
+  if (res.success) return res.data as Record<string, unknown>;
+  return { ...def.defaults };
+}
+
+/** Default props for a new section of `type`, with an optional variant applied. */
+export function defaultPropsFor(
+  def: SectionDefinition,
+  variantId?: string,
+): Record<string, unknown> {
+  const base = { ...def.defaults };
+  if (!variantId) return base;
+  const v = def.variants?.find((x) => x.id === variantId);
+  return { ...base, ...(v?.props ?? {}) };
+}

package/src/renderer/index.tsx

@@ -0,0 +1,55 @@
+/**
+ * Production renderer — RSC-safe. No client imports, no hooks. The published
+ * site uses this: server-renders a `PageDocument` to static HTML, theme tokens
+ * on the container, each section via its catalog `Component` (no `edit` prop →
+ * pure/static). The editor canvas renders the same components with `edit`
+ * injected (see editor/Canvas).
+ */
+import { createElement, type ReactNode } from "react";
+import type { PageDocument, Section } from "../model";
+import { hideOnClasses } from "../model";
+import { type Catalog, getDefinition, resolveProps } from "../registry";
+import { googleFontsHref, themeVars } from "../theme";
+
+/** One section, statically. Unknown types render an inert placeholder. */
+export function renderSection(catalog: Catalog, section: Section): ReactNode {
+  const def = getDefinition(catalog, section.type);
+  const visibility = hideOnClasses(section.hideOn);
+  if (!def) {
+    return createElement(
+      "div",
+      {
+        key: section.id,
+        className: `px-6 py-8 text-center text-xs opacity-40 ${visibility}`,
+      },
+      `Unknown section: ${section.type}`,
+    );
+  }
+  const props = resolveProps(def, section.props);
+  // Wrap only when the section is hidden on a breakpoint — keeps the DOM flat
+  // for normally-visible sections (no wrapper to disturb full-bleed layouts).
+  if (!visibility) return createElement(def.Component, { key: section.id, ...props });
+  const el = createElement(def.Component, props);
+  return createElement("div", { key: section.id, className: visibility }, el);
+}
+
+export function PageRenderer({
+  doc,
+  catalog,
+  className,
+}: {
+  doc: PageDocument;
+  catalog: Catalog;
+  className?: string;
+}) {
+  return (
+    <div style={themeVars(doc.theme)} className={className}>
+      {doc.sections.map((section) => renderSection(catalog, section))}
+    </div>
+  );
+}
+
+/** <link> tag for the document's Google fonts — drop in <head> or above body. */
+export function PageFonts({ doc }: { doc: PageDocument }) {
+  return <link rel="stylesheet" href={googleFontsHref(doc.theme)} />;
+}

package/src/store.ts

@@ -0,0 +1,216 @@
+/**
+ * Editor state store — zustand (vanilla, per-instance) + zundo for undo/redo.
+ *
+ * Pure data operations only: actions take fully-formed sections, so the store
+ * has NO dependency on the catalog. The editor computes default/variant props
+ * from the catalog and hands the store a ready `Section`. History tracks only
+ * `doc` (selection changes don't create undo steps), keyed by `doc` reference —
+ * so every real edit is one clean undo step.
+ */
+"use client";
+
+import { createContext, createElement, useContext, useRef, type ReactNode } from "react";
+import { createStore, type StoreApi } from "zustand/vanilla";
+import { useStore } from "zustand";
+import { temporal, type TemporalState } from "zundo";
+import {
+  cloneSection,
+  type PageDocument,
+  type Section,
+  type ThemeTokens,
+} from "./model";
+
+export interface BuilderState {
+  doc: PageDocument;
+  selectedId: string | null;
+
+  select(id: string | null): void;
+  /** Insert a ready-built section at `index` (default: append). Selects it. */
+  insertSection(section: Section, index?: number): void;
+  /** Shallow-merge a patch into a section's props. */
+  updateProps(id: string, patch: Record<string, unknown>): void;
+  /** Replace a section's props wholesale (used by "Change Layout"). */
+  setProps(id: string, props: Record<string, unknown>): void;
+  /** Set a section's layout variant, optionally replacing props. */
+  setVariant(id: string, variant: string, props?: Record<string, unknown>): void;
+  /** Set a section's responsive visibility (hide on mobile/tablet/desktop). */
+  setHideOn(id: string, hideOn: import("./model").Breakpoint[]): void;
+  /** Move a section from one index to another. */
+  moveSection(from: number, to: number): void;
+  removeSection(id: string): void;
+  duplicateSection(id: string): void;
+  setTheme(patch: Partial<ThemeTokens>): void;
+  /** Replace the whole document (load / apply template). Clears selection. */
+  replaceDocument(doc: PageDocument): void;
+}
+
+type PartializedHistory = { doc: PageDocument };
+
+export type BuilderStoreApi = StoreApi<BuilderState> & {
+  temporal: StoreApi<TemporalState<PartializedHistory>>;
+};
+
+function indexOf(doc: PageDocument, id: string): number {
+  return doc.sections.findIndex((s) => s.id === id);
+}
+
+export function createBuilderStore(initial: PageDocument): BuilderStoreApi {
+  const store = createStore<BuilderState>()(
+    temporal(
+      (set, get) => ({
+        doc: initial,
+        selectedId: null,
+
+        select: (id) => set({ selectedId: id }),
+
+        insertSection: (section, index) =>
+          set((s) => {
+            const sections = [...s.doc.sections];
+            const at = index ?? sections.length;
+            sections.splice(Math.max(0, Math.min(at, sections.length)), 0, section);
+            return { doc: { ...s.doc, sections }, selectedId: section.id };
+          }),
+
+        updateProps: (id, patch) =>
+          set((s) => ({
+            doc: {
+              ...s.doc,
+              sections: s.doc.sections.map((sec) =>
+                sec.id === id ? { ...sec, props: { ...sec.props, ...patch } } : sec,
+              ),
+            },
+          })),
+
+        setProps: (id, props) =>
+          set((s) => ({
+            doc: {
+              ...s.doc,
+              sections: s.doc.sections.map((sec) =>
+                sec.id === id ? { ...sec, props } : sec,
+              ),
+            },
+          })),
+
+        setVariant: (id, variant, props) =>
+          set((s) => ({
+            doc: {
+              ...s.doc,
+              sections: s.doc.sections.map((sec) =>
+                sec.id === id
+                  ? { ...sec, variant, props: props ?? sec.props }
+                  : sec,
+              ),
+            },
+          })),
+
+        setHideOn: (id, hideOn) =>
+          set((s) => ({
+            doc: {
+              ...s.doc,
+              sections: s.doc.sections.map((sec) =>
+                sec.id === id
+                  ? hideOn.length === 0
+                    ? (() => {
+                        const { hideOn: _omit, ...rest } = sec;
+                        return rest;
+                      })()
+                    : { ...sec, hideOn }
+                  : sec,
+              ),
+            },
+          })),
+
+        moveSection: (from, to) =>
+          set((s) => {
+            const sections = [...s.doc.sections];
+            if (from < 0 || from >= sections.length) return s;
+            const [moved] = sections.splice(from, 1);
+            sections.splice(Math.max(0, Math.min(to, sections.length)), 0, moved);
+            return { doc: { ...s.doc, sections } };
+          }),
+
+        removeSection: (id) =>
+          set((s) => ({
+            doc: { ...s.doc, sections: s.doc.sections.filter((sec) => sec.id !== id) },
+            selectedId: s.selectedId === id ? null : s.selectedId,
+          })),
+
+        duplicateSection: (id) =>
+          set((s) => {
+            const i = indexOf(s.doc, id);
+            if (i < 0) return s;
+            const copy = cloneSection(s.doc.sections[i]);
+            const sections = [...s.doc.sections];
+            sections.splice(i + 1, 0, copy);
+            return { doc: { ...s.doc, sections }, selectedId: copy.id };
+          }),
+
+        setTheme: (patch) =>
+          set((s) => ({
+            doc: {
+              ...s.doc,
+              theme: {
+                ...s.doc.theme,
+                ...patch,
+                colors: { ...s.doc.theme.colors, ...(patch.colors ?? {}) },
+              },
+            },
+          })),
+
+        replaceDocument: (doc) => set({ doc, selectedId: null }),
+      }),
+      {
+        // Track only the document; key history by doc reference so selection
+        // changes never produce phantom undo steps.
+        partialize: (s) => ({ doc: s.doc }),
+        equality: (a, b) => a.doc === b.doc,
+        limit: 100,
+      },
+    ),
+  );
+  return store as BuilderStoreApi;
+}
+
+/* ── React bindings ─────────────────────────────────────────────────────── */
+
+const BuilderStoreContext = createContext<BuilderStoreApi | null>(null);
+
+export function BuilderProvider({
+  store,
+  children,
+}: {
+  store: BuilderStoreApi;
+  children: ReactNode;
+}) {
+  return createElement(BuilderStoreContext.Provider, { value: store }, children);
+}
+
+/**
+ * Lazily create-and-hold a store for the lifetime of the component.
+ *
+ * NOTE: ignores updates to `initial` after first render. If you need to swap
+ * documents (e.g. navigating to a different page without unmounting), pass a
+ * `key` prop to the parent so React remounts this hook with fresh state.
+ */
+export function useCreateBuilderStore(initial: PageDocument): BuilderStoreApi {
+  const ref = useRef<BuilderStoreApi | null>(null);
+  if (ref.current === null) ref.current = createBuilderStore(initial);
+  return ref.current;
+}
+
+export function useBuilderStoreApi(): BuilderStoreApi {
+  const store = useContext(BuilderStoreContext);
+  if (!store) throw new Error("useBuilderStoreApi must be used within <BuilderProvider>");
+  return store;
+}
+
+export function useBuilder<T>(selector: (s: BuilderState) => T): T {
+  return useStore(useBuilderStoreApi(), selector);
+}
+
+/** Subscribe to undo/redo state (pastStates/futureStates/undo/redo/clear). */
+export function useTemporal<T>(
+  selector: (s: TemporalState<PartializedHistory>) => T,
+): T {
+  return useStore(useBuilderStoreApi().temporal, selector);
+}

package/src/theme.ts

@@ -0,0 +1,85 @@
+/**
+ * Theme → CSS custom properties. The engine emits BOTH the legacy storefront
+ * tokens (`--sf-*`, so pixbox's existing block renderers work unchanged) and
+ * generic `--pb-*` tokens for new/cross-app blocks. Blocks read tokens via
+ * `var(--pb-color-accent, ...)` so one component skins across every theme — the
+ * same "UI as skinnable primitives" convention used by event-card skins.
+ */
+import type { CSSProperties } from "react";
+import type { ThemeTokens } from "./model";
+
+function fontStack(family: string, fallback: "serif" | "sans-serif"): string {
+  const tail =
+    fallback === "serif"
+      ? "ui-serif, Georgia, 'Times New Roman', serif"
+      : "ui-sans-serif, system-ui, sans-serif";
+  return `"${family}", ${tail}`;
+}
+
+function radiusPx(r: ThemeTokens["radius"]): string {
+  return r === "none" ? "0px" : r === "sm" ? "4px" : r === "md" ? "10px" : "20px";
+}
+
+function spacingScale(s: ThemeTokens["spacing"]): string {
+  return s === "tight" ? "0.85" : s === "roomy" ? "1.25" : "1";
+}
+
+/** Inline style object setting every theme token on a container element. */
+export function themeVars(theme: ThemeTokens): CSSProperties {
+  const heading = fontStack(theme.fontHeading, "serif");
+  const body = fontStack(theme.fontBody, "sans-serif");
+  const vars: Record<string, string> = {
+    // legacy storefront tokens (existing renderers depend on these)
+    "--sf-font-heading": heading,
+    "--sf-font-body": body,
+    "--sf-bg": theme.colors.bg,
+    "--sf-text": theme.colors.text,
+    "--sf-accent": theme.colors.accent,
+    "--sf-primary": theme.colors.primary,
+    // generic page-builder tokens
+    "--pb-font-heading": heading,
+    "--pb-font-body": body,
+    "--pb-color-bg": theme.colors.bg,
+    "--pb-color-text": theme.colors.text,
+    "--pb-color-primary": theme.colors.primary,
+    "--pb-color-accent": theme.colors.accent,
+    "--pb-color-muted": theme.colors.muted,
+    "--pb-radius": radiusPx(theme.radius),
+    "--pb-spacing": spacingScale(theme.spacing),
+  };
+  return {
+    ...(vars as CSSProperties),
+    backgroundColor: theme.colors.bg,
+    color: theme.colors.text,
+  };
+}
+
+const WEIGHTS = "wght@300;400;500;600;700";
+
+/** Google Fonts stylesheet href for the theme's two families. */
+export function googleFontsHref(theme: ThemeTokens): string {
+  const fam = (f: string) => `family=${encodeURIComponent(f)}:${WEIGHTS}`;
+  const families = [theme.fontHeading, theme.fontBody]
+    .filter((f, i, a) => a.indexOf(f) === i)
+    .map(fam)
+    .join("&");
+  return `https://fonts.googleapis.com/css2?${families}&display=swap`;
+}
+
+/** Curated heading/body font pairings offered in the theme panel. */
+export const FONT_PAIRS: { id: string; label: string; heading: string; body: string }[] = [
+  { id: "editorial", label: "Editorial", heading: "Cormorant Garamond", body: "Jost" },
+  { id: "classic", label: "Classic", heading: "Playfair Display", body: "Inter" },
+  { id: "modern", label: "Modern", heading: "Fraunces", body: "Manrope" },
+  { id: "grotesk", label: "Grotesk", heading: "Space Grotesk", body: "Inter" },
+  { id: "warm", label: "Warm", heading: "DM Serif Display", body: "DM Sans" },
+];
+
+/** Curated palettes offered in the theme panel. */
+export const PALETTES: { id: string; label: string; colors: ThemeTokens["colors"] }[] = [
+  { id: "ivory", label: "Ivory", colors: { bg: "#ffffff", text: "#1a1a1a", primary: "#1a1a1a", accent: "#9a7b4f", muted: "#6b6b6b" } },
+  { id: "noir", label: "Noir", colors: { bg: "#0e0e0e", text: "#f5f5f5", primary: "#f5f5f5", accent: "#c9a36a", muted: "#9a9a9a" } },
+  { id: "blush", label: "Blush", colors: { bg: "#fbf6f3", text: "#2b2422", primary: "#2b2422", accent: "#c98b7e", muted: "#8a7d78" } },
+  { id: "sage", label: "Sage", colors: { bg: "#f4f6f2", text: "#22281f", primary: "#22281f", accent: "#7c8a6a", muted: "#7a8073" } },
+  { id: "cobalt", label: "Cobalt", colors: { bg: "#ffffff", text: "#0f172a", primary: "#0f172a", accent: "#2f5cff", muted: "#64748b" } },
+];