@dfosco/storyboard-react 2.8.0 → 3.1.0

package/src/hooks/useFlows.js

@@ -0,0 +1,50 @@
+import { useContext, useMemo, useCallback } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getFlowsForPrototype, resolveFlowRoute } from '@dfosco/storyboard-core'
+import { getFlowMeta } from '@dfosco/storyboard-core'
+
+/**
+ * List all flows for the current prototype and switch between them.
+ *
+ * @returns {{
+ *   flows: Array<{ key: string, name: string, title: string, route: string }>,
+ *   activeFlow: string,
+ *   switchFlow: (flowKey: string) => void,
+ *   prototypeName: string | null
+ * }}
+ */
+export function useFlows() {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useFlows must be used within a <StoryboardProvider>')
+  }
+
+  const { flowName: activeFlow, prototypeName } = context
+
+  const flows = useMemo(() => {
+    if (!prototypeName) return []
+    return getFlowsForPrototype(prototypeName).map(f => {
+      const meta = getFlowMeta(f.key)
+      return {
+        key: f.key,
+        name: f.name,
+        title: meta?.title || f.name,
+        route: resolveFlowRoute(f.key),
+      }
+    })
+  }, [prototypeName])
+
+  const switchFlow = useCallback((flowKey) => {
+    const flow = flows.find(f => f.key === flowKey)
+    if (flow) {
+      window.location.href = flow.route
+    }
+  }, [flows])
+
+  return {
+    flows,
+    activeFlow,
+    switchFlow,
+    prototypeName,
+  }
+}

package/src/hooks/useFlows.test.js

@@ -0,0 +1,134 @@
+import { renderHook } from '@testing-library/react'
+import { createElement } from 'react'
+import { init, getFlowsForPrototype } from '@dfosco/storyboard-core'
+import { useFlows } from './useFlows.js'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+// Test data with prototype-scoped flows
+const SCOPED_FLOWS = {
+  'default': { meta: { title: 'Default' } },
+  'Signup/empty-form': { meta: { title: 'Empty Form' }, _route: '/Signup' },
+  'Signup/validation-errors': { meta: { title: 'Validation Errors' }, _route: '/Signup' },
+  'Signup/prefilled-review': { meta: { title: 'Prefilled Review' }, _route: '/Signup' },
+  'Signup/error-state': { meta: { title: 'Error State' }, _route: '/Signup' },
+  'Example/basic': { meta: { title: 'Example Data Flow' }, _route: '/Example' },
+}
+
+function seedScopedData() {
+  init({ flows: SCOPED_FLOWS, objects: {}, records: {} })
+}
+
+function createWrapperWithPrototype(flowName = 'default', prototypeName = null) {
+  return function Wrapper({ children }) {
+    return createElement(
+      StoryboardContext.Provider,
+      { value: { data: {}, error: null, loading: false, flowName, sceneName: flowName, prototypeName } },
+      children,
+    )
+  }
+}
+
+beforeEach(() => {
+  seedScopedData()
+})
+
+// ── Core utility: getFlowsForPrototype ──
+
+describe('getFlowsForPrototype', () => {
+  it('returns flows scoped to the given prototype', () => {
+    const flows = getFlowsForPrototype('Signup')
+    expect(flows).toHaveLength(4)
+    expect(flows.map(f => f.name)).toEqual([
+      'empty-form', 'validation-errors', 'prefilled-review', 'error-state',
+    ])
+  })
+
+  it('returns the full key with prototype prefix', () => {
+    const flows = getFlowsForPrototype('Signup')
+    expect(flows[0].key).toBe('Signup/empty-form')
+  })
+
+  it('returns empty array for prototype with no flows', () => {
+    const flows = getFlowsForPrototype('NonExistent')
+    expect(flows).toEqual([])
+  })
+
+  it('returns empty array when prototypeName is null', () => {
+    const flows = getFlowsForPrototype(null)
+    expect(flows).toEqual([])
+  })
+
+  it('returns empty array when prototypeName is empty string', () => {
+    const flows = getFlowsForPrototype('')
+    expect(flows).toEqual([])
+  })
+
+  it('excludes global flows (no prototype prefix)', () => {
+    const flows = getFlowsForPrototype('Signup')
+    const keys = flows.map(f => f.key)
+    expect(keys).not.toContain('default')
+  })
+
+  it('returns single flow for prototype with one flow', () => {
+    const flows = getFlowsForPrototype('Example')
+    expect(flows).toHaveLength(1)
+    expect(flows[0].name).toBe('basic')
+  })
+})
+
+// ── useFlows hook ──
+
+describe('useFlows', () => {
+  it('returns flows for the current prototype', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(result.current.flows).toHaveLength(4)
+    expect(result.current.flows[0].title).toBe('Empty Form')
+  })
+
+  it('returns the active flow key', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/validation-errors', 'Signup'),
+    })
+    expect(result.current.activeFlow).toBe('Signup/validation-errors')
+  })
+
+  it('returns prototype name', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(result.current.prototypeName).toBe('Signup')
+  })
+
+  it('returns empty flows when no prototype', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('default', null),
+    })
+    expect(result.current.flows).toEqual([])
+  })
+
+  it('switchFlow is a function', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(typeof result.current.switchFlow).toBe('function')
+  })
+
+  it('flow entries have title from meta', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    const titles = result.current.flows.map(f => f.title)
+    expect(titles).toContain('Empty Form')
+    expect(titles).toContain('Validation Errors')
+    expect(titles).toContain('Prefilled Review')
+    expect(titles).toContain('Error State')
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useFlows())
+    }).toThrow('useFlows must be used within a <StoryboardProvider>')
+  })
+})

package/src/index.js

@@ -16,6 +16,7 @@ export { useSceneData, useSceneLoading } from './hooks/useSceneData.js'
 export { useOverride } from './hooks/useOverride.js'
 export { useOverride as useSession } from './hooks/useOverride.js' // deprecated alias
 export { useFlow, useScene } from './hooks/useScene.js'
+export { useFlows } from './hooks/useFlows.js'
 export { useRecord, useRecords } from './hooks/useRecord.js'
 export { useObject } from './hooks/useObject.js'
 export { useLocalStorage } from './hooks/useLocalStorage.js'
@@ -35,3 +36,7 @@ export { FormContext } from './context/FormContext.js'
 
 // Viewfinder dashboard
 export { default as Viewfinder } from './Viewfinder.jsx'
+
+// Canvas
+export { default as CanvasPage } from './canvas/CanvasPage.jsx'
+export { useCanvas } from './canvas/useCanvas.js'

package/src/vite/data-plugin.js

@@ -3,11 +3,13 @@ import path from 'node:path'
 import { execSync } from 'node:child_process'
 import { globSync } from 'glob'
 import { parse as parseJsonc } from 'jsonc-parser'
+import { materializeFromText } from '@dfosco/storyboard-core/canvas/materializer'
 
 const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
 const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
 
 const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jsonc}'
+const CANVAS_GLOB_PATTERN = '**/*.canvas.jsonl'
 
 /**
  * Extract the data name and type suffix from a file path.
@@ -22,6 +24,44 @@ const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jso
  */
 function parseDataFile(filePath) {
   const base = path.basename(filePath)
+
+  // Handle .canvas.jsonl files
+  const canvasJsonlMatch = base.match(/^(.+)\.canvas\.jsonl$/)
+  if (canvasJsonlMatch) {
+    if (canvasJsonlMatch[1].startsWith('_')) return null
+    const normalized = filePath.replace(/\\/g, '/')
+    if (normalized.split('/').some(seg => seg.startsWith('_'))) return null
+
+    const name = canvasJsonlMatch[1]
+    let inferredRoute = null
+    const canvasFolderMatch = normalized.match(/(?:^|\/)src\/canvas\/([^/]+)\.folder\//)
+    const canvasFolderName = canvasFolderMatch ? canvasFolderMatch[1] : null
+    const folderDirMatch = normalized.match(/(?:^|\/)src\/prototypes\/([^/]+)\.folder\//)
+    const folderName = folderDirMatch ? folderDirMatch[1] : null
+
+    const canvasCheck = normalized.match(/(?:^|\/)src\/canvas\//)
+    if (canvasCheck) {
+      const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
+      const routeBase = (dirPath + '/')
+        .replace(/^.*?src\/canvas\//, '')
+        .replace(/[^/]*\.folder\/?/g, '')
+        .replace(/\/$/, '')
+      inferredRoute = '/canvas/' + (routeBase ? routeBase + '/' : '') + name
+      inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/canvas'
+    }
+    const protoCheck = normalized.match(/(?:^|\/)src\/prototypes\//)
+    if (!canvasCheck && protoCheck) {
+      const dirPath = normalized.substring(0, normalized.lastIndexOf('/'))
+      const routeBase = (dirPath + '/')
+        .replace(/^.*?src\/prototypes\//, '')
+        .replace(/[^/]*\.folder\/?/g, '')
+        .replace(/\/$/, '')
+      inferredRoute = '/canvas/' + (routeBase ? routeBase + '/' : '') + name
+      inferredRoute = inferredRoute.replace(/\/+/g, '/').replace(/\/$/, '') || '/canvas'
+    }
+    return { name, suffix: 'canvas', ext: 'jsonl', folder: canvasFolderName || folderName, inferredRoute }
+  }
+
   const match = base.match(/^(.+)\.(flow|scene|object|record|prototype|folder)\.(jsonc?)$/)
   if (!match) return null
 
@@ -121,6 +161,7 @@ function getLastModified(root, dirPath) {
 function buildIndex(root) {
   const ignore = ['node_modules/**', 'dist/**', '.git/**']
   const files = globSync(GLOB_PATTERN, { cwd: root, ignore, absolute: false })
+  const canvasFiles = globSync(CANVAS_GLOB_PATTERN, { cwd: root, ignore, absolute: false })
 
   // Detect nested .folder/ directories (not supported)
   // Scan directories directly since empty nested folders have no data files
@@ -137,12 +178,13 @@ function buildIndex(root) {
     }
   }
 
-  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {} }
+  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {}, canvas: {} }
   const seen = {} // "name.suffix" → absolute path (for duplicate detection)
   const protoFolders = {} // prototype name → folder name (for injection)
   const flowRoutes = {} // flow name → inferred route (for _route injection)
+  const canvasRoutes = {} // canvas name → inferred route
 
-  for (const relPath of files) {
+  for (const relPath of [...files, ...canvasFiles]) {
     const parsed = parseDataFile(relPath)
     if (!parsed) continue
 
@@ -175,9 +217,14 @@ function buildIndex(root) {
     if (parsed.suffix === 'flow' && parsed.inferredRoute) {
       flowRoutes[parsed.name] = parsed.inferredRoute
     }
+
+    // Track inferred routes for canvases
+    if (parsed.suffix === 'canvas' && parsed.inferredRoute) {
+      canvasRoutes[parsed.name] = parsed.inferredRoute
+    }
   }
 
-  return { index, protoFolders, flowRoutes }
+  return { index, protoFolders, flowRoutes, canvasRoutes }
 }
 
 /**
@@ -248,25 +295,26 @@ function readConfig(root) {
 }
 
 /**
- * Read modes.config.json from @dfosco/storyboard-core.
- * Returns the full config object { modes, tools }.
+ * Read core-ui.config.json from @dfosco/storyboard-core.
+ * Returns the full config object with modes array.
  * Falls back to hardcoded defaults if not found.
  */
 function readModesConfig(root) {
   const fallback = {
     modes: [
-      { name: 'prototype', label: 'Navigate' },
-      { name: 'inspect', label: 'Develop' },
-      { name: 'present', label: 'Collaborate' },
-      { name: 'plan', label: 'Canvas' },
+      { name: 'prototype', label: 'Navigate', hue: '#2a2a2a' },
+      { name: 'inspect', label: 'Develop', hue: '#7655a4' },
+      { name: 'present', label: 'Collaborate', hue: '#2a9d8f' },
+      { name: 'plan', label: 'Canvas', hue: '#4a7fad' },
     ],
-    tools: {},
   }
 
   // Try local workspace path first (monorepo), then node_modules
   const candidates = [
-    path.resolve(root, 'packages/core/modes.config.json'),
-    path.resolve(root, 'node_modules/@dfosco/storyboard-core/modes.config.json'),
+    path.resolve(root, 'packages/core/core-ui.config.json'),
+    path.resolve(root, 'packages/core/configs/modes.config.json'),
+    path.resolve(root, 'node_modules/@dfosco/storyboard-core/core-ui.config.json'),
+    path.resolve(root, 'node_modules/@dfosco/storyboard-core/configs/modes.config.json'),
   ]
 
   for (const filePath of candidates) {
@@ -274,7 +322,7 @@ function readModesConfig(root) {
       const raw = fs.readFileSync(filePath, 'utf-8')
       const parsed = JSON.parse(raw)
       if (Array.isArray(parsed.modes) && parsed.modes.length > 0) {
-        return { modes: parsed.modes, tools: parsed.tools ?? {} }
+        return { modes: parsed.modes }
       }
     } catch {
       // try next candidate
@@ -284,10 +332,10 @@ function readModesConfig(root) {
   return fallback
 }
 
-function generateModule({ index, protoFolders, flowRoutes }, root) {
+function generateModule({ index, protoFolders, flowRoutes, canvasRoutes }, root) {
   const declarations = []
-  const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder']
-  const entries = { flow: [], object: [], record: [], prototype: [], folder: [] }
+  const INDEX_KEYS = ['flow', 'object', 'record', 'prototype', 'folder', 'canvas']
+  const entries = { flow: [], object: [], record: [], prototype: [], folder: [], canvas: [] }
   const resolvedFlowRoutes = {} // flow name → resolved route (for multi-flow logging)
   let i = 0
 
@@ -295,7 +343,9 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
     for (const [name, absPath] of Object.entries(index[suffix])) {
       const varName = `_d${i++}`
       const raw = fs.readFileSync(absPath, 'utf-8')
-      let parsed = parseJsonc(raw)
+      let parsed = suffix === 'canvas'
+        ? materializeFromText(raw)
+        : parseJsonc(raw)
 
       // Auto-fill gitAuthor for prototype metadata from git history
       if (suffix === 'prototype' && parsed && !parsed.gitAuthor) {
@@ -332,6 +382,37 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
         }
       }
 
+      // Inject inferred route and resolve JSX companion for canvases
+      if (suffix === 'canvas') {
+        if (canvasRoutes[name]) {
+          parsed = { ...parsed, _route: canvasRoutes[name] }
+        }
+        // Inject folder association
+        const folderDirMatch = path.relative(root, absPath).replace(/\\/g, '/').match(/(?:^|\/)src\/(?:prototypes|canvas)\/([^/]+)\.folder\//)
+        if (folderDirMatch) {
+          parsed = { ...parsed, _folder: folderDirMatch[1] }
+        }
+        // Resolve JSX companion file path
+        if (parsed?.jsx) {
+          const jsxPath = path.resolve(path.dirname(absPath), parsed.jsx)
+          if (fs.existsSync(jsxPath)) {
+            const relJsx = '/' + path.relative(root, jsxPath).replace(/\\/g, '/')
+            parsed = { ...parsed, _jsxModule: relJsx }
+          } else {
+            console.warn(
+              `[storyboard-data] Canvas "${name}" references JSX file "${parsed.jsx}" but it was not found at ${jsxPath}`
+            )
+          }
+        } else {
+          // Auto-detect a same-name .canvas.jsx companion
+          const autoJsx = absPath.replace(/\.canvas\.(jsonl|jsonc?)$/, '.canvas.jsx')
+          if (fs.existsSync(autoJsx)) {
+            const relJsx = '/' + path.relative(root, autoJsx).replace(/\\/g, '/')
+            parsed = { ...parsed, _jsxModule: relJsx }
+          }
+        }
+      }
+
       // Resolve template variables (${currentDir}, ${currentProto}, ${currentProtoDir})
       const templateVars = computeTemplateVars(absPath, root)
       if (!templateVars.currentProto && raw.includes('${currentProto}')) {
@@ -354,7 +435,7 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
   }
 
   const imports = [`import { init } from '@dfosco/storyboard-core'`]
-  const initCalls = [`init({ flows, objects, records, prototypes, folders })`]
+  const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases })`]
 
   // Feature flags from storyboard.config.json
   const { config } = readConfig(root)
@@ -383,15 +464,16 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
         initCalls.push(`registerMode(${JSON.stringify(m.name)}, { label: ${JSON.stringify(m.label)} })`)
       }
 
-      // Seed tool registry from modes.config.json
-      if (Object.keys(modesConfig.tools).length > 0) {
-        initCalls.push(`initTools(${JSON.stringify(modesConfig.tools)})`)
-      }
-
       initCalls.push(`syncModeClasses()`)
     }
   }
 
+  // UI config from storyboard.config.json (menu visibility overrides)
+  if (config?.ui) {
+    imports.push(`import { initUIConfig } from '@dfosco/storyboard-core'`)
+    initCalls.push(`initUIConfig(${JSON.stringify(config.ui)})`)
+  }
+
   // Log info when multiple flows target the same route
   const routeGroups = {}
   for (const [name, { route, isDefault }] of Object.entries(resolvedFlowRoutes)) {
@@ -422,14 +504,15 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
     `const records = {\n${entries.record.join(',\n')}\n}`,
     `const prototypes = {\n${entries.prototype.join(',\n')}\n}`,
     `const folders = {\n${entries.folder.join(',\n')}\n}`,
+    `const canvases = {\n${entries.canvas.join(',\n')}\n}`,
     '',
     '// Backward-compatible alias',
     'const scenes = flows',
     '',
     initCalls.join('\n'),
     '',
-    `export { flows, scenes, objects, records, prototypes, folders }`,
-    `export const index = { flows, scenes, objects, records, prototypes, folders }`,
+    `export { flows, scenes, objects, records, prototypes, folders, canvases }`,
+    `export const index = { flows, scenes, objects, records, prototypes, folders, canvases }`,
     `export default index`,
   ].join('\n')
 }
@@ -437,7 +520,7 @@ function generateModule({ index, protoFolders, flowRoutes }, root) {
 /**
  * Vite plugin for storyboard data discovery.
  *
- * - Scans the repo for *.flow.json, *.scene.json (compat), *.object.json, *.record.json
+ * - Scans the repo for *.flow.json, *.scene.json (compat), *.object.json, *.record.json, *.canvas.jsonl
  * - Validates no two files share the same name+suffix (hard build error)
  * - Generates a virtual module `virtual:storyboard-data-index`
  * - Watches for file additions/removals in dev mode
@@ -477,9 +560,15 @@ export default function storyboardDataPlugin() {
       const watcher = server.watcher
 
       const invalidate = (filePath) => {
+        const normalized = filePath.replace(/\\/g, '/')
+        // Skip .canvas.jsonl content changes entirely — these are mutated
+        // at runtime by the canvas server API. A full-reload would create
+        // a feedback loop (save → file change → reload → lose editing state).
+        if (/\.canvas\.jsonl$/.test(normalized)) return
+
         const parsed = parseDataFile(filePath)
         // Also invalidate when files are added/removed inside .folder/ directories
-        const inFolder = filePath.replace(/\\/g, '/').includes('.folder/')
+        const inFolder = normalized.includes('.folder/')
         if (!parsed && !inFolder) return
         // Rebuild index and invalidate virtual module
         buildResult = null
@@ -490,6 +579,19 @@ export default function storyboardDataPlugin() {
         }
       }
 
+      const invalidateOnAddRemove = (filePath) => {
+        const parsed = parseDataFile(filePath)
+        const inFolder = filePath.replace(/\\/g, '/').includes('.folder/')
+        if (!parsed && !inFolder) return
+        // Canvas additions/removals DO need a reload (new routes)
+        buildResult = null
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod)
+          server.ws.send({ type: 'full-reload' })
+        }
+      }
+
       // Watch storyboard.config.json for changes
       const { configPath } = readConfig(root)
       watcher.add(configPath)
@@ -504,8 +606,8 @@ export default function storyboardDataPlugin() {
         }
       }
 
-      watcher.on('add', invalidate)
-      watcher.on('unlink', invalidate)
+      watcher.on('add', invalidateOnAddRemove)
+      watcher.on('unlink', invalidateOnAddRemove)
       watcher.on('change', (filePath) => {
         invalidate(filePath)
         invalidateConfig(filePath)

package/src/vite/data-plugin.test.js

@@ -69,13 +69,13 @@ describe('storyboardDataPlugin', () => {
     const code = plugin.load(RESOLVED_ID)
 
     expect(code).toContain("import { init } from '@dfosco/storyboard-core'")
-    expect(code).toContain('init({ flows, objects, records, prototypes, folders })')
+    expect(code).toContain('init({ flows, objects, records, prototypes, folders, canvases })')
     expect(code).toContain('"Test"')
     expect(code).toContain('"Jane"')
     expect(code).toContain('"First"')
     // Backward-compat alias
     expect(code).toContain('const scenes = flows')
-    expect(code).toContain('export { flows, scenes, objects, records, prototypes, folders }')
+    expect(code).toContain('export { flows, scenes, objects, records, prototypes, folders, canvases }')
   })
 
   it('load returns null for other IDs', () => {
@@ -161,7 +161,7 @@ describe('storyboardDataPlugin', () => {
 
     // .scene.json files should be normalized to the flows category
     expect(code).toContain('"Legacy Scene"')
-    expect(code).toContain('init({ flows, objects, records, prototypes, folders })')
+    expect(code).toContain('init({ flows, objects, records, prototypes, folders, canvases })')
   })
 
   it('buildStart resets the index cache', () => {