@12-apps/ui 1.0.0

package/src/components/data-display/Table/Table.types.ts

@@ -0,0 +1,335 @@
+import type { TableProps as MuiTableProps } from '@mui/material';
+import type React from 'react';
+
+// Advanced feature types
+export type TableDensity = 'compact' | 'normal' | 'comfortable';
+
+export interface SortConfig {
+  key: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface FilterConfig {
+  [key: string]: {
+    value: unknown;
+    operator?: 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'lt' | 'gte' | 'lte';
+  };
+}
+
+export interface ColumnConfig {
+  key: string;
+  label: string;
+  sortable?: boolean;
+  filterable?: boolean;
+  width?: number | string;
+  minWidth?: number;
+  priority?: number; // 1 = highest priority, higher numbers = lower priority
+  align?: 'left' | 'center' | 'right';
+  render?: (value: unknown, rowData: Record<string, unknown>) => React.ReactNode;
+  filterType?: 'text' | 'number' | 'select' | 'date' | 'boolean';
+  filterOptions?: { label: string; value: unknown }[];
+}
+
+export interface VirtualScrollConfig {
+  enabled: boolean;
+  rowHeight: number;
+  overscan?: number; // Number of items to render outside visible area
+  estimatedRowHeight?: number;
+}
+
+export interface ResponsiveConfig {
+  enabled: boolean;
+  columnPriorities?: number[]; // Priority order for columns
+  breakpoints?: {
+    hideColumns?: {
+      xs?: number[]; // Column indices to hide on extra small screens
+      sm?: number[]; // Column indices to hide on small screens
+      md?: number[]; // Column indices to hide on medium screens
+    };
+  };
+}
+
+export interface SelectionConfig {
+  enabled: boolean;
+  selectedRows: (string | number)[];
+  onSelectionChange: (selectedRows: (string | number)[]) => void;
+  selectAllEnabled?: boolean;
+  rowKeyExtractor?: (rowData: Record<string, unknown>, index: number) => string | number;
+}
+
+export type TableStripeColor = 'primary' | 'secondary' | 'info' | 'success' | 'warning' | 'error' | 'neutral';
+
+export interface TableProps extends Omit<MuiTableProps, 'variant'> {
+  /**
+   * The variant of the table
+   */
+  variant?: 'default' | 'striped' | 'glass' | 'minimal' | 'gradient';
+
+  /**
+   * The color for striped rows (only applies when variant is 'striped')
+   * @default 'neutral'
+   */
+  stripeColor?: TableStripeColor;
+
+  /**
+   * Whether the table should have a glow effect
+   */
+  glow?: boolean;
+  
+  /**
+   * Whether the table should have a pulse animation
+   */
+  pulse?: boolean;
+  
+  /**
+   * Whether table rows should be hoverable
+   */
+  hoverable?: boolean;
+  
+  /**
+   * Whether the table is in loading state
+   */
+  loading?: boolean;
+  
+  /**
+   * Handler for row click
+   */
+  onRowClick?: (event: React.MouseEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+  
+  /**
+   * Handler for row focus
+   */
+  onRowFocus?: (event: React.FocusEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+  
+  /**
+   * Handler for row blur
+   */
+  onRowBlur?: (event: React.FocusEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+
+  // Advanced Features
+  
+  /**
+   * The density of the table rows
+   */
+  density?: TableDensity;
+  
+  /**
+   * Whether the table header should be sticky during scroll
+   */
+  stickyHeader?: boolean;
+  
+  /**
+   * Row selection configuration
+   */
+  selectable?: boolean;
+  
+  /**
+   * Array of selected row keys
+   */
+  selectedRows?: (string | number)[];
+  
+  /**
+   * Callback when row selection changes
+   */
+  onSelectionChange?: (selectedRows: (string | number)[]) => void;
+  
+  /**
+   * Function to extract unique key from row data
+   */
+  rowKeyExtractor?: (rowData: Record<string, unknown>, index: number) => string | number;
+  
+  /**
+   * Whether columns are sortable
+   */
+  sortable?: boolean;
+  
+  /**
+   * Current sort configuration
+   */
+  sortConfig?: SortConfig;
+  
+  /**
+   * Callback when sort changes
+   */
+  onSortChange?: (key: string, direction: 'asc' | 'desc') => void;
+  
+  /**
+   * Whether columns are filterable
+   */
+  filterable?: boolean;
+  
+  /**
+   * Current filter configuration
+   */
+  filterConfig?: FilterConfig;
+  
+  /**
+   * Callback when filter changes
+   */
+  onFilterChange?: (filterConfig: FilterConfig) => void;
+  
+  /**
+   * Column configuration for advanced features
+   */
+  columns?: ColumnConfig[];
+  
+  /**
+   * Table data for advanced features
+   */
+  data?: Record<string, unknown>[];
+  
+  /**
+   * Whether to enable virtual scrolling for large datasets
+   */
+  virtualScrolling?: boolean;
+  
+  /**
+   * Height of each row for virtual scrolling (required if virtualScrolling is true)
+   */
+  rowHeight?: number;
+  
+  /**
+   * Number of items to render outside visible area for virtual scrolling
+   */
+  overscan?: number;
+  
+  /**
+   * Whether to enable responsive design features
+   */
+  responsive?: boolean;
+  
+  /**
+   * Priority order for columns in responsive mode (1 = highest priority)
+   */
+  columnPriorities?: number[];
+  
+  /**
+   * Custom breakpoints for responsive behavior
+   */
+  responsiveBreakpoints?: {
+    xs?: number; // pixel width
+    sm?: number;
+    md?: number;
+    lg?: number;
+  };
+  
+  /**
+   * Whether to show column toggle menu on mobile
+   */
+  showColumnToggle?: boolean;
+  
+  /**
+   * Container height for virtual scrolling
+   */
+  containerHeight?: number | string;
+  
+  /**
+   * Custom loading component
+   */
+  loadingComponent?: React.ReactNode;
+  
+  /**
+   * Custom empty state component
+   */
+  emptyStateComponent?: React.ReactNode;
+  
+  /**
+   * Whether to enable keyboard navigation
+   */
+  keyboardNavigation?: boolean;
+  
+  /**
+   * Custom row renderer for advanced use cases
+   */
+  renderRow?: (rowData: Record<string, unknown>, index: number, isSelected: boolean) => React.ReactNode;
+  
+  /**
+   * Custom cell renderer
+   */
+  renderCell?: (value: unknown, column: ColumnConfig, rowData: Record<string, unknown>, rowIndex: number) => React.ReactNode;
+  
+  /**
+   * Whether to enable row drag and drop
+   */
+  draggableRows?: boolean;
+  
+  /**
+   * Callback when rows are reordered
+   */
+  onRowsReorder?: (fromIndex: number, toIndex: number) => void;
+  
+  /**
+   * Fixed columns configuration
+   */
+  fixedColumns?: {
+    left?: number; // Number of columns to fix on the left
+    right?: number; // Number of columns to fix on the right
+  };
+  
+  /**
+   * Custom styling for different row states
+   */
+  rowStyleConfig?: {
+    selected?: React.CSSProperties;
+    hover?: React.CSSProperties;
+    focused?: React.CSSProperties;
+  };
+}
+
+// Export utility types
+export type TableSortDirection = 'asc' | 'desc';
+export type TableVariant = 'default' | 'striped' | 'glass' | 'minimal' | 'gradient';
+
+// Component prop interfaces for internal use
+export interface TableHeaderProps {
+  columns: ColumnConfig[];
+  data: Record<string, unknown>[];
+  sortable?: boolean;
+  sortConfig?: SortConfig;
+  onSortChange?: (key: string, direction: 'asc' | 'desc') => void;
+  selectable?: boolean;
+  selectedRows?: (string | number)[];
+  onSelectAll?: (selected: boolean) => void;
+  density?: TableDensity;
+  stickyHeader?: boolean;
+}
+
+export interface TableBodyProps {
+  data: Record<string, unknown>[];
+  columns: ColumnConfig[];
+  selectedRows?: (string | number)[];
+  onRowClick?: (event: React.MouseEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+  onRowFocus?: (event: React.FocusEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+  onRowBlur?: (event: React.FocusEvent<globalThis.HTMLTableRowElement>, rowData: Record<string, unknown>) => void;
+  onSelectionChange?: (rowKey: string | number, selected: boolean) => void;
+  rowKeyExtractor?: (rowData: Record<string, unknown>, index: number) => string | number;
+  density?: TableDensity;
+  selectable?: boolean;
+  hoverable?: boolean;
+  renderRow?: (rowData: Record<string, unknown>, index: number, isSelected: boolean) => React.ReactNode;
+  renderCell?: (value: unknown, column: ColumnConfig, rowData: Record<string, unknown>, rowIndex: number) => React.ReactNode;
+  virtualScrolling?: boolean;
+  containerHeight?: number;
+  rowHeight?: number;
+  overscan?: number;
+}
+
+export interface VirtualTableBodyProps extends TableBodyProps {
+  virtualScrolling: true;
+  containerHeight: number;
+  rowHeight: number;
+}
+
+export interface ResponsiveTableProps {
+  responsive: boolean;
+  columnPriorities?: number[];
+  responsiveBreakpoints?: {
+    xs?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+  };
+  showColumnToggle?: boolean;
+  columns: ColumnConfig[];
+  onColumnVisibilityChange?: (columnIndex: number, visible: boolean) => void;
+}

package/src/components/data-display/Table/index.ts

@@ -0,0 +1,2 @@
+export { Table } from './Table';
+export type { ColumnConfig, TableProps, TableStripeColor } from './Table.types';

package/src/components/data-display/Timeline/Timeline.md

@@ -0,0 +1,201 @@
+# Timeline Component
+
+A flexible and animated timeline component for displaying chronological events and milestones.
+
+## Features
+
+- **Multiple Variants**: Default, compact, and detailed display modes
+- **Orientation Support**: Vertical and horizontal timeline layouts
+- **Interactive Elements**: Expandable items with metadata and actions
+- **Animation Support**: Slide-in animations and pulsing indicators
+- **Customizable**: Custom icons, colors, and styling options
+- **Responsive**: Adapts to different screen sizes
+- **Accessible**: Full keyboard navigation and screen reader support
+
+## Usage
+
+```tsx
+import { Timeline } from '@/components/enhanced/Timeline';
+
+const items = [
+  {
+    id: '1',
+    title: 'Project Started',
+    description: 'Initial project setup and planning phase',
+    timestamp: '2 hours ago',
+    icon: <StartIcon />,
+    color: '#4CAF50',
+    metadata: { status: 'completed', duration: '1 week' },
+    action: { label: 'View Details', onClick: () => {} },
+  },
+  {
+    id: '2',
+    title: 'Development Phase',
+    description: 'Core functionality implementation',
+    timestamp: '1 hour ago',
+    color: '#2196F3',
+  },
+];
+
+<Timeline
+  items={items}
+  variant="default"
+  orientation="vertical"
+  animated={true}
+  showConnector={true}
+  onItemClick={(item) => console.log(item)}
+/>;
+```
+
+## Props
+
+### TimelineProps
+
+| Prop          | Type                                   | Default      | Description                              |
+| ------------- | -------------------------------------- | ------------ | ---------------------------------------- |
+| items         | `TimelineItem[]`                       | -            | Array of timeline items to display       |
+| variant       | `'default' \| 'compact' \| 'detailed'` | `'default'`  | Display variant                          |
+| orientation   | `'vertical' \| 'horizontal'`           | `'vertical'` | Timeline orientation                     |
+| showConnector | `boolean`                              | `true`       | Show connecting lines between items      |
+| animated      | `boolean`                              | `true`       | Enable slide-in animations               |
+| alternating   | `boolean`                              | `false`      | Alternate item positions (vertical only) |
+| onItemClick   | `(item: TimelineItem) => void`         | -            | Callback when item is clicked            |
+
+### TimelineItem
+
+| Prop        | Type                                   | Required | Description                       |
+| ----------- | -------------------------------------- | -------- | --------------------------------- |
+| id          | `string`                               | ✓        | Unique identifier for the item    |
+| title       | `string`                               | ✓        | Main title text                   |
+| description | `string`                               | -        | Detailed description              |
+| timestamp   | `string`                               | ✓        | Time/date display text            |
+| icon        | `React.ReactNode`                      | -        | Custom icon component             |
+| color       | `string`                               | -        | Custom color for the timeline dot |
+| action      | `{label: string, onClick: () => void}` | -        | Action button configuration       |
+| expanded    | `boolean`                              | -        | Initial expanded state            |
+| metadata    | `Record<string, string>`               | -        | Key-value metadata pairs          |
+
+## Variants
+
+### Default
+
+Standard timeline with expandable items and full feature set.
+
+### Compact
+
+Minimal design with condensed spacing and always-visible descriptions.
+
+### Detailed
+
+Expanded view with all details visible by default.
+
+## Accessibility
+
+- Full keyboard navigation support
+- Screen reader compatible with proper ARIA attributes
+- Focus management for interactive elements
+- Semantic HTML structure
+
+## Examples
+
+### Basic Timeline
+
+```tsx
+<Timeline items={basicItems} />
+```
+
+### Horizontal Timeline
+
+```tsx
+<Timeline items={items} orientation="horizontal" variant="compact" />
+```
+
+### Alternating Timeline
+
+```tsx
+<Timeline items={items} alternating={true} animated={true} />
+```
+
+## Testing
+
+### Test IDs
+
+The Timeline component includes `data-testid` attributes for reliable testing:
+
+| Test ID | Element | Description |
+|---------|---------|-------------|
+| `timeline-container` | Main container | Root Box element wrapping all timeline items |
+| `timeline-item-container` | Item wrapper | Container for each timeline item (one per item) |
+| `timeline-dot` | Timeline dot | Circular dot/icon container for each item |
+| `item-icon` | Custom icon | Box wrapper around custom icon (when provided) |
+| `item-icon-default` | Default icon | Default Circle icon (when no custom icon) |
+| `timeline-connector` | Connector line | Line connecting dots between items |
+| `timeline-card` | Content card | Card containing item title, description, metadata |
+| `timeline-timestamp` | Timestamp | Timestamp display element |
+
+### Testing Best Practices
+
+**Wait for Timeline to Render:**
+```typescript
+// Use async queries to wait for elements
+const container = await canvas.findByTestId('timeline-container');
+expect(container).toBeInTheDocument();
+
+// Wait for all items
+await waitFor(async () => {
+  const items = await canvas.findAllByTestId('timeline-item-container');
+  expect(items).toHaveLength(expectedCount);
+}, { timeout: 3000 });
+```
+
+**Test Icon Rendering:**
+```typescript
+const dots = await canvas.findAllByTestId('timeline-dot');
+
+for (const dot of dots) {
+  // Check for either custom or default icon
+  const icon = await within(dot).findByTestId(/item-icon/);
+  expect(icon).toBeInTheDocument();
+}
+```
+
+**Test Interactions:**
+```typescript
+// Click timeline card
+const cards = await canvas.findAllByRole('article');
+await userEvent.click(cards[0]);
+expect(onItemClick).toHaveBeenCalledWith(expectedItem);
+
+// Expand/collapse items
+const expandButtons = canvasElement.querySelectorAll('button');
+const expandBtn = Array.from(expandButtons).find(
+  btn => btn.querySelector('svg[data-testid="ExpandMoreIcon"]')
+);
+await userEvent.click(expandBtn);
+
+await waitFor(() => {
+  const description = canvas.getByText(expectedDescription);
+  expect(description).toBeVisible();
+}, { timeout: 3000 });
+```
+
+**Test Animations:**
+```typescript
+// When animated=true, items have slide-in animation
+const items = await canvas.findAllByTestId('timeline-item-container');
+for (const item of items) {
+  const style = window.getComputedStyle(item);
+  expect(style.animation).not.toBe('none');
+}
+```
+
+### Common Test Scenarios
+
+1. **Basic Rendering** - Verify container and all items render
+2. **Icon Display** - Check custom icons vs default icons
+3. **Orientation** - Test vertical vs horizontal layouts
+4. **Variants** - Test default, compact, and detailed variants
+5. **Interactions** - Test click handlers and expand/collapse
+6. **Animations** - Verify animations when enabled
+7. **Responsive** - Test mobile/tablet viewports
+8. **Accessibility** - Verify ARIA attributes and keyboard navigation