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

package/src/components/data/NuiCodeBlock.svelte

@@ -0,0 +1,256 @@
+<!--
+  @component NuiCodeBlock
+  Code snippet block with optional title, language syntax classes, and clipboard copy button.
+-->
+<script module lang="ts">
+  export type NuiCodeLanguage =
+    | 'csharp'
+    | 'javascript'
+    | 'typescript'
+    | 'lua'
+    | 'sql'
+    | 'json'
+    | 'xml'
+    | 'bash'
+    | 'css'
+    | 'markdown'
+    | (string & {});
+</script>
+
+<script lang="ts">
+  import { onDestroy } from 'svelte';
+
+  interface Props {
+    /** Code snippet to display. */
+    code?: string;
+    /**
+     * Programming language for syntax highlighting classes.
+     * Integrates with external highlighters like highlight.js or Prism.
+     * @defaultValue 'csharp'
+     */
+    language?: NuiCodeLanguage;
+    /** Optional title or filename displayed in the header. */
+    title?: string;
+    /**
+     * Whether to show the copy-to-clipboard button.
+     * @defaultValue true
+     */
+    showCopyButton?: boolean;
+    /**
+     * Rounded container borders.
+     * @defaultValue true
+     */
+    rounded?: boolean;
+    /**
+     * Label for copy button in idle state.
+     * @defaultValue 'Copy'
+     */
+    copyLabel?: string;
+    /**
+     * Label for copy button in copied state.
+     * @defaultValue 'Copied!'
+     */
+    copiedLabel?: string;
+    /**
+     * Label for copy button in error state.
+     * @defaultValue 'Failed'
+     */
+    errorLabel?: string;
+    /** Callback executed on successful clipboard copy. */
+    onCopy?: (code: string) => void;
+    /** Callback executed when clipboard copy fails. */
+    onCopyError?: (error: unknown) => void;
+  }
+
+  let {
+    code = '',
+    language = 'csharp',
+    title,
+    showCopyButton = true,
+    rounded = true,
+    copyLabel = 'Copy',
+    copiedLabel = 'Copied!',
+    errorLabel = 'Failed',
+    onCopy,
+    onCopyError
+  }: Props = $props();
+
+  let copying = $state(false);
+  let copied = $state(false);
+  let copyFailed = $state(false);
+  let copyTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  onDestroy(() => {
+    if (copyTimeout !== undefined) {
+      clearTimeout(copyTimeout);
+      copyTimeout = undefined;
+    }
+  });
+
+  async function copyToClipboard() {
+    if (copying) return;
+
+    if (copyTimeout !== undefined) {
+      clearTimeout(copyTimeout);
+      copyTimeout = undefined;
+    }
+
+    copying = true;
+    copied = false;
+    copyFailed = false;
+
+    let writeSuccess = false;
+    let writeError: unknown;
+
+    try {
+      if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+        throw new Error('Clipboard API not available');
+      }
+      await navigator.clipboard.writeText(code);
+      writeSuccess = true;
+    } catch (e) {
+      writeError = e;
+      console.warn('[fivem-nui-components] Clipboard copy failed:', e);
+    }
+
+    copying = false;
+
+    if (writeSuccess) {
+      copied = true;
+      try {
+        onCopy?.(code);
+      } catch (cbErr) {
+        console.error('[fivem-nui-components] onCopy callback error:', cbErr);
+      }
+    } else {
+      copyFailed = true;
+      try {
+        onCopyError?.(writeError);
+      } catch (cbErr) {
+        console.error('[fivem-nui-components] onCopyError callback error:', cbErr);
+      }
+    }
+
+    copyTimeout = setTimeout(() => {
+      copied = false;
+      copyFailed = false;
+      copyTimeout = undefined;
+    }, 2000);
+  }
+</script>
+
+<div class="nui-code-block" class:nui-code-block--rounded={rounded}>
+  {#if title || showCopyButton}
+    <div class="nui-code-block__header">
+      {#if title}<span class="nui-code-block__title">{title}</span>{/if}
+      {#if showCopyButton}
+        <button
+          type="button"
+          class="nui-code-block__copy"
+          class:nui-code-block__copy--copied={copied}
+          class:nui-code-block__copy--error={copyFailed}
+          disabled={copying}
+          onclick={copyToClipboard}
+          aria-label={copied ? copiedLabel : copyFailed ? errorLabel : copyLabel}
+        >
+          <span aria-live="polite" aria-atomic="true">
+            {copied ? copiedLabel : copyFailed ? errorLabel : copyLabel}
+          </span>
+        </button>
+      {/if}
+    </div>
+  {/if}
+
+  <pre class="nui-code-block__pre"><code class="language-{language}">{code}</code></pre>
+</div>
+
+<style>
+  .nui-code-block {
+    width: 100%;
+    font-family: 'Consolas', 'Monaco', monospace;
+  }
+
+  .nui-code-block__header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 0.5rem 1rem;
+    background: var(--nui-surface-alt, #101012);
+    border: 1px solid var(--nui-border, #27272a);
+    border-bottom: none;
+  }
+
+  .nui-code-block__title {
+    font-size: 0.8125rem;
+    color: var(--nui-fg-secondary, #8b8b99);
+    font-weight: 500;
+  }
+
+  .nui-code-block__copy {
+    background: transparent;
+    border: 1px solid var(--nui-border, #3f3f46);
+    border-radius: var(--nui-radius, 0.25rem);
+    padding: 0.25rem 0.5rem;
+    font-size: 0.75rem;
+    color: var(--nui-fg, #fafafa);
+    cursor: pointer;
+    transition: background 0.15s ease, border-color 0.15s ease, color 0.15s ease;
+  }
+
+  .nui-code-block__copy:hover:not(:disabled) {
+    background: var(--nui-hover, rgb(255 255 255 / 0.06));
+  }
+
+  .nui-code-block__copy:disabled {
+    opacity: 0.6;
+    cursor: default;
+  }
+
+  .nui-code-block__copy:focus-visible {
+    outline: 2px solid var(--nui-primary, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  .nui-code-block__copy--copied {
+    border-color: var(--nui-success, #22c55e);
+    color: var(--nui-success, #22c55e);
+  }
+
+  .nui-code-block__copy--error {
+    border-color: var(--nui-danger, #ef4444);
+    color: var(--nui-danger, #ef4444);
+  }
+
+  .nui-code-block__pre {
+    margin: 0;
+    padding: 1rem;
+    background: var(--nui-surface, #18181b);
+    border: 1px solid var(--nui-border, #27272a);
+    overflow-x: auto;
+    color: var(--nui-fg, #fafafa);
+  }
+
+  .nui-code-block--rounded .nui-code-block__header {
+    border-radius: var(--nui-radius, 0.5rem) var(--nui-radius, 0.5rem) 0 0;
+  }
+
+  .nui-code-block--rounded .nui-code-block__pre {
+    border-radius: var(--nui-radius, 0.5rem);
+  }
+
+  .nui-code-block--rounded .nui-code-block__header + .nui-code-block__pre {
+    border-radius: 0 0 var(--nui-radius, 0.5rem) var(--nui-radius, 0.5rem);
+  }
+
+  .nui-code-block__pre code {
+    font-size: 0.8125rem;
+    line-height: 1.5;
+  }
+
+  /* Scoped syntax highlighting tokens (when external highlighter is applied) */
+  .nui-code-block__pre :global(.string) { color: #facc15; }
+  .nui-code-block__pre :global(.keyword) { color: #60a5fa; font-weight: 600; }
+  .nui-code-block__pre :global(.function) { color: #a7f3d0; }
+  .nui-code-block__pre :global(.comment) { color: #6b7280; opacity: 0.8; font-style: italic; }
+  .nui-code-block__pre :global(.number) { color: #f472b6; }
+</style>

package/src/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>