### Setup HModalProvider and Opener Component

Source: https://design.holistics.dev/guides/modal-mechanism

This snippet shows the basic setup for using the modal system. It wraps the `Opener` component within an `HModalProvider` to make the `useModal` composable available to its descendants. No external dependencies are required beyond the design system.

```vue
<script setup lang="ts">
import { HModalProvider } from '@holistics/design-system'
import Opener from './Opener.vue'
</script>

<template>
  <HModalProvider>
    <Opener />
  </HModalProvider>
</template>

```

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

### HTag Component Theming Examples (Vue)

Source: https://design.holistics.dev/components/tag

Illustrates how to apply different themes to the HTag component using the 'theme' prop. This example iterates through a predefined array of theme names. Requires importing HTag from '@holistics/design-system'.

```vue
<script setup lang="ts">
import { HTag } from '@holistics/design-system'

const themes = ['green', 'blue', 'red', 'orange', 'purple', 'gray', 'white'] as const
</script>

<template>
  <div class="flex gap-2">
    <HTag
      v-for="theme in themes"
      :key="theme"
      tag="Primary"
      :theme="theme"
    />
  </div>
</template>

```

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

### Vue Script Setup for Avatar Component Metadata

Source: https://design.holistics.dev/components/avatar

This script setup defines the metadata for the Avatar component's props. It initializes an object `_meta` and populates its `props` array with detailed information for each prop, including name, type, requirement, default value, and description.

```vue
<script setup>
const _meta = {}

_meta.props = [
  {
    "name": "size",
    "type": "\"md\" | \"sm\" | \"lg\" | \"xl\"",
    "required": true,
    "description": ""
  },
  {
    "name": "shape",
    "type": "\"round\" | \"square\"",
    "required": false,
    "default": "AVATAR_SHAPES[0]",
    "description": ""
  },
  {
    "name": "tag",
    "type": "string",
    "required": false,
    "description": "<p>The HTML tag for the Avatar component.</p>\n"
  },
  {
    "name": "image",
    "type": "string",
    "required": false,
    "description": "<p>The url of the image for the avatar</p>\n"
  },
  {
    "name": "name",
    "type": "string",
    "required": false,
    "description": ""
  },
  {
    "name": "initials",
    "type": "string",
    "required": false,
    "description": "<p>This is placeholder when an avatar image is not available or while it's loading.</p>\n"
  },
  {
    "name": "badge",
    "type": "\"sm\" | \"lg\"",
    "required": false,
    "description": "<p>The badge size for the avatar.</p>\n"
  },
  {
    "name": "href",
    "type": "string",
    "required": false,
    "description": "<p>Hyperlink reference for the avatar. Will open this URL on click.</p>\n"
  },
  {
    "name": "target",
    "type": "HTMLAttributeTarget",
    "required": false,
    "description": "<p>The target attribute specifies where to open the linked document. Usually use with <code>href</code>.</p>\n"
  },
  {
    "name": "to",
    "type": "string",
    "required": false,
    "description": "<p>A string representing a path or route.</p>\n"
  },
  {
    "name": "replace",
    "type": "boolean",
    "required": false,
    "description": "<p>Specifies whether or not the history should be replaced. Usually use with <code>to</code>.</p>\n"
  }
]
</script>
```

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

### Install Vue Router

Source: https://design.holistics.dev/components/tree

Installs the Vue Router package using npm, pnpm, or yarn. This is a prerequisite for using router links within the Tree component.

```shell
npm add vue-router
```

```shell
pnpm add vue-router
```

```shell
yarn add vue-router
```

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

### Vue Tree Component - Basic Usage Example

Source: https://design.holistics.dev/components/tree

Demonstrates the basic structure and usage of the Tree component in Vue.js. It includes setting up the component with an array of nodes and shows how to handle events like node loading.

```vue
<template>
  <ComponentDemo>
    <template #default="{ component: HTree }">
      <HTree :nodes="nodes" />
    </template>
  </ComponentDemo>
</template>

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

const nodes = [
  { key: 'Monitoring', label: 'Monitoring', icon: 'canvas' },
  {
    key: 'DataSets',
    label: 'DataSets',
    icon: 'folder-solid',
    children: [
      { key: 'Calendar', label: 'Calendar', icon: 'data-set' },
      { key: 'Performance', label: 'Performance', icon: 'data-set' },
      { key: 'Metrics', label: 'Metrics', icon: 'data-set' },
    ],
  },
  { key: 'README.md', label: 'README.md', icon: 'markdown' },
  {
    key: 'Drag & Drop',
    label: 'Drag & Drop',
    icon: 'folder-solid',
    children: [
      {
        key: 'Inner',
        label: 'Inner',
        icon: 'folder-solid',
        children: [
          { key: '1. One', label: '1. One', icon: 'user' },
          { key: '2. Two', label: '2. Two', icon: 'group' },
          { key: '3. Three', label: '3. Three', icon: 'globe' },
          {
            key: '4. Four', label: '4. Four', icon: 'bell', disabled: true,
          },
          { key: '5. Five', label: '5. Five', icon: 'file/csv' },
        ],
      },
    ],
  },
  {
    key: 'So long....',
    // eslint-disable-next-line max-len
    label: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.',
    icon: 'database',
  },
  { key: 'Last Disabled', label: 'Last Disabled', icon: 'formula', disabled: true },
]
</script>
```

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

### Basic HBadge Usage in Vue

Source: https://design.holistics.dev/components/badge

Demonstrates the basic implementation of the HBadge component. It imports HBadge from the design system and renders a simple badge with the label 'Badge'. This serves as a starting point for using the component.

```vue
<script setup lang="ts">
import { HBadge } from '@holistics/design-system'
</script>

<template>
  <div class="flex flex-wrap items-center justify-center gap-2">
    <HBadge label="Badge" />
  </div>
</template>

```

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

### Install TailwindCSS Preset via Package Managers

Source: https://design.holistics.dev/guides/tailwindcss-preset

Installs the `@holistics/configs` package, which provides a custom TailwindCSS preset. Supports npm, pnpm, and yarn package managers.

```shell
npm add -D @holistics/configs
```

```shell
pnpm add -D @holistics/configs
```

```shell
yarn add -D @holistics/configs
```

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

### Vue.js Component Setup for Pass-through Div

Source: https://design.holistics.dev/components/banner

This Vue.js script setup defines the metadata for a pass-through component. It specifies the component's props, events, and slots, enabling flexible attribute and event handling. The `_meta` object holds the definitions that can be used to generate documentation tables.

```javascript
const _meta = {}

_meta.props = [
  {
    "name": "type",
    "type": "\"info\" | \"success\" | \"warning\" | \"danger\" | \"neutral\"",
    "required": true,
    "description": ""
  },
  {
    "name": "theme",
    "type": "\"inline\" | \"full-width\"",
    "required": false,
    "default": "\"inline\"",
    "description": ""
  },
  {
    "name": "title",
    "type": "string",
    "required": false,
    "description": ""
  },
  {
    "name": "description",
    "type": "string",
    "required": false,
    "description": ""
  },
  {
    "name": "hideIcon",
    "type": "boolean",
    "required": false,
    "description": ""
  },
  {
    "name": "dismissible",
    "type": "boolean",
    "required": false,
    "description": ""
  },
  {
    "name": "dismissable",
    "type": "boolean",
    "required": false,
    "description": ""
  },
  {
    "name": "button",
    "type": "string | ButtonPropsPreTyped",
    "required": false,
    "description": ""
  }
]

_meta.events = [
  {
    "name": "buttonClick",
    "type": "[e: MouseEvent]",
    "description": ""
  },
  {
    "name": "dismiss",
    "type": "[]",
    "description": ""
  }
]

_meta.slots = [
  {
    "name": "header",
    "type": "any",
    "description": ""
  },
  {
    "name": "default",
    "type": "any",
    "description": ""
  }
]
```

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

### HShortcut Component - Dark Theme Examples (Vue)

Source: https://design.holistics.dev/components/shortcut

Illustrates how to use the HShortcut component with a dark theme. It shows both the default and outlined versions of the shortcut in a dark background context.

```vue
<script setup lang="ts">
import { HShortcut } from '@holistics/design-system'

</script>

<template>
  <div class="flex flex-col gap-4">
    <HShortcut
      theme="dark"
    >
      Esc
    </HShortcut>

    <HShortcut
      theme="dark"
      outline
    >
      Esc
    </HShortcut>
  </div>
</template>

```

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

### Switch Component with Size Variations (Vue)

Source: https://design.holistics.dev/components/switch

Illustrates how to use the HSwitch component with different size variants provided by the SWITCH_SIZES constant. This example iterates through available sizes and applies them to the switch. Requires Vue 3 and the @holistics/design-system library.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HSwitch, SWITCH_SIZES } from '@holistics/design-system'

const isOn = ref(false)
</script>

<template>
  <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
    <HSwitch
      v-for="size in SWITCH_SIZES"
      :key="size"
      v-model="isOn"
      :size="size"
    />
  </div>
</template>

```

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

### Component Configuration (Vue.js)

Source: https://design.holistics.dev/components/tag_list

This script sets up metadata for a component, defining its properties, events, and slots. It utilizes Vue.js's <script setup> syntax for component logic and configuration.

```javascript
const _meta = {}

_meta.props = [
  {
    "name": "modelValue",
    "type": "unknown[]",
    "required": true,
    "description": ""
  },
  {
    "name": "getLabel",
    "type": "TagListGetLabel<unknown>",
    "required": false,
    "description": "<p>A function to get the tag label from the passed generic type <code>T</code>.</p>\n"
  },
  {
    "name": "gap",
    "type": "number",
    "required": false,
    "default": "4",
    "description": "<p>The gap (px) between each tag.</p>\n"
  },
  {
    "name": "minTagSize",
    "type": "number",
    "required": false,
    "default": "(p) => {\n    const base = 2 + 16;\n    if (p.closeable)\n        return base + 2 + 16;\n    return base;\n}",
    "description": "<p>The minimal size (px) of a tag. By default, it's the width of the <code>&lt;Tag&gt;</code> component without any content.</p>\n"
  },
  {
    "name": "counterTagSize",
    "type": "TagListCounterTagSizeFn",
    "required": false,
    "description": "<p>A function to calculate the size (px) of the remaining-counter tag. Since the counter could be <code>1</code> or <code>1000</code>, the\nwidth of the tag is dynamic.</p>\n<p>By default, it's the width of the <code>Tag</code> component with the dynamic content <code>+&lt;number&gt;</code>. The default width of the\n<code>+</code> and all number characters are set to <code>0.7em</code> which is the <em>maximum width</em> of these characters in the \&quot;Inter\&quot;\nfont at <code>font-size: 11px</code>.</p>\n<p>If you use a different font-family or font-size, you should determine the maximum rendered width of <code>+</code> and all\nnumber characters, then update this value accodringly in the calculation.</p>\n"
  },
  {
    "name": "theme",
    "type": \"blue\" | \"green\" | \"red\" | \"orange\" | \"purple\" | \"gray\" | \"white\" | `#$\{string}\",
    "required": false,
    "description": ""
  },
  {
    "name": "closeable",
    "type": "boolean",
    "required": false,
    "description": ""
  }
]

_meta.events = [
  {
    "name": "close",
    "type": "[event: MouseEvent | KeyboardEvent, tag: unknown, index: number]",
    "description": ""
  },
  {
    "name": "update:modelValue",
    "type": "[tags: unknown[]]",
    "description": ""
  }
]

_meta.slots = [
  {
    "name": "tag",
    "type": "{ tag: unknown; index: number; visible?: boolean | undefined; forwardRef?: ((element: HTMLElement, index: number) => void) | undefined; }",
    "description": ""
  },
  {
    "name": "counter-tag",
    "type": "{ remainingCount: number; counterTagSize: TagListCounterTagSizeFn; }",
    "description": ""
  }
]

```

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

### Default Segmented Control Example (Vue)

Source: https://design.holistics.dev/components/segmented-control

Demonstrates the basic implementation of the HSegmentedControl component with customizable items, including labels, icons, values, and tooltips. It uses Vue's Composition API with `ref` for managing the selected value.

```vue
<script setup lang="ts">
import { HSegmentedControl, SegmentedControlItem } from '@holistics/design-system'
import { ref } from 'vue'

const items: SegmentedControlItem<number>[] = [
  {
    label: 'Label 1',
    icon: 'list-ul',
    value: 1,
    class: 'ci-item-1 ci-test-test',
  },
  {
    label: 'Label 2',
    icon: 'address-card',
    value: 2,
    tooltip: 'example tooltip',
  },
  {
    label: 'Label 3',
    icon: 'comment',
    value: 3,
    tooltip: {
      content: 'With shortcut',
      shortcuts: ['Ctrl + x'],
    },
  },
]

const value = ref(items[0].value)
</script>

<template>
  <HSegmentedControl
    v-model="value"
    :items="items"
  />
</template>

```

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

### Vue Radio Button: Default Example

Source: https://design.holistics.dev/components/radio

Demonstrates the default usage of the HRadio component in Vue.js. It shows how to bind a model value and iterate over options to render radio buttons. Dependencies include 'vue' and '@holistics/design-system'.

```vue
<script setup lang="ts">
import { HRadio } from '@holistics/design-system'
import { ref } from 'vue'

const model = ref()

const values = ['Option 1', 'Option 2']

</script>

<template>
  <div class="w-32">
    <div>Result: {{ model }}</div>
    <HRadio
      v-for="value in values"
      :key="value"
      v-model="model"
      :value="value"
    >
      {{ value }}
    </HRadio>
  </div>
</template>

```

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

### Default Avatar Group Setup (Vue)

Source: https://design.holistics.dev/components/avatar_group

Demonstrates the basic implementation of the HAvatarGroup component. It requires an array of avatar information, including image URLs, names, or initials, and a size prop. This example shows how to import and use the component with sample avatar data.

```vue
<script setup lang="ts">
import { HAvatarGroup } from '@holistics/design-system'
</script>

<template>
  <HAvatarGroup
    size="xl"
    :avatars="[
      { image: 'https://avatars.slack-edge.com/2023-12-12/6334464122773_2329a6293a6184549150_72.png' },
      { name: 'Design System' },
      { initials: 'H' }
    ]"
  />
</template>

```

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

### Vue Pagination Component - Default Usage

Source: https://design.holistics.dev/components/pagination

A Vue.js 3 script setup example demonstrating the default usage of the HPagination component. It shows how to import the component, manage the current page state using `ref`, and bind it to the pagination component with a total of 100 pages.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HPagination } from '@holistics/design-system'

const page = ref(1)
</script>

<template>
  <HPagination
    v-model="page"
    :pages="100"
  />
</template>

```

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

### Floating Component Props

Source: https://design.holistics.dev/components/popover-onboarding

Configuration options for the Floating component.

```APIDOC
## Props

### `popperSafeAreas` (boolean)

**Description:** By default, `PopperSafeAreas` provided by the parent (if exists) will override any Hover Provider. Setting this to `true` will force Hover Provider to override the parent instead.

### `floatingTeleportTo` (string | RendererElement | null)

**Description:** Specify target container. Can either be a selector or an actual element. See {@link https://vuejs.org/api/built-in-components.html#teleport}.

### `floatingTeleportDisabled` (boolean)

**Description:** When `true`, the content will remain in its original location instead of moved into the target container. Can be changed dynamically. See {@link https://vuejs.org/api/built-in-components.html#teleport}.

### `floatingTeleportDefer` (boolean)

**Description:** When `true`, the Teleport will defer until other parts of the application have been mounted before resolving its target. (3.5+). See {@link https://vuejs.org/api/built-in-components.html#teleport}.

### `floatingClass` (HTMLAttributeClass)

**Description:** HTML `class` applied to the Floating element.

### `floatingStyle` (StyleValue)

**Description:** HTML `style` applied to the Floating element.

### `contentAsChild` (boolean)

**Description:** `asChild` prop but applied for the Content element (i.e. the direct element inside the inner Floating element).
`asChild` prop: Change the default rendered element for the one passed as a child, merging their props and behavior. If there are multiple elements/components passed, only the first valid one will have the props.

### `title` (string)

**Description:** (No description provided)

### `description` (string)

**Description:** (No description provided)

### `leftButton` (string | ButtonPropsPreTyped)

**Description:** (No description provided)

### `rightButton` (string | ButtonPropsPreTyped)

**Description:** (No description provided)

### `stepText` (string)

**Description:** (No description provided)
```

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

### Floating Component Exposed Methods

Source: https://design.holistics.dev/components/popover-onboarding

Methods exposed by the Floating component.

```APIDOC
## Exposed

### `popperRef` ({ $: ComponentInternalInstance; $data: {}; $props: { readonly open?: boolean | undefined; readonly trigger: PopperTrigger; readonly delay?: number | null | undefined; ... 45 more ...; readonly onAutoFocusOnUnmount?: ((event: CustomEvent<...>) => any) | undefined; } & VNodeProps & AllowedComponentProps & ComponentCu... })

**Description:** (No description provided)
```

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

### Vue HTree Component Basic Example

Source: https://design.holistics.dev/components/tree

This Vue.js component demonstrates the basic usage of the HTree component. It includes functionality for context menus, node expansion/collapse, and drag-and-drop. Dependencies include Vue.js and the @holistics/design-system library. The component takes an array of TreeNodeBase objects and expandedKeys as input.

```vue
<script setup lang="ts">
import { type Ref, ref } from 'vue'
import { HTree } from '@holistics/design-system'
import type {
  TreeNodeBase,
  TreeContextMenuOptions,
  TreeNodeKey,
  DropdownOption,
} from '@holistics/design-system'
import { NODES } from './nodes'

const nodes = ref(NODES()) as Ref<TreeNodeBase[]>
const expandedKeys = ref<TreeNodeKey[]>([])

const contextMenuOptions: TreeContextMenuOptions<TreeNodeBase> = (node) => {
  const expandedIndex = expandedKeys.value.indexOf(node.key)

  if (node.children)
    return [
      expandedIndex === -1 && {
        key: 'Expand',
        label: 'Expand',
        icons: 'expand',
        action: () => { expandedKeys.value.push(node.key); node.icon = 'folder-open' },
      },
      expandedIndex !== -1 && {
        key: 'Collapse',
        label: 'Collapse',
        icons: 'collapse',
        action: () => { expandedKeys.value.splice(expandedIndex, 1); node.icon = 'folder-solid' },
      },

      {
        key: 'Edit',
        label: 'Edit',
        icons: 'edit',
        action: () => { alert(`Edit ${node.label}`) },
      },
      {
        key: 'Remove',
        label: 'Remove',
        icons: 'delete',
        class: 'text-red-500',
        action: () => { alert(`ARE YOU SURE? DELETING ${node.label}...!`)
      },
    ].filter(Boolean) as DropdownOption[]

  return [
    {
      key: 'Edit',
      label: 'Edit',
      icons: 'edit',
      action: () => { alert(`Edit ${node.label}`) },
    },
    {
      key: 'Remove',
      label: 'Remove',
      icons: 'delete',
      class: 'text-red-500',
      action: () => { alert(`ARE YOU SURE? DELETING ${node.label}...!`)
    },
  ]
}
</script>

<template>
  <HTree
    v-model:nodes="nodes"
    v-model:expanded-keys="expandedKeys"
    show-line
    click-mode="expand"
    multiple
    checkable
    check-cascade
    draggable
    :context-menu-options
    class="w-full rounded border sm:w-80"
    @expanded-keys-change="(node, action) => {
      if (action === 'expand') {
        node.icon = 'folder-open'
      } else {
        node.icon = 'folder-solid'
      }
    }"
  />
</template>

```

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

### Vue PopoverOnboarding Component for Onboarding

Source: https://design.holistics.dev/components/popover-onboarding

Implements an onboarding popover using Vue.js and Holistics Design System components (HIcon, HPopoverOnboarding). It displays a notification with a title, description, and an image, typically used to guide users through new features or changes. Dependencies include '@holistics/design-system'.

```vue
<script setup lang="ts">
import { HIcon, HPopoverOnboarding } from '@holistics/design-system'
</script>

<template>
  <div class="relative flex items-center text-xs">
    <HIcon name="canvas" />
    <span class="ml-1">Canvas Dashboard</span>

    <HPopoverOnboarding
      title="Date Drill has been moved to Control"
      description="Allowing you more control over it. Also, can persist on data export!"
      class="absolute -right-3 -top-3"
    >
      <div class="relative size-3 cursor-pointer rounded-full bg-blue-600">
        <div class="absolute inset-0 animate-ping rounded-full bg-blue-600" />
      </div>

      <template #content>
        <img
          src="https://cdn.holistics.io/assets/date-drill-update.gif"
          class="min-h-32"
        >
      </template>
    </HPopoverOnboarding>
  </div>
</template>

```

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

### Shortcut Component API

Source: https://design.holistics.dev/components/shortcut

API documentation for the Shortcut component, detailing its available props and slots.

```APIDOC
## Shortcut Component

### Description

Displays a keyboard shortcut. This component acts as a pass-through for `<kbd>` elements, meaning most standard HTML attributes and events will be directly applied.

### Method

N/A (Component)

### Endpoint

N/A (Component)

### Parameters

#### Props

- **outline** (boolean) - Optional - If set to true, the shortcut will have an outline style.
- **theme** ("light" | "dark") - Optional - Specifies the theme of the shortcut. Defaults to "light".

#### Slots

- **default** ({}) - The content of the slot is the text displayed as the shortcut (e.g., 'Esc').

### Request Example

```vue
<script setup lang="ts">
import { HShortcut } from '@holistics/design-system'
</script>

<template>
  <HShortcut>
    Esc
  </HShortcut>
</template>
```

### Response

#### Success Response (200)

N/A (Component)

#### Response Example

N/A (Component)
```

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

### Vue Tree Component - Generic Types Example

Source: https://design.holistics.dev/components/tree

Illustrates how to use generic types with the Tree component to provide type safety for node objects. This example defines a custom node type and demonstrates its usage with props and events.

```vue
<script setup lang="ts">
import { ref, type Ref } from 'vue'
import { HTree, type TreeNode } from '@holistics/design-system'

interface MyTreeNode extends TreeNode<MyTreeNode> {
//        ^ Your node                 ^ `children` of your node
  canDelete?: boolean
}

const nodes = ref([]) as Ref<MyTreeNode[]>
</script>

<template>
  <HTree
    v-model:nodes="nodes"
    :sort="(nodeA, nodeB) => {
      // `nodeA` & `nodeB` will have type `MyTreeNode`
    }"
    @node-load="(node) => {
      // `node` will have type `MyTreeNode`
      if (node.canDelete) {
        // ...
      }
    }"
  />
</template>
```

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

### Dismissible Banner Example in Vue.js

Source: https://design.holistics.dev/components/banner

Shows how to create dismissible HBanner components in Vue.js. This example dynamically adds banners when buttons are clicked and removes them when the dismiss event is triggered. It manages the state of multiple banners using `ref`.

```vue
<script setup lang="ts">
import {
  BANNER_TYPES, type BannerType, HBanner, HButton, type ButtonType,
} from '@holistics/design-system'
import { ref } from 'vue'

let id = 0

const baseBanners = BANNER_TYPES.map((type) => ({
  id: id++,
  type,
  title: type.toUpperCase(),
}))

const alerts = ref(baseBanners.slice())

function getButtonType (type: BannerType): ButtonType {
  switch (type) {
    case 'info': return 'outline-highlight'
    case 'neutral': return 'secondary-default'
    default: return `outline-${type}`
  }
}
function addBanner (type: BannerType) {
  alerts.value.push({
    ...baseBanners.find(((al) => al.type === type))!,
    id: id++,
  })
}

function onDismiss (i: number) {
  alerts.value.splice(i, 1)
}
</script>

<template>
  <div class="grid grid-cols-5 gap-x-4 gap-y-2">
    <HButton
      v-for="type in BANNER_TYPES"
      :key="type"
      :type="getButtonType(type)"
      icon="add"
      @click="addBanner(type)"
    >
      {{ type.toUpperCase() }}
    </HButton>
  </div>

  <div
    v-if="alerts.length"
    class="mt-8 space-y-2"
  >
    <HBanner
      v-for="(al, i) in alerts"
      :key="al.id"
      :type="al.type"
      :title="al.title"
      dismissible
      class="w-[32rem]"
      @dismiss="onDismiss(i)"
    >
      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    </HBanner>
  </div>
</template>

```

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

### Basic Switch Component Usage (Vue)

Source: https://design.holistics.dev/components/switch

Demonstrates the basic implementation of the HSwitch component from the @holistics/design-system library. It shows how to bind the switch state using v-model and includes an example of a disabled switch. Requires Vue 3 and the design system library.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HSwitch } from '@holistics/design-system'

const isOn = ref(false)
</script>

<template>
  <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
    <HSwitch v-model="isOn" />

    <HSwitch
      v-model="isOn"
      disabled
    />
  </div>
</template>

```

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

### HPopper Component API

Source: https://design.holistics.dev/components/popover-onboarding

This section details the props available for the HPopper component. All props are optional and affect the positioning and behavior of the floating element.

```APIDOC
## HPopper Component API

### Description
The HPopper component allows for the creation of floating UI elements with customizable behavior and positioning. Props listed below control various aspects of its functionality, including its open state, anchor, placement, and collision handling. Any props not explicitly defined here will be passed through to the underlying element.

### Props

#### `open` (boolean) - Optional
The opening state of the Floating element.

#### `disabled` (boolean) - Optional
When `true`, disable `Popper` functionalities entirely.

#### `anchor` (PopperAnchorRect | PopperAnchorElement) - Optional
Anchor element. Can be an object with coordinates or a virtual element.
Refer to: https://floating-ui.com/docs/virtual-elements

#### `safeAreaDuration` (number) - Optional
Duration (ms) of the safe area to exist before closing.

#### `disableOutsidePointerEvents` (boolean) - Optional
When `true`, only the top layer with `disableOutsidePointerEvents = true` has `pointer-events: auto`, all lower layers will have `pointer-events: none`. This can be used as a way to force all lower layers to not emit `@pointer-down-outside` while this layer is rendered.

#### `strategy` (Strategy) - Optional
The type of CSS `position` property to use. This could affect the positioning computation of the Floating element.
Refer to: https://floating-ui.com/docs/computeposition#strategy

#### `disableTransform` (boolean) - Optional
By default, the Floating element is positioned using `transform`. This is the most performant way to position elements. However, `transform` will create a new stacking context which could be problematic in some cases. For example, if there is a `position: fixed` element inside the Floating element that expects to be calculated against the viewport, `transform` positioning will place that element incorrectly, hence need to be disabled.
Refer to: https://floating-ui.com/docs/vue#disabling-transform

#### `placement` (Placement) - Optional
The placement of the Floating element relative to the Anchor element.
Refer to: https://floating-ui.com/docs/computeposition#placement

#### `distance` (number) - Optional, Default: 2
The distance between the Floating element and the Anchor element (applied on the axis that runs along the *side* of the Floating element).
Refer to: https://floating-ui.com/docs/offset#mainaxis

#### `skidding` (number) - Optional
The skidding between the Floating element and the Anchor element (applied on the axis that runs along the *alignment* of the Floating element).
Refer to: https://floating-ui.com/docs/offset#crossaxis

#### `allowCollisions` (boolean) - Optional
Whether to allow the Floating element to collide with the boundary.

#### `collisionBoundary` (Boundary) - Optional
The clipping element(s) or area that collision will be checked relative to.
Refer to: https://floating-ui.com/docs/detectOverflow#boundary

#### `collisionPadding` (Padding) - Optional
The virtual padding around the boundary to check for collision.
Refer to: https://floating-ui.com/docs/detectOverflow#padding

#### `noShift` (boolean) - Optional
When `true`, the Floating element won't be shifted if collisions occur.
Refer to: https://floating-ui.com/docs/shift

#### `noFlip` (boolean) - Optional
When `true`, the placement of the Floating element won't change if collisions occur.
Refer to: https://floating-ui.com/docs/flip

#### `prioritizePlacement` (string[]) - Optional
An array of placements to try in order when `noFlip` is false. This allows for more control over fallback placements.

```

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

### Adding a New Icon

Source: https://design.holistics.dev/base-elements/icon

Step-by-step guide on how to add a new SVG icon to the design system.

```APIDOC
## Add New Icon

### Description
Instructions for adding new SVG icons to the Holistics Design System.

### Steps
1.  **Copy SVG:** Place the SVG file in the `./src/icons` directory. The icon name is derived from the file name (e.g., `delete.svg` becomes `delete`, `ai/blink.svg` becomes `ai/blink`).
2.  **Set Fill Color:** For single-color icons, set the `fill` attribute to `currentColor` in the SVG.
3.  **Generate Icon Map:** Run `node ./generateIconMap.cjs`.
4.  **Bump Version:** Use `pnpm changeset` to bump the package version (recommended: `patch` for icon changes).
```

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

### Accordion with Pill - Vue

Source: https://design.holistics.dev/components/accordion

Shows how to add a 'pill' to the Accordion header for additional actions or information. This example uses the 'pill-icon' and 'pill-label' props.

```vue
<script setup lang="ts">
import { HAccordion } from '@holistics/design-system'
</script>

<template>
  <HAccordion
    label="Label"
    pill-icon="share-alt"
    pill-label="Share"
    class="w-[32rem]"
  >
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.  Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  </HAccordion>
</template>

```

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

### Accordion with Icons - Vue

Source: https://design.holistics.dev/components/accordion

Demonstrates how to add icons to the Accordion header for visual cues. This example uses 'icon' for the left icon and 'icon-right' for the right icon.

```vue
<script setup lang="ts">
import { HAccordion } from '@holistics/design-system'
</script>

<template>
  <HAccordion
    label="Label"
    icon="data-set"
    icon-right="info"
    class="w-[32rem]"
  >
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.  Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
  </HAccordion>
</template>

```

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

### Disabled Segmented Control Example (Vue)

Source: https://design.holistics.dev/components/segmented-control

Shows how to disable the HSegmentedControl component by passing the `disabled` prop. This prevents user interaction with the segmented control, making it read-only.

```vue
<script setup lang="ts">
import { HSegmentedControl, SegmentedControlItem } from '@holistics/design-system'
import { ref } from 'vue'

const items: SegmentedControlItem<number>[] = [
  {
    label: 'Label 1',
    icon: 'list-ul',
    value: 1,
    class: 'ci-item-1 ci-test-test',
  },
  {
    label: 'Label 2',
    icon: 'address-card',
    value: 2,
    tooltip: 'example tooltip',
  },
  {
    label: 'Label 3',
    icon: 'comment',
    value: 3,
    tooltip: {
      content: 'With shortcut',
      shortcuts: ['Ctrl + x'],
    },
  },
]

const value = ref(items[0].value)
</script>

<template>
  <HSegmentedControl
    v-model="value"
    :items="items"
    disabled
  />
</template>

```

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

### Basic HSelect Component Usage (Vue)

Source: https://design.holistics.dev/components/select

Demonstrates the basic implementation of the HSelect component in Vue. It requires importing HSelect and SelectOption from '@holistics/design-system'. The component takes an array of options and a model value for the selected option, returning the chosen option's value.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HSelect, type SelectOption } from '@holistics/design-system'

const options = [
  { value: 1, label: 'Option 1' },
  { value: 2, label: 'Option 2' },
  { value: 3, label: 'Option 3', disabled: true },
  { value: 4, label: 'Option 4' },
] as const satisfies SelectOption[]

const value = ref<typeof options[number]['value']>()
</script>

<template>
  <HSelect
    v-model="value"
    :options="options"
    class="w-80"
  />
</template>

```

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

### HDropdown Component: Options with Divider (Vue)

Source: https://design.holistics.dev/components/dropdown

This example shows how to include a visual divider within the HDropdown options. A 'divider' type option is added to the list, separating subsequent items.

```vue
<script setup lang="ts">
import { type DropdownOption, HDropdown, HButton } from '@holistics/design-system'

const options = [
  { key: '1', label: 'First item' },
  { key: '2', label: 'Second item' },
  { type: 'divider' },
  { key: '3', label: 'Third item' },
] as const satisfies DropdownOption[]
</script>

<template>
  <HDropdown :options="options">
    <HButton type="primary-highlight">
      Divider
    </HButton>
  </HDropdown>
</template>

```

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

### Configure HSelect with Various Option Types (Vue)

Source: https://design.holistics.dev/components/select

Demonstrates configuring the HSelect component with a variety of option types. This includes options with sticky positioning, tooltips, icons, descriptions, disabled states, and nested children. The example uses Vue's Composition API and TypeScript.

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { HSelect, type SelectOption, type SelectValue } from '@holistics/design-system'

const options = [
  {
    stickyTop: true, value: 101, label: 'Top Option 1', tooltip: 'Lorem ipsum donor',
  },
  {
    stickyTop: true,
    value: 102,
    label: 'Top Option 2',
    tooltip: 'Some tips at a group',
    children: [
      { stickyTop: true, value: '102.1', label: 'Top Option 2.1' },
      {
        stickyTop: true, value: '102.2', label: 'Inner-Bell', icon: 'bell', action: () => { console.log('Inner-bell logged!') },
      },
    ],
    initialExpanded: true,
  },
  {
    stickyTop: true,
    value: 103,
    label: 'Top Action Option',
    icon: 'function',
    action: (option) => { alert(`You clicked an option with value: "${option.value}" and label: "${option.label}"`) },
    tooltip: { content: '<em>I can be HTML, too!</em>', html: true },
  },
  { value: 1, label: 'Option 1', tooltip: 'I can be anywhere!' },
  { value: 2, label: 'Option 2 (with icon)', icon: 'favorite' },
  { value: 3, label: 'Option 3', description: 'Option with description' },
  {
    value: 4, label: 'Option 4 has a VERY Very very long label', icon: 'data-set', description: 'Option with description & icon, and a very long long long long long long long long long long long description',
  },
  {
    value: 5, label: 'Option 5 (disabled)', disabled: true, tooltip: 'Disabled option only shows tooltip on hovering (not keyboad)!',
  },
  {
    value: 6,
    label: 'Option 6',
    children: [
      { label: 'Option a.1', value: '6.1', icon: 'type/number' },
      { label: 'Option b.2', value: '6.2', icon: 'type/string' },
      {
        label: 'Option x.3',
        value: '6.3',
        children: [
          { label: 'Option d.3.1', value: '6.3.1' },
          { label: 'Option e.3.2', value: '6.3.2' },
          {
            label: 'Option x.3.3',
            value: '6.3.3',
            children: [
              { label: 'Option g.3.3.1', value: '6.3.3.1' },
              { label: 'Option h.3.3.2', value: '6.3.3.2' },
              { label: 'Option i.3.3.3', value: '6.3.3.3' },
              {
                label: 'Option x.3.3.4',
                value: '6.3.3.4',
                children: [
                  { label: 'Option k.3.3.4.1', value: '6.3.3.4.1' },
                  { label: 'Option l.3.3.4.2', value: '6.3.3.4.2' },
                  { label: 'Option 6.3.3.4.3', value: '6.3.3.4.3' },
                  { label: 'Option m.3.3.4.4', value: '6.3.3.4.4' },
                ],
              },
              { label: 'Option j.3.3.3', value: '6.3.3.5' },
            ],
            initialExpanded: true,
          },
          { label: 'Option f.3.4', value: '6.3.4' },
        ],
      },
      { label: 'Option c.4', value: '6.4' },
    ],
  },
  { value: 7, label: 'Option 7', icon: 'user' },
  { value: 8, label: 'Option 8' },
  { value: 9, label: 'Option 9' },
  { value: 10, label: 'Option 10' },
  { value: null, label: 'Option null' },
  { stickyBottom: true, value: 901, label: 'Bottom Option 1' },
  {
    stickyBottom: true,
    value: 902,
    label: 'Bottom Option 2',
    children: [
      { stickyBottom: true, value: '901.1', label: 'Bottom Option 2.1' },
      { stickyBottom: true, value: '901.2', label: 'Bottom Option 2.2' },
    ],
  },
  {
    stickyBottom: true,
    value: 903,
    label: 'Async Refresh (done after 2s)',
    icon: 'refresh',
    action: async () => {
      await new Promise((res) => { setTimeout(res, 2000) })
      alert('Done refreshing!')
    },
  },
] as const satisfies SelectOption[]

const value = ref<SelectValue>()
</script>

<template>
  <HSelect
    v-model="value"
    :options="options"
    class="w-80"
  />
</template>

```

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

### Vue Tooltip: With Shortcuts

Source: https://design.holistics.dev/components/tooltip

Illustrates how to configure the HTooltip component in Vue.js to display shortcut keys. This example shows a tooltip with the content 'Lorem Ipsum' and shortcuts 'Alt' and 'E', triggered by hovering over an info icon. It depends on HIcon and HTooltip from '@holistics/design-system'.

```vue
<script setup lang="ts">
import { HIcon, HTooltip } from '@holistics/design-system'
</script>

<template>
  <HTooltip
    content="Lorem Ipsum"
    :shortcuts="['Alt', 'E']"
  >
    <HIcon
      size="lg"
      name="info"
    />
  </HTooltip>
</template>

```