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

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@fivem-nui/svelte-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "UI components for FiveM NUI built on Svelte 5",
+  "type": "module",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./src": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "svelte-package -i src -o dist",
+    "check": "tsc --noEmit --skipLibCheck --moduleResolution bundler --allowJs --esModuleInterop --strict",
+    "test": "npx --prefix ../bridge vitest run --config ../bridge/vitest.config.ts"
+  },
+  "keywords": [
+    "fivem",
+    "nui",
+    "components",
+    "svelte"
+  ],
+  "author": "Rainbe",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rian-be/FiveM.Nui.git",
+    "directory": "packages/svelte/components"
+  },
+  "bugs": {
+    "url": "https://github.com/rian-be/FiveM.Nui/issues"
+  },
+  "homepage": "https://github.com/rian-be/FiveM.Nui/tree/main/packages/svelte/components#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "@fivem-nui/core": "^1.0.0",
+    "@fivem-nui/svelte": "^1.0.0",
+    "svelte": "^5.20.0"
+  },
+  "dependencies": {
+    "esm-env": "^1.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.0.0",
+    "svelte": "^5.20.0",
+    "typescript": "^5.7.3"
+  }
 }

package/src/components/actions/NuiButton.svelte

@@ -0,0 +1,292 @@
+<script lang="ts">
+  import { nui } from '@fivem-nui/svelte';
+  import type { SvelteNuiClient } from '@fivem-nui/svelte';
+
+  interface Props {
+    /** Event name sent to the game when the button is clicked. */
+    eventName?: string;
+    /** Payload sent along with {@link eventName}. */
+    payload?: unknown;
+    client?: SvelteNuiClient;
+    loading?: boolean;
+    disabled?: boolean;
+    type?: 'button' | 'submit' | 'reset';
+    variant?: 'primary' | 'secondary' | 'danger' | 'link';
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    /** Event sent right after the main NUI operation succeeds. */
+    onSuccess?: string;
+    /**
+     * Event sent when the local handler or main NUI operation fails.
+     * Note: A failure in sending onSuccess will not trigger this.
+     */
+    onError?: string;
+    onSuccessPayload?: unknown;
+    onErrorPayload?: unknown;
+    /** Local callback invoked when the operation fails. */
+    onFailure?: (error: unknown) => void;
+    /** Local callback invoked when the operation succeeds. */
+    onSuccessCallback?: (result?: unknown) => void;
+    /**
+     * Predicate deciding whether the button is currently enabled.
+     * Function must read reactive Svelte state to update automatically.
+     */
+    condition?: (() => boolean) | null;
+    /**
+     * Predicate or boolean that disables the button when true.
+     * Function must read reactive Svelte state to update automatically.
+     */
+    disabledWhen?: (() => boolean) | boolean | null;
+    /**
+     * When true, keeps loading state true upon successful completion.
+     * The parent component is responsible for resetting loading via bind:loading.
+     * On error, loading is always reset to false if autoReset is true.
+     */
+    keepLoadingOnSuccess?: boolean;
+    /**
+     * @deprecated Use {@link keepLoadingOnSuccess} instead.
+     */
+    autoUpdateOnSuccess?: boolean;
+    /**
+     * Reset loading state automatically after click.
+     * Set to false if parent exclusively manages loading state via bind:loading.
+     */
+    autoReset?: boolean;
+    /**
+     * Local click handler, invoked before the NUI event. Can be async.
+     * Return `false` or call `event.preventDefault()` to cancel the subsequent NUI event.
+     */
+    onclick?: (event: MouseEvent) => boolean | void | Promise<boolean | void>;
+    children?: import('svelte').Snippet;
+  }
+
+  let {
+    eventName = '',
+    payload = undefined,
+    client = nui,
+    loading = $bindable(false),
+    disabled = $bindable(false),
+    type = 'button',
+    variant = 'primary',
+    size = 'md',
+    onSuccess = '',
+    onError = '',
+    onSuccessPayload = {},
+    onErrorPayload = {},
+    onFailure,
+    onSuccessCallback,
+    condition = null,
+    disabledWhen = null,
+    keepLoadingOnSuccess = false,
+    autoUpdateOnSuccess = false,
+    autoReset = true,
+    onclick,
+    children
+  }: Props = $props();
+
+  const shouldKeepLoading = $derived(keepLoadingOnSuccess || autoUpdateOnSuccess);
+
+  const isEnabled = $derived.by(() => {
+    if (condition && typeof condition === 'function' && !condition()) return false;
+    if (disabledWhen) {
+      if (typeof disabledWhen === 'function') {
+        if (disabledWhen()) return false;
+      } else if (typeof disabledWhen === 'boolean') {
+        if (disabledWhen) return false;
+      }
+    }
+    return true;
+  });
+
+  async function dispatchClientEvent(name: string, data?: unknown): Promise<unknown> {
+    if ('sendAndWait' in client && typeof client.sendAndWait === 'function') {
+      return await client.sendAndWait(name, data);
+    }
+    return client.send(name, data);
+  }
+
+  async function handleClick(event: MouseEvent) {
+    if (!isEnabled || loading || disabled) return;
+
+    // If there is no NUI event and no custom onclick, let native action proceed
+    if (!eventName && !onclick) {
+      return;
+    }
+
+    loading = true;
+    let hasError = false;
+
+    try {
+      // 1. Run local onclick hook
+      if (onclick) {
+        const initialPrevented = event.defaultPrevented;
+        const result = await onclick(event);
+
+        // Cancel if onclick returned false or marked event as defaultPrevented
+        if (result === false || (!initialPrevented && event.defaultPrevented)) {
+          if (autoReset) {
+            loading = false;
+          }
+          return;
+        }
+      }
+
+      // 2. Prevent native form submission/reset if proceeding with NUI event
+      if (eventName && (type === 'submit' || type === 'reset')) {
+        event.preventDefault();
+      }
+
+      // 3. Send main NUI event
+      let operationResult: unknown = undefined;
+      if (eventName) {
+        operationResult = await dispatchClientEvent(eventName, payload);
+
+        // Handle clients or mocks returning an explicit failure envelope { success: false, error: ... }
+        if (
+          operationResult &&
+          typeof operationResult === 'object' &&
+          'success' in operationResult &&
+          (operationResult as { success?: boolean }).success === false
+        ) {
+          const envelope = operationResult as { error?: { message?: string } | string };
+          const errMsg =
+            typeof envelope.error === 'object' && envelope.error !== null
+              ? envelope.error.message || 'NUI operation returned failure'
+              : typeof envelope.error === 'string'
+                ? envelope.error
+                : 'NUI operation returned failure';
+          throw new Error(errMsg);
+        }
+      }
+
+      // 4. Trigger local success callback
+      onSuccessCallback?.(operationResult);
+
+      // 5. Send success notification event (isolated so its failure does not trigger onError)
+      if (onSuccess) {
+        try {
+          await dispatchClientEvent(onSuccess, onSuccessPayload);
+        } catch (successSendError) {
+          console.warn(
+            `[NuiButton] Main operation succeeded, but failed to dispatch onSuccess event '${onSuccess}':`,
+            successSendError
+          );
+        }
+      }
+    } catch (error) {
+      hasError = true;
+      const message = error instanceof Error ? error.message : String(error);
+
+      // Trigger local failure callback
+      onFailure?.(error);
+
+      const basePayload =
+        typeof onErrorPayload === 'object' && onErrorPayload !== null && !Array.isArray(onErrorPayload)
+          ? onErrorPayload
+          : { payload: onErrorPayload };
+
+      if (onError) {
+        try {
+          await dispatchClientEvent(onError, { ...basePayload, error: message });
+        } catch (sendErr) {
+          console.error(`[NuiButton] Failed to dispatch onError event '${onError}':`, sendErr);
+        }
+      }
+
+      console.error(`[NuiButton] Error handling click for event '${eventName || 'local'}':`, error);
+    } finally {
+      if (autoReset) {
+        if (hasError || !shouldKeepLoading) {
+          loading = false;
+        }
+      }
+    }
+  }
+</script>
+
+<button
+  {type}
+  class="nui-btn nui-btn--{variant} nui-btn--{size}"
+  disabled={!isEnabled || disabled || loading}
+  aria-busy={loading}
+  onclick={handleClick}
+>
+  {#if loading}
+    <span class="nui-btn__spinner" aria-hidden="true"></span>
+  {/if}
+  {@render children?.()}
+</button>
+
+<style>
+  .nui-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    border: 1px solid transparent;
+    border-radius: var(--nui-radius, 0.375rem);
+    font-family: inherit;
+    font-weight: 600;
+    line-height: 1;
+    cursor: pointer;
+    transition: background 0.15s ease, border-color 0.15s ease, opacity 0.15s ease;
+    box-sizing: border-box;
+  }
+
+  .nui-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .nui-btn--xs { padding: 0.2rem 0.5rem;    font-size: 0.75rem; }
+  .nui-btn--sm { padding: 0.25rem 0.625rem; font-size: 0.8125rem; }
+  .nui-btn--md { padding: 0.5rem 0.875rem;   font-size: 0.9375rem; }
+  .nui-btn--lg { padding: 0.75rem 1.25rem;  font-size: 1.0625rem; }
+
+  .nui-btn--primary {
+    background: var(--nui-primary, #3b82f6);
+    color: #fff;
+  }
+  .nui-btn--primary:hover:not(:disabled) {
+    background: var(--nui-primary-hover, #2563eb);
+  }
+
+  .nui-btn--secondary {
+    background: transparent;
+    border-color: var(--nui-border, #3f3f46);
+    color: var(--nui-fg, #fafafa);
+  }
+  .nui-btn--secondary:hover:not(:disabled) {
+    background: var(--nui-hover, rgb(255 255 255 / 0.06));
+  }
+
+  .nui-btn--danger {
+    background: var(--nui-danger, #ef4444);
+    color: #fff;
+  }
+  .nui-btn--danger:hover:not(:disabled) {
+    background: var(--nui-danger-hover, #dc2626);
+  }
+
+  .nui-btn--link {
+    background: transparent;
+    color: var(--nui-primary, #3b82f6);
+    padding-left: 0;
+    padding-right: 0;
+  }
+  .nui-btn--link:hover:not(:disabled) {
+    text-decoration: underline;
+  }
+
+  .nui-btn__spinner {
+    width: 0.85em;
+    height: 0.85em;
+    border: 2px solid currentColor;
+    border-right-color: transparent;
+    border-radius: 50%;
+    animation: nui-btn-spin 0.6s linear infinite;
+  }
+
+  @keyframes nui-btn-spin {
+    to { transform: rotate(360deg); }
+  }
+</style>

package/src/components/data/NuiBadge.svelte

@@ -0,0 +1,277 @@
+<!--
+  @component NuiBadge
+  Status badge and notification counter component.
+-->
+<script lang="ts">
+  interface Props {
+    /** Text or snippet content rendered inside the badge. */
+    children?: import("svelte").Snippet;
+    /**
+     * Numerical counter value (e.g. notification count).
+     * Negative, non-numeric, or infinite values are normalized to 0.
+     * @defaultValue 0
+     */
+    count?: number;
+    /**
+     * Whether to display the counter when count is 0.
+     * When false (default), a count of 0 falls back to children or a dot indicator.
+     * @defaultValue false
+     */
+    showZero?: boolean;
+    /**
+     * Maximum displayed counter value (e.g. 99 displays as "99+").
+     * @defaultValue 99
+     */
+    maxCount?: number;
+    /**
+     * Color variant.
+     * @defaultValue 'primary'
+     */
+    variant?:
+      | "primary"
+      | "secondary"
+      | "success"
+      | "warning"
+      | "danger"
+      | "info";
+    /**
+     * Size of the badge.
+     * @defaultValue 'md'
+     */
+    size?: "xs" | "sm" | "md" | "lg";
+    /**
+     * Outline style with transparent background and colored border.
+     * @defaultValue false
+     */
+    outline?: boolean;
+    /**
+     * Pill-shaped rounded borders.
+     * @defaultValue true
+     */
+    rounded?: boolean;
+    /**
+     * Visibility of the badge.
+     * @defaultValue true
+     */
+    visible?: boolean;
+    /**
+     * Whether the badge is interactive (automatically true when onclick is provided).
+     * @defaultValue false
+     */
+    clickable?: boolean;
+    /**
+     * Whether the clickable badge is disabled.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+    /**
+     * Accessible description for screen readers.
+     * Recommended for interactive badges or badges displaying only symbols/numbers.
+     */
+    ariaLabel?: string;
+    /**
+     * Optional role (defaults to "status" when ariaLabel is provided on a non-interactive <span>).
+     */
+    role?: string;
+    /** Click event handler. */
+    onclick?: (event: MouseEvent) => void;
+  }
+
+  let {
+    children,
+    count = 0,
+    showZero = false,
+    maxCount = 99,
+    variant = "primary",
+    size = "md",
+    outline = false,
+    rounded = true,
+    visible = true,
+    clickable = false,
+    disabled = false,
+    ariaLabel,
+    role,
+    onclick,
+  }: Props = $props();
+
+  const normalizedCount = $derived(
+    Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0,
+  );
+  const normalizedMaxCount = $derived(
+    Number.isFinite(maxCount) ? Math.max(1, Math.floor(maxCount)) : 99,
+  );
+  const showCount = $derived(
+    normalizedCount > 0 || (showZero && count !== undefined),
+  );
+  const displayCount = $derived(
+    normalizedCount > normalizedMaxCount
+      ? `${normalizedMaxCount}+`
+      : normalizedCount,
+  );
+  const isClickable = $derived(clickable || typeof onclick === "function");
+  const resolvedRole = $derived(
+    role ?? (ariaLabel && !isClickable ? "status" : undefined),
+  );
+</script>
+
+{#if visible}
+  {#if isClickable}
+    <button
+      type="button"
+      class="nui-badge nui-badge--{variant} nui-badge--{size} nui-badge--clickable"
+      class:nui-badge--outline={outline}
+      class:nui-badge--rounded={rounded}
+      class:nui-badge--square={!rounded}
+      aria-label={ariaLabel}
+      {disabled}
+      {onclick}
+    >
+      {#if showCount}
+        {displayCount}
+      {:else if children}
+        {@render children()}
+      {:else}
+        <span aria-hidden="true">●</span>
+      {/if}
+    </button>
+  {:else}
+    <span
+      class="nui-badge nui-badge--{variant} nui-badge--{size}"
+      class:nui-badge--outline={outline}
+      class:nui-badge--rounded={rounded}
+      class:nui-badge--square={!rounded}
+      aria-label={ariaLabel}
+      role={resolvedRole}
+    >
+      {#if showCount}
+        {displayCount}
+      {:else if children}
+        {@render children()}
+      {:else}
+        <span aria-hidden="true">●</span>
+      {/if}
+    </span>
+  {/if}
+{/if}
+
+<style>
+  .nui-badge {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font: inherit;
+    font-weight: 600;
+    line-height: 1;
+    text-align: center;
+    border: 1px solid transparent;
+    transition:
+      opacity 0.15s ease,
+      background 0.15s ease,
+      border-color 0.15s ease;
+    box-sizing: border-box;
+    vertical-align: middle;
+  }
+
+  button.nui-badge {
+    appearance: none;
+    -webkit-appearance: none;
+    color: inherit;
+    padding: 0;
+    cursor: pointer;
+  }
+
+  button.nui-badge:focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+
+  .nui-badge--clickable {
+    cursor: pointer;
+  }
+
+  .nui-badge--clickable:hover:not(:disabled) {
+    opacity: 0.85;
+  }
+
+  .nui-badge--clickable:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+
+  .nui-badge--primary {
+    background: var(--nui-primary, #3b82f6);
+    color: #fff;
+  }
+  .nui-badge--secondary {
+    background: var(--nui-surface-alt, #3f3f46);
+    color: var(--nui-fg, #fafafa);
+  }
+  .nui-badge--success {
+    background: var(--nui-success, #22c55e);
+    color: #fff;
+  }
+  .nui-badge--warning {
+    background: var(--nui-warning, #f59e0b);
+    color: #18181b;
+  }
+  .nui-badge--danger {
+    background: var(--nui-danger, #ef4444);
+    color: #fff;
+  }
+  .nui-badge--info {
+    background: var(--nui-info, #06b6d4);
+    color: #fff;
+  }
+
+  .nui-badge.nui-badge--outline {
+    background: transparent;
+  }
+  .nui-badge.nui-badge--outline.nui-badge--primary {
+    border-color: var(--nui-primary, #3b82f6);
+    color: var(--nui-primary, #3b82f6);
+  }
+  .nui-badge.nui-badge--outline.nui-badge--secondary {
+    border-color: var(--nui-border, #3f3f46);
+    color: var(--nui-fg-secondary, #8b8b99);
+  }
+  .nui-badge.nui-badge--outline.nui-badge--success {
+    border-color: var(--nui-success, #22c55e);
+    color: var(--nui-success, #22c55e);
+  }
+  .nui-badge.nui-badge--outline.nui-badge--warning {
+    border-color: var(--nui-warning, #f59e0b);
+    color: var(--nui-warning, #f59e0b);
+  }
+  .nui-badge.nui-badge--outline.nui-badge--danger {
+    border-color: var(--nui-danger, #ef4444);
+    color: var(--nui-danger, #ef4444);
+  }
+  .nui-badge.nui-badge--outline.nui-badge--info {
+    border-color: var(--nui-info, #06b6d4);
+    color: var(--nui-info, #06b6d4);
+  }
+
+  .nui-badge--xs {
+    padding: 0.125rem 0.35rem;
+    font-size: 0.625rem;
+  }
+  .nui-badge--sm {
+    padding: 0.2rem 0.5rem;
+    font-size: 0.75rem;
+  }
+  .nui-badge--md {
+    padding: 0.3rem 0.65rem;
+    font-size: 0.8125rem;
+  }
+  .nui-badge--lg {
+    padding: 0.4rem 0.85rem;
+    font-size: 0.9375rem;
+  }
+
+  .nui-badge--rounded {
+    border-radius: 9999px;
+  }
+  .nui-badge--square {
+    border-radius: var(--nui-radius, 0.25rem);
+  }
+</style>