@morphika/webframe 0.1.0

package/lib/builder/cascade.ts

@@ -0,0 +1,533 @@
+/**
+ * Push Cascade Engine — V2 Grid System
+ *
+ * The central algorithm driving resize, drag & drop, and add column.
+ * A single, reusable pure function engine.
+ *
+ * Rules:
+ * 1. Horizontal push within a row: When column A grows or is inserted,
+ *    everything to its right shifts rightward.
+ * 2. Overflow → drop to next row: If a column exceeds grid_columns,
+ *    it moves to the next row at position 1, keeping its span.
+ * 3. Cascade continues: If the dropped column collides with columns in
+ *    the destination row, horizontal push applies again.
+ * 4. Always terminates: In the worst case, each column occupies its own row.
+ * 5. Column constraints: Span 1–grid_columns (integer). Grid positions are integers.
+ * 6. Atomic undo: The entire cascade is a single history entry.
+ *
+ * Session 83: V2 Grid System — Phase 1.
+ */
+
+import type { SectionColumn } from "../../lib/sanity/types";
+import { logger } from "../../lib/logger";
+
+// ============================================
+// Types
+// ============================================
+
+/** Minimal column representation for cascade computation */
+export interface CascadeColumn {
+  _key: string;
+  grid_column: number;  // 1-based
+  grid_row: number;     // 1-based
+  span: number;         // 1–gridColumns
+}
+
+// ============================================
+// Core Cascade
+// ============================================
+
+/**
+ * Compute the push cascade for a flat list of columns within a section.
+ *
+ * Given a set of columns (potentially with overlapping or overflowing positions),
+ * resolves all conflicts by pushing columns rightward and dropping to new rows
+ * when they overflow.
+ *
+ * @param columns - The columns to resolve (will NOT be mutated)
+ * @param gridColumns - Total columns in the grid (default 12)
+ * @returns A new array of columns with valid, non-overlapping positions
+ */
+export function computeCascade(
+  columns: CascadeColumn[],
+  gridColumns: number = 12
+): CascadeColumn[] {
+  if (columns.length === 0) return [];
+
+  // Defensive validation — warn on invalid input but don't throw (self-healing)
+  if (gridColumns < 1 || !Number.isInteger(gridColumns)) {
+    logger.warn("[Cascade]", "Invalid gridColumns, defaulting to 12", { gridColumns });
+    gridColumns = 12;
+  }
+
+  // Deep clone to avoid mutation
+  const cols = columns.map((c) => {
+    // Clamp and warn on out-of-range values
+    const span = Math.max(1, Math.min(Math.round(c.span), gridColumns));
+    const grid_column = Math.max(1, Math.round(c.grid_column));
+    const grid_row = Math.max(1, Math.round(c.grid_row));
+
+    if (span !== c.span || grid_column !== c.grid_column || grid_row !== c.grid_row) {
+      logger.warn("[Cascade]", "Clamped invalid column values", {
+        key: c._key,
+        original: { span: c.span, grid_column: c.grid_column, grid_row: c.grid_row },
+        clamped: { span, grid_column, grid_row },
+      });
+    }
+
+    return { ...c, span, grid_column, grid_row };
+  });
+
+  // Convergence loop: resolve overlaps and overflows across all rows
+  // until no more changes occur. Handles cascading effects where
+  // pushing a column to a new row creates new conflicts.
+  const maxIterations = cols.length * gridColumns; // Safety limit
+  let stable = false;
+  let passes = 0;
+  while (!stable && passes < maxIterations) {
+    passes++;
+    stable = true;
+    const allRows = [...new Set(cols.map((c) => c.grid_row))].sort((a, b) => a - b);
+
+    for (const row of allRows) {
+      const rowCols = cols
+        .filter((c) => c.grid_row === row)
+        .sort((a, b) => a.grid_column - b.grid_column);
+
+      if (rowCols.length <= 1) continue;
+
+      // Resolve overlaps
+      const hadOverlap = resolveRowOverlaps(rowCols);
+      if (hadOverlap) stable = false;
+
+      // Check for overflows
+      for (const col of rowCols) {
+        if (col.grid_column + col.span - 1 > gridColumns) {
+          col.grid_row = row + 1;
+          col.grid_column = 1;
+          stable = false;
+        }
+      }
+    }
+  }
+
+  if (!stable) {
+    logger.warn("[Cascade]", "Convergence limit reached — layout may have unresolved overlaps", {
+      passes,
+      maxIterations,
+      columnCount: cols.length,
+    });
+  }
+
+  return cols;
+}
+
+/**
+ * Resolve overlaps within a single row by pushing columns rightward.
+ * Columns must be sorted by grid_column (ascending).
+ * Mutates the columns in place.
+ *
+ * @returns true if any columns were moved
+ */
+function resolveRowOverlaps(rowCols: CascadeColumn[]): boolean {
+  let moved = false;
+
+  for (let i = 1; i < rowCols.length; i++) {
+    const prev = rowCols[i - 1];
+    const curr = rowCols[i];
+    const prevEnd = prev.grid_column + prev.span; // 1 past the end of prev
+
+    if (curr.grid_column < prevEnd) {
+      // Overlap — push current to just after prev
+      curr.grid_column = prevEnd;
+      moved = true;
+    }
+  }
+
+  return moved;
+}
+
+/**
+ * Get the maximum row number across all columns.
+ */
+function getMaxRow(cols: CascadeColumn[]): number {
+  if (cols.length === 0) return 0;
+  return Math.max(...cols.map((c) => c.grid_row));
+}
+
+// ============================================
+// Preset Detection
+// ============================================
+
+/**
+ * Detect which preset a set of columns matches, if any.
+ * Returns "custom" if no preset matches.
+ */
+export function detectPreset(
+  columns: CascadeColumn[],
+  gridColumns: number = 12
+): "full" | "halves" | "thirds" | "quarters" | "1/3+2/3" | "2/3+1/3" | "custom" {
+  // All columns must be on row 1 for a preset match
+  if (columns.length === 0) return "full";
+  if (columns.some((c) => c.grid_row !== 1)) return "custom";
+
+  const sorted = [...columns].sort((a, b) => a.grid_column - b.grid_column);
+  const spans = sorted.map((c) => c.span);
+
+  // Check contiguous placement (no gaps)
+  let expectedCol = 1;
+  for (const col of sorted) {
+    if (col.grid_column !== expectedCol) return "custom";
+    expectedCol = col.grid_column + col.span;
+  }
+  // Must fill exactly gridColumns
+  if (expectedCol - 1 !== gridColumns) return "custom";
+
+  // Match against known presets
+  const key = spans.join(",");
+
+  // For 12-column grid, specific common presets
+  if (gridColumns === 12) {
+    if (key === "12") return "full";
+    if (key === "6,6") return "halves";
+    if (key === "4,4,4") return "thirds";
+    if (key === "3,3,3,3") return "quarters";
+    if (key === "4,8") return "1/3+2/3";
+    if (key === "8,4") return "2/3+1/3";
+  } else {
+    // Generic preset detection for non-12 grids
+    if (spans.length === 1 && spans[0] === gridColumns) return "full";
+    if (spans.length === 2 && spans[0] === spans[1] && spans[0] * 2 === gridColumns) return "halves";
+    if (spans.length === 3 && spans.every((s) => s === spans[0]) && spans[0] * 3 === gridColumns) return "thirds";
+    if (spans.length === 4 && spans.every((s) => s === spans[0]) && spans[0] * 4 === gridColumns) return "quarters";
+  }
+
+  return "custom";
+}
+
+// ============================================
+// Column Operations (use cascade internally)
+// ============================================
+
+/**
+ * Resize a column to a new span, applying push cascade.
+ *
+ * @param columns - All columns in the section
+ * @param columnKey - The column to resize
+ * @param newSpan - The desired new span
+ * @param gridColumns - Total columns in the grid
+ * @returns Updated columns after cascade
+ */
+export function resizeColumn(
+  columns: CascadeColumn[],
+  columnKey: string,
+  newSpan: number,
+  gridColumns: number = 12
+): CascadeColumn[] {
+  if (!columns.find((c) => c._key === columnKey)) {
+    logger.warn("[Cascade]", "resizeColumn: column not found", { columnKey });
+    return columns.map((c) => ({ ...c }));
+  }
+  const clampedSpan = Math.max(1, Math.min(newSpan, gridColumns));
+  const updated = columns.map((c) =>
+    c._key === columnKey ? { ...c, span: clampedSpan } : { ...c }
+  );
+  return computeCascade(updated, gridColumns);
+}
+
+/**
+ * Resize a column from the left edge (stretch left).
+ * Moves the column's start position leftward and increases span.
+ *
+ * When expanding left into a neighbor, the neighbor is compressed
+ * (its span shrinks to make room) down to a minimum of 1 column.
+ * Only the immediate left neighbor is affected — no recursive cascade.
+ *
+ * Returns null only when truly impossible (column not found, or the
+ * neighbor is already at span 1 and can't shrink further).
+ *
+ * The `neighborAtMinimum` flag in the result signals that the left
+ * neighbor has been compressed to its minimum span (1), so the UI
+ * can show a visual indicator that further expansion is blocked.
+ *
+ * @param columns - All columns in the section
+ * @param columnKey - The column to resize
+ * @param newGridColumn - The desired new start position
+ * @param gridColumns - Total columns in the grid
+ * @returns Updated columns + metadata, or null if completely blocked
+ */
+export interface ResizeLeftResult {
+  columns: CascadeColumn[];
+  /** Key of the left neighbor that was compressed, if any */
+  compressedNeighborKey: string | null;
+  /** True when the left neighbor is at minimum span (1) — further expansion blocked */
+  neighborAtMinimum: boolean;
+}
+
+export function resizeColumnLeft(
+  columns: CascadeColumn[],
+  columnKey: string,
+  newGridColumn: number,
+  gridColumns: number = 12
+): ResizeLeftResult | null {
+  const col = columns.find((c) => c._key === columnKey);
+  if (!col) return null;
+
+  // The right edge stays fixed: rightEdge = col.grid_column + col.span - 1
+  const rightEdge = col.grid_column + col.span - 1;
+
+  // Clamp: can't go past position 1 on the left, and can't go past
+  // rightEdge on the right (minimum span of 1)
+  let clampedStart = Math.max(1, Math.min(newGridColumn, rightEdge));
+
+  // Find the column immediately to the left in the same row
+  const sameRowCols = columns
+    .filter((c) => c.grid_row === col.grid_row && c._key !== columnKey)
+    .sort((a, b) => a.grid_column - b.grid_column);
+
+  const leftNeighbor = sameRowCols
+    .filter((c) => c.grid_column + c.span - 1 < col.grid_column)
+    .pop(); // rightmost column that ends before us
+
+  let compressedNeighborKey: string | null = null;
+  let neighborAtMinimum = false;
+  let neighborNewSpan: number | null = null;
+
+  if (leftNeighbor) {
+    // Hard floor: neighbor can't shrink below span 1
+    const neighborAbsoluteMin = leftNeighbor.grid_column + 1; // neighbor at span 1 ends here
+    const freeStart = leftNeighbor.grid_column + leftNeighbor.span; // current free position
+
+    if (clampedStart < freeStart) {
+      // We're pushing into the neighbor — compress it
+      // The neighbor's new span = clampedStart - neighbor.grid_column
+      const desiredNeighborSpan = clampedStart - leftNeighbor.grid_column;
+
+      if (desiredNeighborSpan < 1) {
+        // Can't compress further — clamp our start to neighbor's absolute minimum
+        clampedStart = neighborAbsoluteMin;
+        neighborNewSpan = 1;
+        neighborAtMinimum = true;
+      } else {
+        neighborNewSpan = desiredNeighborSpan;
+        neighborAtMinimum = desiredNeighborSpan === 1;
+      }
+
+      compressedNeighborKey = leftNeighbor._key;
+    }
+  }
+
+  // Compute new span from the fixed right edge
+  const newSpan = rightEdge - clampedStart + 1;
+
+  if (newSpan < 1 || newSpan > gridColumns) return null;
+
+  // If nothing changed (same position as current), return null
+  if (clampedStart === col.grid_column && !compressedNeighborKey) return null;
+
+  const updated = columns.map((c) => {
+    if (c._key === columnKey) {
+      return { ...c, grid_column: clampedStart, span: newSpan };
+    }
+    if (c._key === compressedNeighborKey && neighborNewSpan !== null) {
+      return { ...c, span: neighborNewSpan };
+    }
+    return { ...c };
+  });
+
+  return { columns: updated, compressedNeighborKey, neighborAtMinimum };
+}
+
+/**
+ * Add a new column at a specific gap position.
+ * The column fills the available gap space.
+ *
+ * @param columns - All columns in the section
+ * @param gridRow - The row to add the column in
+ * @param gridColumn - The start position for the new column
+ * @param span - The span for the new column
+ * @param columnKey - The _key for the new column
+ * @param gridColumns - Total columns in the grid
+ * @returns Updated columns with the new column added, after cascade
+ */
+export function addColumn(
+  columns: CascadeColumn[],
+  gridRow: number,
+  gridColumn: number,
+  span: number,
+  columnKey: string,
+  gridColumns: number = 12
+): CascadeColumn[] {
+  const newCol: CascadeColumn = {
+    _key: columnKey,
+    grid_column: gridColumn,
+    grid_row: gridRow,
+    span: Math.max(1, Math.min(span, gridColumns)),
+  };
+
+  const updated = [...columns.map((c) => ({ ...c })), newCol];
+  return computeCascade(updated, gridColumns);
+}
+
+/**
+ * Move a column to a new position (drag & drop).
+ *
+ * @param columns - All columns in the section
+ * @param columnKey - The column to move
+ * @param targetRow - The destination row
+ * @param targetColumn - The destination grid column
+ * @param gridColumns - Total columns in the grid
+ * @returns Updated columns after cascade
+ */
+export function moveColumn(
+  columns: CascadeColumn[],
+  columnKey: string,
+  targetRow: number,
+  targetColumn: number,
+  gridColumns: number = 12
+): CascadeColumn[] {
+  if (!columns.find((c) => c._key === columnKey)) {
+    logger.warn("[Cascade]", "moveColumn: column not found", { columnKey });
+    return columns.map((c) => ({ ...c }));
+  }
+  const updated = columns.map((c) =>
+    c._key === columnKey
+      ? { ...c, grid_row: targetRow, grid_column: Math.max(1, Math.min(targetColumn, gridColumns)) }
+      : { ...c }
+  );
+  return computeCascade(updated, gridColumns);
+}
+
+/**
+ * Delete a column. Returns the remaining columns (no cascade needed
+ * since deletion only creates empty space, and per the spec,
+ * remaining columns do NOT collapse into the gap).
+ *
+ * @param columns - All columns in the section
+ * @param columnKey - The column to delete
+ * @returns Updated columns with the column removed
+ */
+export function deleteColumn(
+  columns: CascadeColumn[],
+  columnKey: string
+): CascadeColumn[] {
+  return columns.filter((c) => c._key !== columnKey).map((c) => ({ ...c }));
+}
+
+// ============================================
+// Gap Detection (for + Add Column buttons)
+// ============================================
+
+export interface GridGap {
+  grid_row: number;
+  grid_column: number;    // start position of the gap
+  span: number;           // width of the gap in grid columns
+}
+
+/**
+ * Find all empty gaps in the grid where "+ Add Column" buttons should appear.
+ *
+ * @param columns - All columns in the section
+ * @param gridColumns - Total columns in the grid
+ * @returns Array of gaps sorted by row then column
+ */
+export function findGaps(
+  columns: CascadeColumn[],
+  gridColumns: number = 12
+): GridGap[] {
+  if (columns.length === 0) {
+    // Entire grid is one big gap
+    return [{ grid_row: 1, grid_column: 1, span: gridColumns }];
+  }
+
+  const gaps: GridGap[] = [];
+  const maxRow = getMaxRow(columns);
+
+  for (let row = 1; row <= maxRow; row++) {
+    const rowCols = columns
+      .filter((c) => c.grid_row === row)
+      .sort((a, b) => a.grid_column - b.grid_column);
+
+    if (rowCols.length === 0) {
+      // Empty row — entire row is a gap
+      gaps.push({ grid_row: row, grid_column: 1, span: gridColumns });
+      continue;
+    }
+
+    // Check gap before first column
+    if (rowCols[0].grid_column > 1) {
+      gaps.push({
+        grid_row: row,
+        grid_column: 1,
+        span: rowCols[0].grid_column - 1,
+      });
+    }
+
+    // Check gaps between columns
+    for (let i = 0; i < rowCols.length - 1; i++) {
+      const endOfCurrent = rowCols[i].grid_column + rowCols[i].span;
+      const startOfNext = rowCols[i + 1].grid_column;
+      if (startOfNext > endOfCurrent) {
+        gaps.push({
+          grid_row: row,
+          grid_column: endOfCurrent,
+          span: startOfNext - endOfCurrent,
+        });
+      }
+    }
+
+    // Check gap after last column
+    const lastCol = rowCols[rowCols.length - 1];
+    const endOfLast = lastCol.grid_column + lastCol.span;
+    if (endOfLast <= gridColumns) {
+      gaps.push({
+        grid_row: row,
+        grid_column: endOfLast,
+        span: gridColumns - endOfLast + 1,
+      });
+    }
+  }
+
+  return gaps;
+}
+
+// ============================================
+// Preset → Columns factory
+// ============================================
+
+/**
+ * Create columns from a preset layout.
+ *
+ * @param preset - The layout preset
+ * @param gridColumns - Total columns in the grid (default 12)
+ * @param keyFactory - Function to generate unique keys
+ * @returns Array of columns matching the preset layout
+ */
+export function columnsFromPreset(
+  preset: "full" | "halves" | "thirds" | "quarters" | "1/3+2/3" | "2/3+1/3",
+  gridColumns: number = 12,
+  keyFactory: () => string = () => Math.random().toString(36).substring(2, 14)
+): CascadeColumn[] {
+  const presetSpans: Record<string, number[]> = {
+    full: [gridColumns],
+    halves: [gridColumns / 2, gridColumns / 2],
+    thirds: [gridColumns / 3, gridColumns / 3, gridColumns / 3],
+    quarters: [gridColumns / 4, gridColumns / 4, gridColumns / 4, gridColumns / 4],
+    "1/3+2/3": [Math.round(gridColumns / 3), gridColumns - Math.round(gridColumns / 3)],
+    "2/3+1/3": [gridColumns - Math.round(gridColumns / 3), Math.round(gridColumns / 3)],
+  };
+
+  const spans = presetSpans[preset] || [gridColumns];
+  let currentCol = 1;
+
+  return spans.map((span) => {
+    const col: CascadeColumn = {
+      _key: keyFactory(),
+      grid_column: currentCol,
+      grid_row: 1,
+      span: Math.round(span),
+    };
+    currentCol += Math.round(span);
+    return col;
+  });
+}

package/lib/builder/constants.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared constants for the builder and public site renderers.
+ * Consolidates duplicated maps and utility functions.
+ */
+
+
+// ============================================
+// Responsive Breakpoints
+// ============================================
+// Single source of truth for all media query breakpoints.
+// Import these instead of hardcoding numeric values.
+
+export const BREAKPOINTS = {
+  /** Phone max-width breakpoint (640px) */
+  phone: 640,
+  /** Scroll animation disable breakpoint (768px) */
+  mobileAnimation: 768,
+  /** Tablet max-width breakpoint (1024px) */
+  tablet: 1024,
+} as const;
+
+// ============================================
+// Default Grid Width
+// ============================================
+// The default page grid max-width in pixels.
+
+export const DEFAULT_GRID_WIDTH = "1445";
+export const DEFAULT_GRID_WIDTH_PX = `${DEFAULT_GRID_WIDTH}px`;
+
+// ============================================
+// Default Page Colors
+// ============================================
+// Default background and text colors for new pages.
+
+export const DEFAULT_BG_COLOR = "#ffffff";
+export const DEFAULT_TEXT_COLOR = "#000000";
+
+// ============================================
+// Admin UI Colors
+// ============================================
+// Accent colors used throughout the admin/builder interface.
+// These are also available as CSS custom properties:
+//   --admin-accent, --admin-accent-dark
+
+export const ADMIN_ACCENT = "#076bff";
+export const ADMIN_ACCENT_DARK = "#0559d4";
+export const ADMIN_ACCENT_SHADOW = "rgba(7,107,255,0.06)";
+export const ADMIN_ERROR = "#ed3821";
+export const ADMIN_ERROR_DARK = "#d42f1a";
+
+// ============================================
+// Builder Semantic Color System
+// ============================================
+// Each UI entity in the builder has a dedicated color to provide
+// visual differentiation at a glance. This is a design rule that
+// MUST be followed across all builder components.
+//
+//   BLUE    (#076bff) — Columns: outlines, resize handles, drag grip,
+//                        span badge, column selection/hover chrome.
+//   ORANGE  (#e28b00) — Blocks: "+ Add Block" buttons, block toolbar
+//                        pill, block selection ring, block-level actions.
+//   GREEN   (#22c55e) — Drop zones: gap drop targets during drag,
+//                        insertion lines, "Drop Here" labels, swap target
+//                        highlight (green border + tinted background).
+//   VIOLET  (#8b5cf6) — Custom sections: saved section cards, custom
+//                        section instance badges, section editor chrome,
+//                        "Create New" custom section button.
+//
+// When adding new builder UI, pick the color that matches the entity
+// being represented, not the action being performed. For example, a
+// delete button on a column is BLUE (it belongs to the column chrome),
+// while a delete button on a block toolbar is ORANGE.
+
+export const BUILDER_BLUE = "#076bff";       // Columns
+export const BUILDER_ORANGE = "#e28b00";     // Blocks
+export const BUILDER_GREEN = "#22c55e";      // Drop zones
+export const BUILDER_VIOLET = "#8b5cf6";     // Custom sections
+
+/**
+ * Padding map for Row settings (in pixels)
+ * Used by builder (SortableRow, ReadOnlyFrame) and public site (RowRenderer)
+ */
+export const PADDING_MAP: Record<string, string> = {
+  none: "0",
+  small: "16px",
+  medium: "32px",
+  large: "64px",
+  xlarge: "96px",
+};
+
+/**
+ * Padding map for Row settings (in Tailwind classes)
+ * Used only by public site (RowRenderer) when using class-based padding
+ */
+export const PADDING_CLASSES_MAP: Record<string, string> = {
+  none: "py-0",
+  small: "py-4",
+  medium: "py-8",
+  large: "py-16",
+  xlarge: "py-24",
+};
+
+