@dfosco/storyboard 0.5.0-alpha.0

package/src/core/stores/recentArtifacts.js

@@ -0,0 +1,68 @@
+/**
+ * Recent Artifacts — localStorage-backed recents for the command palette.
+ *
+ * Stores artifact identity (type + key + label), not routes.
+ * Routes are derived at read time from the live data index so they
+ * stay correct across branch/basePath changes.
+ */
+
+const STORAGE_KEY = 'storyboard:recent-artifacts'
+const MAX_ITEMS = 10
+
+/**
+ * @typedef {{ type: string, key: string, label: string }} RecentEntry
+ */
+
+/**
+ * Track a recently visited artifact.
+ * Pushes to the top, deduplicates by type+key, trims to MAX_ITEMS.
+ *
+ * @param {string} type  — 'prototype' | 'canvas' | 'story' | 'flow'
+ * @param {string} key   — unique identifier (e.g. dirName, canvas id, story name)
+ * @param {string} label — display label
+ */
+export function trackRecent(type, key, label) {
+  if (!type || !key) return
+  const entries = _read()
+  const deduped = entries.filter(e => !(e.type === type && e.key === key))
+  deduped.unshift({ type, key, label: label || key })
+  _write(deduped.slice(0, MAX_ITEMS))
+}
+
+/**
+ * Get the list of recently visited artifacts, newest first.
+ * @returns {RecentEntry[]}
+ */
+export function getRecent() {
+  return _read()
+}
+
+/**
+ * Clear all recent artifacts. Useful for testing.
+ */
+export function clearRecent() {
+  try {
+    localStorage.removeItem(STORAGE_KEY)
+  } catch { /* ignore */ }
+}
+
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+
+function _read() {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return []
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed : []
+  } catch {
+    return []
+  }
+}
+
+function _write(entries) {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(entries))
+  } catch { /* quota exceeded or unavailable */ }
+}

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

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { trackRecent, getRecent, clearRecent } from './recentArtifacts.js'
+
+describe('recentArtifacts', () => {
+  beforeEach(() => {
+    clearRecent()
+  })
+
+  it('returns empty array when nothing tracked', () => {
+    expect(getRecent()).toEqual([])
+  })
+
+  it('tracks a single entry', () => {
+    trackRecent('prototype', 'my-proto', 'My Proto')
+    const items = getRecent()
+    expect(items).toHaveLength(1)
+    expect(items[0]).toEqual({ type: 'prototype', key: 'my-proto', label: 'My Proto' })
+  })
+
+  it('puts newest entry first', () => {
+    trackRecent('prototype', 'a', 'A')
+    trackRecent('prototype', 'b', 'B')
+    const items = getRecent()
+    expect(items[0].key).toBe('b')
+    expect(items[1].key).toBe('a')
+  })
+
+  it('deduplicates by type+key and moves to top', () => {
+    trackRecent('prototype', 'a', 'A')
+    trackRecent('prototype', 'b', 'B')
+    trackRecent('prototype', 'a', 'A updated')
+    const items = getRecent()
+    expect(items).toHaveLength(2)
+    expect(items[0]).toEqual({ type: 'prototype', key: 'a', label: 'A updated' })
+    expect(items[1].key).toBe('b')
+  })
+
+  it('allows same key with different types', () => {
+    trackRecent('prototype', 'foo', 'Foo Proto')
+    trackRecent('canvas', 'foo', 'Foo Canvas')
+    const items = getRecent()
+    expect(items).toHaveLength(2)
+  })
+
+  it('limits to 10 items', () => {
+    for (let i = 0; i < 15; i++) {
+      trackRecent('prototype', `p${i}`, `Proto ${i}`)
+    }
+    expect(getRecent()).toHaveLength(10)
+    // newest should be first
+    expect(getRecent()[0].key).toBe('p14')
+  })
+
+  it('clears all entries', () => {
+    trackRecent('prototype', 'a', 'A')
+    trackRecent('canvas', 'b', 'B')
+    clearRecent()
+    expect(getRecent()).toEqual([])
+  })
+
+  it('ignores entries with missing type or key', () => {
+    trackRecent('', 'a', 'A')
+    trackRecent('prototype', '', 'B')
+    expect(getRecent()).toEqual([])
+  })
+
+  it('falls back to key as label if label is empty', () => {
+    trackRecent('prototype', 'my-proto', '')
+    expect(getRecent()[0].label).toBe('my-proto')
+  })
+})

package/src/core/stores/sidePanelStore.ts

@@ -0,0 +1,143 @@
+/**
+ * Side Panel Store — manages the open/close state and active tab of the
+ * side panel UI.
+ *
+ * Framework-agnostic state with a subscribe/set interface.
+ * Toggles the `sb-sidepanel-open` class on `<html>` so CSS can react
+ * to the panel being open (e.g. shifting the main content area).
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type SidePanelTab = 'docs' | 'inspector'
+
+export interface SidePanelState {
+  /** Whether the side panel is currently open */
+  open: boolean
+  /** The currently active tab */
+  activeTab: SidePanelTab
+}
+
+type Subscriber<T> = (value: T) => void
+type Unsubscriber = () => void
+
+interface Readable<T> {
+  subscribe(run: Subscriber<T>): Unsubscriber
+}
+
+interface Writable<T> extends Readable<T> {
+  set(value: T): void
+  update(fn: (value: T) => T): void
+}
+
+function writable<T>(initial: T): Writable<T> {
+  let value = initial
+  const subs = new Set<Subscriber<T>>()
+  return {
+    set(v: T) {
+      value = v
+      subs.forEach((fn) => fn(value))
+    },
+    update(fn: (v: T) => T) {
+      value = fn(value)
+      subs.forEach((fn) => fn(value))
+    },
+    subscribe(run: Subscriber<T>): Unsubscriber {
+      subs.add(run)
+      run(value)
+      return () => { subs.delete(run) }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+const PANEL_CLASS = 'sb-sidepanel-open'
+
+const DEFAULT_STATE: SidePanelState = Object.freeze({
+  open: false,
+  activeTab: 'docs',
+})
+
+const _store = writable<SidePanelState>({ ...DEFAULT_STATE })
+
+// ---------------------------------------------------------------------------
+// DOM class sync
+// ---------------------------------------------------------------------------
+
+/**
+ * Toggle the `sb-sidepanel-open` class on `document.documentElement`
+ * to match the current open state. Guarded for SSR.
+ */
+function _syncDomClass(open: boolean): void {
+  if (typeof document === 'undefined') return
+  document.documentElement.classList.toggle(PANEL_CLASS, open)
+}
+
+// ---------------------------------------------------------------------------
+// Readable store
+// ---------------------------------------------------------------------------
+
+/**
+ * Readable store for the side panel state.
+ */
+export const sidePanelState: Readable<SidePanelState> = { subscribe: _store.subscribe }
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+/**
+ * Open the side panel to the given tab.
+ *
+ * @param tab — The tab to display when the panel opens.
+ */
+export function openPanel(tab: SidePanelTab): void {
+  _store.set({ open: true, activeTab: tab })
+  _syncDomClass(true)
+}
+
+/**
+ * Close the side panel. The active tab is preserved so that
+ * re-opening the panel returns to the same tab.
+ */
+export function closePanel(): void {
+  _store.update((s) => ({ ...s, open: false }))
+  _syncDomClass(false)
+}
+
+/**
+ * Toggle the side panel for a specific tab.
+ *
+ * - If the panel is open **and** already showing this tab → close it.
+ * - Otherwise → open the panel to the given tab.
+ *
+ * @param tab — The tab to toggle.
+ */
+export function togglePanel(tab: SidePanelTab): void {
+  _store.update((s) => {
+    const shouldClose = s.open && s.activeTab === tab
+    const next: SidePanelState = shouldClose
+      ? { ...s, open: false }
+      : { open: true, activeTab: tab }
+    _syncDomClass(next.open)
+    return next
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset the side panel store to its default state.
+ * Only for use in tests.
+ */
+export function _resetSidePanel(): void {
+  _store.set({ ...DEFAULT_STATE })
+  _syncDomClass(false)
+}

package/src/core/stores/themeStore.ts

@@ -0,0 +1,291 @@
+/**
+ * Theme Store — manages the active color scheme for the entire app.
+ *
+ * Reads/writes `sb-color-scheme` in localStorage, sets Primer CSS attributes
+ * (`data-color-mode`, `data-light-theme`, `data-dark-theme`) and the internal
+ * `data-sb-theme` attribute on `<html>`, and dispatches a
+ * `storyboard:theme:changed` custom event so that non-store consumers
+ * (React ThemeProvider, etc.) can react.
+ *
+ * Supports a "system" value that follows the OS preference via
+ * `prefers-color-scheme`, updating automatically when the user changes
+ * their system theme.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type ThemeValue =
+  | 'system'
+  | 'light'
+  | 'light_colorblind'
+  | 'dark'
+  | 'dark_colorblind'
+  | 'dark_high_contrast'
+  | 'dark_dimmed'
+
+export interface ThemeOption {
+  name: string
+  value: ThemeValue
+}
+
+export interface ThemeState {
+  /** The stored theme value (may be "system") */
+  theme: ThemeValue
+  /** The resolved CSS theme value (never "system") */
+  resolved: string
+}
+
+type Subscriber<T> = (value: T) => void
+type Unsubscriber = () => void
+
+interface Readable<T> {
+  subscribe(run: Subscriber<T>): Unsubscriber
+}
+
+interface Writable<T> extends Readable<T> {
+  set(value: T): void
+}
+
+function writable<T>(initial: T): Writable<T> {
+  let value = initial
+  const subs = new Set<Subscriber<T>>()
+  return {
+    set(v: T) {
+      value = v
+      subs.forEach((fn) => fn(value))
+    },
+    subscribe(run: Subscriber<T>): Unsubscriber {
+      subs.add(run)
+      run(value)
+      return () => { subs.delete(run) }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const STORAGE_KEY = 'sb-color-scheme'
+
+export const THEMES: ThemeOption[] = [
+  { name: 'System', value: 'system' },
+  { name: 'Light', value: 'light' },
+  { name: 'Light colorblind', value: 'light_colorblind' },
+  { name: 'Dark', value: 'dark' },
+  { name: 'Dark colorblind', value: 'dark_colorblind' },
+  { name: 'Dark high contrast', value: 'dark_high_contrast' },
+  { name: 'Dark Dimmed', value: 'dark_dimmed' },
+]
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getSystemTheme(): string {
+  if (typeof window === 'undefined') return 'light'
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+}
+
+function resolveTheme(value: ThemeValue): string {
+  return value === 'system' ? getSystemTheme() : value
+}
+
+function readStoredTheme(): ThemeValue {
+  if (typeof localStorage === 'undefined') return 'system'
+  const stored = localStorage.getItem(STORAGE_KEY)
+  if (!stored) return 'system'
+  // Legacy values (pre-system support) are plain scheme names
+  if (stored === 'system') return 'system'
+  return stored as ThemeValue
+}
+
+function snapshot(theme: ThemeValue): ThemeState {
+  return { theme, resolved: resolveTheme(theme) }
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+let _current: ThemeValue = readStoredTheme()
+const _store = writable<ThemeState>(snapshot(_current))
+
+function _applyToDOM(theme: ThemeValue, resolved: string): void {
+  if (typeof document === 'undefined') return
+  const el = document.documentElement
+
+  // Per-target resolved themes
+  const prototypeTheme = _syncTargets.prototype ? resolved : 'light'
+  const toolbarTheme = _syncTargets.toolbar ? resolved : 'light'
+  const codeTheme = _syncTargets.codeBoxes ? resolved : 'light'
+  const canvasTheme = _syncTargets.canvas ? resolved : 'light'
+
+  // Internal attributes
+  el.setAttribute('data-sb-theme', prototypeTheme)
+  el.setAttribute('data-sb-code-theme', codeTheme)
+
+  // Toolbar theme — follows global theme when synced, stays light otherwise
+  el.setAttribute('data-sb-toolbar-theme', toolbarTheme)
+  el.setAttribute('data-sb-canvas-theme', canvasTheme)
+
+  // Primer CSS attributes — these drive @primer/react ThemeProvider and
+  // Primer CSS custom-property layers without needing React state updates.
+  if (theme === 'system' && _syncTargets.prototype) {
+    el.setAttribute('data-color-mode', 'auto')
+    el.setAttribute('data-light-theme', 'light')
+    el.setAttribute('data-dark-theme', 'dark')
+  } else if (prototypeTheme.startsWith('dark')) {
+    el.setAttribute('data-color-mode', 'dark')
+    el.setAttribute('data-dark-theme', prototypeTheme)
+    el.setAttribute('data-light-theme', 'light')
+  } else {
+    el.setAttribute('data-color-mode', 'light')
+    el.setAttribute('data-light-theme', prototypeTheme)
+    el.setAttribute('data-dark-theme', 'dark')
+  }
+}
+
+function _dispatchEvent(theme: ThemeValue, resolved: string): void {
+  if (typeof document === 'undefined') return
+  const prototypeTheme = _syncTargets.prototype ? theme : 'light'
+  const prototypeResolved = _syncTargets.prototype ? resolved : 'light'
+  const toolbarResolved = _syncTargets.toolbar ? resolved : 'light'
+  const codeResolved = _syncTargets.codeBoxes ? resolved : 'light'
+  const canvasResolved = _syncTargets.canvas ? resolved : 'light'
+
+  document.dispatchEvent(
+    new CustomEvent('storyboard:theme:changed', {
+      detail: {
+        theme,
+        resolved,
+        prototypeTheme,
+        prototypeResolved,
+        toolbarResolved,
+        codeResolved,
+        canvasResolved,
+      },
+    }),
+  )
+}
+
+/**
+ * Return the current theme value (may be "system").
+ */
+export function getTheme(): ThemeValue {
+  return _current
+}
+
+/**
+ * Set the active theme. Updates localStorage, the DOM attribute,
+ * and dispatches a change event.
+ */
+export function setTheme(value: ThemeValue): void {
+  _current = value
+
+  if (typeof localStorage !== 'undefined') {
+    if (value === 'system') {
+      localStorage.removeItem(STORAGE_KEY)
+    } else {
+      localStorage.setItem(STORAGE_KEY, value)
+    }
+  }
+
+  const state = snapshot(value)
+  _store.set(state)
+  _applyToDOM(value, state.resolved)
+  _dispatchEvent(value, state.resolved)
+}
+
+/**
+ * Readable store for the current theme state.
+ */
+export const themeState: Readable<ThemeState> = { subscribe: _store.subscribe }
+
+// ---------------------------------------------------------------------------
+// OS preference listener
+// ---------------------------------------------------------------------------
+
+if (typeof window !== 'undefined') {
+  window
+    .matchMedia('(prefers-color-scheme: dark)')
+    .addEventListener('change', () => {
+      if (_current !== 'system') return
+      const state = snapshot('system')
+      _store.set(state)
+      _applyToDOM('system', state.resolved)
+      _dispatchEvent('system', state.resolved)
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Theme sync targets
+// ---------------------------------------------------------------------------
+
+/** Which parts of the UI follow the global theme */
+export interface ThemeSyncTargets {
+  prototype: boolean
+  toolbar: boolean
+  codeBoxes: boolean
+  canvas: boolean
+}
+
+const SYNC_STORAGE_KEY = 'sb-theme-sync'
+
+const DEFAULT_SYNC: ThemeSyncTargets = {
+  prototype: true,
+  toolbar: false,
+  codeBoxes: true,
+  canvas: true,
+}
+
+function readStoredSync(): ThemeSyncTargets {
+  if (typeof localStorage === 'undefined') return { ...DEFAULT_SYNC }
+  try {
+    const raw = localStorage.getItem(SYNC_STORAGE_KEY)
+    if (!raw) return { ...DEFAULT_SYNC }
+    return { ...DEFAULT_SYNC, ...JSON.parse(raw) }
+  } catch {
+    return { ...DEFAULT_SYNC }
+  }
+}
+
+let _syncTargets: ThemeSyncTargets = readStoredSync()
+const _syncStore = writable<ThemeSyncTargets>(_syncTargets)
+
+/**
+ * Get the current theme sync targets.
+ */
+export function getThemeSyncTargets(): ThemeSyncTargets {
+  return { ..._syncTargets }
+}
+
+/**
+ * Set a theme sync target. Persists to localStorage.
+ */
+export function setThemeSyncTarget(target: keyof ThemeSyncTargets, value: boolean): void {
+  _syncTargets = { ..._syncTargets, [target]: value }
+  _syncStore.set(_syncTargets)
+
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem(SYNC_STORAGE_KEY, JSON.stringify(_syncTargets))
+  }
+
+  // Re-apply DOM attributes so toolbar/codebox can react
+  const state = snapshot(_current)
+  _applyToDOM(_current, state.resolved)
+  _dispatchEvent(_current, state.resolved)
+}
+
+/**
+ * Readable store for sync target state.
+ */
+export const themeSyncState: Readable<ThemeSyncTargets> = { subscribe: _syncStore.subscribe }
+
+// ---------------------------------------------------------------------------
+// Boot — apply the stored theme immediately on import
+// ---------------------------------------------------------------------------
+
+_applyToDOM(_current, resolveTheme(_current))