# Vue Adapter

GNexus UI Kit ships a Vue 3 adapter for projects that need stable Vue components instead of hand-written kit markup in every codebase.

The adapter is intentionally thin:

- CSS classes and visual behavior still come from `dist/css/kit.css`;
- Vue components normalize props, events, slots, and state;
- Vue runtime is external and must be installed by the host app;
- legacy `dist/js/gnexus-ui-kit.js` remains for plain HTML pages.

## Install Contract

In a Vue project, import CSS once near the app root:

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

Then import components:

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

Or register everything:

```js
import { createApp } from "vue";
import { GnexusUiVue } from "gnexus-ui-kit/vue";
import App from "./App.vue";

createApp(App).use(GnexusUiVue).mount("#app");
```

## Example Usage

```vue
<script setup>
import { ref } from "vue";
import { GnButton, GnTabs, GnModal } from "gnexus-ui-kit/vue";

const tab = ref("overview");
const modalOpen = ref(false);

const tabs = [
  { id: "overview", label: "Overview", icon: "ph-chart-bar" },
  { id: "activity", label: "Activity", icon: "ph-clock" }
];
</script>

<template>
  <GnButton variant="secondary" icon="ph-plus" @click="modalOpen = true">
    Create
  </GnButton>

  <GnTabs v-model="tab" :items="tabs">
    <template #overview>Overview content</template>
    <template #activity>Activity content</template>
  </GnTabs>

  <GnModal v-model:open="modalOpen" title="Create item">
    Modal content
  </GnModal>
</template>
```

## Toasts

Wrap the app once:

```vue
<template>
  <GnToastProvider>
    <RouterView />
  </GnToastProvider>
</template>
```

Use the composable inside descendants:

```js
import { useToast } from "gnexus-ui-kit/vue";

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

## Build

```bash
npm run build:vue
```

Outputs:

```text
dist/vue/index.js
```

The normal `npm run build` also builds the Vue adapter.

Vue example smoke check:

```bash
npm --prefix examples/vue install
npm run build:example:vue
```

The example uses a Vite alias for `vue` because `gnexus-ui-kit` is linked as a local file dependency. Published package consumers do not need that alias if `vue` is installed in the host project.

`kit.css` currently references fonts through absolute `/assets/...` URLs. Vite may warn that those URLs are left for runtime resolution; host apps must serve `dist/assets` at `/assets` or adjust their asset pipeline accordingly.

## Current Components

See [Vue Component Map](vue/component-map.md).

## Layout And Data Patterns

Second-wave adapter components cover common application surfaces:

```vue
<script setup>
import { ref } from "vue";
import {
  GnToolbar,
  GnSearchField,
  GnDescriptionList,
  GnProgress,
  GnChip,
  GnChipGroup
} from "gnexus-ui-kit/vue";

const query = ref("");
const details = [
  { key: "owner", term: "Owner", value: "Ops Console" },
  { key: "status", term: "Status", value: "Active" }
];
</script>

<template>
  <GnToolbar title="Projects" meta="24 records">
    <template #actions>
      <GnSearchField v-model="query" />
    </template>
  </GnToolbar>

  <GnDescriptionList :items="details" />
  <GnProgress label="Rollout" :value="72" animated />

  <GnChipGroup>
    <GnChip variant="secondary" selected>Vue</GnChip>
    <GnChip variant="success">Stable</GnChip>
  </GnChipGroup>
</template>
```

For AI agents and project-specific rules, see [Vue AI Usage Guide](vue/ai-usage-guide.md).

For compatibility rules and breaking-change policy, see [Vue Migration Policy](vue/migration-policy.md).