@dfosco/storyboard-react 2.1.0 → 2.2.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "dependencies": {
-    "@dfosco/storyboard-core": "2.1.0",
+    "@dfosco/storyboard-core": "2.2.0",
     "glob": "^11.0.0",
     "jsonc-parser": "^3.3.1"
   },

package/src/Viewfinder.jsx

@@ -15,12 +15,14 @@ import { useRef, useEffect } from 'react'
  * @param {string} [props.title] - Header title
  * @param {string} [props.subtitle] - Optional subtitle
  * @param {boolean} [props.showThumbnails] - Show thumbnail previews
- * @param {boolean} [props.hideDefaultScene] - Hide the "default" flow
+ * @param {boolean} [props.hideDefaultFlow] - Hide the "default" flow from the "Other flows" section
  */
-export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyboard', subtitle, showThumbnails = false, hideDefaultScene = false }) {
+export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyboard', subtitle, showThumbnails = false, hideDefaultFlow, hideDefaultScene = false }) {
   const containerRef = useRef(null)
   const handleRef = useRef(null)
 
+  const shouldHideDefault = hideDefaultFlow ?? hideDefaultScene
+
   const knownRoutes = Object.keys(pageModules)
     .map(p => p.replace('/src/prototypes/', '').replace('.jsx', ''))
     .filter(n => !n.startsWith('_') && n !== 'index' && n !== 'viewfinder')
@@ -40,7 +42,7 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         basePath,
         knownRoutes,
         showThumbnails,
-        hideDefaultFlow: hideDefaultScene,
+        hideDefaultFlow: shouldHideDefault,
       })
     })
 
@@ -51,7 +53,7 @@ export default function Viewfinder({ pageModules = {}, basePath, title = 'Storyb
         handleRef.current = null
       }
     }
-  }, [title, subtitle, basePath, showThumbnails, hideDefaultScene])
+  }, [title, subtitle, basePath, showThumbnails, shouldHideDefault])
 
   return <div ref={containerRef} style={{ minHeight: '100vh' }} />
 }

package/src/context.jsx

@@ -32,7 +32,7 @@ function getPageFlowName(pathname) {
 
 /**
  * Provides loaded flow data to the component tree.
- * Reads the flow name from the ?scene= URL param, the flowName prop,
+ * Reads the flow name from the ?flow= URL param (with ?scene= as alias),
  * a matching flow file for the current page, or defaults to "default".
  *
  * Derives the prototype scope from the route and uses it to resolve
@@ -43,7 +43,8 @@ function getPageFlowName(pathname) {
  */
 export default function StoryboardProvider({ flowName, sceneName, recordName, recordParam, children }) {
   const location = useLocation()
-  const sceneParam = new URLSearchParams(location.search).get('scene')
+  const searchParams = new URLSearchParams(location.search)
+  const sceneParam = searchParams.get('flow') || searchParams.get('scene')
   const prototypeName = getPrototypeName(location.pathname)
   const pageFlow = getPageFlowName(location.pathname)
   const params = useParams()

package/src/context.test.jsx

@@ -187,7 +187,18 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('nav')).toHaveTextContent('Home,Repos')
   })
 
-  it('reads ?scene= param from location.search', () => {
+  it('reads ?flow= param from location.search', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('reads ?scene= as alias for ?flow=', () => {
     mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?scene=other', hash: '' })
 
     render(
@@ -198,6 +209,17 @@ describe('StoryboardProvider', () => {
     expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
   })
 
+  it('prefers ?flow= over ?scene= when both present', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/whatever', search: '?flow=other&scene=default', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
   it('loads prototype flow for sub-pages when no page-specific flow exists', () => {
     init({
       flows: {

package/src/hooks/useRecord.js

@@ -20,15 +20,26 @@ import { StoryboardContext } from '../StoryboardContext.js'
  * - 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)
@@ -37,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
@@ -104,7 +117,7 @@ export function useRecord(recordName, paramName = 'id') {
     try {
       const resolvedName = resolveRecordName(prototypeName, recordName)
       const base = loadRecord(resolvedName)
-      const merged = applyRecordOverrides(base, resolvedName)
+      const merged = applyRecordOverrides(base, resolvedName, recordName)
       return merged.find(e => e[paramName] === paramValue) ?? null
     } catch (err) {
       console.error(`[useRecord] ${err.message}`)
@@ -136,7 +149,7 @@ export function useRecords(recordName) {
     try {
       const resolvedName = resolveRecordName(prototypeName, recordName)
       const base = loadRecord(resolvedName)
-      return applyRecordOverrides(base, resolvedName)
+      return applyRecordOverrides(base, resolvedName, recordName)
     } catch (err) {
       console.error(`[useRecords] ${err.message}`)
       return []

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

@@ -6,7 +6,7 @@ import { StoryboardContext } from '../StoryboardContext.js'
  *
  * @returns {{ flowName: string, switchFlow: (name: string) => void }}
  *   - flowName    – current active flow (e.g. "default")
- *   - switchFlow  – navigate to a different flow by updating ?scene= param
+ *   - switchFlow  – navigate to a different flow by updating ?flow= param
  */
 export function useFlow() {
   const context = useContext(StoryboardContext)
@@ -16,7 +16,8 @@ export function useFlow() {
 
   const switchFlow = useCallback((name) => {
     const url = new URL(window.location.href)
-    url.searchParams.set('scene', name)
+    url.searchParams.delete('scene')
+    url.searchParams.set('flow', name)
     // Preserve hash params across flow switches
     window.location.href = url.toString()
   }, [])