feat(data-table): support programmatic sorting (#1337)

* refactor(data-table): pass down sortable props instead of using context

* feat(data-table): support programmatic sorting

* test(data-table): assert new props

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

* refactor(data-table): remove unused tableSortable store

* refactor(data-table): remove unused indices

docs/src/COMPONENT_API.json

@@ -2421,6 +2421,30 @@
           "constant": false,
           "reactive": false
         },
+        {
+          "name": "sortKey",
+          "kind": "let",
+          "description": "Specify the header key to sort by",
+          "type": "DataTableKey",
+          "value": "null",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": true
+        },
+        {
+          "name": "sortDirection",
+          "kind": "let",
+          "description": "Specify the sort direction",
+          "type": "\"none\" | \"ascending\" | \"descending\"",
+          "value": "\"none\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": true
+        },
         {
           "name": "expandable",
           "kind": "let",
@@ -11843,9 +11867,33 @@
       "filePath": "src/DataTable/TableHeader.svelte",
       "props": [
         {
-          "name": "disableSorting",
+          "name": "sortable",
           "kind": "let",
-          "description": "Set to `true` to disable sorting on this specific cell",
+          "description": "Set to `true` for the sortable variant",
+          "type": "boolean",
+          "value": "false",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "sortDirection",
+          "kind": "let",
+          "description": "Specify the sort direction",
+          "type": "\"none\" | \"ascending\" | \"descending\"",
+          "value": "\"none\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "active",
+          "kind": "let",
+          "description": "Set to `true` if the column sorting",
           "type": "boolean",
           "value": "false",
           "isFunction": false,

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',
+    },
+  ]}"
+/>