@one-paragon/angular-utilities 2.8.2 → 2.8.4

package/src/table-builder/documentation/table-builder/METADATA-DOCUMENTATION.md

@@ -0,0 +1,517 @@
+# MetaData Configuration Documentation
+
+## Overview
+
+`MetaData` defines the configuration for table columns in the Table Builder. Each column can be configured with shared settings and type-specific options based on the `FieldType`.
+
+## Shared MetaData Settings
+
+All `MetaData` types inherit these common configuration options:
+
+### Core Settings
+
+#### `key` (required)
+- **Type**: `string` (mapped path or custom key)
+- **Description**: The property path on the data object or a custom identifier for the column. For mapped fields, supports nested paths like `'user.address.city'`.
+
+#### `fieldType` (required)
+- **Type**: `FieldType`
+- **Description**: Specifies the data type for the column, which determines sorting, filtering, and display behavior.
+
+#### `displayName`
+- **Type**: `string`
+- **Description**: The column header text. If not provided, defaults to the `key` value.
+
+#### `order`
+- **Type**: `number`
+- **Description**: Defines the display order of columns. Lower numbers appear first.
+
+#### `width`
+- **Type**: `string`
+- **Description**: CSS width value for the column (e.g., `'150px'`, `'20%'`).
+
+### Data Transformation
+
+#### `map`
+- **Type**: `(t: T) => any`
+- **Description**: Transforms the entire row object to extract or compute the cell value. This is the preferred method for custom value extraction.
+- **Example**: 
+  ```typescript
+  map: (user) => `${user.firstName} ${user.lastName}`
+  ```
+
+#### `mapItem`
+- **Type**: `(i: any) => any`
+- **Description**: Transforms the extracted value for display. When used with `map`, `mapItem` is only applied in contexts where the full row is unavailable (e.g., group headers).
+
+#### `transform` ⚠️ **Deprecated**
+- **Type**: `((o: T, ...args: any[]) => any) | PipeTransform`
+- **Description**: Legacy transformation method. Use `map` instead.
+
+### Sorting Configuration
+
+#### `preSort`
+- **Type**: `SortDef`
+- **Description**: Defines initial sorting for the column.
+- **Properties**:
+  - `direction`: `'asc'` or `'desc'`
+  - `precedence`: Sort priority when multiple columns are sorted
+
+#### `sortLogic`
+- **Type**: `object`
+- **Description**: Customizes sorting behavior.
+- **Properties**:
+  - `nulls`: `'first'` | `'last'` (default: `'last'`) - Controls null value positioning
+  - `sortBy`: `((t: T) => any)` | `'use map'` - Custom sort value extraction. Use `'use map'` to apply the column's `map` function for sorting.
+
+#### `noSort`
+- **Type**: `boolean`
+- **Description**: When `true`, removes the sorting button from the column header and excludes the column from the sort menu list.
+
+### Filtering Configuration
+
+#### `filterLogic`
+- **Type**: `object`
+- **Description**: Customizes filtering behavior.
+- **Properties**:
+  - `filterBy`: `((t: T) => any)` | `'use map'` - Custom filter value extraction. Use `'use map'` to apply the column's `map` function.
+  - `filterType`: `FieldType` - Override the filter UI type (defaults to the column's `fieldType`)
+
+#### `noFilter`
+- **Type**: `boolean`
+- **Description**: Disables filtering for this column.
+
+### Grouping Configuration
+
+#### `groupByLogic`
+- **Type**: `object`
+- **Description**: Enables and configures row grouping by this column.
+- **Properties**:
+  - `groupBy`: `((t: T) => any)` | `'use map'` - Determines the grouping value
+  - `groupByHeader`: `(groupByVal: any) => string` - Formats the group header text
+
+### Display & Interaction
+
+#### `template`
+- **Type**: `TemplateRef<any>`
+- **Description**: Custom Angular template for rendering the cell content.
+
+#### `click`
+- **Type**: `(element: T, key?: string, event?: MouseEvent) => void`
+- **Description**: Click handler for the cell.
+
+#### `classes`
+- **Type**: `Dictionary<Predicate<T> | true>`
+- **Description**: CSS classes to apply to cells. Keys are class names, values are predicates that determine when to apply the class.
+- **Example**:
+  ```typescript
+  classes: {
+    'text-danger': (row) => row.status === 'error',
+    'text-success': (row) => row.status === 'success'
+  }
+  ```
+
+#### `toolTip`
+- **Type**: `string | ((t: T) => string)`
+- **Description**: Tooltip text for the cell, either static or computed from the row data.
+
+#### `useIcon`
+- **Type**: `boolean`
+- **Description**: Renders the cell value as an icon (typically used with icon fonts).
+
+### Export Configuration
+
+#### `noExport`
+- **Type**: `boolean`
+- **Description**: Excludes this column from data exports.
+
+---
+
+## Type-Specific MetaData Options
+
+Each `FieldType` may have specific `additional` properties for advanced configuration.
+
+### String Types
+
+**Applicable to**: `FieldType.String`, `FieldType.PhoneNumber`, `FieldType.ImageUrl`, `FieldType.Link`, `FieldType.Hidden`, `FieldType.Unknown`
+
+**Interface**: `MappedMetaData<T>`
+
+#### Additional Properties
+
+- **`filterOptions`**: `FilterOptions<string>`
+  - `filterableValues`: Array of specific values to show in filter dropdown, `'all values'` to show all unique values, or `AllValueOptions` object
+  - **Example**: 
+    ```typescript
+    additional: {
+      filterOptions: {
+        filterableValues: ['Active', 'Inactive', 'Pending']
+      }
+    }
+    ```
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+---
+
+### Number Types
+
+**Applicable to**: `FieldType.Number`, `FieldType.Currency`
+
+**Interface**: `MappedNumberMetaData<T>`
+
+#### Additional Properties
+
+- **`filterOptions`**: `FilterOptions<number>`
+  - Numeric filter options
+
+- **`footer`**: `{ type: 'sum' }`
+  - Enables automatic sum calculation in the footer row
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+**Example**:
+```typescript
+{
+  key: 'totalSales',
+  fieldType: FieldType.Currency,
+  displayName: 'Total Sales',
+  additional: {
+    footer: { type: 'sum' }
+  }
+}
+```
+
+---
+
+### Enum Types
+
+**Applicable to**: `FieldType.Enum`
+
+**Interface**: `MappedEnumMetaData<T>`
+
+#### Additional Properties
+
+- **`enumMap`**: `{[key: number]: string}`
+  - Maps numeric enum values to display strings
+  - **Example**:
+    ```typescript
+    additional: {
+      enumMap: {
+        0: 'Pending',
+        1: 'Approved',
+        2: 'Rejected'
+      }
+    }
+    ```
+
+- **`filterOptions`**: `FilterOptions<number>`
+  - Numeric filter options for enum values
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+---
+
+### Boolean Types
+
+**Applicable to**: `FieldType.Boolean`
+
+**Interface**: `MappedBooleanMetaData<T>`
+
+#### Additional Properties
+
+- **`boolean`**: Configuration for boolean display
+  - **`showForFalse`**: `true | { icon: string }`
+    - If `true`, shows a default indicator for false values
+    - If object, shows the specified icon for false values
+  - **`forTrue`**: `{ icon: string }`
+    - Icon to display for true values
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+**Example**:
+```typescript
+{
+  key: 'isActive',
+  fieldType: FieldType.Boolean,
+  displayName: 'Active',
+  additional: {
+    boolean: {
+      showForFalse: { icon: 'close' },
+      forTrue: { icon: 'check' }
+    }
+  }
+}
+```
+
+---
+
+### Date Types
+
+**Applicable to**: `FieldType.Date`, `FieldType.DateTime`
+
+**Interface**: `MappedDateMetaData<T>`
+
+#### Additional Properties
+
+- **`dateFormat`**: `string`
+  - Custom date format string (e.g., `'MM/dd/yyyy'`)
+
+- **`dateTimeOptions`**: `DateTimeOptions`
+  - **`format`**: Custom format string
+  - **`includeSeconds`**: Include seconds in time display
+  - **`includeMilliseconds`**: Include milliseconds in time display
+
+- **`filterOptions`**: `FilterOptions<Date>`
+  - Date-specific filtering options
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+**Example**:
+```typescript
+{
+  key: 'createdAt',
+  fieldType: FieldType.DateTime,
+  displayName: 'Created',
+  additional: {
+    dateTimeOptions: {
+      includeSeconds: true,
+      includeMilliseconds: false
+    }
+  }
+}
+```
+
+---
+
+### Array Types
+
+**Applicable to**: `FieldType.Array`
+
+**Interface**: `MappedArrayMetaData<T>`
+
+#### Additional Properties
+
+- **`limit`**: `number`
+  - Maximum number of array items to display
+
+- **`arrayStyle`**: `ArrayStyle`
+  - **`ArrayStyle.CommaDelimited`**: Display items separated by commas
+  - **`ArrayStyle.NewLine`**: Display each item on a new line
+
+- **`filterOptions`**: `FilterOptions<string>`
+  - Array-specific filtering
+
+- All properties from `BaseAdditional` (see Common Additional Properties section)
+
+**Example**:
+```typescript
+{
+  key: 'tags',
+  fieldType: FieldType.Array,
+  displayName: 'Tags',
+  additional: {
+    limit: 5,
+    arrayStyle: ArrayStyle.CommaDelimited
+  }
+}
+```
+
+---
+
+### NotMapped Types
+
+**Applicable to**: `FieldType.NotMapped`, `FieldType.Expression` (deprecated)
+
+**Interface**: `NotMappedMetaData<T>`
+
+Used for computed or virtual columns that don't correspond to a direct property on the data object. The `key` can be any string identifier, and the `map` function is required to provide the cell value.
+
+#### Additional Properties
+
+- All properties from `Additional<T>` (same as String types)
+
+**Example**:
+```typescript
+{
+  key: 'fullName',
+  fieldType: FieldType.NotMapped,
+  displayName: 'Full Name',
+  map: (user) => `${user.firstName} ${user.lastName}`
+}
+```
+
+---
+
+## Common Additional Properties
+
+The following properties are available in the `additional` object for all or most field types:
+
+### Link Configuration
+
+#### `link`
+- **Type**: `object`
+- **Description**: Configures the cell as a clickable link.
+- **Properties**:
+  - **`base`**: Base URL for the link
+  - **`urlKey`**: Property name to append to the base URL
+  - **`target`**: Link target (`Target.Blank`, `Target.Self`, etc.)
+  - **`useRouterLink`**: Use Angular router navigation instead of standard href
+  - **`interpolatedRoute`**: Route with interpolated parameters
+    - Use `{propertyName}` syntax to inject values from the row
+    - Example: `'/users/{id}/edit'` replaces `{id}` with `row.id`
+    - Can also be a function: `(t: T) => string`
+  - **`routerLinkOptions`**: Additional router link configuration
+    - **`queryParams`**: Array of `[paramName, value | interpolatedRoute | function]` tuples
+    - **`fragment`**: URL fragment (hash)
+    - **`preserveFragment`**: Preserve existing fragment
+    - **`queryParamsHandling`**: How to handle existing query params
+
+**Example**:
+```typescript
+additional: {
+  link: {
+    interpolatedRoute: '/users/{userId}/details',
+    useRouterLink: true,
+    target: Target.Blank,
+    routerLinkOptions: {
+      queryParams: [
+        ['tab', 'profile'],
+        ['edit', (row) => row.isEditable.toString()]
+      ]
+    }
+  }
+}
+```
+
+### Export Configuration
+
+#### `export`
+- **Type**: `MetaDataExport<T>`
+- **Description**: Customizes how the column is exported.
+- **Properties**:
+  - **`mapForExport`**: `(t: T) => string` - Custom export value mapper (supersedes all other mappings)
+  - **`linkColumnName`**: `string` - Column name for links when using `mapLink: 'add link'`
+  - **`dateFormat`**: `string` - Date format for this column's export
+  - **`dateTimeFormat`**: `string` - DateTime format for this column's export
+  - **`prepend`**: `string` - Text to prepend to exported values
+  - **`mapEnumToString`**: `boolean` - If `true`, maps enum numeric values to their string representations
+  - **`mapLink`**: `'as link'` | `'as view'` | `'add link'` | `'as excel'` | `'add excel'`
+    - `'as view'` (default): Export the link as it appears in the view
+    - `'as link'`: Export the full URL
+    - `'add link'`: Export the view value and add a separate column with the link URL
+    - `'as excel'`: Export as an Excel hyperlink formula
+    - `'add excel'`: Export the view value and add a separate column with the Excel hyperlink formula
+  - **`linkDomainPrefix`**: `string` - Domain prefix to add to links when using `mapLink: 'as link'` or `'add link'`
+
+### Styling Configuration
+
+#### `styles`
+- **Type**: [`StylerStyle<T>`](./STYLER-STYLE.md)
+- **Description**: Dynamic inline styles applied to cells based on row data. See [StylerStyle documentation](./STYLER-STYLE.md) for detailed usage patterns.
+
+#### `columnPartStyles`
+- **Type**: `object`
+- **Description**: Styles for different parts of the column.
+- **Properties**:
+  - **`header`**: `Dictionary<string>` - Header cell styles
+  - **`body`**: [`StylerStyle<T>`](./STYLER-STYLE.md) - Body cell styles (row-dependent)
+  - **`innerBody`**: [`StylerStyle<T>`](./STYLER-STYLE.md) - Inner content styles (row-dependent)
+  - **`footer`**: `Dictionary<string>` - Footer cell styles
+
+#### `columnPartClasses`
+- **Type**: `object`
+- **Description**: CSS classes for different parts of the column.
+- **Properties**:
+  - **`header`**: `Dictionary<Predicate<T> | true>` - Header cell classes
+  - **`footer`**: `Dictionary<Predicate<T> | true>` - Footer cell classes
+
+**Example**:
+```typescript
+additional: {
+  columnPartStyles: {
+    header: { 'background-color': '#f0f0f0' },
+    body: (row) => ({ 'font-weight': row.isPriority ? 'bold' : 'normal' })
+  },
+  columnPartClasses: {
+    header: { 'text-center': true },
+    footer: { 'text-muted': true }
+  }
+}
+```
+
+---
+
+## Complete Example
+
+```typescript
+const userTableMetadata: MetaData<User>[] = [
+  {
+    key: 'id',
+    fieldType: FieldType.Number,
+    displayName: 'ID',
+    width: '80px',
+    preSort: { direction: SortDirection.asc, precedence: 1 }
+  },
+  {
+    key: 'fullName',
+    fieldType: FieldType.NotMapped,
+    displayName: 'Name',
+    map: (user) => `${user.firstName} ${user.lastName}`,
+    additional: {
+      link: {
+        interpolatedRoute: '/users/{id}',
+        useRouterLink: true
+      }
+    }
+  },
+  {
+    key: 'email',
+    fieldType: FieldType.String,
+    displayName: 'Email',
+    toolTip: 'User email address'
+  },
+  {
+    key: 'status',
+    fieldType: FieldType.Enum,
+    displayName: 'Status',
+    additional: {
+      enumMap: { 0: 'Inactive', 1: 'Active', 2: 'Suspended' },
+    },
+    classes: {
+      'text-success': (user) => user.status === 1,
+      'text-danger': (user) => user.status === 2
+    }
+  },
+  {
+    key: 'salary',
+    fieldType: FieldType.Currency,
+    displayName: 'Salary',
+    width: '120px',
+    additional: {
+      footer: { type: 'sum' }
+    }
+  },
+  {
+    key: 'isActive',
+    fieldType: FieldType.Boolean,
+    displayName: 'Active',
+    additional: {
+      boolean: {
+        showForFalse: { icon: 'close' },
+        forTrue: { icon: 'check' }
+      }
+    }
+  },
+  {
+    key: 'createdAt',
+    fieldType: FieldType.DateTime,
+    displayName: 'Created',
+    additional: {
+      dateTimeOptions: {
+        includeSeconds: true
+      }
+    }
+  }
+];
+```