@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/mock/interceptor.ts

@@ -0,0 +1,177 @@
+import { isNuiUrl, parseNuiUrl } from './url';
+
+export interface InterceptorContext {
+  targetResource: string;
+  latencyMs: number;
+  log: boolean;
+  activeRequests: Record<string, (payload: any) => Promise<any> | any>;
+  activeCallbacks: Record<string, (payload: any) => void>;
+  activeSendHandlers: Record<string, (payload: any) => void>;
+  originalFetch: typeof window.fetch;
+}
+
+/**
+ * Extracts the body payload from a `fetch` invocation, supporting both `init.body`
+ * and body text inside a `Request` instance.
+ */
+export async function extractRequestBody(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): Promise<any> {
+  let bodyText = typeof init?.body === 'string' ? init.body : null;
+  if (!bodyText && typeof Request !== 'undefined' && input instanceof Request) {
+    try {
+      bodyText = await input.clone().text();
+    } catch {
+      // body already consumed or unreadable
+    }
+  }
+
+  if (bodyText) {
+    try {
+      return JSON.parse(bodyText);
+    } catch {
+      return bodyText;
+    }
+  }
+  return null;
+}
+
+/**
+ * Creates the `window.fetch` interceptor function that simulates FiveM CEF transport.
+ */
+export function createFetchInterceptor(ctx: InterceptorContext): typeof window.fetch {
+  const {
+    targetResource,
+    latencyMs,
+    log,
+    activeRequests,
+    activeCallbacks,
+    activeSendHandlers,
+    originalFetch
+  } = ctx;
+
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const url =
+      typeof input === 'string'
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : input.url;
+
+    if (!isNuiUrl(url, targetResource)) {
+      return originalFetch(input, init);
+    }
+
+    const { resourceName, callbackName } = parseNuiUrl(url);
+    const bodyObj = await extractRequestBody(input, init);
+
+    const eventName = bodyObj?.event;
+    const correlationId = bodyObj?.id;
+    const payload = bodyObj?.payload ?? bodyObj?.data;
+    const messageType = bodyObj?.type;
+
+    if (log) {
+      console.debug(
+        `[NUI Mock] -> POST https://${resourceName}/${callbackName} type='${messageType ?? 'event'}' event='${eventName ?? callbackName}' id=${correlationId ?? '-'}`,
+        payload
+      );
+    }
+
+    // Simulate consistent transport latency across all NUI operations
+    if (latencyMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, latencyMs));
+    }
+
+    let handled = false;
+
+    // Check callback notifications
+    if (activeCallbacks[callbackName]) {
+      handled = true;
+      try {
+        activeCallbacks[callbackName](payload);
+      } catch (e) {
+        console.error(`[NUI Mock] Error in callback handler '${callbackName}':`, e);
+      }
+    }
+
+    // Check send handlers
+    if (eventName && activeSendHandlers[eventName]) {
+      handled = true;
+      try {
+        activeSendHandlers[eventName](payload);
+      } catch (e) {
+        console.error(`[NUI Mock] Error in send handler '${eventName}':`, e);
+      }
+    }
+
+    // Handle correlated request/response
+    if (eventName && activeRequests[eventName]) {
+      handled = true;
+      try {
+        const result = await activeRequests[eventName](payload);
+
+        // In FiveM CEF, HTTP POST to https://<resource>/<callback> is strictly an outgoing transport ACK;
+        // the native C# backend delivers the correlated response envelope asynchronously via
+        // SendNuiMessage -> window.postMessage.
+        if (correlationId) {
+          window.postMessage(
+            {
+              type: 'response',
+              id: correlationId,
+              success: true,
+              payload: result,
+              data: result
+            },
+            '*'
+          );
+        }
+
+        return new Response(JSON.stringify({ ok: true }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' }
+        });
+      } catch (err: unknown) {
+        const errorEnvelope = {
+          code: (err as any)?.code ?? 'MOCK_ERROR',
+          message: err instanceof Error ? err.message : String(err)
+        };
+
+        if (correlationId) {
+          window.postMessage(
+            {
+              type: 'response',
+              id: correlationId,
+              success: false,
+              error: errorEnvelope
+            },
+            '*'
+          );
+        }
+
+        return new Response(
+          JSON.stringify({
+            success: false,
+            error: errorEnvelope
+          }),
+          {
+            status: 500,
+            headers: { 'Content-Type': 'application/json' }
+          }
+        );
+      }
+    }
+
+    if (!handled && log) {
+      const targetEvent = eventName ?? callbackName;
+      console.warn(
+        `[NUI Mock] Unhandled NUI message: no mock handler registered for '${targetEvent}'.`
+      );
+    }
+
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  };
+}

package/src/mock/types.ts

@@ -0,0 +1,125 @@
+import type { NuiWindowAction } from '@fivem-nui/core';
+
+/**
+ * Message types for synthetic NUI postMessage envelopes in the mock environment.
+ */
+export enum NuiMessageType {
+  /**
+   * Standard event message.
+   */
+  Event = 'event',
+
+  /**
+   * RPC request message.
+   */
+  Request = 'request',
+
+  /**
+   * RPC response message.
+   */
+  Response = 'response'
+}
+
+/**
+ * Configuration options for {@link setupNuiMock}.
+ */
+export interface NuiMockOptions {
+  /**
+   * Expected FiveM resource name to intercept.
+   * If omitted, falls back to `getResourceName('')` or `'nui'`.
+   */
+  resourceName?: string;
+
+  /**
+   * Mock handlers for requests sent via `nui.request(eventName, payload)`.
+   * Return the response payload or a Promise resolving to it.
+   */
+  requests?: Record<string, (payload: any) => Promise<any> | any>;
+
+  /**
+   * Mock callbacks registered with `nui.notify(callbackName, payload)`.
+   */
+  callbacks?: Record<string, (payload: any) => void>;
+
+  /**
+   * Listeners invoked when UI sends fire-and-forget messages (`nui.send`).
+   */
+  onSend?: Record<string, (payload: any) => void>;
+
+  /**
+   * Delay in milliseconds to simulate network latency in the browser.
+   * @defaultValue 50
+   */
+  latencyMs?: number;
+
+  /**
+   * Whether to log mock events and requests in the browser console.
+   * @defaultValue true
+   */
+  log?: boolean;
+}
+
+/**
+ * Controller interface returned by {@link setupNuiMock} for controlling the mock runtime.
+ */
+export interface NuiMockController {
+  /**
+   * Simulates an event dispatched from C#/server to NUI.
+   *
+   * @param eventName - Name of the simulated event.
+   * @param payload - Optional data payload.
+   * @param delayMs - Optional delay in milliseconds before dispatching.
+   */
+  emitEvent(eventName: string, payload?: unknown, delayMs?: number): void;
+
+  /**
+   * Simulates a window lifecycle action (`'open'`, `'close'`, `'focus'`, `'blur'`).
+   *
+   * @param action - The window lifecycle action.
+   * @param windowName - Optional target window identifier.
+   * @param delayMs - Optional delay in milliseconds before dispatching.
+   */
+  emitWindow(action: NuiWindowAction, windowName?: string, delayMs?: number): void;
+
+  /**
+   * Dynamically adds or updates a request mock handler.
+   *
+   * @param eventName - RPC request event name to intercept.
+   * @param handler - Handler function returning the mock response.
+   * @returns Unsubscribe function to remove the mock handler.
+   */
+  mockRequest<TRequest = unknown, TResponse = unknown>(
+    eventName: string,
+    handler: (payload: TRequest) => Promise<TResponse> | TResponse
+  ): () => void;
+
+  /**
+   * Removes a mock request handler.
+   *
+   * @param eventName - Name of the request to remove.
+   */
+  removeRequest(eventName: string): void;
+
+  /**
+   * Dynamically adds a listener for UI-sent messages (`nui.send`).
+   *
+   * @param eventName - Event name to listen for.
+   * @param handler - Callback invoked with the sent payload.
+   * @returns Unsubscribe function to remove the listener.
+   */
+  onSend<T = unknown>(eventName: string, handler: (payload: T) => void): () => void;
+
+  /**
+   * Restores original window.fetch and cleans up mock handlers.
+   */
+  destroy(): void;
+}
+
+export const NOOP_CONTROLLER: NuiMockController = {
+  emitEvent: () => {},
+  emitWindow: () => {},
+  mockRequest: () => () => {},
+  removeRequest: () => {},
+  onSend: () => () => {},
+  destroy: () => {}
+};

package/src/mock/url.ts

@@ -0,0 +1,37 @@
+/**
+ * Checks whether a given URL matches a targeted FiveM NUI endpoint:
+ * `https://<resourceName>/<callback>` or `https://cfx-nui-<resourceName>/<callback>`.
+ * Rejects localhost, IP addresses, ports, and external domains.
+ */
+export function isNuiUrl(url: string, targetResource: string): boolean {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.port) {
+      return false;
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === 'localhost' || host === '127.0.0.1' || host === '::1' || host.includes('.')) {
+      return false;
+    }
+
+    const expected = targetResource.toLowerCase();
+    return host === expected || host === `cfx-nui-${expected}`;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extracts and safely decodes the resource name and callback endpoint from a NUI URL.
+ */
+export function parseNuiUrl(url: string): { resourceName: string; callbackName: string } {
+  const urlParts = url.replace('https://', '').split('/');
+  const resourceName = urlParts[0];
+  let callbackName = urlParts[1] ?? 'nui';
+  try {
+    callbackName = decodeURIComponent(callbackName);
+  } catch {
+    // malformed URI sequence, keep raw callbackName
+  }
+  return { resourceName, callbackName };
+}

package/src/runes/clickOutside.svelte.ts

@@ -0,0 +1,53 @@
+import { untrack } from 'svelte';
+import {
+  createClickOutsideHandler,
+  type ClickOutsideTarget,
+  type NuiClickOutsideParameter
+} from '../actions/clickOutside';
+
+export type { ClickOutsideTarget, NuiClickOutsideParameter };
+
+/**
+ * Detects clicks outside a target element and invokes a callback.
+ * Automatically cleans up listeners on unmount.
+ *
+ * @param target - Getter returning the target DOM element.
+ * @param getOptions - Getter returning options (onClickOutside, ignore, enabled).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let panelEl = $state<HTMLElement>();
+ *   let triggerEl = $state<HTMLElement>();
+ *   let isOpen = $state(false);
+ *
+ *   useClickOutside(
+ *     () => panelEl,
+ *     () => ({
+ *       onClickOutside: () => { isOpen = false; },
+ *       ignore: [triggerEl],
+ *       enabled: isOpen
+ *     })
+ *   );
+ * </script>
+ * ```
+ */
+export function useClickOutside(
+  target: () => Element | null | undefined,
+  getOptions: () => NuiClickOutsideParameter
+): void {
+  const handler = createClickOutsideHandler(target, getOptions);
+
+  $effect(() => {
+    if (!target()) return;
+
+    const capture = untrack(() => getOptions().capture ?? true);
+    const ac = new AbortController();
+    document.addEventListener('pointerdown', handler, {
+      capture,
+      signal: ac.signal
+    });
+
+    return () => ac.abort();
+  });
+}

package/src/runes/escape.svelte.ts

@@ -0,0 +1,71 @@
+import { untrack } from 'svelte';
+import {
+  createEscapeHandler,
+  toEscapeOptions,
+  type NuiEscapeParameter,
+  NuiEscapeTarget
+} from '../actions/escape';
+
+export { NuiEscapeTarget };
+
+export type NuiEscapeComposableParameter = Omit<NuiEscapeParameter, 'target'> & {
+  /**
+   * Where to attach the global listener:
+   * - `'document'` / `NuiEscapeTarget.Document`: listens globally on the document (default)
+   * - `'window'` / `NuiEscapeTarget.Window`: listens globally on the window
+   *
+   * Note: To scope Escape to a specific DOM element with focus, use the `nuiEscapeAction` action instead.
+   * @defaultValue NuiEscapeTarget.Document
+   */
+  target?: NuiEscapeTarget.Window | NuiEscapeTarget.Document;
+};
+
+export type NuiEscapeComposableInput =
+  | ((event: KeyboardEvent) => void)
+  | NuiEscapeComposableParameter;
+
+/**
+ * Listens for the Escape key and invokes a callback.
+ * Automatically cleans up listeners on unmount.
+ *
+ * @param getOptions - Getter returning options or an onEscape callback.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let isOpen = $state(false);
+ *
+ *   useEscape(() => ({
+ *     onEscape: () => { isOpen = false; },
+ *     enabled: isOpen
+ *   }));
+ * </script>
+ * ```
+ */
+export function useEscape(
+  getOptions: () => NuiEscapeComposableInput
+): void {
+  const normalized = () => toEscapeOptions<NuiEscapeComposableParameter>(getOptions());
+  const handler = createEscapeHandler(normalized);
+
+  $effect(() => {
+    // Intentionally untracked: attach the DOM listener once upon mount,
+    // preserving event listener order. Reactive state (`enabled`, `onEscape`, etc.)
+    // is read lazily on each keydown event. Cleanup is called on component unmount.
+    const { target, capture } = untrack(() => {
+      const o = normalized();
+      return {
+        target: o?.target === NuiEscapeTarget.Window ? window : document,
+        capture: o?.capture ?? false
+      };
+    });
+
+    const ac = new AbortController();
+    target.addEventListener('keydown', handler as EventListener, {
+      capture,
+      signal: ac.signal
+    });
+
+    return () => ac.abort();
+  });
+}

package/src/runes/focusTrap.svelte.ts

@@ -0,0 +1,56 @@
+import { untrack } from 'svelte';
+import {
+  nuiFocusTrap,
+  type NuiFocusTrapInput,
+  type NuiFocusTrapOptions,
+  type FocusTrapAllowOutsideTarget,
+  type FocusTrapAllowOutside
+} from '../actions/focusTrap';
+
+export type {
+  NuiFocusTrapInput,
+  NuiFocusTrapOptions,
+  FocusTrapAllowOutsideTarget,
+  FocusTrapAllowOutside
+};
+
+/**
+ * Traps Tab key navigation inside a container element.
+ * Automatically activates and tears down as the target element mounts/unmounts.
+ *
+ * @param target - Getter returning the container element.
+ * @param getOptions - Optional getter returning options or boolean enabled flag.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let modalEl = $state<HTMLElement>();
+ *   let isOpen = $state(false);
+ *
+ *   useFocusTrap(() => modalEl, () => isOpen);
+ * </script>
+ * ```
+ */
+export function useFocusTrap(
+  target: () => HTMLElement | null | undefined,
+  getOptions?: () => NuiFocusTrapInput
+): void {
+  let action: ReturnType<typeof nuiFocusTrap> | undefined;
+
+  $effect(() => {
+    const node = target();
+    if (!node) return;
+
+    action = nuiFocusTrap(node, untrack(() => getOptions?.() ?? true));
+
+    return () => {
+      action?.destroy?.();
+      action = undefined;
+    };
+  });
+
+  $effect(() => {
+    const opts = getOptions?.() ?? true;
+    action?.update?.(opts);
+  });
+}

package/src/runes/index.svelte.ts

@@ -0,0 +1,38 @@
+export {
+  useNuiState,
+  NuiStateController,
+  type NuiState,
+  type NuiStateOptions
+} from './state.svelte';
+
+export {
+  useNuiQuery,
+  NuiQueryController,
+  type NuiQuery,
+  type NuiQueryOptions,
+  NuiQueryStatus
+} from './query.svelte';
+
+export {
+  useNuiWindow,
+  NuiWindowController,
+  type NuiWindow,
+  type NuiWindowOptions,
+  NuiWindowActionType,
+  NuiWindowNotification
+} from './window.svelte';
+
+export { useClickOutside } from './clickOutside.svelte';
+
+export {
+  useEscape,
+  type NuiEscapeComposableParameter,
+  type NuiEscapeComposableInput
+} from './escape.svelte';
+
+export { useFocusTrap } from './focusTrap.svelte';
+
+export {
+  useLayer,
+  type NuiLayerComposableInput
+} from './layer.svelte';

package/src/runes/layer.svelte.ts

@@ -0,0 +1,74 @@
+import { untrack } from 'svelte';
+import {
+  nuiLayer,
+  NuiLayerDismissReason,
+  type NuiLayerInput,
+  type NuiLayerOptions,
+  type LayerInstance
+} from '../actions/layer';
+
+export {
+  NuiLayerDismissReason
+};
+
+export type {
+  NuiLayerInput,
+  NuiLayerOptions,
+  LayerInstance
+};
+
+/**
+ * Reactive options getter for `useLayer`.
+ */
+export type NuiLayerComposableInput = () => NuiLayerOptions;
+
+/**
+ * Manages an overlay layer (modal, dialog, drawer) in FiveM NUI.
+ * Coordinates Escape key, outside click, and focus trapping through a central layer stack.
+ *
+ * @param target - Getter returning the container element.
+ * @param getOptions - Optional getter returning layer options.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let modalEl = $state<HTMLElement>();
+ *   let isOpen = $state(false);
+ *
+ *   useLayer(
+ *     () => modalEl,
+ *     () => ({ onDismiss: () => { isOpen = false; }, enabled: isOpen })
+ *   );
+ * </script>
+ *
+ * {#if isOpen}
+ *   <div bind:this={modalEl} class="modal">
+ *     <h2>Modal</h2>
+ *     <button onclick={() => { isOpen = false; }}>Close</button>
+ *   </div>
+ * {/if}
+ * ```
+ */
+export function useLayer(
+  target: () => HTMLElement | null | undefined,
+  getOptions?: () => NuiLayerOptions
+): void {
+  let action: ReturnType<typeof nuiLayer> | undefined;
+
+  $effect(() => {
+    const node = target();
+    if (!node) return;
+
+    action = nuiLayer(node, untrack(() => getOptions?.()));
+
+    return () => {
+      action?.destroy?.();
+      action = undefined;
+    };
+  });
+
+  $effect(() => {
+    const opts = getOptions?.();
+    action?.update?.(opts);
+  });
+}