@aleph-alpha/ui-library 1.9.0 → 1.11.0

package/src/compositions/UiDataTable/UiDataTable.stories.ts

@@ -0,0 +1,1575 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import type { ColumnDef } from '@tanstack/vue-table';
+import { computed, h, ref } from 'vue';
+import { Ban, MoreHorizontal } from 'lucide-vue-next';
+import {
+  UiDataTable,
+  UiDataTableColumnHeader,
+  UiDataTablePagination,
+  UiDataTableToolbar,
+} from './index';
+import { UiCheckbox } from '@/primitives/UiCheckbox';
+import { UiButton } from '@/primitives/UiButton';
+import {
+  UiDropdownMenu,
+  UiDropdownMenuContent,
+  UiDropdownMenuItem,
+  UiDropdownMenuLabel,
+  UiDropdownMenuSeparator,
+  UiDropdownMenuTrigger,
+} from '@/primitives/UiDropdownMenu';
+import { payments, paymentsMedium, datasetOptions, type Payment } from './UiDataTable.mock';
+
+// Basic columns
+const basicColumns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: () => h('div', { class: 'text-right' }, 'Amount'),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+];
+
+// Sortable columns using UiDataTableColumnHeader
+const sortableColumns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) =>
+      h(UiDataTableColumnHeader, { column, title: 'Amount', class: 'justify-end' }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+];
+
+// Columns with selection using UiDataTableColumnHeader
+const selectableColumns: ColumnDef<Payment>[] = [
+  {
+    id: 'select',
+    header: ({ table }) =>
+      h(UiCheckbox, {
+        modelValue:
+          table.getIsAllPageRowsSelected() ||
+          (table.getIsSomePageRowsSelected() && 'indeterminate'),
+        'onUpdate:modelValue': (value: boolean) => table.toggleAllPageRowsSelected(!!value),
+        ariaLabel: 'Select all',
+        name: 'select-all',
+      }),
+    cell: ({ row }) =>
+      h(UiCheckbox, {
+        modelValue: row.getIsSelected(),
+        'onUpdate:modelValue': (value: boolean) => row.toggleSelected(!!value),
+        ariaLabel: 'Select row',
+        name: `select-${row.id}`,
+      }),
+    enableSorting: false,
+    enableHiding: false,
+    size: 40,
+  },
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) =>
+      h(UiDataTableColumnHeader, { column, title: 'Amount', class: 'justify-end' }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+];
+
+// Column options for controls
+const columnOptions = {
+  Basic: basicColumns,
+  Sortable: sortableColumns,
+  'With Selection': selectableColumns,
+} as const;
+
+const meta = {
+  title: 'Compositions/UiDataTable',
+  component: UiDataTable,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A powerful data table component built with TanStack Table and Vue 3. Supports sorting, pagination, filtering, and row selection. Use `UiDataTable` for the core table, `UiDataTablePagination` for pagination controls, and `UiDataTableToolbar` for search and filters.',
+      },
+    },
+  },
+  argTypes: {
+    columns: {
+      control: 'select',
+      options: Object.keys(columnOptions),
+      mapping: columnOptions,
+      description: 'The column definitions for the table. Select from predefined configurations.',
+    },
+    data: {
+      control: 'select',
+      options: Object.keys(datasetOptions),
+      mapping: datasetOptions,
+      description: 'The data to display in the table. Select from predefined datasets.',
+    },
+    emptyText: {
+      control: 'text',
+      description: 'Text to display when there are no results.',
+    },
+    tableMinHeight: {
+      control: 'text',
+      description:
+        'Minimum height for the table container. Useful for preventing layout shifts during pagination. The last row will have a visible bottom border even when the container is taller than the content.',
+    },
+  },
+  args: {
+    data: 'Large (100 items)',
+    columns: 'Sortable',
+  },
+} satisfies Meta<typeof UiDataTable>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Templates for source code display
+const basicTemplateSource = `<script setup lang="ts">
+import { UiDataTable } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: 'status', header: 'Status' },
+  { accessorKey: 'email', header: 'Email' },
+  { accessorKey: 'amount', header: 'Amount' },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns" />
+</template>`;
+
+const withSortingTemplateSource = `<script setup lang="ts">
+import { h } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+// Use UiDataTableColumnHeader for sortable columns with dropdown menu
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { 
+      column, 
+      title: 'Amount',
+      class: 'justify-end' 
+    }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      return new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+    },
+    size: 120,
+  },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns" />
+</template>`;
+
+const withPaginationTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTablePagination } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  // ... more data (pagination works best with 10+ items)
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+  },
+];
+
+// Access the table instance via ref
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- tableMinHeight prevents layout shifts during pagination -->
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" table-min-height="500px" />
+    <UiDataTablePagination v-if="table" :table="table" />
+  </div>
+</template>`;
+
+const withToolbarTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTableToolbar } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+  },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- filter-column filters a specific column -->
+    <UiDataTableToolbar 
+      v-if="table"
+      :table="table" 
+      filter-column="email"
+      filter-placeholder="Filter emails..."
+    />
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" />
+  </div>
+</template>`;
+
+const fullExampleTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { 
+  UiDataTable, 
+  UiDataTableColumnHeader,
+  UiDataTableToolbar, 
+  UiDataTablePagination 
+} from '@aleph-alpha/ui-library';
+import { UiCheckbox } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+  // ... more data
+];
+
+// Columns with selection checkbox and sortable headers
+const columns: ColumnDef<Payment>[] = [
+  {
+    id: 'select',
+    header: ({ table }) => h(UiCheckbox, {
+      modelValue: table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && 'indeterminate'),
+      'onUpdate:modelValue': (value: boolean) => table.toggleAllPageRowsSelected(!!value),
+      ariaLabel: 'Select all',
+      name: 'select-all',
+    }),
+    cell: ({ row }) => h(UiCheckbox, {
+      modelValue: row.getIsSelected(),
+      'onUpdate:modelValue': (value: boolean) => row.toggleSelected(!!value),
+      ariaLabel: 'Select row',
+      name: \`select-\${row.id}\`,
+    }),
+    enableSorting: false,
+    enableHiding: false,
+    size: 40,
+  },
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+    size: 120,
+  },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <UiDataTableToolbar 
+      v-if="table"
+      :table="table" 
+      global-filter
+      filter-placeholder="Search..."
+    />
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" />
+    <UiDataTablePagination v-if="table" :table="table" />
+  </div>
+</template>`;
+
+const withGlobalFilterTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTableToolbar } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+    size: 120,
+  },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- global-filter searches across ALL columns -->
+    <UiDataTableToolbar 
+      v-if="table"
+      :table="table" 
+      global-filter
+      filter-placeholder="Search all columns..."
+    />
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" />
+  </div>
+</template>`;
+
+const withRowSelectionTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTablePagination } from '@aleph-alpha/ui-library';
+import { UiCheckbox } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+// Add a selection column using UiCheckbox
+const columns: ColumnDef<Payment>[] = [
+  {
+    id: 'select',
+    header: ({ table }) => h(UiCheckbox, {
+      modelValue: table.getIsAllPageRowsSelected() || (table.getIsSomePageRowsSelected() && 'indeterminate'),
+      'onUpdate:modelValue': (value: boolean) => table.toggleAllPageRowsSelected(!!value),
+      ariaLabel: 'Select all',
+      name: 'select-all',
+    }),
+    cell: ({ row }) => h(UiCheckbox, {
+      modelValue: row.getIsSelected(),
+      'onUpdate:modelValue': (value: boolean) => row.toggleSelected(!!value),
+      ariaLabel: 'Select row',
+      name: \`select-\${row.id}\`,
+    }),
+    enableSorting: false,
+    enableHiding: false,
+    size: 40,
+  },
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+    size: 120,
+  },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" />
+    <!-- Pagination shows selection count -->
+    <UiDataTablePagination v-if="table" :table="table" />
+  </div>
+</template>`;
+
+const customEmptyStateTemplateSource = `<script setup lang="ts">
+import { UiDataTable } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = []; // Empty data
+
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: 'status', header: 'Status' },
+  { accessorKey: 'email', header: 'Email' },
+  { accessorKey: 'amount', header: 'Amount' },
+];
+</script>
+
+<template>
+  <!-- Use empty-text prop to customize the empty state message -->
+  <UiDataTable 
+    :data="data" 
+    :columns="columns" 
+    empty-text="No payments found." 
+  />
+</template>`;
+
+const withPageSizeTemplateSource = `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTablePagination } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  // ... more data
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount' }),
+    size: 120,
+  },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" />
+    <!-- Customize page sizes and hide selection count -->
+    <UiDataTablePagination 
+      v-if="table" 
+      :table="table"
+      :page-size-options="[5, 10, 20, 50]"
+      :show-selection="false"
+    />
+  </div>
+</template>`;
+
+/**
+ * Basic table with minimal configuration.
+ *
+ * The simplest way to use UiDataTable - just pass `data` and `columns`.
+ * Column headers are plain text, no sorting or filtering.
+ */
+export const Basic: Story = {
+  args: {
+    data: payments,
+    columns: basicColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: basicTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      return { args };
+    },
+    template: '<UiDataTable v-bind="args" />',
+  }),
+};
+
+/**
+ * Table with sortable columns using UiDataTableColumnHeader.
+ *
+ * Use `UiDataTableColumnHeader` in your column definitions to enable:
+ * - Click to sort (ascending/descending)
+ * - Dropdown menu with sort options and hide column
+ *
+ * This is the recommended approach for sortable headers.
+ */
+export const WithSorting: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withSortingTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      return { args };
+    },
+    template: '<UiDataTable v-bind="args" />',
+  }),
+};
+
+/**
+ * Table with pagination controls.
+ *
+ * Use `UiDataTablePagination` when displaying more than 10 rows.
+ * Shows navigation buttons (first, prev, next, last), page info, and rows per page selector.
+ *
+ * The `tableMinHeight` prop prevents layout shifts during pagination by ensuring
+ * the table container maintains a minimum height. The last row has a visible
+ * bottom border (Material UI-inspired behavior).
+ *
+ * Access the table instance via ref to pass to pagination component.
+ */
+export const WithPagination: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+    tableMinHeight: '500px',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withPaginationTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTablePagination },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTable ref="tableRef" v-bind="args" />
+        <UiDataTablePagination v-if="table" :table="table" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with column-specific filtering.
+ *
+ * Use `UiDataTableToolbar` with `filter-column` prop to filter a specific column.
+ */
+export const WithToolbar: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withToolbarTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTableToolbar },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTableToolbar 
+          v-if="table"
+          :table="table" 
+          filter-column="email"
+          filter-placeholder="Filter emails..."
+        />
+        <UiDataTable ref="tableRef" v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with global search across all columns.
+ *
+ * Use `global-filter` prop instead of `filter-column` to search across ALL columns.
+ * Matches any value in status, email, amount, or ID.
+ *
+ * Try typing "success", "gmail", or "316" to see it match different columns.
+ */
+export const WithGlobalFilter: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withGlobalFilterTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTableToolbar },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTableToolbar 
+          v-if="table"
+          :table="table" 
+          global-filter
+          filter-placeholder="Search all columns..."
+        />
+        <UiDataTable ref="tableRef" v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with row selection checkboxes.
+ *
+ * Add a selection column using `UiCheckbox` to enable row selection.
+ * Use `table.getIsAllPageRowsSelected()` for the header checkbox and
+ * `row.getIsSelected()` for row checkboxes.
+ *
+ * The pagination component shows the selection count automatically.
+ */
+export const WithRowSelection: Story = {
+  args: {
+    data: payments,
+    columns: selectableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withRowSelectionTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTablePagination },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTable ref="tableRef" v-bind="args" />
+        <UiDataTablePagination v-if="table" :table="table" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Complete example combining all DataTable features.
+ *
+ * This example demonstrates the full power of UiDataTable with:
+ * - **Sortable columns** using `UiDataTableColumnHeader`
+ * - **Row selection** with checkboxes (header + row)
+ * - **Global search** across all columns
+ * - **Pagination** with page size selector
+ *
+ * Use this as a reference for building feature-rich data tables.
+ */
+export const FullExample: Story = {
+  args: {
+    data: payments,
+    columns: selectableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: fullExampleTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTableToolbar, UiDataTablePagination },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTableToolbar 
+          v-if="table"
+          :table="table" 
+          global-filter
+          filter-placeholder="Search..."
+        />
+        <UiDataTable ref="tableRef" v-bind="args" />
+        <UiDataTablePagination v-if="table" :table="table" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with custom empty state message using the `empty-text` prop.
+ *
+ * Use the `empty-text` prop to customize the message shown when there's no data.
+ * Defaults to "No results." if not specified.
+ */
+export const WithCustomEmptyText: Story = {
+  args: {
+    data: [],
+    columns: basicColumns,
+    emptyText: 'No payments found.',
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: customEmptyStateTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      return { args };
+    },
+    template: '<UiDataTable v-bind="args" />',
+  }),
+};
+
+const withCustomEmptySlotTemplateSource = `<script setup lang="ts">
+import { UiDataTable } from '@aleph-alpha/ui-library';
+import { Ban } from 'lucide-vue-next';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = []; // Empty data
+
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: 'status', header: 'Status' },
+  { accessorKey: 'email', header: 'Email' },
+  { accessorKey: 'amount', header: 'Amount' },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns">
+    <template #empty>
+      <div class="flex flex-col items-center gap-2 text-muted-foreground">
+        <Ban class="h-8 w-8" />
+        <p>No data available for this view.</p>
+      </div>
+    </template>
+  </UiDataTable>
+</template>`;
+
+export const WithCustomEmptySlot: Story = {
+  args: {
+    data: [],
+    columns: basicColumns,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use the `#empty` slot to provide a fully custom empty state, such as an icon or formatted text.',
+      },
+      source: {
+        code: withCustomEmptySlotTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, Ban },
+    setup() {
+      return { args };
+    },
+    template: `
+      <UiDataTable v-bind="args">
+        <template #empty>
+          <div class="flex flex-col items-center gap-2 text-muted-foreground">
+            <Ban class="h-8 w-8" />
+            <p>No data available for this view.</p>
+          </div>
+        </template>
+      </UiDataTable>
+    `,
+  }),
+};
+
+// Columns using UiDataTableColumnHeader component
+const columnHeaderColumns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) =>
+      h(UiDataTableColumnHeader, { column, title: 'Amount', class: 'justify-end' }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+];
+
+const withColumnHeaderTemplateSource = `<script setup lang="ts">
+import { h } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  // ... more data
+];
+
+// Using UiDataTableColumnHeader for sortable headers with hide option
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { 
+      column, 
+      title: 'Amount',
+      class: 'justify-end' 
+    }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns" />
+</template>`;
+
+/**
+ * Table demonstrating sortable columns with UiDataTableColumnHeader.
+ *
+ * The `UiDataTableColumnHeader` provides a dropdown with sort options.
+ *
+ * For right-aligned headers (like amounts), pass `class="justify-end"`.
+ */
+export const WithColumnHeader: Story = {
+  args: {
+    data: payments,
+    columns: columnHeaderColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withColumnHeaderTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTableToolbar },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTableToolbar 
+          v-if="table"
+          :table="table" 
+          global-filter
+          filter-placeholder="Search..."
+        />
+        <UiDataTable ref="tableRef" v-bind="args" />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with customized pagination options.
+ *
+ * Customize `UiDataTablePagination` with:
+ * - `page-size-options`: Array of page size options (default: [10, 20, 30, 50])
+ * - `show-page-size`: Show/hide the rows per page selector (default: true)
+ * - `show-selection`: Show/hide the selection count (default: true)
+ */
+export const WithPageSizeSelector: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withPageSizeTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTablePagination },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTable ref="tableRef" v-bind="args" />
+        <UiDataTablePagination 
+          v-if="table" 
+          :table="table"
+          :page-size-options="[5, 10, 20, 50]"
+          :show-selection="false"
+        />
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Table with 14 items, minimum height, and pagination.
+ *
+ * Demonstrates how `tableMinHeight` keeps stable layout when there's content
+ * below the table (pagination). Page 1 shows 10 rows, page 2 shows 4 rows -
+ * the table maintains consistent height regardless of how many rows are visible.
+ */
+export const WithMinHeightSmallDataset: Story = {
+  args: {
+    // Use 14 items: page 1 = 10 rows, page 2 = 4 rows
+    data: paymentsMedium.slice(0, 14),
+    columns: sortableColumns,
+    tableMinHeight: '500px',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstrates `tableMinHeight` with 14 items and pagination. Page 1 shows 10 rows, page 2 shows only 4 rows. The table keeps a consistent height, preventing layout shifts when navigating between pages.',
+      },
+      source: {
+        code: `<script setup lang="ts">
+import { h, ref, computed } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader, UiDataTablePagination } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment { id: string; amount: number; status: string; email: string; }
+
+// 14 items: page 1 = 10 rows, page 2 = 4 rows
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'user1@example.com' },
+  { id: '2', amount: 242, status: 'pending', email: 'user2@example.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'user3@example.com' },
+  { id: '4', amount: 154, status: 'failed', email: 'user4@example.com' },
+  { id: '5', amount: 429, status: 'success', email: 'user5@example.com' },
+  { id: '6', amount: 512, status: 'pending', email: 'user6@example.com' },
+  { id: '7', amount: 623, status: 'processing', email: 'user7@example.com' },
+  { id: '8', amount: 734, status: 'failed', email: 'user8@example.com' },
+  { id: '9', amount: 845, status: 'success', email: 'user9@example.com' },
+  { id: '10', amount: 956, status: 'pending', email: 'user10@example.com' },
+  { id: '11', amount: 167, status: 'processing', email: 'user11@example.com' },
+  { id: '12', amount: 278, status: 'failed', email: 'user12@example.com' },
+  { id: '13', amount: 389, status: 'success', email: 'user13@example.com' },
+  { id: '14', amount: 490, status: 'pending', email: 'user14@example.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  { accessorKey: 'status', header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }) },
+  { accessorKey: 'email', header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }) },
+  { accessorKey: 'amount', header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Amount', class: 'justify-end' }) },
+];
+
+const tableRef = ref<InstanceType<typeof UiDataTable>>();
+const table = computed(() => tableRef.value?.table);
+</script>
+
+<template>
+  <div class="space-y-4">
+    <UiDataTable ref="tableRef" :data="data" :columns="columns" table-min-height="500px" />
+    <UiDataTablePagination v-if="table" :table="table" :show-selection="false" />
+  </div>
+</template>`,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable, UiDataTablePagination },
+    setup() {
+      const tableRef = ref<InstanceType<typeof UiDataTable>>();
+      const table = computed(() => tableRef.value?.table);
+      return { args, tableRef, table };
+    },
+    template: `
+      <div class="space-y-4">
+        <UiDataTable ref="tableRef" v-bind="args" />
+        <UiDataTablePagination v-if="table" :table="table" :show-selection="false" />
+      </div>
+    `,
+  }),
+};
+
+// Row Actions columns with dropdown menu
+const rowActionsColumns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) =>
+      h(UiDataTableColumnHeader, { column, title: 'Amount', class: 'justify-end' }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+    size: 120,
+  },
+  {
+    id: 'actions',
+    enableHiding: false,
+    enableSorting: false,
+    header: () => h('span', { class: 'sr-only' }, 'Actions'),
+    cell: ({ row }) => {
+      const payment = row.original;
+      return h(
+        UiDropdownMenu,
+        {},
+        {
+          default: () => [
+            h(UiDropdownMenuTrigger, { asChild: true }, () =>
+              h(UiButton, { variant: 'ghost', size: 'icon', class: 'h-8 w-8' }, () => [
+                h('span', { class: 'sr-only' }, 'Open menu'),
+                h(MoreHorizontal, { class: 'h-4 w-4' }),
+              ]),
+            ),
+            h(UiDropdownMenuContent, { align: 'end' }, () => [
+              h(UiDropdownMenuLabel, {}, () => 'Actions'),
+              h(
+                UiDropdownMenuItem,
+                { onClick: () => navigator.clipboard.writeText(payment.id) },
+                () => 'Copy payment ID',
+              ),
+              h(UiDropdownMenuSeparator),
+              h(UiDropdownMenuItem, {}, () => 'View details'),
+              h(UiDropdownMenuItem, {}, () => 'View customer'),
+            ]),
+          ],
+        },
+      );
+    },
+    size: 50,
+  },
+];
+
+const withRowActionsTemplateSource = `<script setup lang="ts">
+import { h } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader } from '@aleph-alpha/ui-library';
+import {
+  UiDropdownMenu,
+  UiDropdownMenuContent,
+  UiDropdownMenuItem,
+  UiDropdownMenuLabel,
+  UiDropdownMenuSeparator,
+  UiDropdownMenuTrigger,
+} from '@aleph-alpha/ui-library';
+import { UiButton } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+// Define a component for row actions (or use inline h() calls)
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    cell: ({ row }) => h('div', { class: 'capitalize' }, row.getValue('status')),
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    cell: ({ row }) => h('div', { class: 'lowercase' }, row.getValue('email')),
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, { 
+      column, 
+      title: 'Amount',
+      class: 'justify-end' 
+    }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', { class: 'text-right font-medium' }, formatted);
+    },
+  },
+  {
+    id: 'actions',
+    enableHiding: false,
+    cell: ({ row }) => {
+      const payment = row.original;
+
+      // You can return a Vue component or use h() to render dropdown
+      // For complex actions, create a separate component like DataTableRowActions.vue
+      return h(UiDropdownMenu, {}, {
+        default: () => [
+          h(UiDropdownMenuTrigger, { asChild: true }, () =>
+            h(UiButton, { variant: 'ghost', size: 'sm' }, () => '⋮')
+          ),
+          h(UiDropdownMenuContent, { align: 'end' }, () => [
+            h(UiDropdownMenuLabel, {}, () => 'Actions'),
+            h(UiDropdownMenuItem, { 
+              onClick: () => navigator.clipboard.writeText(payment.id) 
+            }, () => 'Copy payment ID'),
+            h(UiDropdownMenuSeparator),
+            h(UiDropdownMenuItem, {}, () => 'View details'),
+            h(UiDropdownMenuItem, {}, () => 'View customer'),
+          ]),
+        ],
+      });
+    },
+  },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns" />
+</template>`;
+
+/**
+ * Table with row actions dropdown menu.
+ *
+ * Add an actions column with a dropdown menu for each row.
+ * Use `row.original` to access the full row data for actions.
+ *
+ * For complex actions, create a separate component (e.g., `DataTableRowActions.vue`)
+ * and import it in your column definition.
+ */
+export const WithRowActions: Story = {
+  args: {
+    data: payments,
+    columns: rowActionsColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withRowActionsTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      return { args };
+    },
+    template: '<UiDataTable v-bind="args" />',
+  }),
+};
+
+// Cell formatting columns
+const cellFormattingColumns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => {
+      const status = row.getValue('status') as string;
+      const statusStyles: Record<string, string> = {
+        success: 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300',
+        processing: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-300',
+        pending: 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300',
+        failed: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300',
+      };
+      return h(
+        'span',
+        {
+          class: `inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium capitalize ${statusStyles[status] || ''}`,
+        },
+        status,
+      );
+    },
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    cell: ({ row }) => h('div', { class: 'lowercase font-mono text-sm' }, row.getValue('email')),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: () => h('div', { class: 'text-right' }, 'Amount'),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h(
+        'div',
+        {
+          class: `text-right font-medium ${amount > 500 ? 'text-green-600' : 'text-muted-foreground'}`,
+        },
+        formatted,
+      );
+    },
+    size: 120,
+  },
+];
+
+const withCellFormattingTemplateSource = `<script setup lang="ts">
+import { h } from 'vue';
+import { UiDataTable } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: 'pending' | 'processing' | 'success' | 'failed';
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'pending', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+  { id: '4', amount: 721, status: 'failed', email: 'carmella@hotmail.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    // Custom status badge with semantic colors
+    cell: ({ row }) => {
+      const status = row.getValue('status') as string;
+      const statusStyles: Record<string, string> = {
+        success: 'bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-300',
+        processing: 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900 dark:text-yellow-300',
+        pending: 'bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-300',
+        failed: 'bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-300',
+      };
+      return h('span', {
+        class: \`inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium capitalize \${statusStyles[status] || ''}\`,
+      }, status);
+    },
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    // Monospace font for emails
+    cell: ({ row }) => h('div', { 
+      class: 'lowercase font-mono text-sm' 
+    }, row.getValue('email')),
+  },
+  {
+    accessorKey: 'amount',
+    // Right-aligned header
+    header: () => h('div', { class: 'text-right' }, 'Amount'),
+    // Conditional formatting: green for high amounts
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      const formatted = new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+      return h('div', {
+        class: \`text-right font-medium \${amount > 500 ? 'text-green-600' : 'text-muted-foreground'}\`,
+      }, formatted);
+    },
+  },
+];
+</script>
+
+<template>
+  <UiDataTable :data="data" :columns="columns" />
+</template>`;
+
+/**
+ * Table with custom cell formatting.
+ *
+ * Use the `cell` property in column definitions to customize how data is displayed:
+ * - **Status badges** with semantic colors (green=success, yellow=processing, etc.)
+ * - **Monospace font** for emails
+ * - **Currency formatting** with conditional colors based on value
+ *
+ * Access cell value with `row.getValue('columnKey')` and return a VNode using `h()`.
+ */
+export const WithCellFormatting: Story = {
+  args: {
+    data: payments,
+    columns: cellFormattingColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withCellFormattingTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      return { args };
+    },
+    template: '<UiDataTable v-bind="args" />',
+  }),
+};