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

package/src/context.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, Suspense, lazy } from 'react'
 import { useParams, useLocation } from 'react-router-dom'
-// Named import seeds the core data index via init() AND provides canvas route data
-import { canvases } from 'virtual:storyboard-data-index'
+// Named import seeds the core data index via init() AND provides canvas/story route data
+import { canvases, canvasAliases, stories } from 'virtual:storyboard-data-index'
 import { loadFlow, flowExists, findRecord, deepMerge, setFlowClass, installBodyClassSync, resolveFlowName, resolveRecordName, isModesEnabled } from '@dfosco/storyboard-core'
 import { StoryboardContext } from './StoryboardContext.js'
 import styles from './FlowError.module.css'
@@ -9,24 +9,77 @@ import styles from './FlowError.module.css'
 export { StoryboardContext }
 
 const CanvasPageLazy = lazy(() => import('./canvas/CanvasPage.jsx'))
+const StoryPageLazy = lazy(() => import('./story/StoryPage.jsx'))
 
 // Build a map from canvas route paths → canvas names at module load time
 const canvasRouteMap = new Map()
+// Build a map from group name → array of { name, route, title } for page selector
+const canvasGroupMap = new Map()
 for (const [name, data] of Object.entries(canvases || {})) {
-  const route = (data?._route || `/${name}`).replace(/\/+$/, '')
+  const route = (data?._route || `/canvas/${name}`).replace(/\/+$/, '')
   canvasRouteMap.set(route, name)
+  const group = data?._group
+  if (group) {
+    if (!canvasGroupMap.has(group)) canvasGroupMap.set(group, [])
+    canvasGroupMap.get(group).push({
+      name,
+      route,
+      title: data?.title || name.split('/').pop(),
+      _canvasMeta: data?._canvasMeta || null,
+    })
+  }
+}
+
+// Build a map from story route paths → story names at module load time
+const storyRouteMap = new Map()
+for (const [name, data] of Object.entries(stories || {})) {
+  if (data?._route) {
+    const route = data._route.replace(/\/+$/, '')
+    storyRouteMap.set(route, name)
+  }
 }
 
 function matchCanvasRoute(pathname) {
-  const normalized = pathname.replace(/\/+$/, '') || '/'
+  const normalized = stripBasePath(pathname)
   return canvasRouteMap.get(normalized) || null
 }
 
+function matchStoryRoute(pathname) {
+  const normalized = stripBasePath(pathname)
+  return storyRouteMap.get(normalized) || null
+}
+
+/**
+ * Strip the app's sub-path prefix (e.g. /storyboard) from the pathname.
+ * React Router's basename strips the branch prefix but not the app name prefix
+ * when the app runs under a nested base path.
+ */
+function stripBasePath(pathname) {
+  let p = pathname.replace(/\/+$/, '') || '/'
+  // BASE_URL includes branch prefix + app path (e.g. /branch--name/storyboard/)
+  // React Router strips the branch prefix but may leave the app sub-path
+  const base = (import.meta.env?.BASE_URL || '/').replace(/\/+$/, '')
+  if (base && base !== '/') {
+    // Extract just the last segment(s) after the branch prefix
+    const withoutBranch = base.replace(/^\/branch--[^/]+/, '')
+    const subPath = withoutBranch.replace(/\/+$/, '')
+    if (subPath && p.startsWith(subPath)) {
+      p = p.slice(subPath.length) || '/'
+    }
+  }
+  return p
+}
+
 function isCanvasPath(pathname) {
-  const normalized = pathname.replace(/\/+$/, '') || '/'
+  const normalized = stripBasePath(pathname)
   return normalized === '/canvas' || normalized.startsWith('/canvas/')
 }
 
+function isStoryPath(pathname) {
+  const normalized = stripBasePath(pathname)
+  return normalized === '/components' || normalized.startsWith('/components/')
+}
+
 /**
  * Derives the top-level prototype name from a pathname.
  * "/Dashboard" → "Dashboard", "/Dashboard/sub" → "Dashboard"
@@ -68,18 +121,25 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
   // Canvas route detection — matches current URL against registered canvas routes
   const canvasName = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
   const isMissingCanvasRoute = useMemo(
-    () => isCanvasPath(location.pathname) && !canvasName,
+    () => isCanvasPath(location.pathname) && !canvasName && !matchStoryRoute(location.pathname),
     [location.pathname, canvasName],
   )
 
+  // Story route detection — matches current URL against registered story routes
+  const storyName = useMemo(() => matchStoryRoute(location.pathname), [location.pathname])
+  const isMissingStoryRoute = useMemo(
+    () => isStoryPath(location.pathname) && !storyName,
+    [location.pathname, storyName],
+  )
+
   const searchParams = new URLSearchParams(location.search)
   const sceneParam = searchParams.get('flow') || searchParams.get('scene')
   const prototypeName = getPrototypeName(location.pathname)
   const pageFlow = getPageFlowName(location.pathname)
 
-  // Resolve flow name with prototype scoping (skip for canvas pages)
+  // Resolve flow name with prototype scoping (skip for canvas/story pages)
   const activeFlowName = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute) return null
+    if (canvasName || isMissingCanvasRoute || storyName || isMissingStoryRoute) return null
     const requested = sceneParam || flowName || sceneName
     if (requested) {
       // Allow fully-scoped flow names from URLs/widgets without re-prefixing
@@ -103,11 +163,32 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     // 4. Global default — or null if no flow exists at all
     if (flowExists('default')) return 'default'
     return null
-  }, [canvasName, isMissingCanvasRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
+  }, [canvasName, isMissingCanvasRoute, storyName, isMissingStoryRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
 
   // Auto-install body class sync (sb-key--value classes on <body>)
   useEffect(() => installBodyClassSync(), [])
 
+  // Update document.title to reflect the current artifact
+  useEffect(() => {
+    const base = import.meta.env?.BASE_URL || '/'
+    const branchMatch = base.match(/\/branch--([^/]+)/)
+    const branchSuffix = branchMatch ? ` (${branchMatch[1]})` : ''
+
+    let title
+    if (canvasName) {
+      const canvasData = canvases?.[canvasName]
+      const meta = canvasData?._canvasMeta
+      const pageTitle = canvasData?.title || canvasName.split('/').pop()
+      title = (meta?.title || pageTitle) + ' · Storyboard'
+    } else if (prototypeName) {
+      title = prototypeName + ' · Storyboard'
+    } else {
+      title = 'Storyboard'
+    }
+
+    document.title = title + branchSuffix
+  }, [canvasName, prototypeName])
+
   // Mount design modes UI when enabled in storyboard.config.json
   useEffect(() => {
     if (!isModesEnabled()) return
@@ -124,9 +205,9 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     return () => cleanup?.()
   }, [])
 
-  // Skip flow loading for canvas pages and flow-less pages
+  // Skip flow loading for canvas/story pages and flow-less pages
   const { data, error } = useMemo(() => {
-    if (canvasName || isMissingCanvasRoute) return { data: null, error: null }
+    if (canvasName || isMissingCanvasRoute || storyName || isMissingStoryRoute) return { data: null, error: null }
     if (!activeFlowName) return { data: {}, error: null }
     try {
       let flowData = loadFlow(activeFlowName)
@@ -145,10 +226,14 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     } catch (err) {
       return { data: null, error: err.message }
     }
-  }, [canvasName, isMissingCanvasRoute, activeFlowName, recordName, recordParam, params, prototypeName])
+  }, [canvasName, isMissingCanvasRoute, storyName, isMissingStoryRoute, activeFlowName, recordName, recordParam, params, prototypeName])
 
   // Canvas pages get their own rendering path — no flow data needed
   if (canvasName) {
+    const canvasData = canvases?.[canvasName]
+    const group = canvasData?._group
+    const siblingPages = group ? canvasGroupMap.get(group) || [] : []
+    const canvasMeta = canvasData?._canvasMeta || null
     const canvasValue = {
       data: null,
       error: null,
@@ -160,7 +245,26 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     return (
       <StoryboardContext.Provider value={canvasValue}>
         <Suspense fallback={null}>
-          <CanvasPageLazy name={canvasName} />
+          <CanvasPageLazy name={canvasName} siblingPages={siblingPages} canvasMeta={canvasMeta} />
+        </Suspense>
+      </StoryboardContext.Provider>
+    )
+  }
+
+  // Story pages get their own rendering path — no flow data needed
+  if (storyName) {
+    const storyValue = {
+      data: null,
+      error: null,
+      loading: false,
+      flowName: null,
+      sceneName: null,
+      prototypeName: null,
+    }
+    return (
+      <StoryboardContext.Provider value={storyValue}>
+        <Suspense fallback={null}>
+          <StoryPageLazy name={storyName} />
         </Suspense>
       </StoryboardContext.Provider>
     )
@@ -187,6 +291,27 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     )
   }
 
+  if (isMissingStoryRoute) {
+    const currentUrl = `${location.pathname}${location.search}`
+    const truncatedUrl = currentUrl.length > 60
+      ? currentUrl.slice(0, 60) + '…'
+      : currentUrl
+
+    return (
+      <main className={styles.container}>
+        <div className={styles.banner}>
+          <strong>Story not found</strong>
+          No story matches this route.
+        </div>
+        <p className={styles.meta}>
+          Tried to open{' '}
+          <a href={currentUrl} title={currentUrl}>{truncatedUrl}</a>
+        </p>
+        <a className={styles.homeLink} href="/">← Go to index page</a>
+      </main>
+    )
+  }
+
   const value = {
     data,
     error,

package/src/hooks/useSceneData.js

@@ -17,10 +17,12 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  *
  * @param {string} [path] - Dot-notation path (e.g. 'user.profile.name').
  *                          Omit to get the entire flow object.
+ * @param {{ optional?: boolean }} [opts] - Pass { optional: true } to suppress
+ *                          the "path not found" warning for optional data.
  * @returns {*} The resolved value. Returns {} if path is missing after loading.
  * @throws If used outside a StoryboardProvider.
  */
-export function useFlowData(path) {
+export function useFlowData(path, opts) {
   const context = useContext(StoryboardContext)
 
   if (context === null) {
@@ -73,7 +75,7 @@ export function useFlowData(path) {
     }
 
     if (sceneValue === undefined) {
-      if (data != null && Object.keys(data).length > 0) {
+      if (!opts?.optional && data != null && Object.keys(data).length > 0) {
         console.warn(`[useFlowData] Path "${path}" not found in flow data.`)
       }
       return {}

package/src/story/StoryPage.jsx

@@ -0,0 +1,152 @@
+/**
+ * StoryPage — renders a .story.jsx module at its own route.
+ *
+ * When visited at e.g. /canvas/button-patterns, renders all named exports
+ * from button-patterns.story.jsx in a gallery layout.
+ *
+ * When ?export=ExportName is present, renders only that single export
+ * (used by iframe embeds from canvas StoryWidget).
+ */
+import { useState, useEffect, useMemo } from 'react'
+import { useLocation } from 'react-router-dom'
+import { getStoryData } from '@dfosco/storyboard-core'
+import { ThemeProvider, BaseStyles } from '@primer/react'
+import styles from './StoryPage.module.css'
+
+function StoryErrorBoundaryFallback({ name, error }) {
+  return (
+    <div className={styles.error}>
+      <strong>{name}</strong>
+      <span>{String(error?.message || error)}</span>
+    </div>
+  )
+}
+
+export default function StoryPage({ name }) {
+  const location = useLocation()
+  const searchParams = new URLSearchParams(location.search)
+  const exportFilter = searchParams.get('export')
+  const isEmbed = searchParams.has('_sb_embed')
+
+  const story = useMemo(() => getStoryData(name), [name])
+  const [exports, setExports] = useState(null)
+  const [error, setError] = useState(null)
+
+  useEffect(() => {
+    if (!story?._storyImport) {
+      Promise.resolve().then(() => setError(`Story "${name}" not found or missing import`))
+      return
+    }
+
+    let cancelled = false
+    story._storyImport()
+      .then((mod) => {
+        if (cancelled) return
+        const namedExports = {}
+        for (const [key, value] of Object.entries(mod)) {
+          if (key !== 'default' && typeof value === 'function') {
+            namedExports[key] = value
+          }
+        }
+        setExports(namedExports)
+        setError(null)
+      })
+      .catch((err) => {
+        if (cancelled) return
+        setError(`Failed to load story "${name}": ${err.message || err}`)
+      })
+
+    return () => { cancelled = true }
+  }, [name, story])
+
+  // Signal snapshot-ready after story renders in embed mode
+  useEffect(() => {
+    if (!isEmbed || !exports || window.parent === window) return
+    // Wait for fonts + paint to settle before signaling ready
+    Promise.all([
+      document.fonts?.ready || Promise.resolve(),
+      new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r))),
+    ]).then(() => {
+      window.parent.postMessage({ type: 'storyboard:embed:snapshot-ready' }, '*')
+    })
+  }, [isEmbed, exports])
+
+  if (error) {
+    return (
+      <div className={styles.page}>
+        <StoryErrorBoundaryFallback name={name} error={error} />
+      </div>
+    )
+  }
+
+  if (!exports) {
+    return (
+      <div className={styles.page}>
+        <div className={styles.loading}>Loading story…</div>
+      </div>
+    )
+  }
+
+  // Single export mode (for iframe embedding)
+  if (exportFilter) {
+    const Component = exports[exportFilter]
+    if (!Component) {
+      return (
+        <div className={styles.page}>
+          <StoryErrorBoundaryFallback
+            name={`${name}/${exportFilter}`}
+            error={`Export "${exportFilter}" not found in story "${name}"`}
+          />
+        </div>
+      )
+    }
+
+    // Minimal wrapper for embed mode
+    if (isEmbed) {
+      return (
+        <ThemeProvider colorMode="day">
+          <BaseStyles>
+            <Component />
+          </BaseStyles>
+        </ThemeProvider>
+      )
+    }
+
+    return (
+      <div className={styles.page}>
+        <header className={styles.header}>
+          <h1 className={styles.title}>{name}</h1>
+          <span className={styles.exportBadge}>{exportFilter}</span>
+        </header>
+        <section className={styles.storySection}>
+          <Component />
+        </section>
+      </div>
+    )
+  }
+
+  // Gallery mode — render all exports
+  const exportNames = Object.keys(exports)
+
+  return (
+    <div className={styles.page}>
+      {!isEmbed && (
+        <header className={styles.header}>
+          <h1 className={styles.title}>{name}</h1>
+          <span className={styles.count}>{exportNames.length} {exportNames.length === 1 ? 'export' : 'exports'}</span>
+        </header>
+      )}
+      {exportNames.map((exportName) => {
+        const Component = exports[exportName]
+        return (
+          <section key={exportName} className={styles.storySection}>
+            {!isEmbed && <h2 className={styles.exportName}>{exportName}</h2>}
+            <div className={styles.storyContent}>
+              <Component />
+            </div>
+          </section>
+        )
+      })}
+    </div>
+  )
+}

package/src/story/StoryPage.module.css

@@ -0,0 +1,73 @@
+.page {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 2rem;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+.header {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  margin-bottom: 2rem;
+  padding-bottom: 1rem;
+  border-bottom: 1px solid var(--borderColor-muted, #d0d7de);
+}
+
+.title {
+  font-size: 1.5rem;
+  font-weight: 600;
+  margin: 0;
+  color: var(--fgColor-default, #1f2328);
+}
+
+.exportBadge {
+  font-size: 0.875rem;
+  font-weight: 500;
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--bgColor-accent-muted, #ddf4ff);
+  color: var(--fgColor-accent, #0969da);
+}
+
+.count {
+  font-size: 0.875rem;
+  color: var(--fgColor-muted, #656d76);
+}
+
+.storySection {
+  margin-bottom: 2rem;
+}
+
+.exportName {
+  font-size: 1rem;
+  font-weight: 500;
+  margin: 0 0 0.75rem;
+  color: var(--fgColor-default, #1f2328);
+}
+
+.storyContent {
+  border: 1px solid var(--borderColor-muted, #d0d7de);
+  border-radius: 8px;
+  padding: 1.5rem;
+  background: var(--bgColor-default, #ffffff);
+}
+
+.loading {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 3rem;
+  color: var(--fgColor-muted, #656d76);
+  font-size: 0.875rem;
+}
+
+.error {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 1rem;
+  color: var(--fgColor-danger, #cf222e);
+  font-size: 0.875rem;
+  line-height: 1.5;
+}