@dreamboard-games/sdk 0.5.0-alpha.21 → 0.5.0-alpha.23

package/dist/index.js

@@ -73,7 +73,7 @@ import {
 } from "./chunk-CZRPUWCT.js";
 
 // src/package-set.ts
-var DREAMBOARD_SDK_VERSION = true ? "0.5.0-alpha.21" : "0.0.0-development";
+var DREAMBOARD_SDK_VERSION = true ? "0.5.0-alpha.23" : "0.0.0-development";
 var DREAMBOARD_SDK_PACKAGES = {
   "@dreamboard-games/sdk": DREAMBOARD_SDK_VERSION
 };

package/dist/react.d.ts

@@ -7,6 +7,19 @@ import 'zod';
 import 'honeycomb-grid';
 import '@tanstack/store';
 
+/** How the dragged card would show where it lands if dropped now. */
+interface DragFit {
+    /**
+     * The width of the card-sized box marked `data-drop-landing` there,
+     * relative to the picked-up card's layout width. Null until the card has
+     * been over such a box; between areas it keeps the last one's.
+     */
+    readonly scale: number | null;
+    /** Drawn in a pile's slot. */
+    readonly snapped: boolean;
+    /** The area's zone would conceal the card. */
+    readonly concealed: boolean;
+}
 interface CardGestureProps {
     onPointerDown(event: PointerEvent<Element>): void;
     onFocus(event: FocusEvent<Element>): void;
@@ -83,6 +96,12 @@ interface DragOverlay<G> {
     readonly target: DropTarget<G> | null;
     /** A registered zone landing; absent for interactions with no zone destination. */
     readonly landing: PositionTarget<IdOf<G, "zoneId">, ZoneHostId<G>> | null;
+    /**
+     * Draw the copy at `fit.scale` once it is known, in place of its lifted
+     * size, and as its back while `fit.concealed`. The ref already moves it
+     * into a pile's slot while `fit.snapped`.
+     */
+    readonly fit: DragFit;
     /** Attach to a fixed-position copy of the card; it follows the pointer. */
     readonly ref: (element: HTMLElement | null) => (() => void) | undefined;
 }
@@ -155,4 +174,4 @@ declare function useMarqueeSelection<Id extends string>(options: {
     };
 };
 
-export { type CardGesture, type CardGestureOptions, type CardGestureProps, type CardPresentation, type CardRow, type DragOverlay, type DropArea, DropAreaBinding, type DropAreaOptions, type MarqueeBounds, type SelectionOptions, type ZonePresentation, createGameHook, useMarqueeSelection };
+export { type CardGesture, type CardGestureOptions, type CardGestureProps, type CardPresentation, type CardRow, type DragFit, type DragOverlay, type DropArea, DropAreaBinding, type DropAreaOptions, type MarqueeBounds, type SelectionOptions, type ZonePresentation, createGameHook, useMarqueeSelection };

package/dist/react.js

@@ -93,6 +93,165 @@ import {
   createContext,
   useContext
 } from "react";
+
+// src/headless/drop-snap.ts
+var SNAP = Object.freeze({
+  /** A pile catches a card whose centre comes this close to its own. */
+  slotCatch: 0.75,
+  /** A caught card leaves the pile beyond this. */
+  slotRelease: 1.15,
+  /** A finger reaches this much further. */
+  coarseReach: 0.2,
+  /** Another pile takes a caught card only when this much closer. */
+  slotSwitch: 0.1,
+  /** A card enters a zone once this share of it covers the zone... */
+  zoneEnter: 0.35,
+  /** ...and leaves it once less than this share does. */
+  zoneLeave: 0.1,
+  /** How much a card in a pile still follows the pointer. */
+  slotGive: 0.15,
+  /** How much a card held inside a zone's edge follows the pointer beyond it. */
+  edgeGive: 0.25
+});
+var centerOf = (box) => ({
+  x: box.x + box.width / 2,
+  y: box.y + box.height / 2
+});
+var toward = (from, to, share) => ({
+  x: from.x + (to.x - from.x) * share,
+  y: from.y + (to.y - from.y) * share
+});
+var contains = (box, point) => point.x >= box.x && point.x <= box.x + box.width && point.y >= box.y && point.y <= box.y + box.height;
+function cover(card, box) {
+  const width = Math.min(card.x + card.width, box.x + box.width) - Math.max(card.x, box.x);
+  const height = Math.min(card.y + card.height, box.y + box.height) - Math.max(card.y, box.y);
+  return width > 0 && height > 0 ? width * height / (card.width * card.height) : 0;
+}
+function snapDrop({
+  pointer,
+  card,
+  areas,
+  hit,
+  retained,
+  coarse
+}) {
+  const free = centerOf(card);
+  const inSlot = (index, box) => ({
+    index,
+    center: toward(centerOf(box), free, SNAP.slotGive),
+    held: true
+  });
+  let best = -1;
+  let score = Infinity;
+  areas.forEach((area, index) => {
+    const box = area?.slot ? area.box : null;
+    if (!box?.width || !box.height) return;
+    const middle = centerOf(box);
+    const distance = Math.hypot(
+      (free.x - middle.x) / box.width,
+      (free.y - middle.y) / box.height
+    );
+    const kept2 = index === retained;
+    const reach = (kept2 ? SNAP.slotRelease : SNAP.slotCatch) + (coarse ? SNAP.coarseReach : 0);
+    const value = kept2 ? distance - SNAP.slotSwitch : distance;
+    if (distance <= reach && value < score) {
+      best = index;
+      score = value;
+    }
+  });
+  if (best >= 0) return inSlot(best, areas[best].box);
+  const under = hit >= 0 ? areas[hit] : null;
+  if (under)
+    return under.slot && under.box?.width ? inSlot(hit, under.box) : { index: hit, center: free, held: false };
+  const hold = (index, box) => {
+    if (contains(box, pointer)) return { index, center: free, held: false };
+    const inside = {
+      x: Math.max(box.x, Math.min(free.x, box.x + box.width)),
+      y: Math.max(box.y, Math.min(free.y, box.y + box.height))
+    };
+    return { index, center: toward(inside, free, SNAP.edgeGive), held: true };
+  };
+  const zone = (index) => {
+    const area = areas[index];
+    return area && !area.slot && area.box?.width ? area.box : null;
+  };
+  const kept = retained >= 0 ? zone(retained) : null;
+  if (kept && (cover(card, kept) >= SNAP.zoneLeave || magneticDropPoint(pointer, kept, true, coarse)))
+    return hold(retained, kept);
+  let chosen = -1;
+  let share = 0;
+  areas.forEach((_, index) => {
+    const box = zone(index);
+    if (!box) return;
+    const value = cover(card, box);
+    if (value < SNAP.zoneEnter && !magneticDropPoint(pointer, box, false, coarse))
+      return;
+    const deeper = chosen < 0 || areas[index].depth > areas[chosen].depth;
+    if (deeper || areas[index].depth === areas[chosen].depth && value > share) {
+      chosen = index;
+      share = value;
+    }
+  });
+  return chosen >= 0 ? hold(chosen, zone(chosen)) : { index: -1, center: free, held: false };
+}
+
+// src/react/gesture.tsx
+var UNFIT = Object.freeze({
+  scale: null,
+  snapped: false,
+  concealed: false
+});
+var CATCH_UP_MS = 50;
+var SCROLL_EDGE = { fine: 48, coarse: 64 };
+var SCROLL_SPEED = 16;
+var VISUALLY_HIDDEN = {
+  position: "fixed",
+  width: "1px",
+  height: "1px",
+  overflow: "hidden",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap"
+};
+function landingIn(area) {
+  for (const element of area?.querySelectorAll("[data-drop-landing]") ?? [])
+    if (element instanceof HTMLElement && element.closest("[data-drop-area]") === area)
+      return element;
+  return null;
+}
+function visibleBox(element, clips) {
+  let { left, top, right, bottom } = element.getBoundingClientRect();
+  for (const clip of clips) {
+    const box = clip.getBoundingClientRect();
+    left = Math.max(left, box.left);
+    top = Math.max(top, box.top);
+    right = Math.min(right, box.right);
+    bottom = Math.min(bottom, box.bottom);
+  }
+  return right > left && bottom > top ? { x: left, y: top, width: right - left, height: bottom - top } : null;
+}
+function scrollStep(node, at, edge, frames) {
+  const root = node === document.scrollingElement;
+  const { overflowX, overflowY } = getComputedStyle(node);
+  const box = root ? { left: 0, top: 0, right: innerWidth, bottom: innerHeight } : node.getBoundingClientRect();
+  const speed = (gap) => gap < edge ? SCROLL_SPEED * frames * (1 - Math.max(0, gap) / edge) ** 2 : 0;
+  const axis = (overflow, position, room, before, after) => (root || overflow === "auto" || overflow === "scroll") && room > 0 ? (position < room ? speed(after) : 0) - (position > 0 ? speed(before) : 0) : 0;
+  return {
+    x: axis(
+      overflowX,
+      node.scrollLeft,
+      node.scrollWidth - node.clientWidth,
+      at.x - box.left,
+      box.right - at.x
+    ),
+    y: axis(
+      overflowY,
+      node.scrollTop,
+      node.scrollHeight - node.clientHeight,
+      at.y - box.top,
+      box.bottom - at.y
+    )
+  };
+}
 var CARD_STYLE = Object.freeze({
   // Sideways movement stays native scrolling; everything else reaches the recognizer.
   touchAction: "pan-x",
@@ -152,6 +311,18 @@ function createGestureSession(game) {
   let domFocused = null;
   let alt = false;
   let pointer = { x: 0, y: 0 };
+  let goal = { x: 0, y: 0 };
+  let offset = { x: 0, y: 0 };
+  let lag = { x: 0, y: 0 };
+  let shown = { x: 0, y: 0 };
+  let held = false;
+  let reduced = false;
+  let frame = 0;
+  let lastFrame = 0;
+  let remeasure = false;
+  const located = /* @__PURE__ */ new Map();
+  const engaged = /* @__PURE__ */ new Set();
+  let announcer = null;
   let swallowing = false;
   let guardingClicks = false;
   let disposed = false;
@@ -209,57 +380,174 @@ function createGestureSession(game) {
     if (drag?.settling && (game.request === null || changedSnapshot || changedLifetime))
       set({ drag: null });
   });
-  function hitArea(at) {
+  function hitAreas(at) {
     for (const element of document.elementsFromPoint(at.x, at.y)) {
       if (element.closest("[data-drag-overlay]")) continue;
-      const area = element.closest("[data-drop-area]");
-      if (area) return area.getAttribute("data-drop-area");
+      const ids = [];
+      for (let area = element.closest("[data-drop-area]"); area; area = area.parentElement?.closest("[data-drop-area]") ?? null)
+        ids.push(area.getAttribute("data-drop-area"));
+      if (ids.length) return ids;
     }
-    return null;
+    return [];
   }
-  function retarget(at) {
-    if (!press?.dragging) return at;
-    let area = hitArea(at);
-    const read = area === null ? void 0 : areas.get(area);
-    let target = read ? resolveDropArea(game.drag, read(at)) : null;
-    let point = at;
-    if (!target) {
-      const candidates = [...areas].sort(
-        ([left], [right]) => left === press?.area ? -1 : right === press?.area ? 1 : 0
-      );
-      let distance = Infinity;
-      for (const [id2, binding] of candidates) {
-        const resolved = resolveDropArea(game.drag, binding(at));
-        if (!resolved || !game.drag?.getDropTargets().some((item) => sameDropTarget(item, resolved)))
-          continue;
-        const element = document.querySelector(
-          `[data-drop-area="${CSS.escape(id2)}"]`
-        );
-        if (!(element instanceof HTMLElement)) continue;
-        const snapped = magneticDropPoint(
-          at,
-          element.getBoundingClientRect(),
-          id2 === press.area,
-          press.pointerType === "touch"
-        );
-        if (!snapped) continue;
-        const nextDistance = Math.hypot(at.x - snapped.x, at.y - snapped.y);
-        if (nextDistance >= distance) continue;
-        area = id2;
-        target = resolved;
-        point = snapped;
-        distance = nextDistance;
-        if (id2 === press.area) break;
-      }
+  function locate(id2) {
+    const known = located.get(id2);
+    const element = known?.element?.isConnected ? known.element : document.querySelector(`[data-drop-area="${CSS.escape(id2)}"]`);
+    const landing = landingIn(element);
+    const slot = landing?.dataset.dropLanding === "slot" ? landing : null;
+    if (known && known.element === element && known.slot === slot) return known;
+    const clips = [];
+    for (let node = (slot ?? element)?.parentElement; node; node = node.parentElement) {
+      const { overflowX, overflowY } = getComputedStyle(node);
+      if (/auto|scroll|hidden|clip/.test(overflowX + overflowY))
+        clips.push(node);
+    }
+    let depth = 0;
+    for (let node = element?.parentElement; node; node = node.parentElement) {
+      if (node.hasAttribute("data-drop-area")) depth++;
+    }
+    const next = {
+      element,
+      clips,
+      slot,
+      depth
+    };
+    located.set(id2, next);
+    return next;
+  }
+  function destinationOf(area, target) {
+    const areaPresentation = area ? presentations.get(area)?.() : void 0;
+    const position = target?.kind === "position" ? target.value : null;
+    const zone = position ?? areaPresentation?.zone;
+    const presentation = zone ? [
+      areaPresentation,
+      ...Array.from(presentations.values(), (read) => read())
+    ].find(
+      (candidate) => candidate?.zone.zoneId === zone.zoneId && candidate.zone.hostId === zone.hostId
+    ) : void 0;
+    return { zone, position, presentation };
+  }
+  const conceals = (presentation, hostId) => presentation.visibility === "hidden" || presentation.visibility === "ownerOnly" && hostId !== game.me?.id;
+  function announce(area) {
+    const element = area === null ? null : locate(area).element;
+    const label = element?.getAttribute("aria-label") ?? element?.getAttribute("aria-labelledby")?.split(/\s+/).map((labelId) => document.getElementById(labelId)?.textContent).join(" ") ?? "";
+    if (!announcer?.isConnected) {
+      announcer = document.createElement("div");
+      announcer.setAttribute("role", "status");
+      Object.assign(announcer.style, VISUALLY_HIDDEN);
+      document.body.append(announcer);
     }
-    if (area !== press.area || !sameDropTarget(target, press.target)) {
+    announcer.textContent = label;
+  }
+  function retarget(at) {
+    const drag = store.get().drag;
+    if (!press?.dragging || !drag) return;
+    pointer = at;
+    const ids = [...areas.keys()];
+    const found = ids.map((id2) => {
+      const target2 = resolveDropArea(game.drag, areas.get(id2)(at));
+      if (!target2) return null;
+      const { element, clips, slot, depth } = locate(id2);
+      const box = element instanceof HTMLElement ? visibleBox(slot ?? element, clips) : null;
+      return { target: target2, box, slot: slot !== null, depth };
+    });
+    const pickup = drag.width > 0 && drag.size.width > 0 ? drag.size.width / drag.width : 1;
+    const ratio = drag.fit.scale === null ? 1 : drag.fit.scale / pickup;
+    const width = drag.size.width * ratio;
+    const height = drag.size.height * ratio;
+    const free = {
+      x: at.x - (drag.grab.x - drag.size.width / 2) * ratio,
+      y: at.y - (drag.grab.y - drag.size.height / 2) * ratio
+    };
+    const snap = snapDrop({
+      pointer: at,
+      card: { x: free.x - width / 2, y: free.y - height / 2, width, height },
+      areas: found,
+      hit: ids.indexOf(hitAreas(at).find((id2) => found[ids.indexOf(id2)]) ?? ""),
+      retained: press.area === null ? -1 : ids.indexOf(press.area),
+      coarse: press.pointerType === "touch"
+    });
+    const area = snap.index < 0 ? null : ids[snap.index];
+    const target = snap.index < 0 ? null : found[snap.index].target;
+    const changed = area !== press.area || !sameDropTarget(target, press.target);
+    if (changed) {
       press.area = area;
       press.target = target;
       game.drag?.setDropTarget(target);
-      const drag = store.get().drag;
-      if (drag) set({ drag: { ...drag, area, target } });
+      announce(area);
+      remeasure = true;
     }
-    return point;
+    const { zone, presentation } = destinationOf(area, target);
+    const place = area === null ? null : locate(area);
+    const landing = place && (place.slot ?? landingIn(place.element));
+    const fit = {
+      scale: landing && drag.width > 0 ? landing.offsetWidth / drag.width : drag.fit.scale,
+      snapped: snap.held && !!found[snap.index]?.slot,
+      concealed: !!presentation && !!zone && conceals(presentation, zone.hostId)
+    };
+    const refit = Math.abs((fit.scale ?? 0) - (drag.fit.scale ?? 0)) > 0.01 || fit.snapped !== drag.fit.snapped || fit.concealed !== drag.fit.concealed;
+    if (changed || refit)
+      set({
+        drag: {
+          ...drag,
+          area,
+          target,
+          fit: refit ? fit : drag.fit
+        }
+      });
+    draw(snap.center, changed || refit || snap.held !== held);
+    held = snap.held;
+    schedule();
+  }
+  function draw(next, jump) {
+    const nextOffset = { x: next.x - pointer.x, y: next.y - pointer.y };
+    if (jump && !reduced)
+      lag = {
+        x: lag.x + offset.x - nextOffset.x,
+        y: lag.y + offset.y - nextOffset.y
+      };
+    offset = nextOffset;
+    goal = next;
+    show();
+    if (lag.x || lag.y) schedule();
+  }
+  function show() {
+    shown = { x: goal.x + lag.x, y: goal.y + lag.y };
+    for (const follow of followers) follow(shown);
+  }
+  function schedule() {
+    if (frame || disposed) return;
+    lastFrame = performance.now();
+    frame = requestAnimationFrame(tick);
+  }
+  function tick(now) {
+    frame = 0;
+    if (!store.get().drag) return;
+    const elapsed = Math.min(64, Math.max(0, now - lastFrame));
+    const decay = Math.exp(-elapsed / CATCH_UP_MS);
+    lag = Math.hypot(lag.x, lag.y) * decay < 0.5 ? { x: 0, y: 0 } : { x: lag.x * decay, y: lag.y * decay };
+    const scrolling = press?.dragging ? autoScroll(elapsed / 16.7) : false;
+    if (scrolling || remeasure) {
+      remeasure = false;
+      retarget(pointer);
+    } else show();
+    if (lag.x || lag.y || scrolling) schedule();
+  }
+  function autoScroll(frames) {
+    const edge = SCROLL_EDGE[press?.pointerType === "touch" ? "coarse" : "fine"];
+    const top = document.elementsFromPoint(pointer.x, pointer.y).find((element) => !element.closest("[data-drag-overlay]"));
+    for (let node = top ?? null; node; node = node.parentElement) {
+      const step = scrollStep(node, pointer, edge, frames);
+      if (!step.x && !step.y) {
+        if (node.scrollHeight > node.clientHeight || node.scrollWidth > node.clientWidth)
+          engaged.add(node);
+        continue;
+      }
+      if (!engaged.has(node)) return false;
+      node.scrollBy(step.x, step.y);
+      return true;
+    }
+    return false;
   }
   function swallow(event) {
     if (!swallowing || event.detail === 0) return;
@@ -386,12 +674,26 @@ function createGestureSession(game) {
           clearHover();
           focused = null;
           press.dragging = true;
+          located.clear();
+          engaged.clear();
+          if (announcer) announcer.textContent = "";
+          reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
+          held = false;
+          remeasure = false;
+          lag = { x: 0, y: 0 };
+          goal = shown = {
+            x: box.left + box.width / 2,
+            y: box.top + box.height / 2
+          };
+          offset = { x: goal.x - origin.x, y: goal.y - origin.y };
           set({
             drag: {
               cardIds: game.drag?.active?.cardIds ?? [cardId2],
               cardId: cardId2,
               grab: { x: origin.x - box.left, y: origin.y - box.top },
               size: { width: box.width, height: box.height },
+              width: element2 instanceof HTMLElement ? element2.offsetWidth : 0,
+              fit: UNFIT,
               settling: false,
               area: null,
               target: null,
@@ -402,10 +704,7 @@ function createGestureSession(game) {
           });
           return true;
         },
-        dragMove(at) {
-          pointer = retarget(at);
-          for (const follow of followers) follow(pointer);
-        },
+        dragMove: retarget,
         browse: scrubTo,
         end(kind, at) {
           const dragging = press.dragging;
@@ -423,15 +722,10 @@ function createGestureSession(game) {
           }
           const before = game.request;
           const drag = store.get().drag;
-          const areaPresentation = drag?.area ? presentations.get(drag.area)?.() : void 0;
-          const position = drag?.target?.kind === "position" ? drag.target.value : null;
-          const zone = position ?? areaPresentation?.zone;
-          const presentation = zone ? [
-            areaPresentation,
-            ...Array.from(presentations.values(), (read) => read())
-          ].find(
-            (candidate) => candidate?.zone.zoneId === zone.zoneId && candidate.zone.hostId === zone.hostId
-          ) : void 0;
+          const { zone, position, presentation } = destinationOf(
+            drag?.area ?? null,
+            drag?.target ?? null
+          );
           const destination = zone && game.zones.find(zone.zoneId, zone.hostId);
           const cards = drag?.cardIds.flatMap((id2) => {
             const card2 = game.cards.find(id2);
@@ -441,7 +735,7 @@ function createGestureSession(game) {
             zoneId: zone.zoneId,
             hostId: zone.hostId,
             index: position?.index ?? presentation?.index ?? destination.getCards().length,
-            concealed: presentation ? presentation.visibility === "hidden" || presentation.visibility === "ownerOnly" && zone.hostId !== game.me?.id : cards.some(
+            concealed: presentation ? conceals(presentation, zone.hostId) : cards.some(
               (card2) => card2.zone !== zone.zoneId || card2.hostId !== zone.hostId || card2.hidden
             ),
             cards: Object.freeze(cards),
@@ -542,11 +836,11 @@ function createGestureSession(game) {
       width: px(drag.size.width),
       height: px(drag.size.height)
     });
-    const follow = (at) => {
-      element.style.left = px(at.x - drag.grab.x);
-      element.style.top = px(at.y - drag.grab.y);
+    const follow = (center) => {
+      element.style.left = px(center.x - drag.size.width / 2);
+      element.style.top = px(center.y - drag.size.height / 2);
     };
-    follow(pointer);
+    follow(shown);
     followers.add(follow);
     return () => {
       followers.delete(follow);
@@ -630,6 +924,8 @@ function createGestureSession(game) {
     dispose() {
       disposed = true;
       press?.recognizer.cancel();
+      cancelAnimationFrame(frame);
+      announcer?.remove();
       clearHover();
       removeEventListener("keydown", key);
       removeEventListener("keyup", key);
@@ -990,6 +1286,7 @@ function createGameHook() {
           hostId: drag.landing.hostId,
           index: drag.landing.index
         } : null,
+        fit: drag.fit,
         ref: session.overlayRef
       } : null;
     }