docs(combo-box): add virtualization example

Author: metonym

docs/src/pages/components/ComboBox.svx

@@ -115,6 +115,30 @@ Set `allowCustomValue` to `true` to let users enter custom text that isn't in th
 
 <FileSource src="/framed/ComboBox/AllowCustomValue" />
 
+## Virtualized items (large lists)
+
+Enable virtualization for large lists to improve performance. Only visible items are rendered in the DOM.
+
+In the example below, 10,000 items are provided to the combobox but only 11 items (8 visible items + 3 overscan items) are rendered in the DOM.
+
+<FileSource src="/framed/ComboBox/VirtualizedComboBox" />
+
+## Virtualized items (custom overscan)
+
+Overscanning is the process of rendering extra items above and below the viewport to ensure smooth scrolling. The default overscan value is 3.
+
+Specify a custom value for `overscan` to control how many extra items are rendered above/below the viewport for smoother scrolling.
+
+<FileSource src="/framed/ComboBox/VirtualizeOverscan" />
+
+## Virtualized items (custom threshold)
+
+The threshold is the minimum number of items required before virtualization activates. The default threshold value is 100.
+
+Specify a custom value for `threshold` to control when virtualization activates. Below the threshold, all items are rendered normally without virtualization.
+
+<FileSource src="/framed/ComboBox/VirtualizeThreshold" />
+
 ## Top direction
 
 Set `direction` to `"top"` to make the dropdown menu appear above the input.

docs/src/pages/framed/ComboBox/VirtualizeOverscan.svelte

@@ -0,0 +1,22 @@
+<script>
+  import { ComboBox } from "carbon-components-svelte";
+
+  const items = Array.from({ length: 10_000 }, (_, i) => ({
+    id: i,
+    text: "Item " + (i + 1),
+  }));
+
+  let value = "";
+  let selectedId = undefined;
+</script>
+
+<ComboBox
+  virtualize={{ overscan: 100 }}
+  labelText="High overscan (overscan: 100)"
+  placeholder="Filter..."
+  {items}
+  shouldFilterItem={(item, value) =>
+    item.text.toLowerCase().includes(value.toLowerCase())}
+  bind:selectedId
+  bind:value
+/>

docs/src/pages/framed/ComboBox/VirtualizeThreshold.svelte

@@ -0,0 +1,22 @@
+<script>
+  import { ComboBox } from "carbon-components-svelte";
+
+  const items = Array.from({ length: 100 }, (_, i) => ({
+    id: i,
+    text: "Item " + (i + 1),
+  }));
+
+  let value = "";
+  let selectedId = undefined;
+</script>
+
+<ComboBox
+  virtualize={{ threshold: 200 }}
+  labelText="Custom threshold (threshold: 200)"
+  placeholder="Filter..."
+  {items}
+  shouldFilterItem={(item, value) =>
+    item.text.toLowerCase().includes(value.toLowerCase())}
+  bind:selectedId
+  bind:value
+/>

docs/src/pages/framed/ComboBox/VirtualizedComboBox.svelte

@@ -0,0 +1,29 @@
+<script>
+  import { ComboBox, Stack } from "carbon-components-svelte";
+
+  const items = Array.from({ length: 10_000 }, (_, i) => ({
+    id: i,
+    text: "Item " + (i + 1),
+  }));
+
+  let value = "";
+  let selectedId = undefined;
+  $: selectedItem = items.find((item) => item.id === selectedId);
+</script>
+
+<Stack gap={5}>
+  <ComboBox
+    virtualize={true}
+    labelText="Virtualized ComboBox (10,000 items)"
+    placeholder="Filter..."
+    {items}
+    shouldFilterItem={(item, value) =>
+      item.text.toLowerCase().includes(value.toLowerCase())}
+    bind:selectedId
+    bind:value
+  />
+  <div>
+    <strong>Selected:</strong>
+    {selectedItem?.text}
+  </div>
+</Stack>