@dfosco/storyboard-react 4.0.0-beta.2 → 4.0.0-beta.20

package/src/canvas/CanvasPage.module.css

@@ -44,58 +44,14 @@
   gap: 8px;
 }
 
-.canvasTitleWrap {
-  display: inline-grid;
-}
-
-.canvasTitleWrap > * {
-  grid-area: 1 / 1;
-}
-
-.canvasTitleMeasure {
-  visibility: hidden;
-  white-space: pre;
-  font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
-  font-size: 14px;
-  font-weight: 600;
-  padding: 4px 8px;
-  border: 1px solid transparent;
-  min-width: 80px;
-  pointer-events: none;
-}
-
-.canvasTitleInput {
+.canvasTitleStatic {
   font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
   font-size: 14px;
   font-weight: 600;
   color: var(--fgColor-muted, #656d76);
-  background: transparent;
-  border: 1px solid transparent;
-  border-radius: 6px;
-  padding: 4px 8px;
   margin: 0;
-  outline: none;
-  width: 100%;
-  min-width: 0;
-  transition: border-color 150ms, background-color 150ms, color 150ms;
-}
-
-.canvasTitleInput:hover {
-  color: var(--fgColor-default, #1f2328);
-  border-color: var(--borderColor-default, #d1d9e0);
-  background: var(--bgColor-default, #ffffff);
-}
-
-.canvasTitleInput:focus {
-  color: var(--fgColor-default, #1f2328);
-  border-color: var(--bgColor-accent-emphasis, #2f81f7);
-  background: var(--bgColor-default, #ffffff);
-}
-
-.canvasTitleStatic {
-  composes: canvasTitleInput;
-  cursor: default;
-  pointer-events: none;
+  padding: 4px 8px;
+  white-space: nowrap;
 }
 
 /* Remove tiny-canvas wrapper clipping — widgets handle their own overflow/radius */
@@ -103,6 +59,12 @@
   overflow: visible;
 }
 
+/* Elevate stacking context for hovered/selected widgets so their chrome
+   (toolbar, menus, selection outline) renders above sibling widgets. */
+:global(.tc-drag:has([data-tc-elevated])) {
+  z-index: 1;
+}
+
 .localEditingLabel {
   display: inline-flex;
   align-items: center;

package/src/canvas/ComponentErrorBoundary.jsx

@@ -0,0 +1,50 @@
+import { Component } from 'react'
+
+/**
+ * Error boundary for canvas component widgets.
+ * Catches render-time errors so a single broken component
+ * doesn't crash the entire canvas page.
+ *
+ * Used as a production fallback when iframe isolation is not available.
+ */
+export default class ComponentErrorBoundary extends Component {
+  constructor(props) {
+    super(props)
+    this.state = { error: null }
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error }
+  }
+
+  componentDidCatch(error, info) {
+    console.error(
+      `[storyboard] Component widget "${this.props.name || 'unknown'}" crashed:`,
+      error,
+      info?.componentStack,
+    )
+  }
+
+  render() {
+    if (this.state.error) {
+      return (
+        <div style={{
+          padding: '16px',
+          color: '#cf222e',
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          fontSize: '13px',
+          lineHeight: 1.5,
+          whiteSpace: 'pre-wrap',
+          wordBreak: 'break-word',
+          minWidth: 200,
+          minHeight: 60,
+        }}>
+          <strong>{this.props.name || 'Component'}</strong>
+          <br />
+          {String(this.state.error.message || this.state.error)}
+        </div>
+      )
+    }
+    return this.props.children
+  }
+}

package/src/canvas/PageSelector.jsx

@@ -0,0 +1,102 @@
+import { useCallback, useRef, useState, useEffect } from 'react'
+import styles from './PageSelector.module.css'
+
+/**
+ * In-canvas page selector — shows sibling pages in the same canvas group.
+ * Only renders when 2+ sibling pages exist.
+ * Uses window.location for navigation to avoid requiring a Router context.
+ *
+ * @param {{ currentName: string, pages: Array<{ name: string, route: string, title: string }> }} props
+ */
+export default function PageSelector({ currentName, pages }) {
+  const [open, setOpen] = useState(false)
+  const containerRef = useRef(null)
+
+  const currentPage = pages.find((p) => p.name === currentName)
+  const currentLabel = currentPage?.title || currentName.split('/').pop()
+  const currentIndex = pages.findIndex((p) => p.name === currentName)
+
+  const handleSelect = useCallback(
+    (page) => {
+      if (page.name !== currentName) {
+        const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+        window.location.href = base + page.route
+      }
+      setOpen(false)
+    },
+    [currentName],
+  )
+
+  // Close on outside click
+  useEffect(() => {
+    if (!open) return
+    function handleClick(e) {
+      if (containerRef.current && !containerRef.current.contains(e.target)) {
+        setOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClick)
+    return () => document.removeEventListener('mousedown', handleClick)
+  }, [open])
+
+  // Close on Escape
+  useEffect(() => {
+    if (!open) return
+    function handleKey(e) {
+      if (e.key === 'Escape') setOpen(false)
+    }
+    document.addEventListener('keydown', handleKey)
+    return () => document.removeEventListener('keydown', handleKey)
+  }, [open])
+
+  if (!pages || pages.length < 2) return null
+
+  return (
+    <nav ref={containerRef} className={styles.container} aria-label="Canvas pages">
+      <button
+        className={styles.trigger}
+        onClick={() => setOpen((v) => !v)}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        title="Switch canvas page"
+      >
+        <span className={styles.label}>{currentLabel}</span>
+        <span className={styles.badge}>
+          {currentIndex + 1}/{pages.length}
+        </span>
+        <svg
+          className={`${styles.chevron} ${open ? styles.chevronOpen : ''}`}
+          width="12"
+          height="12"
+          viewBox="0 0 12 12"
+          fill="none"
+          aria-hidden="true"
+        >
+          <path d="M3 4.5L6 7.5L9 4.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      </button>
+      {open && (
+        <ul className={styles.menu} role="listbox" aria-label="Canvas pages">
+          {pages.map((page) => (
+            <li
+              key={page.name}
+              role="option"
+              aria-selected={page.name === currentName}
+              className={`${styles.item} ${page.name === currentName ? styles.itemActive : ''}`}
+              onClick={() => handleSelect(page)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault()
+                  handleSelect(page)
+                }
+              }}
+              tabIndex={0}
+            >
+              {page.title}
+            </li>
+          ))}
+        </ul>
+      )}
+    </nav>
+  )
+}

package/src/canvas/PageSelector.module.css

@@ -0,0 +1,93 @@
+.container {
+  position: relative;
+  font-size: 13px;
+}
+
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 5px 10px;
+  border: 1px solid var(--borderColor-default, rgba(0, 0, 0, 0.15));
+  border-radius: 6px;
+  background: var(--bgColor-default, #fff);
+  color: var(--fgColor-default, #1f2328);
+  cursor: pointer;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+  transition: border-color 0.15s, box-shadow 0.15s;
+  line-height: 1;
+}
+
+.trigger:hover {
+  border-color: var(--borderColor-emphasis, rgba(0, 0, 0, 0.3));
+  box-shadow: 0 1px 5px rgba(0, 0, 0, 0.12);
+}
+
+.label {
+  font-weight: 600;
+  max-width: 200px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.badge {
+  font-size: 11px;
+  color: var(--fgColor-muted, #656d76);
+  font-variant-numeric: tabular-nums;
+}
+
+.chevron {
+  color: var(--fgColor-muted, #656d76);
+  transition: transform 0.15s;
+  flex-shrink: 0;
+}
+
+.chevronOpen {
+  transform: rotate(180deg);
+}
+
+.menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  min-width: 180px;
+  max-width: 300px;
+  max-height: 320px;
+  overflow-y: auto;
+  margin: 0;
+  padding: 4px;
+  list-style: none;
+  background: var(--bgColor-default, #fff);
+  border: 1px solid var(--borderColor-default, rgba(0, 0, 0, 0.15));
+  border-radius: 8px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
+}
+
+.item {
+  padding: 6px 10px;
+  border-radius: 4px;
+  cursor: pointer;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--fgColor-default, #1f2328);
+}
+
+.item:hover {
+  background: var(--bgColor-muted, #f6f8fa);
+}
+
+.item:focus-visible {
+  outline: 2px solid var(--focus-outlineColor, #0969da);
+  outline-offset: -2px;
+}
+
+.itemActive {
+  font-weight: 600;
+  background: var(--bgColor-accent-muted, #ddf4ff);
+}
+
+.itemActive:hover {
+  background: var(--bgColor-accent-muted, #ddf4ff);
+}

package/src/canvas/PageSelector.test.jsx

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import PageSelector from './PageSelector.jsx'
+
+const PAGES = [
+  { name: 'research/interviews', route: '/canvas/research/interviews', title: 'Interviews' },
+  { name: 'research/surveys', route: '/canvas/research/surveys', title: 'Surveys' },
+  { name: 'research/analysis', route: '/canvas/research/analysis', title: 'Analysis' },
+]
+
+describe('PageSelector', () => {
+  beforeEach(() => {
+    // Reset location mock
+    delete window.location
+    window.location = { href: '' }
+  })
+
+  it('renders nothing when fewer than 2 pages', () => {
+    const { container } = render(<PageSelector currentName="solo" pages={[{ name: 'solo', route: '/canvas/solo', title: 'Solo' }]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('renders nothing when pages is empty', () => {
+    const { container } = render(<PageSelector currentName="foo" pages={[]} />)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('shows current page label and page count', () => {
+    render(<PageSelector currentName="research/interviews" pages={PAGES} />)
+    expect(screen.getByText('Interviews')).toBeTruthy()
+    expect(screen.getByText('1/3')).toBeTruthy()
+  })
+
+  it('shows correct index for non-first page', () => {
+    render(<PageSelector currentName="research/surveys" pages={PAGES} />)
+    expect(screen.getByText('Surveys')).toBeTruthy()
+    expect(screen.getByText('2/3')).toBeTruthy()
+  })
+
+  it('opens dropdown on click and shows all pages', () => {
+    render(<PageSelector currentName="research/interviews" pages={PAGES} />)
+    const trigger = screen.getByTitle('Switch canvas page')
+    fireEvent.click(trigger)
+
+    const options = screen.getAllByRole('option')
+    expect(options).toHaveLength(3)
+    expect(options[0].textContent).toBe('Interviews')
+    expect(options[1].textContent).toBe('Surveys')
+    expect(options[2].textContent).toBe('Analysis')
+  })
+
+  it('marks the current page as active', () => {
+    render(<PageSelector currentName="research/surveys" pages={PAGES} />)
+    fireEvent.click(screen.getByTitle('Switch canvas page'))
+
+    const options = screen.getAllByRole('option')
+    expect(options[1].getAttribute('aria-selected')).toBe('true')
+    expect(options[0].getAttribute('aria-selected')).toBe('false')
+  })
+
+  it('navigates to selected page', () => {
+    render(<PageSelector currentName="research/interviews" pages={PAGES} />)
+    fireEvent.click(screen.getByTitle('Switch canvas page'))
+    // Click the option in the menu (not the trigger label)
+    const options = screen.getAllByRole('option')
+    fireEvent.click(options[1]) // Surveys
+
+    expect(window.location.href).toContain('/canvas/research/surveys')
+  })
+
+  it('closes dropdown on Escape', () => {
+    render(<PageSelector currentName="research/interviews" pages={PAGES} />)
+    fireEvent.click(screen.getByTitle('Switch canvas page'))
+    expect(screen.queryByRole('listbox')).toBeTruthy()
+
+    fireEvent.keyDown(document, { key: 'Escape' })
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('closes dropdown on outside click', () => {
+    render(
+      <div>
+        <PageSelector currentName="research/interviews" pages={PAGES} />
+        <span data-testid="outside">Outside</span>
+      </div>
+    )
+    fireEvent.click(screen.getByTitle('Switch canvas page'))
+    expect(screen.queryByRole('listbox')).toBeTruthy()
+
+    fireEvent.mouseDown(screen.getByTestId('outside'))
+    expect(screen.queryByRole('listbox')).toBeNull()
+  })
+
+  it('does not navigate when selecting the current page', () => {
+    render(<PageSelector currentName="research/interviews" pages={PAGES} />)
+    fireEvent.click(screen.getByTitle('Switch canvas page'))
+    // Click the current page option
+    const options = screen.getAllByRole('option')
+    fireEvent.click(options[0]) // Interviews (current)
+
+    // location.href was set to '' initially, should remain unchanged
+    expect(window.location.href).toBe('')
+  })
+})

package/src/canvas/canvasApi.js

@@ -47,3 +47,7 @@ export function uploadImage(dataUrl, canvasName) {
 export function toggleImagePrivacy(filename) {
   return request('/image/toggle-private', 'POST', { filename })
 }
+
+export function getCanvas(name) {
+  return request(`/read?name=${encodeURIComponent(name)}`, 'GET')
+}

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

@@ -32,12 +32,13 @@ export function resolveCanvasModuleImport(modulePath, baseUrl = import.meta.env?
  * 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 }}
+ * @returns {{ canvas: object|null, jsxExports: object|null, jsxError: boolean, loading: boolean }}
  */
 export function useCanvas(name) {
   const buildTimeCanvas = useMemo(() => getCanvasData(name), [name])
   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
@@ -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])
 
@@ -109,5 +113,5 @@ export function useCanvas(name) {
     }
   }, [name, buildTimeCanvas])
 
-  return { canvas, jsxExports, loading }
+  return { canvas, jsxExports, jsxError, loading }
 }