@dfosco/storyboard-react 2.0.0 → 2.2.0

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.
@@ -19,15 +20,26 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  * - Unknown ids create new entries appended to the array.
  *
  * @param {Array} baseRecords - The original record array (will be deep-cloned)
- * @param {string} recordName - Record collection name (e.g. "posts")
+ * @param {string} resolvedName - Resolved (possibly scoped) record name (e.g. "security/rules")
+ * @param {string} [plainName] - Original unscoped record name (e.g. "rules"). Falls back to resolvedName.
  * @returns {Array} Merged array
  */
-function applyRecordOverrides(baseRecords, recordName) {
+function applyRecordOverrides(baseRecords, resolvedName, plainName) {
   const allParams = isHideMode() ? getAllShadows() : getAllParams()
-  const prefix = `record.${recordName}.`
+
+  // Check both the resolved (scoped) prefix and the plain (unscoped) prefix.
+  // Callers write overrides with the plain name, but the data index resolves
+  // to the scoped name — we need to match both so overrides are not silently
+  // dropped for prototype-scoped records.
+  const resolvedPrefix = `record.${resolvedName}.`
+  const plainPrefix = plainName && plainName !== resolvedName
+    ? `record.${plainName}.`
+    : null
 
   // Collect only the params that target this record
-  const overrideKeys = Object.keys(allParams).filter(k => k.startsWith(prefix))
+  const overrideKeys = Object.keys(allParams).filter(k =>
+    k.startsWith(resolvedPrefix) || (plainPrefix && k.startsWith(plainPrefix))
+  )
   if (overrideKeys.length === 0) return baseRecords
 
   const records = deepClone(baseRecords)
@@ -36,6 +48,8 @@ function applyRecordOverrides(baseRecords, recordName) {
   // key format: record.{name}.{entryId}.{field...}
   const byEntryId = {}
   for (const key of overrideKeys) {
+    // Determine which prefix matched to slice correctly
+    const prefix = key.startsWith(resolvedPrefix) ? resolvedPrefix : plainPrefix
     const rest = key.slice(prefix.length) // "{entryId}.{field...}"
     const dotIdx = rest.indexOf('.')
     if (dotIdx === -1) continue // no field path — skip
@@ -91,6 +105,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 +115,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, recordName)
       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 +138,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, recordName)
     } 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/useRecord.test.js

@@ -1,6 +1,8 @@
+import React from 'react'
 import { renderHook, act } from '@testing-library/react'
 import { seedTestData, TEST_RECORDS } from '../../test-utils.js'
-import { activateHideMode, setShadow } from '@dfosco/storyboard-core'
+import { activateHideMode, setShadow, init } from '@dfosco/storyboard-core'
+import { StoryboardContext } from '../StoryboardContext.js'
 
 vi.mock('react-router-dom', async () => {
   const actual = await vi.importActual('react-router-dom')
@@ -15,6 +17,20 @@ beforeEach(() => {
   useParams.mockReturnValue({})
 })
 
+/**
+ * Create a wrapper that provides StoryboardContext with a prototypeName,
+ * used for testing scoped (prototype-level) records.
+ */
+function createPrototypeWrapper(prototypeName) {
+  return function Wrapper({ children }) {
+    return React.createElement(
+      StoryboardContext.Provider,
+      { value: { data: {}, prototypeName } },
+      children,
+    )
+  }
+}
+
 // ── useRecord ──
 
 describe('useRecord', () => {
@@ -128,3 +144,78 @@ describe('useRecords (hide mode)', () => {
     expect(newPost.title).toBe('New Shadow')
   })
 })
+
+// ── Scoped (prototype) records ──
+
+const SCOPED_RECORDS = {
+  'security/rules': [
+    { id: 'constant-condition', title: 'Constant Condition', state: 'open' },
+    { id: 'unused-var', title: 'Unused Variable', state: 'open' },
+  ],
+}
+
+function seedScopedData() {
+  init({
+    flows: {},
+    objects: {},
+    records: SCOPED_RECORDS,
+  })
+}
+
+describe('useRecords (scoped records)', () => {
+  beforeEach(() => {
+    seedScopedData()
+    window.location.hash = ''
+  })
+
+  it('applies overrides written with the plain (unscoped) record name', () => {
+    // Callers write: record.rules.constant-condition.state=dismissed
+    // Reader resolves to "security/rules" — this was the bug
+    window.location.hash = 'record.rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    const rule = result.current.find(e => e.id === 'constant-condition')
+    expect(rule.state).toBe('dismissed')
+  })
+
+  it('applies overrides written with the resolved (scoped) record name', () => {
+    window.location.hash = 'record.security/rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    const rule = result.current.find(e => e.id === 'constant-condition')
+    expect(rule.state).toBe('dismissed')
+  })
+
+  it('merges overrides from both plain and scoped prefixes', () => {
+    window.location.hash =
+      'record.rules.constant-condition.state=dismissed' +
+      '&record.security/rules.unused-var.state=resolved'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecords('rules'), { wrapper })
+
+    expect(result.current.find(e => e.id === 'constant-condition').state).toBe('dismissed')
+    expect(result.current.find(e => e.id === 'unused-var').state).toBe('resolved')
+  })
+})
+
+describe('useRecord (scoped records)', () => {
+  beforeEach(() => {
+    seedScopedData()
+    window.location.hash = ''
+    useParams.mockReturnValue({ id: 'constant-condition' })
+  })
+
+  it('applies overrides written with the plain (unscoped) record name', () => {
+    window.location.hash = 'record.rules.constant-condition.state=dismissed'
+
+    const wrapper = createPrototypeWrapper('security')
+    const { result } = renderHook(() => useRecord('rules'), { wrapper })
+
+    expect(result.current.state).toBe('dismissed')
+  })
+})

package/src/hooks/useScene.js

@@ -2,27 +2,37 @@ 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 ?flow= 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
+    url.searchParams.delete('scene')
+    url.searchParams.set('flow', name)
+    // 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,10 +10,12 @@ 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'

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
     )
   }