import {Meta} from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesPalette - Trình quản lý Bảng màu & Sắc độ'/>

# Lớp PropertiesPalette

Lớp `PropertiesPalette` là một trình quản lý chuyên biệt để xử lý các token thiết kế liên quan đến màu sắc. Nó tập trung vào hai lĩnh vực chính: quản lý các bước độ bão hòa màu (sắc độ - shades) và theo dõi việc sử dụng thực tế của các màu trong bảng màu (palette) bên trong các biến chức năng. Bằng cách phân tích cách các màu sắc được tham chiếu trong toàn bộ hệ thống thiết kế, nó giúp đảm bảo rằng các định nghĩa chủ đề vẫn nhất quán và các biến CSS được tạo ra trỏ chính xác đến các mục bảng màu tương ứng của chúng.

## Các tính năng chính

- **Khám phá độ bão hòa** — Tự động trích xuất các mức độ sắc độ có sẵn (ví dụ: 50, 100, 200) từ cây thuộc tính.
- **Theo dõi sử dụng** — Xác định các màu bảng màu nào thực sự được ánh xạ tới các biến thành phần, hỗ trợ loại bỏ mã chết hoặc báo cáo kiểm tra.
- **Ánh xạ nhận biết chủ đề (Theme-Aware Mapping)** — Phân giải các liên kết màu phức tạp, tính đến các ghi đè cụ thể của chủ đề (như `basic` hoặc `dark`).
- **Tổng hợp biến CSS** — Chuyển đổi minh bạch các tham chiếu màu nội bộ thành các tên biến CSS chuẩn hóa (ví dụ: `--design-palette-theme-color`).

## Khởi tạo

Để khởi tạo đối tượng, hãy gọi hàm khởi tạo `PropertiesPalette(items)`.

**Tham số:**
- `items: PropertiesItems` — một thực thể của lớp điều phối chịu trách nhiệm duyệt và tìm kiếm cây thuộc tính.

```typescript
import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'

// 1. Chuẩn bị bộ điều phối tiên quyết
const manager = new PropertiesItems(allTokenData)

// 2. Tạo trình quản lý bảng màu
const palette = new PropertiesPalette(manager)

// 3. Trích xuất các sắc độ hoạt động hoặc các màu đã sử dụng
const shades = palette.getShade()
const usedColors = palette.getUsed()
```

## Các phương thức

### `getShade`
Truy xuất danh sách các mức độ bão hòa có sẵn (sắc độ - shades) được nhóm theo thiết kế. Phương thức này quét toàn bộ cây thuộc tính để tìm các mục được phân loại cụ thể là 'shade' và trả về cấu trúc đã phân giải của chúng. Các sắc độ này thường đại diện cho thang điểm định số của độ bão hòa màu (ví dụ: 50, 100, 200) được sử dụng trong hệ thống thiết kế.

**Trả về:** `PropertyPaletteList` — một đối tượng chuyên biệt trong đó các khóa là tên thiết kế và giá trị là các mảng token sắc độ màu.

```typescript
const shades = palette.getShade();
// Kết quả: { "basic": ["50", "100", ...], "premium": ["50", ...] }
```

### `getUsed`
Tạo một báo cáo toàn diện về tất cả các màu bảng màu hiện đang được sử dụng trong các biến chức năng trên toàn bộ hệ thống thiết kế. Nó lặp qua tất cả các token, xác định các tham chiếu biến CSS trỏ đến các mục bảng màu và ánh xạ chúng tới các tên biến CSS được tạo ra. Điều này rất cần thiết để kiểm tra việc sử dụng màu sắc và xác định các mục bảng màu không được sử dụng.

**Trả về:** `PropertyPaletteUsed[]` — một mảng các đối tượng, mỗi đối tượng chứa tên biến chức năng và tên biến CSS tương ứng được dẫn xuất từ bảng màu.

```typescript
const report = palette.getUsed();
/* Kết quả: 
[
  { "name": "primaryBackground", "value": ["--basic-palette-basic-blue-50"] }
] 
*/
```

### `getFocusUsed`
Phân giải đệ quy một giá trị thuộc tính cụ thể để xác định nguồn bảng màu cuối cùng của nó. Phương thức tiện ích này được sử dụng để theo dõi các liên kết qua nhiều lớp trừu tượng (chẳng hạn như các biến thành phần trỏ đến màu chủ đề, vốn lại trỏ đến các sắc độ bảng màu).

**Tham số:**
- `list: PropertyItem['value'][]` — danh sách các giá trị bảng màu đã biết để kiểm tra trong quá trình phân giải.
- `design: string` — tên của chủ đề thiết kế hiện tại.
- `component: string` — tên của ngữ cảnh thành phần đang được phân giải.
- `value: string` — giá trị thô hoặc liên kết (ví dụ: `{color.primary}`) để truy xuất nguồn gốc trở lại bảng màu.

**Trả về:** `string | undefined` — chuỗi giá trị đã phân giải cuối cùng nếu nó dẫn đến một mục bảng màu; nếu không sẽ là `undefined`.

```typescript
const source = palette.getFocusUsed(
  paletteValueList, 
  'basic', 
  'button', 
  '{color.primary}'
);
```

## Các thao tác (Operations)

### Luồng Phân giải Sử dụng Màu sắc (The Color Usage Resolution Flow)

`PropertiesPalette` thực hiện phân tích sâu về cách màu sắc truyền từ bảng màu đến các thành phần:
1. **Duyệt cây**: Sử dụng `PropertiesItems.each()`, lớp sẽ truy cập mọi nút trong hệ thống thiết kế.
2. **Lọc biến**: Nó nhắm mục tiêu cụ thể vào các mục thuộc loại `var` không phải là loại `color`, nhưng giữ các giá trị chuỗi trông giống như các liên kết màu.
3. **Phân giải liên kết đệ quy**: Khi tìm thấy một ứng cử viên, `getFocusUsed()` sẽ phân giải mọi liên kết trung gian (ví dụ: `primary` -> `theme.brand.main` -> `palette.blue.50`) cho đến khi nó đạt đến định nghĩa bảng màu thô hoặc xác nhận liên kết đó không phải bảng màu.
4. **Phát hiện chủ đề**: Nó kiểm tra hệ thống phân cấp (`parents`) để xác định xem màu sắc có thuộc về một khối chủ đề cụ thể hay không, cho phép nó đặt tên chính xác cho biến CSS kết quả (ví dụ: thêm tên chủ đề vào trước).
5. **Tổng hợp dữ liệu**: Kết quả được nhóm theo tên biến, cung cấp một bản đồ rõ ràng về các token chức năng nào tiêu thụ màu sắc bảng màu nào.

## Ví dụ (Examples)

### Trích xuất sắc độ và Cách sử dụng
```typescript
import { PropertiesPalette, PropertiesItems } from '@dxtmisha/scripts'

const manager = new PropertiesItems(allTokenData)
const palette = new PropertiesPalette(manager)

// 1. Lấy các sắc độ có sẵn
const shades = palette.getShade()

// 2. Quét các màu đã sử dụng trong các thành phần
const report = palette.getUsed()
```

### Phân giải liên kết thủ công
```typescript
const isPaletteValue = palette.getFocusUsed(
  paletteValueList, 
  'basic', 
  'button', 
  '{color.primary}'
)
```
