@dfosco/storyboard-react 4.0.0-beta.3 → 4.0.0-beta.31

package/src/canvas/canvasReloadGuard.js

@@ -0,0 +1,37 @@
+/**
+ * Canvas reload guard — client-side state for preventing HMR full reloads.
+ *
+ * This module tracks whether a canvas is currently active. When active,
+ * the Vite plugin suppresses full-page reloads to preserve canvas state.
+ *
+ * The actual guard logic is implemented in:
+ * - Server: vite.config.js (ws.send monkey-patch + heartbeat)
+ * - Client: CanvasPage.jsx (vite:beforeFullReload + vite:ws:disconnect)
+ *
+ * This module provides the state that those systems check.
+ */
+
+let active = false
+
+/**
+ * Enable the canvas reload guard.
+ * Call when a canvas page mounts.
+ */
+export function enableCanvasGuard() {
+  active = true
+}
+
+/**
+ * Disable the canvas reload guard.
+ * Call when a canvas page unmounts.
+ */
+export function disableCanvasGuard() {
+  active = false
+}
+
+/**
+ * Check if the canvas reload guard is currently active.
+ */
+export function isCanvasGuardActive() {
+  return active
+}

package/src/canvas/canvasReloadGuard.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { enableCanvasGuard, disableCanvasGuard, isCanvasGuardActive } from './canvasReloadGuard.js'
+
+describe('canvasReloadGuard', () => {
+  beforeEach(() => {
+    disableCanvasGuard()
+  })
+
+  it('starts inactive', () => {
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+
+  it('can be enabled and disabled', () => {
+    enableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(true)
+    disableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+
+  it('enable is idempotent', () => {
+    enableCanvasGuard()
+    enableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(true)
+    disableCanvasGuard()
+    expect(isCanvasGuardActive()).toBe(false)
+  })
+})

package/src/canvas/componentIsolate.jsx

@@ -0,0 +1,135 @@
+/**
+ * Canvas Component Isolate — iframe entry point.
+ *
+ * Renders a single named export from a .canvas.jsx module inside an
+ * isolated document. The parent CanvasPage embeds this via an iframe
+ * so a broken component cannot crash the entire canvas.
+ *
+ * Query params:
+ *   module — absolute or base-relative path to the .canvas.jsx file
+ *   export — the named export to render
+ *   theme  — canvas theme (light / dark / dark_dimmed)
+ */
+import { createElement, Component as ReactComponent } 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'
+
+// ── 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
+  }
+}
+
+// ── Styles ──────────────────────────────────────────────────────────
+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 (mirrors useCanvas.resolveCanvasModuleImport) ─
+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}`
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+const params = new URLSearchParams(window.location.search)
+const modulePath = params.get('module')
+const exportName = params.get('export')
+const theme = params.get('theme') || 'light'
+
+// Map theme to Primer colorMode
+const colorMode = theme.startsWith('dark') ? 'night' : 'day'
+
+// Apply theme to document for Primer / CSS-var inheritance
+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')
+
+const root = createRoot(document.getElementById('root'))
+
+async function mount() {
+  if (!modulePath || !exportName) {
+    root.render(createElement('div', { style: errorStyle }, 'Missing module or export param'))
+    return
+  }
+
+  // Validate: only allow .canvas.jsx and .story.{jsx,tsx} modules
+  if (!modulePath.endsWith('.canvas.jsx') && !modulePath.match(/\.story\.(jsx|tsx)$/)) {
+    root.render(createElement('div', { style: errorStyle }, 'Invalid module path — only .canvas.jsx and .story.jsx/.tsx files are allowed'))
+    return
+  }
+
+  try {
+    const resolved = resolveModulePath(modulePath)
+    const mod = await import(/* @vite-ignore */ resolved)
+    const Component = mod[exportName]
+
+    if (!Component || typeof Component !== 'function') {
+      throw new Error(`Export "${exportName}" not found or is not a component`)
+    }
+
+    root.render(
+      createElement(ThemeProvider, { colorMode },
+        createElement(BaseStyles, null,
+          createElement(IsolateErrorBoundary, { name: exportName },
+            createElement(Component),
+          ),
+        ),
+      ),
+    )
+  } catch (err) {
+    root.render(
+      createElement('div', { style: errorStyle },
+        createElement('strong', null, exportName),
+        createElement('br'),
+        String(err.message || err),
+      ),
+    )
+  }
+}
+
+mount()

package/src/canvas/useCanvas.js

@@ -31,13 +31,14 @@ export function resolveCanvasModuleImport(modulePath, baseUrl = import.meta.env?
  * 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} name - Canvas name as indexed by the data plugin
- * @returns {{ canvas: object|null, jsxExports: object|null, loading: boolean }}
+ * @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(name) {
-  const buildTimeCanvas = useMemo(() => getCanvasData(name), [name])
+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
@@ -49,7 +50,7 @@ export function useCanvas(name) {
     }
 
     setLoading(true)
-    fetchCanvasFromServer(name).then((fresh) => {
+    fetchCanvasFromServer(canvasId).then((fresh) => {
       if (fresh) {
         // Merge: use server data for widgets/sources, keep build-time for _route/_jsxModule
         setCanvas({ ...buildTimeCanvas, ...fresh })
@@ -58,7 +59,7 @@ export function useCanvas(name) {
       }
       setLoading(false)
     })
-  }, [name, buildTimeCanvas])
+  }, [canvasId, buildTimeCanvas])
 
   const jsxModule = canvas?._jsxModule
   const jsxImport = canvas?._jsxImport
@@ -66,6 +67,7 @@ export function useCanvas(name) {
   useEffect(() => {
     if (!jsxModule) {
       setJsxExports(null)
+      setJsxError(false)
       return
     }
 
@@ -82,10 +84,12 @@ export function useCanvas(name) {
           }
         }
         setJsxExports(exports)
+        setJsxError(false)
       })
       .catch((err) => {
         console.error(`[storyboard] Failed to load canvas JSX module: ${jsxModule}`, err)
         setJsxExports(null)
+        setJsxError(true)
       })
   }, [jsxModule, jsxImport])
 
@@ -95,8 +99,9 @@ export function useCanvas(name) {
     if (!import.meta.hot || !buildTimeCanvas) return
 
     const handleCanvasFileChanged = ({ data }) => {
-      if (!data || data.name !== name) return
-      fetchCanvasFromServer(name).then((fresh) => {
+      const eventId = data?.canvasId || data?.name
+      if (!data || eventId !== canvasId) return
+      fetchCanvasFromServer(canvasId).then((fresh) => {
         if (fresh) {
           setCanvas((prev) => ({ ...(prev || buildTimeCanvas), ...fresh }))
         }
@@ -107,7 +112,7 @@ export function useCanvas(name) {
     return () => {
       import.meta.hot.off('storyboard:canvas-file-changed', handleCanvasFileChanged)
     }
-  }, [name, buildTimeCanvas])
+  }, [canvasId, buildTimeCanvas])
 
-  return { canvas, jsxExports, loading }
+  return { canvas, jsxExports, jsxError, loading }
 }

package/src/canvas/widgets/CodePenEmbed.jsx

@@ -0,0 +1,292 @@
+/**
+ * CodePen embed widget for canvas.
+ *
+ * Behaves like FigmaEmbed: click-to-interact overlay, iframe kept alive
+ * after deselect, expand modal, open-external action. Created via paste
+ * when a CodePen URL is pasted onto the canvas.
+ */
+import { forwardRef, useImperativeHandle, useMemo, useCallback, useState, useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
+import WidgetWrapper from './WidgetWrapper.jsx'
+import { readProp } from './widgetProps.js'
+import { schemas } from './widgetConfig.js'
+import { isCodePenUrl, toCodePenEmbedUrl, getCodePenTitle, fetchCodePenMeta } from './codepenUrl.js'
+import { useIframeDevLogs } from './iframeDevLogs.js'
+import styles from './CodePenEmbed.module.css'
+import overlayStyles from './embedOverlay.module.css'
+
+const codepenEmbedSchema = schemas['codepen-embed']
+
+/** Feather Icons codepen icon (stroke-based) */
+function CodePenLogo({ className }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <polygon points="12 2 22 8.5 22 15.5 12 22 2 15.5 2 8.5 12 2" />
+      <line x1="12" y1="22" x2="12" y2="15.5" />
+      <polyline points="22 8.5 12 15.5 2 8.5" />
+      <polyline points="2 15.5 12 8.5 22 15.5" />
+      <line x1="12" y1="2" x2="12" y2="8.5" />
+    </svg>
+  )
+}
+
+/** Stroke-based code icon for empty state */
+function CodeIcon({ size = 32, className }) {
+  return (
+    <svg
+      className={className}
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <polyline points="16 18 22 12 16 6" />
+      <polyline points="8 6 2 12 8 18" />
+    </svg>
+  )
+}
+
+export default forwardRef(function CodePenEmbed({ props, onUpdate, resizable }, ref) {
+  const url = readProp(props, 'url', codepenEmbedSchema)
+  const width = readProp(props, 'width', codepenEmbedSchema)
+  const height = readProp(props, 'height', codepenEmbedSchema)
+
+  const [interactive, setInteractive] = useState(false)
+  const [showIframe, setShowIframe] = useState(true)
+  const [expanded, setExpanded] = useState(false)
+
+  const iframeRef = useRef(null)
+  const embedRef = useRef(null)
+  const inlineContainerRef = useRef(null)
+  const modalContainerRef = useRef(null)
+  const teardownTimerRef = useRef(null)
+  const exitSessionRef = useRef(0)
+
+  const isValid = useMemo(() => isCodePenUrl(url), [url])
+  const embedUrl = useMemo(() => (isValid ? toCodePenEmbedUrl(url) : ''), [url, isValid])
+  const fallbackTitle = useMemo(() => (url ? getCodePenTitle(url) : 'CodePen'), [url])
+
+  // Fetch pen metadata (title + author) from CodePen oEmbed API
+  const [penMeta, setPenMeta] = useState(null)
+  useEffect(() => {
+    if (!url || !isValid) return
+    let cancelled = false
+    fetchCodePenMeta(url).then((meta) => {
+      if (!cancelled && meta) setPenMeta(meta)
+    })
+    return () => { cancelled = true }
+  }, [url, isValid])
+
+  const headerTitle = penMeta?.title
+    ? `${penMeta.title} · ${penMeta.author || fallbackTitle}`
+    : fallbackTitle
+
+  useIframeDevLogs({
+    widget: 'CodePenEmbed',
+    loaded: showIframe && Boolean(embedUrl),
+    src: embedUrl,
+  })
+
+  const enterInteractive = useCallback(() => {
+    exitSessionRef.current++
+    clearTimeout(teardownTimerRef.current)
+    setShowIframe(true)
+    setInteractive(true)
+  }, [])
+
+  // Exit interactive mode on click outside — keep iframe alive for 2 min
+  useEffect(() => {
+    if (!interactive || expanded) return
+    function handlePointerDown(e) {
+      if (embedRef.current && !embedRef.current.contains(e.target)) {
+        setInteractive(false)
+        const session = ++exitSessionRef.current
+        clearTimeout(teardownTimerRef.current)
+        teardownTimerRef.current = setTimeout(() => {
+          if (exitSessionRef.current !== session) return
+          setShowIframe(false)
+        }, 2 * 60 * 1000)
+      }
+    }
+    document.addEventListener('pointerdown', handlePointerDown)
+    return () => document.removeEventListener('pointerdown', handlePointerDown)
+  }, [interactive, expanded])
+
+  useEffect(() => () => clearTimeout(teardownTimerRef.current), [])
+
+  // Close expanded modal on Escape
+  useEffect(() => {
+    if (!expanded) return
+    function handleKeyDown(e) {
+      if (e.key === 'Escape') {
+        e.stopPropagation()
+        setExpanded(false)
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown, true)
+    return () => document.removeEventListener('keydown', handleKeyDown, true)
+  }, [expanded])
+
+  // Reparent iframe between inline and modal containers
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (!iframe) return
+
+    if (expanded && modalContainerRef.current) {
+      iframe._savedClassName = iframe.className
+      iframe._savedStyle = iframe.getAttribute('style') || ''
+      iframe.className = styles.expandIframe
+      iframe.removeAttribute('style')
+      const target = modalContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, target.firstChild)
+      } else {
+        target.prepend(iframe)
+      }
+    } else if (!expanded && inlineContainerRef.current) {
+      if (iframe._savedClassName !== undefined) {
+        iframe.className = iframe._savedClassName
+        iframe.setAttribute('style', iframe._savedStyle)
+        delete iframe._savedClassName
+        delete iframe._savedStyle
+      }
+      const target = inlineContainerRef.current
+      if (target.moveBefore) {
+        target.moveBefore(iframe, null)
+      } else {
+        target.appendChild(iframe)
+      }
+    }
+  }, [expanded])
+
+  useImperativeHandle(ref, () => ({
+    handleAction(actionId) {
+      if (actionId === 'open-external') {
+        if (url) window.open(url, '_blank', 'noopener')
+      } else if (actionId === 'expand') {
+        setShowIframe(true)
+        setExpanded(true)
+      }
+    },
+  }), [url])
+
+  return (
+    <>
+    <WidgetWrapper>
+      <div ref={embedRef} className={styles.embed} style={{ width, height }}>
+        <div className={styles.header}>
+          <CodePenLogo className={styles.codepenLogo} />
+          <span className={styles.headerTitle}>{headerTitle}</span>
+        </div>
+        {embedUrl ? (
+          <>
+            {showIframe ? (
+              <div
+                ref={inlineContainerRef}
+                className={styles.iframeContainer}
+                style={expanded ? { visibility: 'hidden' } : undefined}
+              >
+                <iframe
+                  ref={iframeRef}
+                  src={embedUrl}
+                  className={styles.iframe}
+                  title={`CodePen: ${headerTitle}`}
+                  allowFullScreen
+                  loading="lazy"
+                />
+              </div>
+            ) : (
+              <div className={styles.iframeContainer} />
+            )}
+            {!interactive && !expanded && (
+              <div
+                className={overlayStyles.interactOverlay}
+                onClick={(e) => {
+                  if (e.shiftKey || e.metaKey || e.ctrlKey || e.altKey) return
+                  enterInteractive()
+                }}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault()
+                    e.stopPropagation()
+                    enterInteractive()
+                  }
+                }}
+                aria-label="Click to interact with CodePen embed"
+              >
+                <span className={overlayStyles.interactHint}>Click to interact</span>
+              </div>
+            )}
+          </>
+        ) : (
+          <div className={styles.emptyState}>
+            <CodeIcon size={32} className={styles.emptyIcon} />
+            <span className={styles.emptyLabel}>No CodePen URL</span>
+          </div>
+        )}
+      </div>
+      {resizable && (
+        <div
+          className={styles.resizeHandle}
+          onMouseDown={(e) => {
+            e.stopPropagation()
+            e.preventDefault()
+            const startX = e.clientX
+            const startY = e.clientY
+            const startW = width
+            const startH = height
+            function onMove(ev) {
+              const newW = Math.max(200, startW + ev.clientX - startX)
+              const newH = Math.max(150, startH + ev.clientY - startY)
+              onUpdate?.({ width: newW, height: newH })
+            }
+            function onUp() {
+              document.removeEventListener('mousemove', onMove)
+              document.removeEventListener('mouseup', onUp)
+            }
+            document.addEventListener('mousemove', onMove)
+            document.addEventListener('mouseup', onUp)
+          }}
+          onPointerDown={(e) => e.stopPropagation()}
+        />
+      )}
+    </WidgetWrapper>
+    {createPortal(
+      <div
+        className={styles.expandBackdrop}
+        style={expanded && embedUrl ? undefined : { display: 'none' }}
+        onClick={() => setExpanded(false)}
+        onPointerDown={(e) => e.stopPropagation()}
+        onKeyDown={(e) => {
+          e.stopPropagation()
+          if (e.key === 'Escape') setExpanded(false)
+        }}
+        onWheel={(e) => e.stopPropagation()}
+        tabIndex={-1}
+        ref={(el) => { if (el && expanded) el.focus() }}
+      >
+        <div
+          ref={modalContainerRef}
+          className={styles.expandContainer}
+          onClick={(e) => e.stopPropagation()}
+        >
+          <button
+            className={styles.expandClose}
+            onClick={() => setExpanded(false)}
+            aria-label="Close expanded view"
+            autoFocus
+          >✕</button>
+        </div>
+      </div>,
+      document.body
+    )}
+    </>
+  )
+})