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

package/dist/components/data/NuiList.svelte

@@ -0,0 +1,341 @@
+<!--
+  @component NuiList
+  Interactive list component supporting actions, icons, descriptions, and toggle switches.
+
+  Controlled Component:
+  Switch items follow a controlled state pattern where `switchValue` reflects the authoritative state
+  from backend/parent data. Toggling emits `switchEvent` and `onSwitchToggle` to request a state change.
+-->
+<script module lang="ts">
+  /**
+   * Represents an item in the {@link NuiList} component.
+   */
+  export interface NuiListItem {
+    /** Unique item identifier. Highly recommended for dynamic or reorderable lists. */
+    id?: string;
+    /** Primary display label. */
+    label: string;
+    /** Associated value (should be JSON-serializable if transmitted via NUI). */
+    value?: unknown;
+    /** Icon string, emoji, or icon character. */
+    icon?: string;
+    /** Secondary description text. */
+    description?: string;
+    /** Whether to render a toggle switch instead of an action button. */
+    switch?: boolean;
+    /** Current state of the toggle switch. */
+    switchValue?: boolean;
+    /** NUI event sent to game client when switch state is toggled. */
+    switchEvent?: string;
+    /** Item-specific NUI event sent on item click. */
+    eventName?: string;
+    /** Whether the item is disabled. */
+    disabled?: boolean;
+  }
+</script>
+
+<script lang="ts">
+  import { nui } from '@fivem-nui/svelte';
+  import type { SvelteNuiClient } from '@fivem-nui/svelte';
+
+  type MaybePromise<T> = T | Promise<T>;
+
+  interface Props {
+    /** Array of list items to display. */
+    items?: NuiListItem[];
+    /** SvelteNuiClient instance for event transport. */
+    client?: SvelteNuiClient;
+    /** Vertical density sizing. */
+    itemSize?: 'sm' | 'md' | 'lg';
+    /** Global NUI event name sent with `{ id, value }` when any row is activated. */
+    selectEvent?: string;
+    /** Local click callback executed when an item is activated (supports sync or async). */
+    onItemClick?: (item: NuiListItem) => MaybePromise<void>;
+    /** Local change callback executed when a switch item is toggled (supports sync or async). */
+    onSwitchToggle?: (item: NuiListItem, value: boolean) => MaybePromise<void>;
+  }
+
+  let {
+    items = [],
+    client = nui,
+    itemSize = 'md',
+    selectEvent = '',
+    onItemClick,
+    onSwitchToggle
+  }: Props = $props();
+
+  function safeCall(fn: (() => unknown) | undefined, errorPrefix: string): void {
+    if (!fn) return;
+    try {
+      const result = fn();
+      if (result && typeof (result as Promise<unknown>).catch === 'function') {
+        (result as Promise<unknown>).catch((err) => {
+          console.error(errorPrefix, err);
+        });
+      }
+    } catch (err) {
+      console.error(errorPrefix, err);
+    }
+  }
+
+  function handleItemClick(item: NuiListItem) {
+    if (item.disabled) return;
+    if (item.eventName) {
+      try {
+        client.send(item.eventName, { value: item.value, id: item.id });
+      } catch (err) {
+        console.error(`[fivem-nui-components] Failed to send event '${item.eventName}':`, err);
+      }
+    }
+    if (selectEvent) {
+      try {
+        client.send(selectEvent, { id: item.id, value: item.value });
+      } catch (err) {
+        console.error(`[fivem-nui-components] Failed to send selectEvent '${selectEvent}':`, err);
+      }
+    }
+    safeCall(
+      () => onItemClick?.(item),
+      '[fivem-nui-components] onItemClick callback error:'
+    );
+  }
+
+  function handleSwitch(item: NuiListItem) {
+    if (item.disabled) return;
+    const nextVal = !(item.switchValue ?? false);
+    if (item.switchEvent) {
+      try {
+        client.send(item.switchEvent, { id: item.id, value: nextVal });
+      } catch (err) {
+        console.error(`[fivem-nui-components] Failed to send switchEvent '${item.switchEvent}':`, err);
+      }
+    }
+    safeCall(
+      () => onSwitchToggle?.(item, nextVal),
+      '[fivem-nui-components] onSwitchToggle callback error:'
+    );
+  }
+</script>
+
+<ul class="nui-list nui-list--{itemSize}">
+  {#each items as item, index (item.id ?? `${item.label}-${index}`)}
+    <li class="nui-list-item" class:nui-list-item--switch={item.switch}>
+      {#if item.switch}
+        <label class="nui-list-item-label" class:disabled={item.disabled}>
+          {#if item.icon}
+            <span class="nui-list-item-icon" aria-hidden="true">{item.icon}</span>
+          {/if}
+          <span class="nui-list-item-text">
+            <span class="nui-list-item-title">{item.label}</span>
+            {#if item.description}
+              <span class="nui-list-item-description">{item.description}</span>
+            {/if}
+          </span>
+          <span class="nui-switch-wrapper">
+            <input
+              type="checkbox"
+              class="nui-switch__input"
+              checked={item.switchValue ?? false}
+              disabled={item.disabled}
+              onchange={() => handleSwitch(item)}
+            />
+            <span class="nui-switch" class:checked={item.switchValue ?? false} aria-hidden="true">
+              <span class="nui-switch__thumb"></span>
+            </span>
+          </span>
+        </label>
+      {:else}
+        <button
+          type="button"
+          class="nui-list-item-btn"
+          disabled={item.disabled}
+          onclick={() => handleItemClick(item)}
+        >
+          {#if item.icon}
+            <span class="nui-list-item-icon" aria-hidden="true">{item.icon}</span>
+          {/if}
+          <span class="nui-list-item-text">
+            <span class="nui-list-item-title">{item.label}</span>
+            {#if item.description}
+              <span class="nui-list-item-description">{item.description}</span>
+            {/if}
+          </span>
+        </button>
+      {/if}
+    </li>
+  {/each}
+</ul>
+
+<style>
+  .nui-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    font-family: inherit;
+    width: 100%;
+  }
+
+  .nui-list-item {
+    display: flex;
+    align-items: center;
+    border-bottom: 1px solid var(--nui-border, #27272a);
+  }
+
+  .nui-list-item:last-child {
+    border-bottom: none;
+  }
+
+  .nui-list-item-btn,
+  .nui-list-item-label {
+    box-sizing: border-box;
+  }
+
+  .nui-list--sm .nui-list-item-btn,
+  .nui-list--sm .nui-list-item-label {
+    padding: 0.4rem 0.625rem;
+  }
+  .nui-list--md .nui-list-item-btn,
+  .nui-list--md .nui-list-item-label {
+    padding: 0.6rem 0.875rem;
+  }
+  .nui-list--lg .nui-list-item-btn,
+  .nui-list--lg .nui-list-item-label {
+    padding: 0.85rem 1.125rem;
+  }
+
+  .nui-list-item-btn {
+    appearance: none;
+    -webkit-appearance: none;
+    border: none;
+    background: transparent;
+    padding: 0;
+    margin: 0;
+    font: inherit;
+    color: inherit;
+    text-align: left;
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    width: 100%;
+    cursor: pointer;
+    border-radius: var(--nui-radius, 0.375rem);
+    transition: background 0.15s ease;
+  }
+
+  .nui-list-item-btn:hover:not(:disabled) {
+    background: var(--nui-hover, rgb(255 255 255 / 0.04));
+  }
+
+  .nui-list-item-btn:disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+
+  .nui-list-item-btn:focus-visible {
+    outline: 2px solid var(--nui-primary, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  .nui-list-item-label {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+    width: 100%;
+    font-size: 0.875rem;
+    cursor: pointer;
+    border-radius: var(--nui-radius, 0.375rem);
+    transition: background 0.15s ease;
+  }
+
+  .nui-list-item-label:hover:not(.disabled) {
+    background: var(--nui-hover, rgb(255 255 255 / 0.04));
+  }
+
+  .nui-list-item-label.disabled {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+
+  .nui-list-item-icon {
+    font-size: 1.15rem;
+    line-height: 1;
+    flex-shrink: 0;
+  }
+
+  .nui-list-item-text {
+    display: flex;
+    flex-direction: column;
+    line-height: 1.3;
+    flex: 1;
+    min-width: 0;
+  }
+
+  .nui-list-item-title {
+    font-weight: 500;
+    font-size: 0.875rem;
+    color: var(--nui-fg, #fafafa);
+    overflow-wrap: anywhere;
+  }
+
+  .nui-list-item-description {
+    font-size: 0.75rem;
+    opacity: 0.65;
+    overflow-wrap: anywhere;
+  }
+
+  .nui-switch-wrapper {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+  }
+
+  .nui-switch__input {
+    position: absolute;
+    opacity: 0;
+    width: 0;
+    height: 0;
+    margin: 0;
+    pointer-events: none;
+  }
+
+  .nui-switch {
+    flex: none;
+    width: 2.25rem;
+    height: 1.25rem;
+    padding: 0.125rem;
+    border-radius: 999px;
+    background: var(--nui-surface-alt, #3f3f46);
+    border: 1px solid var(--nui-border, #52525b);
+    transition: background 0.2s ease, border-color 0.2s ease;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .nui-switch.checked {
+    background: var(--nui-primary, #3b82f6);
+    border-color: var(--nui-primary, #3b82f6);
+  }
+
+  .nui-switch__input:focus-visible + .nui-switch {
+    outline: 2px solid var(--nui-primary, #3b82f6);
+    outline-offset: 3px;
+  }
+
+  .nui-switch__thumb {
+    display: block;
+    width: 0.95rem;
+    height: 0.95rem;
+    border-radius: 50%;
+    background: #fff;
+    transition: transform 0.2s ease;
+  }
+
+  .nui-switch.checked .nui-switch__thumb {
+    transform: translateX(1rem);
+  }
+</style>

package/dist/components/data/NuiList.svelte.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Represents an item in the {@link NuiList} component.
+ */
+export interface NuiListItem {
+    /** Unique item identifier. Highly recommended for dynamic or reorderable lists. */
+    id?: string;
+    /** Primary display label. */
+    label: string;
+    /** Associated value (should be JSON-serializable if transmitted via NUI). */
+    value?: unknown;
+    /** Icon string, emoji, or icon character. */
+    icon?: string;
+    /** Secondary description text. */
+    description?: string;
+    /** Whether to render a toggle switch instead of an action button. */
+    switch?: boolean;
+    /** Current state of the toggle switch. */
+    switchValue?: boolean;
+    /** NUI event sent to game client when switch state is toggled. */
+    switchEvent?: string;
+    /** Item-specific NUI event sent on item click. */
+    eventName?: string;
+    /** Whether the item is disabled. */
+    disabled?: boolean;
+}
+import type { SvelteNuiClient } from '@fivem-nui/svelte';
+type MaybePromise<T> = T | Promise<T>;
+interface Props {
+    /** Array of list items to display. */
+    items?: NuiListItem[];
+    /** SvelteNuiClient instance for event transport. */
+    client?: SvelteNuiClient;
+    /** Vertical density sizing. */
+    itemSize?: 'sm' | 'md' | 'lg';
+    /** Global NUI event name sent with `{ id, value }` when any row is activated. */
+    selectEvent?: string;
+    /** Local click callback executed when an item is activated (supports sync or async). */
+    onItemClick?: (item: NuiListItem) => MaybePromise<void>;
+    /** Local change callback executed when a switch item is toggled (supports sync or async). */
+    onSwitchToggle?: (item: NuiListItem, value: boolean) => MaybePromise<void>;
+}
+/**
+ * NuiList
+ * Interactive list component supporting actions, icons, descriptions, and toggle switches.
+ *
+ * Controlled Component:
+ * Switch items follow a controlled state pattern where `switchValue` reflects the authoritative state
+ * from backend/parent data. Toggling emits `switchEvent` and `onSwitchToggle` to request a state change.
+ */
+declare const NuiList: import("svelte").Component<Props, {}, "">;
+type NuiList = ReturnType<typeof NuiList>;
+export default NuiList;

package/dist/components/data/NuiProgressBar.svelte

@@ -0,0 +1,264 @@
+<!--
+  @component NuiProgressBar
+  Accessible progress bar component with real-time NUI sync, custom colors, and percentage indicators.
+
+  Data Precedence & Synchronization:
+  - If `eventName` is specified, the component listens for incoming progress payloads (number or `{ value, max }`).
+  - Incoming NUI updates take precedence over initial `value`/`max` props.
+  - If the parent component changes `value`, `max`, or `eventName` props, remote overrides are reset.
+
+  Completion Contract:
+  - Completion is detected when `safeValue >= safeMax` (not by rounded percent).
+  - Fires `onComplete` and emits `completeEvent` once when reaching 100%.
+  - If progress drops below 100% and reaches 100% again, the completion handlers are re-triggered.
+
+  Label Behavior:
+  - `labelPosition === 'top'` renders the label above the track on the left, with percentage on the right.
+  - `labelPosition === 'inside'` renders the text label inside the progress fill, while percentage (if enabled) remains above the track.
+-->
+<script lang="ts">
+  import { nui } from '@fivem-nui/svelte';
+  import type { SvelteNuiClient } from '@fivem-nui/svelte';
+
+  type MaybePromise<T> = T | Promise<T>;
+
+  interface Props {
+    /** Current progress value. */
+    value?: number;
+    /** Maximum progress value. Defaults to 100 if <= 0, NaN, or non-finite. */
+    max?: number;
+    /** Text label describing the progress (e.g. "Downloading resources"). */
+    label?: string;
+    /** Custom CSS color override for the fill bar. */
+    color?: string;
+    /** Whether to display the percentage number. */
+    showPercentage?: boolean;
+    /** Position of the text label ('top' above track, 'inside' within fill bar). */
+    labelPosition?: 'top' | 'inside';
+    /** Sizing density. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Color palette variant. */
+    variant?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+    /** Optional NUI event name to listen for progress updates from the game backend. */
+    eventName?: string;
+    /** Optional NUI event name sent to the game backend once progress reaches 100%. */
+    completeEvent?: string;
+    /** Callback executed when progress reaches 100% (safe for sync or async). */
+    onComplete?: () => MaybePromise<void>;
+    /** Accessible label for screen readers (defaults to label or "Progress"). */
+    ariaLabel?: string;
+    /** SvelteNuiClient instance for event transport. */
+    client?: SvelteNuiClient;
+  }
+
+  let {
+    value = 0,
+    max = 100,
+    label,
+    color,
+    showPercentage = false,
+    labelPosition = 'top',
+    size = 'md',
+    variant = 'primary',
+    eventName,
+    completeEvent,
+    onComplete,
+    ariaLabel,
+    client = nui
+  }: Props = $props();
+
+  let remoteValue = $state<number | null>(null);
+  let remoteMax = $state<number | null>(null);
+
+  let lastPropsValue = value;
+  let lastPropsMax = max;
+  let lastEventName = eventName;
+
+  // Reset remote overrides when parent updates props or switches eventName
+  $effect(() => {
+    if (value !== lastPropsValue || max !== lastPropsMax || eventName !== lastEventName) {
+      lastPropsValue = value;
+      lastPropsMax = max;
+      lastEventName = eventName;
+      remoteValue = null;
+      remoteMax = null;
+    }
+  });
+
+  // Listen for real-time progress updates from NUI game client
+  $effect(() => {
+    if (!eventName || !client) return;
+    const unsub = client.on(eventName, (payload: unknown) => {
+      if (typeof payload === 'number' && Number.isFinite(payload)) {
+        remoteValue = payload;
+      } else if (payload && typeof payload === 'object') {
+        const obj = payload as Record<string, unknown>;
+        if (typeof obj.value === 'number' && Number.isFinite(obj.value)) {
+          remoteValue = obj.value;
+        }
+        if (typeof obj.max === 'number' && Number.isFinite(obj.max)) {
+          remoteMax = obj.max;
+        }
+      }
+    });
+    return () => unsub();
+  });
+
+  const activeValue = $derived(remoteValue ?? value);
+  const activeMax = $derived(remoteMax ?? max);
+
+  const safeMax = $derived(
+    typeof activeMax === 'number' && Number.isFinite(activeMax) && activeMax > 0
+      ? activeMax
+      : 100
+  );
+
+  const safeValue = $derived(
+    typeof activeValue === 'number' && Number.isFinite(activeValue)
+      ? Math.max(0, Math.min(safeMax, activeValue))
+      : 0
+  );
+
+  const clampedPercent = $derived(
+    safeMax > 0 ? Math.min(100, Math.max(0, Math.round((safeValue / safeMax) * 100))) : 0
+  );
+
+  const isComplete = $derived(safeValue >= safeMax);
+
+  let hasCompleted = $state(false);
+
+  function safeCall(fn: (() => unknown) | undefined, errorPrefix: string): void {
+    if (!fn) return;
+    try {
+      const result = fn();
+      if (result && typeof (result as Promise<unknown>).catch === 'function') {
+        (result as Promise<unknown>).catch((err) => {
+          console.error(errorPrefix, err);
+        });
+      }
+    } catch (err) {
+      console.error(errorPrefix, err);
+    }
+  }
+
+  $effect(() => {
+    if (isComplete) {
+      if (!hasCompleted) {
+        hasCompleted = true;
+        if (completeEvent) {
+          try {
+            client.send(completeEvent, { value: safeValue, max: safeMax });
+          } catch (err) {
+            console.error(`[fivem-nui-components] Failed to send completeEvent '${completeEvent}':`, err);
+          }
+        }
+        safeCall(() => onComplete?.(), '[fivem-nui-components] onComplete callback error:');
+      }
+    } else {
+      hasCompleted = false;
+    }
+  });
+
+  const resolvedAriaLabel = $derived(ariaLabel || label || 'Progress');
+  const resolvedAriaValueText = $derived(`${clampedPercent}%`);
+</script>
+
+<div class="nui-progress-bar nui-progress-bar--{size}">
+  {#if (label && labelPosition === 'top') || showPercentage}
+    <div class="nui-progress-bar__label">
+      {#if label && labelPosition === 'top'}
+        <span>{label}</span>
+      {/if}
+      {#if showPercentage}
+        <span class="nui-progress-bar__percent">{clampedPercent}%</span>
+      {/if}
+    </div>
+  {/if}
+
+  <div
+    class="nui-progress-bar__track"
+    role="progressbar"
+    aria-label={resolvedAriaLabel}
+    aria-valuenow={safeValue}
+    aria-valuemin={0}
+    aria-valuemax={safeMax}
+    aria-valuetext={resolvedAriaValueText}
+  >
+    <div
+      class="nui-progress-bar__fill nui-progress-bar__fill--{variant}"
+      style:width="{clampedPercent}%"
+      style:background={color || undefined}
+      aria-hidden="true"
+    >
+      {#if label && labelPosition === 'inside'}
+        <span class="nui-progress-bar__inner-label">
+          {label}
+        </span>
+      {/if}
+    </div>
+  </div>
+</div>
+
+<style>
+  .nui-progress-bar {
+    display: flex;
+    flex-direction: column;
+    gap: 0.35rem;
+    font-family: inherit;
+    width: 100%;
+    box-sizing: border-box;
+  }
+
+  .nui-progress-bar__label {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    font-size: 0.8125rem;
+    color: var(--nui-fg, #fafafa);
+    opacity: 0.85;
+    line-height: 1.2;
+  }
+
+  .nui-progress-bar__percent {
+    font-weight: 600;
+    margin-left: auto;
+  }
+
+  .nui-progress-bar__track {
+    width: 100%;
+    background: var(--nui-surface-alt, #27272a);
+    border: 1px solid var(--nui-border, #3f3f46);
+    border-radius: var(--nui-radius, 0.375rem);
+    overflow: hidden;
+    position: relative;
+    box-sizing: border-box;
+  }
+
+  .nui-progress-bar--sm .nui-progress-bar__track { height: 0.75rem; }
+  .nui-progress-bar--md .nui-progress-bar__track { height: 1.25rem; }
+  .nui-progress-bar--lg .nui-progress-bar__track { height: 1.75rem; }
+
+  .nui-progress-bar__fill {
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: width 0.3s ease;
+    border-radius: inherit;
+  }
+
+  .nui-progress-bar__fill--primary { background: var(--nui-primary, #3b82f6); }
+  .nui-progress-bar__fill--secondary { background: var(--nui-secondary, #8b8b99); }
+  .nui-progress-bar__fill--success { background: var(--nui-success, #22c55e); }
+  .nui-progress-bar__fill--warning { background: var(--nui-warning, #f59e0b); }
+  .nui-progress-bar__fill--danger { background: var(--nui-danger, #ef4444); }
+
+  .nui-progress-bar__inner-label {
+    color: #fff;
+    font-size: 0.75rem;
+    font-weight: 600;
+    padding: 0 0.5rem;
+    white-space: nowrap;
+    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.6);
+  }
+</style>

package/dist/components/data/NuiProgressBar.svelte.d.ts

@@ -0,0 +1,51 @@
+import type { SvelteNuiClient } from '@fivem-nui/svelte';
+type MaybePromise<T> = T | Promise<T>;
+interface Props {
+    /** Current progress value. */
+    value?: number;
+    /** Maximum progress value. Defaults to 100 if <= 0, NaN, or non-finite. */
+    max?: number;
+    /** Text label describing the progress (e.g. "Downloading resources"). */
+    label?: string;
+    /** Custom CSS color override for the fill bar. */
+    color?: string;
+    /** Whether to display the percentage number. */
+    showPercentage?: boolean;
+    /** Position of the text label ('top' above track, 'inside' within fill bar). */
+    labelPosition?: 'top' | 'inside';
+    /** Sizing density. */
+    size?: 'sm' | 'md' | 'lg';
+    /** Color palette variant. */
+    variant?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+    /** Optional NUI event name to listen for progress updates from the game backend. */
+    eventName?: string;
+    /** Optional NUI event name sent to the game backend once progress reaches 100%. */
+    completeEvent?: string;
+    /** Callback executed when progress reaches 100% (safe for sync or async). */
+    onComplete?: () => MaybePromise<void>;
+    /** Accessible label for screen readers (defaults to label or "Progress"). */
+    ariaLabel?: string;
+    /** SvelteNuiClient instance for event transport. */
+    client?: SvelteNuiClient;
+}
+/**
+ * NuiProgressBar
+ * Accessible progress bar component with real-time NUI sync, custom colors, and percentage indicators.
+ *
+ * Data Precedence & Synchronization:
+ * - If `eventName` is specified, the component listens for incoming progress payloads (number or `{ value, max }`).
+ * - Incoming NUI updates take precedence over initial `value`/`max` props.
+ * - If the parent component changes `value`, `max`, or `eventName` props, remote overrides are reset.
+ *
+ * Completion Contract:
+ * - Completion is detected when `safeValue >= safeMax` (not by rounded percent).
+ * - Fires `onComplete` and emits `completeEvent` once when reaching 100%.
+ * - If progress drops below 100% and reaches 100% again, the completion handlers are re-triggered.
+ *
+ * Label Behavior:
+ * - `labelPosition === 'top'` renders the label above the track on the left, with percentage on the right.
+ * - `labelPosition === 'inside'` renders the text label inside the progress fill, while percentage (if enabled) remains above the track.
+ */
+declare const NuiProgressBar: import("svelte").Component<Props, {}, "">;
+type NuiProgressBar = ReturnType<typeof NuiProgressBar>;
+export default NuiProgressBar;