npm - @dfosco/storyboard-core - Versions diffs - 2.0.0 → 2.2.0 - Mend

@dfosco/storyboard-core 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/modes.config.json +17 -0
package/package.json +8 -3
package/src/bodyClasses.js +11 -8
package/src/bodyClasses.test.js +26 -12
package/src/devtools.js +9 -8
package/src/devtools.test.js +2 -2
package/src/index.js +20 -5
package/src/loader.js +116 -35
package/src/loader.test.js +189 -48
package/src/modes.js +170 -0
package/src/modes.test.js +216 -0
package/src/sceneDebug.js +17 -13
package/src/sceneDebug.test.js +42 -29
package/src/svelte-plugin-ui/__tests__/ToolbarShell.test.ts +77 -19
package/src/svelte-plugin-ui/__tests__/designModes.test.ts +1 -1
package/src/svelte-plugin-ui/components/ToolbarShell.svelte +59 -19
package/src/svelte-plugin-ui/components/Viewfinder.svelte +573 -0
package/src/svelte-plugin-ui/index.ts +3 -0
package/src/svelte-plugin-ui/stores/toolStore.ts +71 -0
package/src/svelte-plugin-ui/stores/types.ts +22 -8
package/src/{svelte-plugin-ui/plugins → ui}/design-modes.ts +9 -7
package/src/ui/viewfinder.ts +58 -0
package/src/viewfinder.js +100 -20
package/src/viewfinder.test.js +64 -42
package/src/workshop/features/createPage/server.js +8 -8

package/modes.config.json ADDED Viewed

@@ -0,0 +1,17 @@
+{
+  "modes": [
+    { "name": "prototype", "label": "Navigate" },
+    { "name": "inspect", "label": "Develop" },
+    { "name": "present", "label": "Collaborate" },
+    { "name": "plan", "label": "Canvas" }
+  ],
+  "tools": {
+    "*": [
+      { "id": "viewfinder", "label": "Viewfinder", "group": "dev" },
+      { "id": "scene-info", "label": "Show scene info", "group": "dev" },
+      { "id": "reset-params", "label": "Reset all params", "group": "dev" },
+      { "id": "hide-mode", "label": "Hide mode", "group": "dev" },
+      { "id": "feature-flags", "label": "Feature flags", "group": "dev" }
+    ]
+  }
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -9,17 +9,22 @@
     "directory": "packages/core"
   },
   "files": [
-    "src"
+    "src",
+    "modes.config.json"
   ],
   "exports": {
     ".": "./src/index.js",
+    "./modes.config.json": "./modes.config.json",
     "./vite/server": "./src/vite/server-plugin.js",
     "./comments": "./src/comments/index.js",
     "./comments/ui/comments.css": "./src/comments/ui/comments.css",
     "./workshop/ui/mount.js": "./src/workshop/ui/mount.js",
     "./modes.css": "./src/modes.css",
     "./svelte-plugin-ui": "./src/svelte-plugin-ui/index.ts",
-    "./svelte-plugin-ui/design-modes": "./src/svelte-plugin-ui/plugins/design-modes.ts",
+    "./svelte-plugin-ui/design-modes": "./src/ui/design-modes.ts",
+    "./svelte-plugin-ui/viewfinder": "./src/ui/viewfinder.ts",
+    "./ui/design-modes": "./src/ui/design-modes.ts",
+    "./ui/viewfinder": "./src/ui/viewfinder.ts",
     "./svelte-plugin-ui/styles/base.css": "./src/svelte-plugin-ui/styles/base.css"
   },
   "dependencies": {

package/src/bodyClasses.js CHANGED Viewed

@@ -14,7 +14,7 @@ import { subscribeToStorage } from './localStorage.js'
 import { syncFlagBodyClasses } from './featureFlags.js'
 const PREFIX = 'sb-'
-const SCENE_PREFIX = 'sb-scene--'
+const FLOW_PREFIX = 'sb-scene--'
 const FF_PREFIX = 'sb-ff-'
 /**
@@ -49,7 +49,7 @@ function overrideClass(key, value) {
 function getCurrentOverrideClasses() {
   const classes = new Set()
   for (const cls of document.body.classList) {
-    if (cls.startsWith(PREFIX) && !cls.startsWith(SCENE_PREFIX) && !cls.startsWith(FF_PREFIX)) {
+    if (cls.startsWith(PREFIX) && !cls.startsWith(FLOW_PREFIX) && !cls.startsWith(FF_PREFIX)) {
       classes.add(cls)
     }
   }
@@ -86,21 +86,24 @@ export function syncOverrideClasses() {
 }
 /**
- * Set the scene class on <body>. Removes any previous scene class.
- * @param {string} name - Scene name (e.g. "Dashboard")
+ * Set the flow class on <body>. Removes any previous flow class.
+ * @param {string} name - Flow name (e.g. "Dashboard")
  */
-export function setSceneClass(name) {
-  // Remove any existing scene classes
+export function setFlowClass(name) {
+  // Remove any existing flow classes
   for (const cls of [...document.body.classList]) {
-    if (cls.startsWith(SCENE_PREFIX)) {
+    if (cls.startsWith(FLOW_PREFIX)) {
       document.body.classList.remove(cls)
     }
   }
   if (name) {
-    document.body.classList.add(`${SCENE_PREFIX}${sanitize(name)}`)
+    document.body.classList.add(`${FLOW_PREFIX}${sanitize(name)}`)
   }
 }
+/** @deprecated Use setFlowClass() */
+export const setSceneClass = setFlowClass
 /**
  * Install listeners that keep body classes in sync with overrides.
  * Subscribes to both hashchange (normal mode) and storage (hide mode).

package/src/bodyClasses.test.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import {
   syncOverrideClasses,
+  setFlowClass,
   setSceneClass,
   installBodyClassSync,
 } from './bodyClasses.js'
@@ -90,37 +91,50 @@ describe('Override body classes', () => {
   })
 })
-// ── Scene Classes ──
+// ── Flow Classes ──
-describe('Scene body classes', () => {
+describe('Flow body classes', () => {
   it('sets sb-scene-- class', () => {
-    setSceneClass('Dashboard')
+    setFlowClass('Dashboard')
     expect(getSbClasses()).toContain('sb-scene--dashboard')
   })
-  it('replaces previous scene class', () => {
-    setSceneClass('Dashboard')
-    setSceneClass('Settings')
+  it('replaces previous flow class', () => {
+    setFlowClass('Dashboard')
+    setFlowClass('Settings')
     expect(getSbClasses()).not.toContain('sb-scene--dashboard')
     expect(getSbClasses()).toContain('sb-scene--settings')
   })
-  it('removes scene class when called with empty string', () => {
-    setSceneClass('Dashboard')
-    setSceneClass('')
-    const sceneClasses = getSbClasses().filter((c) => c.startsWith('sb-scene--'))
-    expect(sceneClasses).toEqual([])
+  it('removes flow class when called with empty string', () => {
+    setFlowClass('Dashboard')
+    setFlowClass('')
+    const flowClasses = getSbClasses().filter((c) => c.startsWith('sb-scene--'))
+    expect(flowClasses).toEqual([])
   })
   it('does not interfere with override classes', () => {
     window.location.hash = '#theme=dark'
     syncOverrideClasses()
-    setSceneClass('Dashboard')
+    setFlowClass('Dashboard')
     expect(getSbClasses()).toContain('sb-theme--dark')
     expect(getSbClasses()).toContain('sb-scene--dashboard')
   })
 })
+// ── setSceneClass (deprecated alias) ──
+describe('setSceneClass (deprecated alias)', () => {
+  it('is the same function as setFlowClass', () => {
+    expect(setSceneClass).toBe(setFlowClass)
+  })
+  it('sets sb-scene-- class', () => {
+    setSceneClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+})
 // ── Hide Mode ──
 describe('Hide mode body classes', () => {

package/src/devtools.js CHANGED Viewed

@@ -5,7 +5,7 @@
  *
  * Features:
  *  - Floating beaker button (bottom-right) that opens a menu
- *  - "Show scene info" — overlay panel with resolved scene JSON
+ *  - "Show flow info" — overlay panel with resolved scene JSON
  *  - "Reset all params" — clears all URL hash session params
  *  - Cmd+. (Mac) / Ctrl+. (other) toggles visibility
  *
@@ -13,7 +13,7 @@
  *   import { mountDevTools } from '@dfosco/storyboard-core'
  *   mountDevTools() // call once at app startup
  */
-import { loadScene } from './loader.js'
+import { loadFlow } from './loader.js'
 import { isCommentsEnabled } from './comments/config.js'
 import { isHideMode, activateHideMode, deactivateHideMode } from './hideMode.js'
 import { getAllFlags, toggleFlag, getFlagKeys } from './featureFlags.js'
@@ -180,8 +180,9 @@ const EYE_CLOSED_ICON = '<svg viewBox="0 0 16 16"><path d="M.143 2.31a.75.75 0 0
 const CHECK_ICON = '<svg viewBox="0 0 16 16"><path d="M13.78 4.22a.75.75 0 0 1 0 1.06l-7.25 7.25a.75.75 0 0 1-1.06 0L2.22 9.28a.751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018L6 10.94l6.72-6.72a.75.75 0 0 1 1.06 0Z"/></svg>'
 const ZAP_ICON = '<svg viewBox="0 0 16 16"><path d="M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004Z"/></svg>'
-function getSceneName() {
-  return new URLSearchParams(window.location.search).get('scene') || 'default'
+function getFlowName() {
+  const p = new URLSearchParams(window.location.search)
+  return p.get('flow') || p.get('scene') || 'default'
 }
 /**
@@ -235,7 +236,7 @@ export function mountDevTools(options = {}) {
   const showInfoBtn = document.createElement('button')
   showInfoBtn.className = 'sb-devtools-menu-item'
-  showInfoBtn.innerHTML = `${INFO_ICON} Show scene info`
+  showInfoBtn.innerHTML = `${INFO_ICON} Show flow info`
   const resetBtn = document.createElement('button')
   resetBtn.className = 'sb-devtools-menu-item'
@@ -391,11 +392,11 @@ export function mountDevTools(options = {}) {
     if (overlay) overlay.remove()
-    const sceneName = getSceneName()
+    const sceneName = getFlowName()
     let sceneJson = ''
     let error = null
     try {
-      sceneJson = JSON.stringify(loadScene(sceneName), null, 2)
+      sceneJson = JSON.stringify(loadFlow(sceneName), null, 2)
     } catch (err) {
       error = err.message
     }
@@ -412,7 +413,7 @@ export function mountDevTools(options = {}) {
     const header = document.createElement('div')
     header.className = 'sb-devtools-panel-header'
-    header.innerHTML = `<span class="sb-devtools-panel-title">Scene: ${sceneName}</span>`
+    header.innerHTML = `<span class="sb-devtools-panel-title">Flow: ${sceneName}</span>`
     const closeBtn = document.createElement('button')
     closeBtn.className = 'sb-devtools-panel-close'

package/src/devtools.test.js CHANGED Viewed

@@ -1,7 +1,7 @@
 import { vi } from 'vitest'
 vi.mock('./loader.js', () => ({
-  loadScene: vi.fn(() => ({ test: true })),
+  loadFlow: vi.fn(() => ({ test: true })),
 }))
 import { mountDevTools } from './devtools.js'
@@ -68,7 +68,7 @@ describe('mountDevTools', () => {
     expect(trigger.getAttribute('aria-label')).toBe('Storyboard DevTools')
   })
-  it('contains a menu with scene info and reset buttons', () => {
+  it('contains a menu with flow info and reset buttons', () => {
     mountDevTools()
     const menuItems = document.body.querySelectorAll('.sb-devtools-menu-item')

package/src/index.js CHANGED Viewed

@@ -8,8 +8,14 @@
 // Data index initialization
 export { init } from './loader.js'
-// Scene, object & record loading
-export { loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
+// Flow, object & record loading
+export { loadFlow, listFlows, flowExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
+// Scoped name resolution
+export { resolveFlowName, resolveRecordName } from './loader.js'
+// Prototype metadata
+export { listPrototypes, getPrototypeMetadata } from './loader.js'
+// Deprecated scene aliases
+export { loadScene, listScenes, sceneExists } from './loader.js'
 // Dot-notation path utilities
 export { getByPath, setByPath, deepClone } from './dotPath.js'
@@ -27,18 +33,27 @@ export { interceptHideParams, installHideParamListener } from './interceptHidePa
 // Hash change subscription (for reactive frameworks)
 export { subscribeToHash, getHashSnapshot } from './hashSubscribe.js'
-// Body class sync (overrides + scene → <body> classes)
-export { installBodyClassSync, setSceneClass, syncOverrideClasses } from './bodyClasses.js'
+// Body class sync (overrides + flow → <body> classes)
+export { installBodyClassSync, setFlowClass, syncOverrideClasses } from './bodyClasses.js'
+// Deprecated alias
+export { setSceneClass } from './bodyClasses.js'
 // Design modes (mode registry, switching, event bus)
 export { registerMode, unregisterMode, getRegisteredModes, getCurrentMode, activateMode, deactivateMode, subscribeToMode, getModeSnapshot, syncModeClasses, on, off, emit, initModesConfig, isModesEnabled } from './modes.js'
+// Tool registry (declared in modes.config.json, state managed at runtime)
+export { initTools, setToolAction, setToolState, getToolState, getToolsForMode, subscribeToTools, getToolsSnapshot } from './modes.js'
 // Dev tools (vanilla JS, framework-agnostic)
 export { mountDevTools } from './devtools.js'
+export { mountFlowDebug } from './sceneDebug.js'
+// Deprecated alias
 export { mountSceneDebug } from './sceneDebug.js'
 // Viewfinder utilities
-export { hash, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
+export { hash, resolveFlowRoute, getFlowMeta, buildPrototypeIndex } from './viewfinder.js'
+// Deprecated aliases
+export { resolveSceneRoute, getSceneMeta } from './viewfinder.js'
 // Feature flags
 export { initFeatureFlags, getFlag, setFlag, toggleFlag, getAllFlags, resetFlags, getFlagKeys, syncFlagBodyClasses } from './featureFlags.js'

package/src/loader.js CHANGED Viewed

@@ -28,24 +28,25 @@ function deepMerge(target, source) {
 /**
  * Module-level data index, seeded by init().
- * Shape: { scenes: {}, objects: {}, records: {} }
+ * Shape: { flows: {}, objects: {}, records: {} }
  */
-let dataIndex = { scenes: {}, objects: {}, records: {} }
+let dataIndex = { flows: {}, objects: {}, records: {}, prototypes: {} }
 /**
  * Seed the data index. Call once at app startup before any load functions.
  * The Vite data plugin calls this automatically via the generated virtual module.
  *
- * @param {{ scenes: object, objects: object, records: object }} index
+ * @param {{ flows?: object, scenes?: object, objects: object, records: object, prototypes?: object }} index
  */
 export function init(index) {
   if (!index || typeof index !== 'object') {
-    throw new Error('[storyboard-core] init() requires { scenes, objects, records }')
+    throw new Error('[storyboard-core] init() requires { flows, objects, records }')
   }
   dataIndex = {
-    scenes: index.scenes || {},
+    flows: index.flows || index.scenes || {},
     objects: index.objects || {},
     records: index.records || {},
+    prototypes: index.prototypes || {},
   }
 }
@@ -63,24 +64,29 @@ function loadDataFile(name, type) {
   // Search all types if no specific type given
   if (!type) {
-    for (const t of ['scenes', 'objects', 'records']) {
+    for (const t of ['flows', 'objects', 'records']) {
       if (dataIndex[t]?.[name] != null) {
         return dataIndex[t][name]
       }
     }
   }
-  // Case-insensitive fallback for scenes
-  if (type === 'scenes' || !type) {
+  // Case-insensitive fallback for flows
+  if (type === 'flows' || !type) {
     const lower = name.toLowerCase()
-    for (const key of Object.keys(dataIndex.scenes)) {
+    for (const key of Object.keys(dataIndex.flows)) {
       if (key.toLowerCase() === lower) {
-        return dataIndex.scenes[key]
+        return dataIndex.flows[key]
       }
     }
   }
-  throw new Error(`Data file not found: ${name}${type ? ` (type: ${type})` : ''}`)
+  const available = Object.keys(dataIndex[type] || {})
+  const scopedHints = available.filter(k => k.includes('/')).slice(0, 5)
+  const hint = scopedHints.length > 0
+    ? `\n  Scoped names in index: ${scopedHints.join(', ')}`
+    : ''
+  throw new Error(`Data file not found: ${name}${type ? ` (type: ${type})` : ''}${hint}`)
 }
 /**
@@ -117,49 +123,62 @@ function resolveRefs(node, seen = new Set()) {
 }
 /**
- * Returns the names of all registered scenes.
+ * Returns the names of all registered flows.
  * @returns {string[]}
  */
-export function listScenes() {
-  return Object.keys(dataIndex.scenes)
+export function listFlows() {
+  return Object.keys(dataIndex.flows)
 }
+/** @deprecated Use listFlows() */
+export const listScenes = listFlows
 /**
- * Checks whether a scene file exists for the given name.
- * @param {string} sceneName - e.g., "Overview"
+ * Checks whether a flow file exists for the given name.
+ * @param {string} flowName - e.g., "Overview"
  * @returns {boolean}
  */
-export function sceneExists(sceneName) {
-  if (dataIndex.scenes[sceneName] != null) return true
-  const lower = sceneName.toLowerCase()
-  for (const key of Object.keys(dataIndex.scenes)) {
+export function flowExists(flowName) {
+  if (dataIndex.flows[flowName] != null) return true
+  const lower = flowName.toLowerCase()
+  for (const key of Object.keys(dataIndex.flows)) {
     if (key.toLowerCase() === lower) return true
   }
   return false
 }
+/** @deprecated Use flowExists() */
+export const sceneExists = flowExists
 /**
- * Loads a scene file and resolves $global and $ref references.
+ * Loads a flow file and resolves $global and $ref references.
  *
- * - $global: array of data names merged into root (scene wins on conflicts)
+ * - $global: array of data names merged into root (flow wins on conflicts)
  * - $ref: inline object replacement at any nesting level
  *
- * @param {string} sceneName - Name of the scene (e.g., "default")
- * @returns {object} Resolved scene data
+ * @param {string} flowName - Name of the flow (e.g., "default")
+ * @returns {object} Resolved flow data
  */
-export function loadScene(sceneName = 'default') {
-  let sceneData
+export function loadFlow(flowName = 'default') {
+  let flowData
   try {
-    sceneData = structuredClone(loadDataFile(sceneName, 'scenes'))
+    flowData = structuredClone(loadDataFile(flowName, 'flows'))
   } catch {
-    throw new Error(`Failed to load scene: ${sceneName}`)
+    const available = listFlows()
+    const related = available.filter(k =>
+      k.endsWith('/' + flowName) || k.startsWith(flowName + '/')
+    )
+    const hint = related.length > 0
+      ? ` Did you mean: ${related.join(', ')}?`
+      : ''
+    throw new Error(`Failed to load flow: ${flowName}.${hint}`)
   }
   // Handle $global: root-level merge from referenced data files
-  if (Array.isArray(sceneData.$global)) {
-    const globalNames = sceneData.$global
-    delete sceneData.$global
+  if (Array.isArray(flowData.$global)) {
+    const globalNames = flowData.$global
+    delete flowData.$global
     let mergedGlobals = {}
     for (const name of globalNames) {
@@ -172,16 +191,19 @@ export function loadScene(sceneName = 'default') {
       }
     }
-    sceneData = deepMerge(mergedGlobals, sceneData)
+    flowData = deepMerge(mergedGlobals, flowData)
   }
-  sceneData = resolveRefs(sceneData)
+  flowData = resolveRefs(flowData)
   // Single clone at the boundary — resolveRefs builds new objects internally,
   // so the index data is safe. Clone here to prevent consumer mutation.
-  return structuredClone(sceneData)
+  return structuredClone(flowData)
 }
+/** @deprecated Use loadFlow() */
+export const loadScene = loadFlow
 /**
  * Loads a record collection by name.
  * @param {string} recordName - Name of the record file (e.g., "posts")
@@ -190,7 +212,14 @@ export function loadScene(sceneName = 'default') {
 export function loadRecord(recordName) {
   const data = dataIndex.records[recordName]
   if (data == null) {
-    throw new Error(`Record not found: ${recordName}`)
+    const available = Object.keys(dataIndex.records)
+    const related = available.filter(k =>
+      k.endsWith('/' + recordName) || k.startsWith(recordName + '/')
+    )
+    const hint = related.length > 0
+      ? ` Did you mean: ${related.join(', ')}?`
+      : ''
+    throw new Error(`Record not found: ${recordName}.${hint}`)
   }
   if (!Array.isArray(data)) {
     throw new Error(`Record "${recordName}" must be an array, got ${typeof data}`)
@@ -222,4 +251,56 @@ export function loadObject(objectName) {
   return resolved
 }
+/**
+ * Resolve a flow name within a prototype scope.
+ * Tries the scoped name first ({scope}/{name}), then falls back to the plain name.
+ *
+ * @param {string|null} scope - Prototype name (e.g. "Dashboard"), or null for global-only
+ * @param {string} name - Flow name (e.g. "default" or "Dashboard/signup")
+ * @returns {string} The resolved flow name that exists in the index
+ */
+export function resolveFlowName(scope, name) {
+  if (scope) {
+    const scoped = `${scope}/${name}`
+    if (flowExists(scoped)) return scoped
+  }
+  if (flowExists(name)) return name
+  // Return the scoped name for better error messages even if it doesn't exist
+  return scope ? `${scope}/${name}` : name
+}
+/**
+ * Resolve a record name within a prototype scope.
+ * Tries the scoped name first ({scope}/{name}), then falls back to the plain name.
+ *
+ * @param {string|null} scope - Prototype name (e.g. "Dashboard"), or null for global-only
+ * @param {string} name - Record name (e.g. "posts")
+ * @returns {string} The resolved record name that exists in the index
+ */
+export function resolveRecordName(scope, name) {
+  if (scope) {
+    const scoped = `${scope}/${name}`
+    if (dataIndex.records[scoped] != null) return scoped
+  }
+  if (dataIndex.records[name] != null) return name
+  return scope ? `${scope}/${name}` : name
+}
+/**
+ * Returns the names of all registered prototypes.
+ * @returns {string[]}
+ */
+export function listPrototypes() {
+  return Object.keys(dataIndex.prototypes)
+}
+/**
+ * Returns prototype metadata by name.
+ * @param {string} name - Prototype name (e.g. "Example")
+ * @returns {object|null} Metadata from the .prototype.json file, or null
+ */
+export function getPrototypeMetadata(name) {
+  return dataIndex.prototypes[name] ?? null
+}
 export { deepMerge }