Support TreeView as a form element

Author: HDinger

app/components/primer/alpha/tree_view.html.erb

@@ -1,4 +1,9 @@
 <tree-view>
+  <% if acts_as_form_input? %>
+    <%= @form_arguments[:builder].hidden_field(@form_arguments[:name], multiple: true, skip_default_ids: true, form: "", data: { target: "tree-view.formInputPrototype" }) %>
+    <div data-target="tree-view.formInputContainer"></div>
+  <% end %>
+
   <%= render(Primer::BaseComponent.new(**@system_arguments)) do %>
     <% nodes.each do |node| %>
       <%= node %>

app/components/primer/alpha/tree_view.rb

@@ -407,9 +407,11 @@ class TreeView < Primer::Component
       attr_reader :node_variant
 
       # @param node_variant [Symbol] The variant to use for this node. <%= one_of(Primer::Alpha::TreeView::NODE_VARIANT_OPTIONS) %>
+      # @param form_arguments [Hash] These arguments allow the selections made within a `TreeView` to be submitted to the server as part of a Rails form. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission.
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>.
-      def initialize(node_variant: DEFAULT_NODE_VARIANT, **system_arguments)
+      def initialize(node_variant: DEFAULT_NODE_VARIANT, form_arguments: {}, **system_arguments)
         @system_arguments = deny_tag_argument(**system_arguments)
+        @form_arguments = form_arguments
 
         @node_variant = fetch_or_fallback(NODE_VARIANT_OPTIONS, node_variant, DEFAULT_NODE_VARIANT)
 
@@ -421,6 +423,10 @@ def initialize(node_variant: DEFAULT_NODE_VARIANT, **system_arguments)
         )
       end
 
+      def acts_as_form_input?
+        @form_arguments[:builder] && @form_arguments[:name]
+      end
+
       private
 
       def before_render

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

@@ -74,6 +74,7 @@ class Node < Primer::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 value [String] If this node is checked, this value will be sent to the server on form submission.
         # @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:,
@@ -83,6 +84,7 @@ def initialize(
           select_variant: DEFAULT_SELECT_VARIANT,
           checked: DEFAULT_CHECKED_STATE,
           disabled: false,
+          value: nil,
           **content_arguments
         )
           @system_arguments = {
@@ -123,8 +125,12 @@ def initialize(
           )
 
           @content_arguments[:data] = merge_data(
-            @content_arguments,
-            { data: { path: @path.to_json } }
+            @content_arguments, {
+            data: {
+              value: value,
+              path: @path.to_json
+            }
+          }
           )
 
           return unless current?

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

@@ -1,10 +1,13 @@
-import {controller} from '@github/catalyst'
+import {controller, target} from '@github/catalyst'
 import {TreeViewSubTreeNodeElement} from './tree_view_sub_tree_node_element'
 import {useRovingTabIndex} from './tree_view_roving_tab_index'
 import type {TreeViewNodeType, TreeViewCheckedValue, TreeViewNodeInfo} from '../../shared_events'
 
 @controller
 export class TreeViewElement extends HTMLElement {
+  @target formInputContainer: HTMLElement
+  @target formInputPrototype: HTMLInputElement
+
   #abortController: AbortController
 
   connectedCallback() {
@@ -28,6 +31,47 @@ export class TreeViewElement extends HTMLElement {
       }
     }).observe(this, {childList: true, subtree: true})
 
+    const updateInputsObserver = new MutationObserver(mutations => {
+      if (!this.formInputContainer) return
+
+      // There is another MutationObserver in TreeViewSubTreeNodeElement that manages checking/unchecking
+      // nodes based on the component's select strategy. These two observers can conflict and cause infinite
+      // looping, so we make sure something actually changed before computing inputs again.
+      const somethingChanged = mutations.some(m => {
+        if (!(m.target instanceof HTMLElement)) return false
+        return m.target.getAttribute('aria-checked') !== m.oldValue
+      })
+
+      if (!somethingChanged) return
+
+      const newInputs = []
+
+      // eslint-disable-next-line custom-elements/no-dom-traversal-in-connectedcallback
+      for (const node of this.querySelectorAll('[role=treeitem][aria-checked=true]')) {
+        const newInput = this.formInputPrototype.cloneNode() as HTMLInputElement
+        newInput.removeAttribute('data-target')
+        newInput.removeAttribute('form')
+
+        const payload: {path: string[]; value?: string} = {
+          path: this.getNodePath(node),
+        }
+
+        const inputValue = this.getFormInputValueForNode(node)
+        if (inputValue) payload.value = inputValue
+
+        newInput.value = JSON.stringify(payload)
+        newInputs.push(newInput)
+      }
+
+      this.formInputContainer.replaceChildren(...newInputs)
+    })
+
+    updateInputsObserver.observe(this, {
+      childList: true,
+      subtree: true,
+      attributeFilter: ['aria-checked'],
+    })
+
     // eslint-disable-next-line github/no-then -- We don't want to wait for this to resolve, just get on with it
     customElements.whenDefined('tree-view-sub-tree-node').then(() => {
       // depends on TreeViewSubTreeNodeElement#eachAncestorSubTreeNode, which may not be defined yet
@@ -173,6 +217,10 @@ export class TreeViewElement extends HTMLElement {
     }
   }
 
+  getFormInputValueForNode(node: Element): string | null {
+    return node.getAttribute('data-value')
+  }
+
   getNodePath(node: Element): string[] {
     const rawPath = node.getAttribute('data-path')
 

previews/primer/alpha/tree_view_preview.rb

@@ -151,6 +151,15 @@ def auto_expansion
         end
       end
 
+      # @label Form input
+      #
+      # @param expanded [Boolean] toggle
+      def form_input(expanded: true)
+        render_with_template(locals: {
+          expanded: coerce_bool(expanded)
+        })
+      end
+
       private
 
       def coerce_bool(value)

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

@@ -0,0 +1,14 @@
+<%= form_with(url: primer_view_components.generic_form_submission_path(format: :json)) do |f| %>
+  <%= render(Primer::Alpha::Stack.new) do %>
+    <%= render(Primer::Alpha::TreeView.new(form_arguments: { builder: f, name: "folder_structure" })) do |tree| %>
+      <% tree.with_sub_tree(label: "src", expanded: expanded, select_variant: :multiple, value: 0) do |sub_tree| %>
+        <% sub_tree.with_leaf(label: "button.rb", select_variant: :multiple, value: 1) %>
+        <% sub_tree.with_leaf(label: "icon_button.rb", current: true, select_variant: :multiple, value: 2) %>
+      <% end %>
+
+      <% tree.with_leaf(label: "action_menu.rb", select_variant: :multiple, value: 3) %>
+    <% end %>
+
+    <%= render(Primer::Alpha::SubmitButton.new(name: :submit, label: "Submit")) %>
+  <% end %>
+<% end %>

test/system/alpha/tree_view_test.rb

@@ -785,5 +785,19 @@ def test_self_select_strategy_checking_sub_tree_does_not_check_children
 
       assert_path_checked "primer", "alpha", "action_bar"
     end
+
+
+    def test_form_submission
+      visit_preview(:form_input, expanded: true, route_format: :json)
+
+      check_at_path("action_menu.rb")
+
+      find("button[type=submit]").click
+
+      # for some reason the JSON response is wrapped in HTML, I have no idea why
+      response = JSON.parse(find("pre").text)
+
+      assert_equal "{\"path\":[\"action_menu.rb\"],\"value\":\"3\"}", response.dig("form_params", "folder_structure", 0)
+    end
   end
 end