@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/actions/layer/layer.ts

@@ -0,0 +1,140 @@
+import type { Action } from 'svelte/action';
+import { nuiFocusTrap, type NuiFocusTrapOptions } from '../focusTrap';
+import {
+  type NuiLayerOptions,
+  type NuiLayerInput,
+  type LayerInstance,
+  toLayerOptions
+} from './types';
+import {
+  pushLayer,
+  removeLayer,
+  getTopLayer,
+  nextLayerId
+} from './layerStack';
+
+/**
+ * Managing an overlay layer in FiveM NUI.
+ *
+ * Coordinates:
+ * - **Escape key**: Traverses the layer stack top-to-bottom. The topmost active layer that handles Escape
+ *   receives the event and dismisses. If the topmost layer disables Escape (`onEscape: false`),
+ *   lower layers can handle it.
+ * - **Outside click**: Evaluates strictly the topmost active layer. If the topmost layer disables outside
+ *   clicks (`onClickOutside: false`), clicks outside are blocked and do NOT fall through to underlying layers,
+ *   preserving modal barrier isolation.
+ * - **Focus trap**: Integrates `nuiFocusTrap` synchronized with layer priority so focus containment and Tab
+ *   navigation are enforced by the topmost layer even when layers have varying priorities.
+ * - **Portal integration**: `allowOutside` allows portaled children (selects, datepickers, tooltips)
+ *   without triggering outside clicks or breaking focus containment.
+ *
+ * @param node - The DOM element attaching the layer action.
+ * @param parameter - Dismissal callback function or layer configuration options object.
+ *
+ * @example
+ * ```svelte
+ * <div use:nuiLayer={() => (isOpen = false)}>...</div>
+ * <div use:nuiLayer={{ onDismiss: close, allowOutside: '.portal-menu' }}>...</div>
+ * ```
+ */
+export const nuiLayer: Action<HTMLElement, NuiLayerInput> = (node, parameter) => {
+  let currentParam = parameter;
+  let active = false;
+  let trapAction: ReturnType<typeof nuiFocusTrap> | null = null;
+  const id = toLayerOptions(parameter).id ?? nextLayerId();
+
+  function getOptions(): NuiLayerOptions {
+    return toLayerOptions(currentParam);
+  }
+
+  function isEnabled(): boolean {
+    const opts = getOptions();
+    const { enabled } = opts;
+    return typeof enabled === 'function' ? enabled() : (enabled ?? true);
+  }
+
+  const instance: LayerInstance = {
+    id,
+    node,
+    getOptions
+  };
+
+  function syncFocusTrap() {
+    const opts = getOptions();
+    const enabled = isEnabled();
+
+    if (!enabled || opts.trapFocus === false) {
+      if (trapAction) {
+        trapAction.destroy?.();
+        trapAction = null;
+      }
+      return;
+    }
+
+    const trapConfig: NuiFocusTrapOptions =
+      typeof opts.trapFocus === 'object' ? { ...opts.trapFocus } : {};
+
+    if (trapConfig.allowOutside === undefined && opts.allowOutside !== undefined) {
+      trapConfig.allowOutside = opts.allowOutside;
+    }
+    if (trapConfig.initialFocus === undefined && opts.initialFocus !== undefined) {
+      trapConfig.initialFocus = opts.initialFocus;
+    }
+    if (trapConfig.returnFocus === undefined && opts.returnFocus !== undefined) {
+      trapConfig.returnFocus = opts.returnFocus;
+    }
+    if (trapConfig.autofocus === undefined && opts.autofocus !== undefined) {
+      trapConfig.autofocus = opts.autofocus;
+    }
+    trapConfig.enabled = enabled;
+    trapConfig.isTopmost = () => getTopLayer() === instance;
+
+    if (!trapAction) {
+      trapAction = nuiFocusTrap(node, trapConfig);
+    } else {
+      trapAction.update?.(trapConfig);
+    }
+  }
+
+  function setup() {
+    if (active) return;
+    active = true;
+    pushLayer(instance);
+    syncFocusTrap();
+  }
+
+  function deactivate() {
+    if (!active) return;
+    active = false;
+
+    if (trapAction) {
+      trapAction.destroy?.();
+      trapAction = null;
+    }
+
+    removeLayer(instance);
+  }
+
+  if (isEnabled()) {
+    setup();
+  }
+
+  return {
+    update(newParam) {
+      const wasEnabled = active;
+      currentParam = newParam;
+      const nowEnabled = isEnabled();
+
+      if (!wasEnabled && nowEnabled) {
+        setup();
+      } else if (wasEnabled && !nowEnabled) {
+        deactivate();
+      } else if (nowEnabled) {
+        syncFocusTrap();
+      }
+    },
+    destroy() {
+      deactivate();
+    }
+  };
+};

package/src/actions/layer/layerStack.ts

@@ -0,0 +1,169 @@
+import { NuiLayerDismissReason, type LayerInstance } from './types';
+import { isNodeAllowedOutside } from '../focusTrap';
+import { resolveElement } from '../clickOutside';
+
+/**
+ * Global stack of active overlay layers.
+ * Manages hierarchical Escape key and outside click handling across modals, dialogs,
+ * drawers, and portaled overlays in FiveM NUI.
+ */
+const layerStack: LayerInstance[] = [];
+
+let globalController: AbortController | null = null;
+let layerIdCounter = 0;
+
+export function nextLayerId(): string {
+  return `nui-layer-${++layerIdCounter}`;
+}
+
+export function pushLayer(instance: LayerInstance): void {
+  layerStack.push(instance);
+  ensureGlobalListeners();
+}
+
+export function removeLayer(instance: LayerInstance): void {
+  const idx = layerStack.findIndex((l) => l === instance);
+  if (idx !== -1) {
+    layerStack.splice(idx, 1);
+  }
+  cleanupGlobalListeners();
+}
+
+export function getLayerStack(): readonly LayerInstance[] {
+  return [...layerStack];
+}
+
+export function resetLayerStack(): void {
+  layerStack.length = 0;
+  cleanupGlobalListeners();
+}
+
+function getSortedStack(): LayerInstance[] {
+  return [...layerStack].sort((a, b) => {
+    return (a.getOptions().priority ?? 0) - (b.getOptions().priority ?? 0);
+  });
+}
+
+export function getTopLayer(): LayerInstance | undefined {
+  const sorted = getSortedStack();
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const layer = sorted[i];
+    const opts = layer.getOptions();
+    const isEnabled = typeof opts.enabled === 'function' ? opts.enabled() : (opts.enabled ?? true);
+    if (isEnabled && layer.node.isConnected) {
+      return layer;
+    }
+  }
+  return undefined;
+}
+
+function onGlobalKeyDown(event: KeyboardEvent) {
+  if (event.key !== 'Escape' || event.isComposing) return;
+  if (layerStack.length === 0) return;
+
+  const sorted = getSortedStack();
+
+  // Find the topmost active layer that handles Escape
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const layer = sorted[i];
+    const opts = layer.getOptions();
+    const isEnabled = typeof opts.enabled === 'function' ? opts.enabled() : (opts.enabled ?? true);
+    if (!isEnabled || !layer.node.isConnected) continue;
+
+    const handlesEscape =
+      opts.onEscape !== false &&
+      (typeof opts.onEscape === 'function' || typeof opts.onDismiss === 'function');
+
+    if (!handlesEscape) continue;
+
+    if ((opts.ignoreRepeat ?? true) && event.repeat) {
+      if (opts.preventEscapeDefault ?? true) {
+        event.preventDefault();
+      }
+      return;
+    }
+
+    if (opts.preventEscapeDefault ?? true) {
+      event.preventDefault();
+    }
+    if (opts.stopEscapePropagation) {
+      event.stopPropagation();
+    }
+
+    try {
+      if (typeof opts.onEscape === 'function') {
+        opts.onEscape(event);
+      } else if (typeof opts.onDismiss === 'function') {
+        opts.onDismiss(NuiLayerDismissReason.Escape);
+      }
+    } catch (err) {
+      console.error('[NuiLayer] Error in onEscape/onDismiss callback:', err);
+    }
+
+    // Only the topmost handling layer responds to Escape
+    return;
+  }
+}
+
+function onGlobalPointerDown(event: PointerEvent) {
+  if (event.button !== 0 || layerStack.length === 0) return;
+
+  const topLayer = getTopLayer();
+  if (!topLayer) return;
+
+  const opts = topLayer.getOptions();
+  const handlesOutside =
+    opts.onClickOutside !== false &&
+    (typeof opts.onClickOutside === 'function' || typeof opts.onDismiss === 'function');
+
+  if (!handlesOutside) return;
+
+  const path = event.composedPath();
+
+  // 1. Click inside top layer node
+  if (path.includes(topLayer.node)) return;
+
+  // 2. Click inside any allowed outside target (e.g. portaled dropdown)
+  if (opts.allowOutside && isNodeAllowedOutside(event.target as Node | null, opts.allowOutside)) {
+    return;
+  }
+
+  // 3. Click inside any ignoreOutside target (e.g. trigger button)
+  if (opts.ignoreOutside) {
+    for (const item of opts.ignoreOutside) {
+      const el = resolveElement(item);
+      if (el && path.includes(el)) return;
+    }
+  }
+
+  // Trigger outside click for the topmost layer only
+  try {
+    if (typeof opts.onClickOutside === 'function') {
+      opts.onClickOutside(event);
+    } else if (typeof opts.onDismiss === 'function') {
+      opts.onDismiss(NuiLayerDismissReason.Outside);
+    }
+  } catch (err) {
+    console.error('[NuiLayer] Error in onClickOutside/onDismiss callback:', err);
+  }
+}
+
+export function ensureGlobalListeners(): void {
+  if (globalController || layerStack.length === 0) return;
+  globalController = new AbortController();
+  document.addEventListener('keydown', onGlobalKeyDown, {
+    capture: true,
+    signal: globalController.signal
+  });
+  document.addEventListener('pointerdown', onGlobalPointerDown, {
+    capture: true,
+    signal: globalController.signal
+  });
+}
+
+export function cleanupGlobalListeners(): void {
+  if (layerStack.length === 0 && globalController) {
+    globalController.abort();
+    globalController = null;
+  }
+}

package/src/actions/layer/types.ts

@@ -0,0 +1,132 @@
+import type { NuiFocusTrapOptions, FocusTrapAllowOutside } from '../focusTrap';
+import type { ClickOutsideTarget } from '../clickOutside';
+
+export enum NuiLayerDismissReason {
+  Escape = 'escape',
+  Outside = 'outside'
+}
+
+export interface NuiLayerOptions {
+  /**
+   * Unique identifier for the layer.
+   * Auto-generated if omitted.
+   */
+  id?: string;
+
+  /**
+   * Whether the layer is active in the layer stack.
+   * Accepts a boolean or a reactive getter `() => boolean`.
+   * @defaultValue true
+   */
+  enabled?: boolean | (() => boolean);
+
+  /**
+   * Unified callback invoked when the layer should be dismissed
+   * (either via Escape key or outside click while topmost).
+   */
+  onDismiss?: (reason: NuiLayerDismissReason) => void;
+
+  /**
+   * Specific callback invoked when the Escape key is pressed while this layer is topmost.
+   * Set to `false` to disable Escape handling for this layer.
+   */
+  onEscape?: ((event: KeyboardEvent) => void) | boolean;
+
+  /**
+   * Specific callback invoked when a click occurs outside this layer while it is topmost.
+   * Set to `false` to disable outside click handling for this layer.
+   */
+  onClickOutside?: ((event: PointerEvent) => void) | boolean;
+
+  /**
+   * Focus trap configuration for this layer:
+   * - `true`: enables default focus trap (default)
+   * - `false`: disables focus trap
+   * - `NuiFocusTrapOptions`: custom focus trap options (initialFocus, returnFocus, autofocus, etc.)
+   *
+   * @remarks
+   * `nuiLayer` automatically controls and overrides `trapFocus.isTopmost` so focus containment
+   * is synchronized strictly with layer priority (`getTopLayer() === instance`).
+   * @defaultValue true
+   */
+  trapFocus?: boolean | NuiFocusTrapOptions;
+
+  /**
+   * Elements, selectors, or getters outside the container that are permitted.
+   * Shared between focus trap (won't redirect Tab from them) and click-outside (won't dismiss on them).
+   * Essential for portaled child elements (e.g. dropdowns, date pickers, tooltips).
+   */
+  allowOutside?: FocusTrapAllowOutside;
+
+  /**
+   * Additional elements, selectors, or getters to ignore specifically for click-outside detection
+   * (e.g. the toggle or trigger button that opened this layer).
+   */
+  ignoreOutside?: ClickOutsideTarget[];
+
+  /**
+   * Custom element, selector or getter to receive initial focus upon activation.
+   * Shorthand for `trapFocus.initialFocus`.
+   */
+  initialFocus?: HTMLElement | string | (() => HTMLElement | null | undefined);
+
+  /**
+   * Whether to restore focus to previously focused element upon layer deactivation.
+   * Shorthand for `trapFocus.returnFocus`.
+   * @defaultValue true
+   */
+  returnFocus?: boolean | HTMLElement;
+
+  /**
+   * Whether to automatically move focus inside the layer on activation.
+   * Shorthand for `trapFocus.autofocus`.
+   * @defaultValue true
+   */
+  autofocus?: boolean;
+
+  /**
+   * Priority/z-index override. Layers with higher priority are considered on top
+   * regardless of activation order. Equal priority layers follow activation order.
+   * @defaultValue 0
+   */
+  priority?: number;
+
+  /**
+   * Whether to ignore repeated keydown events fired while holding the Escape key down.
+   * If `true`, holding Escape will not dismiss subsequent layers in rapid succession.
+   * @defaultValue true
+   */
+  ignoreRepeat?: boolean;
+
+  /**
+   * Whether to call `event.preventDefault()` when Escape is handled.
+   * @defaultValue true
+   */
+  preventEscapeDefault?: boolean;
+
+  /**
+   * Whether to call `event.stopPropagation()` when Escape is handled.
+   * Defaults to `false` to avoid breaking uncoordinated parent listeners on window/document.
+   * @defaultValue false
+   */
+  stopEscapePropagation?: boolean;
+}
+
+export type NuiLayerInput =
+  | ((reason: NuiLayerDismissReason) => void)
+  | NuiLayerOptions
+  | undefined;
+
+export function toLayerOptions(input: NuiLayerInput): NuiLayerOptions {
+  if (!input) return { enabled: true };
+  if (typeof input === 'function') {
+    return { enabled: true, onDismiss: input };
+  }
+  return input;
+}
+
+export interface LayerInstance {
+  id: string;
+  node: HTMLElement;
+  getOptions: () => NuiLayerOptions;
+}