@spectrum-web-components/table 0.0.2-table.2609 → 0.0.2-table.2625

package/README.md

@@ -42,7 +42,7 @@ import {
 To ensure that the table scrolls, make sure to add a `style` attribute to `<sp-table>` with your desired height. Otherwise, the table will automatically show all its items.
 
 ```html
-<sp-table size="m" style="height: 120px">
+<sp-table size="m">
     <sp-table-head>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
@@ -78,55 +78,12 @@ To ensure that the table scrolls, make sure to add a `style` attribute to `<sp-t
 </sp-table>
 ```
 
-## Sorting
-
-For each table column you want to sort, use the `sortable` attribute in its respective `<sp-table-head-cell>`. `sort-direction="asc"|"desc"` specifies the direction the sort goes, in either ascending or descending order, respectively. The `@sorted` event listener on `<sp-table>` can be utilised to specify a method to fire when the `<sp-table-head-cell>` dispatches the `sorted` event. To specify which aspect of an item you'd like to sort by, use the `sort-key` attribute.
-
-```html
-<sp-table size="m" style="height: 120px">
-    <sp-table-head>
-        <sp-table-head-cell sortable sort-direction="asc">
-            Column Title
-        </sp-table-head-cell>
-        <sp-table-head-cell>Column Title</sp-table-head-cell>
-        <sp-table-head-cell>Column Title</sp-table-head-cell>
-    </sp-table-head>
-    <sp-table-body>
-        <sp-table-row>
-            <sp-table-cell>Row Item Bravo</sp-table-cell>
-            <sp-table-cell>Row Item Bravo</sp-table-cell>
-            <sp-table-cell>Row Item Bravo</sp-table-cell>
-        </sp-table-row>
-        <sp-table-row>
-            <sp-table-cell>Row Item Alpha</sp-table-cell>
-            <sp-table-cell>Row Item Alpha</sp-table-cell>
-            <sp-table-cell>Row Item Alpha</sp-table-cell>
-        </sp-table-row>
-        <sp-table-row>
-            <sp-table-cell>Row Item Charlie</sp-table-cell>
-            <sp-table-cell>Row Item Charlie</sp-table-cell>
-            <sp-table-cell>Row Item Charlie</sp-table-cell>
-        </sp-table-row>
-        <sp-table-row>
-            <sp-table-cell>Row Item Delta</sp-table-cell>
-            <sp-table-cell>Row Item Delta</sp-table-cell>
-            <sp-table-cell>Row Item Delta</sp-table-cell>
-        </sp-table-row>
-        <sp-table-row>
-            <sp-table-cell>Row Item Echo</sp-table-cell>
-            <sp-table-cell>Row Item Echo</sp-table-cell>
-            <sp-table-cell>Row Item Echo</sp-table-cell>
-        </sp-table-row>
-    </sp-table-body>
-</sp-table>
-```
-
 ## Selection
 
 To manage selection on an `<sp-table>`, utilise the `selects` attribute on `<sp-table>`. Each `<sp-table-row>` has a `value` attribute which, by default, corresponds to its index in the table, and these `value`s tell `<sp-table>` which `<sp-table-row>`s are selected. The selected items can be manually fed in through the `.selected` attribute on the table.
 
 ```html
-<sp-table size="m" style="height: 120px">
+<sp-table size="m">
     <sp-table-head>
         <sp-table-head-cell sortable sort>Column Title</sp-table-head-cell>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
@@ -169,8 +126,8 @@ To manage selection on an `<sp-table>`, utilise the `selects` attribute on `<sp-
     size="m"
     selects="single"
     selected='["row1"]'
-    style="height: 120px"
-    onchange="spAlert(`Selected: ${JSON.stringify(this.selected)`)"
+    style="height: 200px"
+    onchange="spAlert(this, `Selected: ${JSON.stringify(this.selected)}`)"
 >
     <sp-table-head>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
@@ -214,10 +171,10 @@ When `selects` is set to "multiple", the `<sp-table-checkbox-cell>` in `<sp-tabl
 ```html
 <sp-table
     size="m"
-    style="height: 120px"
+    style="height: 200px"
     selects="multiple"
     selected='["row1", "row2"]'
-    onchange="spAlert(`Selected: ${JSON.stringify(this.selected)`)"
+    onchange="spAlert(this, `Selected: ${JSON.stringify(this.selected)}`)"
 >
     <sp-table-head>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
@@ -262,6 +219,8 @@ For large amounts of data, the `<sp-table>` can be virtualised to easily add tab
 <sp-table
     size="m"
     id="table-virtualized-demo"
+    style="height: 200px"
+    scroller="true"
 >
     <sp-table-head>
         <sp-table-head-cell>Column Title</sp-table-head-cell>
@@ -296,7 +255,9 @@ For large amounts of data, the `<sp-table>` can be virtualised to easily add tab
             return [cell1, cell2, cell3];
         }
     };
-    setTimeout(initTable, 500);
+    customElements.whenDefined('sp-table').then(() => {
+        initTable();
+    });
 </script>
 ```
 
@@ -314,7 +275,6 @@ For large amounts of data, the `<sp-table>` can be virtualised to easily add tab
         return items;
     }
 
-    }
     const initTable = () => {
         const table = document.querySelector('#table-virtualized-demo');
         table.items = initItems(50);
@@ -329,12 +289,14 @@ For large amounts of data, the `<sp-table>` can be virtualised to easily add tab
             return [cell1, cell2, cell3];
         }
     };
-    setTimeout(initTable, 500);
+    customElements.whenDefined('sp-table').then(() => {
+        initTable();
+    });
 </script>
 
 ### How to use it
 
-The virtualised table takes `.items`, an array of type `Record`, where the key is a `string` and the value can be whatever you'd like. `.items` is then fed into the `renderItem` method, which takes an `item` and its `index` as parameters and renders the `<sp-table-row>` for each item. An example is as follows:
+The virtualised table takes `items` as either a property or a JSON-encoded string, an array of type `Record`, where the key is a `string` and the value can be whatever you'd like. `items` is then fed into the `renderItem` method, which takes an `item` and its `index` as parameters and renders the `<sp-table-row>` for each item. An example is as follows:
 
 ```javascript
 const renderItem = (item: Item, index: number): TemplateResult => {
@@ -346,19 +308,145 @@ const renderItem = (item: Item, index: number): TemplateResult => {
 };
 ```
 
-`.renderItem` is then included as a property of `<sp-table>`, along with the `.items`, to render a full `<sp-table>` without excessive manual HTML writing.
+`renderItem` is then included as a property of `<sp-table>`, along with the `items`, to render a full `<sp-table>` without excessive manual HTML writing.
+
+You can also render a different cell at a particular index by doing something like below:
+
+```javascript
+const renderItem = (item: Item, index: number): TemplateResult => {
+    if (index === 15) {
+        return html`
+            <sp-table-cell style="text-align: center">Custom Row</sp-table-cell>
+        `;
+    }
+    return html`
+        <sp-table-cell>Row Item ${item.name}</sp-table-cell>
+        <sp-table-cell>Row Item ${item.date}</sp-table-cell>
+        <sp-table-cell>Row Item ${index}</sp-table-cell>
+    `;
+};
+```
 
 Please note that there is a bug when attempting to select all virtualised elements. The items are selected programatically, it's just not reflected visually.
 
-## TO-DO:
+### The `scroller` property
+
+By default, the virtualized table doesn't contain a scroll bar and will display the entire length of the table body. Use the `scroller` property and specify an inline style for the height to get a `Table` of your desired height that scrolls.
+
+## Sorting on the Virtualized Table
+
+The virtualized table supports sorting its elements.
+
+For each table column you want to sort, use the `sortable` attribute in its respective `<sp-table-head-cell>`. `sort-direction="asc"|"desc"` specifies the direction the sort goes, in either ascending or descending order, respectively. The `@sorted` event listener on `<sp-table>` can be utilised to specify a method to fire when the `<sp-table-head-cell>` dispatches the `sorted` event. To specify which aspect of an item you'd like to sort by, use the `sort-key` attribute.
+
+```html-live
+<sp-table
+    size="m"
+    id="sorted-virtualized-table"
+    style="height: 200px"
+    scroller="true"
+>
+    <sp-table-head>
+        <sp-table-head-cell sortable sort-direction="desc" sort-key="name">
+            Sortable Column
+        </sp-table-head-cell>
+        <sp-table-head-cell>Non-sortable Column</sp-table-head-cell>
+        <sp-table-head-cell>Non-sortable Column</sp-table-head-cell>
+    </sp-table-head>
+</sp-table>
+<script type="module">
+    const initItems = (count) => {
+        const total = count;
+        const items = [];
+        while (count) {
+            count--;
+            items.push({
+                name: String(total - count),
+                date: count,
+            });
+        }
+        return items;
+    }
+
+    let items = initItems(50);
 
-Scrolling w/ screenreader on virtualised table elements
+    const initTable = () => {
+        const table = document.querySelector('#sorted-virtualized-table');
 
-NOT CURRENTLY NEEDED but still important:
+        table.items = items;
 
-1. multiselects via attributes (not required for Express delivery)
-2. Update checkbox element to dispatch event correctly
-3. Non-virtual sorting (ie sort data supplied through the DOM)
-4. Handle the console error that happens when we don't use Virtualizer
-5. Manage sort internally & prevent sort events
-6. Preventing change events
+        table.renderItem = (item, index) => {
+            const cell1 = document.createElement('sp-table-cell');
+            const cell2 = document.createElement('sp-table-cell');
+            const cell3 = document.createElement('sp-table-cell');
+            cell1.textContent = `Row Item Alpha ${item.name}`;
+            cell2.textContent = `Row Item Beta ${item.date}`;
+            cell3.textContent = `Index: ${index}`;
+            return [cell1, cell2, cell3];
+        }
+        table.addEventListener('sorted', (event) => {
+            const { sortDirection, sortKey } = event.detail;
+            items = items.sort((a, b) => {
+                const first = String(a[sortKey]);
+                const second = String(b[sortKey]);
+                return sortDirection === 'asc'
+                    ? first.localeCompare(second)
+                    : second.localeCompare(first);
+            });
+            table.items = [...items];
+        });
+    };
+
+    customElements.whenDefined('sp-table').then(() => {
+        initTable();
+    });
+</script>
+```
+
+<script type="module">
+    const initItems = (count) => {
+        const total = count;
+        const items = [];
+        while (count) {
+            count--;
+            items.push({
+                name: String(total - count),
+                date: count,
+            });
+        }
+        return items;
+    }
+
+    let items = initItems(50);
+
+    const initTable = () => {
+        const table = document.querySelector('#sorted-virtualized-table');
+
+        table.items = items;
+
+        table.renderItem = (item, index) => { 
+            const cell1 = document.createElement('sp-table-cell');
+            const cell2 = document.createElement('sp-table-cell');
+            const cell3 = document.createElement('sp-table-cell');
+            cell1.textContent = `Row Item Alpha ${item.name}`;
+            cell2.textContent = `Row Item Beta ${item.date}`;
+            cell3.textContent = `Index: ${index}`;
+            return [cell1, cell2, cell3];
+        }
+        table.addEventListener('sorted', (event) => {
+            const { sortDirection, sortKey } = event.detail;
+            items = items.sort((a, b) => {
+                const first = String(a[sortKey]);
+                const second = String(b[sortKey]);
+                return sortDirection === 'asc'
+                    ? first.localeCompare(second)
+                    : second.localeCompare(first);
+            });
+            table.items = [...items];
+        });
+    };
+
+    customElements.whenDefined('sp-table').then(() => {
+        initTable();
+    });
+</script>

package/custom-elements.json

@@ -183,6 +183,7 @@
                 "text": "undefined | 'single' | 'multiple'"
               },
               "privacy": "public",
+              "description": "Whether the Table allows users to select a row or rows, and thus controls whether or not the Table also renders checkboxes.",
               "attribute": "selects",
               "reflects": true
             },
@@ -194,6 +195,7 @@
               },
               "privacy": "public",
               "default": "[]",
+              "description": "An array of <sp-row> values that have been selected.",
               "attribute": "selected"
             },
             {
@@ -210,14 +212,27 @@
               },
               "privacy": "public",
               "default": "[]",
+              "description": "The content of the rows rendered by the virtualized table. The key is the value of the sp-table-row, and the value is the sp-table-row's content (not the row itself).",
               "attribute": "items"
             },
             {
               "kind": "field",
               "name": "itemValue",
               "privacy": "public",
+              "description": "The value of an item. By default, it is set to the index of the sp-table-row.",
               "attribute": "itemValue"
             },
+            {
+              "kind": "field",
+              "name": "scroller",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "default": "false",
+              "description": "Whether or not the virtualized table has a scroll bar. If this is set to true, make sure to specify a height in the sp-table's inline styles.",
+              "attribute": "scroller"
+            },
             {
               "kind": "field",
               "name": "tableBody",
@@ -234,6 +249,22 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "tableHead",
+              "type": {
+                "text": "TableHead"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "tableRows",
+              "type": {
+                "text": "TableRow[]"
+              },
+              "privacy": "private"
+            },
             {
               "kind": "field",
               "name": "isVirtualized",
@@ -302,6 +333,24 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "manageHeadCheckbox",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "allSelected",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "handleChange",
@@ -364,12 +413,17 @@
               "name": "change",
               "type": {
                 "text": "Event"
-              }
+              },
+              "description": "Announces a change in the `selected` property of a table row"
             },
             {
               "type": {
                 "text": "RangeChangedEvent"
               }
+            },
+            {
+              "description": "Announces a change in the range of visible cells on the table body",
+              "name": "rangeChanged"
             }
           ],
           "attributes": [
@@ -386,6 +440,7 @@
               "type": {
                 "text": "undefined | 'single' | 'multiple'"
               },
+              "description": "Whether the Table allows users to select a row or rows, and thus controls whether or not the Table also renders checkboxes.",
               "fieldName": "selects"
             },
             {
@@ -394,6 +449,7 @@
                 "text": "string[]"
               },
               "default": "[]",
+              "description": "An array of <sp-row> values that have been selected.",
               "fieldName": "selected"
             },
             {
@@ -402,11 +458,22 @@
                 "text": "Record<string, unknown>[]"
               },
               "default": "[]",
+              "description": "The content of the rows rendered by the virtualized table. The key is the value of the sp-table-row, and the value is the sp-table-row's content (not the row itself).",
               "fieldName": "items"
             },
             {
               "name": "itemValue",
+              "description": "The value of an item. By default, it is set to the index of the sp-table-row.",
               "fieldName": "itemValue"
+            },
+            {
+              "name": "scroller",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether or not the virtualized table has a scroll bar. If this is set to true, make sure to specify a height in the sp-table's inline styles.",
+              "fieldName": "scroller"
             }
           ],
           "superclass": {
@@ -505,17 +572,6 @@
               "default": "'gridcell'",
               "attribute": "role",
               "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "public",
-              "default": "-1",
-              "attribute": "tabIndex",
-              "reflects": true
             }
           ],
           "attributes": [
@@ -526,14 +582,6 @@
               },
               "default": "'gridcell'",
               "fieldName": "role"
-            },
-            {
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "default": "-1",
-              "fieldName": "tabIndex"
             }
           ],
           "superclass": {
@@ -575,17 +623,6 @@
               "attribute": "role",
               "reflects": true
             },
-            {
-              "kind": "field",
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "public",
-              "default": "-1",
-              "attribute": "tabIndex",
-              "reflects": true
-            },
             {
               "kind": "field",
               "name": "checkbox",
@@ -634,6 +671,16 @@
               "default": "false",
               "attribute": "selects-single",
               "reflects": true
+            },
+            {
+              "kind": "method",
+              "name": "handleChange",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             }
           ],
           "events": [
@@ -653,14 +700,6 @@
               "default": "'gridcell'",
               "fieldName": "role"
             },
-            {
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "default": "-1",
-              "fieldName": "tabIndex"
-            },
             {
               "name": "indeterminate",
               "type": {
@@ -867,17 +906,6 @@
               "default": "''",
               "attribute": "sort-key"
             },
-            {
-              "kind": "field",
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "privacy": "public",
-              "default": "-1",
-              "attribute": "tabIndex",
-              "reflects": true
-            },
             {
               "kind": "method",
               "name": "handleClick",
@@ -894,7 +922,8 @@
               "name": "sorted",
               "type": {
                 "text": "CustomEvent"
-              }
+              },
+              "description": "Announces that the table head has been sorted and handles the sorted event"
             }
           ],
           "attributes": [
@@ -928,14 +957,6 @@
               },
               "default": "''",
               "fieldName": "sortKey"
-            },
-            {
-              "name": "tabIndex",
-              "type": {
-                "text": "number"
-              },
-              "default": "-1",
-              "fieldName": "tabIndex"
             }
           ],
           "superclass": {
@@ -1034,6 +1055,12 @@
               }
             }
           ],
+          "events": [
+            {
+              "description": "Announces that `selected` of the table row has changed",
+              "name": "sorted"
+            }
+          ],
           "attributes": [
             {
               "name": "role",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spectrum-web-components/table",
-    "version": "0.0.2-table.2609+8b4f9a13c",
+    "version": "0.0.2-table.2625+0c83ba2e6",
     "publishConfig": {
         "access": "public"
     },
@@ -23,19 +23,12 @@
         ".": "./src/index.js",
         "./src/*": "./src/*.js",
         "./package.json": "./package.json",
-        "./sp-table-body": "./sp-table-body.js",
         "./sp-table-body.js": "./sp-table-body.js",
-        "./sp-table-cell": "./sp-table-cell.js",
         "./sp-table-cell.js": "./sp-table-cell.js",
-        "./sp-table-checkbox-cell": "./sp-table-checkbox-cell.js",
         "./sp-table-checkbox-cell.js": "./sp-table-checkbox-cell.js",
-        "./sp-table-head": "./sp-table-head.js",
         "./sp-table-head.js": "./sp-table-head.js",
-        "./sp-table-head-cell": "./sp-table-head-cell.js",
         "./sp-table-head-cell.js": "./sp-table-head-cell.js",
-        "./sp-table-row": "./sp-table-row.js",
         "./sp-table-row.js": "./sp-table-row.js",
-        "./sp-table": "./sp-table.js",
         "./sp-table.js": "./sp-table.js"
     },
     "scripts": {
@@ -70,5 +63,5 @@
     "sideEffects": [
         "./sp-*.js"
     ],
-    "gitHead": "8b4f9a13ca09b7a0e0e966cc8a9ebfdff8b3b565"
+    "gitHead": "0c83ba2e61dcd1713c08495ea92ee1a8531c1123"
 }

package/src/Table.d.ts

@@ -1,4 +1,6 @@
 import { CSSResultArray, PropertyValues, SpectrumElement, TemplateResult } from '@spectrum-web-components/base';
+import '../sp-table-row.js';
+import '../sp-table-checkbox-cell.js';
 interface Range {
     first: number;
     last: number;
@@ -11,6 +13,9 @@ export declare class RangeChangedEvent extends Event {
 }
 /**
  * @element sp-table
+ *
+ * @fires rangeChanged - Announces a change in the range of visible cells on the table body
+ * @event change - Announces a change in the `selected` property of a table row
  */
 export declare class Table extends SpectrumElement {
     static get styles(): CSSResultArray;
@@ -18,13 +23,31 @@ export declare class Table extends SpectrumElement {
     set renderItem(fn: (item: Record<string, unknown>, index: number) => TemplateResult);
     private _renderItem;
     role: string;
+    /**
+     * Whether the Table allows users to select a row or rows, and thus controls whether or not the Table also renders checkboxes.
+     */
     selects: undefined | 'single' | 'multiple';
+    /**
+     * An array of <sp-row> values that have been selected.
+     */
     selected: string[];
     private selectedSet;
+    /**
+     * The content of the rows rendered by the virtualized table. The key is the value of the sp-table-row, and the value is the sp-table-row's content (not the row itself).
+     */
     items: Record<string, unknown>[];
+    /**
+     * The value of an item. By default, it is set to the index of the sp-table-row.
+     */
     itemValue: (_item: unknown, index: number) => string;
+    /**
+     * Whether or not the virtualized table has a scroll bar. If this is set to true, make sure to specify a height in the sp-table's inline styles.
+     */
+    scroller: boolean;
     private tableBody?;
     private tableHeadCheckboxCell?;
+    private get tableHead();
+    private get tableRows();
     private get isVirtualized();
     focus(): void;
     private selectAllRows;
@@ -32,6 +55,7 @@ export declare class Table extends SpectrumElement {
     protected manageSelects(): void;
     protected manageSelected(): void;
     protected manageCheckboxes(): void;
+    protected manageHeadCheckbox(allSelected: boolean): void;
     protected handleChange(event: Event): void;
     scrollToIndex(index?: number): void;
     protected render(): TemplateResult;