@dfosco/storyboard-core 3.3.1 → 3.4.0

package/src/toolRegistry.js

@@ -0,0 +1,226 @@
+/**
+ * Tool Registry — config-driven state management for toolbar tools.
+ *
+ * Every tool is declared in toolbar.config.json under the `tools` key.
+ * Each tool specifies a `toolbar` target (main-toolbar, secondary-toolbar,
+ * command-list) and a `render` type (button, menu, sidepanel, submenu, link).
+ *
+ * Code modules register themselves via registerToolModule() to provide
+ * component, handler, setup, and guard functions.
+ *
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/** @type {Record<string, object>} tool id → config from toolbar.config.json */
+let _toolConfigs = {}
+
+/** @type {Map<string, object>} tool id → code module { component?, handler?, setup?, guard? } */
+const _modules = new Map()
+
+/** @type {Map<string, any>} tool id → resolved component (after lazy loading) */
+const _components = new Map()
+
+/** @type {Map<string, boolean>} tool id → guard result */
+const _guardResults = new Map()
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed the registry from toolbar config.
+ * Called once at app startup.
+ *
+ * @param {object} config - The full toolbar config object
+ */
+export function initToolRegistry(config) {
+  if (config.tools) {
+    _toolConfigs = { ...config.tools }
+  }
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Module registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a code module for a declared tool.
+ *
+ * @param {string} id - Tool id (matches key in toolbar.config.json tools)
+ * @param {object} mod
+ * @param {Function} [mod.component] - () => import('./SomeComponent.svelte')
+ * @param {object|Function} [mod.handler] - Command action handler
+ * @param {Function} [mod.setup] - async (ctx) => void — called once at mount
+ * @param {Function} [mod.guard] - async (ctx) => boolean — return false to hide
+ */
+export function registerToolModule(id, mod) {
+  _modules.set(id, mod)
+  _notify()
+}
+
+/**
+ * Store a resolved component for a tool (after lazy loading).
+ *
+ * @param {string} id
+ * @param {any} component
+ */
+export function setToolComponent(id, component) {
+  _components.set(id, component)
+  _notify()
+}
+
+/**
+ * Store a guard result for a tool.
+ *
+ * @param {string} id
+ * @param {boolean} result
+ */
+export function setToolGuardResult(id, result) {
+  _guardResults.set(id, result)
+  _notify()
+}
+
+/**
+ * Get the resolved component for a tool.
+ *
+ * @param {string} id
+ * @returns {any|null}
+ */
+export function getToolComponent(id) {
+  return _components.get(id) || null
+}
+
+/**
+ * Get the code module for a tool.
+ *
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function getToolModule(id) {
+  return _modules.get(id) || null
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Get tools for a specific toolbar target, filtered by mode and visibility.
+ *
+ * @param {string} toolbar - "main-toolbar" | "secondary-toolbar" | "command-list"
+ * @param {string} mode - Current mode name
+ * @param {object} [options]
+ * @param {boolean} [options.isLocalDev] - Whether running in local dev
+ * @returns {Array<{ id: string, config: object, module: object|null, component: any|null }>}
+ */
+export function getToolsForToolbar(toolbar, mode, options = {}) {
+  const { isLocalDev = false } = options
+  const results = []
+
+  for (const [id, config] of Object.entries(_toolConfigs)) {
+    if (config.toolbar !== toolbar) continue
+    if (config.localOnly && !isLocalDev) continue
+    if (!isToolVisibleInMode(config, mode)) continue
+
+    // Check guard result if one was registered
+    if (_guardResults.has(id) && !_guardResults.get(id)) continue
+
+    results.push({
+      id,
+      config,
+      module: _modules.get(id) || null,
+      component: _components.get(id) || null,
+    })
+  }
+
+  return results
+}
+
+/**
+ * Get the config for a specific tool.
+ *
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function getToolConfig(id) {
+  return _toolConfigs[id] || null
+}
+
+/**
+ * Get all tool configs.
+ *
+ * @returns {Record<string, object>}
+ */
+export function getAllToolConfigs() {
+  return { ..._toolConfigs }
+}
+
+/**
+ * Check if a tool is visible in a given mode.
+ *
+ * @param {object} config - Tool config
+ * @param {string} mode - Current mode name
+ * @returns {boolean}
+ */
+function isToolVisibleInMode(config, mode) {
+  const modes = config.modes
+  if (!modes) return true
+  return modes.includes('*') || modes.includes(mode)
+}
+
+// ---------------------------------------------------------------------------
+// Reactivity
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to registry changes. Compatible with useSyncExternalStore.
+ *
+ * @param {Function} callback
+ * @returns {Function} Unsubscribe
+ */
+export function subscribeToToolRegistry(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot for useSyncExternalStore.
+ *
+ * @returns {string}
+ */
+export function getToolRegistrySnapshot() {
+  return String(_snapshotVersion)
+}
+
+function _notify() {
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb() } catch (err) {
+      console.error('[storyboard] Error in tool registry subscriber:', err)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/** Reset all state. Only for tests. */
+export function _resetToolRegistry() {
+  _toolConfigs = {}
+  _modules.clear()
+  _components.clear()
+  _guardResults.clear()
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/toolStateStore.js

@@ -0,0 +1,180 @@
+/**
+ * Tool State Store — runtime state management for toolbar tools.
+ *
+ * Each tool declared in toolbar.config.json can be in one of five states:
+ *   active    — Normal, clickable (default)
+ *   inactive  — Visible but unclickable, disabled-looking (also for errors)
+ *   hidden    — Invisible but shortcuts still work, tool is loaded
+ *   dimmed    — Visible but dimmed opacity, still clickable
+ *   disabled  — Completely removed, not loaded on FE
+ *
+ * Tools default to "active" unless:
+ *   1. Config declares a "state" property
+ *   2. The tool is localOnly and the environment is not local dev → "disabled"
+ *
+ * State can be changed at runtime by application code via setToolbarToolState().
+ * Framework-agnostic (zero npm dependencies).
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** All valid tool states. */
+export const TOOL_STATES = Object.freeze({
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+  HIDDEN: 'hidden',
+  DIMMED: 'dimmed',
+  DISABLED: 'disabled',
+})
+
+const VALID_STATES = new Set(Object.values(TOOL_STATES))
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/** @type {Map<string, string>} tool id → state */
+let _states = new Map()
+
+/** @type {Map<string, boolean>} tool id → localOnly flag */
+let _localOnlyFlags = new Map()
+
+/** @type {Set<Function>} */
+const _listeners = new Set()
+
+let _snapshotVersion = 0
+
+// ---------------------------------------------------------------------------
+// Initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed tool states from toolbar.config.json's `tools` object.
+ * Called once at app startup.
+ *
+ * @param {object} toolsConfig - The `tools` object from toolbar.config.json
+ *   (keys are tool IDs, values are tool config objects)
+ * @param {{ isLocalDev?: boolean }} [options]
+ */
+export function initToolbarToolStates(toolsConfig, options = {}) {
+  const { isLocalDev = false } = options
+
+  _states = new Map()
+  _localOnlyFlags = new Map()
+
+  if (!toolsConfig || typeof toolsConfig !== 'object') {
+    _notify()
+    return
+  }
+
+  for (const [id, tool] of Object.entries(toolsConfig)) {
+    const isLocalOnly = tool.localOnly === true
+    _localOnlyFlags.set(id, isLocalOnly)
+
+    if (isLocalOnly && !isLocalDev) {
+      _states.set(id, TOOL_STATES.DISABLED)
+    } else {
+      const state = tool.state || TOOL_STATES.ACTIVE
+      _states.set(id, state)
+    }
+  }
+
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Runtime state changes
+// ---------------------------------------------------------------------------
+
+/**
+ * Set state for a tool at runtime.
+ * Validates that the state is one of the 5 valid values.
+ *
+ * @param {string} id    Tool id
+ * @param {string} state One of: active, inactive, hidden, dimmed, disabled
+ */
+export function setToolbarToolState(id, state) {
+  if (!VALID_STATES.has(state)) {
+    console.warn(`[storyboard] Invalid tool state "${state}" for tool "${id}". Valid states: ${[...VALID_STATES].join(', ')}`)
+    return
+  }
+  _states.set(id, state)
+  _notify()
+}
+
+// ---------------------------------------------------------------------------
+// Access
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the current state for a tool.
+ * Returns "active" for unknown tool IDs (safe default).
+ *
+ * @param {string} id Tool id
+ * @returns {string}
+ */
+export function getToolbarToolState(id) {
+  return _states.get(id) || TOOL_STATES.ACTIVE
+}
+
+/**
+ * Returns whether the tool was marked localOnly in config.
+ * Returns false for unknown IDs.
+ *
+ * @param {string} id Tool id
+ * @returns {boolean}
+ */
+export function isToolbarToolLocalOnly(id) {
+  return _localOnlyFlags.get(id) || false
+}
+
+// ---------------------------------------------------------------------------
+// Reactivity
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to tool state changes. Compatible with useSyncExternalStore.
+ *
+ * @param {Function} callback
+ * @returns {Function} Unsubscribe
+ */
+export function subscribeToToolbarToolStates(callback) {
+  _listeners.add(callback)
+  return () => _listeners.delete(callback)
+}
+
+/**
+ * Snapshot for useSyncExternalStore.
+ *
+ * @returns {string}
+ */
+export function getToolbarToolStatesSnapshot() {
+  return String(_snapshotVersion)
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function _notify() {
+  _snapshotVersion++
+  for (const cb of _listeners) {
+    try { cb() } catch (err) {
+      console.error('[storyboard] Error in tool state subscriber:', err)
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/** Reset all state. Only for tests. */
+export function _resetToolbarToolStates() {
+  _states = new Map()
+  _localOnlyFlags = new Map()
+  _listeners.clear()
+  _snapshotVersion = 0
+}

package/src/toolStateStore.test.js

@@ -0,0 +1,204 @@
+import {
+  TOOL_STATES,
+  initToolbarToolStates,
+  setToolbarToolState,
+  getToolbarToolState,
+  isToolbarToolLocalOnly,
+  subscribeToToolbarToolStates,
+  getToolbarToolStatesSnapshot,
+  _resetToolbarToolStates,
+} from './toolStateStore.js'
+
+afterEach(() => {
+  _resetToolbarToolStates()
+})
+
+describe('toolStateStore', () => {
+  describe('TOOL_STATES', () => {
+    it('exports all 5 state constants', () => {
+      expect(TOOL_STATES.ACTIVE).toBe('active')
+      expect(TOOL_STATES.INACTIVE).toBe('inactive')
+      expect(TOOL_STATES.HIDDEN).toBe('hidden')
+      expect(TOOL_STATES.DIMMED).toBe('dimmed')
+      expect(TOOL_STATES.DISABLED).toBe('disabled')
+      expect(Object.keys(TOOL_STATES)).toHaveLength(5)
+    })
+  })
+
+  describe('getToolbarToolState', () => {
+    it('returns "active" for unknown tool IDs', () => {
+      expect(getToolbarToolState('nonexistent')).toBe('active')
+    })
+
+    it('returns "active" after init with no state in config', () => {
+      initToolbarToolStates({ myTool: {} })
+      expect(getToolbarToolState('myTool')).toBe('active')
+    })
+  })
+
+  describe('initToolbarToolStates', () => {
+    it('seeds states from config', () => {
+      initToolbarToolStates({
+        inspector: { state: 'hidden' },
+        comments: { state: 'dimmed' },
+      })
+      expect(getToolbarToolState('inspector')).toBe('hidden')
+      expect(getToolbarToolState('comments')).toBe('dimmed')
+    })
+
+    it('defaults to active when no state specified', () => {
+      initToolbarToolStates({ inspector: { render: 'panel' } })
+      expect(getToolbarToolState('inspector')).toBe('active')
+    })
+
+    it('reads state from config when specified', () => {
+      initToolbarToolStates({ inspector: { state: 'inactive' } })
+      expect(getToolbarToolState('inspector')).toBe('inactive')
+    })
+
+    it('localOnly + !isLocalDev → disabled (overrides config state)', () => {
+      initToolbarToolStates(
+        { devTool: { localOnly: true, state: 'active' } },
+        { isLocalDev: false },
+      )
+      expect(getToolbarToolState('devTool')).toBe('disabled')
+    })
+
+    it('localOnly + isLocalDev → uses config state (active by default)', () => {
+      initToolbarToolStates(
+        { devTool: { localOnly: true } },
+        { isLocalDev: true },
+      )
+      expect(getToolbarToolState('devTool')).toBe('active')
+    })
+
+    it('handles empty config', () => {
+      initToolbarToolStates({})
+      expect(getToolbarToolState('anything')).toBe('active')
+    })
+
+    it('replaces previous state on re-init', () => {
+      initToolbarToolStates({ inspector: { state: 'hidden' } })
+      expect(getToolbarToolState('inspector')).toBe('hidden')
+
+      initToolbarToolStates({ inspector: { state: 'dimmed' } })
+      expect(getToolbarToolState('inspector')).toBe('dimmed')
+    })
+  })
+
+  describe('setToolbarToolState', () => {
+    it('updates state for a known tool', () => {
+      initToolbarToolStates({ inspector: {} })
+      setToolbarToolState('inspector', 'hidden')
+      expect(getToolbarToolState('inspector')).toBe('hidden')
+    })
+
+    it('updates state for unknown tool (creates entry)', () => {
+      setToolbarToolState('newTool', 'dimmed')
+      expect(getToolbarToolState('newTool')).toBe('dimmed')
+    })
+
+    it('warns on invalid state value', () => {
+      const spy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      setToolbarToolState('inspector', 'bogus')
+      expect(spy).toHaveBeenCalledOnce()
+      expect(spy.mock.calls[0][0]).toContain('Invalid tool state')
+      spy.mockRestore()
+    })
+
+    it('notifies subscribers on change', () => {
+      const cb = vi.fn()
+      subscribeToToolbarToolStates(cb)
+      initToolbarToolStates({ inspector: {} })
+      const callsBefore = cb.mock.calls.length
+
+      setToolbarToolState('inspector', 'inactive')
+      expect(cb).toHaveBeenCalledTimes(callsBefore + 1)
+    })
+  })
+
+  describe('isToolbarToolLocalOnly', () => {
+    it('returns true for localOnly tools', () => {
+      initToolbarToolStates(
+        { devTool: { localOnly: true } },
+        { isLocalDev: true },
+      )
+      expect(isToolbarToolLocalOnly('devTool')).toBe(true)
+    })
+
+    it('returns false for non-localOnly tools', () => {
+      initToolbarToolStates({ inspector: {} })
+      expect(isToolbarToolLocalOnly('inspector')).toBe(false)
+    })
+
+    it('returns false for unknown tools', () => {
+      expect(isToolbarToolLocalOnly('nonexistent')).toBe(false)
+    })
+  })
+
+  describe('subscribeToToolbarToolStates', () => {
+    it('calls callback on state changes', () => {
+      const cb = vi.fn()
+      subscribeToToolbarToolStates(cb)
+      initToolbarToolStates({ inspector: {} })
+      expect(cb).toHaveBeenCalled()
+    })
+
+    it('returns working unsubscribe function', () => {
+      const cb = vi.fn()
+      const unsub = subscribeToToolbarToolStates(cb)
+      unsub()
+
+      initToolbarToolStates({ inspector: {} })
+      expect(cb).not.toHaveBeenCalled()
+    })
+
+    it('supports multiple subscribers', () => {
+      const cb1 = vi.fn()
+      const cb2 = vi.fn()
+      subscribeToToolbarToolStates(cb1)
+      subscribeToToolbarToolStates(cb2)
+
+      initToolbarToolStates({ inspector: {} })
+      expect(cb1).toHaveBeenCalled()
+      expect(cb2).toHaveBeenCalled()
+    })
+  })
+
+  describe('getToolbarToolStatesSnapshot', () => {
+    it('returns string', () => {
+      expect(typeof getToolbarToolStatesSnapshot()).toBe('string')
+    })
+
+    it('changes on mutation', () => {
+      const before = getToolbarToolStatesSnapshot()
+      initToolbarToolStates({ inspector: {} })
+      const after = getToolbarToolStatesSnapshot()
+      expect(after).not.toBe(before)
+    })
+
+    it('does not change without mutation', () => {
+      const a = getToolbarToolStatesSnapshot()
+      const b = getToolbarToolStatesSnapshot()
+      expect(a).toBe(b)
+    })
+  })
+
+  describe('_resetToolbarToolStates', () => {
+    it('clears all state', () => {
+      initToolbarToolStates({ inspector: { state: 'hidden', localOnly: true } }, { isLocalDev: true })
+      _resetToolbarToolStates()
+      expect(getToolbarToolState('inspector')).toBe('active')
+      expect(isToolbarToolLocalOnly('inspector')).toBe(false)
+    })
+
+    it('clears all listeners', () => {
+      const cb = vi.fn()
+      subscribeToToolbarToolStates(cb)
+      _resetToolbarToolStates()
+
+      initToolbarToolStates({ inspector: {} })
+      expect(cb).not.toHaveBeenCalled()
+    })
+  })
+})