@dfosco/storyboard-react 1.1.0

package/src/hooks/useSceneData.test.js

@@ -0,0 +1,108 @@
+import { renderHook } from '@testing-library/react'
+import { useSceneData, useSceneLoading } from './useSceneData.js'
+import { seedTestData, createWrapper, TEST_SCENES } from '../test-utils.js'
+
+const sceneData = TEST_SCENES.default
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useSceneData', () => {
+  it('returns entire scene object when no path given', () => {
+    const { result } = renderHook(() => useSceneData(), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toEqual(sceneData)
+  })
+
+  it('returns nested value by dot-notation path', () => {
+    const { result } = renderHook(() => useSceneData('user.name'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toBe('Jane')
+  })
+
+  it('returns deep nested value', () => {
+    const { result } = renderHook(() => useSceneData('user.profile.bio'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toBe('Dev')
+  })
+
+  it('returns array by path', () => {
+    const { result } = renderHook(() => useSceneData('projects'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toEqual([
+      { id: 1, name: 'alpha' },
+      { id: 2, name: 'beta' },
+    ])
+  })
+
+  it('returns array element by index path', () => {
+    const { result } = renderHook(() => useSceneData('projects.0'), {
+      wrapper: createWrapper(sceneData),
+    })
+    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(() => useSceneData('nonexistent.path'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toEqual({})
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining('nonexistent.path')
+    )
+    spy.mockRestore()
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useSceneData())
+    }).toThrow('useSceneData must be used within a <StoryboardProvider>')
+  })
+
+  it('returns hash override value when param matches path', () => {
+    window.location.hash = '#user.name=Alice'
+    const { result } = renderHook(() => useSceneData('user.name'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toBe('Alice')
+  })
+
+  it('applies child overrides to arrays', () => {
+    window.location.hash = '#projects.0.name=gamma'
+    const { result } = renderHook(() => useSceneData('projects'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current[0].name).toBe('gamma')
+    expect(result.current[1].name).toBe('beta')
+  })
+
+  it('returns full scene with all overrides applied when no path', () => {
+    window.location.hash = '#user.name=Alice'
+    const { result } = renderHook(() => useSceneData(), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current.user.name).toBe('Alice')
+    expect(result.current.settings.theme).toBe('dark')
+  })
+})
+
+describe('useSceneLoading', () => {
+  it('returns false when not loading', () => {
+    const { result } = renderHook(() => useSceneLoading(), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toBe(false)
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useSceneLoading())
+    }).toThrow('useSceneLoading must be used within a <StoryboardProvider>')
+  })
+})

package/src/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/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/hooks/useUndoRedo.js

@@ -0,0 +1,28 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import { undo, redo, canUndo, canRedo } from '@dfosco/storyboard-core'
+import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * 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/hooks/useUndoRedo.test.js

@@ -0,0 +1,64 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData } from '../../test-utils.js'
+import { pushSnapshot } from '@dfosco/storyboard-core'
+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/index.js

@@ -0,0 +1,27 @@
+/**
+ * @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 { useSceneData, useSceneLoading } from './hooks/useSceneData.js'
+export { useOverride } from './hooks/useOverride.js'
+export { useOverride as useSession } from './hooks/useOverride.js' // deprecated alias
+export { useScene } from './hooks/useScene.js'
+export { useRecord, useRecords } from './hooks/useRecord.js'
+export { useRecordOverride } from './hooks/useRecordOverride.js'
+export { useLocalStorage } from './hooks/useLocalStorage.js'
+export { useHideMode } from './hooks/useHideMode.js'
+export { useUndoRedo } from './hooks/useUndoRedo.js'
+
+// React Router integration
+export { installHashPreserver } from './hashPreserver.js'
+
+// Form context (for design system packages to use)
+export { FormContext } from './context/FormContext.js'

package/src/test-utils.js

@@ -0,0 +1,42 @@
+import { createElement } from 'react'
+import { StoryboardContext } from './StoryboardContext.js'
+import { init } from '@dfosco/storyboard-core'
+
+// Default test data
+export const TEST_SCENES = {
+  default: {
+    user: { name: 'Jane', profile: { bio: 'Dev' } },
+    settings: { theme: 'dark' },
+    projects: [{ id: 1, name: 'alpha' }, { id: 2, name: 'beta' }],
+  },
+  other: {
+    user: { name: 'Bob' },
+    settings: { theme: 'light' },
+  },
+}
+
+export const TEST_OBJECTS = {
+  'jane-doe': { name: 'Jane Doe', role: 'admin' },
+}
+
+export const TEST_RECORDS = {
+  posts: [
+    { id: 'post-1', title: 'First Post', author: 'Jane' },
+    { id: 'post-2', title: 'Second Post', author: 'Bob' },
+  ],
+}
+
+export function seedTestData() {
+  init({ scenes: TEST_SCENES, objects: TEST_OBJECTS, records: TEST_RECORDS })
+}
+
+// Wrapper that provides StoryboardContext with given scene data
+export function createWrapper(sceneData, sceneName = 'default') {
+  return function Wrapper({ children }) {
+    return createElement(
+      StoryboardContext.Provider,
+      { value: { data: sceneData, error: null, loading: false, sceneName } },
+      children
+    )
+  }
+}

package/src/vite/data-plugin.js

@@ -0,0 +1,151 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { globSync } from 'glob'
+import { parse as parseJsonc } from 'jsonc-parser'
+
+const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
+const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
+
+const SUFFIXES = ['scene', 'object', 'record']
+const GLOB_PATTERN = '**/*.{scene,object,record}.{json,jsonc}'
+
+/**
+ * Extract the data name and type suffix from a file path.
+ * e.g. "src/data/default.scene.json" → { name: "default", suffix: "scene" }
+ *      "anywhere/posts.record.jsonc" → { name: "posts", suffix: "record" }
+ */
+function parseDataFile(filePath) {
+  const base = path.basename(filePath)
+  const match = base.match(/^(.+)\.(scene|object|record)\.(jsonc?)$/)
+  if (!match) return null
+  return { name: match[1], suffix: match[2], ext: match[3] }
+}
+
+/**
+ * Scan the repo for all data files, validate uniqueness, return the index.
+ */
+function buildIndex(root) {
+  const ignore = ['node_modules/**', 'dist/**', '.git/**']
+  const files = globSync(GLOB_PATTERN, { cwd: root, ignore, absolute: false })
+
+  const index = { scene: {}, object: {}, record: {} }
+  const seen = {} // "name.suffix" → absolute path (for duplicate detection)
+
+  for (const relPath of files) {
+    const parsed = parseDataFile(relPath)
+    if (!parsed) continue
+
+    const key = `${parsed.name}.${parsed.suffix}`
+    const absPath = path.resolve(root, relPath)
+
+    if (seen[key]) {
+      throw new Error(
+        `[storyboard-data] Duplicate data file: "${key}.json"\n` +
+        `  Found at: ${seen[key]}\n` +
+        `  And at:   ${absPath}\n` +
+        `  Every data file name+suffix must be unique across the repo.`
+      )
+    }
+
+    seen[key] = absPath
+    index[parsed.suffix][parsed.name] = absPath
+  }
+
+  return index
+}
+
+/**
+ * Generate the virtual module source code.
+ * Reads each data file, parses JSONC at build time, and emits pre-parsed
+ * JavaScript objects — no runtime parsing needed.
+ */
+function generateModule(index) {
+  const declarations = []
+  const entries = { scene: [], object: [], record: [] }
+  let i = 0
+
+  for (const suffix of SUFFIXES) {
+    for (const [name, absPath] of Object.entries(index[suffix])) {
+      const varName = `_d${i++}`
+      const raw = fs.readFileSync(absPath, 'utf-8')
+      const parsed = parseJsonc(raw)
+      declarations.push(`const ${varName} = ${JSON.stringify(parsed)}`)
+      entries[suffix].push(`  ${JSON.stringify(name)}: ${varName}`)
+    }
+  }
+
+  return [
+    `import { init } from '@dfosco/storyboard-core'`,
+    '',
+    declarations.join('\n'),
+    '',
+    `const scenes = {\n${entries.scene.join(',\n')}\n}`,
+    `const objects = {\n${entries.object.join(',\n')}\n}`,
+    `const records = {\n${entries.record.join(',\n')}\n}`,
+    '',
+    `init({ scenes, objects, records })`,
+    '',
+    `export { scenes, objects, records }`,
+    `export const index = { scenes, objects, records }`,
+    `export default index`,
+  ].join('\n')
+}
+
+/**
+ * Vite plugin for storyboard data discovery.
+ *
+ * - Scans the repo for *.scene.json, *.object.json, *.record.json
+ * - 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
+ */
+export default function storyboardDataPlugin() {
+  let root = ''
+  let index = null
+
+  return {
+    name: 'storyboard-data',
+    enforce: 'pre',
+
+    configResolved(config) {
+      root = config.root
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) return RESOLVED_ID
+    },
+
+    load(id) {
+      if (id !== RESOLVED_ID) return null
+      if (!index) index = buildIndex(root)
+      return generateModule(index)
+    },
+
+    configureServer(server) {
+      // Watch for data file changes in dev mode
+      const dataGlob = GLOB_PATTERN
+      const watcher = server.watcher
+
+      const invalidate = (filePath) => {
+        const parsed = parseDataFile(filePath)
+        if (!parsed) return
+        // Rebuild index and invalidate virtual module
+        index = null
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID)
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod)
+          server.ws.send({ type: 'full-reload' })
+        }
+      }
+
+      watcher.on('add', invalidate)
+      watcher.on('unlink', invalidate)
+      watcher.on('change', invalidate)
+    },
+
+    // Rebuild index on each build start
+    buildStart() {
+      index = null
+    },
+  }
+}

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

@@ -0,0 +1,127 @@
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import storyboardDataPlugin from './data-plugin.js'
+
+const RESOLVED_ID = '\0virtual:storyboard-data-index'
+
+let tmpDir
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(path.join(tmpdir(), 'sb-test-'))
+})
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+function createPlugin(root) {
+  const plugin = storyboardDataPlugin()
+  plugin.configResolved({ root: root ?? tmpDir })
+  return plugin
+}
+
+function writeDataFiles(dir) {
+  writeFileSync(
+    path.join(dir, 'default.scene.json'),
+    JSON.stringify({ title: 'Test' }),
+  )
+  writeFileSync(
+    path.join(dir, 'user.object.json'),
+    JSON.stringify({ name: 'Jane' }),
+  )
+  writeFileSync(
+    path.join(dir, 'posts.record.json'),
+    JSON.stringify([{ id: '1', title: 'First' }]),
+  )
+}
+
+describe('storyboardDataPlugin', () => {
+  it("has name 'storyboard-data'", () => {
+    const plugin = storyboardDataPlugin()
+    expect(plugin.name).toBe('storyboard-data')
+  })
+
+  it("has enforce 'pre'", () => {
+    const plugin = storyboardDataPlugin()
+    expect(plugin.enforce).toBe('pre')
+  })
+
+  it("resolveId returns resolved ID for 'virtual:storyboard-data-index'", () => {
+    const plugin = createPlugin()
+    expect(plugin.resolveId('virtual:storyboard-data-index')).toBe(RESOLVED_ID)
+  })
+
+  it('resolveId returns undefined for other IDs', () => {
+    const plugin = createPlugin()
+    expect(plugin.resolveId('some-other-module')).toBeUndefined()
+  })
+
+  it('load generates valid module code with init() call', () => {
+    writeDataFiles(tmpDir)
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain("import { init } from '@dfosco/storyboard-core'")
+    expect(code).toContain('init({ scenes, objects, records })')
+    expect(code).toContain('"Test"')
+    expect(code).toContain('"Jane"')
+    expect(code).toContain('"First"')
+  })
+
+  it('load returns null for other IDs', () => {
+    const plugin = createPlugin()
+    expect(plugin.load('other-id')).toBeNull()
+  })
+
+  it('duplicate data files throw an error', () => {
+    writeFileSync(
+      path.join(tmpDir, 'dup.scene.json'),
+      JSON.stringify({ a: 1 }),
+    )
+    const subDir = path.join(tmpDir, 'nested')
+    mkdirSync(subDir, { recursive: true })
+    writeFileSync(
+      path.join(subDir, 'dup.scene.json'),
+      JSON.stringify({ a: 2 }),
+    )
+
+    const plugin = createPlugin()
+    expect(() => plugin.load(RESOLVED_ID)).toThrow(/Duplicate data file/)
+  })
+
+  it('handles JSONC files (with comments)', () => {
+    writeFileSync(
+      path.join(tmpDir, 'commented.scene.jsonc'),
+      '{\n  // This is a comment\n  "title": "JSONC Scene"\n}\n',
+    )
+    const plugin = createPlugin()
+    const code = plugin.load(RESOLVED_ID)
+
+    expect(code).toContain('"JSONC Scene"')
+  })
+
+  it('buildStart resets the index cache', () => {
+    writeDataFiles(tmpDir)
+    const plugin = createPlugin()
+
+    // First load builds the index
+    const code1 = plugin.load(RESOLVED_ID)
+    expect(code1).toContain('"Test"')
+
+    // Add a new file
+    writeFileSync(
+      path.join(tmpDir, 'extra.scene.json'),
+      JSON.stringify({ title: 'Extra' }),
+    )
+
+    // Without buildStart, cached index is used — "Extra" won't appear
+    const code2 = plugin.load(RESOLVED_ID)
+    expect(code2).not.toContain('"Extra"')
+
+    // After buildStart, index is rebuilt
+    plugin.buildStart()
+    const code3 = plugin.load(RESOLVED_ID)
+    expect(code3).toContain('"Extra"')
+  })
+})