@dreamboard-games/sdk 0.5.0-alpha.11 → 0.5.0-alpha.13

package/dist/react.d.ts

@@ -1,23 +1,23 @@
 import * as react from 'react';
-import { PointerEvent, MouseEvent, DragEvent, CSSProperties, ReactNode } from 'react';
-import { a4 as TargetOptions, a1 as SeatCardId, q as Features, E as InstanceOptions, n as CoreInstance, p as FeatureContext, G as GameInstance, r as GameSnapshot, o as DropTarget } from './model-BeslAXVA.js';
+import { PointerEvent, FocusEvent, MouseEvent, DragEvent, CSSProperties, ReactNode } from 'react';
+import { aa as TargetOptions, a1 as SeatCardId, q as Features, E as InstanceOptions, n as CoreInstance, p as FeatureContext, G as GameInstance, r as GameSnapshot, a5 as ShortcutOptions, a6 as ShortcutTarget, a4 as ShortcutHint, o as DropTarget } from './shortcuts-Chlx8o7p.js';
 import { G as GameSource } from './types-Xg_RxV1n.js';
+import '@tanstack/store';
 import './extract-DgzrJ5el.js';
 import 'zod';
 import 'honeycomb-grid';
-import '@tanstack/store';
 
 interface CardGestureProps {
     onPointerDown(event: PointerEvent<Element>): void;
-    onPointerEnter(event: PointerEvent<Element>): void;
-    onPointerLeave(event: PointerEvent<Element>): void;
-    onFocus(): void;
+    onFocus(event: FocusEvent<Element>): void;
     onBlur(): void;
     onContextMenu(event: MouseEvent<Element>): void;
     onDragStart(event: DragEvent<Element>): void;
     readonly style: CSSProperties;
     readonly "data-dragging"?: true;
     readonly "data-inspecting"?: "hold" | "hover";
+    readonly "data-card-gesture": string;
+    readonly "data-gesture-session": string;
 }
 
 interface SelectionOptions<Value> {
@@ -36,6 +36,7 @@ interface CardGesture {
     readonly props: CardGestureProps;
     readonly canDrag: boolean;
     readonly isDragging: boolean;
+    readonly isActive: boolean;
     /** Held on touch, or rested on with a mouse. */
     readonly inspecting: "hold" | "hover" | null;
 }
@@ -73,6 +74,21 @@ declare function createGameHook<Game, Source extends GameSource = GameSource>():
         children: (value: Value) => ReactNode;
     }) => ReactNode;
     useCardGesture: (cardId: SeatCardId<Game>, options: CardGestureOptions<Game>) => CardGesture;
+    useActiveCard: () => SeatCardId<Game> | null;
+    useGameShortcuts: (options: ShortcutOptions<Game>) => {
+        readonly target: ShortcutTarget<Game> | null;
+        readonly hints: readonly ShortcutHint<Game>[];
+    };
+    useShortcutTarget: (target: ShortcutTarget<Game>) => {
+        props: {
+            "data-shortcut-target": string;
+            "data-gesture-session": string;
+            onPointerDown(event: react.PointerEvent<Element>): void;
+            onFocus(event: react.FocusEvent<Element>): void;
+            onBlur(): void;
+        };
+    };
+    useShortcutHints: (target: ShortcutTarget<Game> | null) => readonly ShortcutHint<Game>[];
     useDropArea: (binding: DropTarget<Game> | DropAreaBinding<Game> | null) => DropArea;
     useDragOverlay: () => DragOverlay<Game> | null;
 };

package/dist/react.js

@@ -3,8 +3,76 @@ import {
   createGestureRecognizer,
   isSameDropTarget,
   magneticDropPoint
-} from "./chunk-2IGXAYW4.js";
-import "./chunk-ES74C2IN.js";
+} from "./chunk-W5G6VMMQ.js";
+import {
+  inputValueKey
+} from "./chunk-ES74C2IN.js";
+
+// src/react/create-game-hook.tsx
+import { createStore as createStore2 } from "@tanstack/store";
+
+// src/react/shortcuts.ts
+import { useLayoutEffect, useRef } from "react";
+function canHandle(event) {
+  const target = event.target;
+  return !event.defaultPrevented && !event.repeat && !event.isComposing && !event.altKey && !event.ctrlKey && !event.metaKey && !event.shiftKey && !(target instanceof Element && target.closest(
+    "input, textarea, select, [contenteditable]:not([contenteditable='false']), [role='textbox']"
+  )) && !Array.from(
+    document.querySelectorAll(
+      "[aria-modal='true'], dialog[open], [role='dialog'], [role='menu'], [role='listbox']"
+    )
+  ).some(
+    (surface) => !surface.closest("[aria-hidden='true']") && surface.checkVisibility({
+      visibilityProperty: true,
+      opacityProperty: true
+    })
+  );
+}
+function useShortcutsAdapter(game, controller, session, options, onResult) {
+  const latest = useRef({ options, onResult });
+  const registration = useRef(null);
+  useLayoutEffect(() => {
+    latest.current = { options, onResult };
+  });
+  useLayoutEffect(() => {
+    let mounted = true;
+    const owned = controller.register(latest.current.options);
+    registration.current = owned;
+    function keydown(event) {
+      if (!canHandle(event)) return;
+      const source = game.getOptions().source;
+      const seat = game.snapshot?.me;
+      const active = () => mounted && game.getOptions().source === source && game.snapshot?.me === seat;
+      const pending = controller.handle(
+        event.key,
+        session.getActiveTarget()
+      );
+      if (!pending) return;
+      event.preventDefault();
+      void pending.then(
+        (result) => {
+          if (active()) latest.current.onResult(result);
+        },
+        (cause) => {
+          if (active())
+            latest.current.onResult(
+              cause instanceof Error ? cause : new Error(String(cause))
+            );
+        }
+      );
+    }
+    window.addEventListener("keydown", keydown);
+    return () => {
+      mounted = false;
+      window.removeEventListener("keydown", keydown);
+      registration.current = null;
+      owned.dispose();
+    };
+  }, [game, controller, session]);
+  useLayoutEffect(() => {
+    registration.current?.update(options);
+  });
+}
 
 // src/react/gesture.tsx
 import { createStore } from "@tanstack/store";
@@ -38,11 +106,18 @@ var sameDropTarget = (left, right) => left === right || !!left && !!right && isS
 var sessions = 0;
 function createGestureSession(game) {
   const id = `g${++sessions}`;
-  const store = createStore({ drag: null, inspect: null });
+  const store = createStore({
+    activeTarget: null,
+    drag: null,
+    inspect: null
+  });
+  const targets = /* @__PURE__ */ new Map();
+  const sameTarget = (left, right) => inputValueKey(left) === inputValueKey(right);
   const areas = /* @__PURE__ */ new Map();
   const followers = /* @__PURE__ */ new Set();
   let press = null;
   let hover = null;
+  let hoverPoint = null;
   let focused = null;
   let alt = false;
   let pointer = { x: 0, y: 0 };
@@ -51,12 +126,34 @@ function createGestureSession(game) {
   let disposed = false;
   const set = (patch) => store.setState((previous) => ({ ...previous, ...patch }));
   let snapshot = game.snapshot;
+  let source = game.getOptions().source;
+  function admitted(target) {
+    if (!target || !game.snapshot) return null;
+    const zones = game.snapshot.frame.zones;
+    if (target.kind === "zone")
+      return zones[target.zoneId]?.[target.hostId] ? target : null;
+    if (target.kind === "card")
+      return Object.entries(snapshot?.frame.zones ?? {}).some(
+        ([zoneId, hosts]) => Object.entries(hosts).some(
+          ([hostId, zone]) => zone.cardIds.includes(target.value) && zones[zoneId]?.[hostId]?.cardIds.includes(target.value)
+        )
+      ) ? target : null;
+    return [...targets.values()].some((read) => sameTarget(read(), target)) ? target : null;
+  }
   const unsubscribe = game.subscribe(() => {
-    if (snapshot !== game.snapshot) {
+    const nextSource = game.getOptions().source;
+    const changedLifetime = source !== nextSource || snapshot?.me !== game.snapshot?.me;
+    if (changedLifetime || snapshot !== game.snapshot) {
+      const nextHover = changedLifetime ? null : admitted(hover);
+      const nextFocused = changedLifetime ? null : admitted(focused);
+      source = nextSource;
       snapshot = game.snapshot;
       press?.recognizer.cancel();
       alt = false;
-      set({ inspect: null });
+      hover = nextHover;
+      focused = nextFocused;
+      if (changedLifetime) hoverPoint = null;
+      set({ activeTarget: hover ?? focused, inspect: null });
     }
     if (press?.dragging && !game.drag?.active) press.recognizer.cancel();
     const drag = store.get().drag;
@@ -132,9 +229,33 @@ function createGestureSession(game) {
     hover = null;
   }
   function inspectWithAlt() {
-    const cardId = hover ?? focused;
-    set({ inspect: alt && cardId && !press ? { cardId, via: "hover" } : null });
+    const target = hover ?? focused;
+    const cardId = target?.kind === "card" ? target.value : null;
+    set({
+      activeTarget: target,
+      inspect: alt && cardId && !press ? { cardId, via: "hover" } : null
+    });
+  }
+  function hoverAt(at) {
+    hoverPoint = at;
+    const wasFocused = focused !== null;
+    focused = null;
+    const hit = document.elementFromPoint(at.x, at.y)?.closest("[data-card-gesture], [data-shortcut-target]");
+    const control = hit?.getAttribute("data-gesture-session") === id ? hit : null;
+    const targetId = control?.getAttribute("data-shortcut-target");
+    const cardId = control?.getAttribute("data-card-gesture");
+    const next = targetId ? targets.get(targetId)?.() ?? null : cardId ? { kind: "card", value: cardId } : null;
+    if (sameTarget(hover, next) && !wasFocused) return;
+    hover = next;
+    inspectWithAlt();
   }
+  const browse = (event) => {
+    if (event.pointerType !== "mouse" || press) return;
+    if (hoverPoint?.x === event.clientX && hoverPoint.y === event.clientY)
+      return;
+    alt = event.altKey;
+    hoverAt({ x: event.clientX, y: event.clientY });
+  };
   const key = (event) => {
     if (event.key === "Escape") {
       press?.recognizer.cancel();
@@ -148,12 +269,23 @@ function createGestureSession(game) {
   const loseFocus = () => {
     alt = false;
     clearHover();
+    hoverPoint = null;
     focused = null;
-    set({ inspect: null });
+    set({ activeTarget: null, inspect: null });
   };
   addEventListener("keydown", key);
   addEventListener("keyup", key);
   addEventListener("blur", loseFocus);
+  const leaveWindow = (event) => {
+    if (event.pointerType !== "mouse" || event.relatedTarget !== null) return;
+    clearHover();
+    hoverPoint = null;
+    focused = null;
+    alt = false;
+    inspectWithAlt();
+  };
+  addEventListener("pointermove", browse);
+  addEventListener("pointerout", leaveWindow);
   function release() {
     press?.detach();
     press = null;
@@ -169,6 +301,7 @@ function createGestureSession(game) {
           return false;
         const box = element.getBoundingClientRect();
         clearHover();
+        focused = null;
         press.dragging = true;
         set({
           drag: {
@@ -177,7 +310,8 @@ function createGestureSession(game) {
             size: { width: box.width, height: box.height },
             settling: false
           },
-          inspect: null
+          inspect: null,
+          activeTarget: null
         });
         return true;
       },
@@ -187,11 +321,15 @@ function createGestureSession(game) {
       },
       end(kind, at) {
         const dragging = press.dragging;
+        const pointerType = press.pointerType;
         if (dragging) retarget(at);
         release();
         if (kind !== "tap") swallowNextClick();
         if (kind === "hold") set({ inspect: null });
-        if (!dragging) return;
+        if (!dragging) {
+          if (kind === "browse" && pointerType === "mouse") hoverAt(at);
+          return;
+        }
         const before = game.request;
         game.drag?.drop();
         const drag = store.get().drag;
@@ -240,24 +378,22 @@ function createGestureSession(game) {
   }
   function cardProps(cardId, options, flags) {
     return {
-      onPointerDown: (event) => start(event.nativeEvent, cardId, event.currentTarget, options),
-      onPointerEnter(event) {
-        if (event.pointerType !== "mouse" || press?.dragging) return;
-        clearHover();
-        hover = cardId;
-        alt = event.altKey;
-        inspectWithAlt();
-      },
-      onPointerLeave() {
-        if (hover === cardId) clearHover();
-        inspectWithAlt();
+      onPointerDown(event) {
+        if (event.pointerType === "mouse") {
+          hover = { kind: "card", value: cardId };
+          alt = event.altKey;
+          inspectWithAlt();
+        }
+        start(event.nativeEvent, cardId, event.currentTarget, options);
       },
-      onFocus() {
-        focused = cardId;
+      onFocus(event) {
+        focused = event.currentTarget.matches(":focus-visible") ? { kind: "card", value: cardId } : null;
+        if (focused) hover = null;
         inspectWithAlt();
       },
       onBlur() {
-        if (focused === cardId) focused = null;
+        if (focused?.kind === "card" && focused.value === cardId)
+          focused = null;
         inspectWithAlt();
       },
       onContextMenu(event) {
@@ -267,7 +403,9 @@ function createGestureSession(game) {
       onDragStart: (event) => event.preventDefault(),
       style: options === false ? INSPECTION_STYLE : CARD_STYLE,
       "data-dragging": flags.dragging || void 0,
-      "data-inspecting": flags.inspecting ?? void 0
+      "data-inspecting": flags.inspecting ?? void 0,
+      "data-card-gesture": cardId,
+      "data-gesture-session": id
     };
   }
   function overlayRef(element) {
@@ -295,6 +433,43 @@ function createGestureSession(game) {
     id,
     store,
     cardProps,
+    getActiveCardId() {
+      const target = store.get().activeTarget;
+      return target?.kind === "card" ? target.value : null;
+    },
+    getActiveTarget: () => store.get().activeTarget,
+    registerTarget(targetId, read) {
+      const target = read();
+      targets.set(targetId, read);
+      return () => {
+        targets.delete(targetId);
+        if (sameTarget(hover, target)) hover = null;
+        if (sameTarget(focused, target)) focused = null;
+        inspectWithAlt();
+      };
+    },
+    targetProps(targetId) {
+      return {
+        "data-shortcut-target": targetId,
+        "data-gesture-session": id,
+        onPointerDown(event) {
+          if (event.pointerType !== "mouse") return;
+          hover = targets.get(targetId)?.() ?? null;
+          alt = event.altKey;
+          inspectWithAlt();
+        },
+        onFocus(event) {
+          focused = event.currentTarget.matches(":focus-visible") ? targets.get(targetId)?.() ?? null : null;
+          if (focused) hover = null;
+          inspectWithAlt();
+        },
+        onBlur() {
+          const target = targets.get(targetId)?.() ?? null;
+          if (sameTarget(focused, target)) focused = null;
+          inspectWithAlt();
+        }
+      };
+    },
     overlayRef,
     /** `read` returns the area's current binding; targets resolve when hit. */
     registerArea(area, read) {
@@ -310,8 +485,11 @@ function createGestureSession(game) {
       removeEventListener("keydown", key);
       removeEventListener("keyup", key);
       removeEventListener("blur", loseFocus);
+      removeEventListener("pointermove", browse);
+      removeEventListener("pointerout", leaveWindow);
       unsubscribe();
       followers.clear();
+      targets.clear();
       if (!guardingClicks) return;
       removeEventListener("click", swallow, true);
       removeEventListener("pointerdown", newPress, true);
@@ -333,8 +511,8 @@ import {
   createContext as createContext2,
   useContext as useContext2,
   useId,
-  useLayoutEffect,
-  useRef,
+  useLayoutEffect as useLayoutEffect2,
+  useRef as useRef2,
   useState
 } from "react";
 import { useSelector as useSelector2 } from "@tanstack/react-store";
@@ -344,12 +522,12 @@ function createGameHook() {
     const Context = createContext2(null);
     function GameProvider({ children, ...overrides }) {
       const [owned, setOwned] = useState(null);
-      const lifetime = useRef(null);
+      const lifetime = useRef2(null);
       const options = {
         ...defaults,
         ...overrides
       };
-      useLayoutEffect(() => {
+      useLayoutEffect2(() => {
         let current = lifetime.current;
         if (!current) {
           const instance = createGameInstance()(options);
@@ -373,7 +551,7 @@ function createGameHook() {
           });
         };
       }, []);
-      useLayoutEffect(() => {
+      useLayoutEffect2(() => {
         lifetime.current?.instance.setOptions(options);
       });
       return owned ? /* @__PURE__ */ jsx(Context.Provider, { value: owned.instance, children: /* @__PURE__ */ jsx(GestureContext.Provider, { value: owned.session, children }) }) : null;
@@ -416,10 +594,15 @@ function createGameHook() {
         session,
         (state) => state.inspect?.cardId === cardId ? state.inspect.via : null
       );
+      const isActive = useGestureState(
+        session,
+        (state) => state.activeTarget?.kind === "card" && state.activeTarget.value === cardId
+      );
       return {
         props: session.cardProps(cardId, routes, { dragging, inspecting }),
         canDrag,
         isDragging: dragging,
+        isActive,
         inspecting
       };
     }
@@ -435,11 +618,11 @@ function createGameHook() {
         const active = dragOf(snapshot)?.active?.target;
         return !!target && sameDropTarget(active ?? null, target);
       });
-      const latest = useRef(erased);
-      useLayoutEffect(() => {
+      const latest = useRef2(erased);
+      useLayoutEffect2(() => {
         latest.current = erased;
       });
-      useLayoutEffect(
+      useLayoutEffect2(
         () => session.registerArea(id, () => latest.current),
         [session, id]
       );
@@ -453,6 +636,61 @@ function createGameHook() {
         isOver
       };
     }
+    const shortcutsOf = (snapshot) => snapshot.shortcuts;
+    const noShortcutsConfiguration = createStore2(
+      null
+    );
+    const sameHints = (left, right) => left.length === right.length && left.every((hint, index) => {
+      const next = right[index];
+      return hint.label === next.label && hint.interaction === next.interaction && hint.keys.length === next.keys.length && hint.keys.every((key, at) => key === next.keys[at]);
+    });
+    function useShortcutHints(target) {
+      const controller = shortcutsOf(useInstance());
+      useGame((snapshot) => shortcutsOf(snapshot)?.getHints(target) ?? [], {
+        compare: sameHints
+      });
+      return useSelector2(
+        controller?.configuration ?? noShortcutsConfiguration,
+        () => controller?.getHints(target) ?? [],
+        { compare: sameHints }
+      );
+    }
+    function useGameShortcuts(options) {
+      const instance = useInstance();
+      const session = useGestureSession();
+      const controller = shortcutsOf(instance);
+      if (!controller)
+        throw new Error(
+          "useGameShortcuts requires shortcutsFeature in the game binding."
+        );
+      useShortcutsAdapter(instance, controller, session, options, (result) => {
+        if (result instanceof Error) instance.getOptions().onError?.(result);
+        else if (!result.accepted)
+          instance.getOptions().onError?.(
+            new Error(result.message ?? result.errorCode, { cause: result })
+          );
+      });
+      const target = useGestureState(
+        session,
+        (state) => state.activeTarget
+      );
+      const hints = useShortcutHints(target);
+      return { target, hints };
+    }
+    function useShortcutTarget(target) {
+      const session = useGestureSession();
+      const id = `${session.id}${useId()}`;
+      const latest = useRef2(target);
+      const targetKey = inputValueKey(target);
+      useLayoutEffect2(() => {
+        latest.current = target;
+      });
+      useLayoutEffect2(
+        () => session.registerTarget(id, () => latest.current),
+        [session, id, targetKey]
+      );
+      return { props: session.targetProps(id) };
+    }
     function useDragOverlay() {
       const session = useGestureSession();
       const drag = useGestureState(session, (state) => state.drag);
@@ -462,11 +700,22 @@ function createGameHook() {
         ref: session.overlayRef
       } : null;
     }
+    function useActiveCard() {
+      const session = useGestureSession();
+      return useGestureState(
+        session,
+        (state) => state.activeTarget?.kind === "card" ? state.activeTarget.value : null
+      );
+    }
     return {
       GameProvider,
       useGame,
       Subscribe,
       useCardGesture,
+      useActiveCard,
+      useGameShortcuts,
+      useShortcutTarget,
+      useShortcutHints,
       useDropArea,
       useDragOverlay
     };