@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/hooks/useSceneData.test.js

@@ -0,0 +1,136 @@
+import { renderHook } from '@testing-library/react'
+import { useFlowData, useFlowLoading, useSceneData, useSceneLoading } from './useSceneData.js'
+import { seedTestData, createWrapper, TEST_FLOWS } from '../test-utils.js'
+
+const flowData = TEST_FLOWS.default
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useFlowData', () => {
+  it('returns entire flow object when no path given', () => {
+    const { result } = renderHook(() => useFlowData(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toEqual(flowData)
+  })
+
+  it('returns nested value by dot-notation path', () => {
+    const { result } = renderHook(() => useFlowData('user.name'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toBe('Jane')
+  })
+
+  it('returns deep nested value', () => {
+    const { result } = renderHook(() => useFlowData('user.profile.bio'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toBe('Dev')
+  })
+
+  it('returns array by path', () => {
+    const { result } = renderHook(() => useFlowData('projects'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toEqual([
+      { id: 1, name: 'alpha' },
+      { id: 2, name: 'beta' },
+    ])
+  })
+
+  it('returns array element by index path', () => {
+    const { result } = renderHook(() => useFlowData('projects.0'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toEqual({ id: 1, name: 'alpha' })
+  })
+
+  it('returns empty object and warns for missing path', () => {
+    const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { result } = renderHook(() => useFlowData('nonexistent.path'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toEqual({})
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining('nonexistent.path')
+    )
+    spy.mockRestore()
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useFlowData())
+    }).toThrow('useFlowData must be used within a <StoryboardProvider>')
+  })
+
+  it('returns hash override value when param matches path', () => {
+    window.location.hash = '#user.name=Alice'
+    const { result } = renderHook(() => useFlowData('user.name'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toBe('Alice')
+  })
+
+  it('applies child overrides to arrays', () => {
+    window.location.hash = '#projects.0.name=gamma'
+    const { result } = renderHook(() => useFlowData('projects'), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current[0].name).toBe('gamma')
+    expect(result.current[1].name).toBe('beta')
+  })
+
+  it('returns full flow with all overrides applied when no path', () => {
+    window.location.hash = '#user.name=Alice'
+    const { result } = renderHook(() => useFlowData(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current.user.name).toBe('Alice')
+    expect(result.current.settings.theme).toBe('dark')
+  })
+})
+
+describe('useFlowLoading', () => {
+  it('returns false when not loading', () => {
+    const { result } = renderHook(() => useFlowLoading(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toBe(false)
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useFlowLoading())
+    }).toThrow('useFlowLoading must be used within a <StoryboardProvider>')
+  })
+})
+
+// ── Deprecated aliases ──
+
+describe('useSceneData (deprecated alias)', () => {
+  it('is the same function as useFlowData', () => {
+    expect(useSceneData).toBe(useFlowData)
+  })
+
+  it('returns flow data', () => {
+    const { result } = renderHook(() => useSceneData(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toEqual(flowData)
+  })
+})
+
+describe('useSceneLoading (deprecated alias)', () => {
+  it('is the same function as useFlowLoading', () => {
+    expect(useSceneLoading).toBe(useFlowLoading)
+  })
+
+  it('returns loading state', () => {
+    const { result } = renderHook(() => useSceneLoading(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toBe(false)
+  })
+})

package/src/internals/hooks/useSession.js

@@ -0,0 +1,4 @@
+/**
+ * @deprecated Use `useOverride` instead. This re-export exists for backwards compatibility.
+ */
+export { useOverride as useSession } from './useOverride.js'

package/src/internals/hooks/useSession.test.js

@@ -0,0 +1,8 @@
+import { useSession } from './useSession.js'
+import { useOverride } from './useOverride.js'
+
+describe('useSession', () => {
+  it('is the same function as useOverride', () => {
+    expect(useSession).toBe(useOverride)
+  })
+})

package/src/internals/hooks/useThemeState.js

@@ -0,0 +1,61 @@
+/**
+ * useThemeState — React hook for the global storyboard theme.
+ *
+ * Subscribes to the core themeStore via useSyncExternalStore so React
+ * components re-render whenever the theme changes (user action, system
+ * preference toggle, or sync-target change).
+ *
+ * Returns { theme, resolved } where `theme` may be "system" and
+ * `resolved` is always a concrete Primer theme name.
+ *
+ * useThemeSyncTargets — React hook for which UI surfaces follow the theme.
+ * Returns { prototype, toolbar, codeBoxes, canvas }.
+ */
+
+import { useSyncExternalStore } from 'react'
+import {
+  themeState,
+  themeSyncState,
+} from '../../core/index.js'
+
+// --- useThemeState ----------------------------------------------------------
+
+function subscribeTheme(cb) {
+  return themeState.subscribe(cb)
+}
+
+let _themeSnapshot = null
+themeState.subscribe((s) => { _themeSnapshot = s })
+
+function getThemeSnapshot() {
+  return _themeSnapshot
+}
+
+/**
+ * Subscribe to the global storyboard theme.
+ * @returns {{ theme: string, resolved: string }}
+ */
+export function useThemeState() {
+  return useSyncExternalStore(subscribeTheme, getThemeSnapshot, getThemeSnapshot)
+}
+
+// --- useThemeSyncTargets ----------------------------------------------------
+
+function subscribeSyncTargets(cb) {
+  return themeSyncState.subscribe(cb)
+}
+
+let _syncSnapshot = null
+themeSyncState.subscribe((s) => { _syncSnapshot = s })
+
+function getSyncSnapshot() {
+  return _syncSnapshot
+}
+
+/**
+ * Subscribe to which UI surfaces follow the global theme.
+ * @returns {{ prototype: boolean, toolbar: boolean, codeBoxes: boolean, canvas: boolean }}
+ */
+export function useThemeSyncTargets() {
+  return useSyncExternalStore(subscribeSyncTargets, getSyncSnapshot, getSyncSnapshot)
+}

package/src/internals/hooks/useThemeState.test.js

@@ -0,0 +1,66 @@
+import { renderHook, act } from '@testing-library/react'
+import { describe, it, expect, beforeEach } from 'vitest'
+import { setTheme, setThemeSyncTarget } from '../../core/index.js'
+import { useThemeState, useThemeSyncTargets } from './useThemeState.js'
+
+beforeEach(() => {
+  localStorage.clear()
+  // Reset to defaults
+  setTheme('system')
+})
+
+describe('useThemeState', () => {
+  it('returns { theme, resolved }', () => {
+    const { result } = renderHook(() => useThemeState())
+    expect(result.current).toHaveProperty('theme')
+    expect(result.current).toHaveProperty('resolved')
+  })
+
+  it('defaults to system theme', () => {
+    const { result } = renderHook(() => useThemeState())
+    expect(result.current.theme).toBe('system')
+    // resolved should be 'light' or 'dark' depending on matchMedia mock
+    expect(['light', 'dark']).toContain(result.current.resolved)
+  })
+
+  it('updates when setTheme is called', () => {
+    const { result } = renderHook(() => useThemeState())
+
+    act(() => {
+      setTheme('dark_dimmed')
+    })
+
+    expect(result.current.theme).toBe('dark_dimmed')
+    expect(result.current.resolved).toBe('dark_dimmed')
+  })
+
+  it('reverts to system when set back', () => {
+    const { result } = renderHook(() => useThemeState())
+
+    act(() => { setTheme('dark') })
+    expect(result.current.theme).toBe('dark')
+
+    act(() => { setTheme('system') })
+    expect(result.current.theme).toBe('system')
+  })
+})
+
+describe('useThemeSyncTargets', () => {
+  it('returns default sync targets', () => {
+    const { result } = renderHook(() => useThemeSyncTargets())
+    expect(result.current.prototype).toBe(true)
+    expect(result.current.toolbar).toBe(false)
+    expect(result.current.codeBoxes).toBe(true)
+    expect(result.current.canvas).toBe(true)
+  })
+
+  it('updates when setThemeSyncTarget is called', () => {
+    const { result } = renderHook(() => useThemeSyncTargets())
+
+    act(() => {
+      setThemeSyncTarget('toolbar', true)
+    })
+
+    expect(result.current.toolbar).toBe(true)
+  })
+})

package/src/internals/hooks/useUndoRedo.js

@@ -0,0 +1,28 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import { undo, redo, canUndo, canRedo } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+import { subscribeToHash, getHashSnapshot } from '../../core/index.js'
+
+/**
+ * Undo/redo controls for override history.
+ *
+ * Every override write (via useOverride) pushes a snapshot to the history
+ * stack. This hook exposes navigation through that stack.
+ *
+ * @returns {{ undo: function, redo: function, canUndo: boolean, canRedo: boolean }}
+ */
+export function useUndoRedo() {
+  // Re-render on storage or hash changes
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+  useSyncExternalStore(subscribeToHash, getHashSnapshot)
+
+  const handleUndo = useCallback(() => undo(), [])
+  const handleRedo = useCallback(() => redo(), [])
+
+  return {
+    undo: handleUndo,
+    redo: handleRedo,
+    canUndo: canUndo(),
+    canRedo: canRedo(),
+  }
+}

package/src/internals/hooks/useUndoRedo.test.js

@@ -0,0 +1,64 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData } from '../../test-utils.js'
+import { pushSnapshot } from '../../core/index.js'
+import { useUndoRedo } from './useUndoRedo.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useUndoRedo', () => {
+  it('returns { undo, redo, canUndo, canRedo }', () => {
+    const { result } = renderHook(() => useUndoRedo())
+    expect(typeof result.current.undo).toBe('function')
+    expect(typeof result.current.redo).toBe('function')
+    expect(typeof result.current.canUndo).toBe('boolean')
+    expect(typeof result.current.canRedo).toBe('boolean')
+  })
+
+  it('canUndo and canRedo are false initially', () => {
+    const { result } = renderHook(() => useUndoRedo())
+    expect(result.current.canUndo).toBe(false)
+    expect(result.current.canRedo).toBe(false)
+  })
+
+  it('after pushing snapshots and undoing, canUndo/canRedo reflect state', () => {
+    // Pre-populate history with 3 entries so we can undo twice
+    pushSnapshot('a=1', '/')
+    pushSnapshot('b=2', '/')
+    pushSnapshot('c=3', '/')
+
+    const { result, rerender } = renderHook(() => useUndoRedo())
+
+    // At index 2 (last entry), can undo but not redo
+    expect(result.current.canUndo).toBe(true)
+    expect(result.current.canRedo).toBe(false)
+
+    act(() => {
+      result.current.undo()
+    })
+
+    rerender()
+    // At index 1, can undo and redo
+    expect(result.current.canUndo).toBe(true)
+    expect(result.current.canRedo).toBe(true)
+
+    act(() => {
+      result.current.undo()
+    })
+
+    rerender()
+    // At index 0, cannot undo but can redo
+    expect(result.current.canUndo).toBe(false)
+    expect(result.current.canRedo).toBe(true)
+
+    act(() => {
+      result.current.redo()
+    })
+
+    rerender()
+    // At index 1 again, can undo and redo
+    expect(result.current.canUndo).toBe(true)
+    expect(result.current.canRedo).toBe(true)
+  })
+})

package/src/internals/index.js

@@ -0,0 +1,58 @@
+/**
+ * @dfosco/storyboard-react — React framework binding for Storyboard.
+ *
+ * Provides hooks, context, and provider for React apps.
+ * Design-system-agnostic — no Primer, Reshaped, or other UI library deps.
+ */
+
+// Context & Provider
+export { default as StoryboardProvider } from './context.jsx'
+export { StoryboardContext } from './StoryboardContext.js'
+
+// Hooks
+export { useFlowData, useFlowLoading } from './hooks/useSceneData.js'
+// Deprecated aliases
+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'
+export { useHideMode } from './hooks/useHideMode.js'
+export { useUndoRedo } from './hooks/useUndoRedo.js'
+export { useFeatureFlag } from './hooks/useFeatureFlag.js'
+export { useMode } from './hooks/useMode.js'
+export { useThemeState, useThemeSyncTargets } from './hooks/useThemeState.js'
+export { useConfig } from './hooks/useConfig.js'
+
+// React Router integration
+export { installHashPreserver } from './hashPreserver.js'
+
+// Form context (for design system packages to use)
+export { FormContext } from './context/FormContext.js'
+
+// Design mode hook (keep — React apps may still read mode state)
+
+
+// Workspace dashboard
+export { default as Workspace } from './Workspace.jsx'
+// Deprecated alias — use Workspace instead
+export { default as Viewfinder } from './Workspace.jsx'
+
+// Command Palette (includes BranchBar automatically)
+export { default as StoryboardCommandPalette } from './CommandPalette/CommandPalette.jsx'
+
+// Branch Bar (standalone, for consumers who don't use CommandPalette)
+export { default as BranchBar } from './BranchBar/BranchBar.jsx'
+
+// Auth Modal (standalone, for consumers who don't use CommandPalette)
+export { default as AuthModal } from './AuthModal/AuthModal.jsx'
+
+// Canvas
+export { default as CanvasPage } from './canvas/CanvasPage.jsx'
+export { useCanvas } from './canvas/useCanvas.js'
+
+// Icon
+export { default as Icon } from './Icon.jsx'

package/src/internals/story/ComponentSetPage.jsx

@@ -0,0 +1,198 @@
+/**
+ * ComponentSetPage — renders all exports from a .story.jsx in a grid.
+ *
+ * Mounted when StoryPage detects `?_sb_component_set` in the URL.
+ * Each export gets its own grid cell with a selectable label header.
+ *
+ * URL params:
+ *   layout   — "horizontal" (default) | "vertical"
+ *   selected — export name of the currently selected cell
+ *
+ * Selection: clicking a cell label updates `?selected=` and posts
+ * `storyboard:component-set:select` to the parent window so the
+ * canvas widget can track which export the user picked.
+ */
+import { useState, useEffect, useLayoutEffect, useMemo, useCallback, useRef } from 'react'
+import { useLocation, useNavigate } from 'react-router-dom'
+import { getStoryData } from '../../core/index.js'
+import { ThemeProvider, BaseStyles } from '@primer/react'
+import styles from './ComponentSetPage.module.css'
+
+export default function ComponentSetPage({ name }) {
+  const location = useLocation()
+  const navigate = useNavigate()
+  const searchParams = new URLSearchParams(location.search)
+
+  const layout = searchParams.get('layout') || 'horizontal'
+  const selected = searchParams.get('selected') || ''
+  const isEmbed = searchParams.has('_sb_embed')
+
+  // Suppress HMR full-reloads when embedded as a canvas iframe
+  useEffect(() => {
+    if (!isEmbed || !import.meta.hot) return
+    const msg = { active: true }
+    import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    const interval = setInterval(() => {
+      import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
+    }, 3000)
+    return () => {
+      clearInterval(interval)
+      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
+    }
+  }, [isEmbed])
+
+  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 grid renders in embed mode
+  useEffect(() => {
+    if (!isEmbed || !exports || window.parent === window) return
+    document.fonts.ready.then(() => {
+      requestAnimationFrame(() => requestAnimationFrame(() => {
+        window.__sbSnapshotReady?.()
+      }))
+    })
+  }, [isEmbed, exports])
+
+  const gridRef = useRef(null)
+
+  // Measure all cell content elements and snap cells to the largest.
+  // Posts the total grid size to the parent widget so it can auto-size.
+  useLayoutEffect(() => {
+    const grid = gridRef.current
+    if (!grid || !exports) return
+
+    const cells = grid.querySelectorAll('[data-cell-content]')
+    if (cells.length === 0) return
+
+    function measure() {
+      let maxW = 0
+      let maxH = 0
+      for (const el of cells) {
+        maxW = Math.max(maxW, el.scrollWidth)
+        maxH = Math.max(maxH, el.scrollHeight)
+      }
+      grid.style.setProperty('--cell-snap-w', `${maxW}px`)
+      grid.style.setProperty('--cell-snap-h', `${maxH}px`)
+
+      // Post total grid size to parent widget
+      if (isEmbed && window.parent !== window) {
+        requestAnimationFrame(() => {
+          window.parent.postMessage({
+            type: 'storyboard:component-set:resize',
+            width: grid.scrollWidth,
+            height: grid.scrollHeight,
+          }, '*')
+        })
+      }
+    }
+
+    // Measure after fonts load and initial paint
+    measure()
+    document.fonts.ready.then(() => requestAnimationFrame(measure))
+
+    const ro = new ResizeObserver(measure)
+    for (const el of cells) ro.observe(el)
+    return () => ro.disconnect()
+  }, [exports, layout, isEmbed])
+
+  const handleSelect = useCallback((exportName) => {
+    const params = new URLSearchParams(location.search)
+    if (exportName === params.get('selected')) {
+      params.delete('selected')
+    } else {
+      params.set('selected', exportName)
+    }
+    navigate(`${location.pathname}?${params}`, { replace: true })
+
+    // Notify parent widget
+    if (window.parent !== window) {
+      window.parent.postMessage({
+        type: 'storyboard:component-set:select',
+        storyId: name,
+        exportName: exportName === selected ? null : exportName,
+      }, '*')
+    }
+  }, [location, navigate, name, selected])
+
+  if (error) {
+    return (
+      <div className={styles.error}>
+        <strong>Component Set Error</strong>
+        <span>{error}</span>
+      </div>
+    )
+  }
+
+  if (!exports) {
+    if (isEmbed) return null
+    return <div className={styles.loading}>Loading component set…</div>
+  }
+
+  const exportNames = Object.keys(exports)
+
+  return (
+    <ThemeProvider colorMode="day">
+      <BaseStyles>
+        <div
+          ref={gridRef}
+          className={styles.grid}
+          data-layout={layout}
+        >
+          {exportNames.map((exportName) => {
+            const Component = exports[exportName]
+            const isSelected = exportName === selected
+            return (
+              <div
+                key={exportName}
+                className={styles.cell}
+                data-selected={isSelected || undefined}
+              >
+                <button
+                  className={styles.cellLabel}
+                  onClick={() => handleSelect(exportName)}
+                  data-selected={isSelected || undefined}
+                  aria-pressed={isSelected}
+                >
+                  <span className={styles.cellRadio} data-selected={isSelected || undefined} />
+                  <span className={styles.cellName}>{exportName}</span>
+                </button>
+                <div className={styles.cellContent} data-cell-content>
+                  <Component />
+                </div>
+              </div>
+            )
+          })}
+        </div>
+      </BaseStyles>
+    </ThemeProvider>
+  )
+}