@one-paragon/angular-utilities 2.8.4 → 2.8.5

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

@@ -1,517 +0,0 @@
-# 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
-      }
-    }
-  }
-];
-```