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

package/src/composables/useKeyboardShortcut.svelte.ts

@@ -0,0 +1,278 @@
+/**
+ * Keyboard shortcut hooks for FiveM NUI.
+ */
+
+export interface KeyboardShortcut {
+  /**
+   * The key to match case-insensitively (eg. 'e', 'Enter', 'Escape', ' ', 'F1').
+   * Ignored if `code` is provided.
+   */
+  key?: string;
+  /**
+   * @deprecated Use `key` instead. Alias kept for backwards compatibility.
+   */
+  event?: KeyboardEvent['key'];
+  /**
+   * Physical key code to match (e.g. 'KeyE', 'Digit1', 'Space', 'Enter').
+   * When provided, `key` is completely ignored in favor of `code`.
+   * Highly recommended for layout-independent shortcuts and combinations with Shift (e.g. Shift+1).
+   */
+  code?: string;
+  /**
+   * Require Ctrl key to be pressed in the FiveM Windows CEF environment.
+   */
+  ctrl?: boolean;
+  /**
+   * Require primary modifier key to be pressed.
+   * In FiveM (Windows CEF), this is equivalent to `ctrl`.
+   * Note: `ctrl` takes precedence over `mod` if both are defined.
+   */
+  mod?: boolean;
+  /**
+   * Require Alt key to be pressed.
+   */
+  alt?: boolean;
+  /**
+   * Require Shift key to be pressed.
+   */
+  shift?: boolean;
+  /**
+   * Require Meta (Windows key) to be pressed.
+   */
+  meta?: boolean;
+  /**
+   * When true, requires modifier keys (Ctrl, Alt, Shift, Meta) to strictly match
+   * the specified options. Unspecified modifiers must NOT be pressed.
+   * @default false
+   */
+  exact?: boolean;
+  /**
+   * Callback invoked when the shortcut matches.
+   */
+  callback: (event: KeyboardEvent) => void;
+  /**
+   * Whether the shortcut is currently enabled.
+   * Accepts a boolean or a reactive getter `() => boolean`.
+   * @default true
+   */
+  enabled?: boolean | (() => boolean);
+  /**
+   * Automatically call `event.preventDefault()`.
+   * @default true
+   */
+  preventDefault?: boolean;
+  /**
+   * Automatically call `event.stopPropagation()`.
+   * Stops bubbling up the DOM hierarchy.
+   * @default false
+   */
+  stopPropagation?: boolean;
+  /**
+   * Automatically call `event.stopImmediatePropagation()`.
+   * Prevents other listeners on the same element from being executed.
+   * @default false
+   */
+  stopImmediatePropagation?: boolean;
+  /**
+   * If true, suppresses shortcut execution when the active element is an input,
+   * textarea, select, contenteditable, or ARIA textbox/searchbox.
+   * @default false
+   */
+  ignoreInputs?: boolean;
+  /**
+   * Ignore repeating keydown events when holding a key down.
+   * @default false
+   */
+  ignoreRepeat?: boolean;
+}
+
+export interface KeyboardShortcutOptions {
+  /**
+   * Event target to attach the keydown listener to.
+   * Can be an EventTarget (e.g. window, document, HTMLElement) or getter function returning one (e.g. `() => myElement`).
+   * Note: The options object itself is evaluated once on init to make the target reactive, pass `target` as a getter function.
+   * Defaults to `window` (global NUI shortcuts).
+   */
+  target?: EventTarget | null | (() => EventTarget | null);
+  /**
+   * Listen during capture phase. Useful for global NUI handlers to intercept events early.
+   * @default false
+   */
+  capture?: boolean;
+}
+
+export type KeyboardShortcutsSource =
+  | KeyboardShortcut[]
+  | (() => KeyboardShortcut[]);
+
+export type KeyboardShortcutSource =
+  | KeyboardShortcut
+  | (() => KeyboardShortcut);
+
+/**
+ * Checks whether the focused element accepts text input, supporting Shadow DOM via event.composedPath().
+ */
+function isTextInputFocused(event: KeyboardEvent): boolean {
+  if (typeof document === 'undefined') return false;
+
+  const path = event.composedPath();
+  const el = path[0] instanceof HTMLElement ? path[0] : document.activeElement;
+
+  if (!el || !(el instanceof HTMLElement)) return false;
+
+  const tag = el.tagName.toLowerCase();
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+    return true;
+  }
+
+  if (el.isContentEditable) {
+    return true;
+  }
+
+  const role = el.getAttribute('role');
+  if (role === 'textbox' || role === 'searchbox') {
+    return true;
+  }
+
+  if (el.closest('[contenteditable]:not([contenteditable="false"])')) {
+    return true;
+  }
+
+  return false;
+}
+
+function isShortcutActive(shortcut: KeyboardShortcut, event: KeyboardEvent): boolean {
+  // 1. Cheap checks first (ignoreRepeat)
+  if (shortcut.ignoreRepeat && event.repeat) return false;
+
+  // 2. Key or Code match (code overrides key entirely)
+  if (shortcut.code) {
+    if (event.code?.toLowerCase() !== shortcut.code.toLowerCase()) return false;
+  } else {
+    const expectedKey = (shortcut.key ?? shortcut.event ?? '').toLowerCase();
+    if (!expectedKey) return false;
+    if (event.key?.toLowerCase() !== expectedKey) return false;
+  }
+
+  // 3. Modifier match
+  const expectedCtrl = shortcut.ctrl ?? shortcut.mod;
+
+  if (shortcut.exact) {
+    const needCtrl = Boolean(expectedCtrl);
+    const needAlt = Boolean(shortcut.alt);
+    const needShift = Boolean(shortcut.shift);
+    const needMeta = Boolean(shortcut.meta);
+
+    if (event.ctrlKey !== needCtrl) return false;
+    if (event.altKey !== needAlt) return false;
+    if (event.shiftKey !== needShift) return false;
+    if (event.metaKey !== needMeta) return false;
+  } else {
+    if (expectedCtrl !== undefined && Boolean(expectedCtrl) !== event.ctrlKey) return false;
+    if (shortcut.alt !== undefined && Boolean(shortcut.alt) !== event.altKey) return false;
+    if (shortcut.shift !== undefined && Boolean(shortcut.shift) !== event.shiftKey) return false;
+    if (shortcut.meta !== undefined && Boolean(shortcut.meta) !== event.metaKey) return false;
+  }
+
+  // 4. Expensive / side-effect checks last (enabled function, DOM queries for inputs)
+  if (shortcut.enabled !== undefined) {
+    const isAllowed = typeof shortcut.enabled === 'function' ? shortcut.enabled() : shortcut.enabled;
+    if (!isAllowed) return false;
+  }
+
+  if (shortcut.ignoreInputs && isTextInputFocused(event)) return false;
+
+  return true;
+}
+
+/**
+ * Registers multiple keyboard shortcuts with reactive lifecycle management.
+ * 
+ * Note: 
+ * - Must be called within a component initialization context (or wrapped in `$effect.root`).
+ * - Array order matters: the first matching shortcut terminates evaluation via `break`.
+ */
+export function useKeyboardShortcuts(
+  shortcuts: KeyboardShortcutsSource,
+  options?: KeyboardShortcutOptions
+): () => void {
+  let controller: AbortController | null = null;
+
+  function handler(event: KeyboardEvent) {
+    // Ignore IME composition events (e.g. active Asian text input)
+    if (event.isComposing) return;
+
+    const list = typeof shortcuts === 'function' ? shortcuts() : shortcuts;
+    if (!list || !Array.isArray(list)) return;
+
+    for (const shortcut of list) {
+      if (isShortcutActive(shortcut, event)) {
+        if (shortcut.preventDefault ?? true) {
+          event.preventDefault();
+        }
+        if (shortcut.stopPropagation) {
+          event.stopPropagation();
+        }
+        if (shortcut.stopImmediatePropagation) {
+          event.stopImmediatePropagation();
+        }
+        try {
+          shortcut.callback(event);
+        } catch (err) {
+          console.error(
+            '[nui-keyboard] Error in shortcut callback:',
+            err
+          );
+        }
+        break;
+      }
+    }
+  }
+
+  const cleanup = () => {
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+  };
+
+  const setupListener = () => {
+    cleanup(); // Prevent memory leaks on re-binding
+
+    const targetFn = options?.target;
+    const target = typeof targetFn === 'function' ? targetFn() : targetFn;
+    const resolvedTarget = target ?? (typeof window !== 'undefined' ? window : null);
+
+    if (!resolvedTarget) return;
+
+    controller = new AbortController();
+    resolvedTarget.addEventListener('keydown', handler as EventListener, {
+      capture: options?.capture ?? false,
+      signal: controller.signal
+    });
+  };
+
+  // Lifecycle binding
+  $effect(() => {
+    setupListener();
+    return cleanup;
+  });
+
+  return cleanup;
+}
+
+/**
+ * Registers a single keyboard shortcut with reactive lifecycle management.
+ */
+export function useKeyboardShortcut(
+  shortcut: KeyboardShortcutSource,
+  options?: KeyboardShortcutOptions
+): () => void {
+  return useKeyboardShortcuts(
+    () => {
+      const item = typeof shortcut === 'function' ? shortcut() : shortcut;
+      return item ? [item] : [];
+    },
+    options
+  );
+}

package/src/composables/useLocalStorage.svelte.ts

@@ -0,0 +1,137 @@
+/**
+ * LocalStorage synchronization hook for FiveM NUI.
+ */
+export interface LocalStorageState<T> {
+  get current(): T;
+  set current(value: T);
+  set(value: T | ((prev: T) => T)): void;
+}
+
+const STORAGE_EVENT_PREFIX = 'nui-local-storage:';
+
+/**
+ * LocalStorage synchronization hook.
+ * 
+ * Automatically synchronizes state with `localStorage`, listens for cross-window 
+ * `storage` events (including removals/clears), and dispatches custom events with 
+ * source filtering for intra-window CEF (FiveM NUI) synchronization.
+ * 
+ * Note: 
+ * - Must be called within a component initialization context (or wrapped in `$effect.root`).
+ * - Mutating nested properties of objects directly (e.g. `state.current.prop = val`) does not trigger a write; use assignments or `.set()`.
+ * - If the key changes dynamically, the state switches to the new key, overwriting uncommitted state.
+ * - Write failures (e.g., storage quota exceeded) keep the memory state updated while leaving storage unchanged.
+ */
+export function useLocalStorage<T>(
+  key: string | (() => string),
+  initialValue: T
+): LocalStorageState<T> {
+  // Helper to resolve reactive or static key
+  const resolveKey = () => (typeof key === 'function' ? key() : key);
+
+  function cloneInitial(): T {
+    if (initialValue === undefined) return initialValue as T;
+    try {
+      if (typeof structuredClone === 'function') {
+        return structuredClone(initialValue);
+      }
+      return JSON.parse(JSON.stringify(initialValue));
+    } catch {
+      return initialValue;
+    }
+  }
+
+  function readStorage(targetKey: string): T {
+    try {
+      const item = window.localStorage.getItem(targetKey);
+      if (item !== null) {
+        return JSON.parse(item);
+      }
+    } catch (error) {
+      console.warn(`[nui-local-storage] Error reading key "${targetKey}":`, error);
+    }
+    return cloneInitial();
+  }
+
+  // Synchronous initial read to prevent flash of default value on first render
+  let stored = $state<T>(readStorage(resolveKey()));
+  let loadedKey = resolveKey();
+  const instanceId = Symbol();
+
+  function setValue(value: T | ((prev: T) => T)) {
+    const currentKey = resolveKey();
+    const valueToStore = typeof value === 'function' ? (value as (prev: T) => T)(stored) : value;
+    stored = valueToStore;
+
+    try {
+      window.localStorage.setItem(currentKey, JSON.stringify(valueToStore));
+    } catch (error) {
+      console.warn(`[nui-local-storage] Error writing key "${currentKey}":`, error);
+      return; // Memory state is updated, but storage write failed
+    }
+
+    // Dispatch custom event for intra-window CEF synchronization (critical for FiveM NUI) only after successful write
+    try {
+      window.dispatchEvent(
+        new CustomEvent(`${STORAGE_EVENT_PREFIX}${currentKey}`, {
+          detail: { source: instanceId }
+        })
+      );
+    } catch (error) {
+      console.warn(`[nui-local-storage] Error dispatching sync event for key "${currentKey}":`, error);
+    }
+  }
+
+  const setupEffect = () => {
+    const currentKey = resolveKey();
+
+    // Sync state only if the key has actually changed (prevents double parsing on initial mount)
+    if (currentKey !== loadedKey) {
+      loadedKey = currentKey;
+      stored = readStorage(currentKey);
+    }
+
+    const controller = new AbortController();
+    const { signal } = controller;
+
+    // 1. Cross-window storage events (handles external tabs, clear(), removeItem())
+    window.addEventListener(
+      'storage',
+      (event: StorageEvent) => {
+        if (event.key === currentKey || event.key === null) {
+          stored = readStorage(currentKey);
+        }
+      },
+      { signal }
+    );
+
+    // 2. Intra-window custom events (FiveM NUI CEF synchronization with fresh storage reads)
+    window.addEventListener(
+      `${STORAGE_EVENT_PREFIX}${currentKey}`,
+      (event: Event) => {
+        const customEvent = event as CustomEvent<{ source: symbol }>;
+        if (customEvent.detail.source !== instanceId) {
+          stored = readStorage(currentKey);
+        }
+      },
+      { signal }
+    );
+
+    return () => {
+      controller.abort();
+    };
+  };
+
+  // Reactive lifecycle management for dynamic keys
+  $effect(setupEffect);
+
+  return {
+    get current() {
+      return stored;
+    },
+    set current(val: T) {
+      setValue(val);
+    },
+    set: setValue
+  };
+}

package/src/composables/useMediaQuery.svelte.ts

@@ -0,0 +1,102 @@
+/**
+ * Media query hooks for FiveM NUI.
+ */
+
+export interface MediaQueryState {
+  readonly matches: boolean;
+}
+
+export type MediaQuerySource = string | (() => string);
+
+/**
+ * Media query listener.
+ * 
+ * Supports both static query strings and reactive getters (`() => string`).
+ * Automatically manages event listener lifecycle via `$effect`.
+ * 
+ * Note: Must be called within a component initialization context (or wrapped in `$effect.root`).
+ */
+export function useMediaQuery(querySource: MediaQuerySource): MediaQueryState {
+  const resolveQuery = () => (typeof querySource === 'function' ? querySource() : querySource);
+
+  let matches = $state<boolean>(
+    typeof window !== 'undefined' ? window.matchMedia(resolveQuery()).matches : false
+  );
+
+  $effect(() => {
+    const query = resolveQuery();
+    const mediaQuery = window.matchMedia(query);
+
+    // Sync matches state in case the query changed
+    matches = mediaQuery.matches;
+
+    const handler = (event: MediaQueryListEvent) => {
+      matches = event.matches;
+    };
+
+    mediaQuery.addEventListener('change', handler);
+
+    return () => {
+      mediaQuery.removeEventListener('change', handler);
+    };
+  });
+
+  return {
+    get matches() {
+      return matches;
+    }
+  };
+}
+
+/**
+ * Tracks whether the viewport width is strictly less than the specified breakpoint.
+ * Uses modern CSS range syntax (fully supported in modern Chromium/FiveM CEF).
+ * Accepts any valid CSS length unit (e.g. '768px', '48rem').
+ * @default breakpoint '768px'
+ */
+export function useIsMobile(breakpoint = '768px'): MediaQueryState {
+  return useMediaQuery(`(width < ${breakpoint})`);
+}
+
+/**
+ * Tracks whether the viewport width falls within the tablet range using modern CSS range syntax.
+ * Accepts any valid CSS length units.
+ * @default min '768px', max '1024px'
+ */
+export function useIsTablet(min = '768px', max = '1024px'): MediaQueryState {
+  return useMediaQuery(`(${min} <= width < ${max})`);
+}
+
+/**
+ * Tracks whether the viewport width is greater than or equal to the specified breakpoint.
+ * Accepts any valid CSS length units.
+ * @default breakpoint '1024px'
+ */
+export function useIsDesktop(breakpoint = '1024px'): MediaQueryState {
+  return useMediaQuery(`(width >= ${breakpoint})`);
+}
+
+/**
+ * Tracks dark mode preference. 
+ * Note: In embedded CEF (FiveM NUI), OS-level color scheme detection may not reflect host system settings;
+ * consider overriding or syncing this via `useLocalStorage` if your UI supports manual theme switching.
+ */
+export function useDarkMode(): MediaQueryState {
+  return useMediaQuery('(prefers-color-scheme: dark)');
+}
+
+/**
+ * Tracks reduced motion preference.
+ * Note: In embedded CEF (FiveM NUI), OS-level accessibility settings may not propagate from the host system.
+ */
+export function useReducedMotion(): MediaQueryState {
+  return useMediaQuery('(prefers-reduced-motion: reduce)');
+}
+
+/**
+ * Tracks high contrast / forced colors mode.
+ * Note: In embedded CEF (FiveM NUI), system contrast settings may not propagate from the host system.
+ */
+export function useHighContrast(): MediaQueryState {
+  return useMediaQuery('(forced-colors: active)');
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+// Actions
+export { default as NuiButton } from './components/actions/NuiButton.svelte';
+
+// Forms
+export { default as NuiForm } from './components/forms/NuiForm.svelte';
+export { default as NuiInput } from './components/forms/NuiInput.svelte';
+export { default as NuiCheckbox } from './components/forms/NuiCheckbox.svelte';
+export { default as NuiRadioGroup } from './components/forms/NuiRadioGroup.svelte';
+export type { NuiRadioOption } from './components/forms/NuiRadioGroup.svelte';
+export { default as NuiSelect } from './components/forms/NuiSelect.svelte';
+export type { NuiSelectOption } from './components/forms/NuiSelect.svelte';
+export { default as NuiDatepicker } from './components/forms/NuiDatepicker.svelte';
+export { default as NuiFileInput } from './components/forms/NuiFileInput.svelte';
+export type { FileInfo, FileMetadata } from './components/forms/NuiFileInput.types';
+
+// Layout
+export { default as NuiCard } from './components/layout/NuiCard.svelte';
+export { default as NuiCardGrid } from './components/layout/NuiCardGrid.svelte';
+export { default as NuiFlex } from './components/layout/NuiFlex.svelte';
+export { default as NuiGrid } from './components/layout/NuiGrid.svelte';
+export { default as NuiStack } from './components/layout/NuiStack.svelte';
+
+// Navigation
+export { default as NuiAccordion } from './components/navigation/NuiAccordion.svelte';
+export type { AccordionItem } from './components/navigation/NuiAccordion.svelte';
+export { default as NuiBreadcrumbs } from './components/navigation/NuiBreadcrumbs.svelte';
+export { default as NuiMenu } from './components/navigation/NuiMenu.svelte';
+export { default as NuiPagination } from './components/navigation/NuiPagination.svelte';
+export { default as NuiSidebar } from './components/navigation/NuiSidebar.svelte';
+export { default as NuiTabs } from './components/navigation/NuiTabs.svelte';
+export type { Tab } from './components/navigation/NuiTabs.svelte';
+
+// Overlay
+export { default as NuiDialog } from './components/overlay/NuiDialog.svelte';
+export type { NuiDialogAction } from './components/overlay/NuiDialog.svelte';
+export { default as NuiModal } from './components/overlay/NuiModal.svelte';
+export type { ModalAction } from './components/overlay/NuiModal.svelte';
+export { default as NuiTooltip } from './components/overlay/NuiTooltip.svelte';
+
+// Data display
+export { default as NuiBadge } from './components/data/NuiBadge.svelte';
+export { default as NuiChart } from './components/data/chart/NuiChart.svelte';
+export type { ChartData, ChartDataset, ChartOptions, ChartType } from './components/data/chart/types';
+export { default as NuiCodeBlock } from './components/data/NuiCodeBlock.svelte';
+export { default as NuiList } from './components/data/NuiList.svelte';
+export type { NuiListItem } from './components/data/NuiList.svelte';
+export { default as NuiProgressBar } from './components/data/NuiProgressBar.svelte';
+export { default as NuiRichText } from './components/data/NuiRichText.svelte';
+export { default as NuiTable } from './components/data/NuiTable.svelte';
+export type { Column as NuiTableColumn } from './components/data/NuiTable.svelte';
+
+// Composables
+export { validateForm, validateField } from './composables/useFormValidation';
+export type { ValidationRules } from './composables/useFormValidation';
+export {
+  useKeyboardShortcut,
+  useKeyboardShortcuts,
+  type KeyboardShortcut,
+  type KeyboardShortcutOptions,
+  type KeyboardShortcutsSource,
+  type KeyboardShortcutSource
+} from './composables/useKeyboardShortcut.svelte';
+export { useClickOutside, useClickOutsideElement, clickOutsideAction, type ClickOutsideOptions } from './composables/useClickOutside';
+export { useLocalStorage, type LocalStorageState } from './composables/useLocalStorage.svelte';
+export { useMediaQuery, useIsMobile, useIsTablet, useIsDesktop, useDarkMode, useReducedMotion, useHighContrast, type MediaQueryState } from './composables/useMediaQuery.svelte';
+export { useIdle, useIdleUntil, type IdleState } from './composables/useIdle.svelte';