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

package/src/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/src/components/data/NuiRichText.svelte

@@ -0,0 +1,260 @@
+<!--
+  @component NuiRichText
+  Renders formatted text or sanitized HTML content.
+
+  Security Policy & Sanitization:
+  - Default Mode (`parseHtml = false`):
+    Safe by default. Content is rendered via Svelte's native text binding inside `<pre>`,
+    preventing any HTML or script execution.
+  - HTML Mode (`parseHtml = true`):
+    Enables HTML parsing. Applies an allowlist of safe formatting tags/attributes, protocol
+    filtering on links (http, https, mailto, safe relative URLs), unwraps benign wrapper tags,
+    and drops dangerous elements (script, style, iframe, etc.).
+  - Custom Sanitizer:
+    For untrusted or user-submitted content (e.g. player chat, server announcements, external API data),
+    pass an enterprise-grade sanitizer (e.g. `DOMPurify.sanitize`) via the `sanitizer` prop.
+    The provided sanitizer function must return an XSS-safe HTML string.
+-->
+<script lang="ts">
+  interface Props {
+    /** Text or HTML content to display. */
+    content: string;
+    /** Whether to parse and render content as HTML. Defaults to false. */
+    parseHtml?: boolean;
+    /**
+     * Optional custom sanitizer function (e.g. DOMPurify.sanitize).
+     * Must return an XSS-safe HTML string.
+     */
+    sanitizer?: ((dirty: string) => string) | null;
+    /** Optional additional CSS class for root container. */
+    className?: string;
+  }
+
+  let {
+    content,
+    parseHtml = false,
+    sanitizer = null,
+    className = ''
+  }: Props = $props();
+
+  const ALLOWED_TAGS = new Set([
+    'a', 'b', 'blockquote', 'br', 'code', 'dd', 'del', 'div', 'dl', 'dt',
+    'em', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'i', 'ins', 'kbd',
+    'li', 'mark', 'ol', 'p', 'pre', 's', 'small', 'span', 'strike',
+    'strong', 'sub', 'sup', 'time', 'u', 'ul'
+  ]);
+
+  const DROP_CONTENT_TAGS = new Set([
+    'script', 'style', 'iframe', 'noembed', 'noframes', 'noscript',
+    'object', 'embed', 'template', 'svg', 'canvas', 'audio', 'video',
+    'input', 'textarea', 'select', 'button', 'form'
+  ]);
+
+  const ALLOWED_ATTRS: Record<string, Set<string>> = {
+    a: new Set(['href', 'title', 'target', 'rel']),
+    time: new Set(['datetime']),
+    '*': new Set(['class', 'title', 'aria-label', 'aria-hidden'])
+  };
+
+  // Strict ISO-8601 date/time (e.g. 2026-10-17, 2026-10-17T14:30:00Z)
+  const ISO_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2}(?:[T\s]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+
+  function escapeHtml(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#039;');
+  }
+
+  /**
+   * Validates whether a URL uses a safe protocol (http, https, mailto, or relative).
+   * Rejects control characters, protocol-relative URLs (//...), and dangerous schemes.
+   */
+  function isSafeUrl(urlStr: string): boolean {
+    const value = urlStr.trim();
+
+    // Reject control characters rather than trying to normalize them
+    if (/[\u0000-\u001F\u007F-\u009F]/.test(value)) {
+      return false;
+    }
+
+    // Allow ordinary relative URLs, but reject protocol-relative URLs (//...)
+    if (value.startsWith('/') && !value.startsWith('//')) {
+      return true;
+    }
+
+    // Allow anchors and query parameters
+    if (value.startsWith('#') || value.startsWith('?')) {
+      return true;
+    }
+
+    try {
+      const parsed = new URL(value);
+      return (
+        parsed.protocol === 'https:' ||
+        parsed.protocol === 'http:' ||
+        parsed.protocol === 'mailto:'
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  function cleanNode(node: Node): void {
+    const children = Array.from(node.childNodes);
+
+    for (const child of children) {
+      if (child.nodeType === Node.ELEMENT_NODE) {
+        const el = child as HTMLElement;
+        const tagName = el.tagName.toLowerCase();
+
+        // Completely discard dangerous elements and their subtrees
+        if (DROP_CONTENT_TAGS.has(tagName)) {
+          node.removeChild(child);
+          continue;
+        }
+
+        // Unwrap benign wrapper elements not in allowlist, preserving their sanitized text/children
+        if (!ALLOWED_TAGS.has(tagName)) {
+          cleanNode(child);
+          while (child.firstChild) {
+            node.insertBefore(child.firstChild, child);
+          }
+          node.removeChild(child);
+          continue;
+        }
+
+        const attrs = Array.from(el.attributes);
+        for (const attr of attrs) {
+          const attrName = attr.name.toLowerCase();
+          const allowedForTag = ALLOWED_ATTRS[tagName];
+          const allowedGlobal = ALLOWED_ATTRS['*'];
+          const isAllowed =
+            (allowedForTag && allowedForTag.has(attrName)) ||
+            (allowedGlobal && allowedGlobal.has(attrName));
+
+          if (!isAllowed || attrName.startsWith('on')) {
+            el.removeAttribute(attr.name);
+            continue;
+          }
+
+          if (attrName === 'href' && !isSafeUrl(attr.value)) {
+            el.removeAttribute(attr.name);
+            continue;
+          }
+
+          if (attrName === 'datetime' && !ISO_DATETIME_REGEX.test(attr.value.trim())) {
+            el.removeAttribute(attr.name);
+            continue;
+          }
+        }
+
+        if (tagName === 'a') {
+          el.setAttribute('rel', 'noopener noreferrer');
+        }
+
+        cleanNode(child);
+      } else if (
+        child.nodeType !== Node.TEXT_NODE &&
+        child.nodeType !== Node.COMMENT_NODE
+      ) {
+        node.removeChild(child);
+      }
+    }
+  }
+
+  function defaultSanitize(dirtyHtml: string): string {
+    if (typeof window === 'undefined' || typeof DOMParser === 'undefined') {
+      return escapeHtml(dirtyHtml);
+    }
+    try {
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(dirtyHtml, 'text/html');
+      cleanNode(doc.body);
+      return doc.body.innerHTML;
+    } catch {
+      return escapeHtml(dirtyHtml);
+    }
+  }
+
+  const safeContent = $derived.by(() => {
+    if (!content) return '';
+    if (!parseHtml) return content;
+
+    try {
+      return sanitizer ? sanitizer(content) : defaultSanitize(content);
+    } catch (error) {
+      console.error('[fivem-nui-components] Failed to sanitize rich text:', error);
+      return escapeHtml(content);
+    }
+  });
+</script>
+
+<div
+  class="nui-rich-text {className}"
+  class:nui-rich-text--html={parseHtml}
+>
+  {#if parseHtml}
+    {@html safeContent}
+  {:else}
+    <pre class="nui-rich-text__pre">{content}</pre>
+  {/if}
+</div>
+
+<style>
+  .nui-rich-text {
+    font-family: inherit;
+    line-height: 1.6;
+    color: var(--nui-fg, #fafafa);
+  }
+
+  .nui-rich-text__pre {
+    background: var(--nui-surface-alt, #101012);
+    border: 1px solid var(--nui-border, #27272a);
+    border-radius: var(--nui-radius, 0.375rem);
+    padding: 1rem;
+    overflow-x: auto;
+    font-family: 'Consolas', 'Monaco', monospace;
+    font-size: 0.875rem;
+    margin: 0;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
+  .nui-rich-text :global(pre),
+  .nui-rich-text :global(code) {
+    font-family: 'Consolas', 'Monaco', monospace;
+    font-size: 0.875rem;
+  }
+
+  .nui-rich-text :global(p) {
+    margin: 0 0 1rem 0;
+  }
+
+  .nui-rich-text :global(ul),
+  .nui-rich-text :global(ol) {
+    margin: 0 0 1rem 0;
+    padding-left: 1.5rem;
+  }
+
+  .nui-rich-text :global(li) {
+    margin: 0 0 0.25rem 0;
+  }
+
+  .nui-rich-text :global(h1),
+  .nui-rich-text :global(h2),
+  .nui-rich-text :global(h3),
+  .nui-rich-text :global(h4),
+  .nui-rich-text :global(h5),
+  .nui-rich-text :global(h6) {
+    margin: 1rem 0 0.5rem 0;
+    font-weight: 600;
+  }
+
+  .nui-rich-text :global(h1) { font-size: 1.5rem; }
+  .nui-rich-text :global(h2) { font-size: 1.25rem; }
+  .nui-rich-text :global(h3) { font-size: 1.125rem; }
+  .nui-rich-text :global(h4) { font-size: 1rem; }
+</style>