@dfosco/storyboard 0.9.5 → 0.10.0

package/src/internals/hooks/useKnob.js

@@ -0,0 +1,97 @@
+/**
+ * Read-only knob hook.
+ *
+ * Resolves the current prototype/route, reads the corresponding knob hash
+ * value through useOverride, coerces it by schema, and falls back to defaults.
+ */
+
+import { useContext } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { useOverride } from './useOverride.js'
+import {
+  buildKnobKey,
+  coerceByType,
+  getPrototypeKnobs,
+  normalizeScope,
+  resolveKnobDef,
+} from '../../core/knobs/index.js'
+
+/**
+ * Detect the active prototype and route scope from the current URL.
+ *
+ * Handles the dev-only `/prototypes.html/<proto>/...` iframe-isolation
+ * prefix (`packages/storyboard/src/internals/canvas/widgets/PrototypeEmbed.jsx`)
+ * by stripping it before parsing — otherwise `prototypes.html` ends up as
+ * the prototype name and the real prototype is treated as a route segment.
+ *
+ * @param {string} [pathname]
+ * @param {string} [basePath]
+ * @returns {{ prototypeName: string|null, route: string|undefined }}
+ */
+export function detectKnobRoute(
+  pathname = window.location.pathname,
+  basePath = import.meta.env?.BASE_URL || '/',
+) {
+  let path = pathname
+  const base = basePath.replace(/\/+$/, '')
+  if (base && base !== '/' && path.startsWith(base)) {
+    path = path.slice(base.length) || '/'
+  }
+
+  // Strip the prototypes.html isolation prefix (dev iframe path).
+  path = path.replace(/^\/prototypes\.html(?=\/|$)/, '') || '/'
+
+  path = path.replace(/\/+$/, '') || '/'
+  const segments = path.split('/').filter(Boolean)
+  const branchSegment = segments[0]?.startsWith('branch--') ? segments[0] : null
+  const protoIdx = branchSegment ? 1 : 0
+  const prototypeName = segments[protoIdx] || null
+  const routeSegments = prototypeName ? segments.slice(protoIdx + 1) : []
+  const route = routeSegments.length > 0 ? `/${routeSegments.join('/')}` : undefined
+
+  return { prototypeName, route }
+}
+
+/**
+ * Read a typed knob value from URL hash state.
+ *
+ * Behaves like `useOverride`: reads the URL hash key, re-renders on
+ * `hashchange`. When a schema is declared, coercion + default fallback
+ * apply. When no schema is discovered, returns the raw hash value as-is
+ * so prototypes always react to URL changes (even before discovery runs).
+ *
+ * @param {string} id
+ * @param {{ route?: string|null, scope?: string|null }} [options]
+ * @returns {*}
+ */
+export function useKnob(id, { route, scope } = {}) {
+  const context = useContext(StoryboardContext)
+  const detected = detectKnobRoute()
+  const hasExplicitRoute = route !== undefined || scope !== undefined
+  const routeValue = route !== undefined ? route : scope
+  const resolvedRoute = hasExplicitRoute ? normalizeScope(routeValue) : detected.route
+  const prototypeName = context?.prototypeName ?? detected.prototypeName
+
+  const key = buildKnobKey(id, { route: resolvedRoute })
+  const [rawValue] = useOverride(key)
+  const knobs = prototypeName ? getPrototypeKnobs(prototypeName) : []
+  const def = resolveKnobDef(id, { route: resolvedRoute, knobs })
+
+  // No schema discovered? Best-effort coerce common string forms so
+  // consumers don't have to ?? against the string "false" (truthy!).
+  // Numeric strings stay numeric. Everything else passes through as-is.
+  if (!def) {
+    if (rawValue == null) return undefined
+    if (rawValue === 'true') return true
+    if (rawValue === 'false') return false
+    const asNumber = Number(rawValue)
+    if (rawValue !== '' && !Number.isNaN(asNumber)) return asNumber
+    return rawValue
+  }
+
+  // With a schema: coerce → fall back to default when raw is missing or
+  // un-coercible. Mirrors the original "URL is invalid, use the default"
+  // semantics so consumers always get a typed value.
+  const coerced = coerceByType(rawValue, def)
+  return coerced !== undefined ? coerced : def.default
+}

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

@@ -0,0 +1,133 @@
+import { createElement } from 'react'
+import { renderHook } from '@testing-library/react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { initKnobs } from '../../core/knobs/index.js'
+import { detectKnobRoute, useKnob } from './useKnob.js'
+
+function wrapper(prototypeName = 'Signup') {
+  return function Wrapper({ children }) {
+    return createElement(
+      StoryboardContext.Provider,
+      { value: { data: {}, error: null, loading: false, prototypeName } },
+      children,
+    )
+  }
+}
+
+beforeEach(() => {
+  initKnobs()
+  window.history.pushState(null, '', '/')
+})
+
+describe('detectKnobRoute', () => {
+  it('detects prototype and route from normal and branch-prefixed paths', () => {
+    expect(detectKnobRoute('/Signup/Branding')).toEqual({
+      prototypeName: 'Signup',
+      route: '/Branding',
+    })
+    expect(detectKnobRoute('/branch--knobs-system/Signup/Branding')).toEqual({
+      prototypeName: 'Signup',
+      route: '/Branding',
+    })
+  })
+
+  it('strips the /prototypes.html iframe-isolation prefix', () => {
+    expect(detectKnobRoute('/prototypes.html/Signup')).toEqual({
+      prototypeName: 'Signup',
+      route: undefined,
+    })
+    expect(detectKnobRoute('/prototypes.html/Signup/Branding')).toEqual({
+      prototypeName: 'Signup',
+      route: '/Branding',
+    })
+  })
+})
+
+describe('useKnob', () => {
+  it('returns a prototype-wide default when no hash value is present', () => {
+    initKnobs({
+      prototypeKnobs: {
+        Signup: [{ id: 'showAvatar', type: 'boolean', default: true }],
+      },
+    })
+    window.history.pushState(null, '', '/Signup')
+
+    const { result } = renderHook(() => useKnob('showAvatar'), {
+      wrapper: wrapper('Signup'),
+    })
+
+    expect(result.current).toBe(true)
+  })
+
+  it('coerces prototype-wide hash values', () => {
+    initKnobs({
+      prototypeKnobs: {
+        Signup: [{ id: 'showAvatar', type: 'boolean', default: true }],
+      },
+    })
+    window.history.pushState(null, '', '/Signup#knobShowAvatar=false')
+
+    const { result } = renderHook(() => useKnob('showAvatar'), {
+      wrapper: wrapper('Signup'),
+    })
+
+    expect(result.current).toBe(false)
+  })
+
+  it('auto-detects route-scoped knob values', () => {
+    initKnobs({
+      prototypeKnobs: {
+        Signup: [{
+          id: 'variant',
+          type: 'select',
+          scope: '/Branding',
+          options: ['small', 'large'],
+          default: 'small',
+        }],
+      },
+    })
+    window.history.pushState(null, '', '/Signup/Branding#knobBrandingVariant=large')
+
+    const { result } = renderHook(() => useKnob('variant'), {
+      wrapper: wrapper('Signup'),
+    })
+
+    expect(result.current).toBe('large')
+  })
+
+  it('treats scope as a route alias', () => {
+    initKnobs({
+      prototypeKnobs: {
+        Signup: [{
+          id: 'variant',
+          type: 'select',
+          scope: '/Branding',
+          options: ['small', 'large'],
+          default: 'small',
+        }],
+      },
+    })
+    window.history.pushState(null, '', '/Signup#knobBrandingVariant=large')
+
+    const { result } = renderHook(() => useKnob('variant', { scope: '/Branding' }), {
+      wrapper: wrapper('Signup'),
+    })
+
+    expect(result.current).toBe('large')
+  })
+
+  it('falls back to defaults for malformed hash values', () => {
+    initKnobs({
+      prototypeKnobs: {
+        Signup: [{ id: 'showAvatar', type: 'boolean', default: true }],
+      },
+    })
+    window.history.pushState(null, '', '/Signup#knobShowAvatar=nope')
+
+    const { result } = renderHook(() => useKnob('showAvatar'), {
+      wrapper: wrapper('Signup'),
+    })
+
+    expect(result.current).toBe(true)
+  })
+})

package/src/internals/index.js

@@ -26,6 +26,8 @@ export { useFeatureFlag } from './hooks/useFeatureFlag.js'
 export { useMode } from './hooks/useMode.js'
 export { useThemeState, useThemeSyncTargets } from './hooks/useThemeState.js'
 export { useConfig } from './hooks/useConfig.js'
+export { useKnob } from './hooks/useKnob.js'
+export { KnobsForm } from './Knobs/index.js'
 
 // React Router integration
 export { installHashPreserver } from './hashPreserver.js'

package/src/internals/story/ComponentSetPage.jsx

@@ -21,6 +21,18 @@ import styles from './ComponentSetPage.module.css'
 
 const StoryWrapper = getStoryWrapper()
 
+function parseHashSelected(hash) {
+  if (!hash) return ''
+  const trimmed = hash.startsWith('#') ? hash.slice(1) : hash
+  if (!trimmed) return ''
+  try {
+    const params = new URLSearchParams(trimmed)
+    return params.get('selected') || ''
+  } catch {
+    return ''
+  }
+}
+
 export default function ComponentSetPage({ name }) {
   const location = useLocation()
   const navigate = useNavigate()
@@ -28,7 +40,7 @@ export default function ComponentSetPage({ name }) {
 
   const layout = searchParams.get('layout') || 'auto'
   const density = searchParams.get('density') || 'comfy'
-  const selected = searchParams.get('selected') || ''
+  const selected = parseHashSelected(location.hash)
   const isEmbed = searchParams.has('_sb_embed')
 
   // Same reload-guard policy as StoryPage / prototype embeds.
@@ -157,20 +169,20 @@ export default function ComponentSetPage({ name }) {
   }, [exports, layout, density, isEmbed])
 
   const handleSelect = useCallback((exportName) => {
-    const params = new URLSearchParams(location.search)
-    if (exportName === params.get('selected')) {
-      params.delete('selected')
-    } else {
-      params.set('selected', exportName)
-    }
-    navigate(`${location.pathname}?${params}`, { replace: true })
+    const isToggleOff = exportName === selected
+    const newSelected = isToggleOff ? '' : exportName
+    const hash = newSelected ? `#selected=${encodeURIComponent(newSelected)}` : ''
+    // Preserve current search params; only flip the fragment. The parent
+    // widget keeps `selected` in the URL hash specifically so this update
+    // round-trips as a same-document fragment change — no iframe reload.
+    navigate(`${location.pathname}${location.search}${hash}`, { replace: true })
 
     // Notify parent widget
     if (window.parent !== window) {
       window.parent.postMessage({
         type: 'storyboard:component-set:select',
         storyId: name,
-        exportName: exportName === selected ? null : exportName,
+        exportName: newSelected || null,
       }, '*')
     }
   }, [location, navigate, name, selected])

package/src/internals/vite/data-plugin.js

@@ -17,7 +17,7 @@ import { createIsolationMiddleware } from '../canvas/isolation/createIsolationMi
 const VIRTUAL_MODULE_ID = 'virtual:storyboard-data-index'
 const RESOLVED_ID = '\0' + VIRTUAL_MODULE_ID
 
-const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder}.{json,jsonc}'
+const GLOB_PATTERN = '**/*.{flow,scene,object,record,prototype,folder,component}.{json,jsonc}'
 const CANVAS_GLOB_PATTERN = '**/*.canvas.jsonl'
 const CANVAS_META_GLOB_PATTERN = '**/*.meta.json'
 const STORY_GLOB_PATTERN = '**/*.story.{jsx,tsx}'
@@ -171,7 +171,7 @@ function parseDataFile(filePath, opts = {}) {
     return { name, suffix: 'story', ext: storyMatch[2], inferredRoute, isPrivate }
   }
 
-  const match = base.match(/^(.+)\.(flow|scene|object|record|prototype|folder)\.(jsonc?)$/)
+  const match = base.match(/^(.+)\.(flow|scene|object|record|prototype|folder|component)\.(jsonc?)$/)
   if (!match) return null
 
   // Skip _-prefixed files (drafts/internal — never visible)
@@ -210,6 +210,12 @@ function parseDataFile(filePath, opts = {}) {
     return { name, suffix, ext: match[3], folder: folderName, isPrivate }
   }
 
+  // Component metadata files are keyed by their component config basename.
+  if (suffix === 'component') {
+    const isPrivate = normalized.split('/').includes('drafts')
+    return { name, suffix, ext: match[3], isPrivate }
+  }
+
   // Scope flows, records, and objects inside src/prototypes/{Name}/ with a prefix
   // (skip .folder/ and `drafts/` segments when determining prototype name).
   const protoMatch = normalized.match(/(?:^|\/)src\/prototypes\/(?:(?:[^/]+\.folder|drafts)\/)*([^/]+)\//)
@@ -350,7 +356,7 @@ function buildIndex(root, opts = {}) {
     }
   }
 
-  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {}, canvas: {}, 'canvas-meta': {}, story: {} }
+  const index = { flow: {}, object: {}, record: {}, prototype: {}, folder: {}, component: {}, canvas: {}, 'canvas-meta': {}, story: {} }
   const seen = {} // "name.suffix" or "id.suffix" → absolute path (for duplicate detection)
   const protoFolders = {} // prototype name → folder name (for injection)
   const flowRoutes = {} // flow name → inferred route (for _route injection)
@@ -857,12 +863,26 @@ function findOverlappingKeys(a, b, prefix = '') {
   return overlaps
 }
 
+function extractPrototypeKnobs(parsed) {
+  if (Array.isArray(parsed?.meta?.knobs)) return parsed.meta.knobs
+  if (Array.isArray(parsed?.knobs)) return parsed.knobs
+  return []
+}
+
+function extractComponentKnobs(parsed) {
+  if (Array.isArray(parsed?.knobs)) return parsed.knobs
+  if (Array.isArray(parsed?.meta?.knobs)) return parsed.meta.knobs
+  return []
+}
+
 function buildDiscoveryResult({ index, protoFolders, flowRoutes, canvasRoutes, canvasAliases, canvasGroups, storyRoutes, privateBySuffix = {} }, root) {
   const discovery = {
     flows: {},
     objects: {},
     records: {},
     prototypes: {},
+    prototypeKnobs: {},
+    componentKnobs: {},
     folders: {},
     canvases: {},
     canvasAliases: canvasAliases || {},
@@ -1027,10 +1047,21 @@ function buildDiscoveryResult({ index, protoFolders, flowRoutes, canvasRoutes, c
         parsed = { ...parsed, _isPrivate: true }
       }
 
+      if (suffix === 'prototype') {
+        discovery.prototypeKnobs[name] = extractPrototypeKnobs(parsed)
+      }
+
       discovery[resultKeys[suffix]][name] = parsed
     }
   }
 
+  for (const [name, absPath] of Object.entries(index.component || {})) {
+    const raw = fs.readFileSync(absPath, 'utf-8')
+    let parsed = parseJsonc(raw)
+    parsed = resolveTemplateVars(parsed, computeTemplateVars(absPath, root))
+    discovery.componentKnobs[name] = extractComponentKnobs(parsed)
+  }
+
   // Generate story entries (code modules with dynamic imports, not JSON data)
   for (const [name, absPath] of Object.entries(index.story || {})) {
     const relModule = '/' + path.relative(root, absPath).replace(/\\/g, '/')
@@ -1088,8 +1119,11 @@ function generateModule(buildResult, root) {
     storyEntries.push(`  ${JSON.stringify(name)}: ${varName}`)
   }
 
-  const imports = [`import { init } from '@dfosco/storyboard/core'`]
-  const initCalls = [`init({ flows, objects, records, prototypes, folders, canvases, stories })`]
+  const imports = [`import { init, initKnobs } from '@dfosco/storyboard/core'`]
+  const initCalls = [
+    `init({ flows, objects, records, prototypes, folders, canvases, stories })`,
+    `initKnobs({ prototypeKnobs, componentKnobs })`,
+  ]
 
   // Build unified config from all sources
   const { unified: unifiedConfig, warnings: configWarnings } = buildUnifiedConfig(root)
@@ -1183,6 +1217,8 @@ function generateModule(buildResult, root) {
     `const objects = {\n${entries.object.join(',\n')}\n}`,
     `const records = {\n${entries.record.join(',\n')}\n}`,
     `const prototypes = {\n${entries.prototype.join(',\n')}\n}`,
+    `const prototypeKnobs = ${JSON.stringify(discovery.prototypeKnobs || {})}`,
+    `const componentKnobs = ${JSON.stringify(discovery.componentKnobs || {})}`,
     `const folders = {\n${entries.folder.join(',\n')}\n}`,
     `const canvases = {\n${entries.canvas.join(',\n')}\n}`,
     `const stories = {\n${storyEntries.join(',\n')}\n}`,
@@ -1195,8 +1231,8 @@ function generateModule(buildResult, root) {
     '',
     initCalls.join('\n'),
     '',
-    `export { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }`,
-    `export const index = { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }`,
+    `export { flows, scenes, objects, records, prototypes, prototypeKnobs, componentKnobs, folders, canvases, canvasAliases, stories }`,
+    `export const index = { flows, scenes, objects, records, prototypes, prototypeKnobs, componentKnobs, folders, canvases, canvasAliases, stories }`,
     `export default index`,
     '',
     '// Live-patch canvas data on HMR events so SPA navigation shows fresh state',
@@ -1213,6 +1249,7 @@ function generateModule(buildResult, root) {
     '        : data.metadata',
     '    }',
     '    init({ flows, objects, records, prototypes, folders, canvases, stories })',
+    '    initKnobs({ prototypeKnobs, componentKnobs })',
     '    document.dispatchEvent(new CustomEvent("storyboard:canvas-index-changed"))',
     '  })',
     '  import.meta.hot.on("storyboard:story-file-changed", (data) => {',
@@ -1224,6 +1261,7 @@ function generateModule(buildResult, root) {
     '        _storyImport: () => import(/* @vite-ignore */ data._storyModule) }',
     '    }',
     '    init({ flows, objects, records, prototypes, folders, canvases, stories })',
+    '    initKnobs({ prototypeKnobs, componentKnobs })',
     '    document.dispatchEvent(new CustomEvent("storyboard:story-index-changed"))',
     '  })',
     '}',

package/src/internals/vite/data-plugin.test.js

@@ -76,14 +76,14 @@ describe('storyboardDataPlugin', () => {
     const plugin = createPlugin()
     const code = plugin.load(RESOLVED_ID)
 
-    expect(code).toContain("import { init } from '@dfosco/storyboard/core'")
+    expect(code).toContain("import { init, initKnobs } from '@dfosco/storyboard/core'")
     expect(code).toContain('init({ flows, objects, records, prototypes, folders, canvases, stories })')
     expect(code).toContain('"Test"')
     expect(code).toContain('"Jane"')
     expect(code).toContain('"First"')
     // Backward-compat alias
     expect(code).toContain('const scenes = flows')
-    expect(code).toContain('export { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }')
+    expect(code).toContain('export { flows, scenes, objects, records, prototypes, prototypeKnobs, componentKnobs, folders, canvases, canvasAliases, stories }')
   })
 
   it('load returns null for other IDs', () => {
@@ -1115,7 +1115,7 @@ describe('canvas watcher behavior', () => {
 
     expect(code).toContain('const stories = {')
     expect(code).toContain('init({ flows, objects, records, prototypes, folders, canvases, stories })')
-    expect(code).toContain('export { flows, scenes, objects, records, prototypes, folders, canvases, canvasAliases, stories }')
+    expect(code).toContain('export { flows, scenes, objects, records, prototypes, prototypeKnobs, componentKnobs, folders, canvases, canvasAliases, stories }')
   })
 
   it('infers /components/ route for stories in src/canvas/', () => {

package/storyboard.config.json

@@ -33,6 +33,12 @@
       "resizable": false,
       "defaultWidth": 800,
       "defaultHeight": 450
+    },
+    "fileEditor": {
+      "theme": {
+        "light": null,
+        "dark": "oneDark"
+      }
     }
   },
   "customerMode": {

package/toolbar.config.json

@@ -36,7 +36,20 @@
       "handler": "core:flows",
       "excludeRoutes": ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"],
       "hideInCommandPalette": ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"]
-    },    
+    },
+    "knobs": {
+      "label": "Knobs",
+      "ariaLabel": "Tweak knobs",
+      "icon": "iconoir/select-point-3d",
+      "render": "knobs-panel",
+      "surface": "command-toolbar",
+      "handler": "core:knobs",
+      "modes": ["prototype"],
+      "prod": true,
+      "excludeRoutes": ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"],
+      "hideInCommandPalette": ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"],
+      "shortcut": { "key": "K", "label": "cmd + shift + k" }
+    },
     "theme": {
       "label": "Theme",
       "ariaLabel": "Switch theme",
@@ -152,7 +165,7 @@
       "ariaLabel": "Zoom to objects",
       "label": "Zoom to objects",
       "icon": "iconoir/square-3d-three-points",
-      "meta": { "strokeWeight": 2, "scale": 1.2 },
+      "meta": { "strokeWeight": 1.5, "scale": 0.5 },
       "render": "canvas-zoom-to-fit",
       "surface": "canvas-toolbar",
       "handler": "core:canvas-toolbar",