From 3ab5406c6134508ee7b2fdeedbd26b8bffc38c68 Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Fri, 27 Sep 2024 16:13:31 -0700 Subject: [PATCH 1/4] docs(BCollapse): parity pass cleanup --- apps/docs/src/docs/components/collapse.md | 227 +----------------- .../docs/components/demo/CollapseContent.vue | 13 + .../docs/components/demo/CollapseInitial.vue | 10 + .../docs/components/demo/CollapseModel.vue | 20 ++ .../docs/components/demo/CollapseMultiple.vue | 19 ++ .../docs/components/demo/CollapseOverview.vue | 15 ++ .../docs/components/demo/CollapseUsage.vue | 14 ++ apps/docs/src/docs/migration-guide.md | 7 + 8 files changed, 111 insertions(+), 214 deletions(-) create mode 100644 apps/docs/src/docs/components/demo/CollapseContent.vue create mode 100644 apps/docs/src/docs/components/demo/CollapseInitial.vue create mode 100644 apps/docs/src/docs/components/demo/CollapseModel.vue create mode 100644 apps/docs/src/docs/components/demo/CollapseMultiple.vue create mode 100644 apps/docs/src/docs/components/demo/CollapseOverview.vue create mode 100644 apps/docs/src/docs/components/demo/CollapseUsage.vue diff --git a/apps/docs/src/docs/components/collapse.md b/apps/docs/src/docs/components/collapse.md index a5099339e..20e530c5a 100644 --- a/apps/docs/src/docs/components/collapse.md +++ b/apps/docs/src/docs/components/collapse.md @@ -10,97 +10,24 @@ Easily toggle visibility of almost any content on your pages in a vertically collapsing container. Includes support for making accordions. Visibility can be easily toggled with our -[`v-b-toggle` directive](/docs/directives/toggle), or via `v-model`. +[`v-b-toggle` directive](/docs/directives/BToggle), or via [`v-model`](#v-model-support). - - Toggle Collapse - - -

Collapse contents Here

- Toggle Inner Collapse - - Hello! - - - - - +<<< DEMO ./demo/CollapseOverview.vue#template{vue-html} ## Usage Other elements can easily toggle `BCollapse` components using the [`v-b-toggle` directive](/docs/directives/toggle). - - - Toggle Collapse - - Toggle Collapse - - - I am collapsible content! - - - +<<< DEMO ./demo/CollapseUsage.vue#template{vue-html} ## Initial visibility (start expanded) To make the `BCollapse` show initially, set the `v-model` prop: - - Toggle Collapse - - I should start open! - - - - -~~By default, an initially visible collapse will not animate on mount. To enable the collapse -expanding animation on mount (when `visible` or `v-model` is `true`), set the `appear` prop on -`BCollapse`.~~ +<<< DEMO ./demo/CollapseInitial.vue#template{vue-html} ## `v-model` support @@ -112,44 +39,7 @@ are not automatically placed on the trigger button (as is the case when using th directive). In this example we **must control the attributes ourselves** for proper accessibility support. - - - Toggle Collapse - - - I should start open! - - - +<<< DEMO ./demo/CollapseModel.vue ## Trigger multiple collapse elements @@ -158,51 +48,10 @@ multiple target Ids using _modifiers_. You can also pass multiple target Ids via the directive _value_ in BootstrapVueNext. - -
- - Toggle Collapse A and B - - Toggle Collapse A and B - - Toggle Collapse A and B -
- - - I am collapsible content A! - - - I am collapsible content B! - - - +<<< DEMO ./demo/CollapseMultiple.vue#template{vue-html} ## Hiding and showing content in the toggle button based on collapse state -New in v0.8.0 - The `header` slot can be used to create custom toggles for your collapsible content. The `footer` slot is also available and can be used in the same manner. 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. @@ -217,32 +66,7 @@ The following properties are available for the `header` and `footer` slots: | `hide` | Function | When called, will close the collapse | | `id` | String | The ID of the collapsible element | - - - - -
This is data that is being collapsed
- - - +<<< DEMO ./demo/CollapseContent.vue#template{vue-html} ## Accessibility @@ -262,39 +86,14 @@ something other than a button or link (or similar component), you should add the `tabindex="0"` and `role="button"` to allow users of assistive technology to reach your trigger element. -When using accordion mode, make sure you place the trigger elements and `BCollapse` components -inside an element with `role="tablist"` and set `role="tab"` on each trigger element's container in -order to help screen reader users navigate the accordion group. Unfortunately, BootstrapVueNext cannot -apply those roles for you automatically, as it depends on your final document markup. - - - + diff --git a/apps/docs/src/docs/components/demo/CollapseContent.vue b/apps/docs/src/docs/components/demo/CollapseContent.vue new file mode 100644 index 000000000..98332498d --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseContent.vue @@ -0,0 +1,13 @@ + diff --git a/apps/docs/src/docs/components/demo/CollapseInitial.vue b/apps/docs/src/docs/components/demo/CollapseInitial.vue new file mode 100644 index 000000000..776dc8538 --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseInitial.vue @@ -0,0 +1,10 @@ + diff --git a/apps/docs/src/docs/components/demo/CollapseModel.vue b/apps/docs/src/docs/components/demo/CollapseModel.vue new file mode 100644 index 000000000..7e5cd1fd0 --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseModel.vue @@ -0,0 +1,20 @@ + + + diff --git a/apps/docs/src/docs/components/demo/CollapseMultiple.vue b/apps/docs/src/docs/components/demo/CollapseMultiple.vue new file mode 100644 index 000000000..b7d5a16f7 --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseMultiple.vue @@ -0,0 +1,19 @@ + diff --git a/apps/docs/src/docs/components/demo/CollapseOverview.vue b/apps/docs/src/docs/components/demo/CollapseOverview.vue new file mode 100644 index 000000000..fff194758 --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseOverview.vue @@ -0,0 +1,15 @@ + diff --git a/apps/docs/src/docs/components/demo/CollapseUsage.vue b/apps/docs/src/docs/components/demo/CollapseUsage.vue new file mode 100644 index 000000000..baab9578e --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseUsage.vue @@ -0,0 +1,14 @@ + diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index b7f1897b3..349d6ea30 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -146,6 +146,13 @@ The `sliding-start` and `sliding-end` events have been renamed to `slide` and `s The `label-indicators` prop has been renamed to `indicators-button-label`. The `label-goto-slide`and `no-animation` props. +## BCollapse + +In `bootstrap-vue`/`bootstrap4`, accordians are implemented via `BCollapse` in `boostrap-vue-nexst`/`bootstrap5` +accordians are first class citizens, so please use the [`BAccordian`](/docs/components/accordian) instead. + +The `appear` prop. + ## BForm Bootstrap 5 has dropped form-specific layout classes for the grid system. See the From 4525d5ec2703bc96ca7464ec2e9ee9cf4ca1bf7d Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Fri, 27 Sep 2024 17:01:21 -0700 Subject: [PATCH 2/4] docs(BCollapse): Fill out component reference --- .../docs/src/data/components/collapse.data.ts | 109 ++++++++++++------ apps/docs/src/docs/components/collapse.md | 3 + apps/docs/src/docs/migration-guide.md | 11 +- 3 files changed, 88 insertions(+), 35 deletions(-) diff --git a/apps/docs/src/data/components/collapse.data.ts b/apps/docs/src/data/components/collapse.data.ts index fe686813e..74f6f7ddf 100644 --- a/apps/docs/src/data/components/collapse.data.ts +++ b/apps/docs/src/data/components/collapse.data.ts @@ -1,5 +1,34 @@ import type {BvnComponentProps} from 'bootstrap-vue-next' -import type {ComponentReference, PropertyReference} from '../../types' +import type {ComponentReference, PropertyReference, SlotScopeReference} from '../../types' +import {buildCommonProps, pick} from '../../utils' + +const sharedSlots: SlotScopeReference[] = [ + { + prop: 'hide', + type: '() => void', + description: "Closes the collapse and fires the 'hide' event", + }, + { + prop: 'id', + type: 'string', + description: 'The id of the collapse element', + }, + { + prop: 'show', + type: '() => void', + description: "Shows the collapse and fires the 'show' event", + }, + { + prop: 'toggle', + type: '() => void', + description: "Toggles the collapse and fires the 'hide' or 'show' event, as appropriate", + }, + { + prop: 'visible', + type: '() => void', + description: 'Visible state of the collapse. `true` if the collapse is visible', + }, +] export default { load: (): ComponentReference[] => [ @@ -12,94 +41,108 @@ export default { type: 'boolean', default: false, }, - id: { - type: 'string', - default: undefined, - }, isNav: { type: 'boolean', default: false, + description: + 'When set, signifies that the collapse is part of a navbar, enabling certain features for navbar support', }, modelValue: { type: 'boolean', default: false, + description: 'Controls the visibility of the collapse', }, skipAnimation: { type: 'boolean', default: false, - }, - tag: { - type: 'string', - default: 'div', + description: 'When set, disables the animation', }, toggle: { type: 'boolean', default: false, + description: + "When set, and prop 'visible' is false on mount, will animate from closed to open on initial mount", }, visible: { type: 'boolean', default: false, + description: "When 'true', expands the collapse", }, + ...pick(buildCommonProps(), ['id', 'tag']), } satisfies Record, }, emits: [ { + event: 'update:model-value', + description: 'Used to update the v-model', args: [ { - arg: 'update:model-value', - description: '', + arg: 'value', type: 'boolean', + description: 'Will be true if the collapse is visible', }, ], - description: '', - event: 'update:model-value', }, { - args: [], - description: '', - event: 'show', + event: 'hide', + description: 'Emitted when collapse has started to close', + args: [ + { + arg: 'value', + type: 'BvTriggerableEvent', + description: 'The event object', + }, + ], }, { + event: 'hidden', + description: 'Emitted when collapse has finished closing', args: [], - description: '', - event: 'shown', }, { + event: 'hide-prevented', + description: 'Emitted when the Collapse tried to close, but was prevented from doing so.', args: [], - description: '', - event: 'show-prevented', }, { + event: 'show', + description: 'Emitted when collapse has started to open', args: [], - description: '', - event: 'hide', }, { - args: [], - description: '', - event: 'hidden', + event: 'shown', + description: 'Emitted when collapse has finished opening', + args: [ + { + arg: 'value', + type: 'BvTriggerableEvent', + description: 'The event object', + }, + ], }, { + event: 'show-prevented', + description: 'Emitted when the Collapse tried to open, but was prevented from doing so.', args: [], - description: '', - event: 'hide-prevented', }, ], slots: [ { - description: '', name: 'default', - scope: [], + description: 'The content shown and hidden by the collapse', + scope: sharedSlots, }, { - description: '', name: 'footer', - scope: [], + description: + 'Used to create custom toggles for your collapsible content. Placed directly below the content', + scope: sharedSlots, }, { - description: '', name: 'header', - scope: [], + description: + 'Used to create custom toggles for your collapsible content. Placed directly above the content', + scope: sharedSlots, }, ], }, diff --git a/apps/docs/src/docs/components/collapse.md b/apps/docs/src/docs/components/collapse.md index 20e530c5a..e37fc0684 100644 --- a/apps/docs/src/docs/components/collapse.md +++ b/apps/docs/src/docs/components/collapse.md @@ -39,6 +39,9 @@ are not automatically placed on the trigger button (as is the case when using th directive). In this example we **must control the attributes ourselves** for proper accessibility support. +By default, an initially visible collapse will not animate on mount. To enable the collapse expanding animation on mount, +set the `toggle` prop on `` and leave the `visible` prop as false. + <<< DEMO ./demo/CollapseModel.vue ## Trigger multiple collapse elements diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index 349d6ea30..6d73383cb 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -148,8 +148,15 @@ The `label-indicators` prop has been renamed to `indicators-button-label`. ## BCollapse -In `bootstrap-vue`/`bootstrap4`, accordians are implemented via `BCollapse` in `boostrap-vue-nexst`/`bootstrap5` -accordians are first class citizens, so please use the [`BAccordian`](/docs/components/accordian) instead. +The `accordian` prop is deprecated: In `bootstrap-vue`/`bootstrap4`, accordians are implemented via `BCollapse`. +In `boostrap-vue-nexst`/`bootstrap5` accordians are first class citizens, so please use the +[`BAccordian`](/docs/components/accordian) instead. + +The prop `toggle` has replaced the prop `appear` with slightly different semantics. In order to create a +collapse that is closed and transitions to open on the initial mount, set `visible` to false and `toggle` to true. + +The `close` scoped slot element has been replaced by `hide` for consistency with the other props and +events on this component. The `appear` prop. From e0ed3ed7b3778f315dc4d7a6cb705adc62273c4c Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Fri, 27 Sep 2024 17:35:23 -0700 Subject: [PATCH 3/4] docs(BCollapse): Document expose --- .../docs/src/data/components/collapse.data.ts | 2 +- apps/docs/src/docs/components/collapse.md | 13 +++++++++++ .../docs/components/demo/CollapseExpose.vue | 23 +++++++++++++++++++ apps/docs/src/docs/migration-guide.md | 2 ++ 4 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 apps/docs/src/docs/components/demo/CollapseExpose.vue diff --git a/apps/docs/src/data/components/collapse.data.ts b/apps/docs/src/data/components/collapse.data.ts index 74f6f7ddf..1cc94dd37 100644 --- a/apps/docs/src/data/components/collapse.data.ts +++ b/apps/docs/src/data/components/collapse.data.ts @@ -6,7 +6,7 @@ const sharedSlots: SlotScopeReference[] = [ { prop: 'hide', type: '() => void', - description: "Closes the collapse and fires the 'hide' event", + description: "Hides the collapse and fires the 'hide' event", }, { prop: 'id', diff --git a/apps/docs/src/docs/components/collapse.md b/apps/docs/src/docs/components/collapse.md index e37fc0684..d3564880e 100644 --- a/apps/docs/src/docs/components/collapse.md +++ b/apps/docs/src/docs/components/collapse.md @@ -71,6 +71,19 @@ The following properties are available for the `header` and `footer` slots: <<< DEMO ./demo/CollapseContent.vue#template{vue-html} +## Exposed functions + +`BCollapse` exposes several functions and properties that allow manipulation and examination of the state of the components. +These are accessed through the [template ref](https://vuejs.org/guide/essentials/template-refs.html#template-refs) + +- hide: Hides the collapse and fires the `hide` event +- show: Shows the collapse and fires the `show` event +- toggle: Toggles the collapse and fires the `hide` or `show` event, as appropriate +- isNav: The value of the `isNav` prop of the collapse +- visible: The visible state of the collapse + +<<< DEMO ./demo/CollapseExpose.vue + ## Accessibility The `v-b-toggle` directive will automatically add the ARIA attributes `aria-controls` and diff --git a/apps/docs/src/docs/components/demo/CollapseExpose.vue b/apps/docs/src/docs/components/demo/CollapseExpose.vue new file mode 100644 index 000000000..a000f509b --- /dev/null +++ b/apps/docs/src/docs/components/demo/CollapseExpose.vue @@ -0,0 +1,23 @@ + + + diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md index 6d73383cb..fd324b366 100644 --- a/apps/docs/src/docs/migration-guide.md +++ b/apps/docs/src/docs/migration-guide.md @@ -158,6 +158,8 @@ collapse that is closed and transitions to open on the initial mount, set `visib The `close` scoped slot element has been replaced by `hide` for consistency with the other props and events on this component. +`$root` instance events `bv::collapse::state` and `bv::toggle::collapse` are deprecrated. + The `appear` prop. ## BForm From c8347623c9f1b4077b6868e3f52e80ed7bf01cda Mon Sep 17 00:00:00 2001 From: "David W. Gray" Date: Sat, 28 Sep 2024 16:18:36 -0700 Subject: [PATCH 4/4] doc(BCollapse): document provide/inject --- apps/docs/src/docs/components/collapse.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/apps/docs/src/docs/components/collapse.md b/apps/docs/src/docs/components/collapse.md index d3564880e..7ac49f8b2 100644 --- a/apps/docs/src/docs/components/collapse.md +++ b/apps/docs/src/docs/components/collapse.md @@ -53,13 +53,14 @@ You can also pass multiple target Ids via the directive _value_ in BootstrapVueN <<< DEMO ./demo/CollapseMultiple.vue#template{vue-html} -## Hiding and showing content in the toggle button based on collapse state +## Slots -The `header` slot can be used to create custom toggles for your collapsible content. The `footer` slot is also available and can be used in the same manner. +The `header` and `footer` slots can be used to create custom toggles for your collapsible content. The default slot is +used for the content to be hidden or shown. 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. -The following properties are available for the `header` and `footer` slots: +The following properties are available for the `header` and `footer` and `default` slots: | Property | Type | Description | | --------- | -------- | ------------------------------------- | @@ -69,6 +70,9 @@ The following properties are available for the `header` and `footer` slots: | `hide` | Function | When called, will close the collapse | | `id` | String | The ID of the collapsible element | +`BCollapse` also [provides](https://vuejs.org/guide/components/provide-inject.html) the above variables +to its children as well as the value of the `isNav` prop. + <<< DEMO ./demo/CollapseContent.vue#template{vue-html} ## Exposed functions