AdvancedTable - Column reordering - Docs (#3194)

Co-authored-by: Jory Tindall <[email protected]>
Co-authored-by: shleewhite <[email protected]>

Author: 3 people

website/cspell-config/project-words.txt

@@ -67,6 +67,7 @@ Wireframes
 wireframing
 workramp
 nullvoxpopuli
+reorderable
 
 # Component-specific
 dont

website/docs/components/table/advanced-table/partials/accessibility/accessibility.md

@@ -145,6 +145,40 @@ Focus will be moved to the resize border. Use the right and left arrow keys to i
 
 ![Keyboard focus on the resize border for the column.](/assets/components/table/advanced-table/advanced-table-keyboard-action-mode-resize-border.png)
 
+### Reordering columns
+
+<Doc::Badge @type="neutral">Tab</Doc::Badge>
+
+While in Action Mode, Tab to the context menu.
+
+![Keyboard focus on the context menu within the column header.](/assets/components/table/advanced-table/advanced-table-keyboard-action-reorder.png)
+
+<Doc::Badge @type="neutral">Enter</Doc::Badge>
+
+Press Enter to open the context menu.
+
+![The open context menu with the move column option.](/assets/components/table/advanced-table/advanced-table-keyboard-action-reorder-context-menu.png)
+
+<Doc::Badge @type="neutral">Tab</Doc::Badge>
+
+With the context menu open, press Tab to select the `Move column` option.
+
+![Keyboard focus on the move column option in the context menu.](/assets/components/table/advanced-table/advanced-table-keyboard-action-reorder-move-column.png)
+
+<Doc::BadgeGroup>
+  <Doc::Badge @type="neutral">
+    <Hds::Icon @name="arrow-left" @title="Left arrow" />
+  </Doc::Badge>
+  <Doc::Badge @type="neutral">
+    <Hds::Icon @name="arrow-right" @title="Right` arrow" />
+  </Doc::Badge>
+</Doc::BadgeGroup>
+
+Focus will be moved to the reorder handle. Use the right and left arrow keys to move the column to the next or previous position.
+
+![Keyboard focus on the reorder handle for the column.](/assets/components/table/advanced-table/advanced-table-keyboard-action-reorder-drag-handle.png)
+
+
 ### Row selection
 
 You should clearly communicate to the user how many rows are selected and how many rows there are total outside of the Advanced Table. For additional considerations, read the [Multi-select usability and accessibility considerations](/components/table/advanced-table?tab=code#usability-and-accessibility-considerations).

website/docs/components/table/advanced-table/partials/code/component-api.md

@@ -78,9 +78,26 @@ The Advanced Table component itself is where most of the options will be applied
       </C.Property>
     </Doc::ComponentApi>
   </C.Property>
+  <C.Property @name="columnOrder" @type="array">
+    Array of column keys that determines the initial order of table columns. Keys in this array must match `key` values present in objects in the `columns` argument.
+  </C.Property>
+  <C.Property @name="hasReorderableColumns" @type="boolean" @default="false">
+    If set to `true`, allows users to reorder columns either by clicking and dragging on the column reorder handle with a mouse, or by moving focus to the handle with a keyboard and using the right and left arrow keys.
+  </C.Property>
+  <C.Property @name="reorderedMessageText" @type="string" @default="Moved (label) column to (position)">
+    Customizable text added to `caption` element when a column reorder is performed.
+  </C.Property>
   <C.Property @name="hasResizableColumns" @type="boolean" @default="false">
     If set to `true`, allows users to resize columns either by clicking and dragging on the column border with a mouse, or by moving focus to the resize border with a keyboard and using the right and left arrow keys.
   </C.Property>
+  <C.Property @name="onColumnReorder" @type="function">
+    Use in conjunction with `hasReorderableColumns` to pass a callback function to know the updated column order after a reorder event.
+    <br /><br />
+    When called, this function receives one positional argument:
+    <ul>
+    <li>an array of reordered column keys (e.g., `['name', 'age', 'height']`).</li>
+    </ul>
+  </C.Property>
   <C.Property @name="onColumnResize" @type="function">
     Use in conjunction with `hasResizableColumns` to pass a callback function to know the updated width of a resized column.
     <br /><br />

website/docs/components/table/advanced-table/partials/code/how-to-use.md

@@ -148,7 +148,40 @@ Similar to the basic Advanced Table, you can insert your own content into the `:
 </Hds::AdvancedTable>
 ```
 
-### Resizable Columns
+### Reordering columns
+
+!!! Info
+
+Reorderable columns are not supported in instances of the Advanced Table that have nested rows or sticky columns.
+!!!
+
+Set the `@hasReorderableColumns` argument to `true` in order to make columns reorderable either by clicking and dragging on the column reorder handle, or by moving focus to the handle and using the right and left arrow keys.
+
+Columns will render in the order they appear in the `@columns` array. However, this order can be overridden by providing an array of column keys to the `@columnOrder` argument.
+
+Optionally, the `@onColumnReorder` attribute accepts a callback function that receives the updated column key order.
+
+```handlebars
+<Hds::AdvancedTable
+  @model={{this.model.myDemoData}}
+  @hasReorderableColumns={{true}}
+  @columns={{array
+    (hash key="artist" label="Artist" isSortable=true)
+    (hash key="album" label="Album" isSortable=true)
+    (hash key="year" label="Release Year")
+  }}
+>
+  <:body as |B|>
+    <B.Tr>
+      <B.Td>{{B.data.artist}}</B.Td>
+      <B.Td>{{B.data.album}}</B.Td>
+      <B.Td>{{B.data.year}}</B.Td>
+    </B.Tr>
+  </:body>
+</Hds::AdvancedTable>
+```
+
+### Resizing Columns
 
 !!! Info
 
@@ -271,13 +304,6 @@ How resizing for the cell content works is determined by the implementation. For
 
 ### Sortable Advanced Table
 
-!!! Insight
-
-**Code tip**
-
-This component takes advantage of the `sort-by` helper provided by [@nullvoxpopuli/ember-composable-helpers](https://github.com/NullVoxPopuli/ember-composable-helpers)
-!!!
-
 !!! Callout
 
 At this time, the Advanced Table does not support sortable nested rows. If this is a use case you require, please [contact the Design Systems Team](/about/support).

website/docs/components/table/advanced-table/partials/guidelines/guidelines.md

@@ -124,10 +124,35 @@ Don’t center header labels or cell content within a table.
 
 !!!
 
-### Resizable columns
+### Reordering columns
+
+If `hasReorderableColumns` is enabled on the Ember component, users can reorder columns either by clicking and dragging on the column reorder handle with a mouse, or by moving focus to the handle with a keyboard and using the right and left arrow keys.
+
+!!! Info
+
+While these properties aren't available in the Figma component, [examples](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=81060-291665&t=KXQulxNCTwGhmCX5-1) are available to copy and paste into design files.
+!!!
+
+![](/assets/components/table/advanced-table/advanced-table-focus-drag-target.png)
+
+![](/assets/components/table/advanced-table/advanced-table-drag-column.png)
+
+Actions related to moving columns are displayed in a context menu in the table header. These are not customizable and include:
+
+- Move column: moves focus to the reordering handle
+- Move column to start/end: moves the column to the first or last position in the table unless the column is already in this position.
+
+![The open context menu in the Advanced Table displaying "Move column", "Move column to start", and "Move column to end" actions.](/assets/components/table/advanced-table/advanced-table-reorder-context-menu.png)
+
+### Resizing columns
 
 Columns can be resized by dragging the "resize border" with a mouse or by moving focus to it and using the left and right arrow keys.
 
+!!! Info
+
+While these properties aren't available in the Figma component, [examples](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=81060-291665&t=UHpPyO7erZKLy4SD-1) are available to copy and paste into design files and the [Resize Border](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=80647-127234&t=UHpPyO7erZKLy4SD-1) is available to use as a starting point for expressing this interaction.
+!!!
+
 The Figma component does not support this resizing feature. Instead, we publish a [Resize Border](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=80647-127234&t=UHpPyO7erZKLy4SD-1) component and [Templates](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=72039-5091&t=UHpPyO7erZKLy4SD-1) to use as a starting point for expressing this interaction. We also provide [examples](https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?m=auto&node-id=81060-291665&t=UHpPyO7erZKLy4SD-1) that you can copy and paste into your design files.
 
 ![The interactive resize border in its active state being dragged with a mouse](/assets/components/table/advanced-table/advanced-table-resize-interaction.png)
@@ -236,7 +261,7 @@ Striping enhances readability by alternating row colors, making it easier to sca
 The row placement property is only relevant within Figma and doesn’t exist as a property within the code.
 !!!
 
-The `rowPlacement` property determines the border radius of a cell. It is only available on cells where the `colPlacement` property is set to `start` or `end`. 
+The `rowPlacement` property determines the border radius of a cell. It is only available on cells where the `colPlacement` property is set to `start` or `end`.
 
 ![The cell with column placement end and row placement end has a border radius set on the bottom right corner.](/assets/components/table/advanced-table/table-row-placement.png)
 
@@ -280,7 +305,7 @@ If `hasStickyFirstColumn` is set to true or false in the Ember component, a cont
 Multi-select is not supported for nested rows at this time.
 !!!
 
-Multi-select allows users to select multiple rows to perform bulk actions, such as deleting or exporting data. Selection states are maintained across pagination and filtering. 
+Multi-select allows users to select multiple rows to perform bulk actions, such as deleting or exporting data. Selection states are maintained across pagination and filtering.
 
 A multi-select pattern consists of:
 

website/docs/components/table/advanced-table/partials/specifications/anatomy.md

@@ -19,7 +19,7 @@
 
 | Element                          | Usage                                                                       |
 | -------------------------------- | --------------------------------------------------------------------------- |
-| Context menu and resize controls | Optional, conditionally renders when `@hasResizableColumns` is set to true. |
+| Context menu and actions | Optional, conditionally renders when a column has context menu actions available for interactions such as resizing, reordering, or pinning.  |
 
 ### Advanced Table cells
 

website/docs/components/table/advanced-table/partials/specifications/states.md

@@ -11,3 +11,9 @@ Cells have a default and focused state. The focused state provides visual feedba
 To indicate interactivity, the border on a resizable column has visual interactive states.
 
 ![Resize border states](/assets/components/table/advanced-table/advanced-table-resize-border-states.png)
+
+### Drag handle
+
+The drag handle is displayed either when hovering on a table header with a mouse, or when focus is moved to it from the context menu.
+
+![Drag handle states](/assets/components/table/advanced-table/advanced-table-drag-handle-button-states.png)