@dfosco/storyboard 0.5.0-alpha.0

package/src/core/stores/paletteProviders.js

@@ -0,0 +1,360 @@
+/**
+ * Palette Providers — adapters that produce searchable items for the command palette.
+ *
+ * Each provider returns an array of palette items:
+ *   { id, label, category, icon?, action: () => void }
+ *
+ * Providers cache their datasets on palette open. Only fuzzy scoring runs per keystroke.
+ */
+
+import { buildPrototypeIndex } from '../data/viewfinder.js'
+import { listStories, getStoryData } from '../data/loader.js'
+import { getActionsForMode, executeAction, getActionChildren } from './commandActions.js'
+import { getToolbarToolState } from './toolStateStore.js'
+import { getRecent, trackRecent } from './recentArtifacts.js'
+import { fuzzySearch } from '../utils/fuzzySearch.js'
+
+// ---------------------------------------------------------------------------
+// Palette item factory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} PaletteItem
+ * @property {string}   id        — unique within provider
+ * @property {string}   label     — display text (also used for fuzzy matching)
+ * @property {string}   category  — group header in results
+ * @property {string}   [icon]    — optional icon name
+ * @property {boolean}  [localOnly]
+ * @property {string}   [hint]    — secondary text (e.g. folder name)
+ * @property {Function} action    — called when the item is selected
+ */
+
+// ---------------------------------------------------------------------------
+// Provider: Commands
+// ---------------------------------------------------------------------------
+
+/**
+ * Build command items from the resolved action registry.
+ * Flattens submenus so their children appear as individual items.
+ *
+ * @param {string} mode — current mode name
+ * @param {string} basePath
+ * @returns {PaletteItem[]}
+ */
+export function buildCommandItems(mode, basePath) {
+  const actions = getActionsForMode(mode)
+  const items = []
+
+  for (const action of actions) {
+    // Skip structural items
+    if (action.type === 'header' || action.type === 'separator' || action.type === 'footer') continue
+
+    // Skip hidden/disabled tools
+    if (action.toolKey) {
+      const state = getToolbarToolState(action.toolKey)
+      if (state === 'disabled' || state === 'hidden') continue
+    }
+
+    // Skip items hidden from search
+    if (action.hideFromCommandPaletteSearch) continue
+
+    if (action.type === 'submenu') {
+      // Flatten submenu children into individual items
+      const children = getActionChildren(action.id)
+      for (const child of children) {
+        items.push({
+          id: `cmd:${action.id}/${child.id || child.label}`,
+          label: child.label,
+          category: 'Commands',
+          hint: action.label,
+          localOnly: action.localOnly,
+          action: () => { if (child.execute) child.execute() },
+        })
+      }
+    } else if (action.type === 'toggle') {
+      items.push({
+        id: `cmd:${action.id}`,
+        label: `${action.label}${action.active ? ' ✓' : ''}`,
+        category: 'Commands',
+        localOnly: action.localOnly,
+        action: () => executeAction(action.id),
+      })
+    } else if (action.type === 'link' && action.url) {
+      items.push({
+        id: `cmd:${action.id}`,
+        label: action.label,
+        category: 'Commands',
+        localOnly: action.localOnly,
+        action: () => {
+          if (action.url.startsWith('/') && !action.url.startsWith('//')) {
+            const base = (basePath || '/').replace(/\/+$/, '')
+            window.location.href = (base === '/' ? '' : base) + action.url
+          } else {
+            window.location.href = action.url
+          }
+        },
+      })
+    } else {
+      items.push({
+        id: `cmd:${action.id}`,
+        label: action.label,
+        category: 'Commands',
+        localOnly: action.localOnly,
+        action: () => executeAction(action.id),
+      })
+    }
+  }
+
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// Provider: Prototypes
+// ---------------------------------------------------------------------------
+
+/**
+ * Build prototype items from the viewfinder index.
+ *
+ * @param {string} basePath
+ * @returns {PaletteItem[]}
+ */
+export function buildPrototypeItems(basePath) {
+  const index = buildPrototypeIndex()
+  const items = []
+  const base = (basePath || '/').replace(/\/+$/, '')
+
+  function addProto(proto) {
+    if (proto.isExternal) {
+      items.push({
+        id: `proto:${proto.dirName}`,
+        label: proto.name,
+        category: 'Prototypes',
+        hint: proto.folder || undefined,
+        action: () => {
+          trackRecent('prototype', proto.dirName, proto.name)
+          window.open(proto.externalUrl, '_blank')
+        },
+      })
+    } else {
+      const route = (base === '/' ? '' : base) + '/' + proto.dirName
+      items.push({
+        id: `proto:${proto.dirName}`,
+        label: proto.name,
+        category: 'Prototypes',
+        hint: proto.folder || undefined,
+        action: () => {
+          trackRecent('prototype', proto.dirName, proto.name)
+          window.location.href = route
+        },
+      })
+    }
+  }
+
+  // Ungrouped prototypes
+  for (const proto of index.prototypes) addProto(proto)
+
+  // Folder prototypes
+  for (const folder of index.folders) {
+    for (const proto of folder.prototypes) addProto(proto)
+  }
+
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// Provider: Canvases
+// ---------------------------------------------------------------------------
+
+/**
+ * Build canvas items from the viewfinder index.
+ *
+ * @param {string} basePath
+ * @returns {PaletteItem[]}
+ */
+export function buildCanvasItems(basePath) {
+  const index = buildPrototypeIndex()
+  const items = []
+  const base = (basePath || '/').replace(/\/+$/, '')
+
+  function addCanvas(canvas) {
+    const route = (base === '/' ? '' : base) + canvas.route
+    items.push({
+      id: `canvas:${canvas.dirName}`,
+      label: canvas.name,
+      category: 'Canvases',
+      hint: canvas.folder || undefined,
+      action: () => {
+        trackRecent('canvas', canvas.dirName, canvas.name)
+        window.location.href = route
+      },
+    })
+  }
+
+  // Ungrouped canvases
+  for (const canvas of index.canvases) addCanvas(canvas)
+
+  // Folder canvases
+  for (const folder of index.folders) {
+    if (folder.canvases) {
+      for (const canvas of folder.canvases) addCanvas(canvas)
+    }
+  }
+
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// Provider: Stories
+// ---------------------------------------------------------------------------
+
+/**
+ * Build story items from the data index.
+ *
+ * @param {string} basePath
+ * @returns {PaletteItem[]}
+ */
+export function buildStoryItems(basePath) {
+  const names = listStories()
+  const items = []
+  const base = (basePath || '/').replace(/\/+$/, '')
+
+  for (const name of names) {
+    const data = getStoryData(name)
+    if (!data) continue
+    const route = data._route || `/components/${name}`
+    items.push({
+      id: `story:${name}`,
+      label: name,
+      category: 'Stories',
+      action: () => {
+        trackRecent('story', name, name)
+        window.location.href = (base === '/' ? '' : base) + route
+      },
+    })
+  }
+
+  return items
+}
+
+// ---------------------------------------------------------------------------
+// Provider: Recent
+// ---------------------------------------------------------------------------
+
+/**
+ * Build recent items from localStorage.
+ * Derives routes at read time for correctness across branches.
+ *
+ * @param {string} basePath
+ * @returns {PaletteItem[]}
+ */
+export function buildRecentItems(basePath) {
+  const recent = getRecent()
+  const base = (basePath || '/').replace(/\/+$/, '')
+
+  return recent.map(entry => ({
+    id: `recent:${entry.type}:${entry.key}`,
+    label: entry.label,
+    category: 'Recent',
+    hint: entry.type,
+    action: () => {
+      // Re-track to bump to top
+      trackRecent(entry.type, entry.key, entry.label)
+      const route = resolveRecentRoute(entry, base)
+      if (route) window.location.href = route
+    },
+  }))
+}
+
+/**
+ * Derive a route for a recent entry from the live data index.
+ */
+function resolveRecentRoute(entry, base) {
+  const prefix = base === '/' ? '' : base
+  switch (entry.type) {
+    case 'prototype':
+      return `${prefix}/${entry.key}`
+    case 'canvas':
+      return `${prefix}/canvas/${entry.key}`
+    case 'story': {
+      const data = getStoryData(entry.key)
+      const route = data?._route || `/components/${entry.key}`
+      return `${prefix}${route}`
+    }
+    default:
+      return null
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Palette search — runs all providers against a query
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} PaletteDataset
+ * @property {PaletteItem[]} commands
+ * @property {PaletteItem[]} prototypes
+ * @property {PaletteItem[]} canvases
+ * @property {PaletteItem[]} stories
+ * @property {PaletteItem[]} recent
+ */
+
+/**
+ * Build all provider datasets. Call once per palette open, cache the result.
+ *
+ * @param {string} mode
+ * @param {string} basePath
+ * @returns {PaletteDataset}
+ */
+export function buildAllItems(mode, basePath) {
+  return {
+    commands: buildCommandItems(mode, basePath),
+    prototypes: buildPrototypeItems(basePath),
+    canvases: buildCanvasItems(basePath),
+    stories: buildStoryItems(basePath),
+    recent: buildRecentItems(basePath),
+  }
+}
+
+/**
+ * Search across all cached datasets.
+ *
+ * @param {PaletteDataset} dataset — cached from buildAllItems
+ * @param {string} query
+ * @returns {{ category: string, items: PaletteItem[] }[]}
+ */
+export function searchPalette(dataset, query) {
+  const q = query.trim()
+
+  if (!q) {
+    // Empty query: show recent (if any), then commands
+    const groups = []
+    if (dataset.recent.length > 0) {
+      groups.push({ category: 'Recent', items: dataset.recent.slice(0, 5) })
+    }
+    if (dataset.commands.length > 0) {
+      groups.push({ category: 'Commands', items: dataset.commands })
+    }
+    return groups
+  }
+
+  // Search each category independently
+  const categories = [
+    { key: 'commands', label: 'Commands', max: 5 },
+    { key: 'prototypes', label: 'Prototypes', max: 8 },
+    { key: 'canvases', label: 'Canvases', max: 8 },
+    { key: 'stories', label: 'Stories', max: 5 },
+  ]
+
+  const groups = []
+  for (const cat of categories) {
+    const results = fuzzySearch(dataset[cat.key], q, { maxResults: cat.max })
+    if (results.length > 0) {
+      groups.push({
+        category: cat.label,
+        items: results.map(r => r.item),
+      })
+    }
+  }
+
+  return groups
+}

package/src/core/stores/paletteProviders.test.js

@@ -0,0 +1,186 @@
+import { describe, it, expect, vi } from 'vitest'
+
+// Mock loader and workspace before importing providers
+vi.mock('../data/loader.js', () => ({
+  listStories: vi.fn(() => ['button', 'card']),
+  getStoryData: vi.fn((name) => ({
+    button: { _route: '/components/button', _storyModule: '/src/button.story.jsx' },
+    card: { _route: '/components/card', _storyModule: '/src/card.story.jsx' },
+  })[name] || null),
+  listFlows: vi.fn(() => ['MyProto/default', 'MyProto/dark', 'global-flow']),
+  loadFlow: vi.fn((name) => ({
+    'MyProto/default': { _route: '/MyProto', meta: { default: true } },
+    'MyProto/dark': { _route: '/MyProto', meta: {} },
+    'global-flow': { _route: '/', meta: {} },
+  })[name] || null),
+  listPrototypes: vi.fn(() => ['MyProto', 'ExternalApp']),
+  getPrototypeMetadata: vi.fn((name) => ({
+    MyProto: { meta: { title: 'My Prototype', author: 'alice' }, folder: null },
+    ExternalApp: { meta: { title: 'External App' }, url: 'https://example.com', folder: null },
+  })[name] || null),
+  listFolders: vi.fn(() => []),
+  getFolderMetadata: vi.fn(() => null),
+  listCanvases: vi.fn(() => ['design-overview']),
+  getCanvasData: vi.fn((name) => ({
+    'design-overview': {
+      title: 'Design Overview',
+      _route: '/canvas/design-overview',
+      _canvasMeta: { title: 'Design Overview' },
+      _group: null,
+      _folder: null,
+    },
+  })[name] || null),
+}))
+
+vi.mock('./commandActions.js', () => ({
+  getActionsForMode: vi.fn(() => [
+    { id: 'core/workspace', label: 'Go to Workspace', type: 'link', url: '/', toolKey: 'workspace' },
+    { id: 'core/docs', label: 'Documentation', type: 'default', toolKey: 'docs' },
+    { id: 'core/devtools', label: 'DevTools', type: 'submenu', toolKey: 'devtools' },
+    { type: 'header', label: 'Command Menu' },
+    { type: 'footer', label: '⌘ + K to open' },
+  ]),
+  executeAction: vi.fn(),
+  getActionChildren: vi.fn((id) => {
+    if (id === 'core/devtools') {
+      return [
+        { id: 'devtools:inspector', label: 'Inspector', execute: vi.fn() },
+        { id: 'devtools:network', label: 'Network', execute: vi.fn() },
+      ]
+    }
+    return []
+  }),
+}))
+
+vi.mock('./toolStateStore.js', () => ({
+  getToolbarToolState: vi.fn(() => 'active'),
+  isToolbarToolLocalOnly: vi.fn(() => false),
+}))
+
+vi.mock('./recentArtifacts.js', () => ({
+  getRecent: vi.fn(() => [
+    { type: 'prototype', key: 'MyProto', label: 'My Prototype' },
+  ]),
+  trackRecent: vi.fn(),
+  clearRecent: vi.fn(),
+}))
+
+import {
+  buildCommandItems,
+  buildPrototypeItems,
+  buildCanvasItems,
+  buildStoryItems,
+  buildRecentItems,
+  buildAllItems,
+  searchPalette,
+} from './paletteProviders.js'
+
+describe('buildCommandItems', () => {
+  it('produces items from resolved actions', () => {
+    const items = buildCommandItems('default', '/')
+    expect(items.length).toBeGreaterThan(0)
+    expect(items.every(i => i.category === 'Commands')).toBe(true)
+  })
+
+  it('skips structural items (header, separator, footer)', () => {
+    const items = buildCommandItems('default', '/')
+    expect(items.some(i => i.label === 'Command Menu')).toBe(false)
+    expect(items.some(i => i.label === '⌘ + K to open')).toBe(false)
+  })
+
+  it('flattens submenu children into individual items', () => {
+    const items = buildCommandItems('default', '/')
+    expect(items.some(i => i.label === 'Inspector')).toBe(true)
+    expect(items.some(i => i.label === 'Network')).toBe(true)
+    // The submenu parent should not appear as its own item
+    expect(items.some(i => i.label === 'DevTools')).toBe(false)
+  })
+
+  it('items have executable actions', () => {
+    const items = buildCommandItems('default', '/')
+    for (const item of items) {
+      expect(typeof item.action).toBe('function')
+    }
+  })
+})
+
+describe('buildPrototypeItems', () => {
+  it('includes prototypes from the index', () => {
+    const items = buildPrototypeItems('/')
+    expect(items.some(i => i.label === 'My Prototype')).toBe(true)
+  })
+
+  it('handles external prototypes', () => {
+    const items = buildPrototypeItems('/')
+    const ext = items.find(i => i.label === 'External App')
+    expect(ext).toBeDefined()
+  })
+
+  it('sets category to Prototypes', () => {
+    const items = buildPrototypeItems('/')
+    expect(items.every(i => i.category === 'Prototypes')).toBe(true)
+  })
+})
+
+describe('buildCanvasItems', () => {
+  it('includes canvases from the index', () => {
+    const items = buildCanvasItems('/')
+    expect(items.some(i => i.label === 'Design Overview')).toBe(true)
+  })
+
+  it('sets category to Canvases', () => {
+    const items = buildCanvasItems('/')
+    expect(items.every(i => i.category === 'Canvases')).toBe(true)
+  })
+})
+
+describe('buildStoryItems', () => {
+  it('includes stories from the data index', () => {
+    const items = buildStoryItems('/')
+    expect(items).toHaveLength(2)
+    expect(items.some(i => i.label === 'button')).toBe(true)
+    expect(items.some(i => i.label === 'card')).toBe(true)
+  })
+
+  it('sets category to Stories', () => {
+    const items = buildStoryItems('/')
+    expect(items.every(i => i.category === 'Stories')).toBe(true)
+  })
+})
+
+describe('buildRecentItems', () => {
+  it('includes recent entries', () => {
+    const items = buildRecentItems('/')
+    expect(items).toHaveLength(1)
+    expect(items[0].label).toBe('My Prototype')
+  })
+
+  it('sets category to Recent', () => {
+    const items = buildRecentItems('/')
+    expect(items.every(i => i.category === 'Recent')).toBe(true)
+  })
+})
+
+describe('searchPalette', () => {
+  it('shows recent + commands for empty query', () => {
+    const dataset = buildAllItems('default', '/')
+    const groups = searchPalette(dataset, '')
+    expect(groups[0].category).toBe('Recent')
+    expect(groups[1].category).toBe('Commands')
+  })
+
+  it('filters results by query', () => {
+    const dataset = buildAllItems('default', '/')
+    const groups = searchPalette(dataset, 'button')
+    // Should find the story
+    const storyGroup = groups.find(g => g.category === 'Stories')
+    expect(storyGroup).toBeDefined()
+    expect(storyGroup.items.some(i => i.label === 'button')).toBe(true)
+  })
+
+  it('returns empty groups when nothing matches', () => {
+    const dataset = buildAllItems('default', '/')
+    const groups = searchPalette(dataset, 'zzzznonexistent')
+    expect(groups).toHaveLength(0)
+  })
+})

package/src/core/stores/plugins.js

@@ -0,0 +1,40 @@
+/**
+ * Plugin configuration — enable/disable storyboard plugins.
+ *
+ * Plugins are enabled by default. The config is read from
+ * storyboard.config.json under the "plugins" key and injected
+ * at build time by the Vite data plugin.
+ *
+ * Example config:
+ *   { "plugins": { "devtools": false } }
+ */
+
+let _plugins = {}
+
+/**
+ * Initialize plugin configuration.
+ * Called by the Vite data plugin's generated virtual module.
+ * @param {Record<string, boolean>} config
+ */
+export function initPlugins(config) {
+  _plugins = { ...config }
+}
+
+/**
+ * Check whether a plugin is enabled.
+ * Returns true by default if the plugin is not explicitly configured.
+ * @param {string} name - Plugin name (e.g. "devtools", "comments")
+ * @returns {boolean}
+ */
+export function isPluginEnabled(name) {
+  if (name in _plugins) return Boolean(_plugins[name])
+  return true
+}
+
+/**
+ * Get the full plugins config (for diagnostics / testing).
+ * @returns {Record<string, boolean>}
+ */
+export function getPluginsConfig() {
+  return { ..._plugins }
+}

package/src/core/stores/plugins.test.js

@@ -0,0 +1,68 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { initPlugins, isPluginEnabled, getPluginsConfig } from './plugins.js'
+
+describe('plugins config', () => {
+  beforeEach(() => {
+    // Reset to empty config between tests
+    initPlugins({})
+  })
+
+  describe('isPluginEnabled', () => {
+    it('returns true by default for unconfigured plugins', () => {
+      expect(isPluginEnabled('devtools')).toBe(true)
+      expect(isPluginEnabled('comments')).toBe(true)
+      expect(isPluginEnabled('anything')).toBe(true)
+    })
+
+    it('returns false when a plugin is explicitly disabled', () => {
+      initPlugins({ devtools: false })
+      expect(isPluginEnabled('devtools')).toBe(false)
+    })
+
+    it('returns true when a plugin is explicitly enabled', () => {
+      initPlugins({ devtools: true })
+      expect(isPluginEnabled('devtools')).toBe(true)
+    })
+
+    it('handles multiple plugins independently', () => {
+      initPlugins({ devtools: false, comments: true })
+      expect(isPluginEnabled('devtools')).toBe(false)
+      expect(isPluginEnabled('comments')).toBe(true)
+      expect(isPluginEnabled('other')).toBe(true)
+    })
+  })
+
+  describe('getPluginsConfig', () => {
+    it('returns an empty object by default', () => {
+      expect(getPluginsConfig()).toEqual({})
+    })
+
+    it('returns a copy of the config', () => {
+      initPlugins({ devtools: false })
+      const config = getPluginsConfig()
+      expect(config).toEqual({ devtools: false })
+
+      // Mutating the returned object should not affect internal state
+      config.devtools = true
+      expect(isPluginEnabled('devtools')).toBe(false)
+    })
+  })
+
+  describe('initPlugins', () => {
+    it('replaces previous config on re-init', () => {
+      initPlugins({ devtools: false })
+      expect(isPluginEnabled('devtools')).toBe(false)
+
+      initPlugins({ devtools: true })
+      expect(isPluginEnabled('devtools')).toBe(true)
+    })
+
+    it('does not mutate the passed config object', () => {
+      const config = { devtools: false }
+      initPlugins(config)
+      // Internal state is a copy
+      expect(getPluginsConfig()).toEqual({ devtools: false })
+      expect(getPluginsConfig()).not.toBe(config)
+    })
+  })
+})