fix(*): deprecate and update boolean props [KHCP-9548] (#1793)

* fix(kinput): deprecate hasError prop in favor of error [KHCP-9548] * fix(kdropdown): rename selectionMenu prop [KHCP-9548] * fix(kdropdown): deprecate isDangerous prop [KHCP-9548] * fix(kdropdown): rename danger prop [KHCP-9548] * chore(deps): bump @kong/icons [KHCP-9548] * docs(input): minor fix [KHCP-9548] * fix(*): add console.warn to deprecated props [KHCP-9548] * fix(sandbox): add deprecated props to sandbox [KHCP-9548] * docs(contributing): add toto items [KHCP-9548] * fix(*): address PR feedback [KHCP-9548]
Kong · Oct 26, 2023 · 9b97cf8 · 9b97cf8
1 parent 221adcb
commit 9b97cf8
Show file tree

Hide file tree

Showing 15 changed files with 130 additions and 64 deletions.
diff --git a/docs/components/dropdown.md b/docs/components/dropdown.md
@@ -143,17 +143,17 @@ Text to display on hover if dropdown is disabled.
 />
 ```
 
-### isSelectionMenu
+### selectionMenu
 
 Defaults to `false`.
 
 Use this prop when a visual indication of the currently selected menu item is needed. 
 
-By default the dropdown has no notion of "selection". When `isSelectionMenu` is `true`, `selected` state is handled automatically when clicking a KDropdownItem if used in conjunction with the `items` prop. Each item should have a `label` and a `value`. To keep track of changes in your host app you can utilize [`@change` event](#events).
+By default the dropdown has no notion of "selection". When `selectionMenu` is `true`, `selected` state is handled automatically when clicking a KDropdownItem if used in conjunction with the `items` prop. Each item should have a `label` and a `value`. To keep track of changes in your host app you can utilize [`@change` event](#events).
 
 <ClientOnly>
   <KDropdown
-    is-selection-menu
+    selection-menu
     :items="selectionMenuItems"
     trigger-text="Select region"
     @change="handleSelectionMenuUpdate"
@@ -164,7 +164,7 @@ By default the dropdown has no notion of "selection". When `isSelectionMenu` is
 ```vue
 <template>
   <KDropdown
-    is-selection-menu
+    selection-menu
     :items="[{ label: 'US (United States)', value: 'us' }, 
       { label: 'FR (France)', value: 'fr' }]"
     trigger-text="Select region"
@@ -186,7 +186,7 @@ If using the [`items` slot](#items-1), you will have access to the `handleSelect
 
 <ClientOnly>
   <KDropdown
-    is-selection-menu
+    selection-menu
     trigger-text="Select region (with items slot)"
     @change="handleSelectionMenuUpdate"
     show-caret
@@ -206,7 +206,7 @@ If using the [`items` slot](#items-1), you will have access to the `handleSelect
 ```vue
 <template>
   <KDropdown
-    is-selection-menu
+    selection-menu
     trigger-text="Select region (with items slot)"
     @change="handleSelectionMenuUpdate"
     show-caret
@@ -265,7 +265,7 @@ Slot props:
   - Function that triggers dropdown close.
 - `handleSelection`
   - type: `Function`
-  - Function that lets KDropdown track selected item when `isSelectionMenu` is `true`.
+  - Function that lets KDropdown track selected item when `selectionMenu` is `true`.
 
 KDropdownItem takes care of icon color, size and spacing as long as you use icons provided by [@kong/icons](https://github.com/Kong/icons) package.
 
@@ -341,13 +341,13 @@ KDropdown generates a KDropdownItem for each object in the `items` prop array. A
 
 ### Props
 
-| Prop          | Description                                                                                                                                                                                                                                                                                                                                         |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `item`        | The properties the link is built from, it expects a `label` and optionally a `to` or `value` (when `isSelectionMenu` is `true`). If `to` is `typeof object`, the item will be rendered as a `<router-link>`. Otherwise, if `to` is `typeof string`, it will be rendered as an `<a>` element with the value of `to` applied to the `href` attribute. |
-| `disabled`    | A boolean (defaults to `false`), indicating whether or not to disable the item.                                                                                                                                                                                                                                                                     |
-| `selected`    | A boolean (defaults to `false`), indicating whether or not the item is selected when the `isSelectionMenu` prop is `true`.                                                                                                                                                                                                                          |
-| `hasDivider`  | A boolean (defaults to `false`), indicating whether or not the item should have a divider bar displayed above it.                                                                                                                                                                                                                                   |
-| `isDangerous` | A boolean (defaults to `false`), indicating whether or not to apply danger styles (text color is red).                                                                                                                                                                                                                                              |
+| Prop         | Description                                                                                                                                                                                                                                                                                                                                       |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `item`       | The properties the link is built from, it expects a `label` and optionally a `to` or `value` (when `selectionMenu` is `true`). If `to` is `typeof object`, the item will be rendered as a `<router-link>`. Otherwise, if `to` is `typeof string`, it will be rendered as an `<a>` element with the value of `to` applied to the `href` attribute. |
+| `disabled`   | A boolean (defaults to `false`), indicating whether or not to disable the item.                                                                                                                                                                                                                                                                   |
+| `selected`   | A boolean (defaults to `false`), indicating whether or not the item is selected when the `selectionMenu` prop is `true`.                                                                                                                                                                                                                          |
+| `hasDivider` | A boolean (defaults to `false`), indicating whether or not the item should have a divider bar displayed above it.                                                                                                                                                                                                                                 |
+| `danger`     | A boolean (defaults to `false`), indicating whether or not to apply danger styles (text color is red).                                                                                                                                                                                                                                            |
 
 <ClientOnly>
   <KDropdown trigger-text="All kinds of dropdown items">
@@ -402,7 +402,7 @@ KDropdown generates a KDropdownItem for each object in the `items` prop array. A
       </KDropdownItem>
       <KDropdownItem
         has-divider
-        is-dangerous
+        danger
         @click="clickHandler"
       >
         Danger button
@@ -464,7 +464,7 @@ KDropdown generates a KDropdownItem for each object in the `items` prop array. A
       </KDropdownItem>
       <KDropdownItem
         has-divider
-        is-dangerous
+        danger
         @click="clickHandler"
       >
         Danger button
@@ -511,7 +511,7 @@ You can bind event handlers to `@click` event just like you would normally do wi
 
 #### change
 
-Fires when items are clicked when `isSelectionMenu` is `true`. Returns the selected menu item object or `null`.
+Fires when items are clicked when `selectionMenu` is `true`. Returns the selected menu item object or `null`.
 
 #### toggleDropdown
 

diff --git a/docs/components/input.md b/docs/components/input.md
@@ -75,26 +75,26 @@ String to be displayed as help text.
 <KInput help="I can help with that." placeholder="Need help?" />
 ```
 
-If [`hasError`](#haserror) is true, the `help` prop text will be styled as error message.
+If [`error`](#error) is true, the `help` prop text will be styled as error message.
 
-<KInput has-error help="I can help with that." />
+<KInput error help="I can help with that." />
 
 ```html
-<KInput has-error help="I can help with that." />
+<KInput error help="I can help with that." />
 ```
 
-### hasError
+### error
 
 Boolean to indicate whether the element is in an error state and should apply error styling. Defaults to `false`.
 
 ### errorMessage
 
-String to be displayed as an error message if `hasError` prop is `true`. This prop will supersede the `help` prop if both have a value and `hasError` is `true`.
+String to be displayed as an error message if `error` prop is `true`. This prop will supersede the `help` prop if both have a value and `error` is `true`.
 
-<KInput has-error error-message="Service name should not contain '_'" help="Service name can be anything with only a few exceptions." />
+<KInput error error-message="Service name should not contain '_'" help="Service name can be anything with only a few exceptions." />
 
 ```html
-<KInput has-error error-message="Service name should not contain '_'" help="Service name can be anything with only a few exceptions." />
+<KInput error error-message="Service name should not contain '_'" help="Service name can be anything with only a few exceptions." />
 ```
 
 ### characterLimit
@@ -132,7 +132,6 @@ You can pass any input attribute and it will get properly bound to the element.
 <KInput class="vertical-spacing" disabled model-value="disabled"/>
 <KInput class="vertical-spacing" readonly model-value="readonly"/>
 <KInput class="vertical-spacing" type="search" model-value="search"/>
-<KInput class="vertical-spacing" type="email" model-value="[email protected]"/>
 
 ```html
 <KInput placeholder="placeholder" />
@@ -142,7 +141,6 @@ You can pass any input attribute and it will get properly bound to the element.
 <KInput disabled model-value="disabled"/>
 <KInput read-only model-value="read-only"/>
 <KInput type="search" model-value="search"/>
-<KInput type="email" model-value="[email protected]"/>
 ```
 
 ### required

diff --git a/docs/components/table.md b/docs/components/table.md
@@ -1039,7 +1039,7 @@ This example uses the [`KDropdown`](/components/dropdown) component as the slot
           </KDropdownItem>
           <KDropdownItem
             has-divider
-            is-dangerous
+            danger
             @click="clickHandler('Delete clicked!')"
           >
             Delete
@@ -1084,7 +1084,7 @@ This example uses the [`KDropdown`](/components/dropdown) component as the slot
           </KDropdownItem>
           <KDropdownItem
             has-divider
-            is-dangerous
+            danger
             @click="clickHandler('Delete clicked!')"
           >
             Delete

diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md
@@ -188,6 +188,8 @@ In order to prevent component styles from leaking out into the consuming applica
 
 2. All component styles must be wrapped in a unique wrapper class so that styles do not leak out into the consuming application.
 
+  TODO: update class naming guidelines
+
     The class name should follow the syntax `.k-{component-name}-*`
 
    This is a good practice even if you go with option one outlined above.
@@ -206,6 +208,12 @@ Kongponent styles should **never** use relative font units; specifically, do not
 
 We cannot control the `html` base font size and therefore these relative units are not predictable within a host application. Use `px` (pixels) or a similar unit instead.
 
+### Code best practices
+
+#### Prop naming
+
+TODO: wip
+
 ## Testing your component
 
 You're free to play around with your component on the local instance of the docs site by running `yarn docs:dev`; however, you may also want to test your local changes in a consuming application.

diff --git a/docs/guide/migrating-to-version-9.md b/docs/guide/migrating-to-version-9.md
@@ -125,11 +125,12 @@ Component has been renamed to `KDropdown`
 #### Props
 
 * `label` prop has been deprecated in favor of the new `trigger-text` prop (usage is the same)
-* `appearance` prop has been changed in favor of the `isSelectionMenu` prop for the selection menu functionality. `appearance` now controls the underlying `KButton` `appearance` prop (note that default `appearance` for component when `isSelectionMenu` is `true` changed from `tertiary` to `primary`)
+* `appearance` prop has been changed in favor of the `selectionMenu` prop for the selection menu functionality. `appearance` now controls the underlying `KButton` `appearance` prop (note that default `appearance` for component when `selectionMenu` is `true` changed from `tertiary` to `primary`)
 * `buttonAppearance` prop has been removed in favor of `appearance`, still controlling the `KButton` `appearance` prop
 * `testMode` prop has been removed
 * `icon` prop is removed (TODO: [beta])
 * `caretColor` prop is removed
+* `isDangerous` `KDropdownItem` prop has been deprecated in favor of `danger`
 
 #### Slots
 
@@ -156,9 +157,7 @@ Component has been renamed to `KDropdown`
 
 * `form-control` class has been removed
 * `over-char-limit` class has been removed
-* `has-error` class has been removed
 * `help` class has been changed to `help-text`
-* `input-error` class has been changed to `has-error`
 
 #### Constants, Types & Interfaces
 
@@ -173,6 +172,7 @@ Component has been renamed to `KDropdown`
 * `iconPosition` prop has been removed
 * `testMode` prop has been removed
 * `help` property was removed from `labelAttributes` prop (TODO: after KLabel is reskinned)
+* `hasError` prop has been deprecated in favor of `error`
 
 #### Slots
 

diff --git a/sandbox/pages/SandboxDropdown.vue b/sandbox/pages/SandboxDropdown.vue
@@ -28,11 +28,11 @@
       />
     </SandboxSectionComponent>
     <SandboxSectionComponent
-      title="isSelectionMenu (replacement for `appearance` prop)"
+      title="selectionMenu (replacement for `appearance` prop)"
     >
       <KDropdown
-        is-selection-menu
         :items="selectionMenuItems"
+        selection-menu
         trigger-text="Selection menu"
         @change="handleSelectionMenuUpdate"
       />
@@ -93,7 +93,7 @@
           trigger-text="Show caret"
         />
         <KDropdown
-          is-selection-menu
+          selection-menu
           show-caret
           trigger-text="Selection menu with caret"
           @change="handleSelectionMenuUpdate"
@@ -206,8 +206,8 @@
             Disabled external link
           </KDropdownItem>
           <KDropdownItem
+            danger
             has-divider
-            is-dangerous
             @click="handleItemClick"
           >
             <TrashIcon />
@@ -290,7 +290,7 @@
     </SandboxSectionComponent>
     <SandboxSectionComponent
       description="The old KDropdownMenu component that utilizes the KDropdown under the hood still works as expected."
-      title="Deprecated KDropdownMenu"
+      title="KDropdownMenu (deprecated)"
     >
       <KDropdownMenu
         trigger-text="KDropdownMenu"
@@ -328,6 +328,20 @@
         </template>
       </KDropdownMenu>
     </SandboxSectionComponent>
+    <SandboxSectionComponent
+      title="KDropdownItem isDangerous prop (deprecated)"
+    >
+      <KDropdown trigger-text="Deprecated KDropdownItem prop">
+        <template #items>
+          <KDropdownItem
+            is-dangerous
+            @click="handleItemClick"
+          >
+            I am dangerous
+          </KDropdownItem>
+        </template>
+      </KDropdown>
+    </SandboxSectionComponent>
   </div>
 </template>
 

diff --git a/sandbox/pages/SandboxInput.vue b/sandbox/pages/SandboxInput.vue
@@ -28,8 +28,8 @@
         <KToggle v-slot="{isToggled, toggle}">
           <KInput
             class="full-width-input"
-            :has-error="isToggled.value"
-            help="This is help text. When hasError is true, this text will be red."
+            :error="isToggled.value"
+            help="This is help text. When error is true, this text will be red."
             label="Label"
           />
           <KButton
@@ -41,9 +41,9 @@
         </KToggle>
       </div>
     </SandboxSectionComponent>
-    <SandboxSectionComponent title="hasError">
+    <SandboxSectionComponent title="error">
       <KInput
-        has-error
+        error
         label="Label"
       />
     </SandboxSectionComponent>
@@ -54,9 +54,9 @@
         <KToggle v-slot="{isToggled, toggle}">
           <KInput
             class="full-width-input"
+            :error="isToggled.value"
             error-message="This is errorMessage."
-            :has-error="isToggled.value"
-            help="This is help text. When hasError is true, this text will be red. When hasError is true and errorMessage is set, this text will be replaced by the errorMessage."
+            help="This is help text. When error is true, this text will be red. When error is true and errorMessage is set, this text will be replaced by the errorMessage."
             label="Label"
           />
           <KButton
@@ -77,9 +77,9 @@
           <KInput
             :character-limit="67"
             class="full-width-input"
+            :error="isToggled.value"
             error-message="This is errorMessage. When character limit is exceeded, this text will be replaced by character limit error message."
-            :has-error="isToggled.value"
-            help="This is help text. When hasError is true, this text will be red. When hasError is true and errorMessage is set, this text will be replaced by the errorMessage. When character limit is exceeded, errorMessage text will be replaced by character limit error message."
+            help="This is help text. When error is true, this text will be red. When error is true and errorMessage is set, this text will be replaced by the errorMessage. When character limit is exceeded, errorMessage text will be replaced by character limit error message."
             label="Label"
             model-value="Type in 1 more character to see the character limit error message: "
           />
@@ -165,6 +165,8 @@
         </template>
       </KInput>
     </SandboxSectionComponent>
+
+    <!-- Examples -->
     <SandboxTitleComponent
       is-subtitle
       title="Examples"
@@ -182,6 +184,20 @@
         </KButton>
       </div>
     </SandboxSectionComponent>
+
+    <!-- Legacy -->
+    <SandboxTitleComponent
+      is-subtitle
+      title="Legacy"
+    />
+    <SandboxSectionComponent
+      title="hasError prop (deprecated)"
+    >
+      <KInput
+        has-error
+        label="Label"
+      />
+    </SandboxSectionComponent>
   </div>
 </template>
 

diff --git a/sandbox/pages/SandboxTable.vue b/sandbox/pages/SandboxTable.vue
@@ -26,8 +26,8 @@
             Edit
           </KDropdownItem>
           <KDropdownItem
+            danger
             has-divider
-            is-dangerous
           >
             Delete
           </KDropdownItem>

diff --git a/src/components/KDropdown/KDropdown.cy.ts b/src/components/KDropdown/KDropdown.cy.ts
@@ -76,10 +76,10 @@ describe('KDropdown', () => {
     cy.get('.k-tooltip').should('contain.text', tooltipText)
   })
 
-  it('renders correctly when isSelectionMenu', () => {
+  it('renders correctly when selectionMenu', () => {
     mount(KDropdown, {
       props: {
-        isSelectionMenu: true,
+        selectionMenu: true,
         items: selectionMenuItems,
       },
     })