@dfosco/storyboard-react 4.0.0-beta.26 → 4.0.0-beta.28

package/src/canvas/widgets/WidgetChrome.jsx

@@ -1,6 +1,6 @@
 import { useState, useCallback, useRef, useEffect, useSyncExternalStore } from 'react'
 import { Tooltip } from '@primer/react'
-import { EyeIcon as OcticonEye, EyeClosedIcon as OcticonEyeClosed, CodeIcon as OcticonCode, UnwrapIcon as OcticonUnwrap, ImageIcon as OcticonImage } from '@primer/octicons-react'
+import { EyeIcon as OcticonEye, EyeClosedIcon as OcticonEyeClosed, CodeIcon as OcticonCode, UnwrapIcon as OcticonUnwrap, ImageIcon as OcticonImage, UnfoldIcon as OcticonUnfold, FoldIcon as OcticonFold } from '@primer/octicons-react'
 import styles from './WidgetChrome.module.css'
 
 const STICKY_NOTE_COLORS = {
@@ -122,6 +122,22 @@ function ExpandIcon() {
   )
 }
 
+function SyncIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      <path d="M1.705 8.005a.75.75 0 0 1 .834.656 5.5 5.5 0 0 0 9.592 2.97l-1.204-1.204a.25.25 0 0 1 .177-.427h3.646a.25.25 0 0 1 .25.25v3.646a.25.25 0 0 1-.427.177l-1.38-1.38A7.002 7.002 0 0 1 1.05 8.84a.75.75 0 0 1 .656-.834ZM8 2.5a5.487 5.487 0 0 0-4.131 1.869l1.204 1.204A.25.25 0 0 1 4.896 6H1.25A.25.25 0 0 1 1 5.75V2.104a.25.25 0 0 1 .427-.177l1.38 1.38A7.002 7.002 0 0 1 14.95 7.16a.75.75 0 0 1-1.49.178A5.5 5.5 0 0 0 8 2.5Z" />
+    </svg>
+  )
+}
+
+function UnfoldIcon() {
+  return <OcticonUnfold size={12} />
+}
+
+function FoldIcon() {
+  return <OcticonFold size={12} />
+}
+
 /** Icon registry — maps icon name strings from config to React components. */
 const ICON_REGISTRY = {
   'trash': DeleteIcon,
@@ -140,6 +156,9 @@ const ICON_REGISTRY = {
   'chevron-down': ChevronDownIcon,
   'download': DownloadIcon,
   'expand': ExpandIcon,
+  'sync': SyncIcon,
+  'unfold': UnfoldIcon,
+  'fold': FoldIcon,
 }
 
 /** Danger-styled actions in the overflow menu. */

package/src/canvas/widgets/embedInteraction.test.jsx

@@ -56,10 +56,10 @@ describe('Embed interaction overlay', () => {
       resizable: false,
     }
 
-    it('renders "Click to interact" hint on hover', () => {
+    it('renders "Click to open" hint when no snapshot exists', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const hint = screen.getByText('Click to interact')
+      const hint = screen.getByText('Click to open')
       expect(hint).toBeInTheDocument()
       // CSS modules mangle class names, just check the element exists
     })
@@ -68,62 +68,60 @@ describe('Embed interaction overlay', () => {
       const { container } = render(<PrototypeEmbed {...defaultProps} />)
       
       // Overlay should exist before interaction
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const overlay = screen.getByRole('button', { name: /click to open/i })
       expect(overlay).toBeInTheDocument()
       expect(container.querySelector('iframe')).not.toBeInTheDocument()
       expect(screen.getByText('Design Overview')).toBeInTheDocument()
-      expect(screen.getByText('Design Overview prototype')).toBeInTheDocument()
       
       // Single click should remove the overlay (enter interactive mode)
       fireEvent.click(overlay)
       
       // Overlay should no longer exist
-      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
-      expect(screen.queryByText('Design Overview prototype')).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
       expect(container.querySelector('iframe')).toBeInTheDocument()
 
       fireEvent.pointerDown(document.body)
-      expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
       expect(container.querySelector('iframe')).not.toBeInTheDocument()
     })
 
     it('does not enter interactive mode on shift+click (preserves multi-select)', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const overlay = screen.getByRole('button', { name: /click to open/i })
       fireEvent.click(overlay, { shiftKey: true })
       
       // Overlay should still exist (did not enter interactive mode)
-      expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
     })
 
     it('does not enter interactive mode on meta+click (preserves multi-select)', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const overlay = screen.getByRole('button', { name: /click to open/i })
       fireEvent.click(overlay, { metaKey: true })
       
-      expect(screen.getByRole('button', { name: /click to interact/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to open/i })).toBeInTheDocument()
     })
 
     it('supports keyboard interaction (Enter key) with event prevention', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const overlay = screen.getByRole('button', { name: /click to open/i })
       const event = { key: 'Enter', preventDefault: vi.fn(), stopPropagation: vi.fn() }
       fireEvent.keyDown(overlay, event)
       
-      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
     })
 
     it('supports keyboard interaction (Space key) with event prevention', () => {
       render(<PrototypeEmbed {...defaultProps} />)
       
-      const overlay = screen.getByRole('button', { name: /click to interact/i })
+      const overlay = screen.getByRole('button', { name: /click to open/i })
       const event = { key: ' ', preventDefault: vi.fn(), stopPropagation: vi.fn() }
       fireEvent.keyDown(overlay, event)
       
-      expect(screen.queryByRole('button', { name: /click to interact/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to open/i })).not.toBeInTheDocument()
     })
   })
 
@@ -167,16 +165,16 @@ describe('Embed interaction overlay', () => {
     it('mounts iframe only after user activation', () => {
       const { container } = render(<StoryWidget {...defaultProps} />)
 
-      const overlay = screen.getByRole('button', { name: /click to interact with story component/i })
+      const overlay = screen.getByRole('button', { name: /click to open story component/i })
       expect(container.querySelector('iframe')).not.toBeInTheDocument()
 
       fireEvent.click(overlay)
 
-      expect(screen.queryByRole('button', { name: /click to interact with story component/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /click to open story component/i })).not.toBeInTheDocument()
       expect(container.querySelector('iframe')).toBeInTheDocument()
 
       fireEvent.pointerDown(document.body)
-      expect(screen.getByRole('button', { name: /click to interact with story component/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /click to open story component/i })).toBeInTheDocument()
       expect(container.querySelector('iframe')).not.toBeInTheDocument()
     })
   })

package/src/canvas/widgets/embedTheme.js

@@ -4,7 +4,7 @@
  */
 export function resolveCanvasTheme() {
   if (typeof localStorage === 'undefined') return 'light'
-  let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: false }
+  let sync = { prototype: true, toolbar: false, codeBoxes: true, canvas: true }
   try {
     const rawSync = localStorage.getItem('sb-theme-sync')
     if (rawSync) sync = { ...sync, ...JSON.parse(rawSync) }
@@ -18,6 +18,42 @@ export function resolveCanvasTheme() {
     window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
 }
 
+/**
+ * Subscribe to canvas theme changes for embed widget snapshot switching.
+ *
+ * Reads `data-sb-canvas-theme` from the nearest ancestor set by CanvasPage.
+ * With canvas sync ON (the default), this attribute follows the global theme.
+ * Uses MutationObserver for immediate reaction + event backup.
+ */
+export function subscribeCanvasTheme({ anchorRef, onTheme }) {
+  if (typeof onTheme !== 'function') return () => {}
+
+  let observed = null
+  let observer = null
+
+  function readAndEmit() {
+    const el = anchorRef?.current?.closest?.('[data-sb-canvas-theme]') || null
+    if (el !== observed) {
+      if (observer) observer.disconnect()
+      observer = null
+      observed = el
+      if (el && typeof MutationObserver !== 'undefined') {
+        observer = new MutationObserver(readAndEmit)
+        observer.observe(el, { attributes: true, attributeFilter: ['data-sb-canvas-theme'] })
+      }
+    }
+    onTheme(el?.getAttribute('data-sb-canvas-theme') || 'light')
+  }
+
+  readAndEmit()
+  document.addEventListener('storyboard:theme:changed', readAndEmit)
+
+  return () => {
+    document.removeEventListener('storyboard:theme:changed', readAndEmit)
+    if (observer) observer.disconnect()
+  }
+}
+
 export function getEmbedChromeVars(theme) {
   const value = String(theme || 'light')
   if (value === 'dark_dimmed') {

package/src/canvas/widgets/githubUrl.js

@@ -0,0 +1,82 @@
+const GH_HOST_RE = /^(www\.)?github\.com$/i
+const ISSUE_PATH_RE = /^\/([^/]+)\/([^/]+)\/issues\/(\d+)\/?$/
+const DISCUSSION_PATH_RE = /^\/([^/]+)\/([^/]+)\/discussions\/(\d+)\/?$/
+const PULL_REQUEST_PATH_RE = /^\/([^/]+)\/([^/]+)\/pull\/(\d+)\/?$/
+const ISSUE_COMMENT_HASH_RE = /^#issuecomment-(\d+)$/i
+const DISCUSSION_COMMENT_HASH_RE = /^#discussioncomment-(\d+)$/i
+
+function toNumber(raw) {
+  const value = Number.parseInt(raw, 10)
+  return Number.isFinite(value) ? value : null
+}
+
+/**
+ * Parse supported GitHub embed URLs (issues, discussions, comments).
+ * @param {string} rawUrl
+ * @returns {null | {
+ *   kind: 'issue' | 'discussion' | 'comment',
+ *   parentKind: 'issue' | 'discussion',
+ *   owner: string,
+ *   repo: string,
+ *   number: number,
+ *   commentId?: number
+ * }}
+ */
+export function parseGitHubUrl(rawUrl) {
+  try {
+    const parsed = new URL(rawUrl)
+    if (!GH_HOST_RE.test(parsed.hostname)) return null
+
+    const issueMatch = parsed.pathname.match(ISSUE_PATH_RE)
+    if (issueMatch) {
+      const [, owner, repo, numberRaw] = issueMatch
+      const number = toNumber(numberRaw)
+      if (!number) return null
+
+      const commentMatch = parsed.hash.match(ISSUE_COMMENT_HASH_RE)
+      if (commentMatch) {
+        const commentId = toNumber(commentMatch[1])
+        if (!commentId) return null
+        return { kind: 'comment', parentKind: 'issue', owner, repo, number, commentId }
+      }
+
+      if (parsed.hash) return null
+      return { kind: 'issue', parentKind: 'issue', owner, repo, number }
+    }
+
+    const discussionMatch = parsed.pathname.match(DISCUSSION_PATH_RE)
+    if (discussionMatch) {
+      const [, owner, repo, numberRaw] = discussionMatch
+      const number = toNumber(numberRaw)
+      if (!number) return null
+
+      const commentMatch = parsed.hash.match(DISCUSSION_COMMENT_HASH_RE)
+      if (commentMatch) {
+        const commentId = toNumber(commentMatch[1])
+        if (!commentId) return null
+        return { kind: 'comment', parentKind: 'discussion', owner, repo, number, commentId }
+      }
+
+      if (parsed.hash) return null
+      return { kind: 'discussion', parentKind: 'discussion', owner, repo, number }
+    }
+
+    const prMatch = parsed.pathname.match(PULL_REQUEST_PATH_RE)
+    if (prMatch) {
+      const [, owner, repo, numberRaw] = prMatch
+      const number = toNumber(numberRaw)
+      if (!number) return null
+
+      if (parsed.hash) return null
+      return { kind: 'pull_request', parentKind: 'pull_request', owner, repo, number }
+    }
+  } catch {
+    return null
+  }
+
+  return null
+}
+
+export function isGitHubEmbedUrl(rawUrl) {
+  return parseGitHubUrl(rawUrl) !== null
+}

package/src/canvas/widgets/githubUrl.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest'
+import { isGitHubEmbedUrl, parseGitHubUrl } from './githubUrl.js'
+
+describe('parseGitHubUrl', () => {
+  it('classifies issue URLs', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/issues/12')).toEqual({
+      kind: 'issue',
+      parentKind: 'issue',
+      owner: 'dfosco',
+      repo: 'storyboard',
+      number: 12,
+    })
+  })
+
+  it('classifies discussion URLs', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/discussions/99')).toEqual({
+      kind: 'discussion',
+      parentKind: 'discussion',
+      owner: 'dfosco',
+      repo: 'storyboard',
+      number: 99,
+    })
+  })
+
+  it('classifies issue comment URLs', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/issues/12#issuecomment-345')).toEqual({
+      kind: 'comment',
+      parentKind: 'issue',
+      owner: 'dfosco',
+      repo: 'storyboard',
+      number: 12,
+      commentId: 345,
+    })
+  })
+
+  it('classifies discussion comment URLs', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/discussions/99#discussioncomment-888')).toEqual({
+      kind: 'comment',
+      parentKind: 'discussion',
+      owner: 'dfosco',
+      repo: 'storyboard',
+      number: 99,
+      commentId: 888,
+    })
+  })
+
+  it('classifies pull request URLs', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/pull/12')).toEqual({
+      kind: 'pull_request',
+      parentKind: 'pull_request',
+      owner: 'dfosco',
+      repo: 'storyboard',
+      number: 12,
+    })
+  })
+
+  it('rejects unsupported paths and hashes', () => {
+    expect(parseGitHubUrl('https://github.com/dfosco/storyboard/issues/12#random')).toBeNull()
+    expect(parseGitHubUrl('https://example.com/dfosco/storyboard/issues/12')).toBeNull()
+    expect(parseGitHubUrl('not a url')).toBeNull()
+  })
+})
+
+describe('isGitHubEmbedUrl', () => {
+  it('returns true for supported GitHub URLs', () => {
+    expect(isGitHubEmbedUrl('https://github.com/dfosco/storyboard/issues/12')).toBe(true)
+    expect(isGitHubEmbedUrl('https://github.com/dfosco/storyboard/discussions/99#discussioncomment-888')).toBe(true)
+    expect(isGitHubEmbedUrl('https://github.com/dfosco/storyboard/pull/1')).toBe(true)
+  })
+
+  it('returns false for unsupported URLs', () => {
+    expect(isGitHubEmbedUrl('https://example.com')).toBe(false)
+  })
+})

package/src/canvas/widgets/refreshQueue.js

@@ -0,0 +1,108 @@
+/**
+ * Concurrent refresh queue for bulk snapshot recapture (e.g. on theme change).
+ *
+ * Captures run in parallel (up to MAX_CONCURRENT) for speed, but REVEALS are
+ * staggered on a fixed timeline — widget 0 reveals at 0ms, widget 1 at
+ * REVEAL_INTERVAL ms, widget 2 at 2×REVEAL_INTERVAL ms, etc., all relative to
+ * batch start. This creates a clean, predictable wave sweep regardless of how
+ * fast each capture completes.
+ *
+ * After a batch completes, any widgets that failed are re-enqueued for a
+ * single retry pass.
+ *
+ * Sorted spatially (top-to-bottom, left-to-right) before assigning reveal slots.
+ * Supports cancellation by widget ID.
+ */
+const queue = []
+let running = 0
+let drainScheduled = false
+let batchTotal = 0
+let batchDone = 0
+const batchFailed = []
+
+const MAX_CONCURRENT = 4
+export const REVEAL_INTERVAL = 200
+
+/**
+ * Enqueue a snapshot refresh task for a widget.
+ * @param {string} widgetId — unique widget identifier (for cancellation)
+ * @param {(meta: { revealOrder: number, batchStart: number }) => Promise<boolean>} fn
+ *   Must resolve to `true` on success, `false` on failure.
+ * @param {{ x: number, y: number }} [pos] — spatial position for wave ordering
+ */
+export function enqueueRefresh(widgetId, fn, pos) {
+  const existing = queue.findIndex(item => item.widgetId === widgetId)
+  if (existing !== -1) queue.splice(existing, 1)
+
+  queue.push({ widgetId, fn, x: pos?.x ?? 0, y: pos?.y ?? 0 })
+  scheduleDrain()
+}
+
+/**
+ * Cancel a pending refresh for a widget (e.g. user activated it manually).
+ */
+export function cancelRefresh(widgetId) {
+  const idx = queue.findIndex(item => item.widgetId === widgetId)
+  if (idx !== -1) queue.splice(idx, 1)
+}
+
+function scheduleDrain() {
+  if (drainScheduled) return
+  drainScheduled = true
+  // Batch all enqueueRefresh calls from the same React commit, then sort
+  // spatially and assign reveal slots before starting captures.
+  setTimeout(() => {
+    drainScheduled = false
+    queue.sort((a, b) => a.y - b.y || a.x - b.x)
+    const batchStart = Date.now()
+    batchTotal = queue.length
+    batchDone = 0
+    batchFailed.length = 0
+    queue.forEach((item, i) => {
+      item.revealOrder = i
+      item.batchStart = batchStart
+      item.isRetry = item.isRetry || false
+    })
+    drain()
+  }, 0)
+}
+
+function onTaskDone(success, item) {
+  batchDone++
+  if (!success && !item.isRetry) {
+    batchFailed.push(item)
+  }
+  // When batch is complete, re-enqueue failures for one retry
+  if (batchDone >= batchTotal && batchFailed.length > 0) {
+    const retries = batchFailed.splice(0)
+    for (const failed of retries) {
+      failed.isRetry = true
+      queue.push(failed)
+    }
+    batchTotal = queue.length
+    batchDone = 0
+    const batchStart = Date.now()
+    queue.forEach((item, i) => {
+      item.revealOrder = i
+      item.batchStart = batchStart
+    })
+  }
+  drain()
+}
+
+function drain() {
+  if (running >= MAX_CONCURRENT || queue.length === 0) return
+
+  running++
+  const item = queue.shift()
+  const { fn, revealOrder, batchStart } = item
+  Promise.resolve()
+    .then(() => fn({ revealOrder, batchStart }))
+    .then((success) => { running--; onTaskDone(success !== false, item) })
+    .catch(() => { running--; onTaskDone(false, item) })
+
+  // Start next capture immediately (no stagger on capture start — only reveals are staggered)
+  if (queue.length > 0 && running < MAX_CONCURRENT) {
+    drain()
+  }
+}