From 9198ed5474db8aed2b01c6c0ec0f756baceb19af Mon Sep 17 00:00:00 2001
From: Enrico Sacchetti <enrico@theetrain.ca>
Date: Tue, 13 Dec 2022 13:22:17 -0500
Subject: [PATCH] feat!: dispatch "change" event in `Pagination`, rename
 "change" to "update" in `Select` (#1497)

Closes #1491

* feat(pagination): dispatch "change" event when interacting with previous/next buttons, page/page size dropdowns

* breaking(select): rename dispatched "change" event to "update"

* breaking(select): forward `change` event to `Select`
---
 COMPONENT_INDEX.md                      | 14 ++++++-----
 docs/src/COMPONENT_API.json             | 18 +++++++++++---
 docs/src/components/ComponentApi.svelte | 32 +++++++++++++++++++++----
 docs/src/pages/components/Select.svx    |  8 +++----
 src/Pagination/Pagination.svelte        | 11 ++++++++-
 src/Select/Select.svelte                |  6 +++--
 tests/Pagination.test.svelte            |  3 +++
 types/Pagination/Pagination.svelte.d.ts |  4 +++-
 types/Select/Select.svelte.d.ts         |  3 ++-
 9 files changed, 76 insertions(+), 23 deletions(-)

diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
index 35693a94..eb6335b8 100644
--- a/COMPONENT_INDEX.md
+++ b/COMPONENT_INDEX.md
@@ -2682,11 +2682,12 @@ None.
 
 ### Events
 
-| Event name             | Type       | Detail                                           |
-| :--------------------- | :--------- | :----------------------------------------------- |
-| update                 | dispatched | <code>{ pageSize: number; page: number; }</code> |
-| click:button--previous | dispatched | <code>{ page: number; }</code>                   |
-| click:button--next     | dispatched | <code>{ page: number; }</code>                   |
+| Event name             | Type       | Detail                                            |
+| :--------------------- | :--------- | :------------------------------------------------ |
+| change                 | dispatched | <code>{ page?: number; pageSize?: number }</code> |
+| click:button--previous | dispatched | <code>{ page: number; }</code>                    |
+| click:button--next     | dispatched | <code>{ page: number; }</code>                    |
+| update                 | dispatched | <code>{ pageSize: number; page: number; }</code>  |
 
 ## `PaginationNav`
 
@@ -3179,7 +3180,8 @@ None.
 
 | Event name | Type       | Detail                            |
 | :--------- | :--------- | :-------------------------------- |
-| change     | dispatched | <code>string &#124; number</code> |
+| update     | dispatched | <code>string &#124; number</code> |
+| change     | forwarded  | --                                |
 | input      | forwarded  | --                                |
 | focus      | forwarded  | --                                |
 | blur       | forwarded  | --                                |
diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json
index b870e435..fe1f293f 100644
--- a/docs/src/COMPONENT_API.json
+++ b/docs/src/COMPONENT_API.json
@@ -8405,8 +8405,9 @@
       "events": [
         {
           "type": "dispatched",
-          "name": "update",
-          "detail": "{ pageSize: number; page: number; }"
+          "name": "change",
+          "detail": "{ page?: number; pageSize?: number }",
+          "description": "Dispatched after any user interaction"
         },
         {
           "type": "dispatched",
@@ -8417,6 +8418,11 @@
           "type": "dispatched",
           "name": "click:button--next",
           "detail": "{ page: number; }"
+        },
+        {
+          "type": "dispatched",
+          "name": "update",
+          "detail": "{ pageSize: number; page: number; }"
         }
       ],
       "typedefs": [],
@@ -10252,7 +10258,13 @@
         }
       ],
       "events": [
-        { "type": "dispatched", "name": "change", "detail": "string | number" },
+        {
+          "type": "dispatched",
+          "name": "update",
+          "detail": "string | number",
+          "description": "The selected value."
+        },
+        { "type": "forwarded", "name": "change", "element": "select" },
         { "type": "forwarded", "name": "input", "element": "select" },
         { "type": "forwarded", "name": "focus", "element": "select" },
         { "type": "forwarded", "name": "blur", "element": "select" }
diff --git a/docs/src/components/ComponentApi.svelte b/docs/src/components/ComponentApi.svelte
index 8bce3d17..a60230a0 100644
--- a/docs/src/components/ComponentApi.svelte
+++ b/docs/src/components/ComponentApi.svelte
@@ -168,11 +168,33 @@
 <h2 id="dispatched-events">Dispatched events</h2>
 
 {#if dispatched_events.length > 0}
-  <UnorderedList class="my-layout-01-03">
-    {#each dispatched_events as event (event.name)}
-      <ListItem>on:{event.name}</ListItem>
-    {/each}
-  </UnorderedList>
+  {@const hasDescription = dispatched_events.find((el) => el.description)}
+  <StructuredList flush>
+    <StructuredListHead>
+      <StructuredListRow>
+        <StructuredListCell>Event name</StructuredListCell>
+        <StructuredListCell><code>event.details</code> type</StructuredListCell>
+        {#if hasDescription}
+          <StructuredListCell>Description</StructuredListCell>
+        {/if}
+      </StructuredListRow>
+    </StructuredListHead>
+    <StructuredListBody>
+      {#each dispatched_events as event (event.name)}
+        <StructuredListRow>
+          <StructuredListCell>
+            <strong>on:{event.name}</strong>
+          </StructuredListCell>
+          <StructuredListCell>
+            <code>{event.detail}</code>
+          </StructuredListCell>
+          <StructuredListCell>
+            {event.description ?? ""}
+          </StructuredListCell>
+        </StructuredListRow>
+      {/each}
+    </StructuredListBody>
+  </StructuredList>
 {:else}
   <p class="my-layout-01-03">No dispatched events.</p>
 {/if}
diff --git a/docs/src/pages/components/Select.svx b/docs/src/pages/components/Select.svx
index e7bb5e90..3a619e29 100644
--- a/docs/src/pages/components/Select.svx
+++ b/docs/src/pages/components/Select.svx
@@ -11,7 +11,7 @@ components: ["Select", "SelectItem", "SelectItemGroup", "SelectSkeleton"]
 
 If the `selected` prop is not set, the value of the first `SelectItem` will be used as the default value.
 
-<Select labelText="Carbon theme" on:change={e => console.log("value", e.detail)}>
+<Select labelText="Carbon theme" on:change={e => console.log("value", e.target.value)}>
   <SelectItem value="white" />
   <SelectItem value="g10" />
   <SelectItem value="g80" />
@@ -23,7 +23,7 @@ If the `selected` prop is not set, the value of the first `SelectItem` will be u
 
 Use the `text` prop on `SelectItem` to customize the display value.
 
-<Select labelText="Carbon theme" on:change={e => console.log("value", e.detail)}>
+<Select labelText="Carbon theme" on:change={e => console.log("value", e.target.value)}>
   <SelectItem value="white" text="White" />
   <SelectItem value="g10" text="Gray 10" />
   <SelectItem value="g80" text="Gray 80" />
@@ -35,7 +35,7 @@ Use the `text` prop on `SelectItem` to customize the display value.
 
 Use the `selected` prop to specify an initial value.
 
-<Select labelText="Carbon theme" selected="g10" on:change={e => console.log("value", e.detail)}>
+<Select labelText="Carbon theme" selected="g10" on:change={e => console.log("value", e.target.value)}>
   <SelectItem value="white" text="White" />
   <SelectItem value="g10" text="Gray 10" />
   <SelectItem value="g80" text="Gray 80" />
@@ -160,4 +160,4 @@ The `selected` prop is reactive and supports two-way binding.
 
 ## Skeleton (hidden label)
 
-<SelectSkeleton hideLabel />
\ No newline at end of file
+<SelectSkeleton hideLabel />
diff --git a/src/Pagination/Pagination.svelte b/src/Pagination/Pagination.svelte
index 3f972b10..b307e078 100644
--- a/src/Pagination/Pagination.svelte
+++ b/src/Pagination/Pagination.svelte
@@ -1,8 +1,9 @@
 <script>
   /**
-   * @event {{ pageSize: number; page: number; }} update
+   * @event {{ page?: number; pageSize?: number }} change - Dispatched after any user interaction
    * @event {{ page: number; }} click:button--previous
    * @event {{ page: number; }} click:button--next
+   * @event {{ pageSize: number; page: number; }} update
    */
 
   /** Specify the current page index */
@@ -109,6 +110,9 @@
         hideLabel
         noLabel
         inline
+        on:change="{() => {
+          dispatch('change', { pageSize });
+        }}"
         bind:selected="{pageSize}"
       >
         {#each pageSizes as size, i (size)}
@@ -136,6 +140,9 @@
         labelText="Page number, of {totalPages} pages"
         inline
         hideLabel
+        on:change="{() => {
+          dispatch('change', { page });
+        }}"
         bind:selected="{page}"
       >
         {#each selectItems as size, i (size)}
@@ -161,6 +168,7 @@
       on:click="{() => {
         page--;
         dispatch('click:button--previous', { page });
+        dispatch('change', { page });
       }}"
     />
     <Button
@@ -176,6 +184,7 @@
       on:click="{() => {
         page++;
         dispatch('click:button--next', { page });
+        dispatch('change', { page });
       }}"
     />
   </div>
diff --git a/src/Select/Select.svelte b/src/Select/Select.svelte
index dfaf8861..1199ed6f 100644
--- a/src/Select/Select.svelte
+++ b/src/Select/Select.svelte
@@ -1,6 +1,6 @@
 <script>
   /**
-   * @event {string | number} change
+   * @event {string | number} update The selected value.
    */
 
   /**
@@ -114,7 +114,7 @@
     selected = $selectedValue;
 
     if (prevSelected !== undefined && selected !== prevSelected) {
-      dispatch("change", $selectedValue);
+      dispatch("update", $selectedValue);
     }
 
     prevSelected = selected;
@@ -163,6 +163,7 @@
             class:bx--select-input--sm="{size === 'sm'}"
             class:bx--select-input--xl="{size === 'xl'}"
             on:change="{handleChange}"
+            on:change
             on:input
             on:focus
             on:blur
@@ -206,6 +207,7 @@
           class:bx--select-input--sm="{size === 'sm'}"
           class:bx--select-input--xl="{size === 'xl'}"
           on:change="{handleChange}"
+          on:change
           on:input
           on:focus
           on:blur
diff --git a/tests/Pagination.test.svelte b/tests/Pagination.test.svelte
index e1e29e89..3183f8cf 100644
--- a/tests/Pagination.test.svelte
+++ b/tests/Pagination.test.svelte
@@ -5,6 +5,9 @@
 <Pagination
   totalItems="{102}"
   pageSizes="{[10, 15, 20]}"
+  on:change="{(e) => {
+    console.log(e.detail); // { pageSize?: number, page?: number }
+  }}"
   on:update="{(e) => {
     console.log(e.detail); // { pageSize: number; page: number; }
   }}"
diff --git a/types/Pagination/Pagination.svelte.d.ts b/types/Pagination/Pagination.svelte.d.ts
index d88ab7d2..11b7675a 100644
--- a/types/Pagination/Pagination.svelte.d.ts
+++ b/types/Pagination/Pagination.svelte.d.ts
@@ -103,9 +103,11 @@ export interface PaginationProps
 export default class Pagination extends SvelteComponentTyped<
   PaginationProps,
   {
-    update: CustomEvent<{ pageSize: number; page: number }>;
+    /** Dispatched after any user interaction */
+    change: CustomEvent<{ page?: number; pageSize?: number }>;
     ["click:button--previous"]: CustomEvent<{ page: number }>;
     ["click:button--next"]: CustomEvent<{ page: number }>;
+    update: CustomEvent<{ pageSize: number; page: number }>;
   },
   {}
 > {}
diff --git a/types/Select/Select.svelte.d.ts b/types/Select/Select.svelte.d.ts
index 6c5a57ff..db1736f8 100644
--- a/types/Select/Select.svelte.d.ts
+++ b/types/Select/Select.svelte.d.ts
@@ -109,7 +109,8 @@ export interface SelectProps
 export default class Select extends SvelteComponentTyped<
   SelectProps,
   {
-    change: CustomEvent<string | number>;
+    /** The selected value. */ update: CustomEvent<string | number>;
+    change: WindowEventMap["change"];
     input: WindowEventMap["input"];
     focus: WindowEventMap["focus"];
     blur: WindowEventMap["blur"];