@dfosco/storyboard-react 2.8.0 → 3.0.0

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "2.8.0",
+    "@dfosco/storyboard-core": "3.0.0",
+    "@dfosco/tiny-canvas": "file:../tiny-canvas",
+    "@neodrag/react": "^2.3.1",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1"
   },
@@ -24,6 +26,7 @@
   "exports": {
     ".": "./src/index.js",
     "./vite": "./src/vite/data-plugin.js",
-    "./hash-preserver": "./src/hashPreserver.js"
+    "./hash-preserver": "./src/hashPreserver.js",
+    "./canvas/CanvasPage": "./src/canvas/CanvasPage.jsx"
   }
 }

package/src/Viewfinder.jsx

@@ -1,5 +1,5 @@
 
-import { useRef, useEffect } from 'react'
+import { useRef, useEffect, useMemo } from 'react'
 
 /**
  * Viewfinder — thin React wrapper around the Svelte Viewfinder component.
@@ -23,9 +23,10 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
 
   const shouldHideDefault = hideDefaultFlow ?? hideDefaultScene
 
-  const knownRoutes = Object.keys(pageModules)
+  const knownRoutes = useMemo(() => Object.keys(pageModules)
     .map(p => p.replace('/src/prototypes/', '').replace('.jsx', ''))
-    .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder')
+    .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder'),
+  [pageModules])
 
   useEffect(() => {
     if (!containerRef.current) return
@@ -53,7 +54,7 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         handleRef.current = null
       }
     }
-  }, [title, subtitle, basePath, showThumbnails, shouldHideDefault])
+  }, [title, subtitle, basePath, knownRoutes, showThumbnails, shouldHideDefault])
 
   return <div ref={containerRef} style={{ minHeight: '100vh' }} />
 }

package/src/canvas/CanvasPage.jsx

@@ -0,0 +1,145 @@
+import { createElement, useCallback, useRef, useState } from 'react'
+import { Canvas } from '@dfosco/tiny-canvas'
+import { useCanvas } from './useCanvas.js'
+import { getWidgetComponent } from './widgets/index.js'
+import ComponentWidget from './widgets/ComponentWidget.jsx'
+import CanvasToolbar from './CanvasToolbar.jsx'
+import { updateCanvas, removeWidget as removeWidgetApi } from './canvasApi.js'
+import styles from './CanvasPage.module.css'
+
+/**
+ * Debounce helper — returns a function that delays invocation.
+ */
+function debounce(fn, ms) {
+  let timer
+  return (...args) => {
+    clearTimeout(timer)
+    timer = setTimeout(() => fn(...args), ms)
+  }
+}
+
+/** Renders a single JSON-defined widget by type lookup. */
+function WidgetRenderer({ widget, onUpdate, onRemove }) {
+  const Component = getWidgetComponent(widget.type)
+  if (!Component) {
+    console.warn(`[canvas] Unknown widget type: ${widget.type}`)
+    return null
+  }
+  return createElement(Component, {
+    id: widget.id,
+    props: widget.props,
+    onUpdate,
+    onRemove,
+  })
+}
+
+/**
+ * Generic canvas page component.
+ * Reads canvas data from the index and renders all widgets on a draggable surface.
+ *
+ * @param {{ name: string }} props - Canvas name as indexed by the data plugin
+ */
+export default function CanvasPage({ name }) {
+  const { canvas, jsxExports, loading } = useCanvas(name)
+
+  // Local mutable copy of widgets for instant UI updates
+  const [localWidgets, setLocalWidgets] = useState(canvas?.widgets ?? null)
+  const [trackedCanvas, setTrackedCanvas] = useState(canvas)
+  if (canvas !== trackedCanvas) {
+    setTrackedCanvas(canvas)
+    setLocalWidgets(canvas?.widgets ?? null)
+  }
+
+  // Debounced save to server
+  const debouncedSave = useRef(
+    debounce((canvasName, widgets) => {
+      updateCanvas(canvasName, { widgets }).catch((err) =>
+        console.error('[canvas] Failed to save:', err)
+      )
+    }, 2000)
+  ).current
+
+  const handleWidgetUpdate = useCallback((widgetId, updates) => {
+    setLocalWidgets((prev) => {
+      if (!prev) return prev
+      const next = prev.map((w) =>
+        w.id === widgetId ? { ...w, props: { ...w.props, ...updates } } : w
+      )
+      debouncedSave(name, next)
+      return next
+    })
+  }, [name, debouncedSave])
+
+  const handleWidgetRemove = useCallback((widgetId) => {
+    setLocalWidgets((prev) => prev ? prev.filter((w) => w.id !== widgetId) : prev)
+    removeWidgetApi(name, widgetId).catch((err) =>
+      console.error('[canvas] Failed to remove widget:', err)
+    )
+  }, [name])
+
+  if (!canvas) {
+    return (
+      <div className={styles.empty}>
+        <p>Canvas &ldquo;{name}&rdquo; not found</p>
+      </div>
+    )
+  }
+
+  if (loading) {
+    return (
+      <div className={styles.loading}>
+        <p>Loading canvas…</p>
+      </div>
+    )
+  }
+
+  const canvasProps = {
+    centered: canvas.centered ?? false,
+    dotted: canvas.dotted ?? false,
+    grid: canvas.grid ?? false,
+    gridSize: canvas.gridSize ?? 18,
+    colorMode: canvas.colorMode ?? 'auto',
+  }
+
+  // Merge JSX-sourced widgets (from .canvas.jsx) and JSON widgets
+  const allChildren = []
+
+  // 1. JSX-sourced component widgets
+  if (jsxExports) {
+    for (const [exportName, Component] of Object.entries(jsxExports)) {
+      allChildren.push(
+        <div key={`jsx-${exportName}`} id={`jsx-${exportName}`}>
+          <ComponentWidget component={Component} />
+        </div>
+      )
+    }
+  }
+
+  // 2. JSON-defined mutable widgets
+  for (const widget of (localWidgets ?? [])) {
+    allChildren.push(
+      <div key={widget.id} id={widget.id}>
+        <WidgetRenderer
+          widget={widget}
+          onUpdate={(updates) => handleWidgetUpdate(widget.id, updates)}
+          onRemove={() => handleWidgetRemove(widget.id)}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <>
+      <Canvas {...canvasProps}>
+        {allChildren}
+      </Canvas>
+      <CanvasToolbar
+        canvasName={name}
+        onWidgetAdded={() => {
+          // Reload the page to pick up the new widget from the updated .canvas.json
+          window.location.reload()
+        }}
+      />
+    </>
+  )
+}

package/src/canvas/CanvasPage.module.css

@@ -0,0 +1,15 @@
+.empty,
+.loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
+  color: var(--fgColor-muted, #656d76);
+  font-size: 16px;
+}
+
+.empty p,
+.loading p {
+  margin: 0;
+}

package/src/canvas/CanvasToolbar.jsx

@@ -0,0 +1,76 @@
+import { useState } from 'react'
+import { addWidget as addWidgetApi } from './canvasApi.js'
+import { schemas, getDefaults } from './widgets/widgetProps.js'
+import styles from './CanvasToolbar.module.css'
+
+const WIDGET_TYPES = [
+  { type: 'sticky-note', label: 'Sticky Note', icon: '📝' },
+  { type: 'markdown', label: 'Markdown', icon: '📄' },
+  { type: 'prototype', label: 'Prototype', icon: '🖥️' },
+]
+
+/**
+ * Floating toolbar for adding widgets to a canvas.
+ */
+export default function CanvasToolbar({ canvasName, onWidgetAdded }) {
+  const [open, setOpen] = useState(false)
+  const [adding, setAdding] = useState(false)
+
+  async function handleAdd(type) {
+    if (adding) return
+    setAdding(true)
+    try {
+      const defaultProps = schemas[type] ? getDefaults(schemas[type]) : {}
+      const result = await addWidgetApi(canvasName, {
+        type,
+        props: defaultProps,
+        position: { x: 0, y: 0 },
+      })
+      if (result.success) {
+        onWidgetAdded?.(result.widget)
+        setOpen(false)
+      }
+    } catch (err) {
+      console.error('[canvas] Failed to add widget:', err)
+    } finally {
+      setAdding(false)
+    }
+  }
+
+  return (
+    <nav className={styles.toolbar}>
+      {open ? (
+        <div className={styles.menu}>
+          <header className={styles.menuHeader}>
+            <span>Add widget</span>
+            <button
+              className={styles.closeBtn}
+              onClick={() => setOpen(false)}
+              aria-label="Close"
+            >×</button>
+          </header>
+          {WIDGET_TYPES.map(({ type, label, icon }) => (
+            <button
+              key={type}
+              className={styles.menuItem}
+              onClick={() => handleAdd(type)}
+              disabled={adding}
+            >
+              <span className={styles.menuIcon}>{icon}</span>
+              {label}
+            </button>
+          ))}
+        </div>
+      ) : (
+        <button
+          className={styles.addBtn}
+          onClick={() => setOpen(true)}
+          title="Add widget"
+          aria-label="Add widget"
+        >
+          +
+        </button>
+      )}
+    </nav>
+  )
+}

package/src/canvas/CanvasToolbar.module.css

@@ -0,0 +1,92 @@
+.toolbar {
+  position: fixed;
+  bottom: 80px;
+  left: 24px;
+  z-index: 1000;
+  font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
+}
+
+.addBtn {
+  all: unset;
+  cursor: pointer;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background: var(--bgColor-accent-emphasis, #2f81f7);
+  color: var(--fgColor-onEmphasis, #ffffff);
+  font-size: 28px;
+  font-weight: 300;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+  transition: transform 150ms, background 150ms;
+}
+
+.addBtn:hover {
+  transform: scale(1.08);
+  background: var(--bgColor-accent-emphasis, #388bfd);
+}
+
+.menu {
+  background: var(--bgColor-default, #ffffff);
+  border: 1px solid var(--borderColor-muted, rgba(0, 0, 0, 0.15));
+  border-radius: 12px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
+  overflow: hidden;
+  min-width: 180px;
+}
+
+.menuHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--fgColor-muted, #656d76);
+  border-bottom: 1px solid var(--borderColor-muted, rgba(0, 0, 0, 0.1));
+}
+
+.closeBtn {
+  all: unset;
+  cursor: pointer;
+  font-size: 16px;
+  line-height: 1;
+  color: var(--fgColor-muted, #656d76);
+  padding: 0 2px;
+  border-radius: 4px;
+}
+
+.closeBtn:hover {
+  color: var(--fgColor-default, #1f2328);
+}
+
+.menuItem {
+  all: unset;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  font-size: 14px;
+  color: var(--fgColor-default, #1f2328);
+  width: 100%;
+  box-sizing: border-box;
+  transition: background 100ms;
+}
+
+.menuItem:hover {
+  background: var(--bgColor-muted, #f6f8fa);
+}
+
+.menuItem:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.menuIcon {
+  font-size: 18px;
+}

package/src/canvas/canvasApi.js

@@ -0,0 +1,41 @@
+/**
+ * Client-side API for canvas CRUD operations.
+ * Calls the /_storyboard/canvas/ server endpoints.
+ */
+
+const BASE = '/_storyboard/canvas'
+
+function getApiBase() {
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+  return base + BASE
+}
+
+async function request(path, method, body) {
+  const url = getApiBase() + path
+  const res = await fetch(url, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  return res.json()
+}
+
+export function listCanvases() {
+  return request('/list', 'GET')
+}
+
+export function createCanvas(data) {
+  return request('/create', 'POST', data)
+}
+
+export function updateCanvas(name, { widgets, sources, settings }) {
+  return request('/update', 'PUT', { name, widgets, sources, settings })
+}
+
+export function addWidget(name, { type, props, position }) {
+  return request('/widget', 'POST', { name, type, props, position })
+}
+
+export function removeWidget(name, widgetId) {
+  return request('/widget', 'DELETE', { name, widgetId })
+}

package/src/canvas/useCanvas.js

@@ -0,0 +1,74 @@
+import { useState, useEffect, useMemo } from 'react'
+import { getCanvasData } from '@dfosco/storyboard-core'
+
+/**
+ * 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) {
+  try {
+    const base = (import.meta.env?.BASE_URL || '/').replace(/\/$/, '')
+    const res = await fetch(`${base}/_storyboard/canvas/read?name=${encodeURIComponent(name)}`)
+    if (res.ok) return res.json()
+  } catch { /* fall back to build-time data */ }
+  return null
+}
+
+/**
+ * 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} name - Canvas name as indexed by the data plugin
+ * @returns {{ canvas: object|null, jsxExports: object|null, loading: boolean }}
+ */
+export function useCanvas(name) {
+  const buildTimeCanvas = useMemo(() => getCanvasData(name), [name])
+  const [canvas, setCanvas] = useState(buildTimeCanvas)
+  const [jsxExports, setJsxExports] = useState(null)
+  const [loading, setLoading] = useState(true)
+
+  // Fetch fresh data from server on mount
+  useEffect(() => {
+    if (!buildTimeCanvas) {
+      setCanvas(null)
+      setLoading(false)
+      return
+    }
+
+    setLoading(true)
+    fetchCanvasFromServer(name).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)
+    })
+  }, [name, buildTimeCanvas])
+
+  useEffect(() => {
+    if (!canvas?._jsxModule) {
+      setJsxExports(null)
+      return
+    }
+
+    import(/* @vite-ignore */ canvas._jsxModule)
+      .then((mod) => {
+        const exports = {}
+        for (const [key, value] of Object.entries(mod)) {
+          if (key !== 'default' && typeof value === 'function') {
+            exports[key] = value
+          }
+        }
+        setJsxExports(exports)
+      })
+      .catch((err) => {
+        console.error(`[storyboard] Failed to load canvas JSX module: ${canvas._jsxModule}`, err)
+        setJsxExports(null)
+      })
+  }, [canvas?._jsxModule])
+
+  return { canvas, jsxExports, loading }
+}

package/src/canvas/widgets/ComponentWidget.jsx

@@ -0,0 +1,15 @@
+import WidgetWrapper from './WidgetWrapper.jsx'
+
+/**
+ * Renders a live JSX export from a .canvas.jsx companion file.
+ * Content is read-only (re-renders on HMR), only position is mutable.
+ */
+export default function ComponentWidget({ component: Component }) {
+  if (!Component) return null
+
+  return (
+    <WidgetWrapper>
+      <Component />
+    </WidgetWrapper>
+  )
+}

package/src/canvas/widgets/MarkdownBlock.jsx

@@ -0,0 +1,87 @@
+import { useState, useRef, useEffect } from 'react'
+import WidgetWrapper from './WidgetWrapper.jsx'
+import { readProp, markdownSchema } from './widgetProps.js'
+import styles from './MarkdownBlock.module.css'
+
+/**
+ * Renders markdown as plain HTML using a minimal built-in converter.
+ */
+function renderMarkdown(text) {
+  if (!text) return ''
+  return text
+    .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+    .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+    .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    .replace(/\*(.+?)\*/g, '<em>$1</em>')
+    .replace(/`(.+?)`/g, '<code>$1</code>')
+    .replace(/^- (.+)$/gm, '<li>$1</li>')
+    .replace(/(<li>.*<\/li>)/s, '<ul>$1</ul>')
+    .replace(/\n\n/g, '</p><p>')
+    .replace(/\n/g, '<br>')
+    .replace(/^(.+)$/gm, (line) => {
+      if (line.startsWith('<')) return line
+      return `<p>${line}</p>`
+    })
+}
+
+export default function MarkdownBlock({ props, onUpdate, onRemove }) {
+  const content = readProp(props, 'content', markdownSchema)
+  const width = readProp(props, 'width', markdownSchema)
+  const [editing, setEditing] = useState(false)
+  const textareaRef = useRef(null)
+  const blockRef = useRef(null)
+  const [editHeight, setEditHeight] = useState(null)
+
+  useEffect(() => {
+    if (editing) {
+      // Capture the preview height before switching to editor
+      if (blockRef.current && !editHeight) {
+        setEditHeight(blockRef.current.offsetHeight)
+      }
+      if (textareaRef.current) {
+        textareaRef.current.focus()
+      }
+    } else {
+      setEditHeight(null)
+    }
+  }, [editing, editHeight])
+
+  return (
+    <WidgetWrapper onRemove={onRemove}>
+      <div
+        ref={blockRef}
+        className={styles.block}
+        style={{ width, minHeight: editHeight || undefined }}
+      >
+        {editing ? (
+          <textarea
+            ref={textareaRef}
+            className={styles.editor}
+            style={{ minHeight: editHeight ? editHeight - 2 : undefined }}
+            value={content}
+            onChange={(e) => onUpdate?.({ content: e.target.value })}
+            onBlur={() => setEditing(false)}
+            onMouseDown={(e) => e.stopPropagation()}
+            onPointerDown={(e) => e.stopPropagation()}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape') setEditing(false)
+            }}
+            placeholder="Write markdown…"
+          />
+        ) : (
+          <div
+            className={styles.preview}
+            onDoubleClick={() => setEditing(true)}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') setEditing(true) }}
+            dangerouslySetInnerHTML={{
+              __html: renderMarkdown(content) || '<p class="placeholder">Double-click to edit…</p>',
+            }}
+          />
+        )}
+      </div>
+    </WidgetWrapper>
+  )
+}

package/src/canvas/widgets/MarkdownBlock.module.css

@@ -0,0 +1,78 @@
+.block {
+  min-height: 80px;
+  background: var(--bgColor-default, #ffffff);
+  font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
+}
+
+.preview {
+  padding: 16px 20px;
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--fgColor-default, #1f2328);
+  cursor: text;
+  min-height: 60px;
+}
+
+.preview h1 {
+  font-size: 20px;
+  font-weight: 700;
+  margin: 0 0 8px;
+  line-height: 1.3;
+}
+
+.preview h2 {
+  font-size: 17px;
+  font-weight: 600;
+  margin: 0 0 6px;
+  line-height: 1.3;
+}
+
+.preview h3 {
+  font-size: 15px;
+  font-weight: 600;
+  margin: 0 0 4px;
+  line-height: 1.3;
+}
+
+.preview p {
+  margin: 0 0 8px;
+}
+
+.preview code {
+  background: var(--bgColor-neutral-muted, #afb8c133);
+  padding: 2px 5px;
+  border-radius: 4px;
+  font-size: 13px;
+  font-family: ui-monospace, monospace;
+}
+
+.preview ul {
+  margin: 0 0 8px;
+  padding-left: 20px;
+}
+
+.preview li {
+  margin: 0 0 2px;
+}
+
+.preview :global(.placeholder) {
+  color: var(--fgColor-muted, #656d76);
+  font-style: italic;
+}
+
+.editor {
+  display: block;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  min-height: 120px;
+  padding: 16px 20px;
+  border: none;
+  outline: none;
+  background: var(--bgColor-default, #ffffff);
+  font-family: ui-monospace, SFMono-Regular, monospace;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--fgColor-default, #1f2328);
+  resize: none;
+}