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

package/dist/components/forms/NuiSelect.svelte.d.ts

@@ -0,0 +1,49 @@
+export interface NuiSelectOption {
+    /** Unique value identifying this option. */
+    value: string;
+    /** Human-readable text label. */
+    label: string;
+    /** Whether this individual option is disabled. */
+    disabled?: boolean;
+}
+import type { SvelteNuiClient } from "@fivem-nui/svelte";
+interface Props {
+    /** NUI event name emitted when selection changes or is cleared. */
+    eventName?: string;
+    /** SvelteNuiClient instance used to dispatch NUI events. */
+    client?: SvelteNuiClient;
+    /**
+     * Current selection value (two-way bindable):
+     * - In single-select mode (`multiple={false}`): a plain string containing the selected option's `value` (e.g. `'item_1'`), or `''` if empty.
+     * - In multi-select mode (`multiple={true}`): a serialized JSON array string of selected option values (e.g. `'["item_1", "item_2"]'`), or `'[]'` / `''` if empty.
+     *
+     * Note: In multi-select mode, the underlying `<input type="hidden" {name} {value} />` submits this JSON string.
+     * When emitting the NUI event (`eventName`), a parsed array (`value: string[]`) is provided in the event payload.
+     */
+    value?: string;
+    /** Text label displayed above the select control. */
+    label?: string;
+    /** Placeholder text shown when no option is selected. Defaults to 'Select...'. */
+    placeholder?: string;
+    /** Available select options. Each option's `value` must be unique. */
+    options?: NuiSelectOption[];
+    /** Whether the select control is disabled. */
+    disabled?: boolean;
+    /**
+     * Whether multiple options can be selected simultaneously.
+     * When enabled, `value` binds to a serialized JSON array of selected strings (e.g. `'["opt1","opt2"]'`).
+     */
+    multiple?: boolean;
+    /** Whether the search input is enabled in the dropdown panel. Defaults to true. */
+    searchable?: boolean;
+    /** Maximum CSS height for the dropdown panel (e.g. '200px', '15rem'). Defaults to '200px'. */
+    maxHeight?: string;
+    /**
+     * Form input name attribute rendered on an underlying `<input type="hidden" {name} {value} />`.
+     * In single mode, submits the selected string value. In multi-select mode, submits the JSON array string.
+     */
+    name?: string;
+}
+declare const NuiSelect: import("svelte").Component<Props, {}, "value">;
+type NuiSelect = ReturnType<typeof NuiSelect>;
+export default NuiSelect;

package/dist/components/layout/NuiCard.svelte

@@ -0,0 +1,314 @@
+<script lang="ts" module>
+  let warnedNoAccessibleName = false;
+</script>
+
+<script lang="ts">
+  import { DEV } from 'esm-env';
+  import type { Snippet } from 'svelte';
+  import type { HTMLAttributes } from 'svelte/elements';
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> {
+    /** Card header title */
+    title?: string;
+    /** Optional icon displayed before the title */
+    icon?: string;
+    /** Card elevation level (1 to 5) */
+    elevation?: 1 | 2 | 3 | 4 | 5 | '1' | '2' | '3' | '4' | '5';
+    /**
+     * Whether the card can be toggled/selected.
+     * When true and not `controlled`, clicking toggles `selected` (supports `bind:selected`).
+     * For single-select card groups (radio behavior), set `controlled={true}` and update `selected` via `onSelect`.
+     */
+    selectable?: boolean;
+    /**
+     * Whether the card is currently selected.
+     * Supports two-way binding via `bind:selected` when `controlled` is false.
+     */
+    selected?: boolean;
+    /**
+     * When true, the parent owns the `selected` state; the card will not mutate `selected` locally upon click.
+     * Do not use `bind:selected` together with `controlled={true}`.
+     * @default false
+     */
+    controlled?: boolean;
+    /** Whether the card behaves as a clickable button */
+    clickable?: boolean;
+    /**
+     * Whether the card is disabled.
+     * When true, disables the interactive card overlay (if interactive) and marks `actions` and `children` as `inert`.
+     * Note: `inert` is applied to `actions` and `children` even on non-interactive cards to suppress descendant interactivity.
+     */
+    disabled?: boolean;
+    /** Accessible name for the interactive card when there is no title */
+    label?: string;
+    /** Heading level for the card title (defaults to 3 -> <h3>) */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | (number & {});
+    /** Callback fired when the card is clicked or activated via keyboard. For `selectable` cards, also receives the intended next selection state. */
+    onSelect?: (event: MouseEvent | KeyboardEvent, nextSelected?: boolean) => void;
+    /** Card body content snippet */
+    children?: Snippet;
+    /** Header action buttons or badges snippet */
+    actions?: Snippet;
+  }
+
+  const uid = $props.id();
+  const titleId = `nui-card-${uid}-title`;
+
+  let {
+    title = '',
+    icon = '',
+    elevation = 1,
+    selectable = false,
+    selected = $bindable(false),
+    controlled = false,
+    clickable = false,
+    disabled = false,
+    label,
+    headingLevel = 3,
+    onSelect,
+    children,
+    actions,
+    class: className = '',
+    role: roleProp,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    ...rest
+  }: Props = $props();
+
+  const interactive = $derived(selectable || clickable || Boolean(onSelect));
+  const computedAriaLabelledby = $derived(title ? titleId : ariaLabelledby);
+  const computedAriaLabel = $derived(
+    computedAriaLabelledby ? undefined : (label ?? ariaLabel)
+  );
+
+  const safeHeadingTag = $derived.by(() => {
+    const level = Number(headingLevel);
+    if (Number.isInteger(level) && level >= 1 && level <= 6) {
+      return `h${level}`;
+    }
+    return 'h3';
+  });
+
+  // Warn once in development mode if an interactive card lacks an accessible name
+  $effect(() => {
+    if (!DEV || warnedNoAccessibleName) return;
+    if (interactive && !computedAriaLabel && !computedAriaLabelledby) {
+      warnedNoAccessibleName = true;
+      console.warn(
+        '[fivem-nui-components] NuiCard: Interactive card must have an accessible name. Provide a `title`, `label`, or `aria-label`.'
+      );
+    }
+  });
+
+  function handleClick(event: MouseEvent | KeyboardEvent) {
+    if (disabled) return;
+    if (selectable) {
+      const next = !selected;
+      if (!controlled) {
+        selected = next;
+      }
+      onSelect?.(event, next);
+    } else {
+      onSelect?.(event);
+    }
+  }
+
+  function handleKeyDown(event: KeyboardEvent) {
+    if (disabled) return;
+    if (event.key === 'Enter' || event.key === ' ') {
+      event.preventDefault();
+      handleClick(event);
+    }
+  }
+</script>
+
+<div
+  {...rest}
+  role={roleProp ?? (!interactive && (ariaLabel || ariaLabelledby) ? 'group' : undefined)}
+  aria-label={!interactive ? ariaLabel : undefined}
+  aria-labelledby={!interactive ? ariaLabelledby : undefined}
+  class={['nui-card', `nui-card--elevation-${elevation}`, className]}
+  class:nui-card--interactive={interactive}
+  class:nui-card--selected={selectable && selected}
+  class:nui-card--disabled={disabled}
+>
+  {#if interactive}
+    <button
+      type="button"
+      class="nui-card-hit"
+      {disabled}
+      aria-pressed={selectable ? selected : undefined}
+      aria-labelledby={computedAriaLabelledby}
+      aria-label={computedAriaLabel}
+      onclick={handleClick}
+      onkeydown={handleKeyDown}
+    ></button>
+  {/if}
+
+  {#if title || icon || actions}
+    <div class="nui-card-header">
+      {#if icon}<span class="nui-card-icon" aria-hidden="true">{icon}</span>{/if}
+      {#if title}
+        <svelte:element this={safeHeadingTag} id={titleId} class="nui-card-title">
+          {title}
+        </svelte:element>
+      {/if}
+      {#if actions}
+        <div class="nui-card-actions" inert={disabled || undefined}>{@render actions()}</div>
+      {/if}
+    </div>
+  {/if}
+
+  {#if children}
+    <div class="nui-card-body" inert={disabled || undefined}>{@render children()}</div>
+  {/if}
+</div>
+
+<style>
+  .nui-card {
+    position: relative;
+    background: var(--nui-surface, #18181b);
+    color: var(--nui-fg, #fafafa);
+    border: 1px solid var(--nui-border, #27272a);
+    border-radius: var(--nui-radius, 0.5rem);
+    padding: 1rem;
+    box-sizing: border-box;
+    font-family: inherit;
+    box-shadow: var(--nui-card-shadow);
+    transition: transform 0.15s ease, border-color 0.15s ease,
+      opacity 0.15s ease, box-shadow 0.15s ease;
+  }
+
+  .nui-card--elevation-1 { --nui-card-shadow: 0 1px 3px rgb(0 0 0 / 0.12); }
+  .nui-card--elevation-2 { --nui-card-shadow: 0 3px 6px rgb(0 0 0 / 0.16); }
+  .nui-card--elevation-3 { --nui-card-shadow: 0 10px 20px rgb(0 0 0 / 0.19); }
+  .nui-card--elevation-4 { --nui-card-shadow: 0 20px 40px rgb(0 0 0 / 0.23); }
+  .nui-card--elevation-5 { --nui-card-shadow: 0 30px 60px rgb(0 0 0 / 0.3); }
+
+  .nui-card--interactive:not(.nui-card--disabled):hover {
+    transform: translateY(-2px);
+    border-color: var(--nui-primary, #3b82f6);
+    z-index: 2;
+  }
+
+  .nui-card:focus-within {
+    z-index: 2;
+  }
+
+  .nui-card--interactive:not(.nui-card--disabled):active {
+    transform: none;
+  }
+
+  .nui-card--selected {
+    border-color: var(--nui-primary, #3b82f6);
+    box-shadow: inset 0 0 0 1px var(--nui-primary, #3b82f6), var(--nui-card-shadow);
+  }
+
+  .nui-card--disabled {
+    opacity: 0.5;
+  }
+
+  /* Fallback for environments lacking native inert support */
+  .nui-card--disabled .nui-card-actions,
+  .nui-card--disabled .nui-card-body {
+    pointer-events: none;
+  }
+
+  .nui-card-hit {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    border-radius: inherit;
+    background: transparent;
+    appearance: none;
+    cursor: pointer;
+  }
+
+  /* Overlay expands -2px only during hover to eliminate jitter without overlapping adjacent cards at rest */
+  .nui-card--interactive:not(.nui-card--disabled):hover .nui-card-hit {
+    bottom: -2px;
+  }
+
+  .nui-card-hit:disabled {
+    cursor: not-allowed;
+  }
+
+  .nui-card-hit:focus-visible {
+    outline: 2px solid var(--nui-primary, #3b82f6);
+    outline-offset: 2px;
+  }
+
+  .nui-card-header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.75rem;
+  }
+
+  .nui-card-header:last-child {
+    margin-bottom: 0;
+  }
+
+  .nui-card-icon {
+    font-size: 1.25rem;
+    line-height: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .nui-card-title {
+    margin: 0;
+    font-size: 1rem;
+    font-weight: 600;
+    flex: 1;
+    color: inherit;
+  }
+
+  /* Above overlay so actions, interactive content, and user-marked elements receive direct pointer/keyboard focus */
+  .nui-card-actions {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    gap: 0.375rem;
+  }
+
+  .nui-card-body {
+    font-size: 0.875rem;
+    color: inherit;
+  }
+
+  .nui-card-body :global(:is(
+    a,
+    button,
+    input,
+    select,
+    textarea,
+    label,
+    summary,
+    [tabindex],
+    [role="button"],
+    [role="checkbox"],
+    [role="radio"],
+    [role="switch"],
+    [role="link"],
+    [role="textbox"],
+    [contenteditable],
+    .nui-card-interactive
+  )) {
+    position: relative;
+    z-index: 1;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .nui-card {
+      transition: none;
+    }
+    .nui-card--interactive:hover {
+      transform: none;
+    }
+  }
+</style>

package/dist/components/layout/NuiCard.svelte.d.ts

@@ -0,0 +1,48 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> {
+    /** Card header title */
+    title?: string;
+    /** Optional icon displayed before the title */
+    icon?: string;
+    /** Card elevation level (1 to 5) */
+    elevation?: 1 | 2 | 3 | 4 | 5 | '1' | '2' | '3' | '4' | '5';
+    /**
+     * Whether the card can be toggled/selected.
+     * When true and not `controlled`, clicking toggles `selected` (supports `bind:selected`).
+     * For single-select card groups (radio behavior), set `controlled={true}` and update `selected` via `onSelect`.
+     */
+    selectable?: boolean;
+    /**
+     * Whether the card is currently selected.
+     * Supports two-way binding via `bind:selected` when `controlled` is false.
+     */
+    selected?: boolean;
+    /**
+     * When true, the parent owns the `selected` state; the card will not mutate `selected` locally upon click.
+     * Do not use `bind:selected` together with `controlled={true}`.
+     * @default false
+     */
+    controlled?: boolean;
+    /** Whether the card behaves as a clickable button */
+    clickable?: boolean;
+    /**
+     * Whether the card is disabled.
+     * When true, disables the interactive card overlay (if interactive) and marks `actions` and `children` as `inert`.
+     * Note: `inert` is applied to `actions` and `children` even on non-interactive cards to suppress descendant interactivity.
+     */
+    disabled?: boolean;
+    /** Accessible name for the interactive card when there is no title */
+    label?: string;
+    /** Heading level for the card title (defaults to 3 -> <h3>) */
+    headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | (number & {});
+    /** Callback fired when the card is clicked or activated via keyboard. For `selectable` cards, also receives the intended next selection state. */
+    onSelect?: (event: MouseEvent | KeyboardEvent, nextSelected?: boolean) => void;
+    /** Card body content snippet */
+    children?: Snippet;
+    /** Header action buttons or badges snippet */
+    actions?: Snippet;
+}
+declare const NuiCard: import("svelte").Component<Props, {}, "selected">;
+type NuiCard = ReturnType<typeof NuiCard>;
+export default NuiCard;

package/dist/components/layout/NuiCardGrid.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+
+  interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Max number of columns (responsive) or exact count (fixed) */
+    columns?: number | `${number}` | (string & {});
+    /**
+     * Gap between cards. Numbers are treated as px (e.g. 16 -> '16px').
+     * Fixed units (rem, px) are recommended; percentage units in responsive mode may produce
+     * variable track minimums because container-relative calc() evaluation depends on outer context.
+     */
+    gap?: string | number;
+    /** Auto fit columns by `minCardWidth`, capped by `columns` */
+    responsive?: boolean;
+    /** Minimum card width. Numbers are treated as px */
+    minCardWidth?: string | number;
+    /** Center cards within their cells */
+    center?: boolean;
+    children?: Snippet;
+  }
+
+  let {
+    columns = 3,
+    gap = "1rem",
+    responsive = true,
+    minCardWidth = "250px",
+    center = false,
+    children,
+    class: className = "",
+    style,
+    ...rest
+  }: Props = $props();
+
+  const toCss = (v: string | number | undefined | null, fallback: string) => {
+    if (typeof v === "number") return `${v}px`;
+    if (typeof v === "string" && v.trim().length > 0) return v.trim();
+    return fallback;
+  };
+
+  const cols = $derived.by(() => {
+    if (columns == null) return 3;
+    const num = Number(columns);
+    if (!Number.isFinite(num)) return 1;
+    return Math.max(1, Math.floor(num));
+  });
+
+  const styleVars = $derived(
+    `--nui-card-columns:${cols};--nui-card-gap:${toCss(gap, "1rem")};--nui-card-min-width:${toCss(minCardWidth, "250px")};`,
+  );
+  /**
+   * Concatenate extra inline style. Svelte 5 passes style strings here; non-string values are safely ignored.
+   */
+  const styleExtra = $derived(typeof style === "string" ? style : "");
+</script>
+
+<div
+  {...rest}
+  class={[
+    "nui-card-grid",
+    responsive ? "nui-card-grid--responsive" : "nui-card-grid--fixed",
+    center && "nui-card-grid--center",
+    className,
+  ]}
+  style={styleVars + styleExtra}
+>
+  {@render children?.()}
+</div>
+
+<style>
+  .nui-card-grid {
+    display: grid;
+    gap: var(--nui-card-gap, 1rem);
+    width: 100%;
+    font-family: inherit;
+    box-sizing: border-box;
+  }
+
+  .nui-card-grid--responsive {
+    --_gap-total: calc((var(--nui-card-columns) - 1) * var(--nui-card-gap));
+    --_min: min(
+      100%,
+      max(
+        var(--nui-card-min-width),
+        calc((100% - var(--_gap-total)) / var(--nui-card-columns))
+      )
+    );
+    grid-template-columns: repeat(auto-fit, minmax(var(--_min), 1fr));
+  }
+
+  .nui-card-grid--fixed {
+    grid-template-columns: repeat(var(--nui-card-columns), minmax(0, 1fr));
+  }
+
+  .nui-card-grid--center {
+    justify-items: center;
+  }
+</style>

package/dist/components/layout/NuiCardGrid.svelte.d.ts

@@ -0,0 +1,22 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Max number of columns (responsive) or exact count (fixed) */
+    columns?: number | `${number}` | (string & {});
+    /**
+     * Gap between cards. Numbers are treated as px (e.g. 16 -> '16px').
+     * Fixed units (rem, px) are recommended; percentage units in responsive mode may produce
+     * variable track minimums because container-relative calc() evaluation depends on outer context.
+     */
+    gap?: string | number;
+    /** Auto fit columns by `minCardWidth`, capped by `columns` */
+    responsive?: boolean;
+    /** Minimum card width. Numbers are treated as px */
+    minCardWidth?: string | number;
+    /** Center cards within their cells */
+    center?: boolean;
+    children?: Snippet;
+}
+declare const NuiCardGrid: import("svelte").Component<Props, {}, "">;
+type NuiCardGrid = ReturnType<typeof NuiCardGrid>;
+export default NuiCardGrid;

package/dist/components/layout/NuiFlex.svelte

@@ -0,0 +1,121 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+
+  type Direction = "row" | "column" | "row-reverse" | "column-reverse";
+  type Justify = "start" | "center" | "end" | "between" | "around" | "evenly";
+  type Align = "start" | "center" | "end" | "stretch" | "baseline";
+
+  interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Main axis direction. Note: `*-reverse` changes visual order only, not DOM/tab order */
+    direction?: Direction;
+    /** Alignment along the main axis */
+    justify?: Justify;
+    /** Alignment along the cross axis */
+    align?: Align;
+    /** Allow items to wrap onto multiple lines */
+    wrap?: boolean;
+    /** Gap between items. Numbers are treated as px */
+    gap?: string | number;
+    /** Render as inline-flex */
+    inline?: boolean;
+    children?: Snippet;
+  }
+
+  let {
+    direction = "row",
+    justify = "start",
+    align = "stretch",
+    wrap = false,
+    gap = "1rem",
+    inline = false,
+    children,
+    class: className = "",
+    style,
+    ...rest
+  }: Props = $props();
+
+  const toCss = (v: string | number) => (typeof v === "number" ? `${v}px` : v);
+  const styleVars = $derived(`--nui-flex-gap:${toCss(gap)};`);
+  const styleExtra = $derived(typeof style === "string" ? style : "");
+</script>
+
+<div
+  {...rest}
+  class={[
+    "nui-flex",
+    `nui-flex--${direction}`,
+    `nui-flex--justify-${justify}`,
+    `nui-flex--align-${align}`,
+    wrap && "nui-flex--wrap",
+    inline && "nui-flex--inline",
+    className,
+  ]}
+  style={styleVars + styleExtra}
+>
+  {@render children?.()}
+</div>
+
+<style>
+  .nui-flex {
+    display: flex;
+    gap: var(--nui-flex-gap, 1rem);
+    font-family: inherit;
+    box-sizing: border-box;
+  }
+
+  .nui-flex--inline {
+    display: inline-flex;
+  }
+  .nui-flex--wrap {
+    flex-wrap: wrap;
+  }
+
+  .nui-flex--row {
+    flex-direction: row;
+  }
+  .nui-flex--column {
+    flex-direction: column;
+  }
+  .nui-flex--row-reverse {
+    flex-direction: row-reverse;
+  }
+  .nui-flex--column-reverse {
+    flex-direction: column-reverse;
+  }
+
+  .nui-flex--justify-start {
+    justify-content: flex-start;
+  }
+  .nui-flex--justify-center {
+    justify-content: center;
+  }
+  .nui-flex--justify-end {
+    justify-content: flex-end;
+  }
+  .nui-flex--justify-between {
+    justify-content: space-between;
+  }
+  .nui-flex--justify-around {
+    justify-content: space-around;
+  }
+  .nui-flex--justify-evenly {
+    justify-content: space-evenly;
+  }
+
+  .nui-flex--align-start {
+    align-items: flex-start;
+  }
+  .nui-flex--align-center {
+    align-items: center;
+  }
+  .nui-flex--align-end {
+    align-items: flex-end;
+  }
+  .nui-flex--align-stretch {
+    align-items: stretch;
+  }
+  .nui-flex--align-baseline {
+    align-items: baseline;
+  }
+</style>

package/dist/components/layout/NuiFlex.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+type Direction = "row" | "column" | "row-reverse" | "column-reverse";
+type Justify = "start" | "center" | "end" | "between" | "around" | "evenly";
+type Align = "start" | "center" | "end" | "stretch" | "baseline";
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /** Main axis direction. Note: `*-reverse` changes visual order only, not DOM/tab order */
+    direction?: Direction;
+    /** Alignment along the main axis */
+    justify?: Justify;
+    /** Alignment along the cross axis */
+    align?: Align;
+    /** Allow items to wrap onto multiple lines */
+    wrap?: boolean;
+    /** Gap between items. Numbers are treated as px */
+    gap?: string | number;
+    /** Render as inline-flex */
+    inline?: boolean;
+    children?: Snippet;
+}
+declare const NuiFlex: import("svelte").Component<Props, {}, "">;
+type NuiFlex = ReturnType<typeof NuiFlex>;
+export default NuiFlex;