npm package: @org12/angular-components
Description: A modern Angular 19 component library with Button, Card, and Grid components
Author: Your Name
Latest version: 1.0.2

# Angular Components Demo Library

A modern Angular 19 component library with reusable UI components.

## Features

- 🚀 Built with Angular 19
- 📦 Standalone components
- 🎨 Pre-styled components ready to use
- 🌓 **Comprehensive theming system** with 6+ pre-built themes (light, dark, high-contrast, ocean, forest, sunset)
- 🎯 **CSS Custom Properties** for easy customization
- ♿ Accessibility-focused with high-contrast theme
- 🔄 Dynamic theme switching with ThemeService
- ✅ Fully tested with Jasmine
- 📝 TypeScript support
- 🔧 Easy to customize

## Installation

### Install from local build

```bash
npm install path/to/dist/components
```

### Install from npm (after publishing)

```bash
npm install @org12/angular-components
```

### Setup Theming (Required)

Import the theme CSS in your global styles:

```css
/* styles.css */
@import '@org12/angular-components/themes/themes.css';
```

Or add it to your `angular.json`:

```json
{
  "styles": [
    "node_modules/@org12/angular-components/themes/themes.css",
    "src/styles.css"
  ]
}
```

**📖 For complete theming documentation, see [THEMING.md](./THEMING.md)**

## Available Components

### Button Component

A customizable button component with multiple variants.

**Usage:**

```typescript
import { ButtonComponent } from 'components';

@Component({
  selector: 'app-example',
  imports: [ButtonComponent],
  template: `
    <lib-button 
      variant="primary" 
      (clicked)="handleClick()">
      Click Me
    </lib-button>
  `
})
export class ExampleComponent {
  handleClick() {
    console.log('Button clicked!');
  }
}
```

**Properties:**
- `variant`: 'primary' | 'secondary' | 'success' | 'danger' (default: 'primary')
- `disabled`: boolean (default: false)
- `type`: 'button' | 'submit' | 'reset' (default: 'button')

**Events:**
- `clicked`: Emitted when button is clicked

### Card Component

A flexible card component for displaying content.

**Usage:**

```typescript
import { CardComponent } from 'components';

@Component({
  selector: 'app-example',
  imports: [CardComponent],
  template: `
    <lib-card 
      title="Card Title" 
      variant="elevated"
      [hasFooter]="true">
      <p>Card content goes here</p>
      <div footer>
        <button>Action</button>
      </div>
    </lib-card>
  `
})
export class ExampleComponent {}
```

**Properties:**
- `title`: string (optional)
- `variant`: 'default' | 'elevated' | 'bordered' (default: 'default')
- `hasFooter`: boolean (default: false)

### Grid Component

A powerful data grid component with filtering, sorting, pagination, row selection, and export functionality.

**Usage:**

```typescript
import { GridComponent, GridColumn } from 'components';

@Component({
  selector: 'app-example',
  imports: [GridComponent],
  template: `
    <lib-grid
      [columns]="columns"
      [data]="data"
      [rowsPerPage]="25"
      [showRowSelection]="true"
      [showExport]="true"
      [loading]="isLoading"
      (rowSelected)="onRowSelected($event)"
      (dataExported)="onDataExported($event)">
    </lib-grid>
  `
})
export class ExampleComponent {
  columns: GridColumn[] = [
    { 
      field: 'id', 
      label: 'ID', 
      dataType: 'number', 
      width: '80px',
      sortable: true, 
      filterable: true 
    },
    { 
      field: 'name', 
      label: 'Name', 
      dataType: 'string', 
      sortable: true, 
      filterable: true 
    },
    { 
      field: 'email', 
      label: 'Email', 
      dataType: 'string', 
      width: '250px',
      filterable: true 
    },
    { 
      field: 'active', 
      label: 'Active', 
      dataType: 'boolean', 
      width: '100px',
      sortable: true 
    },
    { 
      field: 'createdDate', 
      label: 'Created', 
      dataType: 'date', 
      sortable: true 
    }
  ];

  data = [
    { id: 1, name: 'John Doe', email: 'john@example.com', active: true, createdDate: '2024-01-15' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com', active: false, createdDate: '2024-02-20' }
  ];

  isLoading = false;

  onRowSelected(selectedRows: any[]) {
    console.log('Selected rows:', selectedRows);
  }

  onDataExported(exportedData: any[]) {
    console.log('Exported data:', exportedData);
  }
}
```

**Column Configuration (GridColumn interface):**
- `field`: string - Field name in the data object (required)
- `label`: string - Display label for the column header (required)
- `dataType`: 'string' | 'number' | 'date' | 'boolean' - Data type for proper sorting and formatting (required)
- `width`: string - Column width (e.g., '100px', '20%', 'auto') (optional, default: 'auto')
- `filterable`: boolean - Enable filtering for this column (optional, default: false)
- `sortable`: boolean - Enable sorting for this column (optional, default: false)

**Input Properties:**
- `columns`: GridColumn[] - Array of column configurations (required)
- `data`: any[] - Array of data objects to display (required)
- `rowsPerPage`: number - Number of rows per page (default: 10)
- `showRowSelection`: boolean - Enable row selection with checkboxes (default: false)
- `showExport`: boolean - Show export button (default: false)
- `loading`: boolean - Show loading state (default: false)
- `emptyMessage`: string - Message to display when no data (default: 'No data available')

**Output Events:**
- `rowSelected`: Emits array of selected row objects when selection changes
- `dataExported`: Emits array of data being exported (selected rows or all filtered data)

**Features:**
- ✅ **Client-side filtering** - Text-based filtering per column (when filterable: true)
- ✅ **Single column sorting** - Click column headers to sort (when sortable: true)
- ✅ **Pagination** - Navigate through pages with configurable rows per page (10, 25, 50, 100)
- ✅ **Row selection** - Select individual rows or all rows on current page
- ✅ **CSV Export** - Export selected rows or all filtered data to CSV file
- ✅ **Loading state** - Display spinner during data loading
- ✅ **Empty state** - User-friendly message when no data available
- ✅ **Responsive design** - Horizontal scroll on mobile devices
- ✅ **Alternate row colors** - Better readability with striped rows
- ✅ **Data type support** - Proper formatting for string, number, date, and boolean types

## Theming

The library includes a powerful theming system with multiple pre-built themes and full customization support.

### Quick Theme Switching

```typescript
import { ThemeService } from '@org12/angular-components';

export class AppComponent {
  constructor(private themeService: ThemeService) {}

  switchTheme() {
    this.themeService.setTheme('dark'); // or 'light', 'ocean', 'forest', 'sunset', 'high-contrast', 'auto'
  }
}
```

### Available Themes

- **Light** - Clean, modern light theme (default)
- **Dark** - Dark mode for low-light environments
- **High Contrast** - Maximum contrast for accessibility
- **Ocean** - Teal and cyan color palette
- **Forest** - Green nature-inspired palette
- **Sunset** - Warm orange and amber tones
- **Auto** - Follows system dark mode preference

### Custom Theming

Override CSS variables to create your own theme:

```css
:root {
  --lib-primary-600: #8b5cf6;
  --lib-button-primary-bg: #8b5cf6;
  --lib-card-bg: #ffffff;
}
```

**📖 Complete theming guide:** [THEMING.md](./THEMING.md)

## Development

### Build the library

```bash
ng build components
```

The build artifacts will be stored in the `dist/` directory.

### Running unit tests

```bash
ng test components
```

### Generate new components

```bash
ng generate component component-name --project components
```

## Publishing

After building your library:

```bash
cd dist/components
npm publish
```

## Requirements

- Angular 19.2.0 or higher
- TypeScript 5.7.2 or higher

## License

MIT