npm - @dfosco/storyboard-core - Versions diffs - 1.11.1 → 1.11.3 - Mend

@dfosco/storyboard-core 1.11.1 → 1.11.3

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 (4) hide show

package/package.json CHANGED Viewed

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

package/src/bodyClasses.js ADDED Viewed

@@ -0,0 +1,117 @@
+/**
+ * Body class sync for overrides and scenes.
+ *
+ * Mirrors active overrides as `sb-{key}--{value}` classes on <body>
+ * and the active scene as `sb-scene--{name}`.
+ *
+ * Works in both normal mode (URL hash) and hide mode (localStorage shadows).
+ */
+import { getAllParams } from './session.js'
+import { isHideMode, getAllShadows } from './hideMode.js'
+import { subscribeToHash } from './hashSubscribe.js'
+import { subscribeToStorage } from './localStorage.js'
+const PREFIX = 'sb-'
+const SCENE_PREFIX = 'sb-scene--'
+/**
+ * Sanitize a string for use in a CSS class name.
+ * Dots and spaces become dashes, lowercased, non-alphanumeric stripped.
+ * @param {string} str
+ * @returns {string}
+ */
+function sanitize(str) {
+  return String(str)
+    .toLowerCase()
+    .replace(/[\.\s]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+/**
+ * Build the class name for an override key/value pair.
+ * @param {string} key
+ * @param {string} value
+ * @returns {string}
+ */
+function overrideClass(key, value) {
+  return `${PREFIX}${sanitize(key)}--${sanitize(value)}`
+}
+/**
+ * Get all current sb- classes on body (excluding scene 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)) {
+      classes.add(cls)
+    }
+  }
+  return classes
+}
+/**
+ * Sync override classes on <body> with current hash/shadow state.
+ * Diffs against existing classes to minimize DOM mutations.
+ */
+export function syncOverrideClasses() {
+  const overrides = isHideMode() ? getAllShadows() : getAllParams()
+  const desired = new Set()
+  for (const [key, value] of Object.entries(overrides)) {
+    if (key && value != null && value !== '') {
+      desired.add(overrideClass(key, value))
+    }
+  }
+  const current = getCurrentOverrideClasses()
+  // Remove stale classes
+  for (const cls of current) {
+    if (!desired.has(cls)) {
+      document.body.classList.remove(cls)
+    }
+  }
+  // Add missing classes
+  for (const cls of desired) {
+    if (!current.has(cls)) {
+      document.body.classList.add(cls)
+    }
+  }
+}
+/**
+ * Set the scene class on <body>. Removes any previous scene class.
+ * @param {string} name - Scene name (e.g. "Dashboard")
+ */
+export function setSceneClass(name) {
+  // Remove any existing scene classes
+  for (const cls of [...document.body.classList]) {
+    if (cls.startsWith(SCENE_PREFIX)) {
+      document.body.classList.remove(cls)
+    }
+  }
+  if (name) {
+    document.body.classList.add(`${SCENE_PREFIX}${sanitize(name)}`)
+  }
+}
+/**
+ * Install listeners that keep body classes in sync with overrides.
+ * Subscribes to both hashchange (normal mode) and storage (hide mode).
+ * Runs an initial sync immediately.
+ *
+ * @returns {function} unsubscribe — removes all listeners
+ */
+export function installBodyClassSync() {
+  syncOverrideClasses()
+  const unsubHash = subscribeToHash(syncOverrideClasses)
+  const unsubStorage = subscribeToStorage(syncOverrideClasses)
+  return () => {
+    unsubHash()
+    unsubStorage()
+  }
+}

package/src/bodyClasses.test.js ADDED Viewed

@@ -0,0 +1,150 @@
+import {
+  syncOverrideClasses,
+  setSceneClass,
+  installBodyClassSync,
+} from './bodyClasses.js'
+import { activateHideMode, deactivateHideMode, setShadow } from './hideMode.js'
+/**
+ * Collect all sb- prefixed classes currently on document.body.
+ * @returns {string[]}
+ */
+function getSbClasses() {
+  return [...document.body.classList].filter((c) => c.startsWith('sb-'))
+}
+beforeEach(() => {
+  // Clear all sb- classes and hash between tests
+  for (const cls of getSbClasses()) {
+    document.body.classList.remove(cls)
+  }
+  window.location.hash = ''
+  // Ensure hide mode is off
+  try {
+    deactivateHideMode()
+  } catch {
+    // ignore if not active
+  }
+})
+// ── Override Classes ──
+describe('Override body classes', () => {
+  it('adds sb- classes for hash overrides', () => {
+    window.location.hash = '#theme=dark&sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-sidebar--collapsed')
+  })
+  it('removes stale classes when overrides are cleared', () => {
+    window.location.hash = '#theme=dark&sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    window.location.hash = '#sidebar=collapsed'
+    syncOverrideClasses()
+    expect(getSbClasses()).not.toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-sidebar--collapsed')
+  })
+  it('removes all override classes when hash is empty', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    window.location.hash = ''
+    syncOverrideClasses()
+    const overrideClasses = getSbClasses().filter((c) => !c.startsWith('sb-scene--'))
+    expect(overrideClasses).toEqual([])
+  })
+  it('sanitizes dot-notation keys (dots become dashes)', () => {
+    window.location.hash = '#settings.theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-settings-theme--dark')
+  })
+  it('sanitizes values with special characters', () => {
+    window.location.hash = '#mode=dark.dimmed'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-mode--dark-dimmed')
+  })
+  it('skips overrides with empty values', () => {
+    window.location.hash = '#theme='
+    syncOverrideClasses()
+    const overrideClasses = getSbClasses().filter((c) => !c.startsWith('sb-scene--'))
+    expect(overrideClasses).toEqual([])
+  })
+  it('updates classes when override value changes', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    window.location.hash = '#theme=light'
+    syncOverrideClasses()
+    expect(getSbClasses()).not.toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-theme--light')
+  })
+})
+// ── Scene Classes ──
+describe('Scene body classes', () => {
+  it('sets sb-scene-- class', () => {
+    setSceneClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+  it('replaces previous scene class', () => {
+    setSceneClass('Dashboard')
+    setSceneClass('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('does not interfere with override classes', () => {
+    window.location.hash = '#theme=dark'
+    syncOverrideClasses()
+    setSceneClass('Dashboard')
+    expect(getSbClasses()).toContain('sb-theme--dark')
+    expect(getSbClasses()).toContain('sb-scene--dashboard')
+  })
+})
+// ── Hide Mode ──
+describe('Hide mode body classes', () => {
+  it('reflects shadow overrides as body classes', () => {
+    activateHideMode()
+    setShadow('theme', 'dark')
+    syncOverrideClasses()
+    expect(getSbClasses()).toContain('sb-theme--dark')
+  })
+})
+// ── installBodyClassSync ──
+describe('installBodyClassSync', () => {
+  it('runs initial sync on install', () => {
+    window.location.hash = '#layout=compact'
+    const unsub = installBodyClassSync()
+    expect(getSbClasses()).toContain('sb-layout--compact')
+    unsub()
+  })
+  it('returns an unsubscribe function', () => {
+    const unsub = installBodyClassSync()
+    expect(typeof unsub).toBe('function')
+    unsub()
+  })
+})

package/src/index.js CHANGED Viewed

@@ -27,6 +27,9 @@ 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'
 // Dev tools (vanilla JS, framework-agnostic)
 export { mountDevTools } from './devtools.js'
 export { mountSceneDebug } from './sceneDebug.js'