npm package: @ng-shangjc/card
Description: Card component source package for ng-shangjc angular components
Author: jc-develop
Latest version: 1.0.1-beta

<p align="center">
<a href="https://juliancallejas.github.io/ng-shangjc-docs">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1772819746/shangjc/shangjc-64-bg-dark_kwzs81.svg" width="307" alt="Shangjc"  /> 
</a>
</p>

# Card Component

A flexible and versatile card component that provides a consistent container for displaying grouped content. Perfect for creating user profiles, product cards, statistics dashboards, and notification panels with customizable styling and comprehensive accessibility support.

## Official Documentation

<a href="https://juliancallejas.github.io/ng-shangjc-docs/?path=/docs/components-card">
    ng-Shangjc docs
</a>

## Features

- 🚀 **Flexible Layout**: Compose cards with header, content, and footer sections or use them independently
- 🎨 **Customizable Styling**: Full Tailwind CSS class support for complete design control
- ♿ **Accessibility**: WAI-ARIA compliant with proper semantic HTML structure
- ⌨️ **Keyboard Navigation**: Full keyboard support with proper focus management
- 🎯 **Type-Safe**: Built with TypeScript for enhanced developer experience
- ⚡ **Performance**: Optimized with OnPush change detection and computed signals
- 📱 **Responsive**: Works seamlessly across all screen sizes and devices
- 🧩 **Component Composition**: Modular subcomponents for maximum flexibility

## Installation

### Step 1: Install the CLI

First, install the ng-shangjc CLI globally or use npx:

```bash
# Install globally
npm install -g @ng-shangjc/cli

# or with yarn
yarn global add @ng-shangjc/cli

# or with pnpm
pnpm install -g @ng-shangjc/cli

# Or use npx without installation
npx @ng-shangjc/cli <command>
```

### Step 2: Initialize your project

If you haven't already, initialize your Angular project for ng-shangjc components:

```bash
ng-shangjc init
```

This will create a `shangjc.config.json` file and set up your project for component installations.

### Step 3: Install the component

Install the card component into your project:

```bash
ng-shangjc install card
```

The component will be installed in the configured path (default: `src/ui/shangjc`). Adjust the import path in your components based on your project structure and the configured installation path.

## Import

After installation, import the components from your configured installation path. The examples below use the default path `src/ui/shangjc` - adjust the path according to your project structure and configuration.

### Standalone Components (Recommended)

Import and use the individual components directly in your standalone components:

```typescript
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { 
  CardComponent, 
  CardHeaderComponent,
  CardTitleComponent,
  CardDescriptionComponent,
  CardContentComponent,
  CardFooterComponent
} from './ui/shangjc/card';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    CardComponent,
    CardHeaderComponent,
    CardTitleComponent,
    CardDescriptionComponent,
    CardContentComponent,
    CardFooterComponent
  ],
  template: `
    <ng-shangjc-card>
      <ng-shangjc-card-header>
        <ng-shangjc-card-title>Card Title</ng-shangjc-card-title>
        <ng-shangjc-card-description>
          A description of what this card is about
        </ng-shangjc-card-description>
      </ng-shangjc-card-header>
      <ng-shangjc-card-content>
        <p>This is the main content of the card.</p>
      </ng-shangjc-card-content>
      <ng-shangjc-card-footer>
        <button>Action</button>
      </ng-shangjc-card-footer>
    </ng-shangjc-card>
  `
})
export class ExampleComponent { }
```

### Using NgModule (Legacy)

If you're using NgModules, import the `CardModule`:

```typescript
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { CardModule } from './ui/shangjc/card';

@NgModule({
  declarations: [YourComponent],
  imports: [
    CommonModule,
    CardModule
  ]
})
export class YourModule { }
```

Then use the components in your templates:

```html
<ng-shangjc-card>
  <!-- Component content -->
</ng-shangjc-card>
```

## Basic Usage

### Default Example

A complete, working example showing the most common use case:

```typescript
import { Component } from '@angular/core';
import { 
  CardComponent, 
  CardHeaderComponent,
  CardTitleComponent,
  CardDescriptionComponent,
  CardContentComponent,
  CardFooterComponent
} from './ui/shangjc/card';

@Component({
  selector: 'app-default-card',
  standalone: true,
  imports: [
    CardComponent,
    CardHeaderComponent,
    CardTitleComponent,
    CardDescriptionComponent,
    CardContentComponent,
    CardFooterComponent
  ],
  template: `
    <ng-shangjc-card>
      <ng-shangjc-card-header>
        <ng-shangjc-card-title>Card Title</ng-shangjc-card-title>
        <ng-shangjc-card-description>
          Card description goes here. This provides additional context about the card content.
        </ng-shangjc-card-description>
      </ng-shangjc-card-header>
      <ng-shangjc-card-content>
        <p>This is the main content area of the card. You can put any content here.</p>
      </ng-shangjc-card-content>
      <ng-shangjc-card-footer>
        <button>Action</button>
      </ng-shangjc-card-footer>
    </ng-shangjc-card>
  `
})
export class DefaultCardComponent {}
```

### Alternative Usage Patterns

#### Simple Card
```html
<ng-shangjc-card>
  <ng-shangjc-card-content class="py-2">
    <p>A simple card with just content. No header or footer needed.</p>
  </ng-shangjc-card-content>
</ng-shangjc-card>
```

#### Card with Image
```html
<ng-shangjc-card class="w-[350px]">
  <div class="aspect-video bg-gradient-to-r from-blue-500 to-purple-600 rounded-t-lg"></div>
  <ng-shangjc-card-header>
    <ng-shangjc-card-title>Beautiful Gradient</ng-shangjc-card-title>
    <ng-shangjc-card-description>
      A card with a beautiful gradient background image.
    </ng-shangjc-card-description>
  </ng-shangjc-card-header>
  <ng-shangjc-card-content>
    <p>This card demonstrates how to include images or visual elements at the top.</p>
  </ng-shangjc-card-content>
  <ng-shangjc-card-footer>
    <button variant="outline" class="w-full">View Details</button>
  </ng-shangjc-card-footer>
</ng-shangjc-card>
```

## Advanced Usage

### Product Card
```typescript
import { Component } from '@angular/core';
import { 
  CardComponent, 
  CardHeaderComponent,
  CardTitleComponent,
  CardDescriptionComponent,
  CardContentComponent,
  CardFooterComponent
} from './ui/shangjc/card';

@Component({
  selector: 'app-product-card',
  standalone: true,
  imports: [
    CardComponent,
    CardHeaderComponent,
    CardTitleComponent,
    CardDescriptionComponent,
    CardContentComponent,
    CardFooterComponent
  ],
  template: `
    <ng-shangjc-card class="w-[300px]">
      <div class="aspect-square bg-gray-100 rounded-t-lg flex items-center justify-center overflow-hidden">
        <img src="product-image.jpg" alt="Product" class="w-full h-full object-cover" />
      </div>
      <ng-shangjc-card-header>
        <ng-shangjc-card-title>Product Name</ng-shangjc-card-title>
        <ng-shangjc-card-description>
          High-quality product with amazing features.
        </ng-shangjc-card-description>
      </ng-shangjc-card-header>
      <ng-shangjc-card-content>
        <div class="flex items-center justify-between">
          <span class="text-2xl font-bold">$99.99</span>
          <div class="flex items-center">
            <span class="text-yellow-400">★★★★★</span>
            <span class="ml-1 text-sm text-gray-600">(4.8)</span>
          </div>
        </div>
      </ng-shangjc-card-content>
      <ng-shangjc-card-footer>
        <button class="w-full">Add to Cart</button>
      </ng-shangjc-card-footer>
    </ng-shangjc-card>
  `
})
export class ProductCardComponent {}
```

### Statistics Dashboard
```typescript
import { Component } from '@angular/core';
import { 
  CardComponent, 
  CardHeaderComponent,
  CardTitleComponent,
  CardContentComponent
} from './ui/shangjc/card';

@Component({
  selector: 'app-stats-dashboard',
  standalone: true,
  imports: [
    CardComponent,
    CardHeaderComponent,
    CardTitleComponent,
    CardContentComponent
  ],
  template: `
    <div class="grid grid-cols-1 md:grid-cols-3 gap-4 w-full max-w-3xl">
      <ng-shangjc-card>
        <ng-shangjc-card-header class="flex flex-row items-center justify-between space-y-0 pb-2">
          <ng-shangjc-card-title class="text-sm font-medium">Total Revenue</ng-shangjc-card-title>
          <svg class="h-4 w-4 text-muted-foreground" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 2v20m9-9H3"/>
          </svg>
        </ng-shangjc-card-header>
        <ng-shangjc-card-content>
          <div class="text-2xl font-bold">$45,231.89</div>
          <p class="text-xs text-muted-foreground">+20.1% from last month</p>
        </ng-shangjc-card-content>
      </ng-shangjc-card>
      
      <ng-shangjc-card>
        <ng-shangjc-card-header class="flex flex-row items-center justify-between space-y-0 pb-2">
          <ng-shangjc-card-title class="text-sm font-medium">Subscriptions</ng-shangjc-card-title>
          <svg class="h-4 w-4 text-muted-foreground" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z"/>
          </svg>
        </ng-shangjc-card-header>
        <ng-shangjc-card-content>
          <div class="text-2xl font-bold">+2350</div>
          <p class="text-xs text-muted-foreground">+180.1% from last month</p>
        </ng-shangjc-card-content>
      </ng-shangjc-card>
    </div>
  `
})
export class StatsDashboardComponent {}
```

## API Reference

### CardComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card |

### CardHeaderComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card header |

### CardTitleComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card title |

### CardDescriptionComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card description |

### CardContentComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card content |

### CardFooterComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes to apply to the card footer |

## Accessibility

- **Keyboard Navigation**: Full support for Tab, Shift+Tab, Enter, Space, and Arrow keys
- **ARIA Attributes**: Proper ARIA labels, roles, and states for screen readers
- **Focus Management**: Visible focus indicators and proper focus handling
- **Screen Reader**: Compatible with all major screen readers
- **Semantic Structure**: Uses proper HTML semantic elements (`h3` for titles, `p` for descriptions)

### ARIA Features

- `role="region"` on content areas for landmark navigation
- Semantic heading structure for proper document outline
- Proper color contrast ratios for text readability
- Focus visible states for keyboard navigation

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Contributing

See the main project [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

---

**Part of ng-shangjc component library** • [Documentation](https://juliancallejas.github.io/ng-shangjc-docs/)

<p align="center">
<a href="https://github.com/JulianCallejas">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1740784502/github-jc-develop/JC-LOGO-Horizontal-170-50-thin-github_uu3b5n.svg" width="170" alt="{ jc - develop }"  /> 
</a>
</p>