@dfosco/storyboard-react 1.24.0 → 2.0.0-beta.1

package/src/hooks/useRecord.js

@@ -1,11 +1,12 @@
-import { useMemo, useSyncExternalStore } from 'react'
+import { useContext, useMemo, useSyncExternalStore } from 'react'
 import { useParams } from 'react-router-dom'
-import { loadRecord } from '@dfosco/storyboard-core'
+import { loadRecord, resolveRecordName } from '@dfosco/storyboard-core'
 import { deepClone, setByPath } from '@dfosco/storyboard-core'
 import { getAllParams } from '@dfosco/storyboard-core'
 import { isHideMode, getAllShadows } from '@dfosco/storyboard-core'
 import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
 import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+import { StoryboardContext } from '../StoryboardContext.js'
 
 /**
  * Collect overrides for a record and merge them into the base array.
@@ -91,6 +92,8 @@ function applyRecordOverrides(baseRecords, recordName) {
 export function useRecord(recordName, paramName = 'id') {
   const params = useParams()
   const paramValue = params[paramName]
+  const context = useContext(StoryboardContext)
+  const prototypeName = context?.prototypeName ?? null
 
   // Re-render on hash or localStorage changes so overrides are reactive
   const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
@@ -99,14 +102,15 @@ export function useRecord(recordName, paramName = 'id') {
   return useMemo(() => {
     if (!paramValue) return null
     try {
-      const base = loadRecord(recordName)
-      const merged = applyRecordOverrides(base, recordName)
+      const resolvedName = resolveRecordName(prototypeName, recordName)
+      const base = loadRecord(resolvedName)
+      const merged = applyRecordOverrides(base, resolvedName)
       return merged.find(e => e[paramName] === paramValue) ?? null
     } catch (err) {
       console.error(`[useRecord] ${err.message}`)
       return null
     }
-  }, [recordName, paramName, paramValue, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [recordName, paramName, paramValue, prototypeName, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
 }
 
 /**
@@ -121,17 +125,21 @@ export function useRecord(recordName, paramName = 'id') {
  * const allPosts = useRecords('posts')
  */
 export function useRecords(recordName) {
+  const context = useContext(StoryboardContext)
+  const prototypeName = context?.prototypeName ?? null
+
   // Re-render on hash or localStorage changes so overrides are reactive
   const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
   const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
 
   return useMemo(() => {
     try {
-      const base = loadRecord(recordName)
-      return applyRecordOverrides(base, recordName)
+      const resolvedName = resolveRecordName(prototypeName, recordName)
+      const base = loadRecord(resolvedName)
+      return applyRecordOverrides(base, resolvedName)
     } catch (err) {
       console.error(`[useRecords] ${err.message}`)
       return []
     }
-  }, [recordName, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [recordName, prototypeName, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
 }

package/src/hooks/useScene.js

@@ -2,27 +2,36 @@ import { useContext, useCallback } from 'react'
 import { StoryboardContext } from '../StoryboardContext.js'
 
 /**
- * Read the current scene name and programmatically switch scenes.
+ * Read the current flow name and programmatically switch flows.
  *
- * @returns {{ sceneName: string, switchScene: (name: string) => void }}
- *   - sceneName   – current active scene (e.g. "default")
- *   - switchScene – navigate to a different scene by updating ?scene= param
+ * @returns {{ flowName: string, switchFlow: (name: string) => void }}
+ *   - flowName    – current active flow (e.g. "default")
+ *   - switchFlow  – navigate to a different flow by updating ?scene= param
  */
-export function useScene() {
+export function useFlow() {
   const context = useContext(StoryboardContext)
   if (context === null) {
-    throw new Error('useScene must be used within a <StoryboardProvider>')
+    throw new Error('useFlow must be used within a <StoryboardProvider>')
   }
 
-  const switchScene = useCallback((name) => {
+  const switchFlow = useCallback((name) => {
     const url = new URL(window.location.href)
     url.searchParams.set('scene', name)
-    // Preserve hash params across scene switches
+    // Preserve hash params across flow switches
     window.location.href = url.toString()
   }, [])
 
   return {
-    sceneName: context.sceneName,
-    switchScene,
+    flowName: context.flowName,
+    switchFlow,
+  }
+}
+
+/** @deprecated Use useFlow() */
+export function useScene() {
+  const { flowName, switchFlow } = useFlow()
+  return {
+    sceneName: flowName,
+    switchScene: switchFlow,
   }
 }

package/src/hooks/useScene.test.js

@@ -1,39 +1,66 @@
 import { renderHook } from '@testing-library/react'
+import { useFlow } from './useScene.js'
 import { useScene } from './useScene.js'
-import { seedTestData, createWrapper, TEST_SCENES } from '../test-utils.js'
+import { seedTestData, createWrapper, TEST_FLOWS } from '../test-utils.js'
 
-const sceneData = TEST_SCENES.default
+const flowData = TEST_FLOWS.default
 
 beforeEach(() => {
   seedTestData()
 })
 
-describe('useScene', () => {
+describe('useFlow', () => {
+  it('returns { flowName, switchFlow }', () => {
+    const { result } = renderHook(() => useFlow(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(result.current).toHaveProperty('flowName')
+    expect(result.current).toHaveProperty('switchFlow')
+  })
+
+  it('flowName matches the value from context', () => {
+    const { result } = renderHook(() => useFlow(), {
+      wrapper: createWrapper(flowData, 'other'),
+    })
+    expect(result.current.flowName).toBe('other')
+  })
+
+  it('switchFlow is a function', () => {
+    const { result } = renderHook(() => useFlow(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(typeof result.current.switchFlow).toBe('function')
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useFlow())
+    }).toThrow('useFlow must be used within a <StoryboardProvider>')
+  })
+})
+
+// ── useScene (deprecated alias) ──
+
+describe('useScene (deprecated alias)', () => {
   it('returns { sceneName, switchScene }', () => {
     const { result } = renderHook(() => useScene(), {
-      wrapper: createWrapper(sceneData),
+      wrapper: createWrapper(flowData),
     })
     expect(result.current).toHaveProperty('sceneName')
     expect(result.current).toHaveProperty('switchScene')
   })
 
-  it('sceneName matches the value from context', () => {
+  it('sceneName matches the flow name from context', () => {
     const { result } = renderHook(() => useScene(), {
-      wrapper: createWrapper(sceneData, 'other'),
+      wrapper: createWrapper(flowData, 'other'),
     })
     expect(result.current.sceneName).toBe('other')
   })
 
   it('switchScene is a function', () => {
     const { result } = renderHook(() => useScene(), {
-      wrapper: createWrapper(sceneData),
+      wrapper: createWrapper(flowData),
     })
     expect(typeof result.current.switchScene).toBe('function')
   })
-
-  it('throws when used outside StoryboardProvider', () => {
-    expect(() => {
-      renderHook(() => useScene())
-    }).toThrow('useScene must be used within a <StoryboardProvider>')
-  })
 })

package/src/hooks/useSceneData.js

@@ -7,24 +7,24 @@ import { isHideMode, getShadow, getAllShadows } from '@dfosco/storyboard-core'
 import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
 
 /**
- * Access scene data by dot-notation path.
- * Hash params override scene data — both exact matches and nested paths.
+ * Access flow data by dot-notation path.
+ * Hash params override flow data — both exact matches and nested paths.
  *
  * Examples:
- *   useSceneData('user.name') with #user.name=Alice → "Alice"
- *   useSceneData('repositories') with #repositories.0.name=Foo
+ *   useFlowData('user.name') with #user.name=Alice → "Alice"
+ *   useFlowData('repositories') with #repositories.0.name=Foo
  *     → deep clone of repositories array with [0].name overridden to "Foo"
  *
  * @param {string} [path] - Dot-notation path (e.g. 'user.profile.name').
- *                          Omit to get the entire scene object.
+ *                          Omit to get the entire flow object.
  * @returns {*} The resolved value. Returns {} if path is missing after loading.
  * @throws If used outside a StoryboardProvider.
  */
-export function useSceneData(path) {
+export function useFlowData(path) {
   const context = useContext(StoryboardContext)
 
   if (context === null) {
-    throw new Error('useSceneData must be used within a <StoryboardProvider>')
+    throw new Error('useFlowData must be used within a <StoryboardProvider>')
   }
 
   const { data, loading, error } = context
@@ -73,7 +73,7 @@ export function useSceneData(path) {
     }
 
     if (sceneValue === undefined) {
-      console.warn(`[useSceneData] Path "${path}" not found in scene data.`)
+      console.warn(`[useFlowData] Path "${path}" not found in flow data.`)
       return {}
     }
 
@@ -83,15 +83,21 @@ export function useSceneData(path) {
   return result
 }
 
+/** @deprecated Use useFlowData() */
+export const useSceneData = useFlowData
+
 /**
- * Returns true while scene data is still loading.
+ * Returns true while flow data is still loading.
  */
-export function useSceneLoading() {
+export function useFlowLoading() {
   const context = useContext(StoryboardContext)
 
   if (context === null) {
-    throw new Error('useSceneLoading must be used within a <StoryboardProvider>')
+    throw new Error('useFlowLoading must be used within a <StoryboardProvider>')
   }
 
   return context.loading
 }
+
+/** @deprecated Use useFlowLoading() */
+export const useSceneLoading = useFlowLoading

package/src/hooks/useSceneData.test.js

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

@@ -10,16 +10,19 @@ 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 { useScene } from './hooks/useScene.js'
+export { useFlow, useScene } from './hooks/useScene.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'
 
 // React Router integration
 export { installHashPreserver } from './hashPreserver.js'
@@ -27,5 +30,8 @@ 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)
+// ModeSwitch and ToolbarShell UI moved to @dfosco/storyboard-svelte-ui
+
 // Viewfinder dashboard
 export { default as Viewfinder } from './Viewfinder.jsx'

package/src/test-utils.js

@@ -3,7 +3,7 @@ import { StoryboardContext } from './StoryboardContext.js'
 import { init } from '@dfosco/storyboard-core'
 
 // Default test data
-export const TEST_SCENES = {
+export const TEST_FLOWS = {
   default: {
     user: { name: 'Jane', profile: { bio: 'Dev' } },
     settings: { theme: 'dark' },
@@ -15,6 +15,9 @@ export const TEST_SCENES = {
   },
 }
 
+/** @deprecated Use TEST_FLOWS */
+export const TEST_SCENES = TEST_FLOWS
+
 export const TEST_OBJECTS = {
   'jane-doe': { name: 'Jane Doe', role: 'admin' },
 }
@@ -27,15 +30,15 @@ export const TEST_RECORDS = {
 }
 
 export function seedTestData() {
-  init({ scenes: TEST_SCENES, objects: TEST_OBJECTS, records: TEST_RECORDS })
+  init({ flows: TEST_FLOWS, objects: TEST_OBJECTS, records: TEST_RECORDS })
 }
 
-// Wrapper that provides StoryboardContext with given scene data
-export function createWrapper(sceneData, sceneName = 'default') {
+// Wrapper that provides StoryboardContext with given flow data
+export function createWrapper(flowData, flowName = 'default') {
   return function Wrapper({ children }) {
     return createElement(
       StoryboardContext.Provider,
-      { value: { data: sceneData, error: null, loading: false, sceneName } },
+      { value: { data: flowData, error: null, loading: false, flowName, sceneName: flowName } },
       children
     )
   }