@xen-orchestra/web-core 0.31.1 → 0.32.0

package/lib/packages/table/README.md

@@ -0,0 +1,336 @@
+# Table System
+
+Table system that separates data logic from presentation through reusable renderers.
+
+## Understanding Renderers
+
+A **renderer** is a function that creates a VNode for a specific part of the table (cell, row, or table). When you define a renderer, you specify:
+
+1. **Component**: The Vue component to render (loaded asynchronously)
+2. **Props function** (optional): Default props based on configuration
+3. **Extensions** (optional): Named categories of additional functionality
+
+### Props System
+
+The `props` parameter is a function that receives an optional typed config and returns default props:
+
+```typescript
+const TextBody = defineTableCellRenderer({
+  component: () => import('./TextCell.vue'),
+  props: (config: { text: string }) => ({ data: config.text }),
+  //      ^ This config type will be enforced when using the renderer
+})
+
+// Usage - TypeScript knows you need to provide `text`
+TextBody({ text: 'Hello' })
+```
+
+When you use the renderer, you can:
+
+- Provide the expected config to satisfy the `props` function
+- Add additional props that will be merged
+- Override default props
+
+```typescript
+// The renderer merges:
+// 1. Props from the props function: { text: 'Hello' }
+// 2. Additional/override props: { class: 'custom' }
+TextBody({
+  text: 'Hello', // Used by props function
+  props: {
+    // Additional or override props
+    class: 'custom',
+  },
+})
+```
+
+### Extensions System
+
+Extensions work like the `props` function but are optional and named. Each extension:
+
+- Has a unique name (like `selectable`, `highlightable`)
+- Receives typed configuration
+- Returns the extension arguments (only `props` for now) to merge into the component
+
+```typescript
+const MyRow = defineTableRowRenderer({
+  component: () => import('./Row.vue'),
+  extensions: {
+    selectable: (config: { id: string; selectedId: Ref<string | null> }) => ({
+      props: {
+        selected: config.id === config.selectedId.value,
+      },
+    }),
+    highlightable: (config: { isHighlighted: boolean }) => ({
+      props: {
+        highlighted: config.isHighlighted,
+      },
+    }),
+  },
+})
+
+// Usage - provide config for the extensions you want to use
+MyRow({
+  cells: () => [...],
+  extensions: {
+    selectable: { id: user.id, selectedId },
+    highlightable: { isHighlighted: true },
+  }
+})
+```
+
+Extensions are optional when using the renderer - you only provide the ones you need.
+
+## Defining Renderers
+
+### Cell Renderers
+
+Create header and body cell renderers:
+
+```typescript
+import { defineTableCellRenderer } from '@core/packages/table'
+
+const TextHeader = defineTableCellRenderer({
+  component: () => import('./VtsHeaderCell.vue'),
+  props: (config: { label: string }) => ({
+    label: config.label,
+    icon: icon('fa:align-left'),
+  }),
+})
+
+const TextBody = defineTableCellRenderer({
+  component: () => import('./body-cells/VtsTextCell.vue'),
+  props: (config: { text: string | number }) => ({ text: config.text }),
+})
+
+// Usage
+TextHeader({ label: 'Name' })
+TextBody({ text: user.name })
+```
+
+### Row Renderers
+
+Create row renderer:
+
+```typescript
+import { defineTableRowRenderer } from '@core/packages/table'
+
+const DefaultRow = defineTableRowRenderer({
+  component: () => import('./VtsRow.vue'),
+})
+
+DefaultRow({
+  cells: () => [...]
+})
+```
+
+### Table Renderers
+
+Create table renderer:
+
+```typescript
+import { defineTableRenderer } from '@core/packages/table'
+
+const DefaultTable = defineTableRenderer({
+  component: () => import('./VtsTableNew.vue'),
+})
+
+// Usage
+DefaultTable({
+  thead: MyThead(...),
+  // thead: { rows: () => [...] },  // to use native "thead"
+  // thead: { cells: () => [...] }, // to use native "thead" + "tr",
+  tbody: MyTBody(...),
+  // tbody: { rows: () => [...] }, // to use native "tbody"
+})
+```
+
+## Building Tables
+
+### Column Definition
+
+Use `defineColumns` to create columns configuration.
+
+```typescript
+const columns = defineColumns({
+  name: {
+    header: () => TextHeader({ label: 'Name' }),
+    body: user => TextBody({ text: user.name }),
+  },
+  email: {
+    header: () => TextHeader({ label: 'Email' }),
+    body: user => TextBody({ text: user.email }),
+  },
+  // Conditional column
+  role: isAdmin
+    ? {
+        header: () => TextHeader({ label: 'Role' }),
+        body: user => TextBody({ text: user.role }),
+      }
+    : undefined,
+})
+```
+
+`header` and `body` can also take a config parameter if needed:
+
+```typescript
+const columns = defineColumns({
+  name: {
+    header: (config) => TextHeader(...),
+    body: (user, config) => TextBody(...),
+  },
+})
+```
+
+```typescript
+// API
+columns.getHeaderCells(config?) // Array of header cell VNodes
+columns.getBodyCells(user, config?) // Array of body cell VNodes for a row
+columns.toggleColumn('name') // Toggle column visibility
+columns.toggleColumn('name', true) // Force column visibility
+columns.visibleColumnsCount // ComputedRef<number>, useful for colspan
+```
+
+### Table Definition
+
+Use one of three table definition functions:
+
+#### Define basic single-source table: `defineTable`
+
+```typescript
+const { getHeaderCells, getBodyCells } = defineColumns(...)
+
+const useUserTable = defineTable((sources: ComputedRef<User[]>) =>
+  () => DefaultTable({
+    thead: {
+      cells: () => getHeaderCells()
+    },
+    tbody: {
+      rows: () => sources.value.map(user =>
+        DefaultRow({
+          cells: () => getBodyCells(user)
+        })
+      )
+    },
+  })
+)
+```
+
+```typescript
+// Usage
+const users = ref<User[]>([...])
+
+const table = useUserTable(users, {})
+```
+
+`defineTable` setup function can also define a config parameter as second argument:
+
+```typescript
+const useUserTable = defineTable((sources: ComputedRef<User[]>, config: { needThis: string }) => ...)
+
+const table = useUserTable(users, { needThis: 'value' })
+```
+
+#### Define type-discriminated table: `defineTypedTable`
+
+```typescript
+type Source = { type: 'user'; sources: ComputedRef<User[]> } | { type: 'admin'; sources: ComputedRef<Admin[]> }
+
+const useItemTable = defineTypedTable(({ type, sources }: Source) => {
+  // If type === 'user', sources is ComputedRef<User[]>
+  // If type === 'admin', sources is ComputedRef<Admin[]>
+
+  return () => DefaultTable({...})
+})
+
+// Usage
+useItemTable('admin', admins, {})
+```
+
+#### Define multiple sources table: `defineMultiSourceTable`
+
+```typescript
+type Sources = {
+  users: ComputedRef<User[]>
+  admins: ComputedRef<Admin[]>
+}
+
+const useDashboard = defineMultiSourceTable((sources: Sources) => {
+  // sources.users: ComputedRef<User[]>
+  // sources.admins: ComputedRef<Admin[]>
+
+  return () => DefaultTable({...})
+})
+
+// Usage
+useDashboard({ users, admins }, {})
+```
+
+### Source Transformation
+
+When using a defined table, if passed sources doesn't match expected sources, then a `transform` config will be required to add missing or incorrectly typed properties:
+
+```typescript
+type User = {
+  id: string
+  fullName: string
+}
+
+const useUserTable = defineTable((sources: ComputedRef<User[]>) => {})
+
+// Raw data has different shape
+interface RawUser {
+  uuid: string
+  firstName: string
+  lastName: string
+}
+
+// Transform is required when types don't match
+useUserTable(rawUsers, {
+  transform: user => ({
+    id: user.uuid,
+    fullName: `${user.firstName} ${user.lastName}`,
+  }),
+})
+
+// Transform is optional when types already match
+useUserTable(users, {})
+```
+
+## Rendering the table
+
+```vue
+<template>
+  <MyUsersTable />
+</template>
+
+<script setup lang="ts">
+const MyUsersTable = useUsersTable(users, {})
+</script>
+```
+
+## Props
+
+When a table is rendered, each element's props will be merged together in the following order:
+
+1. Props from the renderer `props` function
+2. Props from extensions `props` functions
+3. Props provided when using the renderer
+
+They will be merged with Vue's default merging strategy (for example, `class` and `style` will be concatenated).
+
+## API Reference
+
+### Renderer Functions
+
+- `defineTableRenderer` - Define table wrapper (`table`)
+- `defineTableSectionRenderer` - Define table sections (`thead` / `tbody`)
+- `defineTableRowRenderer` - Define table rows (`tr`)
+- `defineTableCellRenderer` - Define table cells (`th` / `td`)
+
+### Table Functions
+
+- `defineTable` - Single source table
+- `defineTypedTable` - Type-discriminated table
+- `defineMultiSourceTable` - Multiple sources table
+- `defineColumns` - Column definitions

package/lib/packages/table/apply-extensions.ts

@@ -0,0 +1,26 @@
+import type { Extensions } from '.'
+import { mergeProps } from 'vue'
+
+export function applyExtensions(
+  config: {
+    props?: (config: any) => Record<string, any>
+    extensions?: Extensions<any>
+  },
+  renderConfig: {
+    props?: Record<string, any>
+    extensions?: Record<string, any>
+  }
+): { props: Record<string, any> } {
+  const baseProps = mergeProps(config.props?.(renderConfig) ?? {}, renderConfig.props ?? {})
+
+  if (!renderConfig.extensions) {
+    return { props: baseProps }
+  }
+
+  const props = Object.entries(renderConfig.extensions).reduce(
+    (props, [extName, extData]) => mergeProps(props, config.extensions?.[extName!](extData).props ?? {}),
+    baseProps
+  )
+
+  return { props }
+}

package/lib/packages/table/define-columns.ts

@@ -0,0 +1,62 @@
+import type { TableCellVNode } from '.'
+import { reactive, computed } from 'vue'
+
+export function defineColumns<
+  TSource,
+  TColumns extends Record<
+    string,
+    | {
+        header: (arg: THeaderArg) => TableCellVNode
+        body: (source: TSource, arg: TBodyArg) => TableCellVNode
+      }
+    | undefined
+  >,
+  TColumnName extends Extract<keyof TColumns, string>,
+  THeaderArg = undefined,
+  TBodyArg = undefined,
+>(
+  config: TColumns &
+    Record<
+      string,
+      | {
+          header: (arg: THeaderArg) => TableCellVNode
+          body: (source: TSource, arg: TBodyArg) => TableCellVNode
+        }
+      | undefined
+    >
+) {
+  const columnNames = Object.keys(config).filter(key => config[key] !== undefined) as TColumnName[]
+
+  const hiddenColumnNames = reactive(new Set()) as Set<TColumnName>
+
+  const visibleColumnNames = computed(() => columnNames.filter(name => !hiddenColumnNames.has(name)))
+
+  const visibleColumns = computed(() => visibleColumnNames.value.map(name => config[name]!))
+
+  const visibleColumnsCount = computed(() => visibleColumnNames.value.length)
+
+  type GetHeaderCells = THeaderArg extends undefined
+    ? (arg?: THeaderArg) => TableCellVNode[]
+    : (arg: THeaderArg) => TableCellVNode[]
+
+  type GetBodyCells = TBodyArg extends undefined
+    ? (source: TSource, arg?: TBodyArg) => TableCellVNode[]
+    : (source: TSource, arg: TBodyArg) => TableCellVNode[]
+
+  return {
+    getHeaderCells: ((arg?: THeaderArg) =>
+      visibleColumns.value.map(column => column.header(arg as THeaderArg))) as GetHeaderCells,
+
+    getBodyCells: ((source: TSource, arg?: TBodyArg) =>
+      visibleColumns.value.map(column => column.body(source, arg as TBodyArg))) as GetBodyCells,
+
+    toggleColumn: (name: TColumnName, forcedValue = !hiddenColumnNames.has(name)) => {
+      if (forcedValue) {
+        hiddenColumnNames.add(name)
+      } else {
+        hiddenColumnNames.delete(name)
+      }
+    },
+    visibleColumnsCount,
+  }
+}

package/lib/packages/table/define-renderer/define-table-cell-renderer.ts

@@ -0,0 +1,27 @@
+import { type VNode, defineAsyncComponent, h } from 'vue'
+import {
+  type TableCellRenderer,
+  type TableCellVNode,
+  type Extensions,
+  applyExtensions,
+  type ComponentLoader,
+  type PropsOverride,
+} from '..'
+
+export function defineTableCellRenderer<
+  TComponentProps extends Record<string, any>,
+  TExtensions extends Extensions<TComponentProps>,
+  TPropsConfig extends Record<string, any>,
+>(config: {
+  component: ComponentLoader<TComponentProps>
+  props?: (config: TPropsConfig) => PropsOverride<TComponentProps>
+  extensions?: TExtensions
+}): TableCellRenderer<TComponentProps, TExtensions, TPropsConfig> {
+  const component = defineAsyncComponent(config.component)
+
+  return function RenderCell(renderConfig) {
+    const extension = applyExtensions(config, renderConfig)
+
+    return h(component, extension.props) satisfies VNode as TableCellVNode
+  }
+}

package/lib/packages/table/define-renderer/define-table-renderer.ts

@@ -0,0 +1,47 @@
+import { type VNode, defineAsyncComponent, h } from 'vue'
+import {
+  applyExtensions,
+  type ComponentLoader,
+  type PropsOverride,
+  type Extensions,
+  type TableRenderer,
+  type TableVNode,
+} from '..'
+
+export function defineTableRenderer<
+  TComponentProps extends Record<string, any>,
+  TExtensions extends Extensions<TComponentProps>,
+  TPropsConfig extends Record<string, any>,
+>(config: {
+  component: ComponentLoader<TComponentProps>
+  props?: (config: TPropsConfig) => PropsOverride<TComponentProps>
+  extensions?: TExtensions
+}): TableRenderer<TComponentProps, TExtensions, TPropsConfig> {
+  const component = defineAsyncComponent(config.component)
+
+  return function RenderTable(renderConfig) {
+    const { thead, tbody } = renderConfig
+
+    const renderThead =
+      typeof thead === 'function'
+        ? thead
+        : 'cells' in thead && thead.cells
+          ? () => h('thead', {}, h('tr', {}, { default: () => thead.cells() }))
+          : 'rows' in thead && thead.rows
+            ? () => h('thead', {}, { default: () => thead.rows() })
+            : () => undefined
+
+    const renderTbody =
+      typeof tbody === 'function'
+        ? tbody
+        : 'rows' in tbody && tbody.rows
+          ? () => h('tbody', {}, { default: () => tbody.rows() })
+          : () => undefined
+
+    const extension = applyExtensions(config, renderConfig)
+
+    return h(component, extension.props, () => {
+      return [renderThead(), renderTbody()]
+    }) satisfies VNode as TableVNode
+  }
+}

package/lib/packages/table/define-renderer/define-table-row-renderer.ts

@@ -0,0 +1,29 @@
+import { type VNode, defineAsyncComponent, h } from 'vue'
+import {
+  applyExtensions,
+  type TableRowRenderer,
+  type TableRowVNode,
+  type Extensions,
+  type ComponentLoader,
+  type PropsOverride,
+} from '..'
+
+export function defineRowRenderer<
+  TComponentProps extends Record<string, any>,
+  TExtensions extends Extensions<TComponentProps>,
+  TPropsConfig extends Record<string, any>,
+>(config: {
+  component: ComponentLoader<TComponentProps>
+  props?: (config: TPropsConfig) => PropsOverride<TComponentProps>
+  extensions?: TExtensions
+}): TableRowRenderer<TComponentProps, TExtensions, TPropsConfig> {
+  const component = defineAsyncComponent(config.component)
+
+  return function RenderRow(renderConfig): TableRowVNode {
+    const extension = applyExtensions(config, renderConfig)
+
+    return h(component, extension.props, {
+      default: () => renderConfig.cells(),
+    }) satisfies VNode as TableRowVNode
+  }
+}

package/lib/packages/table/define-renderer/define-table-section-renderer.ts

@@ -0,0 +1,29 @@
+import { type VNode, defineAsyncComponent, h } from 'vue'
+import {
+  applyExtensions,
+  type TableSectionRenderer,
+  type TableSectionVNode,
+  type Extensions,
+  type ComponentLoader,
+  type PropsOverride,
+} from '..'
+
+export function defineSectionRenderer<
+  TComponentProps extends Record<string, any>,
+  TExtensions extends Extensions<TComponentProps>,
+  TPropsConfig extends Record<string, any>,
+>(config: {
+  component: ComponentLoader<TComponentProps>
+  props?: (config: TPropsConfig) => PropsOverride<TComponentProps>
+  extensions?: TExtensions
+}): TableSectionRenderer<TComponentProps, TExtensions, TPropsConfig> {
+  const component = defineAsyncComponent(config.component)
+
+  return function RenderSection(renderConfig): TableSectionVNode {
+    const extension = applyExtensions(config, renderConfig)
+
+    return h(component, extension.props, {
+      default: () => renderConfig.rows(),
+    }) satisfies VNode as TableSectionVNode
+  }
+}

package/lib/packages/table/define-table/define-multi-source-table.ts

@@ -0,0 +1,39 @@
+import { type MaybeRefOrGetter } from 'vue'
+import { type Sources, type TransformProperty, transformSources } from '..'
+
+export function defineMultiSourceTable<
+  TSources extends Record<string, Sources>,
+  TConfig extends Record<string, unknown> = Record<string, unknown>,
+>(setup: (sources: TSources, config: TConfig) => any) {
+  return function useTable<
+    TUseSources extends {
+      [K in keyof TSources]: any
+    },
+    TTransforms extends {
+      [K in keyof TSources]: TSources[K] extends Sources<infer T>
+        ? TransformProperty<T, TUseSources[K], K & string>[K & string]
+        : never
+    },
+  >(
+    sources: {
+      [K in keyof TUseSources]: MaybeRefOrGetter<TUseSources[K][]>
+    },
+    config: TConfig &
+      (Record<keyof TTransforms, undefined> extends TTransforms
+        ? { transform?: Partial<TTransforms> }
+        : {
+            transform: { [K in keyof TTransforms as undefined extends TTransforms[K] ? K : never]?: TTransforms[K] } & {
+              [K in keyof TTransforms as undefined extends TTransforms[K] ? never : K]: TTransforms[K]
+            }
+          })
+  ) {
+    const transformedSources = Object.fromEntries(
+      Object.entries(sources).map(([key, value]) => [
+        key,
+        transformSources(value, (config.transform as any)?.[key as any]),
+      ])
+    )
+
+    return setup(transformedSources as TSources, config)
+  }
+}

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

@@ -0,0 +1,13 @@
+import { type MaybeRefOrGetter } from 'vue'
+import { type Sources, type TableVNode, type TransformProperty, transformSources } from '..'
+
+export function defineTable<TSource, TConfig extends Record<string, unknown> = Record<string, unknown>>(
+  setup: (sources: Sources<TSource>, config: TConfig) => () => TableVNode
+) {
+  return function useTable<TUseSource>(
+    sources: MaybeRefOrGetter<TUseSource[]>,
+    config: TConfig & TransformProperty<TSource, TUseSource>
+  ) {
+    return setup(transformSources<TSource>(sources, config?.transform), config)
+  }
+}

package/lib/packages/table/define-table/define-typed-table.ts

@@ -0,0 +1,18 @@
+import { type MaybeRefOrGetter } from 'vue'
+import { type Sources, type TransformProperty, transformSources } from '..'
+
+export function defineTypedTable<
+  TTypedSource extends { type: string; data: Sources },
+  TConfig extends Record<string, unknown> = Record<string, unknown>,
+>(setup: (typedSource: TTypedSource, config: TConfig) => any) {
+  return function useTable<
+    TUseSource,
+    const TType extends TTypedSource['type'],
+    TSource extends TTypedSource extends { type: TType; data: Sources<infer TSource> } ? TSource : never,
+  >(type: TType, sources: MaybeRefOrGetter<TUseSource[]>, config: TConfig & TransformProperty<TSource, TUseSource>) {
+    return setup(
+      { type, data: transformSources<TSource>(sources, config.transform) } as unknown as TTypedSource,
+      config
+    )
+  }
+}

package/lib/packages/table/index.ts

@@ -0,0 +1,11 @@
+export * from './apply-extensions'
+export * from './define-renderer/define-table-cell-renderer'
+export * from './define-renderer/define-table-row-renderer'
+export * from './define-columns'
+export * from './define-table/define-multi-source-table'
+export * from './define-table/define-table'
+export * from './define-renderer/define-table-renderer'
+export * from './define-renderer/define-table-section-renderer'
+export * from './define-table/define-typed-table'
+export * from './transform-sources'
+export * from './types'

package/lib/packages/table/transform-sources.ts

@@ -0,0 +1,13 @@
+import { useArrayMap } from '@vueuse/shared'
+import { type MaybeRefOrGetter, type ComputedRef, computed, toValue } from 'vue'
+
+export function transformSources<TSource>(
+  sources: MaybeRefOrGetter<any[]>,
+  transformer?: (source: any, index: number) => any
+) {
+  return transformer
+    ? (useArrayMap(sources, (source, index) => ({ ...source, ...transformer!(source, index) })) as ComputedRef<
+        TSource[]
+      >)
+    : (computed(() => toValue(sources)) as unknown as ComputedRef<TSource[]>)
+}

package/lib/packages/table/types/extensions.ts

@@ -0,0 +1,16 @@
+import type { PropsOverride, Renderer } from '.'
+
+export type Extension<
+  TConfig extends Record<string, any> = Record<string, any>,
+  TComponentProps extends Record<string, any> = Record<string, any>,
+> = (config: TConfig) => { props: PropsOverride<TComponentProps> }
+
+export type Extensions<TComponentProps extends Record<string, any>> = Record<string, Extension<any, TComponentProps>>
+
+export type ExtensionConfig<
+  TRenderer extends Renderer<any, any, any>,
+  TExtensionName extends keyof $Extensions,
+  $Extensions extends Record<string, any> = TRenderer extends Renderer<any, infer TExtensions, any>
+    ? { [K in keyof TExtensions]: Parameters<TExtensions[K]>[0] }
+    : never,
+> = $Extensions[TExtensionName]