flipfolio 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,19 @@
 # flipfolio
 
+[![npm](https://img.shields.io/npm/v/flipfolio)](https://www.npmjs.com/package/flipfolio)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/flipfolio)](https://bundlephobia.com/package/flipfolio)
+[![CI](https://github.com/kirthi-b/flipfolio/actions/workflows/ci.yml/badge.svg)](https://github.com/kirthi-b/flipfolio/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/flipfolio)](LICENSE)
+
 A gallery where every item is a folder: stack them, grid them, spin them.
 
 Started as a CSS 3D experiment; it now runs the [kirthi.studio](https://kirthi.studio) homepage. No framework, no dependencies.
 
-Live demo: [kirthi.studio/demos/flipfolio](https://kirthi.studio/demos/flipfolio/)
+Live demo: [kirthi.studio/demos/flipfolio](https://kirthi.studio/demos/flipfolio/), or edit it on [StackBlitz](https://stackblitz.com/github/kirthi-b/flipfolio/tree/master/examples/vanilla?file=main.js)
 
-> v0.1.0, an early release.
+> v0.3.0. New this release: a crisp grid view, runtime color and gradient theming, and drag hooks.
 
-![flipfolio demo: stack, grid, and carousel modes](assets/demo.gif)
+![flipfolio demo: throwing folders off the stack, grid mode, and photo decals](assets/demo.gif)
 
 ## Quick start
 ```sh
@@ -72,6 +77,9 @@ Folders hold your actual content. These are live project images, loaded with `it
 ![The same five folders laid out as a stack, a grid, and a carousel](assets/showcase/modes.png)
 One items array, three layouts. `setMode()` animates between them at runtime.
 
+![The front folder flung up off the pile with a grab cursor, the next folder revealed behind it](assets/showcase/throw.png)
+Grab the front folder and throw it. Stack mode, `drag: 'fling'`; a short drag springs back.
+
 ![Four folders holding a photo, a text document, an SVG chart, and a custom-rendered card](assets/showcase/any-content.png)
 Interiors take images, markup, DOM nodes, or a `contentRenderer` for anything else.
 
@@ -85,28 +93,47 @@ Per-folder tab colors, tokens for radius and blur, and the silhouette itself is
 |---|---|---|---|
 | `items` | `Item[]` | `[]` | `{ label?, color?, src?, content?, decal?, ...data }` |
 | `mode` | `'stack'\|'grid'\|'carousel'` | `'stack'` | 3 modes (a 4th "shelf" is planned) |
+| `grid` | `{ columns?, gap? }` | auto | pin the grid's column count and/or gap (px); default is a width/count heuristic |
 | `peek` | `'hover'\|'always'\|'off'` | `'hover'` | contents slide out of the folder |
+| `drag` | `'fling'\|'off'` | `'fling'` | grab the active folder and throw it (stack mode) |
 | `contentRenderer` | `(card, item, i) => void` | built-in | fills the folder interior with whatever you render |
 | `onSelect` | `(item, i) => void` | (none) | fired on click/Enter of the active folder (no built-in navigation) |
-| `folderPath` | `string` | manila default | SVG path `d` (viewBox `0 0 480 342`) |
+| `folderPath` | `string` | manila default | SVG path `d` (viewBox `0 0 480 342`), or a `FOLDER_PATHS` preset |
 | `loop` | `boolean` | `true` | wrap-around |
 | `scrollNav` | `boolean` | `true` | wheel/trackpad cycles the stack/carousel |
 | `reducedMotion` | `'auto'\|'off'\|'force'` | `'auto'` | drops the 3D tilt when reduced |
 | `defaultActiveIndex` | `number` | `0` | |
 | `label` | `string` | `'Folder gallery'` | `aria-label` for the listbox |
 
-Handle: `next()`, `prev()`, `goTo(i)`, `setMode(m)`, `setPeek(p)`, `getActiveIndex()`, `getMode()`, `destroy()`.
+Handle: `next()`, `prev()`, `goTo(i)`, `setMode(m)`, `setPeek(p)`, `setColor(i, hex)`, `setGradient(i, gradient)`, `getActiveIndex()`, `getMode()`, `getPeek()`, `getColor(i)`, `getGradient(i)`, `getItems()`, `destroy()`.
 
-Events (CustomEvent on the root, bubbling): `fg-select`, `fg-activechange`, `fg-modechange`, each with `event.detail`.
+Events (CustomEvent on the root, bubbling): `fg-select`, `fg-activechange`, `fg-modechange`, `fg-peekchange` (detail `{ peek }`), `fg-flingstart` and `fg-flingend` (detail `{ index, direction }`, direction `'next' | 'prev'`), each with `event.detail`. React props: `onSelect`, `onActiveChange`, `onModeChange`, `onPeekChange`, `onFlingStart`, `onFlingEnd`. Vue emits: `@select`, `@active-change`, `@mode-change`, `@peek-change`, `@fling-start`, `@fling-end`.
 
 ## Content
 Each folder renders what you give it: `item.src` for an image, `item.content` for an HTML string or a DOM node, or a `contentRenderer(card, item, index)` for anything richer. Set `item.decal` to an image URL and the photo prints on the folder's front panel; the back and tab keep their color. Contents slide out of the folder on hover; the `peek` option makes that always-on or turns it off.
 
+## Silhouette
+`folderPath` takes any SVG path `d` in the `0 0 480 342` viewBox. Three presets ship as `FOLDER_PATHS`: `left` (the default tab), `right` (tab mirrored), and `tray` (no tab). Pass one instead of a raw string:
+
+```js
+import { createFolderGallery, FOLDER_PATHS } from 'flipfolio';
+createFolderGallery(el, { items, folderPath: FOLDER_PATHS.tray });
+```
+
+## Runtime theming
+Each folder's palette derives from `item.color`; `setColor(index, hex)` re-derives the whole thing (SVG back, frosted + solid fronts, auto-contrast label) at runtime, no rebuild. `item.gradient` paints a CSS gradient across the front over the frosted surface, and `setGradient(index, gradient)` sets or clears it live (pass a falsy value to clear). Together they drive swatch pickers and theme switchers:
+
+```js
+gallery.setColor(0, '#3d2e42');                       // recolor one folder
+gallery.setGradient(0, 'linear-gradient(135deg, #236363, #6FCDCD, #8B7FB8)');
+gallery.setGradient(0, null);                          // back to the flat front
+```
+
 ## Accessibility
 `role="listbox"`/`option`, roving tabindex, arrow-key + Home/End navigation, `aria-live` position announcements, `:focus-visible` rings, and a `prefers-reduced-motion` fallback that drops the 3D tilt.
 
 ## Theming
-Override the CSS custom properties on `.fg-root`: `--fg-folder-bg`, `--fg-radius`, `--fg-perspective`, `--fg-ease`, `--fg-front`, `--fg-front-solid`, `--fg-active-blur`, `--fg-label`, `--fg-dot`, `--fg-dot-active`. Light is the default; dark applies automatically under `prefers-color-scheme: dark`, and `data-fg-theme="light"` or `"dark"` on `.fg-root` overrides either way.
+Override the CSS custom properties on `.fg-root`: `--fg-folder-bg`, `--fg-radius`, `--fg-perspective`, `--fg-ease`, `--fg-front`, `--fg-front-solid`, `--fg-active-blur`, `--fg-label`, `--fg-dot`, `--fg-dot-active`, `--fg-scene-height`, `--fg-gap`, `--fg-folder-shadow`, `--fg-gradient-opacity`, `--fg-label-size`, `--fg-label-weight`, `--fg-label-tracking`. Light is the default; dark applies automatically under `prefers-color-scheme: dark`, and `data-fg-theme="light"` or `"dark"` on `.fg-root` overrides either way.
 
 ## Limits
 Client-rendered only: folders paint after JS runs, there is no SSR of the layout itself. Every folder is a live 3D layer, so the sweet spot is 12 items or fewer, not hundreds. Uses `aspect-ratio` and `backdrop-filter`: evergreen browsers only, no IE fallback.

package/dist/{chunk-DT6YOBGV.js → chunk-RFBZ3WPG.js}

@@ -1,35 +1,11 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropSymbols = Object.getOwnPropertySymbols;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __propIsEnum = Object.prototype.propertyIsEnumerable;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __spreadValues = (a, b) => {
-  for (var prop in b || (b = {}))
-    if (__hasOwnProp.call(b, prop))
-      __defNormalProp(a, prop, b[prop]);
-  if (__getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(b)) {
-      if (__propIsEnum.call(b, prop))
-        __defNormalProp(a, prop, b[prop]);
-    }
-  return a;
-};
-var __objRest = (source, exclude) => {
-  var target = {};
-  for (var prop in source)
-    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
-      target[prop] = source[prop];
-  if (source != null && __getOwnPropSymbols)
-    for (var prop of __getOwnPropSymbols(source)) {
-      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
-        target[prop] = source[prop];
-    }
-  return target;
-};
-
 // src/folder-gallery.js
 var SVG_NS = "http://www.w3.org/2000/svg";
 var DEFAULT_FOLDER_PATH = "M 0 22 C 0 10 10 0 22 0 L 155 0 C 168 0 172 6 176 14 C 180 24 188 32 204 32 L 458 32 C 470 32 480 42 480 54 L 480 320 C 480 332 470 342 458 342 L 22 342 C 10 342 0 332 0 320 Z";
+var FOLDER_PATHS = {
+  left: DEFAULT_FOLDER_PATH,
+  right: "M 480 22 C 480 10 470 0 458 0 L 325 0 C 312 0 308 6 304 14 C 300 24 292 32 276 32 L 22 32 C 10 32 0 42 0 54 L 0 320 C 0 332 10 342 22 342 L 458 342 C 470 342 480 332 480 320 Z",
+  tray: "M 0 22 C 0 10 10 0 22 0 L 458 0 C 470 0 480 10 480 22 L 480 320 C 480 332 470 342 458 342 L 22 342 C 10 342 0 332 0 320 Z"
+};
 var DEFAULTS = {
   mode: "stack",
   // 'stack' | 'grid' | 'carousel'
@@ -40,19 +16,27 @@ var DEFAULTS = {
   // 'auto' | 'off' | 'force'
   peek: "hover",
   // 'hover' | 'always' | 'off'
+  drag: "fling",
+  // 'fling' | 'off' - grab the active folder and throw it (stack mode)
   defaultActiveIndex: 0,
   label: "Folder gallery"
 };
 var PEEK_MODES = /* @__PURE__ */ new Set(["hover", "always", "off"]);
+var DRAG_MODES = /* @__PURE__ */ new Set(["fling", "off"]);
+var INSTANCES = /* @__PURE__ */ new WeakMap();
 var MODE_WIDTHS = { stack: 480, grid: 720, carousel: 720 };
 var SCROLL_THRESHOLD = 30;
 var SCROLL_COOLDOWN = { stack: 450, carousel: 300 };
 function hexToRgb(hex) {
-  const h = String(hex).replace("#", "");
+  let h = String(hex).trim().replace(/^#/, "");
+  if (h.length === 3) h = h.replace(/./g, (c) => c + c);
+  if (!/^[0-9a-f]{6}$/i.test(h)) return null;
   return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
 }
 function folderColors(hex) {
-  const [r, g, b] = hexToRgb(hex);
+  const rgb = hexToRgb(hex);
+  if (!rgb) return null;
+  const [r, g, b] = rgb;
   const dn = (v) => Math.max(v - 30, 0);
   const up = (v, o) => Math.min(v + o, 255);
   const fr = up(r, 35);
@@ -66,6 +50,34 @@ function folderColors(hex) {
     label: yiq >= 128 ? "#1c1c1a" : "#ffffff"
   };
 }
+function paintFolder(card, hex) {
+  const c = folderColors(hex);
+  if (!c) return;
+  card.style.setProperty("--fg-folder-bg", hex);
+  card.style.setProperty("--fg-front", c.front);
+  card.style.setProperty("--fg-front-solid", c.frontSolid);
+  card.style.setProperty("--fg-label-on-color", c.label);
+  const path = card.querySelector(".fg-folder path");
+  if (path) path.setAttribute("fill", c.back);
+}
+function paintGradient(card, gradient) {
+  const front = card.querySelector(".fg-front");
+  if (!front) return;
+  let layer = front.querySelector(".fg-gradient");
+  if (!gradient) {
+    if (layer) layer.remove();
+    card.classList.remove("fg-card--gradient");
+    return;
+  }
+  if (!layer) {
+    layer = document.createElement("div");
+    layer.className = "fg-gradient";
+    layer.setAttribute("aria-hidden", "true");
+    front.insertBefore(layer, front.firstChild);
+  }
+  layer.style.background = gradient;
+  card.classList.add("fg-card--gradient");
+}
 function defaultContentRenderer(card, item) {
   const wrap = document.createElement("div");
   wrap.className = "fg-content";
@@ -85,12 +97,17 @@ function defaultContentRenderer(card, item) {
   card.appendChild(wrap);
 }
 function createFolderGallery(root, options = {}) {
-  if (!root || !root.nodeType) throw new Error("createFolderGallery: a root element is required");
-  const opts = __spreadValues(__spreadValues({}, DEFAULTS), options);
+  if (!root || root.nodeType !== 1) throw new Error("createFolderGallery: a root element is required");
+  const prior = INSTANCES.get(root);
+  if (prior) prior();
+  const provided = {};
+  for (const k in options) if (options[k] !== void 0) provided[k] = options[k];
+  const opts = { ...DEFAULTS, ...provided };
   const items = Array.isArray(opts.items) ? opts.items : [];
   const n = items.length;
   const renderContent = typeof opts.contentRenderer === "function" ? opts.contentRenderer : defaultContentRenderer;
-  const reduced = opts.reducedMotion === "force" || opts.reducedMotion !== "off" && typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const reducedQuery = opts.reducedMotion === "auto" && typeof matchMedia === "function" ? matchMedia("(prefers-reduced-motion: reduce)") : null;
+  let reduced = opts.reducedMotion === "force" || (reducedQuery ? reducedQuery.matches : false);
   let mode = MODE_WIDTHS[opts.mode] ? opts.mode : "stack";
   let active = Math.min(Math.max(opts.defaultActiveIndex | 0, 0), Math.max(n - 1, 0));
   let scrollCooldown = false;
@@ -101,9 +118,29 @@ function createFolderGallery(root, options = {}) {
     cleanups.push(() => el.removeEventListener(ev, fn, o));
   };
   const emit = (name, detail) => root.dispatchEvent(new CustomEvent(name, { detail, bubbles: true }));
+  let destroyed = false;
+  const timers = /* @__PURE__ */ new Set();
+  const rafs = /* @__PURE__ */ new Set();
+  const later = (fn, ms) => {
+    const id = setTimeout(() => {
+      timers.delete(id);
+      fn();
+    }, ms);
+    timers.add(id);
+    return id;
+  };
+  const frame = (fn) => {
+    const id = requestAnimationFrame(() => {
+      rafs.delete(id);
+      fn();
+    });
+    rafs.add(id);
+    return id;
+  };
   root.classList.add("fg-root");
   root.setAttribute("data-fg-mode", mode);
   root.setAttribute("data-fg-peek", PEEK_MODES.has(opts.peek) ? opts.peek : "hover");
+  root.setAttribute("data-fg-drag", DRAG_MODES.has(opts.drag) ? opts.drag : "fling");
   const scene = document.createElement("div");
   scene.className = "fg-scene";
   scene.setAttribute("role", "listbox");
@@ -118,26 +155,48 @@ function createFolderGallery(root, options = {}) {
   live.setAttribute("aria-atomic", "true");
   root.append(scene, dotsEl, live);
   function teardown() {
+    if (destroyed) return;
+    destroyed = true;
+    timers.forEach(clearTimeout);
+    timers.clear();
+    rafs.forEach(cancelAnimationFrame);
+    rafs.clear();
     cleanups.forEach((fn) => fn());
     cleanups.length = 0;
     root.replaceChildren();
     root.classList.remove("fg-root");
     root.removeAttribute("data-fg-mode");
     root.removeAttribute("data-fg-peek");
+    root.removeAttribute("data-fg-drag");
+    INSTANCES.delete(root);
   }
   if (n === 0) {
-    return { next() {
-    }, prev() {
-    }, goTo() {
-    }, setMode() {
-    }, setPeek() {
-    }, getActiveIndex: () => -1, getMode: () => mode, destroy: teardown };
+    const noop = () => {
+    };
+    INSTANCES.set(root, teardown);
+    return {
+      next: noop,
+      prev: noop,
+      goTo: noop,
+      setMode: noop,
+      setPeek: noop,
+      setColor: noop,
+      setGradient: noop,
+      getActiveIndex: () => -1,
+      getMode: () => mode,
+      getPeek: () => root.getAttribute("data-fg-peek"),
+      getColor: () => void 0,
+      getGradient: () => void 0,
+      getItems: () => [],
+      destroy: teardown
+    };
   }
   function setCardTransform(card, { x, y, z, rx, ry, s, zIndex, opacity, isActive }) {
-    card.style.transform = `translate3d(${x}px,${y}px,${z}px) rotateX(${rx}deg) rotateY(${ry}deg) scale(${s})`;
-    card.style.transformOrigin = "center bottom";
+    if (!card.classList.contains("fg-card--flung")) {
+      card.style.transform = `translate3d(${x}px,${y}px,${z}px) rotateX(${rx}deg) rotateY(${ry}deg) scale(${s})`;
+      card.style.opacity = String(opacity);
+    }
     card.style.zIndex = String(zIndex);
-    card.style.opacity = String(opacity);
     card.setAttribute("aria-selected", isActive ? "true" : "false");
     card.classList.toggle("is-active", isActive);
   }
@@ -147,13 +206,9 @@ function createFolderGallery(root, options = {}) {
     card.tabIndex = i === active ? 0 : -1;
     card.setAttribute("role", "option");
     card.setAttribute("aria-label", item.label || `Item ${i + 1}`);
-    if (item.color) {
-      const c = folderColors(item.color);
-      card.style.setProperty("--fg-folder-bg", item.color);
-      card.style.setProperty("--fg-front", c.front);
-      card.style.setProperty("--fg-front-solid", c.frontSolid);
-      card.style.setProperty("--fg-label-on-color", c.label);
-    }
+    card.setAttribute("aria-setsize", String(n));
+    card.setAttribute("aria-posinset", String(i + 1));
+    card.setAttribute("data-fg-index", String(i));
     const svg = document.createElementNS(SVG_NS, "svg");
     svg.setAttribute("class", "fg-folder");
     svg.setAttribute("viewBox", "0 0 480 342");
@@ -161,7 +216,7 @@ function createFolderGallery(root, options = {}) {
     svg.setAttribute("aria-hidden", "true");
     const path = document.createElementNS(SVG_NS, "path");
     path.setAttribute("d", opts.folderPath);
-    path.setAttribute("fill", item.color ? folderColors(item.color).back : "var(--fg-folder-bg)");
+    path.setAttribute("fill", "var(--fg-folder-bg)");
     svg.appendChild(path);
     card.appendChild(svg);
     renderContent(card, item, i);
@@ -184,6 +239,8 @@ function createFolderGallery(root, options = {}) {
       front.appendChild(label);
     }
     card.appendChild(front);
+    if (item.color) paintFolder(card, item.color);
+    if (item.gradient) paintGradient(card, item.gradient);
     scene.appendChild(card);
     return card;
   });
@@ -197,9 +254,13 @@ function createFolderGallery(root, options = {}) {
     dotsEl.appendChild(dot);
     return dot;
   });
+  const clearGridWidth = (card) => {
+    if (card.style.width) card.style.width = "";
+  };
   function layoutStack() {
     scene.style.height = "";
     cardEls.forEach((card, i) => {
+      clearGridWidth(card);
       const behind = (i - active + n) % n;
       if (behind === 0) {
         setCardTransform(card, { x: 0, y: 100, z: 20, rx: 0, ry: 0, s: 1, zIndex: n + 1, opacity: 1, isActive: true });
@@ -215,33 +276,31 @@ function createFolderGallery(root, options = {}) {
   }
   function layoutGrid() {
     const sceneW = scene.clientWidth || MODE_WIDTHS.grid;
-    const cols = sceneW < 520 ? 2 : n <= 4 ? 2 : 3;
-    const gap = 16;
-    const cardW = sceneW;
-    const cardH = sceneW * (2 / 3);
-    const sc = (sceneW - (cols - 1) * gap) / (cols * cardW);
-    const scaledW = cardW * sc;
-    const scaledH = cardH * sc;
-    const tabScaled = 22 * sc;
+    const gap = Number.isFinite(opts.grid && opts.grid.gap) ? opts.grid.gap : 16;
+    const cols = Math.max(1, Math.round(
+      opts.grid && opts.grid.columns ? opts.grid.columns : sceneW < 520 ? 2 : n <= 4 ? 2 : 3
+    ));
+    const cellW = (sceneW - (cols - 1) * gap) / cols;
+    const cellH = cellW * (2 / 3);
     const rows = Math.ceil(n / cols);
     cardEls.forEach((card, i) => {
       const col = i % cols;
       const row = Math.floor(i / cols);
       const itemsInRow = Math.min(cols, n - row * cols);
-      const rowW = itemsInRow * scaledW + (itemsInRow - 1) * gap;
+      const rowW = itemsInRow * cellW + (itemsInRow - 1) * gap;
       const rowStartX = (sceneW - rowW) / 2;
-      const cellLeft = rowStartX + col * (scaledW + gap);
-      const cellTop = row * (scaledH + tabScaled + gap) + tabScaled;
-      const tx = cellLeft + scaledW / 2 - cardW / 2;
-      const ty = cellTop + scaledH - cardH;
-      setCardTransform(card, { x: tx, y: ty, z: 0, rx: 0, ry: 0, s: sc, zIndex: i === active ? 2 : 1, opacity: 1, isActive: i === active });
+      const x = rowStartX + col * (cellW + gap);
+      const y = row * (cellH + gap);
+      card.style.width = cellW + "px";
+      setCardTransform(card, { x, y, z: 0, rx: 0, ry: 0, s: 1, zIndex: i === active ? 2 : 1, opacity: 1, isActive: i === active });
     });
-    scene.style.height = rows * (scaledH + tabScaled + gap) + 20 + "px";
+    scene.style.height = rows * cellH + (rows - 1) * gap + "px";
   }
   function layoutCarousel() {
     const sceneW = scene.clientWidth || MODE_WIDTHS.carousel;
     const cardW = sceneW;
     const cardH = cardW * (2 / 3);
+    cardEls.forEach(clearGridWidth);
     const activeSc = 0.62;
     const activeW = cardW * activeSc;
     const sceneH = Math.max(cardH * activeSc + 40, 180);
@@ -276,29 +335,39 @@ function createFolderGallery(root, options = {}) {
     live.textContent = cur && cur.label ? `${active + 1} of ${n}: ${cur.label}` : `${active + 1} of ${n}`;
   }
   function goTo(i) {
-    const next = opts.loop ? (i % n + n) % n : Math.min(Math.max(i, 0), n - 1);
+    if (destroyed) return;
+    const t = Number.isFinite(+i) ? Math.trunc(+i) : active;
+    const next = opts.loop ? (t % n + n) % n : Math.min(Math.max(t, 0), n - 1);
     if (next === active) return;
     active = next;
     applyLayout();
     emit("fg-activechange", { index: active, item: items[active] });
   }
   function select(i) {
+    if (destroyed) return;
     emit("fg-select", { index: i, item: items[i] });
     if (typeof opts.onSelect === "function") opts.onSelect(items[i], i);
   }
   function setMode(m) {
-    if (m === mode || !MODE_WIDTHS[m]) return;
+    if (destroyed || m === mode || !MODE_WIDTHS[m]) return;
     mode = m;
     root.setAttribute("data-fg-mode", mode);
     applyLayout();
     emit("fg-modechange", { mode });
   }
   function setPeek(p) {
-    if (!PEEK_MODES.has(p)) return;
+    if (destroyed || !PEEK_MODES.has(p) || p === root.getAttribute("data-fg-peek")) return;
     root.setAttribute("data-fg-peek", p);
+    emit("fg-peekchange", { peek: p });
   }
+  const dragEnabled = opts.drag !== "off";
+  let suppressClick = false;
   cardEls.forEach((card, i) => {
     on(card, "click", () => {
+      if (suppressClick) {
+        suppressClick = false;
+        return;
+      }
       i === active ? select(i) : goTo(i);
     });
     on(card, "keydown", (e) => {
@@ -364,7 +433,7 @@ function createFolderGallery(root, options = {}) {
         scrollAccum = 0;
         scrollCooldown = true;
         goTo(active + dir);
-        setTimeout(() => {
+        later(() => {
           scrollCooldown = false;
           scrollAccum = 0;
         }, SCROLL_COOLDOWN[mode] || 300);
@@ -378,6 +447,7 @@ function createFolderGallery(root, options = {}) {
     touchStartY = e.touches[0].clientY;
   }, { passive: true });
   on(scene, "touchend", (e) => {
+    if (dragEnabled && mode === "stack") return;
     const dx = touchStartX - e.changedTouches[0].clientX;
     const dy = touchStartY - e.changedTouches[0].clientY;
     const ax = Math.abs(dx);
@@ -386,29 +456,158 @@ function createFolderGallery(root, options = {}) {
     const dir = ax > ay ? dx > 0 ? 1 : -1 : dy > 0 ? 1 : -1;
     goTo(active + dir);
   }, { passive: true });
+  if (dragEnabled) {
+    const DRAG_ROT = 0.04;
+    const FLING_DIST = 90;
+    const FLING_VEL = 0.5;
+    const TAP_SLOP = 6;
+    let dragCard = null;
+    let dragBase = "";
+    let startPX = 0, startPY = 0, dragDX = 0, dragDY = 0;
+    let lastX = 0, lastY = 0, lastT = 0, velX = 0, velY = 0;
+    on(scene, "pointerdown", (e) => {
+      if (mode !== "stack") return;
+      if (e.button !== void 0 && e.button !== 0) return;
+      const card = e.target && e.target.closest ? e.target.closest(".fg-card") : null;
+      if (!card || !card.classList.contains("is-active")) return;
+      dragCard = card;
+      dragBase = card.style.transform;
+      startPX = e.clientX;
+      startPY = e.clientY;
+      dragDX = 0;
+      dragDY = 0;
+      lastX = e.clientX;
+      lastY = e.clientY;
+      lastT = typeof performance !== "undefined" ? performance.now() : Date.now();
+      velX = 0;
+      velY = 0;
+      card.classList.add("fg-card--dragging");
+      if (card.setPointerCapture && e.pointerId !== void 0) {
+        try {
+          card.setPointerCapture(e.pointerId);
+        } catch (_) {
+        }
+      }
+    });
+    on(window, "pointermove", (e) => {
+      if (!dragCard) return;
+      dragDX = e.clientX - startPX;
+      dragDY = e.clientY - startPY;
+      const now = typeof performance !== "undefined" ? performance.now() : Date.now();
+      const dt = Math.max(now - lastT, 1);
+      velX = (e.clientX - lastX) / dt;
+      velY = (e.clientY - lastY) / dt;
+      lastX = e.clientX;
+      lastY = e.clientY;
+      lastT = now;
+      dragCard.style.transform = `${dragBase} translate3d(${dragDX}px, ${dragDY}px, 40px) rotate(${(dragDX * DRAG_ROT).toFixed(2)}deg)`;
+    });
+    const endDrag = () => {
+      if (!dragCard) return;
+      const card = dragCard;
+      dragCard = null;
+      card.classList.remove("fg-card--dragging");
+      const dist = Math.hypot(dragDX, dragDY);
+      if (dist < TAP_SLOP) {
+        card.style.transform = dragBase;
+        return;
+      }
+      suppressClick = true;
+      const horizontal = Math.abs(dragDX) >= Math.abs(dragDY);
+      const flung = dist > FLING_DIST || Math.hypot(velX, velY) > FLING_VEL;
+      const dir = horizontal ? dragDX > 0 ? -1 : 1 : dragDY > 0 ? -1 : 1;
+      const target = active + dir;
+      const blocked = !opts.loop && (target < 0 || target > n - 1);
+      if (!flung || blocked) {
+        card.style.transform = dragBase;
+        return;
+      }
+      const semantic = dir > 0 ? "next" : "prev";
+      emit("fg-flingstart", { index: active, direction: semantic });
+      if (reduced) {
+        goTo(target);
+        emit("fg-flingend", { index: target, direction: semantic });
+        return;
+      }
+      const offX = horizontal ? Math.sign(dragDX) * Math.max(window.innerWidth * 0.7, 480) : dragDX * 3;
+      const offY = horizontal ? dragDY * 3 : Math.sign(dragDY) * Math.max(window.innerHeight * 0.7, 480);
+      card.classList.add("fg-card--flung");
+      card.style.transform = `${dragBase} translate3d(${offX}px, ${offY}px, 40px) rotate(${Math.sign(dragDX || 1) * 18}deg)`;
+      card.style.opacity = "0";
+      goTo(target);
+      later(() => {
+        card.classList.add("fg-card--snap");
+        card.classList.remove("fg-card--flung");
+        applyLayout();
+        const slot = card.style.transform;
+        const slotOpacity = card.style.opacity;
+        card.style.transform = `${slot} translate3d(0, -90px, 0)`;
+        card.style.opacity = "0";
+        frame(() => frame(() => {
+          card.classList.remove("fg-card--snap");
+          card.classList.add("fg-card--entering");
+          card.style.transform = slot;
+          card.style.opacity = slotOpacity;
+          later(() => {
+            card.classList.remove("fg-card--entering");
+            emit("fg-flingend", { index: target, direction: semantic });
+          }, 700);
+        }));
+      }, 400);
+    };
+    on(window, "pointerup", endDrag);
+    on(window, "pointercancel", endDrag);
+  }
   let resizeTimer;
   on(window, "resize", () => {
     clearTimeout(resizeTimer);
-    resizeTimer = setTimeout(applyLayout, 150);
+    resizeTimer = later(applyLayout, 150);
   });
+  if (reducedQuery && reducedQuery.addEventListener) {
+    on(reducedQuery, "change", (e) => {
+      if (!destroyed) {
+        reduced = e.matches;
+        applyLayout();
+      }
+    });
+  }
   applyLayout();
-  return {
+  const handle = {
     next: () => goTo(active + 1),
     prev: () => goTo(active - 1),
     goTo,
     setMode,
     setPeek,
+    setColor: (i, hex) => {
+      const card = cardEls[i];
+      if (card && !destroyed) paintFolder(card, hex);
+    },
+    setGradient: (i, gradient) => {
+      const card = cardEls[i];
+      if (card && !destroyed) paintGradient(card, gradient);
+    },
     getActiveIndex: () => active,
     getMode: () => mode,
+    getPeek: () => root.getAttribute("data-fg-peek"),
+    getColor: (i) => {
+      const card = cardEls[i];
+      return card ? card.style.getPropertyValue("--fg-folder-bg") || void 0 : void 0;
+    },
+    getGradient: (i) => {
+      const layer = cardEls[i] && cardEls[i].querySelector(".fg-gradient");
+      return layer ? layer.style.background || void 0 : void 0;
+    },
+    getItems: () => items.slice(),
     destroy: teardown
   };
+  INSTANCES.set(root, teardown);
+  return handle;
 }
 var folder_gallery_default = createFolderGallery;
 
 export {
-  __spreadValues,
-  __objRest,
+  FOLDER_PATHS,
   createFolderGallery,
   folder_gallery_default
 };
-//# sourceMappingURL=chunk-DT6YOBGV.js.map
+//# sourceMappingURL=chunk-RFBZ3WPG.js.map