@dfosco/storyboard-react 1.20.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-react",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "type": "module",
   "dependencies": {
     "@dfosco/storyboard-core": "*",

package/src/hooks/useObject.js

@@ -0,0 +1,83 @@
+import { useMemo, useSyncExternalStore } from 'react'
+import { loadObject } from '@dfosco/storyboard-core'
+import { getByPath, deepClone, setByPath } from '@dfosco/storyboard-core'
+import { getParam, getAllParams } from '@dfosco/storyboard-core'
+import { isHideMode, getShadow, getAllShadows } from '@dfosco/storyboard-core'
+import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
+import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * Load an object data file directly by name, without going through a scene.
+ * Supports dot-notation path access and URL hash overrides.
+ *
+ * Hash override convention: object.{objectName}.{field}=value
+ *
+ * @param {string} objectName - Name of the object file (e.g., "jane-doe")
+ * @param {string} [path] - Optional dot-notation path (e.g., "profile.name")
+ * @returns {*} The resolved value, or undefined if loading fails
+ *
+ * @example
+ * const user = useObject('jane-doe')
+ * const name = useObject('jane-doe', 'profile.name')
+ *
+ * // Override via URL hash: #object.jane-doe.name=Alice
+ */
+export function useObject(objectName, path) {
+  const hashString = useSyncExternalStore(subscribeToHash, getHashSnapshot)
+  const storageString = useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  return useMemo(() => {
+    let data
+    try {
+      data = loadObject(objectName)
+    } catch (err) {
+      console.error(`[useObject] ${err.message}`)
+      return undefined
+    }
+
+    const hidden = isHideMode()
+    const readParam = hidden ? getShadow : getParam
+    const readAllParams = hidden ? getAllShadows : getAllParams
+
+    // Apply overrides scoped to this object
+    const prefix = `object.${objectName}.`
+    const allParams = readAllParams()
+    const overrideKeys = Object.keys(allParams).filter(k => k.startsWith(prefix))
+
+    if (overrideKeys.length > 0) {
+      data = deepClone(data)
+      for (const key of overrideKeys) {
+        const fieldPath = key.slice(prefix.length)
+        setByPath(data, fieldPath, allParams[key])
+      }
+    }
+
+    if (!path) return data
+
+    // Exact match for this sub-path override
+    const exactKey = `${prefix}${path}`
+    const exact = readParam(exactKey)
+    if (exact !== null) return exact
+
+    // Child overrides under the sub-path
+    const subPrefix = exactKey + '.'
+    const childKeys = overrideKeys.filter(k => k.startsWith(subPrefix))
+    const baseValue = getByPath(data, path)
+
+    if (childKeys.length > 0 && baseValue !== undefined) {
+      const merged = deepClone(baseValue)
+      for (const key of childKeys) {
+        const relativePath = key.slice(subPrefix.length)
+        setByPath(merged, relativePath, allParams[key])
+      }
+      return merged
+    }
+
+    if (baseValue === undefined) {
+      console.warn(`[useObject] Path "${path}" not found in object "${objectName}".`)
+      return undefined
+    }
+
+    return baseValue
+  }, [objectName, path, hashString, storageString]) // eslint-disable-line react-hooks/exhaustive-deps
+}

package/src/hooks/useObject.test.js

@@ -0,0 +1,74 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, TEST_OBJECTS } from '../../test-utils.js'
+import { activateHideMode, setShadow } from '@dfosco/storyboard-core'
+import { useObject } from './useObject.js'
+
+beforeEach(() => {
+  seedTestData()
+  window.location.hash = ''
+})
+
+describe('useObject', () => {
+  it('loads an object by name', () => {
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current).toEqual(TEST_OBJECTS['jane-doe'])
+  })
+
+  it('returns undefined for missing object', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const { result } = renderHook(() => useObject('nonexistent'))
+    expect(result.current).toBeUndefined()
+    console.error.mockRestore()
+  })
+
+  it('resolves dot-notation path', () => {
+    const { result } = renderHook(() => useObject('jane-doe', 'name'))
+    expect(result.current).toBe('Jane Doe')
+  })
+
+  it('returns undefined for missing path', () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { result } = renderHook(() => useObject('jane-doe', 'missing.path'))
+    expect(result.current).toBeUndefined()
+    console.warn.mockRestore()
+  })
+
+  it('applies hash overrides to full object', () => {
+    window.location.hash = 'object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current.name).toBe('Alice')
+    expect(result.current.role).toBe('admin')
+  })
+
+  it('applies hash overrides when accessing by path', () => {
+    window.location.hash = 'object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useObject('jane-doe', 'name'))
+    expect(result.current).toBe('Alice')
+  })
+
+  it('returns deep clone (mutations do not affect source data)', () => {
+    const { result: r1 } = renderHook(() => useObject('jane-doe'))
+    r1.current.name = 'Mutated'
+    // A fresh hook call should return original data, not the mutated reference
+    const { result: r2 } = renderHook(() => useObject('jane-doe'))
+    expect(r2.current.name).toBe('Jane Doe')
+  })
+})
+
+describe('useObject (hide mode)', () => {
+  beforeEach(() => {
+    act(() => { activateHideMode() })
+  })
+
+  it('reads overrides from localStorage shadow in hide mode', () => {
+    act(() => { setShadow('object.jane-doe.name', 'Shadow Jane') })
+    const { result } = renderHook(() => useObject('jane-doe'))
+    expect(result.current.name).toBe('Shadow Jane')
+  })
+
+  it('reads path-specific overrides from shadow in hide mode', () => {
+    act(() => { setShadow('object.jane-doe.role', 'superadmin') })
+    const { result } = renderHook(() => useObject('jane-doe', 'role'))
+    expect(result.current).toBe('superadmin')
+  })
+})

package/src/hooks/useOverride.js

@@ -7,7 +7,7 @@ import { isHideMode, getShadow, setShadow, removeShadow } from '@dfosco/storyboa
 import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
 
 /**
- * Read/write overrides on top of scene data.
+ * Read/write overrides on top of scene data or object data.
  *
  * **Normal mode:**
  *   Read priority:  URL hash param → Scene JSON value → undefined
@@ -20,19 +20,23 @@ import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
  * Every write also mirrors to localStorage shadow keys, so hide mode
  * can hot-swap without data loss.
  *
+ * Works with any override namespace — scene paths (e.g. 'settings.theme'),
+ * object paths (e.g. 'object.jane-doe.name'), or record paths
+ * (e.g. 'record.posts.post-1.title').
+ *
+ * When used outside a StoryboardProvider (e.g. for object overrides),
+ * the scene fallback is skipped and value resolves to override ?? undefined.
+ *
  * @param {string} path - Dot-notation key (e.g. 'settings.theme')
  * @returns {[any, function, function]}
- *   [0] current value (override ?? scene default)
+ *   [0] current value (override ?? scene default ?? undefined)
  *   [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 data = context?.data
   const hidden = isHideMode()
 
   // Scene default for this path (fallback when no override exists)

package/src/hooks/useOverride.test.js

@@ -58,9 +58,14 @@ describe('useOverride', () => {
     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>')
+  it('works without StoryboardProvider for object overrides', () => {
+    window.location.hash = '#object.jane-doe.name=Alice'
+    const { result } = renderHook(() => useOverride('object.jane-doe.name'))
+    expect(result.current[0]).toBe('Alice')
+  })
+
+  it('returns undefined without provider when no override exists', () => {
+    const { result } = renderHook(() => useOverride('object.jane-doe.name'))
+    expect(result.current[0]).toBeUndefined()
   })
 })

package/src/index.js

@@ -15,7 +15,7 @@ export { useOverride } from './hooks/useOverride.js'
 export { useOverride as useSession } from './hooks/useOverride.js' // deprecated alias
 export { useScene } from './hooks/useScene.js'
 export { useRecord, useRecords } from './hooks/useRecord.js'
-export { useRecordOverride } from './hooks/useRecordOverride.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'

package/src/vite/data-plugin.js

@@ -67,7 +67,11 @@ function readConfig(root) {
   const configPath = path.resolve(root, 'storyboard.config.json')
   try {
     const raw = fs.readFileSync(configPath, 'utf-8')
-    return { config: parseJsonc(raw), configPath }
+    const errors = []
+    const config = parseJsonc(raw, errors)
+    // Treat malformed JSON (e.g. mid-edit partial saves) as missing config
+    if (errors.length > 0) return { config: null, configPath }
+    return { config, configPath }
   } catch {
     return { config: null, configPath }
   }

package/src/hooks/useRecordOverride.js

@@ -1,22 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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')
-  })
-})