From 90b067ded3cfb00777806651dde4f3bce7685962 Mon Sep 17 00:00:00 2001
From: Eric Liu <ericyl.us@gmail.com>
Date: Sun, 20 Apr 2025 15:30:40 -0700
Subject: [PATCH] docs(data-table): improve docs

---
 docs/src/pages/components/DataTable.svx       | 145 +++++++++---------
 .../DataTableProgrammaticSorting.svelte       |  65 ++++----
 2 files changed, 108 insertions(+), 102 deletions(-)

diff --git a/docs/src/pages/components/DataTable.svx b/docs/src/pages/components/DataTable.svx
index 70c758e3..c3eb1c59 100644
--- a/docs/src/pages/components/DataTable.svx
+++ b/docs/src/pages/components/DataTable.svx
@@ -8,21 +8,20 @@ components: ["DataTable", "Pagination","Toolbar", "ToolbarContent", "ToolbarSear
   import Preview from "../../components/Preview.svelte";
 </script>
 
-`DataTable` is keyed for performance reasons.
+`DataTable` displays structured data in a tabular format. Use it to present large datasets with features like sorting, filtering, pagination, and row selection.
 
 <InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
-  <div class="body-short-01">Every <code>headers</code> object must have a unique "key" property.</div>
-</InlineNotification>
-
-<InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
-  <div class="body-short-01">Every <code>rows</code> object must have a unique "id" property.</div>
+  <div class="body-short-01">
+    This component is keyed for performance.
+    
+    Every <strong>headers</strong> object must have a unique "key" property.
+    <div class="body-short-01">Every <strong>rows</strong> object must have a unique "id" property.</div>
+  </div>
 </InlineNotification>
 
 ## Default
 
-The key value in `headers` corresponds to the key value defined in `rows`.
-
-For example, the header key `"name"` will use the value of `rows[index].name`.
+Create a basic table by providing `headers` and `rows` data. Match the `key` in headers with the corresponding property in rows.
 
 <DataTable
   headers="{[
@@ -79,9 +78,7 @@ For example, the header key `"name"` will use the value of `rows[index].name`.
 
 ## Slotted cells
 
-Use the `"cell"` slot to control the display value per table cell. Individual row and cell data are provided through the `let:row` and `let:cell` directives.
-
-The slot name for the table header cells is `"cell-header"`.
+Use the `"cell"` slot to customize cell content. Access row and cell data through `let:row` and `let:cell` directives. Use `"cell-header"` slot for header cells.
 
 <DataTable
   headers="{[
@@ -153,6 +150,8 @@ The slot name for the table header cells is `"cell-header"`.
 
 ## With title, description
 
+Add a title and description to provide context for the table data.
+
 <DataTable title="Load balancers" description="Your organization's active load balancers."
   headers="{[
     { key: "name", value: "Name" },
@@ -208,7 +207,7 @@ The slot name for the table header cells is `"cell-header"`.
 
 ## Slottable title, description
 
-The `title` and `description` props are slottable.
+Use slots to customize the title and description content.
 
 <DataTable
   headers="{[
@@ -270,7 +269,7 @@ The `title` and `description` props are slottable.
 
 ## Static width
 
-Set `useStaticWidth` to `true` to render the table with a width of "auto" instead of "100%".
+Set `useStaticWidth` to `true` to render the table with an auto width instead of 100%.
 
 <DataTable useStaticWidth
 title="Load balancers" description="Your organization's active load balancers."
@@ -328,9 +327,7 @@ title="Load balancers" description="Your organization's active load balancers."
 
 ## Custom column widths
 
-Specify a `width` or `minWidth` property in the `headers` object to customize the width of each column.
-
-A [table-layout: fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/table-layout#values) rule will be applied to the `table` element when using custom widths.
+Specify `width` or `minWidth` in the `headers` object to set column dimensions. This applies a fixed table layout.
 
 <InlineNotification svx-ignore lowContrast kind="warning" title="Note:" hideCloseButton>
   <div class="body-short-01">Custom column widths do not work with a <a class="bx--link" href="#sticky-header">sticky header</a>.</div>
@@ -340,9 +337,7 @@ A [table-layout: fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/table-l
 
 ## Sticky header
 
-Set `stickyHeader` to `true` for the header to be fixed in place.
-
-A maximum height will applied to the datatable to force a scrollbar.
+Set `stickyHeader` to `true` to fix the header in place. This adds a maximum height to force scrolling.
 
 <DataTable
   stickyHeader
@@ -363,6 +358,8 @@ A maximum height will applied to the datatable to force a scrollbar.
 
 ## With toolbar
 
+Add a toolbar with search, menu, and actions above the table.
+
 <DataTable title="Load balancers" description="Your organization's active load balancers."
   headers="{[
     { key: "name", value: "Name" },
@@ -432,6 +429,8 @@ A maximum height will applied to the datatable to force a scrollbar.
 
 ## With toolbar (small size)
 
+Use `size="short"` to create a more compact table with a small toolbar.
+
 <DataTable size="short" title="Load balancers" description="Your organization's active load balancers."
   headers="{[
     { key: "name", value: "Name" },
@@ -499,24 +498,22 @@ A maximum height will applied to the datatable to force a scrollbar.
 
 ## Filterable
 
-By default, `ToolbarSearch` will not filter `DataTable` rows.
+Set `shouldFilterRows` to `true` to enable client-side filtering. The default filter performs string comparisons on cell values.
 
-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.
-
-To use filtering with pagination, bind to the `filteredRowIds` prop and pass its length to `totalItems` in `Pagination`.
-
-Note that in-memory filtering is not optimal for large data sets, where you might consider using server-side search.
+For pagination with filtering, bind to `filteredRowIds` and pass its length to `Pagination`'s `totalItems`.
 
 <FileSource src="/framed/DataTable/DataTableFilterable" />
 
 ## Filterable (custom)
 
-`shouldFilterRows` also accepts a function and passes it the current row and search value. It expects the function to return a boolean.
+Pass a function to `shouldFilterRows` to implement custom filtering logic.
 
 <FileSource src="/framed/DataTable/DataTableFilterCustom" />
 
 ## Zebra stripes
 
+Set `zebra` to `true` to add alternating row colors.
+
 <DataTable zebra
   headers="{[
     { key: "name", value: "Name" },
@@ -572,6 +569,8 @@ Note that in-memory filtering is not optimal for large data sets, where you migh
 
 ## Tall rows
 
+Set `size="tall"` for increased row height.
+
 <DataTable size="tall"
   headers="{[
     { key: "name", value: "Name" },
@@ -627,6 +626,8 @@ Note that in-memory filtering is not optimal for large data sets, where you migh
 
 ## Medium rows
 
+Set `size="medium"` for standard row height.
+
 <DataTable size="medium"
   headers="{[
     { key: "name", value: "Name" },
@@ -682,6 +683,8 @@ Note that in-memory filtering is not optimal for large data sets, where you migh
 
 ## Short rows
 
+Set `size="short"` for compact row height.
+
 <DataTable size="short"
   headers="{[
     { key: "name", value: "Name" },
@@ -737,6 +740,8 @@ Note that in-memory filtering is not optimal for large data sets, where you migh
 
 ## Compact rows
 
+Set `size="compact"` for minimal row height.
+
 <DataTable size="compact"
   headers="{[
     { key: "name", value: "Name" },
@@ -792,11 +797,7 @@ Note that in-memory filtering is not optimal for large data sets, where you migh
 
 ## Sortable
 
-Set `sortable` to `true` to enable table column sorting.
-
-To disable sorting on a specific column, set `sort` to `false` in the header object passed to the `headers` prop.
-
-In the example below, the "Protocol" column is not sortable.
+Set `sortable` to `true` to enable column sorting. Disable sorting on specific columns by setting `sort: false` in the header object.
 
 <DataTable sortable
   headers="{[
@@ -853,12 +854,14 @@ In the example below, the "Protocol" column is not sortable.
 
 ## Sortable with pagination
 
-For pagination, bind to the `pageSize` and `page` props of `Pagination` and pass their values to `DataTable`.
+Bind to `pageSize` and `page` props of `Pagination` and pass them to `DataTable`.
 
 <FileSource src="/framed/DataTable/DataTablePagination" />
 
 ## Sortable with custom display and sort methods
 
+Use `display` and `sort` functions in header objects to customize cell rendering and sorting.
+
 <DataTable sortable title="Load balancers" description="Your organization's active load balancers."
   headers="{[
     { key: "name", value: "Name" },
@@ -926,6 +929,8 @@ For pagination, bind to the `pageSize` and `page` props of `Pagination` and pass
 
 ## Sortable with nested object values
 
+Access nested object properties using dot notation in the header key.
+
 <DataTable sortable title="Load balancers" description="Your organization's active load balancers."
            headers="{[
     { key: "name", value: "Name" },
@@ -1005,83 +1010,61 @@ For pagination, bind to the `pageSize` and `page` props of `Pagination` and pass
 
 ## 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.
+Use `sortKey` and `sortDirection` props to control sorting programmatically. Set `sortKey` to a valid header key and `sortDirection` to "none", "ascending", or "descending".
 
 <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.
-
-For an object in the `headers` array, set `empty` to `true` to render an empty column.
-
-In the following example, each row in the sortable data table has an overflow menu. There isn't a separate, useless table header column for the overflow menu.
+Set `empty: true` in a header object to create an empty column. Use this for overflow menus without a header.
 
 <FileSource src="/framed/DataTable/DataTableAppendColumns" />
 
 ## Selectable rows (checkbox)
 
-Set `selectable` to `true` for rows to be multi-selectable.
-
-Bind to `selectedRowIds` to get the ids of the selected rows.
-
-To customize the `input` name for the checkbox, use the `inputName` prop.
+Set `selectable` to `true` for multi-select functionality. Bind to `selectedRowIds` to track selections. Use `inputName` to customize checkbox names.
 
 <FileSource src="/framed/DataTable/SelectableDataTable" />
 
 ## Batch selection
 
-To enable batch selection, set `batchSelection` to `true`.
-
-This checkbox is used to select all rows. It enters an indeterminate state when some rows are selected.
+Set `batchSelection` to `true` to add a checkbox for selecting all rows. The checkbox shows an indeterminate state when some rows are selected.
 
 <FileSource src="/framed/DataTable/DataTableBatchSelection" />
 
 ## Batch selection with initial selected rows
 
-Use the `selectedRowIds` prop to specify which rows should be selected.
+Use `selectedRowIds` to specify initially selected rows.
 
 <FileSource src="/framed/DataTable/DataTableBatchSelectionInitial" />
 
 ## Batch selection with batch actions toolbar
 
+Add a toolbar for batch actions when rows are selected.
+
 <FileSource src="/framed/DataTable/DataTableBatchSelectionToolbar" />
 
 ## Batch selection with controlled toolbar
 
-By default, `ToolbarBatchActions` is activated if one or more rows is selected. Clicking "Cancel" will deactivate it.
-
-Use the `active` prop to control the toolbar. Note that it will still activate if one or more rows are selected.
-
-You can prevent the default "Cancel" behavior in the dispatched `on:cancel` event.
+Control the batch actions toolbar with the `active` prop. Prevent default cancel behavior in the `on:cancel` event.
 
 <FileSource src="/framed/DataTable/DataTableBatchSelectionToolbarControlled" />
 
 ## Selectable rows (radio)
 
-Set `radio` to `true` for only one row to be selected at a time.
-
-Bind to `selectedRowIds` to get the ids of the selected rows. Because it's radio selection, `selectedRowIds` will only contain one id.
-
-To customize the `input` name for the radio button, use the `inputName` prop.
+Set `radio` to `true` for single-row selection. Bind to `selectedRowIds` to track the selected row. Use `inputName` to customize radio button names.
 
 <FileSource src="/framed/DataTable/RadioSelectableDataTable" />
 
 ## Non-selectable rows
 
-Use `nonSelectableRowIds` to specify the ids for rows that should not be selectable.
+Use `nonSelectableRowIds` to prevent selection of specific rows.
 
 <FileSource src="/framed/DataTable/DataTableNonSelectableRows" />
 
 ## Expandable rows
 
-Set `expandable` to `true` for rows to be expandable.
+Set `expandable` to `true` to make rows expandable. Use the `expanded-row` slot to customize expanded content.
 
 <DataTable expandable
   headers="{[
@@ -1142,16 +1125,20 @@ Set `expandable` to `true` for rows to be expandable.
 
 ## Non-expandable rows
 
-Use `nonExpandableRowIds` to specify the ids for rows that should not be expandable.
+Use `nonExpandableRowIds` to prevent expansion of specific rows.
 
 <FileSource src="/framed/DataTable/DataTableNonExpandableRows" />
 
 ## Expandable (zebra styles)
 
+Combine expandable rows with zebra striping.
+
 <FileSource src="/framed/DataTable/DataTableExpandableZebra" />
 
 ## Expandable (compact size)
 
+Set `size="compact"` for expandable rows with minimal height.
+
 <DataTable size="compact" expandable
   headers="{[
     { key: "name", value: "Name" },
@@ -1211,6 +1198,8 @@ Use `nonExpandableRowIds` to specify the ids for rows that should not be expanda
 
 ## Expandable (short size)
 
+Set `size="short"` for expandable rows with compact height.
+
 <DataTable size="short" expandable
   headers="{[
     { key: "name", value: "Name" },
@@ -1270,6 +1259,8 @@ Use `nonExpandableRowIds` to specify the ids for rows that should not be expanda
 
 ## Expandable (tall size)
 
+Set `size="tall"` for expandable rows with increased height.
+
 <DataTable size="tall" expandable
   headers="{[
     { key: "name", value: "Name" },
@@ -1329,7 +1320,7 @@ Use `nonExpandableRowIds` to specify the ids for rows that should not be expanda
 
 ## Batch expansion
 
-Set `batchExpansion` to `true` for the ability to expand and collapse all rows at once.
+Set `batchExpansion` to `true` to expand and collapse all rows at once.
 
 <DataTable batchExpansion
   headers="{[
@@ -1390,42 +1381,54 @@ Set `batchExpansion` to `true` for the ability to expand and collapse all rows a
 
 ## Expandable and selectable rows
 
-The `batchExpansion` and `batchSelection` props can be used together.
+Combine `batchExpansion` and `batchSelection` for tables with both expandable and selectable rows.
 
 <FileSource src="/framed/DataTable/DataTableExpandableSelectable" />
 
 ## Skeleton
 
+Use `DataTableSkeleton` to show a loading state.
+
 <DataTableSkeleton />
 
 ## Skeleton with headers, row count
 
+Specify headers and row count for the skeleton.
+
 <DataTableSkeleton headers={["Name", "Protocol", "Port", "Rule"]} rows={10} />
 
 ## Skeleton with object headers
 
-`headers` can also be an array of objects. The type is the same as the `headers` prop type used in `DataTable`.
+Pass header objects to customize the skeleton.
 
 <DataTableSkeleton headers={[{ value: "Name" }, {value: "Protocol"}, {value:"Port"}, { value: "Rule"}]} rows={10} />
 
 ## Skeleton with empty header
 
-Pass an object with `"empty"` set to `true` to render an empty table header column.
+Add an empty header column with `empty: true`.
 
 <DataTableSkeleton headers={[{ value: "Name" }, {value: "Protocol"}, {value:"Port"}, { value: "Rule"}, { empty: true }]} rows={10} />
 
 ## Skeleton without header, toolbar
 
+Hide the header and toolbar in the skeleton.
+
 <DataTableSkeleton showHeader={false} showToolbar={false} />
 
 ## Skeleton (tall size)
 
+Set `size="tall"` for a taller skeleton.
+
 <DataTableSkeleton showHeader={false} showToolbar={false} size="tall" />
 
 ## Skeleton (short size)
 
+Set `size="short"` for a shorter skeleton.
+
 <DataTableSkeleton showHeader={false} showToolbar={false} size="short" />
 
 ## Skeleton (compact size)
 
+Set `size="compact"` for a minimal skeleton.
+
 <DataTableSkeleton showHeader={false} showToolbar={false} size="compact" />
\ No newline at end of file
diff --git a/docs/src/pages/framed/DataTable/DataTableProgrammaticSorting.svelte b/docs/src/pages/framed/DataTable/DataTableProgrammaticSorting.svelte
index 785487c7..998856dc 100644
--- a/docs/src/pages/framed/DataTable/DataTableProgrammaticSorting.svelte
+++ b/docs/src/pages/framed/DataTable/DataTableProgrammaticSorting.svelte
@@ -8,37 +8,40 @@
   $: 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>
+<div style="margin-bottom: 1rem">
+  <Button
+    size="sm"
+    kind="tertiary"
+    disabled={sortKey === "port" && sortDirection === "ascending"}
+    on:click={() => {
+      sortKey = "port";
+      sortDirection = "ascending";
+    }}
+  >
+    Sort "port" in ascending order
+  </Button>
+  <Button
+    size="sm"
+    kind="tertiary"
+    disabled={sortKey === "name" && sortDirection === "descending"}
+    on:click={() => {
+      sortKey = "name";
+      sortDirection = "descending";
+    }}
+  >
+    Sort "name" in descending order
+  </Button>
+  <Button
+    size="sm"
+    kind="ghost"
+    on:click={() => {
+      sortKey = null;
+      sortDirection = "none";
+    }}
+  >
+    Clear sorting
+  </Button>
+</div>
 
 <DataTable
   sortable