docs(migration): add v-html deprecation to the migration guide (boots…

…trap-vue-next#2403)
dwgray · Dec 1, 2024 · 302b9df · 302b9df
1 parent 64f3534
commit 302b9df
Show file tree

Hide file tree

Showing 5 changed files with 160 additions and 28 deletions.
diff --git a/apps/docs/src/data/components/form.data.ts b/apps/docs/src/data/components/form.data.ts
@@ -59,6 +59,28 @@ export default {
           name: 'first',
           description: "Slot to place options above options provided via the 'options' prop",
         },
+        {
+          name: 'option',
+          description:
+            'Use this slot to have finer control over the content render inside each data item',
+          scope: [
+            {
+              prop: 'value',
+              type: 'any (T)',
+              description: 'The value of the option',
+            },
+            {
+              prop: 'text',
+              type: 'string',
+              description: 'The text of the option',
+            },
+            {
+              prop: 'disabled',
+              type: 'boolean',
+              description: 'Is the option disabled',
+            },
+          ],
+        },
       ],
     },
 

diff --git a/apps/docs/src/data/components/formSelect.data.ts b/apps/docs/src/data/components/formSelect.data.ts
@@ -2,6 +2,29 @@ import type {BvnComponentProps} from 'bootstrap-vue-next'
 import type {ComponentReference, PropertyReference} from '../../types'
 import {buildCommonProps, pick} from '../../utils'
 
+const optionSlot = {
+  name: 'option',
+  description:
+    'Use this slot to have finer control over the content render inside each select item',
+  scope: [
+    {
+      prop: 'value',
+      type: 'any (T)',
+      description: 'The value of the option',
+    },
+    {
+      prop: 'text',
+      type: 'string',
+      description: 'The text of the option',
+    },
+    {
+      prop: 'disabled',
+      type: 'boolean',
+      description: 'Is the option disabled',
+    },
+  ],
+}
+
 export default {
   load: (): ComponentReference[] => [
     {
@@ -82,6 +105,7 @@ export default {
             "Slot to place options or option groups above options provided via the 'options' prop",
           name: 'first',
         },
+        optionSlot,
       ],
     },
     {
@@ -137,6 +161,7 @@ export default {
           name: 'default',
           description: "Slot to place options above options provided via the 'options' prop",
         },
+        optionSlot,
       ],
     },
   ],

diff --git a/apps/docs/src/docs/demo/CheckboxGroupMigration.vue b/apps/docs/src/docs/demo/CheckboxGroupMigration.vue
@@ -0,0 +1,31 @@
+<template>
+  <div>
+    <BFormCheckboxGroup v-model="model" :options="options">
+      <template #option="{value}">
+        {{ (value as Name).first }} <b>{{ (value as Name).last }}</b>
+      </template>
+    </BFormCheckboxGroup>
+    <b>model = </b>{{ model }}
+  </div>
+</template>
+
+<script setup lang="ts">
+import type {CheckboxOption} from 'bootstrap-vue-next'
+import {ref} from 'vue'
+
+interface Name {
+  first: string
+  last: string
+}
+
+const model = ref<CheckboxOption[]>([])
+const options = [
+  {value: {last: 'Brown', first: 'Christina'}},
+  {value: {last: 'Smith', first: 'John'}},
+  {value: {last: 'Doe', first: 'Jane'}},
+  {value: {last: 'Johnson', first: 'Michael'}},
+  {value: {last: 'Williams', first: 'Patricia'}},
+  {value: {last: 'Jones', first: 'Robert'}},
+  {value: {last: 'Garcia', first: 'Linda'}},
+]
+</script>
diff --git a/apps/docs/src/docs/migration-guide.md b/apps/docs/src/docs/migration-guide.md
@@ -77,6 +77,46 @@ The properties and components that are affected by this change are show in the f
 
 <ShowHideProps/>
 
+### v-html
+
+BootstrapVue provided a number of different props named `html` and `*-html` that passed arbitrary data to Vue's `v-html`.
+While a warning was included with each instance of this use, it is not recommeded practice to use `v-html` and obscuring
+that practice further by passing down other props is ill advised in our oppinion. We have instead worked to insure
+that you have the ability to access the same funcdtionality via slots. In many cases slots were already available and
+took priority over the `[*-]html` props and we've filled in the gaps where there wasn't a direct replacement.
+We believe the developer experience in these cases is as good or better than when using props.
+Most importantly any use your code makes of `v-html` will be explicit. See the [Vue Documentation](https://vuejs.org/guide/best-practices/security.html#html-injection) for their take on the `HTML Injection` attack that use of `v-html` exposes.
+
+| Component                      | Prop                  | Replacement Slot |
+| ------------------------------ | --------------------- | ---------------- |
+| `BBreadcrumbItem`              | `html`                | `default`        |
+| `BCard`                        | `footer-html`         | `footer`         |
+| `BCard`                        | `header-html`         | `header`         |
+| `BCardFooter`                  | `html`                | `default`        |
+| `BCardHeader`                  | `html`                | `default`        |
+| `BCarouselSlide`               | `caption-html`        | `caption`        |
+| `BCarouselSlide`               | `text-html`           | `default`        |
+| `BDropdown`                    | `html`                | `default`        |
+| `BInputGroup`                  | `append-html`         | `append`         |
+| `BInputGroup`                  | `prepend-html`        | `prepend`        |
+| `BModal`                       | `cancel-title-html`   | `cancel`         |
+| `BModal`                       | `ok-title`            | `ok`             |
+| `BModal`                       | `title-html`          | `title`          |
+| `BNavItemDropdown`             | `html`                | `default`        |
+| `BPopover` [\*](#popover-html) | `html`                | `default`        |
+| `BProgressBar`                 | `label-html`          | `default`        |
+| `BTable`                       | `empty-filtered-html` | `empty-filtered` |
+| `BTable`                       | `empty-html`          | `empty`          |
+| `BTable`                       | `caption-html`        | `table-caption`  |
+| `BTableSimple`                 | `caption-html`        | `table-caption`  |
+
+<a name="popover-html">BootstrapVue `b-popover` didn't have an `html` attribute, but alpha versions of BSVN did</a>
+
+Each of the options group components `BFormDatalist`, `BFormRadioGroup`, `BFormSelect`, and
+`BFormSelectOptionGroup` implements a scoped slot `option` which takes a `SelectOption<T>` parameter.
+
+<<< DEMO ./demo/CheckboxGroupMigration.vue
+
 ## Grid
 
 BSVN doesn't currently implement the ability to define `breakpoint` names.
@@ -86,11 +126,11 @@ values for `order` on `<BCol>` only provides support for 1 - 5.
 
 ## BAccordian
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ### BAccordianItem
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BAlert
 
@@ -138,7 +178,7 @@ Badges no longer have focus or hover styles for links. See the
 
 ## BBreadcrumb
 
-The `html` prop on `BBreadcrumbItem` is deprecated. Use the default slot instead.
+See the [v-html](#v-html) section for information on deprecation of the `html` prop.
 
 ## BButton
 
@@ -186,6 +226,9 @@ and `BCardTitle` components.
 `body-border-variant` and `body-variant` are not implemented on `BCard` and `border-variant` is not
 implemented on `BCardBody`.
 
+See the [v-html](#v-html) section for information on deprecation of the `footer-html` and `header-html` props on
+`BCard` and the `html` props on `BCardFooter` and `BCardHeader`.
+
 ## BCardImgLazy
 
 This functionality has been replaced by lazy loading on `<BImg>` see [BImg notes](#bimg) for details.
@@ -194,7 +237,9 @@ This functionality has been replaced by lazy loading on `<BImg>` see [BImg notes
 
 The `sliding-start` and `sliding-end` events have been renamed to `slide` and `slid`.
 The `label-indicators` prop has been renamed to `indicators-button-label`.
-<NotYetImplemented>The `label-goto-slide`and `no-animation` props.</NotYetImplemented>
+
+See the [v-html](#v-html) section for information on deprecation of the `caption-html` and `text-html` props
+on `BCarouselSlide`.
 
 ## BCollapse
 
@@ -210,7 +255,7 @@ events on this component.
 
 `$root` instance events `bv::collapse::state` and `bv::toggle::collapse` are deprecrated.
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BDropdown
 
@@ -234,7 +279,9 @@ The `html` prop has been deprecated, use the `button-content`.
 The the boolean argument to control returning focus to the toggle button on the `hide` scoped property of the default slot is deprecated.
 It is less important in BSVN since bootstrap v5 by default doesn't have the focus ring that v4 has.
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
+
+See the [v-html](#v-html) section for information on deprecation of the `html` prop.
 
 <NotYetImplemented>`toggleAttrs`</NotYetImplemented>
 
@@ -300,6 +347,9 @@ property and `update:model-value` events. Bootstrap-vue-next no longer provides
 See the [Vue 3 migration guide](https://v3-migration.vuejs.org/breaking-changes/v-model.html)
 for more info.
 
+See the [v-html](#v-html) section for information on deprecation of the `html` prop on
+`BFormDatalist`, `BFormRadioGroup`, `BFormSelect`, and`BFormSelectOptionGroup`
+
 ## BFormDatePicker
 
 <NotYetImplemented><BLink href="https://github.com/bootstrap-vue-next/bootstrap-vue-next/issues/1860#event-14531487213">See issue #1860</BLink></NotYetImplemented>
@@ -352,6 +402,8 @@ This also has implications on the use of `<BInputGroupText>` - in BootstrapVue,
 sub-components. In BootstrapVueNext, `<BInputGroupText>` should only be used to apply styles to textual elements
 appended or prepended to a group. Using it to group components breaks the automatic append and prepend stylings.
 
+See the [v-html](#v-html) section for information on deprecation of the `append-html` and `prepend-html` props.
+
 ## BInputGroupAddon
 
 Deprectated - See [BInputGroup]
@@ -426,6 +478,8 @@ flex utility classes. See their [documentation](https://getbootstrap.com/docs/5.
 
 ## BModal
 
+See the [v-html](#v-html) section for information on deprecation of the `cancel-title-html`, `ok-title-html`, and `title-html` props.
+
 ### Replacement for Modal Message boxes
 
 [BootstrapVue](https://bootstrap-vue.org/docs/components/modal#modal-message-boxes) provided two methods on the `this.$bvModal` object called `msgBoxOk` and `msgBoxConfirm`.
@@ -446,7 +500,7 @@ Example using `useModalController.confirm` to replace `msgBoxConfirm` (Remember
 The `show` and `confirm` `props` object accepts all of the properties that are defined on
 [BModal](/docs/components/modal#component-reference) excpet for `modelValue`.
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BNav
 
@@ -456,6 +510,8 @@ see [Show and Hide](#show-and-hide) shared properties.
 
 See [`BDropdown`](#bdropdown) for details
 
+See the [v-html](#v-html) section for information on deprecation of the `html` prop.
+
 ## BNavbar
 
 The `type` prop is deprectated. Use the the `v-b-color-mode` directive or `useColorMode` composable instead. Details in our [docs](/components/navbar#color-scheme)
@@ -466,19 +522,25 @@ The `type` prop is deprectated. Use the the `v-b-color-mode` directive or `useCo
 
 ## BOffcanvas
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BPagination
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BPaginationNav
 
 <NotYetImplemented/>
 
 ## BPopover
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
+
+See the [v-html](#v-html) section for information on deprecation of the `html` prop.
+
+## BProgressBar
+
+See the [v-html](#v-html) section for information on deprecation of the `label-html` prop.
 
 ## BSkeleton
 
@@ -488,6 +550,14 @@ see [Show and Hide](#show-and-hide) shared properties.
 [icon documentation](/docs/icons) for details. This functionality can be replicated by using
 `<BplaceholderWrapper>` with your choice of icon replacement in the `loading` slot.
 
+## BTable
+
+See the [v-html](#v-html) section for information on deprecation of the `html` prop.
+
+## BTableSimple
+
+See the [v-html](#v-html) section for information on deprecation of the `caption-html` prop.
+
 ## BTabs
 
 `align` prop now takes values from [`AlignmentJustifyContent`](/docs/types/alignment): `start`, `center`, `end`, `between`, `around`, and `evenly`
@@ -505,8 +575,8 @@ see [Show and Hide](#show-and-hide) shared properties.
 
 ## BToast
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
 
 ## BTooltip
 
-see [Show and Hide](#show-and-hide) shared properties.
+See [Show and Hide](#show-and-hide) shared properties.
diff --git a/apps/docs/src/utils/common-props.ts b/apps/docs/src/utils/common-props.ts
@@ -161,11 +161,6 @@ export const commonProps = () =>
       default: undefined,
       description: 'CSS class (or classes) to apply to the footer',
     },
-    footerHtml: {
-      type: 'string',
-      default: "''",
-      description: 'HTML string content to place in the footer',
-    },
     footerTag: {
       type: 'string',
       default: 'div',
@@ -212,11 +207,6 @@ export const commonProps = () =>
       default: undefined,
       description: 'CSS class (or classes) to apply to the header',
     },
-    headerHtml: {
-      type: 'string',
-      default: "''",
-      description: 'HTML string content to place in the header',
-    },
     headerTag: {
       type: 'string',
       default: 'div',
@@ -232,12 +222,6 @@ export const commonProps = () =>
       default: undefined,
       description: 'Applies one of the Bootstrap theme color variants to the header',
     },
-    htmlField: {
-      type: 'string',
-      default: 'html',
-      description:
-        'Field name in the `options` array that should be used for the html label instead of text field',
-    },
     id: {
       type: 'string',
       default: undefined,