From 1627fa023f3cdc61ecb890575737c294def08415 Mon Sep 17 00:00:00 2001
From: Enrico Sacchetti <enrico@theetrain.ca>
Date: Mon, 12 Dec 2022 15:21:54 -0500
Subject: [PATCH] docs: add dispatched event details

Brought in part by sveld 0.18
---
 docs/src/COMPONENT_API.json             | 10 ++++++--
 docs/src/components/ComponentApi.svelte | 32 +++++++++++++++++++++----
 src/Select/Select.svelte                |  2 +-
 types/Pagination/Pagination.svelte.d.ts |  1 +
 types/Select/Select.svelte.d.ts         |  2 +-
 5 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json
index e93bf3b6..fe1f293f 100644
--- a/docs/src/COMPONENT_API.json
+++ b/docs/src/COMPONENT_API.json
@@ -8406,7 +8406,8 @@
         {
           "type": "dispatched",
           "name": "change",
-          "detail": "{ page?: number; pageSize?: number }"
+          "detail": "{ page?: number; pageSize?: number }",
+          "description": "Dispatched after any user interaction"
         },
         {
           "type": "dispatched",
@@ -10257,7 +10258,12 @@
         }
       ],
       "events": [
-        { "type": "dispatched", "name": "update", "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" },
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/src/Select/Select.svelte b/src/Select/Select.svelte
index 10e70809..1199ed6f 100644
--- a/src/Select/Select.svelte
+++ b/src/Select/Select.svelte
@@ -1,6 +1,6 @@
 <script>
   /**
-   * @event {string | number} update
+   * @event {string | number} update The selected value.
    */
 
   /**
diff --git a/types/Pagination/Pagination.svelte.d.ts b/types/Pagination/Pagination.svelte.d.ts
index c733d3d2..11b7675a 100644
--- a/types/Pagination/Pagination.svelte.d.ts
+++ b/types/Pagination/Pagination.svelte.d.ts
@@ -103,6 +103,7 @@ export interface PaginationProps
 export default class Pagination extends SvelteComponentTyped<
   PaginationProps,
   {
+    /** Dispatched after any user interaction */
     change: CustomEvent<{ page?: number; pageSize?: number }>;
     ["click:button--previous"]: CustomEvent<{ page: number }>;
     ["click:button--next"]: CustomEvent<{ page: number }>;
diff --git a/types/Select/Select.svelte.d.ts b/types/Select/Select.svelte.d.ts
index eca400f3..db1736f8 100644
--- a/types/Select/Select.svelte.d.ts
+++ b/types/Select/Select.svelte.d.ts
@@ -109,7 +109,7 @@ export interface SelectProps
 export default class Select extends SvelteComponentTyped<
   SelectProps,
   {
-    update: CustomEvent<string | number>;
+    /** The selected value. */ update: CustomEvent<string | number>;
     change: WindowEventMap["change"];
     input: WindowEventMap["input"];
     focus: WindowEventMap["focus"];