@adobe-commerce/elsie 1.6.0-alpha999 → 1.6.0-beta2

package/src/components/Table/Table.stories.tsx

@@ -0,0 +1,1024 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this 
+ * file in accordance with the terms of the Adobe license agreement 
+ * accompanying it. 
+ *******************************************************************/
+
+// https://storybook.js.org/docs/7.0/preact/writing-stories/introduction
+import type { Meta, StoryObj } from '@storybook/preact';
+import { useState } from 'preact/hooks';
+import { Table as TableComponent, TableProps } from '@adobe-commerce/elsie/components/Table';
+import { ActionButton } from '@adobe-commerce/elsie/components/ActionButton';
+import { ActionButtonGroup } from '@adobe-commerce/elsie/components/ActionButtonGroup';
+import { Pagination } from '@adobe-commerce/elsie/components/Pagination';
+import { Picker, type PickerOption } from '@adobe-commerce/elsie/components/Picker';
+
+/**
+ * Use the `Table` component to render data in a structured table.
+ * 
+ * ## Column Structure
+ * Each column in the `columns` array defines a table column with:
+ * - **`key`**: Unique identifier that matches the property names in `rowData` objects
+ * - **`label`**: Display text shown in the column header
+ * - **`sortBy`**: Optional sorting state (`true` for sortable but neutral, `'asc'` for ascending, `'desc'` for descending)
+ * 
+ * ## Row Data Structure
+ * Each object in the `rowData` array represents a table row where:
+ * - **Keys** must match the `key` values from the `columns` array
+ * - **Values** can be:
+ *   - **Strings**: Plain text content
+ *   - **Numbers**: Numeric values (automatically converted to strings for display)
+ *   - **VNode**: Preact `VNode` for complex content (buttons, icons, formatted text, etc.)
+ * 
+ * ## Mobile Layout & Container Queries
+ * The table uses **container queries** instead of media queries for responsive behavior:
+ * - **`mobileLayout`**: Optional prop that controls mobile behavior
+ *   - `'none'` (default): No special mobile layout
+ *   - `'stacked'`: Stacks cells vertically when container width ≤ 600px
+ * - **Container Query Breakpoint**: 600px - triggers when the table's container becomes narrow
+ * - **`data-label`**: Automatically added to cells for accessibility in stacked layout
+ * - **Responsive Behavior**: Table adapts to its container width, not viewport width
+ * 
+ * ## All props
+ * The table below shows all the props for the `Table` component.
+ */
+
+const meta: Meta<TableProps> = {
+  title: 'Components/Table',
+  component: TableComponent,
+  parameters: {
+    layout: 'padded',
+  },
+  argTypes: {
+    columns: {
+      description: 'Array of column definitions for the table. Each column defines the structure and behavior of a table column.',
+      table: {
+        type: { summary: 'Column[]' },
+      },
+      control: 'object',
+    },
+    rowData: {
+      description: 'Array of data objects to display in table rows. Each object represents a table row where keys match column keys and values contain the cell content.',
+      table: {
+        type: { summary: 'RowData[]' },
+      },
+      control: 'object',
+    },
+    mobileLayout: {
+      description: 'Controls responsive layout behavior using container queries. When set to "stacked", cells stack vertically when the table container width ≤ 600px. The `data-label` attribute is automatically added to cells for accessibility.',
+      table: {
+        type: { summary: 'none | stacked' },
+      },
+      control: 'select',
+      options: ['none', 'stacked'],
+      mapping: {
+        none: 'none',
+        stacked: 'stacked',
+      },
+    },
+    caption: {
+      description: 'Optional table caption that provides context and description. Displays above the table and is announced by screen readers.',
+      table: {
+        type: { summary: 'string' },
+      },
+      control: 'text',
+    },
+    onSortChange: {
+      description: 'Callback function triggered when column sorting changes.',
+      table: {
+        type: { summary: '(columnKey: string, direction: Sortable) => void' },
+      },
+      action: 'onSortChange',
+    },
+    expandedRows: {
+      description: 'Set of row indices that are currently expanded. Used to control which rows are shown in expanded state. Row details will only render for rows that have `_rowDetails` content and are included in this set.',
+      table: {
+        type: { summary: 'Set<number>' },
+      },
+      control: 'object',
+    },
+    loading: {
+      description: 'When true, renders skeleton rows instead of actual data. Useful for showing loading state while data is being fetched.',
+      table: {
+        type: { summary: 'boolean' },
+      },
+      control: 'boolean',
+    },
+    skeletonRowCount: {
+      description: 'Number of skeleton rows to render when loading is true. Defaults to 10 rows.',
+      table: {
+        type: { summary: 'number' },
+      },
+      control: 'number',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<TableProps>;
+
+// Wrapper component to manage sorting state
+const TableWithState = (args: TableProps) => {
+  const [columns, setColumns] = useState(args.columns);
+
+  const handleSortChange = (columnKey: string, direction: 'asc' | 'desc' | true) => {
+    // call Action onSortChange
+    args.onSortChange?.(columnKey, direction);
+
+    // Update column sort states
+    setColumns(prevColumns =>
+      prevColumns.map(col => {
+        if (col.key === columnKey) {
+          return { ...col, sortBy: direction };
+        } else if (col.sortBy === 'asc' || col.sortBy === 'desc') {
+          return { ...col, sortBy: true }; // Reset other sorted columns to neutral
+        }
+        return col;
+      })
+    );
+  };
+
+  return (
+    <TableComponent
+      {...args}
+      columns={columns}
+      onSortChange={handleSortChange}
+    />
+  );
+};
+
+/**
+ * Simple table.
+ * Demonstrates basic table structure with string and number content types.
+ * 
+ * 
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { key: 'name', label: 'Name' },  
+ *     { key: 'email', label: 'Email' },
+ *     { key: 'age', label: 'Age' }     
+ *   ]}
+ *   rowData={[
+ *     { name: 'John', email: 'john@example.com', age: 20 },
+ *     { name: 'Jane', email: 'jane@example.com', age: 21 }
+ *   ]}
+ * />
+ * ```
+ */
+export const Table: Story = {
+  args: {
+    columns: [
+      { key: 'name', label: 'Name' },
+      { key: 'email', label: 'Email' },
+      { key: 'age', label: 'Age' },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [
+      { name: 'John', email: 'john@example.com', age: 20, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jane', email: 'jane@example.com', age: 21, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jim', email: 'jim@example.com', age: 22, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jill', email: 'jill@example.com', age: 23, actions: <ActionButton>Edit</ActionButton> },
+    ],
+  },
+};
+
+/**
+ * Table where all columns are sortable. Demonstrates the three-state sorting cycle: `true` → `'asc'` → `'desc'` → `true`.
+ * Shows how multiple columns can be sortable simultaneously, with only one active sort at a time.
+ * 
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { key: 'name', label: 'Name', sortBy: true },  
+ *     { key: 'email', label: 'Email', sortBy: true },
+ *     { key: 'age', label: 'Age', sortBy: true }    
+ *   ]}
+ *   rowData={[
+ *     { name: 'John', email: 'john@example.com', age: 20 },
+ *     { name: 'Jane', email: 'jane@example.com', age: 21 }
+ *   ]}
+ *   onSortChange={(columnKey, direction) => handleSort(columnKey, direction)}
+ * />
+ * ```
+ */
+export const AllSortable: Story = {
+  render: TableWithState,
+  args: {
+    columns: [
+      { key: 'name', label: 'Name', sortBy: true },
+      { key: 'email', label: 'Email', sortBy: true },
+      { key: 'age', label: 'Age', sortBy: true },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [
+      { name: 'John', email: 'john@example.com', age: 20, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jane', email: 'jane@example.com', age: 21, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jim', email: 'jim@example.com', age: 22, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jill', email: 'jill@example.com', age: 23, actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jack', email: 'jack@example.com', age: 24, actions: <ActionButton>Edit</ActionButton> },
+    ],
+  },
+};
+
+/**
+ * Wide table with 10 columns to demonstrate horizontal scrolling and container query behavior.
+ * This table will show how the container query responds when the table becomes too wide for its container.
+ * 
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { key: 'id', label: 'ID' },
+ *     { key: 'name', label: 'Full Name' },
+ *     { key: 'email', label: 'Email Address' },
+ *     { key: 'phone', label: 'Phone Number' },
+ *     { key: 'department', label: 'Department' },
+ *     { key: 'position', label: 'Position' },
+ *     { key: 'salary', label: 'Salary' },
+ *     { key: 'startDate', label: 'Start Date' },
+ *     { key: 'status', label: 'Status' },
+ *     { key: 'actions', label: 'Actions' }
+ *   ]}
+ *   rowData={[
+ *     { id: 1, name: 'John Doe', email: 'john@company.com', phone: '+1-555-0123', department: 'Engineering', position: 'Senior Developer', salary: '$95,000', startDate: '2022-01-15', status: 'Active', actions: <ActionButton>Edit</ActionButton> }
+ *   ]}
+ * />
+ * ```
+ */
+export const WideTable: Story = {
+  args: {
+    columns: [
+      { key: 'id', label: 'ID' },
+      { key: 'name', label: 'Full Name' },
+      { key: 'email', label: 'Email Address' },
+      { key: 'phone', label: 'Phone Number' },
+      { key: 'department', label: 'Department' },
+      { key: 'position', label: 'Position' },
+      { key: 'salary', label: 'Salary' },
+      { key: 'startDate', label: 'Start Date' },
+      { key: 'status', label: 'Status' },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [
+      { 
+        id: 1, 
+        name: 'John Doe', 
+        email: 'john.doe@company.com', 
+        phone: '+1-555-0123', 
+        department: 'Engineering', 
+        position: 'Senior Developer', 
+        salary: '$95,000', 
+        startDate: '2022-01-15', 
+        status: 'Active', 
+        actions: <ActionButton>Edit</ActionButton> 
+      },
+      { 
+        id: 2, 
+        name: 'Jane Smith', 
+        email: 'jane.smith@company.com', 
+        phone: '+1-555-0124', 
+        department: 'Marketing', 
+        position: 'Marketing Manager', 
+        salary: '$78,000', 
+        startDate: '2021-06-20', 
+        status: 'Active', 
+        actions: <ActionButton>Edit</ActionButton> 
+      },
+      { 
+        id: 3, 
+        name: 'Bob Johnson', 
+        email: 'bob.johnson@company.com', 
+        phone: '+1-555-0125', 
+        department: 'Sales', 
+        position: 'Sales Director', 
+        salary: '$110,000', 
+        startDate: '2020-03-10', 
+        status: 'Active', 
+        actions: <ActionButton>Edit</ActionButton> 
+      },
+      { 
+        id: 4, 
+        name: 'Alice Brown', 
+        email: 'alice.brown@company.com', 
+        phone: '+1-555-0126', 
+        department: 'HR', 
+        position: 'HR Specialist', 
+        salary: '$65,000', 
+        startDate: '2023-02-28', 
+        status: 'Pending', 
+        actions: <ActionButton>Edit</ActionButton> 
+      },
+      { 
+        id: 5, 
+        name: 'Charlie Wilson', 
+        email: 'charlie.wilson@company.com', 
+        phone: '+1-555-0127', 
+        department: 'Finance', 
+        position: 'Financial Analyst', 
+        salary: '$72,000', 
+        startDate: '2022-09-12', 
+        status: 'Active', 
+        actions: <ActionButton>Edit</ActionButton> 
+      },
+    ],
+  },
+};
+
+/**
+ * Table demonstrating complex VNode content in cells with multi-line text and interactive elements.
+ * This shows how the table handles rich content including buttons, badges, and formatted text.
+ * 
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { key: 'user', label: 'User Info' },
+ *     { key: 'description', label: 'Description' },
+ *     { key: 'status', label: 'Status' },
+ *     { key: 'actions', label: 'Actions' }
+ *   ]}
+ *   rowData={[
+ *     { 
+ *       user: <div><strong>John Doe</strong><br/>john@example.com<br/>Senior Developer</div>,
+ *       description: <div>Lead developer for the<br/>e-commerce platform<br/>with 5+ years experience</div>,
+ *       status: <span>Active</span>,
+ *       actions: <div><ActionButton>Edit</ActionButton><br/><ActionButton>Delete</ActionButton><br/><ActionButton>View</ActionButton></div>
+ *     }
+ *   ]}
+ * />
+ * ```
+ */
+export const ComplexCells: Story = {
+  args: {
+    columns: [
+      { key: 'user', label: 'User Info' },
+      { key: 'description', label: 'Description' },
+      { key: 'status', label: 'Status' },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [
+      { 
+        user: (
+          <div>
+            <strong>John Doe</strong><br/>
+            john.doe@company.com<br/>
+            <em>Senior Developer</em>
+          </div>
+        ),
+        description: (
+          <div>
+            Lead developer for the<br/>
+            e-commerce platform<br/>
+            <small>with 5+ years experience</small>
+          </div>
+        ),
+        status: (
+          <span>Active</span>
+        ),
+        actions: (
+          <ActionButtonGroup>
+            <ActionButton value="edit">Edit</ActionButton>
+            <ActionButton value="delete">Delete</ActionButton>
+            <ActionButton value="view">View</ActionButton>
+          </ActionButtonGroup>
+        ),
+      },
+      { 
+        user: (
+          <div>
+            <strong>Jane Smith</strong><br/>
+            jane.smith@company.com<br/>
+            <em>Product Manager</em>
+          </div>
+        ),
+        description: (
+          <div>
+            Manages product roadmap<br/>
+            and feature planning<br/>
+            <small>3+ years in product</small>
+          </div>
+        ),
+        status: (
+          <span>Pending</span>
+        ),
+        actions: (
+          <ActionButtonGroup>
+            <ActionButton value="edit">Edit</ActionButton>
+            <ActionButton value="approve">Approve</ActionButton>
+            <ActionButton value="reject">Reject</ActionButton>
+          </ActionButtonGroup>
+        ),
+      },
+      { 
+        user: (
+          <div>
+            <strong>Bob Johnson</strong><br/>
+            bob.johnson@company.com<br/>
+            <em>UX Designer</em>
+          </div>
+        ),
+        description: (
+          <div>
+            Designs user interfaces<br/>
+            and user experiences<br/>
+            <small>Expert in Figma & Sketch</small>
+          </div>
+        ),
+        status: (
+          <span>Inactive</span>
+        ),
+        actions: (
+          <ActionButtonGroup>
+            <ActionButton value="edit">Edit</ActionButton>
+            <ActionButton value="activate">Activate</ActionButton>
+            <ActionButton value="archive">Archive</ActionButton>
+          </ActionButtonGroup>
+        ),
+      },
+    ],
+  },
+};
+
+/**
+ * Table with stacked mobile layout that uses container queries. 
+ * This demonstrates how the table adapts to its container width rather than viewport width.
+ * The table will stack vertically when its container becomes narrow (≤600px).
+ * 
+ * **Container Query Behavior**: Uses `mobileLayout="stacked"` to enable responsive stacking.
+ * When the container width ≤ 600px:
+ * - Headers are hidden (`display: none`)
+ * - Cells stack vertically (`display: block`)
+ * - Column labels appear as `data-label` attributes before each cell value
+ * - Perfect for mobile views, sidebars, or constrained layouts
+ * 
+ * ```tsx
+ * <Table
+ *   mobileLayout="stacked"
+ *   columns={[
+ *     { key: 'name', label: 'Name' },  
+ *     { key: 'email', label: 'Email' },
+ *     { key: 'age', label: 'Age' }    
+ *   ]}
+ *   rowData={[
+ *     { name: 'John', email: 'john@example.com', age: 20 },
+ *     { name: 'Jane', email: 'jane@example.com', age: 21 }
+ *   ]}
+ * />
+ * ```
+ */
+export const StackedMobileLayout: Story = {
+  args: {
+    mobileLayout: 'stacked',
+    columns: [
+      { key: 'name', label: 'Name' },
+      { key: 'email', label: 'Email' },
+      { key: 'age', label: 'Age' },
+      { key: 'status', label: 'Status' },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [
+      { name: 'John Doe', email: 'john.doe@example.com', age: 28, status: 'Active', actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Jane Smith', email: 'jane.smith@example.com', age: 32, status: 'Inactive', actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Bob Johnson', email: 'bob.johnson@example.com', age: 45, status: 'Active', actions: <ActionButton>Edit</ActionButton> },
+      { name: 'Alice Brown', email: 'alice.brown@example.com', age: 29, status: 'Pending', actions: <ActionButton>Edit</ActionButton> },
+    ],
+  },
+};
+
+
+/**
+ * Table with programmatically controlled expandable rows.
+ * Row expansion is controlled by buttons or other interactive elements within the column content.
+ * Developers must manage the `expandedRows` state themselves.
+ * 
+ * **Features**:
+ * - Row details only render when both `_rowDetails` exists and row index is in `expandedRows`
+ * - Row details span the full width of the table
+ * - Supports any VNode content in the `_rowDetails` property
+ * 
+ * ```tsx
+ * const [expandedRows, setExpandedRows] = useState(new Set());
+ * 
+ * const toggleRow = (rowIndex: number) => {
+ *   setExpandedRows(prev => {
+ *     const newSet = new Set(prev);
+ *     if (newSet.has(rowIndex)) {
+ *       newSet.delete(rowIndex);
+ *     } else {
+ *       newSet.add(rowIndex);
+ *     }
+ *     return newSet;
+ *   });
+ * };
+ * 
+ * <Table
+ *   columns={[
+ *     { key: 'name', label: 'Name' },  
+ *     { key: 'email', label: 'Email' },
+ *     { key: 'actions', label: 'Actions' }
+ *   ]}
+ *   rowData={[
+ *     { 
+ *       name: 'John', 
+ *       email: 'john@example.com', 
+ *       actions: <ActionButton onClick={() => toggleRow(0)}>Toggle Details</ActionButton>,
+ *       _rowDetails: <div>Additional information...</div>
+ *     }
+ *   ]}
+ *   expandedRows={expandedRows}
+ * />
+ * ```
+ */
+export const RowDetails: Story = {
+  render: (args) => {
+    const [expandedRows, setExpandedRows] = useState(new Set<number>());
+
+    const toggleRow = (rowIndex: number) => {
+      setExpandedRows(prev => {
+        const newSet = new Set(prev);
+        if (newSet.has(rowIndex)) {
+          newSet.delete(rowIndex);
+        } else {
+          newSet.add(rowIndex);
+        }
+        return newSet;
+      });
+    };
+
+    const rowData = [
+      { 
+        name: 'John Doe', 
+        email: 'john.doe@company.com', 
+        status: 'Active', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(0)}>
+            {expandedRows.has(0) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Employee Details</h3>
+            <p><strong>Department:</strong> Engineering</p>
+            <p><strong>Position:</strong> Senior Developer</p>
+            <p><strong>Start Date:</strong> January 15, 2022</p>
+            <p><strong>Notes:</strong> Excellent performance, leads the frontend team.</p>
+            <div style={{ marginTop: '12px' }}>
+              <ActionButton style={{ marginRight: '8px' }}>Update Details</ActionButton>
+              <ActionButton>View Full Profile</ActionButton>
+            </div>
+          </>
+        )
+      },
+      { 
+        name: 'Jane Smith', 
+        email: 'jane.smith@company.com', 
+        status: 'Pending', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(1)}>
+            {expandedRows.has(1) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Pending Approval</h3>
+            <p><strong>Department:</strong> Marketing</p>
+            <p><strong>Position:</strong> Marketing Manager</p>
+            <p><strong>Application Date:</strong> December 1, 2024</p>
+            <p><strong>Status:</strong> Awaiting HR approval</p>
+            <div style={{ marginTop: '12px' }}>
+              <ActionButton style={{ marginRight: '8px', backgroundColor: '#22c55e', color: 'white', border: 'none', padding: '6px 12px', borderRadius: '4px' }}>Approve</ActionButton>
+              <ActionButton style={{ backgroundColor: '#ef4444', color: 'white', border: 'none', padding: '6px 12px', borderRadius: '4px' }}>Reject</ActionButton>
+            </div>
+          </>
+        )
+      },
+      { 
+        name: 'Bob Johnson', 
+        email: 'bob.johnson@company.com', 
+        status: 'Inactive', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(2)}>
+            {expandedRows.has(2) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Account Information</h3>
+            <p><strong>Department:</strong> Sales</p>
+            <p><strong>Position:</strong> Sales Director</p>
+            <p><strong>Last Active:</strong> November 20, 2024</p>
+            <p><strong>Reason:</strong> On extended leave</p>
+            <div style={{ marginTop: '12px' }}>
+              <ActionButton style={{ marginRight: '8px' }}>Reactivate Account</ActionButton>
+              <ActionButton>Contact Employee</ActionButton>
+            </div>
+          </>
+        )
+      },
+    ];
+
+    return (
+      <TableComponent
+        {...args}
+        columns={[
+          { key: 'name', label: 'Name' },
+          { key: 'email', label: 'Email' },
+          { key: 'status', label: 'Status' },
+          { key: 'actions', label: 'Actions' },
+        ]}
+        rowData={rowData}
+        expandedRows={expandedRows}
+      />
+    );
+  },
+};
+
+/**
+ * Table in loading state with skeleton rows.
+ * Demonstrates how the table appears while data is being fetched.
+ * Each cell shows a skeleton placeholder that matches the table structure.
+ * 
+ * **Features**:
+ * - Shows skeleton rows instead of actual data when `loading` is true
+ * - Configurable number of skeleton rows via `skeletonRowCount` prop
+ * - Maintains table structure and column headers during loading
+ * - Each cell contains a single-line skeleton component
+ * 
+ * ```tsx
+ * <Table
+ *   loading={true}
+ *   skeletonRowCount={5}
+ *   columns={[
+ *     { key: 'name', label: 'Name' },  
+ *     { key: 'email', label: 'Email' },
+ *     { key: 'status', label: 'Status' }
+ *   ]}
+ *   rowData={[]} // Empty array when loading
+ * />
+ * ```
+ */
+export const LoadingState: Story = {
+  args: {
+    loading: true,
+    skeletonRowCount: 5,
+    columns: [
+      { key: 'name', label: 'Name' },
+      { key: 'email', label: 'Email' },
+      { key: 'status', label: 'Status' },
+      { key: 'actions', label: 'Actions' },
+    ],
+    rowData: [], // Empty when loading
+  },
+};
+
+/**
+ * Table with VNode labels in column headers.
+ * Demonstrates how column labels can be VNode elements instead of simple strings.
+ * This allows for rich header content like icons, formatted text, or custom components.
+ *
+ * **Features**:
+ * - Column labels can be VNode elements (JSX components)
+ * - Supports any valid Preact VNode content in headers
+ * - Maintains all table functionality with custom header content
+ * - Useful for adding icons, tooltips, or formatted text to headers
+ *
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { key: 'name', label: <span><strong>👤 User Name</strong></span> },
+ *     { key: 'email', label: <span style={{ color: '#0066cc' }}>📧 Email</span> },
+ *     { key: 'status', label: <em>Status Info</em> }
+ *   ]}
+ *   rowData={[
+ *     { name: 'John', email: 'john@example.com', status: 'Active' }
+ *   ]}
+ * />
+ * ```
+ */
+export const VNodeLabels: Story = {
+  args: {
+    columns: [
+      {
+        key: 'name',
+        label: (
+          <span>
+            <strong>👤 User Name</strong>
+          </span>
+        ),
+        ariaLabel: 'User Name',
+      },
+      {
+        key: 'email',
+        label: <span style={{ color: '#0066cc' }}>📧 Email Address</span>,
+        ariaLabel: 'Email Address',
+      },
+      {
+        key: 'role',
+        label: <em style={{ color: '#666' }}>Role & Department</em>,
+        ariaLabel: 'Role & Department',
+      },
+      {
+        key: 'status',
+        label: (
+          <span
+            style={{
+              padding: '4px 8px',
+              backgroundColor: '#f0f9ff',
+              borderRadius: '4px',
+              fontSize: '12px',
+            }}
+          >
+            📊 Status
+          </span>
+        ),
+        ariaLabel: 'Status',
+      },
+      {
+        key: 'actions',
+        label: <span>⚙️ Actions</span>,
+        ariaLabel: 'Actions',
+      },
+    ],
+    rowData: [
+      {
+        name: 'John Doe',
+        email: 'john.doe@company.com',
+        role: 'Senior Developer',
+        status: 'Active',
+        actions: <ActionButton>Edit</ActionButton>,
+      },
+      {
+        name: 'Jane Smith',
+        email: 'jane.smith@company.com',
+        role: 'Product Manager',
+        status: 'Active',
+        actions: <ActionButton>Edit</ActionButton>,
+      },
+      {
+        name: 'Bob Johnson',
+        email: 'bob.johnson@company.com',
+        role: 'UX Designer',
+        status: 'Inactive',
+        actions: <ActionButton>Edit</ActionButton>,
+      },
+    ],
+  },
+};
+
+/**
+ * Table with pagination to navigate through multiple pages of data.
+ * This demonstrates how to integrate the Pagination component with the Table component.
+ * 
+ * **Features**:
+ * - Pagination controls below the table
+ * - Page state management with useState
+ * - Dynamic row data based on current page
+ * - Items per page configuration
+ * 
+ * ```tsx
+ * const [currentPage, setCurrentPage] = useState(1);
+ * const itemsPerPage = 5;
+ * const totalItems = 50;
+ * const totalPages = Math.ceil(totalItems / itemsPerPage);
+ * 
+ * const paginatedData = allData.slice(
+ *   (currentPage - 1) * itemsPerPage,
+ *   currentPage * itemsPerPage
+ * );
+ * 
+ * <div>
+ *   <Table
+ *     columns={columns}
+ *     rowData={paginatedData}
+ *   />
+ *   <Pagination
+ *     currentPage={currentPage}
+ *     totalPages={totalPages}
+ *     onChange={setCurrentPage}
+ *   />
+ * </div>
+ * ```
+ */
+export const WithPagination: Story = {
+  render: (args) => {
+    const [currentPage, setCurrentPage] = useState(1);
+    const [pageSize, setPageSize] = useState(5);
+    
+    // Page size options
+    const pageSizeOptions: PickerOption[] = [
+      { value: '5', text: '5' },
+      { value: '10', text: '10' },
+      { value: '15', text: '15' },
+    ];
+    
+    // Generate sample data (287 items to match screenshot)
+    const allData = Array.from({ length: 287 }, (_, index) => ({
+      id: index + 1,
+      name: `User ${index + 1}`,
+      email: `user${index + 1}@example.com`,
+      department: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'][index % 5],
+      status: ['Active', 'Inactive', 'Pending'][index % 3],
+      actions: <ActionButton>Edit</ActionButton>,
+    }));
+
+    const totalPages = Math.ceil(allData.length / pageSize);
+    
+    // Calculate item range
+    const startItem = (currentPage - 1) * pageSize + 1;
+    const endItem = Math.min(currentPage * pageSize, allData.length);
+    const totalItems = allData.length;
+    
+    // Get current page data
+    const paginatedData = allData.slice(
+      (currentPage - 1) * pageSize,
+      currentPage * pageSize
+    );
+
+    // Handle page size change
+    const handlePageSizeChange = (event: Event) => {
+      const target = event.target as HTMLSelectElement;
+      const newPageSize = Number(target.value);
+      setPageSize(newPageSize);
+      setCurrentPage(1); // Reset to first page when page size changes
+    };
+
+    return (
+      <div>
+        <TableComponent
+          {...args}
+          columns={[
+            { key: 'id', label: 'ID' },
+            { key: 'name', label: 'Name' },
+            { key: 'email', label: 'Email' },
+            { key: 'department', label: 'Department' },
+            { key: 'status', label: 'Status' },
+            { key: 'actions', label: 'Actions' },
+          ]}
+          rowData={paginatedData}
+        />
+        <div style={{ marginTop: 'var(--spacing-small)', display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+          <span style={{ 
+            font: 'var(--type-body-1-default-font)',
+            letterSpacing: 'var(--type-body-1-default-letter-spacing)',
+            color: 'var(--color-neutral-800)'
+          }}>
+            Items {startItem} to {endItem} of {totalItems} total
+          </span>
+          <Pagination
+            currentPage={currentPage}
+            totalPages={totalPages}
+            onChange={setCurrentPage}
+          />
+          <div style={{ 
+            display: 'flex', 
+            alignItems: 'center', 
+            gap: 'var(--spacing-xsmall)',
+            font: 'var(--type-body-1-default-font)',
+            letterSpacing: 'var(--type-body-1-default-letter-spacing)',
+            color: 'var(--color-neutral-800)'
+          }}>
+            <span>Show</span>
+            <Picker
+              variant="primary"
+              size="medium"
+              value={String(pageSize)}
+              options={pageSizeOptions}
+              handleSelect={handlePageSizeChange}
+              aria-label="Items per page"
+            />
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Table with expandable row details and stacked mobile layout.
+ * Combines the expandable rows feature with responsive mobile behavior using container queries.
+ * 
+ * **Features**:
+ * - Expandable rows with toggle buttons
+ * - Stacked mobile layout when container width ≤ 600px
+ * - Row details expand in both desktop and mobile views
+ * - Mobile view shows labels above each cell value
+ * 
+ * ```tsx
+ * const [expandedRows, setExpandedRows] = useState(new Set());
+ * 
+ * const toggleRow = (rowIndex: number) => {
+ *   setExpandedRows(prev => {
+ *     const newSet = new Set(prev);
+ *     if (newSet.has(rowIndex)) {
+ *       newSet.delete(rowIndex);
+ *     } else {
+ *       newSet.add(rowIndex);
+ *     }
+ *     return newSet;
+ *   });
+ * };
+ * 
+ * <Table
+ *   mobileLayout="stacked"
+ *   columns={columns}
+ *   rowData={rowDataWithDetails}
+ *   expandedRows={expandedRows}
+ * />
+ * ```
+ */
+export const ExpandableRowsWithMobileLayout: Story = {
+  render: (args) => {
+    const [expandedRows, setExpandedRows] = useState(new Set<number>());
+
+    const toggleRow = (rowIndex: number) => {
+      setExpandedRows((prev) => {
+        const newSet = new Set(prev);
+        if (newSet.has(rowIndex)) {
+          newSet.delete(rowIndex);
+        } else {
+          newSet.add(rowIndex);
+        }
+        return newSet;
+      });
+    };
+
+    const rowData = [
+      { 
+        name: 'John Doe', 
+        email: 'john.doe@company.com', 
+        status: 'Active', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(0)}>
+            {expandedRows.has(0) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Employee Details</h3>
+            <p><strong>Department:</strong> Engineering</p>
+            <p><strong>Position:</strong> Senior Developer</p>
+            <p><strong>Start Date:</strong> January 15, 2022</p>
+            <p><strong>Notes:</strong> Excellent performance, leads the frontend team.</p>
+          </>
+        )
+      },
+      { 
+        name: 'Jane Smith', 
+        email: 'jane.smith@company.com', 
+        status: 'Pending', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(1)}>
+            {expandedRows.has(1) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Pending Approval</h3>
+            <p><strong>Department:</strong> Marketing</p>
+            <p><strong>Position:</strong> Marketing Manager</p>
+            <p><strong>Application Date:</strong> December 1, 2024</p>
+            <p><strong>Status:</strong> Awaiting HR approval</p>
+          </>
+        )
+      },
+      { 
+        name: 'Bob Johnson', 
+        email: 'bob.johnson@company.com', 
+        status: 'Inactive', 
+        actions: (
+          <ActionButton onClick={() => toggleRow(2)}>
+            {expandedRows.has(2) ? 'Hide' : 'Show'}
+          </ActionButton>
+        ),
+        _rowDetails: (
+          <>
+            <h3>Account Information</h3>
+            <p><strong>Department:</strong> Sales</p>
+            <p><strong>Position:</strong> Sales Director</p>
+            <p><strong>Last Active:</strong> November 20, 2024</p>
+            <p><strong>Reason:</strong> On extended leave</p>
+          </>
+        )
+      },
+    ];
+
+    return (
+      <TableComponent
+        {...args}
+        mobileLayout="stacked"
+        columns={[
+          { key: 'name', label: 'Name', ariaLabel: 'Name' },
+          { key: 'email', label: 'Email', ariaLabel: 'Email' },
+          { key: 'status', label: 'Status', ariaLabel: 'Status' },
+          { key: 'actions', label: 'Actions', ariaLabel: 'Actions' },
+        ]}
+        rowData={rowData}
+        expandedRows={expandedRows}
+      />
+    );
+  },
+};
+