docs(data-table): add "Programmatic sorting" example

docs/src/pages/components/DataTable.svx

@@ -1075,6 +1075,18 @@ and then limit displayed content by using `pageSize` and `page` props, which are
   ]}"
 />
 
+### Programmatic sorting
+
+Use the reactive `sortKey` and `sortDirection` props for programmatic sorting.
+
+By default, the table is not sorted by a specific key. The `sortKey` value must be a valid `key` specified in the `headers` object.
+
+Possible values for `sortDirection` include `"none"` or `"ascending"` or `"descending"`.
+
+Setting `sortKey` to `null` and `sortDirection` to `"none"` should reset the table rows to their initial order.
+
+<FileSource src="/framed/DataTable/DataTableProgrammaticSorting" />
+
 ### Empty column with overflow menu
 
 Some use cases require an empty column in the table body without a corresponding table header.

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

@@ -0,0 +1,97 @@
+<script>
+  import { DataTable, Button } from "carbon-components-svelte";
+
+  let sortKey = "port";
+  let sortDirection = "ascending";
+
+  $: console.log("sortKey", sortKey);
+  $: console.log("sortDirection", sortDirection);
+</script>
+
+<Button
+  kind="tertiary"
+  disabled="{sortKey === 'port' && sortDirection === 'ascending'}"
+  on:click="{() => {
+    sortKey = 'port';
+    sortDirection = 'ascending';
+  }}"
+>
+  Sort "port" in ascending order
+</Button>
+
+<Button
+  kind="tertiary"
+  disabled="{sortKey === 'name' && sortDirection === 'descending'}"
+  on:click="{() => {
+    sortKey = 'name';
+    sortDirection = 'descending';
+  }}"
+>
+  Sort "name" in descending order
+</Button>
+
+<Button
+  kind="ghost"
+  on:click="{() => {
+    sortKey = null;
+    sortDirection = 'none';
+  }}"
+>
+  Clear sorting
+</Button>
+
+<DataTable
+  sortable
+  bind:sortKey
+  bind:sortDirection
+  headers="{[
+    { key: 'name', value: 'Name' },
+    { key: 'protocol', value: 'Protocol', sort: false },
+    { key: 'port', value: 'Port' },
+    { key: 'rule', value: 'Rule' },
+  ]}"
+  rows="{[
+    {
+      id: 'a',
+      name: 'Load Balancer 3',
+      protocol: 'HTTP',
+      port: 3000,
+      rule: 'Round robin',
+    },
+    {
+      id: 'b',
+      name: 'Load Balancer 1',
+      protocol: 'HTTP',
+      port: 443,
+      rule: 'Round robin',
+    },
+    {
+      id: 'c',
+      name: 'Load Balancer 2',
+      protocol: 'HTTP',
+      port: 80,
+      rule: 'DNS delegation',
+    },
+    {
+      id: 'd',
+      name: 'Load Balancer 6',
+      protocol: 'HTTP',
+      port: 3000,
+      rule: 'Round robin',
+    },
+    {
+      id: 'e',
+      name: 'Load Balancer 4',
+      protocol: 'HTTP',
+      port: 443,
+      rule: 'Round robin',
+    },
+    {
+      id: 'f',
+      name: 'Load Balancer 5',
+      protocol: 'HTTP',
+      port: 80,
+      rule: 'DNS delegation',
+    },
+  ]}"
+/>