@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,285 @@
-# Temporary Holding Version
+# @fivem-nui/svelte
 
-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.
+> Svelte adapter and reactive toolkit for FiveM NUI communication, engineered for **Svelte 5** Runes (`$state`, `$derived`, `$effect`).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/rian-be/FiveM.Nui/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.12.0-brightgreen.svg)](#requirements)
+[![TypeScript](https://img.shields.io/badge/TypeScript-7.x-blue.svg)](#requirements)
+[![Svelte](https://img.shields.io/badge/Svelte-5.x-orange.svg)](https://svelte.dev)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+
+`@fivem-nui/svelte` provides seamless, reactive integration between client C# scripts (.NET 10) and Svelte 5 NUI panels. It wraps `@fivem-nui/core` with native Svelte 5 Runes, DOM actions (`use:action`), keyboard shortcuts, focus trapping, and browser mocking for rapid local development.
+
+---
+
+## Installation
+
+```bash
+npm install @fivem-nui/svelte @fivem-nui/core svelte
+```
+
+> **Note:** `@fivem-nui/core` (`>=1.0.0`) and `svelte` (`>=5.0.0`) are peer dependencies.
+
+---
+
+## Package Entry Points
+
+The package exposes modular subpaths for tree-shaking and isolation:
+
+| Import Path | Description | Contents |
+|---|---|---|
+| `@fivem-nui/svelte` | Main library | Runes (`useNuiState`, `useNuiQuery`, `useNuiWindow`), client, context, error re-exports |
+| `@fivem-nui/svelte/actions` | DOM actions | `nuiEscapeAction`, `nuiFocusTrap`, `nuiClickOutside`, `nuiLayer` |
+| `@fivem-nui/svelte/mock` | Browser mocking | `setupNuiMock`, mock transport and window emission helpers |
+
+```ts
+import { nui, useNuiState, useNuiQuery } from '@fivem-nui/svelte';
+import { nuiFocusTrap, nuiClickOutside } from '@fivem-nui/svelte/actions';
+import { setupNuiMock } from '@fivem-nui/svelte/mock';
+```
+
+---
+
+## Runes API
+
+### 1. `useNuiState` (Reactive C# → UI Events)
+
+Synchronizes incoming NUI events with a reactive `$state` rune, supporting functional updates:
+
+```svelte
+<script lang="ts">
+  import { useNuiState } from '@fivem-nui/svelte';
+
+  interface PlayerStats {
+    health: number;
+    armor: number;
+  }
+
+  // Automatically listens to 'player:stats' and unregisters on component unmount
+  const stats = useNuiState<PlayerStats>('player:stats', { health: 100, armor: 0 });
+
+  function heal(amount: number) {
+    stats.update(prev => ({ ...prev, health: Math.min(100, prev.health + amount) }));
+  }
+</script>
+
+<div class="hud">
+  <p>Health: {stats.value.health}%</p>
+  <p>Armor: {stats.value.armor}%</p>
+  {#if stats.updatedAt}
+    <small>Last updated: {new Date(stats.updatedAt).toLocaleTimeString()}</small>
+  {/if}
+</div>
+```
+
+---
+
+### 2. `useNuiQuery` (Reactive UI → C# Request/Response)
+
+Manages outgoing `nui.request` calls with automated reactive states (`loading`, `error`, `data`), retries, and cancellation:
+
+```svelte
+<script lang="ts">
+  import { useNuiQuery } from '@fivem-nui/svelte';
+
+  interface BuyRequest { itemId: string; quantity: number; }
+  interface BuyResponse { success: boolean; balance: number; }
+
+  const buy = useNuiQuery<BuyRequest, BuyResponse>('shop:buy');
+</script>
+
+<button 
+  onclick={() => buy.execute({ itemId: 'water', quantity: 2 })} 
+  disabled={buy.loading}
+>
+  {buy.loading ? 'Purchasing...' : 'Buy Water'}
+</button>
+
+<button onclick={() => buy.refetch()} disabled={!buy.called || buy.loading}>
+  Repeat Purchase
+</button>
+
+{#if buy.error}
+  <p class="error">{buy.error.message}</p>
+{/if}
+
+{#if buy.data}
+  <p>Remaining Balance: ${buy.data.balance}</p>
+{/if}
+```
+
+---
+
+### 3. `useNuiWindow` (Window Visibility & Lifecycle)
+
+Synchronizes window visibility with `onWindow` events emitted from C# (`open`, `close`, `focus`, `unfocus`) and handles the `Escape` key by default:
+
+```svelte
+<script lang="ts">
+  import { useNuiWindow } from '@fivem-nui/svelte';
+
+  // closeOnEscape is enabled by default (true)
+  const panel = useNuiWindow('inventory', {
+    onClose: () => console.log('Window closed')
+  });
+</script>
+
+{#if panel.visible}
+  <div class="panel">
+    <h2>Inventory</h2>
+    <button onclick={() => panel.close()}>Close (or press ESC)</button>
+  </div>
+{/if}
+```
+
+---
+
+## UI Utilities, Keyboard & Svelte Actions
+
+The package provides two integration paths: **Svelte Actions (`use:action`)** for declarative DOM binding and **Runes Composables** for programmatic control in `<script>`:
+
+| Feature | Svelte Action (`use:action`) | Runes Composable | Use Case |
+|---|---|---|---|
+| **Escape Key** | `nuiEscapeAction` | `useEscape()` / `useNuiEscape()` | Close modals or panels on ESC |
+| **Focus Trap** | `nuiFocusTrap` | `useFocusTrap()` | Prevent keyboard Tab key from escaping modal |
+| **Click Outside** | `nuiClickOutside` | `useClickOutside()` | Dismiss dropdowns and context menus |
+| **Layer Stack (Z-Index)** | `nuiLayer` | `useLayer()` | Manage stacking order of nested modals |
+| **Keyboard Shortcuts** | — | `useNuiKey()` | Listen for custom hotkeys (e.g., F1, Enter) |
+
+### 1. Keyboard Shortcuts (`useNuiEscape` & `useNuiKey`)
+
+```svelte
+<script lang="ts">
+  import { useNuiEscape, useNuiKey, nui } from '@fivem-nui/svelte';
+
+  // Cleaned up automatically on component unmount
+  useNuiEscape(() => nui.notify('close'));
+
+  // Listen to arbitrary keys with optional condition:
+  useNuiKey('F1', () => console.log('Help toggled'), { enabled: () => true });
+</script>
+```
+
+Or declaratively in template:
+```svelte
+<div use:nuiEscapeAction={() => panel.close()}>...</div>
+```
+
+### 2. Focus Trap (`nuiFocusTrap` / `useFocusTrap`)
+
+Keeps keyboard Tab focus trapped inside the active dialog:
+
+```svelte
+<script lang="ts">
+  import { nuiFocusTrap } from '@fivem-nui/svelte/actions';
+</script>
+
+<div class="modal-dialog" use:nuiFocusTrap>
+  <input type="text" placeholder="Character Name..." />
+  <button>Save</button>
+</div>
+```
+
+### 3. Click Outside (`nuiClickOutside` / `useClickOutside`)
+
+Automatically closes popups or dropdowns when clicking outside their element:
+
+```svelte
+<script lang="ts">
+  import { nuiClickOutside } from '@fivem-nui/svelte/actions';
+
+  let open = $state(true);
+</script>
+
+{#if open}
+  <div class="dropdown" use:nuiClickOutside={() => (open = false)}>
+    Menu Content...
+  </div>
+{/if}
+```
+
+---
+
+## Environment Detection
+
+Detect whether the UI is running inside GTA V / FiveM CEF or in a standard browser:
+
+```typescript
+import { isNui, isBrowser, getResourceName } from '@fivem-nui/svelte';
+
+if (isBrowser()) {
+  console.log('Running locally in browser (outside FiveM CEF)');
+}
+
+console.log('Resource Name:', getResourceName());
+```
+
+---
+
+## Browser Mocking (`setupNuiMock`)
+
+Test and style your UI panels in Google Chrome (`npm run dev`) with instant Vite HMR without launching FiveM:
+
+```typescript
+import { isBrowser, setupNuiMock } from '@fivem-nui/svelte/mock';
+
+if (isBrowser()) {
+  setupNuiMock({
+    requests: {
+      'shop:buy': async (payload) => {
+        return { success: true, balance: 4500, bought: payload.itemId };
+      }
+    },
+    callbacks: {
+      'close': () => console.log('Panel closed by UI'),
+      'ready': () => console.log('Panel ready acknowledged')
+    },
+    onSend: {
+      'comps:log': (toast) => console.log('Toast sent from UI:', toast)
+    }
+  });
+
+  // You can also simulate incoming C# traffic from browser DevTools:
+  // window.__nuiMock.emitEvent('player:stats', { health: 80, armor: 50 });
+  // window.__nuiMock.emitWindow('open', 'inventory');
+}
+```
+
+---
+
+## Svelte Context & Custom Clients
+
+When you need an isolated NUI client passed down the component hierarchy:
+
+```svelte
+<script lang="ts">
+  import { setNuiClient, SvelteNuiClient } from '@fivem-nui/svelte';
+
+  const customClient = new SvelteNuiClient({ resource: 'my_resource' });
+  setNuiClient(customClient);
+</script>
+```
+
+In any descendant component:
+```svelte
+<script lang="ts">
+  import { useNuiClient } from '@fivem-nui/svelte';
+
+  const client = useNuiClient();
+</script>
+```
+
+---
+
+## Re-exports & Error Handling
+
+`@fivem-nui/svelte` directly re-exports the entire `@fivem-nui/error` toolkit and core contract types:
+
+- **Error handling:** `installGlobalErrorHandlers`, `withRetry`, `globalErrorHandler`, `NuiErrorCategory`, `NuiErrorSeverity`, `captureRenderError`, `isAbortError`.
+- **Core contracts:** `NuiEventMap`, `NuiEventKey`, `NuiEventRequest`, `NuiEventResponse`, `NuiMessage`, `NuiError`.
+
+---
+
+## License
+
+[MIT](../../../LICENSE) © 2026 Rian.be

package/dist/actions/clickOutside/clickOutside.d.ts

@@ -0,0 +1,24 @@
+import type { Action } from 'svelte/action';
+import { type NuiClickOutsideInput } from './types';
+/**
+ * Svelte Action for reliable outside click detection in FiveM CEF.
+ *
+ * Uses `event.composedPath()` to eliminate the detached DOM node bug when
+ * inner elements mutate during click events.
+ *
+ * @remarks
+ * **Multiple Overlays in CEF**:
+ * Because `pointerdown` is used with `capture: true`, clicking into another open NUI panel
+ * will trigger an outside click unless that other panel is explicitly included in `ignore`.
+ *
+ * @param node - The DOM element to monitor for outside clicks.
+ * @param parameter - Callback function or configuration options object.
+ *
+ * @example
+ * ```svelte
+ * <div use:nuiClickOutside={() => (isOpen = false)}>...</div>
+ * <div use:nuiClickOutside={{ onClickOutside: close, ignore: [triggerEl, '.header-btn'] }}>...</div>
+ * ```
+ */
+export declare const nuiClickOutside: Action<HTMLElement, NuiClickOutsideInput>;
+//# sourceMappingURL=clickOutside.d.ts.map

package/dist/actions/clickOutside/clickOutside.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickOutside.d.ts","sourceRoot":"","sources":["../../../src/actions/clickOutside/clickOutside.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,SAAS,CAAC;AAGjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,oBAAoB,CAkDrE,CAAC"}

package/dist/actions/clickOutside/clickOutside.js

@@ -0,0 +1,62 @@
+import { toClickOutsideOptions } from './types';
+import { createClickOutsideHandler } from './handler';
+/**
+ * Svelte Action for reliable outside click detection in FiveM CEF.
+ *
+ * Uses `event.composedPath()` to eliminate the detached DOM node bug when
+ * inner elements mutate during click events.
+ *
+ * @remarks
+ * **Multiple Overlays in CEF**:
+ * Because `pointerdown` is used with `capture: true`, clicking into another open NUI panel
+ * will trigger an outside click unless that other panel is explicitly included in `ignore`.
+ *
+ * @param node - The DOM element to monitor for outside clicks.
+ * @param parameter - Callback function or configuration options object.
+ *
+ * @example
+ * ```svelte
+ * <div use:nuiClickOutside={() => (isOpen = false)}>...</div>
+ * <div use:nuiClickOutside={{ onClickOutside: close, ignore: [triggerEl, '.header-btn'] }}>...</div>
+ * ```
+ */
+export const nuiClickOutside = (node, parameter) => {
+    let currentParam = parameter;
+    let controller = null;
+    const handler = createClickOutsideHandler(() => node, () => toClickOutsideOptions(currentParam));
+    function getCapture() {
+        const opts = toClickOutsideOptions(currentParam);
+        return opts?.capture ?? true;
+    }
+    function setup() {
+        teardown();
+        controller = new AbortController();
+        document.addEventListener('pointerdown', handler, {
+            capture: getCapture(),
+            signal: controller.signal
+        });
+    }
+    function teardown() {
+        if (controller) {
+            controller.abort();
+            controller = null;
+        }
+    }
+    setup();
+    return {
+        update(newParam) {
+            const prevCapture = getCapture();
+            currentParam = newParam;
+            // Only changes to `capture` require re-binding the document listener.
+            // All other options (`enabled`, `onClickOutside`, `ignore`)
+            // are read lazily on each pointerdown event via getOptions().
+            if (getCapture() !== prevCapture) {
+                setup();
+            }
+        },
+        destroy() {
+            teardown();
+        }
+    };
+};
+//# sourceMappingURL=clickOutside.js.map

package/dist/actions/clickOutside/clickOutside.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickOutside.js","sourceRoot":"","sources":["../../../src/actions/clickOutside/clickOutside.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,qBAAqB,EACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,eAAe,GAA8C,CACxE,IAAI,EACJ,SAAS,EACT,EAAE;IACF,IAAI,YAAY,GAAG,SAAS,CAAC;IAC7B,IAAI,UAAU,GAA2B,IAAI,CAAC;IAE9C,MAAM,OAAO,GAAG,yBAAyB,CACvC,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAC1C,CAAC;IAEF,SAAS,UAAU;QACjB,MAAM,IAAI,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;QACjD,OAAO,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC;IAC/B,CAAC;IAED,SAAS,KAAK;QACZ,QAAQ,EAAE,CAAC;QACX,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,EAAE;YAChD,OAAO,EAAE,UAAU,EAAE;YACrB,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAED,SAAS,QAAQ;QACf,IAAI,UAAU,EAAE,CAAC;YACf,UAAU,CAAC,KAAK,EAAE,CAAC;YACnB,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,KAAK,EAAE,CAAC;IAER,OAAO;QACL,MAAM,CAAC,QAAQ;YACb,MAAM,WAAW,GAAG,UAAU,EAAE,CAAC;YACjC,YAAY,GAAG,QAAQ,CAAC;YACxB,sEAAsE;YACtE,4DAA4D;YAC5D,8DAA8D;YAC9D,IAAI,UAAU,EAAE,KAAK,WAAW,EAAE,CAAC;gBACjC,KAAK,EAAE,CAAC;YACV,CAAC;QACH,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/actions/clickOutside/handler.d.ts

@@ -0,0 +1,11 @@
+import type { ClickOutsideTarget, NuiClickOutsideParameter } from './types';
+/**
+ * Resolves a DOM Element from an Element reference, CSS selector string, or getter function.
+ */
+export declare function resolveElement(target: ClickOutsideTarget): Element | null;
+/**
+ * Creates a reusable pointerdown event handler for outside click detection.
+ * Shared between Svelte action and composable to eliminate duplication.
+ */
+export declare function createClickOutsideHandler(getNode: () => Element | null | undefined, getOptions: () => NuiClickOutsideParameter | undefined): (event: PointerEvent) => void;
+//# sourceMappingURL=handler.d.ts.map

package/dist/actions/clickOutside/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/actions/clickOutside/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,SAAS,CAAC;AAE5E;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,EACzC,UAAU,EAAE,MAAM,wBAAwB,GAAG,SAAS,WAEvC,YAAY,UAyB5B"}

package/dist/actions/clickOutside/handler.js

@@ -0,0 +1,45 @@
+/**
+ * Resolves a DOM Element from an Element reference, CSS selector string, or getter function.
+ */
+export function resolveElement(target) {
+    if (typeof target === 'string') {
+        return document.querySelector(target);
+    }
+    if (typeof target === 'function') {
+        return target() ?? null;
+    }
+    return target ?? null;
+}
+/**
+ * Creates a reusable pointerdown event handler for outside click detection.
+ * Shared between Svelte action and composable to eliminate duplication.
+ */
+export function createClickOutsideHandler(getNode, getOptions) {
+    return (event) => {
+        const node = getNode();
+        const opts = getOptions();
+        if (!node?.isConnected || !opts)
+            return;
+        const enabled = typeof opts.enabled === 'function' ? opts.enabled() : opts.enabled ?? true;
+        if (!enabled || event.button !== 0)
+            return;
+        const path = event.composedPath();
+        if (path.includes(node))
+            return;
+        for (const item of opts.ignore ?? []) {
+            const el = resolveElement(item);
+            if (el && path.includes(el))
+                return;
+        }
+        const callback = opts.onClickOutside ?? opts.callback;
+        if (callback) {
+            try {
+                callback(event);
+            }
+            catch (err) {
+                console.error('[NuiClickOutside] Error in onClickOutside callback:', err);
+            }
+        }
+    };
+}
+//# sourceMappingURL=handler.js.map

package/dist/actions/clickOutside/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/actions/clickOutside/handler.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAA0B;IACvD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,MAAM,EAAE,IAAI,IAAI,CAAC;IAC1B,CAAC;IACD,OAAO,MAAM,IAAI,IAAI,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAyC,EACzC,UAAsD;IAEtD,OAAO,CAAC,KAAmB,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,EAAE,WAAW,IAAI,CAAC,IAAI;YAAE,OAAO;QAExC,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;QAC3F,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAE3C,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO;QAEhC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YACrC,MAAM,EAAE,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAAE,OAAO;QACtC,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ,CAAC;QACtD,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,qDAAqD,EAAE,GAAG,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/actions/clickOutside/index.d.ts

@@ -0,0 +1,4 @@
+export { nuiClickOutside } from './clickOutside';
+export { type ClickOutsideTarget, type NuiClickOutsideParameter, type NuiClickOutsideInput, toClickOutsideOptions } from './types';
+export { resolveElement, createClickOutsideHandler } from './handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/actions/clickOutside/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/actions/clickOutside/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,yBAAyB,EAC1B,MAAM,WAAW,CAAC"}

package/dist/actions/clickOutside/index.js

@@ -0,0 +1,4 @@
+export { nuiClickOutside } from './clickOutside';
+export { toClickOutsideOptions } from './types';
+export { resolveElement, createClickOutsideHandler } from './handler';
+//# sourceMappingURL=index.js.map

package/dist/actions/clickOutside/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/actions/clickOutside/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAIL,qBAAqB,EACtB,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,cAAc,EACd,yBAAyB,EAC1B,MAAM,WAAW,CAAC"}

package/dist/actions/clickOutside/types.d.ts

@@ -0,0 +1,36 @@
+export type ClickOutsideTarget = Element | string | null | undefined | (() => Element | null | undefined);
+export interface NuiClickOutsideParameter {
+    /**
+     * Callback invoked when a click or touch occurs outside the target node.
+     */
+    onClickOutside?: (event: PointerEvent) => void;
+    /**
+     * @deprecated Use `onClickOutside` instead.
+     */
+    callback?: (event: PointerEvent) => void;
+    /**
+     * Whether the outside click detector is active.
+     * Can be a static boolean or a reactive getter `() => boolean`.
+     * @defaultValue true
+     */
+    enabled?: boolean | (() => boolean);
+    /**
+     * Elements, selectors, or getters to exclude from triggering outside click.
+     *
+     * @remarks
+     * **Trigger / Toggle Buttons**:
+     * Because `capture: true` listens on the capturing phase (`pointerdown` fires before `click`),
+     * clicking a toggle/trigger button without adding it to `ignore` will cause an immediate
+     * flicker (the outside click closes the popover during `pointerdown`, and the button's
+     * subsequent `click` immediately re-opens it). Always pass your toggle button in `ignore`.
+     */
+    ignore?: ClickOutsideTarget[];
+    /**
+     * Listen during capture phase to intercept before bubbling mutations.
+     * @defaultValue true
+     */
+    capture?: boolean;
+}
+export type NuiClickOutsideInput = ((event: PointerEvent) => void) | NuiClickOutsideParameter;
+export declare function toClickOutsideOptions(param: NuiClickOutsideInput | undefined): NuiClickOutsideParameter | undefined;
+//# sourceMappingURL=types.d.ts.map

package/dist/actions/clickOutside/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/actions/clickOutside/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,MAAM,GACN,IAAI,GACJ,SAAS,GACT,CAAC,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEvC,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAEpC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAC5B,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,GAC/B,wBAAwB,CAAC;AAE7B,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,GAAG,SAAS,GACtC,wBAAwB,GAAG,SAAS,CAGtC"}

package/dist/actions/clickOutside/types.js

@@ -0,0 +1,6 @@
+export function toClickOutsideOptions(param) {
+    if (!param)
+        return undefined;
+    return typeof param === 'function' ? { onClickOutside: param } : param;
+}
+//# sourceMappingURL=types.js.map

package/dist/actions/clickOutside/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/actions/clickOutside/types.ts"],"names":[],"mappings":"AAgDA,MAAM,UAAU,qBAAqB,CACnC,KAAuC;IAEvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AACzE,CAAC"}

package/dist/actions/clickOutside.d.ts

@@ -0,0 +1,63 @@
+import type { Action } from 'svelte/action';
+export type ClickOutsideTarget = Element | string | null | undefined | (() => Element | null | undefined);
+export interface NuiClickOutsideParameter {
+    /**
+     * Callback invoked when a click or touch occurs outside the target node.
+     */
+    onClickOutside?: (event: PointerEvent) => void;
+    /**
+     * @deprecated Use `onClickOutside` instead.
+     */
+    callback?: (event: PointerEvent) => void;
+    /**
+     * Whether the outside click detector is active.
+     * Can be a static boolean or a reactive getter `() => boolean`.
+     * @defaultValue true
+     */
+    enabled?: boolean | (() => boolean);
+    /**
+     * Elements, selectors, or getters to exclude from triggering outside click.
+     *
+     * @remarks
+     * **Trigger / Toggle Buttons**:
+     * Because `capture: true` listens on the capturing phase (`pointerdown` fires before `click`),
+     * clicking a toggle/trigger button without adding it to `ignore` will cause an immediate
+     * flicker (the outside click closes the popover during `pointerdown`, and the button's
+     * subsequent `click` immediately re-opens it). Always pass your toggle button in `ignore`.
+     */
+    ignore?: ClickOutsideTarget[];
+    /**
+     * Listen during capture phase to intercept before bubbling mutations.
+     * @defaultValue true
+     */
+    capture?: boolean;
+}
+export type NuiClickOutsideInput = ((event: PointerEvent) => void) | NuiClickOutsideParameter;
+export declare function resolveElement(target: ClickOutsideTarget): Element | null;
+/**
+ * Creates a reusable pointerdown event handler for outside click detection.
+ * Shared between Svelte action and composable to eliminate duplication.
+ */
+export declare function createClickOutsideHandler(getNode: () => Element | null | undefined, getOptions: () => NuiClickOutsideParameter | undefined): (event: PointerEvent) => void;
+/**
+ * Svelte Action for reliable outside click detection in FiveM CEF.
+ *
+ * Uses `event.composedPath()` to eliminate the detached DOM node bug when
+ * inner elements mutate during click events.
+ *
+ * @remarks
+ * **Multiple Overlays in CEF**:
+ * Because `pointerdown` is used with `capture: true`, clicking into another open NUI panel
+ * will trigger an outside click unless that other panel is explicitly included in `ignore`.
+ *
+ * @param node - The DOM element to monitor for outside clicks.
+ * @param parameter - Callback function or configuration options object.
+ *
+ * @example
+ * ```svelte
+ * <div use:nuiClickOutside={() => (isOpen = false)}>...</div>
+ * <div use:nuiClickOutside={{ onClickOutside: close, ignore: [triggerEl, '.header-btn'] }}>...</div>
+ * ```
+ */
+export declare const nuiClickOutside: Action<HTMLElement, NuiClickOutsideInput>;
+//# sourceMappingURL=clickOutside.d.ts.map

package/dist/actions/clickOutside.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickOutside.d.ts","sourceRoot":"","sources":["../../src/actions/clickOutside.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,MAAM,GACN,IAAI,GACJ,SAAS,GACT,CAAC,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEvC,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAEpC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAE9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,oBAAoB,GAC5B,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,GAC/B,wBAAwB,CAAC;AAE7B,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,GAAG,IAAI,CAQzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,GAAG,SAAS,EACzC,UAAU,EAAE,MAAM,wBAAwB,GAAG,SAAS,WAEvC,YAAY,UAyB5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,WAAW,EAAE,oBAAoB,CAuDrE,CAAC"}