@dfosco/tiny-canvas 1.1.0

package/README.md

@@ -0,0 +1,95 @@
+# Tiny Canvas
+
+A lightweight React canvas with draggable elements and persistent positions.
+
+## Install
+
+```bash
+npm install tiny-canvas
+```
+
+## Quick start
+
+```jsx
+import { Canvas } from 'tiny-canvas'
+import 'tiny-canvas/style.css'
+
+function App() {
+  return (
+    <Canvas grid>
+      <div id="card-1">Hello</div>
+      <div id="card-2">World</div>
+    </Canvas>
+  )
+}
+```
+
+Give each child an `id` prop — this is how positions are persisted in localStorage. Children without an `id` are still draggable but won't remember their position.
+
+## Components
+
+### `<Canvas>`
+
+Wraps children in draggable containers.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `centered` | `boolean` | `true` | Center children with flexbox |
+| `grid` | `boolean` | `false` | Show dot-grid background and enable snap-to-grid |
+| `gridSize` | `number` | `18` | Grid snap size in pixels (when `grid` is `true`) |
+
+### `<Draggable>`
+
+Standalone draggable wrapper — use directly without `Canvas` if needed.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `gridSize` | `number` | — | Grid snap size in pixels. No snapping when omitted. |
+
+## Hooks
+
+### `useResetCanvas(options?)`
+
+Returns a function that clears all saved positions from localStorage.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `reload` | `boolean` | `false` | Reload the page after clearing |
+
+## Utilities
+
+```js
+import { saveDrag, getQueue, refreshStorage, findDragId } from 'tiny-canvas'
+```
+
+- `saveDrag(id, x, y)` — persist a position
+- `getQueue(id)` — retrieve `{ x, y }` for an element
+- `refreshStorage()` — initialize localStorage if empty
+- `findDragId(children)` — extract the first `id` prop from React children
+
+## CSS customization
+
+Override `--tc-*` custom properties to theme the canvas:
+
+```css
+:root {
+  --tc-border-radius: 12px;
+  --tc-shadow-rest: 0 1px 3px rgba(0, 0, 0, 0.12);
+  --tc-shadow-float: 0 4px 12px rgba(0, 0, 0, 0.15);
+  --tc-border-color: rgba(0, 0, 0, 0.15);
+  --tc-bg-muted: #f6f8fa;
+  --tc-dot-color: rgba(0, 0, 0, 0.08);
+  --tc-grid-size: 36px;
+}
+```
+
+If you use [Primer Primitives](https://github.com/primer/primitives), the variables automatically pick up your theme tokens.
+
+## Peer dependencies
+
+- `react` >= 18
+- `react-dom` >= 18
+
+---
+
+MIT License

package/dist/tiny-canvas.css

@@ -0,0 +1 @@
+:root{--tc-border-radius: var(--borderRadius-large, 12px);--tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, .12));--tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, .15));--tc-border-color: var(--borderColor-muted, rgba(0, 0, 0, .15));--tc-bg-muted: var(--bgColor-muted, #f6f8fa);--tc-dot-color: var(--overlay-backdrop-bgColor, rgba(0, 0, 0, .08));--tc-grid-size: var(--golden-number, 36px);--tc-grid-offset: calc(var(--tc-grid-size) / -2);--tc-font-stack: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif}.tc-canvas{min-width:100vw;min-height:100vh;margin:0;font-family:var(--tc-font-stack);position:relative;background-color:var(--tc-bg-muted);width:100vw;max-width:100vw;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) 2px,transparent 2px);background-size:var(--tc-grid-size) var(--tc-grid-size);background-position:var(--tc-grid-offset) var(--tc-grid-offset)}@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, .1));--tc-border-color: var(--borderColor-muted, rgba(255, 255, 255, .15));--tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, .3));--tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, .4))}}.tc-canvas[data-color-mode=dark]{--tc-bg-muted: var(--bgColor-muted, #161b22);--tc-dot-color: var(--overlay-backdrop-bgColor, rgba(255, 255, 255, .1));--tc-border-color: var(--borderColor-muted, rgba(255, 255, 255, .15));--tc-shadow-rest: var(--shadow-resting-small, 0 1px 3px rgba(0, 0, 0, .3));--tc-shadow-float: var(--shadow-floating-small, 0 4px 12px rgba(0, 0, 0, .4))}body .tc-draggable-inner:not(:active){touch-action:none}.tc-on-translation{transition:transform calc(var(--tc-translation-ms, .25s) * 2) cubic-bezier(.78,.1,.51,.78) var(--tc-translation-ms, .25s)}.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 .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}

package/dist/tiny-canvas.js

@@ -0,0 +1,289 @@
+import { jsx as Q } from "react/jsx-runtime";
+import me, { useRef as le, useState as Y, useEffect as P, Children as Ee, useCallback as Ce } from "react";
+var ae = { dragStart: !0 }, se = { delay: 0, distance: 3 };
+function Ae(e, r = {}) {
+  let n, o, { bounds: a, axis: c = "both", gpuAcceleration: l = !0, legacyTranslate: d = !1, transform: m, applyUserSelectHack: w = !0, disabled: N = !1, ignoreMultitouch: v = !1, recomputeBounds: D = ae, grid: f, threshold: y = se, position: b, cancel: q, handle: M, defaultClass: u = "neodrag", defaultClassDragging: x = "neodrag-dragging", defaultClassDragged: I = "neodrag-dragged", defaultPosition: be = { x: 0, y: 0 }, onDragStart: Se, onDrag: we, onDragEnd: De } = r, H = !1, L = !1, de = 0, O = !1, J = !1, R = 0, T = 0, k = 0, B = 0, _ = 0, G = 0, { x: j, y: z } = b ? { x: (b == null ? void 0 : b.x) ?? 0, y: (b == null ? void 0 : b.y) ?? 0 } : be;
+  te(j, z);
+  let E, $, X, K, Z, fe = "", xe = !!b;
+  D = { ...ae, ...D }, y = { ...se, ...y ?? {} };
+  let U = /* @__PURE__ */ new Set();
+  function ge(t) {
+    H && !L && J && O && Z && (L = !0, (function(s) {
+      re("neodrag:start", Se, s);
+    })(t), A.add(x), w && (fe = ee.userSelect, ee.userSelect = "none"));
+  }
+  const ee = document.body.style, A = e.classList;
+  function te(t = R, s = T) {
+    if (!m) {
+      if (d) {
+        let p = `${+t}px, ${+s}px`;
+        return W(e, "transform", l ? `translate3d(${p}, 0)` : `translate(${p})`);
+      }
+      return W(e, "translate", `${+t}px ${+s}px`);
+    }
+    const g = m({ offsetX: t, offsetY: s, rootNode: e });
+    ie(g) && W(e, "transform", g);
+  }
+  function re(t, s, g) {
+    const p = /* @__PURE__ */ (function(h) {
+      return { offsetX: R, offsetY: T, rootNode: e, currentNode: Z, event: h };
+    })(g);
+    e.dispatchEvent(new CustomEvent(t, { detail: p })), s == null || s(p);
+  }
+  const V = addEventListener, ne = new AbortController(), oe = { signal: ne.signal, capture: !1 };
+  function pe() {
+    let t = e.offsetWidth / $.width;
+    return isNaN(t) && (t = 1), t;
+  }
+  return W(e, "touch-action", "none"), V("pointerdown", ((t) => {
+    if (N || t.button === 2) return;
+    if (U.add(t.pointerId), v && U.size > 1) return t.preventDefault();
+    if (D.dragStart && (E = ce(a, e)), ie(M) && ie(q) && M === q) throw new Error("`handle` selector can't be same as `cancel` selector");
+    if (A.add(u), X = (function(i, S) {
+      if (!i) return [S];
+      if (ue(i)) return [i];
+      if (Array.isArray(i)) return i;
+      const C = S.querySelectorAll(i);
+      if (C === null) throw new Error("Selector passed for `handle` option should be child of the element on which the action is applied");
+      return Array.from(C.values());
+    })(M, e), K = (function(i, S) {
+      if (!i) return [];
+      if (ue(i)) return [i];
+      if (Array.isArray(i)) return i;
+      const C = S.querySelectorAll(i);
+      if (C === null) throw new Error("Selector passed for `cancel` option should be child of the element on which the action is applied");
+      return Array.from(C.values());
+    })(q, e), n = /(both|x)/.test(c), o = /(both|y)/.test(c), ye(K, X)) throw new Error("Element being dragged can't be a child of the element on which `cancel` is applied");
+    const s = t.composedPath()[0];
+    if (!X.some(((i) => {
+      var S;
+      return i.contains(s) || ((S = i.shadowRoot) == null ? void 0 : S.contains(s));
+    })) || ye(K, [s])) return;
+    Z = X.length === 1 ? e : X.find(((i) => i.contains(s))), H = !0, de = Date.now(), y.delay || (O = !0), $ = e.getBoundingClientRect();
+    const { clientX: g, clientY: p } = t, h = pe();
+    n && (k = g - j / h), o && (B = p - z / h), E && (_ = g - $.left, G = p - $.top);
+  }), oe), V("pointermove", ((t) => {
+    if (!H || v && U.size > 1) return;
+    if (!L) {
+      if (O || Date.now() - de >= y.delay && (O = !0, ge(t)), !J) {
+        const h = t.clientX - k, i = t.clientY - B;
+        Math.sqrt(h ** 2 + i ** 2) >= y.distance && (J = !0, ge(t));
+      }
+      if (!L) return;
+    }
+    D.drag && (E = ce(a, e)), t.preventDefault(), $ = e.getBoundingClientRect();
+    let s = t.clientX, g = t.clientY;
+    const p = pe();
+    if (E) {
+      const h = { left: E.left + _, top: E.top + G, right: E.right + _ - $.width, bottom: E.bottom + G - $.height };
+      s = he(s, h.left, h.right), g = he(g, h.top, h.bottom);
+    }
+    if (Array.isArray(f)) {
+      let [h, i] = f;
+      if (isNaN(+h) || h < 0) throw new Error("1st argument of `grid` must be a valid positive number");
+      if (isNaN(+i) || i < 0) throw new Error("2nd argument of `grid` must be a valid positive number");
+      let S = s - k, C = g - B;
+      [S, C] = Ne([h / p, i / p], S, C), s = k + S, g = B + C;
+    }
+    n && (R = Math.round((s - k) * p)), o && (T = Math.round((g - B) * p)), j = R, z = T, re("neodrag", we, t), te();
+  }), oe), V("pointerup", ((t) => {
+    U.delete(t.pointerId), H && (L && (V("click", ((s) => s.stopPropagation()), { once: !0, signal: ne.signal, capture: !0 }), D.dragEnd && (E = ce(a, e)), A.remove(x), A.add(I), w && (ee.userSelect = fe), re("neodrag:end", De, t), n && (k = R), o && (B = T)), H = !1, L = !1, O = !1, J = !1);
+  }), oe), { destroy: () => ne.abort(), update: (t) => {
+    var g, p;
+    c = t.axis || "both", N = t.disabled ?? !1, v = t.ignoreMultitouch ?? !1, M = t.handle, a = t.bounds, D = t.recomputeBounds ?? ae, q = t.cancel, w = t.applyUserSelectHack ?? !0, f = t.grid, l = t.gpuAcceleration ?? !0, d = t.legacyTranslate ?? !1, m = t.transform, y = { ...se, ...t.threshold ?? {} };
+    const s = A.contains(I);
+    A.remove(u, I), u = t.defaultClass ?? "neodrag", x = t.defaultClassDragging ?? "neodrag-dragging", I = t.defaultClassDragged ?? "neodrag-dragged", A.add(u), s && A.add(I), xe && (j = R = ((g = t.position) == null ? void 0 : g.x) ?? R, z = T = ((p = t.position) == null ? void 0 : p.y) ?? T, te());
+  } };
+}
+var he = (e, r, n) => Math.min(Math.max(e, r), n), ie = (e) => typeof e == "string", Ne = ([e, r], n, o) => {
+  const a = (c, l) => l === 0 ? 0 : Math.ceil(c / l) * l;
+  return [a(n, e), a(o, r)];
+}, ye = (e, r) => e.some(((n) => r.some(((o) => n.contains(o)))));
+function ce(e, r) {
+  if (e === void 0) return;
+  if (ue(e)) return e.getBoundingClientRect();
+  if (typeof e == "object") {
+    const { top: o = 0, left: a = 0, right: c = 0, bottom: l = 0 } = e;
+    return { top: o, right: window.innerWidth - c, bottom: window.innerHeight - l, left: a };
+  }
+  if (e === "parent") return r.parentNode.getBoundingClientRect();
+  const n = document.querySelector(e);
+  if (n === null) throw new Error("The selector provided for bound doesn't exists in the document.");
+  return n.getBoundingClientRect();
+}
+var W = (e, r, n) => e.style.setProperty(r, n), ue = (e) => e instanceof HTMLElement;
+function F(e) {
+  return e == null || typeof e == "string" || e instanceof HTMLElement ? e : "current" in e ? e.current : Array.isArray(e) ? e.map(((r) => r instanceof HTMLElement ? r : r.current)) : void 0;
+}
+function qe(e, r = {}) {
+  const n = le(), [o, a] = Y(!1), [c, l] = Y();
+  let { onDragStart: d, onDrag: m, onDragEnd: w, handle: N, cancel: v } = r, D = F(N), f = F(v);
+  function y(u, x) {
+    l(u), x == null || x(u);
+  }
+  function b(u) {
+    a(!0), y(u, d);
+  }
+  function q(u) {
+    y(u, m);
+  }
+  function M(u) {
+    a(!1), y(u, w);
+  }
+  return P((() => {
+    if (typeof window > "u") return;
+    const u = e.current;
+    if (!u) return;
+    ({ onDragStart: d, onDrag: m, onDragEnd: w } = r);
+    const { update: x, destroy: I } = Ae(u, { ...r, handle: D, cancel: f, onDragStart: b, onDrag: q, onDragEnd: M });
+    return n.current = x, I;
+  }), []), P((() => {
+    var u;
+    (u = n.current) == null || u.call(n, { ...r, handle: F(N), cancel: F(v), onDragStart: b, onDrag: q, onDragEnd: M });
+  }), [r]), { isDragging: o, dragState: c };
+}
+const Me = (e) => {
+  if (!e) return null;
+  let r = null;
+  const n = (o) => {
+    if (o.props && o.props.id) {
+      r = o.props.id;
+      return;
+    }
+    o.props && o.props.children && me.Children.forEach(o.props.children, n);
+  };
+  return n(e), r;
+};
+function Ie(e) {
+  let r = 5381;
+  for (let n = 0; n < e.length; n++)
+    r = (r << 5) + r + e.charCodeAt(n) >>> 0;
+  return r.toString(16).padStart(8, "0");
+}
+function ve(e) {
+  var c;
+  if (e == null || typeof e == "boolean") return "";
+  if (typeof e == "string" || typeof e == "number") return "#text";
+  const r = e.type, n = typeof r == "function" ? r.displayName || r.name || "Anonymous" : typeof r == "string" ? r : "Fragment", o = (c = e.props) == null ? void 0 : c.children;
+  if (o == null) return n;
+  const a = [];
+  return me.Children.forEach(o, (l) => {
+    const d = ve(l);
+    d && a.push(d);
+  }), a.length ? `${n}(${a.join(",")})` : n;
+}
+const Re = (e, r) => {
+  const n = ve(e);
+  return `tc-${Ie(n)}-${r}`;
+}, Te = (e) => {
+  try {
+    return (JSON.parse(localStorage.getItem("tiny-canvas-queue")) || []).reduce((o, a) => (o[a.id] = { id: a.id, x: a.x, y: a.y }, o), {})[e] || { x: 0, y: 0 };
+  } catch (r) {
+    return console.error("Error getting saved coordinates:", r), { x: 0, y: 0 };
+  }
+}, $e = () => {
+  try {
+    localStorage.getItem("tiny-canvas-queue") || localStorage.setItem("tiny-canvas-queue", JSON.stringify([]));
+  } catch (e) {
+    console.error("LocalStorage is not available:", e);
+  }
+}, Le = (e, r, n) => {
+  try {
+    const o = JSON.parse(localStorage.getItem("tiny-canvas-queue")) || [], a = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-"), c = { id: e, x: r, y: n, time: a }, l = o.findIndex((d) => d.id === e);
+    l >= 0 ? o[l] = c : o.push(c), localStorage.setItem("tiny-canvas-queue", JSON.stringify(o));
+  } catch (o) {
+    console.error("Error saving drag position:", o);
+  }
+}, ke = 250;
+function Be({ children: e, gridSize: r, dragId: n }) {
+  const o = le(null), a = le(Te(n)).current, [c, l] = Y(!1), [d, m] = Y({ x: 0, y: 0 }), [w, N] = Y(
+    Math.random() < 0.5 ? -0.5 : 0.5
+  );
+  P(() => {
+    const f = o.current;
+    if (f && n && a && (a.x !== 0 || a.y !== 0)) {
+      f.classList.add("tc-on-translation"), l(!0);
+      const y = setTimeout(() => {
+        f.classList.remove("tc-on-translation"), l(!1);
+      }, ke * 4);
+      return () => clearTimeout(y);
+    }
+  }, []), P(() => {
+    $e(), o.current && a && m({ x: a.x, y: a.y });
+  }, [a]);
+  const { isDragging: v } = qe(o, {
+    axis: "both",
+    bounds: "body",
+    threshold: { delay: 50, distance: 30 },
+    defaultClass: "tc-drag",
+    defaultClassDragging: "tc-on",
+    defaultClassDragged: "tc-off",
+    applyUserSelectHack: !0,
+    position: { x: d.x, y: d.y },
+    onDrag: ({ offsetX: f, offsetY: y }) => m({ x: f, y }),
+    onDragEnd: (f) => {
+      m({ x: f.offsetX, y: f.offsetY }), n !== null && Le(n, f.offsetX, f.offsetY);
+    }
+  }), D = v || c ? `${w}deg` : "0deg";
+  return P(() => {
+    N(Math.random() < 0.5 ? -0.5 : 0.5);
+  }, [v]), /* @__PURE__ */ Q(
+    "article",
+    {
+      ref: o,
+      style: { cursor: v ? "grabbing" : "grab" },
+      children: /* @__PURE__ */ Q(
+        "div",
+        {
+          className: "tc-draggable-inner",
+          style: {
+            transform: v || c ? `rotate(${D})` : void 0,
+            transition: "transform ease-in-out 150ms"
+          },
+          children: e
+        }
+      )
+    }
+  );
+}
+function Xe({
+  children: e,
+  centered: r = !0,
+  dotted: n = !1,
+  grid: o = !1,
+  gridSize: a,
+  colorMode: c = "auto"
+}) {
+  return /* @__PURE__ */ Q(
+    "main",
+    {
+      className: "tc-canvas",
+      "data-dotted": n || o || void 0,
+      "data-color-mode": c !== "auto" ? c : void 0,
+      children: Ee.map(e, (d, m) => {
+        const w = Me(d) ?? Re(d, m);
+        return /* @__PURE__ */ Q(Be, { gridSize: a, dragId: w, children: d }, m);
+      })
+    }
+  );
+}
+function Ye({ reload: e = !1 } = {}) {
+  return Ce(() => {
+    try {
+      localStorage.removeItem("tiny-canvas-queue");
+    } catch (r) {
+      console.error("Error clearing canvas state:", r);
+    }
+    e && window.location.reload();
+  }, [e]);
+}
+export {
+  Xe as Canvas,
+  Be as Draggable,
+  Me as findDragId,
+  Re as generateDragId,
+  Te as getQueue,
+  $e as refreshStorage,
+  Le as saveDrag,
+  Ye as useResetCanvas
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@dfosco/tiny-canvas",
+  "version": "1.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "A lightweight React canvas with draggable elements and persistent positions",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./style.css": "./src/style.css"
+  },
+  "publishConfig": {
+    "main": "./dist/tiny-canvas.js",
+    "module": "./dist/tiny-canvas.js",
+    "exports": {
+      ".": {
+        "import": "./dist/tiny-canvas.js",
+        "types": "./src/index.d.ts"
+      },
+      "./style.css": "./dist/tiny-canvas.css"
+    }
+  },
+  "files": [
+    "dist",
+    "src/index.d.ts"
+  ],
+  "scripts": {
+    "build": "vite build"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@neodrag/react": "^2.3.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.4",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vite": "^6.0.5"
+  }
+}

package/src/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;