From 69895aeccbd84bd56e32b1af23b8166da9c018e1 Mon Sep 17 00:00:00 2001
From: Xc <124118265@qq.com>
Date: Fri, 9 Dec 2022 14:46:58 +0800
Subject: [PATCH] docs(components): [color-picker] (#10889)

* docs(components): [color-picker]
* Adjust API style
* classname

* Update docs/en-US/component/color-picker.md

Co-authored-by: qiang <qw13131wang@gmail.com>

Co-authored-by: qiang <qw13131wang@gmail.com>
---
 docs/en-US/component/color-picker.md          | 43 ++++++++++++-------
 .../color-picker/src/color-picker.ts          | 33 ++++++++++++++
 .../color-picker/src/color-picker.vue         | 17 +++++---
 3 files changed, 72 insertions(+), 21 deletions(-)

diff --git a/docs/en-US/component/color-picker.md b/docs/en-US/component/color-picker.md
index a1fb50e731..14c48f3793 100644
--- a/docs/en-US/component/color-picker.md
+++ b/docs/en-US/component/color-picker.md
@@ -39,22 +39,33 @@ color-picker/sizes
 
 :::
 
-## Attributes
+## API
 
-| Name                  | Description                                  | Type    | Accepted Values        | Default                                                       |
-| --------------------- | -------------------------------------------- | ------- | ---------------------- | ------------------------------------------------------------- |
-| model-value / v-model | binding value                                | string  | —                      | —                                                             |
-| disabled              | whether to disable the ColorPicker           | boolean | —                      | false                                                         |
-| size                  | size of ColorPicker                          | string  | large / default /small | —                                                             |
-| show-alpha            | whether to display the alpha slider          | boolean | —                      | false                                                         |
-| color-format          | color format of v-model                      | string  | hsl / hsv / hex / rgb  | hex (when show-alpha is false)/ rgb (when show-alpha is true) |
-| popper-class          | custom class name for ColorPicker's dropdown | string  | —                      | —                                                             |
-| predefine             | predefined color options                     | array   | —                      | —                                                             |
-| validate-event        | whether to trigger form validation           | boolean | -                      | true                                                          |
+### Attributes
 
-## Events
+| Name                  | Description                                  | Type                                                                                                            | Default |
+| --------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
+| model-value / v-model | binding value                                | ^[string]                                                                                                       | —       |
+| disabled              | whether to disable the ColorPicker           | ^[boolean]                                                                                                      | false   |
+| size                  | size of ColorPicker                          | ^[enum]`'large' \| 'default' \| 'small'`                                                                        | —       |
+| show-alpha            | whether to display the alpha slider          | ^[boolean]                                                                                                      | false   |
+| color-format          | color format of v-model                      | ^[enum]`'hsl' \| 'hsv' \| 'hex' \| 'rgb' \| 'hex' (when show-alpha is false) \| 'rgb' (when show-alpha is true)` | —       |
+| popper-class          | custom class name for ColorPicker's dropdown | ^[string]                                                                                                       | —       |
+| predefine             | predefined color options                     | ^[object]`string[]`                                                                                             | —       |
+| validate-event        | whether to trigger form validation           | ^[boolean]                                                                                                      | true    |
+| tabindex              | ColorPicker tabindex                         | ^[string] / ^[number]                                                                                           | 0       |
+| label<A11yTag/>       | ColorPicker aria-label                       | ^[string]                                                                                                       | —       |
+| id                    | ColorPicker id                               | ^[string]                                                                                                       | —       |
 
-| Name          | Description                                    | Parameters         |
-| ------------- | ---------------------------------------------- | ------------------ |
-| change        | triggers when input value changes              | color value        |
-| active-change | triggers when the current active color changes | active color value |
+### Events
+
+| Name          | Description                                    | Type                                 |
+| ------------- | ---------------------------------------------- | ------------------------------------ |
+| change        | triggers when input value changes              | ^[Function]`(value: string) => void` |
+| active-change | triggers when the current active color changes | ^[Function]`(value: string) => void` |
+
+### Exposes
+
+| Name  | Description          | Type             |
+| ----- | -------------------- | ---------------- |
+| color | current color object | ^[object]`Color` |
diff --git a/packages/components/color-picker/src/color-picker.ts b/packages/components/color-picker/src/color-picker.ts
index 65637c9f1f..6b5924febd 100644
--- a/packages/components/color-picker/src/color-picker.ts
+++ b/packages/components/color-picker/src/color-picker.ts
@@ -7,27 +7,60 @@ import type { ComputedRef, ExtractPropTypes, InjectionKey } from 'vue'
 import type ColorPicker from './color-picker.vue'
 
 export const colorPickerProps = buildProps({
+  /**
+   * @description binding value
+   */
   modelValue: String,
+  /**
+   * @description ColorPicker id
+   */
   id: String,
+  /**
+   * @description whether to display the alpha slider
+   */
   showAlpha: Boolean,
+  /**
+   * @description color format of v-model
+   */
   colorFormat: String,
+  /**
+   * @description whether to disable the ColorPicker
+   */
   disabled: Boolean,
+  /**
+   * @description size of ColorPicker
+   */
   size: useSizeProp,
+  /**
+   * @description custom class name for ColorPicker's dropdown
+   */
   popperClass: {
     type: String,
     default: '',
   },
+  /**
+   * @description ColorPicker aria-label
+   */
   label: {
     type: String,
     default: undefined,
   },
+  /**
+   * @description ColorPicker tabindex
+   */
   tabindex: {
     type: [String, Number],
     default: 0,
   },
+  /**
+   * @description predefined color options
+   */
   predefine: {
     type: definePropType<string[]>(Array),
   },
+  /**
+   * @description whether to trigger form validation
+   */
   validateEvent: {
     type: Boolean,
     default: true,
diff --git a/packages/components/color-picker/src/color-picker.vue b/packages/components/color-picker/src/color-picker.vue
index b370351ac0..407c23d53c 100644
--- a/packages/components/color-picker/src/color-picker.vue
+++ b/packages/components/color-picker/src/color-picker.vue
@@ -58,11 +58,7 @@
     <template #default>
       <div
         :id="buttonId"
-        :class="[
-          ns.b('picker'),
-          ns.is('disabled', colorDisabled),
-          ns.bm('picker', colorSize),
-        ]"
+        :class="btnKls"
         role="button"
         :aria-label="buttonAriaLabel"
         :aria-labelledby="buttonAriaLabelledby"
@@ -197,6 +193,14 @@ const buttonAriaLabelledby = computed<string | undefined>(() => {
   return isLabeledByFormItem.value ? formItem?.labelId : undefined
 })
 
+const btnKls = computed(() => {
+  return [
+    ns.b('picker'),
+    ns.is('disabled', colorDisabled.value),
+    ns.bm('picker', colorSize.value),
+  ]
+})
+
 function displayedRgb(color: Color, showAlpha: boolean) {
   if (!(color instanceof Color)) {
     throw new TypeError('color should be instance of _color Class')
@@ -324,6 +328,9 @@ provide(colorPickerContextKey, {
 })
 
 defineExpose({
+  /**
+   * @description current color object
+   */
   color,
 })
 </script>