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

@@ -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  | --                                |

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" }

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}

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" />

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>

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

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; }
   }}"

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 }>;
   },
   {}
 > {}

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"];