npm package: @ng-shangjc/button
Description: Button component source package for ng-shangjc angular components
Author: jc-develop
Latest version: 1.0.8-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>

# Button Component

A versatile and highly customizable button component with multiple variants, sizes, and states. Built with Angular signals and TailwindCSS for modern, reactive UI development. Perfect for any application needing reliable, accessible button interactions.

## Official Documentation

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

## Features

- 🚀 **Multiple Variants**: 6 visual styles (default, destructive, outline, secondary, ghost, link) for any design context
- 🎨 **Flexible Sizing**: 4 size options (sm, default, lg, icon) to match your layout needs
- ⚡ **Signal-based State**: Modern Angular signals for reactive, performant updates
- ♿ **Accessibility**: Full ARIA support, keyboard navigation, and screen reader compatibility
- ⌨️ **Keyboard Navigation**: Complete support for Tab, Enter, Space, and Escape keys
- 🎯 **Type-Safe**: Full TypeScript support with proper interfaces and type checking
- 🎨 **Customizable**: Easy theming with CSS variables and custom class support
- 🔧 **Composition**: Use `asChild` prop to compose with other elements while maintaining button behavior
- 📱 **Responsive**: Adapts seamlessly to different screen sizes and devices
- ⚡ **Performance**: Optimized with OnPush change detection and efficient rendering

## 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 button component into your project:

```bash
ng-shangjc install button
```

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 button component directly in your standalone components:

```typescript
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    ButtonComponent
  ],
  template: `
    <ng-shangjc-button 
      variant="default" 
      size="default"
      (click)="handleClick()">
      Click me
    </ng-shangjc-button>
  `
})
export class ExampleComponent {
  handleClick() {
    console.log('Button clicked!');
  }
}
```

### Using NgModule (Legacy)

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

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

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

Then use the button in your templates:

```html
<ng-shangjc-button variant="secondary" size="lg">Click me</ng-shangjc-button>
```

## Basic Usage

### Default Example

```typescript
import { Component } from '@angular/core';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <ng-shangjc-button>Click me</ng-shangjc-button>
  `,
})
export class ExampleComponent {}
```

### Alternative Usage Patterns

#### With Variants

```html
<ng-shangjc-button variant="default">Default</ng-shangjc-button>
<ng-shangjc-button variant="secondary">Secondary</ng-shangjc-button>
<ng-shangjc-button variant="destructive">Destructive</ng-shangjc-button>
<ng-shangjc-button variant="outline">Outline</ng-shangjc-button>
<ng-shangjc-button variant="ghost">Ghost</ng-shangjc-button>
<ng-shangjc-button variant="link">Link</ng-shangjc-button>
```

#### With Sizes

```html
<ng-shangjc-button size="sm">Small</ng-shangjc-button>
<ng-shangjc-button size="default">Default</ng-shangjc-button>
<ng-shangjc-button size="lg">Large</ng-shangjc-button>
<ng-shangjc-button size="icon">
  <svg class="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6v6m0 0v6m0-6h6m-6 0H6"/>
  </svg>
</ng-shangjc-button>
```

## Advanced Usage

### Composing with asChild

The `asChild` prop allows you to compose the button with other elements while maintaining button styling and behavior:

```typescript
import { Component } from '@angular/core';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-as-child-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <!-- As a link -->
    <ng-shangjc-button variant="outline" [asChild]="true">
      <a href="/dashboard" class="no-underline">
        Go to Dashboard
      </a>
    </ng-shangjc-button>

    <!-- With custom element -->
    <ng-shangjc-button [asChild]="true" (click)="handleCustomClick()">
      <div class="flex items-center gap-2 cursor-pointer">
        <svg class="h-4 w-4">...</svg>
        <span>Custom Element</span>
      </div>
    </ng-shangjc-button>
  `
})
export class AsChildExampleComponent {
  handleCustomClick() {
    console.log('Custom element clicked!');
  }
}
```

### Loading States

```typescript
import { Component, signal } from '@angular/core';
import { ButtonComponent } from './ui/shangjc/button';

@Component({
  selector: 'app-loading-example',
  standalone: true,
  imports: [ButtonComponent],
  template: `
    <ng-shangjc-button [disabled]="isLoading()" (click)="submit()">
      @if (isLoading()) {
        <svg class="mr-2 h-4 w-4 animate-spin" fill="none" viewBox="0 0 24 24">
          <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
          <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
        </svg>
        Loading...
      } @else {
        Submit
      }
    </ng-shangjc-button>
  `
})
export class LoadingExampleComponent {
  isLoading = signal(false);

  async submit() {
    this.isLoading.set(true);
    // Simulate API call
    await new Promise(resolve => setTimeout(resolve, 2000));
    this.isLoading.set(false);
  }
}
```

## API Reference

### ButtonComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `variant` | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | The visual style variant of the button |
| `size` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'default'` | The size of the button |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | The HTML button type |
| `disabled` | `boolean` | `false` | Whether the button is disabled |
| `asChild` | `boolean` | `false` | Whether to render as child element (composition) |
| `class` | `string` | `''` | Additional CSS classes to apply |

### Events

| Event | Type | Description |
|-------|------|-------------|
| `click` | `EventEmitter<Event>` | Emitted when button is clicked (standard DOM click event) |

## Accessibility

- **Keyboard Navigation**: Full support for Tab, Shift+Tab, Enter, Space, and Escape keys
- **ARIA Attributes**: Proper ARIA labels, roles, and states automatically applied
- **Focus Management**: Visible focus indicators and proper focus handling
- **Screen Reader**: Compatible with screen readers and assistive technologies
- **Semantic Structure**: Uses proper HTML semantic elements and button roles

### ARIA Features

- `role="button"` (implicit on button element)
- `tabindex="0"` (implicit for keyboard navigation)
- `aria-disabled="true"` when disabled state is active
- `aria-expanded` support for toggle button patterns
- Focus-visible styles for keyboard navigation
- High contrast mode support
- Screen reader announcements for state changes

## 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>