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

package/dist/components/overlay/NuiModal.svelte.d.ts

@@ -0,0 +1,72 @@
+export interface ModalAction {
+    /**
+     * Unique action identifier within the modal.
+     * Used as a keyed `#each` identifier and for `initialFocus` targeting.
+     */
+    id?: string;
+    label: string;
+    variant?: "primary" | "secondary" | "danger";
+    disabled?: boolean;
+    /** Automatically closes the modal after `onclick` succeeds (does not throw or return `false`). */
+    closeOnClick?: boolean;
+    /** Action callback. Returning `false` or throwing an error prevents `closeOnClick` from closing. */
+    onclick?: (event: MouseEvent) => unknown | Promise<unknown>;
+}
+export interface ModalLabels {
+    dialog?: string;
+    close?: string;
+}
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * Note on transitions: animations are tied to the internal `{#if open}` block.
+ * Control visibility via the `open` prop rather than wrapping `<NuiModal>` in an
+ * external `{#if show}` block so that exit transitions and focus cleanup run properly.
+ */
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "title" | "role" | "tabindex"> {
+    /** Controls whether the modal is open. */
+    open?: boolean;
+    /** Modal header title. */
+    title?: string;
+    /** Optional description text rendered inside the body and linked via `aria-describedby`. */
+    description?: string;
+    /** Modal body content. */
+    children?: Snippet;
+    /**
+     * Custom header snippet. Receives `titleId` so you can bind `id={titleId}`
+     * to your custom heading element for `aria-labelledby`.
+     */
+    header?: Snippet<[titleId: string]>;
+    /** Custom footer snippet (replaces the default `actions` bar). */
+    footer?: Snippet;
+    /** Footer action buttons. Each `action.id` must be unique if provided. */
+    actions?: ModalAction[];
+    /** Master switch for user dismissal. Individual flags (`closeOnEscape`, `closeOnBackdrop`, `showClose`) override this when defined. */
+    closable?: boolean;
+    /** Allow dismissing via the Escape key (defaults to `closable`). */
+    closeOnEscape?: boolean;
+    /** Allow dismissing by clicking the backdrop (defaults to `closable`). */
+    closeOnBackdrop?: boolean;
+    /** Render the header close ("X") button (defaults to `closable`). */
+    showClose?: boolean;
+    /** Modal width preset. */
+    size?: "sm" | "md" | "lg" | "xl" | "full";
+    /** Enable entry and exit transitions (respects `prefers-reduced-motion`). */
+    animated?: boolean;
+    /** Semantic ARIA role. */
+    role?: "dialog" | "alertdialog";
+    /** Action `id` or valid CSS selector to focus when the modal opens. */
+    initialFocus?: string;
+    /** Accessible labels for the dialog and close button. */
+    labels?: ModalLabels;
+    /**
+     * Called when the user dismisses the modal (via Escape, backdrop, close button, or an action with `closeOnClick`).
+     * Not called when `open` is set to `false` programmatically by the parent.
+     */
+    onClose?: () => void;
+    /** Called when an action callback throws or rejects. */
+    onActionError?: (error: unknown, action: ModalAction) => void;
+}
+declare const NuiModal: import("svelte").Component<Props, {}, "open">;
+type NuiModal = ReturnType<typeof NuiModal>;
+export default NuiModal;

package/dist/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/dist/components/overlay/NuiTooltip.svelte.d.ts

@@ -0,0 +1,13 @@
+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;
+}
+declare const NuiTooltip: import("svelte").Component<Props, {}, "">;
+type NuiTooltip = ReturnType<typeof NuiTooltip>;
+export default NuiTooltip;

package/dist/composables/useClickOutside.d.ts

@@ -0,0 +1,43 @@
+import { 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;
+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 declare const clickOutsideAction: ClickOutsideAction;
+export declare function useClickOutside(getElement: () => HTMLElement | null | undefined, callbackOrOptions: ClickOutsideInput | (() => ClickOutsideInput)): void;
+export declare const useClickOutsideElement: typeof useClickOutside;

package/dist/composables/useClickOutside.js

@@ -0,0 +1,73 @@
+import { nuiClickOutside, useClickOutside as bridgeUseClickOutside } from '@fivem-nui/svelte';
+function mapOptions(param) {
+    if (typeof param === 'function') {
+        return {
+            callback: param
+        };
+    }
+    const cb = 'callback' in param && param.callback
+        ? param.callback
+        : 'onClickOutside' in param && param.onClickOutside
+            ? param.onClickOutside
+            : undefined;
+    return {
+        callback: cb,
+        onClickOutside: cb,
+        enabled: param.enabled,
+        ignore: 'ignore' in param ? param.ignore : undefined,
+        capture: 'capture' in param ? param.capture : true
+    };
+}
+/**
+ * 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 = (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) {
+    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, callbackOrOptions) {
+    const getOptions = () => {
+        if (typeof callbackOrOptions !== 'function') {
+            return mapOptions(callbackOrOptions);
+        }
+        if (isOptionsGetter(callbackOrOptions)) {
+            const result = callbackOrOptions();
+            return mapOptions(result);
+        }
+        return {
+            callback: callbackOrOptions,
+            onClickOutside: callbackOrOptions,
+            capture: true
+        };
+    };
+    bridgeUseClickOutside(getElement, getOptions);
+}
+export const useClickOutsideElement = useClickOutside;

package/dist/composables/useFormValidation.d.ts

@@ -0,0 +1,23 @@
+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>>;
+}
+export declare function validateField(name: string, value: unknown, rules: ValidationRules, values?: Record<string, unknown>): string | null;
+/**
+ * Validates form values against the provided rules and returns a map of field errors.
+ */
+export declare function validateForm(values: Record<string, unknown>, rules: Record<string, ValidationRules>): Record<string, string>;

package/dist/composables/useFormValidation.js

@@ -0,0 +1,72 @@
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isEmpty(value) {
+    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) {
+    // 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, value, rules, values) {
+    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.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, rules) {
+    const errors = {};
+    for (const [field, rule] of Object.entries(rules)) {
+        const error = validateField(field, values[field], rule, values);
+        if (error)
+            errors[field] = error;
+    }
+    return errors;
+}

package/dist/composables/useIdle.svelte.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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;
+}
+/**
+ * Tracks user inactivity and idle state in NUI.
+ */
+export declare function useIdle(timeoutMs?: number, updateIntervalMs?: number): IdleState;
+/**
+ * One-shot activity observer: executes callback exactly once when the user becomes idle.
+ * Returns a cancel function to abort observation.
+ */
+export declare function useIdleUntil(timeoutMs?: number, callback?: () => void): () => void;

package/dist/composables/useIdle.svelte.js

@@ -0,0 +1,144 @@
+/**
+ * Hooks tracking user inactivity and idle state in FiveM NUI.
+ * Note: Must be called within a component lifecycle context due to `$effect`.
+ */
+const IDLE_EVENTS = [
+    'pointermove',
+    'pointerdown',
+    'keydown',
+    'scroll',
+    'wheel',
+];
+const THROTTLE_MS = 500;
+/**
+ * Shared core helper managing event listeners with capture mode, throttle bypass, and timeout scheduling.
+ */
+function createIdleManager(timeoutMs, onTimeout, onActivity, shouldBypassThrottle) {
+    let timer = null;
+    let controller = 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) {
+    let isIdle = $state(false);
+    let idleTime = $state(0);
+    let lastActive = Date.now();
+    let interval = 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);
+    $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) {
+    let fired = false;
+    let cleanupManager = 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;
+}