feat: update docs

one/docs/en-US/components/button-group.md

@@ -4,7 +4,7 @@
 
 ### Stylistic variants
 
-Available style variants for the `ui` prop: `primary`/`strong`.
+Available style variants for the `ui` prop: `primary`/`strong`/`basic`.
 
 [[ demo src="/demo/button-group/style.vue" ]]
 
@@ -44,6 +44,7 @@ Style variants. A space-separated list of enum values.
 | -- | -- |
 | `primary` | Primary buttons. |
 | `strong` | Strong buttons. |
+| `basic` | Basic buttons. |
 | `xs` | Extra small. |
 | `s` | Small. |
 | `m` | Medium. |

one/docs/en-US/components/calendar.md

@@ -35,7 +35,7 @@ When `multiple` and `range` are both set to `true`, you can select multiple date
 | `week-start` | `number=` | `calendar.weekStart` | The start of a week. Can be [globally configured](#global-config). |
 | `fill-month` | `boolean=` | `true` | Whether to show dates of previous and next month in current panel when there's only one month panel. |
 | `date-class` | `string|Array|Object|function=` | `{}` | Custom HTML `class` for specified date. All [`class` expressions supported by Vue](https://vuejs.org/v2/guide/class-and-style.html#Binding-HTML-Classes) are available for non-function values. When specified as a function, whose signature is `function(Date): string|Array<string>|Object<string, boolean>`, the return value is also `class` expressions suppported by Vue. |
-| `disabled-date` | `function(Date)=: boolean` | `() => false` | Whether the specified date is disabled and cannot be selected. |
+| `disabled-date` | `function(Date, Date=): boolean=` | `() => false` | Used to customize whether the specified date is disabled or not. The first parameter is the date to be used to determine if the date is disabled. When in the range selection process and a date is already selected, it is passed as the second parameter. |
 | `disabled` | `boolean=` | `false` | Whether the calendar is disabled. |
 | `readonly` | `boolean=` | `false` | Whether the calendar is read-only. |
 

one/docs/en-US/components/check-button-group.md

@@ -19,6 +19,7 @@ Available values for the `ui` prop: `s`/`m`.
 | `value` | `Array` | `[]` | [^value] |
 | `disabled` | `boolean=` | `false` | Whether the check button group is disabled. |
 | `readonly` | `boolean=` | `false` | Whether the check button group is read-only. |
+| `empty-value` | `*` | - | The value to be selected when all selected values are deselected. Used when `exclusive` items are present. |
 
 ^^^ui
 Style variants.
@@ -26,12 +27,12 @@ Style variants.
 +++Enum values
 | Value | Description |
 | -- | -- |
-| `m` | Medium. |
 | `s` | Small. |
+| `m` | Medium. |
 ^^^
 
 ^^^items
-The datasource of items with the item type being `{label, value, disabled, ...}`.
+The datasource of items with the item type being `{label, value, disabled, exclusive ...}`.
 
 +++Properties
 | Name | Type | Description |

one/docs/en-US/components/checkbox-group.md

@@ -19,6 +19,7 @@ Available size variant for the `ui` prop: `s`/`m`.
 | `value` | `Array` | `[]` | [^value] |
 | `disabled` | `boolean=` | `false` | Whether the checkbox group is disabled. |
 | `readonly` | `boolean=` | `false` | Whether the checkbox group is read-only. |
+| `empty-value` | `*` | - | The value to be selected when all selected values are deselected. Used when `exclusive` items are present. |
 
 ^^^ui
 Style variants.
@@ -31,7 +32,7 @@ Style variants.
 ^^^
 
 ^^^items
-The datasource of items with the item type being `{label, value, disabled, ...}`.
+The datasource of items with the item type being `{label, value, disabled, exclusive ...}`.
 
 +++Properties
 | Name | Type | Description |
@@ -39,6 +40,7 @@ The datasource of items with the item type being `{label, value, disabled, ...}`
 | `label` | `string` | The descriptive label of the item. |
 | `value` | `*` | The value of the item. |
 | `disabled` | `boolean=` | Whether the item is disabled. |
+| `exclusive` | `boolean=` | Whether the item is exclusive. |
 +++
 ^^^
 

one/docs/en-US/components/column.md

@@ -19,7 +19,7 @@ See [the demos of `Table`](./table#demos).
 | `width` | `string=|number=` | - | The column width in `px` value. |
 | `sortable` | `boolean=` | `false` | [^sortable] |
 | `align` | `string=` | - | The alignment of cell content in the column. Supports `left`/`center`/`right`. |
-| `span` | `function(number)=: Object` | | [^span] |
+| `span` | `function(number): Object=` | | [^span] |
 
 ^^^sortable
 Whether current column is sortable.

one/docs/en-US/components/date-picker.md

@@ -33,10 +33,11 @@ When selecting a date range, the `shortcuts` prop can be used to provide predefi
 | `week-start` | `number=` | `calendar.weekStart` | The start of a week. Can be [globally configured](./calendar#global-config). |
 | `fill-month` | `boolean=` | `true` | Whether to show dates of previous and next month in current panel when there's only one month panel. |
 | `date-class` | `string|Array|Object|function=` | `{}` | Custom HTML `class` for specified date. All [`class` expressions supported by Vue](https://vuejs.org/v2/guide/class-and-style.html#Binding-HTML-Classes) are available for non-function values. When specified as a function, whose signature is `function(Date): string|Array<string>|Object<string, boolean>`, the return value is also `class` expressions suppported by Vue. |
-| `disabled-date` | `function(Date)=: boolean` | `() => false` | Whether the specified date is disabled and cannot be selected. |
+| `disabled-date` | `function(Date, Date=): boolean=` | `() => false` | Used to customize whether the specified date is disabled or not. The first parameter is the date to be used to determine if the date is disabled. When in the range selection process and a date is already selected, it is passed as the second parameter. |
 | `clearable` | `boolean=` | `false` | Whether selected date (ranges) can be cleared. |
 | `placeholder` | `string=` | `range ? datepicker.rangePlaceholder : datepicker.placeholder` | The placeholder text displayed when nothing is selected. Can be [globally configured](./calendar#global-config). |
-| `format` | `string=` | `'YYYY-MM-DD'` | The format expression for displaying final selected date (ranges). See details at [the documentation of date-fns](https://date-fns.org/v1.29.0/docs/format). |
+| `format` | `string|function(Date): string=` | `'YYYY-MM-DD'` | When being string type, denotes the format expression for displaying final selected date (ranges). See details at [the documentation of date-fns](https://date-fns.org/v1.29.0/docs/format). Can also be a function to customize the formatting logic. |
+| `parse` | `function(string): Date=` | Custom function to parse the input string expressions into `Date` objects. |
 | `shortcuts` | `Array<Object>=` | `datepicker.shortcuts` | [^shortcuts] |
 | `shortcuts-position` | `string=` | `datepicker.shortcutsPosition` | The position of shortcuts. Can be either `'before'` or `'after'`, corresponding to the before or after the content of the month panel respectively. Can be [globally configured](./calendar#global-config). |
 | `disabled` | `boolean=` | `false` | Whether the date picker is disabled. |
@@ -182,6 +183,8 @@ The content of each date cell in the dropdown overlay. Displays the correspondin
 | Name | Description |
 | -- | -- |
 | `select` | [^event-select] |
+| `selectstart` | Triggered when selecting a date range and a start date is selected. The callback parameter list is `(picking: Date)`, being the selected start date. |
+| `selectprogress` | [^event-selectprogress] |
 
 ^^^event-select
 :::badges
@@ -191,6 +194,17 @@ The content of each date cell in the dropdown overlay. Displays the correspondin
 Triggered when the selected date (range) is changed. The callback parameter list is `(selected)` with `selected` having the same type with the `selected` prop.
 ^^^
 
+^^^event-selectprogress
+Triggered when selecting a date range and an end date is marked with pointer/keyboard interaction, and for each time the end date changes. The callback parameter list is `(picking)`, with `picking` being the marked date range. The type of `picking` depends on the value of the `multiple` prop.
+
++++Parameters types
+| `multiple` | Type |
+| -- | -- |
+| `false` | `[Date, Date]` |
+| `true` | `Array<[Date, Date]>` |
++++
+^^^
+
 ### Global config
 
 | Key | Type | Default | Description |

one/docs/en-US/components/dialog.md

@@ -40,7 +40,7 @@
 | `footless` | `boolean=` | `false` | Whether to hide the default footer. |
 | `loading` | `boolean=` | `false` | Wehter the dialog is in loading state. When loading, the OK button will enter loading state as well and become unclickable. |
 | `priority` | `number=` | - | The stacking priority of the dialog overlay. See the [`priority`](./overlay#props) prop of [`Overlay`](./overlay) component. |
-| `before-close` | `function(string)=: boolean=|Promise<boolean=>` | - | [^before-close] |
+| `before-close` | `function(string): boolean=|Promise<boolean=>` | - | [^before-close] |
 | `overlay-class` | `string|Object=` | - | The class expression applied to the root element of the dialog overlay. See the [`overlay-class`](./overlay#props) prop of [`Overlay`](./overlay) component. |
 
 ^^^ui

one/docs/en-US/components/input.md

@@ -35,6 +35,7 @@ Use the `disabled` prop to set an input to disabled state.
 | `clearable` | `boolean=` | `false` | Whether to show a clear button. |
 | `composition` | `boolean=` | `false` | Whether the input process should be aware of composition. |
 | `select-on-focus` | `boolean=` | `false` | Whether to select text content when focused. |
+| `get-length` | `function(string): number=` | Used to customize length calculation of the input. |
 
 ^^^ui
 Style variants.

one/docs/en-US/components/textarea.md

@@ -36,6 +36,7 @@ Use the `disabled` prop to set a textarea to disabled state.
 | `composition` | `boolean` | `false` | Whether the input process should be aware of composition. |
 | `select-on-focus` | `boolean` | `false` | Whether to select text content when focused. |
 | `autoresize` | `boolean` | `false` | Whether the textarea should automatically expand when the content exceeds default height. |
+| `get-length` | `function(string): number=` | Used to customize length calculation of the input. |
 
 ^^^ui
 预设样式。

one/docs/en-US/components/uploader.md

@@ -40,6 +40,8 @@ Set the `type` prop to `image` to use the image upload mode.
 | `progress` | `string` | `'text'` | [^progress] |
 | `autoupload` | `boolean` | `true` | Whether to start upload as soon as a file is selected. |
 | `order` | `string` | `asc` | [^order] |
+| `upload` | `function(Object, Object): function` | - | [^upload] |
+| `controls` | `function(Object, Array<Object>): Array<Object>` | - | [^controls] |
 
 ^^^type
 The type of the uploader.
@@ -144,6 +146,31 @@ The order of displaying uploaded files according to start time.
 +++
 ^^^
 
+^^^upload
+Customizing the upload process in case the value of `request-mode` is `'custom'`, the first parameter is the native [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) object and the second parameter is the object that contains callback functions associated with the upload process, with the following properties.
+
++++Properties
+| Property | Type | Description |
+| -- | -- | -- |
+| `onload` | `function` | The upload completion callback function whose arguments is the same as the `convert-response` prop's return value. |
+| `onprogress` | `function` | The callback function for upload progress, the parameter type being `{ loaded: number, total: number }`, `loaded` is the number of bytes that have been uploaded, and `total` is the total number of bytes in the file. |
+| `oncancel` | `function` | The callback to the component when the custom upload is actively cancelled, no parameters. |
+| `onerror` | `function` | The callback for upload error, the parameter type is `{ message: string }` and `message` is the error message. |
+
+If `upload` returns a function, it will be called when the user cancelled proactively or the upload component is destroyed, to abort the custom upload process.
+^^^
+
+^^^controls
+In image upload mode, it is used to customize the actions on the floating toolbar. The parameter types are `(file: Object, defaultControls: Array<Object>)`, where `file` is the file related information and `defaultControls` is the array containing the default actions. It can return an array of different actions depending on the file state. The specific properties for each action item are as follows.
+
++++Properties
+| Property | Type | Description |
+| -- | -- | -- |
+| `name` | `string` | The name of the action item. When the button is clicked, an event with the same name will be emitted, with `(file: Object, index: number)` as the callback parameter, `file` is the file object that triggered the event, and `index` is the number of the file in the list. |
+| `icon` | `string` | The icon of the action item. |
+| `disabled` | `boolean=` | Whether the action item is disabled. If this property is undefined, the disabled state of the action item follows the disabled state of the component. |
+^^^
+
 ### Slots
 
 | Name | Description |
@@ -162,7 +189,7 @@ The order of displaying uploaded files according to start time.
 | `extra-operation` | The content of extra operatins when under image upload mode, eg. custom buttons. Shares the same slot properties with slot `file'. |
 
 ^^^button-label
-The content of the uploader button. Suggests to select a file by default.
+The content of the uploader button. By default, it suggests to select a file for file uploaders and shows an upload icon for image uploaders.
 ^^^
 
 ^^^type-invalid
@@ -210,6 +237,7 @@ The content of each file.
 | `remove` | [^event-remove] |
 | `success` | Triggers when upload succeeded. Shares the same callback parameter list with the `remove` event. |
 | `failure` | Triggers when upload failed. Shares the same callback parameter list with the `remove` event. |
+| `invalid` | [^event-invalid] |
 | `statuschange` | [^event-statuschange] |
 | `progress` | [^event-progress] |
 
@@ -244,6 +272,34 @@ Fields added from `convert-response` are also available.
 +++
 ^^^
 
+^^^event-invalid
+Triggered when file validation fails. The callback parameter list is `(validity: Object)`.
+
++++Parameter properties
+| Name | Type | Description |
+| -- | -- | -- |
+| `file` | `Object` | The information about the file that failed the validation, being the same type as `file` in the callback parameter of the `remove` event. This property is empty if the validation fails because the number of files selected exceeds the `max-count` limit. |
+| `errors` | `Array<Object>` | Array of all the validation error messages of the file, each item in it is an object that contains validation failure information. |
++++
+
++++Validation error properties
+| Name | Type | Description |
+| -- | -- | -- |
+| `type` | `string` | The type of validation error, whose enum value can be accessed from the `Uploader.errors` object, eg. `Uploader.errors.SIZE_INVALID`. |
+| `value` | `number|string|Object` | The value that doesn't pass validation, can be different types depending on the `type` property. |
+| `message` | `string` | The validation error message. |
++++
+
++++Relationship between validation failure types and parameters
+| type | description | `value` type | `value` description |
+| -- | -- | -- | -- |
+| `TYPE_INVALID` | File type validation failure. | `string` | File name. |
+| `SIZE_INVALID` | File size validation failure. | `number` | File size in bytes. |
+| `TOO_MANY_FILES` | The number of selected files exceeds the `max-count` limit. | `number` | Number of files selected. |
+| `CUSTOM_INVALID` | Custom validation failure returned by `validator` prop. | `Object` | File object, same as `remove` event callback parameter. |
++++
+^^^
+
 ^^^event-statuschange
 Triggered when the status of the entire uploader changes. The callback parameter list is `(status: string)`.