-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
5 changed files
with
1,843 additions
and
734 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,14 +1,14 @@ | ||
# Vue A11yDialog [](https://travis-ci.org/morkro/vue-a11y-dialog) | ||
|
||
This is a Vue.js wrapper component for [`a11y-dialog@5.2.0`](https://github.com/edenspiekermann/a11y-dialog) ([**demo**](https://codesandbox.io/s/rj20wr1kpp)) using [`[email protected]`](https://github.com/LinusBorg/portal-vue). | ||
This is a Vue.js wrapper component for [`a11y-dialog@5.3.1`](https://github.com/edenspiekermann/a11y-dialog) ([**demo**](https://codesandbox.io/s/rj20wr1kpp)) using [`[email protected]`](https://github.com/LinusBorg/portal-vue). | ||
|
||
- [Install](#install) | ||
- [Usage](#usage) | ||
- [Multiple dialogs](#multiple-dialogs) | ||
- [API](#api) | ||
- [Events](#events) | ||
- [Slots](#slots) | ||
- [Server-side Rendering](#server-side-rendering) | ||
- [Install](#install) | ||
- [Usage](#usage) | ||
- [Multiple dialogs](#multiple-dialogs) | ||
- [API](#api) | ||
- [Events](#events) | ||
- [Slots](#slots) | ||
- [Server-side Rendering](#server-side-rendering) | ||
|
||
## Install | ||
|
||
|
@@ -21,9 +21,9 @@ npm install vue-a11y-dialog | |
In your `main.js` application file, install the component: | ||
|
||
```js | ||
import VueA11yDialog from 'vue-a11y-dialog' | ||
import VueA11yDialog from "vue-a11y-dialog"; | ||
|
||
Vue.use(VueA11yDialog) | ||
Vue.use(VueA11yDialog); | ||
``` | ||
|
||
Then use it as follows: | ||
|
@@ -52,26 +52,27 @@ Then use it as follows: | |
</div> | ||
</template> | ||
``` | ||
|
||
```js | ||
export default { | ||
name: 'YourComponent', | ||
name: "YourComponent", | ||
|
||
data: () => ({ | ||
dialog: null | ||
}), | ||
|
||
methods: { | ||
openDialog () { | ||
openDialog() { | ||
if (this.dialog) { | ||
this.dialog.show() | ||
this.dialog.show(); | ||
} | ||
}, | ||
|
||
assignDialogRef (dialog) { | ||
this.dialog = dialog | ||
assignDialogRef(dialog) { | ||
this.dialog = dialog; | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
In your `index.html`, add a container where your dialog will be rendered into. | ||
|
@@ -92,18 +93,18 @@ It's important to assign the direct reference to the dialog instance via `@dialo | |
Alternatively, you can also import the component directly into your file without installing it first: | ||
|
||
```js | ||
import { A11yDialog } from 'vue-a11y-dialog' | ||
import { A11yDialog } from "vue-a11y-dialog"; | ||
export default { | ||
name: 'YourComponent', | ||
name: "YourComponent", | ||
|
||
components: { | ||
'a11y-dialog': A11yDialog | ||
"a11y-dialog": A11yDialog | ||
}, | ||
|
||
methods: { | ||
// ... | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
### Multiple dialogs | ||
|
@@ -149,21 +150,22 @@ In your `<template>`: | |
``` | ||
|
||
In your `<script>`: | ||
|
||
```js | ||
import { A11yDialog } from 'vue-a11y-dialog' | ||
import { A11yDialog } from "vue-a11y-dialog"; | ||
export default { | ||
name: 'YourComponent', | ||
name: "YourComponent", | ||
|
||
data: () => ({ | ||
dialogs: {} | ||
}), | ||
|
||
methods: { | ||
assignDialogRef (type, dialog) { | ||
this.dialogs[type] = dialog | ||
assignDialogRef(type, dialog) { | ||
this.dialogs[type] = dialog; | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
## API | ||
|
@@ -172,11 +174,12 @@ export default { | |
### `disable-native` | ||
|
||
- **Property**: `disable-native` | ||
- **Type**: `Boolean` | ||
- **Default**: `false` | ||
- **Description**: Per default we're using the native `<dialog>` element. However, if you want to disable that and use a `<div role="dialog">` instead, you can just do that by adding this attribute. This gives you full control (and responsibilites) over styling. Read the [`a11y-dialog` Styling layer documentation](http://edenspiekermann.github.io/a11y-dialog/#styling-layer) for more information. | ||
- **Usage**: | ||
- **Property**: `disable-native` | ||
- **Type**: `Boolean` | ||
- **Default**: `false` | ||
- **Description**: Per default we're using the native `<dialog>` element. However, if you want to disable that and use a `<div role="dialog">` instead, you can just do that by adding this attribute. This gives you full control (and responsibilites) over styling. Read the [`a11y-dialog` Styling layer documentation](http://edenspiekermann.github.io/a11y-dialog/#styling-layer) for more information. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog disable-native> | ||
<!-- ... --> | ||
|
@@ -185,11 +188,12 @@ export default { | |
|
||
### `id` | ||
|
||
- **Property**: `id` | ||
- **Type**: `String` | ||
- **Required**: `true` | ||
- **Description**: The unique HTML `id` attribute added to the dialog element, internally used by a11y-dialog to manipulate the dialog. | ||
- **Usage**: | ||
- **Property**: `id` | ||
- **Type**: `String` | ||
- **Required**: `true` | ||
- **Description**: The unique HTML `id` attribute added to the dialog element, internally used by a11y-dialog to manipulate the dialog. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog id="main-dialog"> | ||
<!-- ... --> | ||
|
@@ -198,11 +202,12 @@ export default { | |
|
||
### `app-root` | ||
|
||
- **Property**: `app-root` | ||
- **Type**: `String`, `Array<String>` — CSS Selector string. | ||
- **Required**: `true` | ||
- **Description**: The selector(s) `a11y-dialog` needs to disable when the dialog is open. | ||
- **Usage**: | ||
- **Property**: `app-root` | ||
- **Type**: `String`, `Array<String>` — CSS Selector string. | ||
- **Required**: `true` | ||
- **Description**: The selector(s) `a11y-dialog` needs to disable when the dialog is open. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog app-root="#app"> | ||
<!-- ... --> | ||
|
@@ -211,11 +216,12 @@ export default { | |
|
||
### `dialog-root` | ||
|
||
- **Property**: `dialog-root` | ||
- **Type**: `String` — CSS Selector string. | ||
- **Required**: `true` | ||
- **Description**: The container for the dialog to be rendered into. | ||
- **Usage**: | ||
- **Property**: `dialog-root` | ||
- **Type**: `String` — CSS Selector string. | ||
- **Required**: `true` | ||
- **Description**: The container for the dialog to be rendered into. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog dialog-root="#dialog-root"> | ||
<!-- ... --> | ||
|
@@ -224,12 +230,13 @@ export default { | |
|
||
### `class-names` | ||
|
||
- **Property**: `class-names` | ||
- **Type**: `Object` | ||
- **Required**: `false` | ||
- **Default**: `{}` | ||
- **Description**: Object of classes for each HTML element of the dialog element. Keys are: `base`, `overlay`, `element`, `document`, `title`, `closeButton`. See [a11y-dialog docs](http://edenspiekermann.github.io/a11y-dialog/#expected-dom-structure) for reference. | ||
- **Usage**: | ||
- **Property**: `class-names` | ||
- **Type**: `Object` | ||
- **Required**: `false` | ||
- **Default**: `{}` | ||
- **Description**: Object of classes for each HTML element of the dialog element. Keys are: `base`, `overlay`, `element`, `document`, `title`, `closeButton`. See [a11y-dialog docs](http://edenspiekermann.github.io/a11y-dialog/#expected-dom-structure) for reference. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog :class-names="{ base: 'base-class', overlay: 'overlay-class' }"> | ||
<!-- ... --> | ||
|
@@ -238,12 +245,13 @@ export default { | |
|
||
### `title-id` | ||
|
||
- **Property**: `title-id` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: Defaults to `id + '-title'`. | ||
- **Description**: The HTML `id` attribute of the dialog’s title element, used by assistive technologies to provide context and meaning to the dialog window. | ||
- **Usage**: | ||
- **Property**: `title-id` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: Defaults to `id + '-title'`. | ||
- **Description**: The HTML `id` attribute of the dialog’s title element, used by assistive technologies to provide context and meaning to the dialog window. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog title-id="main-title"> | ||
<!-- ... --> | ||
|
@@ -252,12 +260,13 @@ export default { | |
|
||
### `close-button-label` | ||
|
||
- **Property**: `close-button-label` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: `'Close this dialog window'` | ||
- **Description**: The HTML `aria-label` attribute of the close button, used by assistive technologies to provide extra meaning to the usual cross-mark. | ||
- **Usage**: | ||
- **Property**: `close-button-label` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: `'Close this dialog window'` | ||
- **Description**: The HTML `aria-label` attribute of the close button, used by assistive technologies to provide extra meaning to the usual cross-mark. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog close-button-label="Close this super dialog"> | ||
<!-- ... --> | ||
|
@@ -266,12 +275,13 @@ export default { | |
|
||
### `role` | ||
|
||
- **Property**: `role` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: `dialog` | ||
- **Description**: The `role` attribute of the dialog element, either `dialog` (default) or `alertdialog` to make it a modal (preventing closing on click outside of <kbd>ESC</kbd> key). | ||
- **Usage**: | ||
- **Property**: `role` | ||
- **Type**: `String` | ||
- **Required**: `false` | ||
- **Default**: `dialog` | ||
- **Description**: The `role` attribute of the dialog element, either `dialog` (default) or `alertdialog` to make it a modal (preventing closing on click outside of <kbd>ESC</kbd> key). | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog role="alertdialog"> | ||
<!-- ... --> | ||
|
@@ -282,32 +292,35 @@ export default { | |
|
||
### `dialog-ref` | ||
|
||
- **Returns**: An `a11y-dialog` instance or `undefined`. | ||
- **Description**: This event emits the `a11y-dialog` instance once the component has been initialised. When it gets `destroyed`, the event returns `undefined`. This is needed to call instance methods of the dialog, e.g. `this.dialog.show()`. | ||
- **Usage**: | ||
- **Returns**: An `a11y-dialog` instance or `undefined`. | ||
- **Description**: This event emits the `a11y-dialog` instance once the component has been initialised. When it gets `destroyed`, the event returns `undefined`. This is needed to call instance methods of the dialog, e.g. `this.dialog.show()`. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog @dialog-ref="assignDialogRef"> | ||
<!-- ... --> | ||
</a11y-dialog> | ||
``` | ||
|
||
```js | ||
export default { | ||
// ... | ||
methods: { | ||
assignDialogRef (dialog) { | ||
this.dialog = dialog | ||
assignDialogRef(dialog) { | ||
this.dialog = dialog; | ||
} | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
## Slots | ||
|
||
### `title` | ||
|
||
- **Name**: `title` | ||
- **Description**: The title of the dialog, mandatory in the document to provide context to assistive technology. Could be [hidden with CSS](https://hugogiraudel.com/2016/10/13/css-hide-and-seek/) (while remaining accessible). | ||
- **Usage**: | ||
- **Name**: `title` | ||
- **Description**: The title of the dialog, mandatory in the document to provide context to assistive technology. Could be [hidden with CSS](https://hugogiraudel.com/2016/10/13/css-hide-and-seek/) (while remaining accessible). | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog> | ||
<template v-slot:title> | ||
|
@@ -319,10 +332,11 @@ export default { | |
|
||
### `closeButtonContent` | ||
|
||
- **Name**: `closeButtonLabel` | ||
- **Default**: `\u00D7` (×) | ||
- **Description**: The string that is the inner HTML of the close button. | ||
- **Usage**: | ||
- **Name**: `closeButtonLabel` | ||
- **Default**: `\u00D7` (×) | ||
- **Description**: The string that is the inner HTML of the close button. | ||
- **Usage**: | ||
|
||
```html | ||
<a11y-dialog> | ||
<template v-slot:closeButtonContent> | ||
|
Oops, something went wrong.