ms-time-sheet 0.0.5 → 0.0.7

package/README.md

@@ -1,24 +1,428 @@
-# MsTimeSheet
+# MS Time Sheet Component
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 18.2.0.
+A powerful, high-performance Angular data grid component specifically designed for time sheet management and attendance tracking systems. Built with Angular 18+ and optimized for handling large datasets with advanced features like virtual scrolling, infinite scroll, drag-and-drop column management, and comprehensive filtering capabilities.
 
-## Code scaffolding
+## Features
 
-Run `ng generate component component-name --project ms-time-sheet` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project ms-time-sheet`.
-> Note: Don't forget to add `--project ms-time-sheet` or else it will be added to the default project in your `angular.json` file. 
+### Core Functionality
+- **Advanced Data Grid**: Full-featured table component with customizable columns, rows, and cell types
+- **Time Sheet Management**: Specialized for attendance, clock-in/out, breaks, and manual log tracking
+- **Virtual Scrolling**: Efficiently handles thousands of rows with smooth scrolling performance
+- **Infinite Scroll**: Load data progressively as users scroll for better performance with large datasets
 
-## Build
+### User Interactions
+- **Drag & Drop**: Reorder columns, pin/unpin columns, group data by dragging
+- **Column Management**: Show/hide columns, resize columns, autosize columns, column grouping
+- **Advanced Filtering**: Multi-condition filtering with dropdown, text, date, number filters, and logical operators (AND/OR/NONE)
+- **Sorting**: Ascending/descending sort with multi-column support and custom sort fields
+- **Row Selection**: Single and multi-row selection with taskbar actions and bulk operations
+- **Accordion Details**: Expandable row details with nested tables and manual log tracking
+- **Copy/Paste Operations**: Advanced clipboard functionality with cell-level and row-level copy/paste
+- **Cut Operations**: Cut selected data with visual feedback animations
+- **Cell Editing**: Inline editing with validation and change detection
+- **Context Menus**: Right-click context menus with customizable actions
+- **Tooltips**: Rich tooltips for breaks, manual logs, and status information
+- **Modal Dialogs**: Manual logs modal, column chooser, table presets, and filter panels
 
-Run `ng build ms-time-sheet` to build the project. The build artifacts will be stored in the `dist/` directory.
+### Performance Optimizations
+- **Virtual Scrolling**: Efficiently handles thousands of rows with smooth scrolling performance and dynamic item heights
+- **Infinite Scroll**: Load data progressively as users scroll for better performance with large datasets, including prefetching
+- **Advanced Caching**: DOM query caching, computation caching, service worker support, and template expression memoization
+- **Memory Management**: Automatic cleanup of event listeners, timers, component references, and WeakRef-based cleanup
+- **Lazy Loading**: Modules loaded on-demand based on feature usage with progressive hydration
+- **Advanced DOM Optimization**: DOM query caching with TTL, LRU eviction, and optimized element selection
+- **Zone.js Optimizations**: Batched microtasks for ultra-fast change detection
+- **Performance Profiling**: Built-in performance metrics and optimization suggestions
+- **Worker-based Computations**: Heavy filtering operations moved to web workers
 
-## Publishing
+### UI/UX Features
+- **Responsive Design**: Adapts to different screen sizes and layouts
+- **Themes & Styling**: Customizable colors, fonts, and visual themes
+- **Tooltips & Modals**: Rich tooltips for breaks, manual logs modal, and context menus
+- **Export Functionality**: Export selected data or entire datasets
+- **Presets**: Save and load table configurations and filter states
 
-After building your library with `ng build ms-time-sheet`, go to the dist folder `cd dist/ms-time-sheet` and run `npm publish`.
+### Data Types Supported
+- Text/String fields
+- Numbers
+- Dates with custom formatting
+- Booleans with badge display
+- Status fields with color coding
+- Arrays with item counts
+- Images with fallback avatars
+- Custom cell templates
 
-## Running unit tests
+## Installation
 
-Run `ng test ms-time-sheet` to execute the unit tests via [Karma](https://karma-runner.github.io).
+### As an Angular Library
 
-## Further help
+1. Install the library:
+```bash
+npm install ms-time-sheet
+```
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+2. Import the module in your Angular application:
+```typescript
+import { TimeSheetComponent } from 'ms-time-sheet';
+
+@NgModule({
+  imports: [
+    // ... other imports
+    TimeSheetComponent
+  ]
+})
+export class AppModule { }
+```
+
+### Development Setup
+
+1. Clone the repository
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the library:
+```bash
+ng build ms-time-sheet
+```
+
+4. Run tests:
+```bash
+ng test ms-time-sheet
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<time-sheet
+  [dataSet]="timeSheetData"
+  [columns]="columnDefinitions"
+  [config]="paginationConfig"
+  (filterOptions)="onFilterChange($event)"
+  (sortingOrderOptions)="onSortChange($event)">
+</time-sheet>
+```
+
+### Advanced Configuration
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-time-sheet-demo',
+  template: `
+    <time-sheet
+      [dataSet]="attendanceData"
+      [columns]="columns"
+      [config]="config"
+      [filtersConfig]="filters"
+      [paginationConfig]="pagination"
+      [showFilterRow]="true"
+      [showColumnsGrouping]="true"
+      [enableInfiniteScroll]="true"
+      [enableProgressiveLoading]="true"
+      [rowHeight]="44"
+      [headerRowHeight]="44"
+      [showVerticalBorder]="true"
+      [showSerialNumber]="true"
+      [tableName]="'attendance'"
+      [selectedTableLayout]="'medium'"
+      [globalSearchText]="searchText"
+      [actions]="['edit', 'delete', 'export']"
+      [taskbarActions]="['Export', 'Delete']"
+      [showTaskbar]="true"
+      [showSideMenu]="true"
+      [columnThreedotsMunuConfig]="menuConfig"
+      [timezonePrefs]="timezoneSettings"
+      [gridType]="'TimeSheet'"
+      [isSingleDay]="false"
+      [dateFormat]="'dd/MM/yyyy'"
+      [tableSearch]="tableSearch"
+      [loading]="isLoading"
+      [verticalScrollbarWidth]="'auto'"
+      [horizintalScrollbarWidth]="'auto'"
+      [showCellDetailsBox]="true"
+      [fontFaimly]="'sans-serif'"
+      [showRowsGrouping]="false"
+      [showFilterRow]="true"
+      [footerRowHeight]="46"
+      [topFilterRowHeight]="50"
+      [rowShadingEnabled]="false"
+      [singleSpaAssetsPath]="'assets/'"
+      [filtersConfig]="activeFilters"
+      [loading]="false"
+      [actions]="contextMenuActions"
+      [config]="tableConfig"
+      [showTaskbar]="true"
+      [tableName]="'timeSheet'"
+      [listingType]="''"
+      [checkboxState]="{ reset: false }"
+      [taskbarActions]="['Export', 'Delete']"
+      [sortingConfig]="currentSorting"
+      [tableFilterViewId]="currentViewId"
+      [selectedTableLayout]="'medium'"
+      [closeDropdown]="{ preset: { closed: false, loading: false } }"
+      [globalSearchText]="globalSearch"
+      [nestedTablerowFontsize]="14"
+      [nestedTableHeaderRowHeight]="40"
+      [nestedTablerowHeight]="36"
+      [gridType]="'TimeSheet'"
+      [isSingleDay]="false"
+      [leftPinnedBoxshadow]="'#4b4b4b 1px 1px 5px 0px'"
+      [rightPinnedBoxshadow]="'#4b4b4b 4px 1px 6px 0px'"
+      [enableAccordionShadow]="false"
+      [enableAccordionSeparators]="false"
+      [enableRowShading]="false"
+      [selectedRowsBackgroundColor]="'#8ac5ff'"
+      [nestedTableHeaderBAckgroundColor]="'#eaeaea'"
+      [tableView]="savedViews"
+      [columnThreedotsMunuConfig]="columnMenuConfig"
+      [timezonePrefs]="timezonePreferences"
+      [enableProgressiveLoading]="true"
+      [progressiveChunkSize]="100"
+      [progressiveDelay]="50"
+      [enableInfiniteScroll]="true"
+      [hasMoreData]="hasMorePages"
+      [loadingMore]="loadingMoreData"
+      (loadMoreData)="loadMore()"
+      (changeLayout)="onLayoutChange($event)"
+      (filterOptions)="onFilterApply($event)"
+      (genericEvent)="onGenericEvent($event)"
+      (tablePresetConfig)="onPresetConfig($event)"
+      (sortingOrderOptions)="onSortingChange($event)"
+      (createUpdateConfigListing)="onConfigUpdate($event)"
+      (onShortBreakClick)="onShortBreakClick($event)"
+      (searchEvent)="onSearch($event)">
+    </time-sheet>
+  `
+})
+export class TimeSheetDemoComponent {
+  // Component logic here
+}
+```
+
+## API Reference
+
+### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dataSet` | `any[]` | `[]` | Array of data objects to display |
+| `columns` | `any[]` | `[]` | Column definitions with field, header, type, etc. |
+| `config` | `any` | `{}` | Table configuration including pagination |
+| `filtersConfig` | `any[]` | `[]` | Active filter configurations |
+| `paginationConfig` | `any` | `{}` | Pagination settings |
+| `rowHeight` | `number` | `44` | Height of data rows in pixels |
+| `headerRowHeight` | `number` | `44` | Height of header rows in pixels |
+| `showVerticalBorder` | `boolean` | `true` | Show vertical borders between columns |
+| `showSerialNumber` | `boolean` | `false` | Display row serial numbers |
+| `showFilterRow` | `boolean` | `false` | Show filter row below headers |
+| `showColumnsGrouping` | `boolean` | `false` | Enable column grouping functionality |
+| `showRowsGrouping` | `boolean` | `false` | Enable row grouping |
+| `showSideMenu` | `boolean` | `false` | Show side menu for column management |
+| `enableInfiniteScroll` | `boolean` | `false` | Enable infinite scrolling |
+| `enableProgressiveLoading` | `boolean` | `false` | Enable progressive data loading |
+| `loading` | `boolean` | `false` | Show loading state |
+| `tableName` | `string` | `''` | Unique identifier for table state management |
+| `selectedTableLayout` | `string` | `'medium'` | Layout size: 'small', 'medium', 'large' |
+| `globalSearchText` | `string` | `''` | Global search text |
+| `actions` | `any[]` | `[]` | Context menu actions |
+| `taskbarActions` | `any[]` | `[]` | Actions for selected rows taskbar |
+| `showTaskbar` | `boolean` | `false` | Show taskbar for selected rows |
+| `dateFormat` | `string` | `'dd/MM/yyyy'` | Date display format |
+| `fontFaimly` | `string` | `'sans-serif'` | Font family for the table |
+| `singleSpaAssetsPath` | `string` | `'assets/'` | Path to static assets |
+| `gridType` | `string` | `'TimeSheet'` | Type of grid for styling |
+| `isSingleDay` | `boolean` | `false` | Single day view mode |
+| `timezonePrefs` | `any` | `{}` | Timezone preferences |
+| `columnThreedotsMunuConfig` | `any` | `{}` | Configuration for column menu |
+
+### Outputs
+
+| Output | Description |
+|--------|-------------|
+| `filterOptions` | Emitted when filters are applied |
+| `sortingOrderOptions` | Emitted when sorting changes |
+| `genericEvent` | Generic event emitter for various actions |
+| `tablePresetConfig` | Emitted for preset configuration changes |
+| `createUpdateConfigListing` | Emitted when column configuration updates |
+| `changeLayout` | Emitted when layout changes |
+| `loadMoreData` | Emitted when more data is needed (infinite scroll) |
+| `onShortBreakClick` | Emitted when short break is clicked |
+| `searchEvent` | Emitted for search events |
+
+### Column Definition Structure
+
+```typescript
+interface Column {
+  field: string;           // Data field name
+  header: string;          // Display header
+  type: 'string' | 'number' | 'date' | 'boolean' | 'status' | 'array' | 'image';
+  width?: number;          // Column width
+  is_visible?: boolean;    // Visibility state
+  is_sortable?: boolean;   // Sortable flag
+  is_groupable?: boolean;  // Groupable flag
+  pinned?: 'left' | 'right' | null; // Pin position
+  children?: Column[];     // Child columns for grouping
+  query?: any;            // Filter query configuration
+  // ... additional properties
+}
+```
+
+## Data Structure
+
+The component expects data in the following format for time sheet functionality:
+
+```typescript
+interface TimeSheetRow {
+  _id?: string;
+  id?: string;
+  User?: {
+    full_name: string;
+    profile_pictures?: Array<{ path: string }>;
+    logo?: string;
+  };
+  attendanceDate: string;
+  clock_in_time?: string;
+  clock_out_time?: string;
+  attendanceStatus: string;
+  breaks?: Array<{
+    break_duration: number;
+    type: string;
+  }>;
+  manually_logs?: Array<{
+    log_date: string;
+    clock_in?: {
+      time: string;
+      status: string;
+      previous_state: string;
+    };
+    clock_out?: {
+      time: string;
+      status: string;
+      previous_state: string;
+    };
+    breaks?: any[];
+    remarks?: string;
+    updated_by?: {
+      full_name: string;
+    };
+  }>;
+  short_leave?: Array<{
+    // Short leave details
+  }>;
+  // ... additional fields
+}
+```
+
+## Styling and Theming
+
+The component supports extensive customization through input properties:
+
+- Row colors (even/odd, hover, selected)
+- Header and body colors
+- Font sizes and weights
+- Border styles and shadows
+- Pinned column shadows
+
+## Performance Considerations
+
+- **Virtual Scrolling**: Enabled by default for datasets > 1000 rows with adaptive overscan and dynamic item heights
+- **Progressive Loading**: Load data in chunks to prevent UI blocking with configurable chunk sizes and delays
+- **DOM Caching**: Intelligent caching of DOM queries and computations with TTL and LRU eviction
+- **Memory Management**: Automatic cleanup of resources with WeakRef registry and advanced cleanup patterns
+- **Lazy Loading**: Modules loaded on-demand with progressive hydration for better initial load performance
+- **Worker Computations**: Heavy operations like filtering moved to web workers to prevent UI blocking
+- **Performance Monitoring**: Built-in profiling with thresholds and optimization suggestions
+
+## Browser Support
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Dependencies
+
+- Angular 18.2.0+
+- Angular CDK (for drag-drop, scrolling, virtual scrolling)
+- ngx-bootstrap (for datepickers and UI components)
+- ng-inline-svg (for SVG icon support)
+- moment.js (for date manipulation)
+- tslib (TypeScript runtime helpers)
+
+## Services and Pipes
+
+### Included Services
+- **CommonService**: Utility functions for column visibility, filtering, and data manipulation
+- **SplitColumnsService**: Handles column splitting and width calculations
+- **CopyServiceService**: Advanced clipboard operations with copy/paste/cut functionality
+- **MsTimeSheetService**: Main service for time sheet operations
+
+### Included Pipes
+- **FilterPipe**: Generic filtering pipe for arrays with search functionality
+- **PinnedColumnsPipe**: Filters columns by pinned state (left/right/center)
+
+## Status Badge System
+
+The component includes a comprehensive status badge system with predefined color mappings:
+
+```typescript
+// Success (Green)
+'active', 'approved', 'accepted', 'completed', 'evaluated', 'assigned', 'scrap', 'move-available', 'move-assigned', 'present'
+
+// Warning (Yellow)
+'contract', 'warranty', 'scheduled', 'leased', 'disposed', 'maintenance', 'assigning start', 'evaluation start', 'to be start assigning', 'pending', 'leave'
+
+// Danger (Red)
+'inactive', 'rejected', 'unassigned', 'trashed', 'onhold', 'assigning stop', 'evaluation stop', 'unavailable', 'move-error', 'failed', 'absent'
+
+// Info (Blue)
+'insurance', 'pastdue'
+
+// Dark (Neutral)
+'expired', 'draft'
+```
+
+## Advanced Features
+
+### Copy/Paste Operations
+- **Cell-level Copy**: Copy individual cells or ranges
+- **Row-level Copy**: Copy entire selected rows
+- **Paste Support**: Paste data with automatic type conversion
+- **Cut Operations**: Cut data with visual feedback animations
+
+### Change Detection
+- **Field-level Change Detection**: Tracks changes by field type (string, number, date, boolean, dropdown)
+- **Dirty State Management**: Maintains original vs current values
+- **Validation**: Built-in validation for different data types
+
+### Keyboard Navigation
+- **Arrow Keys**: Navigate between cells
+- **Enter/Escape**: Confirm/cancel edits
+- **Tab**: Move to next cell
+- **Copy/Paste Shortcuts**: Standard Ctrl+C/Ctrl+V support
+
+### Export Functionality
+- **Selected Rows Export**: Export only selected data
+- **Filtered Data Export**: Export current filtered view
+- **Custom Export**: Configurable export formats
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+For support and questions, please open an issue on the GitHub repository.