@dfosco/storyboard-react 3.11.1-beta.0 → 3.11.1

package/src/canvas/widgets/figmaUrl.js

@@ -0,0 +1,118 @@
+/**
+ * Figma URL utilities — detection, sanitization, and embed URL transformation.
+ *
+ * Supports three Figma link types:
+ *   - Board:  figma.com/board/{key}/{name}
+ *   - Design: figma.com/design/{key}/{name}
+ *   - Proto:  figma.com/proto/{key}/{name}
+ */
+
+const FIGMA_HOST_RE = /^(www\.)?figma\.com$/
+const FIGMA_PATH_RE = /^\/(board|design|proto)\/[A-Za-z0-9]+/
+
+/** Params to strip from stored/embed URLs (session/tracking tokens). */
+const STRIP_PARAMS = new Set(['t'])
+
+/**
+ * Check whether a URL string is a Figma board, design, or prototype link.
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isFigmaUrl(url) {
+  try {
+    const parsed = new URL(url)
+    return FIGMA_HOST_RE.test(parsed.hostname) && FIGMA_PATH_RE.test(parsed.pathname)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Return the Figma link type: 'board', 'design', or 'proto'.
+ * Returns null for non-Figma URLs.
+ * @param {string} url
+ * @returns {'board' | 'design' | 'proto' | null}
+ */
+export function getFigmaType(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return null
+    const match = parsed.pathname.match(FIGMA_PATH_RE)
+    if (!match) return null
+    return match[1]
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Sanitize a Figma URL for storage — strips tracking params like `t`.
+ * Returns a canonical www.figma.com URL safe to persist in canvas data.
+ * @param {string} url — raw pasted Figma URL
+ * @returns {string} sanitized URL
+ */
+export function sanitizeFigmaUrl(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return url
+    // Normalize to www.figma.com
+    parsed.hostname = 'www.figma.com'
+    for (const key of STRIP_PARAMS) {
+      parsed.searchParams.delete(key)
+    }
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Transform a Figma URL into its embed counterpart.
+ *
+ * - Replaces host with `embed.figma.com`
+ * - Strips tracking params (`t`)
+ * - Appends `embed-host=share`
+ *
+ * @param {string} url — original Figma URL
+ * @returns {string} embed URL, or the original URL if it can't be transformed
+ */
+export function toFigmaEmbedUrl(url) {
+  try {
+    const parsed = new URL(url)
+    if (!FIGMA_HOST_RE.test(parsed.hostname)) return url
+
+    parsed.hostname = 'embed.figma.com'
+
+    // Strip tracking/session params
+    for (const key of STRIP_PARAMS) {
+      parsed.searchParams.delete(key)
+    }
+
+    // Ensure embed-host is set
+    parsed.searchParams.set('embed-host', 'share')
+
+    return parsed.toString()
+  } catch {
+    return url
+  }
+}
+
+/**
+ * Extract a human-readable title from a Figma URL.
+ * Uses the name segment from the path (e.g. "Security-Products-HQ").
+ * @param {string} url
+ * @returns {string}
+ */
+export function getFigmaTitle(url) {
+  try {
+    const parsed = new URL(url)
+    // Path: /board|design|proto/{key}/{name}
+    const segments = parsed.pathname.split('/').filter(Boolean)
+    if (segments.length >= 3) {
+      return segments[2].replace(/-/g, ' ')
+    }
+    return 'Figma'
+  } catch {
+    return 'Figma'
+  }
+}

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

@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest'
+import { isFigmaUrl, getFigmaType, toFigmaEmbedUrl, getFigmaTitle, sanitizeFigmaUrl } from './figmaUrl.js'
+
+describe('isFigmaUrl', () => {
+  it('detects board URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0')).toBe(true)
+  })
+
+  it('detects design URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=103-4739')).toBe(true)
+  })
+
+  it('detects proto URLs', () => {
+    expect(isFigmaUrl('https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=122-9632&p=f&t=9XSi047pSbt81sZS-0&scaling=min-zoom')).toBe(true)
+  })
+
+  it('works without www prefix', () => {
+    expect(isFigmaUrl('https://figma.com/board/abc123/My-Board')).toBe(true)
+  })
+
+  it('rejects non-Figma URLs', () => {
+    expect(isFigmaUrl('https://example.com/board/abc')).toBe(false)
+    expect(isFigmaUrl('https://www.figma.com/file/abc')).toBe(false)
+    expect(isFigmaUrl('not a url')).toBe(false)
+    expect(isFigmaUrl('')).toBe(false)
+  })
+})
+
+describe('getFigmaType', () => {
+  it('returns board for board URLs', () => {
+    expect(getFigmaType('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Name')).toBe('board')
+  })
+
+  it('returns design for design URLs', () => {
+    expect(getFigmaType('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Name')).toBe('design')
+  })
+
+  it('returns proto for proto URLs', () => {
+    expect(getFigmaType('https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Name')).toBe('proto')
+  })
+
+  it('returns null for non-Figma URLs', () => {
+    expect(getFigmaType('https://example.com')).toBeNull()
+  })
+})
+
+describe('toFigmaEmbedUrl', () => {
+  it('transforms board URL', () => {
+    const input = 'https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ')
+    expect(parsed.searchParams.get('node-id')).toBe('0-1')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('transforms design URL', () => {
+    const input = 'https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=103-4739'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')
+    expect(parsed.searchParams.get('node-id')).toBe('103-4739')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+  })
+
+  it('transforms proto URL and preserves relevant params', () => {
+    const input = 'https://www.figma.com/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox?node-id=122-9632&p=f&t=9XSi047pSbt81sZS-0&scaling=min-zoom&content-scaling=fixed&page-id=103%3A4739&starting-point-node-id=140%3A5949'
+    const result = toFigmaEmbedUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('embed.figma.com')
+    expect(parsed.pathname).toBe('/proto/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')
+    expect(parsed.searchParams.get('node-id')).toBe('122-9632')
+    expect(parsed.searchParams.get('p')).toBe('f')
+    expect(parsed.searchParams.get('scaling')).toBe('min-zoom')
+    expect(parsed.searchParams.get('content-scaling')).toBe('fixed')
+    expect(parsed.searchParams.get('page-id')).toBe('103:4739')
+    expect(parsed.searchParams.get('starting-point-node-id')).toBe('140:5949')
+    expect(parsed.searchParams.get('embed-host')).toBe('share')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('returns original URL for non-Figma URLs', () => {
+    expect(toFigmaEmbedUrl('https://example.com')).toBe('https://example.com')
+  })
+})
+
+describe('getFigmaTitle', () => {
+  it('extracts title from board URL', () => {
+    expect(getFigmaTitle('https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ')).toBe('Security Products HQ')
+  })
+
+  it('extracts title from design URL', () => {
+    expect(getFigmaTitle('https://www.figma.com/design/i8jI8RuxPnGQGp2QllfAr7/Darby-s-copilot-metric-sandbox')).toBe("Darby s copilot metric sandbox")
+  })
+
+  it('returns Figma for URLs without name segment', () => {
+    expect(getFigmaTitle('https://www.figma.com/board/abc')).toBe('Figma')
+  })
+})
+
+describe('sanitizeFigmaUrl', () => {
+  it('strips tracking param and normalizes to www.figma.com', () => {
+    const input = 'https://www.figma.com/board/QlwxSiYxYQsHmnLNYpQRtR/Security-Products-HQ?node-id=0-1&t=XBF45Am0VgicAITG-0'
+    const result = sanitizeFigmaUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.hostname).toBe('www.figma.com')
+    expect(parsed.searchParams.get('node-id')).toBe('0-1')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('normalizes figma.com to www.figma.com', () => {
+    const input = 'https://figma.com/board/abc/Name?node-id=0-1'
+    const result = sanitizeFigmaUrl(input)
+    expect(new URL(result).hostname).toBe('www.figma.com')
+  })
+
+  it('preserves all non-tracking params for proto URLs', () => {
+    const input = 'https://www.figma.com/proto/abc/Name?node-id=1-2&p=f&t=TOKEN&scaling=min-zoom&page-id=103%3A4739'
+    const result = sanitizeFigmaUrl(input)
+    const parsed = new URL(result)
+
+    expect(parsed.searchParams.get('node-id')).toBe('1-2')
+    expect(parsed.searchParams.get('p')).toBe('f')
+    expect(parsed.searchParams.get('scaling')).toBe('min-zoom')
+    expect(parsed.searchParams.get('page-id')).toBe('103:4739')
+    expect(parsed.searchParams.has('t')).toBe(false)
+  })
+
+  it('returns non-Figma URLs unchanged', () => {
+    expect(sanitizeFigmaUrl('https://example.com')).toBe('https://example.com')
+  })
+})

package/src/canvas/widgets/index.js

@@ -2,6 +2,8 @@ import StickyNote from './StickyNote.jsx'
 import MarkdownBlock from './MarkdownBlock.jsx'
 import PrototypeEmbed from './PrototypeEmbed.jsx'
 import LinkPreview from './LinkPreview.jsx'
+import ImageWidget from './ImageWidget.jsx'
+import FigmaEmbed from './FigmaEmbed.jsx'
 
 /**
  * Maps widget type strings to their React components.
@@ -12,6 +14,8 @@ export const widgetRegistry = {
   'markdown': MarkdownBlock,
   'prototype': PrototypeEmbed,
   'link-preview': LinkPreview,
+  'image': ImageWidget,
+  'figma-embed': FigmaEmbed,
 }
 
 /**

package/src/canvas/widgets/widgetConfig.js

@@ -6,9 +6,44 @@
  *
  * The config is the single source of truth for widget definitions —
  * prop schemas, feature lists, labels, and icons all come from here.
+ *
+ * Supports `$variable` references in string values, resolved from
+ * the top-level `variables` object in widgets.config.json.
  */
 import widgetsConfig from '@dfosco/storyboard-core/widgets.config.json'
 
+/** Variables defined in config — used to resolve `$key` references. */
+const variables = widgetsConfig.variables || {}
+
+/**
+ * Resolve `$variable` references in a string value.
+ * Returns the original value if it's not a string or doesn't start with `$`.
+ */
+function resolveVar(value) {
+  if (typeof value !== 'string' || !value.startsWith('$')) return value
+  const key = value.slice(1)
+  return variables[key] ?? value
+}
+
+/**
+ * Resolve all string values in a feature object, including nested items.
+ */
+function resolveFeature(feature) {
+  const resolved = {}
+  for (const [key, val] of Object.entries(feature)) {
+    if (key === 'items' && Array.isArray(val)) {
+      resolved[key] = val.map((item) => {
+        const r = {}
+        for (const [k, v] of Object.entries(item)) r[k] = resolveVar(v)
+        return r
+      })
+    } else {
+      resolved[key] = resolveVar(val)
+    }
+  }
+  return resolved
+}
+
 /**
  * Convert a config prop definition to the schema shape used by widgetProps.js.
  * Config uses `"default"`, schema uses `"defaultValue"`.
@@ -42,19 +77,52 @@ function buildSchemas() {
   return result
 }
 
+/**
+ * Build resolved widget type entries with variables expanded in features.
+ */
+function buildWidgetTypes() {
+  const result = {}
+  for (const [type, def] of Object.entries(widgetsConfig.widgets)) {
+    result[type] = {
+      ...def,
+      features: (def.features || []).map(resolveFeature),
+    }
+  }
+  return result
+}
+
 /** All widget schemas, keyed by type string. */
 export const schemas = buildSchemas()
 
-/** Full widget config entries, keyed by type string. */
-export const widgetTypes = widgetsConfig.widgets
+/** Full widget config entries (with resolved variables), keyed by type string. */
+export const widgetTypes = buildWidgetTypes()
 
 /**
  * Get the feature list for a widget type.
+ * In production, only features with `prod: true` are returned.
+ * In dev, all features are returned.
  * @param {string} type — widget type string
- * @returns {Array} features array from config, or empty array
+ * @returns {Array} features array from config (variables resolved), or empty array
  */
 export function getFeatures(type) {
-  return widgetTypes[type]?.features ?? []
+  const features = widgetTypes[type]?.features ?? []
+  if (import.meta.env?.PROD) {
+    return features.filter(f => f.prod)
+  }
+  return features
+}
+
+/**
+ * Check if a widget type supports resize in the current environment.
+ * Returns false if resize is disabled, or if in production and prod is not true.
+ * @param {string} type — widget type string
+ * @returns {boolean}
+ */
+export function isResizable(type) {
+  const resize = widgetTypes[type]?.resize
+  if (!resize?.enabled) return false
+  if (import.meta.env?.PROD && !resize.prod) return false
+  return true
 }
 
 /**
@@ -70,10 +138,10 @@ export function getWidgetMeta(type) {
 
 /**
  * Get all widget types as an array of { type, label, icon } for menus.
- * Excludes link-preview which is created via paste only.
+ * Excludes link-preview, image, and figma-embed which are created via paste only.
  */
 export function getMenuWidgetTypes() {
   return Object.entries(widgetTypes)
-    .filter(([type]) => type !== 'link-preview')
+    .filter(([type]) => type !== 'link-preview' && type !== 'image' && type !== 'figma-embed')
     .map(([type, def]) => ({ type, label: def.label, icon: def.icon }))
 }

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { isResizable, getFeatures, getWidgetMeta } from './widgetConfig.js'
+
+describe('isResizable', () => {
+  // Vitest runs with import.meta.env.PROD = true, so prod: false widgets
+  // correctly return false. This tests the production behavior.
+  it('returns false for resize-enabled widgets when prod is false (production env)', () => {
+    expect(isResizable('sticky-note')).toBe(false)
+    expect(isResizable('prototype')).toBe(false)
+    expect(isResizable('figma-embed')).toBe(false)
+    expect(isResizable('image')).toBe(false)
+    expect(isResizable('component')).toBe(false)
+  })
+
+  it('returns false for widget types with resize disabled', () => {
+    expect(isResizable('markdown')).toBe(false)
+    expect(isResizable('link-preview')).toBe(false)
+  })
+
+  it('returns false for unknown widget types', () => {
+    expect(isResizable('nonexistent')).toBe(false)
+  })
+})
+
+describe('getFeatures', () => {
+  it('returns features array for known widget types', () => {
+    const features = getFeatures('sticky-note')
+    expect(Array.isArray(features)).toBe(true)
+    expect(features.length).toBeGreaterThan(0)
+  })
+
+  it('returns empty array for unknown widget types', () => {
+    expect(getFeatures('nonexistent')).toEqual([])
+  })
+})
+
+describe('getWidgetMeta', () => {
+  it('returns label and icon for known types', () => {
+    const meta = getWidgetMeta('sticky-note')
+    expect(meta).toEqual({ label: 'Sticky Note', icon: '📝' })
+  })
+
+  it('returns null for unknown types', () => {
+    expect(getWidgetMeta('nonexistent')).toBeNull()
+  })
+})

package/src/canvas/widgets/widgetProps.js

@@ -127,3 +127,5 @@ export const stickyNoteSchema = schemas['sticky-note']
 export const markdownSchema = schemas['markdown']
 export const prototypeEmbedSchema = schemas['prototype']
 export const linkPreviewSchema = schemas['link-preview']
+export const imageSchema = schemas['image']
+export const figmaEmbedSchema = schemas['figma-embed']

package/src/context.jsx

@@ -22,6 +22,11 @@ function matchCanvasRoute(pathname) {
   return canvasRouteMap.get(normalized) || null
 }
 
+function isCanvasPath(pathname) {
+  const normalized = pathname.replace(/\/+$/, '') || '/'
+  return normalized === '/canvas' || normalized.startsWith('/canvas/')
+}
+
 /**
  * Derives the top-level prototype name from a pathname.
  * "/Dashboard" → "Dashboard", "/Dashboard/sub" → "Dashboard"
@@ -62,6 +67,10 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
 
   // Canvas route detection — matches current URL against registered canvas routes
   const canvasName = useMemo(() => matchCanvasRoute(location.pathname), [location.pathname])
+  const isMissingCanvasRoute = useMemo(
+    () => isCanvasPath(location.pathname) && !canvasName,
+    [location.pathname, canvasName],
+  )
 
   const searchParams = new URLSearchParams(location.search)
   const sceneParam = searchParams.get('flow') || searchParams.get('scene')
@@ -70,7 +79,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
 
   // Resolve flow name with prototype scoping (skip for canvas pages)
   const activeFlowName = useMemo(() => {
-    if (canvasName) return null
+    if (canvasName || isMissingCanvasRoute) return null
     const requested = sceneParam || flowName || sceneName
     if (requested) {
       // Allow fully-scoped flow names from URLs/widgets without re-prefixing
@@ -94,7 +103,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     // 4. Global default — or null if no flow exists at all
     if (flowExists('default')) return 'default'
     return null
-  }, [canvasName, sceneParam, flowName, sceneName, prototypeName, pageFlow])
+  }, [canvasName, isMissingCanvasRoute, sceneParam, flowName, sceneName, prototypeName, pageFlow])
 
   // Auto-install body class sync (sb-key--value classes on <body>)
   useEffect(() => installBodyClassSync(), [])
@@ -117,7 +126,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
 
   // Skip flow loading for canvas pages and flow-less pages
   const { data, error } = useMemo(() => {
-    if (canvasName) return { data: null, error: null }
+    if (canvasName || isMissingCanvasRoute) return { data: null, error: null }
     if (!activeFlowName) return { data: {}, error: null }
     try {
       let flowData = loadFlow(activeFlowName)
@@ -136,7 +145,7 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     } catch (err) {
       return { data: null, error: err.message }
     }
-  }, [canvasName, activeFlowName, recordName, recordParam, params, prototypeName])
+  }, [canvasName, isMissingCanvasRoute, activeFlowName, recordName, recordParam, params, prototypeName])
 
   // Canvas pages get their own rendering path — no flow data needed
   if (canvasName) {
@@ -157,6 +166,27 @@ export default function StoryboardProvider({ flowName, sceneName, recordName, re
     )
   }
 
+  if (isMissingCanvasRoute) {
+    const currentUrl = `${location.pathname}${location.search}`
+    const truncatedUrl = currentUrl.length > 60
+      ? currentUrl.slice(0, 60) + '…'
+      : currentUrl
+
+    return (
+      <main className={styles.container}>
+        <div className={styles.banner}>
+          <strong>Canvas not found</strong>
+          No canvas matches this route.
+        </div>
+        <p className={styles.meta}>
+          Tried to open{' '}
+          <a href={currentUrl} title={currentUrl}>{truncatedUrl}</a>
+        </p>
+        <a className={styles.homeLink} href="/">← Go to index page</a>
+      </main>
+    )
+  }
+
   const value = {
     data,
     error,

package/src/context.test.jsx

@@ -280,4 +280,17 @@ describe('StoryboardProvider', () => {
     )
     expect(screen.getByTestId('ctx')).toHaveTextContent('Global Default')
   })
+
+  it('shows a simple 404 for unknown canvas routes with an index link', () => {
+    mockUseLocation.mockReturnValue({ pathname: '/canvas/unknown-board', search: '', hash: '' })
+
+    render(
+      <StoryboardProvider>
+        <ContextReader />
+      </StoryboardProvider>,
+    )
+
+    expect(screen.getByText('Canvas not found')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: /go to index page/i })).toHaveAttribute('href', '/')
+  })
 })