@morphika/andami 0.3.1 → 0.4.1

package/lib/builder/block-registry.ts

@@ -0,0 +1,195 @@
+"use client";
+
+/**
+ * Block Registry — central source of truth for block-type metadata.
+ *
+ * Inspired by the Puck pattern (puckeditor.com). Each block type declares its
+ * schema, renderer, live-preview, editor, icons, and animation-preset lists
+ * in ONE place instead of scattering across 8 files.
+ *
+ * Currently this file contains only the infrastructure (types + helpers).
+ * Population of the registry happens in `./block-registrations.ts` via
+ * side-effect imports. Dispatch tables (`ALL_BLOCK_INFO`, `BLOCK_CARD_ICONS`,
+ * renderer/editor switches) still exist in their original locations and are
+ * NOT derived from this registry yet — that migration happens in later
+ * sessions, behind the existing public API so it stays backward-compatible.
+ *
+ * ## Stability contract
+ *
+ * The registry is an INTERNAL consolidation helper. Consumers (instances
+ * using `@morphika/andami`) should not import from this module directly.
+ * The existing public exports (`ALL_BLOCK_INFO`, `BLOCK_TYPE_REGISTRY`,
+ * `BLOCK_CARD_ICONS`, etc.) remain the supported API.
+ *
+ * Session A (2026-04-19): infrastructure only — no existing exports change.
+ */
+
+import type React from "react";
+import type { DeviceViewport } from "./types";
+import type { ContentBlock } from "../sanity/types";
+
+// ────────────────────────────────────────────────────────────────────
+// Types
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Full registration for a single block type. Generic over the specific
+ * block union member so renderers / editors / factories can stay strongly
+ * typed even when pulled out of the registry map.
+ */
+export interface BlockRegistrationInput<T extends ContentBlock = ContentBlock> {
+  // ── Identity ──
+  /**
+   * Block type string — MUST match the `_type` literal stored in Sanity
+   * documents. Renaming this string is a breaking data migration.
+   */
+  type: T["_type"];
+  /** Human-readable label shown in the picker modal and settings header. */
+  label: string;
+  /** Short description shown under the label in the picker modal card. */
+  description: string;
+  /**
+   * Where the block appears.
+   *  - "content": rendered inside a column, picked via the "+ Add Block" modal
+   *  - "section": rendered as a full-width section-level block, picked via
+   *     the "+ Add Section" modal (same pattern as projectGridBlock /
+   *     projectCarouselBlock)
+   */
+  category: "content" | "section";
+  /**
+   * Legacy single-char / emoji icon kept for backward compatibility with
+   * `ALL_BLOCK_INFO` entries and debug UIs. Prefer `cardIcon` for rich
+   * visuals.
+   */
+  iconGlyph?: string;
+
+  // ── Sanity ──
+  /**
+   * Sanity schema (result of `defineType(...)`). Kept as `unknown` because
+   * Sanity's internal types are not worth pulling through the generic.
+   * Studio consumers cast at registration time.
+   */
+  schema: unknown;
+
+  // ── Factory ──
+  /**
+   * Creates a default instance of this block type. Receives a pre-generated
+   * `_key` so the caller controls key generation (e.g. for deterministic
+   * snapshots in tests).
+   */
+  defaultFactory: (key: string) => T;
+
+  // ── Runtime components ──
+  /** Public-site renderer (used inside `BlockRenderer`). */
+  renderer: React.ComponentType<{ block: T }>;
+  /**
+   * Builder canvas live preview. Signature is intentionally permissive —
+   * some previews consume `viewport`, some `editable`, most neither. At the
+   * callsite, props are forwarded from `BlockLivePreview`.
+   */
+  livePreview: React.ComponentType<{
+    block: T;
+    viewport?: DeviceViewport;
+    editable?: boolean;
+  }>;
+  /** Settings-panel editor for this block type. */
+  editor: React.ComponentType<{ block: T }>;
+
+  // ── Icons ──
+  /**
+   * Full-size card icon (220×120) used in the "+ Add Block" or "+ Add
+   * Section" picker modal. For section-level blocks, this is the violet
+   * variant from `SectionCardIcons.tsx`; for content blocks, the blue
+   * variant from `BlockCardIcons.tsx`.
+   */
+  cardIcon: React.FC;
+  /**
+   * Compact icon used in the settings panel header, auto-scaled via
+   * `blockStyles.scaleToHeight()` to whatever `size` the caller requests.
+   */
+  compactIcon: React.FC<{ size?: number }>;
+
+  // ── Animation preset allowlists ──
+  /**
+   * Which enter-animation presets apply to this block. Used by
+   * `BLOCK_ENTER_PRESETS` in `lib/animation/enter-types.ts`.
+   */
+  enterPresets: readonly string[];
+  /**
+   * Which hover-effect presets apply to this block. Used by
+   * `BLOCK_HOVER_PRESETS` in `lib/animation/hover-effect-types.ts`.
+   */
+  hoverPresets: readonly string[];
+}
+
+/**
+ * Concrete registration stored in the map. Erases the block-type generic
+ * so heterogeneous registrations can coexist in the same `Map`.
+ */
+export type BlockRegistration = BlockRegistrationInput;
+
+// ────────────────────────────────────────────────────────────────────
+// Registry state (module-level singleton)
+// ────────────────────────────────────────────────────────────────────
+
+const REGISTRY: Map<string, BlockRegistration> = new Map();
+
+// ────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Register a block type. Called once per block type from
+ * `./block-registrations.ts` during module initialization. In dev mode,
+ * warns on duplicate type strings (which usually indicate a bug).
+ */
+export function registerBlockType<T extends ContentBlock>(
+  registration: BlockRegistrationInput<T>,
+): void {
+  if (REGISTRY.has(registration.type)) {
+    if (process.env.NODE_ENV !== "production") {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[block-registry] Duplicate registration for "${registration.type}" — overwriting. ` +
+          `This usually indicates registrations.ts was imported twice or a block type was registered from multiple places.`,
+      );
+    }
+  }
+  REGISTRY.set(
+    registration.type,
+    registration as unknown as BlockRegistration,
+  );
+}
+
+/**
+ * Look up a registration by block type. Returns `undefined` for unknown
+ * types (including when the registrations module hasn't been imported yet).
+ */
+export function getBlockRegistration<T extends ContentBlock = ContentBlock>(
+  type: string,
+): BlockRegistrationInput<T> | undefined {
+  return REGISTRY.get(type) as BlockRegistrationInput<T> | undefined;
+}
+
+/**
+ * All currently-registered blocks in insertion order. Safe to iterate —
+ * the returned array is a snapshot, not a live view of the registry.
+ */
+export function getAllBlockRegistrations(): readonly BlockRegistration[] {
+  return Array.from(REGISTRY.values());
+}
+
+/** Cheap existence check for dispatch-site assertions. */
+export function hasBlockRegistration(type: string): boolean {
+  return REGISTRY.has(type);
+}
+
+/**
+ * Reset the registry. Only used by tests that want a clean slate between
+ * suites — production code should never call this.
+ *
+ * @internal
+ */
+export function __clearBlockRegistryForTests(): void {
+  REGISTRY.clear();
+}

package/lib/builder/defaults.ts

@@ -4,6 +4,12 @@ import { generateKey } from "./utils";
 import type { EnterAnimationConfig, TypewriterConfig } from "../../lib/animation/enter-types";
 import type { HoverEffectConfig } from "../../lib/animation/hover-effect-types";
 
+// Side-effect import: populates the block registry with all built-in block
+// types so `createDefaultBlock` can delegate to each registration's
+// `defaultFactory`. See `./block-registry.ts` for the stability contract.
+import "./block-registrations";
+import { getBlockRegistration } from "./block-registry";
+
 // ============================================
 // Parallax slide defaults (Session 128)
 // ============================================
@@ -116,88 +122,23 @@ export const DEFAULT_TYPEWRITER_CONFIG: Required<TypewriterConfig> = {
 
 /**
  * Create a new block with sensible defaults for the given block type.
+ *
+ * Session 181 (C): switched from a giant switch-case to a registry lookup.
+ * Each block type now declares its default shape in
+ * `./block-registrations.ts` via the `defaultFactory` field. The
+ * registration module is loaded eagerly here (side-effect import) so the
+ * registry is populated before any `createDefaultBlock` call.
+ *
+ * Unknown block types fall back to the minimal `{ _type, _key }` shape —
+ * same behavior as the previous switch-case's `default` branch.
  */
 export function createDefaultBlock(blockType: BlockType): ContentBlock {
-  const _key = generateKey();
-
-  switch (blockType) {
-    case "textBlock":
-      return {
-        _type: "textBlock",
-        _key,
-        text: [],
-        style: { fontSize: 14, alignment: "left", fontWeight: "400" },
-      };
-    case "imageBlock":
-      return {
-        _type: "imageBlock",
-        _key,
-        asset_path: "",
-        alt: "",
-        width: "full",
-        aspect_ratio: "auto",
-        lazy: true,
-        shadow: false,
-        border_radius: "",
-      };
-    case "imageGridBlock":
-      return {
-        _type: "imageGridBlock",
-        _key,
-        images: [],
-        h_gutter: 10,
-        v_gutter: 10,
-        images_per_row: 2,
-        random_grid: "disabled",
-        random_seed: 1,
-        lightbox: false,
-        object_fit: "cover",
-      };
-    case "videoBlock":
-      return {
-        _type: "videoBlock",
-        _key,
-        video_type: "vimeo",
-        url_or_path: "",
-        autoplay: false,
-        loop: false,
-        muted: true,
-        controls: true,
-        aspect_ratio: "16:9",
-      };
-    case "spacerBlock":
-      return {
-        _type: "spacerBlock",
-        _key,
-        height: "medium",
-      };
-    case "buttonBlock":
-      return {
-        _type: "buttonBlock",
-        _key,
-        text: "Button",
-        url: "#",
-        style: "primary",
-        size: "medium",
-      };
-    case "projectGridBlock":
-      return {
-        _type: "projectGridBlock",
-        _key,
-        columns: 3,
-        aspect_ratios: ["16/9"],
-        gap_v: 16,
-        gap_h: 16,
-        hover_effect: "scale",
-        show_subtitle: true,
-        border_radius: 0,
-        video_mode: "off",
-        projects: [],
-      };
-    default:
-      return {
-        _type: blockType,
-        _key,
-      } as ContentBlock;
+  const registration = getBlockRegistration(blockType);
+  if (registration) {
+    return registration.defaultFactory(generateKey());
   }
+  return {
+    _type: blockType,
+    _key: generateKey(),
+  } as ContentBlock;
 }

package/lib/builder/index.ts

@@ -19,3 +19,19 @@ export type {
   SectionTypeInfo,
   SectionBlockType,
 } from "./types";
+
+// ── Block registry (Session A + B: infrastructure + consistency validation) ──
+//
+// Registry API re-exports for consumers that want to register custom block
+// types or introspect the built-in ones. See `./registry` for the batteries-
+// included entry point (triggers `block-registrations` as a side effect).
+export type {
+  BlockRegistration,
+  BlockRegistrationInput,
+} from "./block-registry";
+export {
+  registerBlockType,
+  getBlockRegistration,
+  getAllBlockRegistrations,
+  hasBlockRegistration,
+} from "./block-registry";

package/lib/builder/registry.ts

@@ -0,0 +1,44 @@
+/**
+ * Block registry — batteries-included entry point.
+ *
+ * Importing this module triggers the side-effect load of
+ * `./block-registrations`, populating the registry with all 8 built-in
+ * block types (text, image, imageGrid, video, spacer, button, projectGrid,
+ * projectCarousel). Then re-exports the registry query API so consumers
+ * can introspect registrations with one import.
+ *
+ * ## When to use this vs `./block-registry`
+ *
+ * - **`./block-registry`** — the bare API (types + `registerBlockType` +
+ *   query helpers). Use this if you're registering custom blocks in an
+ *   instance and want to control population order.
+ * - **`./registry`** (this file) — convenience wrapper. Use this if you
+ *   just want to read the built-in registrations from an instance or
+ *   documentation script.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { getAllBlockRegistrations } from "@morphika/andami/lib/builder/registry";
+ *
+ * // Registry is already populated — no side-effect import needed.
+ * const allBlocks = getAllBlockRegistrations();
+ * console.log(allBlocks.map(r => r.type));
+ * // → ["textBlock", "imageBlock", ..., "projectCarouselBlock"]
+ * ```
+ */
+
+// Side-effect: fill the registry with all built-in block types.
+import "./block-registrations";
+
+export type {
+  BlockRegistration,
+  BlockRegistrationInput,
+} from "./block-registry";
+
+export {
+  registerBlockType,
+  getBlockRegistration,
+  getAllBlockRegistrations,
+  hasBlockRegistration,
+} from "./block-registry";

package/lib/builder/store-sections.ts

@@ -57,7 +57,7 @@ export function createSectionActions(set: StoreSet, get: StoreGet) {
      * Existing V1 pages still work — V1 update/delete actions are kept until
      * the data migration in Session 165.
      */
-    addSection: (blockType: "projectGridBlock", afterRowKey?: string | null): void => {
+    addSection: (blockType: "projectGridBlock" | "projectCarouselBlock", afterRowKey?: string | null): void => {
       get()._pushSnapshot();
       const block = createDefaultBlock(blockType);
       const gridColumns = 12;

package/lib/builder/types.ts

@@ -62,6 +62,7 @@ export const ALL_BLOCK_INFO: BlockTypeInfo[] = [
   ...BLOCK_TYPE_REGISTRY,
   // Section blocks — not in the content picker but still need label/icon lookup
   { type: "projectGridBlock", label: "Project Grid", description: "Staggered project showcase grid", group: "generic", icon: "⬡", category: "section" },
+  { type: "projectCarouselBlock", label: "Project Carousel", description: "Horizontal carousel of projects — great for end-of-page 'keep browsing'", group: "generic", icon: "▸", category: "section" },
 ];
 
 // Parallax group info — used by BuilderCanvas/SortableRow for label/icon lookup (not a block)
@@ -72,10 +73,13 @@ export const PARALLAX_GROUP_INFO = { label: "Parallax Showcase", icon: "▽" };
 // ============================================
 
 /** Section block types that create a full-width row with a pre-populated block */
-export type SectionBlockType = "projectGridBlock";
+export type SectionBlockType = "projectGridBlock" | "projectCarouselBlock";
 
 /** Set for fast lookup — used by SortableBlock, ColumnDropZone, SortableRow to suppress inner chrome */
-const SECTION_BLOCK_TYPES: ReadonlySet<string> = new Set<string>(["projectGridBlock"]);
+const SECTION_BLOCK_TYPES: ReadonlySet<string> = new Set<string>([
+  "projectGridBlock",
+  "projectCarouselBlock",
+]);
 
 /** Check if a block type is a section-level block (should render without block/column chrome) */
 export function isSectionBlockType(type: string): boolean {
@@ -107,6 +111,7 @@ export const SECTION_TYPE_REGISTRY: SectionTypeInfo[] = [
   { type: "empty-v2", label: "Empty Section", description: "Grid section with flexible columns", icon: "⊞" },
   { type: "coverSection", label: "Cover Section", description: "Full-viewport section with background and proportional rows", icon: "◆" },
   { type: "projectGridBlock", label: "Project Grid", description: "Staggered project showcase grid", icon: "⬡", blockType: "projectGridBlock" },
+  { type: "projectCarouselBlock", label: "Project Carousel", description: "Horizontal 'keep browsing' carousel of projects", icon: "▸", blockType: "projectCarouselBlock" },
   { type: "parallaxGroup", label: "Parallax Section", description: "Full-screen parallax showcase with V2 slides", icon: "▽" },
 ];
 
@@ -266,7 +271,7 @@ export interface BuilderActions {
 
   // Section operations
   /** Add a Project Grid section as a V2 section with a full-width column (Session 164) */
-  addSection: (blockType: "projectGridBlock", afterRowKey?: string | null) => void;
+  addSection: (blockType: "projectGridBlock" | "projectCarouselBlock", afterRowKey?: string | null) => void;
   reorderRows: (fromIndex: number, toIndex: number) => void;
   /** Delete a section by key */
   deleteSection: (sectionKey: string) => void;

package/lib/sanity/types.ts

@@ -240,6 +240,54 @@ export interface CardEntranceConfig {
   duration?: number;                              // ms, default 500
 }
 
+/**
+ * Project Carousel Block — horizontal "keep browsing" carousel of projects.
+ *
+ * Section-level block (lives in a full-width column). Unlike `projectGridBlock`
+ * there is no manual selection list — projects are pulled automatically (latest
+ * or random), optionally excluding the project currently being viewed when the
+ * page matches `/work/[slug]`.
+ *
+ * Intentionally independent from `ProjectGridBlock` — they share visual
+ * primitives and the same `/api/projects` endpoint but no coupled code.
+ */
+export interface ProjectCarouselBlock {
+  _type: "projectCarouselBlock";
+  _key: string;
+
+  // ─── Source ───
+  source_mode?: "auto_latest" | "auto_random";
+  max_projects?: number;         // 2–20, default 8
+  exclude_current?: boolean;     // default true
+
+  // ─── Layout ───
+  cards_per_view_desktop?: number; // default 3.5 (fractional → peek next card)
+  cards_per_view_tablet?: number;  // default 2.2
+  cards_per_view_phone?: number;   // default 1.2
+  gap?: number;                     // px, default 16
+
+  // ─── Card display ───
+  aspect_ratio?: "16/9" | "4/3" | "1/1" | "3/4" | "9/16";
+  show_title?: boolean;             // default true
+  show_subtitle?: boolean;          // default false
+  border_radius?: number;           // px, default 0
+  hover_effect?: "scale" | "none";  // default "scale"
+  video_mode?: "off" | "hover" | "autoloop"; // default "off"
+
+  // ─── Controls ───
+  show_arrows?: boolean;            // default true
+  show_dots?: boolean;              // default false
+  snap_scroll?: boolean;            // default true
+
+  // ─── Card entrance animation ───
+  card_entrance?: CardEntranceConfig;
+
+  // ─── Standard block fields ───
+  enter_animation?: import("../../lib/animation/enter-types").EnterAnimationConfig;
+  layout?: BlockLayout;
+  responsive?: ResponsiveOverrides<ProjectCarouselBlock>;
+}
+
 export interface ProjectGridBlock {
   _type: "projectGridBlock";
   _key: string;
@@ -570,7 +618,8 @@ export type ContentBlock =
   | VideoBlock
   | SpacerBlock
   | ButtonBlock
-  | ProjectGridBlock;
+  | ProjectGridBlock
+  | ProjectCarouselBlock;
 
 // ============================================
 // Structural types

package/lib/version.ts

@@ -6,4 +6,4 @@
  * Exposed as a plain constant so it can be imported without reading
  * package.json at runtime.
  */
-export const ANDAMI_VERSION = "0.3.1";
+export const ANDAMI_VERSION = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morphika/andami",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Visual Page Builder — core library. A reusable website builder with visual editing, CMS integration, and asset management.",
   "type": "module",
   "license": "MIT",

package/sanity/schemas/blocks/index.ts

@@ -1,4 +1,4 @@
-// Block schemas (7)
+// Block schemas (8)
 export { textBlock } from "./textBlock";
 export { imageBlock } from "./imageBlock";
 export { imageGridBlock } from "./imageGridBlock";
@@ -6,3 +6,4 @@ export { videoBlock } from "./videoBlock";
 export { spacerBlock } from "./spacerBlock";
 export { buttonBlock } from "./buttonBlock";
 export { projectGridBlock } from "./projectGridBlock";
+export { projectCarouselBlock } from "./projectCarouselBlock";