Skip to content

Commit 27b64b7

Browse files
tmorehousejacobmllr95
tmorehouse
and
jacobmllr95
authored
chore: add dedicated documentation for v-b-toggle directive and additional popover/tooltip docs updates (closes bootstrap-vue#5262) (bootstrap-vue#5306)
* chore: add dedicated documentation for `v-b-toggle` directive * Update nuxt.config.js * Update package.json * Update index.js * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update README.md * Update package.json * Update README.md * Update package.json * Update README.md Co-authored-by: Jacob Müller <jacob.mueller.elz@gmail.com>
1 parent 32737f8 commit 27b64b7

File tree

8 files changed

+148
-20
lines changed

8 files changed

+148
-20
lines changed

‎docs/nuxt.config.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -272,7 +272,7 @@ module.exports = {
272272
routes: () => [
273273
// Dynamic slug routes
274274
...getRoutesByDir('src', 'components'),
275-
...getRoutesByDir('src', 'directives', ['modal', 'toggle']),
275+
...getRoutesByDir('src', 'directives', ['modal']),
276276
...getRoutesByDir('docs/markdown', 'reference')
277277
]
278278
},

‎src/components/collapse/README.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,8 @@
2222

2323
## Usage
2424

25-
Other elements can easily toggle `<b-collapse>` components using the `v-b-toggle` directive.
25+
Other elements can easily toggle `<b-collapse>` components using the
26+
[`v-b-toggle` directive](/docs/directives/toggle).
2627

2728
```html
2829
<div>
@@ -300,4 +301,8 @@ query. See the
300301
[reduced motion section of our accessibility documentation](/docs/reference/accessibility) for
301302
additional details.
302303

304+
## See also
305+
306+
- [`v-b-toggle` directive](/docs/directives/toggle)
307+
303308
<!-- Component reference added automatically from component package.json -->

‎src/components/collapse/index.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
import { BCollapse } from './collapse'
2-
import { VBToggle } from '../../directives/toggle/toggle'
2+
import { VBTogglePlugin } from '../../directives/toggle'
33
import { pluginFactory } from '../../utils/plugins'
44

55
const CollapsePlugin = /*#__PURE__*/ pluginFactory({
66
components: { BCollapse },
7-
directives: { VBToggle }
7+
plugins: { VBTogglePlugin }
88
})
99

1010
export { CollapsePlugin, BCollapse }

‎src/components/collapse/package.json

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,8 @@
44
"meta": {
55
"title": "Collapse",
66
"description": "Easily toggle content visibility on your pages. Includes support for making accordions.",
7-
"directives": [
8-
{
9-
"directive": "VBToggle",
10-
"description": "Directive for toggling a collapse by ID",
11-
"expression": "String",
12-
"modifiers": [
13-
{
14-
"name": "{collapseId}",
15-
"pattern": "[a-zA-Z][a-zA-Z0-9_\\-]*",
16-
"description": "Collapse ID to open. Replace `{collapseId}` with the collapse's ID"
17-
}
18-
]
19-
}
7+
"plugins": [
8+
"VBTogglePlugin"
209
],
2110
"components": [
2211
{

‎src/components/popover/README.md

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,29 @@ Things to know when using popover component:
3636
- When triggered from hyperlinks that span multiple lines, popovers will be centered. Use
3737
`white-space: nowrap;` on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
3838

39+
## Target
40+
41+
The target is the _trigger_ element (or component) that will trigger the popover. The target is
42+
specified via the `target` prop, and can be any of the following:
43+
44+
- A string identifying the ID of the trigger element (or ID of the root element of a component)
45+
- A reference (ref) to an `HTMLElement` or an `SVGElement` (e.g. via `this.$refs.refName`)
46+
- A reference (ref) to a component that has either an `HTMLElement` or `SVGElement` as its root
47+
element (e.g. via `this.$refs.refName`)
48+
- A function (callback) that returns a reference to an `HTMLElement` or `SVGElement`
49+
50+
For more information on references, see the official
51+
[Vue documentation](https://vuejs.org/v2/api/#vm-refs).
52+
53+
**Notes:**
54+
3955
The target element **must** exist in the document before `<b-popover>` is mounted. If the target
4056
element is not found during mount, the popover will never open. Always place your `<b-popover>`
41-
component lower in the DOM than your target element.
57+
component lower in the DOM than your target element. This rule also applies if a callback function
58+
is used as target element, since that callback is called only once on mount.
59+
60+
`HTMLElement` refers to standard HTML elements such as `<div>`, `<button>`, etc, while `SVGElement`
61+
refers to `<svg>` or supported child elements of SVGs.
4262

4363
## Positioning
4464

‎src/components/tooltip/README.md

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,29 @@ Things to know when using tooltip component:
3434
- When triggered from hyperlinks that span multiple lines, tooltips will be centered. Use
3535
white-space: nowrap; on your `<a>`s, `<b-link>`s and `<router-link>`s to avoid this behavior.
3636

37+
## Target
38+
39+
The target is the _trigger_ element (or component) that will trigger the tooltip. The target is
40+
specified via the `target` prop, and can be any of the following:
41+
42+
- A string identifying the ID of the trigger element (or ID of the root element of a component)
43+
- A reference (ref) to an `HTMLElement` or an `SVGElement` (e.g. `this.$refs.refName`)
44+
- A reference (ref) to a component that has either an `HTMLElement` or `SVGElement` as its root
45+
element (e.g. `this.$refs.refName`)
46+
- A function (callback) that returns a reference to an `HTMLElement` or `SVGElement`
47+
48+
For more information on references, see the official
49+
[Vue documentation](https://vuejs.org/v2/api/#vm-refs).
50+
51+
**Note:**
52+
3753
The target element **must** exist in the document before `<b-tooltip>` is mounted. If the target
3854
element is not found during mount, the tooltip will never open. Always place your `<b-tooltip>`
39-
component lower in the DOM than your target element. This rule also applies if a callback is used as
40-
target element, since that callback is called only once on mount.
55+
component lower in the DOM than your target element. This rule also applies if a callback function
56+
is used as target element, since that callback is called only once on mount.
57+
58+
`HTMLElement` refers to standard HTML elements such as `<div>`, `<button>`, etc, while `SVGElement`
59+
refers to `<svg>` or supported child elements of SVGs.
4160

4261
## Positioning
4362

‎src/directives/toggle/README.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Toggle
2+
3+
> `v-b-toggle` is a light-weight directive for toggling the visibility of collapses and sidebars,
4+
> and includes automated accessibility handling.
5+
6+
## Overview
7+
8+
The `v-b-toggle` directive can be used on interactive elements, such as buttons, to toggle the
9+
visibility state of the [`<b-collapse>`](/docs/components/collapse) and
10+
[`<b-sidebar>`](/docs/components/sidebar) components.
11+
12+
Besides toggling the visibility of the target component, the directive automatically updates ARIA
13+
accessibility attributes on the element it is applied to so that they reflect the visibility state
14+
of the target component. Refer to the [Accessibility section](#accessibility) below for additional
15+
details.
16+
17+
## Directive syntax and usage
18+
19+
The directive is applied to the element or component that triggers the visibility of hte target. The
20+
target component can be specified (via ID) as either a directive modifier(s) or as a string passed
21+
to as the directive value:
22+
23+
- `v-b-toggle.my-collapse` - the directive modifier (multiple targets allowed)
24+
- `v-b-toggle="'my-collapse'"` - the directive value (as a String, single target only)
25+
26+
Modifiers and the value can be used at the same time.
27+
28+
### Example usage
29+
30+
```html
31+
<template>
32+
<div>
33+
<div class="mb-3">
34+
<b-button v-b-toggle.my-collapse>Toggle Collapse</b-button>
35+
<b-button v-b-toggle.my-sidebar>Toggle Sidebar</b-button>
36+
</div>
37+
38+
<b-collapse id="my-collapse">
39+
<b-card title="Collapsible card">
40+
Hello world!
41+
</b-card>
42+
</b-collapse>
43+
44+
<b-sidebar id="my-sidebar" title="Sidebar" shadow>
45+
<div class="px-3 py-2">
46+
Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
47+
in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
48+
</div>
49+
</b-sidebar>
50+
</div>
51+
</template>
52+
53+
<!-- v-b-toggle-directive.vue -->
54+
```
55+
56+
## Accessibility
57+
58+
The directive, for accessibility reasons, should be placed on an clickable interactive element such
59+
as a `<button>` or `<b-button>`, which can easily be accessed by keyboard-only users and screen
60+
reader users. Elements that do not natively have an accessibility role of `button` will have the
61+
attributes `role="button"` and `tabindex="0"` applied, and will have the appropriate click and
62+
keyboard handlers instantiated. Therefore it is _highly recommended_ to _not_ place the directive on
63+
form controls other than buttons.
64+
65+
The directive applies, and dynamically updates, the following ARIA attributes on the trigger
66+
element:
67+
68+
- `aria-controls` - the ID of the collapse or sidebar component(s) being toggled
69+
- `aria-expanded` - the visibility state of the collapse or sidebar
70+
71+
When the target component is _not_ expanded, the trigger element will have the class `collapsed`
72+
applied. When the target component is expanded, the `collapsed` class will be removed from the
73+
trigger element.
74+
75+
## See also
76+
77+
- [`<b-collapse>`](/docs/components/collapse) Collapsible content with accordion support
78+
- [`<b-sidebar>`](/docs/components/sidebar) Off-canvas sidebar

‎src/directives/toggle/package.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "@bootstrap-vue/v-b-toggle",
3+
"version": "1.0.0",
4+
"meta": {
5+
"title": "Toggle",
6+
"description": "A light-weight directive for toggling visibility state for collapses and sidebars by ID. It automatically handles the accessibility attributes on the trigger element.",
7+
"directive": "VBToggle",
8+
"expression": "String",
9+
"modifiers": [
10+
{
11+
"name": "{componentId}",
12+
"pattern": "[a-zA-Z][a-zA-Z0-9_\\-]*",
13+
"description": "ID of component to toggle"
14+
}
15+
]
16+
}
17+
}

0 commit comments

Comments
 (0)