carbon-components-svelte 0.98.0 → 0.98.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carbon-components-svelte",
-  "version": "0.98.0",
+  "version": "0.98.1",
   "license": "Apache-2.0",
   "description": "Svelte implementation of the Carbon Design System",
   "type": "module",

package/src/Checkbox/Checkbox.svelte

@@ -65,7 +65,17 @@
 
   $: useGroup = Array.isArray(group);
   $: if (useGroup) checked = group.includes(value);
-  $: dispatch("check", checked);
+
+  // Track previous checked value to avoid duplicate dispatches in Svelte 5
+  // The reactive statement will only dispatch when checked changes externally (e.g., via bind:checked)
+  let previousChecked = checked;
+  $: {
+    const hasChanged = previousChecked !== checked;
+    if (hasChanged) {
+      previousChecked = checked;
+      dispatch("check", checked);
+    }
+  }
 
   let refLabel = null;
 
@@ -121,7 +131,11 @@
             ? group.filter((_value) => _value !== value)
             : [...group, value];
         } else {
-          checked = !checked;
+          const newChecked = !checked;
+          previousChecked = newChecked;
+          checked = newChecked;
+          // Dispatch directly for user-initiated changes to avoid duplicate events in Svelte 5
+          dispatch("check", newChecked);
         }
       }}
       on:change

package/src/ComboBox/ComboBox.svelte

@@ -201,7 +201,7 @@
 
   /**
    * Clear the combo box programmatically
-   * @type {(options?: { focus?: boolean; }) => void}
+   * @type {(options?: { focus?: boolean; }) => Promise<void>}
    * @param {object} [options] - Configuration options for clearing
    * @param {boolean} [options.focus=true] - Whether to focus the combo box after clearing
    * @example
@@ -211,7 +211,7 @@
    * <button on:click={() => comboBox.clear({ focus: false })}>Clear (No Focus)</button>
    * ```
    */
-  export function clear(options = {}) {
+  export async function clear(options = {}) {
     prevSelectedId = null;
     highlightedIndex = -1;
     highlightedId = undefined;
@@ -219,6 +219,8 @@
     selectedItem = undefined;
     open = false;
     value = "";
+    // Ensure binding updates are complete before focusing.
+    await tick();
     if (options?.focus !== false) ref?.focus();
   }
 
@@ -262,6 +264,8 @@
 
   $: if (selectedId !== undefined) {
     if (prevSelectedId !== selectedId) {
+      // Only dispatch select event if not initial render (prevSelectedId was not null)
+      const isInitialRender = prevSelectedId === null;
       prevSelectedId = selectedId;
       if (filteredItems?.length === 1 && open) {
         selectedId = filteredItems[0].id;
@@ -271,7 +275,9 @@
       } else {
         selectedItem = items.find((item) => item.id === selectedId);
       }
-      dispatch("select", { selectedId, selectedItem });
+      if (!isInitialRender) {
+        dispatch("select", { selectedId, selectedItem });
+      }
     }
   } else {
     prevSelectedId = selectedId;

package/src/ContentSwitcher/ContentSwitcher.svelte

@@ -12,7 +12,7 @@
    */
   export let size = undefined;
 
-  import { afterUpdate, createEventDispatcher, setContext } from "svelte";
+  import { afterUpdate, createEventDispatcher, setContext, tick } from "svelte";
   import { writable } from "svelte/store";
 
   const dispatch = createEventDispatcher();
@@ -21,6 +21,9 @@
    */
   const currentId = writable(null);
 
+  /** @type {HTMLDivElement | null} */
+  let refContainer = null;
+
   $: currentIndex = -1;
   $: switches = [];
   $: if (switches[currentIndex]) {
@@ -47,9 +50,9 @@
   };
 
   /**
-   * @type {(direction: number) => void}
+   * @type {(direction: number) => Promise<void>}
    */
-  const change = (direction) => {
+  const change = async (direction) => {
     let index = currentIndex + direction;
 
     if (index < 0) {
@@ -59,6 +62,14 @@
     }
 
     selectedIndex = index;
+
+    await tick();
+    const tabs = refContainer?.querySelectorAll("[role='tab']");
+    const tab = tabs?.[index];
+
+    if (tab instanceof HTMLElement) {
+      tab.focus();
+    }
   };
 
   setContext("ContentSwitcher", {
@@ -78,6 +89,7 @@
 <!-- svelte-ignore a11y-mouse-events-have-key-events -->
 <!-- svelte-ignore a11y-interactive-supports-focus -->
 <div
+  bind:this={refContainer}
   role="tablist"
   class:bx--content-switcher={true}
   class:bx--content-switcher--sm={size === "sm"}

package/src/ContentSwitcher/Switch.svelte

@@ -23,7 +23,7 @@
   /** Obtain a reference to the button HTML element */
   export let ref = null;
 
-  import { afterUpdate, getContext, onMount } from "svelte";
+  import { getContext, onMount } from "svelte";
 
   const ctx = getContext("ContentSwitcher");
 
@@ -33,12 +33,6 @@
     selected = currentId === id;
   });
 
-  afterUpdate(() => {
-    if (selected) {
-      ref.focus();
-    }
-  });
-
   onMount(() => {
     return () => unsubscribe();
   });

package/src/DataTable/DataTable.svelte

@@ -192,6 +192,12 @@
   import InlineCheckbox from "../Checkbox/InlineCheckbox.svelte";
   import ChevronRight from "../icons/ChevronRight.svelte";
   import RadioButton from "../RadioButton/RadioButton.svelte";
+  import {
+    compareValues,
+    formatHeaderWidth,
+    getDisplayedRows,
+    resolvePath,
+  } from "./data-table-utils.js";
   import Table from "./Table.svelte";
   import TableBody from "./TableBody.svelte";
   import TableCell from "./TableCell.svelte";
@@ -200,8 +206,6 @@
   import TableHeader from "./TableHeader.svelte";
   import TableRow from "./TableRow.svelte";
 
-  const PATH_SPLIT_REGEX = /[.[\]'"]/;
-
   const sortDirectionMap = {
     none: "ascending",
     ascending: "descending",
@@ -228,13 +232,6 @@
     a[c.key] = c.key;
     return a;
   }, {});
-  const resolvePath = (object, path) => {
-    if (path in object) return object[path];
-    return path
-      .split(PATH_SPLIT_REGEX)
-      .filter((p) => p)
-      .reduce((o, p) => (o && typeof o === "object" ? o[p] : o), object);
-  };
 
   /**
    * @type {() => void}
@@ -342,48 +339,18 @@
       sortedRows = $tableRows;
     } else {
       sortedRows = [...$tableRows].sort((a, b) => {
-        const itemA = ascending
-          ? resolvePath(a, sortKey)
-          : resolvePath(b, sortKey);
-        const itemB = ascending
-          ? resolvePath(b, sortKey)
-          : resolvePath(a, sortKey);
-
-        if (sortingHeader?.sort) return sortingHeader.sort(itemA, itemB);
-
-        if (typeof itemA === "number" && typeof itemB === "number")
-          return itemA - itemB;
-
-        if ([itemA, itemB].every((item) => !item && item !== 0)) return 0;
-        if (!itemA && itemA !== 0) return ascending ? 1 : -1;
-        if (!itemB && itemB !== 0) return ascending ? -1 : 1;
-
-        return itemA
-          .toString()
-          .localeCompare(itemB.toString(), "en", { numeric: true });
+        const itemA = resolvePath(a, sortKey);
+        const itemB = resolvePath(b, sortKey);
+        return compareValues(itemA, itemB, ascending, sortingHeader?.sort);
       });
     }
   }
-  const getDisplayedRows = (rows, page, pageSize) =>
-    page && pageSize
-      ? rows.slice((page - 1) * pageSize, page * pageSize)
-      : rows;
   $: displayedRows = getDisplayedRows($tableRows, page, pageSize);
   $: displayedSortedRows = getDisplayedRows(sortedRows, page, pageSize);
 
   $: hasCustomHeaderWidth = headers.some(
     (header) => header.width || header.minWidth,
   );
-
-  /** @type {(header: DataTableHeader) => undefined | string} */
-  const formatHeaderWidth = (header) => {
-    const styles = [
-      header.width && `width: ${header.width}`,
-      header.minWidth && `min-width: ${header.minWidth}`,
-    ].filter(Boolean);
-    if (styles.length === 0) return undefined;
-    return styles.join(";");
-  };
 </script>
 
 <TableContainer {useStaticWidth} {...$$restProps}>

package/src/DataTable/DataTableTypes.d.ts

@@ -6,8 +6,8 @@ type Join<K, P> = K extends string | number
     : never
   : never;
 
-// For performance, the maximum traversal depth is 10.
-export type PropertyPath<T, D extends number = 10> = [D] extends [never]
+// For performance, the maximum traversal depth is 3.
+export type PropertyPath<T, D extends number = 3> = [D] extends [never]
   ? never
   : T extends object
     ? {

package/src/DataTable/ToolbarSearch.svelte

@@ -48,6 +48,7 @@
 
   import { afterUpdate, getContext, onMount, tick } from "svelte";
   import Search from "../Search/Search.svelte";
+  import { rowsEqual } from "./data-table-utils.js";
 
   const ctx = getContext("DataTable") ?? {};
 
@@ -58,7 +59,7 @@
     unsubscribe = ctx?.tableRows.subscribe((tableRows) => {
       // Only update if the rows have actually changed.
       // This approach works in both Svelte 4 and Svelte 5.
-      if (JSON.stringify(tableRows) !== JSON.stringify(rows)) {
+      if (!rowsEqual(tableRows, rows)) {
         rows = tableRows;
       }
     });

package/src/DataTable/data-table-utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lightweight deep equality check optimized for DataTable rows.
+ * Compares arrays of row objects by first checking IDs (fast path),
+ * then falling back to deep object comparison to handle nested structures.
+ */
+export function rowsEqual<Row extends Record<string, any>>(
+  a: ReadonlyArray<Row> | null,
+  b: ReadonlyArray<Row> | null,
+): boolean;
+
+/**
+ * Resolves a nested property path in an object.
+ * Supports both direct property access and nested paths like "contact.company".
+ */
+export function resolvePath<T extends Record<string, unknown>>(
+  object: T,
+  path: string,
+): unknown;
+
+/**
+ * Paginates an array of rows based on page number and page size.
+ */
+export function getDisplayedRows<Row extends Record<string, unknown>>(
+  rows: ReadonlyArray<Row>,
+  page: number,
+  pageSize: number,
+): ReadonlyArray<Row>;
+
+/**
+ * Formats header width styles for table headers.
+ * Combines width and minWidth into a CSS style string.
+ */
+export function formatHeaderWidth<
+  Header extends {
+    width?: string | null | number;
+    minWidth?: string | null | number;
+    [key: string]: unknown;
+  } = {
+    width?: string | null | number;
+    minWidth?: string | null | number;
+    [key: string]: unknown;
+  },
+>(header: Header): string | undefined;
+
+/**
+ * Compares two values for sorting in a data table.
+ * Handles numbers, strings, null/undefined values, and custom sort functions.
+ */
+export function compareValues<T = unknown>(
+  itemA: T,
+  itemB: T,
+  ascending: boolean,
+  customSort?: ((a: T, b: T) => number) | false | undefined,
+): number;

package/src/DataTable/data-table-utils.js

@@ -0,0 +1,239 @@
+// @ts-check
+/**
+ * Deep equality check for values (nested objects and arrays).
+ * @param {*} a - First value to compare
+ * @param {*} b - Second value to compare
+ * @param {WeakMap<*, Set<*>>} [stack] - WeakMap used to track circular references
+ * @returns {boolean} True if values are deeply equal, false otherwise
+ */
+function deepEqual(a, b, stack = new WeakMap()) {
+  // Fast path: reference equality.
+  if (a === b) return true;
+
+  // Handle null/undefined.
+  if (a == null || b == null) return a === b;
+
+  // Handle NaN: NaN is the only value where NaN !== NaN is true in JavaScript
+  // Without this check, two NaN values would incorrectly be considered unequal.
+  if (Number.isNaN(a) && Number.isNaN(b)) return true;
+  if (Number.isNaN(a) || Number.isNaN(b)) return false;
+
+  if (typeof a !== typeof b) return false;
+
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+
+  if (a instanceof RegExp && b instanceof RegExp) {
+    return a.source === b.source && a.flags === b.flags;
+  }
+
+  if (typeof a === "function" && typeof b === "function") {
+    return a === b;
+  }
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      // Pass the stack to handle nested arrays and prevent infinite recursion.
+      if (!deepEqual(a[i], b[i], stack)) return false;
+    }
+    return true;
+  }
+
+  if (typeof a === "object" && typeof b === "object") {
+    const aVisited = stack.get(a);
+
+    if (aVisited?.has(b)) {
+      // Circular reference: if we've already seen this (a, b) pair, they're equal.
+      return true;
+    }
+
+    // WeakMap entries are auto-removed when keys are garbage collected.
+    if (aVisited) {
+      aVisited.add(b);
+    } else {
+      stack.set(a, new Set([b]));
+    }
+
+    // Compare string keys: objects must have the same enumerable properties.
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) {
+      stack.get(a)?.delete(b);
+      return false;
+    }
+
+    for (const key of keysA) {
+      // Pass the stack to handle nested objects and prevent infinite recursion.
+      if (!(key in b) || !deepEqual(a[key], b[key], stack)) {
+        stack.get(a)?.delete(b);
+        return false;
+      }
+    }
+
+    const symKeysA = Object.getOwnPropertySymbols(a);
+    const symKeysB = Object.getOwnPropertySymbols(b);
+    if (symKeysA.length !== symKeysB.length) {
+      stack.get(a)?.delete(b);
+      return false;
+    }
+
+    // Recursively compare Symbol property values.
+    for (const key of symKeysA) {
+      if (!symKeysB.includes(key) || !deepEqual(a[key], b[key], stack)) {
+        stack.get(a)?.delete(b);
+        return false;
+      }
+    }
+
+    // All checks passed: remove (a, b) from tracking before returning
+    // Cleanup is for correctness (not GC): allows same objects to be
+    // compared again without false circular reference detection.
+    stack.get(a)?.delete(b);
+    return true;
+  }
+
+  // Finally, use strict equality for primitives.
+  return a === b;
+}
+
+/**
+ * Lightweight deep equality check optimized for DataTable rows.
+ * Compares arrays of row objects by first checking IDs (fast path),
+ * then falling back to deep object comparison to handle nested structures.
+ * @template {Record<string, any>} Row - Row type with at least an optional `id` property
+ * @param {ReadonlyArray<Row> | null} a - First array of rows to compare
+ * @param {ReadonlyArray<Row> | null} b - Second array of rows to compare
+ * @returns {boolean} True if row arrays are deeply equal, false otherwise
+ */
+export function rowsEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (!Array.isArray(a) || !Array.isArray(b)) return false;
+
+  if (a.length !== b.length) return false;
+
+  // Fast path: compare by row IDs first, assuming rows have stable IDs.
+  for (let i = 0; i < a.length; i++) {
+    if (a[i]?.id !== b[i]?.id) return false;
+  }
+
+  // If IDs match, do deep comparison of row objects
+  // This catches cases where row data changed but ID stayed the same,
+  // including changes in nested objects (e.g., "contact.company")
+  for (let i = 0; i < a.length; i++) {
+    const rowA = a[i];
+    const rowB = b[i];
+
+    // Fast path: same reference
+    if (rowA === rowB) continue;
+
+    // Deep comparison to handle nested objects and arrays
+    if (!deepEqual(rowA, rowB)) return false;
+  }
+
+  return true;
+}
+
+const PATH_SPLIT_REGEX = /[.[\]'"]/;
+const MAX_PATH_CACHE_SIZE = 1000;
+const pathCache = new Map();
+
+/**
+ * Resolves a nested property path in an object.
+ * Supports both direct property access and nested paths like "contact.company".
+ * @template {Record<string, unknown>} T
+ * @param {T} object - The object to resolve the path from
+ * @param {string} path - The property path (e.g., "name" or "contact.company")
+ * @returns {unknown} The resolved value, or undefined if the path doesn't exist
+ */
+export function resolvePath(object, path) {
+  if (path in object) return object[path];
+
+  let segments = pathCache.get(path);
+  if (!segments) {
+    segments = path.split(PATH_SPLIT_REGEX).filter((p) => p);
+    if (segments.length > 1) {
+      if (pathCache.size >= MAX_PATH_CACHE_SIZE) {
+        const firstKey = pathCache.keys().next().value;
+        pathCache.delete(firstKey);
+      }
+      pathCache.set(path, segments);
+    }
+  }
+
+  return segments.reduce(
+    (o, p) => (o && typeof o === "object" ? o[p] : o),
+    object,
+  );
+}
+
+/**
+ * Paginates an array of rows based on page number and page size.
+ * @template {Record<string, unknown>} Row
+ * @param {ReadonlyArray<Row>} rows - The rows to paginate
+ * @param {number} page - The current page number (1-indexed)
+ * @param {number} pageSize - The number of items per page
+ * @returns {ReadonlyArray<Row>} The paginated rows, or all rows if pagination is disabled
+ */
+export function getDisplayedRows(rows, page, pageSize) {
+  if (page && pageSize) {
+    return rows.slice((page - 1) * pageSize, page * pageSize);
+  }
+  return rows;
+}
+
+/**
+ * Formats header width styles for table headers.
+ * Combines width and minWidth into a CSS style string.
+ * @template {object} Header
+ * @param {Header & { width?: string | null | number; minWidth?: string | null | number; [key: string]: unknown }} header - The header object
+ * @returns {string | undefined} The formatted style string, or undefined if no width styles
+ */
+export function formatHeaderWidth(header) {
+  const styles = [
+    header.width && `width: ${header.width}`,
+    header.minWidth && `min-width: ${header.minWidth}`,
+  ].filter(Boolean);
+  if (styles.length === 0) return undefined;
+  return styles.join(";");
+}
+
+/**
+ * Compares two values for sorting in a data table.
+ * Handles numbers, strings, null/undefined values, and custom sort functions.
+ * @template T
+ * @param {T} itemA - First value to compare
+ * @param {T} itemB - Second value to compare
+ * @param {boolean} ascending - Whether to sort in ascending order
+ * @param {((a: T, b: T) => number) | false | undefined} customSort - Optional custom sort function
+ * @returns {number} Negative if a < b (ascending) or a > b (descending), positive if a > b (ascending) or a < b (descending), 0 if equal
+ */
+export function compareValues(itemA, itemB, ascending, customSort) {
+  if (customSort) return customSort(itemA, itemB);
+
+  let result;
+
+  // Fast path: numeric comparison
+  if (typeof itemA === "number" && typeof itemB === "number") {
+    result = itemA - itemB;
+  } else {
+    // Handle null/undefined values
+    if ([itemA, itemB].every((item) => !item && item !== 0)) {
+      result = 0;
+    } else if (!itemA && itemA !== 0) {
+      result = 1;
+    } else if (!itemB && itemB !== 0) {
+      result = -1;
+    } else {
+      // String comparison with locale-aware numeric sorting
+      result = String(itemA).localeCompare(String(itemB), "en", {
+        numeric: true,
+      });
+    }
+  }
+
+  // Reverse result for descending order
+  return ascending ? result : -result;
+}

package/src/StructuredList/StructuredList.svelte

@@ -27,6 +27,9 @@
    */
   const selectedValue = writable(selected);
 
+  let prevSelectedValue = undefined;
+  let isInitialRender = true;
+
   /**
    * @type {(value: string) => void}
    */
@@ -40,7 +43,13 @@
   });
 
   $: selected = $selectedValue;
-  $: dispatch("change", $selectedValue);
+  $: {
+    if (!isInitialRender && prevSelectedValue !== $selectedValue) {
+      dispatch("change", $selectedValue);
+    }
+    prevSelectedValue = $selectedValue;
+    isInitialRender = false;
+  }
 </script>
 
 <!-- svelte-ignore a11y-mouse-events-have-key-events -->

package/src/Tooltip/Tooltip.svelte

@@ -78,6 +78,8 @@
    */
   const tooltipOpen = writable(open);
 
+  let prevOpen = undefined;
+
   setContext("Tooltip", { tooltipOpen });
 
   function onKeydown(e) {
@@ -175,7 +177,12 @@
   });
 
   $: tooltipOpen.set(open);
-  $: dispatch(open ? "open" : "close");
+  $: {
+    if (prevOpen !== undefined) {
+      dispatch(open ? "open" : "close");
+    }
+    prevOpen = open;
+  }
   $: buttonProps = {
     role: "button",
     "aria-haspopup": "true",

package/src/TreeView/TreeView.svelte

@@ -25,6 +25,38 @@
 
     return null;
   }
+
+  /**
+   * Creates a TreeWalker instance for keyboard navigation.
+   * @param {HTMLElement} root - The root element to traverse
+   * @returns {TreeWalker} A TreeWalker configured to navigate tree nodes
+   */
+  function createTreeWalkerInstance(root) {
+    return document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT, {
+      acceptNode: (node) => {
+        if (node.classList.contains("bx--tree-node--disabled"))
+          return NodeFilter.FILTER_REJECT;
+        if (node.matches("li.bx--tree-node")) return NodeFilter.FILTER_ACCEPT;
+        return NodeFilter.FILTER_SKIP;
+      },
+    });
+  }
+
+  /**
+   * Recursively flattens a tree of nodes into a single array
+   * @template {object} Node
+   * @param {ReadonlyArray<Node & { nodes?: Node[] }>} nodes
+   * @returns {Array<Node>}
+   */
+  function traverse(nodes) {
+    return nodes.reduce((acc, node) => {
+      acc.push(node);
+      if (Array.isArray(node.nodes) && node.nodes.length > 0) {
+        acc.push(...traverse(node.nodes));
+      }
+      return acc;
+    }, []);
+  }
 </script>
 
 <script>
@@ -98,7 +130,9 @@
    * ```
    */
   export function expandAll() {
-    expandedIds = [...nodeIds];
+    expandedIdsSet = new Set(nodeIds);
+    expandedIds = Array.from(expandedIdsSet);
+    lastExpandedIdsRef = expandedIds;
   }
 
   /**
@@ -111,7 +145,9 @@
    * ```
    */
   export function collapseAll() {
+    expandedIdsSet.clear();
     expandedIds = [];
+    lastExpandedIdsRef = expandedIds;
   }
 
   /**
@@ -128,13 +164,16 @@
    * ```
    */
   export function expandNodes(filterNode = (node) => false) {
-    expandedIds = flattenedNodes
+    const nodesToExpand = flattenedNodes
       .filter(
         (node) =>
           filterNode(node) ||
           node.nodes?.some((child) => filterNode(child) && child.nodes),
       )
       .map((node) => node.id);
+    nodesToExpand.forEach((id) => expandedIdsSet.add(id));
+    expandedIds = Array.from(expandedIdsSet);
+    lastExpandedIdsRef = expandedIds;
   }
 
   /**
@@ -151,9 +190,13 @@
    * ```
    */
   export function collapseNodes(filterNode = (node) => true) {
-    expandedIds = flattenedNodes
-      .filter((node) => expandedIds.includes(node.id) && !filterNode(node))
-      .map((node) => node.id);
+    flattenedNodes.forEach((node) => {
+      if (expandedIdsSet.has(node.id) && filterNode(node)) {
+        expandedIdsSet.delete(node.id);
+      }
+    });
+    expandedIds = Array.from(expandedIdsSet);
+    lastExpandedIdsRef = expandedIds;
   }
 
   /**
@@ -181,18 +224,21 @@
     const { expand = true, select = true, focus = true } = options;
 
     for (const child of nodes) {
-      const nodes = findNodeById(child, id);
+      const path = findNodeById(child, id);
 
-      if (nodes) {
-        const ids = nodes.map((node) => node.id);
-        const nodeIds = new Set(ids);
+      if (path) {
+        const ids = path.map((node) => node.id);
+        const lastId = ids[ids.length - 1];
 
         if (expand) {
-          expandNodes((node) => nodeIds.has(node.id));
+          const ancestorIds = ids.slice(0, -1);
+          for (const ancestorId of ancestorIds) {
+            expandedIdsSet.add(ancestorId);
+          }
+          expandedIds = Array.from(expandedIdsSet);
+          lastExpandedIdsRef = expandedIds;
         }
 
-        const lastId = ids[ids.length - 1];
-
         if (select) {
           activeId = lastId;
           selectedIds = [lastId];
@@ -215,57 +261,58 @@
 
   const dispatch = createEventDispatcher();
   const labelId = `label-${Math.random().toString(36)}`;
-  /**
-   * @type {import("svelte/store").Writable<TreeNodeId>}
-   */
+  
+  /** @type {import("svelte/store").Writable<TreeNodeId>} */
   const activeNodeId = writable(activeId);
-  /**
-   * @type {import("svelte/store").Writable<ReadonlyArray<TreeNodeId>>}
-   */
+  /** @type {import("svelte/store").Writable<ReadonlyArray<TreeNodeId>>} */
   const selectedNodeIds = writable(selectedIds);
-  /**
-   * @type {import("svelte/store").Writable<ReadonlyArray<TreeNodeId>>}
-   */
+  /** @type {import("svelte/store").Writable<ReadonlyArray<TreeNodeId>>} */
   const expandedNodeIds = writable(expandedIds);
 
+  /** @type {HTMLElement | null} */
   let ref = null;
+  /** @type {TreeWalker | null} */
   let treeWalker = null;
 
-  /**
-   * @type {(node: TreeNode) => void}
-   */
+  /** @type {ReadonlyArray<Node> | null} */
+  let cachedNodes = null;
+  /** @type {Array<Node> | null} */
+  let cachedFlattenedNodes = null;
+  /** @type {Array<TreeNodeId> | null} */
+  let cachedNodeIds = null;
+
+  /** @type {Set<TreeNodeId>} */
+  let expandedIdsSet = new Set(expandedIds);
+  /** @type {ReadonlyArray<TreeNodeId>} */
+  let lastExpandedIdsRef = expandedIds;
+
+  /** @type {(node: TreeNode) => void} */
   const clickNode = (node) => {
     activeId = node.id;
     selectedIds = [node.id];
     dispatch("select", node);
   };
 
-  /**
-   * @type {(node: TreeNode) => void}
-   */
+  /** @type {(node: TreeNode) => void} */
   const selectNode = (node) => {
     selectedIds = [node.id];
   };
 
-  /**
-   * @type {(node: TreeNode, expanded: boolean) => void}
-   */
+  /** @type {(node: TreeNode, expanded: boolean) => void} */
   const expandNode = (node, expanded) => {
     if (expanded) {
-      expandedIds = [...expandedIds, node.id];
+      expandedIdsSet.add(node.id);
     } else {
-      expandedIds = expandedIds.filter((_id) => _id !== node.id);
+      expandedIdsSet.delete(node.id);
     }
+    expandedIds = Array.from(expandedIdsSet);
+    lastExpandedIdsRef = expandedIds;
   };
 
-  /**
-   * @type {(node: TreeNode) => void}
-   */
+  /** @type {(node: TreeNode) => void} */
   const focusNode = (node) => dispatch("focus", node);
 
-  /**
-   * @type {(node: TreeNode) => void}
-   */
+  /** @type {(node: TreeNode) => void} */
   const toggleNode = (node) => dispatch("toggle", node);
 
   setContext("TreeView", {
@@ -302,37 +349,33 @@
     if (firstFocusableNode != null) {
       firstFocusableNode.tabIndex = "0";
     }
+
+    if (ref && !treeWalker) {
+      treeWalker = createTreeWalkerInstance(ref);
+    }
   });
 
-  /**
-   * Recursively flattens a tree of nodes into a single array
-   * @param {ReadonlyArray<Node & { nodes?: Node[] }>} nodes
-   * @returns {Array<Node>}
-   */
-  function traverse(nodes) {
-    return nodes.reduce((acc, node) => {
-      acc.push(node);
-      if (Array.isArray(node.nodes) && node.nodes.length > 0) {
-        acc.push(...traverse(node.nodes));
-      }
-      return acc;
-    }, []);
+  $: if (nodes !== cachedNodes) {
+    cachedNodes = nodes;
+    cachedFlattenedNodes = traverse(nodes);
+    cachedNodeIds = cachedFlattenedNodes.map((node) => node.id);
   }
 
-  $: flattenedNodes = traverse(nodes);
-  $: nodeIds = flattenedNodes.map((node) => node.id);
-  $: activeNodeId.set(activeId);
-  $: selectedNodeIds.set(selectedIds);
-  $: expandedNodeIds.set(expandedIds);
-  $: if (ref) {
-    treeWalker = document.createTreeWalker(ref, NodeFilter.SHOW_ELEMENT, {
-      acceptNode: (node) => {
-        if (node.classList.contains("bx--tree-node--disabled"))
-          return NodeFilter.FILTER_REJECT;
-        if (node.matches("li.bx--tree-node")) return NodeFilter.FILTER_ACCEPT;
-        return NodeFilter.FILTER_SKIP;
-      },
-    });
+  $: flattenedNodes = cachedFlattenedNodes ?? [];
+  $: nodeIds = cachedNodeIds ?? [];
+
+  $: {
+    if (expandedIds !== lastExpandedIdsRef) {
+      expandedIdsSet = new Set(expandedIds);
+      lastExpandedIdsRef = expandedIds;
+    }
+    activeNodeId.set(activeId);
+    selectedNodeIds.set(selectedIds);
+    expandedNodeIds.set(expandedIds);
+  }
+
+  $: if (ref && (nodes !== cachedNodes || !treeWalker)) {
+    treeWalker = createTreeWalkerInstance(ref);
   }
 </script>
 

package/types/ComboBox/ComboBox.svelte.d.ts

@@ -216,5 +216,5 @@ export default class ComboBox<
    * <button on:click={() => comboBox.clear({ focus: false })}>Clear (No Focus)</button>
    * ```
    */
-  clear: (options?: { focus?: boolean }) => void;
+  clear: (options?: { focus?: boolean }) => Promise<void>;
 }

package/types/ContentSwitcher/ContentSwitcher.svelte.d.ts

@@ -5,7 +5,7 @@ export type ContentSwitcherContext = {
   currentId: import("svelte/store").Writable<string | null>;
   add: (data: { id: string; text: string; selected: boolean }) => void;
   update: (id: string) => void;
-  change: (direction: number) => void;
+  change: (direction: number) => Promise<void>;
 };
 
 type $RestProps = SvelteHTMLElements["div"];

package/types/DataTable/DataTableTypes.d.ts

@@ -6,8 +6,8 @@ type Join<K, P> = K extends string | number
     : never
   : never;
 
-// For performance, the maximum traversal depth is 10.
-export type PropertyPath<T, D extends number = 10> = [D] extends [never]
+// For performance, the maximum traversal depth is 3.
+export type PropertyPath<T, D extends number = 3> = [D] extends [never]
   ? never
   : T extends object
     ? {

package/types/DataTable/data-table-utils.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Lightweight deep equality check optimized for DataTable rows.
+ * Compares arrays of row objects by first checking IDs (fast path),
+ * then falling back to deep object comparison to handle nested structures.
+ */
+export function rowsEqual<Row extends Record<string, any>>(
+  a: ReadonlyArray<Row> | null,
+  b: ReadonlyArray<Row> | null,
+): boolean;
+
+/**
+ * Resolves a nested property path in an object.
+ * Supports both direct property access and nested paths like "contact.company".
+ */
+export function resolvePath<T extends Record<string, unknown>>(
+  object: T,
+  path: string,
+): unknown;
+
+/**
+ * Paginates an array of rows based on page number and page size.
+ */
+export function getDisplayedRows<Row extends Record<string, unknown>>(
+  rows: ReadonlyArray<Row>,
+  page: number,
+  pageSize: number,
+): ReadonlyArray<Row>;
+
+/**
+ * Formats header width styles for table headers.
+ * Combines width and minWidth into a CSS style string.
+ */
+export function formatHeaderWidth<
+  Header extends {
+    width?: string | null | number;
+    minWidth?: string | null | number;
+    [key: string]: unknown;
+  } = {
+    width?: string | null | number;
+    minWidth?: string | null | number;
+    [key: string]: unknown;
+  },
+>(header: Header): string | undefined;
+
+/**
+ * Compares two values for sorting in a data table.
+ * Handles numbers, strings, null/undefined values, and custom sort functions.
+ */
+export function compareValues<T = unknown>(
+  itemA: T,
+  itemB: T,
+  ascending: boolean,
+  customSort?: ((a: T, b: T) => number) | false | undefined,
+): number;