@dfosco/storyboard-react 2.7.1 → 3.0.0

package/src/canvas/widgets/PrototypeEmbed.jsx

@@ -0,0 +1,33 @@
+import WidgetWrapper from './WidgetWrapper.jsx'
+import { readProp, prototypeEmbedSchema } from './widgetProps.js'
+import styles from './PrototypeEmbed.module.css'
+
+export default function PrototypeEmbed({ props, onRemove }) {
+  const src = readProp(props, 'src', prototypeEmbedSchema)
+  const width = readProp(props, 'width', prototypeEmbedSchema)
+  const height = readProp(props, 'height', prototypeEmbedSchema)
+  const label = readProp(props, 'label', prototypeEmbedSchema) || src
+
+  // Build the full iframe URL using the app's base path
+  const basePath = (import.meta.env.BASE_URL || '/').replace(/\/$/, '')
+  const iframeSrc = src ? `${basePath}${src}` : ''
+
+  return (
+    <WidgetWrapper onRemove={onRemove}>
+      <div className={styles.embed} style={{ width, height }}>
+        {iframeSrc ? (
+          <iframe
+            src={iframeSrc}
+            className={styles.iframe}
+            title={label || 'Prototype embed'}
+            sandbox="allow-same-origin allow-scripts allow-forms allow-popups"
+          />
+        ) : (
+          <div className={styles.empty}>
+            <p>No prototype URL set</p>
+          </div>
+        )}
+      </div>
+    </WidgetWrapper>
+  )
+}

package/src/canvas/widgets/PrototypeEmbed.module.css

@@ -0,0 +1,26 @@
+.embed {
+  position: relative;
+  overflow: hidden;
+  background: var(--bgColor-default, #ffffff);
+}
+
+.iframe {
+  width: 100%;
+  height: 100%;
+  border: none;
+  display: block;
+}
+
+.empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: var(--fgColor-muted, #656d76);
+  font-size: 14px;
+  font-style: italic;
+}
+
+.empty p {
+  margin: 0;
+}

package/src/canvas/widgets/StickyNote.jsx

@@ -0,0 +1,106 @@
+import { useState, useRef, useEffect, useCallback } from 'react'
+import { readProp, stickyNoteSchema } from './widgetProps.js'
+import styles from './StickyNote.module.css'
+
+const COLORS = {
+  yellow: { bg: '#fff8c5', border: '#d4a72c', dot: '#e8c846' },
+  blue: { bg: '#ddf4ff', border: '#54aeff', dot: '#74b9ff' },
+  green: { bg: '#dafbe1', border: '#4ac26b', dot: '#6dd58c' },
+  pink: { bg: '#ffebe9', border: '#ff8182', dot: '#ff9a9e' },
+  purple: { bg: '#fbefff', border: '#c297ff', dot: '#d4a8ff' },
+  orange: { bg: '#fff1e5', border: '#d18616', dot: '#e8a844' },
+}
+
+export default function StickyNote({ props, onUpdate, onRemove }) {
+  const text = readProp(props, 'text', stickyNoteSchema)
+  const color = readProp(props, 'color', stickyNoteSchema)
+  const palette = COLORS[color] ?? COLORS.yellow
+  const textareaRef = useRef(null)
+  const [editing, setEditing] = useState(false)
+
+  useEffect(() => {
+    if (editing && textareaRef.current) {
+      textareaRef.current.focus()
+      textareaRef.current.selectionStart = textareaRef.current.value.length
+    }
+  }, [editing])
+
+  const handleTextChange = useCallback((e) => {
+    onUpdate?.({ text: e.target.value })
+  }, [onUpdate])
+
+  const handleColorChange = useCallback((newColor) => {
+    onUpdate?.({ color: newColor })
+  }, [onUpdate])
+
+  return (
+    <div className={styles.container}>
+      <article
+        className={styles.sticky}
+        style={{ '--sticky-bg': palette.bg, '--sticky-border': palette.border }}
+      >
+        {onRemove && (
+          <button
+            className={styles.removeBtn}
+            onClick={(e) => { e.stopPropagation(); onRemove() }}
+            title="Remove"
+            aria-label="Remove sticky note"
+          >×</button>
+        )}
+        {editing ? (
+          <textarea
+            ref={textareaRef}
+            className={styles.textarea}
+            value={text}
+            onChange={handleTextChange}
+            onBlur={() => setEditing(false)}
+            onMouseDown={(e) => e.stopPropagation()}
+            onPointerDown={(e) => e.stopPropagation()}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape') setEditing(false)
+            }}
+            placeholder="Type here…"
+          />
+        ) : (
+          <p
+            className={styles.text}
+            onDoubleClick={() => setEditing(true)}
+            role="button"
+            tabIndex={0}
+            onKeyDown={(e) => { if (e.key === 'Enter') setEditing(true) }}
+          >
+            {text || 'Double-click to edit…'}
+          </p>
+        )}
+      </article>
+
+      {/* Color picker — dot trigger below the sticky */}
+      <div
+        className={styles.pickerArea}
+        onMouseDown={(e) => e.stopPropagation()}
+        onPointerDown={(e) => e.stopPropagation()}
+      >
+        <span
+          className={styles.pickerDot}
+          style={{ background: palette.dot }}
+        />
+        <div className={styles.pickerPopup}>
+          {Object.entries(COLORS).map(([colorName, c]) => (
+            <button
+              key={colorName}
+              className={`${styles.colorDot} ${colorName === color ? styles.active : ''}`}
+              style={{ background: c.bg, borderColor: c.border }}
+              onClick={(e) => {
+                e.stopPropagation()
+                handleColorChange(colorName)
+              }}
+              title={colorName}
+              aria-label={`Set color to ${colorName}`}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+

package/src/canvas/widgets/StickyNote.module.css

@@ -0,0 +1,136 @@
+.container {
+  position: relative;
+}
+
+.sticky {
+  background: var(--sticky-bg, #fff8c5);
+  border-radius: 2px;
+  min-width: 180px;
+  box-shadow: 2px 3px 8px rgba(0, 0, 0, 0.08);
+  font-family: var(--tc-font-stack, system-ui, -apple-system, sans-serif);
+  resize: both;
+  overflow: auto;
+  position: relative;
+}
+
+.removeBtn {
+  all: unset;
+  cursor: pointer;
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  font-size: 16px;
+  line-height: 1;
+  width: 20px;
+  height: 20px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--sticky-border, #d4a72c);
+  border-radius: 2px;
+  opacity: 0;
+  transition: opacity 150ms;
+  z-index: 1;
+}
+
+.sticky:hover .removeBtn {
+  opacity: 0.6;
+}
+
+.removeBtn:hover {
+  opacity: 1;
+  color: var(--fgColor-danger, #d1242f);
+}
+
+.text {
+  padding: 12px 14px;
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.5;
+  color: #1a1a1a;
+  white-space: pre-wrap;
+  word-break: break-word;
+  cursor: text;
+  min-height: 60px;
+}
+
+.textarea {
+  display: block;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  padding: 12px 14px;
+  margin: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 1.5;
+  color: #1a1a1a;
+  resize: none;
+  min-height: 80px;
+}
+
+/* Color picker area — sits below the sticky */
+
+.pickerArea {
+  display: flex;
+  justify-content: center;
+  padding-top: 6px;
+  position: relative;
+}
+
+.pickerDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  opacity: 0.5;
+  transition: opacity 150ms;
+  cursor: pointer;
+}
+
+.pickerPopup {
+  position: absolute;
+  top: 4px;
+  display: flex;
+  gap: 5px;
+  padding: 6px 10px;
+  background: var(--bgColor-default, #ffffff);
+  border-radius: 20px;
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.08),
+    0 4px 12px rgba(0, 0, 0, 0.12);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 150ms;
+  z-index: 10;
+}
+
+.pickerArea:hover .pickerDot {
+  opacity: 0;
+}
+
+.pickerArea:hover .pickerPopup {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.colorDot {
+  all: unset;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  border: 2px solid transparent;
+  cursor: pointer;
+  transition: transform 100ms;
+}
+
+.colorDot:hover {
+  transform: scale(1.15);
+}
+
+.colorDot.active {
+  border-color: var(--sticky-border);
+  box-shadow: 0 0 0 1px var(--sticky-border);
+}

package/src/canvas/widgets/WidgetWrapper.jsx

@@ -0,0 +1,28 @@
+import styles from './WidgetWrapper.module.css'
+
+/**
+ * Common wrapper for all canvas widgets.
+ * Provides shadow/border styling and a remove button on hover.
+ */
+export default function WidgetWrapper({ children, onRemove, className }) {
+  return (
+    <section className={`${styles.wrapper} ${className || ''}`}>
+      {onRemove && (
+        <button
+          className={styles.removeBtn}
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove()
+          }}
+          title="Remove widget"
+          aria-label="Remove widget"
+        >
+          ×
+        </button>
+      )}
+      <div className={styles.content}>
+        {children}
+      </div>
+    </section>
+  )
+}

package/src/canvas/widgets/WidgetWrapper.module.css

@@ -0,0 +1,53 @@
+.wrapper {
+  background: var(--bgColor-default, #ffffff);
+  border-radius: var(--borderRadius-large, 12px);
+  overflow: hidden;
+  min-width: 200px;
+  box-shadow:
+    0 0 0 1px rgba(0, 0, 0, 0.06),
+    0 0 0 2px rgba(255, 255, 255, 0.04),
+    0 2px 8px rgba(0, 0, 0, 0.08);
+}
+
+.removeBtn {
+  all: unset;
+  cursor: pointer;
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  font-size: 16px;
+  line-height: 1;
+  width: 22px;
+  height: 22px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--fgColor-muted, #656d76);
+  border-radius: 6px;
+  background: var(--bgColor-default, #ffffff);
+  opacity: 0;
+  transition: opacity 150ms;
+  z-index: 1;
+}
+
+.wrapper:hover .removeBtn {
+  opacity: 1;
+}
+
+.removeBtn:hover {
+  color: var(--fgColor-danger, #d1242f);
+  background: var(--bgColor-danger-muted, #ffebe9);
+}
+
+.content {
+  position: relative;
+}
+
+@media (prefers-color-scheme: dark) {
+  .wrapper {
+    box-shadow:
+      0 0 0 1px rgba(255, 255, 255, 0.08),
+      0 0 0 2px rgba(0, 0, 0, 0.3),
+      0 2px 8px rgba(0, 0, 0, 0.25);
+  }
+}

package/src/canvas/widgets/index.js

@@ -0,0 +1,21 @@
+import StickyNote from './StickyNote.jsx'
+import MarkdownBlock from './MarkdownBlock.jsx'
+import PrototypeEmbed from './PrototypeEmbed.jsx'
+
+/**
+ * Maps widget type strings to their React components.
+ * Each component receives: { id, props, onUpdate, onRemove }
+ */
+export const widgetRegistry = {
+  'sticky-note': StickyNote,
+  'markdown': MarkdownBlock,
+  'prototype': PrototypeEmbed,
+}
+
+/**
+ * Resolve a widget type string to its component.
+ * Returns null for unknown types.
+ */
+export function getWidgetComponent(type) {
+  return widgetRegistry[type] ?? null
+}

package/src/canvas/widgets/widgetProps.js

@@ -0,0 +1,144 @@
+/**
+ * Canvas Widget Props API
+ *
+ * Every canvas widget receives its data through a structured `props` object
+ * stored in .canvas.json. This module defines the prop schema system that
+ * widgets use to declare, read, and update their editable properties.
+ *
+ * ## Prop Categories
+ *
+ * Widget props are grouped into three categories:
+ *
+ * ### `content` — User-editable content
+ * Text, markdown, URLs — the stuff users type or paste.
+ * Updated frequently (every keystroke when editing).
+ * Examples: sticky note text, markdown content, embed URL.
+ *
+ * ### `settings` — Widget configuration
+ * One-off choices that affect appearance or behavior.
+ * Updated infrequently (user picks from a menu).
+ * Examples: sticky note color, markdown width, embed layout.
+ *
+ * ### `size` — Dimensions
+ * Width and height of the widget.
+ * Updated via resize handles or explicit input.
+ * Examples: markdown block width, prototype embed width/height.
+ *
+ * ## Storage Format (.canvas.json)
+ *
+ * Props are stored flat in the widget's `props` object:
+ *
+ * ```json
+ * {
+ *   "id": "sticky-1",
+ *   "type": "sticky-note",
+ *   "position": { "x": 100, "y": 200 },
+ *   "props": {
+ *     "text": "Hello world",
+ *     "color": "yellow"
+ *   }
+ * }
+ * ```
+ *
+ * ## Widget Contract
+ *
+ * Every widget component receives:
+ *   - `id`       — stable widget identifier
+ *   - `props`    — the flat props object (may be null/undefined)
+ *   - `onUpdate` — callback to persist prop changes: onUpdate({ key: value })
+ *   - `onRemove` — callback to delete the widget
+ *
+ * `onUpdate` accepts a partial object that is shallow-merged into `props`.
+ * Multiple keys can be updated in one call:
+ *   onUpdate({ text: 'new text', color: 'blue' })
+ *
+ * ## Declaring Widget Props (Schema)
+ *
+ * Each widget type exports a `schema` describing its props.
+ * This is used by the toolbar, canvas settings, and future widget inspectors.
+ */
+
+/**
+ * @typedef {'text' | 'select' | 'number' | 'url' | 'boolean'} PropType
+ *
+ * @typedef {Object} PropDef
+ * @property {PropType} type        — input type for editing
+ * @property {string}   label       — human-readable label
+ * @property {string}   category    — 'content' | 'settings' | 'size'
+ * @property {*}        defaultValue — fallback when prop is missing
+ * @property {Array}    [options]   — choices for 'select' type
+ * @property {number}   [min]       — minimum for 'number' type
+ * @property {number}   [max]       — maximum for 'number' type
+ */
+
+/**
+ * Read a prop value with fallback to schema default.
+ * @param {object} props    — widget props object (may be null)
+ * @param {string} key      — prop name
+ * @param {object} schema   — widget schema
+ * @returns {*}
+ */
+export function readProp(props, key, schema) {
+  const value = props?.[key]
+  if (value !== undefined && value !== null) return value
+  return schema[key]?.defaultValue ?? null
+}
+
+/**
+ * Read all props with defaults applied from schema.
+ * @param {object} props  — widget props object (may be null)
+ * @param {object} schema — widget schema
+ * @returns {object}
+ */
+export function readAllProps(props, schema) {
+  const result = {}
+  for (const key of Object.keys(schema)) {
+    result[key] = readProp(props, key, schema)
+  }
+  return result
+}
+
+/**
+ * Get default props for a widget type from its schema.
+ * Used when creating new widgets.
+ * @param {object} schema — widget schema
+ * @returns {object}
+ */
+export function getDefaults(schema) {
+  const result = {}
+  for (const [key, def] of Object.entries(schema)) {
+    if (def.defaultValue !== undefined) {
+      result[key] = def.defaultValue
+    }
+  }
+  return result
+}
+
+// ── Widget Schemas ──────────────────────────────────────────────────
+
+export const stickyNoteSchema = {
+  text:  { type: 'text',   label: 'Text',  category: 'content', defaultValue: '' },
+  color: { type: 'select', label: 'Color', category: 'settings', defaultValue: 'yellow',
+           options: ['yellow', 'blue', 'green', 'pink', 'purple', 'orange'] },
+}
+
+export const markdownSchema = {
+  content: { type: 'text',   label: 'Content', category: 'content', defaultValue: '' },
+  width:   { type: 'number', label: 'Width',   category: 'size',    defaultValue: 360, min: 200, max: 1200 },
+}
+
+export const prototypeEmbedSchema = {
+  src:    { type: 'url',    label: 'URL',    category: 'content',  defaultValue: '' },
+  label:  { type: 'text',   label: 'Label',  category: 'settings', defaultValue: '' },
+  width:  { type: 'number', label: 'Width',  category: 'size',     defaultValue: 800, min: 200, max: 2000 },
+  height: { type: 'number', label: 'Height', category: 'size',     defaultValue: 600, min: 200, max: 1500 },
+}
+
+/**
+ * Schema registry — maps widget type strings to their schemas.
+ */
+export const schemas = {
+  'sticky-note': stickyNoteSchema,
+  'markdown': markdownSchema,
+  'prototype': prototypeEmbedSchema,
+}

package/src/hooks/useFeatureFlag.js

@@ -1,16 +1,14 @@
 import { useSyncExternalStore } from 'react'
-import { getFlag, subscribeToHash, getHashSnapshot, subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
+import { getFlag, subscribeToStorage, getStorageSnapshot } from '@dfosco/storyboard-core'
 
 /**
  * React hook for reading a feature flag value.
- * Re-renders when the flag changes (via hash or localStorage).
+ * Re-renders when the flag changes (via localStorage).
  *
  * @param {string} key - Flag key (without "flag." prefix)
  * @returns {boolean} Current resolved flag value
  */
 export function useFeatureFlag(key) {
-  // Subscribe to both hash and storage changes for reactivity
-  useSyncExternalStore(subscribeToHash, getHashSnapshot)
   useSyncExternalStore(subscribeToStorage, getStorageSnapshot)
   return getFlag(key)
 }

package/src/hooks/useFlows.js

@@ -0,0 +1,50 @@
+import { useContext, useMemo, useCallback } from 'react'
+import { StoryboardContext } from '../StoryboardContext.js'
+import { getFlowsForPrototype, resolveFlowRoute } from '@dfosco/storyboard-core'
+import { getFlowMeta } from '@dfosco/storyboard-core'
+
+/**
+ * List all flows for the current prototype and switch between them.
+ *
+ * @returns {{
+ *   flows: Array<{ key: string, name: string, title: string, route: string }>,
+ *   activeFlow: string,
+ *   switchFlow: (flowKey: string) => void,
+ *   prototypeName: string | null
+ * }}
+ */
+export function useFlows() {
+  const context = useContext(StoryboardContext)
+  if (context === null) {
+    throw new Error('useFlows must be used within a <StoryboardProvider>')
+  }
+
+  const { flowName: activeFlow, prototypeName } = context
+
+  const flows = useMemo(() => {
+    if (!prototypeName) return []
+    return getFlowsForPrototype(prototypeName).map(f => {
+      const meta = getFlowMeta(f.key)
+      return {
+        key: f.key,
+        name: f.name,
+        title: meta?.title || f.name,
+        route: resolveFlowRoute(f.key),
+      }
+    })
+  }, [prototypeName])
+
+  const switchFlow = useCallback((flowKey) => {
+    const flow = flows.find(f => f.key === flowKey)
+    if (flow) {
+      window.location.href = flow.route
+    }
+  }, [flows])
+
+  return {
+    flows,
+    activeFlow,
+    switchFlow,
+    prototypeName,
+  }
+}