dga-ui-lib/README.md

A dga/ui-inspired Angular component library with full developer ownership

# DGA UI Library

A modern, accessible Angular component library inspired by dga/ui philosophy. Built with developer ownership, customizability, and zero vendor lock-in in mind.

## Philosophy

Unlike traditional component libraries, DGA UI Library gives you **ownership** of your components:

- 🎯 **Copy-paste friendly** - Components are added directly to your project
- 🎨 **Fully customizable** - Modify styles, behavior, and structure as needed
- ♿ **Accessibility-first** - WCAG 2.1 AA compliant primitives
- 🚀 **Zero vendor lock-in** - No runtime dependencies on our library
- 📦 **Bootstrap utilities** - Leverages Bootstrap's utility system
- 🔧 **TypeScript** - Full type safety and IntelliSense support

## Installation

Install the library and its peer dependencies:

```bash
npm install dga-ui-lib bootstrap clsx class-variance-authority
```

Or use the automatic setup:

```bash
ng add dga-ui-lib
```

## Adding Components

Add individual components to your project:

```bash
npx dga-ui-lib add button
```

This copies the component files directly to your project at `src/app/components/` (configurable).

## Usage

After adding a component, use it in your templates:

```html
<!-- Basic usage -->
<app-button>Click me</app-button>

<!-- With variants -->
<app-button variant="secondary" size="lg">
  Large secondary button
</app-button>

<!-- With custom classes -->
<app-button additionalClasses="my-custom-class">
  Custom styled button  
</app-button>
```

## Customization

Since components are copied to your project, you can:

1. **Modify styles** - Edit the `.scss` files directly
2. **Add new variants** - Extend the `buttonVariants` configuration
3. **Change behavior** - Modify the component logic
4. **Add features** - Extend components with your own functionality

### Example: Custom Button Variant

```typescript
// In your copied button.component.ts
const buttonVariants = cva(
  // ... base classes
  {
    variants: {
      variant: {
        default: '...',
        secondary: '...',
        // Add your custom variant
        gradient: 'bg-gradient-to-r from-purple-500 to-pink-500 text-white'
      }
    }
  }
);
```

## Available Components

- [x] **Button** - Flexible button component with multiple variants
- [ ] **Input** - Coming soon
- [ ] **Card** - Coming soon
- [ ] **Dialog** - Coming soon

## Development

This library follows modern Angular practices:

- ✅ Standalone components
- ✅ Signal-based reactivity (when available)
- ✅ OnPush change detection
- ✅ Strict TypeScript configuration
- ✅ Accessibility testing
- ✅ Unit tests included

## Contributing

1. Fork the repository
2. Create your feature branch
3. Add tests for your changes
4. Ensure accessibility compliance
5. Submit a pull request

## License

MIT License - see LICENSE file for details.