Merge pull request #2771 from salesforce-ux/feat/metatext-trees

feat(trees): Added metatext state and supporting CSS classes to trees component

ui/components/trees/base/_index.scss

@@ -16,6 +16,10 @@
  *
  * Trees can only contain a single focusable tree item and `tabindex="0"` must be placed on the `li[role="treeitem]` that takes current focus. Every other actionable and non-actionable element must be made unfocusable by adding `tabindex="-1"` or removing `tabindex`, respectively.
  *
+ * When implementing collapsed rows, we suggest showing the content DOM nodes within each collapsed row only once the row is expanded for performance reasons. You can additionally toggle the hidden row with `slds-show` and `slds-hide` if you intend to keep all of the content in the DOM.
+ *
+ * You can add metatext (see: metatext state) to any tree item, which adds a smaller, second line of text below tree node labels to provide supplemental information (to provide users with added context, aid with identification/disambiguation). To add metatext, include an additional `span` within the treeitem with the class `slds-tree__item-meta`. We've added an additional parent span around the label/title and metatext to ensure the spacing works properly when metatext is included. If adding metatext to a tree item with child nodes (i.e. a branch), be sure to update the `aria-label` to include the metatext. For example: `aria-label="Tree Branch Label: Tree Branch Metatext"`
+ *
  * #### Accessibility
  *
  * **Interaction requirements**
@@ -32,7 +36,7 @@
  * - `role="treeitem"` is placed on the tree `li` elements
  * - `aria-level` is applied to `treeitem` elements to indicate their nesting depth
  * - `aria-expanded` is applied to `treeitem` elements that have child tree nodes. It is set to `true` or `false`
- * - `aria-label` is applied to `treeitem` elements that have child tree nodes
+ * - `aria-label` is applied to `treeitem` elements that have child tree nodes. Be sure to add any metatext to the label, if applicable
  * - `aria-selected="true"` is applied to `treeitem` elements that are selected
  * - `tabindex="0"` is applied to the `treeitem` that is in focus
  * - `role="group"` is applied to child tree node containers, `ul`
@@ -72,13 +76,11 @@
 /**
  * @selector .slds-tree
  * @restrict .slds-tree_container ul, table
- * @required
  */
 .slds-tree {
   /**
    * @selector .slds-tree__item
    * @restrict .slds-tree div, .slds-tree th
-   * @required
    */
   &__item {
     display: flex;
@@ -90,7 +92,6 @@
      *
      * @selector .slds-is-disabled
      * @restrict .slds-tree__item button
-     * @required
      * @modifier
      */
     .slds-is-disabled {
@@ -119,7 +120,6 @@
      * @selector .slds-is-hovered
      * @restrict .slds-tree__item
      * @notes Class should be applied via Javascript
-     * @required
      * @modifier
      */
     &.slds-is-hovered,
@@ -129,6 +129,34 @@
     }
   }
 
+  /**
+   * The label text of a tree item or tree branch
+   *
+   * @selector .slds-tree__item-label
+   * @restrict .slds-tree__item span
+   */
+  .slds-tree__item-label {
+    display: block;
+  }
+
+  /**
+   * The meta text or secondary text of a tree item
+   *
+   * @selector .slds-tree__item-meta
+   * @restrict .slds-tree__item span
+   */
+  .slds-tree__item-meta {
+    display: block;
+    margin-top: ($spacing-small * -1); // Offset $line-height-text from result-text
+    color: $color-text-weak;
+  }
+
+  /**
+   * Styles the focus and selected state for any tree item that has role="treeitem"
+   *
+   * @selector [role="treeitem"]
+   * @restrict .slds-tree li
+   */
   [role="treeitem"] {
 
     &:focus {
@@ -161,7 +189,6 @@
    * @selector .slds-is-selected
    * @restrict .slds-tree__item
    * @notes Class should be applied via Javascript
-   * @required
    * @modifier
    */
   @include deprecate('5.0.0', '.slds-is-selected is deprecated in .slds-tree, rely on aria-selected attrbiute') {
@@ -177,7 +204,6 @@
    *
    * @selector .slds-is-focused
    * @restrict .slds-tree__item
-   * @required
    * @modifier
    */
   @include deprecate('5.0.0', '.slds-is-focused is deprecated in .slds-tree, rely on the :focus psuedo class on the role="treeitem" element') {
@@ -225,7 +251,8 @@
   // scss-lint:enable SelectorDepth
 
   .slds-button {
-    align-self: center;
+    align-self: flex-start;
+    margin-top: $spacing-x-small;
   }
 
   .slds-pill {

ui/components/trees/base/example.jsx

@@ -20,8 +20,19 @@ let TreeItem = props => (
       tabIndex="-1"
       title="Expand Tree Item"
     />
-    <span className="slds-truncate" title="Tree Item">
-      Tree Item
+    <span className="slds-size_1-of-1">
+      <span className="slds-tree__item-label slds-truncate" title="Tree Item">
+        Tree Item
+      </span>
+      {props.hasMetatext && (
+        <span
+          className="slds-tree__item-meta slds-truncate"
+          title="Tree Item Metatext"
+        >
+          <span className="slds-assistive-text">:</span>
+          Tree Item Metatext
+        </span>
+      )}
     </span>
     {props.children}
   </div>
@@ -38,8 +49,18 @@ let TreeBranch = props => (
       tabIndex="-1"
       title="Expand Tree Branch"
     />
-    <span className="slds-truncate" title="Tree Branch">
-      Tree Branch
+    <span className="slds-size_1-of-1">
+      <span className="slds-tree__item-label slds-truncate" title="Tree Branch">
+        Tree Branch
+      </span>
+      {props.hasMetatext && (
+        <span
+          className="slds-tree__item-meta slds-truncate"
+          title="Tree Branch Metatext"
+        >
+          Tree Branch Metatext
+        </span>
+      )}
     </span>
   </div>
 );
@@ -165,7 +186,7 @@ let Default = props => (
             aria-selected={!!props.isSelected}
             tabIndex={props.isSelected ? '0' : null}
           >
-            <TreeItem />
+            <TreeItem hasMetatext={props.hasMetatext} />
           </li>
           {props.additionalItems}
         </ul>
@@ -174,9 +195,15 @@ let Default = props => (
         role="treeitem"
         aria-level="1"
         aria-expanded="false"
-        aria-label="Tree Branch"
+        aria-label={
+          props.hasMetatext ? (
+            'Tree Branch: Tree Branch Metatext'
+          ) : (
+            'Tree Branch'
+          )
+        }
       >
-        <TreeBranch />
+        <TreeBranch hasMetatext={props.hasMetatext} />
         <ul role="group">
           <li role="treeitem" aria-level="2">
             <TreeItem />
@@ -211,5 +238,10 @@ export let states = [
     id: 'deep-nesting',
     label: 'Deeply nested branches',
     element: <Default isExpanded additionalItems={<AdditionalItems />} />
+  },
+  {
+    id: 'metatext',
+    label: 'Metatext',
+    element: <Default isExpanded hasMetatext />
   }
 ];

ui/components/trees/grid/_index.scss

@@ -58,6 +58,11 @@
       }
     }
   }
+
+  .slds-button {
+    align-self: center;
+    margin-top: 0;
+  }
 }
 
 /**