@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/canvas/useCanvas.js

@@ -0,0 +1,126 @@
+import { useState, useEffect, useMemo } from 'react'
+import { getCanvasData } from '../../core/index.js'
+
+/**
+ * Fetch fresh canvas data from the server's .canvas.json file.
+ * Falls back to build-time data if the server is unavailable.
+ */
+async function fetchCanvasFromServer(name) {
+  // Canvas server API is only available during local dev
+  if (import.meta.env?.PROD) return null
+  try {
+    const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+    const res = await fetch(`${base}/_storyboard/canvas/read?name=${encodeURIComponent(name)}`)
+    const contentType = res.headers.get('content-type') || ''
+    if (res.ok && contentType.includes('application/json')) return res.json()
+  } catch { /* fall back to build-time data */ }
+  return null
+}
+
+function isAbsoluteUrl(value) {
+  return /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(value)
+}
+
+export function resolveCanvasModuleImport(modulePath, baseUrl = import.meta.env?.BASE_URL || '/') {
+  if (!modulePath || isAbsoluteUrl(modulePath)) return modulePath
+  if (!modulePath.startsWith('/')) return modulePath
+  const base = String(baseUrl || '/').replace(/\/$/, '')
+  return `${base}${modulePath}` || modulePath
+}
+
+/**
+ * Hook to load canvas data by name.
+ * Uses build-time data for static config (routes, JSX path), but fetches
+ * fresh widget data from the server to pick up persisted edits.
+ *
+ * @param {string} canvasId - Canonical canvas ID as indexed by the data plugin
+ * @returns {{ canvas: object|null, jsxExports: object|null, jsxError: boolean, loading: boolean }}
+ */
+export function useCanvas(canvasId) {
+  const buildTimeCanvas = useMemo(() => getCanvasData(canvasId), [canvasId])
+  const [canvas, setCanvas] = useState(buildTimeCanvas)
+  const [jsxExports, setJsxExports] = useState(null)
+  const [jsxError, setJsxError] = useState(false)
+  const [loading, setLoading] = useState(true)
+
+  // Fetch fresh data from server on mount
+  useEffect(() => {
+    if (!buildTimeCanvas) {
+      setCanvas(null)
+      setLoading(false)
+      return
+    }
+
+    setLoading(true)
+    fetchCanvasFromServer(canvasId).then((fresh) => {
+      if (fresh) {
+        // Merge: use server data for widgets/sources, keep build-time for _route/_jsxModule
+        setCanvas({ ...buildTimeCanvas, ...fresh })
+      } else {
+        setCanvas(buildTimeCanvas)
+      }
+      setLoading(false)
+    })
+  }, [canvasId, buildTimeCanvas])
+
+  const jsxModule = canvas?._jsxModule
+  const jsxImport = canvas?._jsxImport
+
+  useEffect(() => {
+    if (!jsxModule) {
+      setJsxExports(null)
+      setJsxError(false)
+      return
+    }
+
+    const loadPromise = jsxImport
+      ? jsxImport()
+      : import(/* @vite-ignore */ resolveCanvasModuleImport(jsxModule))
+
+    loadPromise
+      .then((mod) => {
+        const exports = {}
+        for (const [key, value] of Object.entries(mod)) {
+          if (key !== 'default' && typeof value === 'function') {
+            exports[key] = value
+          }
+        }
+        setJsxExports(exports)
+        setJsxError(false)
+      })
+      .catch((err) => {
+        console.error(`[storyboard] Failed to load canvas JSX module: ${jsxModule}`, err)
+        setJsxExports(null)
+        setJsxError(true)
+      })
+  }, [jsxModule, jsxImport])
+
+  // In dev, react to file mutations from the data plugin without reloading
+  // the current page. This keeps canvas editing state and route stable.
+  useEffect(() => {
+    if (!import.meta.hot || !buildTimeCanvas) return
+
+    const handleCanvasFileChanged = (data) => {
+      const eventId = data?.canvasId || data?.name
+      if (!data || eventId !== canvasId) return
+      // Use metadata from the HMR event directly if available (faster)
+      if (data.metadata?.widgets) {
+        setCanvas((prev) => ({ ...(prev || buildTimeCanvas), ...data.metadata }))
+        return
+      }
+      // Fallback: re-fetch from server
+      fetchCanvasFromServer(canvasId).then((fresh) => {
+        if (fresh) {
+          setCanvas((prev) => ({ ...(prev || buildTimeCanvas), ...fresh }))
+        }
+      })
+    }
+
+    import.meta.hot.on('storyboard:canvas-file-changed', handleCanvasFileChanged)
+    return () => {
+      import.meta.hot.off('storyboard:canvas-file-changed', handleCanvasFileChanged)
+    }
+  }, [canvasId, buildTimeCanvas])
+
+  return { canvas, jsxExports, jsxError, loading }
+}

package/src/internals/canvas/useCanvas.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest'
+import { resolveCanvasModuleImport } from './useCanvas.js'
+
+describe('resolveCanvasModuleImport', () => {
+  it('prefixes root-relative module paths with BASE_URL', () => {
+    expect(resolveCanvasModuleImport('/src/canvas/button-patterns.story.jsx', '/feature-branch/')).toBe(
+      '/feature-branch/src/canvas/button-patterns.story.jsx',
+    )
+  })
+
+  it('keeps root-relative paths unchanged when BASE_URL is root', () => {
+    expect(resolveCanvasModuleImport('/src/canvas/button-patterns.story.jsx', '/')).toBe(
+      '/src/canvas/button-patterns.story.jsx',
+    )
+  })
+
+  it('returns relative paths as-is', () => {
+    expect(resolveCanvasModuleImport('./local-module.js', '/feature-branch/')).toBe('./local-module.js')
+  })
+
+  it('returns absolute URLs as-is', () => {
+    expect(resolveCanvasModuleImport('https://cdn.example.com/module.js', '/feature-branch/')).toBe(
+      'https://cdn.example.com/module.js',
+    )
+  })
+})

package/src/internals/canvas/useMarqueeSelect.js

@@ -0,0 +1,213 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { connectorIntersectsRect } from './connectorGeometry.js'
+
+/**
+ * Returns the bounding-box list for all widgets on the canvas.
+ * Each entry: { id, x, y, width, height }
+ */
+function getWidgetBounds(widgets, componentEntries, fallbackSizes) {
+  const bounds = []
+  for (const w of (widgets ?? [])) {
+    const fb = fallbackSizes[w.type] || { width: 200, height: 150 }
+    bounds.push({
+      id: w.id,
+      x: w?.position?.x ?? 0,
+      y: w?.position?.y ?? 0,
+      width: w.props?.width ?? fb.width,
+      height: w.props?.height ?? fb.height,
+    })
+  }
+  for (const entry of componentEntries) {
+    const fb = fallbackSizes['component'] || { width: 200, height: 150 }
+    bounds.push({
+      id: `jsx-${entry.exportName}`,
+      x: entry.sourceData?.position?.x ?? 0,
+      y: entry.sourceData?.position?.y ?? 0,
+      width: entry.sourceData?.width ?? fb.width,
+      height: entry.sourceData?.height ?? fb.height,
+    })
+  }
+  return bounds
+}
+
+/** Test whether two axis-aligned rectangles overlap. */
+function rectsIntersect(a, b) {
+  return a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+}
+
+/**
+ * Hook that powers marquee (lasso) selection on the canvas.
+ *
+ * @param {Object} opts
+ * @param {React.RefObject} opts.scrollRef    — ref to the scroll container
+ * @param {React.RefObject} opts.zoomRef      — ref holding current zoom (number 25-200)
+ * @param {Function} opts.setSelectedWidgetIds — state setter for selected IDs (Set)
+ * @param {Array} opts.widgets                — current localWidgets array
+ * @param {Array} opts.connectors             — current localConnectors array
+ * @param {Array} opts.componentEntries       — current componentEntries array
+ * @param {Object} opts.fallbackSizes         — WIDGET_FALLBACK_SIZES map
+ * @param {boolean} opts.spaceHeld            — whether the space key is pressed (panning)
+ * @param {boolean} opts.isLocalDev           — only enable in local dev
+ *
+ * @returns {{ marqueeScreenRect: {x,y,w,h}|null, handleMarqueeMouseDown: Function }}
+ */
+export default function useMarqueeSelect({
+  scrollRef,
+  zoomRef,
+  setSelectedWidgetIds,
+  widgets,
+  connectors,
+  componentEntries,
+  fallbackSizes,
+  spaceHeld,
+  isLocalDev,
+}) {
+  const [marqueeScreenRect, setMarqueeScreenRect] = useState(null)
+  const marqueeState = useRef(null) // { startCanvasX, startCanvasY, startClientX, startClientY }
+
+  /** Convert a client (screen) point to canvas-space coords. */
+  const clientToCanvas = useCallback((clientX, clientY) => {
+    const el = scrollRef.current
+    if (!el) return { x: 0, y: 0 }
+    const rect = el.getBoundingClientRect()
+    const scale = (zoomRef.current ?? 100) / 100
+    return {
+      x: (el.scrollLeft + (clientX - rect.left)) / scale,
+      y: (el.scrollTop + (clientY - rect.top)) / scale,
+    }
+  }, [scrollRef, zoomRef])
+
+  // Ref to track active drag listeners for cleanup on unmount
+  const cleanupRef = useRef(null)
+
+  const handleMarqueeMouseDown = useCallback((e) => {
+    if (!isLocalDev) return
+    if (spaceHeld) return
+    // Only start on direct background click (not on a widget)
+    if (e.button !== 0) return
+    if (e.target.closest('[data-tc-x]')) return
+
+    const canvasStart = clientToCanvas(e.clientX, e.clientY)
+    marqueeState.current = {
+      startCanvasX: canvasStart.x,
+      startCanvasY: canvasStart.y,
+      startClientX: e.clientX,
+      startClientY: e.clientY,
+      shiftKey: e.shiftKey,
+      altKey: e.altKey,
+    }
+
+    // Minimum drag distance before showing the marquee (avoids flicker on clicks)
+    const MIN_DRAG = 4
+
+    function handleMove(ev) {
+      const ms = marqueeState.current
+      if (!ms) return
+
+      const dx = ev.clientX - ms.startClientX
+      const dy = ev.clientY - ms.startClientY
+      if (Math.abs(dx) < MIN_DRAG && Math.abs(dy) < MIN_DRAG) return
+
+      const el = scrollRef.current
+      if (!el) return
+      const containerRect = el.getBoundingClientRect()
+
+      // Content-space rectangle (accounts for scroll offset)
+      const sx = Math.min(ms.startClientX, ev.clientX) - containerRect.left + el.scrollLeft
+      const sy = Math.min(ms.startClientY, ev.clientY) - containerRect.top + el.scrollTop
+      const sw = Math.abs(dx)
+      const sh = Math.abs(dy)
+
+      setMarqueeScreenRect({ x: sx, y: sy, w: sw, h: sh })
+    }
+
+    function removeListeners() {
+      document.removeEventListener('mousemove', handleMove)
+      document.removeEventListener('mouseup', handleUp)
+      window.removeEventListener('blur', handleCancel)
+      cleanupRef.current = null
+    }
+
+    function handleCancel() {
+      removeListeners()
+      marqueeState.current = null
+      setMarqueeScreenRect(null)
+    }
+
+    function handleUp(ev) {
+      removeListeners()
+
+      const ms = marqueeState.current
+      marqueeState.current = null
+      setMarqueeScreenRect(null)
+
+      if (!ms) return
+
+      // If the user barely moved, treat as a deselect click (unless shift held)
+      const dx = ev.clientX - ms.startClientX
+      const dy = ev.clientY - ms.startClientY
+      if (Math.abs(dx) < MIN_DRAG && Math.abs(dy) < MIN_DRAG) {
+        if (!ms.shiftKey) setSelectedWidgetIds(new Set())
+        return
+      }
+
+      // Compute the selection rect in canvas space
+      const canvasEnd = clientToCanvas(ev.clientX, ev.clientY)
+      const selRect = {
+        x: Math.min(ms.startCanvasX, canvasEnd.x),
+        y: Math.min(ms.startCanvasY, canvasEnd.y),
+        width: Math.abs(canvasEnd.x - ms.startCanvasX),
+        height: Math.abs(canvasEnd.y - ms.startCanvasY),
+      }
+
+      // Find intersecting widgets
+      const allBounds = getWidgetBounds(widgets, componentEntries, fallbackSizes)
+      const selected = new Set()
+      for (const wb of allBounds) {
+        if (rectsIntersect(selRect, wb)) {
+          selected.add(wb.id)
+        }
+      }
+
+      // Option+marquee: also select widgets connected by intersected connectors
+      if (ms.altKey && connectors?.length) {
+        const widgetMap = new Map()
+        for (const w of (widgets ?? [])) widgetMap.set(w.id, w)
+        for (const conn of connectors) {
+          if (connectorIntersectsRect(conn, widgetMap, selRect)) {
+            if (conn.start?.widgetId) selected.add(conn.start.widgetId)
+            if (conn.end?.widgetId) selected.add(conn.end.widgetId)
+          }
+        }
+      }
+
+      // Shift+marquee merges with existing selection; plain marquee replaces it
+      if (ms.shiftKey) {
+        setSelectedWidgetIds((prev) => {
+          const merged = new Set(prev)
+          for (const id of selected) merged.add(id)
+          return merged
+        })
+      } else {
+        setSelectedWidgetIds(selected)
+      }
+    }
+
+    document.addEventListener('mousemove', handleMove)
+    document.addEventListener('mouseup', handleUp)
+    window.addEventListener('blur', handleCancel)
+    cleanupRef.current = removeListeners
+  }, [isLocalDev, spaceHeld, clientToCanvas, scrollRef, setSelectedWidgetIds, widgets, connectors, componentEntries, fallbackSizes])
+
+  // Clean up listeners if component unmounts mid-drag
+  useEffect(() => {
+    return () => { cleanupRef.current?.() }
+  }, [])
+
+  return { marqueeScreenRect, handleMarqueeMouseDown }
+}
+
+export { getWidgetBounds, rectsIntersect }

package/src/internals/canvas/useMarqueeSelect.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import { rectsIntersect, getWidgetBounds } from './useMarqueeSelect.js'
+
+describe('rectsIntersect', () => {
+  it('returns true for overlapping rectangles', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 50, y: 50, width: 100, height: 100 }
+    expect(rectsIntersect(a, b)).toBe(true)
+  })
+
+  it('returns false for non-overlapping rectangles', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 200, y: 200, width: 100, height: 100 }
+    expect(rectsIntersect(a, b)).toBe(false)
+  })
+
+  it('returns false for edge-touching rectangles (no overlap)', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 100, y: 0, width: 100, height: 100 }
+    expect(rectsIntersect(a, b)).toBe(false)
+  })
+
+  it('returns true when one rectangle contains the other', () => {
+    const a = { x: 0, y: 0, width: 200, height: 200 }
+    const b = { x: 50, y: 50, width: 50, height: 50 }
+    expect(rectsIntersect(a, b)).toBe(true)
+  })
+
+  it('returns true for partial horizontal overlap', () => {
+    const a = { x: 0, y: 0, width: 100, height: 100 }
+    const b = { x: 50, y: 0, width: 100, height: 50 }
+    expect(rectsIntersect(a, b)).toBe(true)
+  })
+})
+
+describe('getWidgetBounds', () => {
+  const fallbackSizes = {
+    'sticky-note': { width: 270, height: 170 },
+    'component': { width: 200, height: 150 },
+  }
+
+  it('returns bounds for JSON widgets', () => {
+    const widgets = [
+      { id: 'w1', type: 'sticky-note', position: { x: 10, y: 20 }, props: { width: 300, height: 200 } },
+      { id: 'w2', type: 'sticky-note', position: { x: 100, y: 200 }, props: {} },
+    ]
+    const result = getWidgetBounds(widgets, [], fallbackSizes)
+    expect(result).toEqual([
+      { id: 'w1', x: 10, y: 20, width: 300, height: 200 },
+      { id: 'w2', x: 100, y: 200, width: 270, height: 170 },
+    ])
+  })
+
+  it('returns bounds for component entries', () => {
+    const entries = [
+      { exportName: 'MyComp', sourceData: { position: { x: 5, y: 10 }, width: 400, height: 300 } },
+    ]
+    const result = getWidgetBounds([], entries, fallbackSizes)
+    expect(result).toEqual([
+      { id: 'jsx-MyComp', x: 5, y: 10, width: 400, height: 300 },
+    ])
+  })
+
+  it('handles null/missing widget data gracefully', () => {
+    const widgets = [
+      { id: 'w1', type: 'unknown' },
+    ]
+    const result = getWidgetBounds(widgets, [], fallbackSizes)
+    expect(result).toEqual([
+      { id: 'w1', x: 0, y: 0, width: 200, height: 150 },
+    ])
+  })
+
+  it('handles null widgets array', () => {
+    const result = getWidgetBounds(null, [], fallbackSizes)
+    expect(result).toEqual([])
+  })
+})

package/src/internals/canvas/useUndoRedo.js

@@ -0,0 +1,86 @@
+import { useRef, useState, useCallback } from 'react'
+
+const MAX_HISTORY = 100
+const COALESCE_MS = 2000
+
+/**
+ * Snapshot-based undo/redo history for canvas widgets.
+ *
+ * Tracks past/future stacks of widget array clones. The present state
+ * is always the live `localWidgets` — this hook only manages history.
+ *
+ * Edit coalescing: continuous edits to the same widget within COALESCE_MS
+ * are merged into one undo step (like Figma).
+ */
+export default function useUndoRedo() {
+  const pastRef = useRef([])
+  const futureRef = useRef([])
+  const lastActionRef = useRef({ type: null, widgetId: null, time: 0 })
+  // State counter drives canUndo/canRedo re-renders without cloning the stacks
+  const [counts, setCounts] = useState({ past: 0, future: 0 })
+
+  const snapshot = useCallback((currentWidgets, actionType, widgetId) => {
+    const widgets = currentWidgets ?? []
+
+    // Edit coalescing — skip snapshot if same edit target within timeout
+    if (actionType === 'edit' && widgetId) {
+      const last = lastActionRef.current
+      const now = Date.now()
+      if (
+        last.type === 'edit' &&
+        last.widgetId === widgetId &&
+        now - last.time < COALESCE_MS
+      ) {
+        lastActionRef.current = { type: 'edit', widgetId, time: now }
+        return
+      }
+    }
+
+    pastRef.current.push(structuredClone(widgets))
+    if (pastRef.current.length > MAX_HISTORY) pastRef.current.shift()
+    futureRef.current = []
+    lastActionRef.current = {
+      type: actionType,
+      widgetId: widgetId || null,
+      time: Date.now(),
+    }
+    setCounts({ past: pastRef.current.length, future: 0 })
+  }, [])
+
+  const undo = useCallback((currentWidgets) => {
+    if (pastRef.current.length === 0) return null
+    futureRef.current.push(structuredClone(currentWidgets))
+    const previous = pastRef.current.pop()
+    lastActionRef.current = { type: 'undo', widgetId: null, time: Date.now() }
+    setCounts({ past: pastRef.current.length, future: futureRef.current.length })
+    return previous
+  }, [])
+
+  const redo = useCallback((currentWidgets) => {
+    if (futureRef.current.length === 0) return null
+    pastRef.current.push(structuredClone(currentWidgets))
+    const next = futureRef.current.pop()
+    lastActionRef.current = { type: 'redo', widgetId: null, time: Date.now() }
+    setCounts({ past: pastRef.current.length, future: futureRef.current.length })
+    return next
+  }, [])
+
+  const reset = useCallback(() => {
+    pastRef.current = []
+    futureRef.current = []
+    lastActionRef.current = { type: null, widgetId: null, time: 0 }
+    setCounts((prev) => {
+      if (prev.past === 0 && prev.future === 0) return prev
+      return { past: 0, future: 0 }
+    })
+  }, [])
+
+  return {
+    snapshot,
+    undo,
+    redo,
+    reset,
+    canUndo: counts.past > 0,
+    canRedo: counts.future > 0,
+  }
+}