@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/runes/window.svelte.ts

@@ -0,0 +1,308 @@
+import { onDestroy } from 'svelte';
+import type { NuiWindowAction } from '@fivem-nui/core';
+import { globalErrorHandler } from '@fivem-nui/error';
+import type { SvelteNuiClient } from '../client';
+import { useNuiClient } from '../context';
+
+/**
+ * Window lifecycle actions dispatched from C# backend to NUI UI.
+ */
+export enum NuiWindowActionType {
+  Open = 'open',
+  Close = 'close',
+  Focus = 'focus',
+  Unfocus = 'unfocus'
+}
+
+/**
+ * Window lifecycle notifications dispatched from UI to C# backend.
+ */
+export enum NuiWindowNotification {
+  Ready = 'ready',
+  Close = 'close'
+}
+
+export interface NuiWindowOptions {
+  /**
+   * Explicit client instance override.
+   * Defaults to the client provided via context (`useNuiClient()`) or global client.
+   */
+  client?: SvelteNuiClient;
+
+  /**
+   * Initial visibility without focus or backend notification.
+   * @defaultValue false
+   */
+  initialVisible?: boolean;
+
+  /**
+   * Automatically closes the window when Escape is pressed.
+   * @defaultValue true
+   */
+  closeOnEscape?: boolean;
+
+  /**
+   * Callback invoked when window visibility changes from hidden to visible.
+   */
+  onOpen?: () => void;
+
+  /**
+   * Callback invoked when window visibility changes from visible to hidden.
+   */
+  onClose?: () => void;
+
+  /**
+   * Callback invoked when window focus state changes.
+   */
+  onFocusChange?: (focused: boolean) => void;
+
+  /**
+   * Controls automatic cleanup through Svelte's component lifecycle.
+   *
+   * - `true`: Strictly requires component initialization lifecycle; throws if called outside.
+   * - `false`: Disables automatic lifecycle cleanup; call `destroy()` manually.
+   * - `undefined`: Attempts automatic cleanup, falling back to manual cleanup outside components.
+   *
+   * @defaultValue undefined
+   */
+  autoDestroy?: boolean;
+}
+
+/**
+ * Controller interface representing a reactive NUI window.
+ */
+export interface NuiWindow {
+  /** Whether the window is currently visible. */
+  readonly visible: boolean;
+
+  /** Whether the window currently has input focus. */
+  readonly focused: boolean;
+
+  /** Opens the window, sets focused to true, and sends a 'ready' notification to C#. */
+  open(): void;
+
+  /** Closes the window, clears focus, and sends a 'close' notification to C#. */
+  close(): void;
+
+  /** Toggles window visibility between open and closed. */
+  toggle(): void;
+
+  /** Destroys the window controller, unsubscribing from C# window events and key listeners. */
+  destroy(): void;
+}
+
+function safeCallback<TArgs extends unknown[]>(
+  operation: string,
+  callback: ((...args: TArgs) => void) | undefined,
+  ...args: TArgs
+): void {
+  if (!callback) return;
+
+  try {
+    callback(...args);
+  } catch (error) {
+    void globalErrorHandler
+      .handle(
+        error instanceof Error ? error : new Error(String(error)),
+        { args },
+        operation
+      )
+      .catch(() => {});
+    console.error(error);
+  }
+}
+
+/**
+ * Controller managing reactive visibility, focus, and backend events for a named NUI window.
+ */
+export class NuiWindowController implements NuiWindow {
+  visible = $state(false);
+  focused = $state(false);
+
+  private destroyed = false;
+  private listeningForEscape = false;
+  private readonly unsubscribe: () => void;
+
+  constructor(
+    private readonly windowName: string,
+    private readonly options: NuiWindowOptions = {},
+    private readonly client: SvelteNuiClient
+  ) {
+    this.visible = options.initialVisible ?? false;
+    this.unsubscribe = client.onWindow(this.handleWindowAction);
+
+    if (this.visible) {
+      this.syncEscapeListener(true);
+    }
+  }
+
+  private syncEscapeListener(shouldListen: boolean): void {
+    if (typeof window === 'undefined' || this.options.closeOnEscape === false) return;
+    if (this.listeningForEscape === shouldListen) return;
+
+    if (shouldListen) {
+      window.addEventListener('keydown', this.handleEscape);
+    } else {
+      window.removeEventListener('keydown', this.handleEscape);
+    }
+
+    this.listeningForEscape = shouldListen;
+  }
+
+  private handleEscape = (event: KeyboardEvent): void => {
+    if (event.key !== 'Escape' || !this.visible || this.destroyed) return;
+
+    event.preventDefault();
+    this.close();
+  };
+
+  private transition(
+    nextVisible?: boolean,
+    nextFocused?: boolean
+  ): { visibility: boolean; focus: boolean } {
+    const changes = {
+      visibility: nextVisible !== undefined && this.visible !== nextVisible,
+      focus: nextFocused !== undefined && this.focused !== nextFocused
+    };
+
+    if (nextVisible !== undefined && changes.visibility) {
+      this.visible = nextVisible;
+      this.syncEscapeListener(nextVisible);
+    }
+
+    if (nextFocused !== undefined && changes.focus) {
+      this.focused = nextFocused;
+    }
+
+    return changes;
+  }
+
+  private notifyAndDispatch(
+    changes: { visibility: boolean; focus: boolean },
+    notification?: NuiWindowNotification
+  ): void {
+    if (notification && (changes.visibility || changes.focus)) {
+      try {
+        this.client.notify(notification, { window: this.windowName });
+      } catch (error) {
+        void globalErrorHandler
+          .handle(
+            error instanceof Error ? error : new Error(String(error)),
+            { window: this.windowName, notification },
+            'useNuiWindow:notify'
+          )
+          .catch(() => {});
+        console.error('[NuiWindow] Failed to dispatch notify to backend:', error);
+      }
+    }
+
+    if (changes.visibility) {
+      safeCallback('useNuiWindow:visibility', this.visible ? this.options.onOpen : this.options.onClose);
+    }
+
+    if (changes.focus) {
+      safeCallback('useNuiWindow:focus', this.options.onFocusChange, this.focused);
+    }
+  }
+
+  open = (): void => {
+    if (this.destroyed) return;
+
+    const changes = this.transition(true, true);
+    this.notifyAndDispatch(changes, NuiWindowNotification.Ready);
+  };
+
+  close = (): void => {
+    if (this.destroyed) return;
+
+    const changes = this.transition(false, false);
+    this.notifyAndDispatch(changes, NuiWindowNotification.Close);
+  };
+
+  toggle = (): void => {
+    if (this.destroyed) return;
+
+    if (this.visible) this.close();
+    else this.open();
+  };
+
+  private handleWindowAction = (
+    action: NuiWindowAction,
+    targetWindow: string | undefined
+  ): void => {
+    if (this.destroyed || (targetWindow && targetWindow !== this.windowName)) {
+      return;
+    }
+
+    switch (action) {
+      case NuiWindowActionType.Open:
+        this.notifyAndDispatch(this.transition(true, true));
+        break;
+
+      case NuiWindowActionType.Close:
+        this.notifyAndDispatch(this.transition(false, false));
+        break;
+
+      case NuiWindowActionType.Focus:
+        if (this.visible) {
+          this.notifyAndDispatch(this.transition(undefined, true));
+        }
+        break;
+
+      case NuiWindowActionType.Unfocus:
+        this.notifyAndDispatch(this.transition(undefined, false));
+        break;
+    }
+  };
+
+  destroy = (): void => {
+    if (this.destroyed) return;
+
+    this.destroyed = true;
+    this.syncEscapeListener(false);
+    this.unsubscribe();
+  };
+}
+
+/**
+ * Reactive controller for a named NUI window.
+ * Synchronizes visibility and focus states with the FiveM C# backend.
+ *
+ * @param windowName - Window identifier matching backend events.
+ * @param options - Optional configuration (callbacks, Escape handling).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useNuiWindow } from '@fivem-nui/svelte';
+ *
+ *   const win = useNuiWindow('inventory', { closeOnEscape: true });
+ * </script>
+ *
+ * {#if win.visible}
+ *   <div class="panel">
+ *     <button onclick={() => win.close()}>Close</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export function useNuiWindow(
+  windowName: string,
+  options: NuiWindowOptions = {}
+): NuiWindow {
+  const client = options.client ?? useNuiClient();
+  const controller = new NuiWindowController(windowName, options, client);
+
+  if (options.autoDestroy !== false) {
+    try {
+      onDestroy(controller.destroy);
+    } catch (error) {
+      if (options.autoDestroy === true) {
+        controller.destroy();
+        throw error;
+      }
+    }
+  }
+
+  return controller;
+}

package/src/utils/env.ts

@@ -0,0 +1,36 @@
+/**
+ * Detects whether the current page is running inside FiveM's Chromium Embedded Framework (CEF).
+ * In FiveM CEF, `window.GetParentResourceName` is injected as a native global function.
+ *
+ * @returns `true` if executing within FiveM CEF, `false` otherwise.
+ */
+export function isNui(): boolean {
+  return typeof (globalThis as { GetParentResourceName?: unknown }).GetParentResourceName === 'function';
+}
+
+/**
+ * Returns true when running in a standard browser (Vite dev server, standalone preview), outside FiveM.
+ *
+ * @returns `true` if running in a standard browser outside FiveM, `false` if inside CEF.
+ */
+export function isBrowser(): boolean {
+  return !isNui();
+}
+
+/**
+ * Safely resolves the parent resource name if running in FiveM CEF, or returns fallback in browser.
+ *
+ * @param fallback - Resource name to return if not running in FiveM CEF or if resolution fails.
+ * @returns The FiveM resource name or the provided fallback.
+ */
+export function getResourceName(fallback = 'unknown_resource'): string {
+  const g = globalThis as { GetParentResourceName?: () => string };
+  if (typeof g.GetParentResourceName === 'function') {
+    try {
+      return g.GetParentResourceName();
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './env';
+export * from './keyboard';

package/src/utils/keyboard.ts

@@ -0,0 +1,244 @@
+import { onDestroy } from 'svelte';
+
+/**
+ * Keyboard modifier keys.
+ */
+export enum NuiKeyboardModifier {
+  Ctrl = 'ctrl',
+  Alt = 'alt',
+  Shift = 'shift',
+  Meta = 'meta'
+}
+
+/**
+ * Standard special key names commonly used in FiveM NUI shortcuts.
+ */
+export enum NuiSpecialKey {
+  Escape = 'Escape',
+  Enter = 'Enter',
+  Tab = 'Tab',
+  Space = ' ',
+  Backspace = 'Backspace',
+  ArrowUp = 'ArrowUp',
+  ArrowDown = 'ArrowDown',
+  ArrowLeft = 'ArrowLeft',
+  ArrowRight = 'ArrowRight'
+}
+
+/**
+ * Configuration options for keyboard event handlers and shortcuts.
+ */
+export interface KeyOptions {
+  /**
+   * Listen during capture phase.
+   * @defaultValue false
+   */
+  capture?: boolean;
+
+  /**
+   * Automatically call `event.preventDefault()`.
+   * @defaultValue false
+   */
+  preventDefault?: boolean;
+
+  /**
+   * Automatically call `event.stopPropagation()`.
+   * @defaultValue false
+   */
+  stopPropagation?: boolean;
+
+  /**
+   * Whether the key shortcut is enabled.
+   * Accepts a static boolean or a reactive getter `() => boolean`.
+   * @defaultValue true
+   */
+  enabled?: boolean | (() => boolean);
+
+  /**
+   * If true, suppresses shortcut execution when the active element is an input,
+   * textarea, select, or contenteditable.
+   * Crucial in FiveM NUI panels to prevent game hotkeys firing while typing messages/searches.
+   * @defaultValue false
+   */
+  ignoreInputs?: boolean;
+
+  /**
+   * Ignore repeating keydown events triggered while holding a key down.
+   * @defaultValue false
+   */
+  ignoreRepeat?: boolean;
+
+  /**
+   * Require Ctrl key to be pressed (or Cmd on Mac).
+   */
+  ctrl?: boolean;
+
+  /**
+   * Require Alt key to be pressed.
+   */
+  alt?: boolean;
+
+  /**
+   * Require Shift key to be pressed.
+   */
+  shift?: boolean;
+
+  /**
+   * Require Meta (Windows / Cmd) key to be pressed.
+   */
+  meta?: boolean;
+
+  /**
+   * Component lifecycle registration strategy:
+   * - `true`: Strictly requires component initialization lifecycle; registers `onDestroy`.
+   *   If called outside a component, unsubscribes immediately to prevent memory leaks and throws.
+   * - `false`: Disables automatic lifecycle cleanup. The caller must invoke the returned cleanup function manually.
+   * - `undefined` (default): Attempts to register `onDestroy` within a component lifecycle;
+   *   falls back gracefully to manual cleanup if called outside a component.
+   * @defaultValue undefined
+   */
+  autoDestroy?: boolean;
+}
+
+function isTextInputActive(): boolean {
+  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: string | string[],
+  handler: (event: KeyboardEvent) => void,
+  options: KeyOptions = {}
+): () => void {
+  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: AbortController | null = null;
+
+  function isAllowed(): boolean {
+    if (enabled === undefined) return true;
+    return typeof enabled === 'function' ? enabled() : enabled;
+  }
+
+  function onKeyDown(event: KeyboardEvent) {
+    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: (event: KeyboardEvent) => void,
+  options: KeyOptions = {}
+): () => void {
+  return useNuiKey(NuiSpecialKey.Escape, onEscape, {
+    preventDefault: true,
+    ...options
+  });
+}