npm package: @octushub/ui
Description: Octushub design system — Vue 3 components (buttons, text, icons) for dashboard and apps
Author: Octushub
Latest version: 0.3.0

# @octushub/ui

Octushub **design system** — Vue 3 components (buttons, text, icons, utilities) for dashboards and apps.

**Quick guide:** [HOW-TO-USE.md](./HOW-TO-USE.md) — install, license, and usage in a few steps.

---

## Installation

```bash
npm install @octushub/ui
```

**Requirements:** Vue 3 and Tailwind CSS. Configure theme variables in your app (e.g. `--primary`, `--primary-foreground`, `--destructive`, `--accent`).

**License:** A valid key in format `OCTUSHUB-XXXX-XXXX-XXXX` is required. Request one from Octushub; without it the plugin will not register components.

---

## Usage

### With the plugin (global registration)

Components available app-wide as `<OctushubButton>`, `<OctushubText>`, etc. Always pass the key in `licenseKey`.

**Vue 3:**

```ts
import { createApp } from "vue";
import OctushubUI from "@octushub/ui";
import App from "./App.vue";

const app = createApp(App);
app.use(OctushubUI, { licenseKey: "OCTUSHUB-XXXX-XXXX-XXXX" });
app.mount("#app");
```

**Nuxt:**

```ts
import OctushubUI from "@octushub/ui";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(OctushubUI, {
    licenseKey: "OCTUSHUB-XXXX-XXXX-XXXX",
  });
});
```

### Direct import (recommended for tree-shaking)

Call `setLicenseKey` once at bootstrap (e.g. `main.ts`), then import only what you need.

```ts
// main.ts (or equivalent)
import { setLicenseKey } from "@octushub/ui";
setLicenseKey("OCTUSHUB-XXXX-XXXX-XXXX");
```

```vue
<script setup lang="ts">
import { Button, Text, cn } from "@octushub/ui";
</script>

<template>
  <Text variant="headlineLarge" as="h1">Title</Text>
  <Text variant="bodyLarge">Example paragraph.</Text>
  <Button variant="filled">Save</Button>
  <Button variant="destructive" size="small">Delete</Button>
</template>
```

---

## Components and API

| Export | Description |
|--------|-------------|
| `cn(...classes)` | Utility to merge classes (clsx + tailwind-merge). |
| **Button** | Material Design 3. `variant`: `filled`, `filledTonal`, `outlined`, `text`, `link`, `destructive`, `surface`, `brand`. `size`: `small`, `medium`, `large`, `icon`. |
| **buttonVariants** | CVA function with the same Button variants. |
| **Text** | Material typography. `variant`: `displayLarge` through `labelSmall`. `as`: HTML element (h1–h6, p, span, label). |
| **Label** | Form label. |
| **Icon** | Icons via Iconify. Prop `name` (e.g. `mdi:content-copy`, `hugeicons:refresh-01`). |
| **IconTextButton** | Button with icon + text. Slots: `#icon`, default. |
| **RefreshButton** | Icon-only button (refresh). Props: `loading`, `disabled`, `title`. |
| **FilterButton** | Icon + "Filter" button. Optional `hasActiveFilters` (badge). |
| **ActionButton** | Icon + label button (e.g. "View details"). Props: `label`, `loading`, `disabled`. |

---

## License gate

The package only works with a valid key (`OCTUSHUB-XXXX-XXXX-XXXX`).

- **Users:** Provide the key via the plugin (`licenseKey`) or `setLicenseKey()`.
- **Distributors (Octushub):** Generate keys with `npm run generate-license` (or `npm run generate-license -- 5` for multiple) and provide them only to authorized clients. The script is not published to npm.

For API validation (revoke keys, etc.), see the comment in `src/license.ts`.

---

## Development

```bash
cd octushub-ui
npm install
npm run build
```

**Run the example app:**

```bash
npm run example
```

Opens the example app at **http://localhost:5175/** with all button variants, text, themes, and states.

---

## License

MIT © Octushub