@delightui/components 0.1.105 → 0.1.107

package/docs/components/organisms/TableHeaderCell.md

@@ -0,0 +1,661 @@
+# TableHeaderCell
+
+## Description
+
+A specialized table header cell component designed for table headers and column headings. TableHeaderCell provides semantic HTML structure and accessibility features for table column headers, supporting features like column sorting, filtering, and proper screen reader navigation. It extends the standard HTML table header cell element with consistent styling and behavior.
+
+## Aliases
+
+- TableHeaderCell
+- Header Cell
+- Column Header
+- TH Cell
+- Table Head Cell
+
+## Props Breakdown
+
+**Extends:** `TdHTMLAttributes<HTMLTableCellElement>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `ReactNode` | - | No | Content to display in the header cell |
+| `className` | `string` | - | No | Additional CSS class names |
+
+Plus all standard HTML td attributes (scope, headers, colSpan, rowSpan, etc.).
+
+## Examples
+
+### Basic Table Header
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell } from '@delightui/components';
+
+function BasicTableHeaderExample() {
+  const employees = [
+    { name: 'Alice Johnson', department: 'Engineering', salary: 75000 },
+    { name: 'Bob Wilson', department: 'Marketing', salary: 65000 },
+    { name: 'Carol Brown', department: 'Design', salary: 70000 }
+  ];
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderCell>Employee Name</TableHeaderCell>
+          <TableHeaderCell>Department</TableHeaderCell>
+          <TableHeaderCell>Annual Salary</TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {employees.map((employee, index) => (
+          <TableRow key={index}>
+            <TableCell>{employee.name}</TableCell>
+            <TableCell>{employee.department}</TableCell>
+            <TableCell>${employee.salary.toLocaleString()}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Sortable Table Headers
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell, Button, Text } from '@delightui/components';
+
+function SortableTableHeaderExample() {
+  const [sortField, setSortField] = useState<string>('');
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+  
+  const products = [
+    { name: 'Laptop Pro', price: 1299.99, stock: 15, category: 'Electronics' },
+    { name: 'Wireless Mouse', price: 49.99, stock: 50, category: 'Accessories' },
+    { name: 'Monitor 27"', price: 399.99, stock: 8, category: 'Electronics' },
+    { name: 'Keyboard Mechanical', price: 129.99, stock: 25, category: 'Accessories' }
+  ];
+
+  const handleSort = (field: string) => {
+    if (sortField === field) {
+      setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc');
+    } else {
+      setSortField(field);
+      setSortDirection('asc');
+    }
+  };
+
+  const sortedProducts = [...products].sort((a, b) => {
+    if (!sortField) return 0;
+    const aValue = a[sortField as keyof typeof a];
+    const bValue = b[sortField as keyof typeof b];
+    const modifier = sortDirection === 'asc' ? 1 : -1;
+    return aValue > bValue ? modifier : aValue < bValue ? -modifier : 0;
+  });
+
+  const getSortIcon = (field: string) => {
+    if (sortField !== field) return '↕️';
+    return sortDirection === 'asc' ? '↑' : '↓';
+  };
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderCell>
+            <Button
+              type="Ghost"
+              onClick={() => handleSort('name')}
+              style={{ display: 'flex', alignItems: 'center', gap: '4px' }}
+            >
+              Product Name {getSortIcon('name')}
+            </Button>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <Button
+              type="Ghost"
+              onClick={() => handleSort('price')}
+              style={{ display: 'flex', alignItems: 'center', gap: '4px' }}
+            >
+              Price {getSortIcon('price')}
+            </Button>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <Button
+              type="Ghost"
+              onClick={() => handleSort('stock')}
+              style={{ display: 'flex', alignItems: 'center', gap: '4px' }}
+            >
+              Stock {getSortIcon('stock')}
+            </Button>
+          </TableHeaderCell>
+          <TableHeaderCell>Category</TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {sortedProducts.map((product, index) => (
+          <TableRow key={index}>
+            <TableCell>{product.name}</TableCell>
+            <TableCell>${product.price.toFixed(2)}</TableCell>
+            <TableCell>{product.stock}</TableCell>
+            <TableCell>{product.category}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Multi-Level Headers
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell } from '@delightui/components';
+
+function MultiLevelHeaderExample() {
+  const salesData = [
+    { region: 'North', q1Sales: 125000, q1Target: 120000, q2Sales: 135000, q2Target: 130000 },
+    { region: 'South', q1Sales: 110000, q1Target: 115000, q2Sales: 125000, q2Target: 120000 },
+    { region: 'East', q1Sales: 95000, q1Target: 100000, q2Sales: 105000, q2Target: 110000 },
+    { region: 'West', q1Sales: 140000, q1Target: 135000, q2Sales: 150000, q2Target: 145000 }
+  ];
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderCell rowSpan={2}>Region</TableHeaderCell>
+          <TableHeaderCell colSpan={2}>Q1 2024</TableHeaderCell>
+          <TableHeaderCell colSpan={2}>Q2 2024</TableHeaderCell>
+        </TableRow>
+        <TableRow>
+          <TableHeaderCell>Sales</TableHeaderCell>
+          <TableHeaderCell>Target</TableHeaderCell>
+          <TableHeaderCell>Sales</TableHeaderCell>
+          <TableHeaderCell>Target</TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {salesData.map((data, index) => (
+          <TableRow key={index}>
+            <TableCell style={{ fontWeight: 'bold' }}>{data.region}</TableCell>
+            <TableCell>${data.q1Sales.toLocaleString()}</TableCell>
+            <TableCell>${data.q1Target.toLocaleString()}</TableCell>
+            <TableCell>${data.q2Sales.toLocaleString()}</TableCell>
+            <TableCell>${data.q2Target.toLocaleString()}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Filterable Headers
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell, Input, Select, Option } from '@delightui/components';
+
+function FilterableHeaderExample() {
+  const [nameFilter, setNameFilter] = useState('');
+  const [departmentFilter, setDepartmentFilter] = useState('');
+  
+  const employees = [
+    { name: 'John Smith', department: 'Engineering', level: 'Senior', salary: 85000 },
+    { name: 'Sarah Davis', department: 'Marketing', level: 'Mid', salary: 65000 },
+    { name: 'Mike Johnson', department: 'Engineering', level: 'Junior', salary: 55000 },
+    { name: 'Lisa Brown', department: 'Design', level: 'Senior', salary: 75000 },
+    { name: 'Tom Wilson', department: 'Marketing', level: 'Senior', salary: 70000 }
+  ];
+
+  const departments = ['All', ...new Set(employees.map(emp => emp.department))];
+
+  const filteredEmployees = employees.filter(employee => {
+    const matchesName = employee.name.toLowerCase().includes(nameFilter.toLowerCase());
+    const matchesDepartment = departmentFilter === '' || departmentFilter === 'All' || employee.department === departmentFilter;
+    return matchesName && matchesDepartment;
+  });
+
+  return (
+    <div>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderCell>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                <span>Employee Name</span>
+                <Input
+                  placeholder="Filter by name..."
+                  value={nameFilter}
+                  onValueChange={setNameFilter}
+                  size="Small"
+                />
+              </div>
+            </TableHeaderCell>
+            <TableHeaderCell>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}>
+                <span>Department</span>
+                <Select value={departmentFilter} onValueChange={setDepartmentFilter}>
+                  {departments.map(dept => (
+                    <Option key={dept} value={dept}>{dept}</Option>
+                  ))}
+                </Select>
+              </div>
+            </TableHeaderCell>
+            <TableHeaderCell>Level</TableHeaderCell>
+            <TableHeaderCell>Salary</TableHeaderCell>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {filteredEmployees.map((employee, index) => (
+            <TableRow key={index}>
+              <TableCell>{employee.name}</TableCell>
+              <TableCell>{employee.department}</TableCell>
+              <TableCell>{employee.level}</TableCell>
+              <TableCell>${employee.salary.toLocaleString()}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+```
+
+### Styled Header Cells
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell, Text } from '@delightui/components';
+
+function StyledHeaderExample() {
+  const performanceData = [
+    { metric: 'Page Views', current: 125000, previous: 115000, change: 8.7 },
+    { metric: 'Unique Visitors', current: 45000, previous: 42000, change: 7.1 },
+    { metric: 'Bounce Rate', current: 35.2, previous: 38.1, change: -7.6 },
+    { metric: 'Conversion Rate', current: 3.4, previous: 3.1, change: 9.7 }
+  ];
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderCell style={{ 
+            backgroundColor: '#f8f9fa', 
+            fontWeight: 'bold',
+            textAlign: 'left',
+            padding: '16px'
+          }}>
+            Performance Metric
+          </TableHeaderCell>
+          <TableHeaderCell style={{ 
+            backgroundColor: '#e3f2fd', 
+            fontWeight: 'bold',
+            textAlign: 'center',
+            padding: '16px'
+          }}>
+            Current Period
+          </TableHeaderCell>
+          <TableHeaderCell style={{ 
+            backgroundColor: '#f3e5f5', 
+            fontWeight: 'bold',
+            textAlign: 'center',
+            padding: '16px'
+          }}>
+            Previous Period
+          </TableHeaderCell>
+          <TableHeaderCell style={{ 
+            backgroundColor: '#e8f5e8', 
+            fontWeight: 'bold',
+            textAlign: 'center',
+            padding: '16px'
+          }}>
+            % Change
+          </TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {performanceData.map((data, index) => (
+          <TableRow key={index}>
+            <TableCell style={{ fontWeight: 'bold' }}>{data.metric}</TableCell>
+            <TableCell style={{ textAlign: 'center' }}>
+              {data.metric.includes('Rate') ? `${data.current}%` : data.current.toLocaleString()}
+            </TableCell>
+            <TableCell style={{ textAlign: 'center' }}>
+              {data.metric.includes('Rate') ? `${data.previous}%` : data.previous.toLocaleString()}
+            </TableCell>
+            <TableCell style={{ 
+              textAlign: 'center',
+              color: data.change > 0 ? '#2e7d32' : '#d32f2f',
+              fontWeight: 'bold'
+            }}>
+              {data.change > 0 ? '+' : ''}{data.change.toFixed(1)}%
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Headers with Icons
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell, Icon, Text } from '@delightui/components';
+
+function IconHeaderExample() {
+  const taskData = [
+    { title: 'Update Homepage', assignee: 'John Doe', priority: 'High', status: 'In Progress', dueDate: '2024-02-15' },
+    { title: 'Fix Login Bug', assignee: 'Jane Smith', priority: 'Critical', status: 'Open', dueDate: '2024-02-10' },
+    { title: 'Design New Logo', assignee: 'Mike Wilson', priority: 'Medium', status: 'Complete', dueDate: '2024-02-20' }
+  ];
+
+  const getPriorityColor = (priority: string) => {
+    switch (priority) {
+      case 'Critical': return '#d32f2f';
+      case 'High': return '#f57c00';
+      case 'Medium': return '#1976d2';
+      default: return '#757575';
+    }
+  };
+
+  const getStatusIcon = (status: string) => {
+    switch (status) {
+      case 'Complete': return '✅';
+      case 'In Progress': return '⏳';
+      case 'Open': return '📋';
+      default: return '❓';
+    }
+  };
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHeaderCell>
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <Icon name="ListItem" />
+              <Text weight="Bold">Task</Text>
+            </div>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <Icon name="Person" />
+              <Text weight="Bold">Assignee</Text>
+            </div>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <Icon name="Priority" />
+              <Text weight="Bold">Priority</Text>
+            </div>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <Icon name="Status" />
+              <Text weight="Bold">Status</Text>
+            </div>
+          </TableHeaderCell>
+          <TableHeaderCell>
+            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+              <Icon name="Calendar" />
+              <Text weight="Bold">Due Date</Text>
+            </div>
+          </TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {taskData.map((task, index) => (
+          <TableRow key={index}>
+            <TableCell>{task.title}</TableCell>
+            <TableCell>{task.assignee}</TableCell>
+            <TableCell>
+              <Text style={{ color: getPriorityColor(task.priority), fontWeight: 'bold' }}>
+                {task.priority}
+              </Text>
+            </TableCell>
+            <TableCell>
+              <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+                <span>{getStatusIcon(task.status)}</span>
+                <Text>{task.status}</Text>
+              </div>
+            </TableCell>
+            <TableCell>{task.dueDate}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+### Resizable Headers
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell } from '@delightui/components';
+
+function ResizableHeaderExample() {
+  const [columnWidths, setColumnWidths] = useState({
+    name: 200,
+    email: 250,
+    phone: 150,
+    department: 150
+  });
+
+  const contacts = [
+    { name: 'Alice Johnson', email: 'alice.johnson@company.com', phone: '+1-555-0101', department: 'Engineering' },
+    { name: 'Bob Smith', email: 'bob.smith@company.com', phone: '+1-555-0102', department: 'Marketing' },
+    { name: 'Carol Brown', email: 'carol.brown@company.com', phone: '+1-555-0103', department: 'Design' }
+  ];
+
+  const handleResize = (column: string, newWidth: number) => {
+    setColumnWidths(prev => ({
+      ...prev,
+      [column]: Math.max(100, newWidth)
+    }));
+  };
+
+  return (
+    <div style={{ overflowX: 'auto' }}>
+      <Table style={{ tableLayout: 'fixed', width: '100%' }}>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderCell 
+              style={{ 
+                width: `${columnWidths.name}px`,
+                position: 'relative',
+                minWidth: '100px'
+              }}
+            >
+              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+                <span>Name</span>
+                <div
+                  style={{
+                    cursor: 'col-resize',
+                    padding: '0 4px',
+                    userSelect: 'none'
+                  }}
+                  onMouseDown={(e) => {
+                    const startX = e.clientX;
+                    const startWidth = columnWidths.name;
+                    
+                    const handleMouseMove = (moveEvent: MouseEvent) => {
+                      const newWidth = startWidth + (moveEvent.clientX - startX);
+                      handleResize('name', newWidth);
+                    };
+                    
+                    const handleMouseUp = () => {
+                      document.removeEventListener('mousemove', handleMouseMove);
+                      document.removeEventListener('mouseup', handleMouseUp);
+                    };
+                    
+                    document.addEventListener('mousemove', handleMouseMove);
+                    document.addEventListener('mouseup', handleMouseUp);
+                  }}
+                >
+                  ⚊
+                </div>
+              </div>
+            </TableHeaderCell>
+            <TableHeaderCell style={{ width: `${columnWidths.email}px` }}>
+              <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center' }}>
+                <span>Email</span>
+                <div
+                  style={{ cursor: 'col-resize', padding: '0 4px' }}
+                  onMouseDown={(e) => {
+                    const startX = e.clientX;
+                    const startWidth = columnWidths.email;
+                    
+                    const handleMouseMove = (moveEvent: MouseEvent) => {
+                      const newWidth = startWidth + (moveEvent.clientX - startX);
+                      handleResize('email', newWidth);
+                    };
+                    
+                    const handleMouseUp = () => {
+                      document.removeEventListener('mousemove', handleMouseMove);
+                      document.removeEventListener('mouseup', handleMouseUp);
+                    };
+                    
+                    document.addEventListener('mousemove', handleMouseMove);
+                    document.addEventListener('mouseup', handleMouseUp);
+                  }}
+                >
+                  ⚊
+                </div>
+              </div>
+            </TableHeaderCell>
+            <TableHeaderCell style={{ width: `${columnWidths.phone}px` }}>Phone</TableHeaderCell>
+            <TableHeaderCell style={{ width: `${columnWidths.department}px` }}>Department</TableHeaderCell>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {contacts.map((contact, index) => (
+            <TableRow key={index}>
+              <TableCell style={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>
+                {contact.name}
+              </TableCell>
+              <TableCell style={{ overflow: 'hidden', textOverflow: 'ellipsis' }}>
+                {contact.email}
+              </TableCell>
+              <TableCell>{contact.phone}</TableCell>
+              <TableCell>{contact.department}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}
+```
+
+### Accessibility Enhanced Headers
+
+```tsx
+import { Table, TableBody, TableRow, TableHeaderCell, TableHeader, TableCell } from '@delightui/components';
+
+function AccessibleHeaderExample() {
+  const studentGrades = [
+    { student: 'Emma Wilson', math: 92, science: 88, english: 95, history: 90 },
+    { student: 'Liam Johnson', math: 85, science: 91, english: 87, history: 93 },
+    { student: 'Olivia Brown', math: 96, science: 94, english: 92, history: 89 }
+  ];
+
+  return (
+    <Table 
+      role="table" 
+      aria-label="Student Grade Report"
+    >
+      <TableHeader>
+        <TableRow role="row">
+          <TableHeaderCell 
+            id="student-header"
+            scope="col"
+            role="columnheader"
+            aria-sort="none"
+            tabIndex={0}
+          >
+            Student Name
+          </TableHeaderCell>
+          <TableHeaderCell 
+            id="math-header"
+            scope="col"
+            role="columnheader"
+            aria-sort="none"
+            tabIndex={0}
+          >
+            Mathematics
+          </TableHeaderCell>
+          <TableHeaderCell 
+            id="science-header"
+            scope="col"
+            role="columnheader"
+            aria-sort="none"
+            tabIndex={0}
+          >
+            Science
+          </TableHeaderCell>
+          <TableHeaderCell 
+            id="english-header"
+            scope="col"
+            role="columnheader"
+            aria-sort="none"
+            tabIndex={0}
+          >
+            English
+          </TableHeaderCell>
+          <TableHeaderCell 
+            id="history-header"
+            scope="col"
+            role="columnheader"
+            aria-sort="none"
+            tabIndex={0}
+          >
+            History
+          </TableHeaderCell>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {studentGrades.map((grades, index) => (
+          <TableRow key={index} role="row">
+            <TableCell 
+              headers="student-header"
+              role="rowheader"
+              scope="row"
+            >
+              {grades.student}
+            </TableCell>
+            <TableCell 
+              headers="math-header"
+              role="cell"
+              aria-label={`Mathematics grade: ${grades.math} out of 100`}
+            >
+              {grades.math}%
+            </TableCell>
+            <TableCell 
+              headers="science-header"
+              role="cell"
+              aria-label={`Science grade: ${grades.science} out of 100`}
+            >
+              {grades.science}%
+            </TableCell>
+            <TableCell 
+              headers="english-header"
+              role="cell"
+              aria-label={`English grade: ${grades.english} out of 100`}
+            >
+              {grades.english}%
+            </TableCell>
+            <TableCell 
+              headers="history-header"
+              role="cell"
+              aria-label={`History grade: ${grades.history} out of 100`}
+            >
+              {grades.history}%
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```