@xen-orchestra/web-core 0.20.1 → 0.21.0

package/lib/packages/icon/README.md

@@ -0,0 +1,286 @@
+# Icon System
+
+A flexible icon system for Vue applications supporting single icons, icon stacks, icon packs, and transformations.
+
+Currently supported icon format: FontAwesome, SimpleIcons
+
+## Core Concepts
+
+- **Icon**: A single SVG icon with transformations
+- **Icon Stack**: Multiple icons layered on top of each other
+- **Icon Pack**: A collection of related icons
+- **Transformations**: Size, color, rotation, flip, and other visual modifications
+
+## Usage
+
+### Basic Icon
+
+```vue
+<template>
+  <DisplayIcon :icon />
+</template>
+
+<script lang="ts" setup>
+const icon = defineIcon({
+  icon: faUser,
+  color: 'blue',
+  size: 24,
+})
+</script>
+```
+
+### Icon Stack
+
+```vue
+<template>
+  <DisplayIcon :icon="stackedIcon" />
+</template>
+
+<script lang="ts" setup>
+const stackedIcon = defineIcon([
+  { icon: faCircle, size: 24, color: 'blue' },
+  { icon: faStar, size: 18, color: 'white' },
+])
+</script>
+```
+
+### Icon Pack
+
+```vue
+<template>
+  <DisplayIcon :icon="icons.user" />
+  <DisplayIcon :icon="icons.star" />
+</template>
+
+<script lang="ts" setup>
+const icons = defineIconPack({
+  user: { icon: faUser, color: 'blue' },
+  star: { icon: faStar, color: 'gold' },
+})
+</script>
+```
+
+### Icon Variants
+
+```vue
+<template>
+  <DisplayIcon :icon="alerts['error:triangle']" />
+  <DisplayIcon :icon="alerts['warning:circle']" />
+</template>
+
+<script lang="ts" setup>
+const alerts = defineIcon(
+  [
+    ['error', 'warning'],
+    ['circle', 'triangle'],
+  ],
+  (status, shape) => {
+    const colors = {
+      error: 'red',
+      warning: 'orange',
+    }
+
+    const shapes = {
+      circle: faCircle,
+      triangle: defineIcon({ icon: faPlay, rotate: 90, size: 20 }),
+    }
+
+    return [
+      { icon: shapes[shape], color: colors[status] },
+      { icon: faExclamation, color: 'white' },
+    ]
+  }
+)
+</script>
+```
+
+## API Reference
+
+### Functions
+
+#### `defineIcon`
+
+Create a single icon, an icon stack, or an icon pack with variants.
+
+**Signature 1: Single Icon or Icon Stack**
+
+```ts
+defineIcon(config: IconSingleConfig): Icon
+defineIcon(icons: (IconSingleConfig | Icon)[], config?: IconStackConfig): IconStack
+```
+
+**Signature 2: Icon Variants**
+
+```ts
+defineIcon(
+  args: string[][],
+  builder: (...args: string[]) => DefineIconConfig,
+  stackConfig?: IconStackConfig
+): IconPack<string>
+```
+
+#### `defineIconPack`
+
+Create a collection of related icons.
+
+```ts
+defineIconPack(config: IconPackConfig): IconPack<string>
+```
+
+### Components
+
+#### `DisplayIcon`
+
+Root component that renders either a single icon or an icon stack.
+
+```vue
+<DisplayIcon :icon />
+```
+
+### Types
+
+#### `IconTransforms`
+
+Transformations that can be applied to icons.
+
+```ts
+type IconTransforms = {
+  borderColor?: string // Add a border around the icon
+  translate?: number | [number, number] // Move the icon
+  size?: number | [number, number] // Resize the icon
+  rotate?: number // Rotate the icon (in degrees)
+  flip?: 'horizontal' | 'vertical' | 'both' // Flip the icon
+  color?: string // Change icon color
+}
+```
+
+#### `IconSingleConfig`
+
+Configuration for a single icon.
+
+```ts
+type IconSingleConfig = {
+  icon?: IconDefinition | SimpleIcon | IconSingle | IconStack
+} & IconTransforms
+```
+
+#### `IconStackConfig`
+
+Configuration for an icon stack.
+
+```ts
+type IconStackConfig = IconTransforms
+```
+
+## Examples
+
+### Basic Transformations
+
+```vue
+<script lang="ts" setup>
+// Color
+const blueIcon = defineIcon({ icon: faUser, color: 'blue' })
+
+// Size
+const largeIcon = defineIcon({ icon: faUser, size: 32 })
+
+// Rotate
+const rotatedIcon = defineIcon({ icon: faUser, rotate: 45 })
+
+// Flip
+const flippedIcon = defineIcon({ icon: faUser, flip: 'horizontal' })
+
+// Multiple transformations
+const customIcon = defineIcon({
+  icon: faUser,
+  color: 'green',
+  size: 24,
+  rotate: 15,
+  translate: [2, 0],
+})
+</script>
+```
+
+### Complex Icon Stack
+
+```vue
+<script lang="ts" setup>
+import { defineIcon, DisplayIconAny } from '@core/packages/icon'
+import { faCircle, faSquare, faStar } from '@fortawesome/free-solid-svg-icons'
+
+const notificationIcon = defineIcon(
+  [
+    { icon: faCircle, size: 24, color: 'red' },
+    { icon: faSquare, size: 16, color: 'white', rotate: 45 },
+    { icon: faStar, size: 10, color: 'gold' },
+  ],
+  { translate: [2, 0] } // Global transforms applied to the entire stack
+)
+</script>
+```
+
+### Icon Variants
+
+```vue
+<script lang="ts" setup>
+const icon = defineIcon(
+  [
+    ['circle', 'square'],
+    ['!', '?'],
+  ],
+  (shape, type) => [
+    { icon: shape === 'circle' ? faCircle : faSquare },
+    {
+      icon: type === '!' ? faExclamation : faQuestion,
+      color: 'white',
+      size: 12,
+    },
+  ]
+)
+
+// You can now use icon['circle:!'], icon['circle:?'], icon['square:!'], icon['square:?']
+</script>
+```
+
+### Icon Pack with Namespaces
+
+```vue
+<script lang="ts" setup>
+import { defineIconPack, DisplayIconAny } from '@core/packages/icon'
+import { faUser, faUsers, faUserPlus } from '@fortawesome/free-solid-svg-icons'
+import { faFile, faFolder, faImage } from '@fortawesome/free-solid-svg-icons'
+
+const icons = defineIconPack({
+  user: defineIconPack({
+    single: { icon: faUser },
+    group: { icon: faUsers },
+    add: { icon: faUserPlus },
+  }),
+  file: defineIconPack({
+    document: { icon: faFile },
+    folder: { icon: faFolder },
+    image: { icon: faImage },
+  }),
+})
+
+// Access icons with namespace
+// icons['user:single']
+// icons['file:folder']
+</script>
+```
+
+### Reusable Icon with Different Transformations
+
+```vue
+<script lang="ts" setup>
+import { defineIcon, DisplayIconAny } from '@core/packages/icon'
+import { faExclamationTriangle } from '@fortawesome/free-solid-svg-icons'
+
+// Define base icon
+const warningIcon = defineIcon({ icon: faExclamationTriangle })
+
+// Create variations with different transformations
+const smallWarningIcon = defineIcon({ icon: warningIcon, size: 12 })
+const redWarningIcon = defineIcon({ icon: warningIcon, color: 'red' })
+</script>
+```

package/lib/packages/icon/create-icon-bindings.ts

@@ -0,0 +1,27 @@
+import type { IconBindings, IconTransforms } from './types.ts'
+import { toTuple } from './to-tuple.ts'
+
+export function createIconBindings(transforms: IconTransforms): IconBindings {
+  const [translateX, translateY] = toTuple(transforms.translate, [0, 0])
+
+  const shouldTranslate = translateX !== 0 || translateY !== 0
+
+  const [sizeX, sizeY] = toTuple(transforms.size, [16, 16])
+
+  const flipX = transforms.flip === 'horizontal' || transforms.flip === 'both' ? -1 : 1
+
+  const flipY = transforms.flip === 'vertical' || transforms.flip === 'both' ? -1 : 1
+
+  const [scaleX, scaleY] = [(sizeX / 16) * flipX, (sizeY / 16) * flipY]
+
+  const shouldScale = scaleX !== 1 || scaleY !== 1
+
+  return {
+    style: {
+      color: transforms.color,
+      translate: shouldTranslate ? `${(translateX / 16) * 100}% ${(translateY / 16) * 100}%` : undefined,
+      rotate: transforms.rotate ? `${transforms.rotate}deg` : undefined,
+      scale: shouldScale ? `${scaleX} ${scaleY}` : undefined,
+    },
+  }
+}

package/lib/packages/icon/define-icon-pack.ts

@@ -0,0 +1,23 @@
+import { defineIcon } from './define-icon.ts'
+import { type Icon, ICON_SYMBOL, type IconPack, type IconPackConfig, type IconPackKeys } from './types.ts'
+
+export function defineIconPack<TConfig extends IconPackConfig>(
+  config: TConfig
+): IconPack<IconPackKeys<NoInfer<TConfig>>> {
+  const result: Record<string, Icon> = Object.fromEntries(
+    Object.entries(config).flatMap(([key, value]) => {
+      if (!(ICON_SYMBOL in value)) {
+        return [[key, defineIcon(value)]]
+      }
+
+      return value[ICON_SYMBOL] === 'pack'
+        ? Object.entries(value).map(([subKey, subValue]) => [`${key}:${subKey}`, subValue])
+        : [[key, value as Icon]]
+    })
+  )
+
+  return {
+    ...result,
+    [ICON_SYMBOL]: 'pack',
+  } as IconPack<IconPackKeys<TConfig>>
+}

package/lib/packages/icon/define-icon-single.ts

@@ -0,0 +1,17 @@
+import { createIconBindings } from './create-icon-bindings.ts'
+import { mergeIcons } from './merge-icons.ts'
+import { normalizeIcon } from './normalize-icon.ts'
+import { type Icon, ICON_SYMBOL, type IconSingleConfig } from './types.ts'
+
+export function defineIconSingle(config: IconSingleConfig): Icon {
+  if (config.icon !== undefined && ICON_SYMBOL in config.icon) {
+    return mergeIcons(config.icon, config)
+  }
+
+  return {
+    [ICON_SYMBOL]: 'icon',
+    ...normalizeIcon(config.icon),
+    config,
+    bindings: createIconBindings(config),
+  }
+}

package/lib/packages/icon/define-icon-stack.ts

@@ -0,0 +1,20 @@
+import { createIconBindings } from './create-icon-bindings.ts'
+import { defineIconSingle } from './define-icon-single.ts'
+import { mergeIcons } from './merge-icons.ts'
+import { type Icon, ICON_SYMBOL, type IconSingleConfig, type IconStack, type IconStackConfig } from './types.ts'
+
+export function defineIconStack(
+  icons: IconStack | (IconSingleConfig | Icon)[],
+  config: IconStackConfig = {}
+): IconStack {
+  if (ICON_SYMBOL in icons) {
+    return mergeIcons(icons, config)
+  }
+
+  return {
+    [ICON_SYMBOL]: 'stack',
+    config,
+    icons: icons.map(icon => (ICON_SYMBOL in icon ? icon : defineIconSingle(icon))),
+    bindings: createIconBindings(config),
+  }
+}

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

@@ -0,0 +1,40 @@
+import { defineIconSingle } from './define-icon-single.ts'
+import { defineIconStack } from './define-icon-stack.ts'
+import { generateIconVariants } from './generate-icon-variants.ts'
+import {
+  type DefineIconConfig,
+  type Icon,
+  ICON_SYMBOL,
+  type IconArgsToNames,
+  type IconPack,
+  type IconStackConfig,
+  type ArgsConfigToBuilderArgs,
+} from './types.ts'
+
+type ArgsValue = string[][]
+
+export function defineIcon(configOrIcons: DefineIconConfig, stackConfig?: IconStackConfig): Icon
+
+export function defineIcon<
+  const TArgsConfig extends ArgsValue,
+  TArgs extends ArgsConfigToBuilderArgs<TArgsConfig>,
+  TNames extends IconArgsToNames<TArgs>,
+>(args: TArgsConfig, builder: (...args: TArgs) => DefineIconConfig, stackConfig?: IconStackConfig): IconPack<TNames>
+
+export function defineIcon(
+  configOrIconsOrArgs: DefineIconConfig | ArgsValue,
+  stackConfigOrBuilder?: IconStackConfig | ((...args: string[]) => DefineIconConfig),
+  stackConfigOrNone?: IconStackConfig
+): Icon | IconPack<any> {
+  if (typeof stackConfigOrBuilder === 'function') {
+    return generateIconVariants(configOrIconsOrArgs as ArgsValue, stackConfigOrBuilder, stackConfigOrNone)
+  }
+
+  const configOrIcons = configOrIconsOrArgs as DefineIconConfig
+
+  if (Array.isArray(configOrIcons) || ICON_SYMBOL in configOrIcons) {
+    return defineIconStack(configOrIcons, stackConfigOrBuilder)
+  }
+
+  return defineIconSingle(configOrIcons)
+}

package/lib/packages/icon/generate-icon-variants.ts

@@ -0,0 +1,17 @@
+import { defineIconPack } from './define-icon-pack.ts'
+import { defineIcon } from './define-icon.ts'
+import { type DefineIconConfig, type IconPack, type IconStackConfig } from './types.ts'
+
+export function generateIconVariants<TArgs extends string[][]>(
+  argsConfigs: TArgs,
+  setup: (...args: any[]) => DefineIconConfig,
+  stackConfig: IconStackConfig | undefined
+): IconPack<any> {
+  const argsCombinations = argsConfigs.reduce((acc, arr) => acc.flatMap(prefix => arr.map(item => [...prefix, item])), [
+    [],
+  ] as string[][])
+
+  return defineIconPack(
+    Object.fromEntries(argsCombinations.map(args => [args.join(':'), defineIcon(setup(...args), stackConfig)]))
+  )
+}

package/lib/packages/icon/index.ts

@@ -0,0 +1,8 @@
+export * from './define-icon.ts'
+export * from './define-icon-pack.ts'
+export * from './types.ts'
+
+export { default as DisplayIcon } from './DisplayIcon.vue'
+export { default as DisplayIconAny } from './DisplayIconAny.vue'
+export { default as DisplayIconSingle } from './DisplayIconSingle.vue'
+export { default as DisplayIconStack } from './DisplayIconStack.vue'

package/lib/packages/icon/is-icon-stack.ts

@@ -0,0 +1,5 @@
+import { type Icon, ICON_SYMBOL, type IconStack } from './types.ts'
+
+export function isIconStack(icon: Icon): icon is IconStack {
+  return icon[ICON_SYMBOL] === 'stack'
+}

package/lib/packages/icon/merge-icons.ts

@@ -0,0 +1,25 @@
+import { defineIconSingle } from './define-icon-single.ts'
+import { defineIconStack } from './define-icon-stack.ts'
+import { mergeTransforms } from './merge-transforms.ts'
+import {
+  type Icon,
+  ICON_SYMBOL,
+  type IconSingle,
+  type IconSingleConfig,
+  type IconStack,
+  type IconStackConfig,
+} from './types.ts'
+
+export function mergeIcons<TOriginal extends Icon>(
+  original: TOriginal,
+  newConfig: TOriginal extends IconSingle ? IconSingleConfig : IconSingleConfig | IconStackConfig
+): TOriginal extends IconSingle ? Icon : IconStack {
+  if (original[ICON_SYMBOL] === 'stack') {
+    return defineIconStack(original.icons, mergeTransforms(original.config, newConfig))
+  }
+
+  return defineIconSingle({
+    icon: original.config.icon,
+    ...mergeTransforms(original.config, newConfig),
+  }) as TOriginal extends IconSingle ? Icon : IconStack
+}

package/lib/packages/icon/merge-transforms.ts

@@ -0,0 +1,12 @@
+import type { IconTransforms } from './types.ts'
+
+export function mergeTransforms(source: IconTransforms, target: IconTransforms): IconTransforms {
+  return {
+    translate: target.translate ?? source.translate,
+    size: target.size ?? source.size,
+    rotate: target.rotate ?? source.rotate,
+    flip: target.flip ?? source.flip,
+    color: target.color ?? source.color,
+    borderColor: target.borderColor ?? source.borderColor,
+  }
+}

package/lib/packages/icon/normalize-icon.ts

@@ -0,0 +1,25 @@
+import { toArray } from '@core/utils/to-array.utils.ts'
+import type { NormalizedIcon } from './types.ts'
+import type { IconDefinition } from '@fortawesome/fontawesome-common-types'
+import type { SimpleIcon } from 'simple-icons'
+
+export function normalizeIcon(icon: IconDefinition | SimpleIcon | undefined): NormalizedIcon {
+  if (icon === undefined) {
+    return {
+      viewBox: '',
+      paths: [],
+    }
+  }
+
+  if ('icon' in icon) {
+    return {
+      viewBox: `0 0 ${icon.icon[0]} ${icon.icon[1]}`,
+      paths: toArray(icon.icon[4]),
+    }
+  }
+
+  return {
+    viewBox: '0 0 24 24',
+    paths: toArray(icon.path),
+  }
+}

package/lib/packages/icon/to-tuple.ts

@@ -0,0 +1,7 @@
+export function toTuple<T>(value: undefined | T | [T, T], defaultValue: [T, T]): [T, T] {
+  if (value === undefined) {
+    return defaultValue
+  }
+
+  return Array.isArray(value) ? value : [value, value]
+}

package/lib/packages/icon/types.ts

@@ -0,0 +1,72 @@
+import type { IconDefinition } from '@fortawesome/fontawesome-common-types'
+import type { SimpleIcon } from 'simple-icons'
+
+export const ICON_SYMBOL = Symbol('Icon')
+
+export type IconTransforms = {
+  borderColor?: string
+  translate?: number | [number, number]
+  size?: number | [number, number]
+  rotate?: number
+  flip?: 'horizontal' | 'vertical' | 'both'
+  color?: string
+}
+
+export type IconSingleConfig = {
+  icon?: IconDefinition | SimpleIcon | IconSingle | IconStack
+} & IconTransforms
+
+export type IconStackConfig = IconTransforms
+
+export type IconBindings = {
+  style?: {
+    color?: string
+    rotate?: string
+    translate?: string
+    scale?: string
+  }
+}
+
+export type IconSingle = NormalizedIcon & {
+  [ICON_SYMBOL]: 'icon'
+  config: IconSingleConfig
+  bindings: IconBindings
+}
+
+export type IconStack = {
+  [ICON_SYMBOL]: 'stack'
+  icons: Icon[]
+  config: IconStackConfig
+  bindings: IconBindings
+}
+
+export type Icon = IconSingle | IconStack
+
+export type IconPackKeys<TConfig extends object> = keyof {
+  [K in keyof TConfig as TConfig[K] extends IconPack<infer TKey> ? `${K & string}:${TKey}` : K]: true
+}
+
+export type IconPackConfig = Record<string, Icon | IconPack<string> | DefineIconConfig>
+
+export type IconPack<TKeys extends string> = {
+  [ICON_SYMBOL]: 'pack'
+} & {
+  [K in TKeys]: Icon
+}
+
+export type ArgsConfigToBuilderArgs<T extends string[][]> = {
+  [K in keyof T]: T[K][number]
+}
+
+export type IconArgsToNames<TArgs extends any[]> = TArgs extends [infer TFirst, ...infer TRest]
+  ? TRest extends []
+    ? TFirst
+    : `${TFirst & string}:${IconArgsToNames<TRest>}`
+  : never
+
+export type DefineIconConfig = IconSingleConfig | IconStack | (IconSingleConfig | IconStack)[]
+
+export type NormalizedIcon = {
+  viewBox: string
+  paths: string[]
+}

package/lib/packages/job/README.md

@@ -42,7 +42,7 @@ const forceArg = defineJobArg<boolean>({
 ```typescript
 const myJob = defineJob('processItems', [userIdArg, itemsArg, optionsArg], () => ({
   validate(isRunning, userId, items) {
-    // You can use custom running check additionnal to internal one
+    // You can use custom running check additional to internal one
     if (isRunning || isProcessingItems(userId, items)) {
       throw new JobRunningError('Items are being processed')
     }
@@ -57,7 +57,7 @@ const myJob = defineJob('processItems', [userIdArg, itemsArg, optionsArg], () =>
   },
   run(userId, items, force) {
     // Job implementation
-    return procesItems(userId, items, force)
+    return processItems(userId, items, force)
   },
 }))
 ```