@xen-orchestra/web-core 0.26.1 → 0.28.0

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

@@ -7,34 +7,33 @@ import {
 } from '@core/packages/collection'
 import type { EmptyObject, MaybeArray } from '@core/types/utility.type.ts'
 import { toArray } from '@core/utils/to-array.utils.ts'
-import type {
-  ExtractValue,
-  FormOptionCollectionItemProperties,
-  FormSelect,
-  FormSelectId,
-  GetOptionLabel,
-  GetOptionValue,
-  UseFormSelectReturn,
-} from './types.ts'
-import { computed, type ComputedRef, type MaybeRefOrGetter, provide, ref, type Ref, toValue, watch } from 'vue'
+import { computed, type ComputedRef, type MaybeRefOrGetter, provide, ref, type Ref, toRaw, toValue, watch } from 'vue'
 import { guessLabel } from './guess-label.ts'
 import { guessValue } from './guess-value.ts'
 import { normalizeSearchTerm } from './normalize-search-term.ts'
+import {
+  EMPTY_OPTION,
+  type ExtractValue,
+  type FormOptionCollectionItemProperties,
+  type FormSelect,
+  type FormSelectId,
+  type GetOptionLabel,
+  type GetOptionValue,
+  type UseFormSelectReturn,
+} from './types.ts'
 
 // Overload #1: Source is CollectionItemId
 
 export function useFormSelect<
-  TBaseSource extends CollectionItemId,
-  TAllowEmpty extends boolean = false,
+  TSource extends CollectionItemId,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -44,32 +43,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #2: Source is an object with id and label
 
 export function useFormSelect<
-  TBaseSource extends { id: CollectionItemId; label: string },
-  TAllowEmpty extends boolean = false,
+  TSource extends { id: CollectionItemId; label: string },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -79,32 +82,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #3: Source is an object with id only
 
 export function useFormSelect<
-  TBaseSource extends { id: CollectionItemId },
-  TAllowEmpty extends boolean = false,
+  TSource extends { id: CollectionItemId },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -114,32 +121,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id?: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #4: Source is an object with label only
 
 export function useFormSelect<
-  TBaseSource extends { label: string },
-  TAllowEmpty extends boolean = false,
+  TSource extends { label: string },
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -149,32 +160,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Overload #5: Any other case
 
 export function useFormSelect<
-  TBaseSource,
-  TAllowEmpty extends boolean = false,
+  TSource,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  sources: MaybeRefOrGetter<TBaseSource[]>,
+  sources: MaybeRefOrGetter<TSource[]>,
   config: {
-    allowEmpty?: MaybeRefOrGetter<TAllowEmpty>
     multiple?: MaybeRefOrGetter<TMultiple>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -184,32 +199,36 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option: {
-      id: GetItemId<TBaseSource>
-      value?: TGetValue | ((source: $TSource, properties: TCustomProperties) => $TValue)
-      properties?: (source: $TSource) => TCustomProperties
-      label: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id: GetItemId<TSource>
+      value?: TGetValue | ((source: TSource, properties: TCustomProperties) => $TValue)
+      properties?: (source: TSource) => TCustomProperties
+      label: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple>
 
 // Implementation
 
 export function useFormSelect<
-  TBaseSource,
-  TAllowEmpty extends boolean = false,
+  TSource,
   TCustomProperties extends CollectionItemProperties = EmptyObject,
-  TGetValue extends GetOptionValue<$TSource, TCustomProperties> = undefined,
+  TGetValue extends GetOptionValue<TSource, TCustomProperties> = undefined,
   TMultiple extends boolean = false,
-  $TSource = TAllowEmpty extends true ? TBaseSource | undefined : TBaseSource,
-  $TValue = ExtractValue<$TSource, TGetValue>,
+  TEmptyValue = never,
+  $TValue = ExtractValue<TSource, TGetValue>,
 >(
-  baseSources: MaybeRefOrGetter<TBaseSource[]>,
+  baseSources: MaybeRefOrGetter<TSource[]>,
   config?: {
-    allowEmpty?: MaybeRefOrGetter<boolean>
     multiple?: MaybeRefOrGetter<boolean>
     model?: Ref<unknown>
     disabled?: MaybeRefOrGetter<boolean>
@@ -219,17 +238,23 @@ export function useFormSelect<
     loading?: MaybeRefOrGetter<boolean>
     required?: MaybeRefOrGetter<boolean>
     searchable?: MaybeRefOrGetter<boolean>
+    emptyOption?: MaybeRefOrGetter<{
+      value: TEmptyValue
+      properties?: TCustomProperties
+      label: string
+      selectedLabel?: string
+    }>
     option?: {
-      id?: GetItemId<TBaseSource>
-      value?: GetOptionValue<$TSource, TCustomProperties>
-      properties?: (source: $TSource) => TCustomProperties
-      label?: GetOptionLabel<$TSource, TCustomProperties>
-      selectedLabel?: (source: $TSource, properties: TCustomProperties) => string
-      disabled?: (source: $TSource, properties: TCustomProperties) => boolean
-      searchableTerm?: (source: $TSource, properties: TCustomProperties) => MaybeArray<string>
+      id?: GetItemId<TSource>
+      value?: GetOptionValue<TSource, TCustomProperties>
+      properties?: (source: TSource) => TCustomProperties
+      label?: GetOptionLabel<TSource, TCustomProperties>
+      selectedLabel?: (source: TSource, properties: TCustomProperties) => string
+      disabled?: (source: TSource, properties: TCustomProperties) => boolean
+      searchableTerm?: (source: TSource, properties: TCustomProperties) => MaybeArray<string>
     }
   }
-): UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple> {
+): UseFormSelectReturn<TCustomProperties, TSource, $TValue | TEmptyValue, TMultiple> {
   const searchTerm = ref('')
 
   const normalizedSearchTerm = computed(() => normalizeSearchTerm(searchTerm))
@@ -249,8 +274,8 @@ export function useFormSelect<
   const isSearchable = computed(() => toValue(config?.searchable) ?? false)
 
   const sources = computed(() =>
-    config?.allowEmpty ? [undefined, ...toValue(baseSources)] : toValue(baseSources)
-  ) as ComputedRef<$TSource[]>
+    config?.emptyOption !== undefined ? [EMPTY_OPTION, ...toValue(baseSources)] : toValue(baseSources)
+  ) as ComputedRef<(TSource | typeof EMPTY_OPTION)[]>
 
   const {
     items: allOptions,
@@ -258,12 +283,25 @@ export function useFormSelect<
     useFlag,
   } = useCollection(sources, {
     itemId: source =>
-      source === undefined ? '__EMPTY_OPTION__' : guessItemId(source as TBaseSource, config?.option?.id),
+      source === EMPTY_OPTION ? '__EMPTY_OPTION__' : guessItemId(source as TSource, config?.option?.id),
     flags: {
       active: { multiple: false },
       selected: { multiple: isMultiple },
     },
     properties: (source): FormOptionCollectionItemProperties<TCustomProperties, $TValue> => {
+      if (source === EMPTY_OPTION) {
+        const emptyOption = toValue(config?.emptyOption)
+
+        return {
+          value: computed(() => emptyOption?.value as $TValue),
+          label: computed(() => emptyOption?.label ?? ''),
+          selectedLabel: computed(() => emptyOption?.selectedLabel),
+          matching: computed(() => normalizedSearchTerm.value === ''),
+          disabled: computed(() => false),
+          ...(emptyOption?.properties ?? ({} as TCustomProperties)),
+        }
+      }
+
       const customProperties = config?.option?.properties?.(source) ?? ({} as TCustomProperties)
       const label = computed(() => guessLabel(source, customProperties, config?.option?.label))
       const value = computed(() => guessValue(source, customProperties, config?.option?.value) as $TValue)
@@ -296,7 +334,7 @@ export function useFormSelect<
 
   const { items: options } = useSubset(option => option.properties.matching)
 
-  const { items: selectedOptions } = useFlag('selected')
+  const { items: selectedOptions, toggleAll: toggleSelectAll } = useFlag('selected')
 
   const selectedOption = computed(() => selectedOptions.value[0])
 
@@ -318,12 +356,18 @@ export function useFormSelect<
     watch(
       model,
       modelValue => {
+        toggleSelectAll(false)
+
         if (isMultiple.value) {
           allOptions.value.forEach(option => {
-            option.toggleFlag('selected', (modelValue as $TValue[]).includes(option.properties.value as $TValue))
+            if ((modelValue as $TValue[]).includes(toRaw(option.properties.value) as $TValue)) {
+              option.toggleFlag('selected', true)
+            }
           })
         } else {
-          allOptions.value.find(option => option.properties.value === modelValue)?.toggleFlag('selected', true)
+          allOptions.value
+            .find(option => toRaw(option.properties.value) === toRaw(modelValue))
+            ?.toggleFlag('selected', true)
         }
       },
       { immediate: true }
@@ -358,14 +402,14 @@ export function useFormSelect<
     selectedOption,
     selectedOptions,
     selectedLabel,
-  } satisfies FormSelect<TCustomProperties, any> as FormSelect<TCustomProperties, $TSource, $TValue, TMultiple>
+  } satisfies FormSelect<TCustomProperties, any> as FormSelect<TCustomProperties, TSource, $TValue, TMultiple>
 
-  const id = Symbol('useFormSelect ID') as FormSelectId<TCustomProperties, $TSource, $TValue, TMultiple>
+  const id = Symbol('useFormSelect ID') as FormSelectId<TCustomProperties, TSource, $TValue, TMultiple>
 
   provide(id, select)
 
   return {
     id,
     ...select,
-  } satisfies UseFormSelectReturn<TCustomProperties, $TSource, $TValue, TMultiple>
+  } satisfies UseFormSelectReturn<TCustomProperties, TSource, $TValue, TMultiple>
 }

package/lib/packages/icon/DisplayIcon.vue

@@ -21,5 +21,6 @@ defineProps<{
   transform-origin: 50% 50%;
   grid-template-rows: 1fr;
   grid-template-columns: 1fr;
+  vertical-align: -0.125em;
 }
 </style>

package/lib/packages/progress/README.md

@@ -0,0 +1,62 @@
+# `useProgress` / `useProgressGroup`
+
+## `useProgress`
+
+### Arguments
+
+| Argument  | Type                       | Required | Description        |
+| --------- | -------------------------- | :------: | ------------------ |
+| `current` | `MaybeRefOrGetter<number>` |    ✓     | The current value. |
+| `total`   | `MaybeRefOrGetter<number>` |    ✓     | The total value.   |
+
+### Returns
+
+| Property        | Type                      | Description                                                |
+| --------------- | ------------------------- | ---------------------------------------------------------- |
+| `current`       | `ComputedRef<number>`     | The normalized `current` input                             |
+| `total`         | `ComputedRef<number>`     | The normalized `total` input                               |
+| `fillWidth`     | `ComputedRef<${number}%>` | The width of the progress bar to be filled (e.g. `"35%"`). |
+| `percentage`    | `ComputedRef<number>`     | The percentage between `current` and `total`.              |
+| `percentageCap` | `number`                  | The percentage cap of the progress bar. (see below)        |
+
+`percentageCap` is the `percentage` rounded up to the nearest hundred.
+
+For example, if `current` is `15` and `total` is `10`, then `percentage` will be `150` and `percentageCap` will be `200`.
+
+`fillWidth` is the percentage of the progress bar to be filled.
+
+In the example above, `fillWidth` will be `"75%"` (`150` / `200` = `0.75`).
+
+```ts
+const { fillWidth, percentage, percentageCap } = useProgress(current, total)
+
+// current = 15; total = 60
+// → percentage = 25
+// → percentageCap = 100
+// → fillWidth = '25%'
+
+// current = 90; total = 60
+// → percentage = 150
+// → percentageCap = 200
+// → fillWidth = '75%'
+```
+
+## `useProgressGroup`
+
+This composable will allow handling multiple progress bars and normalize their fill width across all of them.
+
+### Arguments
+
+| Argument  | Type                                                | Required | Description                                                                                                              |
+| --------- | --------------------------------------------------- | :------: | ------------------------------------------------------------------------------------------------------------------------ |
+| `sources` | `MaybeRefOrGetter<T[]>`                             |    ✓     | The sources array                                                                                                        |
+| `fn`      | `(source: T) => { current: number; total: number }` |    ~     | Returns `current` and `total` for each `source`. If `source` already has these properties, this argument can be omitted. |
+| `options` | `{ sort?: 'asc' \| 'desc' }                         |          | Whether to sort the progress items                                                                                       |
+
+### Returns
+
+| Property               | Type                                                      | Description                                           |
+| ---------------------- | --------------------------------------------------------- | ----------------------------------------------------- |
+| `progressItems`        | `ComputedRef<Reactive<Progress & { source: TSource }>[]>` | The normalized progress items.                        |
+| `highestPercentage`    | `ComputedRef<number>`                                     | The highest `percentage` among all progress items.    |
+| `highestPercentageCap` | `ComputedRef<number>`                                     | The highest `percentageCap` among all progress items. |

package/lib/packages/progress/types.ts

@@ -0,0 +1,19 @@
+import type { ComputedRef, MaybeRefOrGetter, Reactive } from 'vue'
+
+export type Progress = {
+  current: ComputedRef<number>
+  total: ComputedRef<number>
+  percentage: ComputedRef<number>
+  fillWidth: ComputedRef<string>
+  percentageCap: ComputedRef<number>
+}
+
+export type ProgressGroup<TSource> = {
+  progressItems: ComputedRef<Reactive<Progress & { source: TSource }>[]>
+  highestPercentage: ComputedRef<number>
+  highestPercentageCap: ComputedRef<number>
+}
+
+export type UseProgressGroupOptions = {
+  sort?: MaybeRefOrGetter<'asc' | 'desc' | undefined>
+}

package/lib/packages/progress/use-progress-group.ts

@@ -0,0 +1,68 @@
+import type { ProgressGroup, UseProgressGroupOptions } from './types.ts'
+import { useArrayMap } from '@vueuse/shared'
+import { computed, markRaw, type MaybeRefOrGetter, reactive, toValue } from 'vue'
+import { useProgress } from './use-progress.ts'
+
+export function useProgressGroup<TSource extends { current: number; total: number }>(
+  rawSources: MaybeRefOrGetter<TSource[]>,
+  options?: UseProgressGroupOptions
+): ProgressGroup<TSource>
+
+export function useProgressGroup<TSource>(
+  rawSources: MaybeRefOrGetter<TSource[]>,
+  fn: (item: TSource) => { current: number; total: number },
+  options?: UseProgressGroupOptions
+): ProgressGroup<TSource>
+
+export function useProgressGroup<TSource>(
+  rawSources: MaybeRefOrGetter<TSource[]>,
+  fnOrOptions?: UseProgressGroupOptions | ((item: TSource) => { current: number; total: number }),
+  optionsOrNone?: UseProgressGroupOptions
+): ProgressGroup<TSource> {
+  const fn =
+    typeof fnOrOptions === 'function' ? fnOrOptions : (item: TSource) => item as { current: number; total: number }
+  const options = typeof fnOrOptions === 'function' ? optionsOrNone : fnOrOptions
+
+  const progressItems = useArrayMap(rawSources, source => {
+    const { current, total } = fn(source)
+
+    return {
+      source: typeof source === 'object' && source !== null ? markRaw(source) : source,
+      ...useProgress(current, total),
+    }
+  })
+
+  const highestPercentage = computed(() =>
+    progressItems.value.reduce((highestPercentage, item) => Math.max(highestPercentage, item.percentage.value), 0)
+  )
+
+  const highestPercentageCap = computed(() =>
+    progressItems.value.reduce((highestCap, item) => Math.max(highestCap, item.percentageCap.value), 0)
+  )
+
+  const normalizedProgressItems = useArrayMap(progressItems, item => {
+    const fillWidth = computed(() => `${(item.percentage.value / highestPercentageCap.value) * 100}%`)
+
+    return reactive({
+      ...item,
+      fillWidth,
+    })
+  })
+
+  const sortedProgressItems = computed(() => {
+    switch (toValue(options?.sort)) {
+      case 'asc':
+        return [...normalizedProgressItems.value].sort((a, b) => a.percentage - b.percentage)
+      case 'desc':
+        return [...normalizedProgressItems.value].sort((a, b) => b.percentage - a.percentage)
+      default:
+        return normalizedProgressItems.value
+    }
+  })
+
+  return {
+    progressItems: sortedProgressItems,
+    highestPercentage,
+    highestPercentageCap,
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { Progress } from './types.ts'
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function useProgress(rawCurrent: MaybeRefOrGetter<number>, rawTotal: MaybeRefOrGetter<number>): Progress {
+  const current = computed(() => toValue(rawCurrent))
+
+  const total = computed(() => toValue(rawTotal))
+
+  const percentage = computed(() => (total.value === 0 ? 0 : (current.value / total.value) * 100))
+
+  const percentageCap = computed(() => Math.max(100, Math.ceil(percentage.value / 100) * 100))
+
+  const fillWidth = computed(() => `${(percentage.value / percentageCap.value) * 100}%`)
+
+  return {
+    current,
+    total,
+    percentage,
+    fillWidth,
+    percentageCap,
+  }
+}