@dfosco/storyboard 0.11.4 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dfosco/storyboard",
-    "version": "0.11.4",
+    "version": "0.11.5",
     "type": "module",
     "license": "MIT",
     "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/src/internals/canvas/widgets/Widget.jsx

@@ -0,0 +1,270 @@
+import {
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { getWidgetComponent } from './index.js'
+import styles from './Widget.module.css'
+
+/**
+ * `<Widget>` — render any registered canvas widget inside a normal React page.
+ *
+ * Canvas widgets follow a stable contract: they resolve from a `type` string
+ * (via `getWidgetComponent`), read their fields from a flat `props` object, and
+ * render chrome-less (the canvas applies toolbar/anchors/selection externally).
+ * This component reproduces that contract off-canvas so any widget can be used
+ * as a first-class element in a page:
+ *
+ *   <Widget type="markdown" content="# Hi" className="prose" />
+ *   <Widget type="prototype" src="StartupSignup" width={900} height={600} />
+ *   <Widget type="sticky-note" text="Note" color="yellow" draggable resizable />
+ *
+ * Prop mapping
+ * ------------
+ * Reserved props configure the wrapper / contract and are NOT forwarded into
+ * the widget's `props` object:
+ *   type, id, className, style, onUpdate, widgetRef, children,
+ *   draggable, resizable, chrome
+ * Every OTHER prop is spread into the widget `props` object, so all widget
+ * fields (content, settings, size — unique or not) are passable as props.
+ *
+ * onUpdate
+ * --------
+ * Defaults to internal local state (uncontrolled): widgets that self-heal or
+ * edit through `onUpdate(partial)` keep working, and resize/drag persist for
+ * the lifetime of the element. Pass your own `onUpdate` for controlled mode —
+ * it receives the same partial-merge object and you own the props.
+ *
+ * chrome
+ * ------
+ * `chrome` (default true) renders the canvas-style selection outline and the
+ * drag/select handle (the trigger dot that reveals a grab handle on hover),
+ * matching how widgets look on the canvas — minus the action menu. Set
+ * `chrome={false}` for a bare widget with no selection affordance.
+ *
+ * draggable / resizable
+ * ---------------------
+ * `resizable` (default false) is forwarded to the widget, which renders its own
+ * ResizeHandle and persists width/height through `onUpdate`. `draggable`
+ * (default false) is a page-level affordance: the widget body and the select
+ * handle become pointer-draggable and the offset is applied as a CSS translate.
+ */
+
+const RESERVED = new Set([
+  'type',
+  'id',
+  'className',
+  'style',
+  'onUpdate',
+  'widgetRef',
+  'children',
+  'draggable',
+  'resizable',
+  'chrome',
+])
+
+const DRAG_THRESHOLD = 3
+
+function isForwardRef(Component) {
+  return Component != null && Component.$$typeof === Symbol.for('react.forward_ref')
+}
+
+function Widget(
+  {
+    type,
+    id,
+    className,
+    style,
+    onUpdate,
+    draggable = false,
+    resizable = false,
+    chrome = true,
+    ...rest
+  },
+  ref,
+) {
+  const autoId = useId()
+  const widgetId = id || `widget-${type || 'unknown'}-${autoId}`
+
+  // Collect every non-reserved prop into the flat widget props object.
+  const incomingProps = useMemo(() => {
+    const out = {}
+    for (const key of Object.keys(rest)) {
+      if (!RESERVED.has(key)) out[key] = rest[key]
+    }
+    return out
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(rest)])
+
+  // Local override state powers the default (uncontrolled) onUpdate so that
+  // self-healing widgets, resizing, and editing all persist without a canvas.
+  const [overrides, setOverrides] = useState(null)
+
+  const handleUpdate = useCallback(
+    (partial) => {
+      if (!partial || typeof partial !== 'object') return
+      if (typeof onUpdate === 'function') {
+        onUpdate(partial)
+        return
+      }
+      setOverrides((prev) => ({ ...(prev || {}), ...partial }))
+    },
+    [onUpdate],
+  )
+
+  const effectiveProps = useMemo(
+    () => (overrides ? { ...incomingProps, ...overrides } : incomingProps),
+    [incomingProps, overrides],
+  )
+
+  // Selection + drag offset (canvas-style chrome affordances).
+  const [selected, setSelected] = useState(false)
+  const [hovered, setHovered] = useState(false)
+  const [offset, setOffset] = useState({ x: 0, y: 0 })
+  const offsetRef = useRef(offset)
+  offsetRef.current = offset
+  const containerRef = useRef(null)
+
+  const selectWidget = useCallback(() => setSelected(true), [])
+
+  // Click anywhere outside the widget deselects it.
+  useEffect(() => {
+    if (!chrome || !selected) return undefined
+    const onDocPointerDown = (e) => {
+      if (containerRef.current && !containerRef.current.contains(e.target)) {
+        setSelected(false)
+      }
+    }
+    document.addEventListener('pointerdown', onDocPointerDown)
+    return () => document.removeEventListener('pointerdown', onDocPointerDown)
+  }, [chrome, selected])
+
+  // Shared drag/click handler. `fromHandle` distinguishes a click on the select
+  // handle (selects when no drag occurs) from a body drag.
+  const beginPointer = useCallback(
+    (e, fromHandle) => {
+      // Let interactive controls (inputs, links, resize handle…) keep working.
+      if (
+        !fromHandle &&
+        e.target.closest(
+          'input, textarea, select, button, a, [contenteditable="true"], [data-widget-resize-handle]',
+        )
+      ) {
+        return
+      }
+      if (fromHandle) e.stopPropagation()
+      if (!draggable && !fromHandle) return
+
+      const startX = e.clientX
+      const startY = e.clientY
+      const start = offsetRef.current
+      let moved = false
+
+      const move = (ev) => {
+        const dx = ev.clientX - startX
+        const dy = ev.clientY - startY
+        if (!moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return
+        moved = true
+        if (draggable) setOffset({ x: start.x + dx, y: start.y + dy })
+      }
+      const up = () => {
+        document.removeEventListener('pointermove', move)
+        document.removeEventListener('pointerup', up)
+        if (fromHandle && !moved) selectWidget()
+      }
+      document.addEventListener('pointermove', move)
+      document.addEventListener('pointerup', up)
+    },
+    [draggable, selectWidget],
+  )
+
+  const Component = getWidgetComponent(type)
+  if (!Component) {
+    if (typeof console !== 'undefined') {
+      console.warn(`[storyboard] <Widget>: unknown widget type "${type}"`)
+    }
+    return null
+  }
+
+  const elementProps = {
+    id: widgetId,
+    props: effectiveProps,
+    onUpdate: handleUpdate,
+    resizable: !!resizable,
+    selected: chrome ? selected : false,
+    onSelect: chrome ? selectWidget : () => {},
+  }
+  if (isForwardRef(Component)) {
+    elementProps.ref = ref
+  }
+
+  const containerStyle = {
+    ...style,
+    ...(draggable
+      ? {
+          transform: `translate(${offset.x}px, ${offset.y}px)`,
+          touchAction: 'none',
+        }
+      : null),
+  }
+
+  const showHandle = chrome && (hovered || selected)
+
+  return (
+    <div
+      ref={containerRef}
+      className={[
+        styles.widget,
+        chrome ? styles.chromeContainer : '',
+        draggable ? styles.draggable : '',
+        className,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      style={containerStyle}
+      data-widget-type={type}
+      data-widget-selected={chrome && selected ? '' : undefined}
+      onPointerDown={draggable ? (e) => beginPointer(e, false) : undefined}
+      onClick={chrome ? selectWidget : undefined}
+      onMouseEnter={chrome ? () => setHovered(true) : undefined}
+      onMouseLeave={chrome ? () => setHovered(false) : undefined}
+    >
+      <div
+        className={[styles.widgetSlot, chrome && selected ? styles.widgetSlotSelected : '']
+          .filter(Boolean)
+          .join(' ')}
+      >
+        {createElement(Component, elementProps)}
+      </div>
+
+      {chrome && (
+        <div className={styles.toolbar}>
+          <span
+            className={`${styles.triggerDot} ${showHandle ? styles.triggerDotHidden : ''}`}
+            aria-hidden="true"
+          />
+          <div className={`${styles.toolbarContent} ${showHandle ? styles.toolbarContentVisible : ''}`}>
+            <button
+              type="button"
+              className={`${styles.selectHandle} ${selected ? styles.selectHandleActive : ''} ${
+                draggable ? styles.selectHandleDraggable : ''
+              }`}
+              onPointerDown={(e) => beginPointer(e, true)}
+              aria-label={
+                selected ? (draggable ? 'Drag to move widget' : 'Widget selected') : 'Select widget'
+              }
+              aria-pressed={selected}
+            />
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default forwardRef(Widget)

package/src/internals/canvas/widgets/Widget.module.css

@@ -0,0 +1,132 @@
+/* <Widget> — page-embeddable canvas widget.
+   Mirrors the canvas WidgetChrome selection outline + drag/select handle,
+   minus the action menu. */
+
+.widget {
+  display: inline-block;
+  position: relative;
+  max-width: 100%;
+}
+
+.chromeContainer {
+  position: relative;
+}
+
+.draggable {
+  user-select: none;
+}
+
+/* Widget slot — selection outline targets this. */
+.widgetSlot {
+  position: relative;
+  border-radius: 4px;
+}
+
+.widgetSlotSelected {
+  outline: 4px solid var(--color-background-accent-emphasis, #2f81f7);
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+/* Toolbar — absolutely positioned below the widget so it never affects the
+   widget's box dimensions. */
+.toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  height: 28px;
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: calc(100% + 10px);
+}
+
+/* Invisible hit-area bridging the 10px gap so hover survives the pointer
+   crossing the padding between the widget and its handle. */
+.toolbar::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 100%;
+  height: 10px;
+  pointer-events: auto;
+}
+
+/* Trigger dot — visible at rest, hidden once the handle is revealed. */
+.triggerDot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--color-border-muted, #d0d7de);
+  opacity: 0.5;
+  margin-left: auto;
+  transition: opacity 120ms;
+}
+
+:global([data-sb-canvas-theme^='dark']) .triggerDot {
+  background: var(--color-border-muted, #373e47);
+  opacity: 0.6;
+}
+
+.triggerDotHidden {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* Toolbar content — holds the select handle. */
+.toolbarContent {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 120ms;
+}
+
+.toolbarContentVisible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* Select handle — rounded rect. Click selects; drag (when draggable) moves. */
+.selectHandle {
+  all: unset;
+  cursor: pointer;
+  width: 16px;
+  height: 16px;
+  border-radius: 4px;
+  border: 1.6px solid var(--color-border-muted, #d0d7de);
+  background: var(--color-background, #ffffff);
+  transition: background 100ms, border-color 100ms;
+  flex-shrink: 0;
+}
+
+.selectHandleDraggable {
+  cursor: grab;
+}
+
+.selectHandleDraggable:active {
+  cursor: grabbing;
+}
+
+:global([data-sb-canvas-theme^='dark']) .selectHandle {
+  background: var(--color-background-muted, #161b22);
+  border-color: var(--color-border-muted, #373e47);
+}
+
+.selectHandle:hover {
+  border-color: var(--color-background-accent-emphasis, #2f81f7);
+}
+
+.selectHandleActive,
+:global([data-sb-canvas-theme^='dark']) .selectHandleActive {
+  background: var(--color-background-accent-emphasis, #2f81f7);
+  border-color: var(--color-background-accent-emphasis, #2f81f7);
+}
+
+.selectHandleActive:hover,
+:global([data-sb-canvas-theme^='dark']) .selectHandleActive:hover {
+  background: var(--color-background-accent-emphasis, #388bfd);
+  border-color: var(--color-background-accent-emphasis, #388bfd);
+}

package/src/internals/canvas/widgets/Widget.test.jsx

@@ -0,0 +1,186 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import Widget from './Widget.jsx'
+import {
+  registerWidget,
+  _resetWidgetRegistry,
+} from '../../../core/stores/widgetRegistry.js'
+
+afterEach(() => {
+  _resetWidgetRegistry()
+  vi.restoreAllMocks()
+})
+
+// A minimal probe widget that renders its props and exposes onUpdate so we can
+// assert the standard contract the dispatcher supplies.
+function ProbeWidget({ id, props, onUpdate, resizable }) {
+  return (
+    <div data-testid="probe" data-id={id} data-resizable={String(resizable)}>
+      <span data-testid="text">{props?.text ?? ''}</span>
+      <span data-testid="width">{String(props?.width ?? '')}</span>
+      <button type="button" onClick={() => onUpdate({ text: 'updated' })}>
+        update
+      </button>
+    </div>
+  )
+}
+
+describe('<Widget>', () => {
+  it('resolves a registered type and maps non-reserved props into the widget props object', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" text="hello" width={320} />)
+
+    expect(screen.getByTestId('probe')).toBeInTheDocument()
+    expect(screen.getByTestId('text').textContent).toBe('hello')
+    expect(screen.getByTestId('width').textContent).toBe('320')
+  })
+
+  it('applies className and data-widget-type to the wrapper', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(
+      <Widget type="probe" className="my-class" text="x" />,
+    )
+
+    const wrapper = container.querySelector('[data-widget-type="probe"]')
+    expect(wrapper).toBeTruthy()
+    expect(wrapper.className).toContain('my-class')
+  })
+
+  it('forwards the resizable prop to the widget', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" resizable text="x" />)
+    expect(screen.getByTestId('probe').getAttribute('data-resizable')).toBe('true')
+
+    _resetWidgetRegistry()
+    registerWidget('probe', { component: ProbeWidget })
+    render(<Widget type="probe" text="y" />)
+    const probes = screen.getAllByTestId('probe')
+    expect(probes[probes.length - 1].getAttribute('data-resizable')).toBe('false')
+  })
+
+  it('defaults onUpdate to internal local state (uncontrolled)', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    render(<Widget type="probe" text="initial" />)
+    expect(screen.getByTestId('text').textContent).toBe('initial')
+
+    fireEvent.click(screen.getByText('update'))
+    expect(screen.getByTestId('text').textContent).toBe('updated')
+  })
+
+  it('uses a consumer-supplied onUpdate when provided (controlled)', () => {
+    registerWidget('probe', { component: ProbeWidget })
+    const onUpdate = vi.fn()
+
+    render(<Widget type="probe" text="initial" onUpdate={onUpdate} />)
+    fireEvent.click(screen.getByText('update'))
+
+    expect(onUpdate).toHaveBeenCalledWith({ text: 'updated' })
+    // Controlled: local state is not applied, text stays as the incoming prop.
+    expect(screen.getByTestId('text').textContent).toBe('initial')
+  })
+
+  it('does not forward reserved props into the widget props object', () => {
+    function PropsSpy({ props }) {
+      return <pre data-testid="json">{JSON.stringify(props)}</pre>
+    }
+    registerWidget('spy', { component: PropsSpy })
+
+    render(
+      <Widget
+        type="spy"
+        id="fixed-id"
+        className="c"
+        draggable
+        resizable
+        text="keep"
+      />,
+    )
+
+    const parsed = JSON.parse(screen.getByTestId('json').textContent)
+    expect(parsed).toEqual({ text: 'keep' })
+  })
+
+  it('renders nothing and warns for an unknown type', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const { container } = render(<Widget type="does-not-exist" />)
+
+    expect(container.firstChild).toBeNull()
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining('unknown widget type "does-not-exist"'),
+    )
+  })
+
+  it('applies a translate transform to the wrapper when draggable is set', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" draggable text="x" />)
+    const wrapper = container.querySelector('[data-widget-type="probe"]')
+    expect(wrapper.style.transform).toContain('translate(')
+  })
+
+  it('renders the chrome select handle by default and selects on handle click', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" text="x" />)
+    const handle = container.querySelector('[aria-label="Select widget"]')
+    expect(handle).toBeTruthy()
+    expect(handle.getAttribute('aria-pressed')).toBe('false')
+
+    // pointerDown without movement selects on pointerUp.
+    fireEvent.pointerDown(handle, { clientX: 0, clientY: 0 })
+    fireEvent.pointerUp(document, { clientX: 0, clientY: 0 })
+
+    expect(container.querySelector('[aria-pressed="true"]')).toBeTruthy()
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+  })
+
+  it('selects when clicking anywhere on the widget body', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" text="x" />)
+    expect(container.querySelector('[data-widget-selected]')).toBeNull()
+
+    fireEvent.click(screen.getByTestId('probe'))
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+  })
+
+  it('deselects when clicking outside the widget', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(
+      <div>
+        <Widget type="probe" text="x" />
+        <button type="button">outside</button>
+      </div>,
+    )
+
+    fireEvent.click(screen.getByTestId('probe'))
+    expect(container.querySelector('[data-widget-selected]')).toBeTruthy()
+
+    fireEvent.pointerDown(screen.getByText('outside'))
+    expect(container.querySelector('[data-widget-selected]')).toBeNull()
+  })
+
+  it('omits chrome (no handle, no selection) when chrome={false}', () => {
+    registerWidget('probe', { component: ProbeWidget })
+
+    const { container } = render(<Widget type="probe" chrome={false} text="x" />)
+    expect(container.querySelector('[aria-label="Select widget"]')).toBeNull()
+    expect(screen.getByTestId('probe')).toBeInTheDocument()
+  })
+
+  it('does not forward the chrome prop into the widget props object', () => {
+    function PropsSpy({ props }) {
+      return <pre data-testid="json">{JSON.stringify(props)}</pre>
+    }
+    registerWidget('spy', { component: PropsSpy })
+
+    render(<Widget type="spy" chrome text="keep" />)
+    const parsed = JSON.parse(screen.getByTestId('json').textContent)
+    expect(parsed).toEqual({ text: 'keep' })
+  })
+})

package/src/internals/index.js

@@ -62,6 +62,10 @@ export { default as AuthModal } from './AuthModal/AuthModal.jsx'
 export { default as CanvasPage } from './canvas/CanvasPage.jsx'
 export { useCanvas } from './canvas/useCanvas.js'
 
+// Widget — render any registered canvas widget inside a normal React page.
+export { default as Widget } from './canvas/widgets/Widget.jsx'
+export { getWidgetComponent } from './canvas/widgets/index.js'
+
 // Error boundaries
 export { default as PrototypeErrorBoundary, ImportErrorFallback, AppErrorBoundary } from './PrototypeErrorBoundary.jsx'