npm package: @stardyn/angular-ui-group-selector
Description: Angular UI Group Selector Package - Flexible and customizable group selector component with multi-level selection and view mode for Angular applications
Author: Stardyn Team
Latest version: 2.0.9

# @stardyn/angular-ui-group-selector

Flexible and customizable group selector component with multi-level selection and view mode for Angular applications. Provides hierarchical checkbox trees with support for parent-child relationships and different themes.

## Features

- **Multi-level Selection**: Support for nested groups with parent-child checkbox relationships
- **View Mode**: Dedicated component for displaying selected items in a clean view
- **Theme Support**: Dark, light, and red theme options
- **Translation Support**: Built-in translation callback support for internationalization
- **Standalone Components**: All components are standalone and can be used independently
- **Form Integration**: Full Angular Forms support with ControlValueAccessor
- **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- **Performance Focused**: OnPush change detection strategy for optimal performance

## Installation

```bash
npm install @stardyn/angular-ui-group-selector
```

## Quick Start

### 1. Import Components

```typescript
import { Component } from '@angular/core';
import { 
  XConUIGroupSelectorComponent,
  GroupSelectorView,
  XconUIGroupItem,
  XconUIGroupTheme
} from '@stardyn/angular-ui-group-selector';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    XConUIGroupSelectorComponent,
    GroupSelectorView
  ],
  template: `
    <xcon-ui-group-selector
      [items]="groupItems"
      [theme]="theme"
      [selectedKeys]="selectedKeys"
      (selectedKeysChange)="onSelectionChange($event)">
    </xcon-ui-group-selector>
    
    <xcon-ui-group-selector-view
      [items]="groupItems"
      [selectedKeys]="selectedKeys"
      [theme]="theme">
    </xcon-ui-group-selector-view>
  `
})
export class ExampleComponent {
  theme = XconUIGroupTheme.DARK;
  selectedKeys: string[] = [];
  
  groupItems: XconUIGroupItem[] = [
    {
      key: 'group1',
      label: 'Group 1',
      checked: false,
      children: [
        { key: 'item1', label: 'Item 1', checked: false },
        { key: 'item2', label: 'Item 2', checked: false }
      ]
    }
  ];
  
  onSelectionChange(keys: string[]) {
    this.selectedKeys = keys;
  }
}
```

### 2. Advanced Usage with Forms

```typescript
import { FormControl, ReactiveFormsModule } from '@angular/forms';

@Component({
  imports: [XConUIGroupSelectorComponent, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <xcon-ui-group-selector
        formControlName="selectedItems"
        [items]="groupItems"
        [theme]="XconUIGroupTheme.LIGHT"
        [disabled]="form.get('selectedItems')?.disabled">
      </xcon-ui-group-selector>
    </form>
  `
})
export class FormExampleComponent {
  form = new FormGroup({
    selectedItems: new FormControl([])
  });
  
  groupItems: XconUIGroupItem[] = [
    {
      key: 'categories',
      label: 'Categories',
      checked: false,
      children: [
        {
          key: 'tech',
          label: 'Technology',
          checked: false,
          children: [
            { key: 'js', label: 'JavaScript', checked: false },
            { key: 'ts', label: 'TypeScript', checked: false }
          ]
        },
        {
          key: 'design',
          label: 'Design',
          checked: false,
          children: [
            { key: 'ui', label: 'UI Design', checked: false },
            { key: 'ux', label: 'UX Design', checked: false }
          ]
        }
      ]
    }
  ];
}
```

## API Reference

### XConUIGroupSelectorComponent

Main selector component with hierarchical checkbox tree.

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `items` | `XconUIGroupItem[]` | `[]` | Array of group items |
| `selectedKeys` | `string[]` | `[]` | Array of selected item keys |
| `theme` | `XconUIGroupTheme` | `DARK` | Theme for the component |
| `disabled` | `boolean` | `false` | Disable all interactions |
| `translate` | `TranslateCallback` | `undefined` | Translation function |

#### Events

| Event | Type | Description |
|-------|------|-------------|
| `selectionChange` | `XconUIGroupItem[]` | Emitted when selection changes |
| `itemChange` | `{item: XconUIGroupItem, checked: boolean}` | Emitted when individual item changes |
| `selectedKeysChange` | `string[]` | Emitted when selected keys change |

### GroupSelectorView

View component for displaying selected items in a clean layout.

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `items` | `XconUIGroupItem[]` | `[]` | Array of group items |
| `selectedKeys` | `string[]` | `[]` | Array of selected item keys |
| `theme` | `XconUIGroupTheme` | `DARK` | Theme for the component |
| `showDescription` | `boolean` | `true` | Show item descriptions |
| `showIcons` | `boolean` | `true` | Show item icons |
| `emptyMessage` | `string` | `'No items selected'` | Message when no items selected |
| `selectedMessage` | `string` | `'selected items'` | Message for selected items count |
| `groupByParent` | `boolean` | `true` | Group items by parent |
| `translate` | `TranslateCallback` | `undefined` | Translation function |

### XconUIGroupItem Interface

```typescript
interface XconUIGroupItem {
  key: string;
  label: string;
  description?: string;
  icon?: string;
  checked: boolean;
  disabled?: boolean;
  children?: XconUIGroupItem[];
}
```

### XconUIGroupTheme Enum

```typescript
enum XconUIGroupTheme {
  DARK = 'dark',
  LIGHT = 'light',
  RED = 'red'
}
```

## Translation Support

```typescript
// Translation callback function
const translateCallback = async (key: string): Promise<string> => {
  // Your translation logic here
  return await translateService.get(key).toPromise();
};

// Usage in template
<xcon-ui-group-selector
  [translate]="translateCallback"
  [items]="items">
</xcon-ui-group-selector>
```

## Themes

### Dark Theme (Default)
```typescript
theme = XconUIGroupTheme.DARK;
```

### Light Theme
```typescript
theme = XconUIGroupTheme.LIGHT;
```

### Red Theme
```typescript
theme = XconUIGroupTheme.RED;
```

## Form Integration

The component implements ControlValueAccessor for seamless Angular Forms integration:

```typescript
// Reactive Forms
form = new FormGroup({
  selection: new FormControl(['item1', 'item2'])
});

// Template-driven Forms
[(ngModel)]="selectedKeys"
```

## Selection Behavior

- **Leaf Selection**: Only leaf nodes (items without children) contribute to the final selection
- **Parent State**: Parent checkboxes show checked/indeterminate state based on children
- **Auto-update**: Parent states automatically update when children change
- **Key Management**: Selected keys include both leaf items and parent groups with selected children

## Performance

- **OnPush Change Detection**: All components use OnPush strategy for optimal performance
- **Standalone Components**: Tree-shakable components reduce bundle size
- **Efficient Updates**: Smart change detection prevents unnecessary re-renders
- **Memory Optimized**: Deep cloning only when necessary

## Browser Support

- Chrome 80+
- Firefox 75+
- Safari 13+
- Edge 80+

## TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import type { 
  XConUIGroupSelectorComponent,
  GroupSelectorView,
  XconUIGroupItem,
  XconUIGroupTheme
} from '@stardyn/angular-ui-group-selector';
```

## License

MIT License - see LICENSE file for details.

## Repository

https://github.com/stardyn/angular-ui-group-selector