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

<Meta title='@dxtmisha/vi/scripts/Classes/PropertiesKeys - Bộ chuyển đổi ngữ nghĩa khóa'/>

# Lớp PropertiesKeys

Lớp `PropertiesKeys` là một tiện ích tĩnh chuyên biệt được thiết kế để phân tích và chuyển đổi ý nghĩa ngữ nghĩa của các khóa token thiết kế. Nó đóng vai trò là "công cụ ngữ pháp" cho các tên thuộc tính, phân biệt giữa các khóa dữ liệu chức năng và các khóa siêu dữ liệu kiến trúc. Bằng cách cung cấp các cơ chế chuẩn hóa, thêm tiền tố dựa trên loại và phát hiện ký hiệu đặc biệt, nó đảm bảo rằng các khóa token luôn nhất quán và có thể dự đoán được bất kể định dạng nguồn của chúng (JSON, SCSS hoặc trạng thái nội bộ).

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

- **Nhận dạng siêu dữ liệu** — Phát hiện các khóa hệ thống được bảo vệ như `value`, `type` và các thuộc tính nội bộ bắt đầu bằng dấu gạch dưới.
- **Chuẩn hóa tiền tố** — Tự động loại bỏ các ký hiệu kiến trúc (như `=` hoặc `|`) để trích xuất tên ngữ nghĩa thuần túy.
- **Điều phối kiểu chữ** — Tích hợp với `toCamelCase` để duy trì các quy ước đặt tên nhất quán trong toàn bộ cây token.
- **Đổi khóa nhận biết loại (Type-Aware Re-keying)** — Chuyển đổi linh hoạt các khóa dựa trên danh mục của chúng (ví dụ: thêm tiền tố `media-` cho các token media hoặc `container-` cho các truy vấn container).
- **Khả năng tương thích SCSS** — Xử lý định dạng đặc biệt cho các khóa tương thích với SCSS, bao gồm cả các dấu và (`&`) ở đầu.

## Khởi tạo

Là một lớp tiện ích tĩnh, `PropertiesKeys` không yêu cầu khởi tạo thực thể và sẵn sàng sử dụng ngay sau khi nhập.

```typescript
import { PropertiesKeys } from '@dxtmisha/scripts'

// Kiểm tra xem một khóa có phải là trường siêu dữ liệu không
const isReserved = PropertiesKeys.isSpecialKey('type')

// Phân giải một tên ngữ nghĩa sạch
const cleanName = PropertiesKeys.getName('=primary-color')
// Trả về: "primaryColor"
```

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

- `isSpecialKey(key): boolean` — Kiểm tra xem khóa có phải là trường siêu dữ liệu hệ thống được bảo vệ hay không.
- `isFull(name): boolean` — Xác định xem tên có phải là một định nghĩa tuyệt đối/đầy đủ hay không.
- `getName(name, camelCase?): string` — Chuẩn hóa một khóa bằng cách loại bỏ các tiền tố và áp dụng camelCase tùy chọn.
- `reKey(key, type?): string` — Chuyển đổi một khóa dựa trên loại kiến trúc của nó (media, container, scss, v.v.).

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

### Quy trình chuyển đổi khóa (The Key Transformation Pipeline)

`PropertiesKeys` quản lý logic chuyển đổi giữa các định dạng đầu vào thô và các token nội bộ chuẩn hóa:
1. **Trích xuất ngữ nghĩa**: Khi `getName()` được gọi, lớp sử dụng các regex của `PropertiesTypes` để xác định và loại bỏ các ký hiệu điều khiển (như `=` biểu thị một giá trị bất biến).
2. **Thêm tiền tố theo ngữ cảnh**: Trong luồng `reKey()`, lớp kiểm tra `_type` của token. Nếu xác định được loại `media`, nó sẽ đảm bảo khóa phản ánh vai trò này một cách thông minh (ví dụ: `desktop` trở thành `mediaDesktop`), tránh các tiền tố dư thừa nếu chúng đã tồn tại.
3. **Bảo vệ trạng thái nội bộ**: Kiểm tra `isSpecialKey()` là rất quan trọng đối với các công cụ duyệt cây; nó ngăn chặn việc xử lý các cơ chế nội bộ (các khóa bắt đầu bằng `_`) như thể chúng là các token thiết kế thực sự do người dùng định nghĩa.
4. **Thích ứng nền tảng**: Để tạo SCSS, lớp xử lý cụ thể việc thêm tiền tố `&`, cho phép các token thiết kế có thể sử dụng trực tiếp trong các khai báo kiểu lồng nhau.
