@dfosco/storyboard 0.5.0-alpha.0

package/src/internals/context.test.jsx

@@ -0,0 +1,296 @@
+import { render, screen } from '@testing-library/react'
+import { useContext } from 'react'
+import { init } from '../core/index.js'
+import StoryboardProvider, { StoryboardContext } from './context.jsx'
+
+
+const mockUseLocation = vi.fn(() => ({ pathname: '/', search: '', hash: '' }))
+
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom')
+  return {
+    ...actual,
+    useParams: vi.fn(() => ({})),
+    useLocation: (...args) => mockUseLocation(...args),
+  }
+})
+
+beforeEach(() => {
+  init({
+    flows: {
+      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 flow loads successfully', () => {
+    render(
+      <StoryboardProvider>
+        <span>child content</span>
+      </StoryboardProvider>,
+    )
+    expect(screen.getByText('child content')).toBeInTheDocument()
+  })
+
+  it('provides flow data via context', () => {
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
+  })
+
+  it('uses flowName prop when provided', () => {
+    render(
+      <StoryboardProvider flowName="other">
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it('uses sceneName prop for backward compat', () => {
+    render(
+      <StoryboardProvider sceneName="other">
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Other Scene')
+  })
+
+  it("falls back to 'default' flow when no ?scene= param", () => {
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Default Scene')
+  })
+
+  it('shows error message when flow fails to load', () => {
+    render(
+      <StoryboardProvider flowName="nonexistent">
+        <ContextReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByText(/Error loading flow/)).toBeInTheDocument()
+  })
+
+  it('provides flowName in context value', () => {
+    function FlowNameReader() {
+      const ctx = useContext(StoryboardContext)
+      return <span data-testid="name">{ctx?.flowName}</span>
+    }
+    render(
+      <StoryboardProvider flowName="other">
+        <FlowNameReader />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('name')).toHaveTextContent('other')
+  })
+
+  it('provides sceneName (backward compat) in context value', () => {
+    function SceneNameReader() {
+      const ctx = useContext(StoryboardContext)
+      return <span data-testid="name">{ctx?.sceneName}</span>
+    }
+    render(
+      <StoryboardProvider flowName="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')
+  })
+
+  it('auto-matches flow by pathname and resolves $ref data', () => {
+    init({
+      flows: {
+        default: { title: 'Default' },
+        Repositories: {
+          '$global': ['navigation'],
+          heading: 'All repos',
+        },
+      },
+      objects: {
+        navigation: { topnav: [{ label: 'Home' }, { label: 'Repos' }] },
+      },
+      records: {},
+    })
+
+    // Simulate navigating to /base/Repositories
+    mockUseLocation.mockReturnValue({ pathname: '/base/Repositories', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="heading" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('All repos')
+  })
+
+  it('resolves $ref objects when auto-matching flow by pathname', () => {
+    init({
+      flows: {
+        default: { title: 'Default' },
+        Repositories: {
+          '$global': ['navigation'],
+          heading: 'All repos',
+        },
+      },
+      objects: {
+        navigation: { topnav: [{ label: 'Home' }, { label: 'Repos' }] },
+      },
+      records: {},
+    })
+
+    mockUseLocation.mockReturnValue({ pathname: '/base/Repositories', search: '', hash: '' })
+
+    function NavReader() {
+      const ctx = useContext(StoryboardContext)
+      const topnav = ctx?.data?.topnav
+      return <span data-testid="nav">{topnav ? topnav.map(n => n.label).join(',') : 'none'}</span>
+    }
+
+    render(
+      <StoryboardProvider>
+        <NavReader />
+      </StoryboardProvider>,
+    )
+    // $global navigation object should be resolved — topnav merged at root
+    expect(screen.getByTestId('nav')).toHaveTextContent('Home,Repos')
+  })
+
+  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(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </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: {
+        default: { title: 'Global Default' },
+        'Example/example': { title: 'Example Flow' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    // /Example/Forms — no Forms flow exists, should fall back to Example/example
+    mockUseLocation.mockReturnValue({ pathname: '/Example/Forms', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Example Flow')
+  })
+
+  it('page-specific flow takes priority over prototype flow', () => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+        'Example/example': { title: 'Example Flow' },
+        'Example/Forms': { title: 'Forms Flow' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    mockUseLocation.mockReturnValue({ pathname: '/Example/Forms', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Forms Flow')
+  })
+
+  it('falls to global default when no prototype flow exists', () => {
+    init({
+      flows: {
+        default: { title: 'Global Default' },
+      },
+      objects: {},
+      records: {},
+    })
+
+    mockUseLocation.mockReturnValue({ pathname: '/NoProto/SomePage', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader path="title" />
+      </StoryboardProvider>,
+    )
+    expect(screen.getByTestId('ctx')).toHaveTextContent('Global Default')
+  })
+
+  it('shows a simple 404 for unknown canvas routes with an index link', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/canvas/unknown-board', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader />
+      </StoryboardProvider>,
+    )
+
+    expect(screen.getByText('Canvas not found')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /go to index page/i })).toHaveAttribute('href', '/')
+  })
+})

package/src/internals/hashPreserver.js

@@ -0,0 +1,73 @@
+import { interceptHideParams } from '../core/index.js'
+
+/**
+ * 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/internals/hashPreserver.test.js

@@ -0,0 +1,107 @@
+import { installHashPreserver } from './hashPreserver.js'
+
+vi.mock('../core/index.js', async () => {
+  const actual = await vi.importActual('../core/index.js')
+  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/internals/hooks/useConfig.js

@@ -0,0 +1,14 @@
+import { useSyncExternalStore, useCallback } from 'react'
+import { getConfig, subscribeToConfig, getConfigSnapshot } from '../../core/index.js'
+
+/**
+ * React hook for reading from the unified config store.
+ *
+ * @param {string} [domain] - Optional domain key (e.g. 'toolbar', 'canvas')
+ * @returns {object} The config object (full or domain slice)
+ */
+export function useConfig(domain) {
+  const snapshot = useSyncExternalStore(subscribeToConfig, getConfigSnapshot)
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useCallback(() => getConfig(domain), [snapshot, domain])()
+}

package/src/internals/hooks/useFeatureFlag.js

@@ -0,0 +1,14 @@
+import { useSyncExternalStore } from 'react'
+import { getFlag, subscribeToStorage, getStorageSnapshot } from '../../core/index.js'
+
+/**
+ * React hook for reading a feature flag value.
+ * Re-renders when the flag changes (via localStorage).
+ *
+ * @param {string} key - Flag key (without "flag." prefix)
+ * @returns {boolean} Current resolved flag value
+ */
+export function useFeatureFlag(key) {
+  useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
+  return getFlag(key)
+}

package/src/internals/hooks/useFlows.js

@@ -0,0 +1,50 @@
+import { useContext, useMemo, useCallback } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getFlowsForPrototype, resolveFlowRoute } from '../../core/index.js'
+import { getFlowMeta } from '../../core/index.js'
+
+/**
+ * List all flows for the current prototype and switch between them.
+ *
+ * @returns {{
+ *   flows: Array<{ key: string, name: string, title: string, route: string }>,
+ *   activeFlow: string,
+ *   switchFlow: (flowKey: string) => void,
+ *   prototypeName: string | null
+ * }}
+ */
+export function useFlows() {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useFlows must be used within a <StoryboardProvider>')
+  }
+
+  const { flowName: activeFlow, prototypeName } = context
+
+  const flows = useMemo(() => {
+    if (!prototypeName) return []
+    return getFlowsForPrototype(prototypeName).map(f => {
+      const meta = getFlowMeta(f.key)
+      return {
+        key: f.key,
+        name: f.name,
+        title: meta?.title || f.name,
+        route: resolveFlowRoute(f.key),
+      }
+    })
+  }, [prototypeName])
+
+  const switchFlow = useCallback((flowKey) => {
+    const flow = flows.find(f => f.key === flowKey)
+    if (flow) {
+      window.location.href = flow.route
+    }
+  }, [flows])
+
+  return {
+    flows,
+    activeFlow,
+    switchFlow,
+    prototypeName,
+  }
+}

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

@@ -0,0 +1,134 @@
+import { renderHook } from '@testing-library/react'
+import { createElement } from 'react'
+import { init, getFlowsForPrototype } from '../../core/index.js'
+import { useFlows } from './useFlows.js'
+import { StoryboardContext } from '../StoryboardContext.js'
+
+// Test data with prototype-scoped flows
+const SCOPED_FLOWS = {
+  'default': { meta: { title: 'Default' } },
+  'Signup/empty-form': { meta: { title: 'Empty Form' }, _route: '/Signup' },
+  'Signup/validation-errors': { meta: { title: 'Validation Errors' }, _route: '/Signup' },
+  'Signup/prefilled-review': { meta: { title: 'Prefilled Review' }, _route: '/Signup' },
+  'Signup/error-state': { meta: { title: 'Error State' }, _route: '/Signup' },
+  'Example/basic': { meta: { title: 'Example Data Flow' }, _route: '/Example' },
+}
+
+function seedScopedData() {
+  init({ flows: SCOPED_FLOWS, objects: {}, records: {} })
+}
+
+function createWrapperWithPrototype(flowName = 'default', prototypeName = null) {
+  return function Wrapper({ children }) {
+    return createElement(
+      StoryboardContext.Provider,
+      { value: { data: {}, error: null, loading: false, flowName, sceneName: flowName, prototypeName } },
+      children,
+    )
+  }
+}
+
+beforeEach(() => {
+  seedScopedData()
+})
+
+// ── Core utility: getFlowsForPrototype ──
+
+describe('getFlowsForPrototype', () => {
+  it('returns flows scoped to the given prototype', () => {
+    const flows = getFlowsForPrototype('Signup')
+    expect(flows).toHaveLength(4)
+    expect(flows.map(f => f.name)).toEqual([
+      'empty-form', 'validation-errors', 'prefilled-review', 'error-state',
+    ])
+  })
+
+  it('returns the full key with prototype prefix', () => {
+    const flows = getFlowsForPrototype('Signup')
+    expect(flows[0].key).toBe('Signup/empty-form')
+  })
+
+  it('returns empty array for prototype with no flows', () => {
+    const flows = getFlowsForPrototype('NonExistent')
+    expect(flows).toEqual([])
+  })
+
+  it('returns empty array when prototypeName is null', () => {
+    const flows = getFlowsForPrototype(null)
+    expect(flows).toEqual([])
+  })
+
+  it('returns empty array when prototypeName is empty string', () => {
+    const flows = getFlowsForPrototype('')
+    expect(flows).toEqual([])
+  })
+
+  it('excludes global flows (no prototype prefix)', () => {
+    const flows = getFlowsForPrototype('Signup')
+    const keys = flows.map(f => f.key)
+    expect(keys).not.toContain('default')
+  })
+
+  it('returns single flow for prototype with one flow', () => {
+    const flows = getFlowsForPrototype('Example')
+    expect(flows).toHaveLength(1)
+    expect(flows[0].name).toBe('basic')
+  })
+})
+
+// ── useFlows hook ──
+
+describe('useFlows', () => {
+  it('returns flows for the current prototype', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(result.current.flows).toHaveLength(4)
+    expect(result.current.flows[0].title).toBe('Empty Form')
+  })
+
+  it('returns the active flow key', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/validation-errors', 'Signup'),
+    })
+    expect(result.current.activeFlow).toBe('Signup/validation-errors')
+  })
+
+  it('returns prototype name', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(result.current.prototypeName).toBe('Signup')
+  })
+
+  it('returns empty flows when no prototype', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('default', null),
+    })
+    expect(result.current.flows).toEqual([])
+  })
+
+  it('switchFlow is a function', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    expect(typeof result.current.switchFlow).toBe('function')
+  })
+
+  it('flow entries have title from meta', () => {
+    const { result } = renderHook(() => useFlows(), {
+      wrapper: createWrapperWithPrototype('Signup/empty-form', 'Signup'),
+    })
+    const titles = result.current.flows.map(f => f.title)
+    expect(titles).toContain('Empty Form')
+    expect(titles).toContain('Validation Errors')
+    expect(titles).toContain('Prefilled Review')
+    expect(titles).toContain('Error State')
+  })
+
+  it('throws when used outside StoryboardProvider', () => {
+    expect(() => {
+      renderHook(() => useFlows())
+    }).toThrow('useFlows must be used within a <StoryboardProvider>')
+  })
+})