@xen-orchestra/web-core 0.56.0 → 0.58.0

package/lib/packages/overlay/README.md

@@ -0,0 +1,300 @@
+# Overlay
+
+Promise-based overlays (modals, drawers…) for Vue.
+
+You define an overlay from any component, open it, and `await` the user's decision.
+
+`useOverlay` takes a component-loader and the list of its events you want to handle. Events are identified by their handler prop name (`onYes` for a `yes` emit), and the keys are type-checked against the component's actual emits. In the following example, the overlay will automatically close when `ConfirmModal` emits `yes` or `no`:
+
+```ts
+const { open } = useOverlay({
+  component: () => import('path/to/ConfirmModal.vue'),
+  events: {
+    onYes: true,
+    onNo: true,
+  },
+})
+
+async function showConfirmation() {
+  const { event } = await open()
+
+  // At this point, the user has made a decision and the overlay is closed
+
+  if (event === 'onYes') {
+    // The user confirmed
+  }
+}
+```
+
+The promise resolves with `{ event, payload }` (see below) when the user makes a decision, and the overlay closes automatically.
+
+`true` is a shorthand for "when this event is emitted, close the overlay". The response payload is then `undefined`.
+
+## Passing props
+
+If the component has props, pass them to `open()`. They are fully type-checked, and `open()` won't compile without them if any prop is required:
+
+```ts
+const { open } = useOverlay({
+  component: () => import('path/to/VmConfirmModal.vue'),
+  events: {
+    onConfirm: true,
+    onCancel: true,
+  },
+})
+
+async function showConfirmation() {
+  const { event } = await open({
+    props: {
+      message: 'Are you sure you want to do this?',
+    },
+  })
+}
+```
+
+Props are passed as-is and captured when the overlay opens. To keep an overlay in sync with live data, pass a `reactive()` object containing computeds — or better, use `reactiveComputed` from VueUse:
+
+```ts
+const props = reactiveComputed(() => ({
+  message: `${selectedItems.value.length} items will be deleted`,
+}))
+
+async function showDeleteConfirmation() {
+  const { event } = await open({ props })
+}
+```
+
+## Custom handlers and payloads
+
+Instead of `true`, an event can have a handler. It receives the event's emit arguments, and whatever it returns (awaited) becomes the response payload:
+
+```ts
+const { open: openRenameModal } = useOverlay({
+  component: () => import('path/to/RenameModal.vue'),
+  events: {
+    onSubmit: (newName: string) => newName.trim(),
+    onCancel: true,
+  },
+})
+
+async function renameItem() {
+  const response = await openRenameModal()
+
+  if (response.event === 'onSubmit') {
+    response.payload // ← string (trimmed newName)
+  }
+}
+```
+
+The response is a discriminated union: narrowing on `response.event` narrows the type of `response.payload` accordingly.
+
+Handlers can be async. The overlay stays open (and is marked as busy, see below) while the handler runs, then closes when it resolves:
+
+```ts
+events: {
+  onSubmit: async (newName: string) => {
+    await api.rename(newName)
+  },
+  onCancel: true,
+}
+```
+
+While a handler is running, any further event is ignored: a double-click, or a click on Cancel during a save, does nothing.
+
+## Keeping the overlay open with `KEEP_OVERLAY_OPEN`
+
+Sometimes handling an event should _not_ close the overlay — a validation failure, a failed API call. Return `KEEP_OVERLAY_OPEN` for that:
+
+```ts
+const { open } = useOverlay({
+  component: () => import('path/to/RenameModal.vue'),
+  events: {
+    onSubmit: async (newName: string) => {
+      try {
+        await api.rename(newName)
+      } catch {
+        notify('Failed to rename')
+
+        return KEEP_OVERLAY_OPEN
+      }
+    },
+    onCancel: true,
+  },
+})
+```
+
+The overlay stays open, the promise stays pending, and the user can try again. `KEEP_OVERLAY_OPEN` is automatically excluded from the payload type.
+
+## Per-call handlers
+
+`open()` also accepts `events`. A per-call handler for an event that already has a `useOverlay` handler runs _after_ it: the per-call handler receives the payload the `useOverlay` handler produced, and returns the final payload (or `KEEP_OVERLAY_OPEN`):
+
+```ts
+const { open } = useOverlay({
+  component: () => import('path/to/RenameModal.vue'),
+  events: {
+    onSubmit: (newName: string) => newName.trim(),
+    onCancel: true,
+  },
+})
+
+async function renameItem(id: string) {
+  await open({
+    events: {
+      onSubmit: async newName => {
+        const success = await api.rename(id, newName)
+
+        if (!success) {
+          notify('Failed to rename')
+
+          return KEEP_OVERLAY_OPEN
+        }
+
+        return newName
+      },
+    },
+  })
+}
+```
+
+This is what makes composition work: the composable defining the overlay handles the generic part (extracting and cleaning the value), while each call site decides what to do with it.
+
+An event that is _not_ declared in `useOverlay` can also be handled at open time. Its handler then receives the raw emit arguments directly, and the event is added to the response union for that call.
+
+## Aborted overlays
+
+An overlay is not tied to the lifecycle of the component that opened it: it stays open until the user makes a decision, or until it is aborted. An overlay can be aborted in three ways:
+
+- `open()` is called again on the same `useOverlay` instance while the overlay is still open (the previous one is replaced),
+- the `abort()` function returned by `useOverlay` is called,
+- or the store's `abortAll()` is called (see below).
+
+In all cases the promise resolves with `OVERLAY_ABORT_EVENT` (a symbol) as its `event`, and no handler runs:
+
+```ts
+const response = await open()
+
+if (response.event === OVERLAY_ABORT_EVENT) {
+  return
+}
+```
+
+The `OVERLAY_ABORT_EVENT` case is always part of the response union, so exhaustive `event` checks will remind you it exists.
+
+Aborting an overlay whose decision is already being resolved is a no-op: the promise resolves with the actual response.
+
+An overlay can also be aborted while one of its handlers is still awaiting (for example, navigating away while a save is in progress). In that case the overlay closes right away with `OVERLAY_ABORT_EVENT`. The handler's async work keeps running — it cannot be cancelled — but the value it eventually returns is ignored, and the caller sees an abort.
+
+## Busy and disabled triggers
+
+Inside the overlay component, use `useOverlayTrigger()` to wire the controls that emit events (buttons, typically) to the overlay's state:
+
+```html
+<template>
+  <SomeModal @confirm="emit('submit')">
+    <div class="content">
+      <slot />
+    </div>
+    <div class="buttons">
+      <button type="submit" :disabled="isDisabled" @click="trigger">
+        <span v-if="isBusy">Saving...</span>
+        <span v-else>Save</span>
+      </button>
+    </div>
+  </SomeModal>
+</template>
+
+<script lang="ts" setup>
+  const emit = defineEmits<{
+    submit: []
+  }>()
+
+  const { isBusy, isDisabled, trigger } = useOverlayTrigger()
+</script>
+```
+
+- `isDisabled` is `true` while the overlay is handling an event — use it to disable every control.
+- `isBusy` is `true` while an async handler is running _and_ this trigger initiated it — use it to show a spinner on the right control only. For that, call `trigger()` when the control is activated, so the trigger identifies itself before the event is handled.
+
+Each `useOverlayTrigger()` call creates a distinct trigger, so two buttons never show a spinner at the same time. It works from any component rendered inside an overlay, at any depth, and is inert when the component is not rendered in an overlay.
+
+## Escape key
+
+`useOverlayEscape(handler)` calls the handler when Escape is pressed, but only while the calling component is the current (topmost) overlay and is not already handling an event. The handler is expected to emit the component's own close event, so that Escape goes through the exact same pipeline as a pointer interaction:
+
+```ts
+useOverlayEscape(() => emit('dismiss'))
+```
+
+Like `useOverlayTrigger()`, it works from any component rendered inside an overlay, and does nothing when the component is not rendered in an overlay.
+
+## Composition: building your own composable
+
+`useOverlay` is designed to be wrapped in small, domain-specific composables:
+
+```ts
+// use-user-delete-modal.ts
+export function useUserDeleteModal() {
+  return useOverlay({
+    component: () => import('path/to/UserDeleteModal.vue'),
+    events: {
+      onConfirm: true,
+      onCancel: true,
+    },
+  })
+}
+
+// use-user-delete.ts
+export function useUserDelete() {
+  const { open } = useUserDeleteModal()
+
+  async function deleteUser(user: User) {
+    await open({
+      events: {
+        onConfirm: () => api.deleteUser(user.id),
+      },
+      props: { name: user.name },
+    })
+  }
+
+  return { deleteUser }
+}
+```
+
+Call sites stay trivial:
+
+```html
+<template>
+  <button @click="deleteUser(user)">Delete</button>
+</template>
+
+<script lang="ts" setup>
+  const { deleteUser } = useUserDelete()
+</script>
+```
+
+## Rendering the overlays
+
+Opened overlays live in a Pinia store (`useOverlayStore`). The app must render them once, near the root, with `OverlayComponent`:
+
+```html
+<template>
+  <OverlayComponent v-for="overlay of overlayStore.overlays" :key="overlay.key" :overlay />
+</template>
+
+<script lang="ts" setup>
+  const overlayStore = useOverlayStore()
+</script>
+```
+
+Styling and animations are up to you. The store also exposes `isCurrent(key)` to style stacked overlays (e.g. dim the ones below the topmost), and each `overlay` carries its current `status`.
+
+Since overlays are not tied to the component that opened them, dismissing them on navigation is the app's decision. If that's the behavior you want, wire it once on the router:
+
+```ts
+router.isReady().then(() => {
+  router.afterEach(() => useOverlayStore().abortAll())
+})
+```
+
+Register the guard only once the router is ready: the initial navigation also triggers `afterEach`, which would abort any overlay opened while the app was starting up.

package/lib/packages/overlay/create-event-handler.ts

@@ -0,0 +1,73 @@
+import { isThenable } from '@core/packages/overlay/is-thenable.ts'
+import { KEEP_OVERLAY_OPEN } from '@core/packages/overlay/symbols.ts'
+import type { Overlay, OverlayEventHandler, OverlayResponse, OverlayStatus } from '@core/packages/overlay/types.ts'
+
+export function createEventHandler({
+  overlay,
+  definitionEvents,
+  openEvents,
+  settle,
+}: {
+  overlay: Overlay
+  definitionEvents: Record<string, true | OverlayEventHandler>
+  openEvents: Record<string, OverlayEventHandler>
+  settle: (response: OverlayResponse<PropertyKey, unknown>) => Promise<void>
+}) {
+  const shouldStop = (payload: unknown) => payload === KEEP_OVERLAY_OPEN || overlay.status === 'settled'
+
+  const runHandler = async (handler: OverlayEventHandler, handlerArgs: unknown[]) => {
+    const result = handler(...handlerArgs)
+
+    if (isThenable(result)) {
+      overlay.status = 'busy'
+    }
+
+    return await result
+  }
+
+  return async function handleEvent(eventName: string, emitArgs: unknown[]) {
+    if (overlay.status !== 'idle') {
+      return
+    }
+
+    try {
+      overlay.status = 'locked' as OverlayStatus
+
+      // The definition handler receives the raw emit arguments, then the open
+      // handler receives the payload it produced. An event handled at open
+      // time only receives the raw emit arguments directly.
+      let handlerArgs = emitArgs
+      let payload: unknown
+
+      const definitionHandler = definitionEvents[eventName]
+
+      if (definitionHandler !== undefined) {
+        payload = definitionHandler === true ? undefined : await runHandler(definitionHandler, handlerArgs)
+
+        if (shouldStop(payload)) {
+          return
+        }
+
+        handlerArgs = [payload]
+      }
+
+      const openHandler = openEvents[eventName]
+
+      if (openHandler !== undefined) {
+        payload = await runHandler(openHandler, handlerArgs)
+
+        if (shouldStop(payload)) {
+          return
+        }
+      }
+
+      await settle({ event: eventName, payload })
+    } finally {
+      if (overlay.status !== 'settled') {
+        overlay.status = 'idle'
+      }
+
+      overlay.lastTrigger = undefined
+    }
+  }
+}

package/lib/packages/overlay/injection-keys.ts

@@ -0,0 +1,3 @@
+import type { ComputedRef, InjectionKey } from 'vue'
+
+export const IK_OVERLAY_KEY = Symbol('IK_OVERLAY_KEY') as InjectionKey<ComputedRef<symbol>>

package/lib/packages/overlay/is-thenable.ts

@@ -0,0 +1,3 @@
+export function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return typeof (value as PromiseLike<unknown> | undefined)?.then === 'function'
+}

package/lib/packages/overlay/symbols.ts

@@ -0,0 +1,5 @@
+/** Returned from an event handler to keep the overlay open (e.g. after a validation failure) */
+export const KEEP_OVERLAY_OPEN = Symbol('keep overlay open')
+
+/** `event` of the response resolved when an overlay is torn down without a user decision (e.g. the opener's scope was disposed) */
+export const OVERLAY_ABORT_EVENT = Symbol('overlay aborted')

package/lib/packages/overlay/types.ts

@@ -0,0 +1,95 @@
+import type { KEEP_OVERLAY_OPEN, OVERLAY_ABORT_EVENT } from '@core/packages/overlay/symbols.ts'
+import type { Component } from 'vue'
+import type { ComponentProps } from 'vue-component-type-helpers'
+
+export type Prettify<T> = T extends infer R ? { [K in keyof R]: R[K] } & NonNullable<unknown> : never
+
+export type OverlayEvents<TComponent extends Component> = {
+  [TKey in ComponentEmitName<TComponent>]?:
+    | true
+    | ((...args: ExtractHandlerArgs<ComponentProps<TComponent>[TKey]>) => unknown)
+}
+
+// Generic inference skips excess property checks, so unknown event keys are
+// forced to `never` to be rejected at the call site
+export type ForbidExtraEvents<TComponent extends Component, TEvents> = Record<
+  Exclude<keyof TEvents, ComponentEmitName<TComponent>>,
+  never
+>
+
+export type OpenEvents<TComponent extends Component, TEvents extends OverlayEvents<TComponent>> = {
+  [TKey in ComponentEmitName<TComponent>]?: TKey extends keyof TEvents
+    ? (payload: ExtractHandlerPayload<TEvents[TKey]>) => unknown
+    : ComponentProps<TComponent>[TKey]
+}
+
+export type ResolvedPayload<TValue> = Exclude<Awaited<TValue>, typeof KEEP_OVERLAY_OPEN>
+
+export type ExtractHandlerPayload<THandler> = THandler extends (...args: never) => infer TReturn
+  ? ResolvedPayload<TReturn>
+  : THandler extends true
+    ? undefined
+    : never
+
+export type ExtractOverlayResponse<
+  TComponent extends Component,
+  TEvents extends OverlayEvents<TComponent>,
+  TOpenEvents extends OpenEvents<TComponent, TEvents>,
+> =
+  | Prettify<
+      {
+        [TKey in RequiredKeys<TOpenEvents>]: OverlayResponse<
+          TKey,
+          ExtractHandlerPayload<TOpenEvents[TKey & keyof TOpenEvents]>
+        >
+      }[RequiredKeys<TOpenEvents>]
+    >
+  | Prettify<
+      {
+        [TKey in Exclude<keyof TEvents, RequiredKeys<TOpenEvents>>]: OverlayResponse<
+          TKey,
+          ExtractHandlerPayload<TEvents[TKey]>
+        >
+      }[Exclude<keyof TEvents, RequiredKeys<TOpenEvents>>]
+    >
+  | OverlayResponse<typeof OVERLAY_ABORT_EVENT, undefined>
+
+export type OverlayStatus = 'idle' | 'locked' | 'busy' | 'settled'
+
+export interface Overlay {
+  key: symbol
+  component: Component
+  props: Record<string, unknown>
+  status: OverlayStatus
+  lastTrigger: symbol | undefined
+  abort: () => void
+}
+
+export type ExtractEventName<TName> = TName extends `onVnode${string}`
+  ? never
+  : TName extends `on${Capitalize<string>}`
+    ? TName
+    : never
+
+export type ExtractHandlerArgs<THandler> = THandler extends (...args: infer TArgs) => unknown ? TArgs : never
+
+export type ComponentEmitName<TComponent extends Component> = ExtractEventName<
+  keyof Required<ComponentProps<TComponent>>
+>
+
+export type RequiredKeys<TObject> = {
+  [TKey in keyof TObject]-?: NonNullable<unknown> extends Pick<TObject, TKey> ? never : TKey
+}[keyof TObject]
+
+export type OverlayEventHandler = (...args: unknown[]) => unknown
+
+export interface OverlayResponse<TEvent extends PropertyKey, TPayload> {
+  event: TEvent
+  payload: TPayload
+}
+
+export type MaybeOptionalArgs<TObject extends object> =
+  Partial<TObject> extends TObject ? [arg?: TObject] : [arg: TObject]
+
+export type MaybeOptionalKey<TKey extends PropertyKey, TObject extends object> =
+  Partial<TObject> extends TObject ? { [P in TKey]?: TObject } : { [P in TKey]: TObject }

package/lib/packages/overlay/use-overlay-escape.ts

@@ -0,0 +1,34 @@
+import { IK_OVERLAY_KEY } from '@core/packages/overlay/injection-keys.ts'
+import { useOverlayStore } from '@core/packages/overlay/use-overlay-store.ts'
+import { onKeyStroke } from '@vueuse/core'
+import { inject } from 'vue'
+
+/**
+ * Calls the handler when Escape is pressed while the calling component is the
+ * current (topmost) overlay and is not busy. The handler is expected to emit
+ * the component's own close event, so that Escape goes through the exact same
+ * pipeline as a pointer interaction.
+ */
+export function useOverlayEscape(handler: () => void) {
+  const overlayKey = inject(IK_OVERLAY_KEY, undefined)
+
+  if (overlayKey === undefined) {
+    return
+  }
+
+  const overlayStore = useOverlayStore()
+
+  onKeyStroke('Escape', () => {
+    if (!overlayStore.isCurrent(overlayKey.value)) {
+      return
+    }
+
+    const overlay = overlayStore.get(overlayKey.value)
+
+    if (overlay?.status !== 'idle') {
+      return
+    }
+
+    handler()
+  })
+}

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

@@ -0,0 +1,38 @@
+import type { Overlay } from '@core/packages/overlay/types.ts'
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+
+export const useOverlayStore = defineStore('overlay', () => {
+  const registry = ref(new Map<symbol, Overlay>())
+
+  function register(overlay: Overlay) {
+    registry.value.set(overlay.key, overlay)
+  }
+
+  function unregister(overlay: Overlay) {
+    if (registry.value.get(overlay.key) === overlay) {
+      registry.value.delete(overlay.key)
+    }
+  }
+
+  function abortAll() {
+    registry.value.forEach(overlay => overlay.abort())
+  }
+
+  function isCurrent(key: symbol): boolean {
+    return Array.from(registry.value.keys()).at(-1) === key
+  }
+
+  function get(key: symbol): Overlay | undefined {
+    return registry.value.get(key)
+  }
+
+  return {
+    overlays: computed(() => Array.from(registry.value.values())),
+    register,
+    unregister,
+    abortAll,
+    isCurrent,
+    get,
+  }
+})

package/lib/packages/overlay/use-overlay-trigger.ts

@@ -0,0 +1,33 @@
+import { IK_OVERLAY_KEY } from '@core/packages/overlay/injection-keys.ts'
+import { useOverlayStore } from '@core/packages/overlay/use-overlay-store.ts'
+import { computed, inject } from 'vue'
+
+export function useOverlayTrigger() {
+  const overlayKey = inject(IK_OVERLAY_KEY, undefined)
+
+  const triggerKey = Symbol('overlay trigger')
+
+  const overlayStore = useOverlayStore()
+
+  const overlay = computed(() => {
+    if (overlayKey === undefined) {
+      return undefined
+    }
+
+    return overlayStore.get(overlayKey.value)
+  })
+
+  const status = computed(() => overlay.value?.status ?? 'idle')
+
+  const isBusy = computed(() => overlay.value?.lastTrigger === triggerKey && status.value === 'busy')
+
+  const isDisabled = computed(() => status.value !== 'idle')
+
+  function trigger() {
+    if (overlay.value) {
+      overlay.value.lastTrigger = triggerKey
+    }
+  }
+
+  return { isBusy, isDisabled, trigger }
+}