@xen-orchestra/web-core 0.35.1 → 0.37.0

package/lib/packages/table/README.md

@@ -1,336 +1,81 @@
-# Table System
+# `defineColumn`
 
-Table system that separates data logic from presentation through reusable renderers.
+Define the head and body renderers for a column.
 
-## Understanding Renderers
+The render functions can receive arguments and must return a VNode.
 
-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:
+## Example 1 - A simple text column
 
-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',
-  },
-})
+```ts
+const useTextColumn = defineColumn((config?: { headLabel?: string }) => ({
+  renderHead: () => h('th', { class: 'table-head-cell' }, config?.headLabel),
+  renderBody: (text: string) => h('td', { class: 'table-text-cell' }, text),
+}))
 ```
 
-### 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
+## Example 2 - A "number with unit" column
 
-```typescript
-const MyRow = defineTableRowRenderer({
-  component: () => import('./Row.vue'),
-  extensions: {
-    selectable: (config: { id: string; selectedId: Ref<string | null> }) => ({
-      props: {
-        selected: config.id === config.selectedId.value,
-      },
+```ts
+const useNumberWithUnitColumn = defineColumn((config?: { headLabel?: string; defaultUnit?: string }) => ({
+  renderHead: () => h('th', config?.headLabel ?? 'User'),
+  renderBody: (value: number, unit?: string) =>
+    h(NumberCell, {
+      value,
+      suffix: unit ?? config?.defaultUnit,
     }),
-    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
+# `defineColumns`
 
-Create header and body cell renderers:
+Define a set of columns.
 
-```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 }),
-})
+## Example
 
-// Usage
-TextHeader({ label: 'Name' })
-TextBody({ text: user.name })
+```ts
+const useUserTableColumns = defineColumns(() => ({
+  fullName: useTextColumn({ headLabel: 'Full name' }),
+  email: useTextColumn({ headLabel: 'Email' }),
+  age: useNumberWithUnitColumn({ headLabel: 'Age', defaultUnit: 'years' }),
+}))
 ```
 
-### Row Renderers
+# Using the columns set
 
-Create row renderer:
+When using the columns set, you could have to provide `head` and/or `body` arguments based on whether any `renderHead` and/or `renderBody` used in the columns set expect arguments.
 
-```typescript
-import { defineTableRowRenderer } from '@core/packages/table'
+## Example
 
-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
+The `body` function receives the row item (here, a `User`) and returns an object where:
 
-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,
-})
-```
+- **Keys** are column names (`fullName`, `email`, `age`)
+- **Values** are functions that receive the column's original renderer (`r`) and must return a VNode
 
-`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
-```
+You can either use the original renderer by calling `r(data)`, or ignore it and return your own VNode.
 
-### 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}`,
+```ts
+const { HeadCells, BodyCells } = useUserTableColumns({
+  body: (user: User) => ({
+    fullName: r => r(`${user.firstName} ${user.lastName}`),
+    email: r => r(user.email),
+    age: r => r(user.age < 2 ? { value: toMonths(user.age), unit: 'months' } : { value: user.age }),
   }),
 })
-
-// Transform is optional when types already match
-useUserTable(users, {})
 ```
 
-## Rendering the table
-
-```vue
+```html
 <template>
-  <MyUsersTable />
+  <table>
+    <thead>
+      <tr>
+        <HeadCells />
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.id">
+        <BodyCells :item="user" />
+      </tr>
+    </tbody>
+  </table>
 </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/define-column.ts

@@ -0,0 +1,7 @@
+import type { ColumnRenderer } from '@core/packages/table/types.ts'
+
+export function defineColumn<TSetupArgs extends any[], TRenderHeadArgs extends any[], TRenderBodyArgs extends any[]>(
+  setup: (...args: TSetupArgs) => ColumnRenderer<TRenderHeadArgs, TRenderBodyArgs>
+) {
+  return setup
+}

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

@@ -1,62 +1,116 @@
-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
-    >
+import type { AreAllPropertiesOptional, Columns } from '@core/packages/table/types.ts'
+import { objectOmit } from '@vueuse/shared'
+import { computed, defineComponent, Fragment, h, ref, type Component, type Ref, type VNode } from 'vue'
+
+export function defineColumns<TSetupArgs extends any[], TColumns extends Columns>(
+  setup: (...args: TSetupArgs) => TColumns
 ) {
-  const columnNames = Object.keys(config).filter(key => config[key] !== undefined) as TColumnName[]
+  function useColumns<
+    THeadRenderers extends {
+      [K in keyof TColumns as [] extends Parameters<TColumns[K]['renderHead']> ? K : never]?: (
+        renderer: TColumns[K]['renderHead']
+      ) => VNode
+    } & {
+      [K in keyof TColumns as [] extends Parameters<TColumns[K]['renderHead']> ? never : K]: (
+        renderer: TColumns[K]['renderHead']
+      ) => VNode
+    },
+    TBodyRenderers extends {
+      [K in keyof TColumns]: (renderer: TColumns[K]['renderBody']) => VNode
+    },
+    THeadItem,
+    TBodyItem,
+    TExcludedId extends keyof TColumns = never,
+  >(
+    config: {
+      exclude?: TExcludedId[]
+      body: (item: TBodyItem) => Omit<TBodyRenderers, TExcludedId>
+    } & (AreAllPropertiesOptional<Omit<THeadRenderers, TExcludedId>> extends true
+      ? { head?: (item: THeadItem) => Omit<THeadRenderers, TExcludedId> }
+      : { head: (item: THeadItem) => Omit<THeadRenderers, TExcludedId> }),
+    ...args: TSetupArgs
+  ) {
+    type $TAvailableColumns = Omit<TColumns, TExcludedId>
+    type $TAvailableColumnId = keyof $TAvailableColumns
 
-  const hiddenColumnNames = reactive(new Set()) as Set<TColumnName>
+    const allColumns = setup(...args)
 
-  const visibleColumnNames = computed(() => columnNames.filter(name => !hiddenColumnNames.has(name)))
+    const availableColumns = objectOmit(allColumns, config.exclude ?? []) as $TAvailableColumns
 
-  const visibleColumns = computed(() => visibleColumnNames.value.map(name => config[name]!))
+    const hiddenColumnIds = ref(new Set()) as Ref<Set<$TAvailableColumnId>>
 
-  const visibleColumnsCount = computed(() => visibleColumnNames.value.length)
+    const visibleColumnIds = computed(
+      () =>
+        Object.keys(availableColumns).filter(
+          id => !hiddenColumnIds.value.has(id as $TAvailableColumnId)
+        ) as $TAvailableColumnId[]
+    )
 
-  type GetHeaderCells = THeaderArg extends undefined
-    ? (arg?: THeaderArg) => TableCellVNode[]
-    : (arg: THeaderArg) => TableCellVNode[]
+    const colspan = computed(() => visibleColumnIds.value.length)
 
-  type GetBodyCells = TBodyArg extends undefined
-    ? (source: TSource, arg?: TBodyArg) => TableCellVNode[]
-    : (source: TSource, arg: TBodyArg) => TableCellVNode[]
+    function toggle(columnId: $TAvailableColumnId, visible: boolean = hiddenColumnIds.value.has(columnId)) {
+      if (visible) {
+        hiddenColumnIds.value.delete(columnId)
+      } else {
+        hiddenColumnIds.value.add(columnId)
+      }
+    }
 
-  return {
-    getHeaderCells: ((arg?: THeaderArg) =>
-      visibleColumns.value.map(column => column.header(arg as THeaderArg))) as GetHeaderCells,
+    const HeadCells = defineComponent({
+      props: {
+        item: {
+          type: Object as () => THeadItem,
+          required: false,
+        },
+      },
+      setup(props) {
+        const headCellRenderers = config.head?.(props.item as THeadItem) ?? ({} as THeadRenderers)
 
-    getBodyCells: ((source: TSource, arg?: TBodyArg) =>
-      visibleColumns.value.map(column => column.body(source, arg as TBodyArg))) as GetBodyCells,
+        return () =>
+          visibleColumnIds.value.map(columnId => {
+            const { renderHead } = availableColumns[columnId]
 
-    toggleColumn: (name: TColumnName, forcedValue = !hiddenColumnNames.has(name)) => {
-      if (forcedValue) {
-        hiddenColumnNames.add(name)
-      } else {
-        hiddenColumnNames.delete(name)
-      }
-    },
-    visibleColumnsCount,
+            const headCellRenderer = headCellRenderers[columnId as keyof typeof headCellRenderers]
+
+            return h(Fragment, { key: columnId }, [headCellRenderer ? headCellRenderer(renderHead) : renderHead()])
+          })
+      },
+    })
+
+    const BodyCells = defineComponent({
+      props: {
+        item: {
+          type: Object as () => TBodyItem,
+          required: true,
+        },
+      },
+      setup(props) {
+        const bodyCellRenderers = config.body(props.item as TBodyItem) ?? ({} as TBodyRenderers)
+
+        return () =>
+          visibleColumnIds.value.map(columnId => {
+            const { renderBody } = availableColumns[columnId]
+
+            const bodyCellRenderer = bodyCellRenderers[columnId as keyof typeof bodyCellRenderers]
+
+            return h(Fragment, { key: columnId }, [bodyCellRenderer ? bodyCellRenderer(renderBody) : renderBody()])
+          })
+      },
+    })
+
+    return {
+      HeadCells: HeadCells as Component<
+        [THeadItem] extends [undefined]
+          ? Record<string, never>
+          : undefined extends THeadItem
+            ? { item?: THeadItem }
+            : { item: THeadItem }
+      >,
+      BodyCells: BodyCells as Component<{ item: TBodyItem }>,
+      toggle,
+      colspan,
+    }
   }
+
+  return useColumns
 }

package/lib/packages/table/index.ts

@@ -1,11 +1,3 @@
-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'
+export { defineColumn } from './define-column.ts'
+export { defineColumns } from './define-columns.ts'
+export type { ColumnRenderer, Columns } from './types.ts'

package/lib/packages/table/types.ts

@@ -0,0 +1,10 @@
+import { type VNode } from 'vue'
+
+export type ColumnRenderer<THeadArgs extends any[], TBodyArgs extends any[]> = {
+  renderHead: (...args: THeadArgs) => VNode
+  renderBody: (...args: TBodyArgs) => VNode
+}
+
+export type Columns = Record<string, ColumnRenderer<any, any>>
+
+export type AreAllPropertiesOptional<T> = Record<string, never> extends T ? true : false