@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/dist/utils/keyboard.js

@@ -0,0 +1,152 @@
+import { onDestroy } from 'svelte';
+/**
+ * Keyboard modifier keys.
+ */
+export var NuiKeyboardModifier;
+(function (NuiKeyboardModifier) {
+    NuiKeyboardModifier["Ctrl"] = "ctrl";
+    NuiKeyboardModifier["Alt"] = "alt";
+    NuiKeyboardModifier["Shift"] = "shift";
+    NuiKeyboardModifier["Meta"] = "meta";
+})(NuiKeyboardModifier || (NuiKeyboardModifier = {}));
+/**
+ * Standard special key names commonly used in FiveM NUI shortcuts.
+ */
+export var NuiSpecialKey;
+(function (NuiSpecialKey) {
+    NuiSpecialKey["Escape"] = "Escape";
+    NuiSpecialKey["Enter"] = "Enter";
+    NuiSpecialKey["Tab"] = "Tab";
+    NuiSpecialKey["Space"] = " ";
+    NuiSpecialKey["Backspace"] = "Backspace";
+    NuiSpecialKey["ArrowUp"] = "ArrowUp";
+    NuiSpecialKey["ArrowDown"] = "ArrowDown";
+    NuiSpecialKey["ArrowLeft"] = "ArrowLeft";
+    NuiSpecialKey["ArrowRight"] = "ArrowRight";
+})(NuiSpecialKey || (NuiSpecialKey = {}));
+function isTextInputActive() {
+    if (typeof document === 'undefined')
+        return false;
+    const el = document.activeElement;
+    if (!el)
+        return false;
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+        return true;
+    }
+    return el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false';
+}
+/**
+ * Registers a keyboard shortcut with automatic lifecycle management.
+ *
+ * Designed for FiveM NUI with support for:
+ * - `ignoreInputs`: prevents hotkeys from firing while typing in input fields.
+ * - Modifier keys (Ctrl, Alt, Shift, Meta).
+ * - Automatic cleanup via `onDestroy` and `AbortController`.
+ *
+ * @param keys - Key or array of keys (case-insensitive) to listen for.
+ * @param handler - Callback function invoked when matching keydown occurs.
+ * @param options - Optional shortcut configuration including modifiers and lifecycle strategy.
+ * @returns Cleanup function to remove event listeners.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useNuiKey } from '@fivem-nui/svelte';
+ *   useNuiKey('e', () => interact(), { ignoreInputs: true });
+ * </script>
+ * ```
+ */
+export function useNuiKey(keys, handler, options = {}) {
+    const targetKeys = (Array.isArray(keys) ? keys : [keys]).map((k) => k.toLowerCase());
+    const { capture = false, preventDefault = false, stopPropagation = false, enabled, ignoreInputs = false, ignoreRepeat = false, ctrl, alt, shift, meta } = options;
+    let controller = null;
+    function isAllowed() {
+        if (enabled === undefined)
+            return true;
+        return typeof enabled === 'function' ? enabled() : enabled;
+    }
+    function onKeyDown(event) {
+        if (!isAllowed())
+            return;
+        if (ignoreRepeat && event.repeat)
+            return;
+        if (ignoreInputs && isTextInputActive())
+            return;
+        if (ctrl !== undefined && event.ctrlKey !== ctrl)
+            return;
+        if (alt !== undefined && event.altKey !== alt)
+            return;
+        if (shift !== undefined && event.shiftKey !== shift)
+            return;
+        if (meta !== undefined && event.metaKey !== meta)
+            return;
+        if (targetKeys.includes(event.key.toLowerCase())) {
+            if (preventDefault) {
+                event.preventDefault();
+            }
+            if (stopPropagation) {
+                event.stopPropagation();
+            }
+            try {
+                handler(event);
+            }
+            catch (err) {
+                console.error('[NuiKey] Error in key handler callback:', err);
+            }
+        }
+    }
+    if (typeof window !== 'undefined') {
+        controller = new AbortController();
+        window.addEventListener('keydown', onKeyDown, {
+            capture,
+            signal: controller.signal
+        });
+    }
+    let isCleanedUp = false;
+    function cleanup() {
+        if (isCleanedUp)
+            return;
+        isCleanedUp = true;
+        if (controller) {
+            controller.abort();
+            controller = null;
+        }
+    }
+    if (options.autoDestroy !== false) {
+        try {
+            onDestroy(cleanup);
+        }
+        catch (lifecycleError) {
+            if (options.autoDestroy === true) {
+                cleanup();
+                throw lifecycleError;
+            }
+            // Best-effort fallback when autoDestroy is undefined and called outside component
+        }
+    }
+    return cleanup;
+}
+/**
+ * Listens for the `Escape` key to close or dismiss NUI panels.
+ * In FiveM, ESC is the universal standard for closing NUI windows.
+ *
+ * @param onEscape - Callback function invoked when the Escape key is pressed.
+ * @param options - Optional configuration overriding default key options (`preventDefault` defaults to `true`).
+ * @returns Cleanup function to remove the Escape listener.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useNuiEscape, nui } from '@fivem-nui/svelte';
+ *   useNuiEscape(() => nui.notify('close'));
+ * </script>
+ * ```
+ */
+export function useNuiEscape(onEscape, options = {}) {
+    return useNuiKey(NuiSpecialKey.Escape, onEscape, {
+        preventDefault: true,
+        ...options
+    });
+}
+//# sourceMappingURL=keyboard.js.map

package/dist/utils/keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.js","sourceRoot":"","sources":["../../src/utils/keyboard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@fivem-nui/svelte",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Svelte adapter and toolkit for FiveM NUI communication",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "svelte": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./mock": {
+      "types": "./dist/mock/index.d.ts",
+      "default": "./dist/mock/index.js"
+    },
+    "./actions": {
+      "types": "./dist/actions/index.d.ts",
+      "default": "./dist/actions/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "fivem",
+    "nui",
+    "svelte",
+    "runes",
+    "typescript",
+    "bridge"
+  ],
+  "author": "Rainbe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rian-be/FiveM.Nui.git",
+    "directory": "packages/svelte/bridge"
+  },
+  "bugs": {
+    "url": "https://github.com/rian-be/FiveM.Nui/issues"
+  },
+  "homepage": "https://github.com/rian-be/FiveM.Nui/tree/main/packages/svelte/bridge#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "svelte": ">=5.0.0"
+  },
+  "dependencies": {
+    "@fivem-nui/core": "^1.0.0",
+    "@fivem-nui/error": "^1.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@vitest/coverage-v8": "^5.0.4",
+    "happy-dom": "^21.0.3",
+    "svelte": "^5.0.0",
+    "typescript": "^7.0.2",
+    "vite": "^6.0.0",
+    "vitest": "^5.0.4"
+  }
+}

package/src/actions/clickOutside/clickOutside.ts

@@ -0,0 +1,78 @@
+import type { Action } from 'svelte/action';
+import {
+  type NuiClickOutsideInput,
+  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: Action<HTMLElement, NuiClickOutsideInput> = (
+  node,
+  parameter
+) => {
+  let currentParam = parameter;
+  let controller: AbortController | null = null;
+
+  const handler = createClickOutsideHandler(
+    () => node,
+    () => toClickOutsideOptions(currentParam)
+  );
+
+  function getCapture(): boolean {
+    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();
+    }
+  };
+};

package/src/actions/clickOutside/handler.ts

@@ -0,0 +1,49 @@
+import type { ClickOutsideTarget, NuiClickOutsideParameter } from './types';
+
+/**
+ * Resolves a DOM Element from an Element reference, CSS selector string, or getter function.
+ */
+export function resolveElement(target: ClickOutsideTarget): Element | null {
+  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: () => Element | null | undefined,
+  getOptions: () => NuiClickOutsideParameter | undefined
+) {
+  return (event: PointerEvent) => {
+    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);
+      }
+    }
+  };
+}

package/src/actions/clickOutside/index.ts

@@ -0,0 +1,11 @@
+export { nuiClickOutside } from './clickOutside';
+export {
+  type ClickOutsideTarget,
+  type NuiClickOutsideParameter,
+  type NuiClickOutsideInput,
+  toClickOutsideOptions
+} from './types';
+export {
+  resolveElement,
+  createClickOutsideHandler
+} from './handler';

package/src/actions/clickOutside/types.ts

@@ -0,0 +1,54 @@
+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 function toClickOutsideOptions(
+  param: NuiClickOutsideInput | undefined
+): NuiClickOutsideParameter | undefined {
+  if (!param) return undefined;
+  return typeof param === 'function' ? { onClickOutside: param } : param;
+}

package/src/actions/escape/escape.ts

@@ -0,0 +1,90 @@
+import type { Action } from 'svelte/action';
+import {
+  type NuiEscapeInput,
+  toEscapeOptions
+} from './types';
+import { resolveTarget, createEscapeHandler } from './handler';
+
+/**
+ * Svelte Action for handling Escape key presses in FiveM NUI.
+ *
+ * Designed specifically for FiveM NUI where Escape is the universal close/dismiss action.
+ * Defaults to listening on `document` so closing works without requiring focus on a specific `div`.
+ *
+ * @remarks
+ * **Nested Modals & Target Scoping**:
+ * When using `target: NuiEscapeTarget.Document` (default), all registered listeners on `document` will receive
+ * keydown in registration order. If you have nested modals where only the topmost modal should close,
+ * consider using `nuiLayer` (which manages a centralized layer stack so only the topmost active layer dismisses),
+ * or configure `ignoreHandled: true`, or use `target: NuiEscapeTarget.Element` with a focus trap (`nuiFocusTrap`) and `stopPropagation: true`.
+ *
+ * @param node - The DOM element attaching the action.
+ * @param parameter - Callback function or configuration options object.
+ *
+ * @example
+ * ```svelte
+ * <div use:nuiEscapeAction={() => win.close()}>...</div>
+ * <div use:nuiEscapeAction={{ onEscape: close, stopPropagation: true }}>...</div>
+ * ```
+ */
+export const nuiEscapeAction: Action<HTMLElement, NuiEscapeInput> = (
+  node,
+  parameter
+) => {
+  let currentParam = parameter;
+  let controller: AbortController | null = null;
+
+  const handler = createEscapeHandler(() => toEscapeOptions(currentParam));
+
+  function getTarget(): EventTarget {
+    const opts = toEscapeOptions(currentParam);
+    return resolveTarget(node, opts?.target);
+  }
+
+  function getCapture(): boolean {
+    const opts = toEscapeOptions(currentParam);
+    return opts?.capture ?? false;
+  }
+
+  function setup() {
+    teardown();
+    const eventTarget = getTarget();
+    controller = new AbortController();
+    eventTarget.addEventListener('keydown', handler as EventListener, {
+      capture: getCapture(),
+      signal: controller.signal
+    });
+  }
+
+  function teardown() {
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+  }
+
+  setup();
+
+  return {
+    update(newParam) {
+      const prevOpts = toEscapeOptions(currentParam);
+      currentParam = newParam;
+      const nextOpts = toEscapeOptions(currentParam);
+
+      const prevTarget = resolveTarget(node, prevOpts?.target);
+      const nextTarget = resolveTarget(node, nextOpts?.target);
+      const prevCapture = prevOpts?.capture ?? false;
+      const nextCapture = nextOpts?.capture ?? false;
+
+      // Only target or capture changes require re-binding DOM listeners.
+      // Other options (enabled, onEscape, preventDefault, stopPropagation, ignoreRepeat)
+      // are read dynamically inside createEscapeHandler on each keydown event.
+      if (prevTarget !== nextTarget || prevCapture !== nextCapture) {
+        setup();
+      }
+    },
+    destroy() {
+      teardown();
+    }
+  };
+};

package/src/actions/escape/handler.ts

@@ -0,0 +1,52 @@
+import { NuiEscapeTarget, type NuiEscapeParameter } from './types';
+
+/**
+ * Resolves the appropriate EventTarget to attach the Escape key listener to.
+ */
+export function resolveTarget(node: HTMLElement, targetType?: NuiEscapeTarget): EventTarget {
+  if (targetType === NuiEscapeTarget.Window) return window;
+  if (targetType === NuiEscapeTarget.Element) return node;
+  return document;
+}
+
+/**
+ * Creates a reusable keydown event handler for Escape key detection.
+ * Shared between Svelte action and composable to eliminate duplication.
+ */
+export function createEscapeHandler(
+  getOptions: () => NuiEscapeParameter | undefined
+) {
+  return (event: KeyboardEvent) => {
+    const opts = getOptions();
+    if (!opts || event.key !== 'Escape' || event.isComposing) return;
+
+    if (opts.ignoreHandled && event.defaultPrevented) return;
+
+    const enabled = typeof opts.enabled === 'function' ? opts.enabled() : opts.enabled ?? true;
+    const handler = opts.onEscape ?? opts.callback;
+    if (!enabled || !handler) return;
+
+    if ((opts.ignoreRepeat ?? true) && event.repeat) {
+      if (opts.preventDefault ?? true) {
+        event.preventDefault();
+      }
+      return;
+    }
+
+    if (opts.preventDefault ?? true) {
+      event.preventDefault();
+    }
+    if (opts.stopPropagation) {
+      event.stopPropagation();
+    }
+    if (opts.stopImmediatePropagation) {
+      event.stopImmediatePropagation();
+    }
+
+    try {
+      handler(event);
+    } catch (err) {
+      console.error('[NuiEscape] Error in onEscape callback:', err);
+    }
+  };
+}

package/src/actions/escape/index.ts

@@ -0,0 +1,11 @@
+export { nuiEscapeAction } from './escape';
+export {
+  NuiEscapeTarget,
+  type NuiEscapeParameter,
+  type NuiEscapeInput,
+  toEscapeOptions
+} from './types';
+export {
+  resolveTarget,
+  createEscapeHandler
+} from './handler';

package/src/actions/escape/types.ts

@@ -0,0 +1,88 @@
+export enum NuiEscapeTarget {
+  Element = 'element',
+  Window = 'window',
+  Document = 'document'
+}
+
+export interface NuiEscapeParameter {
+  /**
+   * Callback invoked when the Escape key is pressed.
+   */
+  onEscape?: (event: KeyboardEvent) => void;
+
+  /**
+   * @deprecated Use `onEscape` instead.
+   */
+  callback?: (event: KeyboardEvent) => void;
+
+  /**
+   * Whether the Escape listener is active.
+   * Accepts a boolean or a reactive getter `() => boolean`.
+   * @defaultValue true
+   */
+  enabled?: boolean | (() => boolean);
+
+  /**
+   * Where to attach the listener:
+   * - `NuiEscapeTarget.Document`: listens globally on the document (default; does not require element focus)
+   * - `NuiEscapeTarget.Window`: listens globally on the window
+   * - `NuiEscapeTarget.Element`: listens only for keydown events within this element (requires the element to have focus, e.g. tabindex="-1")
+   * @defaultValue NuiEscapeTarget.Document
+   */
+  target?: NuiEscapeTarget;
+
+  /**
+   * Whether to listen during the capturing phase.
+   * Useful when inner elements might stop propagation before bubbling reaches window/document.
+   * @defaultValue false
+   */
+  capture?: boolean;
+
+  /**
+   * Whether to call `event.preventDefault()`.
+   * @defaultValue true
+   */
+  preventDefault?: boolean;
+
+  /**
+   * Whether to stop event propagation to parent elements.
+   * @defaultValue false
+   */
+  stopPropagation?: boolean;
+
+  /**
+   * Whether to stop immediate propagation to other listeners on the same target.
+   * @defaultValue false
+   */
+  stopImmediatePropagation?: boolean;
+
+  /**
+   * Whether to ignore repeated keydown events fired while holding the Escape key down.
+   *
+   * @remarks
+   * If `true` and `preventDefault: true`, `event.preventDefault()` will still be invoked
+   * on repeated keydown events to suppress browser/CEF default actions, but the callback itself
+   * will only be executed once on the initial keydown.
+   * @defaultValue true
+   */
+  ignoreRepeat?: boolean;
+
+  /**
+   * Whether to ignore the Escape keydown event if an earlier handler has already called `event.preventDefault()`.
+   * Useful when multiple independent Escape listeners are registered on `document` to avoid firing handlers
+   * after an inner/prior component has already handled the event.
+   * @defaultValue false
+   */
+  ignoreHandled?: boolean;
+}
+
+export type NuiEscapeInput =
+  | ((event: KeyboardEvent) => void)
+  | NuiEscapeParameter;
+
+export function toEscapeOptions<T extends NuiEscapeParameter = NuiEscapeParameter>(
+  param?: ((event: KeyboardEvent) => void) | T
+): T | undefined {
+  if (!param) return undefined;
+  return typeof param === 'function' ? ({ onEscape: param } as T) : param;
+}