@dfosco/storyboard-react 1.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dfosco/storyboard-react",
+  "version": "1.1.0",
+  "type": "module",
+  "dependencies": {
+    "@dfosco/storyboard-core": "*",
+    "glob": "^11.0.0",
+    "jsonc-parser": "^3.3.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dfosco/storyboard.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-router-dom": ">=6",
+    "vite": ">=5"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./vite": "./src/vite/data-plugin.js",
+    "./hash-preserver": "./src/hashPreserver.js"
+  }
+}

package/src/StoryboardContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react'
+
+export const StoryboardContext = createContext(null)

package/src/__mocks__/virtual-storyboard-data-index.js

@@ -0,0 +1,3 @@
+// Stub for the Vite virtual module used by context.jsx
+// The actual init() seeding is done in each test's beforeEach
+export default {}

package/src/context/FormContext.js

@@ -0,0 +1,13 @@
+import { createContext } from 'react'
+
+/**
+ * Provides the form context from <StoryboardForm> to child inputs.
+ *
+ * Value shape:
+ * {
+ *   prefix: string,             // data path prefix (e.g. "checkout")
+ *   getDraft: (name) => any,    // read local draft value for a field
+ *   setDraft: (name, value) => void,  // write local draft value
+ * }
+ */
+export const FormContext = createContext(null)

package/src/context/FormContext.test.js

@@ -0,0 +1,48 @@
+import { createElement } from 'react'
+import { render, screen } from '@testing-library/react'
+import { FormContext } from './FormContext.js'
+
+describe('FormContext', () => {
+  it('is a React context object', () => {
+    expect(FormContext).toBeDefined()
+    expect(FormContext.Provider).toBeDefined()
+    expect(FormContext.Consumer).toBeDefined()
+  })
+
+  it('has a default value of null', () => {
+    function Reader() {
+      return createElement(FormContext.Consumer, null, (value) =>
+        createElement('span', { 'data-testid': 'val' }, String(value)),
+      )
+    }
+    render(createElement(Reader))
+    expect(screen.getByTestId('val')).toHaveTextContent('null')
+  })
+
+  it('can provide and consume a value with prefix, getDraft, setDraft', () => {
+    const getDraft = vi.fn((name) => `draft-${name}`)
+    const setDraft = vi.fn()
+    const contextValue = { prefix: 'checkout', getDraft, setDraft }
+
+    function Reader() {
+      return createElement(FormContext.Consumer, null, (value) =>
+        createElement(
+          'span',
+          { 'data-testid': 'val' },
+          `${value.prefix}:${value.getDraft('email')}`,
+        ),
+      )
+    }
+
+    render(
+      createElement(
+        FormContext.Provider,
+        { value: contextValue },
+        createElement(Reader),
+      ),
+    )
+
+    expect(screen.getByTestId('val')).toHaveTextContent('checkout:draft-email')
+    expect(getDraft).toHaveBeenCalledWith('email')
+  })
+})

package/src/context.jsx

@@ -0,0 +1,78 @@
+/* eslint-disable react/prop-types */
+import { useMemo } from 'react'
+import { useParams } from 'react-router-dom'
+// Side-effect import: seeds the core data index via init()
+import 'virtual:storyboard-data-index'
+import { loadScene, sceneExists, findRecord, deepMerge } from '@dfosco/storyboard-core'
+import { StoryboardContext } from './StoryboardContext.js'
+
+export { StoryboardContext }
+
+/**
+ * Read the ?scene= param directly from window.location.
+ * Avoids useSearchParams() which re-renders on every router
+ * navigation event (including hash changes), causing a flash.
+ */
+function getSceneParam() {
+  return new URLSearchParams(window.location.search).get('scene')
+}
+
+/**
+ * Derives a scene name from the current page pathname.
+ * "/Overview" → "Overview", "/" → "index", "/nested/Page" → "Page"
+ */
+function getPageSceneName() {
+  const path = window.location.pathname.replace(/\/+$/, '') || '/'
+  if (path === '/') return 'index'
+  const last = path.split('/').pop()
+  return last || 'index'
+}
+
+/**
+ * Provides loaded scene data to the component tree.
+ * Reads the scene name from the ?scene= URL param, the sceneName prop,
+ * a matching scene file for the current page, or defaults to "default".
+ *
+ * Optionally merges record data when `recordName` and `recordParam` are provided.
+ * The matched record entry is injected under the "record" key in scene data.
+ */
+export default function StoryboardProvider({ sceneName, recordName, recordParam, children }) {
+  const pageScene = getPageSceneName()
+  const activeSceneName = getSceneParam() || sceneName || (sceneExists(pageScene) ? pageScene : 'default')
+  const params = useParams()
+
+  const { data, error } = useMemo(() => {
+    try {
+      let sceneData = loadScene(activeSceneName)
+
+      // Merge record data if configured
+      if (recordName && recordParam && params[recordParam]) {
+        const entry = findRecord(recordName, params[recordParam])
+        if (entry) {
+          sceneData = deepMerge(sceneData, { record: entry })
+        }
+      }
+
+      return { data: sceneData, error: null }
+    } catch (err) {
+      return { data: null, error: err.message }
+    }
+  }, [activeSceneName, recordName, recordParam, params])
+
+  const value = {
+    data,
+    error,
+    loading: false,
+    sceneName: activeSceneName,
+  }
+
+  if (error) {
+    return <span style={{ color: 'var(--fgColor-danger, #f85149)' }}>Error loading scene: {error}</span>
+  }
+
+  return (
+    <StoryboardContext.Provider value={value}>
+      {children}
+    </StoryboardContext.Provider>
+  )
+}

package/src/context.test.jsx

@@ -0,0 +1,102 @@
+import { render, screen } from '@testing-library/react'
+import { useContext } from 'react'
+import { init } from '@dfosco/storyboard-core'
+import StoryboardProvider, { StoryboardContext } from './context.jsx'
+
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom')
+  return { ...actual, useParams: vi.fn(() => ({})) }
+})
+
+beforeEach(() => {
+  init({
+    scenes: {
+      default: { title: 'Default Scene' },
+      other: { title: 'Other Scene' },
+    },
+    objects: {},
+    records: {},
+  })
+})
+
+/** Helper component that reads context and renders it. */
+function ContextReader({ path }) {
+  const ctx = useContext(StoryboardContext)
+  if (!ctx) return <span>no context</span>
+  if (ctx.error) return <span>error: {ctx.error}</span>
+  const value = path ? ctx.data?.[path] : JSON.stringify(ctx)
+  return <span data-testid="ctx">{String(value)}</span>
+}
+
+describe('StoryboardProvider', () => {
+  it('renders children when scene loads successfully', () => {
+    render(
+      <StoryboardProvider>
+        <span>child content</span>
+      </StoryboardProvider>,
+    )
+    expect(screen.getByText('child content')).toBeInTheDocument()
+  })
+
+  it('provides scene data via context', () => {
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
+  })
+
+  it('uses sceneName prop when provided', () => {
+    render(
+      <StoryboardProvider sceneName="other">
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it("falls back to 'default' scene when no ?scene= param", () => {
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
+  })
+
+  it('shows error message when scene fails to load', () => {
+    render(
+      <StoryboardProvider sceneName="nonexistent">
+        <ContextReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByText(/Error loading scene/)).toBeInTheDocument()
+  })
+
+  it('provides sceneName in context value', () => {
+    function SceneNameReader() {
+      const ctx = useContext(StoryboardContext)
+      return <span data-testid="name">{ctx?.sceneName}</span>
+    }
+    render(
+      <StoryboardProvider sceneName="other">
+        <SceneNameReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('name')).toHaveTextContent('other')
+  })
+
+  it('provides loading: false in context value', () => {
+    function LoadingReader() {
+      const ctx = useContext(StoryboardContext)
+      return <span data-testid="loading">{String(ctx?.loading)}</span>
+    }
+    render(
+      <StoryboardProvider>
+        <LoadingReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('loading')).toHaveTextContent('false')
+  })
+})

package/src/hashPreserver.js

@@ -0,0 +1,73 @@
+import { interceptHideParams } from '@dfosco/storyboard-core'
+
+/**
+ * Preserve URL hash params across all navigations — both <a> clicks
+ * and programmatic router.navigate() calls.
+ *
+ * Also intercepts ?hide and ?show params on every navigation.
+ *
+ * Hash is NOT preserved when:
+ * - The target path already has its own hash fragment
+ * - The link points to an external origin (click handler only)
+ * - The current URL has no hash
+ *
+ * @param {import('react-router-dom').Router} router - React Router instance
+ * @param {string} basename - Router basename (e.g. "/storyboard")
+ */
+export function installHashPreserver(router, basename = '') {
+  // Normalize basename: ensure no trailing slash
+  const base = basename.replace(/\/+$/, '')
+
+  // --- 1. Intercept <a> clicks ---
+  document.addEventListener('click', (e) => {
+    // Skip if modifier keys are held (open in new tab, etc.)
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return
+
+    const anchor = e.target.closest('a[href]')
+    if (!anchor) return
+    if (anchor.target === '_blank') return
+
+    const targetUrl = new URL(anchor.href, window.location.origin)
+
+    // Skip external links
+    if (targetUrl.origin !== window.location.origin) return
+
+    // Determine the hash to carry forward
+    const currentHash = window.location.hash
+    const hasCurrentHash = currentHash && currentHash !== '#'
+    const targetHasOwnHash = targetUrl.hash && targetUrl.hash !== '#'
+
+    // Use the target's own hash if it has one, otherwise carry current hash
+    const hash = targetHasOwnHash ? targetUrl.hash : (hasCurrentHash ? currentHash : '')
+
+    // Strip basename to get the route path
+    let pathname = targetUrl.pathname
+    if (base && pathname.startsWith(base)) {
+      pathname = pathname.slice(base.length) || '/'
+    }
+
+    // Prevent full page reload — navigate client-side
+    e.preventDefault()
+    router.navigate(pathname + targetUrl.search + hash)
+
+    // Check for ?hide/?show after client-side navigation
+    setTimeout(interceptHideParams, 0)
+  })
+
+  // --- 2. Intercept programmatic router.navigate() ---
+  const originalNavigate = router.navigate.bind(router)
+  router.navigate = (to, opts) => {
+    const currentHash = window.location.hash
+    const hasCurrentHash = currentHash && currentHash !== '#'
+
+    if (hasCurrentHash && typeof to === 'string' && !to.includes('#')) {
+      to = to + currentHash
+    }
+
+    return originalNavigate(to, opts).then((result) => {
+      // Check for ?hide/?show after programmatic navigation
+      interceptHideParams()
+      return result
+    })
+  }
+}

package/src/hashPreserver.test.js

@@ -0,0 +1,107 @@
+import { installHashPreserver } from './hashPreserver.js'
+
+vi.mock('@dfosco/storyboard-core', async () => {
+  const actual = await vi.importActual('@dfosco/storyboard-core')
+  return { ...actual, interceptHideParams: vi.fn() }
+})
+
+function createMockRouter() {
+  const originalNavigate = vi.fn(() => Promise.resolve())
+  return { navigate: originalNavigate, _original: originalNavigate }
+}
+
+describe('installHashPreserver', () => {
+  describe('programmatic navigate()', () => {
+    it('preserves hash when navigate() is called without hash', () => {
+      const router = createMockRouter()
+      window.location.hash = '#foo=bar'
+      installHashPreserver(router)
+
+      router.navigate('/page')
+      expect(router._original).toHaveBeenCalledWith('/page#foo=bar', undefined)
+    })
+
+    it('does NOT append current hash when navigate() target has its own hash', () => {
+      const router = createMockRouter()
+      window.location.hash = '#foo=bar'
+      installHashPreserver(router)
+
+      router.navigate('/page#other')
+      expect(router._original).toHaveBeenCalledWith('/page#other', undefined)
+    })
+
+    it('calls navigate normally when no current hash', () => {
+      const router = createMockRouter()
+      installHashPreserver(router)
+
+      router.navigate('/page')
+      expect(router._original).toHaveBeenCalledWith('/page', undefined)
+    })
+
+    it('passes options through to original navigate', async () => {
+      const router = createMockRouter()
+      installHashPreserver(router)
+
+      await router.navigate('/page', { replace: true })
+      expect(router._original).toHaveBeenCalledWith('/page', { replace: true })
+    })
+  })
+
+  describe('click handler', () => {
+    it('intercepts internal link clicks and navigates client-side', () => {
+      const router = createMockRouter()
+      window.location.hash = '#state=1'
+      installHashPreserver(router)
+
+      const a = document.createElement('a')
+      a.href = '/other-page'
+      document.body.appendChild(a)
+
+      const event = new MouseEvent('click', { bubbles: true, cancelable: true })
+      a.dispatchEvent(event)
+
+      expect(event.defaultPrevented).toBe(true)
+      const callArg = router._original.mock.calls[0][0]
+      expect(callArg).toContain('/other-page')
+
+      document.body.removeChild(a)
+    })
+
+    it('does not intercept clicks with modifier keys', () => {
+      const router = createMockRouter()
+      installHashPreserver(router)
+
+      const a = document.createElement('a')
+      a.href = '/page'
+      document.body.appendChild(a)
+
+      const event = new MouseEvent('click', {
+        bubbles: true,
+        cancelable: true,
+        metaKey: true,
+      })
+      a.dispatchEvent(event)
+
+      expect(event.defaultPrevented).toBe(false)
+
+      document.body.removeChild(a)
+    })
+
+    it('does not intercept clicks on links with target="_blank"', () => {
+      const router = createMockRouter()
+      installHashPreserver(router)
+
+      const a = document.createElement('a')
+      a.href = '/page'
+      a.target = '_blank'
+      document.body.appendChild(a)
+
+      const event = new MouseEvent('click', { bubbles: true, cancelable: true })
+      a.dispatchEvent(event)
+
+      expect(event.defaultPrevented).toBe(false)
+
+      document.body.removeChild(a)
+    })
+  })
+})

package/src/hooks/useHideMode.js

@@ -0,0 +1,31 @@
+import { useCallback, useSyncExternalStore } from 'react'
+import { isHideMode, activateHideMode, deactivateHideMode } from '@dfosco/storyboard-core'
+import { subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * Read/control hide mode.
+ *
+ * Hide mode moves all URL hash overrides into localStorage so the URL
+ * stays clean — useful when sharing storyboards with customers.
+ *
+ * @returns {{ isHidden: boolean, hide: function, show: function }}
+ *   - isHidden – true when hide mode is active
+ *   - hide()   – activate hide mode (copies hash → localStorage, cleans URL)
+ *   - show()   – deactivate hide mode (restores localStorage → hash)
+ */
+export function useHideMode() {
+  // Re-render when localStorage changes (hide flag lives there)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  const isHidden = isHideMode()
+
+  const hide = useCallback(() => {
+    activateHideMode()
+  }, [])
+
+  const show = useCallback(() => {
+    deactivateHideMode()
+  }, [])
+
+  return { isHidden, hide, show }
+}

package/src/hooks/useHideMode.test.js

@@ -0,0 +1,43 @@
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData } from '../../test-utils.js'
+import { useHideMode } from './useHideMode.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+describe('useHideMode', () => {
+  it('returns { isHidden, hide, show }', () => {
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current).toHaveProperty('isHidden')
+    expect(typeof result.current.hide).toBe('function')
+    expect(typeof result.current.show).toBe('function')
+  })
+
+  it('isHidden is false initially', () => {
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current.isHidden).toBe(false)
+  })
+
+  it('after calling hide(), isHidden becomes true', () => {
+    const { result } = renderHook(() => useHideMode())
+
+    act(() => {
+      result.current.hide()
+    })
+
+    expect(result.current.isHidden).toBe(true)
+  })
+
+  it('after calling show(), isHidden becomes false', () => {
+    // Activate hide mode directly via localStorage to set known state
+    localStorage.setItem('storyboard:__hide__', '1')
+    const { result } = renderHook(() => useHideMode())
+    expect(result.current.isHidden).toBe(true)
+
+    act(() => {
+      result.current.show()
+    })
+    expect(result.current.isHidden).toBe(false)
+  })
+})

package/src/hooks/useLocalStorage.js

@@ -0,0 +1,57 @@
+import { useCallback, useContext, useSyncExternalStore } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getByPath } from '@dfosco/storyboard-core'
+import { getParam } from '@dfosco/storyboard-core'
+import { getLocal, setLocal, removeLocal, subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+import { subscribeToHash, getHashSnapshot } from '@dfosco/storyboard-core'
+
+/**
+ * Persistent localStorage override on top of scene data.
+ *
+ * Read priority:  URL hash param → localStorage → Scene JSON value → undefined
+ * Write target:   localStorage (not the URL hash)
+ *
+ * Use this hook for values that should survive page refreshes (e.g. theme).
+ * For ephemeral URL-based overrides, use `useOverride()`.
+ *
+ * @param {string} path - Dot-notation key (e.g. 'settings.theme')
+ * @returns {[any, function, function]}
+ *   [0] current value (hash ?? localStorage ?? scene default)
+ *   [1] setValue(newValue) – write to localStorage
+ *   [2] clearValue()      – remove from localStorage
+ */
+export function useLocalStorage(path) {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useLocalStorage must be used within a <StoryboardProvider>')
+  }
+
+  const { data } = context
+
+  // Scene default for this path
+  const sceneDefault = data != null ? getByPath(data, path) : undefined
+
+  // Subscribe to both hash and localStorage changes for reactivity
+  useSyncExternalStore(subscribeToHash, getHashSnapshot)
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+
+  // Read priority: hash → localStorage → scene default
+  const hashValue = getParam(path)
+  const localValue = getLocal(path)
+  const value = hashValue !== null ? hashValue : (localValue !== null ? localValue : sceneDefault)
+
+  /** Write a value to localStorage */
+  const setValue = useCallback(
+    (newValue) => {
+      setLocal(path, newValue)
+    },
+    [path],
+  )
+
+  /** Remove the localStorage value, reverting to scene default */
+  const clearValue = useCallback(() => {
+    removeLocal(path)
+  }, [path])
+
+  return [value, setValue, clearValue]
+}

package/src/hooks/useLocalStorage.test.js

@@ -0,0 +1,76 @@
+import React from 'react'
+import { renderHook, act } from '@testing-library/react'
+import { seedTestData, createWrapper, TEST_SCENES } from '../../test-utils.js'
+import { useLocalStorage } from './useLocalStorage.js'
+
+beforeEach(() => {
+  seedTestData()
+})
+
+const wrapper = createWrapper(TEST_SCENES.default)
+
+describe('useLocalStorage', () => {
+  it('returns [value, setValue, clearValue]', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current).toHaveLength(3)
+    expect(typeof result.current[1]).toBe('function')
+    expect(typeof result.current[2]).toBe('function')
+  })
+
+  it('falls back to scene default when no override exists', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('dark_dimmed')
+  })
+
+  it('reads from localStorage when present', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('light')
+  })
+
+  it('hash override takes priority over localStorage', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    window.location.hash = 'settings.theme=high-contrast'
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+    expect(result.current[0]).toBe('high-contrast')
+  })
+
+  it('setValue writes to localStorage', () => {
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+
+    act(() => {
+      result.current[1]('light')
+    })
+
+    expect(localStorage.getItem('storyboard:settings.theme')).toBe('light')
+  })
+
+  it('clearValue removes from localStorage', () => {
+    localStorage.setItem('storyboard:settings.theme', 'light')
+    const { result } = renderHook(() => useLocalStorage('settings.theme'), {
+      wrapper,
+    })
+
+    act(() => {
+      result.current[2]()
+    })
+
+    expect(localStorage.getItem('storyboard:settings.theme')).toBeNull()
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useLocalStorage('settings.theme'))
+    }).toThrow('useLocalStorage must be used within a <StoryboardProvider>')
+  })
+})