@dishamahajan36/ui-components/README.md

A collection of reusable Angular UI components built with Spartan UI and Tailwind CSS.

# @dishamahajan36/ui-components

A collection of reusable Angular UI components built with Spartan UI and Tailwind CSS. This library provides modern, accessible, and customizable components for Angular 19+ applications.

## Features

- 🚀 **Angular 19+** - Built with the latest Angular features including signals
- 🎨 **Tailwind CSS** - Styled with utility-first CSS framework
- ♿ **Accessible** - Built with accessibility in mind
- 🔧 **Customizable** - Easy to customize with Tailwind classes
- 📦 **Tree-shakable** - Only import what you need
- 🎭 **Storybook** - Interactive component documentation

## Installation

Install the library using npm:

```bash
npm install @dishamahajan36/ui-components
```

### Peer Dependencies

Make sure you have the required peer dependencies installed:

```bash
npm install @angular/common@^19.2.0 @angular/core@^19.2.0 @angular/cdk@^19.2.0
```

### Tailwind CSS Setup

This library requires Tailwind CSS to be configured in your project. If you haven't set it up yet:

1. Install Tailwind CSS:
```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init
```

2. Configure your `tailwind.config.js`:
```javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{html,ts}",
    "./node_modules/@dishamahajan36/ui-components/**/*.{js,ts}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

3. Add Tailwind directives to your global styles (`src/styles.css`):
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

## Usage

### Importing Components

You can import components individually or use the public API:

```typescript
// Individual import
import { ButtonComponent } from '@dishamahajan36/ui-components';

// Or import from public API
import { ButtonComponent } from '@dishamahajan36/ui-components';
```

### Using in Templates

Since all components are standalone, you can import them directly in your component:

```typescript
import { Component } from '@angular/core';
import { ButtonComponent } from '@dishamahajan36/ui-components';

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

## Components

### ButtonComponent

A versatile button component with multiple variants and sizes.

#### Basic Usage

```html
<ui-button>Default Button</ui-button>
```

#### Properties

All properties are implemented using Angular's modern signal-based inputs for optimal performance and reactivity.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `variant` | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Visual style variant |
| `size` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'default'` | Button size |
| `disabled` | `boolean` | `false` | Whether the button is disabled |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML button type |
| `customClass` | `string` | `''` | Additional CSS classes |

#### Events

Events are implemented using Angular's modern signal-based outputs for better performance and type safety.

| Event | Type | Description |
|-------|------|-------------|
| `clicked` | `MouseEvent` | Emitted when button is clicked (not emitted when disabled) |

#### Examples

**Different Variants:**
```html
<ui-button variant="default">Default</ui-button>
<ui-button variant="destructive">Destructive</ui-button>
<ui-button variant="outline">Outline</ui-button>
<ui-button variant="secondary">Secondary</ui-button>
<ui-button variant="ghost">Ghost</ui-button>
<ui-button variant="link">Link</ui-button>
```

**Different Sizes:**
```html
<ui-button size="sm">Small</ui-button>
<ui-button size="default">Default</ui-button>
<ui-button size="lg">Large</ui-button>
<ui-button size="icon">⚙️</ui-button>
```

**With Custom Classes:**
```html
<ui-button customClass="shadow-lg transform hover:scale-105">
  Custom Styled
</ui-button>
```

**Form Usage:**
```html
<form>
  <ui-button type="submit" variant="default">Submit</ui-button>
  <ui-button type="reset" variant="outline">Reset</ui-button>
  <ui-button type="button" variant="secondary">Cancel</ui-button>
</form>
```

**With Content Projection:**
```html
<ui-button variant="default">
  <span style="display: flex; align-items: center; gap: 0.5rem;">
    <span>📁</span>
    Save Document
  </span>
</ui-button>
```

**Loading State:**
```html
<ui-button [disabled]="isLoading" (clicked)="handleSubmit()">
  {{ isLoading ? 'Loading...' : 'Submit' }}
</ui-button>
```

## Development

### Building the Library

To build the library for distribution:

```bash
ng build ui-components
```

The build artifacts will be stored in the `dist/ui-components` directory.

### Running Storybook

To view the interactive component documentation:

```bash
npm run storybook
```

This will start Storybook on `http://localhost:6006` where you can explore all components and their variants.

### Running Tests

Execute the unit tests:

```bash
ng test ui-components
```

### Code Scaffolding

To generate a new component:

```bash
ng generate component component-name --project=ui-components
```

## Publishing

### Building for Production

1. Build the library:
```bash
ng build ui-components --configuration production
```

2. Navigate to the dist directory:
```bash
cd dist/ui-components
```

3. Publish to npm:
```bash
npm publish
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Roadmap

- [ ] Add more UI components (Input, Card, Dialog, etc.)
- [ ] Add dark mode support
- [ ] Add animation utilities
- [ ] Add form validation components
- [ ] Add data table component

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/your-username/ui-components/issues) on GitHub.

## Changelog

### v0.0.2
- Initial release with ButtonComponent
- Storybook documentation
- Tailwind CSS integration
- Angular 19 support

---

Built with ❤️ using [Angular](https://angular.dev) and [Tailwind CSS](https://tailwindcss.com)