Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commitd4a6402

Browse files
dwgrayCopilot
andauthored
fix(BToggle)! Remove redundant attribute cleanup & update docs for accessibility attributes on show/hide components (#2918)
* refactor(BToggle)!: delegate aria-expanded cleanup to composable* docs: document how we handle accessibility attributes wrt visibility* docs: create an architecture doc covering the work in this PR and update Copilot instructions---------Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent2983d32 commitd4a6402

File tree

16 files changed

+840
-34
lines changed

16 files changed

+840
-34
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 98 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,64 +5,73 @@ Always reference these instructions first and fallback to search or bash command
55
##Working Effectively
66

77
###Required Setup
8+
89
- Install Node.js 20.x or 22.x (engine requires >=22.0.0 but 20.x works with warnings)
910
- Install pnpm globally:`npm install -g pnpm@10.13.1` (ONLY pnpm is allowed as package manager) Use the version specified in the packageManager field of the package.json file
1011
- Clone repository and open the**root** directory (not subdirectories like packages/bootstrap-vue-next)
1112

1213
###Bootstrap, Build, and Test the Repository
14+
1315
1.`pnpm install --ignore-scripts --frozen-lockfile` -- takes 2 seconds. Use`--ignore-scripts` to avoid docs build network issues.
1416
2.`pnpm --filter bootstrap-vue-next run build` -- takes 27 seconds. NEVER CANCEL. Set timeout to 60+ minutes.
1517
3.`pnpm --filter bootstrap-vue-next run test:unit:ci` -- takes 40 seconds. NEVER CANCEL. Set timeout to 60+ minutes.
1618
4.`pnpm --filter bootstrap-vue-next run test:lint` -- takes 12 seconds. NEVER CANCEL. Set timeout to 30+ minutes.
1719

1820
###Build Individual Components
21+
1922
- Bootstrap Vue Next core package:`pnpm --filter bootstrap-vue-next run build` -- 27 seconds
20-
- Nuxt package:`pnpm --filter @bootstrap-vue-next/nuxt run build` -- 25 seconds
23+
- Nuxt package:`pnpm --filter @bootstrap-vue-next/nuxt run build` -- 25 seconds
2124
- Playground app:`pnpm --filter playground run build` -- 8 seconds
2225
-**NEVER** try to build docs app directly - it fails due to network connectivity (OpenCollective API)
2326

2427
###Development Servers
25-
- Core package dev server:`pnpm --filter bootstrap-vue-next run dev` (runs onhttp://localhost:5174)
26-
- Playground app dev server:`pnpm --filter playground run dev` (runs onhttp://localhost:5173)
27-
- Docs dev server:`pnpm --filter docs run dev` (runs onhttp://localhost:8000)
28+
29+
- Core package dev server:`pnpm --filter bootstrap-vue-next run dev` (runs on<http://localhost:5174>)
30+
- Playground app dev server:`pnpm --filter playground run dev` (runs on<http://localhost:5173>)
31+
- Docs dev server:`pnpm --filter docs run dev` (runs on<http://localhost:8000>)
2832
- All dev servers:`pnpm dev` (starts all development environments in parallel)
2933

3034
##Validation
3135

3236
###Always Validate Changes
37+
3338
- ALWAYS run`pnpm --filter bootstrap-vue-next run test:lint` before committing (12 seconds)
3439
- ALWAYS run`pnpm --filter bootstrap-vue-next run test:unit:ci` after making changes (40 seconds)
3540
- ALWAYS run`pnpm --filter bootstrap-vue-next run build` to ensure buildability (27 seconds)
3641
- For linting fixes:`pnpm --filter bootstrap-vue-next run lint` (auto-fixes issues)
3742

3843
###Manual Testing Scenarios
39-
- Test component changes using the core package dev server athttp://localhost:5174
44+
45+
- Test component changes using the core package dev server at<http://localhost:5174>
4046
- Use`./packages/bootstrap-vue-next/src/App.vue` as a test area for changes
41-
- Test real-world usage with the playground app athttp://localhost:5173
47+
- Test real-world usage with the playground app at<http://localhost:5173>
4248
- The playground mimics user library usage but requires`pnpm build` for changes (no hot-reload)
4349

4450
###CI Validation
51+
4552
- The CI runs: build, test:lint:ci, test:unit:ci
4653
- Use`pnpm run test:ci` to run the same tests locally
4754
- NEVER CANCEL builds or tests - they are designed for long runs
4855

4956
##Repository Structure
5057

5158
###Monorepo Layout
52-
```
59+
60+
```plaintext
5361
packages/
5462
├── bootstrap-vue-next/ # Main Vue 3 component library
5563
└── nuxt/ # Nuxt 3 module
5664
5765
apps/
58-
├── docs/ # VitePress documentation site
66+
├── docs/ # VitePress documentation site
5967
└── playground/ # Test application for user scenarios
6068
6169
templates/
6270
└── vite/ # Vite starter template
6371
```
6472

6573
###Key Directories
74+
6675
-`packages/bootstrap-vue-next/src/` - Main library source code
6776
-`packages/bootstrap-vue-next/src/components/` - Vue components
6877
-`packages/bootstrap-vue-next/src/composables/` - Vue composables
@@ -71,15 +80,22 @@ templates/
7180
-`apps/playground/src/` - User scenario testing
7281

7382
###Important Files
83+
7484
-`package.json` - Root workspace configuration
7585
-`pnpm-workspace.yaml` - Workspace package definitions
7686
-`turbo.json` - Task pipeline configuration
7787
-`vitest.workspace.mjs` - Test workspace setup
7888
-`.github/workflows/ci.yaml` - CI pipeline
7989

90+
###Architecture Documentation
91+
92+
-`architecture/` - Technical architecture documentation
93+
-`ARIA_VISIBILITY.md` - ARIA accessibility system for show/hide components
94+
8095
##Documentation Requirements
8196

8297
###Component Documentation (.data.ts files)
98+
8399
-**CRITICAL**: When adding/modifying component props, events, or slots, ALWAYS update the corresponding`.data.ts` file in`apps/docs/src/data/components/`
84100
- Each component has a`.data.ts` file that defines:
85101
-`props`: All component properties with types, defaults, and descriptions
@@ -92,20 +108,23 @@ templates/
92108
##Common Tasks
93109

94110
###Making Component Changes
111+
95112
1. Edit files in`packages/bootstrap-vue-next/src/components/`
96-
2. Test using`packages/bootstrap-vue-next/src/App.vue`
113+
2. Test using`packages/bootstrap-vue-next/src/App.vue`
97114
3. Run`pnpm --filter bootstrap-vue-next run dev` for hot-reload testing
98115
4. Run`pnpm --filter bootstrap-vue-next run test:unit:ci` to validate
99116
5. Run`pnpm --filter bootstrap-vue-next run test:lint` before committing
100117
6.**ALWAYS update documentation** in`apps/docs/src/data/components/*.data.ts` when adding/modifying props, events, or slots
101118

102119
###Testing Changes End-to-End
120+
103121
1. Make changes in`packages/bootstrap-vue-next/`
104122
2. Run`pnpm --filter bootstrap-vue-next run build`
105123
3. Test in playground:`pnpm --filter playground run dev`
106124
4. Check real usage scenarios in the playground app
107125

108126
###Adding New Components
127+
109128
1. Create component in`packages/bootstrap-vue-next/src/components/`
110129
2. Add to`packages/bootstrap-vue-next/src/components/index.ts`
111130
3. Write tests following existing patterns (see`*.spec.ts` files)
@@ -116,55 +135,122 @@ templates/
116135
- Modifying component interfaces
117136

118137
###Working with Styles
138+
119139
- Main styles:`packages/bootstrap-vue-next/src/styles/styles.scss`
120140
- Component styles are typically in the component`.vue` files
121141
- Bootstrap 5.3.x is the base CSS framework
122142

123143
##Timing and Performance
124144

125145
###Command Timing (measured)
146+
126147
-`pnpm install --ignore-scripts --frozen-lockfile`:~2 seconds
127-
-`pnpm --filter bootstrap-vue-next run build`:~27 seconds
148+
-`pnpm --filter bootstrap-vue-next run build`:~27 seconds
128149
-`pnpm --filter bootstrap-vue-next run test:unit:ci`:~40 seconds (1567 tests)
129150
-`pnpm --filter bootstrap-vue-next run test:lint`:~12 seconds
130151
-`pnpm --filter playground run build`:~8 seconds
131152
-`pnpm --filter @bootstrap-vue-next/nuxt run build`:~25 seconds
132153

133154
###CRITICAL TIMEOUT WARNINGS
155+
134156
-**NEVER CANCEL** any build or test command
135-
- Set timeouts to 60+ minutes for builds
157+
- Set timeouts to 60+ minutes for builds
136158
- Set timeouts to 60+ minutes for test suites
137159
- Builds may take longer in CI environments
138160
- Test suites run 1500+ tests and require time
139161

140162
##Known Issues and Workarounds
141163

142164
###Network-Related Build Failures
165+
143166
- Docs build fails due to OpenCollective API calls:**EXPECTED**
144167
- Use`pnpm install --ignore-scripts` to skip problematic prepare scripts
145168
- Filter builds to specific packages to avoid docs:`pnpm --filter bootstrap-vue-next run build`
146169

147170
###Engine Version Warnings
171+
148172
- Repository requires Node.js >=22.0.0 but works with 20.x (shows warnings)
149173
- Warnings are safe to ignore during development
150174

151175
###Generated Files
176+
152177
-`*.timestamp-*` files are generated and should be ignored (already in .gitignore)
153178
- VitePress generates temporary data files during build
154179

155180
##Package Manager Rules
181+
156182
-**ONLY pnpm is allowed** - npm and yarn will cause errors
157183
- Use exact version`pnpm@10.13.1` for consistency
158184
- Always use`--frozen-lockfile` for reproducible installs
159185
- Use workspace filters:`--filter <package-name>` for targeted operations
160186

161187
##Conventional Commits
188+
162189
- Use conventional commit format:`feat:`,`fix:`,`docs:`, etc.
163190
- Required for automated changelog and releases
164191
- Examples:`feat: add new button variant`,`fix: resolve modal focus issue`
165192

166193
##Testing Architecture
194+
167195
- Vitest for unit testing with Vue Test Utils
168196
- 1567+ tests across components
169197
- Coverage reports available via`pnpm --filter bootstrap-vue-next run test:coverage`
170-
- Tests use Happy DOM environment for performance
198+
- Tests use Happy DOM environment for performance
199+
200+
##Documentation Examples
201+
202+
###Demo File Format
203+
204+
All demo files in`apps/docs/src/docs/*/demo/` must follow this structure:
205+
206+
1.**Order**: Template first, then script, then style (if applicable)
207+
2.**Template-Only Examples**: For simple template-only examples wrap example code in`<!-- #region template -->` and`<!-- #endregion template -->` comments
208+
3.**Complex Examples**: Include script setup after template, using TypeScript
209+
210+
**Template-only example:**
211+
212+
```vue
213+
<template>
214+
<!-- #region template -->
215+
<BButton v-b-toggle.my-collapse>Toggle</BButton>
216+
<BCollapse id="my-collapse">
217+
<BCard>Content</BCard>
218+
</BCollapse>
219+
<!-- #endregion template -->
220+
</template>
221+
```
222+
223+
**Example with script:**
224+
225+
```vue
226+
<template>
227+
<BButton @click="toggle">Toggle</BButton>
228+
<BCollapse v-model="visible">
229+
<BCard>Content</BCard>
230+
</BCollapse>
231+
</template>
232+
233+
<script setup lang="ts">
234+
import {ref} from 'vue'
235+
236+
const visible = ref(false)
237+
const toggle = () => {
238+
visible.value = !visible.value
239+
}
240+
</script>
241+
```
242+
243+
###Demo References in Markdown
244+
245+
Use the`<<< DEMO` syntax to reference demo files:
246+
247+
-**Show full file**:`<<< DEMO ./demo/MyComponent.vue{vue}`
248+
-**Show specific section**: Use`#region name` markers in the demo file and reference with`#name` in the markdown (e.g.,`#region template` is referenced as`#template`)
249+
250+
###Demo File Guidelines
251+
252+
- Place demo files in`apps/docs/src/docs/[category]/demo/` directory
253+
- Name files descriptively:`ComponentFeature.vue` (e.g.,`AccordionOverview.vue`,`AlertDismissible.vue`)
254+
- Use unique IDs for all components to avoid conflicts when multiple demos render on same page
255+
- Keep examples focused on demonstrating one feature or pattern
256+
- Include comments for clarity when showing complex patterns

‎apps/docs/src/docs/components/alert.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ The BAlert exposes four functions to manipulate the state of an active timer: `p
6868

6969
<<< DEMO ./demo/AlertFunctions.vue
7070

71+
##Accessibility
72+
73+
For information on managing ARIA attributes for alert triggers (when using dismissible alerts), see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
74+
7175
##Timer Props
7276

7377
-`Immediate`: Setting this property to`false` will cause a timer to not start immediately upon render. A timer that is not started is not rendered. It must manually be started with`resume()` or`restart()`. Default is`true`.

‎apps/docs/src/docs/components/collapse.md‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,6 @@ You can also pass multiple target Ids via the directive _value_ in BootstrapVueN
4949
The`header` and`footer` slots can be used to create custom toggles for your collapsible content. The default slot is
5050
used for the content to be hidden or shown.
5151

52-
Using the`v-b-toggle` directive to toggle the`BCollapse` will still work but the`collapsed` CSS class will no longer be applied to the element with the directive.
53-
5452
The following properties are available for the`header` and`footer` and`default` slots:
5553

5654
| Property| Type| Description|
@@ -81,14 +79,12 @@ These are accessed through the [template ref](https://vuejs.org/guide/essentials
8179

8280
##Accessibility
8381

84-
The`v-b-toggle` directive will automatically add the ARIAattributes`aria-controls`and
85-
`aria-expanded` to the component that thedirective appears on (as well as add the class`collapsed`
86-
when not expanded).`aria-expanded`will reflect the state of thetarget`BCollapse` component,
87-
while`aria-controls` will be set to the Id(s) of the target`BCollapse` component(s).
82+
The`v-b-toggle` directive will automatically add the ARIAattribute`aria-controls`to the trigger
83+
element and register it with thetarget`BCollapse` component. The collapse component will then
84+
automatically manage the`aria-expanded`attribute and`collapsed` class on thetrigger element to
85+
reflect its visibility state.
8886

89-
If using`v-model` to set the visible state instead of the directive`v-b-toggle`, you will be
90-
required to, on the toggle element, add the`aria-controls` and other appropriate attributes and
91-
classes yourself.
87+
For detailed information on managing ARIA attributes for triggers, including examples of using`v-b-toggle` with`v-model` and manual ARIA management, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
9288

9389
While the`v-b-toggle` directive can be placed on almost any HTML element or Vue component, it is
9490
recommended to use a button or link (or similar component) to act as your toggler; otherwise your

‎apps/docs/src/docs/components/dropdown.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,8 @@ The default ARIA role is set to `menu`, but you can change this default to anoth
287287

288288
When a menu item does not trigger navigation, it is recommended to use the`BDropdownItemButton` sub-component (which is not announced as a link) instead of`BDropdownItem` (which is presented as a link to the user).
289289

290+
For information on managing ARIA attributes for dropdown triggers, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
291+
290292
###Headers and accessibility
291293

292294
When using`BDropdownHeader` components in the dropdown menu, it is recommended to add an`id` attribute to each of the headers, and then set the`aria-describedby` attribute (set to the`id` value of the associated header) on each following dropdown items under that header. This will provide users of assistive technologies (i.e. sight-impaired users) additional context about the dropdown item:

‎apps/docs/src/docs/components/modal.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,8 @@ If you're looking for replacements for `$bvModal.msgBoxOk` and `$bvModal.msgBoxC
297297
`<BModal>` provides several accessibility features, including auto focus, return focus, keyboard
298298
(tab)_focus containment_, and automated`aria-*` attributes.
299299

300+
For information on managing ARIA attributes for modal triggers, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
301+
300302
**Note:** The animation effect of this component is dependent on the`prefers-reduced-motion` media
301303
query. See the
302304
[reduced motion section of our accessibility documentation](/docs/reference/accessibility) for

‎apps/docs/src/docs/components/offcanvas.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -150,22 +150,19 @@ elements outside of the offcanvas.
150150
###`v-b-toggle` directive
151151

152152
Using the[`v-b-toggle` directive](/docs/directives/BToggle) is the preferred method for_opening_
153-
the offcanvas, as it automatically handles applying the`aria-controls` and`aria-expanded`
154-
accessibility attributes on the trigger element.
153+
the offcanvas, as it automatically handles applying the`aria-controls` attribute and registering
154+
the trigger with the offcanvas. The offcanvas will then manage the`aria-expanded` attribute and
155+
visual state classes on the trigger element to reflect its open/closed state.
155156

156157
The majority of examples on this page use the`v-b-toggle` directive.
157158

158159
###`v-model`
159160

160161
The`v-model` reflects the current visibility state of the offcanvas. While it can be used to control
161162
the visibility state of the offcanvas, it is recommended to use the
162-
[`v-b-toggle` directive](#v-b-toggle-directive) to_show_ the offcanvas for accessibility reasons. If
163-
you do use the`v-model` to show the offcanvas, you should:
163+
[`v-b-toggle` directive](#v-b-toggle-directive) to_show_ the offcanvas for accessibility reasons.
164164

165-
- Provide an`id` prop on the`<BOffcanvas>` component
166-
- Place the`aria-controls="id"` attribute (where`id` is the ID of the offcanvas) on the trigger element
167-
- Set the`aria-expanded` attribute (also on the trigger element) to either the string`'true'` (if the offcanvas is open) or`'false'` (if the offcanvas is closed)
168-
- Provide either a`title` prop or`aria-label` attribute on the`<BOffcanvas>` component for screen readers
165+
For detailed information on managing ARIA attributes when using`v-model`, including examples of programmatic trigger registration and manual ARIA management, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
169166

170167
##Events
171168

‎apps/docs/src/docs/components/popover.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,3 +132,7 @@ props can be used to control what's considered clipping.
132132
These are accessed through the[template ref](https://vuejs.org/guide/essentials/template-refs.html#template-refs)
133133

134134
<<< DEMO ./demo/PopoverExposed.vue
135+
136+
##Accessibility
137+
138+
For information on managing ARIA attributes for popover triggers, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.

‎apps/docs/src/docs/components/toast.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,8 @@ Toasts are intended to be **small interruptions** to your visitors or users, so
7979

8080
If you just need a single simple message to appear along the bottom or top of the user's window, use a fixed position`BAlert` instead.
8181

82+
For information on managing ARIA attributes for toast triggers, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
83+
8284
###Accessibility tips
8385

8486
Typically, toast messages should display one or two-line non-critical messages that**do not**

‎apps/docs/src/docs/components/tooltip.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,3 +150,7 @@ props can be used to control what's considered clipping.
150150
These are accessed through the[template ref](https://vuejs.org/guide/essentials/template-refs.html#template-refs)
151151

152152
<<< DEMO ./demo/TooltipExposed.vue
153+
154+
##Accessibility
155+
156+
For information on managing ARIA attributes for tooltip triggers, see the[ARIA Trigger Registration for Component Visibility](/docs/reference/accessibility#aria-trigger-registration-for-component-visibility) section in the Accessibility reference.
Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
11
---
2-
description:'A light-weight directive for toggling visibility state for collapses and sidebars by ID. It automaticallyhandles theaccessibility attributes onthe triggerelement'
2+
description:'A light-weight directive for toggling visibility state for collapses and sidebars by ID. It automaticallysets thearia-controls attribute and registersthe triggerwith the target component, which then manages aria-expanded and visual state'
33
---
4+
5+
#v-b-toggle Directive
6+
7+
The`v-b-toggle` directive provides an easy way to toggle visibility of components like`BCollapse`,`BOffcanvas`, and`BModal`.
8+
9+
##Accessibility
10+
11+
The directive automatically handles accessibility by:
12+
13+
1. Setting the`aria-controls` attribute to the ID(s) of the target component(s)
14+
2. Registering the trigger element with the target component
15+
3. The target component then manages:
16+
- The`aria-expanded` attribute (set to`'true'` or`'false'` based on visibility)
17+
- The`collapsed` and`not-collapsed` CSS classes
18+
- Event handlers for the click event
19+
20+
This separation ensures that the directive handles the initial connection while each component manages its own state attributes, providing consistent behavior across all show/hide components.
21+
22+
##Usage
23+
24+
See the documentation for individual components:
25+
26+
-[BCollapse](/docs/components/collapse#v-b-toggle-directive)
27+
-[BOffcanvas](/docs/components/offcanvas#v-b-toggle-directive)
28+
-[BModal](/docs/components/modal)

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp