docs(tabs): add better examples

docs/src/pages/components/Tabs.svx

@@ -33,13 +33,19 @@ components: ["Tabs", "Tab", "TabContent", "TabsSkeleton"]
   </div>
 </Tabs>
 
+### Reactive example
+
+Use the `selected` prop to bind the current tab index.
+
+<FileSource src="/framed/Tabs/TabsReactive" />
+
 ### Re-rendering tabs
 
+In the example below, tabs are rendered using the `#each` block. However, the Tabs component can lose track of the current index if the number of rendered tabs changes.
+
 Use the [`#key` block](https://svelte.dev/docs#key) to dynamically update tab items or content.
 
-The example below shows tabs and the bound `selected` index being programmatically updated.
-
-<FileSource src="/framed/Tabs/TabsDynamic" />
+<FileSource src="/framed/Tabs/TabsReactiveEach" />
 
 ### Skeleton
 

docs/src/pages/framed/Tabs/TabsDynamic.svelte

@@ -1,12 +1,5 @@
 <script>
-  import {
-    ButtonSet,
-    Button,
-    Tabs,
-    Tab,
-    TabContent,
-  } from "carbon-components-svelte";
-  import { afterUpdate } from "svelte";
+  import { Button, Tabs, Tab, TabContent } from "carbon-components-svelte";
 
   let tabs = [
     { title: "blue", visible: true },
@@ -14,22 +7,18 @@
     { title: "red", visible: true },
   ];
 
-  let selected = 0;
-
-  afterUpdate(() => {
-    // if the selected tab is not visible
-    // reset the index to the next visible tab
-    if (tabs[selected].visible === false) {
-      selected = tabs.filter((tab) => tab.visible).length - 1;
+  // this mutates "tabs"
+  // for an immutable example, see "/framed/Tabs/TabsDynamicImmutable"
+  const toggleTab = (title) => {
+    for (const i in tabs) {
+      if (tabs[i].title === title) {
+        tabs[i].visible = !tabs[i].visible;
+      }
     }
-  });
-</script>
+  };
 
-<style>
-  div {
-    margin: var(--cds-layout-02) 0;
-  }
-</style>
+  let selected = 0;
+</script>
 
 {#key tabs}
   <Tabs bind:selected>
@@ -50,34 +39,6 @@
 
 <p>Selected index: {selected}</p>
 
-<div>
-  <ButtonSet>
-    {#each tabs as { title } (title)}
-      <Button
-        kind="tertiary"
-        size="small"
-        on:click="{() => {
-          tabs = tabs.map((tab) => ({
-            ...tab,
-            visible: tab.title === title ? !tab.visible : tab.visible,
-          }));
-        }}"
-      >
-        Toggle
-        {title}
-        tab
-      </Button>
-    {/each}
-  </ButtonSet>
-</div>
-
-<div>
-  <Button
-    size="small"
-    on:click="{() => {
-      selected = 1;
-    }}"
-  >
-    Set selected to 1
-  </Button>
-</div>
+{#each tabs as { title } (title)}
+  <Button on:click="{() => toggleTab(title)}">Toggle {title} tab</Button>
+{/each}

docs/src/pages/framed/Tabs/TabsReactive.svelte

@@ -0,0 +1,36 @@
+<script>
+  import { Button, Tabs, Tab, TabContent } from "carbon-components-svelte";
+
+  let selected = 0;
+</script>
+
+<style>
+  div {
+    margin: var(--cds-layout-02) 0;
+  }
+</style>
+
+<Tabs bind:selected>
+  <Tab label="Tab label 1" />
+  <Tab label="Tab label 2" />
+  <Tab label="Tab label 3" />
+  <div slot="content">
+    <TabContent>Content 1</TabContent>
+    <TabContent>Content 2</TabContent>
+    <TabContent>Content 3</TabContent>
+  </div>
+</Tabs>
+
+<div>
+  <Button
+    size="small"
+    disabled="{selected === 1}"
+    on:click="{() => {
+      selected = 1;
+    }}"
+  >
+    Set selected index to 1
+  </Button>
+</div>
+
+<div>Selected index: {selected}</div>

docs/src/pages/framed/Tabs/TabsReactiveEach.svelte

@@ -0,0 +1,61 @@
+<script>
+  import { Button, Tabs, Tab, TabContent } from "carbon-components-svelte";
+  import { afterUpdate } from "svelte";
+
+  let selected = 0;
+  let update = false;
+
+  $: items = update ? [1, 2, 3, 4, 5, 6] : [1, 2, 3];
+
+  afterUpdate(() => {
+    // reset the selected index of tab no longer exists
+    if (items[selected] === undefined) {
+      selected = 0;
+    }
+  });
+</script>
+
+<style>
+  div {
+    margin: var(--cds-layout-02) 0;
+  }
+</style>
+
+{#key items}
+  <Tabs bind:selected>
+    {#each items as item}
+      <Tab label="Tab label {item}" />
+    {/each}
+    <div slot="content">
+      {#each items as item}
+        <TabContent>Content {item}</TabContent>
+      {/each}
+    </div>
+  </Tabs>
+{/key}
+
+<div>
+  <Button
+    size="small"
+    kind="tertiary"
+    on:click="{() => {
+      update = !update;
+    }}"
+  >
+    Update items
+  </Button>
+</div>
+
+<div>
+  <Button
+    size="small"
+    disabled="{selected === 1}"
+    on:click="{() => {
+      selected = 1;
+    }}"
+  >
+    Set selected index to 1
+  </Button>
+</div>
+
+<div>Selected index: {selected}</div>