docs(table): updates component documentation (#349)

Kajabi · Dec 13, 2024 · 1326717 · 1326717
1 parent 7133840
commit 1326717
Show file tree

Hide file tree

Showing 11 changed files with 98 additions and 44 deletions.
diff --git a/libs/core/src/components.d.ts b/libs/core/src/components.d.ts
@@ -756,23 +756,23 @@ export namespace Components {
     }
     interface PdsTable {
         /**
-          * Determines if table displays compact which reduces the spacing of table cells.
+          * Determines if the table displays with reduced table cell padding.
          */
         "compact": boolean;
         /**
           * A unique identifier used for the table `id` attribute.
          */
         "componentId": string;
         /**
-          * Determines if table displays fixed column which fixes the first column of the table.
+          * Determines if the should display a fixed first column.
          */
         "fixedColumn": boolean;
         /**
           * Enables the table to be responsive by horizontally scrolling on smaller screens.
          */
         "responsive": boolean;
         /**
-          * Determines if table displays checkboxes for selectable rows.
+          * Determines if the table displays checkboxes for selectable rows.
          */
         "selectable": boolean;
     }
@@ -786,11 +786,12 @@ export namespace Components {
     }
     interface PdsTableHead {
         /**
-          * Indicates that the selection state is indeterminate.
+          * Determines if the select all checkbox is in an indeterminate state.
          */
         "indeterminate"?: boolean;
         /**
-          * A local state to track whether the row is currently selected.
+          * Determines if the table row is currently selected.
+          * @defaultValue false
          */
         "isSelected": boolean;
     }
@@ -802,11 +803,11 @@ export namespace Components {
     }
     interface PdsTableRow {
         /**
-          * Indicates that the selection state is indeterminate.
+          * Determines if the row selected is in an indeterminate state.
          */
         "indeterminate"?: boolean;
         /**
-          * A local state to track whether the row is currently selected.
+          * Determines if the table row is currently selected.
          */
         "isSelected"?: boolean;
     }
@@ -2244,15 +2245,15 @@ declare namespace LocalJSX {
     }
     interface PdsTable {
         /**
-          * Determines if table displays compact which reduces the spacing of table cells.
+          * Determines if the table displays with reduced table cell padding.
          */
         "compact"?: boolean;
         /**
           * A unique identifier used for the table `id` attribute.
          */
         "componentId": string;
         /**
-          * Determines if table displays fixed column which fixes the first column of the table.
+          * Determines if the should display a fixed first column.
          */
         "fixedColumn"?: boolean;
         /**
@@ -2268,7 +2269,7 @@ declare namespace LocalJSX {
          */
         "responsive"?: boolean;
         /**
-          * Determines if table displays checkboxes for selectable rows.
+          * Determines if the table displays checkboxes for selectable rows.
          */
         "selectable"?: boolean;
     }
@@ -2282,11 +2283,12 @@ declare namespace LocalJSX {
     }
     interface PdsTableHead {
         /**
-          * Indicates that the selection state is indeterminate.
+          * Determines if the select all checkbox is in an indeterminate state.
          */
         "indeterminate"?: boolean;
         /**
-          * A local state to track whether the row is currently selected.
+          * Determines if the table row is currently selected.
+          * @defaultValue false
          */
         "isSelected"?: boolean;
         /**
@@ -2306,11 +2308,11 @@ declare namespace LocalJSX {
     }
     interface PdsTableRow {
         /**
-          * Indicates that the selection state is indeterminate.
+          * Determines if the row selected is in an indeterminate state.
          */
         "indeterminate"?: boolean;
         /**
-          * A local state to track whether the row is currently selected.
+          * Determines if the table row is currently selected.
          */
         "isSelected"?: boolean;
         /**

diff --git a/libs/core/src/components/pds-table/docs/pds-table.mdx b/libs/core/src/components/pds-table/docs/pds-table.mdx
@@ -3,26 +3,49 @@ import { components } from '../../../../dist/docs.json';
 
 # Table
 
-The table compononent should be used to display tabular data.
+The table, consisting of rows and columns, is used to display and organize tabular data.
+
+## Guidelines
+
+### When to use
+
+- For displaying important data to users in an organized format.
+- When the organized data needs to be sorted.
+
+### When Not to Use
+
+- For building layouts. Please use [Box](/docs/components-layout-box--docs) and [Row](/docs/components-layout-row--docs) instead.
+
+### Accessibility
+
+Be sure to make proper use of the subcomponents to ensure that the table is accessible to screen reader users.
 
 ## Properties
 
 <DocArgsTable componentName="pds-table" docSource={components} />
 
 ### Head Cell
 
+The table header cell. Equivalent to the `<th>` element.
+
 <DocArgsTable componentName="pds-table-head-cell" docSource={components} />
 
 ### Row
 
+The table row. Equivalent to the `<tr>` element.
+
 <DocArgsTable componentName="pds-table-row" docSource={components} />
 
 ### Cell
 
+The table body cell. Equivalent to the `<td>` element.
+
 <DocArgsTable componentName="pds-table-cell" docSource={components} />
 
 ## Default
 
+The default table, properly using all subcomponents.
+
 <DocCanvas mdxSource={{
   react: `<PdsTable componentId="default">
     <PdsTableHead>
@@ -643,7 +666,7 @@ When the `fixed-column` prop is set to `true`, the first column of the table wil
 
 ### Fixed w/ Checkbox
 
-The `fixed-column` prop can be used in conjunction with the `selectable` prop to render an addition checkbox and they will both remain fixed in place while the rest of the table scrolls horizontally.
+The `fixed-column` prop can be used in conjunction with the `selectable` prop to render an additional checkbox, and they will both remain fixed in place while the rest of the table scrolls horizontally.
 
 <DocCanvas mdxSource={{
   react: `<PdsTable componentId="fixedcb" responsive={true} fixed-column={true} selectable={true}>
@@ -913,7 +936,7 @@ When the `truncate` prop is set to `true` on a `pds-table-cell` element, the cel
 
 Basic sorting can be enabled by adding the `sortable` attribute to a `pds-table-head-cell` element. The table will automatically sort in ascending or descending order when the cell is clicked.
 
-In cases where the default sorting functionality is not suitable, you can prevent it and use your own custom sorting mechanism by listening to the `pdsTableSort` event.
+In cases where the default sorting functionality is not suitable, it is possible to use a custom sorting function by listening to the `pdsTableSort` event.
 
 <DocCanvas mdxSource={{
   react: `<PdsTable componentId="sortable" selectable={true}>
@@ -1095,3 +1118,7 @@ In cases where the default sorting functionality is not suitable, you can preven
   </pds-table-body>
 </pds-table>
 </DocCanvas>
+
+## References
+
+[MDN: Table](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table)
diff --git a/libs/core/src/components/pds-table/pds-table-cell/pds-table-cell.tsx b/libs/core/src/components/pds-table/pds-table-cell/pds-table-cell.tsx
@@ -24,6 +24,10 @@ export class PdsTableCell {
    */
   @Prop() truncate: boolean;
 
+  /**
+   * Determines if the table is currently scrolling.
+   * @defaultValue false
+   */
   @State() private tableScrolling: boolean = false;
 
   private classNames() {

diff --git a/libs/core/src/components/pds-table/pds-table-head-cell/pds-table-head-cell.tsx b/libs/core/src/components/pds-table/pds-table-head-cell/pds-table-head-cell.tsx
@@ -21,11 +21,20 @@ export class PdsTableHeadCell {
    */
   @Event() pdsTableSort: EventEmitter<{ column: string; direction: string }>;
 
+  /**
+   * The direction of sorting.
+   */
   @State() private sortingDirection: 'asc' | 'desc' = 'asc';
+
+  /**
+   * Determines if the table is currently scrolling.
+   * @defaultValue false
+   */
   @State() private tableScrolling: boolean = false;
 
   /**
-   * A local state to track whether the row is currently selected.
+   * Determines if the table row is currently selected.
+   * @defaultValue false
    */
   @State() isSelected: boolean = false;
 

diff --git a/libs/core/src/components/pds-table/pds-table-head/pds-table-head.tsx b/libs/core/src/components/pds-table/pds-table-head/pds-table-head.tsx
@@ -10,11 +10,14 @@ export class PdsTableHead {
   @Element() hostElement: HTMLPdsTableHeadElement;
   private tableRef: HTMLPdsTableElement
 
-   /** Indicates that the selection state is indeterminate. */
-   @Prop({ mutable: true }) indeterminate?: boolean
+   /**
+    * Determines if the select all checkbox is in an indeterminate state.
+    */
+   @Prop({ mutable: true }) indeterminate?: boolean;
 
    /**
-   * A local state to track whether the row is currently selected.
+   * Determines if the table row is currently selected.
+   * @defaultValue false
    */
    @Prop({mutable: true}) isSelected: boolean;
 

diff --git a/libs/core/src/components/pds-table/pds-table-head/readme.md b/libs/core/src/components/pds-table/pds-table-head/readme.md
@@ -7,10 +7,10 @@
 
 ## Properties
 
-| Property        | Attribute       | Description                                                   | Type      | Default     |
-| --------------- | --------------- | ------------------------------------------------------------- | --------- | ----------- |
-| `indeterminate` | `indeterminate` | Indicates that the selection state is indeterminate.          | `boolean` | `undefined` |
-| `isSelected`    | `is-selected`   | A local state to track whether the row is currently selected. | `boolean` | `undefined` |
+| Property        | Attribute       | Description                                                         | Type      | Default     |
+| --------------- | --------------- | ------------------------------------------------------------------- | --------- | ----------- |
+| `indeterminate` | `indeterminate` | Determines if the select all checkbox is in an indeterminate state. | `boolean` | `undefined` |
+| `isSelected`    | `is-selected`   | Determines if the table row is currently selected.                  | `boolean` | `undefined` |
 
 
 ## Events

diff --git a/libs/core/src/components/pds-table/pds-table-row/pds-table-row.tsx b/libs/core/src/components/pds-table/pds-table-row/pds-table-row.tsx
@@ -12,12 +12,12 @@ export class PdsTableRow {
   private tableRef: HTMLPdsTableElement;
 
   /**
-   * Indicates that the selection state is indeterminate.
-   * */
-  @Prop({ mutable: true }) indeterminate?: boolean
+    * Determines if the row selected is in an indeterminate state.
+    */
+  @Prop({ mutable: true }) indeterminate?: boolean;
 
   /**
-   * A local state to track whether the row is currently selected.
+   * Determines if the table row is currently selected.
    */
   @Prop({ mutable: true }) isSelected?: boolean;
 

diff --git a/libs/core/src/components/pds-table/pds-table-row/readme.md b/libs/core/src/components/pds-table/pds-table-row/readme.md
@@ -7,10 +7,10 @@
 
 ## Properties
 
-| Property        | Attribute       | Description                                                   | Type      | Default     |
-| --------------- | --------------- | ------------------------------------------------------------- | --------- | ----------- |
-| `indeterminate` | `indeterminate` | Indicates that the selection state is indeterminate.          | `boolean` | `undefined` |
-| `isSelected`    | `is-selected`   | A local state to track whether the row is currently selected. | `boolean` | `undefined` |
+| Property        | Attribute       | Description                                                  | Type      | Default     |
+| --------------- | --------------- | ------------------------------------------------------------ | --------- | ----------- |
+| `indeterminate` | `indeterminate` | Determines if the row selected is in an indeterminate state. | `boolean` | `undefined` |
+| `isSelected`    | `is-selected`   | Determines if the table row is currently selected.           | `boolean` | `undefined` |
 
 
 ## Events

diff --git a/libs/core/src/components/pds-table/pds-table.tsx b/libs/core/src/components/pds-table/pds-table.tsx
@@ -9,7 +9,7 @@ export class PdsTable {
   @Element() el: HTMLPdsTableElement;
 
   /**
-   * Determines if table displays compact which reduces the spacing of table cells.
+   * Determines if the table displays with reduced table cell padding.
    */
   @Prop() compact: boolean;
 
@@ -24,16 +24,25 @@ export class PdsTable {
   @Prop() responsive: boolean;
 
   /**
-   * Determines if table displays fixed column which fixes the first column of the table.
+   * Determines if the should display a fixed first column.
    */
   @Prop() fixedColumn: boolean;
 
   /**
-   * Determines if table displays checkboxes for selectable rows.
+   * Determines if the table displays checkboxes for selectable rows.
    */
   @Prop() selectable: boolean;
 
+  /**
+   * The name of the column being sorted.
+   * @defaultValue null
+   */
   @State() sortingColumn: string | null = null;
+
+  /**
+   * The direction of sorting.
+   * @defaultValue 'asc'
+   */
   @State() sortingDirection: 'asc' | 'desc' = 'asc';
 
 

diff --git a/libs/core/src/components/pds-table/readme.md b/libs/core/src/components/pds-table/readme.md
@@ -7,13 +7,13 @@
 
 ## Properties
 
-| Property                   | Attribute      | Description                                                                          | Type      | Default     |
-| -------------------------- | -------------- | ------------------------------------------------------------------------------------ | --------- | ----------- |
-| `compact`                  | `compact`      | Determines if table displays compact which reduces the spacing of table cells.       | `boolean` | `undefined` |
-| `componentId` _(required)_ | `component-id` | A unique identifier used for the table `id` attribute.                               | `string`  | `undefined` |
-| `fixedColumn`              | `fixed-column` | Determines if table displays fixed column which fixes the first column of the table. | `boolean` | `undefined` |
-| `responsive`               | `responsive`   | Enables the table to be responsive by horizontally scrolling on smaller screens.     | `boolean` | `undefined` |
-| `selectable`               | `selectable`   | Determines if table displays checkboxes for selectable rows.                         | `boolean` | `undefined` |
+| Property                   | Attribute      | Description                                                                      | Type      | Default     |
+| -------------------------- | -------------- | -------------------------------------------------------------------------------- | --------- | ----------- |
+| `compact`                  | `compact`      | Determines if the table displays with reduced table cell padding.                | `boolean` | `undefined` |
+| `componentId` _(required)_ | `component-id` | A unique identifier used for the table `id` attribute.                           | `string`  | `undefined` |
+| `fixedColumn`              | `fixed-column` | Determines if the should display a fixed first column.                           | `boolean` | `undefined` |
+| `responsive`               | `responsive`   | Enables the table to be responsive by horizontally scrolling on smaller screens. | `boolean` | `undefined` |
+| `selectable`               | `selectable`   | Determines if the table displays checkboxes for selectable rows.                 | `boolean` | `undefined` |
 
 
 ## Events

diff --git a/libs/core/src/components/pds-table/stories/pds-table.stories.js b/libs/core/src/components/pds-table/stories/pds-table.stories.js
@@ -8,7 +8,7 @@ export default {
   decorators: [withActions],
   parameters: {
     actions: {
-      handles: ['onclick', 'pdsTableRowSelected', 'onclick', 'pdsTableSelectAll'],
+      handles: ['onclick', 'pdsTableRowSelected', 'onclick', 'pdsTableSelectAll', 'pdsTableSort'],
     },
   },
   title: 'components/Table',