fix: incorporate feedback

Author: shleewhite

website/docs/components/table/advanced-table/index.md

@@ -1,7 +1,7 @@
 ---
 title: Advanced Table
-description: Used to display organized, two-dimensional tabular data.
-caption: Used to display organized, two-dimensional tabular data.
+description: Used to display complex, structured tabular data with advanced features.
+caption: Used to display complex, structured tabular data with advanced features.
 links:
   figma: https://www.figma.com/design/iweq3r2Pi8xiJfD9e6lOhF/HDS-Components-v2.0?node-id=67216-35163&t=w8xQlWxzH7bwXLe2-1
   github: https://github.com/hashicorp/design-system/tree/main/packages/components/src/components/hds/advanced-table

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

@@ -12,7 +12,7 @@ The table row element cannot receive interactions, meaning actions cannot be att
 
 ### Focus in Advanced Tables
 
-Unlike the Table component, each cell receives focus in the Advanced Table to let users navigate through the table efficiently with a keyboard. For any other interactions, you must use interactive elements (buttons, links, etc.) within the cells. 
+Unlike the Table component, each cell receives focus in the Advanced Table to support users navigating through the table efficiently with a keyboard. For any other interactions, you must use interactive elements (buttons, links, etc.) within the cells. 
 
 ### Row selection
 

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

@@ -1,12 +1,12 @@
 ## Component API
 
-The AdvancedTable component itself is where most of the options will be applied. However, the APIs for the child components are also documented here, in case a custom implementation is desired.
+The Advanced Table component itself is where most of the options will be applied. However, the APIs for the child components are also documented here in case a custom implementation is desired.
 
 ### AdvancedTable
 
 <Doc::ComponentApi as |C|>
   <C.Property @name="<:body>" @type="named block">
-    This is a named block where the content for the AdvancedTable body is rendered.
+    This is a named block where the content for the Advanced Table body is rendered.
     <Doc::ComponentApi as |C|>
       <C.Property @name="[B].rowIndex" @type="number | string">
         The value of the index associated with the `@each` loop. Returns a number when there are no nested rows. Returns a string in the form `${parentIndex}.${childIndex}` when there are nested rows.
@@ -23,10 +23,10 @@ The AdvancedTable component itself is where most of the options will be applied.
     </Doc::ComponentApi>
   </C.Property>
   <C.Property @name="model" @type="array">
-    The data model to be used by the AdvancedTable. The model can have any shape, but for nested rows there are two expected keys.
+    The data model to be used by the Advanced Table. The model can have any shape, but for nested rows there are two expected keys.
     <Doc::ComponentApi as |C|>
       <C.Property @name="children" @type="array">
-        If there are nested rows, the AdvancedTable will use the `children` key in the model to render the child content. The key can be changed by setting `childrenKey` argument on the `Hds::AdvancedTable`.
+        If there are nested rows, the Advanced Table will use the `children` key in the model to render the child content. The key can be changed by setting `childrenKey` argument on the `Hds::AdvancedTable`.
       </C.Property>
       <C.Property @name="isExpanded" @type="boolean">
         If there are nested rows, the default state of the toggle can be set by adding `isExpanded` to the row in the model.
@@ -44,7 +44,7 @@ The AdvancedTable component itself is where most of the options will be applied.
       </C.Property>
       <C.Property @name="isSortable" @type="boolean" @default="false">
         If set to `true`, indicates that a column should be sortable.<br><br>
-        **Important**: AdvancedTable does **not** support having `isSelectable` true when there are nested rows.
+        **Important**: Advanced Table does **not** support setting `isSelectable` to true when there are nested rows.
       </C.Property>
       <C.Property @name="align" @type="enum" @values={{array "left" "center" "right" }} @default="left">
         Determines the horizontal content alignment (sometimes referred to as text alignment) for the column header.
@@ -56,10 +56,10 @@ The AdvancedTable component itself is where most of the options will be applied.
         If set to `true`, it visually hides the column’s text content (it will still be available to screen readers for accessibility). <em>Only available for non-sortable columns.</em>
       </C.Property>
       <C.Property @name="sortingFunction" @type="function">
-        Callback function to provide support for custom sorting logic. It should implement a typical bubble-sorting algorithm using two elements and comparing them. For more details, see the example of custom sorting in the How To Use section.
+        Callback function to provide support for custom sorting logic. It should implement a typical bubble-sorting algorithm using two elements and comparing them. For more details, see the example of custom sorting in the [How To Use section](#sortable-advanced-table).
       </C.Property>
       <C.Property @name="tooltip" @type="string">
-        Text string which will appear in the tooltip (see [`Tooltip`](/components/tooltip) for details). May contain basic HTML tags for formatting text such as `strong` and `em` tags. Not intended for multi-paragraph text or other more complex content. May not contain interactive content such as links or buttons. The `placement` and `offset` are automatically set and can’t be overwritten.
+        Text string which will appear in [`Tooltip`](/components/tooltip). May contain basic HTML tags for formatting text such as `strong` and `em` tags. Not intended for multi-paragraph text or other more complex content. May not contain interactive content such as links or buttons. The `placement` and `offset` are automatically set and can’t be overwritten.
       </C.Property>
     </Doc::ComponentApi>
   </C.Property>
@@ -79,18 +79,18 @@ The AdvancedTable component itself is where most of the options will be applied.
     When called, this function receives an object as argument, with different keys corresponding to different information:
     <ul>
     <li>`selectionKey`: the value of the `@selectionKey` argument associated with the row selected/deselected by the user or `all` if the “select all” checkbox has been toggled</li>
-    <li>`selectionCheckboxElement`: the checkbox (DOM element) that has been toggled by the user</li>
-    <li>`selectedRowsKeys`: an array containing all the `@selectionKey`s of the selected rows in the table (an empty array is returned if no row is selected)</li>
-    <li>`selectableRowsStates`: an array of objects corresponding to all the rows displayed in the table when the user changed a selection; each object contains the `@selectionKey` value for the associated row and its `isSelected` boolean state (if the checkbox is checked or not)<br><br>
+    <li>`selectionCheckboxElement`: the checkbox (DOM element) that has been toggled by the user.</li>
+    <li>`selectedRowsKeys`: an array containing all the `@selectionKey`s of the selected rows in the table (an empty array is returned if no row is selected).</li>
+    <li>`selectableRowsStates`: an array of objects corresponding to all the rows displayed in the table when the user changed a selection; each object contains the `@selectionKey` value for the associated row and its `isSelected` boolean state (if the checkbox is checked or not).<br><br>
     **Important**: the order of the rows in the array doesn’t necessarily follow the order of the rows in the table/DOM.</li>
     </ul>
   </C.Property>
   <C.Property @name="isStriped" @type="boolean" @default="false">
     Determines if even-numbered rows will have a different background color from odd-numbered rows.<br><br>
-    **Important**: AdvancedTable does **not** support having `isStriped` true when there are nested rows.
+    **Important**: Advanced Table does **not** support setting `isStriped` to true when there are nested rows.
   </C.Property>
   <C.Property @name="hasStickyHeader" @type="boolean" @default="false">
-    Determines if the AdvancedTable has a sticky header.
+    Determines if the Advanced Table has a sticky header.
   </C.Property>
   <C.Property @name="density" @type="enum" @values={{array "short" "medium" "tall" }} @default="medium">
     If set, determines the density (height) of the body’s rows.
@@ -123,19 +123,23 @@ The AdvancedTable component itself is where most of the options will be applied.
 
 ### AdvancedTable::Tr
 
+!!! Info
+
 Note: This component is not eligible to receive interactions (e.g., it cannot have an `onClick` event handler attached directly to it). Instead, an interactive element should be placed _inside_ of the `AdvancedTable::Th`, `AdvancedTable::Td` components.
 
+!!!
+
 This component can contain `Hds::AdvancedTable::Th` or `Hds::AdvancedTable::Td` components.
 
 <Doc::ComponentApi as |C|>
   <C.Property @name="yield">
     Elements passed as children are yielded as inner content of a `<div role="row">` HTML element.
   </C.Property>
   <C.Property @name="isSelected" @type="boolean" @default="false">
-    Sets the initial selection state for the row (used in conjunction with setting `isSelectable` on the `AdvancedTable`).
+    Sets the initial selection state for the row (used in conjunction with setting `isSelectable` on the Advanced Table).
   </C.Property>
   <C.Property @name="selectionKey" @type="string | number">
-    Required value to associate an unique identifier to each table row (used in conjunction with setting `isSelectable` on the `AdvancedTable` and returned in the `onSelectionChange` callback arguments). It’s required if `isSelectable={{true}}`.
+    Required value to associate an unique identifier to each table row (used in conjunction with setting `isSelectable` on the Advanced Table and returned in the `onSelectionChange` callback arguments). It’s required if `isSelectable={{true}}`.
   </C.Property>
   <C.Property @name="selectionAriaLabelSuffix" @type="string">
     Descriptive `aria-label` attribute applied to the checkbox used to select the row (used in conjunction with setting `isSelectable` on the `AdvancedTable`). The component automatically prepends “Select/Deselect” to the string, depending on the selection status. It’s required if `isSelectable={{true}}`.
@@ -147,8 +151,12 @@ This component can contain `Hds::AdvancedTable::Th` or `Hds::AdvancedTable::Td`
 
 ### AdvancedTable::Th
 
+!!! Info
+
 Note: This component is not eligible to receive interactions (e.g., it cannot have an `onClick` event handler attached directly to it). Instead, an interactive element should be placed _inside_ of the `AdvancedTable::Th` component.
 
+!!!
+
 If the `Th` component is passed as the first cell of a body row, `role="rowheader"` is automatically applied for accessibility purposes.
 
 <Doc::ComponentApi as |C|>
@@ -162,7 +170,7 @@ If the `Th` component is passed as the first cell of a body row, `role="rowheade
     If set, determines the column’s width.
   </C.Property>
   <C.Property @name="tooltip" @type="string">
-    Text string which will appear in the tooltip (see [`Tooltip`](/components/tooltip) for details). May contain basic HTML tags for formatting text such as `strong` and `em` tags. Not intended for multi-paragraph text or other more complex content. May not contain interactive content such as links or buttons. The `placement` and `offset` are automatically set and can’t be overwritten.
+    Text string which will appear in the [`Tooltip`](/components/tooltip). May contain basic HTML tags for formatting text such as `strong` and `em` tags. Not intended for multi-paragraph text or other more complex content. May not contain interactive content such as links or buttons. The `placement` and `offset` are automatically set and can’t be overwritten.
   </C.Property>
   <C.Property @name="isVisuallyHidden" @type="boolean" @default="false">
     If set to `true`, it visually hides the column’s text content (it will still be available to screen readers for accessibility).
@@ -182,9 +190,12 @@ If the `Th` component is passed as the first cell of a body row, `role="rowheade
 </Doc::ComponentApi>
 
 ### AdvancedTable::Td
+!!! Info
 
 Note: This component is not eligible to receive interactions (e.g., it cannot have an `onClick` event handler attached directly to it). Instead, an interactive element should be placed _inside_ of the `AdvancedTable::Td` component.
 
+!!!
+
 <Doc::ComponentApi as |C|>
   <C.Property @name="align" @type="enum" @values={{array "left" "center" "right" }} @default="left">
     Determines the horizontal content alignment (sometimes referred to as text alignment) for the cell (make sure it is also set for the column header).