@dfosco/storyboard-core 1.20.0 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/bodyClasses.js

@@ -11,9 +11,11 @@ import { getAllParams } from './session.js'
 import { isHideMode, getAllShadows } from './hideMode.js'
 import { subscribeToHash } from './hashSubscribe.js'
 import { subscribeToStorage } from './localStorage.js'
+import { syncFlagBodyClasses } from './featureFlags.js'
 
 const PREFIX = 'sb-'
 const SCENE_PREFIX = 'sb-scene--'
+const FF_PREFIX = 'sb-ff-'
 
 /**
  * Sanitize a string for use in a CSS class name.
@@ -41,13 +43,13 @@ function overrideClass(key, value) {
 }
 
 /**
- * Get all current sb- classes on body (excluding scene classes).
+ * Get all current sb- classes on body (excluding scene and feature-flag classes).
  * @returns {Set<string>}
  */
 function getCurrentOverrideClasses() {
   const classes = new Set()
   for (const cls of document.body.classList) {
-    if (cls.startsWith(PREFIX) && !cls.startsWith(SCENE_PREFIX)) {
+    if (cls.startsWith(PREFIX) && !cls.startsWith(SCENE_PREFIX) && !cls.startsWith(FF_PREFIX)) {
       classes.add(cls)
     }
   }
@@ -108,8 +110,10 @@ export function setSceneClass(name) {
  */
 export function installBodyClassSync() {
   syncOverrideClasses()
-  const unsubHash = subscribeToHash(syncOverrideClasses)
-  const unsubStorage = subscribeToStorage(syncOverrideClasses)
+  syncFlagBodyClasses()
+  const sync = () => { syncOverrideClasses(); syncFlagBodyClasses() }
+  const unsubHash = subscribeToHash(sync)
+  const unsubStorage = subscribeToStorage(sync)
   return () => {
     unsubHash()
     unsubStorage()

package/src/featureFlags.js

@@ -15,23 +15,42 @@ import { getParam, setParam, removeParam, getAllParams } from './session.js'
 import { getLocal, setLocal, removeLocal, getAllLocal } from './localStorage.js'
 
 const FLAG_PREFIX = 'flag.'
+const BODY_CLASS_PREFIX = 'sb-ff-'
 
 /** Module-level storage for config defaults */
 let _defaults = {}
 
+/**
+ * Sync body classes for active feature flags.
+ * Adds `sb-ff-{name}` for every flag that resolves to true,
+ * removes it for every flag that resolves to false.
+ */
+export function syncFlagBodyClasses() {
+  if (typeof document === 'undefined') return
+  for (const key of Object.keys(_defaults)) {
+    const cls = BODY_CLASS_PREFIX + key
+    if (getFlag(key)) {
+      document.body.classList.add(cls)
+    } else {
+      document.body.classList.remove(cls)
+    }
+  }
+}
+
 /**
  * Initialize the feature flag system with config defaults.
- * Seeds localStorage with defaults (doesn't overwrite existing values).
+ * Syncs localStorage with config defaults on every call.
  * @param {Record<string, boolean>} defaults - Flag key → default value
  */
 export function initFeatureFlags(defaults = {}) {
   _defaults = { ...defaults }
-  // Seed localStorage with defaults (don't overwrite existing)
+  // Sync localStorage with config defaults — always overwrite so config
+  // changes take effect. User overrides live in the URL hash, which is
+  // checked first by getFlag(), so this is safe.
   for (const [key, value] of Object.entries(_defaults)) {
-    if (getLocal(FLAG_PREFIX + key) === null) {
-      setLocal(FLAG_PREFIX + key, String(value))
-    }
+    setLocal(FLAG_PREFIX + key, String(value))
   }
+  syncFlagBodyClasses()
 }
 
 /**
@@ -59,6 +78,7 @@ export function getFlag(key) {
  */
 export function setFlag(key, value) {
   setParam(FLAG_PREFIX + key, String(value))
+  syncFlagBodyClasses()
 }
 
 /**
@@ -101,6 +121,7 @@ export function resetFlags() {
       removeLocal(localKey)
     }
   }
+  syncFlagBodyClasses()
 }
 
 /**

package/src/index.js

@@ -8,8 +8,8 @@
 // Data index initialization
 export { init } from './loader.js'
 
-// Scene & record loading
-export { loadScene, listScenes, sceneExists, loadRecord, findRecord, deepMerge } from './loader.js'
+// Scene, object & record loading
+export { loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
 
 // Dot-notation path utilities
 export { getByPath, setByPath, deepClone } from './dotPath.js'
@@ -38,7 +38,7 @@ export { mountSceneDebug } from './sceneDebug.js'
 export { hash, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
 
 // Feature flags
-export { initFeatureFlags, getFlag, setFlag, toggleFlag, getAllFlags, resetFlags, getFlagKeys } from './featureFlags.js'
+export { initFeatureFlags, getFlag, setFlag, toggleFlag, getAllFlags, resetFlags, getFlagKeys, syncFlagBodyClasses } from './featureFlags.js'
 
 // Plugin configuration
 export { initPlugins, isPluginEnabled, getPluginsConfig } from './plugins.js'

package/src/loader.js

@@ -209,4 +209,17 @@ export function findRecord(recordName, id) {
   return records.find((entry) => entry.id === id) ?? null
 }
 
+/**
+ * Loads an object data file by name, resolves any nested $ref references,
+ * and returns a deep clone.
+ *
+ * @param {string} objectName - Name of the object file (e.g., "jane-doe")
+ * @returns {object|Array} Resolved object data
+ */
+export function loadObject(objectName) {
+  const data = loadDataFile(objectName, 'objects')
+  const resolved = resolveRefs(structuredClone(data))
+  return resolved
+}
+
 export { deepMerge }

package/src/loader.test.js

@@ -1,4 +1,4 @@
-import { init, loadScene, listScenes, sceneExists, loadRecord, findRecord, deepMerge } from './loader.js'
+import { init, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge } from './loader.js'
 
 const makeIndex = () => ({
   scenes: {
@@ -36,6 +36,10 @@ const makeIndex = () => ({
     'circular-obj-b': {
       nested: { $ref: 'circular-obj-a' },
     },
+    'team-info': {
+      team: 'Engineering',
+      lead: { $ref: 'jane-doe' },
+    },
   },
   records: {
     posts: [
@@ -243,3 +247,31 @@ describe('deepMerge', () => {
     expect(result.c).toBeUndefined()
   })
 })
+
+describe('loadObject', () => {
+  it('loads object by name', () => {
+    const obj = loadObject('jane-doe')
+    expect(obj).toEqual({ name: 'Jane Doe', role: 'admin' })
+  })
+
+  it('resolves $ref within object', () => {
+    const obj = loadObject('team-info')
+    expect(obj.team).toBe('Engineering')
+    expect(obj.lead).toEqual({ name: 'Jane Doe', role: 'admin' })
+  })
+
+  it('throws for missing object', () => {
+    expect(() => loadObject('nonexistent')).toThrow()
+  })
+
+  it('returns deep clone (mutations do not affect index)', () => {
+    const obj1 = loadObject('jane-doe')
+    obj1.name = 'Modified'
+    const obj2 = loadObject('jane-doe')
+    expect(obj2.name).toBe('Jane Doe')
+  })
+
+  it('detects circular $ref and throws', () => {
+    expect(() => loadObject('circular-obj-a')).toThrow(/circular/i)
+  })
+})