@fivem-nui/svelte-components 0.0.0-stage → 1.0.0

package/src/components/overlay/NuiTooltip.svelte

@@ -0,0 +1,159 @@
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+
+  interface Props {
+    /** Tekst podpowiedzi */
+    text: string;
+    /** Pozycja podpowiedzi */
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Czas opóźnienia wyświetlania w ms */
+    delay?: number;
+    /** Element docelowy podpowiedzi */
+    children?: import('svelte').Snippet;
+  }
+
+  let {
+    text,
+    position = 'top',
+    delay = 150,
+    children
+  }: Props = $props();
+
+  let visible = $state(false);
+  let showTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function show() {
+    if (showTimer) clearTimeout(showTimer);
+    if (delay > 0) {
+      showTimer = setTimeout(() => {
+        visible = true;
+      }, delay);
+    } else {
+      visible = true;
+    }
+  }
+
+  function hide() {
+    if (showTimer) {
+      clearTimeout(showTimer);
+      showTimer = null;
+    }
+    visible = false;
+  }
+
+  const cleanup = () => {
+    if (showTimer) clearTimeout(showTimer);
+  };
+
+  try {
+    onDestroy(cleanup);
+  } catch {
+    // Outside component lifecycle
+  }
+</script>
+
+<span
+  class="nui-tooltip-wrapper"
+  role="presentation"
+  onmouseenter={show}
+  onmouseleave={hide}
+  onfocusin={show}
+  onfocusout={hide}
+>
+  {@render children?.()}
+
+  {#if visible && text}
+    <div class="nui-tooltip nui-tooltip--{position}" role="tooltip">
+      {text}
+    </div>
+  {/if}
+</span>
+
+<style>
+  .nui-tooltip-wrapper {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .nui-tooltip {
+    position: absolute;
+    padding: 0.375rem 0.625rem;
+    background: var(--nui-surface-alt, #18181b);
+    color: var(--nui-fg, #fafafa);
+    border: 1px solid var(--nui-border, #3f3f46);
+    border-radius: var(--nui-radius, 0.375rem);
+    font-size: 0.75rem;
+    line-height: 1.2;
+    box-shadow: 0 4px 12px rgb(0 0 0 / 0.35);
+    z-index: var(--nui-z-tooltip, 1100);
+    pointer-events: none;
+    white-space: nowrap;
+    animation: nui-tooltip-pop 0.15s ease-out;
+  }
+
+  .nui-tooltip--top {
+    bottom: calc(100% + 0.375rem);
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  .nui-tooltip--bottom {
+    top: calc(100% + 0.375rem);
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  .nui-tooltip--left {
+    right: calc(100% + 0.375rem);
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  .nui-tooltip--right {
+    left: calc(100% + 0.375rem);
+    top: 50%;
+    transform: translateY(-50%);
+  }
+
+  @keyframes nui-tooltip-pop {
+    from {
+      opacity: 0;
+      transform: translate(-50%, 2px);
+    }
+    to {
+      opacity: 1;
+      transform: translate(-50%, 0);
+    }
+  }
+
+  .nui-tooltip--left {
+    animation-name: nui-tooltip-pop-left;
+  }
+
+  @keyframes nui-tooltip-pop-left {
+    from {
+      opacity: 0;
+      transform: translateY(-50%) translateX(2px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(-50%) translateX(0);
+    }
+  }
+
+  .nui-tooltip--right {
+    animation-name: nui-tooltip-pop-right;
+  }
+
+  @keyframes nui-tooltip-pop-right {
+    from {
+      opacity: 0;
+      transform: translateY(-50%) translateX(-2px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(-50%) translateX(0);
+    }
+  }
+</style>

package/src/composables/useClickOutside.ts

@@ -0,0 +1,132 @@
+import type { Action } from 'svelte/action';
+import {
+  nuiClickOutside,
+  useClickOutside as bridgeUseClickOutside,
+  type ClickOutsideTarget,
+  type NuiClickOutsideParameter
+} from '@fivem-nui/svelte';
+
+export interface ClickOutsideOptions {
+  /**
+   * Callback invoked when a click or touch occurs outside the target element.
+   */
+  callback: (event: MouseEvent | TouchEvent | PointerEvent) => void;
+  /**
+   * Reactive getter or boolean to control whether detection is active.
+   * @default true
+   */
+  enabled?: boolean | (() => boolean);
+  /**
+   * Elements, selectors, or getters to exclude from triggering outside click.
+   * Essential for toggle buttons and popover trigger elements.
+   */
+  ignore?: ClickOutsideTarget[];
+  /**
+   * Listen during capture phase.
+   * @default true
+   */
+  capture?: boolean;
+}
+
+export type ClickOutsideInput =
+  | (() => void)
+  | ((event: MouseEvent | TouchEvent | PointerEvent) => void)
+  | ClickOutsideOptions
+  | NuiClickOutsideParameter;
+
+function mapOptions(param: ClickOutsideInput): NuiClickOutsideParameter {
+  if (typeof param === 'function') {
+    return {
+      callback: param as (event: PointerEvent) => void
+    };
+  }
+
+  const cb = 'callback' in param && param.callback
+    ? (param.callback as (event: PointerEvent) => void)
+    : 'onClickOutside' in param && param.onClickOutside
+      ? (param.onClickOutside as (event: PointerEvent) => void)
+      : undefined;
+
+  return {
+    callback: cb,
+    onClickOutside: cb,
+    enabled: param.enabled,
+    ignore: 'ignore' in param ? param.ignore : undefined,
+    capture: 'capture' in param ? param.capture : true
+  };
+}
+
+export interface ClickOutsideActionReturn {
+  update: (param: ClickOutsideInput) => void;
+  destroy: () => void;
+}
+
+export type ClickOutsideAction = (
+  node: HTMLElement,
+  param: ClickOutsideInput
+) => ClickOutsideActionReturn;
+
+/**
+ * Action for detecting clicks outside an element.
+ *
+ * Backed by `@fivem-nui/svelte` with `event.composedPath()` (eliminating the detached
+ * DOM node bug in dynamic lists) and `AbortController` lifecycle management.
+ *
+ * @example
+ * ```svelte
+ * <div use:clickOutsideAction={() => (open = false)}>...</div>
+ * <div use:clickOutsideAction={{ callback: close, ignore: [btnEl] }}>...</div>
+ * ```
+ */
+export const clickOutsideAction: ClickOutsideAction = (
+  node,
+  param
+) => {
+  const innerAction = nuiClickOutside(node, mapOptions(param));
+
+  return {
+    update(newParam) {
+      innerAction?.update?.(mapOptions(newParam));
+    },
+    destroy() {
+      innerAction?.destroy?.();
+    }
+  };
+};
+
+/**
+ * Functional composable to watch click outside for an element getter or reference.
+ * Automatically cleans up on component unmount via `$effect` in `@fivem-nui/svelte`.
+ */
+function isOptionsGetter(fn: unknown): boolean {
+  if (typeof fn !== 'function') return false;
+  if (fn.length > 0) return false;
+  const str = Function.prototype.toString.call(fn);
+  return /(return\s*\{|\(\s*\{)[\s\S]*\b(callback|onClickOutside|enabled|ignore|capture)\b/.test(str);
+}
+
+export function useClickOutside(
+  getElement: () => HTMLElement | null | undefined,
+  callbackOrOptions: ClickOutsideInput | (() => ClickOutsideInput)
+): void {
+  const getOptions = (): NuiClickOutsideParameter => {
+    if (typeof callbackOrOptions !== 'function') {
+      return mapOptions(callbackOrOptions);
+    }
+
+    if (isOptionsGetter(callbackOrOptions)) {
+      const result = (callbackOrOptions as () => ClickOutsideInput)();
+      return mapOptions(result);
+    }
+
+    return {
+      callback: callbackOrOptions as (event: PointerEvent) => void,
+      onClickOutside: callbackOrOptions as (event: PointerEvent) => void,
+      capture: true
+    };
+  };
+
+  bridgeUseClickOutside(getElement, getOptions);
+}
+
+export const useClickOutsideElement = useClickOutside;

package/src/composables/useFormValidation.ts

@@ -0,0 +1,105 @@
+export interface ValidationRules {
+  /** Whether the field is required. Considered empty: null, undefined, '', whitespace-only, [], NaN */
+  required?: boolean;
+  /** Minimum length for strings/arrays, or minimum numeric value */
+  min?: number;
+  /** Maximum length for strings/arrays, or maximum numeric value */
+  max?: number;
+  /** Whether to validate the value as an email address */
+  email?: boolean;
+  /** Regular expression pattern for strings. Sticky (y) and global (g) flags are ignored */
+  pattern?: string | RegExp;
+  /** Synchronous custom validator. Returns true if valid, false for default error, or a custom error message string */
+  custom?: (value: unknown, values?: Record<string, unknown>) => boolean | string;
+  /** Field label used in validation messages instead of the field key */
+  label?: string;
+  /** Custom error message overrides for specific rules */
+  messages?: Partial<Record<'required' | 'min' | 'max' | 'email' | 'pattern' | 'custom', string>>;
+}
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function isEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value === 'string') return value.trim() === '';
+  if (typeof value === 'number') return Number.isNaN(value);
+  if (Array.isArray(value)) return value.length === 0;
+  return false;
+}
+
+function toRegExp(pattern: string | RegExp): RegExp {
+  // New instance without g/y flags: ensures test() is stateless
+  const flags = pattern instanceof RegExp ? pattern.flags.replace(/[gy]/g, '') : '';
+  return new RegExp(pattern instanceof RegExp ? pattern.source : pattern, flags);
+}
+
+export function validateField(
+  name: string,
+  value: unknown,
+  rules: ValidationRules,
+  values?: Record<string, unknown>,
+): string | null {
+  const label = rules.label ?? name;
+  const msg = rules.messages ?? {};
+
+  if (isEmpty(value)) {
+    return rules.required ? (msg.required ?? `${label} is required`) : null;
+  }
+
+  if (rules.min !== undefined) {
+    if (typeof value === 'string' && value.length < rules.min)
+      return msg.min ?? `${label} must be at least ${rules.min} characters`;
+    if (Array.isArray(value) && value.length < rules.min)
+      return msg.min ?? `${label} must have at least ${rules.min} items`;
+    if (typeof value === 'number' && value < rules.min)
+      return msg.min ?? `${label} must be at least ${rules.min}`;
+  }
+
+  if (rules.max !== undefined) {
+    if (typeof value === 'string' && value.length > rules.max)
+      return msg.max ?? `${label} must be at most ${rules.max} characters`;
+    if (Array.isArray(value) && value.length > rules.max)
+      return msg.max ?? `${label} must have at most ${rules.max} items`;
+    if (typeof value === 'number' && value > rules.max)
+      return msg.max ?? `${label} must be at most ${rules.max}`;
+  }
+
+  if (rules.email && typeof value === 'string' && !EMAIL_RE.test(value.trim())) {
+    return msg.email ?? `${label} must be a valid email address`;
+  }
+
+  if (rules.pattern && typeof value === 'string') {
+    // Invalid pattern is a configuration error: new RegExp will throw SyntaxError
+    if (!toRegExp(rules.pattern).test(value)) {
+      return msg.pattern ?? `${label} has an invalid format`;
+    }
+  }
+
+  if (rules.custom) {
+    const result = rules.custom(value, values);
+    if (result && typeof (result as unknown as Promise<unknown>).then === 'function') {
+      throw new TypeError(`[validateField] "${name}": async custom validators are not supported`);
+    }
+    if (typeof result === 'string') return result === '' ? null : result;
+    if (!result) return msg.custom ?? `${label} is invalid`;
+  }
+
+  return null;
+}
+
+/**
+ * Validates form values against the provided rules and returns a map of field errors.
+ */
+export function validateForm(
+  values: Record<string, unknown>,
+  rules: Record<string, ValidationRules>,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+
+  for (const [field, rule] of Object.entries(rules)) {
+    const error = validateField(field, values[field], rule, values);
+    if (error) errors[field] = error;
+  }
+
+  return errors;
+}

package/src/composables/useIdle.svelte.ts

@@ -0,0 +1,191 @@
+/**
+ * Hooks tracking user inactivity and idle state in FiveM NUI.
+ * Note: Must be called within a component lifecycle context due to `$effect`.
+ */
+
+export interface IdleState {
+  readonly isIdle: boolean;
+  readonly idleTime: number;
+  reset(force?: boolean): void;
+}
+
+const IDLE_EVENTS = [
+  'pointermove',
+  'pointerdown',
+  'keydown',
+  'scroll',
+  'wheel',
+] as const;
+
+const THROTTLE_MS = 500;
+
+/**
+ * Shared core helper managing event listeners with capture mode, throttle bypass, and timeout scheduling.
+ */
+function createIdleManager(
+  timeoutMs: number,
+  onTimeout: () => void,
+  onActivity?: () => void,
+  shouldBypassThrottle?: () => boolean,
+) {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let controller: AbortController | null = null;
+  let lastResetTime = 0;
+
+  function clearTimer() {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  function schedule() {
+    clearTimer();
+    timer = setTimeout(onTimeout, timeoutMs);
+  }
+
+  function handleActivity(force = false) {
+    const now = Date.now();
+    const bypass = force || (shouldBypassThrottle?.() ?? false);
+    if (!bypass && now - lastResetTime < THROTTLE_MS) return;
+    lastResetTime = now;
+
+    onActivity?.();
+    schedule();
+  }
+
+  const listener = () => handleActivity(false);
+
+  function init() {
+    controller = new AbortController();
+    for (const event of IDLE_EVENTS) {
+      window.addEventListener(event, listener, {
+        passive: true,
+        capture: true, // Crucial for catching scrolls inside inner NUI containers
+        signal: controller.signal,
+      });
+    }
+
+    schedule();
+
+    return () => {
+      clearTimer();
+      controller?.abort();
+      controller = null;
+    };
+  }
+
+  return {
+    init,
+    reset: (force = true) => handleActivity(force), // Manual reset defaults to forcing bypass
+  };
+}
+
+/**
+ * Tracks user inactivity and idle state in NUI.
+ */
+export function useIdle(
+  timeoutMs = 30_000,
+  updateIntervalMs = 1_000,
+): IdleState {
+  let isIdle = $state(false);
+  let idleTime = $state(0);
+
+  let lastActive = Date.now();
+  let interval: ReturnType<typeof setInterval> | null = null;
+
+  function updateIdleTime() {
+    idleTime = Math.max(0, Date.now() - lastActive);
+  }
+
+  function startInterval() {
+    if (interval) return;
+    interval = setInterval(updateIdleTime, updateIntervalMs);
+  }
+
+  function stopInterval() {
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  }
+
+  const manager = createIdleManager(
+    timeoutMs,
+    () => {
+      isIdle = true;
+      // Synchronize idleTime immediately when entering idle state
+      idleTime = Math.max(0, Date.now() - lastActive);
+    },
+    () => {
+      lastActive = Date.now();
+      idleTime = 0;
+      if (isIdle) {
+        isIdle = false;
+      }
+      startInterval();
+    },
+    () => isIdle, // Instantly bypass throttle when user is currently idle (waking up)
+  );
+
+  $effect(() => {
+    lastActive = Date.now();
+    idleTime = 0;
+    isIdle = false;
+    startInterval();
+    const cleanupManager = manager.init();
+
+    return () => {
+      cleanupManager();
+      stopInterval();
+    };
+  });
+
+  return {
+    get isIdle() {
+      return isIdle;
+    },
+    get idleTime() {
+      return idleTime;
+    },
+    reset: (force = true) => manager.reset(force),
+  };
+}
+
+/**
+ * One-shot activity observer: executes callback exactly once when the user becomes idle.
+ * Returns a cancel function to abort observation.
+ */
+export function useIdleUntil(
+  timeoutMs = 30_000,
+  callback?: () => void,
+): () => void {
+  let fired = false;
+  let cleanupManager: (() => void) | null = null;
+
+  const manager = createIdleManager(timeoutMs, () => {
+    if (!fired) {
+      fired = true;
+      callback?.();
+      cleanupManager?.();
+      cleanupManager = null;
+    }
+  });
+
+  $effect(() => {
+    fired = false; // Reset fired state on effect re-run/re-mount
+    cleanupManager = manager.init();
+
+    return () => {
+      cleanupManager?.();
+      cleanupManager = null;
+    };
+  });
+
+  const cancel = () => {
+    cleanupManager?.();
+    cleanupManager = null;
+  };
+
+  return cancel;
+}