@one-paragon/angular-utilities 2.8.4 → 2.8.6

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

@@ -1,228 +0,0 @@
-# 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

@@ -1,325 +0,0 @@
-# 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