openproject-primer_view_components 0.73.1 → 0.74.0

data/app/components/primer/open_project/filterable_tree_view.rb

@@ -230,19 +230,43 @@ module Primer
       end
 
       def with_sub_tree(**system_arguments, &block)
+        system_arguments[:select_variant] ||= :multiple
+
+        if system_arguments[:select_variant] != :multiple && system_arguments[:select_variant] != :single
+          raise ArgumentError, "FilterableTreeView only supports `:multiple` or `:single` as select_variant"
+        end
+
+        if system_arguments[:select_variant] == :single
+          # In single selection, the include sub-items checkbox and the SegmentedControl make no sense
+          @include_sub_items_check_box_arguments[:hidden] = true
+          @include_sub_items_check_box_arguments[:checked] = false
+          @filter_mode_control_arguments[:hidden] = true
+        end
+
         @tree_view.with_sub_tree(
           sub_tree_component_klass: SubTree,
           **system_arguments,
-          select_variant: :multiple,
           select_strategy: :self,
           &block
         )
       end
 
       def with_leaf(**system_arguments, &block)
+        system_arguments[:select_variant] ||= :multiple
+
+        if system_arguments[:select_variant] != :multiple && system_arguments[:select_variant] != :single
+          raise ArgumentError, "FilterableTreeView only supports `:multiple` or `:single` as select_variant"
+        end
+
+        if system_arguments[:select_variant] == :single
+          # In single selection, the include sub-items checkbox and the SegmentedControl make no sense
+          @include_sub_items_check_box_arguments[:hidden] = true
+          @include_sub_items_check_box_arguments[:checked] = false
+          @filter_mode_control_arguments[:hidden] = true
+        end
+
         @tree_view.with_leaf(
           **system_arguments,
-          select_variant: :multiple,
           &block
         )
       end

data/lib/primer/view_components/version.rb

@@ -5,8 +5,8 @@ module Primer
   module ViewComponents
     module VERSION
       MAJOR = 0
-      MINOR = 73
-      PATCH = 1
+      MINOR = 74
+      PATCH = 0
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/previews/primer/alpha/tree_view_preview/default.html.erb

@@ -6,7 +6,7 @@
         <% icons.with_collapsed_icon(icon: :"file-directory-fill", color: :accent) %>
       <% end %>
 
-      <% sub_tree.with_trailing_visual_icon(icon: :"diff-modified") %>
+      <% sub_tree.with_trailing_visual_icon(icon: :"diff-modified") unless select_variant == :single %>
 
       <% sub_tree.with_leaf(label: "button.rb", disabled: disabled, select_variant: select_variant) do |item| %>
         <% item.with_leading_visual_icon(icon: :file) %>

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

@@ -1,12 +1,12 @@
 <%= 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) %>
+      <% tree.with_sub_tree(label: "src", expanded: expanded, select_variant: select_variant, value: 0) do |sub_tree| %>
+        <% sub_tree.with_leaf(label: "button.rb", select_variant: select_variant, value: 1) %>
+        <% sub_tree.with_leaf(label: "icon_button.rb", current: true, select_variant: select_variant, value: 2) %>
       <% end %>
 
-      <% tree.with_leaf(label: "action_menu.rb", select_variant: :multiple, value: 3) %>
+      <% tree.with_leaf(label: "action_menu.rb", select_variant: select_variant, value: 3) %>
     <% end %>
 
     <%= render(Primer::Alpha::SubmitButton.new(name: :submit, label: "Submit")) %>

data/previews/primer/alpha/tree_view_preview/multi_select.html.erb

@@ -0,0 +1,10 @@
+<div style="max-width: 400px">
+  <%= render(Primer::Alpha::TreeView.new) do |tree_view| %>
+    <% tree_view.with_sub_tree(label: "src", expanded: expanded, disabled: disabled, select_variant: select_variant) do |sub_tree| %>
+      <% sub_tree.with_leaf(label: "button.rb", disabled: disabled, select_variant: select_variant) %>
+      <% sub_tree.with_leaf(label: "icon_button.rb", current: true, disabled: disabled, select_variant: select_variant) %>
+    <% end %>
+
+    <% tree_view.with_leaf(label: "action_menu.rb", disabled: disabled, select_variant: select_variant) %>
+  <% end %>
+</div>

data/previews/primer/alpha/tree_view_preview/single_select.html.erb

@@ -0,0 +1,10 @@
+<div style="max-width: 400px">
+  <%= render(Primer::Alpha::TreeView.new) do |tree_view| %>
+    <% tree_view.with_sub_tree(label: "src", expanded: expanded, disabled: disabled, select_variant: select_variant) do |sub_tree| %>
+      <% sub_tree.with_leaf(label: "button.rb", disabled: disabled, select_variant: select_variant) %>
+      <% sub_tree.with_leaf(label: "icon_button.rb", current: true, disabled: disabled, select_variant: select_variant) %>
+    <% end %>
+
+    <% tree_view.with_leaf(label: "action_menu.rb", disabled: disabled, select_variant: select_variant) %>
+  <% end %>
+</div>

data/previews/primer/alpha/tree_view_preview.rb

@@ -9,7 +9,7 @@ module Primer
       # @snapshot interactive
       # @param expanded [Boolean] toggle
       # @param disabled [Boolean] toggle
-      # @param select_variant [Symbol] select [multiple, none]
+      # @param select_variant [Symbol] select [multiple, single, none]
       # @param select_strategy [Symbol] select [self, descendants, mixed_descendants]
       def default(
         expanded: false,
@@ -28,7 +28,7 @@ module Primer
       # @label Playground
       #
       # @param expanded [Boolean] toggle
-      # @param select_variant [Symbol] select [multiple, none]
+      # @param select_variant [Symbol] select [multiple, single, none]
       # @param select_strategy [Symbol] select [self, descendants, mixed_descendants]
       def playground(
         expanded: false,
@@ -43,6 +43,38 @@ module Primer
         })
       end
 
+      # @label Single select
+      #
+      # @snapshot interactive
+      # @param expanded [Boolean] toggle
+      # @param disabled [Boolean] toggle
+      def single_select(
+        expanded: false,
+        disabled: false
+      )
+        render_with_template(locals: {
+          expanded: coerce_bool(expanded),
+          disabled: coerce_bool(disabled),
+          select_variant: :single,
+        })
+      end
+
+      # @label Multi select
+      #
+      # @snapshot interactive
+      # @param expanded [Boolean] toggle
+      # @param disabled [Boolean] toggle
+      def multi_select(
+        expanded: false,
+        disabled: false
+      )
+        render_with_template(locals: {
+          expanded: coerce_bool(expanded),
+          disabled: coerce_bool(disabled),
+          select_variant: :multiple,
+        })
+      end
+
       # @label Empty
       #
       # @snapshot interactive
@@ -94,7 +126,7 @@ module Primer
       # @param leading_visual_icon [Symbol] octicon
       # @param leading_action_icon [Symbol] octicon
       # @param trailing_visual_icon [Symbol] octicon
-      # @param select_variant [Symbol] select [multiple, none]
+      # @param select_variant [Symbol] select [multiple, single, none]
       # @param disabled [Boolean] toggle
       def leaf_node_playground(
         label: "Leaf node",
@@ -153,9 +185,11 @@ module Primer
 
       # @label Form input
       #
+      # @param select_variant [Symbol] select [multiple, single]
       # @param expanded [Boolean] toggle
-      def form_input(expanded: true)
+      def form_input(select_variant: :multiple, expanded: true)
         render_with_template(locals: {
+          select_variant: select_variant.to_sym,
           expanded: coerce_bool(expanded)
         })
       end

data/previews/primer/open_project/filterable_tree_view_preview/form_input.html.erb

@@ -1,30 +1,30 @@
 <%= form_with(url: primer_view_components.generic_form_submission_path(format: :json)) do |f| %>
   <%= render(Primer::Alpha::Stack.new) do %>
     <%= render(Primer::OpenProject::FilterableTreeView.new(form_arguments: { builder: f, name: "characters" })) do |tree| %>
-      <% tree.with_sub_tree(label: "Students", expanded: expanded) do |hogwarts| %>
-        <% hogwarts.with_sub_tree(label: "Ravenclaw", expanded: expanded) do |ravenclaw| %>
-          <% ravenclaw.with_leaf(label: "Luna Lovegood") %>
+      <% tree.with_sub_tree(label: "Students", select_variant: select_variant, expanded: expanded) do |hogwarts| %>
+        <% hogwarts.with_sub_tree(label: "Ravenclaw", select_variant: select_variant, expanded: expanded) do |ravenclaw| %>
+          <% ravenclaw.with_leaf(label: "Luna Lovegood", select_variant: select_variant) %>
         <% end %>
 
-        <% hogwarts.with_sub_tree(label: "Slytherin", expanded: expanded) do |hufflepuff| %>
-          <% hufflepuff.with_leaf(label: "Draco Malfoy") %>
+        <% hogwarts.with_sub_tree(label: "Slytherin", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+          <% hufflepuff.with_leaf(label: "Draco Malfoy", select_variant: select_variant) %>
         <% end %>
 
-        <% hogwarts.with_sub_tree(label: "Hufflepuff", expanded: expanded) do |hufflepuff| %>
-          <% hufflepuff.with_leaf(label: "Susan Bones") %>
+        <% hogwarts.with_sub_tree(label: "Hufflepuff", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+          <% hufflepuff.with_leaf(label: "Susan Bones", select_variant: select_variant) %>
         <% end %>
 
-        <% hogwarts.with_sub_tree(label: "Gryffindor", expanded: expanded) do |hufflepuff| %>
-          <% hufflepuff.with_leaf(label: "Harry Potter") %>
-          <% hufflepuff.with_leaf(label: "Ronald Weasley") %>
-          <% hufflepuff.with_leaf(label: "Hermione Granger") %>
+        <% hogwarts.with_sub_tree(label: "Gryffindor", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+          <% hufflepuff.with_leaf(label: "Harry Potter", select_variant: select_variant) %>
+          <% hufflepuff.with_leaf(label: "Ronald Weasley", select_variant: select_variant) %>
+          <% hufflepuff.with_leaf(label: "Hermione Granger", select_variant: select_variant) %>
         <% end %>
       <% end %>
 
-      <% tree.with_leaf(label: "Albus Dumbledore") %>
-      <% tree.with_leaf(label: "Minerva McGonagall") %>
-      <% tree.with_leaf(label: "Severus Snape") %>
-      <% tree.with_leaf(label: "Rubeus Hagrid") %>
+      <% tree.with_leaf(label: "Albus Dumbledore", select_variant: select_variant) %>
+      <% tree.with_leaf(label: "Minerva McGonagall", select_variant: select_variant) %>
+      <% tree.with_leaf(label: "Severus Snape", select_variant: select_variant) %>
+      <% tree.with_leaf(label: "Rubeus Hagrid", select_variant: select_variant) %>
     <% end %>
 
     <%= render(Primer::Alpha::SubmitButton.new(name: :submit, label: "Submit")) %>

data/previews/primer/open_project/filterable_tree_view_preview/playground.html.erb

@@ -2,28 +2,28 @@
   include_sub_items_check_box_arguments: { hidden: !show_checkbox },
   filter_mode_control_arguments: { hidden: !show_segmented_control }
 )) do |tree| %>
-  <% tree.with_sub_tree(label: "Students", expanded: expanded) do |hogwarts| %>
-    <% hogwarts.with_sub_tree(label: "Ravenclaw", expanded: expanded) do |ravenclaw| %>
-      <% ravenclaw.with_leaf(label: "Luna Lovegood") %>
+  <% tree.with_sub_tree(label: "Students", select_variant: select_variant, expanded: expanded) do |hogwarts| %>
+    <% hogwarts.with_sub_tree(label: "Ravenclaw", select_variant: select_variant, expanded: expanded) do |ravenclaw| %>
+      <% ravenclaw.with_leaf(label: "Luna Lovegood", select_variant: select_variant) %>
     <% end %>
 
-    <% hogwarts.with_sub_tree(label: "Slytherin", expanded: expanded) do |hufflepuff| %>
-      <% hufflepuff.with_leaf(label: "Draco Malfoy") %>
+    <% hogwarts.with_sub_tree(label: "Slytherin", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+      <% hufflepuff.with_leaf(label: "Draco Malfoy", select_variant: select_variant) %>
     <% end %>
 
-    <% hogwarts.with_sub_tree(label: "Hufflepuff", expanded: expanded) do |hufflepuff| %>
-      <% hufflepuff.with_leaf(label: "Susan Bones") %>
+    <% hogwarts.with_sub_tree(label: "Hufflepuff", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+      <% hufflepuff.with_leaf(label: "Susan Bones", select_variant: select_variant) %>
     <% end %>
 
-    <% hogwarts.with_sub_tree(label: "Gryffindor", expanded: expanded) do |hufflepuff| %>
-      <% hufflepuff.with_leaf(label: "Harry Potter") %>
-      <% hufflepuff.with_leaf(label: "Ronald Weasley") %>
-      <% hufflepuff.with_leaf(label: "Hermione Granger") %>
+    <% hogwarts.with_sub_tree(label: "Gryffindor", select_variant: select_variant, expanded: expanded) do |hufflepuff| %>
+      <% hufflepuff.with_leaf(label: "Harry Potter", select_variant: select_variant) %>
+      <% hufflepuff.with_leaf(label: "Ronald Weasley", select_variant: select_variant) %>
+      <% hufflepuff.with_leaf(label: "Hermione Granger", select_variant: select_variant) %>
     <% end %>
   <% end %>
 
-  <% tree.with_leaf(label: "Albus Dumbledore") %>
-  <% tree.with_leaf(label: "Minerva McGonagall") %>
-  <% tree.with_leaf(label: "Severus Snape") %>
-  <% tree.with_leaf(label: "Rubeus Hagrid") %>
+  <% tree.with_leaf(label: "Albus Dumbledore", select_variant: select_variant) %>
+  <% tree.with_leaf(label: "Minerva McGonagall", select_variant: select_variant) %>
+  <% tree.with_leaf(label: "Severus Snape", select_variant: select_variant) %>
+  <% tree.with_leaf(label: "Rubeus Hagrid", select_variant: select_variant) %>
 <% end %>

data/previews/primer/open_project/filterable_tree_view_preview.rb

@@ -7,11 +7,13 @@ module Primer
       # @label Playground
       #
       # @param expanded [Boolean] toggle
+      # @param select_variant [Symbol] select [multiple, single]
       # @param show_checkbox [Boolean] toggle
       # @param show_segmented_control [Boolean] toggle
-      def playground(expanded: true, show_checkbox: true, show_segmented_control: true)
+      def playground(expanded: true, select_variant: :multiple, show_checkbox: true, show_segmented_control: true)
         render_with_template(locals: {
           expanded: coerce_bool(expanded),
+          select_variant: select_variant.to_sym,
           show_checkbox: coerce_bool(show_checkbox),
           show_segmented_control: coerce_bool(show_segmented_control)
         })
@@ -29,9 +31,11 @@ module Primer
 
       # @label Form input
       #
+      # @param select_variant [Symbol] select [multiple, single]
       # @param expanded [Boolean] toggle
-      def form_input(expanded: true)
+      def form_input(select_variant: :multiple, expanded: true)
         render_with_template(locals: {
+          select_variant: select_variant.to_sym,
           expanded: coerce_bool(expanded)
         })
       end

data/static/arguments.json

@@ -3529,7 +3529,7 @@
         "name": "select_variant",
         "type": "Symbol",
         "default": "`:none`",
-        "description": "Controls the type of checkbox that appears. One of `:multiple` or `:none`."
+        "description": "Controls the type of checkbox that appears. One of `:multiple`, `:none`, or `:single`."
       },
       {
         "name": "checked",

data/static/constants.json

@@ -875,6 +875,7 @@
       "anchor"
     ],
     "SELECT_VARIANT_OPTIONS": [
+      "single",
       "multiple",
       "none"
     ]

data/static/info_arch.json

@@ -10428,7 +10428,7 @@
   },
   {
     "fully_qualified_name": "Primer::Alpha::TreeView",
-    "description": "TreeView is a hierarchical list of items that may have a parent-child relationship where children\ncan be toggled into view by expanding or collapsing their parent item.\n\n## Terminology\n\nConsider the following tree structure:\n\nsrc\n├ button.rb\n└ action_list\n  ├ item.rb\n  └ header.rb\n\n1. **Node**. A node is an item in the tree. Nodes can either be \"leaf\" nodes (i.e. have no children), or \"sub-tree\"\nnodes, which do have children. In the example above, button.rb, item.rb, and header.rb are all leaf nodes, while\naction_list is a sub-tree node.\n2. **Path**. A node's path is like its ID. It's an array of strings containing the current node's label and all the\nlabels of its ancestors, in order. In the example above, header.rb's path is [\"src\", \"action_list\", \"header.rb\"].\n\n## Static nodes\n\nThe `TreeView` component allows items to be provided statically or loaded dynamically from the server.\nProviding items statically is done using the `leaf` and `sub_tree` slots:\n\n```erb\n<%= render(Primer::Alpha::TreeView.new) do |tree| %>\n  <% tree.with_sub_tree(label: \"Directory\") do |sub_tree| %>\n    <% sub_tree.with_leaf(label: \"File 1\")\n  <% end %>\n  <% tree.with_leaf(label: \"File 2\") %>\n<% end %>\n```\n\n## Dynamic nodes\n\nTree nodes can also be fetched dynamically from the server and will require creating a Rails controller action\nto respond with the list of nodes. Unlike other Primer components, `TreeView` allows the programmer to specify\nloading behavior on a per-sub-tree basis, i.e. each sub-tree must specify how its nodes are loaded. To load nodes\ndynamically for a given sub-tree, configure it with either a loading spinner or a loading skeleton, and provide\nthe URL to fetch nodes from:\n\n```erb\n<%= render(Primer::Alpha::TreeView.new) do |tree| %>\n  <% tree.with_sub_tree(label: \"Directory\") do |sub_tree| %>\n    <% sub_tree.with_loading_spinner(src: primer_view_components.tree_view_items_path) %>\n  <% end %>\n<% end %>\n```\n\nDefine a controller action to serve the list of nodes. The `TreeView` component automatically includes the\nsub-tree's path as a GET parameter, encoded as a JSON array.\n\n```ruby\nclass TreeViewItemsController < ApplicationController\n  def show\n    @path = JSON.parse(params[:path])\n    @results = get_tree_items(starting_at: path)\n  end\nend\n```\n\nResponses must be HTML fragments, eg. have a content type of `text/html+fragment`. This content type isn't\navailable by default in Rails, so you may have to register it eg. in an initializer:\n\n```ruby\nMime::Type.register(\"text/fragment+html\", :html_fragment)\n```\n\nRender a `Primer::Alpha::TreeView::SubTree` in the action's template, tree_view_items/show.html_fragment.erb:\n\n```erb\n<%= render(Primer::Alpha::TreeView::SubTree.new(path: @path, node_variant: :div)) do |tree| %>\n  <% tree.with_leaf(...) %>\n  <% tree.with_sub_tree(...) do |sub_tree| %>\n    ...\n  <% end %>\n<% end %>\n```\n\n## Multi-select mode\n\nPassing `select_variant: :multiple` to both sub-tree and leaf nodes will add a check box to the left of the node's\nlabel. These check boxes behave according to the value of a second argument, `select_strategy:`.\n\nThe default select strategy, `:descendants`, will cause all child nodes to be checked when the node is checked.\nThis includes both sub-tree and leaf nodes. When the node is unchecked, all child nodes will also be unchecked.\nUnchecking a child node of a checked parent will cause the parent to enter a mixed or indeterminate state, which\nis represented by a horizontal line icon instead of a check mark. This icon indicates that some children are\nchecked, but not all.\n\nA secondary select strategy, `:self`, is provided to allow disabling the automatic checking of child nodes. When\n`select_strategy: :self` is specified, checking sub-tree nodes does not check child nodes, and sub-tree nodes\ncannot enter a mixed or indeterminate state.\n\nNodes can be checked via the keyboard by pressing the space key.\n\n## Node tags\n\n`TreeView`s support three different node variants, `:anchor`, `:button`, and `:div` (the default), which controls\nwhich HTML tag is used to construct the nodes. The `:anchor` and `:button` variants correspond to `<a>` and\n`<button>` tags respectively, which are browser-native elements. Anchors and buttons can be activated (i.e.\n\"clicked\") using the mouse or keyboard via the enter or space keys. The node variant must be the same for all\nnodes in the tree, and is therefore specified at the root level, eg. `TreeView.new(node_variant: :anchor)`.\n\nTrees with node variants other than `:div` cannot have check boxes, i.e. cannot be put into multi-select mode.\n\nTrees with node variants other than `:div` do not emit the `treeViewNodeActivated` or `treeViewBeforeNodeActivated`\nevents, since it is assumed any behavior associated with these variants is user- or browser-defined.\n\n## Interaction behavior matrix\n\n|Interaction     |Select variant|Tag          |Result                     |\n|:---------------|:-------------|:------------|:--------------------------|\n|Enter/space     |none          |div          |Expands/collapses          |\n|Enter/space     |none          |anchor/button|Activates anchor/button    |\n|Enter/space     |multiple      |div          |Checks or unchecks         |\n|Enter/space     |multiple      |anchor/button|N/A (not allowed)          |\n|Left/right arrow|none          |div          |Expands/collapses          |\n|Left/right arrow|none          |anchor/button|Expands/collapses          |\n|Left/right arrow|multiple      |div          |Expands/collapses          |\n|Left/right arrow|multiple      |anchor/button|N/A (not allowed)          |\n|Click           |none          |div          |Expands/collapses          |\n|Click           |multiple      |div          |Checks or unchecks         |\n|Click           |multiple      |anchor/button|N/A (not allowed)          |\n\n## JavaScript API\n\n`TreeView`s render a `<tree-view>` custom element that exposes behavior to the client.\n\n|Name                                                              |Notes                                                                                                                                             |\n|:-----------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|\n|`getNodePath(node: Element): string[]`                            |Returns the path to the given node.                                                                                                               |\n|`getNodeType(node: Element): TreeViewNodeType | null`             |Returns either `\"leaf\"` or `\"sub-tree\"`.                                                                                                          |\n|`markCurrentAtPath(path: string[])`                               |Marks the node as the \"current\" node, which appears visually distinct from other nodes.                                                           |\n|`get currentNode(): HTMLLIElement | null`                         |Returns the current node.                                                                                                                         |\n|`expandAtPath(path: string[])`                                    |Expands the sub-tree at `path`.                                                                                                                   |\n|`collapseAtPath(path: string[])`                                  |Collapses the sub-tree at `path`.                                                                                                                 |\n|`toggleAtPath(path: string[])`                                    |If the sub-tree at `path` is collapsed, this function expands it, and vice-versa.                                                                 |\n|`checkAtPath(path: string[])`                                     |If the node at `path` has a checkbox, this function checks it.                                                                                    |\n|`uncheckAtPath(path: string[])`                                   |If the node at `path` has a checkbox, this function unchecks it.                                                                                  |\n|`toggleCheckedAtPath(path: string[])`                             |If the sub-tree at `path` is checked, this function unchecks it, and vice-versa.                                                                  |\n|`checkedValueAtPath(path: string[]): TreeViewCheckedValue`        |Returns `\"true\"` (all child nodes are checked), `\"false\"` (no child nodes are checked), or `\"mixed\"` (some child nodes are checked, some are not).|\n|`nodeAtPath(path: string[], selector?: string): Element | null`   |Returns the node for the given `path`, either a leaf node or sub-tree node.                                                                       |\n|`subTreeAtPath(path: string[]): TreeViewSubTreeNodeElement | null`|Returns the sub-tree at the given `path`, if it exists.                                                                                           |\n|`leafAtPath(path: string[]): HTMLLIElement | null`                |Returns the leaf node at the given `path`, if it exists.                                                                                          |\n|`getNodeCheckedValue(node: Element): TreeViewCheckedValue`        |The same as `checkedValueAtPath`, but accepts a node instead of a path.                                                                           |\n\n### Events\n\nThe events enumerated below include node information by way of the `TreeViewNodeInfo` object, which has the\nfollowing signature:\n\n```typescript\ntype TreeViewNodeType = 'leaf' | 'sub-tree'\ntype TreeViewCheckedValue = 'true' | 'false' | 'mixed'\n\ntype TreeViewNodeInfo = {\n  node: Element\n  type: TreeViewNodeType\n  path: string[]\n  checkedValue: TreeViewCheckedValue\n  previousCheckedValue: TreeViewCheckedValue\n}\n```\n\n|Name                         |Type                                       |Bubbles |Cancelable |\n|:----------------------------|:------------------------------------------|:-------|:----------|\n|`treeViewNodeActivated`      |`CustomEvent<TreeViewNodeInfo>`            |Yes     |No         |\n|`treeViewBeforeNodeActivated`|`CustomEvent<TreeViewNodeInfo>`            |Yes     |Yes        |\n|`treeViewNodeExpanded`       |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |\n|`treeViewNodeCollapsed`      |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |\n|`treeViewNodeChecked`        |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |Yes        |\n|`treeViewBeforeNodeChecked`  |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |No         |\n\n_Item activation_\n\nThe `<tree-view>` element fires an `treeViewNodeActivated` event whenever a node is activated (eg. clicked)\nvia the mouse or keyboard.\n\nThe `treeViewBeforeNodeActivated` event fires before a node is activated. Canceling this event will prevent the\nnode from being activated.\n\n```typescript\ndocument.querySelector(\"select-panel\").addEventListener(\n  \"treeViewBeforeNodeActivated\",\n  (event: CustomEvent<TreeViewNodeInfo>) => {\n    event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)\n  }\n)\n```\n\n_Item checking/unchecking_\n\nThe `tree-view` element fires a `treeViewNodeChecked` event whenever a node is checked or unchecked.\n\nThe `treeViewBeforeNodeChecked` event fires before a node is checked or unchecked. Canceling this event will\nprevent the check/uncheck operation.\n\n```typescript\ndocument.querySelector(\"select-panel\").addEventListener(\n  \"treeViewBeforeNodeChecked\",\n  (event: CustomEvent<TreeViewNodeInfo[]>) => {\n    event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)\n  }\n)\n```\n\nBecause checking or unchecking a sub-tree results in the checking or unchecking of all its children recursively,\nboth the `treeViewNodeChecked` and `treeViewBeforeNodeChecked` events provide an array of `TreeViewNodeInfo`\nobjects, which contain entries for every modified node in the tree.",
+    "description": "TreeView is a hierarchical list of items that may have a parent-child relationship where children\ncan be toggled into view by expanding or collapsing their parent item.\n\n## Terminology\n\nConsider the following tree structure:\n\nsrc\n├ button.rb\n└ action_list\n  ├ item.rb\n  └ header.rb\n\n1. **Node**. A node is an item in the tree. Nodes can either be \"leaf\" nodes (i.e. have no children), or \"sub-tree\"\nnodes, which do have children. In the example above, button.rb, item.rb, and header.rb are all leaf nodes, while\naction_list is a sub-tree node.\n2. **Path**. A node's path is like its ID. It's an array of strings containing the current node's label and all the\nlabels of its ancestors, in order. In the example above, header.rb's path is [\"src\", \"action_list\", \"header.rb\"].\n\n## Static nodes\n\nThe `TreeView` component allows items to be provided statically or loaded dynamically from the server.\nProviding items statically is done using the `leaf` and `sub_tree` slots:\n\n```erb\n<%= render(Primer::Alpha::TreeView.new) do |tree| %>\n  <% tree.with_sub_tree(label: \"Directory\") do |sub_tree| %>\n    <% sub_tree.with_leaf(label: \"File 1\")\n  <% end %>\n  <% tree.with_leaf(label: \"File 2\") %>\n<% end %>\n```\n\n## Dynamic nodes\n\nTree nodes can also be fetched dynamically from the server and will require creating a Rails controller action\nto respond with the list of nodes. Unlike other Primer components, `TreeView` allows the programmer to specify\nloading behavior on a per-sub-tree basis, i.e. each sub-tree must specify how its nodes are loaded. To load nodes\ndynamically for a given sub-tree, configure it with either a loading spinner or a loading skeleton, and provide\nthe URL to fetch nodes from:\n\n```erb\n<%= render(Primer::Alpha::TreeView.new) do |tree| %>\n  <% tree.with_sub_tree(label: \"Directory\") do |sub_tree| %>\n    <% sub_tree.with_loading_spinner(src: primer_view_components.tree_view_items_path) %>\n  <% end %>\n<% end %>\n```\n\nDefine a controller action to serve the list of nodes. The `TreeView` component automatically includes the\nsub-tree's path as a GET parameter, encoded as a JSON array.\n\n```ruby\nclass TreeViewItemsController < ApplicationController\n  def show\n    @path = JSON.parse(params[:path])\n    @results = get_tree_items(starting_at: path)\n  end\nend\n```\n\nResponses must be HTML fragments, eg. have a content type of `text/html+fragment`. This content type isn't\navailable by default in Rails, so you may have to register it eg. in an initializer:\n\n```ruby\nMime::Type.register(\"text/fragment+html\", :html_fragment)\n```\n\nRender a `Primer::Alpha::TreeView::SubTree` in the action's template, tree_view_items/show.html_fragment.erb:\n\n```erb\n<%= render(Primer::Alpha::TreeView::SubTree.new(path: @path, node_variant: :div)) do |tree| %>\n  <% tree.with_leaf(...) %>\n  <% tree.with_sub_tree(...) do |sub_tree| %>\n    ...\n  <% end %>\n<% end %>\n```\n\n## Multi-select mode\n\nPassing `select_variant: :multiple` to both sub-tree and leaf nodes will add a check box to the left of the node's\nlabel. These check boxes behave according to the value of a second argument, `select_strategy:`.\n\nThe default select strategy, `:descendants`, will cause all child nodes to be checked when the node is checked.\nThis includes both sub-tree and leaf nodes. When the node is unchecked, all child nodes will also be unchecked.\nUnchecking a child node of a checked parent will cause the parent to enter a mixed or indeterminate state, which\nis represented by a horizontal line icon instead of a check mark. This icon indicates that some children are\nchecked, but not all.\n\nA secondary select strategy, `:self`, is provided to allow disabling the automatic checking of child nodes. When\n`select_strategy: :self` is specified, checking sub-tree nodes does not check child nodes, and sub-tree nodes\ncannot enter a mixed or indeterminate state.\n\nNodes can be checked via the keyboard by pressing the space key.\n\n## Single-select mode\n\nBy passing `select_variant: :single` to both sub-tree and leaf nodes:\n- Nodes become selectable and can be toggled via keyboard (space key).\n- A selected node displays a checkmark at the end of the line.\nNote: This checkmark conflicts with the `trailing_visual_icon` slot,\nso both cannot be used simultaneously.\n\n## Node tags\n\n`TreeView`s support three different node variants, `:anchor`, `:button`, and `:div` (the default), which controls\nwhich HTML tag is used to construct the nodes. The `:anchor` and `:button` variants correspond to `<a>` and\n`<button>` tags respectively, which are browser-native elements. Anchors and buttons can be activated (i.e.\n\"clicked\") using the mouse or keyboard via the enter or space keys. The node variant must be the same for all\nnodes in the tree, and is therefore specified at the root level, eg. `TreeView.new(node_variant: :anchor)`.\n\nTrees with node variants other than `:div` cannot have check boxes, i.e. cannot be put into multi-select mode.\n\nTrees with node variants other than `:div` do not emit the `treeViewNodeActivated` or `treeViewBeforeNodeActivated`\nevents, since it is assumed any behavior associated with these variants is user- or browser-defined.\n\n## Interaction behavior matrix\n\n|Interaction     |Select variant|Tag          |Result                     |\n|:---------------|:-------------|:------------|:--------------------------|\n|Enter/space     |none          |div          |Expands/collapses          |\n|Enter/space     |none          |anchor/button|Activates anchor/button    |\n|Enter/space     |single        |div          |Selects                    |\n|Enter/space     |single        |anchor/button|N/A (not allowed)          |\n|Enter/space     |multiple      |div          |Checks or unchecks         |\n|Enter/space     |multiple      |anchor/button|N/A (not allowed)          |\n|Left/right arrow|none          |div          |Expands/collapses          |\n|Left/right arrow|none          |anchor/button|Expands/collapses          |\n|Left/right arrow|single        |div          |Expands/collapses          |\n|Left/right arrow|single        |anchor/button|N/A (not allowed)          |\n|Left/right arrow|multiple      |div          |Expands/collapses          |\n|Left/right arrow|multiple      |anchor/button|N/A (not allowed)          |\n|Click           |none          |div          |Expands/collapses          |\n|Click           |single        |div          |Selects                    |\n|Click           |single        |anchor/button|N/A (not allowed)          |\n|Click           |multiple      |div          |Checks or unchecks         |\n|Click           |multiple      |anchor/button|N/A (not allowed)          |\n\n## JavaScript API\n\n`TreeView`s render a `<tree-view>` custom element that exposes behavior to the client.\n\n|Name                                                              |Notes                                                                                                                                             |\n|:-----------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|\n|`getNodePath(node: Element): string[]`                            |Returns the path to the given node.                                                                                                               |\n|`getNodeType(node: Element): TreeViewNodeType | null`             |Returns either `\"leaf\"` or `\"sub-tree\"`.                                                                                                          |\n|`markCurrentAtPath(path: string[])`                               |Marks the node as the \"current\" node, which appears visually distinct from other nodes.                                                           |\n|`get currentNode(): HTMLLIElement | null`                         |Returns the current node.                                                                                                                         |\n|`expandAtPath(path: string[])`                                    |Expands the sub-tree at `path`.                                                                                                                   |\n|`collapseAtPath(path: string[])`                                  |Collapses the sub-tree at `path`.                                                                                                                 |\n|`toggleAtPath(path: string[])`                                    |If the sub-tree at `path` is collapsed, this function expands it, and vice-versa.                                                                 |\n|`checkAtPath(path: string[])`                                     |If the node at `path` has a checkbox, this function checks it.                                                                                    |\n|`uncheckAtPath(path: string[])`                                   |If the node at `path` has a checkbox, this function unchecks it.                                                                                  |\n|`toggleCheckedAtPath(path: string[])`                             |If the sub-tree at `path` is checked, this function unchecks it, and vice-versa.                                                                  |\n|`checkedValueAtPath(path: string[]): TreeViewCheckedValue`        |Returns `\"true\"` (all child nodes are checked), `\"false\"` (no child nodes are checked), or `\"mixed\"` (some child nodes are checked, some are not).|\n|`nodeAtPath(path: string[], selector?: string): Element | null`   |Returns the node for the given `path`, either a leaf node or sub-tree node.                                                                       |\n|`subTreeAtPath(path: string[]): TreeViewSubTreeNodeElement | null`|Returns the sub-tree at the given `path`, if it exists.                                                                                           |\n|`leafAtPath(path: string[]): HTMLLIElement | null`                |Returns the leaf node at the given `path`, if it exists.                                                                                          |\n|`getNodeCheckedValue(node: Element): TreeViewCheckedValue`        |The same as `checkedValueAtPath`, but accepts a node instead of a path.                                                                           |\n\n### Events\n\nThe events enumerated below include node information by way of the `TreeViewNodeInfo` object, which has the\nfollowing signature:\n\n```typescript\ntype TreeViewNodeType = 'leaf' | 'sub-tree'\ntype TreeViewCheckedValue = 'true' | 'false' | 'mixed'\n\ntype TreeViewNodeInfo = {\n  node: Element\n  type: TreeViewNodeType\n  path: string[]\n  checkedValue: TreeViewCheckedValue\n  previousCheckedValue: TreeViewCheckedValue\n}\n```\n\n|Name                         |Type                                       |Bubbles |Cancelable |\n|:----------------------------|:------------------------------------------|:-------|:----------|\n|`treeViewNodeActivated`      |`CustomEvent<TreeViewNodeInfo>`            |Yes     |No         |\n|`treeViewBeforeNodeActivated`|`CustomEvent<TreeViewNodeInfo>`            |Yes     |Yes        |\n|`treeViewNodeExpanded`       |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |\n|`treeViewNodeCollapsed`      |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |\n|`treeViewNodeChecked`        |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |Yes        |\n|`treeViewBeforeNodeChecked`  |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |No         |\n\n_Item activation_\n\nThe `<tree-view>` element fires an `treeViewNodeActivated` event whenever a node is activated (eg. clicked)\nvia the mouse or keyboard.\n\nThe `treeViewBeforeNodeActivated` event fires before a node is activated. Canceling this event will prevent the\nnode from being activated.\n\n```typescript\ndocument.querySelector(\"select-panel\").addEventListener(\n  \"treeViewBeforeNodeActivated\",\n  (event: CustomEvent<TreeViewNodeInfo>) => {\n    event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)\n  }\n)\n```\n\n_Item checking/unchecking_\n\nThe `tree-view` element fires a `treeViewNodeChecked` event whenever a node is checked or unchecked.\n\nThe `treeViewBeforeNodeChecked` event fires before a node is checked or unchecked. Canceling this event will\nprevent the check/uncheck operation.\n\n```typescript\ndocument.querySelector(\"select-panel\").addEventListener(\n  \"treeViewBeforeNodeChecked\",\n  (event: CustomEvent<TreeViewNodeInfo[]>) => {\n    event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)\n  }\n)\n```\n\nBecause checking or unchecking a sub-tree may result in the checking or unchecking of all its children recursively,\nboth the `treeViewNodeChecked` and `treeViewBeforeNodeChecked` events provide an array of `TreeViewNodeInfo`\nobjects, which contain entries for every modified node in the tree.",
     "accessibility_docs": null,
     "is_form_component": false,
     "is_published": true,
@@ -10539,6 +10539,32 @@
           ]
         }
       },
+      {
+        "preview_path": "primer/alpha/tree_view/single_select",
+        "name": "single_select",
+        "snapshot": "interactive",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
+      },
+      {
+        "preview_path": "primer/alpha/tree_view/multi_select",
+        "name": "multi_select",
+        "snapshot": "interactive",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
+      },
       {
         "preview_path": "primer/alpha/tree_view/empty",
         "name": "empty",
@@ -11016,7 +11042,7 @@
             "name": "select_variant",
             "type": "Symbol",
             "default": "`:none`",
-            "description": "Controls the type of checkbox that appears. One of `:multiple` or `:none`."
+            "description": "Controls the type of checkbox that appears. One of `:multiple`, `:none`, or `:single`."
           },
           {
             "name": "checked",

data/static/previews.json

@@ -9113,6 +9113,32 @@
           ]
         }
       },
+      {
+        "preview_path": "primer/alpha/tree_view/single_select",
+        "name": "single_select",
+        "snapshot": "interactive",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
+      },
+      {
+        "preview_path": "primer/alpha/tree_view/multi_select",
+        "name": "multi_select",
+        "snapshot": "interactive",
+        "skip_rules": {
+          "wont_fix": [
+            "region"
+          ],
+          "will_fix": [
+            "color-contrast"
+          ]
+        }
+      },
       {
         "preview_path": "primer/alpha/tree_view/empty",
         "name": "empty",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openproject-primer_view_components
 version: !ruby/object:Gem::Version
-  version: 0.73.1
+  version: 0.74.0
 platform: ruby
 authors:
 - GitHub Open Source
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-09-30 00:00:00.000000000 Z
+date: 2025-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -1104,7 +1104,9 @@ files:
 - previews/primer/alpha/tree_view_preview/loading_failure.html.erb
 - previews/primer/alpha/tree_view_preview/loading_skeleton.html.erb
 - previews/primer/alpha/tree_view_preview/loading_spinner.html.erb
+- previews/primer/alpha/tree_view_preview/multi_select.html.erb
 - previews/primer/alpha/tree_view_preview/playground.html.erb
+- previews/primer/alpha/tree_view_preview/single_select.html.erb
 - previews/primer/alpha/underline_nav_preview.rb
 - previews/primer/alpha/underline_nav_preview/default.html.erb
 - previews/primer/alpha/underline_nav_preview/playground.html.erb