# Installation Guide

Complete installation guide for CCL UI Components library.

## Prerequisites

- **Node.js**: Version 18 or higher
- **npm**: Version 9 or higher  
- **GitHub Account**: With access to this repository
- **Personal Access Token**: With `read:packages` scope

## Quick Installation

```bash
# 1. Configure npm registry
npm config set @<<Scope/Organisation>>:registry https://npm.pkg.github.com/

# 2. Set authentication token
export GITHUB_TOKEN=your_token_here

# 3. Install the package
npm install @<<Scope/Organisation>>/ccl-ui-components

# 4. Import styles in your app
```

## Step-by-Step Installation

### Step 1: Create GitHub Personal Access Token

1. Go to [GitHub Settings](https://github.com/settings/tokens)
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a descriptive name: "CCL UI Components Access"
4. Select scopes:
   - ✅ `read:packages` (required for installation)
   - ✅ `write:packages` (optional, for publishing)
5. Click "Generate token"
6. **Copy the token immediately** (you won't see it again)

### Step 2: Configure npm Registry

#### Option A: Global Configuration (Recommended)

Create or update `~/.npmrc`:

```ini
@<<Scope/Organisation>>:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true
```

#### Option B: Project Configuration

Create `.npmrc` in your project root:

```ini
@<<Scope/Organisation>>:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true
```

**⚠️ Security Note**: Never commit real tokens to version control. Use environment variables instead.

### Step 3: Set Environment Variable

#### macOS/Linux
```bash
export GITHUB_TOKEN=ghp_your_token_here
```

#### Windows (Command Prompt)
```cmd
set GITHUB_TOKEN=ghp_your_token_here
```

#### Windows (PowerShell)
```powershell
$env:GITHUB_TOKEN="ghp_your_token_here"
```

#### Permanent Setup (macOS/Linux)
Add to your `~/.bashrc` or `~/.zshrc`:
```bash
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.bashrc
source ~/.bashrc
```

### Step 4: Install the Package

```bash
npm install @<<Scope/Organisation>>/ccl-ui-components
```

### Step 5: Verify Installation

```bash
# Check if package is installed
npm list @<<Scope/Organisation>>/ccl-ui-components

# Verify registry configuration
npm config get @<<Scope/Organisation>>:registry
# Should return: https://npm.pkg.github.com/

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

### Step 6: Import Styles

Add to your global styles file (`src/styles.css` or `src/styles.scss`):

```css
/* Base design tokens (required) */
@import '@<<Scope/Organisation>>/ccl-ui-components/styles/tokens.css';

/* Default theme (Naked) */
@import '@<<Scope/Organisation>>/ccl-ui-components/styles/naked.css';

/* Optional: Brand theme override */
@import '@<<Scope/Organisation>>/ccl-ui-components/styles/brandA.css';
```

### Step 7: Import Components

```typescript
import { ButtonComponent, InputComponent } from '@<<Scope/Organisation>>/ccl-ui-components';

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

## Alternative Installation Methods

### Using Yarn

```bash
# Configure registry
yarn config set @<<Scope/Organisation>>:registry https://npm.pkg.github.com/

# Install package
yarn add @<<Scope/Organisation>>/ccl-ui-components
```

### Using pnpm

```bash
# Configure registry
pnpm config set @<<Scope/Organisation>>:registry https://npm.pkg.github.com/

# Install package
pnpm add @<<Scope/Organisation>>/ccl-ui-components
```

### Using Bun

```bash
# Install package (registry config in .npmrc)
bun add @<<Scope/Organisation>>/ccl-ui-components
```

## Framework-Specific Setup

### Angular

```typescript
// app.module.ts or standalone component
import { ButtonComponent, InputComponent } from '@<<Scope/Organisation>>/ccl-ui-components';

@NgModule({
  imports: [ButtonComponent, InputComponent],
  // ...
})
export class AppModule {}
```

### React (if using React wrapper)

```typescript
import { Button, Input } from '@<<Scope/Organisation>>/ccl-ui-components';

function App() {
  return (
    <div>
      <Button label="Click me" />
      <Input label="Email" placeholder="Enter email" />
    </div>
  );
}
```

### Vue (if using Vue wrapper)

```vue
<template>
  <div>
    <Button label="Click me" />
    <Input label="Email" placeholder="Enter email" />
  </div>
</template>

<script>
import { Button, Input } from '@<<Scope/Organisation>>/ccl-ui-components';

export default {
  components: { Button, Input }
};
</script>
```

## Troubleshooting

### Common Issues

#### 1. Authentication Failed (401 Unauthorized)

**Symptoms**:
```
npm ERR! 401 Unauthorized - GET https://npm.pkg.github.com/@<<Scope/Organisation>>%2fccl-ui-components
```

**Solutions**:
```bash
# Check your token
echo $GITHUB_TOKEN

# Verify .npmrc configuration
cat .npmrc

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

# Clear npm cache
npm cache clean --force
```

#### 2. Package Not Found (404 Not Found)

**Symptoms**:
```
npm ERR! 404 Not Found - GET https://npm.pkg.github.com/@<<Scope/Organisation>>%2fccl-ui-components
```

**Solutions**:
```bash
# Verify registry URL
npm config get @<<Scope/Organisation>>:registry

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

# Check package name
npm view @<<Scope/Organisation>>/ccl-ui-components
```

#### 3. Permission Denied (403 Forbidden)

**Symptoms**:
```
npm ERR! 403 Forbidden - GET https://npm.pkg.github.com/@<<Scope/Organisation>>%2fccl-ui-components
```

**Solutions**:
- Verify your GitHub account has access to the repository
- Check if your token has the correct scopes
- Ensure the repository is not private or you have access

#### 4. Network Issues

**Symptoms**:
```
npm ERR! network timeout
npm ERR! ECONNREFUSED
```

**Solutions**:
```bash
# Check network connectivity
ping npm.pkg.github.com

# Try with different registry
npm install @<<Scope/Organisation>>/ccl-ui-components --registry=https://npm.pkg.github.com/

# Use proxy if behind corporate firewall
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
```

### Debug Mode

Enable verbose logging to troubleshoot:

```bash
# Install with verbose output
npm install @<<Scope/Organisation>>/ccl-ui-components --verbose

# Check npm configuration
npm config list

# Test registry connectivity
curl -H "Authorization: token $GITHUB_TOKEN" https://npm.pkg.github.com/@<<Scope/Organisation>>/ccl-ui-components
```

## Security Best Practices

### 1. Token Management

- **Never commit tokens** to version control
- **Use environment variables** for token storage
- **Rotate tokens regularly** (every 90 days)
- **Use minimal scopes** (only `read:packages` for installation)

### 2. Registry Configuration

```ini
# Good: Using environment variable
@<<Scope/Organisation>>:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=true

# Bad: Hardcoded token
//npm.pkg.github.com/:_authToken=ghp_1234567890abcdef
```

### 3. CI/CD Setup

For automated environments, use secure token storage:

```yaml
# GitHub Actions
- name: Install CCL UI Components
  run: npm install @<<Scope/Organisation>>/ccl-ui-components
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Next Steps

After successful installation:

1. **Read the [Usage Guide](./usage.md)** for component examples
2. **Explore [Theming Documentation](./theming.md)** for customization
3. **Check [Component API Reference](./README.md)** for detailed documentation
4. **Review [Accessibility Guidelines](./accessibility.md)** for best practices

## Support

If you encounter issues:

1. **Check this troubleshooting guide** first
2. **Search existing issues** on GitHub
3. **Create a new issue** with detailed information
4. **Contact support** for urgent matters

---

**Need help?** Check out our [Usage Guide](./usage.md) or [open an issue](https://github.com/your-org/ccl-ui-components/issues).