# CCL UI Components - Usage Guide

A comprehensive guide for installing, configuring, and using the CCL UI Components library with theming support.

## Table of Contents

- [Quick Start](#quick-start)
- [Installation](#installation)
- [Registry Configuration](#registry-configuration)
- [Basic Usage](#basic-usage)
- [Theming & Customization](#theming--customization)
- [Component Examples](#component-examples)
- [Troubleshooting](#troubleshooting)
- [Migration Guide](#migration-guide)

## Quick Start

Get up and running with CCL UI Components in 3 steps:

```bash
# 1. Configure npm registry
npm config set @Crystal-Code-Labs:registry https://npm.pkg.github.com/

# 2. Install the package
npm install @Crystal-Code-Labs/ccl-ui-components

# 3. Import styles in your app
```

```css
/* In your global styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
```

```typescript
// In your component
import { ButtonComponent } from '@Crystal-Code-Labs/ccl-ui-components';

@Component({
  imports: [ButtonComponent],
  template: '<ccl-button label="Hello World"></ccl-button>'
})
export class MyComponent {}
```

## Installation

### Prerequisites

- Node.js 18+ and npm 9+
- GitHub account with access to this repository
- Personal Access Token (PAT) with `read:packages` scope

### Step 1: Configure npm Registry

Create or update your `.npmrc` file:

**Global configuration** (`~/.npmrc`):
```ini
@Crystal-Code-Labs:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true
```

**Project configuration** (`.npmrc` in your project root):
```ini
@Crystal-Code-Labs:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true
```

### Step 2: Set Up Authentication

1. Generate a GitHub Personal Access Token:
   - Go to GitHub Settings → Developer settings → Personal access tokens
   - Create a new token with `read:packages` scope
   - Copy the token

2. Set the token as an environment variable:
   ```bash
   export GITHUB_TOKEN=your_token_here
   ```

3. Or add it directly to your `.npmrc` (not recommended for production):
   ```ini
   //npm.pkg.github.com/:_authToken=ghp_your_token_here
   ```

### Step 3: Install the Package

```bash
npm install @Crystal-Code-Labs/ccl-ui-components
```

### Step 4: Import Styles

Add the required CSS imports to your application's global styles:

```css
/* src/styles.css or src/styles.scss */

/* Base design tokens (required) */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';

/* Default theme (Naked) */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Optional: Brand theme override */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/brandA.css';
```

## Registry Configuration

### GitHub Packages Registry

The CCL UI Components library is published to GitHub Packages. This requires specific npm configuration:

```ini
# .npmrc configuration
@Crystal-Code-Labs:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true
```

### Alternative Registry Setup

If you're using a different private registry:

```ini
@Crystal-Code-Labs:registry=https://your-registry.com/
//your-registry.com/:_authToken=${YOUR_TOKEN}
always-auth=true
```

### Verification

Verify your installation:

```bash
npm list @Crystal-Code-Labs/ccl-ui-components
```

## Basic Usage

### Import Components

```typescript
import { 
  ButtonComponent, 
  InputComponent, 
  ModalComponent,
  ToastComponent,
  LoadingComponent,
  BadgeComponent
} from '@Crystal-Code-Labs/ccl-ui-components';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    ButtonComponent,
    InputComponent,
    ModalComponent,
    ToastComponent,
    LoadingComponent,
    BadgeComponent
  ],
  template: `
    <ccl-button label="Click me" (clicked)="onClick()"></ccl-button>
    <ccl-input label="Email" placeholder="Enter your email"></ccl-input>
  `
})
export class AppComponent {
  onClick() {
    console.log('Button clicked!');
  }
}
```

### Component Naming Convention

All components use the `ccl-` prefix:
- `<ccl-button>` - Button component
- `<ccl-input>` - Input component
- `<ccl-modal>` - Modal component
- `<ccl-toast>` - Toast component
- `<ccl-loading>` - Loading component
- `<ccl-badge>` - Badge component

## Theming & Customization

### Available Themes

1. **Naked Theme** (Default) - Clean, minimal design
2. **BrandA Theme** - Corporate branding with custom colors
3. **Custom Overrides** - Your own theme modifications

### Using Default Themes

```css
/* Use Naked theme (default) */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Override with BrandA theme */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/brandA.css';
```

### Custom Theme Overrides

Override any design token in your global styles:

```css
/* src/styles.css */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Custom overrides */
:root, :host {
  /* Primary color override */
  --color-primary-default: #ff6600;
  --color-primary-500: #ff6600;
  --color-primary-600: #e55a00;
  
  /* Typography override */
  --typography-font-family-default: 'Inter', system-ui, sans-serif;
  --typography-font-size-md: 1rem;
  
  /* Spacing override */
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* Border radius override */
  --radius-md: 8px;
  --radius-lg: 12px;
}
```

### Scoped Theming

Apply themes to specific sections of your application:

```html
<div class="brand-section">
  <ccl-button label="Brand Button"></ccl-button>
</div>

<div class="custom-section">
  <ccl-button label="Custom Button"></ccl-button>
</div>
```

```css
.brand-section {
  --color-primary-default: #f97316; /* Brand orange */
}

.custom-section {
  --color-primary-default: #8b5cf6; /* Custom purple */
  --radius-md: 16px; /* Rounded corners */
}
```

### Design Token Reference

#### Colors
```css
/* Primary colors */
--color-primary-default: #0055ff;
--color-primary-500: #0055ff;
--color-primary-600: #0044cc;

/* Secondary colors */
--color-secondary-default: #6b7280;
--color-secondary-500: #6b7280;

/* Semantic colors */
--color-success-default: #10b981;
--color-warning-default: #f59e0b;
--color-error-default: #ef4444;

/* Neutral scale */
--color-neutral-50: #f9fafb;
--color-neutral-100: #f3f4f6;
/* ... up to ... */
--color-neutral-900: #111827;
```

#### Typography
```css
/* Font families */
--typography-font-family-default: system-ui, sans-serif;
--typography-font-family-sans: system-ui, sans-serif;
--typography-font-family-serif: Georgia, serif;

/* Font sizes */
--typography-font-size-xs: 0.75rem;
--typography-font-size-sm: 0.875rem;
--typography-font-size-md: 1rem;
--typography-font-size-lg: 1.125rem;
--typography-font-size-xl: 1.25rem;

/* Font weights */
--typography-font-weight-light: 300;
--typography-font-weight-regular: 400;
--typography-font-weight-medium: 500;
--typography-font-weight-semibold: 600;
--typography-font-weight-bold: 700;
```

#### Spacing
```css
/* Spacing scale */
--spacing-0: 0;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-3: 0.75rem;
--spacing-4: 1rem;
--spacing-5: 1.25rem;
--spacing-6: 1.5rem;
--spacing-8: 2rem;
--spacing-10: 2.5rem;
--spacing-12: 3rem;
--spacing-16: 4rem;
--spacing-20: 5rem;
--spacing-24: 6rem;
```

#### Border Radius
```css
--radius-none: 0;
--radius-sm: 0.25rem;
--radius-md: 0.375rem;
--radius-lg: 0.5rem;
--radius-xl: 0.75rem;
--radius-2xl: 1rem;
--radius-full: 9999px;
```

## Component Examples

### Button Component

```html
<!-- Basic button -->
<ccl-button label="Save"></ccl-button>

<!-- Button with variants -->
<ccl-button variant="primary" label="Primary"></ccl-button>
<ccl-button variant="secondary" label="Secondary"></ccl-button>
<ccl-button variant="tertiary" label="Tertiary"></ccl-button>
<ccl-button variant="destructive" label="Delete"></ccl-button>

<!-- Button with sizes -->
<ccl-button size="sm" label="Small"></ccl-button>
<ccl-button size="md" label="Medium"></ccl-button>
<ccl-button size="lg" label="Large"></ccl-button>

<!-- Button with states -->
<ccl-button [disabled]="true" label="Disabled"></ccl-button>
<ccl-button [loading]="isLoading" label="Loading"></ccl-button>

<!-- Button with events -->
<ccl-button 
  label="Click me" 
  (clicked)="onButtonClick()">
</ccl-button>
```

### Input Component

```html
<!-- Basic input -->
<ccl-input label="Email" placeholder="Enter your email"></ccl-input>

<!-- Input with validation -->
<ccl-input 
  label="Password" 
  type="password"
  [error]="hasError"
  errorMessage="Password is required"
  helperText="Must be at least 8 characters">
</ccl-input>

<!-- Input with form control -->
<ccl-input 
  label="Username"
  [formControl]="usernameControl">
</ccl-input>
```

### Modal Component

```html
<!-- Basic modal -->
<ccl-modal 
  [isOpen]="showModal"
  title="Confirm Action"
  (closed)="onModalClose()">
  <p>Are you sure you want to proceed?</p>
  <ccl-button label="Cancel" (clicked)="onModalClose()"></ccl-button>
  <ccl-button label="Confirm" (clicked)="onConfirm()"></ccl-button>
</ccl-modal>

<!-- Modal with different sizes -->
<ccl-modal 
  [isOpen]="showModal"
  title="Large Modal"
  size="lg">
  <p>This is a large modal with more content.</p>
</ccl-modal>
```

### Toast Component

```html
<!-- Basic toast -->
<ccl-toast 
  variant="success"
  message="Data saved successfully!"
  [duration]="3000">
</ccl-toast>

<!-- Toast with title -->
<ccl-toast 
  variant="error"
  title="Error"
  message="Failed to save data. Please try again."
  [dismissible]="true">
</ccl-toast>
```

### Loading Component

```html
<!-- Spinner loading -->
<ccl-loading 
  variant="spinner" 
  size="md" 
  label="Loading data">
</ccl-loading>

<!-- Progress bar loading -->
<ccl-loading 
  variant="bar" 
  label="Uploading file...">
</ccl-loading>

<!-- Pulse loading -->
<ccl-loading 
  variant="pulse" 
  size="sm" 
  label="Syncing">
</ccl-loading>
```

### Badge Component

```html
<!-- Basic badge -->
<ccl-badge label="New"></ccl-badge>

<!-- Badge with variants -->
<ccl-badge variant="success" label="Active"></ccl-badge>
<ccl-badge variant="error" label="Error"></ccl-badge>
<ccl-badge variant="warning" label="Warning"></ccl-badge>

<!-- Badge with count -->
<ccl-badge variant="info" [count]="5" label="Notifications"></ccl-badge>

<!-- Dismissible badge -->
<ccl-badge 
  variant="default" 
  label="Dismissible" 
  [dismissible]="true"
  (onDismiss)="onBadgeDismiss()">
</ccl-badge>
```

## Troubleshooting

### Common Issues

#### 1. Authentication Failed

**Error**: `npm ERR! 401 Unauthorized`

**Solution**:
```bash
# Check your .npmrc configuration
cat .npmrc

# Verify your GitHub token
echo $GITHUB_TOKEN

# Test authentication
npm whoami --registry=https://npm.pkg.github.com/
```

#### 2. Package Not Found

**Error**: `npm ERR! 404 Not Found`

**Solution**:
```bash
# Verify registry configuration
npm config get @Crystal-Code-Labs:registry

# Should return: https://npm.pkg.github.com/

# Clear npm cache
npm cache clean --force

# Try installing again
npm install @Crystal-Code-Labs/ccl-ui-components
```

#### 3. Theme Not Applied

**Issue**: Components appear unstyled

**Solution**:
```css
/* Ensure you've imported the base tokens */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/tokens.css';

/* Import a theme */
@import '@Crystal-Code-Labs/ccl-ui-components/styles/naked.css';

/* Check for CSS conflicts */
/* Make sure your overrides come after theme imports */
```

#### 4. Component Not Rendering

**Issue**: Component doesn't appear in DOM

**Solution**:
```typescript
// Ensure component is imported
import { ButtonComponent } from '@Crystal-Code-Labs/ccl-ui-components';

// Add to imports array
@Component({
  imports: [ButtonComponent], // ← Make sure this is included
  template: '<ccl-button label="Test"></ccl-button>'
})
```

#### 5. TypeScript Errors

**Error**: `Cannot find module '@Crystal-Code-Labs/ccl-ui-components'`

**Solution**:
```bash
# Install types
npm install --save-dev @types/node

# Restart TypeScript server in your IDE
# Or restart your development server
```

### Debug Mode

Enable debug logging to troubleshoot issues:

```typescript
// In your main.ts or app.component.ts
import { enableProdMode } from '@angular/core';

if (!environment.production) {
  // Enable debug mode for CCL components
  console.log('CCL UI Components loaded');
}
```

### Getting Help

1. **Check the documentation**: Review component-specific docs in `/docs/`
2. **GitHub Issues**: Report bugs or request features

## Migration Guide

### From Previous Versions

#### Version 0.2.x to 0.3.x

**Breaking Changes**:
- Some component APIs have been updated

**Migration Steps**:

### From Other UI Libraries

#### From Angular Material

```typescript
// Angular Material
import { MatButtonModule } from '@angular/material/button';
import { MatInputModule } from '@angular/material/input';

// CCL UI Components
import { ButtonComponent, InputComponent } from '@Crystal-Code-Labs/ccl-ui-components';
```

```html
<!-- Angular Material -->
<button mat-button>Click me</button>
<mat-form-field>
  <input matInput placeholder="Email">
</mat-form-field>

<!-- CCL UI Components -->
<ccl-button label="Click me"></ccl-button>
<ccl-input placeholder="Email"></ccl-input>
```

#### From Bootstrap

```html
<!-- Bootstrap -->
<button class="btn btn-primary">Click me</button>
<input class="form-control" placeholder="Email">

<!-- CCL UI Components -->
<ccl-button variant="primary" label="Click me"></ccl-button>
<ccl-input placeholder="Email"></ccl-input>
```

---

## Next Steps

- Explore [Component Documentation](./README.md) for detailed API references
- Check out [Design Tokens](./css-variables.md) for theming options
- Review [Accessibility Guidelines](./accessibility.md) for best practices