@dfosco/storyboard 0.5.0-alpha.0

package/src/canvas/Draggable.jsx

@@ -0,0 +1,235 @@
+import { useRef, useEffect, useState } from 'react';
+import { useDraggable } from '@neodrag/react';
+import { saveDrag } from './utils';
+
+const TRANSLATION_MS = 250;
+const PERSIST_DEADZONE_PX = 4;
+
+/** Minimum hold time (ms) before drag can start.
+ *  Quick clicks (release before this) never trigger drag. */
+const DRAG_DELAY_MS = 150;
+
+/** Minimum pointer travel (px) from the initial pointerdown position
+ *  before drag can start. Computed from the raw clientX/Y delta —
+ *  not from neodrag's translate-offset-based calculation (which is
+ *  broken for positioned elements). */
+const DRAG_DISTANCE_PX = 8;
+
+function Draggable({ children, dragId, initialPosition, onDragStart: onDragStartProp, onDrag: onDragProp, onDragEnd, handle, snapGrid, locked = false, boundaryPad = 0 }) {
+  const draggableRef = useRef(null);
+  const initialSavedPosition = initialPosition || { x: 0, y: 0 };
+  const dragStartRef = useRef(initialSavedPosition);
+  const hasMovedRef = useRef(false);
+
+  // Gate ref for our drag threshold
+  const gateRef = useRef({
+    timer: null,
+    startX: 0,
+    startY: 0,
+    delayMet: false,
+    distanceMet: false,
+    active: false,
+    lastEvent: null,
+  });
+
+  const [position, setPosition] = useState(initialSavedPosition);
+  const [prevInitial, setPrevInitial] = useState(initialSavedPosition);
+
+  // Sync position from parent when it changes externally (undo/redo)
+  if (initialPosition &&
+      (initialPosition.x !== prevInitial.x || initialPosition.y !== prevInitial.y)) {
+    setPrevInitial(initialPosition);
+    setPosition(initialPosition);
+  }
+
+  // Animate elements with saved positions on mount
+  useEffect(() => {
+    const el = draggableRef.current;
+    if (
+      el &&
+      dragId &&
+      (initialSavedPosition.x !== 0 || initialSavedPosition.y !== 0)
+    ) {
+      el.classList.add('tc-on-translation');
+
+      const timer = setTimeout(() => {
+        el.classList.remove('tc-on-translation');
+      }, TRANSLATION_MS * 4);
+
+      return () => {
+        clearTimeout(timer);
+      };
+    }
+  }, [dragId, initialSavedPosition.x, initialSavedPosition.y]);
+
+  // Gate neodrag: intercept pointerdown on the handle via delegation.
+  // We listen on the article element and check if the event target is
+  // inside the handle. stopPropagation in bubble phase prevents neodrag
+  // (which also listens on the article in bubble phase) from seeing it.
+  //
+  // After both delay and distance thresholds are met, we re-dispatch a
+  // synthetic pointerdown from the original target — it bubbles up to
+  // the article and neodrag picks it up.
+  //
+  // React 18 captures events at the root container during capture phase,
+  // so React handlers (onPointerDown/onPointerUp) still fire normally.
+  useEffect(() => {
+    const el = draggableRef.current;
+    if (!el || !handle || locked) return;
+
+    const g = gateRef.current;
+    let synthEvent = null;
+
+    function isHandleEvent(e) {
+      if (!(e.target instanceof Element)) return false;
+      const match = e.target.closest(handle);
+      return match != null && el.contains(match);
+    }
+
+    function onArticlePointerDownCapture(e) {
+      // Let synthetic re-dispatched events pass through to neodrag
+      if (e === synthEvent) {
+        synthEvent = null;
+        return;
+      }
+      if (!isHandleEvent(e)) return;
+      // stopImmediatePropagation prevents neodrag's bubble listener
+      // on this same article from seeing the event
+      e.stopImmediatePropagation();
+      g.active = true;
+      g.delayMet = false;
+      g.distanceMet = false;
+      g.startX = e.clientX;
+      g.startY = e.clientY;
+      g.target = e.target;
+      g.pointerId = e.pointerId;
+      g.button = e.button;
+      g.pointerType = e.pointerType;
+      clearTimeout(g.timer);
+      g.timer = setTimeout(() => {
+        g.delayMet = true;
+        tryEnable();
+      }, DRAG_DELAY_MS);
+    }
+
+    function tryEnable() {
+      if (g.delayMet && g.distanceMet && g.active && g.target) {
+        const synth = new PointerEvent('pointerdown', {
+          bubbles: true,
+          cancelable: true,
+          pointerId: g.pointerId,
+          clientX: g.startX,
+          clientY: g.startY,
+          button: g.button,
+          pointerType: g.pointerType,
+        });
+        synthEvent = synth;
+        g.target.dispatchEvent(synth);
+        g.target = null;
+      }
+    }
+
+    function onDocPointerMove(e) {
+      if (!g.active || g.distanceMet) return;
+      const dx = e.clientX - g.startX;
+      const dy = e.clientY - g.startY;
+      if (Math.hypot(dx, dy) >= DRAG_DISTANCE_PX) {
+        g.distanceMet = true;
+        tryEnable();
+      }
+    }
+
+    function resetGate() {
+      clearTimeout(g.timer);
+      g.active = false;
+      g.target = null;
+    }
+
+    el.addEventListener('pointerdown', onArticlePointerDownCapture, true);
+    document.addEventListener('pointermove', onDocPointerMove);
+    document.addEventListener('pointerup', resetGate);
+    document.addEventListener('pointercancel', resetGate);
+    return () => {
+      el.removeEventListener('pointerdown', onArticlePointerDownCapture, true);
+      document.removeEventListener('pointermove', onDocPointerMove);
+      document.removeEventListener('pointerup', resetGate);
+      document.removeEventListener('pointercancel', resetGate);
+      clearTimeout(g.timer);
+    };
+  }, [handle, locked]);
+
+  const { isDragging } = useDraggable(draggableRef, {
+    axis: 'both',
+    grid: snapGrid,
+    defaultClass: 'tc-drag',
+    defaultClassDragging: 'tc-on',
+    defaultClassDragged: 'tc-off',
+    applyUserSelectHack: true,
+    disabled: locked,
+    ...(handle ? { handle } : {}),
+    position: { x: position.x, y: position.y },
+    // Clamp in the transform callback so neodrag never paints a
+    // negative position — avoids the one-frame flicker that happens
+    // when clamping only in onDrag (React re-render lag).
+    transform: ({ offsetX, offsetY }) => {
+      const x = Math.max(boundaryPad, offsetX)
+      const y = Math.max(boundaryPad, offsetY)
+      return `translate3d(${x}px, ${y}px, 0)`
+    },
+    onDragStart: () => {
+      dragStartRef.current = position;
+      hasMovedRef.current = false;
+      onDragStartProp?.(dragId, position);
+    },
+    onDrag: ({ offsetX, offsetY }) => {
+      const dx = offsetX - dragStartRef.current.x;
+      const dy = offsetY - dragStartRef.current.y;
+      const distance = Math.hypot(dx, dy);
+      if (!hasMovedRef.current && distance >= PERSIST_DEADZONE_PX) {
+        hasMovedRef.current = true;
+      }
+      const clamped = { x: Math.max(boundaryPad, offsetX), y: Math.max(boundaryPad, offsetY) };
+      setPosition(clamped);
+      onDragProp?.(dragId, clamped);
+    },
+    onDragEnd: (data) => {
+      const clampedX = Math.max(boundaryPad, data.offsetX);
+      const clampedY = Math.max(boundaryPad, data.offsetY);
+      setPosition({ x: clampedX, y: clampedY });
+      const dx = clampedX - dragStartRef.current.x;
+      const dy = clampedY - dragStartRef.current.y;
+      const movedEnough = hasMovedRef.current || Math.hypot(dx, dy) >= PERSIST_DEADZONE_PX;
+      if (!movedEnough) return;
+
+      if (dragId) {
+        saveDrag(dragId, clampedX, clampedY);
+      }
+      onDragEnd?.(dragId, { x: clampedX, y: clampedY });
+    },
+  });
+
+  // When locked, no drag cursor. When a handle is set, only the handle
+  // shows grab cursor (via its own CSS). Otherwise the whole article is
+  // the drag surface.
+  const articleCursor = locked
+    ? undefined
+    : handle
+      ? (isDragging ? 'grabbing' : undefined)
+      : (isDragging ? 'grabbing' : 'grab');
+
+  return (
+    <article
+      ref={draggableRef}
+      style={{
+        cursor: articleCursor,
+        transform: `translate3d(${position.x}px, ${position.y}px, 0)`,
+      }}
+    >
+      <div className="tc-draggable-inner">
+        {children}
+      </div>
+    </article>
+  );
+}
+
+export default Draggable;

package/src/canvas/index.d.ts

@@ -0,0 +1,41 @@
+import { ReactNode } from 'react';
+
+export interface CanvasProps {
+  children?: ReactNode;
+  /** Enable centered layout. Default: true */
+  centered?: boolean;
+  /** Show dot background. Default: false */
+  dotted?: boolean;
+  /** Enable grid snapping (also shows dots). Default: false */
+  grid?: boolean;
+  /** Grid snap size in pixels when grid is enabled. Default: 18 */
+  gridSize?: number;
+  /** Color mode: 'auto' follows system preference, 'light' or 'dark' to override. Default: 'auto' */
+  colorMode?: 'auto' | 'light' | 'dark';
+}
+
+export declare function Canvas(props: CanvasProps): JSX.Element;
+
+export interface DraggableProps {
+  children?: ReactNode;
+  /** Grid snap size in pixels. When undefined, no snapping is applied. */
+  gridSize?: number;
+  /** Stable identifier for persisting drag position. Auto-generated by Canvas if not provided. */
+  dragId?: string;
+}
+
+export declare function Draggable(props: DraggableProps): JSX.Element;
+
+export interface UseResetCanvasOptions {
+  /** Reload the page after clearing state. Default: false */
+  reload?: boolean;
+}
+
+/** Returns a function that clears all saved canvas positions from localStorage. */
+export declare function useResetCanvas(options?: UseResetCanvasOptions): () => void;
+
+export declare function findDragId(children: ReactNode): string | null;
+export declare function generateDragId(element: ReactNode, index: number): string;
+export declare function getQueue(dragId: string): { x: number; y: number };
+export declare function refreshStorage(): void;
+export declare function saveDrag(dragId: string, x: number, y: number): void;

package/src/canvas/index.js

@@ -0,0 +1,6 @@
+import './style.css';
+
+export { default as Canvas } from './Canvas';
+export { default as Draggable } from './Draggable';
+export { useResetCanvas } from './useResetCanvas';
+export { findDragId, generateDragId, getQueue, refreshStorage, saveDrag } from './utils';

package/src/canvas/style.css

@@ -0,0 +1,118 @@
+/* tiny-canvas styles */
+
+:root {
+  --tc-border-radius: var(--borderRadius-large, 12px);
+  --tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, 0.12));
+  --tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, 0.15));
+  --tc-border-color: var(--borderColor-muted, rgba(0, 0, 0, 0.15));
+  --tc-bg-muted: var(--bgColor-muted, #f6f8fa);
+  --tc-dot-color: var(--overlay-backdrop-bgColor, rgba(0, 0, 0, 0.08));
+  --tc-grid-size: var(--golden-number, 36px);
+  --tc-grid-offset: calc(var(--tc-grid-size) / -2);
+  --tc-dot-radius: 2px;
+  --tc-font-stack: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
+    Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+/* Canvas */
+
+.tc-canvas {
+  min-width: max(100vw, 10000px);
+  min-height: max(100vh, 10000px);
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  font-family: var(--tc-font-stack);
+  position: relative;
+  background-color: var(--tc-bg-muted);
+  color-scheme: light dark;
+}
+
+.tc-canvas[data-color-mode="light"] {
+  color-scheme: light;
+}
+
+.tc-canvas[data-color-mode="dark"] {
+  color-scheme: dark;
+}
+
+.tc-canvas[data-dotted] {
+  background-image: radial-gradient(var(--tc-dot-color) var(--tc-dot-radius), transparent var(--tc-dot-radius));
+  background-size: var(--tc-grid-size) var(--tc-grid-size);
+  background-position: var(--tc-grid-offset) var(--tc-grid-offset);
+}
+
+/* Dark mode — system preference (auto) */
+
+@media (prefers-color-scheme: dark) {
+  .tc-canvas:not([data-color-mode="light"]) {
+    --tc-bg-muted: var(--bgColor-muted, #161b22);
+    --tc-dot-color: var(--overlay-backdrop-bgColor, rgba(255, 255, 255, 0.1));
+    --tc-border-color: var(--borderColor-muted, rgba(255, 255, 255, 0.15));
+    --tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, 0.3));
+    --tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, 0.4));
+  }
+}
+
+/* Dark mode — explicit override */
+
+.tc-canvas[data-color-mode="dark"] {
+  --tc-bg-muted: var(--bgColor-muted, #161b22);
+  --tc-dot-color: var(--overlay-backdrop-bgColor, rgba(255, 255, 255, 0.1));
+  --tc-border-color: var(--borderColor-muted, rgba(255, 255, 255, 0.15));
+  --tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, 0.3));
+  --tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, 0.4));
+}
+
+/* Draggable */
+
+body .tc-draggable-inner:not(:active) {
+  touch-action: none;
+}
+
+.tc-on-translation {
+  transition: transform calc(var(--tc-translation-ms, 150ms) + var(--tc-translation-delay-ms, 50ms))
+    cubic-bezier(0.78, 0.1, 0.51, 0.78) var(--tc-translation-delay-ms, 50ms);
+}
+
+.tc-drag {
+  position: absolute;
+  width: fit-content;
+}
+
+.tc-draggable-inner {
+  position: relative;
+  width: fit-content;
+  height: min-content;
+}
+
+.tc-draggable-inner::after {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  width: 100%;
+  height: 100%;
+  top: 0;
+  border-radius: var(--tc-border-radius);
+  box-shadow: var(--tc-shadow-float);
+  opacity: 0;
+  transition: opacity 0.3s ease-in-out;
+}
+
+.tc-on-translation .tc-draggable-inner::after,
+.tc-draggable-inner:active::after,
+.tc-draggable-inner:hover::after {
+  opacity: 0;
+}
+
+.tc-on-translation .tc-draggable-inner,
+.tc-draggable-inner:active,
+.tc-draggable-inner:hover {
+  outline: none;
+}
+
+.tc-canvas[data-locked] * {
+  cursor: default !important;
+}
+
+/* Allow text selection inside draggable items */

package/src/canvas/useResetCanvas.js

@@ -0,0 +1,17 @@
+import { useCallback } from 'react';
+
+/**
+ * Hook that returns a function to clear all saved canvas positions.
+ */
+export function useResetCanvas({ reload = false } = {}) {
+  return useCallback(() => {
+    try {
+      localStorage.removeItem('tiny-canvas-queue');
+    } catch (error) {
+      console.error('Error clearing canvas state:', error);
+    }
+    if (reload) {
+      window.location.reload();
+    }
+  }, [reload]);
+}

package/src/canvas/utils.js

@@ -0,0 +1,136 @@
+import React from 'react';
+
+const QUEUE_KEY = 'tiny-canvas-queue';
+
+function readQueue() {
+  const raw = localStorage.getItem(QUEUE_KEY);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    localStorage.setItem(QUEUE_KEY, JSON.stringify([]));
+    return [];
+  }
+}
+
+/**
+ * Recursively searches through React component children.
+ * Returns the id prop value if found, null if not.
+ */
+export const findDragId = (children) => {
+  if (!children) return null;
+
+  let dragId = null;
+  const checkProps = (element) => {
+    if (element.props && element.props.id) {
+      dragId = element.props.id;
+      return;
+    }
+    if (element.props && element.props.children) {
+      React.Children.forEach(element.props.children, checkProps);
+    }
+  };
+
+  checkProps(children);
+  return dragId;
+};
+
+/** djb2 string hash → 8-char hex */
+function hash(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) + h + str.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** Build a structural signature from a React element tree (types + shape only). */
+function signature(node) {
+  if (node == null || typeof node === 'boolean') return '';
+  if (typeof node === 'string' || typeof node === 'number') return '#text';
+
+  const type = node.type;
+  const name =
+    typeof type === 'function'
+      ? type.displayName || type.name || 'Anonymous'
+      : typeof type === 'string'
+        ? type
+        : 'Fragment';
+
+  const kids = node.props?.children;
+  if (kids == null) return name;
+
+  const childSigs = [];
+  React.Children.forEach(kids, (child) => {
+    const s = signature(child);
+    if (s) childSigs.push(s);
+  });
+
+  return childSigs.length ? `${name}(${childSigs.join(',')})` : name;
+}
+
+/**
+ * Generate a stable drag ID from a React element's structural shape.
+ * Uses only component type names and nesting structure — immune to
+ * prop/value/content changes. The index suffix disambiguates identical siblings.
+ */
+export const generateDragId = (element, index) => {
+  const sig = signature(element);
+  return `tc-${hash(sig)}-${index}`;
+};
+
+/**
+ * Gets stored coordinates for a specific dragId from localStorage.
+ * Returns coords object with x,y or default {x:0, y:0} if not found.
+ */
+export const getQueue = (dragId) => {
+  try {
+    const queue = readQueue();
+    const coordsMap = queue.reduce((map, item) => {
+      map[item.id] = { id: item.id, x: item.x, y: item.y };
+      return map;
+    }, {});
+    return coordsMap[dragId] || { x: 0, y: 0 };
+  } catch (error) {
+    console.error('Error getting saved coordinates:', error);
+    return { x: 0, y: 0 };
+  }
+};
+
+/**
+ * Initializes localStorage queue if it doesn't exist.
+ */
+export const refreshStorage = () => {
+  try {
+    const queue = localStorage.getItem(QUEUE_KEY);
+    if (!queue) {
+      localStorage.setItem(QUEUE_KEY, JSON.stringify([]));
+    }
+  } catch (error) {
+    console.error('LocalStorage is not available:', error);
+  }
+};
+
+/**
+ * Saves position data for a draggable element to localStorage.
+ */
+export const saveDrag = (dragId, x, y) => {
+  try {
+    const queue = readQueue();
+    const now = new Date().toISOString().replace(/[:.]/g, '-');
+
+    const dragData = { id: dragId, x, y, time: now };
+    const existingIndex = queue.findIndex((item) => item.id === dragId);
+
+    if (existingIndex >= 0) {
+      queue[existingIndex] = dragData;
+    } else {
+      queue.push(dragData);
+    }
+
+    localStorage.setItem(QUEUE_KEY, JSON.stringify(queue));
+  } catch (error) {
+    console.error('Error saving drag position:', error);
+  }
+};