@xen-orchestra/web-core 0.20.1 → 0.21.0

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

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

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

@@ -0,0 +1,23 @@
+import { createCollection } from '@core/packages/collection/create-collection.ts'
+import type {
+  Collection,
+  CollectionItem,
+  CollectionItemId,
+  CollectionItemProperties,
+  FlagRegistry,
+} from '@core/packages/collection/types.ts'
+import type { ArrayFilterPredicate } from '@core/types/utility.type.ts'
+import { useArrayFilter } from '@vueuse/core'
+import type { ComputedRef } from 'vue'
+
+export function createUseSubset<
+  TSource,
+  TFlag extends string,
+  TProperties extends CollectionItemProperties,
+  TId extends CollectionItemId,
+  $TItem extends CollectionItem<TSource, TFlag, TProperties, TId> = CollectionItem<TSource, TFlag, TProperties, TId>,
+>(items: ComputedRef<$TItem[]>, flagRegistry: FlagRegistry<TId, TFlag>) {
+  return function useSubset(filter: ArrayFilterPredicate<$TItem>): Collection<TSource, TFlag, TProperties, TId> {
+    return createCollection(useArrayFilter(items, filter), flagRegistry)
+  }
+}

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

@@ -1,26 +1,36 @@
-import type { CollectionConfigProperties, GuessItemId } from '@core/packages/collection/types.ts'
+import { hasObjectProperty } from '@core/utils/object.util.ts'
+import type { CollectionItemId, GetItemId } from './types.ts'
 
-function assertValidId(id: unknown): asserts id is PropertyKey {
-  const type = typeof id
+export function guessItemId<TSource>(source: TSource, getter: GetItemId<TSource>): CollectionItemId {
+  const id = extractItemId(source, getter)
 
-  if (!['string', 'number', 'symbol'].includes(type)) {
-    throw new TypeError(`Invalid ID type: ${type}. Expected string, number, or bigint.`)
+  if (isCollectionId(id)) {
+    return id
   }
+
+  throw new Error(`Unable to guess id from source: ${JSON.stringify(source)}`)
+}
+
+function isCollectionId(value: unknown): value is CollectionItemId {
+  return typeof value === 'string' || typeof value === 'number'
 }
 
-export function guessItemId<TSource, TProperties extends CollectionConfigProperties>(
-  source: TSource,
-  properties: TProperties | undefined
-) {
-  let id
+function extractItemId<TSource>(source: TSource, getter: GetItemId<TSource>) {
+  if (getter === undefined) {
+    if (hasObjectProperty(source, 'id')) {
+      return source.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
+    return source
   }
 
-  assertValidId(id)
+  if (typeof getter === 'function') {
+    return getter(source)
+  }
+
+  if (hasObjectProperty(source, getter)) {
+    return source[getter]
+  }
 
-  return id as GuessItemId<TSource, TProperties>
+  throw new Error(`Property "${String(getter)}" not found in source: ${JSON.stringify(source)}`)
 }

package/lib/packages/collection/index.ts

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

package/lib/packages/collection/types.ts

@@ -1,57 +1,85 @@
-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 }>
+import type { ArrayFilterPredicate, KeyOfByValue } from '@core/types/utility.type.ts'
+import type { ComputedRef, MaybeRefOrGetter, Reactive } from 'vue'
 
 export type CollectionItem<
-  TSource,
-  TFlag extends string = never,
-  TProperties extends CollectionConfigProperties = Record<string, never>,
+  TSource = unknown,
+  TFlag extends string = string,
+  TProperties extends CollectionItemProperties = CollectionItemProperties,
+  TId extends CollectionItemId = PickSourceId<TSource, 'id'>,
 > = {
-  id: GuessItemId<TSource, Reactive<TProperties>>
+  id: TId
   source: TSource
   flags: Record<TFlag, boolean>
   properties: Reactive<TProperties>
-  toggleFlag: (flag: TFlag, forcedValue?: boolean) => void
+  toggleFlag: (flag: TFlag, shouldBeFlagged?: boolean) => void
+}
+
+export type Collection<
+  TSource = unknown,
+  TFlag extends string = string,
+  TProperties extends CollectionItemProperties = CollectionItemProperties,
+  TId extends CollectionItemId = PickSourceId<TSource, 'id'>,
+  $TItem extends CollectionItem<TSource, TFlag, TProperties, TId> = CollectionItem<TSource, TFlag, TProperties, TId>,
+> = {
+  items: ComputedRef<$TItem[]>
+  count: ComputedRef<number>
+  useFlag: (flag: TFlag) => UseFlagReturn<TSource, TFlag, TProperties, TId>
+  toggleFlag: (id: TId, flag: TFlag, shouldBeFlagged?: boolean) => void
+  useSubset: (filter: ArrayFilterPredicate<$TItem>) => Collection<TSource, TFlag, TProperties, TId>
+}
+
+export type CollectionItemProperties = Record<PropertyKey, unknown>
+
+export type CollectionItemId = string | number
+
+export type PickSourceId<TSource, TKey> = TKey extends keyof TSource
+  ? TSource[TKey] extends CollectionItemId
+    ? TSource[TKey]
+    : never
+  : never
+
+export type ExtractSourceId<TSource, TGetId extends GetItemId<TSource>> = TGetId extends keyof TSource
+  ? PickSourceId<TSource, TGetId>
+  : TGetId extends (source: TSource) => infer R
+    ? R
+    : TSource extends CollectionItemId
+      ? TSource
+      : PickSourceId<TSource, 'id'>
+
+export type FlagConfig = {
+  multiple?: MaybeRefOrGetter<boolean>
 }
 
-export type FlagRegistry<TFlag extends string> = {
-  isFlagged: (id: PropertyKey, flag: TFlag) => boolean
+export type CollectionConfigFlags<TFlag extends string> = TFlag[] | Record<TFlag, FlagConfig>
+
+export type FlagRegistry<TId extends CollectionItemId, TFlag extends string> = {
+  isFlagged: (id: TId, flag: TFlag) => boolean
   isFlagDefined: (flag: TFlag) => boolean
-  toggleFlag: (id: PropertyKey, flag: TFlag, forcedValue?: boolean) => void
+  toggleFlag: (id: TId, flag: TFlag, shouldBeFlagged?: 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>[]>
+export type UseFlagReturn<
+  TSource,
+  TFlag extends string,
+  TProperties extends CollectionItemProperties,
+  TId extends CollectionItemId,
+  $TItem extends CollectionItem<TSource, TFlag, TProperties, TId> = CollectionItem<TSource, TFlag, TProperties, TId>,
+> = {
+  items: ComputedRef<$TItem[]>
+  ids: ComputedRef<TId[]>
   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>
+  toggle: (id: TId, shouldBeFlagged?: boolean) => void
+  toggleAll: (shouldBeFlagged?: boolean) => void
+  useSubset: (filter: ArrayFilterPredicate<$TItem>) => Collection<TSource, TFlag, TProperties, TId>
 }
 
-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
+export type GetItemId<TSource> =
+  | undefined
+  | KeyOfByValue<TSource, CollectionItemId>
+  | ((source: TSource) => CollectionItemId)

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

@@ -1,47 +1,97 @@
-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 { guessItemId } from '@core/packages/collection/guess-item-id.ts'
+import type { EmptyObject } from '@core/types/utility.type.ts'
+import type {
+  Collection,
+  CollectionConfigFlags,
+  CollectionItemId,
+  CollectionItemProperties,
+  ExtractSourceId,
+  GetItemId,
+} from './types.ts'
 import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+import { createCollection } from './create-collection.ts'
+import { createItem } from './create-item.ts'
+import { useFlagRegistry } from './use-flag-registry.ts'
+
+// Overload #1: Source is CollectionItemId
+
+export function useCollection<
+  TSource extends CollectionItemId,
+  TFlag extends string = never,
+  TProperties extends CollectionItemProperties = EmptyObject,
+  TGetId extends ((source: TSource) => CollectionItemId) | undefined = undefined,
+  $TId extends CollectionItemId = ExtractSourceId<TSource, TGetId>,
+>(
+  source: MaybeRefOrGetter<TSource[]>,
+  config?: {
+    itemId?: TGetId | ((source: TSource) => CollectionItemId)
+    flags?: CollectionConfigFlags<TFlag>
+    properties?: (source: TSource) => TProperties
+  }
+): Collection<TSource, TFlag, TProperties, $TId>
+
+// Overload #2: Source is an object with id
 
 export function useCollection<
-  TSource extends { id: unknown },
+  TSource extends { id: CollectionItemId },
   TFlag extends string = never,
-  TProperties extends CollectionConfigProperties = { id?: unknown },
+  TProperties extends CollectionItemProperties = EmptyObject,
+  TGetId extends GetItemId<TSource> = undefined,
+  $TId extends CollectionItemId = ExtractSourceId<TSource, TGetId>,
 >(
-  sources: MaybeRefOrGetter<TSource[]>,
+  source: MaybeRefOrGetter<TSource[]>,
   config?: {
+    itemId?: TGetId | ((source: TSource) => CollectionItemId)
     flags?: CollectionConfigFlags<TFlag>
     properties?: (source: TSource) => TProperties
   }
-): Collection<TSource, TFlag, TProperties>
+): Collection<TSource, TFlag, TProperties, $TId>
+
+// Overload #3: Any other case
 
 export function useCollection<
   TSource,
   TFlag extends string = never,
-  TProperties extends CollectionConfigProperties & { id: unknown } = never,
+  TProperties extends CollectionItemProperties = EmptyObject,
+  TGetId extends GetItemId<TSource> = never,
+  $TId extends CollectionItemId = ExtractSourceId<TSource, TGetId>,
 >(
-  sources: MaybeRefOrGetter<TSource[]>,
+  source: MaybeRefOrGetter<TSource[]>,
   config: {
+    itemId: TGetId | ((source: TSource) => CollectionItemId)
     flags?: CollectionConfigFlags<TFlag>
-    properties: (source: TSource) => TProperties
+    properties?: (source: TSource) => TProperties
   }
-): Collection<TSource, TFlag, TProperties>
+): Collection<TSource, TFlag, TProperties, $TId>
+
+// Implementation
 
 export function useCollection<
   TSource,
-  TFlag extends string = never,
-  TProperties extends CollectionConfigProperties = { id?: unknown },
+  TFlag extends string,
+  TProperties extends CollectionItemProperties,
+  TGetId extends GetItemId<TSource>,
+  $TId extends CollectionItemId,
 >(
-  sources: MaybeRefOrGetter<TSource[]>,
+  _sources: MaybeRefOrGetter<TSource[]>,
   config?: {
+    itemId?: TGetId
     flags?: CollectionConfigFlags<TFlag>
     properties?: (source: TSource) => TProperties
   }
-): Collection<TSource, TFlag, TProperties> {
-  const flagRegistry = useFlagRegistry(config?.flags)
+): Collection<TSource, TFlag, TProperties, $TId> {
+  const flagRegistry = useFlagRegistry<TFlag, $TId>(config?.flags)
+
+  const sources = computed(() => toValue(_sources))
+
+  const items = computed(() =>
+    sources.value.map(source => {
+      const id = guessItemId(source, config?.itemId) as $TId
+      const properties = config?.properties?.(source) ?? ({} as TProperties)
 
-  const items = computed(() => toValue(sources).map(source => createItem(source, config?.properties, flagRegistry)))
+      return createItem<TSource, TFlag, TProperties, $TId>(id, source, properties, flagRegistry)
+    })
+  )
 
   return createCollection(items, flagRegistry)
 }

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

@@ -1,12 +1,21 @@
-import type { CollectionConfigFlags, FlagRegistry } from '@core/packages/collection/types.ts'
-import { reactive } from 'vue'
+import { objectFromEntries, objectEntries } from '@core/utils/object.util.ts'
+import type { CollectionConfigFlags, CollectionItemId, FlagConfig, FlagRegistry } from './types.ts'
+import { isRef, reactive, toValue, watch } from 'vue'
 
-export function useFlagRegistry<TFlag extends string>(
+export function useFlagRegistry<TFlag extends string, TId extends CollectionItemId>(
   config: CollectionConfigFlags<TFlag> = [] as TFlag[]
-): FlagRegistry<TFlag> {
-  const registry = reactive(new Map<TFlag, Set<PropertyKey>>())
+): FlagRegistry<TId, TFlag> {
+  const registry = reactive(new Map()) as Map<TFlag, Set<TId>>
 
-  const flags = Array.isArray(config) ? Object.fromEntries(config.map(flag => [flag, { multiple: true }])) : config
+  const flags = Array.isArray(config)
+    ? objectFromEntries(config.map(flag => [flag, { multiple: true } as FlagConfig]))
+    : config
+
+  for (const [flag, { multiple }] of objectEntries(flags)) {
+    if (isRef(multiple)) {
+      watch(multiple, () => clearFlag(flag))
+    }
+  }
 
   function isFlagDefined(flag: TFlag) {
     return Object.prototype.hasOwnProperty.call(flags, flag)
@@ -18,39 +27,51 @@ export function useFlagRegistry<TFlag extends string>(
     }
   }
 
-  function isFlagged(id: PropertyKey, flag: TFlag) {
+  function isFlagged(id: TId, flag: TFlag) {
     assertFlag(flag)
 
     return registry.get(flag)?.has(id) ?? false
   }
 
-  function toggleFlag(id: PropertyKey, flag: TFlag, forcedValue = !isFlagged(id, flag)) {
+  function toggleFlag(id: TId, flag: TFlag, shouldBeFlagged = !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)
+    const flagSet = registry.get(flag)!
+
+    if (shouldBeFlagged === flagSet.has(id)) {
+      return
+    }
+
+    if (!shouldBeFlagged) {
+      flagSet.delete(id)
+      return
     }
+
+    if (!isMultipleAllowed(flag) && flagSet.size > 0) {
+      clearFlag(flag)
+    }
+
+    flagSet.add(id)
   }
 
   function clearFlag(flag: TFlag) {
     assertFlag(flag)
 
-    registry.set(flag, new Set())
+    if (!registry.has(flag) || registry.get(flag)!.size === 0) {
+      return
+    }
+
+    registry.get(flag)!.clear()
   }
 
   function isMultipleAllowed(flag: TFlag) {
     assertFlag(flag)
 
-    return flags[flag]?.multiple ?? false
+    return toValue(flags[flag]?.multiple) ?? true
   }
 
   return {

package/lib/packages/form-select/guess-label.ts

@@ -0,0 +1,45 @@
+import type { CollectionItemProperties } from '@core/packages/collection'
+import { hasObjectProperty } from '@core/utils/object.util.ts'
+import type { GetOptionLabel } from './types.ts'
+
+export function guessLabel<TSource, TCustomProperties extends CollectionItemProperties>(
+  source: TSource,
+  extraProperties: TCustomProperties,
+  getter: GetOptionLabel<TSource, TCustomProperties>
+): string {
+  const label = extractLabel(source, extraProperties, getter)
+
+  if (typeof label === 'string' || typeof label === 'number') {
+    return label.toString()
+  }
+
+  throw new Error(`Unable to guess label from source: ${JSON.stringify(source)}`)
+}
+
+export function extractLabel<TSource, TCustomProperties extends CollectionItemProperties>(
+  source: TSource,
+  extraProperties: TCustomProperties,
+  getter: undefined | keyof TSource | ((source: TSource, properties: TCustomProperties) => string)
+): unknown {
+  if (getter === undefined) {
+    if (hasObjectProperty(source, 'label')) {
+      return source.label
+    }
+
+    return source
+  }
+
+  if (typeof getter === 'function') {
+    return getter(source, extraProperties)
+  }
+
+  if (hasObjectProperty(source, getter)) {
+    return source[getter]
+  }
+
+  if (source === undefined) {
+    return ''
+  }
+
+  throw new Error(`Property "${String(getter)}" not found in source: ${JSON.stringify(source)}`)
+}

package/lib/packages/form-select/guess-value.ts

@@ -0,0 +1,23 @@
+import type { CollectionItemProperties } from '@core/packages/collection'
+import { hasObjectProperty } from '@core/utils/object.util.ts'
+import type { GetOptionValue } from './types.ts'
+
+export function guessValue<TSource, TValue, TCustomProperties extends CollectionItemProperties>(
+  source: TSource,
+  customProperties: TCustomProperties,
+  getter: GetOptionValue<TSource, TCustomProperties>
+): TValue {
+  if (getter === undefined) {
+    return source as unknown as TValue
+  }
+
+  if (typeof getter === 'function') {
+    return getter(source, customProperties) as TValue
+  }
+
+  if (hasObjectProperty(source, getter)) {
+    return source[getter] as TValue
+  }
+
+  throw new Error(`Property "${String(getter)}" not found in source: ${JSON.stringify(source)}`)
+}

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

@@ -1,2 +1,8 @@
+export * from './guess-label.ts'
+export * from './guess-value.ts'
+export * from './normalize-search-term.ts'
 export * from './types.ts'
+export * from './use-form-option-controller.ts'
 export * from './use-form-select.ts'
+export * from './use-form-select-controller.ts'
+export * from './use-form-select-keyboard-navigation.ts'

package/lib/packages/form-select/normalize-search-term.ts

@@ -0,0 +1,11 @@
+import { toValue } from 'vue'
+
+export function normalizeSearchTerm(value: unknown): string {
+  const term = toValue(value)
+
+  if (term === undefined || term === null) {
+    return ''
+  }
+
+  return String(term).toLocaleLowerCase().trim()
+}