@one-paragon/angular-utilities 2.8.3 → 2.8.4

package/src/table-builder/documentation/table-builder/STYLER-STYLE.md

@@ -0,0 +1,228 @@
+# StylerStyle Documentation
+
+## Overview
+
+`StylerStyle<T>` is a flexible type for applying dynamic inline CSS styles based on row data. It allows you to conditionally apply styles to table cells, rows, or column parts.
+
+## Type Definition
+
+```typescript
+type StylerStyle<T = any> = Dictionary<
+  string | {
+    condition?: ((t: T) => boolean) | true,
+    value: ((t: T) => string) | string
+  }
+>
+```
+
+Where `Dictionary<T>` is equivalent to `{ [key: string]: T }`.
+
+## Usage Patterns
+
+### Simple Static Styles
+
+Apply a static CSS value directly:
+
+```typescript
+const styles: StylerStyle = {
+  'color': 'red',
+  'font-weight': 'bold',
+  'background-color': '#f0f0f0'
+};
+```
+
+### Dynamic Styles Based on Data
+
+Compute style values from the row data:
+
+```typescript
+const styles: StylerStyle<User> = {
+  'color': (user) => user.isActive ? 'green' : 'gray',
+  'font-size': (user) => user.isPriority ? '16px' : '14px',
+  'opacity': (user) => user.status === 'archived' ? '0.5' : '1'
+};
+```
+
+### Conditional Styles with Static Values
+
+Apply a static style only when a condition is met:
+
+```typescript
+const styles: StylerStyle<User> = {
+  'background-color': {
+    condition: (user) => user.isWarning,
+    value: '#fff3cd'
+  },
+  'border-left': {
+    condition: (user) => user.isPriority,
+    value: '4px solid #dc3545'
+  }
+};
+```
+
+### Conditional Styles with Dynamic Values
+
+Apply a computed style only when a condition is met:
+
+```typescript
+const styles: StylerStyle<User> = {
+  'background-color': {
+    condition: (user) => user.score !== null,
+    value: (user) => user.score > 80 ? '#d4edda' : '#f8d7da'
+  },
+  'font-weight': {
+    condition: (user) => user.role === 'admin',
+    value: (user) => user.isActive ? 'bold' : 'normal'
+  }
+};
+```
+
+### Always-Applied Conditional Styles
+
+Use `condition: true` to always evaluate the value function:
+
+```typescript
+const styles: StylerStyle<User> = {
+  'color': {
+    condition: true,
+    value: (user) => {
+      if (user.status === 'error') return '#dc3545';
+      if (user.status === 'warning') return '#ffc107';
+      if (user.status === 'success') return '#28a745';
+      return 'inherit';
+    }
+  }
+};
+```
+
+## Common Use Cases
+
+### Row-Level Styling
+
+Apply styles to entire table rows based on row data:
+
+```typescript
+tableSettings: {
+  rowStyles: {
+    'background-color': (row) => row.isSelected ? '#e3f2fd' : 'transparent',
+    'opacity': (row) => row.isDeleted ? '0.5' : '1',
+    'cursor': 'pointer'
+  }
+}
+```
+
+### Cell-Level Styling
+
+Apply styles to individual cells in a column:
+
+```typescript
+{
+  key: 'amount',
+  fieldType: FieldType.Currency,
+  additional: {
+    styles: {
+      'color': (row) => row.amount < 0 ? 'red' : 'green',
+      'font-weight': (row) => Math.abs(row.amount) > 1000 ? 'bold' : 'normal'
+    }
+  }
+}
+```
+
+### Column Part Styling
+
+Apply styles to specific parts of a column:
+
+```typescript
+{
+  key: 'status',
+  fieldType: FieldType.String,
+  additional: {
+    columnPartStyles: {
+      header: {
+        'background-color': '#f5f5f5',
+        'font-weight': 'bold'
+      },
+      body: (row) => ({
+        'color': row.status === 'active' ? 'green' : 'red',
+        'text-transform': 'uppercase'
+      }),
+      footer: {
+        'background-color': '#e0e0e0',
+        'font-style': 'italic'
+      }
+    }
+  }
+}
+```
+
+### Complex Conditional Logic
+
+Combine multiple conditions for sophisticated styling:
+
+```typescript
+const styles: StylerStyle<Order> = {
+  'background-color': {
+    condition: (order) => order.isPriority || order.isUrgent,
+    value: (order) => {
+      if (order.isUrgent) return '#ffebee';
+      if (order.isPriority) return '#fff9c4';
+      return 'transparent';
+    }
+  },
+  'border-left': {
+    condition: (order) => order.daysOverdue > 0,
+    value: (order) => {
+      const width = Math.min(order.daysOverdue, 5);
+      return `${width}px solid #f44336`;
+    }
+  },
+  'font-weight': {
+    condition: (order) => order.value > 10000,
+    value: 'bold'
+  }
+};
+```
+
+## Style Properties
+
+Any valid CSS property can be used as a key. Common properties include:
+
+- **Colors**: `color`, `background-color`, `border-color`
+- **Typography**: `font-size`, `font-weight`, `font-style`, `text-align`, `text-transform`
+- **Spacing**: `padding`, `margin`, `padding-left`, `margin-top`
+- **Borders**: `border`, `border-left`, `border-width`, `border-style`
+- **Layout**: `display`, `width`, `height`, `min-width`, `max-width`
+- **Visual Effects**: `opacity`, `box-shadow`, `transform`
+- **Interaction**: `cursor`, `pointer-events`
+
+**Note**: Use camelCase for multi-word CSS properties (e.g., `backgroundColor`) or string literals (e.g., `'background-color'`).
+
+## Performance Considerations
+
+- **Memoization**: Style functions are evaluated on every change detection cycle. Keep them simple and avoid expensive computations.
+- **Condition First**: When using the object form, the `condition` is evaluated before the `value`, allowing you to skip expensive value calculations when not needed.
+- **Static Styles**: Prefer static string values when styles don't depend on data.
+
+## Type Safety
+
+When using TypeScript, the generic type `T` provides type safety for your row data:
+
+```typescript
+interface Product {
+  id: number;
+  name: string;
+  stock: number;
+  price: number;
+}
+
+const productStyles: StylerStyle<Product> = {
+  'color': (product) => product.stock < 10 ? 'red' : 'black',
+  // TypeScript will provide autocomplete for 'product' properties
+  'font-weight': (product) => product.price > 100 ? 'bold' : 'normal'
+};
+```
+
+## Related Documentation
+
+- [MetaData Configuration](./METADATA-DOCUMENTATION.md#styling-configuration) - How to use `StylerStyle` with column metadata
+- [Table Builder Settings](./TABLE-BUILDER-SETTINGS.md#table-settings) - How to use `StylerStyle` for row-level styling

package/src/table-builder/documentation/table-builder/TABLE-BUILDER-CONFIG.md

@@ -0,0 +1,325 @@
+# TableBuilderConfig Documentation
+
+## Overview
+
+`TableBuilderConfig` allows you to set global default settings for all Table Builder instances in your application. These defaults can be overridden at the component level when needed.
+
+## Usage
+
+### Global Configuration (Application-Wide)
+
+Use `provideTableBuilder` in your application configuration to set defaults for all tables:
+
+```typescript
+// In app.config.ts or main.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideTableBuilder } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideTableBuilder({
+      defaultTableSettings: {
+        pageSize: 25,
+        headerSettings: {
+          showTitleWhenCollapsed: true
+        },
+        tableSettings: {
+          usePaginator: true,
+          exportSettings: {
+            dateFormat: 'MM/dd/yyyy',
+            mapEnumToString: true
+          }
+        }
+      },
+      dateFormats: {
+        dateFormat: 'MM/dd/yyyy',
+        dateTimeFormat: 'MM/dd/yyyy HH:mm:ss'
+      },
+      arrayDefaults: {
+        limit: 5,
+        arrayStyle: ArrayStyle.CommaDelimited
+      }
+    })
+  ]
+};
+```
+
+### Component-Level Configuration
+
+You can also provide `TableBuilderConfig` at the component level to set defaults for tables within that component and its children:
+
+```typescript
+import { Component } from '@angular/core';
+import { provideTableBuilder } from 'angular-utilities';
+
+@Component({
+  selector: 'app-users-table',
+  template: `...`,
+  providers: [
+    provideTableBuilder({
+      defaultTableSettings: {
+        pageSize: 50,
+        tableSettings: {
+          includeSelectionColumn: true
+        }
+      }
+    })
+  ]
+})
+export class UsersTableComponent { }
+```
+
+---
+
+## TableBuilderConfig Properties
+
+### `defaultTableSettings`
+
+- **Type**: `Partial<TableBuilderSettings> & { pageSize?: number }`
+- **Description**: Default settings that will be applied to all tables. These can be overridden at the individual table level.
+- **See**: [TableBuilderSettings Documentation](./TABLE-BUILDER-SETTINGS.md) for detailed information about all available settings.
+
+**Example**:
+```typescript
+defaultTableSettings: {
+  pageSize: 25,
+  headerSettings: {
+    hideExport: false,
+    showTitleWhenCollapsed: true
+  },
+  columnHeaderSettings: {
+    stickyHeaderRow: true
+  },
+  tableSettings: {
+    usePaginator: true,
+    useVirtualScroll: false,
+    trackBy: 'id'
+  }
+}
+```
+
+### `export` ⚠️ **Deprecated**
+
+- **Type**: `TableBuilderExport | undefined`
+- **Deprecated**: Use `defaultTableSettings.tableSettings.exportSettings` instead.
+- **Description**: Legacy global export settings.
+- **See**: [MetaData Documentation - Export Configuration](./METADATA-DOCUMENTATION.md#export-configuration) for details on export options.
+
+### `dateFormats`
+
+- **Type**: `DefaultSettings | undefined`
+- **Description**: Default date and datetime formats applied to all Date and DateTime columns unless overridden at the column level.
+
+**Interface**:
+```typescript
+interface DefaultSettings {
+  dateFormat?: string;
+  dateTimeFormat?: string;
+}
+```
+
+**Properties**:
+- **`dateFormat`**: Default format for `FieldType.Date` columns (e.g., `'MM/dd/yyyy'`)
+- **`dateTimeFormat`**: Default format for `FieldType.DateTime` columns (e.g., `'MM/dd/yyyy HH:mm:ss'`)
+
+**Example**:
+```typescript
+dateFormats: {
+  dateFormat: 'dd/MM/yyyy',
+  dateTimeFormat: 'dd/MM/yyyy HH:mm:ss'
+}
+```
+
+### `arrayDefaults`
+
+- **Type**: `ArrayAdditional | undefined`
+- **Description**: Default settings for how array-type columns are displayed.
+- **See**: [MetaData Documentation - Array Types](./METADATA-DOCUMENTATION.md#array-types) for more details on array configuration.
+
+**Properties**:
+- **`limit`**: Maximum number of array items to display (default: `3`)
+- **`arrayStyle`**: How to display array items
+  - `ArrayStyle.CommaDelimited` (default): Items separated by commas
+  - `ArrayStyle.NewLine`: Each item on a new line
+
+**Example**:
+```typescript
+arrayDefaults: {
+  limit: 5,
+  arrayStyle: ArrayStyle.NewLine
+}
+```
+
+### `transformers`
+
+- **Type**: `Partial<{ [key in keyof typeof FieldType]: (val: any) => any }> | undefined`
+- **Description**: Global transformation functions for specific field types. These are applied to values before display, allowing you to customize how data is rendered for each field type across all tables.
+
+**Example**:
+```typescript
+transformers: {
+  [FieldType.Currency]: (val: number) => {
+    // Add custom currency symbol
+    return val != null ? `$${val.toFixed(2)}` : '';
+  },
+  [FieldType.PhoneNumber]: (val: string) => {
+    // Format phone numbers
+    if (!val) return '';
+    const cleaned = val.replace(/\D/g, '');
+    return `(${cleaned.slice(0, 3)}) ${cleaned.slice(3, 6)}-${cleaned.slice(6)}`;
+  },
+  [FieldType.Boolean]: (val: boolean) => {
+    return val ? 'Yes' : 'No';
+  }
+}
+```
+
+**Available FieldTypes**:
+- `FieldType.String`
+- `FieldType.Number`
+- `FieldType.Boolean`
+- `FieldType.Date`
+- `FieldType.DateTime`
+- `FieldType.Currency`
+- `FieldType.PhoneNumber`
+- `FieldType.Enum`
+- `FieldType.Array`
+- `FieldType.ImageUrl`
+- And more...
+
+---
+
+## Configuration Precedence
+
+Settings are applied in the following order (later sources override earlier ones):
+
+1. **Global Config** (via `provideTableBuilder` at app level)
+2. **Component Config** (via `provideTableBuilder` in component providers)
+3. **Table-Specific Settings** (passed directly to the table component)
+4. **Column-Specific Settings** (defined in MetaData for individual columns)
+
+**Example**:
+```typescript
+// 1. Global default (applies to all tables)
+provideTableBuilder({
+  defaultTableSettings: { pageSize: 10 }
+})
+
+// 2. Component-level default (applies to tables in this component)
+@Component({
+  providers: [
+    provideTableBuilder({
+      defaultTableSettings: { pageSize: 25 }  // Overrides global
+    })
+  ]
+})
+
+// 3. Table-specific setting
+const tableSettings: TableBuilderSettings = {
+  tableSettings: {
+    paginatorSettings: { pageSize: 50 }  // Overrides component-level
+  }
+};
+```
+
+---
+
+## Default Configuration
+
+If no configuration is provided, Table Builder uses these defaults:
+
+```typescript
+const defaultConfig: TableBuilderConfig = {
+  defaultTableSettings: {
+    pageSize: 10
+  },
+  arrayDefaults: {
+    limit: 3,
+    arrayStyle: ArrayStyle.CommaDelimited
+  }
+};
+```
+
+---
+
+## Complete Example
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideTableBuilder, ArrayStyle, FieldType } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideTableBuilder({
+      // Default table settings applied to all tables
+      defaultTableSettings: {
+        pageSize: 25,
+        
+        headerSettings: {
+          showTitleWhenCollapsed: true,
+          hideExport: false
+        },
+        
+        columnHeaderSettings: {
+          stickyHeaderRow: true,
+          noFilters: false
+        },
+        
+        tableSettings: {
+          usePaginator: true,
+          useVirtualScroll: false,
+          trackBy: 'id',
+          
+          exportSettings: {
+            dateFormat: 'MM/dd/yyyy',
+            dateTimeFormat: 'MM/dd/yyyy HH:mm:ss',
+            mapEnumToString: true,
+            mapLink: 'as view'
+          },
+          
+          rowClasses: {
+            'hover-highlight': true
+          }
+        }
+      },
+      
+      // Global date formats
+      dateFormats: {
+        dateFormat: 'MM/dd/yyyy',
+        dateTimeFormat: 'MM/dd/yyyy HH:mm:ss'
+      },
+      
+      // Array display defaults
+      arrayDefaults: {
+        limit: 5,
+        arrayStyle: ArrayStyle.CommaDelimited
+      },
+      
+      // Global transformers for field types
+      transformers: {
+        [FieldType.Currency]: (val: number) => 
+          val != null ? `$${val.toLocaleString('en-US', { minimumFractionDigits: 2 })}` : '',
+        
+        [FieldType.PhoneNumber]: (val: string) => {
+          if (!val) return '';
+          const cleaned = val.replace(/\D/g, '');
+          if (cleaned.length === 10) {
+            return `(${cleaned.slice(0, 3)}) ${cleaned.slice(3, 6)}-${cleaned.slice(6)}`;
+          }
+          return val;
+        },
+        
+        [FieldType.Boolean]: (val: boolean) => val ? '✓' : '✗'
+      }
+    })
+  ]
+};
+```
+
+---
+
+## Related Documentation
+
+- [TableBuilderSettings Documentation](./TABLE-BUILDER-SETTINGS.md) - Detailed documentation for all table settings
+- [MetaData Documentation](./METADATA-DOCUMENTATION.md) - Column configuration options
+- [StylerStyle Documentation](./STYLER-STYLE.md) - Dynamic styling patterns