@xsolla/xui-hooks 0.175.0

package/README.md

@@ -0,0 +1,38 @@
+# @xsolla/xui-hooks
+
+Shared React hooks for the XUI toolkit.
+
+## Installation
+
+```bash
+npm install @xsolla/xui-hooks
+```
+
+## Usage
+
+### `useClickOutside`
+
+Calls a callback when a `mousedown` occurs outside the referenced element. The
+listener is attached only while `enabled` is strictly `true`, so you can pass a
+possibly-nullish flag without coercing it (e.g. only listen while a dropdown is
+open and you're on the web).
+
+```tsx
+import { useRef, useState } from "react";
+import { useClickOutside } from "@xsolla/xui-hooks";
+
+function Dropdown() {
+  const ref = useRef<HTMLDivElement>(null);
+  const [open, setOpen] = useState(false);
+
+  useClickOutside(ref, () => setOpen(false), open);
+
+  return <div ref={ref}>{/* ... */}</div>;
+}
+```
+
+## Exports
+
+- `useClickOutside(ref, callback, enabled)` — Fires `callback(event)` on a
+  `mousedown` outside `ref`. Active only when `enabled === true`;
+  `false`/`null`/`undefined` keep it inactive.

package/index.d.mts

@@ -0,0 +1,25 @@
+import { RefObject } from 'react';
+
+/**
+ * Calls `callback` when a `mousedown` happens outside of `ref`'s element.
+ *
+ * Shadow-DOM safe (microfrontends): the listener is attached to the element's
+ * `ownerDocument` and "outside" is checked via `event.composedPath()`, which
+ * pierces shadow boundaries. This avoids the retargeting problem where a
+ * document-level `event.target` collapses to the shadow host, and still catches
+ * clicks in the light DOM outside the shadow root.
+ *
+ * Uses the capture phase so a descendant calling `event.stopPropagation()` on
+ * `mousedown` (common in nested microfrontend trees) cannot suppress detection.
+ * The trigger that toggles open state must live inside `ref`, otherwise the
+ * capture listener may fire before the trigger's own handler.
+ *
+ * @param ref      Ref to the element to detect outside clicks for.
+ * @param callback Invoked with the originating event on an outside click.
+ * @param enabled  Listener is attached only when this is strictly `true`.
+ *                 `false`/`null`/`undefined` leave it detached, so consumers
+ *                 can pass a possibly-nullish flag without coercing it.
+ */
+declare function useClickOutside(ref: RefObject<HTMLElement | null>, callback: (event: MouseEvent) => void, enabled: boolean | null | undefined): void;
+
+export { useClickOutside };

package/index.d.ts

@@ -0,0 +1,25 @@
+import { RefObject } from 'react';
+
+/**
+ * Calls `callback` when a `mousedown` happens outside of `ref`'s element.
+ *
+ * Shadow-DOM safe (microfrontends): the listener is attached to the element's
+ * `ownerDocument` and "outside" is checked via `event.composedPath()`, which
+ * pierces shadow boundaries. This avoids the retargeting problem where a
+ * document-level `event.target` collapses to the shadow host, and still catches
+ * clicks in the light DOM outside the shadow root.
+ *
+ * Uses the capture phase so a descendant calling `event.stopPropagation()` on
+ * `mousedown` (common in nested microfrontend trees) cannot suppress detection.
+ * The trigger that toggles open state must live inside `ref`, otherwise the
+ * capture listener may fire before the trigger's own handler.
+ *
+ * @param ref      Ref to the element to detect outside clicks for.
+ * @param callback Invoked with the originating event on an outside click.
+ * @param enabled  Listener is attached only when this is strictly `true`.
+ *                 `false`/`null`/`undefined` leave it detached, so consumers
+ *                 can pass a possibly-nullish flag without coercing it.
+ */
+declare function useClickOutside(ref: RefObject<HTMLElement | null>, callback: (event: MouseEvent) => void, enabled: boolean | null | undefined): void;
+
+export { useClickOutside };

package/index.js

@@ -0,0 +1,61 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  useClickOutside: () => useClickOutside
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useClickOutside.ts
+var import_react = require("react");
+function useClickOutside(ref, callback, enabled) {
+  (0, import_react.useEffect)(() => {
+    if (enabled !== true) {
+      return;
+    }
+    const { current: element } = ref;
+    if (!element) {
+      return;
+    }
+    const doc = element.ownerDocument ?? (typeof document !== "undefined" ? document : null);
+    if (!doc) {
+      return;
+    }
+    const handleClick = (event) => {
+      const { current: target } = ref;
+      if (!target || !target.isConnected) {
+        return;
+      }
+      const composedPath = typeof event.composedPath === "function" ? event.composedPath() : [];
+      const isInside = composedPath.length ? composedPath.includes(target) : target.contains(event.target);
+      if (!isInside) {
+        callback(event);
+      }
+    };
+    doc.addEventListener("mousedown", handleClick, true);
+    return () => doc.removeEventListener("mousedown", handleClick, true);
+  }, [ref, callback, enabled]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useClickOutside
+});
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx","../src/useClickOutside.ts"],"sourcesContent":["export * from \"./useClickOutside\";\n","import { useEffect, type RefObject } from \"react\";\n\n/**\n * Calls `callback` when a `mousedown` happens outside of `ref`'s element.\n *\n * Shadow-DOM safe (microfrontends): the listener is attached to the element's\n * `ownerDocument` and \"outside\" is checked via `event.composedPath()`, which\n * pierces shadow boundaries. This avoids the retargeting problem where a\n * document-level `event.target` collapses to the shadow host, and still catches\n * clicks in the light DOM outside the shadow root.\n *\n * Uses the capture phase so a descendant calling `event.stopPropagation()` on\n * `mousedown` (common in nested microfrontend trees) cannot suppress detection.\n * The trigger that toggles open state must live inside `ref`, otherwise the\n * capture listener may fire before the trigger's own handler.\n *\n * @param ref      Ref to the element to detect outside clicks for.\n * @param callback Invoked with the originating event on an outside click.\n * @param enabled  Listener is attached only when this is strictly `true`.\n *                 `false`/`null`/`undefined` leave it detached, so consumers\n *                 can pass a possibly-nullish flag without coercing it.\n */\nexport function useClickOutside(\n  ref: RefObject<HTMLElement | null>,\n  callback: (event: MouseEvent) => void,\n  enabled: boolean | null | undefined\n): void {\n  useEffect(() => {\n    if (enabled !== true) {\n      return;\n    }\n\n    const { current: element } = ref;\n    if (!element) {\n      return;\n    }\n\n    const doc =\n      element.ownerDocument ??\n      (typeof document !== \"undefined\" ? document : null);\n    if (!doc) {\n      return;\n    }\n\n    const handleClick = (event: MouseEvent) => {\n      const { current: target } = ref;\n      if (!target || !target.isConnected) {\n        return;\n      }\n\n      const composedPath =\n        typeof event.composedPath === \"function\" ? event.composedPath() : [];\n\n      const isInside = composedPath.length\n        ? composedPath.includes(target)\n        : target.contains(event.target as Node);\n\n      if (!isInside) {\n        callback(event);\n      }\n    };\n\n    doc.addEventListener(\"mousedown\", handleClick, true);\n    return () => doc.removeEventListener(\"mousedown\", handleClick, true);\n  }, [ref, callback, enabled]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,mBAA0C;AAsBnC,SAAS,gBACd,KACA,UACA,SACM;AACN,8BAAU,MAAM;AACd,QAAI,YAAY,MAAM;AACpB;AAAA,IACF;AAEA,UAAM,EAAE,SAAS,QAAQ,IAAI;AAC7B,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAEA,UAAM,MACJ,QAAQ,kBACP,OAAO,aAAa,cAAc,WAAW;AAChD,QAAI,CAAC,KAAK;AACR;AAAA,IACF;AAEA,UAAM,cAAc,CAAC,UAAsB;AACzC,YAAM,EAAE,SAAS,OAAO,IAAI;AAC5B,UAAI,CAAC,UAAU,CAAC,OAAO,aAAa;AAClC;AAAA,MACF;AAEA,YAAM,eACJ,OAAO,MAAM,iBAAiB,aAAa,MAAM,aAAa,IAAI,CAAC;AAErE,YAAM,WAAW,aAAa,SAC1B,aAAa,SAAS,MAAM,IAC5B,OAAO,SAAS,MAAM,MAAc;AAExC,UAAI,CAAC,UAAU;AACb,iBAAS,KAAK;AAAA,MAChB;AAAA,IACF;AAEA,QAAI,iBAAiB,aAAa,aAAa,IAAI;AACnD,WAAO,MAAM,IAAI,oBAAoB,aAAa,aAAa,IAAI;AAAA,EACrE,GAAG,CAAC,KAAK,UAAU,OAAO,CAAC;AAC7B;","names":[]}

package/index.mjs

@@ -0,0 +1,34 @@
+// src/useClickOutside.ts
+import { useEffect } from "react";
+function useClickOutside(ref, callback, enabled) {
+  useEffect(() => {
+    if (enabled !== true) {
+      return;
+    }
+    const { current: element } = ref;
+    if (!element) {
+      return;
+    }
+    const doc = element.ownerDocument ?? (typeof document !== "undefined" ? document : null);
+    if (!doc) {
+      return;
+    }
+    const handleClick = (event) => {
+      const { current: target } = ref;
+      if (!target || !target.isConnected) {
+        return;
+      }
+      const composedPath = typeof event.composedPath === "function" ? event.composedPath() : [];
+      const isInside = composedPath.length ? composedPath.includes(target) : target.contains(event.target);
+      if (!isInside) {
+        callback(event);
+      }
+    };
+    doc.addEventListener("mousedown", handleClick, true);
+    return () => doc.removeEventListener("mousedown", handleClick, true);
+  }, [ref, callback, enabled]);
+}
+export {
+  useClickOutside
+};
+//# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useClickOutside.ts"],"sourcesContent":["import { useEffect, type RefObject } from \"react\";\n\n/**\n * Calls `callback` when a `mousedown` happens outside of `ref`'s element.\n *\n * Shadow-DOM safe (microfrontends): the listener is attached to the element's\n * `ownerDocument` and \"outside\" is checked via `event.composedPath()`, which\n * pierces shadow boundaries. This avoids the retargeting problem where a\n * document-level `event.target` collapses to the shadow host, and still catches\n * clicks in the light DOM outside the shadow root.\n *\n * Uses the capture phase so a descendant calling `event.stopPropagation()` on\n * `mousedown` (common in nested microfrontend trees) cannot suppress detection.\n * The trigger that toggles open state must live inside `ref`, otherwise the\n * capture listener may fire before the trigger's own handler.\n *\n * @param ref      Ref to the element to detect outside clicks for.\n * @param callback Invoked with the originating event on an outside click.\n * @param enabled  Listener is attached only when this is strictly `true`.\n *                 `false`/`null`/`undefined` leave it detached, so consumers\n *                 can pass a possibly-nullish flag without coercing it.\n */\nexport function useClickOutside(\n  ref: RefObject<HTMLElement | null>,\n  callback: (event: MouseEvent) => void,\n  enabled: boolean | null | undefined\n): void {\n  useEffect(() => {\n    if (enabled !== true) {\n      return;\n    }\n\n    const { current: element } = ref;\n    if (!element) {\n      return;\n    }\n\n    const doc =\n      element.ownerDocument ??\n      (typeof document !== \"undefined\" ? document : null);\n    if (!doc) {\n      return;\n    }\n\n    const handleClick = (event: MouseEvent) => {\n      const { current: target } = ref;\n      if (!target || !target.isConnected) {\n        return;\n      }\n\n      const composedPath =\n        typeof event.composedPath === \"function\" ? event.composedPath() : [];\n\n      const isInside = composedPath.length\n        ? composedPath.includes(target)\n        : target.contains(event.target as Node);\n\n      if (!isInside) {\n        callback(event);\n      }\n    };\n\n    doc.addEventListener(\"mousedown\", handleClick, true);\n    return () => doc.removeEventListener(\"mousedown\", handleClick, true);\n  }, [ref, callback, enabled]);\n}\n"],"mappings":";AAAA,SAAS,iBAAiC;AAsBnC,SAAS,gBACd,KACA,UACA,SACM;AACN,YAAU,MAAM;AACd,QAAI,YAAY,MAAM;AACpB;AAAA,IACF;AAEA,UAAM,EAAE,SAAS,QAAQ,IAAI;AAC7B,QAAI,CAAC,SAAS;AACZ;AAAA,IACF;AAEA,UAAM,MACJ,QAAQ,kBACP,OAAO,aAAa,cAAc,WAAW;AAChD,QAAI,CAAC,KAAK;AACR;AAAA,IACF;AAEA,UAAM,cAAc,CAAC,UAAsB;AACzC,YAAM,EAAE,SAAS,OAAO,IAAI;AAC5B,UAAI,CAAC,UAAU,CAAC,OAAO,aAAa;AAClC;AAAA,MACF;AAEA,YAAM,eACJ,OAAO,MAAM,iBAAiB,aAAa,MAAM,aAAa,IAAI,CAAC;AAErE,YAAM,WAAW,aAAa,SAC1B,aAAa,SAAS,MAAM,IAC5B,OAAO,SAAS,MAAM,MAAc;AAExC,UAAI,CAAC,UAAU;AACb,iBAAS,KAAK;AAAA,MAChB;AAAA,IACF;AAEA,QAAI,iBAAiB,aAAa,aAAa,IAAI;AACnD,WAAO,MAAM,IAAI,oBAAoB,aAAa,aAAa,IAAI;AAAA,EACrE,GAAG,CAAC,KAAK,UAAU,OAAO,CAAC;AAC7B;","names":[]}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@xsolla/xui-hooks",
+  "version": "0.175.0",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^14.1.2",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^24.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^8.0.0",
+    "vitest": "^4.0.18"
+  },
+  "license": "MIT",
+  "sideEffects": false
+}