feat(selectable-tile): add SelectableTileGroup component

metonym · metonym · commit 6ba0fdf97fcc · 2025-11-29T09:09:53.000-08:00
Adds a new `SelectableTileGroup` component that manages multiple
`SelectableTile` components using Svelte context API.
diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md
@@ -1,6 +1,6 @@
 # Component Index
 
-> 166 components exported from carbon-components-svelte@0.93.0.
+> 167 components exported from carbon-components-svelte@0.93.0.
 
 ## Components
 
@@ -112,6 +112,7 @@
 - [`SelectItemGroup`](#selectitemgroup)
 - [`SelectSkeleton`](#selectskeleton)
 - [`SelectableTile`](#selectabletile)
+- [`SelectableTileGroup`](#selectabletilegroup)
 - [`SideNav`](#sidenav)
 - [`SideNavDivider`](#sidenavdivider)
 - [`SideNavItems`](#sidenavitems)
@@ -3320,6 +3321,30 @@ None.
 | mouseleave | forwarded  | --                  | --          |
 | keydown    | forwarded  | --                  | --          |
 
+## `SelectableTileGroup`
+
+### Props
+
+| Prop name | Required | Kind             | Reactive | Type                                 | Default value          | Description                                      |
+| :-------- | :------- | :--------------- | :------- | ------------------------------------ | ---------------------- | ------------------------------------------------ |
+| selected  | No       | <code>let</code> | Yes      | <code>T[]</code>                     | <code>[]</code>        | Specify the selected tile values                 |
+| disabled  | No       | <code>let</code> | No       | <code>boolean</code>                 | <code>false</code>     | Set to `true` to disable the tile group          |
+| name      | No       | <code>let</code> | No       | <code>string &#124; undefined</code> | <code>undefined</code> | Specify a name attribute for the checkbox inputs |
+| legend    | No       | <code>let</code> | No       | <code>string</code>                  | <code>""</code>        | Specify the legend text                          |
+
+### Slots
+
+| Slot name | Default | Props                               | Fallback |
+| :-------- | :------ | :---------------------------------- | :------- |
+| --        | Yes     | <code>Record<string, never> </code> | --       |
+
+### Events
+
+| Event name | Type       | Detail         | Description |
+| :--------- | :--------- | :------------- | :---------- |
+| select     | dispatched | <code>T</code> | --          |
+| deselect   | dispatched | <code>T</code> | --          |
+
 ## `SideNav`
 
 ### Props
diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json
@@ -1,5 +1,5 @@
 {
-  "total": 166,
+  "total": 167,
   "components": [
     {
       "moduleName": "Accordion",
@@ -13651,6 +13651,120 @@
       },
       "contexts": []
     },
+    {
+      "moduleName": "SelectableTileGroup",
+      "filePath": "src/Tile/SelectableTileGroup.svelte",
+      "props": [
+        {
+          "name": "selected",
+          "kind": "let",
+          "description": "Specify the selected tile values",
+          "type": "T[]",
+          "value": "[]",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": true
+        },
+        {
+          "name": "disabled",
+          "kind": "let",
+          "description": "Set to `true` to disable the tile group",
+          "type": "boolean",
+          "value": "false",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "name",
+          "kind": "let",
+          "description": "Specify a name attribute for the checkbox inputs",
+          "type": "string | undefined",
+          "value": "undefined",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "legend",
+          "kind": "let",
+          "description": "Specify the legend text",
+          "type": "string",
+          "value": "\"\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        }
+      ],
+      "moduleExports": [],
+      "slots": [
+        {
+          "name": null,
+          "default": true,
+          "slot_props": "Record<string, never>"
+        }
+      ],
+      "events": [
+        {
+          "type": "dispatched",
+          "name": "select",
+          "detail": "T"
+        },
+        {
+          "type": "dispatched",
+          "name": "deselect",
+          "detail": "T"
+        }
+      ],
+      "typedefs": [],
+      "generics": [
+        "T",
+        "T extends string = string"
+      ],
+      "rest_props": {
+        "type": "Element",
+        "name": "fieldset"
+      },
+      "contexts": [
+        {
+          "key": "SelectableTileGroup",
+          "typeName": "SelectableTileGroupContext",
+          "properties": [
+            {
+              "name": "selectedValues",
+              "type": "import(\"svelte/store\").Writable<T[]>",
+              "description": "",
+              "optional": false
+            },
+            {
+              "name": "groupName",
+              "type": "any",
+              "optional": false
+            },
+            {
+              "name": "add",
+              "type": "(data: { selected: boolean; value: T }) => void",
+              "description": "",
+              "optional": false
+            },
+            {
+              "name": "update",
+              "type": "(data: { value: T; selected: boolean }) => void",
+              "description": "",
+              "optional": false
+            }
+          ]
+        }
+      ]
+    },
     {
       "moduleName": "SideNav",
       "filePath": "src/UIShell/SideNav.svelte",
diff --git a/src/Tile/SelectableTile.svelte b/src/Tile/SelectableTile.svelte
@@ -37,12 +37,26 @@
   /** Obtain a reference to the input HTML element */
   export let ref = null;
 
-  import { createEventDispatcher } from "svelte";
+  import { createEventDispatcher, getContext } from "svelte";
+  import { readable } from "svelte/store";
   import CheckmarkFilled from "../icons/CheckmarkFilled.svelte";
 
   const dispatch = createEventDispatcher();
 
-  $: if (!disabled) dispatch(selected ? "select" : "deselect", id);
+  const ctx = getContext("SelectableTileGroup");
+  const hasGroup = ctx !== undefined;
+  const {
+    add = () => {},
+    update = () => {},
+    selectedValues = readable([]),
+    groupName = readable(undefined),
+  } = ctx ?? {};
+
+  add({ value, selected });
+
+  $: if (hasGroup) {
+    selected = $selectedValues.includes(value);
+  }
 </script>
 
 <input
@@ -53,9 +67,24 @@
   checked={selected}
   {id}
   {value}
-  {name}
+  name={$groupName ?? name}
   {title}
   {disabled}
+  on:change={() => {
+    if (disabled) return;
+    if (!ref) return;
+    const newSelected = ref.checked;
+    selected = newSelected;
+    if (hasGroup) {
+      update({ value, selected: newSelected });
+    } else {
+      if (newSelected) {
+        dispatch("select", id);
+      } else {
+        dispatch("deselect", id);
+      }
+    }
+  }}
 />
 <!-- svelte-ignore a11y-mouse-events-have-key-events -->
 <!-- svelte-ignore a11y-no-noninteractive-tabindex -->
@@ -72,7 +101,22 @@
   on:click
   on:click|preventDefault={() => {
     if (disabled) return;
-    selected = !selected;
+    const newSelected = !selected;
+    selected = newSelected;
+
+    if (ref) {
+      ref.checked = newSelected;
+    }
+
+    if (hasGroup) {
+      update({ value, selected: newSelected });
+    } else {
+      if (newSelected) {
+        dispatch("select", id);
+      } else {
+        dispatch("deselect", id);
+      }
+    }
   }}
   on:mouseover
   on:mouseenter
@@ -82,7 +126,9 @@
     if (disabled) return;
     if (e.key === " " || e.key === "Enter") {
       e.preventDefault();
-      selected = !selected;
+      if (ref) {
+        ref.click();
+      }
     }
   }}
 >
diff --git a/src/Tile/SelectableTileGroup.svelte b/src/Tile/SelectableTileGroup.svelte
@@ -0,0 +1,85 @@
+<script>
+  /**
+   * @generics {T extends string = string} T
+   * @template {string} T
+   * @event {T} select
+   * @event {T} deselect
+   */
+
+  /**
+   * Specify the selected tile values
+   * @type {T[]}
+   */
+  export let selected = [];
+
+  /** Set to `true` to disable the tile group */
+  export let disabled = false;
+
+  /**
+   * Specify a name attribute for the checkbox inputs
+   * @type {string | undefined}
+   */
+  export let name = undefined;
+
+  /** Specify the legend text */
+  export let legend = "";
+
+  import { createEventDispatcher, setContext } from "svelte";
+  import { readonly, writable } from "svelte/store";
+
+  const dispatch = createEventDispatcher();
+  /**
+   * @type {import("svelte/store").Writable<T[]>}
+   */
+  const selectedValues = writable(selected);
+  /**
+   * @type {import("svelte/store").Writable<string | undefined>}
+   */
+  const groupName = writable(name);
+
+  /**
+   * @type {(data: { selected: boolean; value: T }) => void}
+   */
+  const add = ({ selected: isSelected, value }) => {
+    if (isSelected && !$selectedValues.includes(value)) {
+      selectedValues.update((values) => [...values, value]);
+    }
+  };
+
+  /**
+   * @type {(data: { value: T; selected: boolean }) => void}
+   */
+  const update = ({ value, selected: isSelected }) => {
+    if (isSelected) {
+      if (!$selectedValues.includes(value)) {
+        selectedValues.update((values) => [...values, value]);
+        dispatch("select", value);
+      }
+    } else {
+      if ($selectedValues.includes(value)) {
+        selectedValues.update((values) => values.filter((v) => v !== value));
+        dispatch("deselect", value);
+      }
+    }
+  };
+
+  setContext("SelectableTileGroup", {
+    selectedValues,
+    groupName: readonly(groupName),
+    add,
+    update,
+  });
+
+  $: selected = $selectedValues;
+  $: selectedValues.set(selected);
+  $: $groupName = name;
+</script>
+
+<fieldset {disabled} class:bx--tile-group={true} {...$$restProps}>
+  {#if legend}
+    <legend class:bx--label={true}>{legend}</legend>
+  {/if}
+  <div>
+    <slot />
+  </div>
+</fieldset>
diff --git a/src/Tile/index.js b/src/Tile/index.js
@@ -2,5 +2,6 @@ export { default as ClickableTile } from "./ClickableTile.svelte";
 export { default as ExpandableTile } from "./ExpandableTile.svelte";
 export { default as RadioTile } from "./RadioTile.svelte";
 export { default as SelectableTile } from "./SelectableTile.svelte";
+export { default as SelectableTileGroup } from "./SelectableTileGroup.svelte";
 export { default as Tile } from "./Tile.svelte";
 export { default as TileGroup } from "./TileGroup.svelte";
diff --git a/src/index.js b/src/index.js
@@ -133,6 +133,7 @@ export { default as ClickableTile } from "./Tile/ClickableTile.svelte";
 export { default as ExpandableTile } from "./Tile/ExpandableTile.svelte";
 export { default as RadioTile } from "./Tile/RadioTile.svelte";
 export { default as SelectableTile } from "./Tile/SelectableTile.svelte";
+export { default as SelectableTileGroup } from "./Tile/SelectableTileGroup.svelte";
 export { default as Tile } from "./Tile/Tile.svelte";
 export { default as TileGroup } from "./Tile/TileGroup.svelte";
 export { default as TimePicker } from "./TimePicker/TimePicker.svelte";
diff --git a/tests/Tile/SelectableTileGroup.test.svelte b/tests/Tile/SelectableTileGroup.test.svelte
@@ -0,0 +1,33 @@
+<svelte:options accessors />
+
+<script lang="ts">
+  import {
+    SelectableTile,
+    SelectableTileGroup,
+  } from "carbon-components-svelte";
+  import type { ComponentProps } from "svelte";
+
+  export let selected: ComponentProps<SelectableTileGroup>["selected"] = [];
+  export let disabled: ComponentProps<SelectableTileGroup>["disabled"] = false;
+  export let name: ComponentProps<SelectableTileGroup>["name"] = undefined;
+  export let legend: ComponentProps<SelectableTileGroup>["legend"] = "";
+  export let customClass = "";
+</script>
+
+<SelectableTileGroup
+  bind:selected
+  {disabled}
+  {name}
+  {legend}
+  class={customClass}
+  on:select={(e) => {
+    console.log("select", e.detail);
+  }}
+  on:deselect={(e) => {
+    console.log("deselect", e.detail);
+  }}
+>
+  <SelectableTile value="option1">Option 1</SelectableTile>
+  <SelectableTile value="option2">Option 2</SelectableTile>
+  <SelectableTile value="option3">Option 3</SelectableTile>
+</SelectableTileGroup>
diff --git a/tests/Tile/SelectableTileGroup.test.ts b/tests/Tile/SelectableTileGroup.test.ts
diff --git a/types/Tile/SelectableTileGroup.svelte.d.ts b/types/Tile/SelectableTileGroup.svelte.d.ts
diff --git a/types/index.d.ts b/types/index.d.ts
