@dfosco/storyboard-react 2.0.0 → 2.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "*",
+    "@dfosco/storyboard-core": "2.2.0",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1"
   },

package/src/Viewfinder.jsx

@@ -1,227 +1,60 @@
 
-import { useState, useEffect, useMemo } from 'react'
-import { hash, resolveSceneRoute, getSceneMeta } from '@dfosco/storyboard-core'
-import styles from './Viewfinder.module.css'
-
-function formatSceneName(name) {
-  return name
-    .split('-')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ')
-}
-
-function PlaceholderGraphic({ name }) {
-  const seed = hash(name)
-  const rects = []
-
-  for (let i = 0; i < 12; i++) {
-    const s = seed * (i + 1)
-    const x = (s * 7 + i * 31) % 320
-    const y = (s * 13 + i * 17) % 200
-    const w = 20 + (s * (i + 3)) % 80
-    const h = 8 + (s * (i + 7)) % 40
-    const opacity = 0.06 + ((s * (i + 2)) % 20) / 100
-    const fill = i % 3 === 0 ? 'var(--placeholder-accent)' : i % 3 === 1 ? 'var(--placeholder-fg)' : 'var(--placeholder-muted)'
-
-    rects.push(
-      <rect
-        key={i}
-        x={x}
-        y={y}
-        width={w}
-        height={h}
-        rx={2}
-        fill={fill}
-        opacity={opacity}
-      />
-    )
-  }
-
-  const lines = []
-  for (let i = 0; i < 6; i++) {
-    const s = seed * (i + 5)
-    const y = 10 + (s % 180)
-    lines.push(
-      <line
-        key={`h${i}`}
-        x1={0}
-        y1={y}
-        x2={320}
-        y2={y}
-        stroke="var(--placeholder-grid)"
-        strokeWidth={0.5}
-        opacity={0.4}
-      />
-    )
-  }
-  for (let i = 0; i < 8; i++) {
-    const s = seed * (i + 9)
-    const x = 10 + (s % 300)
-    lines.push(
-      <line
-        key={`v${i}`}
-        x1={x}
-        y1={0}
-        x2={x}
-        y2={200}
-        stroke="var(--placeholder-grid)"
-        strokeWidth={0.5}
-        opacity={0.3}
-      />
-    )
-  }
-
-  return (
-    <svg viewBox="0 0 320 200" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
-      <rect width="320" height="200" fill="var(--placeholder-bg)" />
-      {lines}
-      {rects}
-    </svg>
-  )
-}
+import { useRef, useEffect } from 'react'
 
 /**
- * Derive the current branch label from the base path.
- * Branch deploy folders use the convention `branch--<name>/`.
- */
-function getCurrentBranch(basePath) {
-  const match = (basePath || '').match(/\/branch--([^/]+)\/?$/)
-  return match ? match[1] : 'main'
-}
-
-/**
- * Viewfinder — scene index and branch preview dashboard.
+ * Viewfinder — thin React wrapper around the Svelte Viewfinder component.
+ *
+ * Mounts the core Svelte Viewfinder into a container div and manages
+ * its lifecycle via React's useEffect.
  *
  * @param {Object} props
- * @param {Record<string, unknown>} props.scenes - Scene index object (keys are scene names)
- * @param {Record<string, unknown>} props.pageModules - import.meta.glob result for page files
- * @param {string} [props.basePath] - Base URL path (defaults to import.meta.env.BASE_URL)
- * @param {string} [props.title] - Header title (defaults to "Viewfinder")
- * @param {string} [props.subtitle] - Optional subtitle displayed below the title
- * @param {boolean} [props.showThumbnails] - Show thumbnail previews (defaults to false)
- * @param {boolean} [props.hideDefaultScene] - Hide the "default" scene from the list (defaults to false)
+ * @param {Record<string, unknown>} [props.scenes] - Scene/flow index (deprecated, ignored — data comes from core)
+ * @param {Record<string, unknown>} [props.flows] - Flow index (deprecated, ignored — data comes from core)
+ * @param {Record<string, unknown>} [props.pageModules] - import.meta.glob result for page files
+ * @param {string} [props.basePath] - Base URL path
+ * @param {string} [props.title] - Header title
+ * @param {string} [props.subtitle] - Optional subtitle
+ * @param {boolean} [props.showThumbnails] - Show thumbnail previews
+ * @param {boolean} [props.hideDefaultFlow] - Hide the "default" flow from the "Other flows" section
  */
-export default function Viewfinder({ scenes = {}, pageModules = {}, basePath, title = 'Viewfinder', subtitle, showThumbnails = false, hideDefaultScene = false }) {
-  const [branches, setBranches] = useState(null)
-
-  const sceneNames = useMemo(() => {
-    const names = Object.keys(scenes)
-    return hideDefaultScene ? names.filter(n => n !== 'default') : names
-  }, [scenes, hideDefaultScene])
-
-  const knownRoutes = useMemo(() =>
-    Object.keys(pageModules)
-      .map(p => p.replace('/src/pages/', '').replace('.jsx', ''))
-      .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder'),
-    [pageModules]
-  )
+export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyboard', subtitle, showThumbnails = false, hideDefaultFlow, hideDefaultScene = false }) {
+  const containerRef = useRef(null)
+  const handleRef = useRef(null)
 
-  const branchBasePath = useMemo(() => {
-    const base = basePath || '/storyboard-source/'
-    return base.replace(/\/branch--[^/]*\/$/, '/')
-  }, [basePath])
+  const shouldHideDefault = hideDefaultFlow ?? hideDefaultScene
 
-  const currentBranch = useMemo(() => getCurrentBranch(basePath), [basePath])
-
-  const MOCK_BRANCHES = useMemo(() => [
-    { branch: 'main', folder: '' },
-    { branch: 'feat/comments-v2', folder: 'branch--feat-comments-v2' },
-    { branch: 'fix/nav-overflow', folder: 'branch--fix-nav-overflow' },
-  ], [])
+  const knownRoutes = Object.keys(pageModules)
+    .map(p => p.replace('/src/prototypes/', '').replace('.jsx', ''))
+    .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder')
 
   useEffect(() => {
-    const url = `${branchBasePath}branches.json`
-    fetch(url)
-      .then(r => r.ok ? r.json() : null)
-      .then(data => setBranches(Array.isArray(data) && data.length > 0 ? data : MOCK_BRANCHES))
-      .catch(() => setBranches(MOCK_BRANCHES))
-  }, [branchBasePath, MOCK_BRANCHES])
-
-  const handleBranchChange = (e) => {
-    const folder = e.target.value
-    if (folder) {
-      window.location.href = `${branchBasePath}${folder}/`
+    if (!containerRef.current) return
+
+    let cancelled = false
+
+    import('@dfosco/storyboard-core/ui/viewfinder').then(({ mountViewfinder, unmountViewfinder }) => {
+      if (cancelled) return
+      // Ensure clean state for re-mounts
+      unmountViewfinder()
+      handleRef.current = mountViewfinder(containerRef.current, {
+        title,
+        subtitle,
+        basePath,
+        knownRoutes,
+        showThumbnails,
+        hideDefaultFlow: shouldHideDefault,
+      })
+    })
+
+    return () => {
+      cancelled = true
+      if (handleRef.current) {
+        handleRef.current.destroy()
+        handleRef.current = null
+      }
     }
-  }
+  }, [title, subtitle, basePath, showThumbnails, shouldHideDefault])
 
-  return (
-    <div className={styles.container}>
-      <header className={styles.header}>
-        <div className={styles.headerTop}>
-          <div>
-            <h1 className={styles.title}>{title}</h1>
-            {subtitle && <p className={styles.subtitle}>{subtitle}</p>}
-          </div>
-          {branches && branches.length > 0 && (
-            <div className={styles.branchDropdown}>
-              <svg className={styles.branchIcon} width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-                <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.492 2.492 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
-              </svg>
-              <select
-                id="branch-select"
-                className={styles.branchSelect}
-                defaultValue=""
-                onChange={handleBranchChange}
-                aria-label="Switch branch"
-              >
-                <option value="" disabled>{currentBranch}</option>
-                {branches.map((b) => (
-                  <option key={b.folder} value={b.folder}>
-                    {b.branch}
-                  </option>
-                ))}
-              </select>
-            </div>
-          )}
-        </div>
-        <p className={styles.sceneCount}>
-          {sceneNames.length} scene{sceneNames.length !== 1 ? 's' : ''}
-        </p>
-      </header>
-
-      {sceneNames.length === 0 ? (
-        <p className={styles.empty}>No scenes found. Add a <code>*.scene.json</code> file to get started.</p>
-      ) : (
-        <section>
-          {/* <h2 className={styles.sectionTitle}>Scenes</h2> */}
-          <div className={showThumbnails ? styles.grid : styles.list}>
-            {sceneNames.map((name) => {
-              const meta = getSceneMeta(name)
-              const displayName = meta?.title || meta?.name || formatSceneName(name)
-              return (
-                <a key={name} href={resolveSceneRoute(name, knownRoutes)} className={showThumbnails ? styles.card : styles.listItem}>
-                  {showThumbnails && (
-                    <div className={styles.thumbnail}>
-                      <PlaceholderGraphic name={name} />
-                    </div>
-                  )}
-                  <div className={styles.cardBody}>
-                    <p className={styles.sceneName}>{displayName}</p>
-                    {meta?.author && (() => {
-                      const authors = Array.isArray(meta.author) ? meta.author : [meta.author]
-                      return (
-                        <div className={styles.author}>
-                          <span className={styles.authorAvatars}>
-                            {authors.map((a) => (
-                              <img
-                                key={a}
-                                src={`https://github.com/${a}.png?size=32`}
-                                alt={a}
-                                className={styles.authorAvatar}
-                              />
-                            ))}
-                          </span>
-                          <span className={styles.authorName}>{authors.join(', ')}</span>
-                        </div>
-                      )
-                    })()}
-                  </div>
-                </a>
-              )
-            })}
-          </div>
-        </section>
-      )}
-    </div>
-  )
+  return <div ref={containerRef} style={{ minHeight: '100vh' }} />
 }
+

package/src/context.jsx

@@ -2,16 +2,28 @@ import { useEffect, useMemo } from 'react'
 import { useParams, useLocation } from 'react-router-dom'
 // Side-effect import: seeds the core data index via init()
 import 'virtual:storyboard-data-index'
-import { loadScene, sceneExists, findRecord, deepMerge, setSceneClass, installBodyClassSync } from '@dfosco/storyboard-core'
+import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled } from '@dfosco/storyboard-core'
 import { StoryboardContext } from './StoryboardContext.js'
 
 export { StoryboardContext }
 
 /**
- * Derives a scene name from a pathname.
+ * Derives the top-level prototype name from a pathname.
+ * "/Dashboard" → "Dashboard", "/Dashboard/sub" → "Dashboard"
+ * "/posts/123" → "posts", "/" → null
+ */
+function getPrototypeName(pathname) {
+  const path = pathname.replace(/\/+$/, '') || '/'
+  if (path === '/') return null
+  const segments = path.split('/').filter(Boolean)
+  return segments[0] || null
+}
+
+/**
+ * Derives a flow name from a pathname.
  * "/Overview" → "Overview", "/" → "index", "/nested/Page" → "Page"
  */
-function getPageSceneName(pathname) {
+function getPageFlowName(pathname) {
   const path = pathname.replace(/\/+$/, '') || '/'
   if (path === '/') return 'index'
   const last = path.split('/').pop()
@@ -19,51 +31,92 @@ function getPageSceneName(pathname) {
 }
 
 /**
- * Provides loaded scene data to the component tree.
- * Reads the scene name from the ?scene= URL param, the sceneName prop,
- * a matching scene file for the current page, or defaults to "default".
+ * Provides loaded flow data to the component tree.
+ * Reads the flow name from the ?flow= URL param (with ?scene= as alias),
+ * a matching flow file for the current page, or defaults to "default".
+ *
+ * Derives the prototype scope from the route and uses it to resolve
+ * scoped flow and record names (e.g. "Dashboard/default" for /Dashboard).
  *
  * Optionally merges record data when `recordName` and `recordParam` are provided.
- * The matched record entry is injected under the "record" key in scene data.
+ * The matched record entry is injected under the "record" key in flow data.
  */
-export default function StoryboardProvider({ sceneName, recordName, recordParam, children }) {
+export default function StoryboardProvider({ flowName, sceneName, recordName, recordParam, children }) {
   const location = useLocation()
-  const sceneParam = new URLSearchParams(location.search).get('scene')
-  const pageScene = getPageSceneName(location.pathname)
-  const activeSceneName = sceneParam || sceneName || (sceneExists(pageScene) ? pageScene : 'default')
+  const searchParams = new URLSearchParams(location.search)
+  const sceneParam = searchParams.get('flow') || searchParams.get('scene')
+  const prototypeName = getPrototypeName(location.pathname)
+  const pageFlow = getPageFlowName(location.pathname)
   const params = useParams()
 
+  // Resolve flow name with prototype scoping
+  const activeFlowName = useMemo(() => {
+    const requested = sceneParam || flowName || sceneName
+    if (requested) {
+      return resolveFlowName(prototypeName, requested)
+    }
+    // 1. Page-specific flow (e.g., Example/Forms)
+    const scopedPageFlow = resolveFlowName(prototypeName, pageFlow)
+    if (flowExists(scopedPageFlow)) return scopedPageFlow
+    // 2. Prototype flow — named after the prototype folder (e.g., Example/example)
+    if (prototypeName) {
+      const protoFlow = resolveFlowName(prototypeName, prototypeName)
+      if (flowExists(protoFlow)) return protoFlow
+    }
+    // 3. Global default
+    return 'default'
+  }, [sceneParam, flowName, sceneName, prototypeName, pageFlow])
+
   // Auto-install body class sync (sb-key--value classes on <body>)
   useEffect(() => installBodyClassSync(), [])
 
+  // Mount design modes UI when enabled in storyboard.config.json
+  useEffect(() => {
+    if (!isModesEnabled()) return
+
+    let cleanup
+    import('@dfosco/storyboard-core/ui/design-modes')
+      .then(({ mountDesignModesUI }) => {
+        cleanup = mountDesignModesUI()
+      })
+      .catch(() => {
+        // Svelte UI not available — degrade gracefully
+      })
+
+    return () => cleanup?.()
+  }, [])
+
   const { data, error } = useMemo(() => {
     try {
-      let sceneData = loadScene(activeSceneName)
+      let flowData = loadFlow(activeFlowName)
 
-      // Merge record data if configured
+      // Merge record data if configured (with scoped resolution)
       if (recordName && recordParam && params[recordParam]) {
-        const entry = findRecord(recordName, params[recordParam])
+        const resolvedRecord = resolveRecordName(prototypeName, recordName)
+        const entry = findRecord(resolvedRecord, params[recordParam])
         if (entry) {
-          sceneData = deepMerge(sceneData, { record: entry })
+          flowData = deepMerge(flowData, { record: entry })
         }
       }
 
-      setSceneClass(activeSceneName)
-      return { data: sceneData, error: null }
+      setFlowClass(activeFlowName)
+      return { data: flowData, error: null }
     } catch (err) {
       return { data: null, error: err.message }
     }
-  }, [activeSceneName, recordName, recordParam, params])
+  }, [activeFlowName, recordName, recordParam, params, prototypeName])
 
   const value = {
     data,
     error,
     loading: false,
-    sceneName: activeSceneName,
+    flowName: activeFlowName,
+    sceneName: activeFlowName, // backward compat
+    prototypeName,
   }
 
   if (error) {
-    return <span style={{ color: 'var(--fgColor-danger, #f85149)' }}>Error loading scene: {error}</span>
+    return <span style={{ color: 'var(--fgColor-danger, #f85149)' }}>Error loading flow: {error}</span>
   }
 
   return (

package/src/context.test.jsx

@@ -17,7 +17,7 @@ vi.mock('react-router-dom', async () => {
 
 beforeEach(() => {
   init({
-    scenes: {
+    flows: {
       default: { title: 'Default Scene' },
       other: { title: 'Other Scene' },
     },
@@ -36,7 +36,7 @@ function ContextReader({ path }) {
 }
 
 describe('StoryboardProvider', () => {
-  it('renders children when scene loads successfully', () => {
+  it('renders children when flow loads successfully', () => {
     render(
       <StoryboardProvider>
         <span>child content</span>
@@ -45,7 +45,7 @@ describe('StoryboardProvider', () => {
     expect(screen.getByText('child content')).toBeInTheDocument()
   })
 
-  it('provides scene data via context', () => {
+  it('provides flow data via context', () => {
     render(
       <StoryboardProvider>
         <ContextReader path="title" />
@@ -54,7 +54,16 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
   })
 
-  it('uses sceneName prop when provided', () => {
+  it('uses flowName prop when provided', () => {
+    render(
+      <StoryboardProvider flowName="other">
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('uses sceneName prop for backward compat', () => {
     render(
       <StoryboardProvider sceneName="other">
         <ContextReader path="title" />
@@ -63,7 +72,7 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
   })
 
-  it("falls back to 'default' scene when no ?scene= param", () => {
+  it("falls back to 'default' flow when no ?scene= param", () => {
     render(
       <StoryboardProvider>
         <ContextReader path="title" />
@@ -72,22 +81,35 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
   })
 
-  it('shows error message when scene fails to load', () => {
+  it('shows error message when flow fails to load', () => {
     render(
-      <StoryboardProvider sceneName="nonexistent">
+      <StoryboardProvider flowName="nonexistent">
         <ContextReader />
       </StoryboardProvider>,
     )
-    expect(screen.getByText(/Error loading scene/)).toBeInTheDocument()
+    expect(screen.getByText(/Error loading flow/)).toBeInTheDocument()
   })
 
-  it('provides sceneName in context value', () => {
+  it('provides flowName in context value', () => {
+    function FlowNameReader() {
+      const ctx = useContext(StoryboardContext)
+      return <span data-testid="name">{ctx?.flowName}</span>
+    }
+    render(
+      <StoryboardProvider flowName="other">
+        <FlowNameReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('name')).toHaveTextContent('other')
+  })
+
+  it('provides sceneName (backward compat) in context value', () => {
     function SceneNameReader() {
       const ctx = useContext(StoryboardContext)
       return <span data-testid="name">{ctx?.sceneName}</span>
     }
     render(
-      <StoryboardProvider sceneName="other">
+      <StoryboardProvider flowName="other">
         <SceneNameReader />
       </StoryboardProvider>,
     )
@@ -107,9 +129,9 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('loading')).toHaveTextContent('false')
   })
 
-  it('auto-matches scene by pathname and resolves $ref data', () => {
+  it('auto-matches flow by pathname and resolves $ref data', () => {
     init({
-      scenes: {
+      flows: {
         default: { title: 'Default' },
         Repositories: {
           '$global': ['navigation'],
@@ -133,9 +155,9 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('All repos')
   })
 
-  it('resolves $ref objects when auto-matching scene by pathname', () => {
+  it('resolves $ref objects when auto-matching flow by pathname', () => {
     init({
-      scenes: {
+      flows: {
         default: { title: 'Default' },
         Repositories: {
           '$global': ['navigation'],
@@ -165,7 +187,18 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('nav')).toHaveTextContent('Home,Repos')
   })
 
-  it('reads ?scene= param from location.search', () => {
+  it('reads ?flow= param from location.search', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('reads ?scene= as alias for ?flow=', () => {
     mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?scene=other', hash: '' })
 
     render(
@@ -175,4 +208,76 @@ describe('StoryboardProvider', () => {
     )
     expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
   })
+
+  it('prefers ?flow= over ?scene= when both present', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other&scene=default', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('loads prototype flow for sub-pages when no page-specific flow exists', () => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+        'Example/example': { title: 'Example Flow' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    // /Example/Forms — no Forms flow exists, should fall back to Example/example
+    mockUseLocation.mockReturnValue({ pathname: '/Example/Forms', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Example Flow')
+  })
+
+  it('page-specific flow takes priority over prototype flow', () => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+        'Example/example': { title: 'Example Flow' },
+        'Example/Forms': { title: 'Forms Flow' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    mockUseLocation.mockReturnValue({ pathname: '/Example/Forms', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Forms Flow')
+  })
+
+  it('falls to global default when no prototype flow exists', () => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    mockUseLocation.mockReturnValue({ pathname: '/NoProto/SomePage', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Global Default')
+  })
 })