@xen-orchestra/web-core 0.7.0 → 0.8.0

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))
+}

package/lib/packages/menu/base.ts

@@ -0,0 +1,26 @@
+import type { MenuAction, MenuLink, MenuRouterLink, MenuToggleTrigger, Menu } from '@core/packages/menu'
+import { computed } from 'vue'
+
+export type MenuItem = MenuAction | MenuLink | MenuRouterLink | MenuToggleTrigger
+
+export abstract class BaseItem {
+  id = Symbol('Menu Item')
+
+  protected constructor(public menu: Menu) {
+    menu.addItem(this as any)
+  }
+
+  get isActive() {
+    return computed(() => this.menu.context.activeItemId.value === this.id)
+  }
+
+  activate() {
+    this.menu.context.activeItemId.value = this.id
+  }
+
+  deactivate() {
+    if (this.isActive.value) {
+      this.menu.context.activeItemId.value = undefined
+    }
+  }
+}

package/lib/packages/menu/context.ts

@@ -0,0 +1,27 @@
+import { uniqueId } from '@core/utils/unique-id.util'
+import { useEventListener } from '@vueuse/core'
+import { type Ref, ref } from 'vue'
+
+export class MenuContext {
+  id: string
+
+  activeItemId: Ref<symbol | undefined> = ref()
+
+  constructor() {
+    this.id = uniqueId()
+
+    useEventListener(window, 'click', (event: PointerEvent) => {
+      if (this.hasSameController(event)) {
+        return
+      }
+
+      this.activeItemId.value = undefined
+    })
+  }
+
+  hasSameController(event: PointerEvent) {
+    return Array.from(window.document.querySelectorAll(`[data-menu-id="${this.id}"]`)).some(
+      el => el === event.target || event.composedPath().includes(el)
+    )
+  }
+}

package/lib/packages/menu/index.ts

@@ -0,0 +1,10 @@
+export * from './base'
+export * from './action'
+export * from './context'
+export * from './link'
+export * from './menu'
+export * from './router-link'
+export * from './structure'
+export * from './toggle'
+export * from './toggle-target'
+export * from './toggle-trigger'

package/lib/packages/menu/job.ts

@@ -0,0 +1,15 @@
+import type { Job } from '@core/packages/job'
+import { action } from '@core/packages/menu/action'
+import type { MenuLike } from '@core/packages/menu/menu'
+import { parseConfigHolder } from '@core/packages/menu/structure'
+
+export function job(job: Job<any>) {
+  return action(() => job.run(), {
+    busy: job.isRunning,
+    disabled: job.errorMessage,
+  })
+}
+
+export function useMenuJob(config: { job: Job<any>; parent: MenuLike }) {
+  return parseConfigHolder(config.parent, job(config.job))
+}

package/lib/packages/menu/link.ts

@@ -0,0 +1,56 @@
+import { BaseItem, type Menu, type MenuLike, parseConfigHolder } from '@core/packages/menu'
+import { computed, type MaybeRefOrGetter, reactive, toValue } from 'vue'
+
+export interface MenuLinkConfig {
+  href: MaybeRefOrGetter<string>
+  rel?: MaybeRefOrGetter<string>
+  target?: MaybeRefOrGetter<string>
+}
+
+export class MenuLinkConfigHolder {
+  constructor(public config: MenuLinkConfig) {}
+}
+
+export interface MenuLinkProps {
+  as: 'a'
+  href: string
+  rel: string
+  target: string
+  onClick: () => void
+  onMouseenter: () => void
+  'data-menu-id': string
+}
+
+export class MenuLink extends BaseItem {
+  constructor(
+    public menu: Menu,
+    public config: MenuLinkConfig
+  ) {
+    super(menu)
+  }
+
+  get props(): MenuLinkProps {
+    return reactive({
+      as: 'a',
+      onMouseenter: () => this.activate(),
+      onClick: () => this.deactivate(),
+      href: computed(() => toValue(this.config.href)),
+      rel: computed(() => toValue(this.config.rel) ?? 'noreferrer noopener'),
+      target: computed(() => toValue(this.config.target) ?? '_blank'),
+      'data-menu-id': this.menu.context.id,
+    })
+  }
+}
+
+export function link(href: MaybeRefOrGetter<string>, config: Omit<MenuLinkConfig, 'href'> = {}) {
+  return new MenuLinkConfigHolder({
+    ...config,
+    href,
+  })
+}
+
+export function useMenuLink(config: MenuLinkConfig & { parent: MenuLike }) {
+  const { parent, href, ...configRest } = config
+
+  return parseConfigHolder(parent, link(href, configRest))
+}

package/lib/packages/menu/menu.ts

@@ -0,0 +1,50 @@
+import {
+  MenuAction,
+  MenuContext,
+  MenuLink,
+  MenuRouterLink,
+  type MenuStructure,
+  MenuToggleTrigger,
+  type ParseStructure,
+  parseStructure,
+} from '@core/packages/menu'
+import { extendRef } from '@vueuse/core'
+import { computed, type ComputedRef, type MaybeRefOrGetter, shallowReactive, type ShallowReactive } from 'vue'
+
+export const MENU_SYMBOL = Symbol('Submenu')
+
+export type WithMenu = { [MENU_SYMBOL]: Menu }
+
+export type MenuLike = Menu | WithMenu
+
+type MenuItem = MenuAction | MenuLink | MenuRouterLink | MenuToggleTrigger
+
+export class Menu {
+  items: ShallowReactive<Map<symbol, MenuItem>> = shallowReactive(new Map())
+
+  isActive = computed(() => Array.from(this.items.values()).some(item => item.isActive.value))
+
+  constructor(public context: MenuContext) {}
+
+  addItem(item: MenuItem) {
+    this.items.set(item.id, item)
+  }
+}
+
+export function useMenu<const TStructure extends MenuStructure>(
+  structure: MaybeRefOrGetter<TStructure>
+): ComputedRef<ParseStructure<TStructure> & WithMenu> & WithMenu {
+  const context = new MenuContext()
+
+  const menu = new Menu(context)
+
+  return extendRef(
+    computed(() => {
+      return {
+        ...parseStructure(menu, structure),
+        [MENU_SYMBOL]: menu,
+      }
+    }),
+    { [MENU_SYMBOL]: menu }
+  )
+}