@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/canvas/componentSetIsolate.jsx

@@ -0,0 +1,257 @@
+/**
+ * Canvas Component-Set Isolate — lightweight iframe entry point.
+ *
+ * Renders ALL named exports from a .story.jsx module in a grid layout,
+ * bypassing the full SPA bootstrap (router, StoryboardProvider, data index).
+ *
+ * This is the component-set equivalent of componentIsolate.jsx, which renders
+ * a single export. By avoiding the full app bootstrap, component-set widgets
+ * load significantly faster — especially important since each widget is an
+ * iframe that would otherwise need to initialize the entire app.
+ *
+ * Query params:
+ *   module   — absolute or base-relative path to the .story.jsx file
+ *   layout   — "horizontal" (default) | "vertical"
+ *   selected — export name of the currently selected cell
+ *   theme    — canvas theme (light / dark / dark_dimmed)
+ */
+import { createElement, Component as ReactComponent, useState, useEffect, useLayoutEffect, useCallback, useRef } from 'react'
+import { createRoot } from 'react-dom/client'
+import { ThemeProvider, BaseStyles } from '@primer/react'
+
+// ── Primer Primitives CSS (required for CSS variables) ──────────────
+import '@primer/primitives/dist/css/base/size/size.css'
+import '@primer/primitives/dist/css/base/typography/typography.css'
+import '@primer/primitives/dist/css/base/motion/motion.css'
+import '@primer/primitives/dist/css/functional/size/border.css'
+import '@primer/primitives/dist/css/functional/size/breakpoints.css'
+import '@primer/primitives/dist/css/functional/size/size-coarse.css'
+import '@primer/primitives/dist/css/functional/size/size-fine.css'
+import '@primer/primitives/dist/css/functional/size/size.css'
+import '@primer/primitives/dist/css/functional/size/viewport.css'
+import '@primer/primitives/dist/css/functional/typography/typography.css'
+import '@primer/primitives/dist/css/functional/themes/light.css'
+import '@primer/primitives/dist/css/functional/themes/light-colorblind.css'
+import '@primer/primitives/dist/css/functional/themes/dark.css'
+import '@primer/primitives/dist/css/functional/themes/dark-colorblind.css'
+import '@primer/primitives/dist/css/functional/themes/dark-high-contrast.css'
+import '@primer/primitives/dist/css/functional/themes/dark-dimmed.css'
+
+import styles from '../story/ComponentSetPage.module.css'
+
+// ── Error Boundary ──────────────────────────────────────────────────
+class IsolateErrorBoundary extends ReactComponent {
+  constructor(props) {
+    super(props)
+    this.state = { error: null }
+  }
+  static getDerivedStateFromError(error) {
+    return { error }
+  }
+  render() {
+    if (this.state.error) {
+      return createElement('div', { style: errorStyle },
+        createElement('strong', null, this.props.name || 'Component'),
+        createElement('br'),
+        String(this.state.error.message || this.state.error),
+      )
+    }
+    return this.props.children
+  }
+}
+
+const errorStyle = {
+  padding: '16px',
+  color: '#cf222e',
+  fontFamily: 'system-ui, -apple-system, sans-serif',
+  fontSize: '13px',
+  lineHeight: 1.5,
+  whiteSpace: 'pre-wrap',
+  wordBreak: 'break-word',
+}
+
+// ── Resolve module path ─────────────────────────────────────────────
+function resolveModulePath(raw) {
+  if (!raw) return raw
+  if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(raw)) return raw
+  if (!raw.startsWith('/')) return raw
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+  if (!base) return raw
+  if (raw.startsWith(base)) return raw
+  return `${base}${raw}`
+}
+
+// ── Component-Set Grid (mirrors ComponentSetPage UI) ────────────────
+function ComponentSetGrid({ exports, layout, initialSelected }) {
+  const [selected, setSelected] = useState(initialSelected)
+  const gridRef = useRef(null)
+
+  const handleSelect = useCallback((exportName) => {
+    const next = exportName === selected ? '' : exportName
+    setSelected(next)
+
+    // Update URL without navigation
+    const params = new URLSearchParams(window.location.search)
+    if (next) params.set('selected', next)
+    else params.delete('selected')
+    window.history.replaceState(null, '', `${window.location.pathname}?${params}`)
+
+    // Notify parent widget
+    if (window.parent !== window) {
+      window.parent.postMessage({
+        type: 'storyboard:component-set:select',
+        exportName: next || null,
+      }, '*')
+    }
+  }, [selected])
+
+  // Measure cells and post grid size to parent
+  useLayoutEffect(() => {
+    const grid = gridRef.current
+    if (!grid || !exports) return
+
+    const cells = grid.querySelectorAll('[data-cell-content]')
+    if (cells.length === 0) return
+
+    function measure() {
+      let maxW = 0
+      let maxH = 0
+      for (const el of cells) {
+        maxW = Math.max(maxW, el.scrollWidth)
+        maxH = Math.max(maxH, el.scrollHeight)
+      }
+      grid.style.setProperty('--cell-snap-w', `${maxW}px`)
+      grid.style.setProperty('--cell-snap-h', `${maxH}px`)
+
+      if (window.parent !== window) {
+        requestAnimationFrame(() => {
+          window.parent.postMessage({
+            type: 'storyboard:component-set:resize',
+            width: grid.scrollWidth,
+            height: grid.scrollHeight,
+          }, '*')
+        })
+      }
+    }
+
+    measure()
+    document.fonts.ready.then(() => requestAnimationFrame(measure))
+
+    const ro = new ResizeObserver(measure)
+    for (const el of cells) ro.observe(el)
+    return () => ro.disconnect()
+  }, [exports, layout])
+
+  // Signal snapshot-ready
+  useEffect(() => {
+    document.fonts.ready.then(() => {
+      requestAnimationFrame(() => requestAnimationFrame(() => {
+        window.__sbSnapshotReady?.()
+      }))
+    })
+  }, [exports])
+
+  const exportNames = Object.keys(exports)
+
+  // eslint-disable-next-line react-hooks/refs -- ref assigned to DOM element, not read during render
+  return createElement('div', {
+    ref: gridRef,
+    className: styles.grid,
+    'data-layout': layout,
+  },
+    exportNames.map((exportName) => {
+      const Component = exports[exportName]
+      const isSelected = exportName === selected
+      return createElement('div', {
+        key: exportName,
+        className: styles.cell,
+        'data-selected': isSelected || undefined,
+      },
+        createElement('button', {
+          className: styles.cellLabel,
+          onClick: () => handleSelect(exportName),
+          'data-selected': isSelected || undefined,
+          'aria-pressed': isSelected,
+        },
+          createElement('span', { className: styles.cellRadio, 'data-selected': isSelected || undefined }),
+          createElement('span', { className: styles.cellName }, exportName),
+        ),
+        createElement('div', { className: styles.cellContent, 'data-cell-content': '' },
+          createElement(IsolateErrorBoundary, { name: exportName },
+            createElement(Component),
+          ),
+        ),
+      )
+    }),
+  )
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+const params = new URLSearchParams(window.location.search)
+const modulePath = params.get('module')
+const layout = params.get('layout') || 'horizontal'
+const selected = params.get('selected') || ''
+const theme = params.get('theme') || 'light'
+
+const colorMode = theme.startsWith('dark') ? 'night' : 'day'
+
+document.documentElement.setAttribute('data-color-mode', theme.startsWith('dark') ? 'dark' : 'light')
+document.documentElement.setAttribute('data-dark-theme', theme.startsWith('dark') ? theme : '')
+document.documentElement.setAttribute('data-light-theme', theme.startsWith('dark') ? '' : theme || 'light')
+
+// Suppress HMR full-reloads — this iframe is embedded inside a canvas page
+// that manages its own reload lifecycle. Without this guard, every file change
+// causes the iframe to flash/reload.
+if (import.meta.hot) {
+  const msg = { active: true }
+  import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+  setInterval(() => import.meta.hot.send('storyboard:canvas-hmr-guard', msg), 3000)
+}
+
+const root = createRoot(document.getElementById('root'))
+
+async function mount() {
+  if (!modulePath) {
+    root.render(createElement('div', { style: errorStyle }, 'Missing module param'))
+    return
+  }
+
+  if (!modulePath.match(/\.story\.(jsx|tsx)$/)) {
+    root.render(createElement('div', { style: errorStyle }, 'Invalid module path — only .story.jsx/.tsx files are allowed'))
+    return
+  }
+
+  try {
+    const resolved = resolveModulePath(modulePath)
+    const mod = await import(/* @vite-ignore */ resolved)
+
+    const namedExports = {}
+    for (const [key, value] of Object.entries(mod)) {
+      if (key !== 'default' && typeof value === 'function') {
+        namedExports[key] = value
+      }
+    }
+
+    if (Object.keys(namedExports).length === 0) {
+      throw new Error('No named exports found in story module')
+    }
+
+    root.render(
+      createElement(ThemeProvider, { colorMode },
+        createElement(BaseStyles, null,
+          createElement(ComponentSetGrid, { exports: namedExports, layout, initialSelected: selected }),
+        ),
+      ),
+    )
+  } catch (err) {
+    root.render(
+      createElement('div', { style: errorStyle },
+        createElement('strong', null, 'Component Set'),
+        createElement('br'),
+        String(err.message || err),
+      ),
+    )
+  }
+}
+
+mount()

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

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest'
+
+// computeCanvasBounds is not exported, so we replicate it here for unit testing.
+// This keeps the test decoupled from CanvasPage internals while validating the algorithm.
+
+const WIDGET_FALLBACK_SIZES = {
+  'sticky-note':  { width: 180, height: 60 },
+  'markdown':     { width: 360, height: 200 },
+  'prototype':    { width: 800, height: 600 },
+  'link-preview': { width: 320, height: 120 },
+  'figma-embed':  { width: 800, height: 450 },
+  'component':    { width: 200, height: 150 },
+  'image':        { width: 400, height: 300 },
+}
+
+function computeCanvasBounds(widgets, sources, jsxExports) {
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  let hasItems = false
+
+  for (const w of (widgets ?? [])) {
+    const x = w?.position?.x ?? 0
+    const y = w?.position?.y ?? 0
+    const fallback = WIDGET_FALLBACK_SIZES[w.type] || { width: 200, height: 150 }
+    const width = w.props?.width ?? fallback.width
+    const height = w.props?.height ?? fallback.height
+    minX = Math.min(minX, x)
+    minY = Math.min(minY, y)
+    maxX = Math.max(maxX, x + width)
+    maxY = Math.max(maxY, y + height)
+    hasItems = true
+  }
+
+  const sourceMap = Object.fromEntries(
+    (sources || []).filter((s) => s?.export).map((s) => [s.export, s])
+  )
+  if (jsxExports) {
+    for (const exportName of Object.keys(jsxExports)) {
+      const sourceData = sourceMap[exportName] || {}
+      const x = sourceData.position?.x ?? 0
+      const y = sourceData.position?.y ?? 0
+      const fallback = WIDGET_FALLBACK_SIZES['component']
+      const width = sourceData.width ?? fallback.width
+      const height = sourceData.height ?? fallback.height
+      minX = Math.min(minX, x)
+      minY = Math.min(minY, y)
+      maxX = Math.max(maxX, x + width)
+      maxY = Math.max(maxY, y + height)
+      hasItems = true
+    }
+  }
+
+  return hasItems ? { minX, minY, maxX, maxY } : null
+}
+
+describe('computeCanvasBounds', () => {
+  it('returns null for empty canvas', () => {
+    expect(computeCanvasBounds([], [], null)).toBeNull()
+    expect(computeCanvasBounds(null, null, null)).toBeNull()
+  })
+
+  it('computes bounds for a single widget using props dimensions', () => {
+    const widgets = [
+      { type: 'sticky-note', position: { x: 100, y: 200 }, props: { width: 300, height: 100 } },
+    ]
+    const bounds = computeCanvasBounds(widgets, [], null)
+    expect(bounds).toEqual({ minX: 100, minY: 200, maxX: 400, maxY: 300 })
+  })
+
+  it('uses fallback dimensions when props are missing', () => {
+    const widgets = [
+      { type: 'sticky-note', position: { x: 50, y: 50 }, props: {} },
+    ]
+    const bounds = computeCanvasBounds(widgets, [], null)
+    expect(bounds).toEqual({ minX: 50, minY: 50, maxX: 230, maxY: 110 }) // 50+180, 50+60
+  })
+
+  it('computes bounds spanning multiple widgets', () => {
+    const widgets = [
+      { type: 'sticky-note', position: { x: 0, y: 0 }, props: { width: 180, height: 60 } },
+      { type: 'markdown', position: { x: 500, y: 300 }, props: { width: 360, height: 200 } },
+    ]
+    const bounds = computeCanvasBounds(widgets, [], null)
+    expect(bounds).toEqual({ minX: 0, minY: 0, maxX: 860, maxY: 500 })
+  })
+
+  it('includes JSX sources in bounds', () => {
+    const sources = [{ export: 'Hero', position: { x: -100, y: -50 }, width: 400, height: 300 }]
+    const jsxExports = { Hero: () => null }
+    const bounds = computeCanvasBounds([], sources, jsxExports)
+    expect(bounds).toEqual({ minX: -100, minY: -50, maxX: 300, maxY: 250 })
+  })
+
+  it('combines widgets and JSX sources', () => {
+    const widgets = [
+      { type: 'sticky-note', position: { x: 200, y: 200 }, props: { width: 180, height: 60 } },
+    ]
+    const sources = [{ export: 'Nav', position: { x: 0, y: 0 }, width: 100, height: 100 }]
+    const jsxExports = { Nav: () => null }
+    const bounds = computeCanvasBounds(widgets, sources, jsxExports)
+    expect(bounds).toEqual({ minX: 0, minY: 0, maxX: 380, maxY: 260 })
+  })
+
+  it('handles widgets with missing position (defaults to 0,0)', () => {
+    const widgets = [
+      { type: 'sticky-note', props: { width: 180, height: 60 } },
+    ]
+    const bounds = computeCanvasBounds(widgets, [], null)
+    expect(bounds).toEqual({ minX: 0, minY: 0, maxX: 180, maxY: 60 })
+  })
+
+  it('uses component fallback for JSX sources without explicit size', () => {
+    const sources = [{ export: 'Card', position: { x: 10, y: 10 } }]
+    const jsxExports = { Card: () => null }
+    const bounds = computeCanvasBounds([], sources, jsxExports)
+    // component fallback: 200x150
+    expect(bounds).toEqual({ minX: 10, minY: 10, maxX: 210, maxY: 160 })
+  })
+})

package/src/internals/canvas/connectorGeometry.js

@@ -0,0 +1,132 @@
+import { getConnectorDefaults } from './widgets/widgetConfig.js'
+
+const connectorConfig = getConnectorDefaults()
+const CONTROL_OFFSET = connectorConfig.controlOffset
+
+/**
+ * Compute the anchor point on a widget's edge.
+ * Reads actual DOM dimensions for accuracy (widgets like markdown auto-size).
+ * Falls back to props/bounds/defaults if DOM element isn't found.
+ */
+export function getAnchorPoint(widget, anchor) {
+  const x = widget.position?.x ?? 0
+  const y = widget.position?.y ?? 0
+
+  let w, h
+  const el = typeof document !== 'undefined' ? document.getElementById(widget.id) : null
+  if (el) {
+    const firstChild = el.querySelector('[data-widget-id]') || el.firstElementChild
+    if (firstChild) {
+      w = firstChild.offsetWidth
+      h = firstChild.offsetHeight
+    }
+  }
+  if (!w) w = widget.props?.width ?? widget.bounds?.width ?? 270
+  if (!h) h = widget.props?.height ?? widget.bounds?.height ?? 170
+
+  switch (anchor) {
+    case 'top':    return { x: x + w / 2, y }
+    case 'bottom': return { x: x + w / 2, y: y + h }
+    case 'left':   return { x, y: y + h / 2 }
+    case 'right':  return { x: x + w, y: y + h / 2 }
+    default:       return { x: x + w / 2, y: y + h / 2 }
+  }
+}
+
+/**
+ * Compute the control point offset direction for an anchor.
+ */
+export function getControlOffset(anchor) {
+  switch (anchor) {
+    case 'top':    return { dx: 0, dy: -CONTROL_OFFSET }
+    case 'bottom': return { dx: 0, dy: CONTROL_OFFSET }
+    case 'left':   return { dx: -CONTROL_OFFSET, dy: 0 }
+    case 'right':  return { dx: CONTROL_OFFSET, dy: 0 }
+    default:       return { dx: 0, dy: 0 }
+  }
+}
+
+/**
+ * Build a cubic Bézier path string between two anchor points.
+ * When `freeEnd` is true, the end control point is computed from
+ * the direction vector (end→start) so the curve never bends in
+ * front of the cursor during drag.
+ */
+export function buildPath(startPt, startAnchor, endPt, endAnchor, freeEnd = false) {
+  const c1 = getControlOffset(startAnchor)
+  let c2
+  if (freeEnd) {
+    const dx = startPt.x - endPt.x
+    const dy = startPt.y - endPt.y
+    const dist = Math.hypot(dx, dy) || 1
+    const scale = Math.min(CONTROL_OFFSET, dist * 0.4)
+    c2 = { dx: (dx / dist) * scale, dy: (dy / dist) * scale }
+  } else {
+    c2 = getControlOffset(endAnchor)
+  }
+  return `M ${startPt.x} ${startPt.y} C ${startPt.x + c1.dx} ${startPt.y + c1.dy}, ${endPt.x + c2.dx} ${endPt.y + c2.dy}, ${endPt.x} ${endPt.y}`
+}
+
+/**
+ * Evaluate a cubic Bézier curve at parameter t.
+ * B(t) = (1-t)³·P0 + 3(1-t)²t·P1 + 3(1-t)t²·P2 + t³·P3
+ */
+function evalCubicBezier(p0, p1, p2, p3, t) {
+  const mt = 1 - t
+  const mt2 = mt * mt
+  const mt3 = mt2 * mt
+  const t2 = t * t
+  const t3 = t2 * t
+  return {
+    x: mt3 * p0.x + 3 * mt2 * t * p1.x + 3 * mt * t2 * p2.x + t3 * p3.x,
+    y: mt3 * p0.y + 3 * mt2 * t * p1.y + 3 * mt * t2 * p2.y + t3 * p3.y,
+  }
+}
+
+/**
+ * Resolve a connector's Bézier control points from widget positions.
+ * Returns { p0, cp1, cp2, p3 } or null if either widget is missing.
+ */
+export function getConnectorControlPoints(connector, widgetMap) {
+  const startWidget = widgetMap.get(connector.start?.widgetId)
+  const endWidget = widgetMap.get(connector.end?.widgetId)
+  if (!startWidget || !endWidget) return null
+
+  const p0 = getAnchorPoint(startWidget, connector.start.anchor)
+  const p3 = getAnchorPoint(endWidget, connector.end.anchor)
+  const c1 = getControlOffset(connector.start.anchor)
+  const c2 = getControlOffset(connector.end.anchor)
+
+  return {
+    p0,
+    cp1: { x: p0.x + c1.dx, y: p0.y + c1.dy },
+    cp2: { x: p3.x + c2.dx, y: p3.y + c2.dy },
+    p3,
+  }
+}
+
+/**
+ * Test whether any point along a connector's Bézier path falls inside a rect.
+ * @param {Object} connector — { start: { widgetId, anchor }, end: { widgetId, anchor } }
+ * @param {Map} widgetMap — Map<widgetId, widget>
+ * @param {{ x, y, width, height }} rect — axis-aligned selection rectangle
+ * @param {number} numSamples — number of evenly-spaced points to test (default 24)
+ * @returns {boolean}
+ */
+export function connectorIntersectsRect(connector, widgetMap, rect, numSamples = 24) {
+  const pts = getConnectorControlPoints(connector, widgetMap)
+  if (!pts) return false
+
+  const { p0, cp1, cp2, p3 } = pts
+  const rRight = rect.x + rect.width
+  const rBottom = rect.y + rect.height
+
+  for (let i = 0; i <= numSamples; i++) {
+    const t = i / numSamples
+    const pt = evalCubicBezier(p0, cp1, cp2, p3, t)
+    if (pt.x >= rect.x && pt.x <= rRight && pt.y >= rect.y && pt.y <= rBottom) {
+      return true
+    }
+  }
+  return false
+}

package/src/internals/canvas/hotPoolDevLogs.js

@@ -0,0 +1,25 @@
+/**
+ * Hot Pool browser devlogs — listens for server HMR events and
+ * logs them to the browser console when DevTools "Dev logs" is on.
+ */
+
+import { getFlag } from '../../core/index.js'
+
+let registered = false
+
+function isDevLogsEnabled() {
+  return getFlag('dev-logs')
+}
+
+export function registerHotPoolDevLogs() {
+  if (registered) return
+  registered = true
+
+  if (!import.meta.hot) return
+
+  import.meta.hot.on('storyboard:hot-pool-log', (data) => {
+    if (!isDevLogsEnabled()) return
+    const poolTag = data.poolId ? `:${data.poolId}` : ''
+    console.log(`%c[hot-pool${poolTag}]%c ${data.message}`, 'color: #8b5cf6; font-weight: bold', 'color: inherit')
+  })
+}

package/src/internals/canvas/textSelection.js

@@ -0,0 +1,10 @@
+const TEXT_SELECTION_EDITING_SELECTOR = 'textarea, [contenteditable="true"], [contenteditable=""], [data-canvas-allow-text-selection]'
+
+/**
+ * Returns true when canvas mouse interactions should suppress browser text selection.
+ */
+export function shouldPreventCanvasTextSelection(target) {
+  if (!(target instanceof Element)) return true
+  return !target.closest(TEXT_SELECTION_EDITING_SELECTOR)
+}
+

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

@@ -0,0 +1,26 @@
+import { shouldPreventCanvasTextSelection } from './textSelection.js'
+
+describe('shouldPreventCanvasTextSelection', () => {
+  it('prevents selection for regular canvas elements', () => {
+    const container = document.createElement('div')
+    const regular = document.createElement('p')
+    container.appendChild(regular)
+
+    expect(shouldPreventCanvasTextSelection(regular)).toBe(true)
+  })
+
+  it('allows selection for textarea editing', () => {
+    const textarea = document.createElement('textarea')
+    expect(shouldPreventCanvasTextSelection(textarea)).toBe(false)
+  })
+
+  it('allows selection for explicit editable markers', () => {
+    const wrapper = document.createElement('div')
+    wrapper.setAttribute('data-canvas-allow-text-selection', '')
+    const child = document.createElement('span')
+    wrapper.appendChild(child)
+
+    expect(shouldPreventCanvasTextSelection(child)).toBe(false)
+  })
+})
+