docs: update documentation

Author: shijistar

README.md

@@ -60,7 +60,7 @@ What other exciting features are there? Please continue to explore! Or you can c
 
 ## Features
 
-- Fully compatible with native `enum` usage
+- Compatible with the usage of native enums
 - Supports multiple data types such as `number` and `string`
 - Enhanced enum items with display names
 - Internationalization support for display names, can be integrated with any i18n library
@@ -174,7 +174,8 @@ const WeekEnum = Enum({
 });
 
 WeekEnum.Sunday; // 0
-WeekEnum.label(0); // I love Sunday
+WeekEnum.items[0].key; // 'Sunday'
+WeekEnum.items[0].label; // I love Sunday
 ```
 
 ### 3. Label-Only Format
@@ -198,7 +199,7 @@ WeekEnum.items[0].label; // I love Sunday
 
 The array format is useful when you need to create enums with dynamic data, for example the data from an API.
 
-You can use dynamic field mapping rules to adapt to various different data structures. Please refer to the [Custom Field Mapping](#-custom-field-mapping-in-array-format-initialization) section for more details.
+You can also use dynamic field mapping rules to adapt to various different data structures. Please refer to the [Custom Field Mapping](#-custom-field-mapping-in-array-format-initialization) section for more details.
 
 ```js
 import { Enum } from 'enum-plus';
@@ -216,7 +217,7 @@ PetEnum.label(1); // Dog
 
 ### 5. Native Enum Format
 
-You can also create from native enums. It benefits from the native enum's `auto-incrementing` behavior.
+Create from native enums. It benefits from the native enum's `auto-incrementing` behavior.
 
 ```ts
 import { Enum } from 'enum-plus';
@@ -290,7 +291,7 @@ WeekEnum.values; // [0, 1, 2, 3, 4, 5, 6]
 
 `string[]`
 
-Returns an array of all enum item `label`(s).
+Returns an array of all enum item `label`(s). If [localization](#localization) has been enabled, the localized texts of each enum item will be returned.
 
 ```js
 WeekEnum.labels; // ['Sunday', 'Monday', ... 'Friday', 'Saturday']
@@ -325,7 +326,7 @@ const ColorEnum = Enum({
 ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']
 ```
 
-By the way, you can quickly access custom fields of a single enum item through the `named` property.
+Aditionally, you can quickly access custom fields of an enum item through the `named` and `raw` property.
 
 ```js
 ColorEnum.named.Red.raw.hex; // '#FF0000'
@@ -609,7 +610,7 @@ Enum.install(i18nextPlugin);
 
 ## User Stories
 
-#### 💡 Prevent Magic Numbers
+### 💡 Prevent Magic Numbers
 
 ```js
 const WeekEnum = Enum({
@@ -626,7 +627,7 @@ if (today === WeekEnum.Sunday) {
 
 ---
 
-#### 💡 Check for Valid Enum Values
+### 💡 Check for Valid Enum Values
 
 ```js
 if (WeekEnum.has(value)) {
@@ -638,7 +639,7 @@ if (WeekEnum.has(value)) {
 
 ---
 
-#### 💡 Check for Enum Objects
+### 💡 Check for Enum Objects
 
 ```ts
 let values: number[] | undefined;
@@ -653,9 +654,9 @@ if (Enum.isEnum(data)) {
 
 ---
 
-#### 💡 Generate UI Controls
+### 💡 Generate UI Controls
 
-Take React and Ant Design as an example. Please refer to the [Supports Various Frontend Frameworks](#-supports-various-frontend-frameworks) section for more examples.
+Take React and Ant Design as examples. Please refer to the [Supports Various Frontend Frameworks](#-supports-various-frontend-frameworks) section for more examples.
 
 ```jsx
 import { Menu, Select, Table } from 'antd';
@@ -678,9 +679,9 @@ const App = () => {
 
 ---
 
-#### 💡 Internationalization for Enum Names and Labels
+### 💡 Internationalization for Enum Names and Labels
 
-Support internationalization. Set the `label` field to a localization key, so that it displays the corresponding text based on the current language environment. Please refer to the [Localization](#localization) section for more details.
+Internationalization support . Set the `label` field to a localization key, so that it displays the corresponding text based on the current language environment. Please refer to the [Localization](#localization) section for more details.
 
 ```js
 WeekEnum.label(1); // Monday or 星期一, depending on the current locale
@@ -690,7 +691,9 @@ WeekEnum.name; // Week or 周, depending on the current locale
 
 ---
 
-#### 💡 Type Narrowing &nbsp; <sup>**_\[TypeScript Only]_**</sup>
+### 💡 Type Narrowing &nbsp; <sup>**_\[TypeScript Only]_**</sup>
+
+Type narrowing is a TypeScript-specific feature that allows you to use `valueType` to constrain the types of variables, function parameters, or component props. This prevents invalid assignments and enhances type safety in your code.
 
 - Variables
 
@@ -734,7 +737,7 @@ const MyComponent = (props: MyComponentProps) => {
 
 ---
 
-#### 💡 Support Metadata Fields That Can Serve as a Static Configuration System
+### 💡 Support Metadata Fields That Can Serve as a Static Configuration System
 
 ```js
 const ColorEnum = Enum({
@@ -753,7 +756,7 @@ ColorEnum.named.Red.raw.icon; // '🔥'
 
 ---
 
-#### Supports Traversing Enum Items in a Read-Only Manner
+### 💡 Supports Traversing Enum Items in a Read-Only Manner
 
 ```js
 Array.isArray(WeekEnum.items); // true
@@ -772,7 +775,7 @@ WeekEnum.items[0].label = 'foo'; // ❌ Not allowed, read-only
 
 ---
 
-#### 💡 Enum Composition (Merging)
+### 💡 Enum Composition (Merging)
 
 ```js
 const PrimaryColorEnum = Enum({
@@ -793,9 +796,9 @@ const AllColorEnum = Enum({
 
 ---
 
-#### 💡 Supports JSDoc Comments on Enum Items, Enabling Code Intelligence
+### 💡 Supports JSDoc Comments on Enum Items, Enabling Code Intelligence
 
-Supports inline documentation through JSDoc, allowing engineers to view detailed comments by simply hovering over enum values in the editor. Please refer to the [Best Practices](./docs/best-practices.md) section for writing good code.
+Supports inline documentation through JSDoc, allowing engineers to view detailed comments by simply hovering over enum values in the editor. Please refer to the [Best Practices](./docs/best-practices.md) section for how to write good code.
 
 ```js
 const WeekEnum = Enum({
@@ -810,13 +813,13 @@ WeekEnum.Monday; // Hover over Monday
 
 ![jsdoc](./public/jsdoc-en.png)
 
-You can see that this hover functionality reveals both documentation and enum values simultaneously, without leaving your current position in the code.
+We can see that both the enumeration value and the description of the enumeration item can be displayed at the same time, when the cursor hovers over an enumeration item. There is no need to jump away from the current position in the code to check the definitions.
 
 ---
 
-#### 💡 Supports Various Frontend Frameworks
+### 💡 Supports Various Frontend Frameworks
 
-`Enum.items` can be consumed as control data sources (using Select as an example).
+`Enum.items` can be consumed as the data source of UI components. Take `Select` component as examples.
 
 - **React-based UI libraries**
 
@@ -876,10 +879,10 @@ You can see that this hover functionality reveals both documentation and enum va
 
   [Angular Material](https://material.angular.io/components/select/overview) Select
 
-  ```jsx
+  ```html
   <mat-select>
     @for (item of WeekEnum.items; track item.value) {
-      <mat-option [value]="item.value">{{ item.label }}</mat-option>
+    <mat-option [value]="item.value">{{ item.label }}</mat-option>
     }
   </mat-select>
   ```
@@ -896,7 +899,7 @@ You can see that this hover functionality reveals both documentation and enum va
 
 ---
 
-#### 💡 Custom Field Mapping in Array Format Initialization
+### 💡 Custom Field Mapping in Array Format Initialization
 
 In [4. Array Format](#4-array-format) section, we know that you can build an enum from dynamic data from the backend, but it is very likely that the field names of dynamic data are not `value`, `label`, `key`, but other field names. In this case, you can pass in a custom option to map these to other field names.
 
@@ -1013,7 +1016,7 @@ This plugin also supports custom i18next options, and even allows complete contr
 
 If you need to automatically update the UI after switching languages, this requires the capabilities of frameworks like React, Vue, or Angular. Please consider using plugins such as [@enum-plus/plugin-react](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-react) or [@enum-plus/plugin-vue](https://github.com/shijistar/enum-plus/tree/main/packages/plugin-vue).
 
-If you are using other internationalization libraries, such as `react-intl`, `vue-i18next`, or `ngx-translate`, you can integrate these libraries through the `Enum.localize` method.
+If you are using other internationalization libraries, such as `react-intl`, `vue-i18next`, or `ngx-translate`, you can integrate these libraries by overwritting the `Enum.localize` method.
 
 _my-extension.js_
 

README.zh-CN.md

@@ -172,7 +172,8 @@ const WeekEnum = Enum({
 });
 
 WeekEnum.Sunday; // 0
-WeekEnum.label(0); // 星期日
+WeekEnum.items[0].key; // 'Sunday'
+WeekEnum.items[0].label; // 星期日
 ```
 
 ### 3. Key-Label 格式
@@ -326,7 +327,7 @@ const ColorEnum = Enum({
 ColorEnum.meta.hex; // ['#FF0000', '#00FF00', '#0000FF']
 ```
 
-顺便一提，可以通过`named`属性快速访问单个枚举项的自定义字段
+顺便一提，可以通过 `named` 和 `raw` 属性快速访问单个枚举项的自定义字段
 
 ```js
 ColorEnum.named.Red.raw.hex; // '#FF0000'
@@ -603,7 +604,7 @@ Enum.install(i18nextPlugin);
 
 ## 使用案例
 
-#### 💡 基础用法，消除魔法数字
+### 💡 基础用法，消除魔法数字
 
 ```js
 const WeekEnum = Enum({
@@ -620,7 +621,7 @@ if (today === WeekEnum.Sunday) {
 
 ---
 
-#### 💡 检查是否一个有效的枚举值
+### 💡 检查是否一个有效的枚举值
 
 ```js
 if (WeekEnum.has(value)) {
@@ -632,7 +633,7 @@ if (WeekEnum.has(value)) {
 
 ---
 
-#### 💡 检查是否一个枚举对象
+### 💡 检查是否一个枚举对象
 
 ```ts
 let values: number[] | undefined;
@@ -647,7 +648,7 @@ if (Enum.isEnum(data)) {
 
 ---
 
-#### 💡 生成 UI 组件
+### 💡 生成 UI 组件
 
 以 React + Ant Design 为例，更多 UI 组件的案例请参考 [支持多种前端框架](#-支持多种前端框架) 章节
 
@@ -672,7 +673,7 @@ const App = () => {
 
 ---
 
-#### 💡 枚举名称/标签支持国际化
+### 💡 枚举名称/标签支持国际化
 
 可以支持多语言环境，将`label`字段设置为一个本地化键值，根据当前语言环境显示对应的文本。请参考 [本地化](#本地化) 章节，了解更多详情。
 
@@ -684,7 +685,9 @@ WeekEnum.name; // Week 或 周，取决于当前语言环境
 
 ---
 
-#### 约束数据类型 (仅 TypeScript)
+### 💡 约束数据类型 (仅 TypeScript)
+
+这是一个 TypeScript 特有的特性，可以使用 `valueType` 约束变量、方法参数或组件属性的类型，防止无效赋值，提高代码的类型安全性。
 
 - 变量
 
@@ -728,7 +731,7 @@ const MyComponent = (props: MyComponentProps) => {
 
 ---
 
-#### 💡 添加元数据字段，可以作为静态配置系统使用
+### 💡 添加元数据字段，可以作为静态配置系统使用
 
 ```js
 const ColorEnum = Enum({
@@ -747,7 +750,7 @@ ColorEnum.named.Red.raw.icon; // '🔥'
 
 ---
 
-#### 支持遍历枚举项数组，但不可修改
+### 💡 支持遍历枚举项数组，但不可修改
 
 ```js
 Array.isArray(WeekEnum.items); // true
@@ -766,7 +769,7 @@ WeekEnum.items[0].label = 'foo'; // ❌ 不可修改
 
 ---
 
-#### 💡 枚举组合（合并）
+### 💡 枚举组合（合并）
 
 ```js
 const PrimaryColorEnum = Enum({
@@ -787,7 +790,7 @@ const AllColorEnum = Enum({
 
 ---
 
-#### 枚举项支持 Jsdoc 注释，启用代码智能提示
+### 💡 枚举项支持 Jsdoc 注释，启用代码智能提示
 
 在代码编辑器中，将光标悬停在枚举项上，即可显示关于该枚举项的详细 Jsdoc 注释，而不必再转到枚举定义处查看。关于如何编写良好的代码，请参考 [最佳实践](./docs/best-practices.md) 章节。
 
@@ -804,11 +807,11 @@ WeekEnum.Monday; // 将光标悬浮在 Monday 上
 
 ![jsdoc](./public/jsdoc-chs.png)
 
-可以看到，不但提示了枚举项的释义，还有枚举项的值，无需跳转离开当前光标位置，在阅读代码时非常方便。
+可以看到，当光标悬浮在枚举项上时，可以同时显示枚举值和枚举项的介绍。无需跳转离开当前光标位置，去查看枚举的定义，这在阅读代码时非常方便。
 
 ---
 
-#### 💡 支持多种前端框架
+### 💡 支持多种前端框架
 
 `Enum.items` 可以直接作为组件的数据源（以 Select 组件为例）
 
@@ -871,10 +874,10 @@ WeekEnum.Monday; // 将光标悬浮在 Monday 上
 
   [Angular Material](https://material.angular.io/components/select/overview) Select
 
-  ```jsx
+  ```html
   <mat-select>
     @for (item of WeekEnum.items; track item.value) {
-      <mat-option [value]="item.value">{{ item.label }}</mat-option>
+    <mat-option [value]="item.value">{{ item.label }}</mat-option>
     }
   </mat-select>
   ```
@@ -891,7 +894,7 @@ WeekEnum.Monday; // 将光标悬浮在 Monday 上
 
 ---
 
-#### 数组格式初始化，设置不同的字段映射
+### 💡 数组格式初始化，设置不同的字段映射
 
 在 [4. 数组格式](#4-数组格式) 章节中，介绍了可以通过后端动态数据来构建枚举，但是很可能动态数据的字段名并不是`value`、`label`、`key`，而是其它的字段名。这时你可以传入一个自定义选项，把这些映射到其它字段名上
 

package.json

@@ -5,7 +5,6 @@
   "keywords": [
     "enum",
     "enumeration",
-    "tool",
     "javascript",
     "typescript",
     "front-end",
@@ -14,20 +13,14 @@
     "browser",
     "mini-program",
     "react-native",
-    "assembly-script",
     "ui-binding",
     "ssr",
     "localization",
     "globalization",
     "plugin-system",
     "react",
     "vue",
-    "angular",
-    "ant-design",
-    "arco-design",
-    "material-ui",
-    "vuetify",
-    "ng-zorro"
+    "angular"
   ],
   "homepage": "https://github.com/shijistar/enum-plus",
   "bugs": {

packages/plugin-react/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@enum-plus/react",
+  "name": "@enum-plus/plugin-react",
   "version": "1.0.0-beta.0",
   "description": "A plugin for enum-plus that provides React components and hooks for enum handling",
   "keywords": [

scripts/add-umd-banner.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from 'fs';
 import packageJson from '../package.json';
 
 const headerComment = (legacy: boolean) => `/**
- * ${packageJson.name} (${legacy ? 'ES2015' : 'ES2020'} version)
+ * ${packageJson.name} (${legacy ? 'ES2015' : 'ES2020'} compatible})
  * ${packageJson.description}
  *
  * @version: ${packageJson.version}