@gridui/react-utils 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# React utils
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@gridui/react-utils` owns React interaction lifecycle hooks shared by independent
+component families. It depends on React and the React-free `@gridui/interaction`
+helpers. It has no stylesheet or Theme dependency.
+
+## Pointer drag
+
+`usePointerDrag<Data>(onCancel)` returns a stable `PointerDrag<Data>` controller.
+Each hook instance owns at most one session. Call its methods from events or
+effects; session changes do not trigger renders. Keep visible state in the owner.
+
+- `start(event, data)` accepts a primary, left-button pointer when no session is
+  active. It captures that pointer on `event.currentTarget`, records caller data,
+  and subscribes to Escape and blur on the element's owning window. It returns
+  whether it started; a native capture error propagates without creating a session.
+- `get(pointerId?)` returns the active caller data, or `null` for an absent or
+  different pointer. Treat the data as the drag's starting snapshot.
+- `finish(pointerId)` releases resources and returns that pointer's data without
+  invoking `onCancel`. The owner decides what to commit.
+- `cancel(pointerId?)` releases resources and invokes the latest committed
+  `onCancel(data)` once. Omitting the ID cancels whichever session is active.
+
+Wire `pointercancel` and `lostpointercapture` to `cancel(event.pointerId)`.
+Escape, window blur, and effect disconnection cancel automatically, including
+React Activity hiding retained content. Cleanup clears ownership before releasing
+capture and notifying the owner, so capture-loss events cannot cancel twice.
+The next drag can start after effects reconnect. IME-owned and already handled
+Escape events are ignored; active Escape is claimed before modal dismissal.
+
+The owner handles focus, preventDefault, touch-action styles, geometry, bounds,
+controlled state, preview, commit, and rollback. `Resizable` rolls back continuous
+size notifications on cancel; `BottomSheet` discards its preview and commits snap
+points only after `finish`. There is no shared cache, persistence, or product state.
+
+```tsx
+import { usePointerDrag } from "@gridui/react-utils";
+
+// Inside a component, where preview is caller-owned React state:
+const drag = usePointerDrag<{ startY: number }>(() => setPreview(null));
+// Pointer down: drag.start(event, { startY: event.clientY });
+// Pointer move: const start = drag.get(event.pointerId);
+// Pointer up: if (drag.finish(event.pointerId)) commitPreview();
+// Pointer cancel / lost capture: drag.cancel(event.pointerId);
+```
+
+## Release history
+
+Package-owned records live in [.changeset/history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-core/react-utils/.changeset/history).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @author WMXPY
+ * @package ReactUtils
+ * @namespace Root
+ * @description Index
+ */
+export type { PointerDrag, PointerDragStart } from "./pointer-drag";
+export { usePointerDrag } from "./use-pointer-drag";

package/dist/index.js

@@ -0,0 +1,73 @@
+// src/pointer-drag.ts
+import { listenForDragCancellation } from "@gridui/interaction";
+var createPointerDrag = (onCancel) => {
+  let active = null;
+  const get = (pointerId) => {
+    return active && (pointerId === void 0 || active.pointerId === pointerId) ? active.data : null;
+  };
+  const detach = (pointerId) => {
+    if (!active || pointerId !== void 0 && active.pointerId !== pointerId) {
+      return null;
+    }
+    const session = active;
+    active = null;
+    session.cleanup();
+    if (session.element.hasPointerCapture(session.pointerId)) {
+      session.element.releasePointerCapture(session.pointerId);
+    }
+    return session.data;
+  };
+  const cancel = (pointerId) => {
+    const data = detach(pointerId);
+    if (data) {
+      onCancel(data);
+    }
+  };
+  return {
+    get,
+    cancel,
+    finish: (pointerId) => {
+      return detach(pointerId);
+    },
+    start: (event, data) => {
+      if (active || event.button !== 0 || !event.isPrimary) {
+        return false;
+      }
+      const element = event.currentTarget;
+      element.setPointerCapture(event.pointerId);
+      active = {
+        pointerId: event.pointerId,
+        element,
+        data,
+        cleanup: listenForDragCancellation(element, () => {
+          cancel();
+        })
+      };
+      return true;
+    }
+  };
+};
+
+// src/use-pointer-drag.ts
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+var usePointerDrag = (onCancel) => {
+  const cancelRef = useRef(onCancel);
+  useLayoutEffect(() => {
+    cancelRef.current = onCancel;
+  });
+  const [drag] = useState(() => {
+    return createPointerDrag((data) => {
+      cancelRef.current(data);
+    });
+  });
+  useEffect(() => {
+    return () => {
+      drag.cancel();
+    };
+  }, [drag]);
+  return drag;
+};
+export {
+  usePointerDrag
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/pointer-drag.ts", "../src/use-pointer-drag.ts"],
+  "sourcesContent": ["/**\n * @author WMXPY\n * @package ReactUtils\n * @namespace Root\n * @description Pointer Drag\n */\n\nimport { listenForDragCancellation } from \"@gridui/interaction\";\nimport type { PointerEvent } from \"react\";\n\nexport type PointerDragStart = Pick<PointerEvent<HTMLElement>, \"button\" | \"isPrimary\" | \"pointerId\" | \"currentTarget\">;\n\nexport type PointerDrag<Data extends object> = {\n    readonly start: (event: PointerDragStart, data: Data) => boolean;\n    readonly get: (pointerId?: number) => Data | null;\n    readonly finish: (pointerId: number) => Data | null;\n    readonly cancel: (pointerId?: number) => void;\n};\n\ntype Session<Data> = {\n    readonly pointerId: number;\n    readonly element: HTMLElement;\n    readonly data: Data;\n    readonly cleanup: () => void;\n};\n\nexport const createPointerDrag = <Data extends object>(onCancel: (data: Data) => void): PointerDrag<Data> => {\n    let active: Session<Data> | null = null;\n    const get = (pointerId?: number) => {\n        return active && (pointerId === undefined || active.pointerId === pointerId) ? active.data : null;\n    };\n    const detach = (pointerId?: number) => {\n        if (!active || (pointerId !== undefined && active.pointerId !== pointerId)) {\n            return null;\n        }\n        const session = active;\n        active = null;\n        session.cleanup();\n        if (session.element.hasPointerCapture(session.pointerId)) {\n            session.element.releasePointerCapture(session.pointerId);\n        }\n        return session.data;\n    };\n    const cancel = (pointerId?: number) => {\n        const data = detach(pointerId);\n        if (data) {\n            onCancel(data);\n        }\n    };\n    return {\n        get,\n        cancel,\n        finish: (pointerId) => {\n            return detach(pointerId);\n        },\n        start: (event, data) => {\n            if (active || event.button !== 0 || !event.isPrimary) {\n                return false;\n            }\n            const element = event.currentTarget;\n            element.setPointerCapture(event.pointerId);\n            active = {\n                pointerId: event.pointerId,\n                element,\n                data,\n                cleanup: listenForDragCancellation(element, () => {\n                    cancel();\n                }),\n            };\n            return true;\n        },\n    };\n};\n", "/**\n * @author WMXPY\n * @package ReactUtils\n * @namespace Root\n * @description Use Pointer Drag\n */\n\nimport { createPointerDrag, type PointerDrag } from \"./pointer-drag\";\nimport { useEffect, useLayoutEffect, useRef, useState } from \"react\";\n\n/** Own one pointer session; the caller owns geometry, rendering, commit and rollback. */\nexport const usePointerDrag = <Data extends object>(onCancel: (data: Data) => void): PointerDrag<Data> => {\n    const cancelRef = useRef(onCancel);\n    useLayoutEffect(() => {\n        cancelRef.current = onCancel;\n    });\n    const [drag] = useState(() => {\n        return createPointerDrag<Data>((data) => {\n            cancelRef.current(data);\n        });\n    });\n    useEffect(() => {\n        return () => {\n            drag.cancel();\n        };\n    }, [drag]);\n    return drag;\n};\n"],
+  "mappings": ";AAOA,SAAS,iCAAiC;AAmBnC,IAAM,oBAAoB,CAAsB,aAAsD;AACzG,MAAI,SAA+B;AACnC,QAAM,MAAM,CAAC,cAAuB;AAChC,WAAO,WAAW,cAAc,UAAa,OAAO,cAAc,aAAa,OAAO,OAAO;AAAA,EACjG;AACA,QAAM,SAAS,CAAC,cAAuB;AACnC,QAAI,CAAC,UAAW,cAAc,UAAa,OAAO,cAAc,WAAY;AACxE,aAAO;AAAA,IACX;AACA,UAAM,UAAU;AAChB,aAAS;AACT,YAAQ,QAAQ;AAChB,QAAI,QAAQ,QAAQ,kBAAkB,QAAQ,SAAS,GAAG;AACtD,cAAQ,QAAQ,sBAAsB,QAAQ,SAAS;AAAA,IAC3D;AACA,WAAO,QAAQ;AAAA,EACnB;AACA,QAAM,SAAS,CAAC,cAAuB;AACnC,UAAM,OAAO,OAAO,SAAS;AAC7B,QAAI,MAAM;AACN,eAAS,IAAI;AAAA,IACjB;AAAA,EACJ;AACA,SAAO;AAAA,IACH;AAAA,IACA;AAAA,IACA,QAAQ,CAAC,cAAc;AACnB,aAAO,OAAO,SAAS;AAAA,IAC3B;AAAA,IACA,OAAO,CAAC,OAAO,SAAS;AACpB,UAAI,UAAU,MAAM,WAAW,KAAK,CAAC,MAAM,WAAW;AAClD,eAAO;AAAA,MACX;AACA,YAAM,UAAU,MAAM;AACtB,cAAQ,kBAAkB,MAAM,SAAS;AACzC,eAAS;AAAA,QACL,WAAW,MAAM;AAAA,QACjB;AAAA,QACA;AAAA,QACA,SAAS,0BAA0B,SAAS,MAAM;AAC9C,iBAAO;AAAA,QACX,CAAC;AAAA,MACL;AACA,aAAO;AAAA,IACX;AAAA,EACJ;AACJ;;;AChEA,SAAS,WAAW,iBAAiB,QAAQ,gBAAgB;AAGtD,IAAM,iBAAiB,CAAsB,aAAsD;AACtG,QAAM,YAAY,OAAO,QAAQ;AACjC,kBAAgB,MAAM;AAClB,cAAU,UAAU;AAAA,EACxB,CAAC;AACD,QAAM,CAAC,IAAI,IAAI,SAAS,MAAM;AAC1B,WAAO,kBAAwB,CAAC,SAAS;AACrC,gBAAU,QAAQ,IAAI;AAAA,IAC1B,CAAC;AAAA,EACL,CAAC;AACD,YAAU,MAAM;AACZ,WAAO,MAAM;AACT,WAAK,OAAO;AAAA,IAChB;AAAA,EACJ,GAAG,CAAC,IAAI,CAAC;AACT,SAAO;AACX;",
+  "names": []
+}

package/dist/pointer-drag.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @author WMXPY
+ * @package ReactUtils
+ * @namespace Root
+ * @description Pointer Drag
+ */
+import type { PointerEvent } from "react";
+export type PointerDragStart = Pick<PointerEvent<HTMLElement>, "button" | "isPrimary" | "pointerId" | "currentTarget">;
+export type PointerDrag<Data extends object> = {
+    readonly start: (event: PointerDragStart, data: Data) => boolean;
+    readonly get: (pointerId?: number) => Data | null;
+    readonly finish: (pointerId: number) => Data | null;
+    readonly cancel: (pointerId?: number) => void;
+};
+export declare const createPointerDrag: <Data extends object>(onCancel: (data: Data) => void) => PointerDrag<Data>;

package/dist/use-pointer-drag.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package ReactUtils
+ * @namespace Root
+ * @description Use Pointer Drag
+ */
+import { type PointerDrag } from "./pointer-drag";
+/** Own one pointer session; the caller owns geometry, rendering, commit and rollback. */
+export declare const usePointerDrag: <Data extends object>(onCancel: (data: Data) => void) => PointerDrag<Data>;

package/docs/catalog.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "name": "@gridui/react-utils",
+  "version": "1.0.0",
+  "category": "core",
+  "description": "Shared React interaction lifecycle hooks",
+  "usage": "`@gridui/react-utils` owns React interaction lifecycle hooks shared by independent component families. It depends on React and the React-free `@gridui/interaction` helpers. It has no stylesheet or Theme dependency.",
+  "documentation": [
+    "README.md"
+  ],
+  "exports": [
+    {
+      "name": "PointerDrag",
+      "kind": "type",
+      "importPath": "@gridui/react-utils"
+    },
+    {
+      "name": "PointerDragStart",
+      "kind": "type",
+      "importPath": "@gridui/react-utils"
+    },
+    {
+      "name": "usePointerDrag",
+      "kind": "function",
+      "importPath": "@gridui/react-utils"
+    }
+  ],
+  "styles": [],
+  "examples": [
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-core/react-utils/stories/getting-started.mdx",
+    "https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/packages-core/react-utils/stories/pointer-drag-lifecycle.mdx"
+  ]
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@gridui/react-utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Shared React interaction lifecycle hooks",
+  "license": "UNLICENSED",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@gridui/interaction": "^1.2.1"
+  },
+  "devDependencies": {
+    "@gridui-internal/configuration": "0.0.0-internal",
+    "@jest/globals": "30.5.2",
+    "@types/jest": "30.0.0",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jest": "30.5.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "scripts": {
+    "build": "node ../../scripts/compilation/package.ts",
+    "compile": "tsc --project tsconfig.json",
+    "test": "jest",
+    "coverage": "jest --coverage"
+  }
 }