# Card Component - Complete Documentation

## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Inputs](#inputs)
- [Content Projection](#content-projection)
- [Usage Examples](#usage-examples)
- [Best Practices](#best-practices)

---

## Overview

The `ngx-st-card` component is a styled card wrapper with header, actions, and content areas. Features include:
- Title with optional back navigation
- Create button with custom link
- Action menu and action button support
- History back button
- Configurable body padding
- Material Design styling

---

## Installation

```bash
npm install ngx-st-card
```

Import the module:

```typescript
import { StCardModule } from 'ngx-st-card';

@NgModule({
  imports: [StCardModule]
})
export class AppModule { }
```

---

## Basic Usage

```html
<ngx-st-card title="User Details">
  <p>Card content goes here</p>
</ngx-st-card>
```

---

## Inputs

### `title`
- **Type:** `string`
- **Default:** `undefined`
- **Description:** Title text displayed in the card header.
- **Example:**
  ```html
  title="User Profile"
  title="Product Details"
  [title]="dynamicTitle"
  ```

### `createLink`
- **Type:** `string[]`
- **Default:** `undefined`
- **Description:** Router link array for the create button. When provided, shows a create button in the header.
- **Example:**
  ```html
  [createLink]="['/users', 'create']"
  [createLink]="['/products', 'new']"
  ```

### `backLink`
- **Type:** `string[]`
- **Default:** `undefined`
- **Description:** Router link array for the back button. When provided, shows a back button in the header.
- **Example:**
  ```html
  [backLink]="['/users']"
  [backLink]="['/dashboard']"
  ```

### `showHistoryBack`
- **Type:** `boolean`
- **Default:** `false`
- **Description:** Shows a back button that uses browser history (`Location.back()`). Alternative to `backLink`. When enabled, iframe history skipping is also enabled by default (see `checkIframeHistoryOnBack`).
- **Example:**
  ```html
  [showHistoryBack]="true"
  ```

### `checkIframeHistoryOnBack`
- **Type:** `boolean | undefined`
- **Default:** `undefined` (falls back to `showHistoryBack()` value)
- **Description:** When enabled, the back button keeps calling `history.back()` until the URL actually changes. Use on pages with iframe embeds (e.g. Power BI paginated reports) that push extra browser history entries without changing the parent URL. Set to `false` to force a single `history.back()` even when `showHistoryBack` is true.
- **Example:**
  ```html
  <ngx-st-card
    [title]="'Power BI Report'"
    [showHistoryBack]="true"
    [checkIframeHistoryOnBack]="true">
  </ngx-st-card>
  ```

### `actionMenu`
- **Type:** `MenuElementModel[]`
- **Default:** `undefined`
- **Description:** Array of menu items to display in the actions dropdown menu. Requires `ngx-st-dynamic-menu` types.
- **Example:**
  ```typescript
  actionMenu: MenuElementModel[] = [
    { label: 'Edit', icon: 'edit', action: () => this.edit() },
    { label: 'Delete', icon: 'delete', action: () => this.delete() }
  ];
  ```
  ```html
  [actionMenu]="actionMenu"
  ```

### `actionButton`
- **Type:** `MenuElementModel`
- **Default:** `undefined`
- **Description:** Single action button to display in the header (not in dropdown).
- **Example:**
  ```typescript
  actionButton: MenuElementModel = {
    label: 'Save',
    icon: 'save',
    action: () => this.save()
  };
  ```
  ```html
  [actionButton]="actionButton"
  ```

### `noBodyTopPadding`
- **Type:** `boolean`
- **Default:** `false`
- **Description:** Removes top padding from the card body. Useful for tables or other content that needs to start at the top.
- **Example:**
  ```html
  [noBodyTopPadding]="true"
  ```

### `createLinkLabel`
- **Type:** `string`
- **Default:** `'Create'`
- **Description:** Custom label for the create button.
- **Example:**
  ```html
  createLinkLabel="Add New"
  createLinkLabel="New Product"
  ```

---

## Content Projection

The component uses content projection for the card body:

```html
<ngx-st-card title="My Card">
  <!-- All content here goes into the card body -->
  <p>Any HTML content</p>
  <div>Components, forms, tables, etc.</div>
</ngx-st-card>
```

---

## Usage Examples

### Example 1: Simple Card

```typescript
// Component
@Component({
  selector: 'app-user-profile',
  template: `
    <ngx-st-card title="User Profile">
      <div class="profile-content">
        <p><strong>Name:</strong> {{ user.name }}</p>
        <p><strong>Email:</strong> {{ user.email }}</p>
        <p><strong>Role:</strong> {{ user.role }}</p>
      </div>
    </ngx-st-card>
  `
})
export class UserProfileComponent {
  user = {
    name: 'John Doe',
    email: 'john@example.com',
    role: 'Administrator'
  };
}
```

### Example 2: Card with Back Button

```typescript
// Component
@Component({
  selector: 'app-user-details',
  template: `
    <ngx-st-card 
      title="User Details"
      [backLink]="['/users']">
      <p>User information here...</p>
    </ngx-st-card>
  `
})
export class UserDetailsComponent { }
```

### Example 3: Card with History Back

```typescript
// Component
@Component({
  selector: 'app-product-view',
  template: `
    <ngx-st-card 
      title="Product Details"
      [showHistoryBack]="true">
      <div>Product content...</div>
    </ngx-st-card>
  `
})
export class ProductViewComponent { }
```

### Example 4: Card with Create Button

```typescript
// Component
@Component({
  selector: 'app-users-list',
  template: `
    <ngx-st-card 
      title="Users"
      [createLink]="['/users', 'create']"
      createLinkLabel="Add User">
      <table>
        <!-- Users table -->
      </table>
    </ngx-st-card>
  `
})
export class UsersListComponent { }
```

### Example 5: Card with Action Menu

```typescript
// Component
@Component({
  selector: 'app-document-view',
  template: `
    <ngx-st-card 
      title="Document"
      [showHistoryBack]="true"
      [actionMenu]="documentActions">
      <div>Document content...</div>
    </ngx-st-card>
  `
})
export class DocumentViewComponent {
  documentActions: MenuElementModel[] = [
    {
      label: 'Edit',
      icon: 'edit',
      action: () => this.editDocument()
    },
    {
      label: 'Download',
      icon: 'download',
      action: () => this.downloadDocument()
    },
    {
      label: 'Share',
      icon: 'share',
      action: () => this.shareDocument()
    },
    {
      label: 'Delete',
      icon: 'delete',
      action: () => this.deleteDocument()
    }
  ];
  
  editDocument(): void {
    console.log('Edit document');
  }
  
  downloadDocument(): void {
    console.log('Download document');
  }
  
  shareDocument(): void {
    console.log('Share document');
  }
  
  deleteDocument(): void {
    console.log('Delete document');
  }
}
```

### Example 6: Card with Action Button

```typescript
// Component
@Component({
  selector: 'app-form-card',
  template: `
    <ngx-st-card 
      title="Edit Profile"
      [showHistoryBack]="true"
      [actionButton]="saveButton">
      <form [formGroup]="profileForm">
        <!-- Form fields -->
      </form>
    </ngx-st-card>
  `
})
export class FormCardComponent {
  profileForm = this.fb.group({
    name: [''],
    email: ['']
  });
  
  saveButton: MenuElementModel = {
    label: 'Save Changes',
    icon: 'save',
    action: () => this.save()
  };
  
  constructor(private fb: FormBuilder) {}
  
  save(): void {
    if (this.profileForm.valid) {
      console.log('Saving:', this.profileForm.value);
    }
  }
}
```

### Example 7: Card with Table (No Top Padding)

```typescript
// Component
@Component({
  selector: 'app-data-table-card',
  template: `
    <ngx-st-card 
      title="Products"
      [createLink]="['/products', 'create']"
      createLinkLabel="New Product"
      [noBodyTopPadding]="true">
      <ngx-st-material-table
        [data]="products"
        [initColumns]="columns">
      </ngx-st-material-table>
    </ngx-st-card>
  `
})
export class DataTableCardComponent {
  products = [...];
  columns = [...];
}
```

### Example 8: Card with Multiple Actions

```typescript
// Component
@Component({
  selector: 'app-project-details',
  template: `
    <ngx-st-card 
      [title]="project.name"
      [backLink]="['/projects']"
      [createLink]="['/projects', project.id, 'tasks', 'create']"
      createLinkLabel="Add Task"
      [actionMenu]="projectActions"
      [actionButton]="primaryAction">
      
      <div class="project-info">
        <p>{{ project.description }}</p>
        <p>Status: {{ project.status }}</p>
        <p>Progress: {{ project.progress }}%</p>
      </div>
      
      <h3>Tasks</h3>
      <div *ngFor="let task of project.tasks">
        {{ task.name }}
      </div>
    </ngx-st-card>
  `
})
export class ProjectDetailsComponent {
  project = {
    id: 1,
    name: 'Project Alpha',
    description: 'Important project',
    status: 'In Progress',
    progress: 65,
    tasks: [...]
  };
  
  primaryAction: MenuElementModel = {
    label: 'Complete Project',
    icon: 'check_circle',
    action: () => this.completeProject()
  };
  
  projectActions: MenuElementModel[] = [
    {
      label: 'Edit Project',
      icon: 'edit',
      action: () => this.editProject()
    },
    {
      label: 'Export',
      icon: 'file_download',
      action: () => this.exportProject()
    },
    {
      label: 'Archive',
      icon: 'archive',
      action: () => this.archiveProject()
    },
    {
      label: 'Delete',
      icon: 'delete',
      action: () => this.deleteProject()
    }
  ];
  
  completeProject(): void {
    console.log('Complete project');
  }
  
  editProject(): void {
    console.log('Edit project');
  }
  
  exportProject(): void {
    console.log('Export project');
  }
  
  archiveProject(): void {
    console.log('Archive project');
  }
  
  deleteProject(): void {
    console.log('Delete project');
  }
}
```

### Example 9: Dynamic Title Card

```typescript
// Component
@Component({
  selector: 'app-dynamic-card',
  template: `
    <ngx-st-card 
      [title]="cardTitle"
      [showHistoryBack]="true"
      [actionMenu]="getActions()">
      <div>Content based on {{ entityType }}</div>
    </ngx-st-card>
  `
})
export class DynamicCardComponent implements OnInit {
  entityType = 'user';
  entityId = 123;
  
  get cardTitle(): string {
    return `${this.entityType} #${this.entityId}`;
  }
  
  ngOnInit(): void {
    // Load entity data
  }
  
  getActions(): MenuElementModel[] {
    return [
      {
        label: 'Edit',
        icon: 'edit',
        action: () => this.edit()
      },
      {
        label: 'Delete',
        icon: 'delete',
        action: () => this.delete()
      }
    ];
  }
  
  edit(): void {
    console.log('Edit', this.entityType);
  }
  
  delete(): void {
    console.log('Delete', this.entityType);
  }
}
```

---

## Best Practices

1. **Use descriptive titles**:
   ```html
   title="User Profile"  <!-- Good -->
   title="Details"       <!-- Less descriptive -->
   ```

2. **Choose appropriate navigation**:
   ```html
   <!-- Use backLink for specific routes -->
   [backLink]="['/users']"
   
   <!-- Use showHistoryBack for general back -->
   [showHistoryBack]="true"
   ```

3. **Group related actions in menu**:
   ```typescript
   actionMenu = [
     { label: 'Edit', ... },
     { label: 'Duplicate', ... },
     { label: 'Delete', ... }
   ];
   ```

4. **Use actionButton for primary action**:
   ```typescript
   actionButton = { label: 'Save', icon: 'save', ... };
   ```

5. **Remove top padding for tables**:
   ```html
   [noBodyTopPadding]="true"  <!-- For tables -->
   ```

6. **Provide clear create button labels**:
   ```html
   createLinkLabel="Add User"
   createLinkLabel="New Product"
   ```

---

## MenuElementModel Interface

When using `actionMenu` or `actionButton`:

```typescript
interface MenuElementModel {
  label: string;              // Button/menu item label
  icon?: string;              // Material icon name
  action?: () => void;        // Click handler function
  url?: string[];             // Router link (alternative to action)
  disabled?: boolean;         // Disable the action
  color?: 'primary' | 'accent' | 'warn';  // Button color
}
```

---

## Common Patterns

### Pattern 1: List Card
Card with create button and table content, no top padding.

### Pattern 2: Details Card
Card with back button and action menu for entity operations.

### Pattern 3: Form Card
Card with back button and save action button.

### Pattern 4: Dashboard Card
Simple card with title and content, no actions.

---

## Component Structure

```html
<ngx-st-card>
  <!-- Header (automatic) -->
  ├── Back Button (optional)
  ├── Title
  ├── Create Button (optional)
  ├── Action Button (optional)
  └── Action Menu (optional)
  
  <!-- Body (content projection) -->
  └── Your content here
</ngx-st-card>
```

---

## Styling

The component includes base Material Design card styling. You can override styles:

```css
ngx-st-card {
  /* Customize card appearance */
}

ngx-st-card ::ng-deep .card-header {
  /* Customize header */
}

ngx-st-card ::ng-deep .card-body {
  /* Customize body */
}
```

---

This documentation covers all inputs and usage patterns for the Card component.