ui-essentials/CONSUMER_INTEGRATION_GUIDE.md

# Angular Library Consumer Integration Guide

## 🚀 Complete Guide: Creating a New Angular Project with SSuite Libraries

This guide shows you how to create a fresh Angular project and integrate any combination of the 12 SSuite libraries using Git submodules.

---

## 📋 Prerequisites

- **Node.js 18+** and npm
- **Angular CLI** (`npm install -g @angular/cli`)
- **Git** configured with access to `git.sky-ai.com`

---

## 🏗️ Step 1: Create New Angular Project

```bash
# Create new Angular project
ng new my-awesome-app
cd my-awesome-app

# Create libs directory for submodules
mkdir libs
```

---

## 📦 Step 2: Choose Your Libraries

Select libraries based on your needs:

### 🎨 **Foundation (Required for most projects)**
- **ui-design-system** - SCSS design tokens, colors, typography, fonts

### 🛠️ **Essential Components**  
- **ui-essentials** - Buttons, forms, tables, cards, navigation, etc.
- **shared-utils** - Common utilities and shared services

### 🎯 **Specialized Libraries**
- **auth-client** - Authentication guards, services, interceptors
- **ui-landing-pages** - Hero sections, pricing tables, testimonials
- **ui-code-display** - Syntax highlighting for code blocks
- **ui-accessibility** - WCAG compliance tools and utilities
- **hcl-studio** - Advanced color management system

### 🎭 **Enhancement Libraries**
- **ui-animations** - CSS animation utilities
- **ui-backgrounds** - Background generators and effects
- **ui-font-manager** - Advanced font management
- **ui-data-utils** - Data manipulation utilities

---

## ⚡ Step 3: Add Libraries as Submodules

**IMPORTANT**: Always add `ui-design-system` first, as other libraries depend on it.

### Minimal Setup (Design System + Components):
```bash
# Add foundation (required)
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system

# Add essential components
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils

# Initialize submodules
git submodule update --init --recursive
```

### Full-Featured Setup (All Libraries):
```bash
# Foundation (required first)
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system

# Core libraries
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils
git submodule add https://git.sky-ai.com/jules/auth-client.git libs/auth-client

# Specialized libraries
git submodule add https://git.sky-ai.com/jules/ui-landing-pages.git libs/ui-landing-pages
git submodule add https://git.sky-ai.com/jules/ui-code-display.git libs/ui-code-display
git submodule add https://git.sky-ai.com/jules/ui-accessibility.git libs/ui-accessibility
git submodule add https://git.sky-ai.com/jules/hcl-studio.git libs/hcl-studio

# Enhancement libraries
git submodule add https://git.sky-ai.com/jules/ui-animations.git libs/ui-animations
git submodule add https://git.sky-ai.com/jules/ui-backgrounds.git libs/ui-backgrounds
git submodule add https://git.sky-ai.com/jules/ui-font-manager.git libs/ui-font-manager
git submodule add https://git.sky-ai.com/jules/ui-data-utils.git libs/ui-data-utils

# Initialize all submodules
git submodule update --init --recursive
```

---

## 🔨 Step 4: Build Libraries

Build libraries in dependency order:

```bash
# Build ui-design-system first (required by others)
cd libs/ui-design-system
npm install
npm run build
cd ../..

# Build other libraries
cd libs/ui-essentials && npm install && npm run build && cd ../..
cd libs/shared-utils && npm install && npm run build && cd ../..
cd libs/auth-client && npm install && npm run build && cd ../..

# Continue for other libraries as needed...
```

### 📜 Automation Script:
Create `build-libs.sh`:
```bash
#!/bin/bash
echo "🏗️ Building all libraries..."

# Array of libraries in dependency order
LIBS=("ui-design-system" "shared-utils" "ui-essentials" "auth-client" "ui-landing-pages" "ui-code-display" "ui-accessibility" "hcl-studio" "ui-animations" "ui-backgrounds" "ui-font-manager" "ui-data-utils")

for lib in "${LIBS[@]}"; do
  if [ -d "libs/$lib" ]; then
    echo "📦 Building $lib..."
    cd libs/$lib
    npm install
    npm run build
    cd ../..
    echo "✅ $lib built successfully"
  else
    echo "⚠️ Skipping $lib (not found)"
  fi
done

echo "🎉 All libraries built!"
```

Make executable: `chmod +x build-libs.sh && ./build-libs.sh`

---

## ⚙️ Step 5: Configure TypeScript Paths

Update `tsconfig.json`:

```json
{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      // Foundation (required)
      "ui-design-system": ["./libs/ui-design-system/dist"],
      "ui-design-system/*": ["./libs/ui-design-system/dist/*", "./libs/ui-design-system/src/*"],
      
      // Core libraries
      "ui-essentials": ["./libs/ui-essentials/dist"],
      "ui-essentials/*": ["./libs/ui-essentials/dist/*"],
      "shared-utils": ["./libs/shared-utils/dist"],
      "shared-utils/*": ["./libs/shared-utils/dist/*"],
      "auth-client": ["./libs/auth-client/dist"],
      "auth-client/*": ["./libs/auth-client/dist/*"],
      
      // Specialized libraries
      "ui-landing-pages": ["./libs/ui-landing-pages/dist"],
      "ui-landing-pages/*": ["./libs/ui-landing-pages/dist/*"],
      "ui-code-display": ["./libs/ui-code-display/dist"],
      "ui-code-display/*": ["./libs/ui-code-display/dist/*"],
      "ui-accessibility": ["./libs/ui-accessibility/dist"],
      "ui-accessibility/*": ["./libs/ui-accessibility/dist/*"],
      "hcl-studio": ["./libs/hcl-studio/dist"],
      "hcl-studio/*": ["./libs/hcl-studio/dist/*"],
      
      // Enhancement libraries
      "ui-animations": ["./libs/ui-animations/dist"],
      "ui-animations/*": ["./libs/ui-animations/dist/*"],
      "ui-backgrounds": ["./libs/ui-backgrounds/dist"],
      "ui-backgrounds/*": ["./libs/ui-backgrounds/dist/*"],
      "ui-font-manager": ["./libs/ui-font-manager/dist"],
      "ui-font-manager/*": ["./libs/ui-font-manager/dist/*"],
      "ui-data-utils": ["./libs/ui-data-utils/dist"],
      "ui-data-utils/*": ["./libs/ui-data-utils/dist/*"]
    }
  }
}
```

**Note**: The `ui-design-system/*` includes both `dist/*` and `src/*` to support SCSS imports.

---

## 🎨 Step 6: Import Styles

### Option A: Complete Design System
In your `src/styles.scss`:
```scss
// Complete design system (includes all tokens + fonts)
@use 'ui-design-system/src/styles' as ui;

// Optional: Additional component styles
@use 'ui-animations/src/styles' as animations;
@use 'ui-backgrounds/src/styles' as backgrounds;
```

### Option B: Selective Imports
```scss
// Just semantic tokens (most common)
@use 'ui-design-system/src/styles/semantic' as tokens;

// Or just base tokens
@use 'ui-design-system/src/styles/base' as base;

// Add specific libraries
@use 'ui-accessibility/src/lib/utilities/a11y-utilities' as a11y;
```

---

## 💻 Step 7: Use Libraries in Your Components

### Example Component using multiple libraries:

```typescript
// src/app/app.component.ts
import { Component } from '@angular/core';
import { ButtonComponent } from 'ui-essentials';
import { AuthService } from 'auth-client';
import { HeroSectionComponent } from 'ui-landing-pages';
import { CodeSnippetComponent } from 'ui-code-display';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    ButtonComponent,
    HeroSectionComponent, 
    CodeSnippetComponent
  ],
  template: `
    <div class="app-container">
      <!-- Hero Section -->
      <ui-hero-section
        title="Welcome to My App"
        subtitle="Built with SSuite Libraries"
        [cta]="{ text: 'Get Started', action: 'primary' }">
      </ui-hero-section>

      <!-- Content Section -->
      <main class="content">
        <!-- Buttons from ui-essentials -->
        <ui-button variant="primary" (click)="handleClick()">
          Primary Action
        </ui-button>
        
        <ui-button variant="secondary" [disabled]="!isLoggedIn">
          Secondary Action  
        </ui-button>

        <!-- Code Display -->
        <ui-code-snippet 
          language="typescript"
          [code]="exampleCode">
        </ui-code-snippet>
      </main>
    </div>
  `,
  styles: [`
    .app-container {
      min-height: 100vh;
    }
    .content {
      padding: 2rem;
      max-width: 1200px;
      margin: 0 auto;
    }
  `]
})
export class AppComponent {
  isLoggedIn = false;
  exampleCode = `
import { ButtonComponent } from 'ui-essentials';
import { AuthService } from 'auth-client';

// Your code here...
  `;

  constructor(private auth: AuthService) {
    this.isLoggedIn = this.auth.isAuthenticated();
  }

  handleClick() {
    console.log('Button clicked!');
  }
}
```

### Component with Authentication:

```typescript
// src/app/protected/dashboard.component.ts
import { Component } from '@angular/core';
import { AuthGuard } from 'auth-client';
import { TableComponent, CardComponent } from 'ui-essentials';
import { StatisticsDisplayComponent } from 'ui-landing-pages';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [TableComponent, CardComponent, StatisticsDisplayComponent],
  template: `
    <div class="dashboard">
      <!-- Stats Cards -->
      <div class="stats-grid">
        <ui-statistics-display
          [statistics]="stats"
          variant="cards">
        </ui-statistics-display>
      </div>

      <!-- Data Table -->
      <ui-card>
        <ui-enhanced-table
          [data]="userData"
          [columns]="tableColumns"
          [searchable]="true"
          [sortable]="true">
        </ui-enhanced-table>
      </ui-card>
    </div>
  `,
  styles: [`
    .dashboard {
      padding: 1.5rem;
    }
    .stats-grid {
      margin-bottom: 2rem;
    }
  `]
})
export class DashboardComponent {
  stats = [
    { label: 'Users', value: '1,234', change: '+12%' },
    { label: 'Revenue', value: '$45,678', change: '+8%' },
    { label: 'Orders', value: '892', change: '+15%' }
  ];

  userData = [
    { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'inactive' }
  ];

  tableColumns = [
    { key: 'id', label: 'ID' },
    { key: 'name', label: 'Name' },
    { key: 'email', label: 'Email' },
    { key: 'status', label: 'Status' }
  ];
}
```

---

## 🔄 Step 8: Library Management

### Update a Single Library:
```bash
cd libs/ui-essentials
git pull origin main
npm run build
cd ../..
```

### Update All Libraries:
```bash
git submodule update --remote
./build-libs.sh  # Rebuild all libraries
```

### Lock Library to Specific Version:
```bash
cd libs/ui-essentials
git checkout v1.2.0  # Specific tag
cd ../..
git add libs/ui-essentials
git commit -m "Lock ui-essentials to v1.2.0"
```

### Remove Unused Library:
```bash
git submodule deinit libs/ui-backgrounds
git rm libs/ui-backgrounds
git commit -m "Remove ui-backgrounds library"
```

---

## 📁 Final Project Structure

```
my-awesome-app/
├── src/
│   ├── app/
│   │   ├── app.component.ts
│   │   ├── protected/
│   │   │   └── dashboard.component.ts
│   │   └── ...
│   ├── styles.scss
│   └── ...
├── libs/                          # Git submodules
│   ├── ui-design-system/         # Foundation
│   ├── ui-essentials/            # Components
│   ├── auth-client/              # Authentication
│   ├── ui-landing-pages/         # Landing components
│   └── [other-libraries]/
├── package.json
├── tsconfig.json
├── angular.json
├── build-libs.sh                 # Build automation
├── .gitmodules                   # Auto-generated
└── README.md
```

---

## ⚡ Quick Start Commands

### Minimal Project (Design System + Components):
```bash
ng new my-app && cd my-app
mkdir libs
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule update --init --recursive
cd libs/ui-design-system && npm install && npm run build && cd ../..
cd libs/ui-essentials && npm install && npm run build && cd ../..
```

### Add TypeScript paths and styles, then start developing!

---

## 🎯 Common Patterns

### Landing Page Project:
```bash
# Essential for marketing sites
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/ui-landing-pages.git libs/ui-landing-pages
git submodule add https://git.sky-ai.com/jules/ui-animations.git libs/ui-animations
```

### Documentation Site:
```bash
# Perfect for docs with code examples
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/ui-code-display.git libs/ui-code-display
git submodule add https://git.sky-ai.com/jules/ui-accessibility.git libs/ui-accessibility
```

### Enterprise Application:
```bash
# Full-featured business app
git submodule add https://git.sky-ai.com/jules/ui-design-system.git libs/ui-design-system
git submodule add https://git.sky-ai.com/jules/ui-essentials.git libs/ui-essentials
git submodule add https://git.sky-ai.com/jules/shared-utils.git libs/shared-utils
git submodule add https://git.sky-ai.com/jules/auth-client.git libs/auth-client
git submodule add https://git.sky-ai.com/jules/ui-data-utils.git libs/ui-data-utils
```

---

## 🚀 You're Ready!

Your new Angular project is now set up with the SSuite library ecosystem. You have:

- ✅ **Modular architecture** - Only include libraries you need
- ✅ **Professional design system** - Consistent styling and components  
- ✅ **Independent updates** - Update libraries separately
- ✅ **Clean imports** - TypeScript paths configured
- ✅ **Version control** - Lock libraries to specific versions
- ✅ **Scalable structure** - Add/remove libraries as needed

Happy coding! 🎉