### Install Dependencies

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Installs project dependencies. Ensure `vuestic-ui` is installed from its local package folder.

```bash
yarn
```

--------------------------------

### Install Vuestic Compiler Package

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/compiler/Readme.md

Install the Vuestic compiler package using npm. This is the first step in setting up the Vuestic UI plugin.

```bash
npm i @vuestic/compiler@latest
```

--------------------------------

### Local Development Setup for Vue CLI Plugin

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/vue-cli-plugin/README.md

Install the plugin locally for development and then invoke it to test changes. This is useful for contributing to the plugin or customizing its behavior.

```bash
yarn add -D file:/full/path/to/your/plugin
vue invoke vuestic-ui
```

--------------------------------

### Create a New Vuestic App

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/create-vuestic/Readme.md

Use this command to start a new Vuestic project with the interactive CLI.

```bash
npm create vuestic@latest
```

--------------------------------

### Basic Web Component Interaction Example

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/docs/page-config/getting-started/web-components/code/example-html.html

This example demonstrates how to interact with Vuestic UI web components, specifically a select component and a button. It shows how to set options for a select element and how to listen for user interactions like option selection and button clicks.

```javascript
const select = document.getElementById("select");
select.options = ["Option 1", "Option 2", "Option 3"];
select.addEventListener("update:modelValue", (e) => {
  e.target.modelValue = e.detail;
  console.log('Option selected!', e.target.modelValue)
});

const button = document.getElementById("button");
button.addEventListener("click", () => {
  console.log("Make something! User clicked the button");
});
```

--------------------------------

### Install AG Grid Theme with yarn

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ag-grid-theme/README.md

Install the AG Grid theme package using yarn.

```bash
yarn add @vuestic/ag-grid-theme
```

--------------------------------

### Install AG Grid Theme with npm

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ag-grid-theme/README.md

Install the AG Grid theme package using npm.

```bash
npm i @vuestic/ag-grid-theme
```

--------------------------------

### VaButton Component Examples

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Demonstrates various presets, color and size options, icon integration, loading and disabled states, and router link/href usage for the VaButton component.

```vue
<template>
  <!-- Basic variants -->
  <va-button>Default</va-button>
  <va-button preset="secondary">Secondary</va-button>
  <va-button preset="plain">Plain</va-button>
  <va-button preset="primary" border-color="primary">Outlined</va-button>

  <!-- Colors & sizes -->
  <va-button color="success" size="small">Small Success</va-button>
  <va-button color="danger" size="large">Large Danger</va-button>
  <va-button color="#FF5733">Custom Hex</va-button>

  <!-- Icons -->
  <va-button icon="add" />
  <va-button icon="search" icon-right="arrow_forward">Search</va-button>

  <!-- States -->
  <va-button :loading="isLoading" @click="fetchData">Load</va-button>
  <va-button disabled>Disabled</va-button>

  <!-- Router link -->
  <va-button :to="{ name: 'home' }">Go Home</va-button>
  <va-button href="https://vuestic.dev" target="_blank">Docs</va-button>

  <!-- Rounded & block -->
  <va-button round block>Full Width Rounded</va-button>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const isLoading = ref(false)
const fetchData = async () => {
  isLoading.value = true
  await new Promise(r => setTimeout(r, 2000))
  isLoading.value = false
}
</script>
```

--------------------------------

### Storybook Development Commands

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/vueform/README.md

Commands to serve, build, and start Storybook for Vuestic UI components. Also includes a build command for the library.

```bash
yarn serve:storybook
```

```bash
yarn build:storybook
```

```bash
yarn start:storybook
```

```bash
yarn build
```

--------------------------------

### Scaffold New Vuestic Project with CLI

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Use the `create-vuestic` CLI to scaffold new Vite or Nuxt projects pre-configured with Vuestic UI. Supports interactive setup or non-interactive creation with specific templates.

```bash
# Interactive project creation (Vite or Nuxt, with optional Vuestic Admin)
npm create vuestic@latest

# Non-interactive with specific template
npm create vuestic@latest my-app -- --template vite
npm create vuestic@latest my-app -- --template nuxt
```

--------------------------------

### Run Vuestic UI Nuxt Module in Development Mode

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Start the playground environment for the Vuestic UI Nuxt module in development mode. This allows for rapid iteration and testing of components.

```bash
npm run dev
```

--------------------------------

### Add Vuestic UI Nuxt Module

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Run this command to add the Vuestic module to your Nuxt 3 project. Refer to the installation documentation for a detailed guide.

```bash
npx nuxi module add vuestic
```

--------------------------------

### Add Vuestic UI to Vue Project

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/vue-cli-plugin/README.md

Use this command to install the Vuestic UI library and its necessary configurations into your Vue application.

```bash
vue add vuestic-ui
```

--------------------------------

### useModal

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Creates confirmation dialogs and custom modals programmatically from within setup functions. It returns a Promise that resolves with the user's interaction, allowing for asynchronous handling of modal responses.

```APIDOC
### `useModal` — Programmatic Modals

Creates confirmation dialogs and custom modals programmatically from within setup functions.

```vue
<script setup lang="ts">
import { useModal } from 'vuestic-ui'

const { init, confirm } = useModal()

// Confirmation dialog — returns Promise<boolean>
const handleDelete = async () => {
  const agreed = await confirm({
    title: 'Delete Record',
    message: 'This action cannot be undone. Are you sure?',
    okText: 'Delete',
    cancelText: 'Cancel',
    size: 'small',    // 'small' | 'medium' | 'large'
    blur: true,
    onOk: () => console.log('Confirmed'),
    onCancel: () => console.log('Cancelled'),
  })

  if (agreed) {
    await deleteRecord()
  }
}

// Non-blocking modal init — returns close function
const closeModal = init({
  title: 'Terms of Service',
  message: 'Please read the terms before continuing.',
  hideDefaultActions: false,
  fullscreen: false,
  closeButton: true,
  overlay: true,
  overlayOpacity: 0.6,
  zIndex: 1000,
  maxWidth: '600px',
  beforeClose: (el) => console.log('closing', el),
})

// Close programmatically
setTimeout(closeModal, 3000)
</script>
```
```

--------------------------------

### Image Loading with Nuxt-Img

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/docs/README.md

Example of how to use the nuxt-img component to load images from the ~/assets/images directory. It is recommended to set image sizes and optimize images.

```vue
<nuxt-img src="/landing/image-open-source.png" height="500px" width="500px" />
```

--------------------------------

### Install Dependencies for Vuestic UI Nuxt Module

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Install project dependencies within the Vuestic UI Nuxt module package. This is a prerequisite for development tasks.

```bash
npm install
```

--------------------------------

### VaSelect Component Examples

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Illustrates using VaSelect with simple string arrays, object arrays with custom text/value mapping, and multi-select functionality with chip display and maximum selection limits.

```vue
<template>
  <!-- Simple string array -->
  <va-select
    v-model="country"
    label="Country"
    :options="['USA', 'Germany', 'France', 'Japan']"
    placeholder="Select a country"
    clearable
    searchable
  />

  <!-- Object options with text/value mapping -->
  <va-select
    v-model="selectedUser"
    label="Assign To"
    :options="users"
    text-by="name"
    value-by="id"
    :rules="[(v) => !!v || 'Please assign a user']"
  >
    <template #option="{ option, isSelected }">
      <va-avatar :src="option.avatar" size="small" />
      {{ option.name }} — {{ option.role }}
      <va-icon v-if="isSelected" name="check" size="small" color="primary" />
    </template>
  </va-select>

  <!-- Multi-select -->
  <va-select
    v-model="tags"
    label="Tags"
    :options="availableTags"
    multiple
    :max-selections="5"
    chip
    clearable
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
const country = ref('')
const selectedUser = ref(null)
const tags = ref<string[]>([])
const users = [
  { id: 1, name: 'Alice Chen', role: 'Admin', avatar: '/alice.jpg' },
  { id: 2, name: 'Bob Smith', role: 'Editor', avatar: '/bob.jpg' },
]
const availableTags = ['Vue', 'TypeScript', 'Nuxt', 'Tailwind', 'Pinia', 'GraphQL']
</script>
```

--------------------------------

### Programmatic Modals with `useModal`

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Creates confirmation dialogs and custom modals programmatically within setup functions. Returns a Promise for confirmation dialogs or a close function for other modals.

```vue
<script setup lang="ts">
import { useModal } from 'vuestic-ui'

const { init, confirm } = useModal()

// Confirmation dialog — returns Promise<boolean>
const handleDelete = async () => {
  const agreed = await confirm({
    title: 'Delete Record',
    message: 'This action cannot be undone. Are you sure?',
    okText: 'Delete',
    cancelText: 'Cancel',
    size: 'small',    // 'small' | 'medium' | 'large'
    blur: true,
    onOk: () => console.log('Confirmed'),
    onCancel: () => console.log('Cancelled'),
  })

  if (agreed) {
    await deleteRecord()
  }
}

// Non-blocking modal init — returns close function
const closeModal = init({
  title: 'Terms of Service',
  message: 'Please read the terms before continuing.',
  hideDefaultActions: false,
  fullscreen: false,
  closeButton: true,
  overlay: true,
  overlayOpacity: 0.6,
  zIndex: 1000,
  maxWidth: '600px',
  beforeClose: (el) => console.log('closing', el),
})

// Close programmatically
setTimeout(closeModal, 3000)
</script>
```

--------------------------------

### Tailwind Configuration with Synced Vuestic Colors

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Example of a `tailwind.config.ts` file after synchronization, showing Vuestic colors and breakpoints integrated as Tailwind utilities. These are auto-populated by the sync scripts.

```typescript
// tailwind.config.ts  (after sync, Vuestic colors appear as Tailwind utilities)
import type { Config } from 'tailwindcss'

export default {
  content: ['./src/**/*.{vue,ts}'],
  theme: {
    extend: {
      colors: {
        // These are auto-populated by sync-vuestic-with-tailwind:
        primary: '#154EC1',
        secondary: '#767C88',
        success: '#3D9209',
        danger: '#E42222',
      },
      screens: {
        // Vuestic breakpoints synced:
        sm: '640px',
        md: '1024px',
        lg: '1440px',
        xl: '1920px',
      },
    },
  },
} satisfies Config
```

--------------------------------

### Interact with Vuestic Button and Select Components

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/web-components/index.html

This snippet shows how to get references to Vuestic button and select components, add event listeners, and configure component properties.

```javascript
const button = document.getElementById("button"); button.addEventListener("click", () => { console.log("clicked"); }); const select = document.getElementById("select"); select.options = ["Option 1", "Option 2", "Option 3"]; select.addEventListener("update:modelValue", (e) => { e.target.modelValue = e.detail; console.log('Option selected!', e.target.modelValue) }); const config = document.getElementById("config"); config.components = { VaButton: { color: "danger", }, };
```

--------------------------------

### VaInput Component Examples

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Showcases a searchable input with clearable state, loading indicator, validation rules, and custom slots for prepend/append elements. Also includes a password field with a visibility toggle.

```vue
<template>
  <va-input
    v-model="search"
    label="Search Users"
    placeholder="Type a name..."
    clearable
    :loading="isSearching"
    :rules="[(v) => v.length >= 2 || 'Min 2 characters']"
    @update:modelValue="onSearch"
  >
    <template #prependInner>
      <va-icon name="search" size="small" />
    </template>
    <template #appendInner>
      <va-button preset="plain" size="small" @click="search = ''">Clear</va-button>
    </template>
  </va-input>

  <!-- Password field with reveal -->
  <va-input
    v-model="password"
    :type="showPassword ? 'text' : 'password'"
    label="Password"
    :rules="[
      (v) => !!v || 'Required',
      (v) => v.length >= 8 || 'Min 8 chars',
    ]"
    :error-messages="serverError ? [serverError] : []"
  >
    <template #appendInner>
      <va-icon
        :name="showPassword ? 'visibility_off' : 'visibility'"
        @click="showPassword = !showPassword"
      />
    </template>
  </va-input>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const search = ref('')
const password = ref('')
const showPassword = ref(false)
const isSearching = ref(false)
const serverError = ref('')
const onSearch = (val: string) => { /* debounced API call */ }
</script>
```

--------------------------------

### Use Vuestic Components in Nuxt 3

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Utilize Vuestic components and composables directly in your Nuxt 3 pages without explicit imports. This example shows a simple card and button with theme toggling.

```vue
<!-- pages/index.vue — No imports needed, all components auto-imported -->
<template>
  <va-card>
    <va-card-title>Welcome to Nuxt + Vuestic</va-card-title>
    <va-card-content>
      <va-button @click="toggleTheme">Toggle Dark Mode</va-button>
    </va-card-content>
  </va-card>
</template>

<script setup lang="ts">
// Composables are also auto-imported
const { applyPreset, currentPresetName } = useColors()
const toggleTheme = () => {
  applyPreset(currentPresetName.value === 'light' ? 'dark' : 'light')
}
</script>
```

--------------------------------

### Build Bundles

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Creates bundles using Vue CLI, Vite, and Nuxt.

```bash
yarn build
```

--------------------------------

### Build and Test All

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds Vuestic, `@vuestic/nuxt`, and `./src` using Vite, Vue CLI, and Nuxt. Also tests for tree-shaking.

```bash
ci
```

--------------------------------

### Serve Vite Build

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Serves the built `./dist/vite` project in production mode using Vite.

```bash
yarn serve:vite
```

--------------------------------

### Serve Nuxt Build

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Serves the built `./dist/nuxt` project in production mode using Nuxt.

```bash
yarn serve:nuxt
```

--------------------------------

### Basic Data Table with Static Data

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/web-components/src/demos/data-table.html

Demonstrates how to initialize a Vuestic UI Data Table with a static array of objects. Ensure your data is properly formatted as an array of objects.

```html
<va-data-table :items="users" :columns="columns" />
```

--------------------------------

### Build with Tree-shaking Analysis

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Performs a build with tree-shaking and generates a `tree-shaking.md` file detailing bundle sizes. Use `--use-cache` to generate the file only if it doesn't exist.

```bash
yarn build:analysis
```

```bash
yarn build:analysis --use-cache
```

--------------------------------

### Run Nuxt Dev Server

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Runs the `./src` project in development mode using Nuxt.

```bash
yarn dev:nuxt
```

--------------------------------

### Build Nuxt Bundle

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds the project specifically for Nuxt.

```bash
yarn build:nuxt
```

--------------------------------

### Build Vite Bundle

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds the project specifically for Vite.

```bash
yarn build:vite
```

--------------------------------

### Running the Release Script with Arguments

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/deploy/release-script/release-script.md

Execute the release script with specific arguments to control its behavior. Use `--release-type` to specify the type of release (e.g., experimental) and `--dry-run` for testing without pushing changes.

```sh
npx tsx release-script/release-script.ts

  # release type (required) - large | tiny | development | experimental
  --release-type=experimental

  # for testing - doesn't push changes anywhere and performs a cleanup
  --dry-run 
```

--------------------------------

### Build Vuestic Nuxt Package

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds the `@vuestic/nuxt` package.

```bash
yarn build:vuestic-nuxt
```

--------------------------------

### Serve Vue CLI Build

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Serves the built `./dist/vue-cli` project in production mode using Vue CLI (Webpack).

```bash
yarn serve:vue-cli
```

--------------------------------

### Run Vite Dev Server

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Runs the `./src` project in development mode using Vite.

```bash
yarn dev:vite
```

--------------------------------

### Tree-Shakeable Plugin Registration with createVuesticEssential

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Use `createVuesticEssential` to register only explicitly provided components and plugins for optimal bundle size. Import `essential.css` and the specific components/plugins needed.

```typescript
import { createApp } from 'vue'
import {
  createVuesticEssential,
  VaButton,
  VaInput,
  VaSelect,
  VaToastPlugin,
  VaModalPlugin,
} from 'vuestic-ui'
import 'vuestic-ui/styles/essential.css'
import App from './App.vue'

createApp(App)
  .use(createVuesticEssential({
    components: { VaButton, VaInput, VaSelect },
    plugins: { VaToastPlugin, VaModalPlugin },
    config: {
      colors: {
        variables: { primary: '#154EC1' },
      },
    },
  }))
  .mount('#app')
```

--------------------------------

### Repo Root Commands for Release Script

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/deploy/release-script/release-script.md

Simplified commands to run the release script from the repository root using npm. These commands abstract the direct execution of the script with predefined release types.

```bash
npm run release:large
npm run release:tiny
npm run release:next
npm run release:experimental
```

--------------------------------

### Select Component with Options Array

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/web-components/src/demos/select.html

Shows how to populate the Select component using a JavaScript array for its options. The `options` prop accepts an array of strings or objects.

```javascript
const value = "";
const options = [
  "one",
  "two",
  "three",
  "four",
  "five",
  "six",
  "seven",
  "eight",
  "nine",
];
```

--------------------------------

### Configure GitHub Label Sync

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/github-utilities/README.md

Define GitHub token and repository details in a .env file to avoid interactive prompts when syncing labels.

```env
GITHUB_TOKEN=your_github_token_here
GITHUB_LABEL_SOURCE=epicmaxco/vuestic-ui
GITHUB_LABEL_TARGET=epicmaxco/vuestic-admin
```

--------------------------------

### Run Tests

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Executes tests to verify that tree-shaking is functioning correctly.

```bash
yarn test
```

--------------------------------

### Sync Vuestic and Tailwind CSS Configurations

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Use the `@vuestic/tailwind` CLI to synchronize color palettes and breakpoints between Vuestic UI and Tailwind CSS. Commands are provided for syncing Tailwind to Vuestic, Vuestic to Tailwind, and for watching changes.

```bash
# Sync Tailwind → Vuestic (reads tailwind.config.* and writes vuestic.config.js)
npx sync-tailwind-with-vuestic

# Sync Vuestic → Tailwind (reads Vuestic defaults and writes tailwind.config.cjs)
npx sync-vuestic-with-tailwind

# Watch tailwind.config.* and keep Vuestic in sync automatically
npx watch-tailwind
```

--------------------------------

### Import Styles in SCSS

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ag-grid-theme/README.md

Import the Vuestic AG Grid theme styles using SCSS.

```scss
@import "@vuestic/ag-grid-theme";
```

--------------------------------

### Publish Vuestic UI Nuxt Module

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Publish the Vuestic UI Nuxt module to a registry. Use the `--tag=next` option for publishing alpha versions.

```bash
npm publish
```

```bash
npm publish --tag=next
```

--------------------------------

### Register All Vuestic Components Globally with createVuestic

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Use `createVuestic` to register all Vuestic components and plugins globally. This method bundles the entire library. Ensure `essential.css` and `typography.css` are imported.

```typescript
import { createApp } from 'vue'
import { createVuestic } from 'vuestic-ui'
import 'vuestic-ui/styles/essential.css'
import 'vuestic-ui/styles/typography.css'
import App from './App.vue'

const app = createApp(App)

app.use(createVuestic({
  config: {
    colors: {
      variables: {
        primary: '#6200EE',
        secondary: '#03DAC6',
      },
    },
    components: {
      VaButton: {
        color: 'primary',
        round: true,
      },
      VaInput: {
        outline: true,
      },
    },
  },
}))

app.mount('#app')
```

--------------------------------

### Build Vuestic UI Nuxt Module

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Build the Vuestic UI Nuxt module package. This command is typically used before publishing or for creating distributable artifacts.

```bash
npm run prepack
```

--------------------------------

### Build Vuestic UI Dist

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds the Vuestic UI distribution files, which will be used in Vite, Vue CLI, and Nuxt projects.

```bash
yarn build:vuestic
```

--------------------------------

### Importing Vuestic UI and Overrides

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ui/src/styles/CssVarsGuide.md

Import Vuestic UI styles and your custom override file in your main JavaScript entry point. Ensure your override file is imported after the Vuestic UI CSS to apply your changes correctly.

```javascript
import { VuesticPlugin } from 'vuestic-ui'
import 'vuestic-ui/dist/vuestic-ui.css'
import './vuestic-overrides.css'
```

--------------------------------

### Run Vue CLI Dev Server

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Runs the `./src` project in development mode using Vue CLI (Webpack).

```bash
yarn dev:vue-cli
```

--------------------------------

### Basic Select Component Usage

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/web-components/src/demos/select.html

Demonstrates the fundamental structure for using the Vuestic UI Select component. Ensure the component is registered and imported correctly in your Vue application.

```html
<vuestic-select v-model="value" :options="options"></vuestic-select>
```

--------------------------------

### Prepare Type Stubs for Vuestic UI Nuxt Module

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/nuxt/README.md

Generate type stubs for the Vuestic UI Nuxt module. This is essential for improved developer experience and type safety during development.

```bash
npm run dev:prepare
```

--------------------------------

### Build Vue CLI Bundle

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/README.md

Builds the project specifically for Vue CLI (Webpack).

```bash
yarn build:vue-cli
```

--------------------------------

### useColors

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Manages the reactive color palette, providing utilities for color resolution, preset switching, and color manipulation. It allows dynamic updates to the color system and retrieval of accessible text colors.

```APIDOC
## `useColors` — Reactive Color System

Exposes the active color palette, color resolution utilities, and preset switching. All color lookups fall back through named variables, CSS variables, and direct hex/rgb values.

### Usage
```vue
<script setup lang="ts">
import { useColors } from 'vuestic-ui'

const { colors, getColor, getTextColor, setColors, applyPreset, currentPresetName, presets, getHoverColor, getFocusColor, colorToRgba } = useColors()

// Resolve a named color to its hex value
const primary = getColor('primary')          // '#154EC1'
const rawHex = getColor('#FF5733')           // '#FF5733' (pass-through)
const withVar = getColor('primary', undefined, true) // 'var(--va-primary)'

// Get accessible text color on a given background
const textOnPrimary = getTextColor(primary)  // '#FFFFFF' or '#000000'

// Programmatically update individual colors
setColors({ primary: '#6200EE', secondary: '#03DAC6' })

// Switch to a named preset ('light' | 'dark' | custom)
applyPreset('dark')
console.log(currentPresetName.value)         // 'dark'
console.log(Object.keys(presets.value))      // ['light', 'dark', 'corporate']

// Utility: get hover/focus variants
const hoverColor = getHoverColor('#154EC1')
const focusRing = getFocusColor('#154EC1')

// Convert to rgba
const rgba = colorToRgba('#154EC1', 0.5)     // 'rgba(21,78,193,0.5)'
</script>
```
```

--------------------------------

### useColors - Reactive Color System

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Manages the active color palette, provides color resolution utilities, and allows preset switching. Color lookups fallback through named variables, CSS variables, and direct hex/rgb values.

```vue
<script setup lang="ts">
import { useColors } from 'vuestic-ui'

const {
  colors,
  getColor,
  getTextColor,
  setColors,
  applyPreset,
  currentPresetName,
  presets,
  getHoverColor,
  getFocusColor,
  colorToRgba,
} = useColors()

// Resolve a named color to its hex value
const primary = getColor('primary')          // '#154EC1'
const rawHex = getColor('#FF5733')           // '#FF5733' (pass-through)
const withVar = getColor('primary', undefined, true) // 'var(--va-primary)'

// Get accessible text color on a given background
const textOnPrimary = getTextColor(primary)  // '#FFFFFF' or '#000000'

// Programmatically update individual colors
setColors({ primary: '#6200EE', secondary: '#03DAC6' })

// Switch to a named preset ('light' | 'dark' | custom)
applyPreset('dark')
console.log(currentPresetName.value)         // 'dark'
console.log(Object.keys(presets.value))      // ['light', 'dark', 'corporate']

// Utility: get hover/focus variants
const hoverColor = getHoverColor('#154EC1')
const focusRing = getFocusColor('#154EC1')

// Convert to rgba
const rgba = colorToRgba('#154EC1', 0.5)     // 'rgba(21,78,193,0.5)'
</script>
```

--------------------------------

### useBreakpoint - Responsive Breakpoint Detection

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Returns reactive breakpoint state based on the current viewport width. Defaults are xs=0, sm=640, md=1024, lg=1440, xl=1920. Use breakpoint flags like `mdUp` to conditionally render elements.

```vue
<template>
  <div>
    <p>Current breakpoint: {{ breakpoint.current }}</p>
    <p>Width: {{ breakpoint.width }}px</p>
    <VaButton v-if="breakpoint.mdUp" size="large">Desktop CTA</VaButton>
    <VaButton v-else size="small">Mobile CTA</VaButton>
    <va-data-table v-if="!breakpoint.xs" :items="rows" :columns="cols" />
  </div>
</template>

<script setup lang="ts">
import { useBreakpoint } from 'vuestic-ui'

const breakpoint = useBreakpoint()
// breakpoint.xs   — true if width < 640
// breakpoint.sm   — true if 640 <= width < 1024
// breakpoint.md   — true if 1024 <= width < 1440
// breakpoint.lg   — true if 1440 <= width < 1920
// breakpoint.xl   — true if width >= 1920
// breakpoint.smUp — true if width >= 640
// breakpoint.mdUp — true if width >= 1024
// breakpoint.smDown — true if width < 1024
</script>
```

--------------------------------

### Configure Vuestic UI Components Globally

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/docs/page-config/getting-started/web-components/code/example-global-config.html

Set default properties for components like VaButton and VaInput. This configuration applies to all instances of these components unless overridden locally.

```javascript
const config = document.getElementById("config");
config.components = {
  VaButton: {
    color: "danger",
  },
  VaInput: {
    outline: true,
  }
};
```

--------------------------------

### useBreakpoint

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Provides reactive breakpoint detection based on the current viewport width. It exposes boolean flags for various screen sizes and ranges, enabling responsive UI design.

```APIDOC
## `useBreakpoint` — Responsive Breakpoint Detection

Returns reactive breakpoint state based on the current viewport width. Defaults: xs=0, sm=640, md=1024, lg=1440, xl=1920.

### Usage
```vue
<template>
  <div>
    <p>Current breakpoint: {{ breakpoint.current }}</p>
    <p>Width: {{ breakpoint.width }}px</p>
    <VaButton v-if="breakpoint.mdUp" size="large">Desktop CTA</VaButton>
    <VaButton v-else size="small">Mobile CTA</VaButton>
    <va-data-table v-if="!breakpoint.xs" :items="rows" :columns="cols" />
  </div>
</template>

<script setup lang="ts">
import { useBreakpoint } from 'vuestic-ui'

const breakpoint = useBreakpoint()
// breakpoint.xs   — true if width < 640
// breakpoint.sm   — true if 640 <= width < 1024
// breakpoint.md   — true if 1024 <= width < 1440
// breakpoint.lg   — true if 1440 <= width < 1920
// breakpoint.xl   — true if width >= 1920
// breakpoint.smUp — true if width >= 640
// breakpoint.mdUp — true if width >= 1024
// breakpoint.smDown — true if width < 1024
</script>
```
```

--------------------------------

### Import Styles in JS/TS

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ag-grid-theme/README.md

Import the Vuestic AG Grid theme styles directly into your project's entry JavaScript or TypeScript file.

```javascript
import '@vuestic/ag-grid-theme'
```

--------------------------------

### Define Typed Vuestic Configuration with defineVuesticConfig

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Use `defineVuesticConfig` as a type-safe helper to define Vuestic configuration in a separate file, suitable for Nuxt or large applications. This allows for detailed theming and component defaults.

```typescript
import { defineVuesticConfig } from 'vuestic-ui'

export default defineVuesticConfig({
  colors: {
    variables: {
      primary: '#154EC1',
      secondary: '#767C88',
      success: '#3D9209',
      danger: '#E42222',
      warning: '#FFD43A',
    },
    presets: {
      corporate: {
        primary: '#003580',
        secondary: '#0071CC',
        success: '#007A4D',
        danger: '#D4111E',
        warning: '#FF8F00',
        backgroundPrimary: '#F8F9FA',
        backgroundSecondary: '#FFFFFF',
        backgroundElement: '#E9ECEF',
        backgroundBorder: '#CED4DA',
        textPrimary: '#212529',
        textInverted: '#FFFFFF',
        shadow: 'rgba(0,0,0,0.1)',
        focus: '#0071CC',
        transparent: 'rgba(0,0,0,0)',
      },
    },
  },
  components: {
    VaButton: { size: 'medium', round: false },
    VaCard: { stripe: false },
  },
})
```

--------------------------------

### Programmatic Toast Notifications with `VaToastPlugin`

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Creates and destroys toast notifications imperatively using the global `$vaToast` instance. Supports simple messages or complex configurations with callbacks and styling.

```vue
<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()!

// Simple message
const id = proxy.$vaToast.init('File saved successfully!')

// Full options
const id2 = proxy.$vaToast.init({
  title: 'Upload Complete',
  message: '3 files were uploaded to the server.',
  color: 'success',         // 'success' | 'danger' | 'warning' | 'info' | any hex
  position: 'bottom-right', // 'top-right'|'top-center'|'top-left'|'bottom-right'|'bottom-center'|'bottom-left'
  duration: 5000,           // ms; 0 = no auto-close
  closeable: true,
  iconClass: 'fa fa-check',
  offsetY: 20,
  onClick: () => console.log('Toast clicked'),
  onClose: () => console.log('Toast closed'),
})

// Close a specific toast
proxy.$vaToast.close(id2)

// Close all toasts in current app
proxy.$vaToast.closeAll()

// Close all toasts across all app instances
proxy.$vaToast.closeAll(true)
</script>
```

--------------------------------

### createIconsConfig for Custom Icon System

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Register custom icon fonts or aliases with createIconsConfig to extend Vuestic UI's icon capabilities. This allows using custom icon libraries or defining shorthand names for existing icons.

```typescript
// main.ts
import { createVuestic, createIconsConfig } from 'vuestic-ui'

app.use(createVuestic({
  config: {
    icons: createIconsConfig({
      // Custom font (e.g., Font Awesome)
      fonts: [
        {
          name: 'fa4 {icon}',
          resolve: ({ icon }) => ({
            class: `fa fa-${icon}`,
            tag: 'i',
            content: '',
          }),
        },
      ],
      // Aliases: map short names to Material Icons or other fonts
      aliases: [
        {
          name: 'logo-github',
          resolve: () => ({
            class: 'fa fa-github',
            tag: 'i',
          }),
        },
        {
          name: 'menu-burger',
          to: 'menu',   // points to Material Icon 'menu'
        },
      ],
    }),
  },
}))

// Usage in template:
// <va-icon name="fa4 star" />
// <va-icon name="logo-github" />
// <va-icon name="menu-burger" />
```

--------------------------------

### useForm

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Offers a typed handle to a `VaForm` instance for programmatic control over form validation, reset, and field inspection. It provides reactive state for form validity, dirty status, and error messages.

```APIDOC
## `useForm` — Form State and Programmatic Control

Provides a typed handle to a `VaForm` instance for programmatic validation, reset, and field inspection.

### Usage
```vue
<template>
  <va-form ref="myForm" @submit.prevent="submit">
    <va-input
      v-model="email"
      name="email"
      label="Email"
      :rules="[
        (v) => !!v || 'Email is required',
        (v) => /.+@.+\..+/.test(v) || 'Invalid email format',
      ]"
    />
    <va-input
      v-model="password"
      name="password"
      type="password"
      label="Password"
      :rules="[
        (v) => !!v || 'Password is required',
        (v) => v.length >= 8 || 'Password must be at least 8 characters',
      ]"
    />
    <va-button type="submit" :disabled="!form.isValid">Submit</va-button>
    <va-button preset="secondary" @click="form.reset()">Reset</va-button>
  </va-form>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useForm } from 'vuestic-ui'

const email = ref('')
const password = ref('')

const form = useForm('myForm')
// form.isValid        — ComputedRef<boolean>
// form.isDirty        — ComputedRef<boolean>
// form.isTouched      — ComputedRef<boolean>
// form.isLoading      — ComputedRef<boolean>
// form.errorMessages  — ComputedRef<string[]>
// form.formData       — ComputedRef<Record<string, any>>
// form.validate()     — triggers all field validations synchronously
// form.validateAsync()— triggers all field validations (incl. async rules)
// form.reset()        — resets values + validation state
// form.resetValidation() — clears errors without resetting values
// form.focusInvalidField() — focuses first invalid field

const submit = async () => {
  const isValid = await form.validateAsync()
  if (!isValid) return
  console.log('Submitted:', form.formData.value)
}
</script>
```
```

--------------------------------

### VaToastPlugin / $vaToast

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Creates and destroys toast notifications imperatively. This plugin is available globally as `$vaToast` or via the composition API, allowing for flexible programmatic control over notifications.

```APIDOC
## Programmatic Plugins

### `VaToastPlugin` / `$vaToast` — Programmatic Notifications

Creates and destroys toast notifications imperatively. Available globally as `$vaToast` or via composition API.

```vue
<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const { proxy } = getCurrentInstance()!

// Simple message
const id = proxy.$vaToast.init('File saved successfully!')

// Full options
const id2 = proxy.$vaToast.init({
  title: 'Upload Complete',
  message: '3 files were uploaded to the server.',
  color: 'success',         // 'success' | 'danger' | 'warning' | 'info' | any hex
  position: 'bottom-right', // 'top-right'|'top-center'|'top-left'|'bottom-right'|'bottom-center'|'bottom-left'
  duration: 5000,           // ms; 0 = no auto-close
  closeable: true,
  iconClass: 'fa fa-check',
  offsetY: 20,
  onClick: () => console.log('Toast clicked'),
  onClose: () => console.log('Toast closed'),
})

// Close a specific toast
proxy.$vaToast.close(id2)

// Close all toasts in current app
proxy.$vaToast.closeAll()

// Close all toasts across all app instances
proxy.$vaToast.closeAll(true)
</script>
```
```

--------------------------------

### Providing Alt Text for Images

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ui/src/components/AccessibilityGuide.md

All images must have an 'alt' attribute, even if it is empty, to ensure accessibility for screen readers.

```html
alt=""
```

--------------------------------

### Data Table with Dynamic Data

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/sandbox/web-components/src/demos/data-table.html

Shows how to bind dynamic data to the Vuestic UI Data Table. The table will automatically update when the 'users' array changes. This is useful for real-time data display.

```javascript
const users = [
  {
    id: 1,
    name: 'Leanne Graham',
    username: 'Bret',
    email: 'Sincere@april.biz',
    phone: '1-770-736-8031 x56442',
    website: 'hildegard.org',
  },
  {
    id: 2,
    name: 'Ervin Howell',
    username: 'Antonette',
    email: 'Shanna@melissa.tv',
    phone: '010-692-6593 x09125',
    website: 'anastasia.net',
  },
  {
    id: 3,
    name: 'Clementine Bauch',
    username: 'Samantha',
    email: 'Nathan@yesenia.net',
    phone: '1-463-123-4447',
    website: 'ramiro.info',
  },
  {
    id: 4,
    name: 'Patricia Lebsack',
    username: 'Karianne',
    email: 'Julianne.OConner@kory.org',
    phone: '493-170-9623 x156',
    website: 'kale.biz',
  },
  {
    id: 5,
    name: 'Chelsey Dietrich',
    username: 'Kamren',
    email: 'Lucio_Hettinger@annie.ca',
    phone: '(254)954-1289',
    website: 'demarco.info',
  },
]
```

--------------------------------

### Access and Mutate Global Configuration with useGlobalConfig

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

The `useGlobalConfig` composable provides reactive access to the global configuration. Use `setGlobalConfig` to fully replace the config or `mergeGlobalConfig` for non-destructive partial updates.

```vue
<script setup lang="ts">
import { useGlobalConfig } from 'vuestic-ui'

const { globalConfig, setGlobalConfig, mergeGlobalConfig } = useGlobalConfig()

// Read current primary color
console.log(globalConfig.value.colors.variables?.primary)

// Fully replace config
setGlobalConfig((prev) => ({
  ...prev,
  components: {
    ...prev.components,
    VaButton: { color: 'danger' },
  },
}))

// Merge partial updates (non-destructive)
mergeGlobalConfig({
  colors: {
    variables: { primary: '#FF5733' },
  },
})
</script>
```

--------------------------------

### CSS Override Template

Source: https://github.com/epicmaxco/vuestic-ui/blob/develop/packages/ui/src/styles/CssVarsGuide.md

Use this template to define your custom CSS variable overrides. Place all your style modifications within the `:root, :host` selector.

```css
:root,
:host {

}
```

--------------------------------

### VaDataTable with Sorting, Filtering, and Selection

Source: https://context7.com/epicmaxco/vuestic-ui/llms.txt

Implement a data table with features like sorting, filtering, selection, pagination, and custom cell rendering. Ensure items and columns are properly defined.

```vue
<template>
  <va-data-table
    v-model:sort-by="sortBy"
    v-model:sorting-order="sortingOrder"
    v-model:selected-items="selected"
    :items="filteredItems"
    :columns="columns"
    :loading="loading"
    selectable
    select-mode="multiple"
    sticky-header
    :per-page="10"
    :current-page="currentPage"
    @sorted="onSort"
  >
    <template #header(status)="{ label }">
      <span style="color: var(--va-primary)">{{ label }}</span>
    </template>

    <template #cell(status)="{ rowData }">
      <va-badge
        :text="rowData.status"
        :color="rowData.status === 'active' ? 'success' : 'danger'"
      />
    </template>

    <template #cell(actions)="{ rowData }">
      <va-button preset="plain" size="small" icon="edit" @click="editRow(rowData)" />
      <va-button preset="plain" size="small" icon="delete" color="danger" @click="deleteRow(rowData.id)" />
    </template>

    <template #no-data>
      <p>No records found. <va-button preset="plain" @click="resetFilter">Clear filter</va-button></p>
    </template>
  </va-data-table>

  <va-pagination v-model="currentPage" :pages="totalPages" />
</template>

<script setup lang="ts">
import { ref, computed } from 'vue'

const loading = ref(false)
const sortBy = ref('name')
const sortingOrder = ref<'asc' | 'desc'>('asc')
const selected = ref([])
const currentPage = ref(1)

const columns = [
  { key: 'name', label: 'Full Name', sortable: true, width: '30%' },
  { key: 'email', label: 'Email', sortable: true },
  { key: 'status', label: 'Status', sortable: false },
  { key: 'actions', label: '', width: '100px' },
]

const items = ref([
  { id: 1, name: 'Alice Chen', email: 'alice@example.com', status: 'active' },
  { id: 2, name: 'Bob Smith', email: 'bob@example.com', status: 'inactive' },
  // ...
])

const filteredItems = computed(() => items.value)
const totalPages = computed(() => Math.ceil(items.value.length / 10))

const editRow = (row: any) => console.log('Edit', row)
const deleteRow = (id: number) => { items.value = items.value.filter(r => r.id !== id) }
const resetFilter = () => {}
const onSort = ({ sortBy: col, sortingOrder: order }: any) => console.log(col, order)
</script>
```