@xen-orchestra/web-core 0.19.0 → 0.20.0

package/lib/packages/collection/README.md

@@ -6,11 +6,11 @@ The `useCollection` composable helps you manage a collection of items with flags
 
 ```typescript
 const { items, useSubset, useFlag } = useCollection(sources, {
-  identifier: source => source.id,
   flags: ['selected', 'active', { highlighted: { multiple: false } }],
   properties: source => ({
-    isAvailable: computed(() => source.status === 'available'),
-    fullName: computed(() => `${source.firstName} ${source.lastName}`),
+    id: source.theId, // Required if TSource doesn't have an `id` property
+    isAvailable: source.status === 'available',
+    fullName: `${source.firstName} ${source.lastName}`,
   }),
 })
 ```
@@ -19,22 +19,27 @@ const { items, useSubset, useFlag } = useCollection(sources, {
 
 - **Collection Item**: An object with a unique identifier, a reference to its source object, flags, computed properties, and methods to manipulate flags
 - **Flags**: Boolean states attached to items (like 'selected', 'active', 'highlighted')
-- **Properties**: Computed values derived from the source object
+- **Properties**: Additional custom values
 
 ## `useCollection` parameters
 
-| Name      | Type                              | Required | Description                                          |
-| --------- | --------------------------------- | :------: | ---------------------------------------------------- |
-| `sources` | `MaybeRefOrGetter<TSource[]>`     |    ✓     | Array of source objects for the collection           |
-| `options` | `CollectionOptions<TSource, TId>` |    ✓     | Configuration options for the collection (see below) |
+| Name      | Type                                             | Required | Description                                          |
+| --------- | ------------------------------------------------ | :------: | ---------------------------------------------------- |
+| `sources` | `MaybeRefOrGetter<TSource[]>`                    |    ✓     | Array of source objects for the collection           |
+| `options` | `CollectionOptions<TSource, TFlag, TProperties>` |    ~     | Configuration options for the collection (see below) |
 
 ### `options` object
 
-| Name         | Type                                               | Required | Description                                              |
-| ------------ | -------------------------------------------------- | :------: | -------------------------------------------------------- |
-| `identifier` | `(source: TSource) => TId`                         |    ✓     | Function to extract a unique identifier from each source |
-| `flags`      | `FlagsConfig<TFlag>`                               |          | Flags that can be applied to items in the collection     |
-| `properties` | `(source: TSource) => Record<string, ComputedRef>` |          | Function that returns computed properties for each item  |
+| Name         | Type                                           | Required | Description                                                           |
+| ------------ | ---------------------------------------------- | :------: | --------------------------------------------------------------------- |
+| `flags`      | `FlagsConfig<TFlag>`                           |          | Flags that can be applied to items in the collection                  |
+| `properties` | `(source: TSource) => Record<string, unknown>` |    ~     | Function that returns additional properties for each item (see below) |
+
+### Item ID
+
+The item ID will be retrieved automatically from `TSource.id`
+
+If `TSource` doesn't provide an `id`, then `options.properties` will be required and must return at least an `id`
 
 ### `FlagsConfig` type
 
@@ -44,17 +49,17 @@ type FlagsConfig<TFlag extends string> = TFlag[] | { [K in TFlag]: { multiple?:
 
 Values for `multiple`:
 
-- `true` (default): multiple items can have the same flag.
+- `true` (default): multiple items can share the same flag.
 - `false`: only one item can have the flag at a time (exclusive selection). Setting the flag on one item will automatically unset it on all other items.
 
 ## Return Value
 
-| Name        | Type                                        | Description                                              |
-| ----------- | ------------------------------------------- | -------------------------------------------------------- |
-| `items`     | `ComputedRef<CollectionItem[]>`             | Array of collection items with flags and properties      |
-| `useSubset` | `(filter: (item) => boolean) => Collection` | Creates a new collection that's a subset of the original |
-| `useFlag`   | `(flag: TFlag) => UseFlag`                  | Utilities for working with a specific flag               |
-| `count`     | `ComputedRef<number>`                       | Number of items in the collection                        |
+| Name        | Type                                        | Description                                         |
+| ----------- | ------------------------------------------- | --------------------------------------------------- |
+| `items`     | `ComputedRef<CollectionItem[]>`             | Array of collection items with flags and properties |
+| `useSubset` | `(filter: (item) => boolean) => Collection` | Creates a sub collection matching the filter        |
+| `useFlag`   | `(flag: TFlag) => UseFlagReturn`            | Utilities for working with a specific flag          |
+| `count`     | `ComputedRef<number>`                       | Number of items in the collection                   |
 
 ### `CollectionItem` object
 
@@ -66,18 +71,19 @@ Values for `multiple`:
 | `properties` | `TProperties`                  | Object containing all computed properties for this item   |
 | `toggleFlag` | `(flag, forcedValue?) => void` | Method to toggle a flag on this item                      |
 
-### Return value of `useFlag(flag)`
+### UseFlagReturn object
 
-| Name        | Type                            | Description                                            |
-| ----------- | ------------------------------- | ------------------------------------------------------ |
-| `items`     | `ComputedRef<CollectionItem[]>` | Array of items that have this flag set                 |
-| `ids`       | `ComputedRef<TId[]>`            | Array of IDs of items that have this flag set          |
-| `count`     | `ComputedRef<number>`           | Number of items that have this flag set                |
-| `areAllOn`  | `ComputedRef<boolean>`          | Whether all items in the collection have this flag set |
-| `areSomeOn` | `ComputedRef<boolean>`          | Whether at least one item has this flag set            |
-| `areNoneOn` | `ComputedRef<boolean>`          | Whether no items have this flag set                    |
-| `toggle`    | `(id, forcedValue?) => void`    | Toggle this flag on a specific item                    |
-| `toggleAll` | `(forcedValue?) => void`        | Toggle this flag on all items in the collection        |
+| Name        | Type                                        | Description                                            |
+| ----------- | ------------------------------------------- | ------------------------------------------------------ |
+| `items`     | `ComputedRef<CollectionItem[]>`             | Array of items that have this flag set                 |
+| `ids`       | `ComputedRef<TId[]>`                        | Array of IDs of items that have this flag set          |
+| `count`     | `ComputedRef<number>`                       | Number of items that have this flag set                |
+| `areAllOn`  | `ComputedRef<boolean>`                      | Whether all items in the collection have this flag set |
+| `areSomeOn` | `ComputedRef<boolean>`                      | Whether at least one item has this flag set            |
+| `areNoneOn` | `ComputedRef<boolean>`                      | Whether no items have this flag set                    |
+| `toggle`    | `(id, forcedValue?) => void`                | Toggle this flag on a specific item                    |
+| `toggleAll` | `(forcedValue?) => void`                    | Toggle this flag on all items in the collection        |
+| `useSubset` | `(filter: (item) => boolean) => Collection` | Creates a sub collection matching the filter           |
 
 ## Flag Operations
 
@@ -136,10 +142,9 @@ const {
   useSubset,
   count,
 } = useCollection(rawUsers, {
-  identifier: user => user.id,
   flags: ['selected'],
   properties: user => ({
-    fullName: computed(() => `${user.firstName} ${user.lastName} (${user.group})`),
+    fullName: `${user.firstName} ${user.lastName} (${user.group})`,
   }),
 })
 

package/lib/packages/collection/create-collection.ts

@@ -1,14 +1,21 @@
-import type { CollectionItem, FlagRegistry } from '@core/packages/collection'
+import type {
+  Collection,
+  CollectionConfigProperties,
+  CollectionItem,
+  FlagRegistry,
+  GuessItemId,
+  UseFlagReturn,
+} from '@core/packages/collection/types.ts'
 import { useArrayFilter, useArrayMap } from '@vueuse/core'
 import { computed, type ComputedRef } from 'vue'
 
-export function createCollection<
-  TSource,
-  TId extends PropertyKey,
-  TFlag extends string,
-  TProperties extends Record<string, any>,
->(items: ComputedRef<CollectionItem<TSource, TId, TFlag, TProperties>[]>, flagRegistry: FlagRegistry<TFlag>) {
-  function useFlag(flag: TFlag) {
+export function createCollection<TSource, TFlag extends string, TProperties extends CollectionConfigProperties>(
+  items: ComputedRef<CollectionItem<TSource, TFlag, TProperties>[]>,
+  flagRegistry: FlagRegistry<TFlag>
+): Collection<TSource, TFlag, TProperties> {
+  function useFlag(flag: TFlag): UseFlagReturn<TSource, TFlag, TProperties> {
+    flagRegistry.assertFlag(flag)
+
     const flaggedItems = useArrayFilter(items, item => item.flags[flag])
 
     const ids = useArrayMap(flaggedItems, item => item.id)
@@ -21,7 +28,7 @@ export function createCollection<
 
     const areNoneOn = computed(() => count.value === 0)
 
-    function toggle(id: TId, forcedValue?: boolean) {
+    function toggle(id: GuessItemId<TSource, TProperties>, forcedValue?: boolean) {
       flagRegistry.toggleFlag(id, flag, forcedValue)
     }
 
@@ -31,6 +38,12 @@ export function createCollection<
       }
     }
 
+    function useSubset(
+      filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
+    ): Collection<TSource, TFlag, TProperties> {
+      return createCollection(useArrayFilter(flaggedItems, filter), flagRegistry)
+    }
+
     return {
       items: flaggedItems,
       ids,
@@ -40,13 +53,14 @@ export function createCollection<
       areNoneOn,
       toggle,
       toggleAll,
+      useSubset,
     }
   }
 
-  function useSubset(filter: (item: CollectionItem<TSource, TId, TFlag, TProperties>) => boolean) {
-    const filteredItems = useArrayFilter(items, item => filter(item))
-
-    return createCollection(filteredItems, flagRegistry)
+  function useSubset(
+    filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
+  ): Collection<TSource, TFlag, TProperties> {
+    return createCollection(useArrayFilter(items, filter), flagRegistry)
   }
 
   const count = computed(() => items.value.length)

package/lib/packages/collection/create-item.ts

@@ -0,0 +1,39 @@
+import { guessItemId } from '@core/packages/collection/guess-item-id.ts'
+import type { CollectionConfigProperties, CollectionItem, FlagRegistry } from '@core/packages/collection/types.ts'
+import { reactive } from 'vue'
+
+export function createItem<TSource, TFlag extends string, TProperties extends CollectionConfigProperties>(
+  source: TSource,
+  getProperties: undefined | ((source: TSource) => TProperties),
+  flagRegistry: FlagRegistry<TFlag>
+): CollectionItem<TSource, TFlag, TProperties> {
+  const properties = reactive(getProperties?.(source) ?? ({} as TProperties))
+
+  const id = guessItemId(source, properties)
+
+  return {
+    id,
+    source,
+    toggleFlag(flag: TFlag, forcedValue?: boolean) {
+      flagRegistry.toggleFlag(id, flag, forcedValue)
+    },
+    flags: new Proxy({} as Record<TFlag, boolean>, {
+      has(_, flag: TFlag) {
+        return flagRegistry.isFlagDefined(flag)
+      },
+      get(_, flag: TFlag) {
+        if (!flagRegistry.isFlagDefined(flag)) {
+          return undefined
+        }
+
+        return flagRegistry.isFlagged(id, flag)
+      },
+      set(_, flag: TFlag, value: boolean) {
+        flagRegistry.toggleFlag(id, flag, value)
+
+        return true
+      },
+    }),
+    properties,
+  }
+}

package/lib/packages/collection/guess-item-id.ts

@@ -0,0 +1,26 @@
+import type { CollectionConfigProperties, GuessItemId } from '@core/packages/collection/types.ts'
+
+function assertValidId(id: unknown): asserts id is PropertyKey {
+  const type = typeof id
+
+  if (!['string', 'number', 'symbol'].includes(type)) {
+    throw new TypeError(`Invalid ID type: ${type}. Expected string, number, or bigint.`)
+  }
+}
+
+export function guessItemId<TSource, TProperties extends CollectionConfigProperties>(
+  source: TSource,
+  properties: TProperties | undefined
+) {
+  let id
+
+  if (typeof properties === 'object' && properties !== null && 'id' in properties) {
+    id = properties.id
+  } else if (typeof source === 'object' && source !== null && 'id' in source) {
+    id = source.id
+  }
+
+  assertValidId(id)
+
+  return id as GuessItemId<TSource, TProperties>
+}

package/lib/packages/collection/index.ts

@@ -1,5 +1,2 @@
-export * from './build-item.ts'
-export * from './create-collection.ts'
 export * from './types.ts'
 export * from './use-collection.ts'
-export * from './use-flag-registry.ts'

package/lib/packages/collection/types.ts

@@ -1,29 +1,57 @@
-import type { useFlagRegistry } from '@core/packages/collection'
+import type { ComputedRef, Reactive } from 'vue'
 
-export type FlagsConfig<TFlag extends string> = TFlag[] | { [K in TFlag]: { multiple?: boolean } }
+export type CollectionConfigProperties = Record<string, unknown> & { id?: unknown }
 
-export type CollectionOptions<
-  TSource,
-  TId extends PropertyKey,
-  TFlag extends string,
-  TProperties extends Record<string, unknown>,
-> = {
-  identifier: (source: TSource) => TId
-  properties?: (source: TSource) => TProperties
-  flags?: FlagsConfig<TFlag>
-}
+export type CollectionConfigFlags<TFlag extends string> = TFlag[] | Record<TFlag, { multiple?: boolean }>
 
 export type CollectionItem<
   TSource,
-  TId extends PropertyKey,
-  TFlag extends string,
-  TProperties extends Record<string, any>,
+  TFlag extends string = never,
+  TProperties extends CollectionConfigProperties = Record<string, never>,
 > = {
-  id: TId
+  id: GuessItemId<TSource, Reactive<TProperties>>
   source: TSource
   flags: Record<TFlag, boolean>
-  properties: TProperties
+  properties: Reactive<TProperties>
   toggleFlag: (flag: TFlag, forcedValue?: boolean) => void
 }
 
-export type FlagRegistry<TFlag extends string> = ReturnType<typeof useFlagRegistry<TFlag>>
+export type FlagRegistry<TFlag extends string> = {
+  isFlagged: (id: PropertyKey, flag: TFlag) => boolean
+  isFlagDefined: (flag: TFlag) => boolean
+  toggleFlag: (id: PropertyKey, flag: TFlag, forcedValue?: boolean) => void
+  clearFlag: (flag: TFlag) => void
+  isMultipleAllowed: (flag: TFlag) => boolean
+  assertFlag: (flag: TFlag) => void
+}
+
+export type UseFlagReturn<TSource, TFlag extends string, TProperties extends CollectionConfigProperties> = {
+  items: ComputedRef<CollectionItem<TSource, TFlag, TProperties>[]>
+  ids: ComputedRef<GuessItemId<TSource, TProperties>[]>
+  count: ComputedRef<number>
+  areAllOn: ComputedRef<boolean>
+  areSomeOn: ComputedRef<boolean>
+  areNoneOn: ComputedRef<boolean>
+  toggle: (id: GuessItemId<TSource, TProperties>, forcedValue?: boolean) => void
+  toggleAll: (forcedValue?: boolean) => void
+  useSubset: (
+    filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
+  ) => Collection<TSource, TFlag, TProperties>
+}
+
+export type Collection<TSource, TFlag extends string, TProperties extends CollectionConfigProperties> = {
+  items: ComputedRef<CollectionItem<TSource, TFlag, TProperties>[]>
+  count: ComputedRef<number>
+  useFlag: (flag: TFlag) => UseFlagReturn<TSource, TFlag, TProperties>
+  useSubset: (
+    filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
+  ) => Collection<TSource, TFlag, TProperties>
+}
+
+type AssertId<TId> = TId extends PropertyKey ? TId : never
+
+export type GuessItemId<TSource, TProperties> = TProperties extends { id: infer TId }
+  ? AssertId<TId>
+  : TSource extends { id: infer TId }
+    ? AssertId<TId>
+    : never

package/lib/packages/collection/use-collection.ts

@@ -1,15 +1,47 @@
-import { buildItem, type CollectionOptions, createCollection, useFlagRegistry } from '@core/packages/collection'
+import { createCollection } from '@core/packages/collection/create-collection.ts'
+import { createItem } from '@core/packages/collection/create-item.ts'
+import type { Collection, CollectionConfigFlags, CollectionConfigProperties } from '@core/packages/collection/types.ts'
+import { useFlagRegistry } from '@core/packages/collection/use-flag-registry.ts'
 import { computed, type MaybeRefOrGetter, toValue } from 'vue'
 
+export function useCollection<
+  TSource extends { id: unknown },
+  TFlag extends string = never,
+  TProperties extends CollectionConfigProperties = { id?: unknown },
+>(
+  sources: MaybeRefOrGetter<TSource[]>,
+  config?: {
+    flags?: CollectionConfigFlags<TFlag>
+    properties?: (source: TSource) => TProperties
+  }
+): Collection<TSource, TFlag, TProperties>
+
+export function useCollection<
+  TSource,
+  TFlag extends string = never,
+  TProperties extends CollectionConfigProperties & { id: unknown } = never,
+>(
+  sources: MaybeRefOrGetter<TSource[]>,
+  config: {
+    flags?: CollectionConfigFlags<TFlag>
+    properties: (source: TSource) => TProperties
+  }
+): Collection<TSource, TFlag, TProperties>
+
 export function useCollection<
   TSource,
-  TId extends PropertyKey,
-  TFlag extends string,
-  TProperties extends Record<string, unknown>,
->(sources: MaybeRefOrGetter<TSource[]>, options: CollectionOptions<TSource, TId, TFlag, TProperties>) {
-  const flagRegistry = useFlagRegistry<TFlag>(options.flags)
+  TFlag extends string = never,
+  TProperties extends CollectionConfigProperties = { id?: unknown },
+>(
+  sources: MaybeRefOrGetter<TSource[]>,
+  config?: {
+    flags?: CollectionConfigFlags<TFlag>
+    properties?: (source: TSource) => TProperties
+  }
+): Collection<TSource, TFlag, TProperties> {
+  const flagRegistry = useFlagRegistry(config?.flags)
 
-  const items = computed(() => toValue(sources).map(source => buildItem(source, options, flagRegistry)))
+  const items = computed(() => toValue(sources).map(source => createItem(source, config?.properties, flagRegistry)))
 
   return createCollection(items, flagRegistry)
 }

package/lib/packages/collection/use-flag-registry.ts

@@ -1,20 +1,32 @@
-import type { FlagsConfig } from '@core/packages/collection/types.ts'
+import type { CollectionConfigFlags, FlagRegistry } from '@core/packages/collection/types.ts'
 import { reactive } from 'vue'
 
-export function useFlagRegistry<TFlag extends string>(_flags: FlagsConfig<TFlag> = []) {
-  const registry = reactive(new Map()) as Map<TFlag, Set<PropertyKey> | undefined>
+export function useFlagRegistry<TFlag extends string>(
+  config: CollectionConfigFlags<TFlag> = [] as TFlag[]
+): FlagRegistry<TFlag> {
+  const registry = reactive(new Map<TFlag, Set<PropertyKey>>())
 
-  const flags = Array.isArray(_flags) ? Object.fromEntries(_flags.map(flag => [flag, { multiple: true }])) : _flags
+  const flags = Array.isArray(config) ? Object.fromEntries(config.map(flag => [flag, { multiple: true }])) : config
 
   function isFlagDefined(flag: TFlag) {
-    return flags[flag] !== undefined
+    return Object.prototype.hasOwnProperty.call(flags, flag)
+  }
+
+  function assertFlag(flag: TFlag) {
+    if (!isFlagDefined(flag)) {
+      throw new Error(`Flag "${flag}" is not defined.`)
+    }
   }
 
   function isFlagged(id: PropertyKey, flag: TFlag) {
+    assertFlag(flag)
+
     return registry.get(flag)?.has(id) ?? false
   }
 
   function toggleFlag(id: PropertyKey, flag: TFlag, forcedValue = !isFlagged(id, flag)) {
+    assertFlag(flag)
+
     if (!registry.has(flag)) {
       registry.set(flag, new Set())
     }
@@ -30,10 +42,14 @@ export function useFlagRegistry<TFlag extends string>(_flags: FlagsConfig<TFlag>
   }
 
   function clearFlag(flag: TFlag) {
+    assertFlag(flag)
+
     registry.set(flag, new Set())
   }
 
   function isMultipleAllowed(flag: TFlag) {
+    assertFlag(flag)
+
     return flags[flag]?.multiple ?? false
   }
 
@@ -43,5 +59,6 @@ export function useFlagRegistry<TFlag extends string>(_flags: FlagsConfig<TFlag>
     toggleFlag,
     clearFlag,
     isMultipleAllowed,
+    assertFlag,
   }
 }

package/lib/packages/form-select/README.md

@@ -0,0 +1,96 @@
+# `useFormSelect` composable
+
+This composable manages a collection of filterable form options to be used with `VtsSelect` component.
+
+## Usage
+
+```typescript
+const { searchTerm, options, selectedOptions, selectedValues } = useFormSelect(sources, {
+  properties: source => ({
+    value: source.id, // optional if source has a `value` or `ìd` property
+    label: source.name, // optional if source has a `label` property
+    searchableTerm: [source.name, source.code], // optional, defaults to the label
+    disabled: source.state == 'offline', // optional, defaults to false
+  }),
+  multiple: false,
+})
+```
+
+## Parameters
+
+|           | Required | Type                          | Default | Description                                               |
+| --------- | :------: | ----------------------------- | ------- | --------------------------------------------------------- |
+| `sources` |    ✓     | `MaybeRefOrGetter<TSource[]>` |         | Array of source objects to be converted into form options |
+| `config`  |    ✓     | (see below)                   |         | Configuration                                             |
+
+### `config` object
+
+|                             | Required | Type                                                       | Default         | Description                                                                             |
+| --------------------------- | :------: | ---------------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------- |
+| `properties`                |    ~     | Record<string, unknown>                                    |                 | Object containing custom properties for each option                                     |
+| `properties.value`          |    ~     | `TValue`                                                   |                 | A unique value for each option. Required if `TSource` doesn't have an `id` or `value`   |
+| `properties.label`          |    ~     | `string`                                                   |                 | A human-readable label for each option. Required if `TSource` doesn't have a `label`    |
+| `properties.searchableTerm` |          | `MaybeArray<string>`                                       | Same as `label` | Searchable term(s) for each option for filtering                                        |
+| `properties.disabled`       |          | `boolean`                                                  | `false`         | Determines if an option should be disabled                                              |
+| `multiple`                  |          | `boolean`                                                  | `false`         | Whether multiple options can be selected simultaneously                                 |
+| `selectedLabel`             |          | `(count: number, labels: string[]) => string \| undefined` |                 | Function to format the label for selected options. Default label is `labels.join(', ')` |
+
+## Return Value
+
+|                   | Type                        | Description                                          |
+| ----------------- | --------------------------- | ---------------------------------------------------- |
+| `searchTerm`      | `Ref<string>`               | Reactive reference to control the search/filter term |
+| `allOptions`      | `ComputedRef<FormOption[]>` | All options, regardless of search filtering          |
+| `options`         | `ComputedRef<FormOption[]>` | Options filtered by the current search term          |
+| `selectedOptions` | `ComputedRef<FormOption[]>` | Options that are currently selected                  |
+| `selectedValues`  | `ComputedRef<TValue[]>`     | Values of options that are currently selected        |
+| `selectedLabel`   | `ComputedRef<string>`       | Label for the selected options                       |
+
+## `FormOption` object
+
+Each item in the `options` array is a `FormOption` object with these properties:
+
+|                         | Type                                     | Description                                            |
+| ----------------------- | ---------------------------------------- | ------------------------------------------------------ |
+| `id`                    | `TValue`                                 | Unique identifier for the option (from `getValue`)     |
+| `source`                | `TSource`                                | The original source object                             |
+| `flags`                 | `{ selected: boolean, active: boolean }` | State flags for selection and keyboard navigation      |
+| `properties`            | `object`                                 | Computed properties for the option                     |
+| &nbsp;⤷&nbsp;`label`    | `string`                                 | Human-readable option label (from `getLabel`)          |
+| &nbsp;⤷&nbsp;`matching` | `boolean`                                | Whether the option matches the current search term     |
+| &nbsp;⤷&nbsp;`disabled` | `boolean`                                | Whether the option is disabled                         |
+| &nbsp;⤷&nbsp;`multiple` | `boolean`                                | Whether multiple selection is enabled                  |
+| &nbsp;⤷&nbsp;`...`      | `any`                                    | Any other custom property defined in the config        |
+| `toggleFlag`            | `(flag, forcedValue?) => void`           | Method to toggle a flag (like 'selected') on this item |
+
+## Example: Basic usage with `VtsSelect`
+
+```vue
+<template>
+  <VtsSelect :options :selected-label />
+</template>
+
+<script lang="ts" setup>
+const { options, selectedLabel, selectedValues } = useFormOptions(vms, {
+  properties: vm => ({
+    label: vm.name_label,
+  }),
+})
+</script>
+```
+
+## Example: Searchable + multi-select + custom selected label
+
+```vue
+<template>
+  <VtsSelect v-model:search="searchTerm" :options :selected-label />
+</template>
+
+<script lang="ts" setup>
+const { options, searchTerm, selectedValues, selectedLabel } = useFormOptions(vms, {
+  properties: vm => ({ label: vm.name_label }),
+  multiple: true,
+  selectedlabel: count => (count > 3 ? `${count} VMs selected` : undefined), // Keep the default label if less than 3
+})
+</script>
+```

package/lib/packages/form-select/index.ts

@@ -0,0 +1,2 @@
+export * from './types.ts'
+export * from './use-form-select.ts'

package/lib/packages/form-select/types.ts

@@ -0,0 +1,75 @@
+import type { CollectionConfigProperties, CollectionItem } from '@core/packages/collection'
+import type { MaybeArray } from '@core/types/utility.type.ts'
+import type { ComputedRef, InjectionKey, Reactive, WritableComputedRef } from 'vue'
+
+export type FormSelectBaseConfig = {
+  multiple?: boolean
+  selectedLabel?: (count: number, labels: string[]) => string | undefined
+}
+
+export type FormSelectBaseProperties = Record<string, unknown> & {
+  disabled?: boolean
+  searchableTerm?: MaybeArray<string>
+}
+
+export type FormOptionValue = string | number
+
+export type FormOptionProperties<TValue extends FormOptionValue> = {
+  id: TValue
+  label: string
+  multiple: boolean
+  disabled: boolean
+  matching: boolean
+}
+
+export type FormOption<
+  TSource = unknown,
+  TValue extends FormOptionValue = FormOptionValue,
+  TProperties extends CollectionConfigProperties = CollectionConfigProperties,
+> = CollectionItem<TSource, 'active' | 'selected', TProperties & FormOptionProperties<TValue>>
+
+export type UseFormSelectReturn<
+  TSource,
+  TValue extends FormOptionValue,
+  TProperties extends CollectionConfigProperties,
+> = {
+  searchTerm: WritableComputedRef<string>
+  allOptions: ComputedRef<FormOption<TSource, TValue, TProperties>[]>
+  options: ComputedRef<FormOption<TSource, TValue, TProperties>[]>
+  selectedOptions: ComputedRef<FormOption<TSource, TValue, TProperties>[]>
+  selectedValues: ComputedRef<TValue[]>
+  selectedLabel: ComputedRef<string>
+}
+
+export type FormOptionIndex =
+  | number
+  | 'previous'
+  | 'next'
+  | 'previous-page'
+  | 'next-page'
+  | 'first'
+  | 'last'
+  | 'selected'
+
+export enum FORM_SELECT_HANDLED_KEY {
+  DOWN = 'ArrowDown',
+  UP = 'ArrowUp',
+  LEFT = 'ArrowLeft',
+  RIGHT = 'ArrowRight',
+  ENTER = 'Enter',
+  SPACE = ' ',
+  ESCAPE = 'Escape',
+  HOME = 'Home',
+  END = 'End',
+  TAB = 'Tab',
+  PAGE_DOWN = 'PageDown',
+  PAGE_UP = 'PageUp',
+}
+
+export type FormSelectController = Reactive<{
+  isNavigatingWithKeyboard: boolean
+  closeDropdown(keepFocus: boolean): void
+  focusSearchOrTrigger(): void
+}>
+
+export const IK_FORM_SELECT_CONTROLLER = Symbol('IK_FORM_SELECT_CONTROLLER') as InjectionKey<FormSelectController>