@xen-orchestra/web-core 0.20.0 → 0.21.0

package/lib/packages/collection/README.md

@@ -6,9 +6,9 @@ The `useCollection` composable helps you manage a collection of items with flags
 
 ```typescript
 const { items, useSubset, useFlag } = useCollection(sources, {
+  itemId: source => source.theId, // Required only if TSource doesn't have an `id` property
   flags: ['selected', 'active', { highlighted: { multiple: false } }],
   properties: source => ({
-    id: source.theId, // Required if TSource doesn't have an `id` property
     isAvailable: source.status === 'available',
     fullName: `${source.firstName} ${source.lastName}`,
   }),
@@ -18,8 +18,8 @@ const { items, useSubset, useFlag } = useCollection(sources, {
 ## Core Concepts
 
 - **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**: Additional custom values
+- **Flags**: Arbitrary `boolean` states attached to items (like `selected`, `active`, `highlighted`, etc.)
+- **Properties**: Additional custom values attached to items, computed from the source object (like `fullName`, `isAvailable`, etc.)
 
 ## `useCollection` parameters
 
@@ -30,21 +30,22 @@ const { items, useSubset, useFlag } = useCollection(sources, {
 
 ### `options` object
 
-| 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) |
+| Name         | Type                                           | Required | Description                                                                                     |
+| ------------ | ---------------------------------------------- | :------: | ----------------------------------------------------------------------------------------------- |
+| `itemId`     | `keyof TSource \| ((source: TSource) => TId)`  |    ~     | Function to retrieve the item ID or property of TSource (if not provided, `TSource.id` is used) |
+| `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`
+If `TSource` doesn't provide an `id`, then `options.itemId` will be required.
 
 ### `FlagsConfig` type
 
 ```typescript
-type FlagsConfig<TFlag extends string> = TFlag[] | { [K in TFlag]: { multiple?: boolean } }
+type FlagsConfig = string[] | Record<string, { multiple?: MaybeRef<boolean> }>
 ```
 
 Values for `multiple`:
@@ -63,13 +64,13 @@ Values for `multiple`:
 
 ### `CollectionItem` object
 
-| Name         | Type                           | Description                                               |
-| ------------ | ------------------------------ | --------------------------------------------------------- |
-| `id`         | `TId`                          | Unique identifier for the item (string, number or symbol) |
-| `source`     | `TSource`                      | The original source object                                |
-| `flags`      | `Record<TFlag, boolean>`       | Object containing the state of all flags for this item    |
-| `properties` | `TProperties`                  | Object containing all computed properties for this item   |
-| `toggleFlag` | `(flag, forcedValue?) => void` | Method to toggle a flag on this item                      |
+| Name         | Type                               | Description                                               |
+| ------------ | ---------------------------------- | --------------------------------------------------------- |
+| `id`         | `TId`                              | Unique identifier for the item (string, number or symbol) |
+| `source`     | `TSource`                          | The original source object                                |
+| `flags`      | `Record<TFlag, boolean>`           | Object containing the state of all flags for this item    |
+| `properties` | `TProperties`                      | Object containing all computed properties for this item   |
+| `toggleFlag` | `(flag, shouldBeFlagged?) => void` | Method to toggle a flag on this item                      |
 
 ### UseFlagReturn object
 
@@ -81,8 +82,8 @@ Values for `multiple`:
 | `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        |
+| `toggle`    | `(id, shouldBeFlagged?) => void`            | Toggle this flag on a specific item                    |
+| `toggleAll` | `(shouldBeFlagged?) => void`                | Toggle this flag on all items in the collection        |
 | `useSubset` | `(filter: (item) => boolean) => Collection` | Creates a sub collection matching the filter           |
 
 ## Flag Operations
@@ -169,4 +170,8 @@ const { items: users, useSubset } = useCollection(rawUsers, {
 const { items: admins, useSubset: useAdminSubset } = useSubset(item => item.source.group === 'admin')
 
 const { items: activeAdmins } = useAdminSubset(item => item.source.status === 'active')
+
+// This would be equivalent to:
+
+const { items: activeAdmins } = useSubset(item => item.source.group === 'admin' && item.source.status === 'active')
 ```

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

@@ -1,19 +1,23 @@
+import { createUseSubset } from '@core/packages/collection/create-use-subset.ts'
 import type {
   Collection,
-  CollectionConfigProperties,
   CollectionItem,
+  CollectionItemId,
+  CollectionItemProperties,
   FlagRegistry,
-  GuessItemId,
   UseFlagReturn,
-} from '@core/packages/collection/types.ts'
+} from './types.ts'
 import { useArrayFilter, useArrayMap } from '@vueuse/core'
 import { computed, type ComputedRef } from 'vue'
 
-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> {
+export function createCollection<
+  TSource,
+  TFlag extends string,
+  TProperties extends CollectionItemProperties,
+  TId extends CollectionItemId,
+  $TItem extends CollectionItem<TSource, TFlag, TProperties, TId>,
+>(items: ComputedRef<$TItem[]>, flagRegistry: FlagRegistry<TId, TFlag>): Collection<TSource, TFlag, TProperties, TId> {
+  function useFlag(flag: TFlag): UseFlagReturn<TSource, TFlag, TProperties, TId> {
     flagRegistry.assertFlag(flag)
 
     const flaggedItems = useArrayFilter(items, item => item.flags[flag])
@@ -28,21 +32,17 @@ export function createCollection<TSource, TFlag extends string, TProperties exte
 
     const areNoneOn = computed(() => count.value === 0)
 
-    function toggle(id: GuessItemId<TSource, TProperties>, forcedValue?: boolean) {
-      flagRegistry.toggleFlag(id, flag, forcedValue)
+    function toggle(id: TId, shouldBeFlagged?: boolean) {
+      flagRegistry.toggleFlag(id, flag, shouldBeFlagged)
     }
 
-    function toggleAll(forcedValue = !areAllOn.value) {
+    function toggleAll(shouldBeFlagged = !areAllOn.value) {
       for (const item of items.value) {
-        flagRegistry.toggleFlag(item.id, flag, forcedValue)
+        flagRegistry.toggleFlag(item.id, flag, shouldBeFlagged)
       }
     }
 
-    function useSubset(
-      filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
-    ): Collection<TSource, TFlag, TProperties> {
-      return createCollection(useArrayFilter(flaggedItems, filter), flagRegistry)
-    }
+    const useSubset = createUseSubset<TSource, TFlag, TProperties, TId>(flaggedItems, flagRegistry)
 
     return {
       items: flaggedItems,
@@ -57,18 +57,19 @@ export function createCollection<TSource, TFlag extends string, TProperties exte
     }
   }
 
-  function useSubset(
-    filter: (item: CollectionItem<TSource, TFlag, TProperties>) => boolean
-  ): Collection<TSource, TFlag, TProperties> {
-    return createCollection(useArrayFilter(items, filter), flagRegistry)
+  function toggleFlag(id: TId, flag: TFlag, shouldBeFlagged?: boolean) {
+    flagRegistry.toggleFlag(id, flag, shouldBeFlagged)
   }
 
+  const useSubset = createUseSubset<TSource, TFlag, TProperties, TId>(items, flagRegistry)
+
   const count = computed(() => items.value.length)
 
   return {
     items,
     count,
     useFlag,
+    toggleFlag,
     useSubset,
   }
 }

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 {