@xen-orchestra/web-core 0.6.0 → 0.8.0

package/lib/locales/fa.json

@@ -33,13 +33,16 @@
 
   "dashboard": "داشبورد",
   "documentation-name": "اسناد {name}",
+  "error-no-data": "خطا، نمی توان داده ها را جمع آوری کرد.",
   "fullscreen": "تمام صفحه",
+  "gateway": "دروازه",
   "learn-more": "بیشتر بدانید",
   "loading-in-progress": "بارگیری در حال انجام است…",
   "log-out": "خروج",
   "master": "میزبان اصلی",
   "network": "شبکه",
   "open-console-in-new-tab": "باز کردن کنسول در برگه جدید",
+  "page-not-found": "این صفحه پیدا نمی شود…",
   "patches": "وصله ها",
   "power-on-vm-for-console": "ماشین مجازی خود را روشن کنید تا به کنسول آن دسترسی داشته باشید",
   "power-on-host-for-console": "هاست خود را برای دسترسی به کنسول آن روشن کنید",

package/lib/locales/fr.json

@@ -45,8 +45,10 @@
   "access-forum": "Accès au forum",
   "dashboard": "Tableau de bord",
   "documentation-name": "Documentation {name}",
+  "error-no-data": "Erreur, impossible de collecter les données.",
   "exit-fullscreen": "Quitter le plein écran",
   "fullscreen": "Plein écran",
+  "gateway": "Passerelle",
   "hosts": "Hôtes",
   "learn-more": "En savoir plus",
   "loading-in-progress": "Chargement en cours…",
@@ -58,6 +60,7 @@
   "object-not-found": "L'objet {id} est introuvable…",
   "open-console-in-new-tab": "Ouvrir la console dans un nouvel onglet",
   "other": "Autre",
+  "page-not-found": "Cette page est introuvable…",
   "patches": "Patches",
   "power-on-vm-for-console": "Allumez votre VM pour accéder à sa console",
   "power-on-host-for-console": "Allumez votre hôte pour accéder à sa console",
@@ -65,8 +68,10 @@
   "receive": "Recevoir",
   "running-vm": "VM en cours d'exécution | VMs en cours d'exécution",
   "see-all": "Voir tout",
+  "select-to-see-details": "Sélectionnez un élement pour voir les details",
   "send": "Envoyer",
   "send-ctrl-alt-del": "Envoyer Ctrl+Alt+Suppr",
+  "speed": "Vitesse",
   "stats": "Stats",
   "storage": "Stockage",
   "system": "Système",

package/lib/packages/job/README.md

@@ -0,0 +1,130 @@
+# Job System Documentation
+
+The Job System provides a type-safe way to manage asynchronous operations with built-in state handling and identity-based concurrency control.
+
+## Core Concepts
+
+- **Job**: An asynchronous operation with validation, state management, and concurrency control
+- **Job Arguments**: Typed parameters that can be single values or arrays
+- **Job Identity**: Values used to track concurrent executions of the same job
+
+## Usage
+
+### When to use argument identity?
+
+You'll want to use a Job argument as identity when two different values means two different processes.
+
+Let's imagine a job to save a document, which will take `id` and `content` as arguments.
+
+Should the job be tracked by the document ID? Yes, because `isRunning` could be `true` for file A and `false` for file B.
+
+Should the job be tracked by the document content? No, because `isRunning` should stay `true` for a specific file, even if the `content` value changes.
+
+### Defining Job Arguments
+
+```typescript
+const userIdArg = defineJobArg<string>({
+  identify: true, // Automatically use value as identity for primitive types
+})
+
+const itemsArg = defineJobArg<Item>({
+  identify: item => item.id, // `Item` not being a primitive, we need to use a function to get its identity
+  toArray: true, // this argument will always be converted to an array if needed
+})
+
+const forceArg = defineJobArg<boolean>({
+  identify: false, // Don't track this argument for concurrency. Whether it to be true or false shouldn't affect the running state of the job
+})
+```
+
+### Defining a Job
+
+```typescript
+const myJob = defineJob('processItems', [userIdArg, itemsArg, optionsArg], () => ({
+  validate(isRunning, userId, items) {
+    // You can use custom running check additionnal to internal one
+    if (isRunning || isProcessingItems(userId, items)) {
+      throw new JobRunningError('Items are being processed')
+    }
+
+    if (items.length === 0) {
+      throw new JobError('No item to process')
+    }
+
+    if (!userId) {
+      throw new JobError('User ID required')
+    }
+  },
+  run(userId, items, force) {
+    // Job implementation
+    return procesItems(userId, items, force)
+  },
+}))
+```
+
+## Type System
+
+### Argument Types
+
+When defining a job argument with `defineJobArg<string>({ toArray?: false })`, then:
+
+- the `defineJob`'s `run` handler will receive a `string`
+- the `defineJob`'s `validate` handler will receive a `string | undefined`
+- the generated `useJob` will receive a `MaybeRefOrGetter<string | undefined>`
+
+When defining a job argument with `defineJobArg<string>({ toArray: true })`, then:
+
+- the `defineJob`'s `run` handler will receive a `string[]`
+- the `defineJob`'s `validate` handler will receive a `string[] | undefined`
+- the generated `useJob` will receive a `MaybeRefOrGetter<MaybeArray<string | undefined>>`
+
+### Using a Job
+
+```typescript
+// Define reactive arguments
+const userId = ref()
+
+const selectedItems = computed(() => props.selectedItems)
+
+// Create job instance with destructured properties
+const {
+  run, // Execute the handler
+  canRun, // A `boolean` computed
+  errorMessage, // A `string | undefined` computed
+  isRunning, // A `boolean` computed
+} = useMyJob(userId, selectedItems, false)
+```
+
+When calling `run`, the job will be marked as "running" for the specified `userId` and `selectedItems` (`force` is ignored because it has been configured with `identify: false`)
+
+When using an array, the tracking is done for each item individually.
+
+Let's take a simplified example for a 5-second handling process:
+
+```typescript
+const userId = ref(1)
+
+const selectedItems = ref([{ id: 'A' }, { id: 'B' }])
+
+const { run, isRunning } = useMyJob(userId, selectedItems)
+
+run()
+
+// isRunning = true
+
+userId.value = 2
+
+// isRunning = false
+
+userId.value = 1
+
+// isRunning = true
+
+selectedItems.value = [{ id: 'A' }, { id: 'C' }]
+
+// isRunning = true
+
+selectedItems.value = [{ id: 'C' }]
+
+// isRunning = false
+```

package/lib/packages/job/define-job-arg.ts

@@ -0,0 +1,12 @@
+export type JobIdentity = string | number | boolean | null | undefined
+
+export type JobArg<TType = any, TToArray extends boolean = boolean> = {
+  identify: ((source: TType) => JobIdentity) | (TType extends JobIdentity ? boolean : false)
+  toArray: TToArray
+}
+
+export function defineJobArg<TType>(config: JobArg<TType, true>): JobArg<TType, true>
+export function defineJobArg<TType>(config: JobArg<TType, false>): JobArg<TType, false>
+export function defineJobArg<TType>(config: JobArg<TType>): JobArg<TType> {
+  return config
+}

package/lib/packages/job/define-job.ts

@@ -0,0 +1,130 @@
+import type { JobArg, JobIdentity } from '@core/packages/job/define-job-arg'
+import { JobError, JobRunningError } from '@core/packages/job/job-error'
+import { useJobStore } from '@core/packages/job/use-job-store'
+import type { MaybeArray } from '@core/types/utility.type'
+import { toArray as convertToArray } from '@core/utils/to-array.utils'
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+
+export type JobRunArgs<TJobArgs> = TJobArgs extends [infer TJobArg, ...infer TRest]
+  ? TJobArg extends JobArg<infer TType, infer TToArray>
+    ? [TToArray extends true ? TType[] : TType, ...JobRunArgs<TRest>]
+    : []
+  : []
+
+export type JobValidateArgs<TJobArgs> = TJobArgs extends [infer TJobArg, ...infer TRest]
+  ? TJobArg extends JobArg<infer TType, infer TToArray>
+    ? [TToArray extends true ? TType[] : TType | undefined, ...JobValidateArgs<TRest>]
+    : []
+  : []
+
+export type JobUseArgs<TJobArgs> = TJobArgs extends [infer TJobArg, ...infer TRest]
+  ? TJobArg extends JobArg<infer TType, infer TToArray>
+    ? [
+        TToArray extends true ? MaybeRefOrGetter<MaybeArray<TType | undefined>> : MaybeRefOrGetter<TType | undefined>,
+        ...JobUseArgs<TRest>,
+      ]
+    : []
+  : []
+
+export type JobSetup<TJobArgs extends JobArg[], TRunResult> = () => {
+  run: (...args: JobRunArgs<TJobArgs>) => TRunResult
+  validate: (isRunning: boolean, ...args: JobValidateArgs<TJobArgs>) => void
+}
+
+export type Job<TRunResult> = {
+  run: () => Promise<TRunResult>
+  canRun: ComputedRef<boolean>
+  error: ComputedRef<JobError | undefined>
+  errorMessage: ComputedRef<string | undefined>
+  isRunning: ComputedRef<boolean>
+}
+
+export function defineJob<const TJobArgs extends JobArg[], TRunResult>(
+  name: string,
+  jobArgs: TJobArgs,
+  setup: JobSetup<TJobArgs, TRunResult>
+) {
+  const jobId = Symbol('jobId')
+
+  return (...useArgs: JobUseArgs<TJobArgs>) => {
+    const config = setup()
+    const jobStore = useJobStore()
+
+    const args = computed(() =>
+      useArgs.map((useArg, index) => {
+        if (jobArgs[index].toArray) {
+          return convertToArray(toValue(useArg))
+        }
+
+        return toValue(useArg)
+      })
+    )
+
+    const identities = computed<JobIdentity[][]>(() =>
+      args.value.map<JobIdentity[]>((arg, index) => {
+        const { toArray, identify } = jobArgs[index]
+
+        if (identify === false) {
+          return [undefined]
+        }
+
+        if (identify === true) {
+          return convertToArray(arg)
+        }
+
+        if (toArray) {
+          return arg.map(identify)
+        }
+
+        return [identify(arg)]
+      })
+    )
+
+    function validate() {
+      config.validate(jobStore.isRunning(jobId, identities.value), ...(args.value as JobValidateArgs<TJobArgs>))
+    }
+
+    const error = computed(() => {
+      try {
+        validate()
+
+        return undefined
+      } catch (error) {
+        if (error instanceof JobError) {
+          error.args = args.value
+          error.jobName = name
+
+          return error
+        }
+
+        return new JobError('Unknown job error', name, args.value, error)
+      }
+    })
+
+    const isRunning = computed(() => error.value instanceof JobRunningError)
+
+    const errorMessage = computed(() => error.value?.message)
+
+    const canRun = computed(() => error.value === undefined)
+
+    async function run() {
+      validate()
+
+      const runId = jobStore.start(jobId, identities.value)
+
+      try {
+        return await config.run(...(args.value as JobRunArgs<TJobArgs>))
+      } finally {
+        jobStore.stop(runId)
+      }
+    }
+
+    return {
+      run,
+      canRun,
+      error,
+      errorMessage,
+      isRunning,
+    } satisfies Job<TRunResult>
+  }
+}

package/lib/packages/job/index.ts

@@ -0,0 +1,4 @@
+export * from './define-job'
+export * from './define-job-arg'
+export * from './job-error'
+export * from './use-job-store'

package/lib/packages/job/job-error.ts

@@ -0,0 +1,14 @@
+export class JobError extends Error {
+  jobName: string | undefined
+  args: any[] | undefined
+  previousError: any
+
+  constructor(message: string, jobName?: string, args?: any[], previousError?: any) {
+    super(message)
+    this.args = args
+    this.jobName = jobName
+    this.previousError = previousError
+  }
+}
+
+export class JobRunningError extends JobError {}

package/lib/packages/job/use-job-store.ts

@@ -0,0 +1,44 @@
+import type { JobIdentity } from '@core/packages/job/define-job-arg'
+import { toArray } from '@core/utils/to-array.utils'
+import { defineStore } from 'pinia'
+import { shallowReactive } from 'vue'
+
+export const useJobStore = defineStore('job', () => {
+  const runningJobs = shallowReactive(new Map<symbol, { jobId: symbol; identities: JobIdentity[][] }>())
+
+  function start(id: symbol, identities: JobIdentity[][]) {
+    const runId = Symbol(`Job run ID`)
+
+    runningJobs.set(runId, {
+      jobId: id,
+      identities,
+    })
+
+    return runId
+  }
+
+  function stop(runId: symbol) {
+    runningJobs.delete(runId)
+  }
+
+  function isRunning(id: symbol, identitiesToCheck: JobIdentity[][]) {
+    return Array.from(runningJobs.values()).some(runningJob => {
+      if (runningJob.jobId !== id) {
+        return false
+      }
+
+      return (
+        identitiesToCheck.length === 0 ||
+        identitiesToCheck.every((identityToCheck, index) =>
+          toArray(identityToCheck).some(identity => runningJob.identities[index]?.includes(identity))
+        )
+      )
+    })
+  }
+
+  return {
+    start,
+    stop,
+    isRunning,
+  }
+})

package/lib/packages/menu/README.md

@@ -0,0 +1,194 @@
+# Menu System
+
+A menu system for Vue applications supporting props binding for actions, links, router links, and nested submenus.
+
+## Basic Usage
+
+```vue
+<template>
+  <MenuList>
+    <li><MenuTrigger v-bind="menu.save">Save</MenuTrigger></li>
+    <li><MenuTrigger v-bind="menu.doc">Documentation</MenuTrigger></li>
+    <li><MenuTrigger v-bind="menu.profile">Profile</MenuTrigger></li>
+    <li>
+      <MenuTrigger v-bind="menu.more.$trigger">More...</MenuTrigger>
+      <MenuList v-bind="menu.more.$target">
+        <MenuTrigger v-bind="menu.more.settings">Settings</MenuTrigger>
+        <MenuTrigger v-bind="menu.more.logout">Logout</MenuTrigger>
+      </MenuList>
+    </li>
+  </MenuList>
+</template>
+
+<script lang="ts" setup>
+import { action, link, routerLink, toggle, useMenu } from '@core/packages/menu'
+
+const menu = useMenu({
+  save: action(() => console.log('Saving...')),
+  doc: link('https://docs.example.com'),
+  profile: routerLink({ name: 'profile' }),
+  more: toggle({
+    settings: action(() => console.log('Settings clicked')),
+    logout: action(() => console.log('Logout clicked')),
+  }),
+})
+</script>
+```
+
+## Core Composables
+
+### useMenu
+
+Create a root menu with multiple items and/or submenus:
+
+```ts
+const fileMenu = useMenu({
+  // Menu structure
+  edit: action(() => handleEdit()),
+  save: action(() => handleSave(), {
+    disabled: () => !canSave.value,
+    busy: isSaving,
+  }),
+})
+```
+
+### useMenuAction
+
+Create an action button. It must be attached to a menu.
+
+Mostly useful when splitting a menu into subcomponents.
+
+```ts
+const props = defineProps<{
+  menu: MenuLike
+}>()
+
+const action = useMenuAction(menu, () => handleClick(), {
+  disabled: isDisabled,
+  busy: isLoading,
+})
+```
+
+### useMenuToggle
+
+Create a toggle menu (dropdown) with nested items.
+
+You can pass a `parent: MenuLike` as option to attach the toggle to a parent Menu.
+
+Skip this option to create a root menu toggle.
+
+```ts
+const dropdown = useMenuToggle(
+  {
+    behavior: 'click', // or 'mouseenter'
+    placement: 'bottom-start',
+  },
+  {
+    edit: action(() => handleEdit()),
+    delete: action(() => handleDelete()),
+  }
+)
+```
+
+## Component Integration
+
+Once you create the menu, you can bind its items as props to your template.
+
+For now, these bindings are meant to be used with a Vue component configured with the same props
+
+For other component or HTML Element, you can still bind the props manually.
+
+`action()` items will generate the following props binding:
+
+```ts
+type Props = {
+  as: 'button'
+  type: 'button'
+  disabled: boolean
+  busy: boolean
+  tooltip: string | false
+  onMouseenter: () => void
+  onClick: () => void
+  'data-menu-id': string
+}
+```
+
+`link()` items will generate the following props binding:
+
+```ts
+type Props = {
+  as: 'a'
+  href: string
+  rel: 'noreferrer noopener'
+  target: '_blank'
+  onMouseenter: () => void
+  onClick: () => void
+  'data-menu-id': string
+}
+```
+
+`routerLink()` items will generate the following props binding:
+
+```ts
+type Props = {
+  as: RouterLink
+  to: RouteLocationRaw
+  onMouseenter: () => void
+  onClick: () => void
+  'data-menu-id': string
+}
+```
+
+`toggle()` items will generate an object containing `$trigger`, `$target` and `$isOpen` (`ComputedRef<boolean>`) properties with the following props binding:
+
+```ts
+// $trigger
+type Props = {
+  as: 'button'
+  type: 'button'
+  submenu: true
+  ref: (el: any) => void
+  active: boolean
+  onClick: () => void
+  onMouseenter: () => void
+  'data-menu-id': string
+}
+
+// $target
+type Props = {
+  ref: (el: any) => void
+  style: object
+  'data-menu-id': string
+}
+```
+
+### Example
+
+```vue
+<template>
+  <MenuTrigger v-bind="menu.save">Save</MenuTrigger>
+  <MenuTrigger v-bind="menu.docs">Documentation</MenuTrigger>
+  <MenuTrigger v-bind="menu.profile">Profile</MenuTrigger>
+
+  <!-- Toggle/Dropdown menu -->
+  <MenuTrigger v-bind="menu.more.$trigger">More</MenuTrigger>
+  <div v-bind="menu.more.$target">
+    <MenuTrigger v-bind="menu.more.settings">Settings</MenuTrigger>
+    <MenuTrigger v-bind="menu.more.logout">Logout</MenuTrigger>
+  </div>
+</template>
+```
+
+If you want to bind props to an HTML element or a Vue component not supporting all the props,
+you can use VueUse's `objectOmit` for example or bind the props completely manually.
+
+```vue
+<script>
+import { objectOmit as omit } from '@vueuse/shared'
+</script>
+
+<template>
+  <MyCustomElement v-bind="omit(menu.save, ['as', 'type'])">Save</MyCustomElement>
+  <button v-bind="omit(menu.save, ['as', busy, 'tooltip'])" :class="{ busy: menu.save.busy }">Save</button>
+</template>
+```

package/lib/packages/menu/action.ts

@@ -0,0 +1,101 @@
+import { BaseItem, type Menu, type MenuLike, parseConfigHolder } from '@core/packages/menu'
+import { computed, type MaybeRefOrGetter, reactive, ref, toValue } from 'vue'
+
+export interface MenuActionConfig {
+  handler: () => any
+  disabled?: MaybeRefOrGetter<boolean | string | undefined>
+  busy?: MaybeRefOrGetter<boolean | string | undefined>
+}
+
+export class MenuActionConfigHolder {
+  constructor(public config: MenuActionConfig) {}
+}
+
+export interface MenuActionProps {
+  as: 'button'
+  type: 'button'
+  disabled: boolean
+  busy: boolean
+  tooltip: string | false
+  onClick: () => void
+  onMouseenter: () => void
+  'data-menu-id': string
+}
+
+export class MenuAction extends BaseItem {
+  isRunning = ref(false)
+
+  constructor(
+    public menu: Menu,
+    public config: MenuActionConfig
+  ) {
+    super(menu)
+  }
+
+  get busyConfig() {
+    return computed(() => toValue(this.config.busy) ?? false)
+  }
+
+  get isBusy() {
+    return computed(() => this.isRunning.value || this.busyConfig.value !== false)
+  }
+
+  get busyReason() {
+    return computed(() => (typeof this.busyConfig.value === 'string' ? this.busyConfig.value : undefined))
+  }
+
+  get disabledConfig() {
+    return computed(() => toValue(this.config.disabled) ?? false)
+  }
+
+  get isDisabled() {
+    return computed(() => this.isBusy.value || this.disabledConfig.value !== false)
+  }
+
+  get disabledReason() {
+    return computed(() => (typeof this.disabledConfig.value === 'string' ? this.disabledConfig.value : undefined))
+  }
+
+  get tooltip() {
+    return computed(() => this.disabledReason.value ?? this.busyReason.value ?? false)
+  }
+
+  get props(): MenuActionProps {
+    return reactive({
+      as: 'button',
+      type: 'button',
+      onClick: async () => {
+        if (this.isDisabled.value) {
+          return
+        }
+
+        this.isRunning.value = true
+
+        try {
+          await this.config.handler()
+          this.deactivate()
+        } finally {
+          this.isRunning.value = false
+        }
+      },
+      onMouseenter: () => this.activate(),
+      disabled: this.isDisabled,
+      busy: this.isBusy,
+      tooltip: this.tooltip,
+      'data-menu-id': this.menu.context.id,
+    })
+  }
+}
+
+export function action(handler: () => void, config: Omit<MenuActionConfig, 'handler'> = {}): MenuActionConfigHolder {
+  return new MenuActionConfigHolder({
+    ...config,
+    handler,
+  })
+}
+
+export function useMenuAction(config: MenuActionConfig & { parent: MenuLike }) {
+  const { parent, handler, ...configRest } = config
+
+  return parseConfigHolder(parent, action(handler, configRest))
+}