# Vue AI Usage Guide

This document is for AI agents working inside Vue projects that consume GNexus UI Kit.

## Rule

The Vue adapter is the primary contract for Vue projects. Always use `gnexus-ui-kit/vue` components instead of writing raw kit markup by hand.

Do not recreate modal, drawer, tab, toast, form, button, or table markup manually unless the adapter does not expose the needed component yet. Raw classes are acceptable only for layout wrappers and content that has no Vue adapter component.

## Required Imports

At app root:

```js
import "gnexus-ui-kit/dist/css/kit.css";
import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css";
```

Use named imports:

```js
import { GnButton, GnInput, GnModal } from "gnexus-ui-kit/vue";
```

Or global registration:

```js
import { GnexusUiVue } from "gnexus-ui-kit/vue";
app.use(GnexusUiVue);
```

## Component Selection

Use these mappings:

- button command: `GnButton`
- icon-only command: `GnIconButton`
- status label: `GnBadge`
- message block: `GnAlert`
- framed content: `GnCard`
- horizontal content card: `GnHorizontalCard`
- page title/actions: `GnPageHeader`
- text field: `GnInput`
- multiline field: `GnTextarea`
- select field: `GnSelect`
- boolean control: `GnCheckbox` or `GnSwitch`
- radio choice: `GnRadio` or `GnRadioGroup`
- range slider: `GnRange`
- file upload: `GnFileUpload`
- searchable option input: `GnCombobox`
- view switcher: `GnTabs`
- router-driven tabs: `GnRouterTabs`
- disclosure group: `GnAccordion`
- dialog: `GnModal`
- side panel: `GnDrawer`
- global notification: `GnToastProvider` + `useToast`
- confirmation: `GnConfirmDialog`
- structured rows: `GnTable`
- toolbar/action row: `GnToolbar`
- input addon layout: `GnInputGroup`
- search input: `GnSearchField`
- pagination: `GnPagination`
- empty result panel: `GnEmptyState`
- loading placeholders: `GnSkeleton`
- key-value metadata: `GnDescriptionList`
- determinate progress: `GnProgress`
- usage/limit card: `GnUsageMeter`
- staged progress strip: `GnProgressStages`
- wizard/staged process: `GnSteps`
- chips/filters: `GnChip`, `GnChipGroup`
- user or entity identity: `GnAvatar`, `GnIdentity`, `GnAvatarStack`
- activity timeline/log: `GnTimeline`, `GnActivityLog`
- basic/definition/action lists: `GnList`, `GnDefinitionList`, `GnActionList`
- loaders: `GnLoader`
- specialized cards: `GnStatusCard`, `GnMetricCard`, `GnActionCard`
- dropdown menu: `GnDropdown`
- contextual panel: `GnPopover`
- compact hint: `GnTooltip`
- navigation list: `GnNavList`
- application shell navigation: `GnNavigationShell`

## Do Not

- Do not copy raw modal markup from demo partials into Vue apps.
- Do not call `GNexusUIKit.Modals.create()` from Vue components.
- Do not call `GNexusUIKit.Overlays.init()` or `GNexusUIKit.NavigationShell.init()` in Vue projects.
- Do not run `Accordion.init()` or `Tabs.init()` inside Vue components.
- Do not use the legacy `advancedSelect()` helper in Vue; use `GnCombobox`.
- Do not use `InputPatterns.init()` for Vue file upload previews; use `GnFileUpload`.
- Do not invent new variant names.
- Do not duplicate GNexus CSS in Vue component scoped styles.
- Do not bundle Vue into the UI-kit adapter.
- Do not pass icon names without the `ph-` prefix (e.g. `icon="house"` is wrong; use `icon="ph-house"`).
- Do not use non-Phosphor icon classes in any `icon` prop.

## Acceptable Raw Markup

Raw classes are acceptable for layout-only wrappers and content that has no Vue adapter yet:

```html
<div class="form-grid">...</div>
<div class="demo-actions">...</div>
```

For interactive components, add or extend the adapter first.

## Update Policy

When the base kit changes markup for a component, update the Vue adapter in this repository. Downstream projects should receive compatibility through dependency updates, not local rewrites.

## Smoke Checks

Before claiming Vue adapter compatibility, run:

```bash
npm run build
npm run test:vue-adapter
```

Warnings about `/assets/fonts/...` in Vite builds are expected with the current CSS contract. They mean the host app must serve GNexus UI Kit assets at `/assets`.

The local example clears `examples/vue/node_modules/.vite` before build because `gnexus-ui-kit` is linked from the repository root and Vite can otherwise reuse stale optimized metadata after `dist/vue` changes.

## Behavior Contracts

- `GnModal` and `GnDrawer` handle Escape, focus return, and Tab focus trapping.
- `GnToastProvider` is single-toast by design: a new toast replaces the current one.
- `GnCombobox` owns combobox/listbox ARIA and keyboard movement.
- `GnFileUpload` owns preview object URLs and cleans them up on remove/unmount.
- `GnRouterTabs` drives active state from the current vue-router route and calls `router.push()` on tab activation. Requires `vue-router` in the host app.
- `GnNavList` detects `item.to` (router target) and renders accessible links with resolved `href`. If `vue-router` is present, clicking navigates via the router and active state is computed from the current route.