dynamic-ds 1.0.0

package/README.md

@@ -0,0 +1,555 @@
+# Dynamic-DS - Dynamic Design System
+
+[English](#english) | [Tiếng Việt](#tiếng-việt)
+
+---
+
+## English
+
+### 📖 Overview
+
+**Dynamic-DS (Dynamic Design System)** is an Angular library that provides a comprehensive design system with dynamic theming capabilities. It allows applications to customize brand colors while maintaining a consistent design language across all components.
+
+### ✨ Key Features
+
+- **Dynamic Color Theming**: Customize brand, primary, secondary, functional, and utility colors
+- **Automatic Palette Generation**: Generates 14 color shades (900-10) from a single base color
+- **CSS Custom Properties**: All colors exposed as CSS variables for easy access
+- **Semantic Color Classes**: Pre-built utility classes for backgrounds, text, borders, and icons
+- **Theme Badge Palettes**: 12 predefined color themes for badges and tags
+- **RGB Mix Algorithm**: Accurate color shade generation using RGB mixing
+- **Runtime Color Updates**: Change theme colors dynamically without page reload
+
+### 📦 Installation
+
+```bash
+npm install dynamic-ds
+```
+
+### 🚀 Quick Start
+
+#### 1. Import Styles
+
+Add the design system styles to your `angular.json`:
+
+```json
+{
+  "styles": [
+    "node_modules/dynamic-ds/styles/system-design.scss"
+  ]
+}
+```
+
+#### 2. Provide Configuration (Optional)
+
+In your `app.config.ts` or module:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { SYSTEM_DESIGN_CONFIG } from 'dynamic-ds';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: SYSTEM_DESIGN_CONFIG,
+      useValue: {
+        brand: '#2740B4',
+        primary: '#006BDF',
+        secondary: '#9F5100',
+        functional: '#006BDF',
+        utility: '#CF0026'
+      }
+    }
+  ]
+};
+```
+
+#### 3. Initialize Theme
+
+In your `app.component.ts`:
+
+```typescript
+import { Component, inject, OnInit } from '@angular/core';
+import { DynamicDsService } from 'dynamic-ds';
+
+@Component({
+  selector: 'app-root',
+  template: `...`
+})
+export class AppComponent implements OnInit {
+  private themeService = inject(DynamicDsService);
+
+  ngOnInit() {
+    // Initialize theme with config or defaults
+    this.themeService.initializeTheme().subscribe();
+  }
+}
+```
+
+### 🎨 Usage
+
+#### Using CSS Classes
+
+```html
+<!-- Background colors -->
+<div class="bg-primary-canvas">Lightest background</div>
+<div class="bg-primary-soft">Soft background</div>
+<div class="bg-primary-accent">Accent background</div>
+
+<!-- Text colors -->
+<p class="text-primary-strong">Strong text</p>
+<p class="text-neutral-soft">Soft neutral text</p>
+
+<!-- Borders -->
+<div class="stroke-primary-sub">Primary border</div>
+
+<!-- Direct color utilities -->
+<div class="color-bg-primary-500">Primary 500 background</div>
+<p class="color-text-neutral-900">Neutral 900 text</p>
+```
+
+#### Using CSS Variables
+
+```scss
+.my-component {
+  background-color: var(--primary-600);
+  color: var(--neutral-900);
+  border: 1px solid var(--primary-200);
+}
+
+// With alpha transparency
+.overlay {
+  background-color: rgba(var(--primary-600-rgb), 0.5);
+}
+```
+
+#### Dynamic Color Updates
+
+```typescript
+import { DynamicDsService } from 'dynamic-ds';
+
+export class SettingsComponent {
+  constructor(private themeService: DynamicDsService) {}
+
+  updateTheme() {
+    this.themeService.updateSystemDesignColor({
+      primaryColor: '#FF5733',
+      secondaryColor: '#33FF57'
+    });
+  }
+
+  resetTheme() {
+    this.themeService.resetToDefaults();
+  }
+
+  getCurrentColors() {
+    const colors = this.themeService.getCurrentColors();
+    console.log(colors);
+    // { brand: '#...', primary: '#...', secondary: '#...', ... }
+  }
+}
+```
+
+### 🎯 Color Palettes
+
+Each color type generates 14 shades:
+
+| Shade | Usage | Mix Ratio |
+|-------|-------|-----------|
+| 900 | Darkest | -73.5% black |
+| 875 | Very dark | -62.5% black |
+| 850 | Darker | -47.0% black |
+| 800 | Dark | -34.5% black |
+| 700 | Medium dark | -18.5% black |
+| 600 | **Base color** | 0% |
+| 500 | Medium light | +17.5% white |
+| 400 | Light | +33.0% white |
+| 300 | Lighter | +53.0% white |
+| 200 | Very light | +72.0% white |
+| 100 | Ultra light | +85.0% white |
+| 50 | Canvas | +89.5% white |
+| 25 | Soft | +93.5% white |
+| 10 | Lightest | +97.0% white |
+
+### 🏷️ Semantic Classes
+
+#### Backgrounds
+- `.bg-{type}-canvas` - Lightest background
+- `.bg-{type}-soft` - Soft background
+- `.bg-{type}-sub` - Subtle background
+- `.bg-{type}-accent` - Accent/primary background
+
+#### Text
+- `.text-{type}-soft` - Soft text color
+- `.text-{type}-sub` - Subtle text color
+- `.text-{type}-strong` - Strong/bold text color
+- `.text-{type}-white` - White text
+
+#### Strokes (Borders)
+- `.stroke-{type}-soft` - Soft border
+- `.stroke-{type}-sub` - Subtle border
+- `.stroke-{type}-strong` - Strong border
+- `.stroke-{type}-strong-alpha` - 50% opacity border
+
+#### Icons
+- `.icon-{type}-soft` - Soft icon color
+- `.icon-{type}-sub` - Subtle icon color
+- `.icon-{type}-strong` - Strong icon color
+- `.icon-{type}-white` - White icon
+
+*Where `{type}` can be: `brand`, `primary`, `secondary`, `functional`, `utility`, `neutral`, or badge themes like `red`, `blue`, `green`, etc.*
+
+### 🎨 Badge Theme Colors
+
+Pre-defined badge/tag color themes:
+- `neutral`, `neutral-light`
+- `red`, `orange`, `yellow`
+- `lime`, `green`, `ocean`
+- `blue`, `indigo`, `violet`, `pink`
+
+Example:
+```html
+<span class="bg-blue-soft text-blue-strong stroke-blue-sub">Blue Badge</span>
+<span class="bg-green-canvas text-green-strong">Success</span>
+```
+
+### 📐 Sizing Utilities
+
+```html
+<!-- Heights -->
+<div class="h-xxs">16px height</div>
+<div class="h-xs">24px height</div>
+<div class="h-sm">28px height</div>
+<div class="h-md">36px height</div>
+<div class="h-lg">44px height</div>
+
+<!-- Widths -->
+<div class="w-md">36px width</div>
+
+<!-- Font sizes -->
+<p class="text-xs">12px font</p>
+<p class="text-sm">14px font</p>
+<p class="text-lg">16px font</p>
+<p class="text-xl">20px font</p>
+
+<!-- Border radius -->
+<div class="rounded-xs">4px radius</div>
+<div class="rounded-md">8px radius</div>
+<div class="rounded-full">999px radius</div>
+```
+
+### 🔧 API Reference
+
+#### DynamicDsService
+
+**Methods:**
+
+- `initializeTheme(): Observable<any>` - Initialize theme from config or defaults
+- `reloadThemeFromConfig(): Observable<any>` - Reload theme from current config
+- `updateSystemDesignColor(colors): void` - Update specific colors dynamically
+- `getCurrentColors(): object` - Get current theme colors
+- `resetToDefaults(): void` - Reset all colors to default values
+
+**Example:**
+```typescript
+// Initialize on app start
+themeService.initializeTheme().subscribe();
+
+// Update colors later
+themeService.updateSystemDesignColor({
+  primaryColor: '#FF6B00',
+  brandColor: '#2740B4'
+});
+
+// Get current colors
+const colors = themeService.getCurrentColors();
+```
+
+### 🎯 Default Colors
+
+| Type | Default Value |
+|------|---------------|
+| Brand | `#2740B4` |
+| Primary | `#006BDF` |
+| Secondary | `#9F5100` |
+| Functional | `#006BDF` |
+| Utility | `#CF0026` |
+| Neutral | `#505A5F` |
+
+### 📝 License
+
+MIT License
+
+---
+
+## Tiếng Việt
+
+### 📖 Tổng quan
+
+**Dynamic-DS (Dynamic Design System)** là thư viện Angular cung cấp hệ thống thiết kế toàn diện với khả năng tùy chỉnh theme động. Nó cho phép ứng dụng tùy chỉnh màu thương hiệu trong khi vẫn duy trì ngôn ngữ thiết kế nhất quán trên tất cả các component.
+
+### ✨ Tính năng chính
+
+- **Theme màu động**: Tùy chỉnh màu brand, primary, secondary, functional và utility
+- **Tự động tạo bảng màu**: Tạo 14 sắc độ màu (900-10) từ một màu cơ sở
+- **CSS Custom Properties**: Tất cả màu được export dưới dạng CSS variables
+- **Semantic Color Classes**: Các lớp tiện ích sẵn có cho background, text, border và icon
+- **Theme Badge Palettes**: 12 bảng màu định sẵn cho badge và tag
+- **RGB Mix Algorithm**: Tạo sắc độ màu chính xác bằng thuật toán pha trộn RGB
+- **Cập nhật màu Runtime**: Thay đổi màu theme động mà không cần tải lại trang
+
+### 📦 Cài đặt
+
+```bash
+npm install dynamic-ds
+```
+
+### 🚀 Bắt đầu nhanh
+
+#### 1. Import Styles
+
+Thêm styles của design system vào `angular.json`:
+
+```json
+{
+  "styles": [
+    "node_modules/dynamic-ds/styles/system-design.scss"
+  ]
+}
+```
+
+#### 2. Cung cấp Configuration (Tùy chọn)
+
+Trong `app.config.ts` hoặc module:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { SYSTEM_DESIGN_CONFIG } from 'dynamic-ds';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: SYSTEM_DESIGN_CONFIG,
+      useValue: {
+        brand: '#2740B4',
+        primary: '#006BDF',
+        secondary: '#9F5100',
+        functional: '#006BDF',
+        utility: '#CF0026'
+      }
+    }
+  ]
+};
+```
+
+#### 3. Khởi tạo Theme
+
+Trong `app.component.ts`:
+
+```typescript
+import { Component, inject, OnInit } from '@angular/core';
+import { DynamicDsService } from 'dynamic-ds';
+
+@Component({
+  selector: 'app-root',
+  template: `...`
+})
+export class AppComponent implements OnInit {
+  private themeService = inject(DynamicDsService);
+
+  ngOnInit() {
+    // Khởi tạo theme với config hoặc giá trị mặc định
+    this.themeService.initializeTheme().subscribe();
+  }
+}
+```
+
+### 🎨 Sử dụng
+
+#### Sử dụng CSS Classes
+
+```html
+<!-- Màu nền -->
+<div class="bg-primary-canvas">Nền sáng nhất</div>
+<div class="bg-primary-soft">Nền mềm</div>
+<div class="bg-primary-accent">Nền nhấn</div>
+
+<!-- Màu chữ -->
+<p class="text-primary-strong">Chữ đậm</p>
+<p class="text-neutral-soft">Chữ neutral nhẹ</p>
+
+<!-- Viền -->
+<div class="stroke-primary-sub">Viền primary</div>
+
+<!-- Tiện ích màu trực tiếp -->
+<div class="color-bg-primary-500">Nền Primary 500</div>
+<p class="color-text-neutral-900">Chữ Neutral 900</p>
+```
+
+#### Sử dụng CSS Variables
+
+```scss
+.my-component {
+  background-color: var(--primary-600);
+  color: var(--neutral-900);
+  border: 1px solid var(--primary-200);
+}
+
+// Với độ trong suốt alpha
+.overlay {
+  background-color: rgba(var(--primary-600-rgb), 0.5);
+}
+```
+
+#### Cập nhật màu động
+
+```typescript
+import { DynamicDsService } from 'dynamic-ds';
+
+export class SettingsComponent {
+  constructor(private themeService: DynamicDsService) {}
+
+  updateTheme() {
+    this.themeService.updateSystemDesignColor({
+      primaryColor: '#FF5733',
+      secondaryColor: '#33FF57'
+    });
+  }
+
+  resetTheme() {
+    this.themeService.resetToDefaults();
+  }
+
+  getCurrentColors() {
+    const colors = this.themeService.getCurrentColors();
+    console.log(colors);
+    // { brand: '#...', primary: '#...', secondary: '#...', ... }
+  }
+}
+```
+
+### 🎯 Bảng màu
+
+Mỗi loại màu tạo ra 14 sắc độ:
+
+| Sắc độ | Cách dùng | Tỷ lệ pha trộn |
+|--------|-----------|----------------|
+| 900 | Tối nhất | -73.5% đen |
+| 875 | Rất tối | -62.5% đen |
+| 850 | Tối hơn | -47.0% đen |
+| 800 | Tối | -34.5% đen |
+| 700 | Tối vừa | -18.5% đen |
+| 600 | **Màu gốc** | 0% |
+| 500 | Sáng vừa | +17.5% trắng |
+| 400 | Sáng | +33.0% trắng |
+| 300 | Sáng hơn | +53.0% trắng |
+| 200 | Rất sáng | +72.0% trắng |
+| 100 | Cực sáng | +85.0% trắng |
+| 50 | Canvas | +89.5% trắng |
+| 25 | Mềm | +93.5% trắng |
+| 10 | Sáng nhất | +97.0% trắng |
+
+### 🏷️ Semantic Classes
+
+#### Backgrounds (Nền)
+- `.bg-{type}-canvas` - Nền sáng nhất
+- `.bg-{type}-soft` - Nền mềm
+- `.bg-{type}-sub` - Nền tinh tế
+- `.bg-{type}-accent` - Nền nhấn/chính
+
+#### Text (Chữ)
+- `.text-{type}-soft` - Màu chữ mềm
+- `.text-{type}-sub` - Màu chữ tinh tế
+- `.text-{type}-strong` - Màu chữ đậm/mạnh
+- `.text-{type}-white` - Chữ trắng
+
+#### Strokes (Viền)
+- `.stroke-{type}-soft` - Viền mềm
+- `.stroke-{type}-sub` - Viền tinh tế
+- `.stroke-{type}-strong` - Viền mạnh
+- `.stroke-{type}-strong-alpha` - Viền độ mờ 50%
+
+#### Icons
+- `.icon-{type}-soft` - Màu icon mềm
+- `.icon-{type}-sub` - Màu icon tinh tế
+- `.icon-{type}-strong` - Màu icon mạnh
+- `.icon-{type}-white` - Icon trắng
+
+*Trong đó `{type}` có thể là: `brand`, `primary`, `secondary`, `functional`, `utility`, `neutral`, hoặc các theme badge như `red`, `blue`, `green`, v.v.*
+
+### 🎨 Màu Badge Theme
+
+Các theme màu định sẵn cho badge/tag:
+- `neutral`, `neutral-light`
+- `red`, `orange`, `yellow`
+- `lime`, `green`, `ocean`
+- `blue`, `indigo`, `violet`, `pink`
+
+Ví dụ:
+```html
+<span class="bg-blue-soft text-blue-strong stroke-blue-sub">Badge xanh</span>
+<span class="bg-green-canvas text-green-strong">Thành công</span>
+```
+
+### 📐 Tiện ích kích thước
+
+```html
+<!-- Chiều cao -->
+<div class="h-xxs">Cao 16px</div>
+<div class="h-xs">Cao 24px</div>
+<div class="h-sm">Cao 28px</div>
+<div class="h-md">Cao 36px</div>
+<div class="h-lg">Cao 44px</div>
+
+<!-- Chiều rộng -->
+<div class="w-md">Rộng 36px</div>
+
+<!-- Kích thước chữ -->
+<p class="text-xs">Chữ 12px</p>
+<p class="text-sm">Chữ 14px</p>
+<p class="text-lg">Chữ 16px</p>
+<p class="text-xl">Chữ 20px</p>
+
+<!-- Bo góc -->
+<div class="rounded-xs">Bo góc 4px</div>
+<div class="rounded-md">Bo góc 8px</div>
+<div class="rounded-full">Bo góc 999px</div>
+```
+
+### 🔧 Tham chiếu API
+
+#### DynamicDsService
+
+**Phương thức:**
+
+- `initializeTheme(): Observable<any>` - Khởi tạo theme từ config hoặc giá trị mặc định
+- `reloadThemeFromConfig(): Observable<any>` - Tải lại theme từ config hiện tại
+- `updateSystemDesignColor(colors): void` - Cập nhật màu cụ thể một cách động
+- `getCurrentColors(): object` - Lấy màu theme hiện tại
+- `resetToDefaults(): void` - Đặt lại tất cả màu về giá trị mặc định
+
+**Ví dụ:**
+```typescript
+// Khởi tạo khi app start
+themeService.initializeTheme().subscribe();
+
+// Cập nhật màu sau đó
+themeService.updateSystemDesignColor({
+  primaryColor: '#FF6B00',
+  brandColor: '#2740B4'
+});
+
+// Lấy màu hiện tại
+const colors = themeService.getCurrentColors();
+```
+
+### 🎯 Màu mặc định
+
+| Loại | Giá trị mặc định |
+|------|------------------|
+| Brand | `#2740B4` |
+| Primary | `#006BDF` |
+| Secondary | `#9F5100` |
+| Functional | `#006BDF` |
+| Utility | `#CF0026` |
+| Neutral | `#505A5F` |