feat: add two-way binding example for MultiSelectSearchAutocomplete with synchronised color state

Ibrahim Haizel · Ibrahim Haizel · commit 8574ff60d584 · 2025-08-21T15:12:36.000+01:00
diff --git a/src/lib/components/ui/MultiSelectSearchAutocomplete.svelte b/src/lib/components/ui/MultiSelectSearchAutocomplete.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
   import { onMount, onDestroy } from "svelte";
+  import { SvelteMap } from "svelte/reactivity";
   import Select, { type SelectItem, type SelectGroup } from "./Select.svelte";
   import IconSearch from "../../icons/IconSearch.svelte";
   import crossIconUrl from "./../../assets/govuk_publishing_components/images/cross-icon.svg?url";
@@ -20,6 +21,10 @@
     value = $bindable<(string | number)[] | string | number | undefined>(),
     multiple = false,
 
+    // Bindable state props for external synchronization
+    bindSelectedItemIndexMap = $bindable(new Map<string, number>()),
+    bindNextSelectionIndex = $bindable(0),
+
     // Label and hints - pass through to Select component
     label,
     labelIsPageHeading = false,
@@ -96,6 +101,7 @@
       "#b1b4b6", // Light grey
       "#0b0c0c", // Black
     ], // Complete GOV.UK Design System palette (19 colors)
+
     ...attributes
   }: {
     id: string;
@@ -134,6 +140,11 @@
     enableSelectedItemCircles?: boolean;
     selectedItemCircleColor?: string;
     selectedItemCircleColorPalette?: string[];
+
+    // Bindable state props for external synchronization
+    // Use these to sync color state with other components
+    bindSelectedItemIndexMap?: Map<string, number> | SvelteMap<string, number>; // Maps item values to their color indices
+    bindNextSelectionIndex?: number; // Next available color index
   } & Omit<
     import("svelte/elements").HTMLSelectAttributes,
     | "id"
@@ -170,8 +181,22 @@
   // Sequential color mapping: each selected item gets a unique color based on selection order
   // This ensures perfect visual distinction and predictable color assignment
   // 1st selection = color[0], 2nd selection = color[1], 3rd selection = color[2], etc.
-  let selectedItemIndexMap = new Map<string, number>(); // Maps item value to selection index
-  let nextSelectionIndex = 0; // Tracks the next available color index
+
+  // Architecture: Single source of truth using external bindings with fallbacks
+  // This eliminates state duplication and sync complexity
+  // Use $derived for reading external bindings reactively
+  // This ensures that when external bindings change, our local state updates automatically
+  let selectedItemIndexMap = $derived(
+    bindSelectedItemIndexMap || new SvelteMap<string, number>(),
+  );
+  let nextSelectionIndex = $derived(bindNextSelectionIndex ?? 0);
+
+  // Helper function to update external bindings when we modify state
+  function updateNextSelectionIndex(newValue: number) {
+    if (bindNextSelectionIndex !== undefined) {
+      bindNextSelectionIndex = newValue;
+    }
+  }
 
   // Get the maximum number of selections allowed (limited by palette size)
   // With 19 GOV.UK colors, maximum selections = 19 before cycling begins
@@ -196,39 +221,28 @@
     // If we've reached the palette limit, cycle back to the beginning
     // This means the 20th selection will get color[0], 21st will get color[1], etc.
     if (nextSelectionIndex >= maxSelections) {
-      nextSelectionIndex = 0;
+      updateNextSelectionIndex(0);
     }
 
     // Assign the next available color index to this item
     const colorIndex = nextSelectionIndex;
+    // SvelteMap.set() automatically triggers reactivity and updates external bindings
     selectedItemIndexMap.set(valueKey, colorIndex);
-    nextSelectionIndex++;
+    updateNextSelectionIndex(colorIndex + 1);
 
     // Log the index map update for debugging
     console.log("🎨 Color index map updated:", {
       itemValue: valueKey,
       assignedColorIndex: colorIndex,
       assignedColor: selectedItemCircleColorPalette[colorIndex],
-      nextSelectionIndex,
+      nextSelectionIndex: colorIndex + 1,
       totalMappedItems: selectedItemIndexMap.size,
       currentMap: Object.fromEntries(selectedItemIndexMap),
     });
 
     return selectedItemCircleColorPalette[colorIndex];
   }
 
-  // Function to reset the selection index when items are removed
-  // Call this when you want to clear all selections and start fresh
-  function resetSelectionIndexes() {
-    console.log("🔄 Color index map reset:", {
-      previousMapSize: selectedItemIndexMap.size,
-      previousNextIndex: nextSelectionIndex,
-    });
-    selectedItemIndexMap.clear();
-    nextSelectionIndex = 0;
-    console.log("✅ Color index map reset complete");
-  }
-
   // Color cache to ensure consistent colors for the same values
   const colorCache = new Map<string, string>();
 
diff --git a/src/wrappers/components/ui/multi-select-search-autocomplete/Examples.svelte b/src/wrappers/components/ui/multi-select-search-autocomplete/Examples.svelte
@@ -5,6 +5,35 @@
   import * as codeBlocks from "./codeBlocks.js";
 
   import MultiSelectSearchAutocomplete from "$lib/components/ui/MultiSelectSearchAutocomplete.svelte";
+  import Button from "$lib/components/ui/Button.svelte";
+  import { SvelteMap } from "svelte/reactivity";
+
+  // State variables for two-way binding example
+  let globalColorMap = new SvelteMap();
+  let globalNextIndex = 0;
+  let globalSelectedValues = []; // Shared selected values between components
+
+  // GOV.UK color palette for the example
+  const selectedItemCircleColorPalette = [
+    "#1d70b8", // Blue (primary)
+    "#d4351c", // Red
+    "#00703c", // Green
+    "#f47738", // Orange
+    "#4c2c92", // Purple
+    "#801650", // Bright purple
+    "#28a197", // Turquoise
+    "#b58840", // Brown
+    "#d53880", // Pink
+    "#6f72af", // Light purple
+    "#f499be", // Light pink
+    "#85994b", // Light green
+    "#ffdd00", // Yellow
+    "#12436d", // Dark blue
+    "#505a5f", // Dark grey
+    "#626a6e", // Mid grey
+    "#b1b4b6", // Light grey
+    "#0b0c0c", // Black
+  ];
 
   let accordionSnippetSections = [
     {
@@ -32,6 +61,11 @@
       heading: "5. Remote API source (postcodes.io)",
       content: Example5,
     },
+    {
+      id: "6",
+      heading: "6. Two-Way Binding with Color State",
+      content: Example6,
+    },
   ];
 </script>
 
@@ -201,3 +235,188 @@
   </div>
   <CodeBlock code={codeBlocks.codeBlockApi} language="svelte"></CodeBlock>
 {/snippet}
+
+<!-- Example 6: Two-Way Binding with Color State -->
+<!-- This example demonstrates how to use the new bindable state props to sync color state between multiple components -->
+{#snippet Example6()}
+  <div class="p-5 bg-white space-y-6">
+    <div>
+      <h2 class="govuk-heading-m">
+        Two-Way Binding Demo: Synchronised Multi-Select Components
+      </h2>
+      <p class="govuk-body">
+        Both components below share the same options and color state. Select or
+        deselect items in either component to see them sync in real-time.
+      </p>
+    </div>
+
+    <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
+      <div class="bg-white p-4 rounded-lg border border-gray-200">
+        <h6 class="font-semibold mb-3 text-gray-800">
+          Component 1 - Left Panel
+        </h6>
+        <MultiSelectSearchAutocomplete
+          id="bound-select-1"
+          name="bound-1"
+          label="Select fruits (Component 1)"
+          hint="Select items here and watch Component 2 sync automatically"
+          items={[
+            { value: "apple", text: "🍎 Apple" },
+            { value: "banana", text: "🍌 Banana" },
+            { value: "cherry", text: "🍒 Cherry" },
+            { value: "date", text: "📅 Date" },
+            { value: "elderberry", text: "🫐 Elderberry" },
+            { value: "fig", text: "🫒 Fig" },
+            { value: "grape", text: "🍇 Grape" },
+            { value: "honeydew", text: "🍈 Honeydew" },
+            { value: "kiwi", text: "🥝 Kiwi" },
+            { value: "lemon", text: "🍋 Lemon" },
+            { value: "mango", text: "🥭 Mango" },
+            { value: "nectarine", text: "🍑 Nectarine" },
+          ]}
+          multiple={true}
+          bind:value={globalSelectedValues}
+          bind:bindSelectedItemIndexMap={globalColorMap}
+          bind:bindNextSelectionIndex={globalNextIndex}
+        />
+      </div>
+
+      <div class="bg-white p-4 rounded-lg border border-gray-200">
+        <h6 class="font-semibold mb-3 text-gray-800">
+          Component 2 - Right Panel
+        </h6>
+        <MultiSelectSearchAutocomplete
+          id="bound-select-2"
+          name="bound-2"
+          label="Select fruits (Component 2)"
+          hint="This component automatically syncs with Component 1"
+          items={[
+            { value: "apple", text: "🍎 Apple" },
+            { value: "banana", text: "🍌 Banana" },
+            { value: "cherry", text: "🍒 Cherry" },
+            { value: "date", text: "📅 Date" },
+            { value: "elderberry", text: "🫐 Elderberry" },
+            { value: "fig", text: "🫒 Fig" },
+            { value: "grape", text: "🍇 Grape" },
+            { value: "honeydew", text: "🍈 Honeydew" },
+            { value: "kiwi", text: "🥝 Kiwi" },
+            { value: "lemon", text: "🍋 Lemon" },
+            { value: "mango", text: "🥭 Mango" },
+            { value: "nectarine", text: "🍑 Nectarine" },
+          ]}
+          multiple={true}
+          bind:value={globalSelectedValues}
+          bind:bindSelectedItemIndexMap={globalColorMap}
+          bind:bindNextSelectionIndex={globalNextIndex}
+        />
+      </div>
+    </div>
+
+    <div>
+      <h2 class="govuk-heading-m">🎨 Live Colour State Synchronisation</h2>
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
+        <div class="space-y-3">
+          <div class="flex items-center justify-between">
+            <span class="font-medium text-gray-700">Next Color Index:</span>
+            <span
+              class="px-3 py-1 bg-blue-100 text-blue-800 rounded-full font-mono"
+            >
+              {globalNextIndex}
+            </span>
+          </div>
+          <div class="flex items-center justify-between">
+            <span class="font-medium text-gray-700">Total Selected Items:</span>
+            <span
+              class="px-3 py-1 bg-green-100 text-green-800 rounded-full font-mono"
+            >
+              {globalColorMap.size}
+            </span>
+          </div>
+          <div class="flex items-center justify-between">
+            <span class="font-medium text-gray-700">Available Colors:</span>
+            <span
+              class="px-3 py-1 bg-purple-100 text-purple-800 rounded-full font-mono"
+            >
+              {selectedItemCircleColorPalette.length - globalColorMap.size}
+            </span>
+          </div>
+          <div class="flex items-center justify-between">
+            <span class="font-medium text-gray-700">Selected Values:</span>
+            <span
+              class="px-3 py-1 bg-orange-100 text-orange-800 rounded-full font-mono"
+            >
+              {globalSelectedValues.length}
+            </span>
+          </div>
+        </div>
+
+        <div class="space-y-2">
+          <span class="font-medium text-gray-700 block mb-2"
+            >Color Mapping:</span
+          >
+          <div class="max-h-32 overflow-y-auto space-y-1">
+            {#each Array.from(globalColorMap.entries()) as [itemValue, colorIndex]}
+              <div class="flex items-center gap-2 p-2 bg-white rounded border">
+                <span
+                  class="w-4 h-4 rounded-full border-2 border-white shadow-sm"
+                  style="background-color: {selectedItemCircleColorPalette[
+                    colorIndex
+                  ]}"
+                ></span>
+                <span class="text-sm font-medium">{itemValue}</span>
+                <span class="text-xs text-gray-500 ml-auto"
+                  >→ Color {colorIndex}</span
+                >
+              </div>
+            {/each}
+            {#if globalColorMap.size === 0}
+              <div
+                class="text-sm text-gray-500 italic p-2 bg-white rounded border"
+              >
+                No items selected yet
+              </div>
+            {/if}
+          </div>
+        </div>
+      </div>
+
+      <div class="govuk-!-margin-top-6 govuk-button-group">
+        <Button
+          buttonType="warning"
+          textContent="Reset All Selections"
+          onClickFunction={() => {
+            // Reset all state - single source of truth means no need for component resets!
+            globalColorMap.clear();
+            globalNextIndex = 0;
+            globalSelectedValues = [];
+          }}
+        />
+        <Button
+          buttonType="secondary"
+          textContent="Add Demo Selections"
+          onClickFunction={() => {
+            // Add some demo selections
+            globalColorMap.set("apple", 0);
+            globalColorMap.set("banana", 1);
+            globalColorMap.set("cherry", 2);
+            globalNextIndex = 3;
+            globalSelectedValues = ["apple", "banana", "cherry"];
+          }}
+        />
+        <Button
+          buttonType="default"
+          textContent="Debug State"
+          onClickFunction={() => {
+            console.log("🔍 Debug State:", {
+              globalColorMap: Object.fromEntries(globalColorMap),
+              globalNextIndex,
+              globalSelectedValues,
+              mapSize: globalColorMap.size,
+            });
+          }}
+        />
+      </div>
+    </div>
+  </div>
+  <CodeBlock code={codeBlocks.codeBlock6} language="svelte"></CodeBlock>
+{/snippet}
diff --git a/src/wrappers/components/ui/multi-select-search-autocomplete/codeBlocks.js b/src/wrappers/components/ui/multi-select-search-autocomplete/codeBlocks.js
