openproject-primer_view_components 0.66.2 → 0.68.0

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

@@ -17,23 +17,27 @@
 #     <ul role="tree">
 #       <LeafNode>
 #         <Node>
-#           <li role="treeitem">
-#             ...
+#           <li role="none">
+#             <div role="treeitem">
+#               ...
+#             </div>
 #           </li>
 #         </Node>
 #       </LeafNode>
 #
 #       <SubTreeNode>
 #         <tree-view-sub-tree-node>
-#           <li role="treeitem">
+#           <li role="none">
 #
 #             <SubTreeContainer>
 #               <ul role="group">
 #                 <SubTree>
 #                   <LeafNode>
 #                     <Node>
-#                       <li role="treeitem">
-#                         ...
+#                       <li role="none">
+#                         <div role="treeitem">
+#                           ...
+#                         </div>
 #                       </li>
 #                     </Node>
 #                   </LeafNode>
@@ -41,8 +45,10 @@
 #                   <SubTreeNode>
 #                     <tree-view-sub-tree-node>
 #                       <Node>
-#                         <li role="treeitem">
-#                           ...
+#                         <li role="none">
+#                           <div role="treeitem">
+#                             ...
+#                           </div>
 #                         </li>
 #                       </Node>
 #                       <SubTreeContainer>
@@ -72,19 +78,21 @@
 #
 # <LeafNode>
 #   <Node>
-#     <li role="treeitem">
-#       <Visual>
-#         <IconPair>
-#           <tree-view-icon-pair>
-#             <Icon slot="expanded_icon">
-#               <Primer::Beta::Octicon />
-#             </Icon>
-#             <Icon slot="collapsed_icon">
-#               <Primer::Beta::Octicon />
-#             </Icon>
-#           </tree-view-icon-pair>
-#         </IconPair>
-#       </Visual>
+#     <li role="none">
+#       <div role="treeitem">
+#         <Visual>
+#           <IconPair>
+#             <tree-view-icon-pair>
+#               <Icon slot="expanded_icon">
+#                 <Primer::Beta::Octicon />
+#               </Icon>
+#               <Icon slot="collapsed_icon">
+#                 <Primer::Beta::Octicon />
+#               </Icon>
+#             </tree-view-icon-pair>
+#           </IconPair>
+#         </Visual>
+#       </div>
 #     </li>
 #   </Node>
 # </LeafNode>
@@ -207,7 +215,7 @@ module Primer
     # Render a `Primer::OpenProject::TreeView::SubTree` in the action's template, tree_view_items/show.html_fragment.erb:
     #
     # ```erb
-    # <%= render(Primer::OpenProject::TreeView::SubTree.new(path: @path)) do |tree| %>
+    # <%= render(Primer::OpenProject::TreeView::SubTree.new(path: @path, node_variant: :div)) do |tree| %>
     #   <% tree.with_leaf(...) %>
     #   <% tree.with_sub_tree(...) do |sub_tree| %>
     #     ...
@@ -215,7 +223,53 @@ module Primer
     # <% end %>
     # ```
     #
-    # ### JavaScript API
+    # ## Multi-select mode
+    #
+    # Passing `select_variant: :multiple` to both sub-tree and leaf nodes will add a check box to the left of the node's
+    # label. These check boxes behave according to the value of a second argument, `select_strategy:`.
+    #
+    # The default select strategy, `:descendants`, will cause all child nodes to be checked when the node is checked.
+    # This includes both sub-tree and leaf nodes. When the node is unchecked, all child nodes will also be unchecked.
+    # Unchecking a child node of a checked parent will cause the parent to enter a mixed or indeterminate state, which
+    # is represented by a horizontal line icon instead of a check mark. This icon indicates that some children are
+    # checked, but not all.
+    #
+    # A secondary select strategy, `:self`, is provided to allow disabling the automatic checking of child nodes. When
+    # `select_strategy: :self` is specified, checking sub-tree nodes does not check child nodes, and sub-tree nodes
+    # cannot enter a mixed or indeterminate state.
+    #
+    # Nodes can be checked via the keyboard by pressing the space key.
+    #
+    # ## Node tags
+    #
+    # `TreeView`s support three different node variants, `:anchor`, `:button`, and `:div` (the default), which controls
+    # which HTML tag is used to construct the nodes. The `:anchor` and `:button` variants correspond to `<a>` and
+    # `<button>` tags respectively, which are browser-native elements. Anchors and buttons can be activated (i.e.
+    # "clicked") using the mouse or keyboard via the enter or space keys. The node variant must be the same for all
+    # nodes in the tree, and is therefore specified at the root level, eg. `TreeView.new(node_variant: :anchor)`.
+    #
+    # Trees with node variants other than `:div` cannot have check boxes, i.e. cannot be put into multi-select mode.
+    #
+    # Trees with node variants other than `:div` do not emit the `treeViewNodeActivated` or `treeViewBeforeNodeActivated`
+    # events, since it is assumed any behavior associated with these variants is user- or browser-defined.
+    #
+    # ## Interaction behavior matrix
+    #
+    # |Interaction     |Select variant|Tag          |Result                     |
+    # |:---------------|:-------------|:------------|:--------------------------|
+    # |Enter/space     |none          |div          |Expands/collapses          |
+    # |Enter/space     |none          |anchor/button|Activates anchor/button    |
+    # |Enter/space     |multiple      |div          |Checks or unchecks         |
+    # |Enter/space     |multiple      |anchor/button|N/A (not allowed)          |
+    # |Left/right arrow|none          |div          |Expands/collapses          |
+    # |Left/right arrow|none          |anchor/button|Expands/collapses          |
+    # |Left/right arrow|multiple      |div          |Expands/collapses          |
+    # |Left/right arrow|multiple      |anchor/button|N/A (not allowed)          |
+    # |Click           |none          |div          |Expands/collapses          |
+    # |Click           |multiple      |div          |Checks or unchecks         |
+    # |Click           |multiple      |anchor/button|N/A (not allowed)          |
+    #
+    # ## JavaScript API
     #
     # `TreeView`s render a `<tree-view>` custom element that exposes behavior to the client.
     #
@@ -237,7 +291,7 @@ module Primer
     # |`leafAtPath(path: string[]): HTMLLIElement | null`                |Returns the leaf node at the given `path`, if it exists.                                                                                          |
     # |`getNodeCheckedValue(node: Element): TreeViewCheckedValue`        |The same as `checkedValueAtPath`, but accepts a node instead of a path.                                                                           |
     #
-    # #### Events
+    # ### Events
     #
     # The events enumerated below include node information by way of the `TreeViewNodeInfo` object, which has the
     # following signature:
@@ -301,6 +355,9 @@ module Primer
     # both the `treeViewNodeChecked` and `treeViewBeforeNodeChecked` events provide an array of `TreeViewNodeInfo`
     # objects, which contain entries for every modified node in the tree.
     class TreeView < Primer::Component
+      DEFAULT_NODE_VARIANT = :div
+      NODE_VARIANT_OPTIONS = [DEFAULT_NODE_VARIANT, :anchor, :button].freeze
+
       # @!parse
       #   # Adds an leaf node to the tree. Leaf nodes are nodes that do not have children.
       #   #
@@ -322,6 +379,7 @@ module Primer
           renders: lambda { |component_klass: LeafNode, label:, **system_arguments|
             component_klass.new(
               **system_arguments,
+              node_variant: node_variant,
               path: [label],
               label: label
             )
@@ -334,6 +392,7 @@ module Primer
           renders: lambda { |component_klass: SubTreeNode, label:, **system_arguments|
             component_klass.new(
               **system_arguments,
+              node_variant: node_variant,
               path: [label],
               label: label
             )
@@ -343,10 +402,15 @@ module Primer
         }
       }
 
+      attr_reader :node_variant
+
+      # @param node_variant [Symbol] The variant to use for this node. <%= one_of(Primer::OpenProject::TreeView::NODE_VARIANT_OPTIONS) %>
       # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>.
-      def initialize(**system_arguments)
+      def initialize(node_variant: DEFAULT_NODE_VARIANT, **system_arguments)
         @system_arguments = deny_tag_argument(**system_arguments)
 
+        @node_variant = fetch_or_fallback(NODE_VARIANT_OPTIONS, node_variant, DEFAULT_NODE_VARIANT)
+
         @system_arguments[:tag] = :ul
         @system_arguments[:role] = :tree
         @system_arguments[:classes] = class_names(

data/lib/primer/view_components/version.rb

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

data/previews/primer/open_project/tree_view_preview/async_alpha.html.erb

@@ -0,0 +1,12 @@
+<div style="max-width: 400px">
+  <%= render(Primer::OpenProject::TreeView.new) do |tree_view| %>
+    <% tree_view.with_sub_tree(label: "primer") do |sub_tree| %>
+      <% sub_tree.with_leading_visual_icons do |icons| %>
+        <% icons.with_expanded_icon(icon: :"file-directory-open-fill", color: :accent) %>
+        <% icons.with_collapsed_icon(icon: :"file-directory-fill", color: :accent) %>
+      <% end %>
+
+      <% sub_tree.with_loading_skeleton(src: tree_view_items_async_alpha_path(action_menu_expanded: action_menu_expanded)) %>
+    <% end %>
+  <% end %>
+</div>

data/previews/primer/open_project/tree_view_preview/buttons.html.erb

@@ -0,0 +1,10 @@
+<div style="max-width: 400px">
+  <%= render(Primer::OpenProject::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')") %>
+    <% end %>
+
+    <% tree_view.with_leaf(label: "What do you give a sick bird?", onclick: "alert('Tweetment')") %>
+  <% end %>
+</div>

data/previews/primer/open_project/tree_view_preview/links.html.erb

@@ -0,0 +1,17 @@
+<div style="max-width: 400px">
+  <%= render(Primer::OpenProject::TreeView.new(node_variant: :anchor)) do |tree_view| %>
+    <% tree_view.with_sub_tree(label: "Cloud Services", href: "https://en.wikipedia.org/wiki/Cloud_computing", target: "blank", expanded: expanded) do |sub_tree| %>
+      <% sub_tree.with_leaf(label: "OpenProject", href: "https://www.openproject.org", target: "blank") do |node| %>
+        <% node.with_trailing_visual_icon(icon: :"link-external") %>
+      <% end %>
+
+      <% sub_tree.with_leaf(label: "Hetzner", href: "https://www.hetzner.com", target: "blank") do |node| %>
+        <% node.with_trailing_visual_icon(icon: :"link-external") %>
+      <% end %>
+    <% end %>
+
+    <% tree_view.with_leaf(label: "GitHub", href: "https://github.com", target: "blank") do |node| %>
+      <% node.with_trailing_visual_icon(icon: :"link-external") %>
+    <% end %>
+  <% end %>
+</div>

data/previews/primer/open_project/tree_view_preview.rb

@@ -10,7 +10,11 @@ module Primer
       # @param expanded [Boolean] toggle
       # @param select_variant [Symbol] select [multiple, none]
       # @param select_strategy [Symbol] select [self, descendants]
-      def default(expanded: false, select_variant: :none, select_strategy: :descendants)
+      def default(
+        expanded: false,
+        select_variant: Primer::OpenProject::TreeView::Node::DEFAULT_SELECT_VARIANT,
+        select_strategy: Primer::OpenProject::TreeView::SubTreeNode::DEFAULT_SELECT_STRATEGY
+      )
         render_with_template(locals: {
           expanded: coerce_bool(expanded),
           select_variant: select_variant.to_sym,
@@ -23,7 +27,11 @@ module Primer
       # @param expanded [Boolean] toggle
       # @param select_variant [Symbol] select [multiple, none]
       # @param select_strategy [Symbol] select [self, descendants]
-      def playground(expanded: false, select_variant: :none, select_strategy: :descendants)
+      def playground(
+        expanded: false,
+        select_variant: Primer::OpenProject::TreeView::Node::DEFAULT_SELECT_VARIANT,
+        select_strategy: Primer::OpenProject::TreeView::SubTreeNode::DEFAULT_SELECT_STRATEGY
+      )
         render_with_template(locals: {
           expanded: coerce_bool(expanded),
           select_variant: select_variant.to_sym,
@@ -68,6 +76,15 @@ module Primer
         })
       end
 
+      # @label Async alpha
+      #
+      # @param action_menu_expanded [Boolean] toggle
+      def async_alpha(action_menu_expanded: false)
+        render_with_template(locals: {
+          action_menu_expanded: coerce_bool(action_menu_expanded)
+        })
+      end
+
       # @label Leaf node playground
       #
       # @param label [String] text
@@ -80,7 +97,7 @@ module Primer
         leading_visual_icon: nil,
         leading_action_icon: nil,
         trailing_visual_icon: nil,
-        select_variant: :none
+        select_variant: Primer::OpenProject::TreeView::Node::DEFAULT_SELECT_VARIANT
       )
         render_with_template(locals: {
           label: label,
@@ -91,6 +108,39 @@ module Primer
         })
       end
 
+      # @label Links
+      #
+      # @param expanded [Boolean] toggle
+      def links(expanded: false)
+        render_with_template(locals: {
+          expanded: coerce_bool(expanded)
+        })
+      end
+
+      # @label Buttons
+      #
+      # @param expanded [Boolean] toggle
+      def buttons(expanded: false)
+        render_with_template(locals: {
+          expanded: coerce_bool(expanded)
+        })
+      end
+
+      # @label Auto expansion
+      #
+      def auto_expansion
+        render(Primer::OpenProject::TreeView.new) do |tree|
+          tree.with_sub_tree(label: "Level 1") do |level1|
+            level1.with_sub_tree(label: "Level 2") do |level2|
+              # marking this node as expanded should automatically expand all ancestors
+              level2.with_sub_tree(label: "Level 3", expanded: true) do |level3|
+                level3.with_leaf(label: "Level 4")
+              end
+            end
+          end
+        end
+      end
+
       private
 
       def coerce_bool(value)

data/static/arguments.json

@@ -5419,6 +5419,12 @@
     "source": "https://github.com/primer/view_components/tree/main/app/components/primer/open_project/file_tree_view.rb",
     "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/open_project/file_tree_view/default/",
     "parameters": [
+      {
+        "name": "node_variant",
+        "type": "Symbol",
+        "default": "`:div`",
+        "description": "The variant to use for this node. One of `:anchor`, `:button`, or `:div`."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",
@@ -5844,6 +5850,12 @@
     "source": "https://github.com/primer/view_components/tree/main/app/components/primer/open_project/tree_view.rb",
     "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/open_project/tree_view/default/",
     "parameters": [
+      {
+        "name": "node_variant",
+        "type": "Symbol",
+        "default": "`:div`",
+        "description": "The variant to use for this node. One of `:anchor`, `:button`, or `:div`."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",
@@ -5970,6 +5982,18 @@
         "default": "N/A",
         "description": "The node's \"path,\" i.e. this node's label and the labels of all its ancestors. This node should be reachable by traversing the tree following this path."
       },
+      {
+        "name": "node_variant",
+        "type": "Symbol",
+        "default": "N/A",
+        "description": "The node variant to use for the node's content, i.e. the `:button` or `:div`. One of `:anchor`, `:button`, or `:div`."
+      },
+      {
+        "name": "href",
+        "type": "String",
+        "default": "`nil`",
+        "description": "The URL to use as the `href` attribute for this node. If set to a truthy value, the `tag:` parameter is ignored and assumed to be `:a`."
+      },
       {
         "name": "current",
         "type": "Boolean",
@@ -5989,10 +6013,10 @@
         "description": "The checked state of the node's checkbox. One of `false`, `mixed`, or `true`."
       },
       {
-        "name": "system_arguments",
+        "name": "content_arguments",
         "type": "Hash",
         "default": "N/A",
-        "description": "The arguments accepted by [ActionList](/components/alpha/actionlist)."
+        "description": "Arguments attached to the node's content, i.e the `<button>` or `<a>` element. [System arguments](/system-arguments)"
       }
     ]
   },
@@ -6054,6 +6078,12 @@
     "source": "https://github.com/primer/view_components/tree/main/app/components/primer/open_project/tree_view/sub_tree.rb",
     "lookbook": "https://primer.style/view-components/lookbook/inspect/primer/open_project/tree_view/sub_tree/default/",
     "parameters": [
+      {
+        "name": "node_variant",
+        "type": "Symbol",
+        "default": "N/A",
+        "description": "The variant to use for this node. One of `:anchor`, `:button`, or `:div`."
+      },
       {
         "name": "system_arguments",
         "type": "Hash",
@@ -6110,6 +6140,12 @@
         "default": "N/A",
         "description": "The node's \"path,\" i.e. this node's label and the labels of all its ancestors. This node should be reachable by traversing the tree following this path."
       },
+      {
+        "name": "node_variant",
+        "type": "Symbol",
+        "default": "N/A",
+        "description": "The variant to use for this node. One of `:anchor`, `:button`, or `:div`."
+      },
       {
         "name": "expanded",
         "type": "Boolean",

data/static/constants.json

@@ -1721,7 +1721,7 @@
   },
   "Primer::OpenProject::PageHeader::Title": {
     "GeneratedSlotMethods": "Primer::OpenProject::PageHeader::Title::GeneratedSlotMethods",
-    "HEADING_TAG_FALLBACK": "h1",
+    "HEADING_TAG_FALLBACK": "h2",
     "HEADING_TAG_OPTIONS": [
       "h1",
       "h2",
@@ -1786,12 +1786,18 @@
     "GeneratedSlotMethods": "Primer::OpenProject::SubHeader::SegmentedControl::GeneratedSlotMethods"
   },
   "Primer::OpenProject::TreeView": {
+    "DEFAULT_NODE_VARIANT": "div",
     "GeneratedSlotMethods": "Primer::OpenProject::TreeView::GeneratedSlotMethods",
     "Icon": "Primer::OpenProject::TreeView::Icon",
     "IconPair": "Primer::OpenProject::TreeView::IconPair",
     "LeadingAction": "Primer::OpenProject::TreeView::LeadingAction",
     "LeafNode": "Primer::OpenProject::TreeView::LeafNode",
     "LoadingFailureMessage": "Primer::OpenProject::TreeView::LoadingFailureMessage",
+    "NODE_VARIANT_OPTIONS": [
+      "div",
+      "anchor",
+      "button"
+    ],
     "Node": "Primer::OpenProject::TreeView::Node",
     "SkeletonLoader": "Primer::OpenProject::TreeView::SkeletonLoader",
     "SpinnerLoader": "Primer::OpenProject::TreeView::SpinnerLoader",
@@ -1824,8 +1830,19 @@
       "mixed"
     ],
     "DEFAULT_CHECKED_STATE": false,
+    "DEFAULT_NODE_VARIANT": "div",
     "DEFAULT_SELECT_VARIANT": "none",
     "GeneratedSlotMethods": "Primer::OpenProject::TreeView::Node::GeneratedSlotMethods",
+    "NODE_VARIANT_TAG_MAP": {
+      "div": "div",
+      "button": "button",
+      "anchor": "a"
+    },
+    "NODE_VARIANT_TAG_OPTIONS": [
+      "div",
+      "button",
+      "anchor"
+    ],
     "SELECT_VARIANT_OPTIONS": [
       "multiple",
       "none"