# @acorex/components/data-list

Secondary entry point of `@acorex/components`. It can be used by importing from `@acorex/components/data-list`.

## Overview

`AXDataList` is a modern, signal-based Angular data list component that provides virtual scrolling, selection management, and tree grouping capabilities. It's designed to replace the existing `AXListComponent` with improved performance and modern Angular patterns.

## Key Features

### Core Functionality

- ✅ **Virtual Scrolling** - CDK-based virtual scrolling for large datasets
- ✅ **Selection Management** - Single and multiple selection modes
- ✅ **Tree Grouping** - Hierarchical item organization with expand/collapse
- ✅ **Template System** - Custom templates for items, loading, and empty states
- ✅ **Keyboard Navigation** - Full keyboard accessibility
- ✅ **Modern Angular** - Signal-based architecture for optimal performance

### Advanced Features

- ✅ **Disabled Items** - Field-based item disabling with visual and behavioral support
- ✅ **Tooltip Support** - Custom tooltip content via field mapping
- ✅ **Checkbox Control** - Configurable checkbox display and behavior
- ✅ **Search API** - External search integration (not built-in)

## Component Architecture

### Base Class

- **Inherits from**: `MXValueComponent` (instead of `MXSelectionValueComponent`)
- **Change Detection**: `OnPush` strategy
- **Encapsulation**: `ViewEncapsulation.None`

### Dependencies

- `@angular/cdk/scrolling` - Virtual scrolling
- `@angular/forms` - Form integration
- `@acorex/cdk/common` - Base components and utilities

## Input Properties

### Basic Properties

| Property   | Type      | Default | Description                  |
| ---------- | --------- | ------- | ---------------------------- |
| `id`       | `string`  | -       | Component identifier         |
| `name`     | `string`  | -       | Component name for forms     |
| `disabled` | `boolean` | `false` | Disable the entire component |
| `readonly` | `boolean` | `false` | Make component read-only     |
| `tabIndex` | `number`  | `0`     | Tab order                    |

### Data & Selection

| Property        | Type                    | Default  | Description                      |
| --------------- | ----------------------- | -------- | -------------------------------- |
| `dataSource`    | `AXDataSource<unknown>` | `[]`     | Data source for the list         |
| `value`         | `unknown \| unknown[]`  | -        | Current selected value(s)        |
| `valueField`    | `string`                | `'id'`   | Field name for item value        |
| `textField`     | `string`                | `'text'` | Field name for item display text |
| `multiple`      | `boolean`               | `false`  | Enable multiple selection        |
| `selectionMode` | `string`                | `'item'` | Selection behavior               |

### Display & Behavior

| Property          | Type               | Default | Description                       |
| ----------------- | ------------------ | ------- | --------------------------------- |
| `itemHeight`      | `number \| 'auto'` | `40`    | Height of each list item          |
| `isItemTruncated` | `boolean`          | `true`  | Enable text truncation            |
| `showItemTooltip` | `boolean`          | `false` | Show tooltips for truncated items |
| `showCheckbox`    | `boolean`          | `true`  | Show checkboxes for selection     |

### Field Mappings

| Property        | Type     | Default | Description                                 |
| --------------- | -------- | ------- | ------------------------------------------- |
| `disabledField` | `string` | -       | Field name to determine if item is disabled |
| `tooltipField`  | `string` | -       | Field name for custom tooltip content       |

### Tree Grouping

| Property             | Type          | Default      | Description                       |
| -------------------- | ------------- | ------------ | --------------------------------- |
| `childrenField`      | `string`      | `'children'` | Field name containing child items |
| `expandedField`      | `string`      | `'expanded'` | Field name for expanded state     |
| `levelField`         | `string`      | `'level'`    | Field name for nesting level      |
| `groupTemplate`      | `TemplateRef` | -            | Template for group headers        |
| `expandIconTemplate` | `TemplateRef` | -            | Custom expand/collapse icons      |

### Templates

| Property          | Type          | Default | Description                    |
| ----------------- | ------------- | ------- | ------------------------------ |
| `itemTemplate`    | `TemplateRef` | -       | Custom template for list items |
| `emptyTemplate`   | `TemplateRef` | -       | Template for empty state       |
| `loadingTemplate` | `TemplateRef` | -       | Template for loading state     |
| `textTemplate`    | `TemplateRef` | -       | Custom text display template   |

## Output Events

### Value & Selection Events

| Event                | Type                      | Description             |
| -------------------- | ------------------------- | ----------------------- |
| `onValueChanged`     | `AXValueChangedEvent`     | Value selection changed |
| `onItemClick`        | `AXItemClickEvent`        | Item clicked            |
| `onItemSelected`     | `AXItemSelectedEvent`     | Item selection changed  |
| `onSelectionChanged` | `AXSelectionChangedEvent` | Selection state changed |

### Focus & Interaction Events

| Event       | Type             | Description            |
| ----------- | ---------------- | ---------------------- |
| `onBlur`    | `AXBlurEvent`    | Component lost focus   |
| `onFocus`   | `AXFocusEvent`   | Component gained focus |
| `onKeyDown` | `AXKeyDownEvent` | Key pressed            |

### Data & State Events

| Event                    | Type                       | Description             |
| ------------------------ | -------------------------- | ----------------------- |
| `onScrolledIndexChanged` | `AXListScrollIndexChanged` | Scroll position changed |
| `onLoadingChanged`       | `AXLoadingChangedEvent`    | Loading state changed   |
| `onDataChanged`          | `AXDataChangedEvent`       | Data source changed     |

### Tree Grouping Events

| Event             | Type                   | Description                   |
| ----------------- | ---------------------- | ----------------------------- |
| `onItemExpanded`  | `AXItemExpandedEvent`  | Item expanded                 |
| `onItemCollapsed` | `AXItemCollapsedEvent` | Item collapsed                |
| `onGroupToggle`   | `AXGroupToggleEvent`   | Group expand/collapse toggled |

## Public API Methods

### Selection Management

| Method                 | Parameters      | Return      | Description                   |
| ---------------------- | --------------- | ----------- | ----------------------------- |
| `selectItem(item)`     | `item: unknown` | `void`      | Select specific item          |
| `deselectItem(item)`   | `item: unknown` | `void`      | Deselect specific item        |
| `clearSelection()`     | -               | `void`      | Clear all selections          |
| `getSelectedItems()`   | -               | `unknown[]` | Get currently selected items  |
| `isItemSelected(item)` | `item: unknown` | `boolean`   | Check if item is selected     |
| `isItemDisabled(item)` | `item: unknown` | `boolean`   | Check if item is disabled     |
| `canSelectItem(item)`  | `item: unknown` | `boolean`   | Check if item can be selected |

### Navigation & Focus

| Method                 | Parameters      | Return | Description                  |
| ---------------------- | --------------- | ------ | ---------------------------- |
| `focus()`              | -               | `void` | Focus the component          |
| `focusItem(index)`     | `index: number` | `void` | Focus specific item by index |
| `focusNextItem()`      | -               | `void` | Focus next item              |
| `focusPreviousItem()`  | -               | `void` | Focus previous item          |
| `scrollToIndex(index)` | `index: number` | `void` | Scroll to specific index     |

### Data & State

| Method                  | Parameters      | Return      | Description                 |
| ----------------------- | --------------- | ----------- | --------------------------- |
| `refresh()`             | -               | `void`      | Refresh data source         |
| `getItemByKey(key)`     | `key: unknown`  | `unknown`   | Get item by key             |
| `getItemByIndex(index)` | `index: number` | `unknown`   | Get item by index           |
| `getVisibleItems()`     | -               | `unknown[]` | Get items currently visible |

### Tree Grouping

| Method                 | Parameters      | Return      | Description               |
| ---------------------- | --------------- | ----------- | ------------------------- |
| `expandItem(item)`     | `item: unknown` | `void`      | Expand group              |
| `collapseItem(item)`   | `item: unknown` | `void`      | Collapse group            |
| `toggleExpanded(item)` | `item: unknown` | `void`      | Toggle expand/collapse    |
| `expandAll()`          | -               | `void`      | Expand all groups         |
| `collapseAll()`        | -               | `void`      | Collapse all groups       |
| `isExpanded(item)`     | `item: unknown` | `boolean`   | Check if item is expanded |
| `getItemLevel(item)`   | `item: unknown` | `number`    | Get nesting level         |
| `getParentItem(item)`  | `item: unknown` | `unknown`   | Get parent item           |
| `getChildItems(item)`  | `item: unknown` | `unknown[]` | Get child items           |

### Viewport Management

| Method                | Parameters | Return | Description                |
| --------------------- | ---------- | ------ | -------------------------- |
| `render()`            | -          | `void` | Re-render the component    |
| `checkViewportSize()` | -          | `void` | Update viewport dimensions |
| `scrollToTop()`       | -          | `void` | Scroll to top              |
| `scrollToBottom()`    | -          | `void` | Scroll to bottom           |

## Template Context Variables

### Standard Item Context

| Variable    | Type      | Description     |
| ----------- | --------- | --------------- |
| `$implicit` | `unknown` | The item data   |
| `index`     | `number`  | Item index      |
| `selected`  | `boolean` | Selection state |
| `disabled`  | `boolean` | Disabled state  |
| `first`     | `boolean` | First item flag |
| `last`      | `boolean` | Last item flag  |
| `even`      | `boolean` | Even index flag |
| `odd`       | `boolean` | Odd index flag  |

### Tree Grouping Context

| Variable      | Type        | Description                    |
| ------------- | ----------- | ------------------------------ |
| `level`       | `number`    | Nesting level (0, 1, 2, etc.)  |
| `isGroup`     | `boolean`   | Whether item is a group/parent |
| `isExpanded`  | `boolean`   | Whether group is expanded      |
| `hasChildren` | `boolean`   | Whether item has children      |
| `parent`      | `unknown`   | Reference to parent item       |
| `children`    | `unknown[]` | Child items array              |

## Behavior Specifications

### Disabled Items

- **Visual**: Grayed out appearance with reduced opacity
- **Focus**: Disabled items are focusable but not selectable
- **Navigation**: Skipped in keyboard navigation (Arrow keys)
- **Selection**: Cannot be selected or deselected
- **Checkbox**: Disabled checkboxes for disabled items

### Tooltip Behavior

- **Custom Tooltip**: `tooltipField` provides custom tooltip content
- **Default Tooltip**: Shows on hover regardless of truncation
- **Priority**: Custom tooltip overrides default text tooltip

### Checkbox Behavior

- **Display**: Controlled by `showCheckbox` input
- **State**: Disabled items show disabled checkboxes
- **Group Headers**: Can show checkboxes for "select all children" behavior
- **Behavior Options**: Configurable checkbox interaction patterns

### Tree Grouping Behavior

- **Expand/Collapse**: Click on group header or expand icon
- **Selection**: Group selection can affect child selection
- **Navigation**: Keyboard navigation respects expanded/collapsed state
- **Performance**: Virtual scrolling optimized for tree structures

## CSS Classes & Styling

### Container Classes

- `.ax-list-container` - Main container
- `.ax-list-container.ax-height-auto` - Auto height mode
- `.ax-list-container.ax-tree-mode` - Tree grouping mode

### Item Classes

- `.ax-list-item` - Individual items
- `.ax-list-item.ax-state-selected` - Selected state
- `.ax-list-item.ax-state-disabled` - Disabled state
- `.ax-list-item.ax-state-focused` - Focused state
- `.ax-list-item.ax-state-loading` - Loading state
- `.ax-list-item.ax-state-empty` - Empty state

### Tree Grouping Classes

- `.ax-list-item.ax-group-header` - Group header items
- `.ax-list-item.ax-group-expanded` - Expanded group
- `.ax-list-item.ax-group-collapsed` - Collapsed group
- `.ax-list-item.ax-group-child` - Child items
- `.ax-list-item.ax-level-{n}` - Nesting level styling

### State Classes

- `.ax-list-item.ax-level-0` - Root level items
- `.ax-list-item.ax-level-1` - First level nested items
- `.ax-list-item.ax-level-2` - Second level nested items
- `.ax-list-item.ax-has-children` - Items with children
- `.ax-list-item.ax-no-children` - Items without children

## Performance Considerations

### Virtual Scrolling

- **Item Size**: Fixed item height for optimal performance
- **Viewport Management**: Efficient viewport size calculations
- **Memory Usage**: Minimal DOM elements for large datasets

### Signal Optimization

- **Change Detection**: Signal-based updates for minimal re-renders
- **Computed Values**: Efficient computed signals for derived state
- **Memory Management**: Proper signal cleanup and disposal

### Tree Grouping Performance

- **Lazy Loading**: Children loaded on demand
- **Virtual Scrolling**: Optimized for hierarchical structures
- **Selection Caching**: Efficient selection state management

## Migration Guide

### From AXListComponent

- **Component Name**: Change from `ax-list` to `ax-data-list`
- **Base Class**: Change from `MXSelectionValueComponent` to `MXValueComponent`
- **Inputs**: Update input property names (e.g., `checkbox` → `showCheckbox`)
- **Events**: Update event handler names
- **Templates**: Ensure template context compatibility

### Breaking Changes

- **Selection API**: Simplified selection management
- **Event Names**: Updated event naming conventions
- **Template Context**: Enhanced context variables for tree grouping

## Future Enhancements

### Planned Features

- **Drag & Drop**: Item reordering and tree restructuring
- **Filtering**: Client-side filtering capabilities
- **Sorting**: Multi-column sorting support
- **Pagination**: Built-in pagination controls
- **Export**: Data export functionality

### Performance Improvements

- **Web Workers**: Background data processing
- **Service Workers**: Offline data caching
- **IndexedDB**: Local data persistence
- **WebAssembly**: High-performance data operations

## Implementation Notes

### Development Phases

1. **Phase 1**: Core functionality with virtual scrolling
2. **Phase 2**: Selection management and templates
3. **Phase 3**: Tree grouping implementation
4. **Phase 4**: Advanced features and optimizations

### Testing Strategy

- **Unit Tests**: Component logic and API methods
- **Integration Tests**: Template system and data binding
- **Performance Tests**: Virtual scrolling and large datasets
- **Accessibility Tests**: Keyboard navigation and screen readers

### Browser Support

- **Modern Browsers**: Chrome 90+, Firefox 88+, Safari 14+
- **Mobile**: iOS Safari 14+, Chrome Mobile 90+
- **Fallbacks**: Graceful degradation for older browsers

---

_This README serves as the complete specification for AXListComponent2 development and implementation._