Introduce disabled state for TreeView items

Author: HDinger

app/components/primer/alpha/tree_view.pcss

@@ -143,6 +143,10 @@
     text-decoration-color: var(--control-fgColor-rest);
   }
 
+  & :has(.TreeViewItemContent[aria-disabled=true]) {
+    cursor: not-allowed;
+  }
+
   & .TreeViewItemContent {
     display: flex;
     height: 100%;
@@ -208,6 +212,37 @@
         }
       }
     }
+
+    &[aria-disabled='true'] {
+      pointer-events: none;
+
+      & .TreeViewItemContentText {
+        color: var(--control-fgColor-disabled);
+      }
+
+      & .TreeViewItemVisual {
+        fill: var(--control-fgColor-disabled);
+
+        & svg {
+          fill: var(--control-fgColor-disabled);
+        }
+      }
+
+      & .FormControl-checkbox {
+        @media (hover: hover) {
+          &:hover {
+            cursor: not-allowed;
+          }
+        }
+      }
+
+      @media (hover: hover) {
+        &:hover {
+          cursor: not-allowed;
+          background-color: transparent;
+        }
+      }
+    }
   }
 
   & .TreeViewItemContentText {

app/components/primer/alpha/tree_view/node.rb

@@ -48,6 +48,12 @@ class Node < Primer::Component
         # @return [Symbol]
         attr_reader :node_variant
 
+        # Whether or not this node is disabled, i.e. cannot be activated.
+        #
+        # @return [Boolean]
+        attr_reader :disabled
+        alias disabled? disabled
+
         DEFAULT_SELECT_VARIANT = :none
         SELECT_VARIANT_OPTIONS = [
           :multiple,
@@ -67,6 +73,7 @@ class Node < Primer::Component
         # @param current [Boolean] Whether or not this node is the current node. The current node is styled differently than regular nodes and is the first element that receives focus when tabbing to the `TreeView` component.
         # @param select_variant [Symbol] Controls the type of checkbox that appears. <%= one_of(Primer::Alpha::TreeView::Node::SELECT_VARIANT_OPTIONS) %>
         # @param checked [Boolean | String] The checked state of the node's checkbox. <%= one_of(Primer::Alpha::TreeView::Node::CHECKED_STATES) %>
+        # @param disabled [Boolean] Whether or not the node can be activated. Passing `false` here will cause the node to appear visually disabled but it is still keyboard-focusable.
         # @param content_arguments [Hash] Arguments attached to the node's content, i.e the `<button>` or `<a>` element. <%= link_to_system_arguments_docs %>
         def initialize(
           path:,
@@ -75,6 +82,7 @@ def initialize(
           current: false,
           select_variant: DEFAULT_SELECT_VARIANT,
           checked: DEFAULT_CHECKED_STATE,
+          disabled: false,
           **content_arguments
         )
           @system_arguments = {
@@ -89,6 +97,7 @@ def initialize(
           @current = current
           @select_variant = fetch_or_fallback(SELECT_VARIANT_OPTIONS, select_variant, DEFAULT_SELECT_VARIANT)
           @checked = fetch_or_fallback(CHECKED_STATES, checked, DEFAULT_CHECKED_STATE)
+          @disabled = disabled
           @node_variant = fetch_or_fallback(NODE_VARIANT_TAG_OPTIONS, node_variant, DEFAULT_NODE_VARIANT)
 
           @content_arguments[:tag] = NODE_VARIANT_TAG_MAP[@node_variant]
@@ -103,13 +112,14 @@ def initialize(
 
           @content_arguments[:aria] = merge_aria(
             @content_arguments, {
-              aria: {
-                level: level,
-                selected: false,
-                checked: checked,
-                labelledby: content_id
-              }
+            aria: {
+              level: level,
+              selected: false,
+              checked: checked,
+              labelledby: content_id,
+              disabled: disabled?
             }
+          }
           )
 
           @content_arguments[:data] = merge_data(

app/components/primer/alpha/tree_view/tree_view.ts

@@ -58,21 +58,21 @@ export class TreeViewElement extends HTMLElement {
   }
 
   #nodeForEvent(event: Event): Element | null {
-    const target = event.target as Element
-    const node = target.closest('[role=treeitem]')
+    const eventTarget = event.target as Element
+    const node = eventTarget.closest('[role=treeitem]')
     if (!node) return null
 
-    if (target.closest('.TreeViewItemToggle')) return null
-    if (target.closest('.TreeViewItemLeadingAction')) return null
+    if (eventTarget.closest('.TreeViewItemToggle')) return null
+    if (eventTarget.closest('.TreeViewItemLeadingAction')) return null
 
     return node
   }
 
   #handleNodeEvent(node: Element, event: Event) {
     if (this.#eventIsCheckboxToggle(event, node)) {
-      this.#handleCheckboxToggle(node)
+      this.#handleCheckboxToggle(event, node)
     } else if (this.#eventIsActivation(event)) {
-      this.#handleNodeActivated(node)
+      this.#handleNodeActivated(event, node)
     } else if (event.type === 'focusin') {
       this.#handleNodeFocused(node)
     } else if (event instanceof KeyboardEvent) {
@@ -84,19 +84,30 @@ export class TreeViewElement extends HTMLElement {
     return event.type === 'click' && this.nodeHasCheckBox(node)
   }
 
-  #handleCheckboxToggle(node: Element) {
-    // only handle checking of leaf nodes
+  #handleCheckboxToggle(event: Event, node: Element) {
+    if (this.getNodeDisabledValue(node)) {
+      event.preventDefault()
+      return
+    }
+
+    // only handle checking of leaf nodes, see TreeViewSubTreeNodeElement for the code that
+    // handles checking sub tree items.
     const type = this.getNodeType(node)
     if (type !== 'leaf') return
 
     if (this.getNodeCheckedValue(node) === 'true') {
-      this.#setNodeCheckedValue(node, 'false')
+      this.setNodeCheckedValue(node, 'false')
     } else {
-      this.#setNodeCheckedValue(node, 'true')
+      this.setNodeCheckedValue(node, 'true')
     }
   }
 
-  #handleNodeActivated(node: Element) {
+  #handleNodeActivated(event: Event, node: Element) {
+    if (this.getNodeDisabledValue(node)) {
+      event.preventDefault()
+      return
+    }
+
     // do not emit activation events for buttons and anchors, since it is assumed any activation
     // behavior for these element types is user- or browser-defined
     if (!(node instanceof HTMLDivElement)) return
@@ -140,13 +151,18 @@ export class TreeViewElement extends HTMLElement {
     switch (event.key) {
       case ' ':
       case 'Enter':
+        if (this.getNodeDisabledValue(node)) {
+          event.preventDefault()
+          break
+        }
+
         if (this.nodeHasCheckBox(node)) {
           event.preventDefault()
 
           if (this.getNodeCheckedValue(node) === 'true') {
-            this.#setNodeCheckedValue(node, 'false')
+            this.setNodeCheckedValue(node, 'false')
           } else {
-            this.#setNodeCheckedValue(node, 'true')
+            this.setNodeCheckedValue(node, 'true')
           }
         } else if (node instanceof HTMLAnchorElement) {
           // simulate click on space
@@ -209,14 +225,14 @@ export class TreeViewElement extends HTMLElement {
     const node = this.nodeAtPath(path)
     if (!node) return
 
-    this.#setNodeCheckedValue(node, 'true')
+    this.setNodeCheckedValue(node, 'true')
   }
 
   uncheckAtPath(path: string[]) {
     const node = this.nodeAtPath(path)
     if (!node) return
 
-    this.#setNodeCheckedValue(node, 'false')
+    this.setNodeCheckedValue(node, 'false')
   }
 
   toggleCheckedAtPath(path: string[]) {
@@ -239,6 +255,13 @@ export class TreeViewElement extends HTMLElement {
     return this.getNodeCheckedValue(node)
   }
 
+  disabledValueAtPath(path: string[]): boolean {
+    const node = this.nodeAtPath(path)
+    if (!node) return false
+
+    return this.getNodeDisabledValue(node)
+  }
+
   nodeAtPath(path: string[], selector?: string): Element | null {
     const pathStr = JSON.stringify(path)
     return this.querySelector(`${selector || ''}[data-path="${CSS.escape(pathStr)}"]`)
@@ -255,14 +278,26 @@ export class TreeViewElement extends HTMLElement {
     return this.nodeAtPath(path, '[data-node-type=leaf]') as HTMLLIElement | null
   }
 
-  #setNodeCheckedValue(node: Element, value: TreeViewCheckedValue) {
+  setNodeCheckedValue(node: Element, value: TreeViewCheckedValue) {
     node.setAttribute('aria-checked', value.toString())
   }
 
   getNodeCheckedValue(node: Element): TreeViewCheckedValue {
     return (node.getAttribute('aria-checked') || 'false') as TreeViewCheckedValue
   }
 
+  getNodeDisabledValue(node: Element): boolean {
+    return node.getAttribute('aria-disabled') === 'true'
+  }
+
+  setNodeDisabledValue(node: Element, disabled: boolean) {
+    if (disabled) {
+      node.setAttribute('aria-disabled', 'true')
+    } else {
+      node.removeAttribute('aria-disabled')
+    }
+  }
+
   nodeHasCheckBox(node: Element): boolean {
     return node.querySelector('.TreeViewItemCheckbox') !== null
   }

app/components/primer/alpha/tree_view/tree_view_sub_tree_node_element.ts

@@ -299,6 +299,11 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
 
     switch (event.key) {
       case 'Enter':
+        if (this.treeView?.getNodeDisabledValue(node)) {
+          event.preventDefault()
+          break
+        }
+
         // eslint-disable-next-line no-restricted-syntax
         event.stopPropagation()
 
@@ -324,6 +329,11 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
         break
 
       case ' ':
+        if (this.treeView?.getNodeDisabledValue(node)) {
+          event.preventDefault()
+          break
+        }
+
         if (this.#checkboxElement) {
           // eslint-disable-next-line no-restricted-syntax
           event.stopPropagation()
@@ -344,6 +354,11 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
   }
 
   #handleCheckboxEvent(event: Event) {
+    if (this.treeView?.getNodeDisabledValue(this.node)) {
+      event.preventDefault()
+      return
+    }
+
     if (event.type !== 'click') return
 
     this.toggleChecked()
@@ -354,7 +369,7 @@ export class TreeViewSubTreeNodeElement extends HTMLElement {
   }
 
   toggleChecked() {
-    const checkValue = this.node.getAttribute('aria-checked') || 'false'
+    const checkValue = this.treeView?.getNodeCheckedValue(this.node) || 'false'
     const newCheckValue = checkValue === 'false' ? 'true' : 'false'
     const nodeInfos: TreeViewNodeInfo[] = []
     const rootInfo = this.treeView?.infoFromNode(this.node, newCheckValue)

previews/primer/alpha/tree_view_preview.rb

@@ -8,15 +8,18 @@ class TreeViewPreview < ViewComponent::Preview
       #
       # @snapshot interactive
       # @param expanded [Boolean] toggle
+      # @param disabled [Boolean] toggle
       # @param select_variant [Symbol] select [multiple, none]
       # @param select_strategy [Symbol] select [self, descendants]
       def default(
         expanded: false,
+        disabled: false,
         select_variant: Primer::Alpha::TreeView::Node::DEFAULT_SELECT_VARIANT,
         select_strategy: Primer::Alpha::TreeView::SubTreeNode::DEFAULT_SELECT_STRATEGY
       )
         render_with_template(locals: {
           expanded: coerce_bool(expanded),
+          disabled: coerce_bool(disabled),
           select_variant: select_variant.to_sym,
           select_strategy: select_strategy.to_sym
         })
@@ -92,37 +95,44 @@ def async_alpha(action_menu_expanded: false)
       # @param leading_action_icon [Symbol] octicon
       # @param trailing_visual_icon [Symbol] octicon
       # @param select_variant [Symbol] select [multiple, none]
+      # @param disabled [Boolean] toggle
       def leaf_node_playground(
         label: "Leaf node",
         leading_visual_icon: nil,
         leading_action_icon: nil,
         trailing_visual_icon: nil,
-        select_variant: Primer::Alpha::TreeView::Node::DEFAULT_SELECT_VARIANT
+        select_variant: Primer::Alpha::TreeView::Node::DEFAULT_SELECT_VARIANT,
+        disabled: false
       )
         render_with_template(locals: {
           label: label,
           leading_visual_icon: leading_visual_icon,
           leading_action_icon: leading_action_icon,
           trailing_visual_icon: trailing_visual_icon,
-          select_variant: select_variant.to_sym
+          select_variant: select_variant.to_sym,
+          disabled: disabled
         })
       end
 
       # @label Links
       #
       # @param expanded [Boolean] toggle
-      def links(expanded: false)
+      # @param disabled [Boolean] toggle
+      def links(expanded: false, disabled: false)
         render_with_template(locals: {
-          expanded: coerce_bool(expanded)
+          expanded: coerce_bool(expanded),
+          disabled: coerce_bool(disabled)
         })
       end
 
       # @label Buttons
       #
       # @param expanded [Boolean] toggle
-      def buttons(expanded: false)
+      # @param disabled [Boolean] toggle
+      def buttons(expanded: false, disabled: false)
         render_with_template(locals: {
-          expanded: coerce_bool(expanded)
+          expanded: coerce_bool(expanded),
+          disabled: coerce_bool(disabled)
         })
       end
 
@@ -161,7 +171,7 @@ def populate(node, data, node_arguments)
 
         entries = (
           data.fetch("children", {}).keys.map { |label, idx| [label, :directory] } +
-          data.fetch("files", []).map { |label| [label, :file] }
+            data.fetch("files", []).map { |label| [label, :file] }
         )
 
         entries.sort_by!(&:first)

previews/primer/alpha/tree_view_preview/buttons.html.erb

@@ -1,10 +1,10 @@
 <div style="max-width: 400px">
   <%= render(Primer::Alpha::TreeView.new(node_variant: :button)) do |tree_view| %>
-    <% tree_view.with_sub_tree(label: "Secrets", expanded: expanded, onclick: "alert('Shhhh')") do |sub_tree| %>
-      <% sub_tree.with_leaf(label: "Life and the universe", onclick: "alert(42)") %>
-      <% sub_tree.with_leaf(label: "Secret ingredient", onclick: "alert('Love')") %>
+    <% tree_view.with_sub_tree(label: "Secrets", expanded: expanded, onclick: "alert('Shhhh')", disabled: disabled) do |sub_tree| %>
+      <% sub_tree.with_leaf(label: "Life and the universe", onclick: "alert(42)", disabled: disabled) %>
+      <% sub_tree.with_leaf(label: "Secret ingredient", onclick: "alert('Love')", disabled: disabled) %>
     <% end %>
 
-    <% tree_view.with_leaf(label: "What do you give a sick bird?", onclick: "alert('Tweetment')") %>
+    <% tree_view.with_leaf(label: "What do you give a sick bird?", onclick: "alert('Tweetment')", disabled: disabled) %>
   <% end %>
 </div>