From 039f79b209d9f10ee7561282a2eb63c4de5c9b9b Mon Sep 17 00:00:00 2001
From: ben <benjamin.devine@gmail.com>
Date: Thu, 18 Dec 2025 07:25:19 -0800
Subject: [PATCH] feat(Combobox,Listbox,Switcher): add generic type support for
 options

---
 src/components/Combobox.vue               | 467 ++++++++++------------
 src/components/Listbox.vue                | 164 ++++----
 src/components/Option.vue                 |  60 ++-
 src/components/OptionGroup.vue            |  65 ++-
 src/components/SelectableOptionGroup.vue  |  83 ++--
 src/components/Switcher.vue               |  85 ++--
 src/components/__tests__/Combobox.test.ts |  50 ++-
 src/components/internal/OptionsPanel.vue  | 106 +++--
 src/index.ts                              |   2 +
 src/types/index.ts                        |  11 +
 src/types/selection.ts                    | 115 ++++++
 11 files changed, 615 insertions(+), 593 deletions(-)
 create mode 100644 src/types/index.ts
 create mode 100644 src/types/selection.ts

diff --git a/src/components/Combobox.vue b/src/components/Combobox.vue
index 49ca912..968531f 100644
--- a/src/components/Combobox.vue
+++ b/src/components/Combobox.vue
@@ -1,27 +1,28 @@
-<script lang="ts">
-import { defineComponent, PropType, ref, computed } from 'vue'
+<script
+  setup
+  lang="ts"
+  generic="
+    T extends BaseOption = ExtendedOption,
+    Options extends T[] | OptionGroup<string, T>[] = T[] | OptionGroup<string, T>[],
+    ModelValue extends string | string[] = string | string[]
+  ">
+import { ref, computed, useAttrs } from 'vue'
 import { Combobox, ComboboxButton, ComboboxInput } from '@headlessui/vue'
-
-import type { Option } from './Option.vue'
-import { OptionGroup, areOptionsGrouped } from './OptionGroup.vue'
-import { GROUP_VALUE_PREFIX } from './SelectableOptionGroup.vue'
 import ATag from './Tag.vue'
 import AColorCircle from './ColorCircle.vue'
-import OptionsPanel, { Direction } from './internal/OptionsPanel.vue'
+import OptionsPanel, { type Direction } from './internal/OptionsPanel.vue'
 import FloatingArrow from './internal/FloatingArrow.vue'
+import {
+  type BaseOption,
+  type ExtendedOption,
+  type OptionGroup,
+  areOptionsGrouped,
+  GROUP_VALUE_PREFIX
+} from '../types/selection'
+import { type Color } from '../colors'
 
-export default defineComponent({
-  name: 'ACombobox',
-  components: {
-    Combobox,
-    ComboboxButton,
-    ComboboxInput,
-    OptionsPanel,
-    ATag,
-    FloatingArrow,
-    AColorCircle
-  },
-  props: {
+const props = withDefaults(
+  defineProps<{
     /**
      * An option is at the minimum a `{ value: string, label: string }` object.
      * This prop is used to display the list of combobox options,
@@ -29,312 +30,267 @@ export default defineComponent({
      *
      * You can also provide a grouped structure of options: `[{ title: string, options: Option[] }]`
      */
-    options: {
-      type: Array as PropType<Option[] | OptionGroup[]>,
-      required: true
-    },
+    options: Options
     /**
      * a placeholder string to be displayed when no value is currently selected.
      */
-    placeholder: {
-      type: String,
-      default: 'Select value'
-    },
+    placeholder?: string
     /**
      * the size of the combobox component
      * same as text inputs and listboxes
      *
      * `'sm' | 'md'`
      */
-    size: {
-      type: String as PropType<'sm' | 'md'>,
-      default: 'sm'
-    },
+    size?: 'sm' | 'md'
     /**
      * visual variant, same as text inputs and listboxes
      * how the combobox button is displayed when not focused
      *
      * `'subtle' | 'default'`
      */
-    variant: {
-      type: String as PropType<'subtle' | 'default'>,
-      default: 'default'
-    },
+    variant?: 'subtle' | 'default'
     /**
      * the prop modelValue is required to use [v-model](https://vuejs.org/guide/components/events.html#usage-with-v-model) with a component.
      * When a single option can be selected, modelValue must be a string.
      * When multiple options can be selected, modelValue must be a list of strings.
      */
-    modelValue: {
-      type: [String, Array] as PropType<string | string[]>,
-      required: true
-    },
+    modelValue: ModelValue
     /**
      * direction in which the dropdown is opening.
      *
      * `'up' | 'down'`
      */
-    direction: {
-      type: String as PropType<Direction>,
-      default: 'down'
-    },
+    direction?: Direction
     /**
      * extra classes to style the combobox options panel
      * useful for setting the panel height
      */
-    panelClasses: {
-      type: String,
-      default: ''
-    },
+    panelClasses?: string
     /**
      * an optional custom filtering function to filter the results based on the user input
      * the default filtering function shows an option if its label property includes the user query
      */
-    filterCallback: {
-      type: Function as PropType<(option: Option, query: string) => boolean>,
-      default: undefined
-    },
+    filterCallback?: (option: T, query: string) => boolean
     /**
      * the options panel can be rendered inline instead of the absolutely positioned dropdown
      */
-    inline: {
-      type: Boolean,
-      default: false
-    },
+    inline?: boolean
     /**
      * allow the options panel to be rendered outside the flow of a container that has content that needs scrolling
      */
-    escapeOverflow: {
-      type: Boolean,
-      default: false
-    },
+    escapeOverflow?: boolean
     /**
      * Maximum number of tags to display in multi-select mode.
      * When exceeded, remaining selections are collapsed into a "+N more" indicator.
      * Set to `undefined` (default) to display all tags.
      */
-    maxTags: {
-      type: Number as PropType<number | undefined>,
-      default: undefined
-    },
+    maxTags?: number
     /**
      * Custom function to generate the collapsed tags label.
      * Receives the count of hidden tags.
      * Default: `(count) => \`+${count} more\``
      */
-    collapsedTagsLabel: {
-      type: Function as PropType<(count: number) => string>,
-      default: (count: number) => `+${count} more`
-    },
+    collapsedTagsLabel?: (count: number) => string
     /**
      * When true and the combobox is in multi-select mode with grouped options,
      * displays a CheckboxSelectAll in each group header to select/clear all
      * options in that group.
      */
-    selectableGroups: {
-      type: Boolean,
-      default: false
-    }
-  },
-  emits: ['update:modelValue', 'update:query'],
-  setup(props, { emit }) {
-    const isMultiSelect = (modelValue: string[] | string): modelValue is string[] => {
-      return Array.isArray(modelValue)
-    }
-    const container = ref()
-    const query = ref('')
+    selectableGroups?: boolean
+  }>(),
+  {
+    placeholder: 'Select value',
+    size: 'sm',
+    variant: 'default',
+    direction: 'down',
+    panelClasses: '',
+    inline: false,
+    escapeOverflow: false,
+    collapsedTagsLabel: (count: number) => `+${count} more`,
+    selectableGroups: false
+  }
+)
 
-    const inputRef = ref()
+const emit = defineEmits<{
+  'update:modelValue': [value: ModelValue]
+  'update:query': [query: string]
+}>()
 
-    const comboboxButton = ref()
-    const optionsPanelWidth = computed(() => comboboxButton.value?.el.offsetWidth)
+const attrs = useAttrs()
 
-    const selectInputValue = () => {
-      if (inputRef.value) {
-        const element = inputRef.value.$el as HTMLInputElement
-        element.select()
-      }
-    }
+const isMultiSelect = (modelValue: string[] | string): modelValue is string[] => {
+  return Array.isArray(modelValue)
+}
 
-    // toggle all options in a group (select all if not all selected, otherwise clear)
-    const handleGroupToggle = (options: Option[]) => {
-      if (!isMultiSelect(props.modelValue)) return
+const container = ref()
+const query = ref('')
+const inputRef = ref()
+const comboboxButton = ref()
+const optionsPanelWidth = computed(() => comboboxButton.value?.el.offsetWidth)
 
-      const values = options.filter(o => !o.disabled).map(o => o.value)
-      const currentSet = new Set(props.modelValue)
-      const allSelected = values.every(v => currentSet.has(v))
-
-      const newSelection = allSelected
-        ? props.modelValue.filter(v => !values.includes(v))
-        : [...new Set([...props.modelValue, ...values])]
-
-      emit('update:modelValue', newSelection)
-      clearQuery()
-    }
+const selectInputValue = () => {
+  if (inputRef.value) {
+    const element = inputRef.value.$el as HTMLInputElement
+    element.select()
+  }
+}
 
-    const model = computed({
-      get: () => {
-        return props.modelValue
-      },
-      set: value => {
-        // handle keyboard selection of group headers (which have __group__ prefix)
-        if (isMultiSelect(value) && areOptionsGrouped(props.options)) {
-          const groupValue = value.find(v => v.startsWith(GROUP_VALUE_PREFIX))
-          if (groupValue) {
-            // extract group title and toggle its options
-            const title = groupValue.slice(GROUP_VALUE_PREFIX.length)
-            const group = props.options.find(g => g.title === title)
-            if (group) {
-              handleGroupToggle(group.options)
-            }
-            return
-          }
-        }
+// toggle all options in a group (select all if not all selected, otherwise clear)
+const handleGroupToggle = (options: T[]) => {
+  if (!isMultiSelect(props.modelValue)) return
 
-        emit('update:modelValue', value)
-        clearQuery()
-      }
-    })
+  const values = options.filter(o => !o.disabled).map(o => String(o.value))
+  const currentSet = new Set(props.modelValue)
+  const allSelected = values.every(v => currentSet.has(v))
 
-    const flatOptions = computed(() =>
-      areOptionsGrouped(props.options)
-        ? props.options.map(({ options }) => options).flat()
-        : props.options
-    )
+  const newSelection = allSelected
+    ? props.modelValue.filter(v => !values.includes(v))
+    : [...new Set([...props.modelValue, ...values])]
 
-    const filteredOptions = computed(() => {
-      if (query.value === '') {
-        return props.options
-      } else {
-        const applyFilter = (option: Option) =>
-          props.filterCallback
-            ? props.filterCallback(option, query.value)
-            : option.label.toLowerCase().includes(query.value.toLowerCase())
+  emit('update:modelValue', newSelection as ModelValue)
+  clearQuery()
+}
 
-        if (areOptionsGrouped(props.options)) {
-          return props.options
-            .map(({ title, options }) => ({
-              title,
-              options: options.filter(applyFilter)
-            }))
-            .filter(group => group.options.length)
-        } else {
-          return props.options.filter(applyFilter)
+const model = computed({
+  get: (): ModelValue => props.modelValue,
+  set: (value: ModelValue) => {
+    // handle keyboard selection of group headers (which have __group__ prefix)
+    if (isMultiSelect(value) && areOptionsGrouped(props.options)) {
+      const groupValue = value.find(v => v.startsWith(GROUP_VALUE_PREFIX))
+      if (groupValue) {
+        // extract group title and toggle its options
+        const title = groupValue.slice(GROUP_VALUE_PREFIX.length)
+        const group = props.options.find(g => g.title === title)
+        if (group) {
+          handleGroupToggle(group.options)
         }
+        return
       }
-    })
-
-    const getOption = (value: string) => {
-      return flatOptions.value.find(option => option.value === value)
     }
 
-    const displayValue = (modelValue: string | string[]) => {
-      return isMultiSelect(modelValue)
-        ? query.value
-        : getOption(modelValue)?.label || query.value || modelValue
-    }
+    emit('update:modelValue', value)
+    clearQuery()
+  }
+})
 
-    const placeholderString = computed(() =>
-      isMultiSelect(model.value) && model.value.length && !props.inline ? '' : props.placeholder
-    )
+const flatOptions = computed((): T[] =>
+  areOptionsGrouped(props.options)
+    ? props.options.map(({ options }) => options).flat()
+    : (props.options as T[])
+)
 
-    const inputSize = computed(() => {
-      const displayValueSize = displayValue(model.value).length
-      const placeholderSize = placeholderString.value.length
-      return displayValueSize || placeholderSize
-    })
+const filteredOptions = computed((): Options => {
+  if (query.value === '') {
+    return props.options
+  } else {
+    const applyFilter = (option: T) =>
+      props.filterCallback
+        ? props.filterCallback(option, query.value)
+        : option.label.toLowerCase().includes(query.value.toLowerCase())
 
-    const updateQuery = (value: string) => {
-      if (model.value && !value && !isMultiSelect(model.value)) {
-        model.value = ''
-      }
-      if (query.value !== value) {
-        query.value = value || ''
-        emit('update:query', query.value)
-      }
+    if (areOptionsGrouped(props.options)) {
+      return props.options
+        .map(({ title, options }) => ({
+          title,
+          options: options.filter(applyFilter)
+        }))
+        .filter(group => group.options.length) as Options
+    } else {
+      return (props.options as T[]).filter(applyFilter) as Options
     }
+  }
+})
 
-    const clearQuery = () => {
-      query.value = ''
-      emit('update:query', query.value)
-    }
+const getOption = (value: string) => {
+  return flatOptions.value.find(option => String(option.value) === value)
+}
 
-    const removeValue = (value: string, event: Event) => {
-      event.stopPropagation()
-      if (isMultiSelect(model.value) && model.value.includes(value)) {
-        model.value = model.value.filter(item => item !== value)
-      }
-    }
+const displayValue = (modelValue: string | string[]) => {
+  return isMultiSelect(modelValue)
+    ? query.value
+    : getOption(modelValue)?.label || query.value || modelValue
+}
 
-    const singleModelValueColor = computed(() => {
-      if (!isMultiSelect(model.value)) {
-        return getOption(model.value)?.color
-      }
-      return undefined
-    })
+const placeholderString = computed(() =>
+  isMultiSelect(model.value) && model.value.length && !props.inline ? '' : props.placeholder
+)
 
-    const visibleValues = computed(() => {
-      if (!isMultiSelect(model.value)) return []
-      if (props.maxTags === undefined) return model.value
-      return model.value.slice(0, props.maxTags)
-    })
+const inputSize = computed(() => {
+  const displayValueSize = displayValue(model.value).length
+  const placeholderSize = placeholderString.value.length
+  return displayValueSize || placeholderSize
+})
 
-    const hiddenCount = computed(() => {
-      if (!isMultiSelect(model.value)) return 0
-      if (props.maxTags === undefined) return 0
-      return Math.max(0, model.value.length - props.maxTags)
-    })
+const updateQuery = (value: string) => {
+  if (model.value && !value && !isMultiSelect(model.value)) {
+    model.value = '' as ModelValue
+  }
+  if (query.value !== value) {
+    query.value = value || ''
+    emit('update:query', query.value)
+  }
+}
 
-    const showSelectableGroups = computed(
-      () =>
-        props.selectableGroups &&
-        isMultiSelect(props.modelValue) &&
-        areOptionsGrouped(props.options)
-    )
+const clearQuery = () => {
+  query.value = ''
+  emit('update:query', query.value)
+}
 
-    const handleDelete = () => {
-      if (isMultiSelect(model.value) && !query.value) {
-        model.value = model.value.slice(0, -1)
-      }
-    }
+const removeValue = (value: string, event: Event) => {
+  event.stopPropagation()
+  if (isMultiSelect(model.value) && model.value.includes(value)) {
+    model.value = model.value.filter(item => item !== value) as ModelValue
+  }
+}
 
-    const handleBlur = (event: FocusEvent) => {
-      if (!container.value?.contains(event.relatedTarget)) {
-        // clear query after some delay in order to wait for the dropdown to be hidden
-        // avoids momentary flash of dropdown menu with unfiltered options list
-        setTimeout(clearQuery, 200)
-      }
-    }
+const getOptionColor = (option: T | undefined): Color | undefined => {
+  const opt = option as (BaseOption & { color?: Color }) | undefined
+  return opt?.color
+}
 
-    return {
-      model,
-      filteredOptions,
-      query,
-      displayValue,
-      updateQuery,
-      isMultiSelect: computed(() => isMultiSelect(model.value)),
-      removeValue,
-      getOption,
-      inputSize,
-      inputRef,
-      selectInputValue,
-      singleModelValueColor,
-      placeholderString,
-      handleDelete,
-      comboboxButton,
-      optionsPanelWidth,
-      handleBlur,
-      container,
-      visibleValues,
-      hiddenCount,
-      showSelectableGroups
-    }
+const singleModelValueColor = computed(() => {
+  if (!isMultiSelect(model.value)) {
+    return getOptionColor(getOption(model.value))
   }
+  return undefined
 })
+
+const visibleValues = computed(() => {
+  if (!isMultiSelect(model.value)) return []
+  if (props.maxTags === undefined) return model.value
+  return model.value.slice(0, props.maxTags)
+})
+
+const hiddenCount = computed(() => {
+  if (!isMultiSelect(model.value)) return 0
+  if (props.maxTags === undefined) return 0
+  return Math.max(0, model.value.length - props.maxTags)
+})
+
+const showSelectableGroups = computed(
+  () =>
+    props.selectableGroups && isMultiSelect(props.modelValue) && areOptionsGrouped(props.options)
+)
+
+const handleDelete = () => {
+  if (isMultiSelect(model.value) && !query.value) {
+    model.value = model.value.slice(0, -1) as ModelValue
+  }
+}
+
+const handleBlur = (event: FocusEvent) => {
+  if (!container.value?.contains(event.relatedTarget)) {
+    // clear query after some delay in order to wait for the dropdown to be hidden
+    // avoids momentary flash of dropdown menu with unfiltered options list
+    setTimeout(clearQuery, 200)
+  }
+}
+
+const isMulti = computed(() => isMultiSelect(model.value))
 </script>
 <template>
   <div ref="container" :class="{ relative: !escapeOverflow }" @focusout="handleBlur">
-    <Combobox v-model="model" :multiple="isMultiSelect" :disabled="!!$attrs.disabled">
+    <Combobox v-model="model" :multiple="isMulti" :disabled="!!attrs.disabled">
       <!-- @slot  named `#input` slot. Requires ComboboxInput component from headless-ui to work, and optionally ComboboxButton. Slot props: `query<string>`, calculated `displayValue<string>`, and `updateQuery<(value:string)=>void>` callback to be used with text input v-model update event-->
       <slot name="input" :query="query" :display-value="displayValue" :update-query="updateQuery">
         <ComboboxButton
@@ -343,17 +299,16 @@ export default defineComponent({
           class="group a-text-input-base relative flex items-center py-0"
           :class="[
             {
-              'h-auto min-h-10 body-lg placeholder:body-lg': size === 'md' && isMultiSelect,
-              'my-px h-auto min-h-[1.875rem] body-sm placeholder:body-sm':
-                size === 'sm' && isMultiSelect,
-              'a-text-input--sm': size === 'sm' && !isMultiSelect,
-              'a-text-input--md': size === 'md' && !isMultiSelect
+              'h-auto min-h-10 body-lg placeholder:body-lg': size === 'md' && isMulti,
+              'my-px h-auto min-h-[1.875rem] body-sm placeholder:body-sm': size === 'sm' && isMulti,
+              'a-text-input--sm': size === 'sm' && !isMulti,
+              'a-text-input--md': size === 'md' && !isMulti
             },
             variant === 'subtle' ? 'a-text-input--subtle' : 'a-text-input--default',
-            $attrs.disabled
+            attrs.disabled
               ? 'a-text-input-disabled border-athens'
               : 'focus-within:a-text-input-focus hover:a-text-input-hover',
-            variant === 'subtle' && $attrs.disabled && 'border-none'
+            variant === 'subtle' && attrs.disabled && 'border-none'
           ]"
           @click="selectInputValue"
           @keydown.delete="handleDelete">
@@ -367,19 +322,19 @@ export default defineComponent({
             ]">
             <!-- @slot Named `#selected-tags` slot. Use to customize how selected values are displayed in multi-select mode. Slot props: `selectedValues` (all selected values), `visibleValues` (values to display respecting maxTags), `hiddenCount` (number of hidden selections), `getOption` (helper to get option details), `removeValue` (helper to remove a value), `disabled` (whether combobox is disabled) -->
             <slot
-              v-if="isMultiSelect && !inline"
+              v-if="isMulti && !inline"
               name="selected-tags"
               :selected-values="model"
               :visible-values="visibleValues"
               :hidden-count="hiddenCount"
               :get-option="getOption"
               :remove-value="removeValue"
-              :disabled="$attrs.disabled">
+              :disabled="attrs.disabled">
               <ATag
                 v-for="value in visibleValues"
                 :key="value"
-                :removable="!($attrs.disabled || getOption(value)?.disabled)"
-                :color="getOption(value)?.color"
+                :removable="!(attrs.disabled || getOption(value)?.disabled)"
+                :color="getOptionColor(getOption(value))"
                 @remove="removeValue(value, $event)">
                 {{ getOption(value)?.label || value }}
               </ATag>
@@ -395,15 +350,15 @@ export default defineComponent({
               ref="inputRef"
               class="truncate bg-transparent focus:focus-none disabled:a-text-input-disabled"
               :style="`width: ${inputSize + 1}ch`"
-              :display-value="value => displayValue(value as string | string[])"
+              :display-value="(value: unknown) => displayValue(value as string | string[])"
               :placeholder="placeholderString"
-              :disabled="$attrs.disabled"
+              :disabled="attrs.disabled"
               @change.stop="updateQuery($event.target.value)" />
           </div>
           <FloatingArrow
             v-if="!inline"
-            :float="variant === 'subtle' && !$attrs.disabled"
-            :class="$attrs.disabled && 'text-warsaw'" />
+            :float="variant === 'subtle' && !attrs.disabled"
+            :class="attrs.disabled && 'text-warsaw'" />
         </ComboboxButton>
       </slot>
       <OptionsPanel
@@ -412,12 +367,12 @@ export default defineComponent({
         :options="filteredOptions"
         :class="panelClasses"
         :direction="direction"
-        :multi="isMultiSelect"
+        :multi="isMulti"
         :inline="inline"
         :escape-overflow="escapeOverflow"
         :width="optionsPanelWidth"
         :selectable-groups="showSelectableGroups"
-        :selected-values="isMultiSelect ? (model as string[]) : []">
+        :selected-values="isMulti ? (model as string[]) : []">
         <template #default>
           <!-- @slot  `#default` slot. Takes `a-option` or `a-option-group` components without any wrappers. Use this slot to render options with extra styles or markup. Default value: `options` prop rendered as `a-option`s or `a-option-group`s -->
           <slot :filtered-options="filteredOptions"></slot>
diff --git a/src/components/Listbox.vue b/src/components/Listbox.vue
index e085640..52631d5 100644
--- a/src/components/Listbox.vue
+++ b/src/components/Listbox.vue
@@ -1,23 +1,26 @@
-<script lang="ts">
-import { defineComponent, PropType, ref, computed } from 'vue'
+<script
+  setup
+  lang="ts"
+  generic="
+    T extends BaseOption = ExtendedOption,
+    Options extends T[] | OptionGroup<string, T>[] = T[] | OptionGroup<string, T>[],
+    ModelValue extends string = string
+  ">
+import { ref, computed, useAttrs } from 'vue'
 import { Listbox, ListboxButton } from '@headlessui/vue'
-
-import type { Option } from './Option.vue'
-import { OptionGroup, areOptionsGrouped } from './OptionGroup.vue'
 import AColorCircle from './ColorCircle.vue'
-import OptionsPanel, { Direction } from './internal/OptionsPanel.vue'
+import OptionsPanel, { type Direction } from './internal/OptionsPanel.vue'
 import FloatingArrow from './internal/FloatingArrow.vue'
+import {
+  type BaseOption,
+  type ExtendedOption,
+  type OptionGroup,
+  areOptionsGrouped
+} from '../types/selection'
+import { type Color } from '../colors'
 
-export default defineComponent({
-  name: 'AListbox',
-  components: {
-    Listbox,
-    ListboxButton,
-    OptionsPanel,
-    FloatingArrow,
-    AColorCircle
-  },
-  props: {
+const props = withDefaults(
+  defineProps<{
     /**
      * An option is at the minimum a `{ value: string, label: string }` object.
      * This prop is used to display the list of listbox options,
@@ -25,105 +28,88 @@ export default defineComponent({
      *
      * You can also provide a grouped structure of options: `[{ title: string, options: Option[] }]`
      */
-    options: {
-      type: Array as PropType<Option[] | OptionGroup[]>,
-      required: true
-    },
+    options: Options
     /**
      * an optional placeholder can be displayed when no value is currently selected.
      */
-    placeholder: {
-      type: String,
-      default: 'Select value'
-    },
+    placeholder?: string
     /**
      * the size of the listbox component
      */
-    size: {
-      type: String as PropType<'sm' | 'md'>,
-      default: 'sm'
-    },
+    size?: 'sm' | 'md'
     /**
      * how the listbox button is displayed when not focused
      */
-    variant: {
-      type: String as PropType<'subtle' | 'default'>,
-      default: 'default'
-    },
+    variant?: 'subtle' | 'default'
     /**
      * the prop modelValue is required to use [v-model](https://vuejs.org/guide/components/events.html#usage-with-v-model) with a component.
      */
-    modelValue: {
-      type: String,
-      required: true
-    },
+    modelValue: ModelValue
     /**
      * direction in which the dropdown is opening.
      * possible values: `up`, `down`. Default is `down`
      */
-    direction: {
-      type: String as PropType<Direction>,
-      default: 'down'
-    },
+    direction?: Direction
     /**
      * extra classes to style the listbox options panel
      * useful for setting the panel height
      */
-    panelClasses: {
-      type: String,
-      default: ''
-    },
+    panelClasses?: string
     /**
      * the options panel can be rendered inline instead of the absolutely positioned dropdown
      */
-    inline: {
-      type: Boolean,
-      default: false
-    },
+    inline?: boolean
     /**
      * allow the options panel to be rendered outside the flow of a container that has content that needs scrolling
      */
-    escapeOverflow: {
-      type: Boolean,
-      default: false
-    }
-  },
-  emits: ['update:modelValue'],
-  setup() {
-    const listboxButton = ref()
-    const optionsPanelWidth = computed(() => listboxButton.value?.el.offsetWidth)
+    escapeOverflow?: boolean
+  }>(),
+  {
+    placeholder: 'Select value',
+    size: 'sm',
+    variant: 'default',
+    direction: 'down',
+    panelClasses: '',
+    inline: false,
+    escapeOverflow: false
+  }
+)
+
+const emit = defineEmits<{
+  'update:modelValue': [value: ModelValue]
+}>()
 
-    // hack together a tab-out behavior for the listbox
-    const handleTab = (event: KeyboardEvent) => {
-      if (event.key === 'Tab') {
-        const newEvent = new KeyboardEvent('keydown', { key: 'Escape' })
-        event.target?.dispatchEvent(newEvent)
-      }
-    }
+const attrs = useAttrs()
 
-    return { handleTab, listboxButton, optionsPanelWidth }
-  },
-  computed: {
-    flatOptions() {
-      return areOptionsGrouped(this.options)
-        ? this.options.map(({ options }) => options).flat()
-        : this.options
-    },
-    valueOption() {
-      return this.flatOptions.find(option => option.value === this.model)
-    },
-    valueLabel() {
-      return this.valueOption?.label || this.model
-    },
-    model: {
-      get() {
-        return this.modelValue
-      },
-      set(value: string) {
-        this.$emit('update:modelValue', value)
-      }
-    }
+const listboxButton = ref()
+const optionsPanelWidth = computed(() => listboxButton.value?.el.offsetWidth)
+
+// hack together a tab-out behavior for the listbox
+const handleTab = (event: KeyboardEvent) => {
+  if (event.key === 'Tab') {
+    const newEvent = new KeyboardEvent('keydown', { key: 'Escape' })
+    event.target?.dispatchEvent(newEvent)
   }
+}
+
+const flatOptions = computed((): T[] =>
+  areOptionsGrouped(props.options)
+    ? props.options.map(({ options }) => options).flat()
+    : (props.options as T[])
+)
+
+const model = computed({
+  get: (): ModelValue => props.modelValue,
+  set: (value: ModelValue) => emit('update:modelValue', value)
+})
+
+const valueOption = computed(() => flatOptions.value.find(option => option.value === model.value))
+
+const valueLabel = computed(() => valueOption.value?.label || model.value)
+
+const valueOptionColor = computed(() => {
+  const opt = valueOption.value as (BaseOption & { color?: Color }) | undefined
+  return opt?.color
 })
 </script>
 <template>
@@ -145,7 +131,7 @@ export default defineComponent({
           -->
           <slot name="listbox-value">
             <div v-if="model" class="truncate">
-              <AColorCircle v-if="valueOption?.color" :color="valueOption?.color" class="mr-2" />
+              <AColorCircle v-if="valueOptionColor" :color="valueOptionColor" class="mr-2" />
               <span>{{ valueLabel }}</span>
             </div>
             <span v-else class="a-text-input-placeholder">{{ placeholder }}</span>
@@ -153,8 +139,8 @@ export default defineComponent({
         </div>
         <FloatingArrow
           v-if="!inline"
-          :float="variant === 'subtle' && !$attrs.disabled"
-          :class="{ 'text-warsaw': $attrs.disabled }" />
+          :float="variant === 'subtle' && !attrs.disabled"
+          :class="{ 'text-warsaw': attrs.disabled }" />
       </slot>
     </ListboxButton>
     <OptionsPanel
diff --git a/src/components/Option.vue b/src/components/Option.vue
index 592f26c..b3f0fec 100644
--- a/src/components/Option.vue
+++ b/src/components/Option.vue
@@ -1,30 +1,23 @@
 <script lang="ts">
-import { computed, defineComponent, PropType } from 'vue'
+export type { Option, BaseOption, ExtendedOption, OptionValue } from '../types/selection'
+</script>
+
+<script setup lang="ts" generic="T extends BaseOption = ExtendedOption">
+import { computed } from 'vue'
 import { ListboxOption, ComboboxOption } from '@headlessui/vue'
 import ACheckbox from './Checkbox.vue'
 import AColorCircle from './ColorCircle.vue'
 import { type Color } from '../colors'
+import { type BaseOption, type ExtendedOption } from '../types/selection'
 
-export type Option = {
-  value: string
-  label: string
-  disabled?: boolean
-  color?: Color
-}
-
-export default defineComponent({
-  name: 'AOption',
-  components: { ListboxOption, ComboboxOption, ACheckbox, AColorCircle },
-  props: {
+const props = withDefaults(
+  defineProps<{
     /**
      * the component inside of which the option is rendered
      *
      * `'listbox' | 'combobox'`
      */
-    component: {
-      type: String as PropType<'listbox' | 'combobox'>,
-      default: 'listbox'
-    },
+    component?: 'listbox' | 'combobox'
     /**
      * the option to be rendered
      * containing `value`, `label` and optional `disabled` properties
@@ -32,28 +25,25 @@ export default defineComponent({
      * alternatively pass `value` and `disabled` props directly to a-option
      * and render a label via the default slot.
      */
-    option: {
-      type: Object as PropType<Option>,
-      default: () => ({})
-    },
+    option: T
     /**
      * whether the option is rendered in multiselect combobox (with a checkbox)
      */
-    multi: {
-      type: Boolean,
-      default: false
-    }
-  },
+    multi?: boolean
+  }>(),
+  {
+    component: 'listbox',
+    multi: false
+  }
+)
 
-  setup(props) {
-    const componentOption = computed(() =>
-      props.component === 'combobox' ? ComboboxOption : ListboxOption
-    )
+const componentOption = computed(() =>
+  props.component === 'combobox' ? ComboboxOption : ListboxOption
+)
 
-    return {
-      componentOption
-    }
-  }
+const optionColor = computed(() => {
+  const opt = props.option as BaseOption & { color?: Color }
+  return opt.color
 })
 </script>
 <template>
@@ -76,7 +66,7 @@ export default defineComponent({
              @slot Named `#extra` slot. Use to add an icon or image preview, or any extra elements on the left-hand side of the option label.
           -->
         <slot name="extra">
-          <a-color-circle v-if="option.color" class="mr-2" :color="option.color"></a-color-circle>
+          <a-color-circle v-if="optionColor" class="mr-2" :color="optionColor"></a-color-circle>
         </slot>
         <!--
             @slot `#default` slot. Use to render custom styles or extra markup for the option. Renders option label by default.
@@ -93,7 +83,7 @@ export default defineComponent({
              @slot Named `#extra` slot. Use to add an icon or image preview, or any extra elements on the left-hand side of the option label.
           -->
           <slot name="extra">
-            <a-color-circle v-if="option.color" class="ml-2" :color="option.color"></a-color-circle>
+            <a-color-circle v-if="optionColor" class="ml-2" :color="optionColor"></a-color-circle>
           </slot>
         </span>
         <!--
diff --git a/src/components/OptionGroup.vue b/src/components/OptionGroup.vue
index 1553989..84e3d3d 100644
--- a/src/components/OptionGroup.vue
+++ b/src/components/OptionGroup.vue
@@ -1,57 +1,42 @@
 <script lang="ts">
-import { defineComponent, PropType } from 'vue'
+export type { OptionGroup } from '../types/selection'
+export { areOptionsGrouped } from '../types/selection'
+</script>
+
+<script setup lang="ts" generic="T extends BaseOption = ExtendedOption">
+import { computed } from 'vue'
 import ASeparator from './Separator.vue'
-import { Option } from './Option.vue'
 import AOption from './Option.vue'
+import { type BaseOption, type ExtendedOption } from '../types/selection'
 
-export type OptionGroup = {
-  title?: string
-  options: Option[]
-}
-
-export const areOptionsGrouped = (options: Option[] | OptionGroup[]): options is OptionGroup[] => {
-  return !!options.length && 'options' in options[0]
-}
-
-export default defineComponent({
-  name: 'AOptionGroup',
-  components: { ASeparator, AOption },
-  props: {
+const props = withDefaults(
+  defineProps<{
     /**
      * the option group title
      */
-    title: {
-      type: String,
-      default: ''
-    },
+    title?: string
     /**
      * list of options to render
      */
-    options: {
-      type: Array as PropType<Option[]>,
-      default: () => []
-    },
+    options?: T[]
     /**
      * parent component, listbox or combobox
      */
-    component: {
-      type: String as PropType<'listbox' | 'combobox'>,
-      default: 'listbox'
-    },
+    component?: 'listbox' | 'combobox'
     /**
      * whether the option is rendered in multiselect combobox (with a checkbox)
      */
-    multi: {
-      type: Boolean,
-      default: false
-    }
-  },
-  computed: {
-    titleId() {
-      return this.title ? `${this.title}-option-group` : undefined
-    }
+    multi?: boolean
+  }>(),
+  {
+    title: '',
+    options: () => [],
+    component: 'listbox',
+    multi: false
   }
-})
+)
+
+const titleId = computed(() => (props.title ? `${props.title}-option-group` : undefined))
 </script>
 
 <template>
@@ -68,14 +53,14 @@ export default defineComponent({
     </div>
     <!--
         @slot  `#default` slot. Takes `a-option` components without any wrappers.
-        Use this slot to render listbox or combobox options with extra styles or markup. 
-        
+        Use this slot to render listbox or combobox options with extra styles or markup.
+
         Default value: `options` prop rendered as `a-option`s
       -->
     <slot>
       <AOption
         v-for="option in options"
-        :key="option.value"
+        :key="String(option.value)"
         :component="component"
         :multi="multi"
         :option="option"></AOption>
diff --git a/src/components/SelectableOptionGroup.vue b/src/components/SelectableOptionGroup.vue
index 616b3a4..0188a48 100644
--- a/src/components/SelectableOptionGroup.vue
+++ b/src/components/SelectableOptionGroup.vue
@@ -1,78 +1,61 @@
 <script lang="ts">
-import { defineComponent, PropType, computed } from 'vue'
+export { GROUP_VALUE_PREFIX } from '../types/selection'
+</script>
+
+<script setup lang="ts" generic="T extends BaseOption = ExtendedOption">
+import { computed } from 'vue'
 import { ComboboxOption } from '@headlessui/vue'
 import ASeparator from './Separator.vue'
-import { Option } from './Option.vue'
 import AOption from './Option.vue'
 import ACheckbox from './Checkbox.vue'
+import { type BaseOption, type ExtendedOption, GROUP_VALUE_PREFIX } from '../types/selection'
 
-export const GROUP_VALUE_PREFIX = '__group__'
-
-export default defineComponent({
-  name: 'ASelectableOptionGroup',
-  components: { ASeparator, AOption, ACheckbox, ComboboxOption },
-  props: {
+const props = withDefaults(
+  defineProps<{
     /**
      * the option group title
      */
-    title: {
-      type: String,
-      required: true
-    },
+    title: string
     /**
      * list of options in this group
      */
-    options: {
-      type: Array as PropType<Option[]>,
-      required: true
-    },
+    options: T[]
     /**
      * current selection values (for computing checkbox state)
      */
-    modelValue: {
-      type: Array as PropType<string[]>,
-      default: () => []
-    },
+    modelValue?: string[]
     /**
      * parent component type. Only 'combobox' is supported because this component
      * uses Headless UI's ComboboxOption for keyboard navigation.
      * This prop exists for API consistency with AOptionGroup.
      */
-    component: {
-      type: String as PropType<'combobox'>,
-      default: 'combobox',
-      validator: (value: string) => value === 'combobox'
-    }
-  },
-  setup(props) {
-    const titleId = computed(() => `${props.title}-option-group`)
+    component?: 'combobox'
+  }>(),
+  {
+    modelValue: () => [],
+    component: 'combobox'
+  }
+)
 
-    // used by Headless UI for keyboard navigation AND click selection
-    const groupValue = computed(() => `${GROUP_VALUE_PREFIX}${props.title}`)
+const titleId = computed(() => `${props.title}-option-group`)
 
-    const enabledOptions = computed(() => props.options.filter(o => !o.disabled))
+// used by Headless UI for keyboard navigation AND click selection
+const groupValue = computed(() => `${GROUP_VALUE_PREFIX}${props.title}`)
 
-    const selectedCount = computed(() => {
-      const selectedSet = new Set(props.modelValue)
-      return props.options.filter(o => selectedSet.has(o.value)).length
-    })
+const enabledOptions = computed(() => props.options.filter(o => !o.disabled))
 
-    const areAllSelected = computed(
-      () => selectedCount.value === enabledOptions.value.length && enabledOptions.value.length > 0
-    )
+const selectedCount = computed(() => {
+  const selectedSet = new Set(props.modelValue)
+  return props.options.filter(o => selectedSet.has(String(o.value))).length
+})
 
-    const isPartiallySelected = computed(
-      () => selectedCount.value > 0 && selectedCount.value < enabledOptions.value.length
-    )
+const areAllSelected = computed(
+  () => selectedCount.value === enabledOptions.value.length && enabledOptions.value.length > 0
+)
 
-    return {
-      titleId,
-      groupValue,
-      areAllSelected,
-      isPartiallySelected
-    }
-  }
-})
+const isPartiallySelected = computed(
+  () => selectedCount.value > 0 && selectedCount.value < enabledOptions.value.length
+)
 </script>
 
 <template>
@@ -105,7 +88,7 @@ export default defineComponent({
       <slot>
         <AOption
           v-for="option in options"
-          :key="option.value"
+          :key="String(option.value)"
           component="combobox"
           multi
           :option="option" />
diff --git a/src/components/Switcher.vue b/src/components/Switcher.vue
index 38b16a5..23b84bf 100644
--- a/src/components/Switcher.vue
+++ b/src/components/Switcher.vue
@@ -1,59 +1,38 @@
 <script lang="ts">
-import { defineComponent, computed, PropType } from 'vue'
+export type { SwitcherOption } from '../types/selection'
+</script>
+
+<script
+  setup
+  lang="ts"
+  generic="T extends SwitcherOption = SwitcherOption, ModelValue extends string = string">
+import { computed } from 'vue'
 import { RadioGroup, RadioGroupLabel, RadioGroupOption } from '@headlessui/vue'
 import AIcon from './Icon.vue'
+import { type SwitcherOption } from '../types/selection'
 
-export type SwitcherOption = {
-  label: string
-  value: string
-  disabled?: boolean
-  icon?: string
-}
-
-export default defineComponent({
-  name: 'ASwitcher',
-  components: {
-    RadioGroup,
-    RadioGroupLabel,
-    RadioGroupOption,
-    AIcon
-  },
-  props: {
-    modelValue: {
-      type: String,
-      required: true
-    },
-    options: {
-      type: Array as PropType<SwitcherOption[]>,
-      required: true
-    },
-    label: {
-      type: String,
-      default: ''
-    },
-    raised: {
-      type: Boolean,
-      default: false
-    },
-    disabled: {
-      type: Boolean,
-      default: false
-    }
-  },
-  emits: ['update:modelValue'],
-  setup(props, { emit }) {
-    const model = computed({
-      get: () => {
-        return props.modelValue
-      },
-      set: value => {
-        emit('update:modelValue', value)
-      }
-    })
-    return {
-      model
-    }
+const props = withDefaults(
+  defineProps<{
+    modelValue: ModelValue
+    options: T[]
+    label?: string
+    raised?: boolean
+    disabled?: boolean
+  }>(),
+  {
+    label: '',
+    raised: false,
+    disabled: false
   }
+)
+
+const emit = defineEmits<{
+  'update:modelValue': [value: ModelValue]
+}>()
+
+const model = computed({
+  get: (): ModelValue => props.modelValue,
+  set: (value: ModelValue) => emit('update:modelValue', value)
 })
 </script>
 <template>
@@ -65,7 +44,7 @@ export default defineComponent({
     <RadioGroupLabel class="sr-only">{{ label }}</RadioGroupLabel>
     <RadioGroupOption
       v-for="option in options"
-      :key="option.value"
+      :key="String(option.value)"
       v-slot="{ checked }"
       :value="option.value"
       :disabled="option.disabled || disabled"
@@ -80,7 +59,7 @@ export default defineComponent({
         }"
         :aria-label="option.icon ? option.label : undefined"
         :title="option.icon ? option.label : undefined">
-        <slot :name="option.value">
+        <slot :name="String(option.value)">
           <a-icon v-if="option.icon" :name="option.icon" size="sm"></a-icon>
           <template v-else>
             {{ option.label }}
diff --git a/src/components/__tests__/Combobox.test.ts b/src/components/__tests__/Combobox.test.ts
index faf5df2..a5fe729 100644
--- a/src/components/__tests__/Combobox.test.ts
+++ b/src/components/__tests__/Combobox.test.ts
@@ -10,6 +10,23 @@ const defaultOptions = [
   { value: 'e', label: 'Option E' }
 ]
 
+// Helper to count visible tags in the combobox trigger
+// Tags have removable buttons with aria-label="Remove"
+const getVisibleTagCount = () => {
+  return screen.queryAllByLabelText('Remove').length
+}
+
+// Helper to check if a tag with specific text is visible
+const hasVisibleTag = (label: string) => {
+  // Tags are rendered as ATag components with removable buttons
+  // The tag text appears alongside the Remove button
+  const removeButtons = screen.queryAllByLabelText('Remove')
+  return removeButtons.some(button => {
+    const tag = button.closest('[class*="a-tag"]') || button.parentElement
+    return tag?.textContent?.includes(label)
+  })
+}
+
 describe('Combobox.vue - Multi-select tag display', () => {
   describe('maxTags prop', () => {
     it('displays all tags when maxTags is undefined', () => {
@@ -20,11 +37,13 @@ describe('Combobox.vue - Multi-select tag display', () => {
         }
       })
 
-      expect(screen.getByText('Option A')).toBeInTheDocument()
-      expect(screen.getByText('Option B')).toBeInTheDocument()
-      expect(screen.getByText('Option C')).toBeInTheDocument()
-      expect(screen.getByText('Option D')).toBeInTheDocument()
-      expect(screen.getByText('Option E')).toBeInTheDocument()
+      // All 5 tags should be visible (each has a Remove button)
+      expect(getVisibleTagCount()).toBe(5)
+      expect(hasVisibleTag('Option A')).toBe(true)
+      expect(hasVisibleTag('Option B')).toBe(true)
+      expect(hasVisibleTag('Option C')).toBe(true)
+      expect(hasVisibleTag('Option D')).toBe(true)
+      expect(hasVisibleTag('Option E')).toBe(true)
     })
 
     it('limits visible tags to maxTags count', () => {
@@ -36,11 +55,13 @@ describe('Combobox.vue - Multi-select tag display', () => {
         }
       })
 
-      expect(screen.getByText('Option A')).toBeInTheDocument()
-      expect(screen.getByText('Option B')).toBeInTheDocument()
-      expect(screen.queryByText('Option C')).not.toBeInTheDocument()
-      expect(screen.queryByText('Option D')).not.toBeInTheDocument()
-      expect(screen.queryByText('Option E')).not.toBeInTheDocument()
+      // Only 2 tags should be visible
+      expect(getVisibleTagCount()).toBe(2)
+      expect(hasVisibleTag('Option A')).toBe(true)
+      expect(hasVisibleTag('Option B')).toBe(true)
+      expect(hasVisibleTag('Option C')).toBe(false)
+      expect(hasVisibleTag('Option D')).toBe(false)
+      expect(hasVisibleTag('Option E')).toBe(false)
     })
 
     it('shows collapsed indicator when tags exceed maxTags', () => {
@@ -76,9 +97,12 @@ describe('Combobox.vue - Multi-select tag display', () => {
         }
       })
 
-      expect(screen.queryByText('Option A')).not.toBeInTheDocument()
-      expect(screen.queryByText('Option B')).not.toBeInTheDocument()
-      expect(screen.queryByText('Option C')).not.toBeInTheDocument()
+      // With maxTags: 0, no tags should be visible (no Remove buttons)
+      expect(getVisibleTagCount()).toBe(0)
+      expect(hasVisibleTag('Option A')).toBe(false)
+      expect(hasVisibleTag('Option B')).toBe(false)
+      expect(hasVisibleTag('Option C')).toBe(false)
+      // The collapsed indicator should be shown
       expect(screen.getByText('+3 more')).toBeInTheDocument()
     })
   })
diff --git a/src/components/internal/OptionsPanel.vue b/src/components/internal/OptionsPanel.vue
index 016c5b4..e48ed9e 100644
--- a/src/components/internal/OptionsPanel.vue
+++ b/src/components/internal/OptionsPanel.vue
@@ -1,25 +1,32 @@
 <script lang="ts">
-import { defineComponent, PropType } from 'vue'
+export type Direction = 'up' | 'down'
+</script>
+
+<script setup lang="ts" generic="T extends BaseOption = ExtendedOption">
 import { ListboxOptions, ComboboxOptions } from '@headlessui/vue'
-import AOption, { Option } from '../Option.vue'
-import AOptionGroup, { OptionGroup, areOptionsGrouped } from '../OptionGroup.vue'
+import AOption from '../Option.vue'
+import AOptionGroup from '../OptionGroup.vue'
 import ASelectableOptionGroup from '../SelectableOptionGroup.vue'
+import {
+  type BaseOption,
+  type ExtendedOption,
+  type OptionGroup,
+  areOptionsGrouped
+} from '../../types/selection'
 
-export type Direction = 'up' | 'down'
+const optionsComponents = {
+  listbox: ListboxOptions,
+  combobox: ComboboxOptions
+}
 
-export default defineComponent({
-  name: 'OptionsPanel',
-  components: { ListboxOptions, ComboboxOptions, AOption, AOptionGroup, ASelectableOptionGroup },
-  props: {
+withDefaults(
+  defineProps<{
     /**
      * the component inside of which the option is rendered
      *
      * `'listbox' | 'combobox'`
      */
-    component: {
-      type: String as PropType<'listbox' | 'combobox'>,
-      default: 'listbox'
-    },
+    component?: 'listbox' | 'combobox'
     /**
      * An option is at the minimum a `{ value: string, label: string }` object.
      * This prop is used to display the list of options,
@@ -27,76 +34,61 @@ export default defineComponent({
      *
      * You can also provide a grouped structure of options: `[{ title: string, options: Option[] }]`
      */
-    options: {
-      type: Array as PropType<Option[] | OptionGroup[]>,
-      required: true
-    },
+    options: T[] | OptionGroup<string, T>[]
     /**
      * direction in which the dropdown is opening.
      * possible values: `up`, `down`. Default is `down`
      */
-    direction: {
-      type: String as PropType<Direction>,
-      default: 'down'
-    },
+    direction?: Direction
     /**
      * the sizing of the component
      */
-    size: {
-      type: String as PropType<'sm' | 'md'>,
-      default: 'sm'
-    },
+    size?: 'sm' | 'md'
     /**
      * whether the options are rendered in multiselect combobox
      */
-    multi: {
-      type: Boolean,
-      default: false
-    },
+    multi?: boolean
     /**
      * whether the options panel is rendered inline
      */
-    inline: {
-      type: Boolean,
-      default: false
-    },
+    inline?: boolean
     /**
      * allow the options panel to be rendered outside the flow of a container that has content that needs scrolling
      */
-    escapeOverflow: {
-      type: Boolean,
-      default: false
-    },
+    escapeOverflow?: boolean
     /**
      * width of the panel in pixels, to be provided when escapeOverflow is true
      */
-    width: {
-      type: Number,
-      default: 0
-    },
+    width?: number
     /**
      * whether to show selectable checkboxes in group headers
      */
-    selectableGroups: {
-      type: Boolean,
-      default: false
-    },
+    selectableGroups?: boolean
     /**
      * current selection values for computing group selection state
      */
-    selectedValues: {
-      type: Array as PropType<string[]>,
-      default: () => []
-    }
-  },
-  setup() {
-    return { areOptionsGrouped }
+    selectedValues?: string[]
+  }>(),
+  {
+    component: 'listbox',
+    direction: 'down',
+    size: 'sm',
+    multi: false,
+    inline: false,
+    escapeOverflow: false,
+    width: 0,
+    selectableGroups: false,
+    selectedValues: () => []
   }
-})
+)
+
+const isGrouped = (opts: T[] | OptionGroup<string, T>[]): opts is OptionGroup<string, T>[] => {
+  return areOptionsGrouped(opts)
+}
 </script>
 <template>
   <component
-    :is="`${component}-options`"
+    :is="optionsComponents[component]"
     as="div"
     :static="inline"
     class="focus-visible:outline-none"
@@ -115,12 +107,12 @@ export default defineComponent({
     :style="escapeOverflow && width && `width: ${width}px`">
     <!-- @slot  `#default` slot. Takes `a-option` or `a-option-group` components without any wrappers. Use this slot to render options with extra styles or markup. Default value: `options` prop rendered as `a-option`s or `a-option-group`s -->
     <slot>
-      <template v-if="areOptionsGrouped(options)">
+      <template v-if="isGrouped(options)">
         <!-- use SelectableOptionGroup when selectableGroups is enabled -->
         <template v-if="selectableGroups">
           <ASelectableOptionGroup
             v-for="group in options"
-            :key="group.title || group.options[0].value"
+            :key="group.title || String(group.options[0].value)"
             :title="group.title || ''"
             :options="group.options"
             :model-value="selectedValues" />
@@ -128,7 +120,7 @@ export default defineComponent({
         <template v-else>
           <AOptionGroup
             v-for="group in options"
-            :key="group.title || group.options[0].value"
+            :key="group.title || String(group.options[0].value)"
             :component="component"
             :options="group.options"
             :title="group.title"
@@ -138,7 +130,7 @@ export default defineComponent({
       <template v-else>
         <AOption
           v-for="option in options"
-          :key="option.value"
+          :key="String(option.value)"
           :component="component"
           :option="option"
           :multi="multi"></AOption>
diff --git a/src/index.ts b/src/index.ts
index 5a53173..4de984f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -12,3 +12,5 @@ export * from './components'
 export * from './composables'
 
 export * from './colors'
+
+export * from './types'
diff --git a/src/types/index.ts b/src/types/index.ts
new file mode 100644
index 0000000..975551f
--- /dev/null
+++ b/src/types/index.ts
@@ -0,0 +1,11 @@
+export {
+  type OptionValue,
+  type BaseOption,
+  type ExtendedOption,
+  type Option,
+  type OptionGroup,
+  type SwitcherOption,
+  areOptionsGrouped,
+  isOptionGroup,
+  GROUP_VALUE_PREFIX
+} from './selection'
diff --git a/src/types/selection.ts b/src/types/selection.ts
new file mode 100644
index 0000000..264a3f5
--- /dev/null
+++ b/src/types/selection.ts
@@ -0,0 +1,115 @@
+import { type Color } from '../colors'
+
+/**
+ * Valid value types that can be used as option values.
+ * Constrained to types compatible with HeadlessUI components.
+ */
+export type OptionValue = string | number | boolean | Record<string, unknown> | null
+
+/**
+ * Base constraint for all option types.
+ * Every option must have at minimum a value, label, and optional disabled state.
+ *
+ * @typeParam V - The type of the option's value (default: string)
+ */
+export interface BaseOption<V extends OptionValue = string> {
+  value: V
+  label: string
+  disabled?: boolean
+}
+
+/**
+ * Extended option with color support.
+ * This is the default option type for backwards compatibility with existing code.
+ *
+ * @typeParam V - The type of the option's value (default: string)
+ */
+export interface ExtendedOption<V extends OptionValue = string> extends BaseOption<V> {
+  color?: Color
+}
+
+/**
+ * Generic Option type alias.
+ * Defaults to ExtendedOption<string> for backwards compatibility.
+ *
+ * @typeParam V - The type of the option's value (default: string)
+ * @typeParam T - The full option type extending BaseOption<V> (default: ExtendedOption<V>)
+ *
+ * @example
+ * // Default usage (backwards compatible)
+ * const options: Option[] = [{ value: 'a', label: 'Option A' }]
+ *
+ * @example
+ * // With custom value type
+ * const numericOptions: Option<number>[] = [{ value: 1, label: 'One' }]
+ *
+ * @example
+ * // With custom option type
+ * interface MyOption extends BaseOption<number> {
+ *   metadata: { priority: number }
+ * }
+ * const customOptions: Option<number, MyOption>[] = [
+ *   { value: 1, label: 'One', metadata: { priority: 1 } }
+ * ]
+ */
+export type Option<V extends OptionValue = string, T extends BaseOption<V> = ExtendedOption<V>> = T
+
+/**
+ * Generic OptionGroup for grouped options.
+ *
+ * @typeParam V - The type of the option's value (default: string)
+ * @typeParam T - The full option type extending BaseOption<V> (default: ExtendedOption<V>)
+ */
+export interface OptionGroup<
+  V extends OptionValue = string,
+  T extends BaseOption<V> = ExtendedOption<V>
+> {
+  title?: string
+  options: T[]
+}
+
+/**
+ * Switcher-specific option with icon support.
+ *
+ * @typeParam V - The type of the option's value (default: string)
+ */
+export interface SwitcherOption<V extends OptionValue = string> extends BaseOption<V> {
+  icon?: string
+}
+
+/**
+ * Type guard to check if options array contains grouped options.
+ *
+ * @typeParam V - The type of the option's value
+ * @typeParam T - The full option type extending BaseOption<V>
+ */
+export function areOptionsGrouped<V extends OptionValue, T extends BaseOption<V>>(
+  options: T[] | OptionGroup<V, T>[]
+): options is OptionGroup<V, T>[] {
+  return !!options.length && 'options' in options[0]
+}
+
+/**
+ * Type guard to check if a single item is an OptionGroup (vs a flat option).
+ * Useful for narrowing types when iterating over mixed option arrays.
+ *
+ * @example
+ * filteredOptions.map(item => {
+ *   if (isOptionGroup(item)) {
+ *     // item is OptionGroup - access item.options, item.title
+ *   } else {
+ *     // item is T - access item.value, item.label
+ *   }
+ * })
+ */
+export function isOptionGroup<V extends OptionValue, T extends BaseOption<V>>(
+  item: T | OptionGroup<V, T>
+): item is OptionGroup<V, T> {
+  return 'options' in item
+}
+
+/**
+ * Prefix used internally for group selection values in SelectableOptionGroup.
+ * This is an internal mechanism and should not be used by consumers.
+ */
+export const GROUP_VALUE_PREFIX = '__group__'