@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/hooks/useRecord.js

@@ -0,0 +1,158 @@
+import { useContext, useMemo, useSyncExternalStore } from 'react'
+import { useParams } from 'react-router-dom'
+import { loadRecord, resolveRecordName } from '../../core/index.js'
+import { deepClone, setByPath } from '../../core/index.js'
+import { getAllParams } from '../../core/index.js'
+import { isHideMode, getAllShadows } from '../../core/index.js'
+import { subscribeToHash, getHashSnapshot } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+/**
+ * Collect overrides for a record and merge them into the base array.
+ *
+ * In normal mode reads from URL hash params; in hide mode reads from
+ * localStorage shadow snapshots.
+ *
+ * Hash convention: record.{recordName}.{entryId}.{field}=value
+ *
+ * - Existing entries (matched by id) get fields merged on top.
+ * - Unknown ids create new entries appended to the array.
+ *
+ * @param {Array} baseRecords - The original record array (will be deep-cloned)
+ * @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, resolvedName, plainName) {
+  const allParams = isHideMode() ? getAllShadows() : getAllParams()
+
+  // 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(resolvedPrefix) || (plainPrefix && k.startsWith(plainPrefix))
+  )
+  if (overrideKeys.length === 0) return baseRecords
+
+  const records = deepClone(baseRecords)
+
+  // Group overrides by entry id
+  // 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
+    const entryId = rest.slice(0, dotIdx)
+    const fieldPath = rest.slice(dotIdx + 1)
+    if (!byEntryId[entryId]) byEntryId[entryId] = {}
+    byEntryId[entryId][fieldPath] = allParams[key]
+  }
+
+  for (const [entryId, fields] of Object.entries(byEntryId)) {
+    const existing = records.find(e => e.id === entryId)
+    if (existing) {
+      // Merge fields into existing entry
+      for (const [fieldPath, value] of Object.entries(fields)) {
+        setByPath(existing, fieldPath, value)
+      }
+    } else {
+      // Create new entry and append
+      const newEntry = { id: entryId }
+      for (const [fieldPath, value] of Object.entries(fields)) {
+        setByPath(newEntry, fieldPath, value)
+      }
+      records.push(newEntry)
+    }
+  }
+
+  return records
+}
+
+/**
+ * Loads a single record entry from a record collection, matched by URL param.
+ * Hash overrides are applied before lookup — both field overrides on existing
+ * entries and entirely new entries added via the URL are supported.
+ *
+ * The `paramName` serves double duty: it's both the route param to read from
+ * the URL and the record field to match against. This maps naturally to the
+ * file-based routing convention — `[id].jsx` matches entry.id,
+ * `[permalink].jsx` would match entry.permalink, etc.
+ *
+ * @param {string} recordName - Name of the record file (e.g., "posts")
+ * @param {string} paramName - Route param name, also used as the entry field to match
+ * @returns {object|null} The matched record entry, or null if not found
+ *
+ * @example
+ * // In pages/issues/[id].jsx:
+ * const issue = useRecord('issues', 'id')
+ * // URL /issues/refactor-auth-sso → finds entry where entry.id === 'refactor-auth-sso'
+ *
+ * // In pages/posts/[permalink].jsx:
+ * const post = useRecord('posts', 'permalink')
+ * // URL /posts/hello-world → finds entry where entry.permalink === 'hello-world'
+ */
+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)
+  const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  return useMemo(() => {
+    if (!paramValue) return null
+    try {
+      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, prototypeName, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+}
+
+/**
+ * Loads all entries from a record collection.
+ * Hash overrides are applied — existing entries can be modified and
+ * new entries can be created entirely from URL hash params.
+ *
+ * @param {string} recordName - Name of the record file (e.g., "posts")
+ * @returns {Array} All record entries (with overrides applied)
+ *
+ * @example
+ * 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 resolvedName = resolveRecordName(prototypeName, recordName)
+      const base = loadRecord(resolvedName)
+      return applyRecordOverrides(base, resolvedName, recordName)
+    } catch (err) {
+      console.error(`[useRecords] ${err.message}`)
+      return []
+    }
+  }, [recordName, prototypeName, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+}

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

@@ -0,0 +1,221 @@
+import React from 'react'
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, TEST_RECORDS } from '../../test-utils.js'
+import { activateHideMode, setShadow, init } from '../../core/index.js'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom')
+  return { ...actual, useParams: vi.fn(() => ({})) }
+})
+import { useParams } from 'react-router-dom'
+
+import { useRecord, useRecords } from './useRecord.js'
+
+beforeEach(() => {
+  seedTestData()
+  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', () => {
+  it('returns null when no URL param matches', () => {
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current).toBeNull()
+  })
+
+  it('returns matching record entry when param is set', () => {
+    useParams.mockReturnValue({ id: 'post-1' })
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current).toEqual(TEST_RECORDS.posts[0])
+  })
+
+  it('returns null when param value does not match any entry', () => {
+    useParams.mockReturnValue({ id: 'nonexistent' })
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current).toBeNull()
+  })
+
+  it('defaults paramName to id', () => {
+    useParams.mockReturnValue({ id: 'post-2' })
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current).toEqual(TEST_RECORDS.posts[1])
+  })
+
+  it('returns null gracefully when record collection does not exist', () => {
+    useParams.mockReturnValue({ id: 'post-1' })
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { result } = renderHook(() => useRecord('nonexistent'))
+    expect(result.current).toBeNull()
+    console.error.mockRestore()
+  })
+})
+
+// ── useRecords ──
+
+describe('useRecords', () => {
+  it('returns all entries from a record collection', () => {
+    const { result } = renderHook(() => useRecords('posts'))
+    expect(result.current).toEqual(TEST_RECORDS.posts)
+  })
+
+  it('returns empty array when record does not exist', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { result } = renderHook(() => useRecords('nonexistent'))
+    expect(result.current).toEqual([])
+    console.error.mockRestore()
+  })
+
+  it('applies hash overrides to existing entries', () => {
+    window.location.hash = 'record.posts.post-1.title=Updated'
+    const { result } = renderHook(() => useRecords('posts'))
+    const post1 = result.current.find(e => e.id === 'post-1')
+    expect(post1.title).toBe('Updated')
+  })
+
+  it('creates new entries from hash overrides', () => {
+    window.location.hash = 'record.posts.new-post.title=New'
+    const { result } = renderHook(() => useRecords('posts'))
+    const newPost = result.current.find(e => e.id === 'new-post')
+    expect(newPost).toBeTruthy()
+    expect(newPost.title).toBe('New')
+  })
+})
+
+// ── Hide mode ──
+
+describe('useRecord (hide mode)', () => {
+  beforeEach(() => {
+    act(() => { activateHideMode() })
+  })
+
+  it('reads overrides from localStorage shadow in hide mode', () => {
+    useParams.mockReturnValue({ id: 'post-1' })
+    act(() => { setShadow('record.posts.post-1.title', 'Shadow Title') })
+
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current.title).toBe('Shadow Title')
+  })
+
+  it('reactively updates when shadow changes in hide mode', () => {
+    useParams.mockReturnValue({ id: 'post-1' })
+    const { result } = renderHook(() => useRecord('posts'))
+    expect(result.current.title).toBe('First Post')
+
+    act(() => { setShadow('record.posts.post-1.title', 'Updated via Shadow') })
+    expect(result.current.title).toBe('Updated via Shadow')
+  })
+})
+
+describe('useRecords (hide mode)', () => {
+  beforeEach(() => {
+    act(() => { activateHideMode() })
+  })
+
+  it('applies shadow overrides to existing entries', () => {
+    act(() => { setShadow('record.posts.post-1.title', 'Hidden Update') })
+
+    const { result } = renderHook(() => useRecords('posts'))
+    const post1 = result.current.find(e => e.id === 'post-1')
+    expect(post1.title).toBe('Hidden Update')
+  })
+
+  it('creates new entries from shadow overrides', () => {
+    act(() => { setShadow('record.posts.shadow-post.title', 'New Shadow') })
+
+    const { result } = renderHook(() => useRecords('posts'))
+    const newPost = result.current.find(e => e.id === 'shadow-post')
+    expect(newPost).toBeTruthy()
+    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/internals/hooks/useScene.js

@@ -0,0 +1,38 @@
+import { useContext, useCallback } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+/**
+ * Read the current flow name and programmatically switch flows.
+ *
+ * @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 useFlow() {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useFlow must be used within a <StoryboardProvider>')
+  }
+
+  const switchFlow = useCallback((name) => {
+    const url = new URL(window.location.href)
+    url.searchParams.delete('scene')
+    url.searchParams.set('flow', name)
+    // Preserve hash params across flow switches
+    window.location.href = url.toString()
+  }, [])
+
+  return {
+    flowName: context.flowName,
+    switchFlow,
+  }
+}
+
+/** @deprecated Use useFlow() */
+export function useScene() {
+  const { flowName, switchFlow } = useFlow()
+  return {
+    sceneName: flowName,
+    switchScene: switchFlow,
+  }
+}

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

@@ -0,0 +1,66 @@
+import { renderHook } from '@testing-library/react'
+import { useFlow } from './useScene.js'
+import { useScene } from './useScene.js'
+import { seedTestData, createWrapper, TEST_FLOWS } from '../test-utils.js'
+
+const flowData = TEST_FLOWS.default
+
+beforeEach(() => {
+  seedTestData()
+})
+
+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(flowData),
+    })
+    expect(result.current).toHaveProperty('sceneName')
+    expect(result.current).toHaveProperty('switchScene')
+  })
+
+  it('sceneName matches the flow name from context', () => {
+    const { result } = renderHook(() => useScene(), {
+      wrapper: createWrapper(flowData, 'other'),
+    })
+    expect(result.current.sceneName).toBe('other')
+  })
+
+  it('switchScene is a function', () => {
+    const { result } = renderHook(() => useScene(), {
+      wrapper: createWrapper(flowData),
+    })
+    expect(typeof result.current.switchScene).toBe('function')
+  })
+})

package/src/internals/hooks/useSceneData.js

@@ -0,0 +1,108 @@
+import { useContext, useMemo, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath, deepClone, setByPath } from '../../core/index.js'
+import { getParam, getAllParams } from '../../core/index.js'
+import { subscribeToHash, getHashSnapshot } from '../../core/index.js'
+import { isHideMode, getShadow, getAllShadows } from '../../core/index.js'
+import { subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+
+/**
+ * Access flow data by dot-notation path.
+ * Hash params override flow data — both exact matches and nested paths.
+ *
+ * Examples:
+ *   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 flow object.
+ * @param {{ optional?: boolean }} [opts] - Pass { optional: true } to suppress
+ *                          the "path not found" warning for optional data.
+ * @returns {*} The resolved value. Returns {} if path is missing after loading.
+ * @throws If used outside a StoryboardProvider.
+ */
+export function useFlowData(path, opts) {
+  const context = useContext(StoryboardContext)
+
+  if (context === null) {
+    throw new Error('useFlowData must be used within a <StoryboardProvider>')
+  }
+
+  const { data, loading, error } = context
+
+  // Re-render on any hash or localStorage change
+  const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
+  const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  // Collect overrides relevant to this path
+  // eslint-disable-next-line react-hooks/preserve-manual-memoization
+  const result = useMemo(() => {
+    if (loading || error || data == null) return undefined
+
+    const hidden = isHideMode()
+    // In hide mode, read from shadow localStorage; otherwise from URL hash
+    const readParam = hidden ? getShadow : getParam
+    const readAllParams = hidden ? getAllShadows : getAllParams
+
+    if (!path) {
+      // No path → return full scene data with all overrides applied
+      const allParams = readAllParams()
+      const keys = Object.keys(allParams)
+      if (keys.length === 0) return data
+      const merged = deepClone(data)
+      for (const key of keys) setByPath(merged, key, allParams[key])
+      return merged
+    }
+
+    // Exact match: param directly for this path
+    const exact = readParam(path)
+    if (exact !== null) return exact
+
+    // Child overrides: params that are nested under this path
+    const prefix = path + '.'
+    const allParams = readAllParams()
+    const childKeys = Object.keys(allParams).filter(k => k.startsWith(prefix))
+
+    const sceneValue = getByPath(data, path)
+
+    if (childKeys.length > 0 && sceneValue !== undefined) {
+      const merged = deepClone(sceneValue)
+      for (const key of childKeys) {
+        const relativePath = key.slice(prefix.length)
+        setByPath(merged, relativePath, allParams[key])
+      }
+      return merged
+    }
+
+    if (sceneValue === undefined) {
+      if (!opts?.optional && data != null && Object.keys(data).length > 0) {
+        console.warn(`[useFlowData] Path "${path}" not found in flow data.`)
+      }
+      return {}
+    }
+
+    return sceneValue
+  }, [data, loading, error, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return result
+}
+
+/** @deprecated Use useFlowData() */
+export const useSceneData = useFlowData
+
+/**
+ * Returns true while flow data is still loading.
+ */
+export function useFlowLoading() {
+  const context = useContext(StoryboardContext)
+
+  if (context === null) {
+    throw new Error('useFlowLoading must be used within a <StoryboardProvider>')
+  }
+
+  return context.loading
+}
+
+/** @deprecated Use useFlowLoading() */
+export const useSceneLoading = useFlowLoading