taolin/docs_vue2
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: publicize doc implemetation

Browse Source
This commit is contained in:
Justineo
2020-08-13 11:47:56 +08:00
parent 55b9b044f2
commit 1e5fcff6ad
372 changed files with 50636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
one/docs/en-US/components/alert-box.md Normal file
View File

@@ -0,0 +1,69 @@
# AlertBox
## Demos
### Types
`AlertBox` component has 3 contextual types, which are `success`, `info`, ` and `error`. Types are specified with the `type` prop.
[[ demo src="/demo/alert-box/type.vue" ]]
### With title
You can customize the title of alert box with the `title` prop.
[[ demo src="/demo/alert-box/title.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `open` | `boolean` | `false` | [^open] |
| `type` | `string=` | `'success'` | [^type] |
| `title` | `string=` | - | The title of the alert box. |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^open
:::badges
`.sync`
:::
Whether the alert box is displayed.
^^^
^^^type
The contextual type of the alert box.
+++Enum values
| Value | Description |
| -- | -- |
| `info` | Information alert box. |
| `success` | Success alert box. |
| `error` | Error alert box. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the alert box. |
| `title` | The title of the alert box. Will ignore the `title` prop when specified. |
| `foot` | The foot area of the alert box. Displays an “OK” button by default. |
### Events
| Name | Description |
| -- | -- |
| `ok` | Triggered when the “OK” button is clicked. |
| `afterclose` | Triggered after the box overlay is closed. If leaving transition is provided by the theme, the event will be triggered after the transition completes. |
### Icons
| Name | Description |
| -- | -- |
| `info` | Information alert. |
| `success` | Success alert. |
| `error` | Error alert. |

91
one/docs/en-US/components/alert.md Normal file
View File

@@ -0,0 +1,91 @@
# Alert
## Demos
### Types
`Alert` component has 4 contextual types, which are `success`, `info`, `warning` and `error`. Types are specified with the `type` prop.
[[ demo src="/demo/alert/type.vue" ]]
### Multiple messages
The `message` prop can be an array to display multiple switchable messages.
[[ demo src="/demo/alert/multiple.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `type` | `string=` | `'success'` | [^type] |
| `title` | `string` | - | The alert title. |
| `message` | `string|Array<string>` | - | The alert message. When specified as an array, multiple messages will be displayed with previous/next navigation. |
| `closable` | `boolean=` | `false` | Whether the alert is allowed to be closed by users. |
| `open` | `boolean=` | `true` | [^open] |
| `index` | `number=` | `0` | [^index] |
^^^type
The contextual type of the alert message.
+++Enum values
| Value | Description |
| -- | -- |
| `info` | Information message. |
| `success` | Success message. |
| `warning` | Warning message. |
| `error` | Error message. |
+++
^^^
^^^open
:::badges
`.sync`
:::
Whether the message is displayed.
^^^
^^^index
:::badges
`.sync`
:::
The index of current message displayed when having multiple messages.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | [^scoped-slot-default] |
| `title` | The content area of the alert title. |
| `extra` | The extra content after the alert message. |
| `content` | The content of the whole component, including message text, status icon, previous/next navigation and close button. |
^^^scoped-slot-default
The content of the message.
Default: message text.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `message` | `string` | Message text. |
| `index` | `number=` | The index of current message displayed when having multiple messages. |
+++
^^^
### Icons
| Name | Description |
| -- | -- |
| `success` | Success message. |
| `warning` | Warning message. |
| `info` | Information message. |
| `error` | Error message. |
| `prev` | Previous message. |
| `next` | Next message. |
| `close` | Close alert. |

48
one/docs/en-US/components/breadcrumb-item.md Normal file
View File

@@ -0,0 +1,48 @@
# BreadcrumbItem
:::tip
`BreadcrumbItem` is required to be used within [`Breadcrumb`](./breadcrumb).
:::
## Demos
See [the demos of `Breadcrumb`](./grid-breadcrumb#demos).
## API
### Props
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `to` | `string|Object` | - | The target location. See [`Link`](./link#Props)'s the `to` prop. |
| `type` | `string` | `'link'` | [^link] |
| `native` | `boolean` | `false` | When set to `true` and `to` is specified, native `<a>` element will be used and `to` will be set as the `href` attribute to this `<a>` element. |
^^^link
The type of the item.
+++Enum values
| Value | Description |
| -- | -- |
| `link` | Hyperlink. |
| `text` | Pure text. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the breadcrumb item. |
### Events
| Name | Description |
| -- | -- |
| `redirect` | Triggered when clicking the item with `type` value `link`. The callback parameter list is `(event: Event)`. `event` is a [native click event object](https://developer.mozilla.org/en-US/docs/Web/Events/click). |
### Icons
| Name | Description |
| -- | -- |
| `separator` | The separator between adjacent breadcrumb items. |

116
one/docs/en-US/components/breadcrumb.md Normal file
View File

@@ -0,0 +1,116 @@
# Breadcrumb
:::tip
`Breadcrumb` can be used with embedded [`BreadcrumbItem`](./breadcrumb-item).
:::
## Demos
### Stylistic variants
Available style variants for the `ui` prop: `strong`.
[[ demo src="/demo/breadcrumb/style.vue" ]]
### Size variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/breadcrumb/size.vue" ]]
### Using inline `BreadcrumbItem`s
Can be used with embedded `BreadcrumbItem`s.
[[ demo src="/demo/breadcrumb/base.vue" ]]
### Using datasource
Can be used with the `routes` prop as well.
[[ demo src="/demo/breadcrumb/datasource.vue" ]]
### Customizable separators
Separators can be customized.
[[ demo src="/demo/breadcrumb/separator.vue" ]]
### Events mode
Handling `redirect` event instead of redirect with router.
[[ demo src="/demo/breadcrumb/redirect.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ui` | `string=` | - | [^ui] |
| `routes` | `Array<Object>` | `[]` | [^routes] |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^routes
The datasource for breadcrumb items. The type of items is `{label: string, type: string, to: string|Object=, native: boolean=}`. Properties apart from `label` can be referred to the props of [`BreadcrumbItem`](./breadcrumb-item) component.
:::warning
The last item will always be displayed as plain text by default.
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The items of the breadcrumb. Can only have [`BreadcrumbItem`](./breadcrumb-item) components as direct children. The `routes` prop will be ignored when this slot is specified. |
| `item` | [^slot-item] |
| `separator` | [^slot-separator] |
^^^slot-item
The content of each breadcrumb item. Default to the `label` properties of each item within `routes`, or the default slot content of [`BreadcrumbItem`]('./breadcrumb-item) components.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `route` | `Object` | The item in `routes`. Custom properties will also be passes into the scope object. |
+++
^^^
^^^slot-separator
Separator between adjacent breadcrumb items. Displays a globally configured icon by default.
:::warning
When using Vue.js version `2.5.17` and below, it's required to bind a `slot-scope`.
:::
^^^^
### Events
| Name | Description |
| -- | -- |
| `redirect` | [^redirect] |
^^^redirect
Triggered when clicking the item with `type` value `link`. The callback parameter list is `(event, route, index)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `event` | [Event](https://developer.mozilla.org/en-US/docs/Web/Events/click) | Native click event object. |
| `route` | `Object` | The corresponding route item in `routes`. |
| `index` | `number` | The index of the clicked item. |
+++
^^^

110
one/docs/en-US/components/button-group.md Normal file
View File

@@ -0,0 +1,110 @@
# ButtonGroup
## Demos
### Stylistic variants
Available style variants for the `ui` prop: `primary`/`strong`.
[[ demo src="/demo/button-group/style.vue" ]]
### Size variants
Available size variants for the `ui` prop: `xs`/`s`/`m`/`l`/`xl`.
[[ demo src="/demo/button-group/size.vue" ]]
### Use datasource via `items`
Use the `items` prop to provide content with a datasource.
[[ demo src="/demo/button-group/items.vue" ]]
### Disabled state
Use the `disabled` prop to set the button group to disabled state.
[[ demo src="/demo/button-group/disabled.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | - | [^items] |
| `disabled` | `boolean=` | `false` | Whether the button is disabled. |
^^^ui
Style variants. A space-separated list of enum values.
+++Enum values
| Value | Description |
| -- | -- |
| `primary` | Primary buttons. |
| `strong` | Strong buttons. |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
| `xl` | Extra large. |
+++
^^^
^^^items
The datasource array for buttons in the group. The type of each item is `{label, value}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The label text of the button. |
| `value` | `*=` | Will emit an event with the same name when given a string value. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | Button group's content. |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The content of each button.
Shows the text specified by the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The label text of the button. |
| `value` | `*=` | The value of button item. |
| `index` | `number` | The index of the button within `items`. |
| `disabled` | `boolean=` | Whether the button is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `click` | [^click-event] |
| <var>&lt;value&gt;</var> | [^value-var-event] |
^^^click-event
Triggered upon clicks. The callback parameter list is `(item, index)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `item` | `{label: string, value: *=, ...}` | Datasource item. |
| `index` | `number` | The index of the button within `items`. |
+++
^^^
^^^value-var-event
If the corresponding item has a string `value` property, an event with the name of `value` value will be emitted each time the button is clicked. It shares the same parameters with the `click` event.
^^^

93
one/docs/en-US/components/button.md Normal file
View File

@@ -0,0 +1,93 @@
# Button
## Demos
### Stylistic variants
Available style variants for the `ui` prop: `primary`/`strong`/`translucent`/`text`/`icon`.
[[ demo src="/demo/button/style.vue" ]]
### Size variants
Available size variants for the `ui` prop: `xs`/`s`/`m`/`l`/`xl`.
[[ demo src="/demo/button/size.vue" ]]
### Disabled state
Use the `disabled` prop to set a button to disabled state.
[[ demo src="/demo/button/disabled.vue" ]]
### Loading state
Use the `loading` prop to set a button to loading state (which will not respond upon clicks).
[[ demo src="/demo/button/loading.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `disabled` | `boolean=` | `false` | Whether the button is disabled. |
| `type` | `string=` | `'button'` | [^type] |
| `loading` | `boolean=` | `false` | Whether the button is in loading state. Loading buttons won't respond to user interactions. |
^^^ui
Style variants. A space-separated list of enum values.
+++Enum values
| Value | Description |
| -- | -- |
| `normal` | Normal button. Default style. |
| `primary` | Primary button. |
| `basic` | Basic button. |
| `strong` | Strong button. Can be used alone or together with `text`/`icon`. |
| `translucent` | Translucent button, typically used on dark background. |
| `text` | Text button. |
| `icon` | Icon button. |
| `aux` | Auxilary button. Need to be used with `text`/`icon` styles. |
| `square` | Square button. Can be used with other styles. |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
| `xl` | Extra large. |
+++
^^^
^^^type
The type of the button. See the [`type`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attr-type) attribute of HTML's native `<button>` element.
+++Enum
| Value | Description |
| -- | -- |
| `button` | Normal button. |
| `submit` | Submit button. Will cause an ancestor form to be submitted upon clicks. |
| `reset` | Reset button. Will reset all fields to initial value upon clicks. |
+++
:::warning
Note that the default value is different from the native `<button>` element. You need to explicitly set `type` to `submit` if you want to trigger a form submit.
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | Content of the button. |
### Events
Additionally, `Button` exposes all native events available for native `<button>` element. The callback parameter is the corresponding native event object for all events.
### Icons
| Name | Description |
| -- | -- |
| `loading` | The loading spinner. |

119
one/docs/en-US/components/calendar.md Normal file
View File

@@ -0,0 +1,119 @@
# Calendar
## Demos
### Selecting a single date
Click to select a single date by default.
[[ demo src="/demo/calendar/default.vue" ]]
### Selecting multiple dates or a date range
You can select multiple date with the `multiple` prop set to `true` and can select a date range with the `range` prop set to `true`.
[[ demo src="/demo/calendar/range-multiple.vue" ]]
### Selecting multiple date ranges
When `multiple` and `range` are both set to `true`, you can select multiple date ranges. You can configure the number of month panels with the `panel` prop. The way we merge newly selected ranges into those are already select are that, if you start select on a unselected date, the range will be selected and if start on a selected one, the range will be unselected.
[[ demo src="/demo/calendar/multiple-ranges.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `type` | `string=` | `'date'` | The type of the calendar. Available values include `'date'`/`'month'`/`'year'`, denoting date/month/year view respectively. When the value is not `'date'`, `multiple` and `range` will be ignored. |
| `multiple` | `boolean=` | `false` | Whether users can select multiple dates (date ranges). |
| `range` | `boolean=` | `false` | Whether users can select a date range (date ranges). |
| `selected` | `Date|Array=` | - | [^selected] |
| `panel` | `number=` | `1` | The number of month panel displayed. |
| `today` | `Date=` | `new Date()` | The date of “today”. |
| `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` | `boolean=` | `false` | Whether the calendar is disabled. |
| `readonly` | `boolean=` | `false` | Whether the calendar is read-only. |
^^^selected
:::badges
`v-model`
:::
Selected date(s) or date range(s). Data type differs according to `multiple` and `range`.
+++Value types
| `multiple` | `range` | Type |
| -- | -- | -- |
| `false` | `false` | `Date` |
| `true` | `false` | `Array<Date>` |
| `false` | `true` | `[Date, Date]` |
| `true` | `true` | `Array<[Date, Date]>` |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `before` | Customizable area before the content of the month panel(s). |
| `after` | Customizable area after the content of the month panel(s). |
| `date` | [^scoped-slot-date] |
^^^scoped-slot-date
The content of each date cell. Displays the corresponding day of month by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `year` | `number` | The full representation of year. |
| `month` | `number` | Month of a year, starting from `0` as January. |
| `date` | `number` | The day of month. |
+++
^^^
### Events
| 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] |
| `viewchange` | Triggered when the month of the month panel changes. The callback parameter list is `(month: Object<{year: number, month: number}>)`, representing the current year and month of the first month panel. |
^^^event-select
:::badges
`v-model`
:::
Triggered when selection change. The callback parameter list is `(selected)`. The type of `selected` is the same as 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 |
| -- | -- | -- | -- |
| `calendar.weekStart` | `number` | `1` | The start of a week, with Monday being `1` and Sunday being `7`. |
### Icons
| Name | Description |
| -- | -- |
| `prev` | Previous page. |
| `next` | Next page. |
| `expand` | Expand dropdowns. |

107
one/docs/en-US/components/carousel.md Normal file
View File

@@ -0,0 +1,107 @@
# Carousel
## Demos
### Switching items
Use the `index` to control the current item to be displayed.
[[ demo src="/demo/carousel/switch.vue" ]]
### Indicator type
Use the `indicator` prop to specify the type of step indicators.
[[ demo src="/demo/carousel/indicator.vue" ]]
### Autoplay
Use the `autoplay` prop to enable autoplay.
[[ demo src="/demo/carousel/autoplay.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `index` | `number=` | `0` | [^index] |
| `indicator` | `string=` | `'radio'` | [^indicator] |
| `switch-trigger` | `string=` | `'click'` | [^switch-trigger] |
| `autoplay` | `boolean=` | `false` | Whether to autoplay the carousel. |
| `pause-on-hover` | `boolean=` | `false` | Whether to pause the cycling on hover when autoplaying. |
| `interval` | `number=` | `3000` | The amount of time to delay between automatically cycling an item. |
| `wrap` | `boolean=` | `false` | Whether the carousel should cycle continuously or have hard stops. |
^^^datasource
The media datasource for the carousel, with the item type being `{src, alt, label}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `src` | `string` | The source of the image. |
| `alt` | `string` | The alternate text of the image. |
| `label` | `string` | Descriptive title of the image. |
+++
^^^
^^^index
:::badges
`.sync`
:::
The index of the current image within the datasource.
^^^
^^^indicator
The way the indicator is displayed.
+++Enum values
| Value | Description |
| -- | -- |
| `radio` | As radio buttons. |
| `number` | As numeric value in the form of *current item / total items*. |
| `none` | Not displayed. |
^^^
^^^switch-trigger
The behavior triggers item switch when radio indicator is displayed.
+++Enum values
| Value | Description |
| -- | -- |
| `click` | Switched on click. |
| `hover` | Switched on hover. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The content of each carousel item. Displays the corresponding image by default.
The slot scope properties are the same as each item inside `datasource` (including custom properties), with an extra `index: number`, which denotes the index within the datasource. i.e. The `slot-scope` is in the form of `{src, alt, label, index, ...}`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
Triggered the current item changed. The callback argument list is `(to: number, from: number)`. `to` and `from` denote the new index and the old index respectively.
^^^
### Icons
| Name | Description |
| -- | -- |
| `prev` | Previous item. |
| `next` | Next item. |

86
one/docs/en-US/components/check-button-group.md Normal file
View File

@@ -0,0 +1,86 @@
# CheckButtonGroup
## Demos
### Size variants
Available values for the `ui` prop: `s`/`m`.
[[ demo src="/demo/check-button-group/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `Array` | `[]` | [^value] |
| `disabled` | `boolean=` | `false` | Whether the check button group is disabled. |
| `readonly` | `boolean=` | `false` | Whether the check button group is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `m` | Medium. |
| `s` | Small. |
^^^
^^^items
The datasource of items with the item type being `{label, value, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The `value`s of the selected items.
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The label content of each button. Displays the value of the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `index` | `number` | The index of the item within `items`. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
Triggers when the selected item changed. The callback parameter list is `(value: Array)` and `value` is the value array of the selected items.
^^^

86
one/docs/en-US/components/checkbox-group.md Normal file
View File

@@ -0,0 +1,86 @@
# CheckboxGroup
## Demos
### Size variants
Available size variant for the `ui` prop: `s`/`m`.
[[ demo src="/demo/checkbox-group/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `Array` | `[]` | [^value] |
| `disabled` | `boolean=` | `false` | Whether the checkbox group is disabled. |
| `readonly` | `boolean=` | `false` | Whether the checkbox group is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
^^^
^^^items
The datasource of items with the item type being `{label, value, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The `value`s of the selected items.
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The label content of each checkbox. Displays the value of the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `index` | `number` | The index of the item within `items`. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
Triggers when the selected item changed. The callback parameter list is `(value: Array)` and `value` is the value array of the selected items.
^^^

83
one/docs/en-US/components/checkbox.md Normal file
View File

@@ -0,0 +1,83 @@
# Checkbox
## Demos
### Size variants
Available size variant for the `ui` prop: `s`/`m`.
[[ demo src="/demo/checkbox/size.vue" ]]
### True/false values
Use the `true-value` and `false-value` props to customize the `model` value (used in its `v-model`) of the checkbox in checked/unchecked state.
[[ demo src="/demo/checkbox/value.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `checked` | `boolean` | `false` | [^checked] |
| `value` | `*` | - | Denotes the value of current checkbox when `v-model` is bound to an array. |
| `true-value` | `*=` | `true` | The value for checked state. |
| `false-value` | `*=` | `false` | The value for unchecked state. |
| `indeterminate` | `boolean=` | `false` | Whether the checkbox is in an indeterminate state. |
| `disabled` | `boolean=` | `false` | Whether the checkbox is disabled. |
| `readonly` | `boolean=` | `false` | Whether the checkbox is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^checked
:::badges
`.sync`
:::
Whether the checkbox is checked.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The label text of the checkbox. The checkbox is toggled when the label is clicked. Displays nothing by default. |
### Events
| Name | Description |
| -- | -- |
| `change` | Triggered when user toggles the state of the checkbox. The callback parameter list is `(checked: boolean)`. `checked` denotes whether the checkbox is checked. |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
Triggered when the check state is changed. The callback parameter list is `(val: *)`, with `val` being the current value of `v-model`. Unlike the `change` event, `input` is triggered even without user interaction.
^^^
Additionally, `Checkbox` exposes the following native events:
`auxclick`, `click`, `contextmenu`, `dblclick`, `mousedown`, `mouseenter`, `mouseleave`, `mousemove`, `mouseover`, `mouseout`, `mouseup`, `select`, `wheel`, `keydown`, `keypress`, `keyup`, `focus`, `blur`, `focusin`, `focusout`.
The callback parameter is the corresponding native event object for all events above.
### Icons
| Name | Description |
| -- | -- |
| `checked` | Checked state. |
| `indeterminate` | Indeterminate state. |

73
one/docs/en-US/components/column.md Normal file
View File

@@ -0,0 +1,73 @@
# Column
:::tip
`Column` is required to be used within [`Table`](./breadcrumb).
:::
## Demos
See [the demos of `Table`](./table#demos).
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `title` | `string` | - | The column title. |
| `field` | `string` | - | The field name as a key of items in the `data` prop of the parent `Table` component. |
| `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] |
^^^sortable
Whether current column is sortable.
:::warning
`Table` and `Column` do not handle sorting. They only emit a `sort` event when the sorter is clicked so users need handle sorting themselves.
:::
^^^
^^^span
A function that defines how cells should span across rows/columns. The type is `function(index: number): { row: number, col: number }`, where `index` being the index of current row inside the `data` prop of the parent `Table`. The `row`/`col` of the return value correspond to table cell's `rowspan`/`colspan` attribut, with a default value of `1`.
:::tip
You can learn more abut how to use this in `Table` component's [Demos › Advanced](./table#advanced).
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `head` | The table head. |
| `foot` | [^slot-foot] |
| `default` | [^scoped-slot-default] |
| `sub-row` | [^scoped-slot-sub-row] |
^^^slot-foot
The table foot.
:::warning
`Column`'s `foot` slot will be ignored if users provide content for `Table`'s `foot` slot.
:::
^^^
^^^scoped-slot-default
The content of the table cell. Displays the property value corresponds to the `field` property in table's `data` prop.
The slot scope properties are the same as each item inside `data`, with an extra `index: number`, which denotes the index within the row data.
^^^
^^^scoped-slot-sub-row
The content of cells in a sub row. Sub row data comes from the `children` array inside the row data in `Table`s `data` prop. The number of sub rows are determined by the length of the `children` array and the sub rows share the same column configuration with the table.
Displays the value keyed by the `field` prop inside the sub row data, which is `data[i].children[j]` of the parent table.
The slot scope properties are the same as each item inside `children`, with an extra `index: number`, which denotes the index within the row data.
:::warning
The `sub-row` slot of `Column` will be ignored when content is provided for `Table`'s `sub-row` slot.
:::
^^^

41
one/docs/en-US/components/confirm-box.md Normal file
View File

@@ -0,0 +1,41 @@
# ConfirmBox
## Demos
The title and content are both customizable.
[[ demo src="/demo/confirm-box/custom.vue"]]
## API
### Props
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | [^open] |
| `title` | `string=` | - | The title of the confirm box. |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^open
:::badges
`.sync`
:::
Whether the confirm box is displayed.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the confirm box. |
| `title` | The title of the confirm box. Will ignore the `title` prop when specified. |
| `foot` | The foot area of the confirm box. Displays an “OK” and a “Cancel” button by default. |
### Events
| Name | Description |
| -- | -- |
| `ok` | Triggered when the “OK” button is clicked. |
| `cancel` | Triggered when the “Cancel” button is clicked. |
| `afterclose` | Triggered after the box overlay is closed. If leaving transition is provided by the theme, the event will be triggered after the transition completes. |

214
one/docs/en-US/components/date-picker.md Normal file
View File

@@ -0,0 +1,214 @@
# DatePicker
## Demos
### Selecting a single date
By default, you can click a date cell in the dropdown overlay to select a single date. Use the `clearable` prop to make selected values clearable. Use the `placeholder` prop to customize the description text displayed when nothing is selected yet.
[[ demo src="/demo/date-picker/default.vue" ]]
### Selecting a date range
When `range` is `true`, you can select a date range in the dropdown overlay.
[[ demo src="/demo/date-picker/range.vue" ]]
### Setting selection shortcuts
When selecting a date range, the `shortcuts` prop can be used to provide predefined date range shortcuts to be selected from.
[[ demo src="/demo/date-picker/shortcuts.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `range` | `boolean=` | `false` | Whether users can select a date range. When the value is not `'date'`, `range` will be ignored. |
| `selected` | `Date|Array=` | - | [^selected] |
| `panel` | `number=` | `1` | The number of month panel displayed in the dropdown overlay. |
| `today` | `Date=` | `new Date()` | The date of “today”. |
| `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. |
| `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). |
| `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. |
| `readonly` | `boolean=` | `false` | Whether the date picker is read-only. |
^^^selected
:::badges
`v-model`
:::
The selected date (range). Value type is determined by whether `range` is `true`.
+++Value types
| `range` | Type |
| -- | -- |
| `false` | `Date` |
| `true` | `[Date, Date]` |
+++
^^^
^^^shortcuts
Selection shortcuts can be custmized when selecting a date range. The data type is `Array<{label, from, to}>`. Can be [globally configured](./calendar#global-config).
+++Properties
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>label</code></td>
<td><code>string</code></td>
<td>Text displayed for the shortcut option.</td>
</tr>
<tr>
<td><code>from</code></td>
<td colspan="2">Denotes the start date of the shortcut option. See more at <a href="#date-offset-format-for-shortcut-option">Date offset format for shortcut option</a> below.</td>
</tr>
<tr>
<td><code>to</code></td>
<td colspan="2">Denotes the end date of the shortcut option. See more at <a href="#date-offset-format-for-shortcut-option">Date offset format for shortcut option</a> below.</td>
</tr>
</tbody>
</table>
+++
^^^
#### Date offset format for shortcut option
The `from` and `to` property in `shortcuts` options, which are used to calculate the start/end date of an shortcut option, share the same format which is `number|Object` and default to `0`.
* `number` values are the offset in days calculated against “today”. eg. `-1` means `{ startOf: 'day', days: -1 }`, which is “yesterday”.
* `Object` values have the type of `{startOf: string=, days: number=, weeks: number=, months: number=, }`.
+++Properties
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `startOf` | `string=` | `'day'` | The base date. Supported values include `'day'`/`'week'`/`'month'`/`'quarter'`/`'year'`. |
| `day` | `number=` | - | Offset in days. |
| `week` | `number=` | - | Offset in weeks. |
| `month` | `number=` | - | Offset in months. |
| `quarter` | `number=` | - | Offset in quarters. |
| `year` | `number=` | - | Offset in years. |
The final date is calculated by accumulating the offset onto the base date.
The following example with `label`s may help to better understand the calculation logic. You can rapidly set shortcut options once you understand the underlying logic.
```js
[
{
label: 'Last month',
// Turn back a month from the first day of current month,
// which is the first day of last month
from: {
startOf: 'month',
month: -1
},
// Turn back a day from the first day of current month,
// which is the last day of last month
to: {
startOf: 'month',
days: -1
}
},
{
label: 'This month',
// The first day of current month
from: {
startOf: 'month'
},
// Today
to: 0
},
{
label: 'This week',
// The first day of the week, days being 0 can be omitted
from: {
startOf: 'week',
days: 0
},
// Today
to: 0
},
{
label: 'Last 7 days',
// Turn back 6 days backward from today
from: -6,
// To today
to: 0
},
{
label: 'Today',
to: 0
}
]
```
### Slots
| Name | Description |
| -- | -- |
| `date` | [^scoped-slot-date] |
^^^scoped-slot-date
The content of each date cell in the dropdown overlay. Displays the corresponding day of month by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `year` | `number` | The full representation of year. |
| `month` | `number` | Month of a year, starting from `0` as January. |
| `date` | `number` | The day of month. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
Triggered when the selected date (range) is changed. The callback parameter list is `(selected)` with `selected` having the same type with the `selected` prop.
^^^
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `datepicker.shortcuts` | `Array` | `[]` | Default shortcut options. |
| `datepicker.shortcutsPosition` | `string` | `'before'` | Shows the shortcut options before or after month panels. Corresponds to `'before'` and `'after'` respectively. |
| `datepicker.placeholder` | `string` | `@@datepicker.selectDate` | Placeholder text displayed when selecting a single date. |
| `datepicker.monthPlaceholder` | `string` | `@@datepicker.selectMonth` | Placeholder text displayed when selecting a month. |
| `datepicker.yearPlaceholder` | `string` | `@@datepicker.selectYear` | Placeholder text displayed when selecting a year. |
| `datepicker.rangePlaceholder` | `string` | `@@datepicker.selectRange` | Placeholder text displayed when selecting a date range. |
:::tip
`@@` prefixed values denote corresponding properties in the locale settings.
:::
### Icons
| Name | Description |
| -- | -- |
| `calendar` | Calendar. |
| `clear` | Clear selection. |

130
one/docs/en-US/components/dialog.md Normal file
View File

@@ -0,0 +1,130 @@
# Dialog
## Demos
### Modal and non-modal
[[ demo src="/demo/dialog/modal.vue" ]]
### Customized content
[[ demo src="/demo/dialog/custom.vue" ]]
### Async support
[[ demo src="/demo/dialog/async.vue" ]]
### Draggable
[[ demo src="/demo/dialog/draggable.vue" ]]
### Stacking order
[[ demo src="/demo/dialog/stack.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `modal` | `boolean=` | `true` | Whether to display a backdrop to block interactions with the content underneath. Modal dialogs preempt focus by default (will return focus when closed). |
| `title` | `string=` | - | The title of the dialog. Will be ignored if `title` slot is specified. |
| `open` | `boolean=` | `false` | [^open] |
| `closable` | `boolean=` | `true` | Whether to display a close button at the top right corner. |
| `outside-closable` | `boolean=` | `false` | Wether to close the dialog when user click outside. |
| `draggable` | `boolean=` | `false` | Whether the dialog is draggable. |
| `escapable` | `boolean=` | `false` | Whether to allow closing the dialog after pressing <kbd>esc</kbd>. Only works when `closable` is set to `true`. |
| `inline` | `boolean=` | `false` | Whether the dialog is displayed inline thus takes up space. |
| `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] |
| `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
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small sized content (not the dimension of the dialog itself). |
| `m` | Medium sized content (not the dimension of the dialog itself). |
| `narrow` | Narrow width. |
| `medium` | Medium width. |
| `wide` | Wide width. |
| `fullscreen` | Fullscreen dialogs. |
| `auto` | Auto-fit dialogs. |
+++
^^^
^^^open
:::badges
`.sync`
:::
Whether the dialog is open.
^^^
^^^before-close
Executed when user interaction is about to trigger closing the dialog. The type is `function(type: string): boolean=|Promise<boolean=>`, where `type` being the action type of the closing behavior. Available values by default are `'ok'/'cancel'`. The return value can be a `boolean` or a `Promise` that resolves a `boolean` value, to handle the situation that an async process is responsible for deciding whether to close the dialog. Will keep the dialog open when returning `false` or the `Promise` resolves with `false`.
+++Code example
```html
<veui-dialog :open.sync="dialogOpen" :before-close="submit">...</veui-dialog>
```
```js
methods: {
submit (type) {
if (type === 'ok') {
return axios.post('/item/create', {/* ... */})
.then(({ id, error }) => {
if (error) {
this.showError(error)
return false // resolving `false` will keep the dialog open
}
})
}
// resolving non-`false` value will close the dialog
},
// ...
}
```
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the dialog. |
| `title` | The title of the dialog. Will ignore the `title` prop if this slot is specified. |
| `foot` | [^slot-foot] |
^^^slot-foot
The foot of the dialog. Displays “OK” and “Cancel” buttons by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `close` | `function(type: string): void` | The callback to trigger closing the dialog. `type` is the action type and will be passed into `before-close` hook as the first argument. And an event named after `type` will be triggered synchronously. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `ok` | Triggered after the “OK” button is clicked or the dialog is closed with the slot scope function call `close('ok')`. |
| `cancel` | Triggered after the “Cancel” button or the close button is clicked, or <kbd>esc</kbd> is pressed, or the dialog is closed with the slot scope function call `close('cancel')`. |
| <var>&lt;value&gt;</var> | Triggered when the dialog is closed with the slot scope function call `close(value)`. |
| `afterclose` | Triggered after the dialog is closed. If leave transition is provided by theme, then `afterclose` will be triggered when the transition finishes. |
### Icons
| Name | Description |
| -- | -- |
| `close` | Close. |

162
one/docs/en-US/components/dropdown.md Normal file
View File

@@ -0,0 +1,162 @@
# Dropdown
:::tip
`Dropdown` can be used with embedded [`Option`](./option) or [`OptionGroup`](./option-group).
:::
## Demos
### Style variants
Available style variants for the `ui` prop: `primary`/`text`.
[[ demo src="/demo/dropdown/style.vue" ]]
### Size variants
Available size values for the `ui` prop: `xs`/`s`/`m`/`l`.
[[ demo src="/demo/dropdown/size.vue" ]]
### Using embedded `OptionGroup`s & `Option`s
Can be used with embedded `OptionGroup`s & `Option`s.
[[ demo src="/demo/dropdown/inline.vue" ]]
### Searchable dropdown
Using`searchable` prop to make the component support search functionality.
[[ demo src="/demo/dropdown/searchable.vue" ]]
### Disabled dropdown
Use the `disabled` property in `options` items to disable single option.
[[ demo src="/demo/dropdown/disable.vue" ]]
### Trigger and split
Use the `trigger` prop to specify when to open the dropdown menu. Use the `split` prop to separate command button and dropdown button.
[[ demo src="/demo/dropdown/other.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `options` | `Array<Object>=` | `[]` | [^options] |
| `label` | `string` | - | The descriptive label of the dropdown button. |
| `trigger` | `string=` | `'click'` | When to trigger the dropdown to open. Available values are `'click'`/`'hover'`. |
| `split` | `boolean=` | `false` | Whether to split the dropdown button into a command button and a toggle button for the dropdown layer. |
| `disabled` | `boolean=` | `false` | Whether the dropdown is disabled. |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `primary` | Primary style. |
| `text` | Text style. |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
^^^
^^^options
The list of options with the option type being `{label, value, dropdown, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `options` | `Array<Object>=` | The child options of current option. The item type is the same as the items of the `options` prop. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the options dropdown layer. Can be used to place `Option`s or `OptionGroups`s when the `options` prop is not specified. |
| `before` | The content before the options in the dropdown layer. |
| `after` | The content after the options in the dropdown layer. |
| `label` | [^scoped-slot-label] |
| `group-label` | [^scoped-slot-group-label] |
| `option-label` | [^scoped-slot-option-label] |
| `option` | [^scoped-slot-option] |
^^^scoped-slot-label
The content of the select button. Displays the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the dropdown option. |
+++
^^^
^^^scoped-slot-group-label
The label text of each option group (option with child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option group. |
| `disabled` | `boolean=` | Whether the option group is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option-label
The label text of each option (option without child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option
The entire content area of each option (option without child `options`). Displays the default content of `Options` component by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `click` | Triggered when an option is clicked. The callback parameter list is `(value: *=)`. `value` is the `value` property of the option being clicked. Also triggered when `split` is `true` and the command button is clicked, in this case there won't be a `value` argument. |
### Icons
| Name | Description |
| -- | -- |
| `expand` | Expand the dropdown layer. |
| `collapse` | Collapse the dropdown layer. |

58
one/docs/en-US/components/filter-panel.md Normal file
View File

@@ -0,0 +1,58 @@
# FilterPanel
## Demos
[[ demo src="/demo/filter-panel/default.vue"]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | Datasource of the filter with the type being `{label: string, ...}`. |
| `searchable` | `boolean=` | `true` | Whether to allow search. |
| `filter` | `function=` | See description. | [^filter] |
| `search-on-input` | `boolean=` | `true` | Whether to trigger search while typing. |
| `placeholder` | `string=` | - | The placeholder text of the search input. |
^^^filter
The filter function. The function signature is `function(keyword, item, index, datasource): boolean`. Items that make filter function returns `false` will be hidden.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `keyword` | `string` | The search keyword. |
| `item` | `Object` | Each item in `datasource`. |
| `index` | `number` | The index of each item among its siblings. |
| `datasource` | `Array<{label: string, ...}>` | Same as the `datasource` prop. |
+++
+++Default value
```js
import { includes } from 'lodash'
function (keyword, { label }) {
return includes(label, keyword)
}
```
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `head` | The head area of the filter panel. Displays the `title` prop by default. |
| `no-data` | Content to be displayed when `datasource` is empty. |
| `default` | [^default] |
^^^default
The content of the filter panel.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `items` | `Array<Object>` | The filtered items from the `datasource` prop and shares the same type with `datasource`. |
+++
^^^

26
one/docs/en-US/components/grid-column.md Normal file
View File

@@ -0,0 +1,26 @@
# GridColumn
:::tip
`GridColumn` is required to be used with [`GridContainer`](./grid-container) and [`GridRow`](./grid-row).
:::
## Demos
See [the demos of `GridContainer`](./grid-container#demos).
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `span` | `number=` | - | The number of original grid columns to span. If not specified it will span across the whole row. |
| `offset` | `number=` | `0` | The number of original grid columns to move current column to the right. Will affect the position of following columns. |
| `pull` | `number=` | `0` | The number of original grid columns to move current column to the left. Will *not* affect the position of following columns. |
| `push` | `number=` | `0` | The number of original grid columns to move current column to the right. Will *not* affect the position of following columns. |
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the grid column. |

48
one/docs/en-US/components/grid-container.md Normal file
View File

@@ -0,0 +1,48 @@
# GridContainer
:::tip
`GridContainer` is required to be used with [`GridRow`](./grid-row) and [`GridColumn`](./grid-row).
:::
## Demos
### Default grid
[[ demo src="/demo/grid/default.vue" browser="/demos/grid/default.vue" ]]
### Fixed-width grid
[[ demo src="/demo/grid/fixed.vue" browser="/demos/grid/fixed.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `columns` | `number` | `gridcontainer.columns` | The number of columns. |
| `margin` | `number` | `gridcontainer.margin` | Margin around both sides of the grid container in `px`. |
| `gutter` | `number` | `gridcontainer.gutter` | Gutter between adjacent grid columns in `px`. |
| `width` | `number` | - | The width of the grid container in `px` when creating fixed-width grids. |
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the grid. Can only have [`GridRow`](./grid-row) components as direct children. |
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `gridcontainer.columns` | `number` | `12` | The number of columns. |
| `gridcontainer.gutter` | `number` | `30` | Gutter between adjacent grid columns in `px`. |
| `gridcontainer.margin` | `number` | `0` | Margin around both sides of the grid container in `px`. |
#### Default config in `veui-theme-dls`
| Key | Type | Default |
| -- | -- | -- | -- |
| `gridcontainer.columns` | `number` | `24` |
| `gridcontainer.gutter` | `number` | `20` |
| `gridcontainer.margin` | `number` | `20` |

17
one/docs/en-US/components/grid-row.md Normal file
View File

@@ -0,0 +1,17 @@
# GridRow
:::tip
`GridRow` is required to be used with [`GridContainer`](./grid-container) and [`GridColumn`](./grid-row).
:::
## Demos
See [the demos of `GridContainer`](./grid-container#demos).
## API
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the grid row. Can only have [`GridColumn`](./grid-column) components as direct children. |

33
one/docs/en-US/components/icon.md Normal file
View File

@@ -0,0 +1,33 @@
# Icon
:::tip
VEUI's `Icon` component is compatible with [Vue-Awesome](https://github.com/Justineo/vue-awesome), including icon registration and specifying icon with a string-typed `name` prop. The `name` prop also accept a component definition directly.
:::
## Demos
[[ demo src="/demo/icon/default.vue"]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `name` | `string|Object` | - | The name of the icon or its component definition. |
| `label` | `string` | - | The descriptive label for the icon, which is accessible to assistive devices. The icon is hidden for assistive devices if `label` doesn't exist. |
| `scale` | `number` | - | The size scale of the icon. Doesn't scale by default. |
| `spin` | `boolean` | `false` | Whether the icon should be spinning. |
| `pulse` | `boolean` | `false` | Whether the icon should be pulsing. |
| `inverse` | `boolean` | `false` | Whether to inverse the color. (Having a white foreground to be used against dark backgrounds.) |
| `flip` | `string` | - | How to flip an icon. Can be either `'horizontal'` or `'vertical'`. |
:::warning
When specifying a component definition for the `name` prop, only `spin` prop is supported.
:::
### Slots
| Name | Description |
| -- | -- |
| `default` | Can be used to implement a stacked icon. The embedded `Icon` components will be stacked together, being centered. The wrapper `Icon` doesn't require the `name` prop. |

119
one/docs/en-US/components/input.md Normal file
View File

@@ -0,0 +1,119 @@
# Input
## Demos
### Size variants
Available size variants for the `ui` prop: `xs`/`s`/`m`/`l`.
[[ demo src="/demo/input/size.vue" ]]
### Read-only state
Use the `readonly` prop to set an input to read-only state.
[[ demo src="/demo/input/readonly.vue" ]]
### Disabled state
Use the `disabled` prop to set an input to disabled state.
[[ demo src="/demo/input/disabled.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `value` | `string` | '' | [^value] |
| `disabled` | `boolean=` | `false` | Whether the input is disabled. |
| `readonly` | `boolean=` | `false` | Whether the input is read-only. |
| `type` | `string=` | `'text'` | [^type] |
| `placeholder` | `string=` | - | The placeholder text of the input. |
| `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. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The value of the input.
^^^
^^^type
The type of the input. See the [`type`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-type) attribute of HTML's native `<input>` element.
+++Enum
| Value | Description |
| -- | -- |
| `text` | Plain text input. |
| `password` | Password input. |
| `hidden` | Hidden input but holds a value to submit. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `before` | The content before the input area inside the component. |
| `after` | The content after the input area inside the component. |
:::warning
Slots will squeeze the width of the input area.
:::
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
| `input` | [^event-input] |
^^^event-change
Triggered when the input value is changed like the native `change` event. The callback parameter list is `(value, event)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `value` | `string` | The value of the input. |
| `event` | [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/change) | Native change event object. |
+++
^^^
^^^event-input
:::badges
`v-model`
:::
Triggered when inputting into the input. Affected by the `composition` prop. The callback parameter list is `(value: string)`, where `value` is the current value of the input.
^^^
Additionally, `Input` exposes the following native events:
`auxclick`, `click`, `contextmenu`, `dblclick`, `mousedown`, `mouseenter`, `mouseleave`, `mousemove`, `mouseover`, `mouseout`, `mouseup`, `select`, `wheel`, `keydown`, `keypress`, `keyup`, `focus`, `blur`, `focusin`, `focusout`.
The callback parameter is the corresponding native event object for all events above.
### Icons
| Name | Description |
| -- | -- |
| `remove` | Remove button. |

51
one/docs/en-US/components/link.md Normal file
View File

@@ -0,0 +1,51 @@
# Link
## Demos
[[ demo src="/demo/link/default.vue"]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `to` | `string|Object` | - | Denotes the target route of the link. When used with Vue Router, the value will be passed to a [`<router-link>`](https://router.vuejs.org/api/#router-link)'s [`to`](https://router.vuejs.org/api/#to) prop. Otherwise only `string` type is supported, and the value will output to the `href` attribute of an `<a>` element. |
| `rel` | `string` | - | Specifies the relationship of the target object to the link object. Refer to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types) for more details. |
| `target` | `string` | - | [^target] |
| `native` | `boolean` | `false` | Whether to enforce the use of native `<a>` element (instead of `<router-link>`). |
| `fallback` | `string` | `'span'` | Specifies the fallback element type when no `to` prop is specified. |
| `disabled` | `boolean=` | `false` | Whether the link is disabled. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `strong` | Strong style. |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^target
Specifies where to display the linked content. Refer to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target) for more details.
:::tip
When `target` has a value of `_blank`, a `noopener` token will be automatically added into `rel` (if not already exist) to enhance safety for free.
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the link. |
### Events
| Name | Description |
| -- | -- |
| `click` | Triggered upon clicks when the `to` prop is falsy or the `native` prop is `true`. The callback parameter list is `(event)`, where the type of `event` is HTML's native [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/click). |

56
one/docs/en-US/components/loading.md Normal file
View File

@@ -0,0 +1,56 @@
# Loading
## Demos
### Stylistic variants
Available style variants for the `ui` prop: `normal`/`strong`/`reverse`.
[[demo src="/demo/loading/style.vue"]]
### Size variants
Available size variants for the `ui` prop: `s`/`m`/`l`.
[[demo src="/demo/loading/size.vue"]]
### Layout variants
Available layout variants for the `ui` prop: `vertical`.
[[demo src="/demo/loading/layout.vue"]]
### Custom loading icons
Using `spinner` slot to replace default loading icon.
[[demo src="/demo/loading/slot.vue"]]
## API
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | `normal` `m` | [^ui] |
| `loading` | `boolean` | `false` | Whether the component is in loading state. |
^^^ui
Style variants. A space-separated list of enum values.
+++Enum
| Value | Description |
| -- | -- |
| `strong` | Strong style. |
| `reverse` | Reverse style, typically used on dark background. |
| `vertical` | Vertical style.|
| `s` | Small style. |
| `m` | Medium. |
| `l` | Large style. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `spinner` | Loading icon. |
| `default` | Loading description. |

113
one/docs/en-US/components/option-group.md Normal file
View File

@@ -0,0 +1,113 @@
# OptionGroup <small>选择组</small>
:::tip
`Option` is required to be used within [`Select`](./select), [`Dropdown`](./dropdown) or other `OptionGroup`, and can be used with [`Option`](./option).
:::
## Demos
See [the demos of `Select`](./select#demos) or [the demos of `Dropdown`](./dropdown#demos).
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `label` | `string` | The descriptive label of the option group. |
| `options` | `Array<Object>` | `[]` | [^options] |
| `position` | `string` | `inline` | [^position] |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^options
The list of options with the option type being `{label, value, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
^^^
^^^position
The way to display child options.
+++Enum values
| Value | Description |
| -- | -- |
| `inline` | Displays child options inline. |
| `popup` | Displays child options in a separate popup menu. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the options dropdown. Can be used to place `Option`s or `OptionGroups`s when the `options` prop is not specified. |
| `label` | [^scoped-slot-label] |
| `group-label` | [^scoped-slot-group-label] |
| `option-label` | [^scoped-slot-option-label] |
| `option` | [^scoped-slot-option] |
^^^scoped-slot-label
The label of the option group. Displays the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option group. |
| `disabled` | `boolean=` | Whether the option group is disabled. |
+++
^^^
^^^scoped-slot-group-label
The label text of each option group (option with child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option group. |
| `disabled` | `boolean=` | Whether the option group is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option-label
The label text of each option (option without child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option
The entire content area of each option (option without child `options`). Displays the default content of `Options` component by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
### Icons
| Name | Description |
| -- | -- |
| `expandable` | Expandable options. |

37
one/docs/en-US/components/option.md Normal file
View File

@@ -0,0 +1,37 @@
# Option
:::tip
`Option` is required to be used within [`Select`](./select), [`Dropdown`](./dropdown) or [`OptionGroup`](./option-group).
:::
## Demos
See [the demos of `Select`](./select#demos) or [the demos of `Dropdown`](./dropdown#demos).
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `disabled` | `boolean=` | Whether the option is disabled. |
| `hidden` | `boolean=` | `false` | Whether the option is hidden. |
### Slots
| Name | Description |
| -- | -- |
| `default` | The entire content area of the option. Displays the label and potential check icon by default.
| `label` | The content of the option label. Displays the `label` prop by default. |
### Events
The `click` event is triggered upon clicks without callback parameters.
### Icons
| Name | Description |
| -- | -- |
| `checked` | Checked state. |

102
one/docs/en-US/components/overlay.md Normal file
View File

@@ -0,0 +1,102 @@
# Overlay
## Demos
### Custom positioning
Overlays can be positioned with custom styles.
[[ demo src="/demo/overlay/position.vue" ]]
### Position relative to an element
Overlays can also be positioned relative to an existing DOM element in the page.
[[ demo src="/demo/overlay/relative-base.vue" ]]
### Stacking order
For sibling overlays with same priority, the ones opened later have a higher stacking order.
[[ demo src="/demo/overlay/stack-display-order.vue" ]]
Opened overlays will establish new stacking contexts and overlays opened inside those overlays will have higher stacking order than their parents.
[[ demo src="/demo/overlay/stack-on-overlay.vue" ]]
The stacking order of child overlays a affected by their parent overlays.
[[ demo src="/demo/overlay/stack-display-order-with-on-overlay.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | Style variants. Not defined by `veui-theme-dls` but can be customized. |
| `open` | `boolean` | `false` | [^open] |
| `target` | `string|Vue|HTMLElement` | - | [^target] |
| `priority` | `number` | - | [^priority] |
| `autofocus` | `boolean` | - | Whether to automatically focus the first focusable element in the overlay. |
| `modal` | `boolean` | `false` | Whether the overlay will preempt focus and trap focus upon keyboard navigation (will return focus when closed). |
| `inline` | `boolean` | `false` | Whether to render the overlay as inline content. |
| `local` | `boolean` | `false` | Whether to keep the overlay in it's original DOM location, instead of moving it to the global scope and participates in the [global overlay management](../advanced/overlay). |
| `overlay-class` | `string|Array|Object=` | - | [^overlay-class] |
| `options` | `Object` | Configuration object passed to the `modifiers` option of the underlying Popper.js implementation. See [here](https://popper.js.org/docs/v1/#modifiers) for more details. |
^^^open
:::badges
`.sync`
:::
Whether the overlay is displayed.
^^^
^^^target
Either of a valid [`ref`](https://vuejs.org/v2/guide/components-edge-cases.html#Accessing-Child-Component-Instances-amp-Child-Elements), a [Vue component instance](https://vuejs.org/v2/guide/instance.html) or an HTML [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) can be used to specify the target element to be relatively positioned against. The positioning logic is specified by `position` and `options`.
+++Value types
| Type | Description |
| -- | -- |
| `string` | A ref inside current component context's `$refs` object. Uses the root element when matches a component. |
| `Vue` | When specified as a Vue component instance, use its root element. |
| `HTMLElement` | Specify the HTML element directly. |
+++
^^^
^^^priority
The stacking order priority of current overlay. For all overlays under same parent overlay in the stacking context tree, the overlay with higher priority will be displayed over those with lower priority.
:::tip
As the root elements of all overlays will be placed as direct children of the `<body>` element, a custom global stacking context mechanism is implemented in VEUI's overlay manager to better control the stacking order of all overlays. The parent-child relationship between overlay components creates tree hierarchy of the stacking context. Sibling overlays are stacked according to their `priority`. Those share the same `priority` value are stacked according to the time when they are instantiated, the ones are instantiated later displays on top of earlier ones.
:::
^^^
^^^overlay-class
The class expression applied to the root element of the overlay. Supports all values defined by [Vue's `class` expressions](https://vuejs.org/v2/guide/class-and-style.html#Binding-HTML-Classes).
:::tip
As the root element of all overlays are placed as direct children of the `<body>` element, this prop can be used to specify custom classes for the root element to customize styles.
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the overlay. |
### Events
| Name | Description |
| -- | -- |
| `locate` | Triggered when the overlay updated its location. |
| `afteropen` | Triggered after the overlay is opened. If leave transition is provided by theme, then `afteropen` will be triggered when the transition finishes. |
| `afterclose` | Triggered after the overlay is closed. If leave transition is provided by theme, then `afterclose` will be triggered when the transition finishes. |
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `overlay.overlayClass` | `string|Array|Object=` | `[]` | The class name to be applied to every overlay. Supports all values defined by [Vue's `class` expressions](https://vuejs.org/v2/guide/class-and-style.html#Binding-HTML-Classes). |

67
one/docs/en-US/components/pagination.md Normal file
View File

@@ -0,0 +1,67 @@
# Pagination
## Demos
### Size variants
[[ demo src="/demo/pagination/size.vue" ]]
### Go to a specific page
Use the `goto` prop to enable the go to page section.
[[ demo src="/demo/pagination/goto.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `page` | `number` | `1` | Current page index (starts from `1`). |
| `total` | `number` | - | Total page count. |
| `to` | `string|Object` | `''` | [^to] |
| `native` | `boolean` | `false` | Use native links for navigation. |
| `page-size` | `number` | `pagination.pageSize` | [^page-size] |
| `page-sizes` | `Array` | `pagination.pageSizes` | The predefined available page sizes for users to select. |
| `goto` | `boolean` | `false` | Whether to show “goto page number” section. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^to
The page path template. The type is the same as the `to` prop of [`Link`](./link#props) component. When being `string`, the `:page` placeholder will be replaced with the actual page number. When being `Object`, the value will be resolved to string first and be go through the same placeholder replacement process.
^^^
^^^page-size
:::badges
`.sync`
:::
The count of item in each page.
^^^
### Events
| Name | Description |
| -- | -- |
| `pagesizechange` | Triggered when `page-size` is changed. The callback parameter list is `(size: number)`, with `size` being the new `page-size` value. |
| `redirect` | Triggered when page links are activated. The callback parameter list is `(page: number, event: Object)`. `page` is the number of the targe page. `event` is the native event object, calling `event.preventDefault` will stop navigation when `native` is `true`. |
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `pagination.pageSize` | `number` | `30` | The count of item in each page. |
| `pagination.pageSizes` | `Array<number>` | `[30, 50, 100]` | The predefined available page sizes for users to select. |

70
one/docs/en-US/components/popover.md Normal file
View File

@@ -0,0 +1,70 @@
# Popover
## Demos
### Style variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/popover/ui.vue" ]]
### Position
Use the `position` prop to specify the placement of the popover.
[[ demo src="/demo/popover/position.vue" ]]
### Triggers
Use the `trigger` prop to specify when to show/hide the popover.
[[ demo src="/demo/popover/trigger.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `open` | `boolean` | `false` | [^open] |
| `target` | `string|Vue|Node` | - | See the [`target` prop](./overlay#props) of thh [`Overlay`](./overlay) component. |
| `position` | `string` | `'top'` | [^position] |
| `trigger` | `string` | `'hover'` | [^trigger] |
| `hide-delay` | `number` | `tooltip.hideDelays` | Time (in milliseconds) to wait before hiding the popover after the close trigger is triggered. Can be used to prevent the popover being immediately closed after pointer leaves the `target` element and before it enters the popover itself. |
| `overlay-class` | `string|Array|Object=` | - | See the [`overlay-class` prop](./overlay#props) of the [`Overlay`](./overlay) component. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | small border radius. |
| `m` | middle border radius. |
+++
^^^
^^^open
:::badges
`.sync`
:::
Whether the popover is displayed.
^^^
^^^position
Denotes the target element of the popover. Used with [Popper.js](https://popper.js.org/)-style placement syntax, see [`Popper.placements`](https://popper.js.org/popper-documentation.html#Popper.placements).
^^^
^^^trigger
The event that triggers the toggle of the popover. Can take valid values for `v-outside` directive's `trigger` parameter, and can use <code>&#0096;${open}-${close}&#0096;</code> syntax to specify different trigger event for showing/hiding the popover. When specified as `custom`, `v-outside` will not be leveraged to automatically toggle the popover.
eg. `click` denotes showing the popover after clicking the `target` and hiding it after clicking outside. `hover-mousedown` denotes showing the popover after hovering the `target`, and hiding it after clicking outside.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the popover. |

58
one/docs/en-US/components/progress.md Normal file
View File

@@ -0,0 +1,58 @@
# Progress
## Demos
[[ demo src="/demo/progress/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `type` | `string` | `'bar'` | The type of the progress. Available values are `bar`/`circular`, denoting progress bar and progress circle respectively. |
| `desc` | `boolean` | `false` | The description of the progress. |
| `value` | `number` | `0` | Progress value. |
| `min` | `number` | `0` | Minimum value. |
| `max` | `number` | `1` | Max value. |
| `decimal-place` | `number` | `0` | Decimal place for the progress value. |
| `status` | `string` | - | [^status] |
| `autosucceed` | `boolean|number` | - | Whether automatically enter the `success` status when the progress reaches the maximum value. `true` denotes entering immediately, while `number` values denotes the delay in milliseconds before entering the `success` status. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `fluid` | Fluid layout for progress bar. |
| `s` | Small. |
| `m` | Medium. |
^^^
^^^status
:::badges
`.sync`
:::
The status of the progress. Available values are `success`/`alert`, denoting success and alert status respectively.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | [^scoped-slot-default] |
^^^scoped-slot-default
The description content. Displays the percentage value of the progress by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `percent` | `number` | The percentage value of the progress. |
| `value` | `number` | The value of the progress, same as the `value` prop. |
| `status` | `string` | The status of the progress, same as the `status` prop. |
+++
^^^

58
one/docs/en-US/components/prompt-box.md Normal file
View File

@@ -0,0 +1,58 @@
# PromptBox
## Demos
[[ demo src="/demo/prompt-box/base.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | [^open] |
| `title` | `string` | - | The title of the prompt box. |
| `content` | `string` | - | The description text above the text input. |
| `value` | `string` | `''` | [^value] |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^open
:::badges
`.sync`
:::
Whether the prompt box is displayed.
^^^
^^^value
:::badges
`v-model`
:::
The value of the prompt input.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the prompt box. |
| `title` | The title of the prompt box. Will ignore the `title` prop when specified. |
| `foot` | The foot area of the prompt box. Displays an “OK” and a “Cancel” button by default. |
### Events
| Name | Description |
| -- | -- |
| `input` | [^event-input] |
| `ok` | Triggered when the “OK” button is clicked. |
| `cancel` | Triggered when the “Cancel” button is clicked. |
| `afterclose` | Triggered after the box overlay is closed. If leaving transition is provided by the theme, the event will be triggered after the transition completes. |
^^^event-input
:::badges
`v-model`
:::
Triggered when the input value changes. The callback parameter list is `(value: string)` with `value` being the current value of the input.
^^^

86
one/docs/en-US/components/radio-button-group.md Normal file
View File

@@ -0,0 +1,86 @@
# RadioButtonGroup
## Demos
### Size variants
Available values for the `ui` prop: `s`/`m`.
[[ demo src="/demo/radio-button-group/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `*` | - | [^value] |
| `disabled` | `boolean=` | `false` | Whether the radio button group is disabled. |
| `readonly` | `boolean=` | `false` | Whether the radio button group is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
^^^
^^^items
The datasource of items with the item type being `{label, value, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The `value`s of the selected items.
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The label content of each button. Displays the value of the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `index` | `number` | The index of the item within `items`. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
Triggers when the selected item changed. The callback parameter list is `(value: *)` and `value` is the value of the selected item.
^^^

86
one/docs/en-US/components/radio-group.md Normal file
View File

@@ -0,0 +1,86 @@
# RadioGroup
## Demos
### Sizes
Available size variant for the `ui` prop: `s`/`m`.
[[ demo src="/demo/radio-group/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `items` | `Array<Object>` | `[]` | [^items] |
| `value` | `*` | - | [^value] |
| `disabled` | `boolean=` | `false` | Whether the radio group is disabled. |
| `readonly` | `boolean=` | `false` | Whether the radio group is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
^^^
^^^items
The datasource of items with the item type being `{label, value, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The `value` of the selected item.
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^scoped-slot-item] |
^^^scoped-slot-item
The label content of each radio. Displays the value of the `label` prop by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the item. |
| `value` | `*` | The value of the item. |
| `index` | `number` | The index of the item within `items`. |
| `disabled` | `boolean=` | Whether the item is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
Triggers when the selected item changed. The callback parameter list is `(value: *)` and `value` is the value of the selected item.
^^^

73
one/docs/en-US/components/radio.md Normal file
View File

@@ -0,0 +1,73 @@
# Radio
## Demos
### Sizes
Available size variant for the `ui` prop: `s`/`m`.
[[ demo src="/demo/radio/size.vue" ]]
### Setting value
Use the `value` prop to specify the value bound to the `model` prop (used for `v-model`).
[[ demo src="/demo/radio/model.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `checked` | `boolean` | `false` | [^checked] |
| `value` | `*` | `true` | The value of the radio. |
| `disabled` | `boolean=` | `false` | Whether the radio is disabled. |
| `readonly` | `boolean=` | `false` | Whether the radio is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^checked
:::badges
`.sync`
:::
Whether the checkbox is checked.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The label text of the radio. The radio is selected when the label is clicked. Displays nothing by default. |
### Events
| Name | Description |
| -- | -- |
| `change` | Triggered when user checks the radio. The callback parameter list is `(checked: boolean)`. `checked` denotes whether the radio is checked. |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
Triggered when the check state is changed. The callback parameter list is `(val: *)`, with `val` being the current value of `v-model`. Unlike the `change` event, `input` is triggered even without user interaction.
^^^
Additionally, `Radio` exposes the following native events:
`auxclick`, `click`, `contextmenu`, `dblclick`, `mousedown`, `mouseenter`, `mouseleave`, `mousemove`, `mouseover`, `mouseout`, `mouseup`, `select`, `wheel`, `keydown`, `keypress`, `keyup`, `focus`, `blur`, `focusin`, `focusout`.
The callback parameter is the corresponding native event object for all events above.

79
one/docs/en-US/components/region-picker.md Normal file
View File

@@ -0,0 +1,79 @@
# RegionPicker
## Demos
[[ demo src="/demo/region-picker/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `selected` | `Array<string>` | - | [^selected] |
| `include-indeterminate` | `boolean` | `false` | Whether to include indeterminate node into selected nodes. Non-leaf nodes inside `datasource` will be in indeterminate state if their descendant nodes are partially selected. |
| `disabled` | `boolean=` | `false` | Whether the region picker is disabled. |
| `readonly` | `boolean=` | `false` | Whether the region picker is read-only. |
^^^datasource
The datasource of the region picker. The type of node item is `{label, value, disabled, children, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the node. |
| `value` | `string` | The value of the node. |
| `disabled` | `boolean=` | Whether the node is disabled. |
| `children` | `Array<Object>=` | The child nodes of the node. The node type is the same as `datasource` items. |
+++
^^^
^^^selected
:::badges
`v-model`
:::
The array of selected `value`s.
^^^
### Slots
| Name | Description |
| -- | -- |
| `label` | [^scoped-slot-label] |
^^^scoped-slot-label
The label content of each node. Displays the `label` property of each item by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the node. |
| `value` | `string` | The value of the node. |
| `disabled` | `boolean=` | Whether the node is disabled. |
| `children` | `Array<Object>=` | The child nodes of the node. The node type is the same as `datasource` items. |
| `level` | `number` | The depth of the node within the tree structure. `0` stands for the top level. |
| `overlay` | `boolean=` | Whether the node is displayed inside the overlay. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
:::tip
When `level` is `2` and `overlay` is `true`, the information of selected node count vs total node count will be displayed after the node label.
:::
^^^
### Events
| Name | Description |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
Triggered when the selection changed. The callback parameter list is `(value: Array)`. The type of `value` is the same as the `selected` prop.
^^^

146
one/docs/en-US/components/schedule.md Normal file
View File

@@ -0,0 +1,146 @@
# Schedule
## Demos
[[ demo src="/demo/schedule/default.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `selected` | `Object` | - | [^selected] |
| `hour-class` | `string|Array|Object|function` | `{}` | The customized HTML `class` for the hour cell. When not being a function, supports all values defined by [Vue's `class` expressions](https://vuejs.org/v2/guide/class-and-style.html#Binding-HTML-Classes). If it's a function, the signature is `function(day: number, hour: number): string|Array<string>|Object<string, boolean>`. The return value is also a Vue `class` expression. |
| `disabled-date` | `function(number, number): boolean` | `() => false` | Whether the hour cell is disabled. Parameter list is `(day: number, hour: number)`. `day` and `hour` denote the day of week and the hour respectively. Return value specifies whether the hour cell is disabled from selection. |
| `shortcuts` | `Array` | `schedule.shortcuts` | [^shortcuts] |
| `shortcuts-display` | `string` | `'inline'` | The display mode of the shortcuts. Supported values are `inline`/`popup`, which denote inline button groups and dropdown select, respectively. |
| `statuses` | `Array<{label: string, value: string}>` | `schedule.statuses` | The datasource of the legends. Legend items will have a `class` value of <code>&#0096;veui-schedule-legend-${value}&#0096;</code> and the `label` property will be the text label of each status. |
| `disabled` | `boolean=` | `false` | Whether the schedule component is disabled. |
| `readonly` | `boolean=` | `false` | Whether the schedule component is read-only. |
^^^selected
:::badges
`v-model`
:::
Selected time ranges. The data type is `Object<number, Array>`.
The keys denote day of week, corresponding to the return value of [`Date.prototype.getDay()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getDay). The values denote the selected time ranges for each day. The data type of each time range is `[start: number, end: number]`, while `start` and `end` are both hours between `0`–`23`.
+++Sample data
```json
{
1: [
[9, 17]
],
6: [
[0, 2],
[18, 20]
]
}
```
This sample stands for 9:00–18:00 of Monday and 0:00–3:00 & 18:00–21:00 of Saturday. The end hour denotes the start point of the last hour in the time range.
+++
^^^
^^^shortcuts
Shortcut selection list. The type is `{label: string, selected: boolean|Array}`.
`label` denotes the text label of each item. `selected` denotes the predefined time ranges. When being an array, it shares the same data type with the `selected` prop. When being `true`, it's same as `[[0, 23]]`.
^^^
### Slots
| Name | Description |
| -- | -- |
| `header` | The entire header section. |
| `header-content` | The content of the header section, not including the container. |
| `shortcuts` | The shortcuts section of the header section. |
| `legend` | The legends section of the header section. |
| `legend-label` | [^scoped-slot-legend-label] |
| `hour` | [^scoped-slot-hour] |
| `label` | [^scoped-slot-label] |
| `tooltip` | [^scoped-slot-tooltip] |
^^^scoped-slot-legend-label
The text label of each legend. Displays the `label` property of each legend by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The text label of the legend. |
| `value` | `string` | The value of the legend. |
+++
Additionally, custom properties inside `statuses` apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-hour
The content of each hour cell.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `day` | `number` | The day of week. `0` denotes Sunday. |
| `hour` | `number` | The hour value. |
+++
^^^
^^^scoped-slot-label
The content of the selected label. By default, displays the time range in the form of <code>&#0096;${from}:00–${to + 1}:00&#0096;</code> when it's more than 3 hours, displays “Entire Day” when every hour of a day are selected; displays nothing for less than 3 hours.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `from` | `number` | The first hour of the time range. |
| `to` | `number` | The last hour of the time range. |
+++
^^^
^^^scoped-slot-tooltip
The tooltip for each hour cell. Displays <code>&#0096;${hour}:00–${hour + 1}:00&#0096;</code> for current hour by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `day` | `number` | The day of week. `0` denotes Sunday. |
| `hour` | `number` | The hour value. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `select` | [^event-select] |
^^^event-select
:::badges
`v-model`
:::
Triggered when selection changed. The callback parameter list is `(value: Object)`. `value` shares the same type with the `selected` prop.
^^^
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `schedule.statuses` | Array<{name, label}> | See description. | [^config-statuses] |
^^^config-statuses
The default status list with item type being `{name: string, label: string}`. The default value is:
```js
[
{ name: 'selected', label: '@@schedule.selectedRanges' },
{ name: 'available', label: '@@schedule.availableRanges' }
]
```
:::tip
`@@` prefixed values denote corresponding properties in the locale settings.
:::
^^^

177
one/docs/en-US/components/search-box.md Normal file
View File

@@ -0,0 +1,177 @@
# SearchBox
## Demos
### Stylistic variants
Available stylistic values for the `ui` prop: `strong`.
[[ demo src="/demo/search-box/style.vue" ]]
### Size variants
Available size values for the `ui` prop: `xs`/`s`/`m`/`l`.
[[ demo src="/demo/search-box/size.vue" ]]
### Read-only and disabled
[[ demo src="/demo/search-box/disabled.vue" ]]
### Suggestion list
[[ demo src="/demo/search-box/suggestion.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `placeholder` | `string` | - | The placeholder text of the search box. |
| `value` | `string` | - | [^value] |
| `autofocus` | `boolean` | `false` | Whether the search box gains focus automatically. |
| `clearable` | `boolean` | `false` | Whether the clear button is displayed. |
| `select-on-focus` | `boolean` | `false` | Whether to select all content upon focus. |
| `composition` | `boolean` | `false` | Whether the search box triggers value change upon composition of IME. |
| `suggestions` | `Array<string>|Array<Object>` | - | [^suggestions] |
| `replace-on-select` | `boolean` | `true` | Whether to replace the content with suggestion item value when it's selected. |
| `suggest-trigger` | `Array<string>|string` | `input` | [^suggest-trigger] |
| `disabled` | `boolean=` | `false` | Whether the search box is disabled. |
| `readonly` | `boolean=` | `false` | Whether the search box is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `strong` | Strong style. |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
| `xl` | Extra large. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The value of the search box.
^^^
^^^suggestions
The suggestion list. When the item type is `Object`, the properties will be `{label, value}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The text of the suggestion option. |
| `value` | `string` | The value of the suggestion option. |
+++
^^^
^^^suggest-trigger
Specifies when the suggestion list is displayed. Can be either an event name or a list of event names.
+++Enum values
| Value | Description |
| -- | -- |
| `focus` | When the search box is focused. |
| `input` | When the input triggers `input` event. |
| `submit` | When the submit button is activated. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `suggestions` | [^slot-suggestions] |
| `suggestions-before` | The content before the suggestion list. |
| `suggestions-after` | The content after the suggestion list. |
| `suggestion` | [^slot-suggestion] |
^^^slot-suggestions
The content of the entire suggestion list.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `suggestions` | `Array<{value: string, label: string}>` | The normalized suggestions from the `suggestions` prop. |
| `select` | `function(suggestion: {value: string, label: string}): void` | Select the specified suggestion. |
^^^slot-suggestion
The content of each suggestion option.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The text label of the suggestion option. |
| `value` | `string` | The value of the suggestion option. |
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
When `suggestions` is an `Array<string>`, the `label` and `value` of the suggestion option will share the same `string` value.
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `input` | [^event-input] |
| `suggest` | [^event-suggest] |
| `select` | [^event-select] |
| `search` | [^event-search] |
^^^event-input
Triggers when the input value changes. The callback parameter list is `(value: string)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `value` | `string` | The value of the input. |
+++
^^^
^^^event-suggest
Triggers when the suggestion list is displayed. The callback parameter list is `(value: string)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `value` | `string` | The value of the input. |
+++
^^^
^^^event-select
Triggered when an suggestion option is selected. The callback parameter list is `(item: Object)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `item` | `{label: string, value: string=, ...}` | The suggestion option. |
+++
^^^
^^^event-search
Triggered when the input value is submitted. The callback parameter list is `(value: string, event: Event)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `value` | `string` | The value of the input. |
| `event` | [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/click) | The native click event object. |
+++
^^^
### Icons
| Name | Description |
| -- | -- |
| `search` | Search. |

184
one/docs/en-US/components/select.md Normal file
View File

@@ -0,0 +1,184 @@
# Select
:::tip
`Select` can be used with embedded [`Option`](./option) or [`OptionGroup`](./option-group).
:::
## Demos
### Size variants
Available size variants for the `ui` prop: `xs`/`s`/`m`/`l`.
[[ demo src="/demo/select/size.vue" ]]
### Using embedded `OptionGroup`s & `Option`s
Can be used with embedded `OptionGroup`s & `Option`s.
[[ demo src="/demo/select/inline.vue" ]]
### Searchable options
Use the `searchable` prop to make options searchable.
[[ demo src="/demo/select/searchable.vue" ]]
### Multiple selections
Use the `multiple` prop to enable multiple selections.
[[ demo src="/demo/select/multiple.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `options` | `Array<Object>` | `-` | [^options] |
| `value` | `Array<*>|*` | - | [^value] |
| `multiple` | `boolean` | `false` | Whether users can select multiple items. |
| `max` | `number` | - | The max items users can select. |
| `placeholder` | `string` | `select.placeholder` | Placeholder text when no option is selected. |
| `clearable` | `boolean` | `false` | Whether the select is clearable. |
| `searchable` | `boolean` | `false` | Whether the options are searchable. |
| `filter` | `function` | - | Filter function for the options. The type is `function(option: Object): boolean`. The type of `option` is the same as the `options` prop. The return value denotes whether the option is shown inside the options dropdown. |
| `disabled` | `boolean=` | `false` | Whether the select is disabled. |
| `readonly` | `boolean=` | `false` | Whether the select is read-only. |
| `overlay-class` | `string|Array|Object=` | - | See the `overlay-class` prop of [`Overlay`](./overlay). |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
| `l` | Large. |
^^^
^^^options
The list of options with the option type being `{label, value, options, disabled, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `options` | `Array<Object>=` | The child options of current option. The item type is the same as the items of the `options` prop. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
^^^
^^^value
:::badges
`v-model`
:::
The value of the selected option.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the options dropdown layer. Can be used to place `Option`s or `OptionGroups`s when the `options` prop is not specified. |
| `before` | The content before the options in the dropdown layer. |
| `after` | The content after the options in the dropdown layer. |
| `label` | [^scoped-slot-label] |
| `group-label` | [^scoped-slot-group-label] |
| `option-label` | [^scoped-slot-option-label] |
| `option` | [^scoped-slot-option] |
^^^scoped-slot-label
The content of the select button. Displays the `label` of selected option or the text content of the selected embedded option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the selected option. |
| `value` | `*` | The value of the selected option. |
| `selected` | `boolean` | Whether the select has a selected value. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-group-label
The label text of each option group (option with child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option group. |
| `disabled` | `boolean=` | Whether the option group is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option-label
The label text of each option (option without child `options`). Displays the `label` of the option by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
^^^scoped-slot-option
The entire content area of each option (option without child `options`). Displays the default content of `Options` component by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of the option. |
| `value` | `*` | The value of the option. |
| `selected` | `boolean` | Whether the the option is selected. |
| `disabled` | `boolean=` | Whether the option is disabled. |
+++
Additionally, custom properties in current option, apart from the listed ones, will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
^^^event-change
:::badges
`v-model`
:::
Triggers when the selected option changed. The callback parameter list is `(value: *)` and `value` is the value of the selected option.
^^^
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `select.placeholder` | `string` | `@@select.placeholder` | The placeholder text when no option is selected. |
:::tip
`@@` prefixed values denote corresponding properties in the locale settings.
:::
### Icons
| Name | Description |
| -- | -- |
| `expand` | Expand the dropdown layer. |
| `collapse` | Collapse the dropdown layer. |

126
one/docs/en-US/components/slider.md Normal file
View File

@@ -0,0 +1,126 @@
# Slider
## Demos
### Size variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/slider/size.vue" ]]
### Read-only/disabled
Use the `readonly` prop to set a slider read-only. Use the `disabled` prop to set a slider disabled.
[[ demo src="/demo/slider/editable.vue" ]]
### Steps
Use the `step` to make value change by specified step value when clicking spinner buttons, or pressing <kbd>▴</kbd> or <kbd>▾</kbd>.
[[ demo src="/demo/slider/steps.vue" ]]
### Range
Use the `max`/`min` props to specify the values at both ends of the slider.
[[ demo src="/demo/slider/range.vue" ]]
### Secondary bar
Use the `secondary-progress` prop to specify a secondary progress bar.
[[ demo src="/demo/slider/buffer.vue" ]]
### Customization
Use the `thumb`/`tip` slots to customize the content of slider thumb and tooltip.
[[ demo src="/demo/slider/variant.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `value` | `*|Array<*>` | - | [^value] |
| `secondary-progress` | `number|Array<number>` | `0` | Secondary progress value. |
| `min` | `number` | `0` | The minimun value after `value` is processed by the `parse` function. |
| `max` | `number` | `1` | The maximum value after `value` is processed by the `parse` function. |
| `step` | `number` | `0` | The step value after `value` is processed by the `parse` function. |
| `mark` | `boolean` | `false` | Whether to display step marks. |
| `parse` | `function` | `val => val` | The parse function to transform input value. |
| `format` | `function` | `val => val` | The format function to transform output value. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^value
The value of the slider.
By default the type is `number` and the value should between `min` and `max` after parsed by the `parse` function.
When being the type of `Array<number>`, multiple thumbs will be rendered corresponding to each value.
:::tip
When `parse` and `format` are specified, values can be of any type, and `parse` should transform the value to `number` and `format` should transform the value to the same type as the `value` prop. `parse` and `format` only need to take care of single values instead of arrays and the component itself will apply transformation on multiple values if necessary.
:::
^^^
### Slots
| Name | Description |
| -- | -- |
| `track` | The track of the slider. Displays a bar by default. |
| `tip-label` | The tooltip content. Displays the current `value` or its item by default. |
| `thumb` | [^scoped-slot-thumb] |
| `tip` | [^scoped-slot-tip] |
^^^scoped-slot-thumb
The thumb(s) of the slider. Displays a round button by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `index` | `number` | The index of current thumb. |
| `focus` | `boolean` | Whether current thumb is focused. |
| `hover` | `boolean` | Whether user is pointing current thumb. |
| `dragging` | `boolean` | Whether the current thumb is being dragged. |
+++
^^^
^^^scoped-slot-tip
The entire tooltip for each thumb. Displays a `Tooltip` component with `value` as its content by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `target` | `HTMLElement` | The rendered `Element` for current thumb. |
| `open` | `boolean` | Whether there is any active thumb. |
| `active-index` | `boolean` | The index of the current active thumb. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
Triggered after the value changed. The callback parameter type is `(value: *)`, where `value` is the new value (transformed by the `format` function).
^^^

89
one/docs/en-US/components/steps.md Normal file
View File

@@ -0,0 +1,89 @@
# Steps
## Demos
### Size and direction variants
Available style variants for the `ui` prop: `s`/`m`/`vertical`/`label-vertical`.
[[ demo src="/demo/steps/default.vue" ]]
### Step status
Set `status` property of the `step` to `error`, if the step fails.
[[ demo src="/demo/steps/status.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `steps` | `Array` | - | [^steps] |
| `current` | `number` | - | The index of current step. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small style. |
| `m` | Medium. |
| `vertical` | Vertical style. |
| `label-vertical` | Label vertical style. |
+++
^^^
^^^steps
The datasource of steps with item type being `{ label, desc, to, status }`.
+++Properties
| Name | Type | | Description |
| -- | -- | -- |
| `label` | `string` | The label of the step. |
| `desc` | `string` | The description of the step. |
| `to` | `string|Object` | The target link of the step. The type is the same as the `to` prop of [`Link`](./link#props) component. |
| `status` | `string` | The statue of the step. Available variants are default normal and `error`. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | [^scoped-slot-default] |
| `index` | The step index. Displays an index value starts from `1`, a success icon for finished steps by default and an error icon for error steps. Resides inside the default slot and share the same scope properties. |
| `label` | The step label. Displays the `label` prop by default. Resides inside the default slot and share the same scope properties. |
| `desc` | The step description. Displays the `desc` prop by default. Resides inside the default slot and share the same scope properties. |
^^^scoped-slot-default
The content of each step. Displays the step index/completed icon, label and description by default.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The label of the step. Same as the `label` property from items of `steps`. |
| `desc` | `string` | The description of the step. Same as the `desc` property from items of `steps`. |
| `to` | `string|Object` | The target link of the step. Same as the `to` property from items of `steps`. |
| `status` | `string` | The status of the step. Same as the `status` property from items of `steps`. |
| `index` | `number` | The index of the step. (Starts from `0`.) |
Additionally, custom properties in current step, apart from the listed ones, will also be passes into the scope object via `v-bind`.
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `click` | Triggered when any step is clicked. The callback parameter type is `(index: number, event: Event)`, where `index` is the index of the clicked step and `event` is the corresponding native event object. |
### Icons
| Name | Description |
| -- | -- |
| `success` | Steps finished successfully. |
| `error` | Steps with error. |

75
one/docs/en-US/components/switch.md Normal file
View File

@@ -0,0 +1,75 @@
# Switch
## Demos
### Size variants
Available size variants for the `ui` prop: `xs`/`s`/`m`.
[[ demo src="/demo/switch/size.vue" ]]
### True/false values
Use the `true-value` and `false-value` props to customize the `model` value (used in its `v-model`) of the checkbox in checked/unchecked state.
[[ demo src="/demo/switch/value.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `checked` | `boolean` | `false` | [^checked] |
| `true-value` | `*` | `true` | The value for checked state. |
| `false-value` | `*` | `false` | The value for unchecked state. |
| `disabled` | `boolean=` | `false` | Whether the switch is disabled. |
| `readonly` | `boolean=` | `false` | Whether the switch is read-only. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `xs` | Extra small. |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^checked
:::badges
`.sync`
:::
Whether the checkbox is on.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The label text of the switch. The switch is toggled when the label is clicked. Displays nothing by default. |
### Events
| Name | Description |
| -- | -- |
| `change` | Triggered when user toggles the state of the switch. The callback parameter list is `(checked: boolean)`. `checked` denotes whether the switch is on. |
| `input` | [^event-input] |
^^^event-input
:::badges
`v-model`
:::
Triggered when the check state is changed. The callback parameter list is `(val: *)`, with `val` being the current value of `v-model`. Unlike the `change` event, `input` is triggered even without user interaction.
^^^
Additionally, `Switch` exposes the following native events:
`auxclick`, `click`, `contextmenu`, `dblclick`, `mousedown`, `mouseenter`, `mouseleave`, `mousemove`, `mouseover`, `mouseout`, `mouseup`, `select`, `wheel`, `keydown`, `keypress`, `keyup`, `focus`, `blur`, `focusin`, `focusout`.
The callback parameter is the corresponding native event object for all events above.

129
one/docs/en-US/components/table.md Normal file
View File

@@ -0,0 +1,129 @@
# Table
:::tip
`Table` is required to be used within [`Column`](./column).
:::
## Demos
### Content density
Available density variants for the `ui` prop: `compact`/`loose`.
[[ demo src="/demo/table/basic.vue" ]]
### Advanced
Supports specifying row keys, mode of selection, and sorting by values of specific column.
[[ demo src="/demo/table/advanced.vue" ]]
### Scroll inside
Allow table content to be scrollable inside the table body, i.e. the effect of fixed head/foot.
[[ demo src="/demo/table/scrollable.vue" ]]
### Fixed columns
Use the `scroll` of `Table` and the `fixed` prop of `Column` to enable fixed columns.
[[ demo src="/demo/table/fixed.vue" ]]
### Expandable row
Rows can be expanded into sub-rows.
[[ demo src="/demo/table/expandable.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `data` | `Array<Object>` | - | Table data in rows. |
| `key-field` | `string` | - | Denotes the unique key of the table data. The value should be a key defined in the data object of each row. The corresponding field will be regarded as the [`key` attribute](https://vuejs.org/v2/guide/list.html#key) for each row element. When `selectable` is `true`, it also indicates the rows of which column should be selected from (and in this occasion the value should be defined as the `field` prop for one of the children `Column` components). |
| `selectable` | `boolean` | `false` | Whether the rows are selectable. |
| `select-mode` | `string` | `'multiple'` | The mode of row selection. Available values are `single`/`multiple`, which denote single selection and multiple selection respectively. |
| `selected` | `Array<*>|*` | `[]` | [^selected] |
| `expandable` | `boolean` | `false` | Whether the rows can be expanded into sub-rows. |
| `expanded` | `Array<*>` | `[]` | [^expanded] |
| `order` | `string|boolean` | `false` | The order for sorting the specified column. `false` denotes no specific order, while string values of `'asc'`/`'desc'` denote ascending/descending order respectively. |
| `order-by` | `string` | - | The column which is currently sorted by. The value should be defined as the `field` prop for one of the children `Column` components. |
| `scroll` | `number` | - | The maximun height of the scrollable area inside the table body. When table content exceeds the specified height, internal scroll will be enabled and the head/foot will become fixed. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `compact` | Compact style. |
| `loose` | Loose style. |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^selected
:::badges
`.sync`
:::
The value(s) of selected rows. When `select-mode` is `'multiple'`, the value is an array of values keyed by the `key-field` prop from the row data . When `select-mode` is `'single'`, the value is such key value of the selected row.
^^^
^^^expanded
:::badges
`.sync`
:::
The values of expanded rows. Each item is the value keyed by the `key-field` prop from the row data.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The columns of the table. Can only have `Column` components as children. |
| `no-data` | The content to be displayed when there's no data to show. |
| `foot` | The content of the table foot. Will span across all columns when defined. |
| `sub-row` | [^scoped-slot-sub-row] |
^^^scoped-slot-sub-row
The content of the expanded sub-row. Will span across all columns and override the `sub-row` slot of the `Column` components inside the table.
The slot scope properties are the same as each item inside `datasource`, with an extra `index: number`, which denotes the index within the datasource.
^^^
### Events
| Name | Description |
| -- | -- |
| `select` | [^event-select] |
| `sort` | [^event-sort] |
^^^event-select
Triggered when the selected item(s) are changed. The callback parameter list is `(selected, item, selectedItems)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `selected` | `boolean` | Whether the item is selected after change. |
| `item` | `Object` | The item in the `data` prop that is being selected/unselected. When it involves row span for the `key-field` mapped column, the data of the first related row is returned. |
| `selectedItems` | `Object<string, Object|Array>` | All selected items as an object. The key is `key-field` mapped value for the selected row and the value is the row data. When it involves row span for the `key-field` mapped column, returns an array of row data of all related rows. |
+++
^^^
^^^event-sort
Triggered when users sort a specific column. The callback parameter list is `(field, order)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `field` | `string` | Which column to be sort by. The value should be defined as the `field` prop for one of the children `Column` components. |
| `order` | `string|boolean` | Same as the [`order` prop](#props). |
+++
^^^

5
one/docs/en-US/components/tabs/index.vue Normal file
View File

@@ -0,0 +1,5 @@
<template>
<div>
Tab content #1
</div>
</template>

5
one/docs/en-US/components/tabs/tab.vue Normal file
View File

@@ -0,0 +1,5 @@
<template>
<div>
Tab content #1
</div>
</template>

5
one/docs/en-US/components/tabs/tab2.vue Normal file
View File

@@ -0,0 +1,5 @@
<template>
<div>
Tab content #2
</div>
</template>

5
one/docs/en-US/components/tabs/tab3.vue Normal file
View File

@@ -0,0 +1,5 @@
<template>
<div>
Tab content #3
</div>
</template>

89
one/docs/en-US/components/textarea.md Normal file
View File

@@ -0,0 +1,89 @@
# Textarea
## Demos
### Size variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/textarea/size.vue" ]]
### Read-only state
Use the `readonly` prop to set a textarea to read-only state.
[[ demo src="/demo/textarea/readonly.vue" ]]
### Disabled state
Use the `disabled` prop to set a textarea to disabled state.
[[ demo src="/demo/textarea/disabled.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `value` | `string` | '' | [^value] |
| `disabled` | `boolean=` | `false` | Whether the textarea is disabled. |
| `readonly` | `boolean=` | `false` | Whether the textarea is read-only. |
| `line-number` | `boolean` | `false` | Whether to show line numbers. |
| `rows` | `number|string` | - | The default visible rows of the textarea. |
| `placeholder` | `string` | - | The placeholder text of the textarea. |
| `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. |
^^^ui
预设样式。
+++枚举值
| 值 | 描述 |
| -- | -- |
| `s` | Small. |
| `m` | Medium. |
+++
^^^
^^^value
:::badges
`v-model`
:::
文本域的值。
^^^
### 事件
| 名称 | 描述 |
| -- | -- |
| `change` | [^event-change] |
| `input` | [^event-input] |
^^^event-change
输入框内容变化时触发，即原生 `change` 事件触发时。回调参数为 `(value, event)`。
+++参数详情
| 名称 | 类型 | 描述 |
| -- | -- | -- |
| `value` | `string` | 文本域的值。 |
| `event` | [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/Events/change) | 原生 `change` 事件对象。 |
+++
^^^
^^^event-input
:::badges
`v-model`
:::
有效输入时触发，受 `composition` 属性影响。回调参数为 `(value: string)`，`value` 为输入框的 `value` 值。
^^^
此外，`Textarea` 支持如下的原生事件：
`auxclick`、`click`、`contextmenu`、`dblclick`、`mousedown`、`mouseenter`、`mouseleave`、`mousemove`、`mouseover`、`mouseout`、`mouseup`、`select`、`wheel`、`keydown`、`keypress`、`keyup`、`focus`、`blur`、`focusin`、`focusout`。
回调函数的参数都为原生事件对象。

74
one/docs/en-US/components/toast.md Normal file
View File

@@ -0,0 +1,74 @@
# Toast
## Demos
### Types
`Toast` component has 4 contextual types, which are `success`, `info`, `warning` and `error`. Types are specified with the `type` prop.
[[ demo src="/demo/toast/default.vue" ]]
### Imperative invocation
Use `veui/plugins/toast` to enable [`toast` plugin](../plugins/toast) and invoke the toast imperatively.
[[ demo src="/demo/toast/plugin.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `open` | `boolean` | `false` | [^open] |
| `type` | `string` | `'success'` | [^type] |
| `message` | `string` | - | The toast message. |
| `duration` | `number` | `toast.duration` | Time (in milliseconds) to wait until the toast is automatically closed. |
^^^open
:::badges
`.sync`
:::
Whether the toast is displayed.
^^^
^^^type
The contextual type of the toast.
+++Enum values
| Value | Description |
| -- | -- |
| `info` | Information toast. |
| `success` | Succuess toast. |
| `warning` | Warning toast. |
| `error` | Error toast. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the toast. Displays the `message` prop by default. |
### Events
| Name | Description |
| -- | -- |
| `close` | Triggered when the toast is closed. |
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `toast.duration` | `number` | `3000` | The duration of the toast in milliseconds. |
### Icons
| Name | Description |
| -- | -- |
| `info` | Information toast. |
| `success` | Success toast. |
| `warning` | Warning toast. |
| `error` | Error toast. |

78
one/docs/en-US/components/tooltip.md Normal file
View File

@@ -0,0 +1,78 @@
# Tooltip
## Demos
### Style variants
Available style variant for the `ui` prop: `alt`.
[[ demo src="/demo/tooltip/style.vue" ]]
### Position
Use the `position` prop to specify the placement of the tooltip.
[[ demo src="/demo/tooltip/position.vue" ]]
### Triggers
Use the `trigger` prop to specify when to show/hide the tooltip.
[[ demo src="/demo/tooltip/trigger.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `open` | `boolean` | `false` | [^open] |
| `target` | `string|Vue|Node` | - | See the [`target` prop](./overlay#props) of thh [`Overlay`](./overlay) component. |
| `position` | `string` | `'top'` | [^position] |
| `trigger` | `string` | `'hover'` | [^trigger] |
| `interactive` | `boolean` | `true` | Whether the tooltip content is interactive. When set to `false`, the tooltip will be automatically hidden after the event specified by `trigger` is triggered outside the `target`. |
| `hide-delay` | `number` | `tooltip.hideDelays` | Time (in milliseconds) to wait before hiding the tooltip after the close trigger is triggered. Can be used to prevent the tooltip being immediately closed after pointer leaves the `target` element and before it enters the tooltip itself. |
| `overlay-class` | `string|Array|Object=` | - | See the [`overlay-class` prop](./overlay#props) of the [`Overlay`](./overlay) component. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `alt` | Reverse style. |
| `s` | Small style. |
| `m` | Medium style. |
+++
^^^
^^^open
:::badges
`.sync`
:::
Whether the tooltip is displayed.
^^^
^^^position
Denotes the target element of the tooltip. Used with [Popper.js](https://popper.js.org/)-style placement syntax, see [`Popper.placements`](https://popper.js.org/popper-documentation.html#Popper.placements).
^^^
^^^trigger
The event that triggers the toggle of the tooltip. Can take valid values for `v-outside` directive's `trigger` parameter, and can use <code>&#0096;${open}-${close}&#0096;</code> syntax to specify different trigger event for showing/hiding the tooltip. When specified as `custom`, `v-outside` will not be leveraged to automatically toggle the tooltip.
eg. `click` denotes showing the tooltip after clicking the `target` and hiding it after clicking outside. `hover-mousedown` denotes showing the tooltip after hovering the `target`, and hiding it after clicking outside.
^^^
### Slots
| Name | Description |
| -- | -- |
| `default` | The content of the tooltip. |
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `tooltip.hideDelay` | `number` | `300` | See the [`hide-delay` prop](#props). |

162
one/docs/en-US/components/transfer.md Normal file
View File

@@ -0,0 +1,162 @@
# Transfer
## Demos
### Size variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/transfer/size.vue" ]]
### Without search input
[[ demo src="/demo/transfer/no-search.vue" ]]
### Custom search
[[ demo src="/demo/transfer/custom-search.vue" ]]
### Selected values as list
[[ demo src="/demo/transfer/flat.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `searchable` | `boolean` | `true` | Whether to allow search. |
| `filter` | `function` | See description | [^filter] |
| `selected` | `Array` | `[]` | [^selected] |
| `candidate-placeholder` | `string` | - | The placeholder text in the search input of the candidate panel. |
| `selected-placeholder` | `string` | - | The placeholder text in the search input of the selected panel. |
| `selected-show-mode` | `string` | `'tree'` | [^selected-show-mode] |
| `keys` | `string|function` | `'value'` | The customized unique key for `datasource` items. String values can be used to specify which field value is used. Also a function can bu used to specify a customized key value. |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small transfer. |
| `m` | Medium transfer. |
+++
^^^
^^^datasource
The datasource of the transfer. The type of node item is `{label, value, children, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of each item. |
| `value` | `string` | The value of each item. |
| `children` | `Array<Object>=` | The child items of each item. The item type is the same as `datasource` items. |
+++
^^^
^^^filter
The filter function. The function signature is `function(from, keyword, item, index, datasource): boolean`. Items that make filter function returns `false` will be hidden.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `from` | `string` | The source of search. Available values are `'candidate'`/`'selected'`. `'candidate'` means search is triggered from the candidate panel, `'selected'` means from the selected panel. |
| `keyword` | `string` | The search keyword. |
| `item` | `Object` | Each item in `datasource`. |
| `index` | `number` | The index of each item among its siblings. |
| `datasource` | `Array<{label: string, ...}>` | Same as the `datasource` prop. |
+++
+++Default value
```js
import { includes } from 'lodash'
function (keyword, { label }) {
return includes(label, keyword)
}
```
+++
^^^
^^^selected
:::badges
`v-model`
:::
The selected values which is the `value` array of `datasource` items (affected by the `keys` prop).
^^^
^^^selected-show-mode
To specify how should items inside selected panel be displayed.
+++Enum values
| Value | Description |
| -- | -- |
| `tree` | Displayed as a tree structure. |
| `flat` | Displayed as a flattened array. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `candidate-head` | The head area of the candidate panel. |
| `selected-head` | The head area of the selected panel. |
| `candidate-title` | The title text of the candidate panel. |
| `selected-title` | The title text of the selected panel. |
| `candidate-no-data` | The content displayed when there's no data inside the candidate panel. |
| `selected-no-data` | The content displayed when there's no data inside the selected panel. |
| `candidate-item` | [^candidate-item] |
| `selected-item` | [^selected-item] |
| `candidate-item-label` | Label text of each item inside the candidate panel. Shares the same scope properties with slot `candidate-item`. |
| `selected-item-label` | Label text of each item inside the selected panel. Shares the same scope properties with slot `selected-item` when `selected-show-mode` is `'tree'`. Otherwise this slot specifies custom content for any item along the path for all selected leaf item and shares the same scope properties with slot `candidate-item`. |
^^^candidate-item
The content of each item inside the candidate panel.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of current item. |
| `value` | `string` | The value of current item. |
| `children` | `Array<Object>=` | The array of the child items of each item. Shares the same type with `datasource` items. |
| `index` | `number` | The index of current item among its siblings. |
| `depth` | `number` | The depth of current item in the tree structure. |
+++
^^^
^^^selected-item
The content of each item inside the selected panel.
+++Scope properties
The scope properties will be the same as slot `candidate-item` when `selected-show-mode` is `'tree'`. They'll be as follows when `selected-show-mode` is `'flat'`.
| Name | Type | Description |
| -- | -- | -- |
| `items` | `Array<Object>` | All ancestor items from the top level down to current item. Shares the same item type with `datasource` items. |
| `index` | `number` | The index of current item among its siblings. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `select` | Triggered when user changes selection. The callback parameter list is `(selected: Array<string>)` and `selected` is the array of `value` properties of selected items.
### Icons
| Name | Description |
| -- | -- |
| `checked` | The checked state. |
| `select` | Select items. |
| `remove` | Remove items. |
| `expand` | Click to expand (currently being collapsed). |
| `collapse` | Click to collapse (currently being expanded). |
| `separator` | The separator between level labels when `selected-show-mode` is `'flat'`. |

153
one/docs/en-US/components/tree.md Normal file
View File

@@ -0,0 +1,153 @@
# Tree
## Demos
### Size variants
Available size variants for the `ui` prop: `s`/`m`.
[[ demo src="/demo/tree/size.vue" ]]
### Item click behavior
[[ demo src="/demo/tree/default.vue" ]]
### Customize content
[[ demo src="/demo/tree/custom-item.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| -- | -- | -- | -- |
| `ui` | `string=` | - | [^ui] |
| `datasource` | `Array<Object>` | `[]` | [^datasource] |
| `expanded` | `Array` | `[]` | [^expanded] |
| `checkable` | `boolean` | `false` | Whether the rows are checkable. |
| `checked` | `Array` | `[]` | [^checked] |
| `selectable` | `boolean` | `false` | Whether the nodes are selectable. |
| `selected` | `string` | - | [^selected] |
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `s` | Small tree. |
| `m` | Medium tree. |
+++
^^^
^^^datasource
The datasource of the tree. The type of node item is `{label, value, children, ...}`.
+++Properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of each node. |
| `value` | `string` | The value of each node. |
| `children` | `Array<Object>=` | The child nodes of each node. The item type is the same as `datasource` items. |
+++
^^^
^^^expanded
:::badges
`.sync`
:::
An array consists of the `value` from datasource items that denotes the expanded nodes.
^^^
^^^checked
:::badges
`v-model`
:::
An array consists of the `value` from datasource items that denotes the checked nodes.
^^^
^^^selected
:::badges
`.sync`
:::
An array consists of the `value` from datasource items that denotes the selected nodes.
^^^
### Slots
| Name | Description |
| -- | -- |
| `item` | [^item] |
| `item-label` | The label of each node. Shares the same scope properties with the `item` slot. |
^^^item
The content of each entire node.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `label` | `string` | The descriptive label of current node. |
| `value` | `string` | The value of current node. |
| `children` | `Array<Object>=` | The array of the child nodes of each node. Shares the same type with `datasource` items. |
| `index` | `number` | The index value of current node among its siblings. |
| `depth` | `number` | The depth of current node. |
+++
Additionally, custom properties apart from the listed ones will also be passes into the scope object via `v-bind`.
^^^
### Events
| Name | Description |
| -- | -- |
| `click` | [^click] |
| `expand` | [^expand] |
| `collapse` | [^collapse] |
^^^click
Triggered when the node is clicked. The callback parameter list is `(item, parents, index, depth)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `item` | `Object` | The node item. Shares the same type with `datasource` items. |
| `parents` | `Array<Object>` | All ancestor nodes from the top level down to the clicked node. Shares the same item type with `datasource` items. |
| `index` | `number` | The index of the clicked node among its siblings. |
| `depth` | `number` | The depth of the clicked node in the tree. |
+++
^^^
^^^expand
Triggered when the node is expanded. The callback parameter list is `(item, index, depth)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `item` | `Object` | The node item. Shares the same type with `datasource` items. |
| `index` | `number` | The index of the expanded node among its siblings. |
| `depth` | `number` | The depth of the expanded node in the tree. |
+++
^^^
^^^collapse
Triggered when the node is collapsed. The callback parameter list is `(item, index, depth)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `item` | `Object` | The node item. Shares the same type with `datasource` items. |
| `index` | `number` | The index of the collapsed node among its siblings. |
| `depth` | `number` | The depth of the collapsed node in the tree. |
+++
^^^
### Icons
| Name | Description |
| -- | -- |
| `expand` | Click to expand (currently being collapsed). |
| `collapse` | Click to collapse (currently being expanded). |

292
one/docs/en-US/components/uploader.md Normal file
View File

@@ -0,0 +1,292 @@
# Uploader
## Demos
### File upload
Set the `type` prop to `file` to use the file upload mode.
[[ demo src="/demo/uploader/file.vue" ]]
### Image upload
Set the `type` prop to `image` to use the image upload mode.
[[ demo src="/demo/uploader/image.vue" ]]
## API
### Props
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `ui` | `string=` | - | [^ui] |
| `type` | `string` | `'file'` | [^type] |
| `value` | `Object|Array<Object>` | - | [^value] |
| `name` | `string` | `'file'` | The `name` of native `<input>` elements. |
| `action` | `string` | - | Upload URL. |
| `headers` | `Object` | `uploader.headers` | Extra [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers). Can be globally configured. |
| `with-credentials` | `boolean` | `true` | The same as the `with-credentials` option of `XMLHttpRequest`. |
| `request-mode` | `string` | `uploader.requestMode` | [^request-mode] |
| `iframe-mode` | `string` | `uploader.iframeMode` | [^iframe-mode] |
| `callback-namespace` | `string` | `uploader.callbackNamespace` | The namespace of the callback function when `request-mode` is `'iframe'` and `iframe-mode` is `'callback'`, will be placed under the `window` object. Can be globally configured. |
| `data-type`| `string` | `'json'` | [^data-type] |
| `convert-response` | `uploader.convertResponse` | - | [^convert-response] |
| `accept` | `string` | - | The same as the `accept` attribute of native `<input>` elements. Works as an extra layer of validation on top of browsers' file filter. Will skip validation when MIME type doesn't match file extension, eg. `application/msword`. |
| `extensions` | `Array<string>` | `['jpg', 'jpeg', 'gif', 'png', 'bmp', 'tif', 'tiff', 'webp', 'apng', 'svg']` | To specify all valid file extensions when `accept` is set to values like `'image/*'`. |
| `max-count` | `number` | - | The maximum file count. |
| `max-size` | `number|string` | - | The maximun size of a single file. When being a `number`, the unit will be `byte`. When being a `string`, units can be added after numbers, including `b`/`kb`/`mb`/`gb`/`tb`. |
| `payload` | `Object` | - | The extra data payload to be sent together with the file. |
| `progress` | `string` | `'text'` | [^progress] |
| `autoupload` | `boolean` | `true` | Whether to start upload as soon as a file is selected. |
| `order` | `string` | `asc` | [^order] |
^^^type
The type of the uploader.
+++Enum values
| Value | Description |
| -- | -- |
| `file` | File upload. |
| `image` | Image upload. |
+++
^^^
^^^value
+++Type details
| `max-count` | Type |
| -- | -- |
| `1` | `Object` |
| > `1`, or `null` | `Array<Object>` |
The type of single file is `{name: string, src: string, ...}`, and fields added inside `convert-response`.
+++
^^^
^^^request-mode
The request mode of the uploader. Can be globally customized.
+++Enum values
| Value | Description |
| -- | -- |
| `xhr` | Upload with `XMLHttpRequest`. |
| `iframe` | Upload with `<iframe>`. |
+++
^^^
^^^iframe-mode
To specify the callback mode when `request-mode` is `iframe`. Can be globally customized.
+++Enum values
| Value | Description |
| -- | -- |
| `postmessage` | Callback with `PostMessage`. |
| `callback` | Callback with callback functions registered according to `callback-namespace` on `window`. |
+++
^^^
^^^data-type
To specify the data type in order to parse the callback value if it's text content. Can be left empty if callback value is `Object`.
+++Enum values
| Value | Description |
| -- | -- |
| `json` | The callback text is JSON. |
| `text` | The callback text is plain text. |
+++
^^^
^^^convert-response
Converts response data to standard format that can be consumed by the uploader, in order to allow the uploader to display upload result. The parameter is the callback data. The type of the return value must conform to the following:
+++Properties
| Property | Type | Description |
| -- | -- | -- |
| `success` | `boolean` | Whether the upload succeeded. |
| `name` | `string=` | The name of the file. Required when `success` is `true`. |
| `src` | `string=` | The location of the file. Required when `success` is `true`. |
| `message` | `string=` | Error message when upload fails. Required when `success` is `false`. |
Additional fields can be added to the response data. These data fields will be included in the `value` prop and parameter of callbacks `change`, `success`, `failure`, `remove` and `progress` events. Can be globally configured.
+++
^^^
^^^ui
Style variants.
+++Enum values
| Value | Description |
| -- | -- |
| `horizontal` | Horizontal style. |
+++
^^^
^^^progress
To specify how to display progress when `request-mode` is `xhr`.
+++Enum values
| Value | Description |
| -- | -- |
| `text` | Displays as status text. |
| `number` | Displays the progress as percentage. |
| `bar` | Displays th progress as a progress bar. |
+++
^^^
^^^order
The order of displaying uploaded files according to start time.
+++Enum values
| Value | Description |
| -- | -- |
| `asc` | Ascending order. |
| `desc` | Descending order. |
+++
^^^
### Slots
| Name | Description |
| -- | -- |
| `button-label` | [^button-label] |
| `desc` | Descriptions of th uploader, usually maximum file count, size or valid formats. |
| `type-invalid` | [^type-invalid] |
| `size-invalid` | [^size-invalid] |
| `count-overflow` | [^count-overflow] |
| `success-label` | [^success-label] |
| `failure-label` | [^failure-label] |
| `uploading-label` | [^uploading-label] |
| `file` | [^file] |
| `file-before` | The content before each file. Shares the same slot properties with slot `file'. |
| `file-after` | The content after each file. Shares the same slot properties with slot `file'. |
| `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.
^^^
^^^type-invalid
The content of invalid type error message. Suggests the type being invalid by default.
^^^
^^^size-invalid
The content of invalid size error message. Suggests the size being invalid by default.
^^^
^^^count-overflow
The content displayed when file count exceeds limit. Suggests too many files by default.
^^^
^^^success-label
The content of upload success message. Suggests upload succeeded by default.
^^^
^^^failure-label
The content of upload failure message. Suggests upload failed by default.
^^^
^^^uploading-label
The content displayed during upload when the `progress` prop is set to `text`. Suggests uploading by default.
^^^
^^^file
The content of each file.
+++Scope properties
| Name | Type | Description |
| -- | -- | -- |
| `name` | `string` | The name of the file. |
| `src` | `string` | The location of the file. |
| `status` | `string` | The status of the file. Can be one of `'success'`/`'uploading'`/`'failure'`. |
| `index` | `number` | The index of the file within the file list. |
+++
^^^
### Events
| Name | Description |
| -- | -- |
| `change` | [^event-change] |
| `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. |
| `statuschange` | [^event-statuschange] |
| `progress` | [^event-progress] |
^^^event-change
Triggers when upload succeeded or a file is removed. The callback parameter list is `(value)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `value` | `Object|Array<Object>` | The `value` of the component. |
+++
^^^
^^^event-remove
Triggered when a file is removed. The callback parameter list is `(file, index)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `file` | `Object` | The removed file object. |
| `index` | `number` | The index of the removed file. |
`file` properties
| Name | Type | Description |
| -- | -- | -- |
| `name` | `string` | The name of the file. |
| `src` | `string` | The location of the file. |
| `status` | `string` | The status of the upload process. Can be one of `'success'`/`'uploading'`/`'failure'`. |
Fields added from `convert-response` are also available.
+++
^^^
^^^event-statuschange
Triggered when the status of the entire uploader changes. The callback parameter list is `(status: string)`.
+++Values
| Value | Description |
| -- | -- |
| `empty` | No file is selected. |
| `uploading` | At least one file is being uploaded. |
| `failure` | Any file is not being successfully uploaded. |
| `success` | All files are successfully uploaded. |
+++
^^^
^^^event-progress
Triggered when upload progress updated, when `request-mode` is `'xhr'`. The callback parameter list is `(file, index, event)`.
+++Parameters
| Name | Type | Description |
| -- | -- | -- |
| `file` | `Object` | Same as the file parameter of the callback for the `remove` event. |
| `index` | `number` | The index of the file being uploaded. |
| `event` | [`Event`](https://developer.mozilla.org/en-US/docs/Web/Events/progress) | Native upload progress event object. |
+++
^^^
### Global config
| Key | Type | Default | Description |
| -- | -- | -- | -- |
| `uploader.requestMode` | `string` | `'xhr'` | Same as the [`request-mode`](#props) prop. |
| `uploader.iframeMode` | `string` | `'xhr'` | Same as the [`iframe-mode`](#props) prop. |
| `uploader.callbackNamespace` | `string` | `'veuiUploadResult'` | Same as the [`callback-namespace`](#props) prop. |
| `uploader.headers` | `Object` | - | Same as the [`headers`](#props) prop. |
| `uploader.convertResponse` | `function(Object): Object` | - | Same as the [`convert-response`](#props) prop. |
### Icons
| Name | Description |
| -- | -- |
| `upload` | Upload file. |
| `clear` | Remove file. |
| `success` | Upload succeeded. |
| `redo` | Retry upload. |
| `file` | File. |
| `add` | Add file. |
| `alert` | Validation failure alert. |

78
one/docs/en-US/getting-started/babel-plugin-veui.md Normal file
View File

@@ -0,0 +1,78 @@
# babel-plugin-veui
:::tip
Currently VEUI is published on npm in the form of source code and has to be transpiled before use. (Read more about the trade-off of publishing source code in [this post](https://babeljs.io/blog/2018/06/26/on-consuming-and-publishing-es2015+-packages) published by [Henry Zhu](https://www.patreon.com/henryzhu) on Babel's blog.) Babel plugins for Lodash and Vue JSX are required to transpile VEUI and VEUI provides its own Babel plugin to offer minimized code size while simply `import`ing components.
:::
## Cherrypicking components
This Babel plugin allows you to write simple `import` statements without importing VEUI as a whole.
With this plugin, the following statement:
```js
import { Button, Input } from 'veui'
```
will be automatically transformed into:
```js
import Button from 'veui/components/Button'
import Input from 'veui/components/Input'
```
So only the components that are actually imported will appear in the final bundle. It works similarly with Lodash's [babel-plugin-lodash](https://github.com/lodash/babel-plugin-lodash).
## Automatic prefixing
To avoid conflict with native HTML elements, it's recommended to prefix components when they are registered as follows:
```js
export default {
components: {
'veui-button': Button,
'veui-input': Input
}
// ...
}
```
It's kind of verbose so `babel-plugin-veui` helps to support the following usage:
```js
import { VeuiButton, VeuiInput } from 'veui'
export default {
components: {
VeuiButton,
VeuiInput
}
// ...
}
```
When the imported component is prefixed with `Veui` the plugin will find the corresponding component without the prefix. Now it's possible to use components inside templates as follows:
```html
<veui-button>Submit</veui-button>
```
Apart from the prefix `veui-`, `babel-plugin-veui` also supports using `v-` as a prefix:
```js
import { VButton, VInput } from 'veui'
export default {
components: {
VButton,
VInput
}
// ...
}
```
And use as follows:
```html
<v-button>Submit</v-button>
```

33
one/docs/en-US/getting-started/focus-visible.md Normal file
View File

@@ -0,0 +1,33 @@
# `:focus-visible`
Usually we provide `:focus` styles for interactive elements to enhance (keyboard) accessibility. But when we click around with mouses, most browsers will activate `:focus` state of elements like `<button>`. This will easily cause misunderstanding that the button is “selected” especially when different types of buttons are placed together. [The draft of CSS Selector Level 4 provided a `:focus-visible` pseudo class selector](https://drafts.csswg.org/selectors-4/#the-focusvisible-pseudo) to help us targeting focused elements more accurately.
Actually Chrome is handling native `<button>`s in a similar way by default.
> [Details on `:focus-visible`](https://github.com/WICG/focus-visible/blob/master/explainer.md)
## Usage
VEUI's default style package `veui-theme-dls` uses a polyfill library for `:focus-visible` to provide optimized interactive experience. You need to import it yourself in your application code:
```js
import 'focus-visible'
```
Technically focus-visible isn't really a “polyfill” because we have to use the `.focus-visible` selector instead of directly using `:focus-visible`. This should also be noted when customizing styles.
### Browser compatibility
As the polyfill provided by WICG won't automatically import other polyfills, you need to import polyfill for `classList` when you need to support IE9 (requires to be installed by yourself as well).
```shell
$ npm i --save classlist-polyfill
```
```js
import 'classlist-polyfill'
```
## Demo
[[ demo src="/demo/focus-visible.vue" ]]

101
one/docs/en-US/getting-started/index.md Normal file
View File

@@ -0,0 +1,101 @@
# Getting started
:::tip
To make VEUI works in your project, please install and configure according to **all** of the following steps.
:::
## Installation
After scaffolding the project with Vue CLI, run the following under the its root directory:
```sh
npm i --save veui veui-theme-dls
npm i --save-dev less less-loader veui-loader babel-plugin-veui babel-plugin-lodash
```
## Configuration
### Babel plugin
You need to configure the auto-generated `babel.config.js` as follows:
```js
module.exports = {
presets: [
'@vue/app'
],
plugins: [
'veui',
'lodash'
]
}
```
Read more about `babel-plugin-veui` [here](/getting-started/babel-plugin-veui).
### webpack Loader
In general, you need to configure `vue.config.js` in the root directory as follows:
```js
module.exports = {
css: {
loaderOptions: {
less: {
javascriptEnabled: true
}
}
},
transpileDependencies: [
'veui',
'vue-awesome',
'resize-detector'
],
chainWebpack: config => {
config.module
.rule('veui')
.test(/\.vue$/)
.pre()
.use('veui-loader')
.loader('veui-loader')
.tap(() => {
return {
modules: [
{
package: 'veui-theme-dls',
fileName: '{module}.less'
},
{
package: 'veui-theme-dls',
fileName: '{module}.js',
transform: false
}
]
}
})
}
}
```
To learn more details of configuring `veui-loader`, read its documentation [here](/getting-started/veui-loader).
+++Why all these configs?
VEUI's style code is separate from its components. The component code doesn't explicitly depend on style code so `veui-loader` is needed to specify and inject style package into the components.
If you want to use `veui-theme-dls`, the default style package, you need import and configure `veui-loader` for webpack. As Less 3+ no longer enable JavaScript evaluation by default, which `veui-theme-dls` relies on, you need to manually enable this option.
We intend to transpile and build VEUI and its dependencies along with the application code itself so you need to add the related packages into the transpilation process.
+++
### Global stylesheet
When using `veui-theme-dls`, you need to import the base stylesheet, which includes style normalization.
You also need to import `:focus-visible` polyfill for better focus style to work properly ([Why?](./getting-started/focus-visible)).
Import from JavaScript:
```js
import 'veui-theme-dls/common.less'
import 'focus-visible'
```

35
one/docs/en-US/getting-started/style-variants.md Normal file
View File

@@ -0,0 +1,35 @@
# Style variants
VEUI provide style variants via the `ui` prop. Theme packages can provide different `ui` value for each component and users can also use custom `ui` values to create extended style variants.
### The `ui` prop
The `ui` prop takes a string consists of a list of whitespace-separated tokens, similar to HTML's native `class` attribute. Each token stands for a style variant of a component. In the following example, `primary` and `large` are both style variants of component `<veui-button>`:
```html
<veui-button ui="primary large">OK</veui-button>
```
:::tip
As we know, most component libraries provide style variants via enum props like `shape`/`size`/`type`/... .
While our design goal is that VEUI should not be bound to a specific design language tightly (though it's hard to completely decouple component structure/behavior and design languages). If we use enum props, once we need to create a completely new theme package but some of the new style variants cannot be described with the preserved enum props, we'll have to use something like `class` to attach style hooks to implement these style variants.
Using `class` will lead to problems of naming conventions, prefixes, etc. So we decided to directly output a custom attribute `ui` to component's DOM nodes for more semantic style variants and minimize the coupling with component logic.
:::
### Use the DLS theme
You can enable `veui-theme-dls` by setting the corresponding options for [`veui-loader`](./veui-loader). The theme package provides style variants for most components. You can refer to documentation for the `ui` prop in each component to learn about the supported style variants.
### Custom style variants
You don't need to register via component API to define custom `ui` tokens. Just adding style declarations for the corresponding `[ui~="..."]` selector would be sufficient.
eg. If you want a new `secondary` variant for `Button` component, just add styles to `.veui-button[ui~"secondary"]`:
[[ demo src="/demo/ui.vue" ]]
### Custom theme package
If you want to create a custom theme package, please read more about VEUI's theming API more the advanced ways of customizing `ui` prop at [Advanced › Theming](../advanced/theming).

64
one/docs/en-US/getting-started/veui-loader.md Normal file
View File

@@ -0,0 +1,64 @@
# veui-loader
This webpack loader is used to inject theme/locale modules for used components only at build time.
You can specify style/script module you want to inject into each VEUI component in loader options:
```js
modules: [
{
package: 'veui-theme-dls',
fileName: '{module}.less'
},
{
package: 'veui-theme-dls',
fileName: '{module}.js',
transform: false
}
]
```
Options above result in importing two extra modules for each component. eg. For `Button.vue`, `veui-theme-dls/components/button.less` and `veui-theme-dls/components/Button.js` will be injected.
## Why not use a Babel plugin?
As we know, in popular component libraries like Ant Design and Element, theme packages are injected with Babel plugins ([babel-plugin-import](https://github.com/ant-design/babel-plugin-import)/[babel-plugin-component](https://github.com/ElementUI/babel-plugin-component)). VEUI is using webpack loader for the following reasons:
1. webpack's resolving logic is transparent to Babel so we cannot accurately guarantee the module exists at the path resolved by webpack, so it's hard to specify arbitrary location of the theme package. veui-loader, on the other hand, can accurately check the existence of each generated path after resolved by webpack.
2. Vue Loader cannot handle styles imported from script blocks while extracting component-level critical CSS, while `veui-loader` solved the issue by preprocessing `.vue` files and inject style blocks instead of injecting import statements into script block.
## Options
* `modules`
Type: `Array<{package, path, fileName, transform}>`
The configuration of all extra modules to be injected into each component.
Properties of each module:
| Property | Type | Default | Description |
| -- | -- | -- | -- |
| `package` | `string` | - | The name of the injected package. It's generally the name of the theme package, like `'veui-theme-dls'`. |
| `path` | `string` | `'components'` | The path of the directory containing the injected module. |
| `fileName` | `string` | `'{module}.css'` | The file name template corresponds to the component name. Must include the placeholder `{module}`. |
| `transform` | `string|boolean` | `'kebab-case'` | Transformation applied for component names. The `{module}` part within `fileName` will be replaced with the transformed name. Provide `false` to prevent transformation. All possible values are `'kebab-case'`, `'camleCase'` and `'PascalCase'`. |
* `locale`
Type: `boolean|string=|Array<string>=`
The ID of the locale modules to be injected. Array values indicate to inject multiple locale packages. Defaults to `zh-Hans`. Current available values are `zh-Hans` and `en-US`.
Provide `false` to explicitly prevent automatically injecting locale package. You need to import locale packages manually.
* `global`
Type: `Array<string>=`
The array of module paths to be injected int every component.
:::warning
Do not inject style modules via the `global` option. This will repeatedly output the same style code for every component.
:::

30
one/docs/en-US/index.md Normal file
View File

@@ -0,0 +1,30 @@
# VEUI
:::oss-badges
[<img alt="VEUI on GitHub" src="https://badgen.net/badge/-/VEUI?label=GitHub" width="85.2" height="20">](https://github.com/ecomfe/veui) [<img alt="VEUI on CircleCI" src="https://badgen.net/circleci/github/ecomfe/veui?label=CircleCI" width="105.1" height="20">](https://circleci.com/gh/ecomfe/veui) [<img alt="VEUI on npm" src="https://badgen.net/npm/v/veui" width="133.5" height="20">](https://www.npmjs.com/package/veui)
:::
> VEUI is an enterprise UI component library, based on [Vue.js](https://vuejs.org).
#### Features
* 🤘 Powerful and flexible components & directives
* 💅 Switchable/customizable themes
* 🌲 Fully tree-shakable components
* 🌐 I18N support w/ compile-time optimization
* ⌨️ A11Y support w/ ARIA annotation & complete keyboard navigation
* ☁️ SSR support w/ component level Critical CSS
VEUI is designed to keep components and styles separated. Users can develop and specify their own theme package for VEUI. `veui-theme-dls` is the built-in theme package.
VEUI is published as ES modules with untranspiled ES next code thus requires to be compiled along with the application project.
Apart from components, VEUI also offers various powerful directives and plugins to boost application development based on Vue.js.
#### Browser compatibility
All evergreen browsers and IE11+.
#### License
[MIT](https://github.com/ecomfe/veui/blob/dev/LICENSE)