@xen-orchestra/web-core 0.17.0 → 0.19.0

package/lib/packages/collection/README.md

@@ -0,0 +1,167 @@
+# `useCollection` composable
+
+The `useCollection` composable helps you manage a collection of items with flags (boolean states) and computed properties. It provides a type-safe way to filter, flag, and manipulate items in a collection.
+
+## Usage
+
+```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}`),
+  }),
+})
+```
+
+## 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**: Computed values derived from the source object
+
+## `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) |
+
+### `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  |
+
+### `FlagsConfig` type
+
+```typescript
+type FlagsConfig<TFlag extends string> = TFlag[] | { [K in TFlag]: { multiple?: boolean } }
+```
+
+Values for `multiple`:
+
+- `true` (default): multiple items can have 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                        |
+
+### `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                      |
+
+### Return value of `useFlag(flag)`
+
+| 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        |
+
+## Flag Operations
+
+The composable provides several ways to work with flags:
+
+### Setting and Toggling Flags
+
+You can work with flags directly on collection items:
+
+```typescript
+// Set flag for a single item
+item.flags.selected = true
+
+// Toggle the 'selected' flag on an item
+// Same as item.flags.selected = !item.flags.selected
+item.toggleFlag('selected')
+
+// Force the 'selected' flag to a specific value
+// Same as item.flags.selected = true
+item.toggleFlag('selected', true)
+```
+
+You can also use the utilities provided by `useFlag`:
+
+```typescript
+// Get utilities for the 'selected' flag
+const { toggle: toggleSelected, toggleAll: toggleAllSelected } = useFlag('selected')
+
+// Toggle flag for a specific item
+toggleSelected(itemId)
+
+// Force flag to true for a specific item
+toggleSelected(itemId, true)
+
+// Toggle flag on all items
+toggleAllSelected()
+
+// Force all items to have the flag
+toggleAllSelected(true)
+```
+
+### Checking Flags
+
+You can check if an item has a flag:
+
+```typescript
+// Check if an item has a specific flag
+const isSelected = item.flags.selected
+```
+
+## Example
+
+```typescript
+const {
+  items: users,
+  useSubset,
+  count,
+} = useCollection(rawUsers, {
+  identifier: user => user.id,
+  flags: ['selected'],
+  properties: user => ({
+    fullName: computed(() => `${user.firstName} ${user.lastName} (${user.group})`),
+  }),
+})
+
+const { items: admins, useFlag: useAdminFlag, count: adminCount } = useSubset(item => item.source.group === 'admin')
+
+const {
+  items: selectedAdmins,
+  areAllOn: areAllAdminSelected,
+  toggleAll: toggleAllAdminSelection,
+  count: selectedAdminCount,
+  toggle: toggleAdminSelection,
+} = useAdminFlag('selected')
+```
+
+It's also possible to create a subset of subset:
+
+```typescript
+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')
+```

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

@@ -0,0 +1,45 @@
+import type { CollectionItem, CollectionOptions, FlagRegistry } from '@core/packages/collection'
+import { unref, type UnwrapRef } from 'vue'
+
+export function buildItem<
+  TSource,
+  TId extends PropertyKey,
+  TFlag extends string,
+  TProperties extends Record<string, unknown>,
+>(
+  source: TSource,
+  options: CollectionOptions<TSource, TId, TFlag, TProperties>,
+  flagRegistry: FlagRegistry<TFlag>
+): CollectionItem<TSource, TId, TFlag, UnwrapRef<TProperties>> {
+  const id = options.identifier(source)
+  const properties = options.properties?.(source)
+
+  return {
+    id,
+    source,
+    toggleFlag(flag: TFlag, forcedValue?: boolean) {
+      flagRegistry.toggleFlag(id, flag, forcedValue)
+    },
+    flags: new Proxy({} as Record<TFlag, boolean>, {
+      has(target, flag: TFlag) {
+        return flagRegistry.isFlagDefined(flag)
+      },
+      get(target, flag: TFlag) {
+        return flagRegistry.isFlagged(id, flag)
+      },
+      set(target, flag: TFlag, value) {
+        flagRegistry.toggleFlag(id, flag, value)
+
+        return true
+      },
+    }),
+    properties: new Proxy({} as UnwrapRef<TProperties>, {
+      has(target, prop: Extract<keyof TProperties, string>) {
+        return properties !== undefined && prop in properties
+      },
+      get(target, prop: Extract<keyof TProperties, string>) {
+        return unref(properties?.[prop])
+      },
+    }),
+  }
+}

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

@@ -0,0 +1,60 @@
+import type { CollectionItem, FlagRegistry } from '@core/packages/collection'
+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) {
+    const flaggedItems = useArrayFilter(items, item => item.flags[flag])
+
+    const ids = useArrayMap(flaggedItems, item => item.id)
+
+    const count = computed(() => flaggedItems.value.length)
+
+    const areAllOn = computed(() => items.value.length === count.value)
+
+    const areSomeOn = computed(() => count.value > 0)
+
+    const areNoneOn = computed(() => count.value === 0)
+
+    function toggle(id: TId, forcedValue?: boolean) {
+      flagRegistry.toggleFlag(id, flag, forcedValue)
+    }
+
+    function toggleAll(forcedValue = !areAllOn.value) {
+      for (const item of items.value) {
+        flagRegistry.toggleFlag(item.id, flag, forcedValue)
+      }
+    }
+
+    return {
+      items: flaggedItems,
+      ids,
+      count,
+      areAllOn,
+      areSomeOn,
+      areNoneOn,
+      toggle,
+      toggleAll,
+    }
+  }
+
+  function useSubset(filter: (item: CollectionItem<TSource, TId, TFlag, TProperties>) => boolean) {
+    const filteredItems = useArrayFilter(items, item => filter(item))
+
+    return createCollection(filteredItems, flagRegistry)
+  }
+
+  const count = computed(() => items.value.length)
+
+  return {
+    items,
+    count,
+    useFlag,
+    useSubset,
+  }
+}

package/lib/packages/collection/index.ts

@@ -0,0 +1,5 @@
+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

@@ -0,0 +1,29 @@
+import type { useFlagRegistry } from '@core/packages/collection'
+
+export type FlagsConfig<TFlag extends string> = TFlag[] | { [K in TFlag]: { multiple?: boolean } }
+
+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 CollectionItem<
+  TSource,
+  TId extends PropertyKey,
+  TFlag extends string,
+  TProperties extends Record<string, any>,
+> = {
+  id: TId
+  source: TSource
+  flags: Record<TFlag, boolean>
+  properties: TProperties
+  toggleFlag: (flag: TFlag, forcedValue?: boolean) => void
+}
+
+export type FlagRegistry<TFlag extends string> = ReturnType<typeof useFlagRegistry<TFlag>>

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

@@ -0,0 +1,15 @@
+import { buildItem, type CollectionOptions, createCollection, useFlagRegistry } from '@core/packages/collection'
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+
+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)
+
+  const items = computed(() => toValue(sources).map(source => buildItem(source, options, flagRegistry)))
+
+  return createCollection(items, flagRegistry)
+}

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

@@ -0,0 +1,47 @@
+import type { FlagsConfig } 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>
+
+  const flags = Array.isArray(_flags) ? Object.fromEntries(_flags.map(flag => [flag, { multiple: true }])) : _flags
+
+  function isFlagDefined(flag: TFlag) {
+    return flags[flag] !== undefined
+  }
+
+  function isFlagged(id: PropertyKey, flag: TFlag) {
+    return registry.get(flag)?.has(id) ?? false
+  }
+
+  function toggleFlag(id: PropertyKey, flag: TFlag, forcedValue = !isFlagged(id, 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) {
+    registry.set(flag, new Set())
+  }
+
+  function isMultipleAllowed(flag: TFlag) {
+    return flags[flag]?.multiple ?? false
+  }
+
+  return {
+    isFlagged,
+    isFlagDefined,
+    toggleFlag,
+    clearFlag,
+    isMultipleAllowed,
+  }
+}

package/lib/utils/time.util.ts

@@ -0,0 +1,18 @@
+import { utcParse } from 'd3-time-format'
+
+export function parseDateTime(dateTime: Date | string | number): number {
+  if (typeof dateTime === 'number') {
+    return dateTime
+  }
+
+  if (dateTime instanceof Date) {
+    return dateTime.getTime()
+  }
+
+  dateTime = dateTime.replace(/(-|\.\d{3})/g, '') // Allow toISOString() date-time format
+  const date = utcParse('%Y%m%dT%H:%M:%SZ')(dateTime)
+  if (date === null) {
+    throw new RangeError(`unable to parse XAPI datetime ${JSON.stringify(dateTime)}`)
+  }
+  return date.getTime()
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xen-orchestra/web-core",
   "type": "module",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "private": false,
   "exports": {
     "./*": {