@xen-orchestra/web-core 0.18.0 → 0.20.0

package/lib/packages/collection/types.ts

@@ -0,0 +1,57 @@
+import type { ComputedRef, Reactive } from 'vue'
+
+export type CollectionConfigProperties = Record<string, unknown> & { id?: unknown }
+
+export type CollectionConfigFlags<TFlag extends string> = TFlag[] | Record<TFlag, { multiple?: boolean }>
+
+export type CollectionItem<
+  TSource,
+  TFlag extends string = never,
+  TProperties extends CollectionConfigProperties = Record<string, never>,
+> = {
+  id: GuessItemId<TSource, Reactive<TProperties>>
+  source: TSource
+  flags: Record<TFlag, boolean>
+  properties: Reactive<TProperties>
+  toggleFlag: (flag: TFlag, forcedValue?: boolean) => void
+}
+
+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

@@ -0,0 +1,47 @@
+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,
+  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 => createItem(source, config?.properties, flagRegistry)))
+
+  return createCollection(items, flagRegistry)
+}

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

@@ -0,0 +1,64 @@
+import type { CollectionConfigFlags, FlagRegistry } from '@core/packages/collection/types.ts'
+import { reactive } from 'vue'
+
+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(config) ? Object.fromEntries(config.map(flag => [flag, { multiple: true }])) : config
+
+  function isFlagDefined(flag: TFlag) {
+    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())
+    }
+
+    if (forcedValue) {
+      if (!isMultipleAllowed(flag)) {
+        clearFlag(flag)
+      }
+      registry.get(flag)!.add(id)
+    } else {
+      registry.get(flag)!.delete(id)
+    }
+  }
+
+  function clearFlag(flag: TFlag) {
+    assertFlag(flag)
+
+    registry.set(flag, new Set())
+  }
+
+  function isMultipleAllowed(flag: TFlag) {
+    assertFlag(flag)
+
+    return flags[flag]?.multiple ?? false
+  }
+
+  return {
+    isFlagged,
+    isFlagDefined,
+    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>

package/lib/packages/form-select/use-form-option-controller.ts

@@ -0,0 +1,50 @@
+import { type FormOption, IK_FORM_SELECT_CONTROLLER } from '@core/packages/form-select/types.ts'
+import { unrefElement, useEventListener, whenever } from '@vueuse/core'
+import { computed, inject, type MaybeRefOrGetter, ref, toValue } from 'vue'
+
+export function useFormOptionController<TOption extends FormOption>(_option: MaybeRefOrGetter<TOption>) {
+  const controller = inject(IK_FORM_SELECT_CONTROLLER)
+
+  if (!controller) {
+    throw new Error('useFormOption needs a FormSelectController to be injected')
+  }
+
+  const option = computed(() => toValue(_option))
+
+  const elementRef = ref<HTMLDivElement>()
+
+  whenever(
+    () => option.value.flags.active,
+    () => {
+      unrefElement(elementRef)?.scrollIntoView({ block: 'nearest' })
+    }
+  )
+
+  useEventListener(elementRef, 'click', event => {
+    event.preventDefault()
+
+    if (option.value.properties.disabled) {
+      return
+    }
+
+    if (option.value.properties.multiple) {
+      option.value.toggleFlag('selected')
+      controller.focusSearchOrTrigger()
+    } else {
+      option.value.toggleFlag('selected', true)
+      controller.closeDropdown(true)
+    }
+  })
+
+  useEventListener(elementRef, 'mouseenter', () => {
+    if (option.value.properties.disabled || controller.isNavigatingWithKeyboard) {
+      return
+    }
+
+    option.value.flags.active = true
+  })
+
+  return {
+    elementRef,
+  }
+}

package/lib/packages/form-select/use-form-select-controller.ts

@@ -0,0 +1,205 @@
+import { type FormOption, type FormOptionIndex, IK_FORM_SELECT_CONTROLLER } from '@core/packages/form-select/types.ts'
+import { useFormSelectKeyboardNavigation } from '@core/packages/form-select/use-form-select-keyboard-navigation.ts'
+import { ifElse } from '@core/utils/if-else.utils'
+import { type MaybeElement, useFloating } from '@floating-ui/vue'
+import { clamp, onClickOutside, useEventListener, useFocusWithin, whenever } from '@vueuse/core'
+import { logicOr } from '@vueuse/math'
+import { computed, type MaybeRefOrGetter, provide, reactive, type Ref, ref, toValue, watch } from 'vue'
+
+export function useFormSelectController<TOption extends FormOption>(config: {
+  options: MaybeRefOrGetter<TOption[]>
+  searchTerm: Ref<string | undefined>
+}) {
+  const options = computed(() => toValue(config.options))
+
+  const isMultiple = computed(() => options.value[0]?.properties.multiple ?? false)
+
+  const activeOption = computed(() => options.value.find(option => option.flags.active))
+
+  const isOpen = ref(false)
+
+  /* TRIGGER */
+
+  const triggerRef = ref<HTMLElement>()
+
+  const { focused: isTriggerFocused } = useFocusWithin(triggerRef)
+
+  const isActive = logicOr(isTriggerFocused, isOpen)
+
+  useEventListener(triggerRef, 'click', () => openDropdown())
+
+  function focusTrigger() {
+    triggerRef.value?.focus?.()
+  }
+
+  /* KEYBOARD NAVIGATION */
+
+  const { isNavigatingWithKeyboard, stopKeyboardNavigation } = useFormSelectKeyboardNavigation({
+    isActive,
+    isMultiple,
+    isOpen,
+    onSelect: () => activeOption.value?.toggleFlag('selected', true),
+    onToggle: () => activeOption.value?.toggleFlag('selected'),
+    onOpen: openDropdown,
+    onClose: closeDropdown,
+    onMove: index => moveToOptionIndex(index),
+  })
+
+  /* DROPDOWN */
+
+  const dropdownRef = ref<HTMLElement>()
+
+  onClickOutside(dropdownRef, () => closeDropdown(true), { ignore: [triggerRef] })
+
+  useEventListener(dropdownRef, 'mousemove', () => stopKeyboardNavigation())
+
+  /* DROPDOWN PLACEMENT */
+
+  const { floatingStyles } = useFloating(triggerRef, dropdownRef, {
+    placement: 'bottom-start',
+    open: isOpen,
+  })
+
+  /* SEARCH */
+
+  watch(config.searchTerm, () => stopKeyboardNavigation())
+
+  const searchRef = ref<MaybeElement<HTMLElement> & { focus?: () => void }>()
+
+  function focusSearch() {
+    if (!searchRef.value?.focus) {
+      return false
+    }
+
+    searchRef.value.focus()
+
+    return true
+  }
+
+  whenever(isOpen, () => focusSearch(), { flush: 'post' })
+
+  const currentIndex = computed(() => options.value.findIndex(option => option.flags.active))
+
+  whenever(options, () => moveToOptionIndex('first'), { flush: 'post' })
+
+  ifElse(isOpen, () => moveToOptionIndex('selected'), clear, { flush: 'post' })
+
+  function openDropdown() {
+    if (!isOpen.value) {
+      isOpen.value = true
+    }
+  }
+
+  function closeDropdown(keepFocus: boolean) {
+    if (!isOpen.value) {
+      return
+    }
+
+    isOpen.value = false
+
+    if (keepFocus) {
+      focusTrigger()
+    }
+  }
+
+  function clear() {
+    if (config.searchTerm.value !== undefined) {
+      config.searchTerm.value = ''
+    }
+  }
+
+  const boundaryIndexes = computed(() => {
+    let firstIndex: number | undefined
+    let lastIndex: number | undefined
+
+    options.value.forEach((option, index) => {
+      if (option.properties.disabled) {
+        return
+      }
+
+      if (firstIndex === undefined) {
+        firstIndex = index
+      }
+
+      lastIndex = index
+    })
+
+    if (firstIndex === undefined || lastIndex === undefined) {
+      return undefined
+    }
+
+    return {
+      first: firstIndex,
+      last: lastIndex,
+    }
+  })
+
+  function parseIndex(index: FormOptionIndex): number {
+    switch (index) {
+      case 'previous':
+        return currentIndex.value - 1
+      case 'next':
+        return currentIndex.value + 1
+      case 'previous-page':
+        return currentIndex.value - 7 // TODO: Better handle page size.
+      case 'next-page':
+        return currentIndex.value + 7 // TODO: Better handle page size.
+      case 'first':
+        return 0
+      case 'last':
+        return options.value.length - 1
+      case 'selected':
+        return options.value.findIndex(option => option.flags.selected)
+      default:
+        return index
+    }
+  }
+
+  function moveToOptionIndex(_index: FormOptionIndex) {
+    if (boundaryIndexes.value === undefined) {
+      activeOption.value?.toggleFlag('active', false)
+      return
+    }
+
+    const index = clamp(parseIndex(_index), boundaryIndexes.value.first, boundaryIndexes.value.last)
+
+    options.value[getClosestEnabledIndex(index)]?.toggleFlag('active', true)
+  }
+
+  function getClosestEnabledIndex(expectedIndex: number) {
+    let index = expectedIndex
+
+    const direction = expectedIndex < currentIndex.value ? -1 : 1
+
+    while (options.value[index]?.properties.disabled) {
+      index += direction
+    }
+
+    return index
+  }
+
+  function focusSearchOrTrigger() {
+    if (!focusSearch()) {
+      focusTrigger()
+    }
+  }
+
+  provide(
+    IK_FORM_SELECT_CONTROLLER,
+    reactive({
+      isNavigatingWithKeyboard,
+      focusSearchOrTrigger,
+      closeDropdown,
+    })
+  )
+
+  return {
+    triggerRef,
+    dropdownRef,
+    searchRef,
+    openDropdown,
+    closeDropdown,
+    isOpen,
+    floatingStyles,
+  }
+}