feat(toolbar-search): support auto-filterable rows (#1179)

Closes #591

docs/src/COMPONENT_API.json

@@ -2282,7 +2282,7 @@
           "isFunction": false,
           "isFunctionDeclaration": false,
           "constant": false,
-          "reactive": true
+          "reactive": false
         },
         {
           "name": "size",
@@ -13218,6 +13218,17 @@
           "constant": false,
           "reactive": false
         },
+        {
+          "name": "shouldFilterRows",
+          "kind": "let",
+          "description": "Set to `true` to filter table rows using the search value.\n\nIf `true`, the default search excludes `id`, `cells` fields and\nonly does a basic comparison on string and number type cell values.\n\nTo implement your own client-side filtering, pass a function\nthat accepts a row and value and returns a boolean.",
+          "type": "boolean | ((rows: import(\"./DataTable.svelte\").DataTableRow, value: number | string) => boolean)",
+          "value": "false",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "constant": false,
+          "reactive": false
+        },
         {
           "name": "tabindex",
           "kind": "let",

docs/src/pages/components/DataTable.svx

@@ -464,6 +464,22 @@ title="Load balancers" description="Your organization's active load balancers."
   </Toolbar>
 </DataTable>
 
+### Filterable
+
+By default, `ToolbarSearch` will not filter `DataTable` rows.
+
+Set `shouldFilterRows` to `true` to enable client-side filtering. The default filtering performs a basic string comparison on cell values that are of a string or a number type.
+
+Note that in-memory filtering is not optimal for large data sets, where you might consider using server-side search.
+
+<FileSource src="/framed/DataTable/DataTableFilterable" />
+
+### Filterable (custom)
+
+`shouldFilterRows` also accepts a function and passes it the current row and value. It expects the function to return a boolean.
+
+<FileSource src="/framed/DataTable/DataTableFilterCustom" />
+
 ### Zebra stripes
 
 <DataTable zebra

docs/src/pages/framed/DataTable/DataTableFilterCustom.svelte

@@ -0,0 +1,55 @@
+<script>
+  import {
+    DataTable,
+    Toolbar,
+    ToolbarContent,
+    ToolbarSearch,
+    ToolbarMenu,
+    ToolbarMenuItem,
+    Button,
+  } from "carbon-components-svelte";
+
+  let rows = Array.from({ length: 10 }).map((_, i) => ({
+    id: i,
+    name: "Load Balancer " + (i + 1),
+    protocol: "HTTP",
+    port: 3000 + i * 10,
+    rule: i % 2 ? "Round robin" : "DNS delegation",
+  }));
+</script>
+
+<DataTable
+  sortable
+  title="Load balancers"
+  description="Your organization's active load balancers."
+  headers="{[
+    { key: 'name', value: 'Name' },
+    { key: 'protocol', value: 'Protocol' },
+    { key: 'port', value: 'Port' },
+    { key: 'rule', value: 'Rule' },
+  ]}"
+  rows="{rows}"
+>
+  <Toolbar>
+    <ToolbarContent>
+      <ToolbarSearch
+        persistent
+        value="round"
+        shouldFilterRows="{(row, value) => {
+          return (
+            /(6|8)$/.test(row.name) &&
+            row.rule.toLowerCase().includes(value.toLowerCase())
+          );
+        }}"
+      />
+      <ToolbarMenu>
+        <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
+        <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service">
+          API documentation
+        </ToolbarMenuItem>
+        <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
+      </ToolbarMenu>
+      <Button>Create balancer</Button>
+    </ToolbarContent>
+  </Toolbar>
+</DataTable>

docs/src/pages/framed/DataTable/DataTableFilterable.svelte

@@ -0,0 +1,46 @@
+<script>
+  import {
+    DataTable,
+    Toolbar,
+    ToolbarContent,
+    ToolbarSearch,
+    ToolbarMenu,
+    ToolbarMenuItem,
+    Button,
+  } from "carbon-components-svelte";
+
+  let rows = Array.from({ length: 10 }).map((_, i) => ({
+    id: i,
+    name: "Load Balancer " + (i + 1),
+    protocol: "HTTP",
+    port: 3000 + i * 10,
+    rule: i % 2 ? "Round robin" : "DNS delegation",
+  }));
+</script>
+
+<DataTable
+  sortable
+  title="Load balancers"
+  description="Your organization's active load balancers."
+  headers="{[
+    { key: 'name', value: 'Name' },
+    { key: 'protocol', value: 'Protocol' },
+    { key: 'port', value: 'Port' },
+    { key: 'rule', value: 'Rule' },
+  ]}"
+  rows="{rows}"
+>
+  <Toolbar>
+    <ToolbarContent>
+      <ToolbarSearch persistent value="round" shouldFilterRows />
+      <ToolbarMenu>
+        <ToolbarMenuItem primaryFocus>Restart all</ToolbarMenuItem>
+        <ToolbarMenuItem href="https://cloud.ibm.com/docs/loadbalancer-service">
+          API documentation
+        </ToolbarMenuItem>
+        <ToolbarMenuItem hasDivider danger>Stop all</ToolbarMenuItem>
+      </ToolbarMenu>
+      <Button>Create balancer</Button>
+    </ToolbarContent>
+  </Toolbar>
+</DataTable>