@fivem-nui/svelte 0.0.0-stage → 1.0.0

package/src/actions/focusTrap/focusTrap.ts

@@ -0,0 +1,228 @@
+import type { Action } from 'svelte/action';
+import {
+  getFocusables,
+  resolveInitialElement,
+  handleTabKey
+} from './focusables';
+import {
+  type FocusTrapEntry,
+  getTopTrap,
+  isNodeAllowedOutside,
+  pushTrap,
+  removeTrap
+} from './trapStack';
+import {
+  type NuiFocusTrapInput,
+  toFocusTrapOptions
+} from './types';
+
+/**
+ * Svelte Action for trapping Tab key navigation inside an element.
+ *
+ * Essential in FiveM NUI to prevent keyboard navigation from leaking out of CEF
+ * modals or into the background game window.
+ *
+ * @param node - The container DOM element confining focus.
+ * @param parameter - Configuration options or boolean enabled flag.
+ *
+ * @example
+ * ```svelte
+ * <div class="modal" use:nuiFocusTrap={isOpen}>...</div>
+ * <div class="dialog" use:nuiFocusTrap={{ enabled: true, allowOutside: '.datepicker-portal' }}>...</div>
+ * ```
+ */
+export const nuiFocusTrap: Action<HTMLElement, NuiFocusTrapInput> = (
+  node,
+  parameter
+) => {
+  let currentParam = parameter;
+  let active = false;
+  let previouslyFocused: HTMLElement | null = null;
+  let rafId: number | null = null;
+  let controller: AbortController | null = null;
+  let addedTabindex = false;
+
+  function isEnabled(): boolean {
+    const opts = toFocusTrapOptions(currentParam);
+    const { enabled } = opts;
+    return typeof enabled === 'function' ? enabled() : (enabled ?? true);
+  }
+
+  function containsOrAllowed(target: Node | null): boolean {
+    if (!target) return false;
+    if (node.contains(target)) return true;
+    const opts = toFocusTrapOptions(currentParam);
+    return isNodeAllowedOutside(target, opts.allowOutside);
+  }
+
+  function focusFirst() {
+    if (!active || !node.isConnected) return;
+
+    const focusables = getFocusables(node);
+    if (focusables.length > 0) {
+      if (addedTabindex) {
+        node.removeAttribute('tabindex');
+        addedTabindex = false;
+      }
+      focusables[0].focus();
+    } else {
+      if (!node.hasAttribute('tabindex')) {
+        node.setAttribute('tabindex', '-1');
+        addedTabindex = true;
+      }
+      node.focus();
+    }
+  }
+
+  function focusInitial() {
+    if (!active || !node.isConnected) return;
+
+    const opts = toFocusTrapOptions(currentParam);
+    if (opts.autofocus === false) return;
+
+    const targetEl = resolveInitialElement(node, opts.initialFocus);
+    if (
+      targetEl &&
+      targetEl.isConnected &&
+      (node.contains(targetEl) || isNodeAllowedOutside(targetEl, opts.allowOutside))
+    ) {
+      if (addedTabindex) {
+        node.removeAttribute('tabindex');
+        addedTabindex = false;
+      }
+      targetEl.focus();
+      return;
+    }
+
+    if (!containsOrAllowed(document.activeElement)) {
+      focusFirst();
+    }
+  }
+
+  function checkIsTopmost(): boolean {
+    const opts = toFocusTrapOptions(currentParam);
+    if (typeof opts.isTopmost === 'function') {
+      return opts.isTopmost();
+    }
+    return getTopTrap()?.node === node;
+  }
+
+  function onFocusIn(event: FocusEvent) {
+    if (!active || !node.isConnected) return;
+    if (!checkIsTopmost()) return;
+
+    const target = event.target as Node | null;
+    if (!target || containsOrAllowed(target)) return;
+
+    focusFirst();
+  }
+
+  function onKeyDown(event: KeyboardEvent) {
+    if (!active || !checkIsTopmost()) return;
+    const opts = toFocusTrapOptions(currentParam);
+    handleTabKey(event, node, opts.allowOutside, focusFirst);
+  }
+
+  function restoreFocus() {
+    const opts = toFocusTrapOptions(currentParam);
+    if (opts.returnFocus === false) return;
+
+    if (opts.returnFocus instanceof HTMLElement && opts.returnFocus.isConnected) {
+      opts.returnFocus.focus();
+    } else if (previouslyFocused && previouslyFocused.isConnected) {
+      previouslyFocused.focus();
+    }
+
+    const topEntry = getTopTrap();
+    if (topEntry && !topEntry.containsOrAllowed(document.activeElement)) {
+      topEntry.focusFirst();
+    }
+  }
+
+  function teardown() {
+    if (rafId !== null) {
+      if (typeof cancelAnimationFrame !== 'undefined') {
+        cancelAnimationFrame(rafId);
+      }
+      rafId = null;
+    }
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+    removeTrap(node);
+  }
+
+  const entry: FocusTrapEntry = {
+    node,
+    focusFirst,
+    containsOrAllowed,
+    isTopmost: () => {
+      const opts = toFocusTrapOptions(currentParam);
+      return typeof opts.isTopmost === 'function' ? opts.isTopmost() : undefined;
+    }
+  };
+
+  function setup() {
+    teardown();
+    if (!isEnabled()) return;
+
+    previouslyFocused = document.activeElement as HTMLElement | null;
+    if (previouslyFocused && node.contains(previouslyFocused)) {
+      previouslyFocused = null;
+    }
+    active = true;
+    pushTrap(entry);
+    controller = new AbortController();
+
+    document.addEventListener('keydown', onKeyDown, { capture: true, signal: controller.signal });
+    document.addEventListener('focusin', onFocusIn, { signal: controller.signal });
+
+    if (typeof requestAnimationFrame !== 'undefined') {
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (active && node.isConnected) {
+          focusInitial();
+        }
+      });
+    } else if (typeof queueMicrotask !== 'undefined') {
+      queueMicrotask(() => {
+        if (active && node.isConnected) {
+          focusInitial();
+        }
+      });
+    }
+  }
+
+  function deactivate() {
+    const wasActive = active;
+    active = false;
+    teardown();
+    if (addedTabindex) {
+      node.removeAttribute('tabindex');
+      addedTabindex = false;
+    }
+    if (wasActive) {
+      restoreFocus();
+    }
+  }
+
+  setup();
+
+  return {
+    update(newParam) {
+      const wasEnabled = active;
+      currentParam = newParam;
+      const nowEnabled = isEnabled();
+
+      if (!wasEnabled && nowEnabled) {
+        setup();
+      } else if (wasEnabled && !nowEnabled) {
+        deactivate();
+      }
+    },
+    destroy() {
+      deactivate();
+    }
+  };
+};

package/src/actions/focusTrap/focusables.ts

@@ -0,0 +1,155 @@
+import { type FocusTrapAllowOutside, isNodeAllowedOutside } from './trapStack';
+
+/**
+ * CSS selector matching all natively and custom focusable elements in HTML documents.
+ */
+export const FOCUSABLE_SELECTORS = [
+  'a[href]',
+  'area[href]',
+  'input:not([type="hidden"])',
+  'select',
+  'textarea',
+  'button',
+  'iframe',
+  'summary',
+  'audio[controls]',
+  'video[controls]',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]'
+].join(', ');
+
+/**
+ * Returns all currently focusable elements in Tab order within a container.
+ * Filters out disabled elements (including `<fieldset disabled>`), negative tabindexes,
+ * aria-hidden, inert, and hidden elements.
+ * Correctly scopes radio button groups per form so only the active radio button is in Tab order.
+ *
+ * @remarks
+ * Assumes DOM order for keyboard navigation. Elements with positive tabindex (> 0)
+ * alter standard browser tab sequencing and should generally be avoided.
+ *
+ * @param container - The root element to query focusable elements from.
+ * @returns Array of focusable HTML elements within the container.
+ */
+export function getFocusables(container: HTMLElement): HTMLElement[] {
+  const elements = Array.from(container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS));
+  const focusables: HTMLElement[] = [];
+  const radioGroups = new Map<HTMLFormElement | null, Map<string, HTMLInputElement>>();
+
+  for (const el of elements) {
+    if (el.matches(':disabled') || el.closest('fieldset[disabled]')) continue;
+    if (el.tabIndex < 0) continue;
+    if (el.closest('[aria-hidden="true"], [inert]')) continue;
+
+    if (typeof el.checkVisibility === 'function') {
+      if (!el.checkVisibility()) continue;
+    } else {
+      const isVisible =
+        el.offsetWidth > 0 ||
+        el.offsetHeight > 0 ||
+        el.getClientRects().length > 0 ||
+        el.offsetParent !== null;
+      if (!isVisible) continue;
+    }
+
+    if (el instanceof HTMLInputElement && el.type === 'radio' && el.name) {
+      const form = el.form;
+      let formRadios = radioGroups.get(form);
+      if (!formRadios) {
+        formRadios = new Map<string, HTMLInputElement>();
+        radioGroups.set(form, formRadios);
+      }
+      const currentRadio = formRadios.get(el.name);
+      if (el.checked) {
+        formRadios.set(el.name, el);
+      } else if (!currentRadio) {
+        formRadios.set(el.name, el);
+      }
+      continue;
+    }
+
+    focusables.push(el);
+  }
+
+  if (radioGroups.size > 0) {
+    const keep = new Set<Element>(focusables);
+    for (const formRadios of radioGroups.values()) {
+      for (const radio of formRadios.values()) {
+        keep.add(radio);
+      }
+    }
+    return elements.filter((el) => keep.has(el));
+  }
+
+  return focusables;
+}
+
+/**
+ * Resolves the designated initial focus element from an element reference, selector, or getter.
+ *
+ * @param container - The container DOM element.
+ * @param initialFocus - Target element, selector string, or getter function.
+ * @returns The resolved HTMLElement, or null if none was found.
+ */
+export function resolveInitialElement(
+  container: HTMLElement,
+  initialFocus?: HTMLElement | string | (() => HTMLElement | null | undefined)
+): HTMLElement | null {
+  if (!initialFocus) return null;
+  if (typeof initialFocus === 'string') {
+    return (
+      container.querySelector<HTMLElement>(initialFocus) ??
+      document.querySelector<HTMLElement>(initialFocus)
+    );
+  }
+  if (typeof initialFocus === 'function') {
+    return initialFocus() ?? null;
+  }
+  return initialFocus;
+}
+
+/**
+ * Confines Tab and Shift+Tab keyboard navigation within a container element.
+ * Wraps around when reaching the start or end of the focus sequence.
+ * Skips redirection if the currently focused element is allowed outside (e.g. portaled child).
+ *
+ * @param event - The keyboard event.
+ * @param container - The container element confining focus.
+ * @param allowOutside - Elements or selectors permitted to retain focus.
+ * @param onEmptyFallback - Callback when no focusable elements exist in container.
+ */
+export function handleTabKey(
+  event: KeyboardEvent,
+  container: HTMLElement,
+  allowOutside?: FocusTrapAllowOutside,
+  onEmptyFallback?: () => void
+): void {
+  if (event.key !== 'Tab') return;
+
+  const activeEl = document.activeElement;
+  if (isNodeAllowedOutside(activeEl, allowOutside)) return;
+
+  const focusables = getFocusables(container);
+  if (focusables.length === 0) {
+    event.preventDefault();
+    if (!container.contains(activeEl)) {
+      onEmptyFallback?.();
+    }
+    return;
+  }
+
+  const first = focusables[0];
+  const last = focusables[focusables.length - 1];
+
+  if (event.shiftKey) {
+    if (activeEl === first || !container.contains(activeEl)) {
+      event.preventDefault();
+      last.focus();
+    }
+  } else {
+    if (activeEl === last || !container.contains(activeEl)) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+}

package/src/actions/focusTrap/index.ts

@@ -0,0 +1,22 @@
+export { nuiFocusTrap } from './focusTrap';
+export {
+  FOCUSABLE_SELECTORS,
+  getFocusables,
+  resolveInitialElement,
+  handleTabKey
+} from './focusables';
+export {
+  type FocusTrapAllowOutsideTarget,
+  type FocusTrapAllowOutside,
+  type FocusTrapEntry,
+  getTopTrap,
+  resolveAllowOutsideElement,
+  isNodeAllowedOutside,
+  pushTrap,
+  removeTrap
+} from './trapStack';
+export {
+  type NuiFocusTrapOptions,
+  type NuiFocusTrapInput,
+  toFocusTrapOptions
+} from './types';

package/src/actions/focusTrap/trapStack.ts

@@ -0,0 +1,109 @@
+export type FocusTrapAllowOutsideTarget =
+  | Element
+  | string
+  | null
+  | undefined
+  | (() => Element | null | undefined);
+
+export type FocusTrapAllowOutside =
+  | FocusTrapAllowOutsideTarget
+  | FocusTrapAllowOutsideTarget[];
+
+export interface FocusTrapEntry {
+  node: HTMLElement;
+  focusFirst: () => void;
+  containsOrAllowed: (el: Node | null) => boolean;
+  isTopmost?: () => boolean | undefined;
+}
+
+/**
+ * Global stack of active focus trap entries.
+ * Ensures only the topmost trap (e.g. child confirmation dialog or portaled modal)
+ * enforces focus containment, preventing nested traps from fighting for focus.
+ */
+const trapStack: FocusTrapEntry[] = [];
+
+/**
+ * Registers an active focus trap entry to the top of the trap stack.
+ */
+export function pushTrap(entry: FocusTrapEntry): void {
+  trapStack.push(entry);
+}
+
+/**
+ * Removes a focus trap entry associated with the given container node.
+ */
+export function removeTrap(node: HTMLElement): void {
+  const idx = trapStack.findIndex((e) => e.node === node);
+  if (idx !== -1) {
+    trapStack.splice(idx, 1);
+  }
+}
+
+/**
+ * Resolves the topmost active focus trap entry.
+ * Evaluates custom `isTopmost` predicates first (e.g. from `nuiLayer`), where layer-managed
+ * traps with `isTopmost: true` always take precedence over standalone traps.
+ * Falls back to activation order (most recently activated connected trap).
+ */
+export function getTopTrap(): FocusTrapEntry | undefined {
+  for (let i = trapStack.length - 1; i >= 0; i--) {
+    const entry = trapStack[i];
+    if (entry.node.isConnected && entry.isTopmost?.() === true) {
+      return entry;
+    }
+  }
+  for (let i = trapStack.length - 1; i >= 0; i--) {
+    if (trapStack[i].node.isConnected) {
+      return trapStack[i];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolves an element, selector, or getter from an `allowOutside` configuration.
+ */
+export function resolveAllowOutsideElement(
+  target: FocusTrapAllowOutsideTarget
+): Element | null {
+  if (typeof target === 'string') {
+    return document.querySelector(target);
+  }
+  if (typeof target === 'function') {
+    return target() ?? null;
+  }
+  return target ?? null;
+}
+
+/**
+ * Checks whether a given node resides within any of the elements specified in `allowOutside`.
+ * Supports selector strings, elements, or reactive getters.
+ */
+export function isNodeAllowedOutside(
+  target: Node | null,
+  allowOutside?: FocusTrapAllowOutside
+): boolean {
+  if (!target || !allowOutside) return false;
+  const list = Array.isArray(allowOutside) ? allowOutside : [allowOutside];
+  const targetElement = target instanceof Element ? target : target.parentElement;
+
+  for (const item of list) {
+    if (!item) continue;
+    if (typeof item === 'string') {
+      try {
+        if (targetElement?.closest(item)) {
+          return true;
+        }
+      } catch {
+        // Invalid selector syntax, ignore
+      }
+      continue;
+    }
+    const el = resolveAllowOutsideElement(item);
+    if (el && (el === target || el.contains(target))) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/actions/focusTrap/types.ts

@@ -0,0 +1,64 @@
+import type { FocusTrapAllowOutside } from './trapStack';
+
+export interface NuiFocusTrapOptions {
+  /**
+   * Whether the focus trap is actively confining focus.
+   * Accepts a boolean or a reactive getter `() => boolean`.
+   * @defaultValue true
+   */
+  enabled?: boolean | (() => boolean);
+
+  /**
+   * Custom element, selector or getter to receive initial focus upon activation.
+   * If omitted, the first focusable element inside the node receives focus.
+   */
+  initialFocus?: HTMLElement | string | (() => HTMLElement | null | undefined);
+
+  /**
+   * Whether to restore focus to the previously focused element upon deactivation.
+   * Can also be a specific HTMLElement to return focus to.
+   * @defaultValue true
+   */
+  returnFocus?: boolean | HTMLElement;
+
+  /**
+   * Whether to automatically move focus inside the trap on activation.
+   * @defaultValue true
+   */
+  autofocus?: boolean;
+
+  /**
+   * Elements, selectors, or getters outside the container that are permitted to receive focus
+   * without being redirected back into the trap.
+   *
+   * Essential for portaled child elements such as select dropdowns, date pickers, or tooltips
+   * rendered into `document.body` outside the modal container.
+   */
+  allowOutside?: FocusTrapAllowOutside;
+
+  /**
+   * Optional custom predicate to determine if this trap is currently topmost.
+   * When provided, takes precedence over the default `trapStack` activation-order check.
+   * Used by coordinators such as `nuiLayer` to synchronize focus trapping with priority order.
+   *
+   * @remarks
+   * If providing custom `isTopmost` predicates manually, ensure only one active trap
+   * evaluates to `true` at any given time to avoid conflicting focus containment.
+   * Note that `nuiLayer` automatically controls and overrides this predicate based on layer priority.
+   */
+  isTopmost?: () => boolean;
+}
+
+export type NuiFocusTrapInput = boolean | NuiFocusTrapOptions | undefined;
+
+/**
+ * Normalizes boolean or option object parameters into `NuiFocusTrapOptions`.
+ */
+export function toFocusTrapOptions(
+  input: NuiFocusTrapInput
+): NuiFocusTrapOptions {
+  if (input === undefined || typeof input === 'boolean') {
+    return { enabled: input ?? true };
+  }
+  return input;
+}

package/src/actions/index.ts

@@ -0,0 +1,35 @@
+export {
+  nuiEscapeAction,
+  NuiEscapeTarget,
+  type NuiEscapeParameter,
+  type NuiEscapeInput
+} from './escape';
+
+export {
+  nuiFocusTrap,
+  type NuiFocusTrapOptions,
+  type NuiFocusTrapInput,
+  type FocusTrapAllowOutsideTarget,
+  type FocusTrapAllowOutside,
+  type FocusTrapEntry,
+  FOCUSABLE_SELECTORS,
+  getFocusables
+} from './focusTrap';
+
+export {
+  nuiClickOutside,
+  type NuiClickOutsideParameter,
+  type NuiClickOutsideInput,
+  type ClickOutsideTarget
+} from './clickOutside';
+
+export {
+  nuiLayer,
+  type NuiLayerOptions,
+  type NuiLayerInput,
+  NuiLayerDismissReason,
+  type LayerInstance,
+  getLayerStack,
+  getTopLayer,
+  resetLayerStack
+} from './layer';

package/src/actions/layer/index.ts

@@ -0,0 +1,13 @@
+export { nuiLayer } from './layer';
+export {
+  NuiLayerDismissReason,
+  type NuiLayerOptions,
+  type NuiLayerInput,
+  type LayerInstance,
+  toLayerOptions
+} from './types';
+export {
+  getLayerStack,
+  getTopLayer,
+  resetLayerStack
+} from './layerStack';