feat(modal): support 3-button Modal, ComposedModal (#724)

* feat(modal): support 3-button modal #528, #472

* fix(modal): "supercede" --> "supersede"

* test(modal): test secondaryButtons prop, updated click:button--secondary custom event

* docs(modal): add multiple secondary button example for ComposedModal

* docs(modal): rename example

* fix(modal): do not render secondary button if secondaryButtonText is falsy

* docs(composed-modal): add button to re-open modal

COMPONENT_INDEX.md

@@ -2224,7 +2224,7 @@ None.
 ### Props
 
 | Prop name                  | Kind             | Reactive | Type                                                | Default value                                    | Description                                                                                             |
-| :------------------------- | :--------------- | :------- | :---------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
+| :------------------------- | :--------------- | :------- | :-------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
 | ref                        | <code>let</code> | Yes      | <code>null &#124; HTMLDivElement</code>             | <code>null</code>                                | Obtain a reference to the top-level HTML element                                                        |
 | open                       | <code>let</code> | Yes      | <code>boolean</code>                                | <code>false</code>                               | Set to `true` to open the modal                                                                         |
 | size                       | <code>let</code> | No       | <code>"xs" &#124; "sm" &#124; "lg"</code>           | --                                               | Set the size of the modal                                                                               |
@@ -2241,6 +2241,7 @@ None.
 | primaryButtonDisabled      | <code>let</code> | No       | <code>boolean</code>                                | <code>false</code>                               | Set to `true` to disable the primary button                                                             |
 | shouldSubmitOnEnter        | <code>let</code> | No       | <code>boolean</code>                                | <code>true</code>                                | Set to `true` for the primary button to be triggered when pressing "Enter"                              |
 | secondaryButtonText        | <code>let</code> | No       | <code>string</code>                                 | <code>""</code>                                  | Specify the secondary button text                                                                       |
+| secondaryButtons           | <code>let</code> | No       | <code>[{ text: string; }, { text: string; }]</code> | <code>[]</code>                                  | 2-tuple prop to render two secondary buttons for a 3 button modal<br />supersedes `secondaryButtonText` |
 | selectorPrimaryFocus       | <code>let</code> | No       | <code>string</code>                                 | <code>"[data-modal-primary-focus]"</code>        | Specify a selector to be focused when opening the modal                                                 |
 | preventCloseOnClickOutside | <code>let</code> | No       | <code>boolean</code>                                | <code>false</code>                               | Set to `true` to prevent the modal from closing when clicking outside                                   |
 | id                         | <code>let</code> | No       | <code>string</code>                                 | <code>"ccs-" + Math.random().toString(36)</code> | Set an id for the top-level element                                                                     |
@@ -2258,13 +2259,13 @@ None.
 | Event name              | Type       | Detail                          |
 | :---------------------- | :--------- | :------------------------------ |
 | transitionend           | dispatched | <code>{ open: boolean; }</code> |
+| click:button--secondary | dispatched | <code>{ text: string; }</code>  |
 | keydown                 | forwarded  | --                              |
 | click                   | forwarded  | --                              |
 | mouseover               | forwarded  | --                              |
 | mouseenter              | forwarded  | --                              |
 | mouseleave              | forwarded  | --                              |
 | submit                  | dispatched | --                              |
-| click:button--secondary | dispatched | --                              |
 | close                   | dispatched | --                              |
 | open                    | dispatched | --                              |
 
@@ -2292,11 +2293,12 @@ None.
 ### Props
 
 | Prop name             | Kind             | Reactive | Type                                                | Default value      | Description                                                                                             |
-| :-------------------- | :--------------- | :------- | :------------------- | ------------------ | ------------------------------------------- |
+| :-------------------- | :--------------- | :------- | :-------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
 | primaryButtonText     | <code>let</code> | No       | <code>string</code>                                 | <code>""</code>    | Specify the primary button text                                                                         |
 | primaryButtonDisabled | <code>let</code> | No       | <code>boolean</code>                                | <code>false</code> | Set to `true` to disable the primary button                                                             |
 | primaryClass          | <code>let</code> | No       | <code>string</code>                                 | --                 | Specify a class for the primary button                                                                  |
 | secondaryButtonText   | <code>let</code> | No       | <code>string</code>                                 | <code>""</code>    | Specify the secondary button text                                                                       |
+| secondaryButtons      | <code>let</code> | No       | <code>[{ text: string; }, { text: string; }]</code> | <code>[]</code>    | 2-tuple prop to render two secondary buttons for a 3 button modal<br />supersedes `secondaryButtonText` |
 | secondaryClass        | <code>let</code> | No       | <code>string</code>                                 | --                 | Specify a class for the secondary button                                                                |
 | danger                | <code>let</code> | No       | <code>boolean</code>                                | <code>false</code> | Set to `true` to use the danger variant                                                                 |
 
@@ -2308,7 +2310,9 @@ None.
 
 ### Events
 
-None.
+| Event name              | Type       | Detail                         |
+| :---------------------- | :--------- | :----------------------------- |
+| click:button--secondary | dispatched | <code>{ text: string; }</code> |
 
 ## `ModalHeader`
 

docs/src/COMPONENT_API.json

@@ -5397,6 +5397,16 @@
           "constant": false,
           "reactive": false
         },
+        {
+          "name": "secondaryButtons",
+          "kind": "let",
+          "description": "2-tuple prop to render two secondary buttons for a 3 button modal\nsupersedes `secondaryButtonText`",
+          "type": "[{ text: string; }, { text: string; }]",
+          "value": "[]",
+          "isFunction": false,
+          "constant": false,
+          "reactive": false
+        },
         {
           "name": "selectorPrimaryFocus",
           "kind": "let",
@@ -5459,13 +5469,17 @@
           "name": "transitionend",
           "detail": "{ open: boolean; }"
         },
+        {
+          "type": "dispatched",
+          "name": "click:button--secondary",
+          "detail": "{ text: string; }"
+        },
         { "type": "forwarded", "name": "keydown", "element": "div" },
         { "type": "forwarded", "name": "click", "element": "div" },
         { "type": "forwarded", "name": "mouseover", "element": "div" },
         { "type": "forwarded", "name": "mouseenter", "element": "div" },
         { "type": "forwarded", "name": "mouseleave", "element": "div" },
         { "type": "dispatched", "name": "submit" },
-        { "type": "dispatched", "name": "click:button--secondary" },
         { "type": "dispatched", "name": "close" },
         { "type": "dispatched", "name": "open" }
       ],
@@ -5545,6 +5559,16 @@
           "constant": false,
           "reactive": false
         },
+        {
+          "name": "secondaryButtons",
+          "kind": "let",
+          "description": "2-tuple prop to render two secondary buttons for a 3 button modal\nsupersedes `secondaryButtonText`",
+          "type": "[{ text: string; }, { text: string; }]",
+          "value": "[]",
+          "isFunction": false,
+          "constant": false,
+          "reactive": false
+        },
         {
           "name": "secondaryClass",
           "kind": "let",
@@ -5566,7 +5590,13 @@
         }
       ],
       "slots": [{ "name": "__default__", "default": true, "slot_props": "{}" }],
-      "events": [],
+      "events": [
+        {
+          "type": "dispatched",
+          "name": "click:button--secondary",
+          "detail": "{ text: string; }"
+        }
+      ],
       "typedefs": [],
       "rest_props": { "type": "Element", "name": "div" }
     },

docs/src/pages/components/ComposedModal.svx

@@ -9,3 +9,9 @@ components: ["ComposedModal", "ModalHeader", "ModalBody", "ModalFooter"]
 ### Composed modal
 
 <FileSource src="/framed/Modal/ComposedModal" />
+
+### Multiple secondary buttons
+
+Use the `secondaryButtons` prop in `ModalFooter` to render two secondary buttons for a "3-button modal". The prop is a 2-tuple type that supersedes `secondaryButtonText`.
+
+<FileSource src="/framed/Modal/3ButtonComposedModal" />

docs/src/pages/components/Modal.svx

@@ -14,6 +14,12 @@
 
 <FileSource src="/framed/Modal/PassiveModal" />
 
+### Multiple secondary buttons
+
+Use the `secondaryButtons` prop to render two secondary buttons for a "3-button modal". The prop is a 2-tuple type that supersedes `secondaryButtonText`.
+
+<FileSource src="/framed/Modal/3ButtonModal" />
+
 ### Extra-small size
 
 <FileSource src="/framed/Modal/ModalExtraSmall" />

docs/src/pages/framed/Modal/3ButtonComposedModal.svelte

@@ -0,0 +1,31 @@
+<script>
+  import {
+    Button,
+    ComposedModal,
+    ModalHeader,
+    ModalBody,
+    ModalFooter,
+    Checkbox,
+  } from "carbon-components-svelte";
+
+  let open = true;
+  let checked = false;
+</script>
+
+<Button on:click="{() => (open = true)}">Review changes</Button>
+
+<ComposedModal bind:open on:submit="{() => (open = false)}">
+  <ModalHeader label="Changes" title="Confirm changes" />
+  <ModalBody hasForm>
+    <Checkbox labelText="I have reviewed the changes" bind:checked />
+  </ModalBody>
+  <ModalFooter
+    primaryButtonText="Proceed"
+    primaryButtonDisabled="{!checked}"
+    secondaryButtons="{[{ text: 'Cancel' }, { text: 'Review' }]}"
+    on:click:button--secondary="{({ detail }) => {
+      if (detail.text === 'Cancel') open = false;
+      if (detail.text === 'Review') console.log('Review');
+    }}"
+  />
+</ComposedModal>

docs/src/pages/framed/Modal/3ButtonModal.svelte

@@ -0,0 +1,23 @@
+<script>
+  import { Button, Modal } from "carbon-components-svelte";
+
+  let open = false;
+</script>
+
+<Button on:click="{() => (open = true)}">Create database</Button>
+
+<Modal
+  bind:open
+  modalHeading="Create database"
+  primaryButtonText="Confirm"
+  secondaryButtons="{[{ text: 'Cancel' }, { text: 'Edit' }]}"
+  on:click:button--secondary="{({ detail }) => {
+    if (detail.text === 'Cancel') open = false;
+    if (detail.text === 'Edit') console.log('Edit');
+  }}"
+  on:open
+  on:close
+  on:submit
+>
+  <p>Create a new Cloudant database in the US South region.</p>
+</Modal>

src/ComposedModal/ModalFooter.svelte

@@ -1,4 +1,8 @@
 <script>
+  /**
+   * @event {{ text: string; }} click:button--secondary
+   */
+
   /** Specify the primary button text */
   export let primaryButtonText = "";
 
@@ -14,6 +18,13 @@
   /** Specify the secondary button text */
   export let secondaryButtonText = "";
 
+  /**
+   * 2-tuple prop to render two secondary buttons for a 3 button modal
+   * supersedes `secondaryButtonText`
+   * @type {[{ text: string; }, { text: string; }]}
+   */
+  export let secondaryButtons = [];
+
   /**
    * Specify a class for the secondary button
    * @type {string}
@@ -23,15 +34,38 @@
   /** Set to `true` to use the danger variant */
   export let danger = false;
 
-  import { getContext } from "svelte";
+  import { getContext, createEventDispatcher } from "svelte";
   import Button from "../Button/Button.svelte";
 
+  const dispatch = createEventDispatcher();
   const { closeModal, submit } = getContext("ComposedModal");
 </script>
 
-<div class:bx--modal-footer="{true}" {...$$restProps}>
-  {#if secondaryButtonText}
-    <Button kind="secondary" class="{secondaryClass}" on:click="{closeModal}">
+<div
+  class:bx--modal-footer="{true}"
+  class:bx--modal-footer--three-button="{secondaryButtons.length === 2}"
+  {...$$restProps}
+>
+  {#if secondaryButtons.length > 0}
+    {#each secondaryButtons as button}
+      <Button
+        kind="secondary"
+        on:click="{() => {
+          dispatch('click:button--secondary', { text: button.text });
+        }}"
+      >
+        {button.text}
+      </Button>
+    {/each}
+  {:else if secondaryButtonText}
+    <Button
+      kind="secondary"
+      class="{secondaryClass}"
+      on:click="{() => {
+        closeModal();
+        dispatch('click:button--secondary', { text: secondaryButtonText });
+      }}"
+    >
       {secondaryButtonText}
     </Button>
   {/if}

src/Modal/Modal.svelte

@@ -1,6 +1,7 @@
 <script>
   /**
    * @event {{ open: boolean; }} transitionend
+   * @event {{ text: string; }} click:button--secondary
    */
 
   /**
@@ -60,6 +61,13 @@
   /** Specify the secondary button text */
   export let secondaryButtonText = "";
 
+  /**
+   * 2-tuple prop to render two secondary buttons for a 3 button modal
+   * supersedes `secondaryButtonText`
+   * @type {[{ text: string; }, { text: string; }]}
+   */
+  export let secondaryButtons = [];
+
   /** Specify a selector to be focused when opening the modal */
   export let selectorPrimaryFocus = "[data-modal-primary-focus]";
 
@@ -257,15 +265,33 @@
       <div class:bx--modal-content--overflow-indicator="{true}"></div>
     {/if}
     {#if !passiveModal}
-      <div class:bx--modal-footer="{true}">
+      <div
+        class:bx--modal-footer="{true}"
+        class:bx--modal-footer--three-button="{secondaryButtons.length === 2}"
+      >
+        {#if secondaryButtons.length > 0}
+          {#each secondaryButtons as button}
             <Button
               kind="secondary"
               on:click="{() => {
-            dispatch('click:button--secondary');
+                dispatch('click:button--secondary', { text: button.text });
+              }}"
+            >
+              {button.text}
+            </Button>
+          {/each}
+        {:else if secondaryButtonText}
+          <Button
+            kind="secondary"
+            on:click="{() => {
+              dispatch('click:button--secondary', {
+                text: secondaryButtonText,
+              });
             }}"
           >
             {secondaryButtonText}
           </Button>
+        {/if}
         <Button
           kind="{danger ? 'danger' : 'primary'}"
           disabled="{primaryButtonDisabled}"

tests/ComposedModal.test.svelte

@@ -15,5 +15,10 @@
   <ModalBody hasForm>
     <Checkbox labelText="I have reviewed the changes" bind:checked />
   </ModalBody>
-  <ModalFooter primaryButtonText="Proceed" primaryButtonDisabled="{!checked}" />
+  <ModalFooter
+    primaryButtonText="Proceed"
+    primaryButtonDisabled="{!checked}"
+    secondaryButtons="{[{ text: 'Cancel' }, { text: 'Duplicate' }]}"
+    on:click:button--secondary="{({ detail }) => {}}"
+  />
 </ComposedModal>

tests/Modal.test.svelte

@@ -10,8 +10,9 @@
   bind:open
   modalHeading="Create database"
   primaryButtonText="Confirm"
+  secondaryButtons="{[{ text: 'Cancel' }, { text: 'Duplicate' }]}"
   secondaryButtonText="Cancel"
-  on:click:button--secondary="{() => (open = false)}"
+  on:click:button--secondary="{({ detail }) => (open = false)}"
   on:open
   on:close
   on:submit

types/ComposedModal/ModalFooter.d.ts

@@ -26,6 +26,13 @@ export interface ModalFooterProps
    */
   secondaryButtonText?: string;
 
+  /**
+   * 2-tuple prop to render two secondary buttons for a 3 button modal
+   * supersedes `secondaryButtonText`
+   * @default []
+   */
+  secondaryButtons?: [{ text: string }, { text: string }];
+
   /**
    * Specify a class for the secondary button
    */
@@ -40,6 +47,6 @@ export interface ModalFooterProps
 
 export default class ModalFooter extends SvelteComponentTyped<
   ModalFooterProps,
-  {},
+  { ["click:button--secondary"]: CustomEvent<{ text: string }> },
   { default: {} }
 > {}

types/Modal/Modal.d.ts

@@ -89,6 +89,13 @@ export interface ModalProps
    */
   secondaryButtonText?: string;
 
+  /**
+   * 2-tuple prop to render two secondary buttons for a 3 button modal
+   * supersedes `secondaryButtonText`
+   * @default []
+   */
+  secondaryButtons?: [{ text: string }, { text: string }];
+
   /**
    * Specify a selector to be focused when opening the modal
    * @default "[data-modal-primary-focus]"
@@ -118,13 +125,13 @@ export default class Modal extends SvelteComponentTyped<
   ModalProps,
   {
     transitionend: CustomEvent<{ open: boolean }>;
+    ["click:button--secondary"]: CustomEvent<{ text: string }>;
     keydown: WindowEventMap["keydown"];
     click: WindowEventMap["click"];
     mouseover: WindowEventMap["mouseover"];
     mouseenter: WindowEventMap["mouseenter"];
     mouseleave: WindowEventMap["mouseleave"];
     submit: CustomEvent<any>;
-    ["click:button--secondary"]: CustomEvent<any>;
     close: CustomEvent<any>;
     open: CustomEvent<any>;
   },