@dfosco/storyboard-react 1.1.0

package/src/hooks/useOverride.js

@@ -0,0 +1,80 @@
+import { useCallback, useContext, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath } from '@dfosco/storyboard-core'
+import { getParam, setParam, removeParam } from '@dfosco/storyboard-core'
+import { subscribeToHash } from '@dfosco/storyboard-core'
+import { isHideMode, getShadow, setShadow, removeShadow } from '@dfosco/storyboard-core'
+import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * Read/write overrides on top of scene data.
+ *
+ * **Normal mode:**
+ *   Read priority:  URL hash param → Scene JSON value → undefined
+ *   Write target:   URL hash + shadow copy to localStorage
+ *
+ * **Hide mode** (activated by `?hide`):
+ *   Read priority:  shadow localStorage → Scene JSON value → undefined
+ *   Write target:   shadow localStorage only (URL stays clean)
+ *
+ * Every write also mirrors to localStorage shadow keys, so hide mode
+ * can hot-swap without data loss.
+ *
+ * @param {string} path - Dot-notation key (e.g. 'settings.theme')
+ * @returns {[any, function, function]}
+ *   [0] current value (override ?? scene default)
+ *   [1] setValue(newValue)  – write an override
+ *   [2] clearValue()       – remove the override, reverting to scene default
+ */
+export function useOverride(path) {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useOverride must be used within a <StoryboardProvider>')
+  }
+
+  const { data } = context
+  const hidden = isHideMode()
+
+  // Scene default for this path (fallback when no override exists)
+  const sceneDefault = data != null ? getByPath(data, path) : undefined
+
+  // Subscribe to both sources for reactivity
+  const getHashSnap = useCallback(() => getParam(path), [path])
+  const hashValue = useSyncExternalStore(subscribeToHash, getHashSnap)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  // Resolved value depends on mode
+  let value
+  if (hidden) {
+    const shadowValue = getShadow(path)
+    value = shadowValue !== null ? shadowValue : sceneDefault
+  } else {
+    value = hashValue !== null ? hashValue : sceneDefault
+  }
+
+  /** Write a value — targets hash or shadow depending on mode */
+  const setValue = useCallback(
+    (newValue) => {
+      if (isHideMode()) {
+        setShadow(path, newValue)
+      } else {
+        setParam(path, newValue)
+        // Always mirror to shadow so hide mode can hot-swap
+        setShadow(path, newValue)
+      }
+    },
+    [path],
+  )
+
+  /** Remove the override, reverting to scene default */
+  const clearValue = useCallback(() => {
+    if (isHideMode()) {
+      removeShadow(path)
+    } else {
+      removeParam(path)
+      removeShadow(path)
+    }
+  }, [path])
+
+  return [value, setValue, clearValue]
+}

package/src/hooks/useOverride.test.js

@@ -0,0 +1,66 @@
+import { renderHook, act } from '@testing-library/react'
+import { useOverride } from './useOverride.js'
+import { seedTestData, createWrapper, TEST_SCENES } from '../test-utils.js'
+
+const sceneData = TEST_SCENES.default
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useOverride', () => {
+  it('returns [value, setValue, clearValue] tuple', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current).toHaveLength(3)
+    expect(typeof result.current[1]).toBe('function')
+    expect(typeof result.current[2]).toBe('function')
+  })
+
+  it('value falls back to scene default when no hash override', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current[0]).toBe('dark')
+  })
+
+  it('value reads from hash override when present', () => {
+    window.location.hash = '#settings.theme=light'
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+    expect(result.current[0]).toBe('light')
+  })
+
+  it('setValue writes to hash', () => {
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+
+    act(() => {
+      result.current[1]('blue')
+    })
+
+    expect(window.location.hash).toContain('settings.theme=blue')
+  })
+
+  it('clearValue removes hash param', () => {
+    window.location.hash = '#settings.theme=red'
+    const { result } = renderHook(() => useOverride('settings.theme'), {
+      wrapper: createWrapper(sceneData),
+    })
+
+    act(() => {
+      result.current[2]()
+    })
+
+    expect(window.location.hash).not.toContain('settings.theme')
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useOverride('settings.theme'))
+    }).toThrow('useOverride must be used within a <StoryboardProvider>')
+  })
+})

package/src/hooks/useRecord.js

@@ -0,0 +1,130 @@
+import { useMemo, useSyncExternalStore } from 'react'
+import { useParams } from 'react-router-dom'
+import { loadRecord } from '@dfosco/storyboard-core'
+import { deepClone, setByPath } from '@dfosco/storyboard-core'
+import { getAllParams } from '@dfosco/storyboard-core'
+import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * Collect hash overrides for a record and merge them into the base array.
+ *
+ * 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} recordName - Record collection name (e.g. "posts")
+ * @returns {Array} Merged array
+ */
+function applyRecordOverrides(baseRecords, recordName) {
+  const allParams = getAllParams()
+  const prefix = `record.${recordName}.`
+
+  // Collect only the params that target this record
+  const overrideKeys = Object.keys(allParams).filter(k => k.startsWith(prefix))
+  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) {
+    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]
+
+  // Re-render on hash changes so overrides are reactive
+  const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
+
+  return useMemo(() => {
+    if (!paramValue) return null
+    try {
+      const base = loadRecord(recordName)
+      const merged = applyRecordOverrides(base, recordName)
+      return merged.find(e => e[paramName] === paramValue) ?? null
+    } catch (err) {
+      console.error(`[useRecord] ${err.message}`)
+      return null
+    }
+  }, [recordName, paramName, paramValue, hashString]) // 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) {
+  // Re-render on hash changes so overrides are reactive
+  const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
+
+  return useMemo(() => {
+    try {
+      const base = loadRecord(recordName)
+      return applyRecordOverrides(base, recordName)
+    } catch (err) {
+      console.error(`[useRecords] ${err.message}`)
+      return []
+    }
+  }, [recordName, hashString]) // eslint-disable-line react-hooks/exhaustive-deps
+}

package/src/hooks/useRecord.test.js

@@ -0,0 +1,81 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, TEST_RECORDS } from '../../test-utils.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({})
+})
+
+// ── 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')
+  })
+})

package/src/hooks/useRecordOverride.js

@@ -0,0 +1,22 @@
+import { useOverride } from './useOverride.js'
+
+/**
+ * Read/write hash-param overrides for a specific record entry field.
+ *
+ * Builds the full override path as `record.{recordName}.{entryId}.{field}`
+ * and delegates to `useOverride`.
+ *
+ * @param {string} recordName - Record collection name (e.g. "posts")
+ * @param {string} entryId - The id of the record entry to override
+ * @param {string} field - Dot-notation field path within the entry (e.g. "title" or "author.name")
+ * @returns {[any, function, function]}
+ *   [0] current value (override ?? record default)
+ *   [1] setValue(newValue) – write an override to the URL hash
+ *   [2] clearValue() – remove the override
+ *
+ * @example
+ * const [title, setTitle, clearTitle] = useRecordOverride('posts', 'welcome-to-storyboard', 'title')
+ */
+export function useRecordOverride(recordName, entryId, field) {
+  return useOverride(`record.${recordName}.${entryId}.${field}`)
+}

package/src/hooks/useRecordOverride.test.js

@@ -0,0 +1,52 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, createWrapper, TEST_SCENES } from '../../test-utils.js'
+import { useRecordOverride } from './useRecordOverride.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+const wrapper = createWrapper(TEST_SCENES.default)
+
+describe('useRecordOverride', () => {
+  it('returns [value, setValue, clearValue]', () => {
+    const { result } = renderHook(
+      () => useRecordOverride('posts', 'post-1', 'title'),
+      { wrapper },
+    )
+    expect(result.current).toHaveLength(3)
+    expect(typeof result.current[1]).toBe('function')
+    expect(typeof result.current[2]).toBe('function')
+  })
+
+  it('builds correct override path (record.posts.post-1.title)', () => {
+    const { result } = renderHook(
+      () => useRecordOverride('posts', 'post-1', 'title'),
+      { wrapper },
+    )
+    // scene data has record.posts.post-1.title = 'Original Title'
+    expect(result.current[0]).toBe('Original Title')
+  })
+
+  it('returns undefined when path does not exist in scene data', () => {
+    const { result } = renderHook(
+      () => useRecordOverride('posts', 'post-99', 'title'),
+      { wrapper },
+    )
+    expect(result.current[0]).toBeUndefined()
+  })
+
+  it('setValue writes to hash at the correct path', () => {
+    const { result } = renderHook(
+      () => useRecordOverride('posts', 'post-1', 'title'),
+      { wrapper },
+    )
+
+    act(() => {
+      result.current[1]('New Title')
+    })
+
+    const params = new URLSearchParams(window.location.hash.replace(/^#/, ''))
+    expect(params.get('record.posts.post-1.title')).toBe('New Title')
+  })
+})

package/src/hooks/useScene.js

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

package/src/hooks/useScene.test.js

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

@@ -0,0 +1,97 @@
+import { useContext, useMemo, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath, deepClone, setByPath } from '@dfosco/storyboard-core'
+import { getParam, getAllParams } from '@dfosco/storyboard-core'
+import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
+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.
+ *
+ * Examples:
+ *   useSceneData('user.name') with #user.name=Alice → "Alice"
+ *   useSceneData('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.
+ * @returns {*} The resolved value. Returns {} if path is missing after loading.
+ * @throws If used outside a StoryboardProvider.
+ */
+export function useSceneData(path) {
+  const context = useContext(StoryboardContext)
+
+  if (context === null) {
+    throw new Error('useSceneData 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
+  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) {
+      console.warn(`[useSceneData] Path "${path}" not found in scene data.`)
+      return {}
+    }
+
+    return sceneValue
+  }, [data, loading, error, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  return result
+}
+
+/**
+ * Returns true while scene data is still loading.
+ */
+export function useSceneLoading() {
+  const context = useContext(StoryboardContext)
+
+  if (context === null) {
+    throw new Error('useSceneLoading must be used within a <StoryboardProvider>')
+  }
+
+  return context.loading
+}