@morphika/webframe 0.1.0

package/lib/builder/masonry.ts

@@ -0,0 +1,166 @@
+// ============================================
+// Masonry Engine — Pure JS, zero React deps
+// ============================================
+// Computes absolute card positions for the Project Grid v2.
+// Used by both the builder preview and the public renderer
+// to guarantee pixel-perfect parity.
+
+// ─── Interfaces ───
+
+export interface MasonryItem {
+  key: string;
+  aspectRatio: number; // width / height, e.g. 16/9 ≈ 1.778, 1/1 = 1, 9/16 ≈ 0.5625
+}
+
+export interface MasonryConfig {
+  columns: number;        // 1–6
+  gapH: number;           // horizontal gap in px
+  gapV: number;           // vertical gap in px
+  containerWidth: number; // px (measured at runtime)
+}
+
+export interface MasonryResult {
+  key: string;
+  x: number;       // px from left
+  y: number;       // px from top
+  width: number;   // px
+  height: number;  // px
+  column: number;  // 0-based column index
+}
+
+export interface MasonryOutput {
+  items: MasonryResult[];
+  totalHeight: number; // px — height of tallest column (for container sizing)
+}
+
+export interface RatioResolverConfig {
+  gridRatios: string[];  // e.g. ["16/9", "1/1"]
+  seed?: number;         // optional deterministic seed
+}
+
+// ─── Helpers ───
+
+/**
+ * Parse a ratio string like "16/9" into a numeric value (width / height).
+ * Returns 1 if the string is malformed.
+ */
+export function parseRatio(ratio: string): number {
+  const parts = ratio.split("/");
+  if (parts.length !== 2) return 1;
+  const w = Number(parts[0]);
+  const h = Number(parts[1]);
+  if (!w || !h || !isFinite(w) || !isFinite(h) || h === 0) return 1;
+  return w / h;
+}
+
+/**
+ * Returns the index of the shortest column. Tie-break: leftmost (lowest index).
+ */
+export function getShortestColumn(columnHeights: number[]): number {
+  if (columnHeights.length === 0) return 0;
+  let minIdx = 0;
+  let minVal = columnHeights[0];
+  for (let i = 1; i < columnHeights.length; i++) {
+    if (columnHeights[i] < minVal) {
+      minVal = columnHeights[i];
+      minIdx = i;
+    }
+  }
+  return minIdx;
+}
+
+/**
+ * Resolve the aspect ratio for a single item.
+ *
+ * Priority: override > grid single ratio > deterministic random pick.
+ *
+ * The deterministic pick uses a simple hash:
+ *   gridRatios[(index * 7 + (seed || 0)) % gridRatios.length]
+ * The * 7 prime multiplier avoids adjacent repeats.
+ */
+export function resolveItemRatio(
+  index: number,
+  override: string | null | undefined,
+  config: RatioResolverConfig,
+): number {
+  // Per-card override wins
+  if (override) {
+    return parseRatio(override);
+  }
+
+  const { gridRatios, seed } = config;
+
+  // Fallback if empty array
+  if (!gridRatios || gridRatios.length === 0) return 1;
+
+  // Single ratio — no randomness needed
+  if (gridRatios.length === 1) {
+    return parseRatio(gridRatios[0]);
+  }
+
+  // Deterministic pseudo-random pick
+  const pick = Math.abs((index * 7 + (seed || 0)) % gridRatios.length);
+  return parseRatio(gridRatios[pick]);
+}
+
+// ─── Core Algorithm ───
+
+/**
+ * Shortest-column masonry layout.
+ *
+ * 1. colWidth = (containerWidth - gapH * (columns - 1)) / columns
+ * 2. For each item → place in shortest column → compute x, y, height
+ * 3. totalHeight = max(columnHeights) - trailing gapV
+ *
+ * Edge cases:
+ * - containerWidth <= 0 → returns empty output
+ * - columns <= 0 → clamped to 1
+ * - empty items → returns { items: [], totalHeight: 0 }
+ */
+export function computeMasonry(
+  items: MasonryItem[],
+  config: MasonryConfig,
+): MasonryOutput {
+  const { gapH, gapV, containerWidth } = config;
+  const columns = Math.max(1, Math.round(config.columns));
+
+  // Graceful handling of invalid container
+  if (containerWidth <= 0 || items.length === 0) {
+    return { items: [], totalHeight: 0 };
+  }
+
+  const colWidth =
+    (containerWidth - gapH * (columns - 1)) / columns;
+
+  // If column width is non-positive (e.g. gaps exceed container), bail
+  if (colWidth <= 0) {
+    return { items: [], totalHeight: 0 };
+  }
+
+  const columnHeights = new Array<number>(columns).fill(0);
+  const results: MasonryResult[] = [];
+
+  for (const item of items) {
+    const col = getShortestColumn(columnHeights);
+    const x = col * (colWidth + gapH);
+    const y = columnHeights[col];
+    const height = colWidth / (item.aspectRatio || 1); // guard div-by-zero
+
+    results.push({
+      key: item.key,
+      x,
+      y,
+      width: colWidth,
+      height,
+      column: col,
+    });
+
+    columnHeights[col] += height + gapV;
+  }
+
+  // totalHeight = tallest column minus trailing gap
+  const maxHeight = Math.max(...columnHeights);
+  const totalHeight = Math.max(0, maxHeight - gapV);
+
+  return { items: results, totalHeight };
+}

package/lib/builder/responsive.ts

@@ -0,0 +1,156 @@
+/**
+ * Responsive block resolution.
+ *
+ * The responsive system works with a simple override model:
+ *
+ *   1. Each block stores its BASE properties (= desktop defaults).
+ *   2. Each block has an optional `responsive` field:
+ *      { tablet?: Partial<Props>, phone?: Partial<Props> }
+ *   3. At render time, `resolveBlock(block, viewport)` returns a merged
+ *      copy: { ...base, ...overrides[viewport] }.
+ *
+ * Desktop always returns the block as-is (no merge needed).
+ * Tablet/phone only store what differs from desktop — everything else
+ * inherits automatically.
+ *
+ */
+
+import type { ContentBlock } from "../../lib/sanity/types";
+import type { DeviceViewport } from "./types";
+
+/**
+ * Type-safe accessor for the `responsive` field on any ContentBlock.
+ * All block types in the union have `responsive?: ResponsiveOverrides<T>`,
+ * but TypeScript can't see the common property without narrowing.
+ */
+type ResponsiveData = Record<string, Record<string, unknown>> | undefined;
+
+function getResponsive(block: ContentBlock): ResponsiveData {
+  // All ContentBlock variants have a `responsive` field — safe to access via index
+  return (block as { responsive?: ResponsiveData }).responsive;
+}
+
+// ============================================
+// Block resolution
+// ============================================
+
+/**
+ * Resolve a block for a given viewport by merging responsive overrides.
+ *
+ * - `desktop` → returns the block unchanged.
+ * - `tablet` / `phone` → shallow-merges the viewport overrides on top of
+ *   the base block properties. Nested objects (like `style` on TextBlock)
+ *   are deep-merged one level.
+ *
+ * The returned block always keeps the original `_type`, `_key`, and
+ * `responsive` fields intact.
+ */
+export function resolveBlock<T extends ContentBlock>(
+  block: T,
+  viewport: DeviceViewport
+): T {
+  if (viewport === "desktop") return block;
+
+  const responsive = getResponsive(block);
+  if (!responsive) return block;
+
+  const overrides = responsive[viewport];
+  if (!overrides || Object.keys(overrides).length === 0) return block;
+
+  // Shallow merge with special handling for nested `style` object
+  const merged = { ...block } as T;
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key === "responsive" || key === "_type" || key === "_key") continue;
+
+    // Deep-merge one-level nested objects (e.g. TextBlock.style, CoverBlock.cta_button)
+    const blockRecord = block as unknown as Record<string, unknown>;
+    const mergedRecord = merged as unknown as Record<string, unknown>;
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      key in block &&
+      typeof blockRecord[key] === "object" &&
+      blockRecord[key] !== null
+    ) {
+      mergedRecord[key] = {
+        ...(blockRecord[key] as Record<string, unknown>),
+        ...(value as Record<string, unknown>),
+      };
+    } else {
+      mergedRecord[key] = value;
+    }
+  }
+
+  return merged;
+}
+
+// ============================================
+// Helpers for the settings panel
+// ============================================
+
+/**
+ * Check if a block property has a responsive override for the given viewport.
+ * Used by the editor to show "inherited" vs "overridden" state.
+ */
+export function hasOverride(
+  block: ContentBlock,
+  viewport: DeviceViewport,
+  property: string
+): boolean {
+  if (viewport === "desktop") return true; // desktop is always "the value"
+  const responsive = getResponsive(block);
+  if (!responsive?.[viewport]) return false;
+  return property in responsive[viewport];
+}
+
+/**
+ * Get the effective value of a block property for a viewport.
+ * If the viewport has an override, returns it. Otherwise returns the base value.
+ */
+export function getEffectiveValue<T>(
+  block: ContentBlock,
+  viewport: DeviceViewport,
+  property: string,
+  baseValue: T
+): T {
+  if (viewport === "desktop") return baseValue;
+  const responsive = getResponsive(block);
+  if (!responsive?.[viewport] || !(property in responsive[viewport])) {
+    return baseValue;
+  }
+  return responsive[viewport][property] as T;
+}
+
+/**
+ * Set or clear a responsive override for a specific property.
+ * Returns the updated `responsive` object to pass to `updateBlock()`.
+ *
+ * If `value` matches the base value, the override is removed (inherit).
+ * If `value` is `undefined`, the override is explicitly removed.
+ */
+export function setResponsiveOverride(
+  block: ContentBlock,
+  viewport: DeviceViewport,
+  property: string,
+  value: unknown
+): { responsive: Record<string, Record<string, unknown>> } {
+  const existing = getResponsive(block) || {};
+  const viewportOverrides = { ...(existing[viewport] || {}) };
+
+  if (value === undefined) {
+    delete viewportOverrides[property];
+  } else {
+    viewportOverrides[property] = value;
+  }
+
+  // Clean up empty viewport objects
+  const responsive = { ...existing } as Record<string, Record<string, unknown>>;
+  if (Object.keys(viewportOverrides).length === 0) {
+    delete responsive[viewport];
+  } else {
+    responsive[viewport] = viewportOverrides;
+  }
+
+  return { responsive };
+}