feat(Table): customize header and cell through slots (#2457)

Co-authored-by: Benjamin Canac <[email protected]>

docs/app/components/content/examples/table/TableSlotsExample.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import type { TableColumn } from '@nuxt/ui'
+
+type User = {
+  id: number
+  name: string
+  position: string
+  email: string
+  role: string
+}
+
+const data = ref<User[]>([{
+  id: 1,
+  name: 'Lindsay Walton',
+  position: 'Front-end Developer',
+  email: '[email protected]',
+  role: 'Member'
+}, {
+  id: 2,
+  name: 'Courtney Henry',
+  position: 'Designer',
+  email: '[email protected]',
+  role: 'Admin'
+}, {
+  id: 3,
+  name: 'Tom Cook',
+  position: 'Director of Product',
+  email: '[email protected]',
+  role: 'Member'
+}, {
+  id: 4,
+  name: 'Whitney Francis',
+  position: 'Copywriter',
+  email: '[email protected]',
+  role: 'Admin'
+}, {
+  id: 5,
+  name: 'Leonard Krasner',
+  position: 'Senior Designer',
+  email: '[email protected]',
+  role: 'Owner'
+}, {
+  id: 6,
+  name: 'Floyd Miles',
+  position: 'Principal Designer',
+  email: '[email protected]',
+  role: 'Member'
+}])
+
+const columns: TableColumn<User>[] = [{
+  accessorKey: 'id',
+  header: 'ID'
+}, {
+  accessorKey: 'name',
+  header: 'Name'
+}, {
+  accessorKey: 'email',
+  header: 'Email'
+}, {
+  accessorKey: 'role',
+  header: 'Role'
+}]
+</script>
+
+<template>
+  <UTable :data="data" :columns="columns" class="flex-1">
+    <template #name-cell="{ row }">
+      <div class="flex items-center gap-3">
+        <UAvatar :src="`https://i.pravatar.cc/120?img=${row.original.id}`" size="lg" />
+        <div>
+          <p class="font-medium text-[var(--ui-text-highlighted)]">
+            {{ row.original.name }}
+          </p>
+          <p>
+            {{ row.original.position }}
+          </p>
+        </div>
+      </div>
+    </template>
+  </UTable>
+</template>

docs/content/3.components/table.md

@@ -80,6 +80,10 @@ Use the `columns` prop as an array of [ColumnDef](https://tanstack.com/table/lat
 
 In order to render components or other HTML elements, you will need to use the Vue [`h` function](https://vuejs.org/api/render-function.html#h) inside the `header` and `cell` props. This is different from other components that use slots but allows for more flexibility.
 
+::tip{to="#with-slots"}
+You can also use slots to customize the header and data cells of the table.
+::
+
 ::component-example
 ---
 prettier: true
@@ -92,8 +96,8 @@ highlights:
 ---
 ::
 
-::tip
-When rendering components with the `h` function, you can utilize the `resolveComponent` function to dynamically resolve and reference components.
+::note
+When rendering components with `h`, you can either use the `resolveComponent` function or import from `#components`.
 ::
 
 ### Loading
@@ -396,6 +400,23 @@ class: '!p-0'
 ---
 ::
 
+### With slots
+
+You can use slots to customize the header and data cells of the table.
+
+Use the `#<column>-header` slot to customize the header of a column. You will have access to the `column`, `header` and `table` properties in the slot scope.
+
+Use the `#<column>-cell` slot to customize the cell of a column. You will have access to the `cell`, `column`, `getValue`, `renderValue`, `row`, and `table` properties in the slot scope.
+
+::component-example
+---
+prettier: true
+collapse: true
+name: 'table-slots-example'
+class: '!p-0'
+---
+::
+
 ## API
 
 ### Props

src/runtime/components/Table.vue

@@ -19,7 +19,9 @@ import type {
   ExpandedOptions,
   SortingOptions,
   RowSelectionOptions,
-  Updater
+  Updater,
+  CellContext,
+  HeaderContext
 } from '@tanstack/vue-table'
 import _appConfig from '#build/app.config'
 import theme from '#build/ui/table'
@@ -87,10 +89,13 @@ export interface TableProps<T> {
   ui?: Partial<typeof table.slots>
 }
 
-export interface TableSlots<T> {
-  expanded(props: { row: Row<T> }): any
-  empty(props?: {}): any
-}
+type DynamicHeaderSlots<T, K = keyof T> = Record<string, T> & Record<`${K extends string ? K : never}-header`, (props: HeaderContext<T, unknown>) => any>
+type DynamicCellSlots<T, K = keyof T> = Record<string, T> & Record<`${K extends string ? K : never}-cell`, (props: CellContext<T, unknown>) => any>
+
+export type TableSlots<T> = {
+  expanded: (props: { row: Row<T> }) => any
+  empty: (props?: {}) => any
+} & DynamicHeaderSlots<T> & DynamicCellSlots<T>
 
 </script>
 
@@ -193,7 +198,9 @@ defineExpose({
             :data-pinned="header.column.getIsPinned()"
             :class="ui.th({ class: [props.ui?.th], pinned: !!header.column.getIsPinned() })"
           >
-            <FlexRender v-if="!header.isPlaceholder" :render="header.column.columnDef.header" :props="header.getContext()" />
+            <slot :name="`${header.id}-header`" v-bind="header.getContext()">
+              <FlexRender v-if="!header.isPlaceholder" :render="header.column.columnDef.header" :props="header.getContext()" />
+            </slot>
           </th>
         </tr>
       </thead>
@@ -208,7 +215,9 @@ defineExpose({
                 :data-pinned="cell.column.getIsPinned()"
                 :class="ui.td({ class: [props.ui?.td], pinned: !!cell.column.getIsPinned() })"
               >
-                <FlexRender :render="cell.column.columnDef.cell" :props="cell.getContext()" />
+                <slot :name="`${cell.column.id}-cell`" v-bind="cell.getContext()">
+                  <FlexRender :render="cell.column.columnDef.cell" :props="cell.getContext()" />
+                </slot>
               </td>
             </tr>
             <tr v-if="row.getIsExpanded()" :class="ui.tr({ class: [props.ui?.tr] })">

test/components/Table.spec.ts

@@ -152,7 +152,12 @@ describe('Table', () => {
     ...loadingColors.map((loadingColor: string) => [`with loading color ${loadingColor}`, { props: { ...props, loading: true, loadingColor } }]),
     ...loadingAnimations.map((loadingAnimation: string) => [`with loading animation ${loadingAnimation}`, { props: { ...props, loading: true, loadingAnimation } }]),
     ['with class', { props: { ...props, class: 'absolute' } }],
-    ['with ui', { props: { ...props, ui: { base: 'table-auto' } } }]
+    ['with ui', { props: { ...props, ui: { base: 'table-auto' } } }],
+    // Slots
+    ['with header slot', { props, slots: { 'id-header': () => 'ID Header slot' } }],
+    ['with cell slot', { props, slots: { 'id-cell': () => 'ID Cell slot' } }],
+    ['with expanded slot', { props, slots: { expanded: () => 'Expanded slot' } }],
+    ['with empty slot', { props, slots: { empty: () => 'Empty slot' } }]
   ])('renders %s correctly', async (nameOrHtml: string, options: { props?: TableProps<typeof data[number]>, slots?: Partial<TableSlots<typeof data[number]>> }) => {
     const html = await ComponentRender(nameOrHtml, options, Table)
     expect(html).toMatchSnapshot()