@xen-orchestra/web-core 0.15.0 → 0.17.0

package/lib/components/ui/table-pagination/UiTablePagination.vue

@@ -2,27 +2,27 @@
 <template>
   <div class="ui-table-pagination">
     <div class="buttons-container">
-      <PaginationButton :disabled="isFirstPage || disabled" :icon="faAngleDoubleLeft" @click="goToFirstPage()" />
-      <PaginationButton :disabled="isFirstPage || disabled" :icon="faAngleLeft" @click="goToPreviousPage()" />
-      <PaginationButton :disabled="isLastPage || disabled" :icon="faAngleRight" @click="goToNextPage()" />
-      <PaginationButton :disabled="isLastPage || disabled" :icon="faAngleDoubleRight" @click="goToLastPage()" />
+      <PaginationButton :disabled="isFirstPage" :icon="faAngleDoubleLeft" @click="emit('first')" />
+      <PaginationButton :disabled="isFirstPage" :icon="faAngleLeft" @click="emit('previous')" />
+      <PaginationButton :disabled="isLastPage" :icon="faAngleRight" @click="emit('next')" />
+      <PaginationButton :disabled="isLastPage" :icon="faAngleDoubleRight" @click="emit('last')" />
     </div>
     <span class="typo-body-regular-small label">
-      {{ $t('core.select.n-object-of', { from: startIndex, to: endIndex, total: totalItems }) }}
+      {{ $t('core.select.n-object-of', { from, to, total }) }}
     </span>
-    <span class="typo-body-regular-small label show">{{ $t('core.show-by') }}</span>
+    <span class="typo-body-regular-small label show">{{ $t('core.pagination.show-by') }}</span>
     <div class="dropdown-wrapper">
-      <select v-model="pageSize" :disabled class="dropdown typo-body-regular-small" @change="goToFirstPage">
-        <option v-for="option in pageSizeOptions" :key="option" :value="option" class="typo-body-bold-small">
-          {{ option }}
+      <select v-model="showBy" class="dropdown typo-body-regular-small">
+        <option v-for="option in [50, 100, 150, 200, -1]" :key="option" :value="option" class="typo-body-bold-small">
+          {{ option === -1 ? $t('core.pagination.all') : option }}
         </option>
       </select>
-      <VtsIcon class="icon" accent="current" :icon="faAngleDown" />
+      <VtsIcon :icon="faAngleDown" accent="current" class="icon" />
     </div>
   </div>
 </template>
 
-<script setup lang="ts">
+<script lang="ts" setup>
 import VtsIcon from '@core/components/icon/VtsIcon.vue'
 import PaginationButton from '@core/components/ui/table-pagination/PaginationButton.vue'
 import {
@@ -32,60 +32,26 @@ import {
   faAngleLeft,
   faAngleRight,
 } from '@fortawesome/free-solid-svg-icons'
-import { useOffsetPagination } from '@vueuse/core'
-import { computed, ref, watch } from 'vue'
-
-export type PaginationPayload = {
-  currentPage: number
-  pageSize: number
-  startIndex: number
-  endIndex: number
-}
 
-const { totalItems, disabled = false } = defineProps<{
-  totalItems: number
-  disabled?: boolean
+defineProps<{
+  from: number
+  to: number
+  total: number
+  isFirstPage: boolean
+  isLastPage: boolean
 }>()
 
 const emit = defineEmits<{
-  change: [payload: PaginationPayload]
+  first: []
+  previous: []
+  next: []
+  last: []
 }>()
 
-const pageSize = ref(50)
-const pageSizeOptions = [10, 50, 100, 150, 200]
-const {
-  currentPage,
-  currentPageSize,
-  pageCount,
-  isFirstPage,
-  isLastPage,
-  prev: goToPreviousPage,
-  next: goToNextPage,
-} = useOffsetPagination({
-  total: () => totalItems,
-  pageSize,
-})
-const startIndex = computed(() => (currentPage.value - 1) * currentPageSize.value + 1)
-const endIndex = computed(() => Math.min(currentPage.value * currentPageSize.value, totalItems))
-
-const goToFirstPage = () => {
-  currentPage.value = 1
-}
-const goToLastPage = () => {
-  currentPage.value = pageCount.value
-}
-
-watch([currentPage, currentPageSize], ([newPage, newPageSize]) => {
-  emit('change', {
-    currentPage: newPage,
-    pageSize: newPageSize,
-    startIndex: startIndex.value,
-    endIndex: endIndex.value,
-  })
-})
+const showBy = defineModel<number>('showBy', { default: 50 })
 </script>
 
-<style scoped lang="postcss">
+<style lang="postcss" scoped>
 .ui-table-pagination {
   display: flex;
   align-items: center;

package/lib/components/ui/{input → text-area}/UiTextarea.vue

@@ -1,25 +1,41 @@
 <!-- v2 -->
 <template>
-  <div class="ui-textarea" :class="toVariants({ accent })">
-    <UiLabel v-if="slots.default" :accent="labelAccent" :required :icon :href><slot /></UiLabel>
-    <textarea v-model="model" :disabled class="textarea" v-bind="attrs" />
-    <UiInfo v-if="slots.info" :accent><slot name="info" /></UiInfo>
+  <div class="ui-textarea" :class="toVariants({ accent: hasMaxCharactersError ? 'danger' : accent })">
+    <UiLabel v-if="slots.default" :accent="labelAccent" :required :icon :href :for="id">
+      <slot />
+    </UiLabel>
+    <textarea v-bind="attrs" :id ref="textarea" v-model="model" :disabled class="textarea" />
+    <UiCharacterLimit v-if="maxCharacters" :count="model.trim().length" :max="maxCharacters" />
+    <UiInfo v-if="isExceedingMaxCharacters" accent="danger">
+      {{ $t('core.textarea.exceeds-max-characters', { max: maxCharacters }) }}
+    </UiInfo>
+    <UiInfo v-if="slots.info" :accent="accent === 'brand' ? 'info' : accent">
+      <slot name="info" />
+    </UiInfo>
   </div>
 </template>
 
 <script lang="ts" setup>
+import UiCharacterLimit from '@core/components/ui/character-limit/UiCharacterLimit.vue'
 import UiInfo from '@core/components/ui/info/UiInfo.vue'
 import UiLabel from '@core/components/ui/label/UiLabel.vue'
 import { toVariants } from '@core/utils/to-variants.util'
 import type { IconDefinition } from '@fortawesome/fontawesome-common-types'
-import { computed, useAttrs } from 'vue'
+import { useFocus } from '@vueuse/core'
+import { computed, useAttrs, useId, useTemplateRef } from 'vue'
 
 defineOptions({
   inheritAttrs: false,
 })
 
-const props = defineProps<{
-  accent: 'info' | 'warning' | 'danger'
+const {
+  accent,
+  maxCharacters,
+  id = useId(),
+} = defineProps<{
+  accent: 'brand' | 'warning' | 'danger'
+  id?: string
+  maxCharacters?: number
   disabled?: boolean
   href?: string
   icon?: IconDefinition
@@ -35,7 +51,24 @@ const slots = defineSlots<{
 
 const attrs = useAttrs()
 
-const labelAccent = computed(() => (props.accent === 'info' ? 'neutral' : props.accent))
+const textAreaElement = useTemplateRef('textarea')
+
+const { focused } = useFocus(textAreaElement)
+
+// WIP: To update when using VeeValidate and custom validation rules
+const isExceedingMaxCharacters = computed(() =>
+  maxCharacters !== undefined ? model.value.trim().length > maxCharacters : false
+)
+
+const hasMaxCharactersError = computed(() => !focused.value && isExceedingMaxCharacters.value)
+
+const labelAccent = computed(() => {
+  if (hasMaxCharactersError.value) {
+    return 'danger'
+  }
+
+  return accent === 'brand' ? 'neutral' : accent
+})
 </script>
 
 <style lang="postcss" scoped>
@@ -54,20 +87,23 @@ const labelAccent = computed(() => (props.accent === 'info' ? 'neutral' : props.
     width: 100%;
   }
 
-  &.accent--info {
+  &.accent--brand {
     .textarea {
       border-color: var(--color-neutral-border);
 
       &:hover {
-        border-color: var(--color-info-item-hover);
+        border-color: var(--color-brand-item-hover);
       }
+
       &:active {
-        border-color: var(--color-info-item-active);
+        border-color: var(--color-brand-item-active);
       }
+
       &:focus:not(:active) {
         border-width: 0.2rem;
-        border-color: var(--color-info-item-base);
+        border-color: var(--color-brand-item-base);
       }
+
       &:disabled {
         background-color: var(--color-neutral-background-disabled);
         border-color: var(--color-neutral-border);
@@ -82,13 +118,16 @@ const labelAccent = computed(() => (props.accent === 'info' ? 'neutral' : props.
       &:hover {
         border-color: var(--color-warning-item-hover);
       }
+
       &:active {
         border-color: var(--color-warning-item-active);
       }
+
       &:focus:not(:active) {
         border-width: 0.2rem;
         border-color: var(--color-warning-item-base);
       }
+
       &:disabled {
         background-color: var(--color-neutral-background-disabled);
         border-color: var(--color-neutral-border);
@@ -103,13 +142,16 @@ const labelAccent = computed(() => (props.accent === 'info' ? 'neutral' : props.
       &:hover {
         border-color: var(--color-danger-item-hover);
       }
+
       &:active {
         border-color: var(--color-danger-item-active);
       }
+
       &:focus:not(:active) {
         border-width: 0.2rem;
         border-color: var(--color-danger-item-base);
       }
+
       &:disabled {
         background-color: var(--color-neutral-background-disabled);
         border-color: var(--color-neutral-border);

package/lib/composables/mapper.composable.md

@@ -0,0 +1,74 @@
+# `useMapper` composable
+
+This composable maps values from one type to another using a mapping record. It takes a source value, a mapping object, and a default value to use when the source value is undefined or not found in the mapping.
+
+## Usage
+
+```ts
+const mappedValue = useMapper(sourceValue, mapping, defaultValue)
+```
+
+|                | Required | Type                      | Default |                                                                                   |
+| -------------- | :------: | ------------------------- | ------- | --------------------------------------------------------------------------------- |
+| `sourceValue`  |    ✓     | `MaybeRefOrGetter<TFrom>` |         | The source value to be mapped. Can be a ref, a getter function, or a raw value    |
+| `mapping`      |    ✓     | `Record<TFrom, TTo>`      |         | An object mapping source values to destination values                             |
+| `defaultValue` |    ✓     | `MaybeRefOrGetter<TTo>`   |         | The default value to use when the source is undefined or not found in the mapping |
+
+## Return value
+
+|               | Type               |                                                  |
+| ------------- | ------------------ | ------------------------------------------------ |
+| `mappedValue` | `ComputedRef<TTo>` | A computed reference containing the mapped value |
+
+## Example
+
+```vue
+<template>
+  <div>
+    <p>Selected car color: {{ carColor }}</p>
+    <p>Recommended wall color: {{ wallColor }}</p>
+
+    <button @click="carColor = 'red'">Red Car</button>
+    <button @click="carColor = 'blue'">Blue Car</button>
+    <button @click="carColor = 'black'">Black Car</button>
+    <button @click="carColor = 'green'">Green Car</button>
+    <button @click="carColor = 'silver'">Silver Car</button>
+    <button @click="carColor = undefined">No Car</button>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { useMapper } from '@/composables/mapper'
+import { ref } from 'vue'
+
+// Source type
+type CarColor = 'red' | 'blue' | 'black' | 'green' | 'silver'
+
+// Destination type
+type WallColor = 'beige' | 'lightGray' | 'cream' | 'white'
+
+// Create a ref for the source value
+const carColor = ref<CarColor | undefined>(undefined)
+
+// Create a computed property that maps car color to wall color
+const wallColor = useMapper<CarColor, WallColor>(
+  carColor,
+  {
+    red: 'beige',
+    blue: 'lightGray',
+    black: 'cream',
+    green: 'beige',
+    silver: 'lightGray',
+  },
+  'white'
+)
+</script>
+```
+
+In this example:
+
+- When `carColor.value` is `'red'` or `'green'`, `wallColor.value` will be `'beige'`
+- When `carColor.value` is `'blue'` or `'silver'`, `wallColor.value` will be `'lightGray'`
+- When `carColor.value` is `'black'`, `wallColor.value` will be `'cream'`
+- When `carColor.value` is `undefined` or any value not in the mapping, `wallColor.value` will be
+  `'white'` (the default value)

package/lib/composables/mapper.composable.ts

@@ -0,0 +1,18 @@
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function useMapper<TFrom extends string | number, TTo>(
+  _source: MaybeRefOrGetter<TFrom | undefined>,
+  mapping: Record<TFrom, TTo>,
+  _defaultValue: MaybeRefOrGetter<TTo>
+): ComputedRef<TTo> {
+  return computed(() => {
+    const source = toValue(_source)
+    const defaultValue = toValue(_defaultValue)
+
+    if (source === undefined) {
+      return defaultValue
+    }
+
+    return Object.prototype.hasOwnProperty.call(mapping, source) ? mapping[source] : defaultValue
+  })
+}

package/lib/composables/pagination.composable.md

@@ -0,0 +1,32 @@
+# usePagination Composable
+
+Handles record pagination with localStorage and route persistence.
+
+The composable uses index-based pagination instead of page numbers, enabling URL sharing across users with different "Show by" settings. The index represents the first visible record.
+
+## Storage
+
+- Route query: `{id}.idx` stores start index
+- LocalStorage: `{id}.per-page` stores "Show by" value (default: 50)
+
+## Key Points
+
+- `showBy = -1` displays all records
+- `pageRecords` returns current page's records subset
+- `seek(predicate)` finds and navigates to specific record's page
+- All indices auto-align to page boundaries
+- `paginationBindings` contains props and events for `UiTablePagination`
+
+## Usage
+
+```typescript
+// Basic usage
+const { pageRecords, paginationBindings } = usePagination('items', items)
+
+// Template
+<div v-for="item in pageRecords" :key="item.id">
+  {{ item.name }}
+</div>
+
+<UiTablePagination v-bind="paginationBindings" />
+```

package/lib/composables/pagination.composable.ts

@@ -0,0 +1,91 @@
+import { useRouteQuery } from '@core/composables/route-query.composable'
+import { clamp, useLocalStorage } from '@vueuse/core'
+import { computed, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function usePagination<T>(id: string, _records: MaybeRefOrGetter<T[]>) {
+  const records = computed(() => toValue(_records))
+
+  const showBy = useLocalStorage(`${id}.per-page`, 50)
+
+  const pageSize = computed({
+    get: () => (showBy.value === -1 ? Number.MAX_SAFE_INTEGER : showBy.value),
+    set: value => (showBy.value = value),
+  })
+
+  function toStartIndex(rawIndex: number | string) {
+    const index = clamp(+rawIndex, 0, records.value.length - 1) || 0
+
+    return Math.floor(index / pageSize.value) * pageSize.value
+  }
+
+  const startIndex = useRouteQuery<number>(`${id}.idx`, {
+    defaultQuery: '0',
+    toData: value => toStartIndex(value),
+    toQuery: value => toStartIndex(value).toString(10),
+  })
+
+  const endIndex = computed(() => Math.min(startIndex.value + pageSize.value - 1, records.value.length - 1))
+
+  const isFirstPage = computed(() => startIndex.value <= 0)
+
+  const isLastPage = computed(() => endIndex.value >= records.value.length - 1)
+
+  const pageRecords = computed(() => records.value.slice(startIndex.value, endIndex.value + 1))
+
+  function seek(predicate: (record: T) => boolean) {
+    const index = records.value.findIndex(predicate)
+
+    if (index !== -1) {
+      startIndex.value = index
+    }
+  }
+
+  function goToNextPage() {
+    if (!isLastPage.value) {
+      startIndex.value = startIndex.value + pageSize.value
+    }
+  }
+
+  function goToPreviousPage() {
+    if (!isFirstPage.value) {
+      startIndex.value = startIndex.value - pageSize.value
+    }
+  }
+
+  function goToFirstPage() {
+    startIndex.value = 0
+  }
+
+  function goToLastPage() {
+    startIndex.value = records.value.length - 1
+  }
+
+  const paginationBindings = computed(() => ({
+    showBy: showBy.value,
+    'onUpdate:showBy': (value: number) => (showBy.value = value),
+    from: Math.max(0, startIndex.value + 1),
+    to: endIndex.value + 1,
+    total: records.value.length,
+    isFirstPage: isFirstPage.value,
+    isLastPage: isLastPage.value,
+    onFirst: goToFirstPage,
+    onLast: goToLastPage,
+    onNext: goToNextPage,
+    onPrevious: goToPreviousPage,
+  }))
+
+  return {
+    startIndex,
+    endIndex,
+    seek,
+    showBy,
+    isFirstPage,
+    isLastPage,
+    goToPreviousPage,
+    goToNextPage,
+    goToFirstPage,
+    goToLastPage,
+    pageRecords,
+    paginationBindings,
+  }
+}

package/lib/composables/ranked.composable.md

@@ -0,0 +1,118 @@
+# `useRanked` composable
+
+This composable helps sort items based on a predefined ranking order.
+
+It takes an array of items and a ranking order, and returns a computed sorted array according to the ranking.
+
+## Usage
+
+### Signature 1: Sorting ranks directly
+
+```ts
+const sortedRanks = useRanked(ranks, ranking)
+```
+
+|           | Required | Type                        | Default | Description                                                |
+| --------- | :------: | --------------------------- | ------- | ---------------------------------------------------------- |
+| `ranks`   |    ✓     | `MaybeRefOrGetter<TRank[]>` |         | The array of ranks to sort                                 |
+| `ranking` |    ✓     | `TRank[]`                   |         | The array of ranks ordered from highest to lowest priority |
+
+#### Return value
+
+|               | Type                   | Description                                                     |
+| ------------- | ---------------------- | --------------------------------------------------------------- |
+| `sortedRanks` | `ComputedRef<TRank[]>` | A computed array of ranks sorted according to the ranking order |
+
+- Ranks are sorted based on their position in the `ranking` array (lower index = higher priority)
+- Ranks not found in the `ranking` array are placed after all defined ranks in their original order
+
+#### Example: Sorting priority levels
+
+```ts
+import { useRanked } from '@core/composables/ranked.composable'
+import { ref } from 'vue'
+
+// Priority levels in random order
+const currentPriorities = ref(['high', 'medium', 'low', 'critical', 'low', 'medium', 'high'])
+
+// Define the ranking order (from highest to lowest priority)
+const priorityRanking = ['critical', 'high', 'medium', 'low']
+
+// Sort priorities according to the ranking
+const sortedPriorities = useRanked(currentPriorities, priorityRanking)
+
+// sortedPriorities.value will be:
+// ['critical', 'high', 'high', 'medium', 'medium', 'low', 'low']
+```
+
+### Signature 2: Sorting items by their rank
+
+```ts
+const sortedItems = useRanked(items, getRank, ranking)
+```
+
+|           | Required | Type                        | Default | Description                                                |
+| --------- | :------: | --------------------------- | ------- | ---------------------------------------------------------- |
+| `items`   |    ✓     | `MaybeRefOrGetter<TItem[]>` |         | The array of items to sort                                 |
+| `getRank` |    ✓     | `(item: TItem) => TRank`    |         | A function to extract rank from an item                    |
+| `ranking` |    ✓     | `TRank[]`                   |         | The array of ranks ordered from highest to lowest priority |
+
+#### Return value
+
+|               | Type                   | Description                                       |
+| ------------- | ---------------------- | ------------------------------------------------- |
+| `sortedItems` | `ComputedRef<TItem[]>` | A computed array of items sorted by their ranking |
+
+- Items are sorted based on their rank in the `ranking` array (lower index = higher priority)
+- Items with ranks not found in the `ranking` array are placed after all ranked items in their original order
+
+#### Example: Sorting tasks by priority
+
+```ts
+import { useRanked } from '@core/composables/ranked.composable'
+import { ref } from 'vue'
+
+// Tasks with different priorities
+const tasks = ref([
+  {
+    id: 1,
+    title: 'Fix login bug',
+    priority: 'high',
+  },
+  {
+    id: 2,
+    title: 'Update documentation',
+    priority: 'low',
+  },
+  {
+    id: 3,
+    title: 'Server outage',
+    priority: 'critical',
+  },
+  {
+    id: 4,
+    title: 'Refactor components',
+    priority: 'medium',
+  },
+  {
+    id: 5,
+    title: 'Design review',
+    priority: 'medium',
+  },
+])
+
+// Define the ranking order (from highest to lowest priority)
+const priorityRanking = ['critical', 'high', 'medium', 'low']
+
+// Sort tasks by priority according to the ranking
+const sortedTasks = useRanked(tasks, task => task.priority, priorityRanking)
+
+// sortedTasks.value will be:
+// [
+//   { id: 3, title: 'Server outage', priority: 'critical' },
+//   { id: 1, title: 'Fix login bug', priority: 'high' },
+//   { id: 4, title: 'Refactor components', priority: 'medium' },
+//   { id: 5, title: 'Design review', priority: 'medium' },
+//   { id: 2, title: 'Update documentation', priority: 'low' }
+// ]
+```

package/lib/composables/ranked.composable.ts

@@ -0,0 +1,37 @@
+import { clamp, useSorted } from '@vueuse/core'
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+
+export function useRanked<TRank extends string | number>(
+  ranks: MaybeRefOrGetter<TRank[]>,
+  ranking: NoInfer<TRank>[]
+): ComputedRef<TRank[]>
+
+export function useRanked<TItem, TRank extends string | number>(
+  items: MaybeRefOrGetter<TItem[]>,
+  getRank: (item: TItem) => TRank,
+  ranking: NoInfer<TRank>[]
+): ComputedRef<TItem[]>
+
+export function useRanked<TItem, TRank extends string | number>(
+  items: MaybeRefOrGetter<TItem[]>,
+  ranksOrGetRank: TRank[] | ((item: TItem) => TRank),
+  ranksOrNone?: TRank[]
+) {
+  const getRank = typeof ranksOrGetRank === 'function' ? ranksOrGetRank : (item: TItem) => item as unknown as TRank
+
+  const ranks = ranksOrNone === undefined ? (ranksOrGetRank as TRank[]) : ranksOrNone
+
+  const ranksMap = computed(() => Object.fromEntries(ranks.map((rank, index) => [rank, index + 1]))) as ComputedRef<
+    Record<TRank, number>
+  >
+
+  function getRankNumber(item: TItem): number {
+    return ranksMap.value[getRank(item)] ?? toValue(items).length + 1
+  }
+
+  function compare(item1: TItem, item2: TItem) {
+    return clamp(getRankNumber(item1) - getRankNumber(item2), -1, 1) as -1 | 0 | 1
+  }
+
+  return useSorted(items, compare)
+}