# Vue Component API

This is the compact API reference for the official Vue adapter. Import components from `gnexus-ui-kit/vue`.

## Foundations

### `GnButton`

Props: `variant`, `size`, `icon`, `loading`, `disabled`, `type`.

Slots: default.

```vue
<GnButton variant="secondary" icon="ph-plus" :loading="saving">Create</GnButton>
```

### `GnIconButton`

Props: `icon`, `label`, `type`, `size` (`'sm'`), `withoutHover`.

```vue
<GnIconButton icon="ph-x" label="Close" />
```

### `GnCopyButton`

Copies text to clipboard. Swaps icon to `successIcon` for `duration` ms after click.

Props: `text` (required), `icon`, `successIcon`, `duration`, `label`, `size` (`'sm'`).

```vue
<GnCopyButton text="ssh-key-value" />
```

### `GnBadge`, `GnAlert`

Props: `variant`; `GnBadge` also supports `outline`.

```vue
<GnBadge variant="success">Online</GnBadge>
<GnAlert variant="warning">Check this before release.</GnAlert>
```

## Forms

### `GnInput`, `GnTextarea`, `GnSelect`

Props: `modelValue`, `label`, `icon`, `state`, `help`.

Emits: `update:modelValue`.

```vue
<GnInput v-model="name" label="Project name" icon="ph-pencil-simple" />
<GnTextarea v-model="notes" label="Notes" state="warning" help="Review before publishing" />
<GnSelect v-model="status" label="Status" :options="statusOptions" />
```

### `GnCheckbox`, `GnSwitch`

Props: `modelValue`, `label`, `disabled`.

Emits: `update:modelValue`.

```vue
<GnSwitch v-model="enabled">Enabled</GnSwitch>
```

### `GnRadio`, `GnRadioGroup`

Props: `modelValue`, `value`, `label`, `name`, `disabled`; group accepts `options`.

Emits: `update:modelValue`.

```vue
<GnRadioGroup v-model="mode" label="Mode" :options="modes" />
```

### `GnRange`

Props: `modelValue`, `label`, `min`, `max`, `step`.

Emits: `update:modelValue`.

```vue
<GnRange v-model="rollout" label="Rollout" />
```

### `GnCombobox`

Props: `modelValue`, `label`, `icon`, `options`, `placeholder`, `notFoundText`, `state`, `help`.

Emits: `update:modelValue`, `select`.

```vue
<GnCombobox v-model="assignee" label="Assignee" icon="ph-user" :options="people" />
```

### `GnFileUpload`

Props: `modelValue`, `title`, `description`, `primary`, `secondary`, `badge`, `multiple`, `accept`.

Emits: `update:modelValue`, `change`.

```vue
<GnFileUpload v-model="files" badge="Max 12 MB" />
```

## Navigation And Overlays

### `GnTabs`

Props: `modelValue`, `items`, `compact`, `vertical`, `ariaLabel`.

Emits: `update:modelValue`.

Slots: one slot per item id.

```vue
<GnTabs v-model="tab" :items="tabs">
  <template #overview>Overview</template>
</GnTabs>
```

### `GnRouterTabs`

Router-aware tabs. Wraps `GnTabs` and drives active state from the current vue-router route.

Props: `items` (with `to`, `id`, `label`, `icon`, `disabled`), `compact`, `vertical`, `ariaLabel`, `activeMatch` (`'exact'` | `'prefix'`).

```vue
<script setup>
const tabs = [
  { id: "overview", label: "Overview", to: "/projects/overview" },
  { id: "activity", label: "Activity", to: "/projects/activity" }
];
</script>

<template>
  <GnRouterTabs :items="tabs">
    <template #overview>Overview content</template>
    <template #activity>Activity content</template>
  </GnRouterTabs>
</template>
```

`activeMatch` defaults to `'prefix'` (highlights tab when current path starts with `to`). Use `'exact'` for strict path equality.

### `GnAccordion`

Props: `items`, `modelValue`, `multiple`.

Emits: `update:modelValue`.

Slots: one slot per item id.

### `GnDropdown`, `GnPopover`, `GnTooltip`

`GnDropdown` props: `label`, `icon`, `variant`, `items`.

`GnPopover` props: `label`, `title`, `text`, `icon`, `variant`.

`GnTooltip` props: `text`.

```vue
<GnDropdown :items="menuItems" @select="handleMenu" />
<GnPopover title="Context" text="Short contextual copy" />
<GnTooltip text="Short hint"><GnButton>Help</GnButton></GnTooltip>
```

### `GnNavigationShell`, `GnNavList`

`GnNavigationShell` props: `brand`, `logoSrc`, `current`, `title`, `subtitle`, `footerLeft`, `footerRight`, `items`.

`GnNavList` props: `items`.

Emits: `select`.

## Feedback

### `GnModal`, `GnDrawer`

Props: `open`, `title`; modal also has `closeOnBackdrop`; drawer has `position`.

Emits: `update:open`, `close`.

```vue
<GnModal v-model:open="open" title="Edit">
  Content
</GnModal>
```

### `GnToastProvider`, `useToast`

Wrap the app once and call `useToast()` in descendants. The provider shows one toast at a time.

```js
toast.success({ title: "Saved", text: "Changes applied" });
```

### `GnConfirmDialog`

Props: `open`, `title`, `message`, `confirmText`, `cancelText`, `confirmVariant`.

Emits: `update:open`, `confirm`, `cancel`.

## Data And Layout

### `GnTable`

Props: `columns`, `rows`, `caption`, `emptyText`.

Slots: `cell-${column.key}`, `empty`.

### `GnToolbar`, `GnSearchField`, `GnPagination`

Use for table/list screens.

```vue
<GnToolbar title="Projects" meta="24 records">
  <template #actions><GnSearchField v-model="query" /></template>
</GnToolbar>
<GnPagination :page="page" :total-pages="12" @update:page="page = $event" />
```

### `GnDescriptionList`, `GnProgress`, `GnUsageMeter`, `GnProgressStages`, `GnSteps`

Use for metadata, rollout state, and staged flows.

### `GnChip`, `GnChipGroup`

Props: `variant`, `icon`, `selected`, `disabled`, `removable`.

Emits: `remove`.

### `GnAvatar`, `GnIdentity`, `GnAvatarStack`

Use for people/entity identity rows.

### `GnTimeline`, `GnActivityLog`

Use for event history and compact audit rows.

### `GnCard`, `GnHorizontalCard`, `GnStatusCard`, `GnMetricCard`, `GnActionCard`

Use specialized cards before writing raw `.card` markup.

`GnHorizontalCard` props: `image`, `title`, `titleHref`, `icon`.
Slots: `default` (content), `footer`.

```vue
<GnHorizontalCard
  image="/assets/imgs/cover.png"
  title="Project Alpha"
  title-href="/projects/alpha"
  icon="ph-arrow-right"
>
  <p>Short description.</p>
  <template #footer>
    <span>Updated 2h ago</span>
    <GnBadge variant="success">Active</GnBadge>
  </template>
</GnHorizontalCard>
```

### `GnLoginCard`

Login form card. Props: `title`, `logoSrc`, `logoIcon`, `usernameLabel`, `usernameIcon`, `passwordLabel`, `passwordIcon`, `rememberMe`, `rememberLabel`, `submitText`, `submitVariant`, `loading`, `error`, `forgotHref`, `forgotText`, `signupHref`, `signupText`.

Emits: `submit({ username, password, remember })`.

```vue
<GnLoginCard
  title="Sign in"
  remember-me
  forgot-href="/forgot"
  signup-href="/signup"
  @submit="handleLogin"
/>
```

### `GnList`, `GnDefinitionList`, `GnActionList`

Use list wrappers before raw `.list` markup when data is available as arrays.

### `GnEmptyState`, `GnSkeleton`, `GnLoader`

Use for loading and empty states.
