openproject-primer_view_components 0.64.0 → 0.65.0

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

@@ -0,0 +1,319 @@
+/* stylelint-disable selector-max-type -- Copied from primer/react */
+
+.TreeViewRootUlStyles {
+  padding: 0;
+  margin: 0;
+  list-style: none;
+
+  /*
+   * WARNING: This is a performance optimization.
+   *
+   * We define styles for the tree items at the root level of the tree
+   * to avoid recomputing the styles for each item when the tree updates.
+   * We're sacrificing maintainability for performance because TreeView
+   * needs to be performant enough to handle large trees (thousands of items).
+   *
+   * This is intended to be a temporary solution until we can improve the
+   * performance of our styling patterns.
+   *
+   * Do NOT copy this pattern without understanding the tradeoffs.
+   */
+  & .TreeViewItem {
+    outline: none;
+
+    &:focus-visible > div {
+      box-shadow: var(--boxShadow-thick) var(--fgColor-accent);
+
+      @media (forced-colors: active) {
+        outline: 2px solid HighlightText;
+        /* stylelint-disable-next-line declaration-property-value-no-unknown -- Copied from primer/react */
+        outline-offset: -2;
+      }
+    }
+
+    &[data-has-leading-action] {
+      --has-leading-action: 1;
+    }
+  }
+
+  & .TreeViewItemContainer {
+    --level: 1;
+    --toggle-width: 1rem;
+    --min-item-height: 2rem;
+
+    position: relative;
+    display: grid;
+    width: 100%;
+    font-size: var(--text-body-size-medium);
+    color: var(--fgColor-default);
+    cursor: pointer;
+    border-radius: var(--borderRadius-medium);
+    grid-template-columns: var(--spacer-width) var(--leading-action-width) var(--toggle-width) 1fr;
+    grid-template-areas: 'spacer leadingAction toggle content';
+
+    --leading-action-width: calc(var(--has-leading-action, 0) * 1.5rem);
+    --spacer-width: calc(calc(var(--level) - 1) * (var(--toggle-width) / 2));
+
+    &:hover {
+      background-color: var(--control-transparent-bgColor-hover);
+
+      @media (forced-colors: active) {
+        outline: 2px solid transparent;
+        outline-offset: -2px;
+      }
+    }
+
+    @media (pointer: coarse) {
+      --toggle-width: 1.5rem;
+      --min-item-height: 2.75rem;
+    }
+
+    &:has(.TreeViewFailureMessage):hover {
+      cursor: default;
+      background-color: transparent;
+
+      @media (forced-colors: active) {
+        outline: none;
+      }
+    }
+  }
+
+  &:where([data-omit-spacer='true']) .TreeViewItemContainer {
+    grid-template-columns: 0 0 0 1fr;
+  }
+
+  & .TreeViewItem[aria-current='true'] > .TreeViewItemContainer {
+    background-color: var(--control-transparent-bgColor-selected);
+
+    /* Current item indicator */
+    /* stylelint-disable-next-line selector-max-specificity -- Copied from primer/react */
+    &::after {
+      position: absolute;
+      top: calc(50% - var(--base-size-12));
+      left: calc(-1 * var(--base-size-8));
+      width: 0.25rem;
+      height: 1.5rem;
+      content: '';
+
+      /*
+       * Use fgColor accent for consistency across all themes. Using the "correct" variable,
+       * --bgColor-accent-emphasis, causes vrt failures for dark high contrast mode
+       */
+      /* stylelint-disable-next-line primer/colors */
+      background-color: var(--fgColor-accent);
+      border-radius: var(--borderRadius-medium);
+
+      @media (forced-colors: active) {
+        background-color: HighlightText;
+      }
+    }
+  }
+
+  /* stylelint-disable-next-line no-duplicate-selectors -- Copied from primer/react */
+  & .TreeViewItem {
+    &[aria-checked='true'] {
+      /* stylelint-disable-next-line selector-max-compound-selectors, selector-max-specificity -- Copied from primer/react */
+      & > .TreeViewItemContainer .FormControl-checkbox {
+        background: var(--control-checked-bgColor-rest);
+        border-color: var(--control-checked-borderColor-rest);
+        transition: background-color, border-color 80ms cubic-bezier(0.32, 0, 0.67, 0) 0ms; /* unchecked -> checked */
+
+        /* stylelint-disable-next-line max-nesting-depth, selector-max-compound-selectors, selector-max-specificity -- Copied from primer/react */
+        &::before {
+          visibility: visible;
+          transition: visibility 0s linear 0s;
+          animation: checkmarkIn 80ms cubic-bezier(0.65, 0, 0.35, 1) forwards 80ms;
+        }
+      }
+    }
+
+    &[aria-checked='mixed'] {
+      /* stylelint-disable-next-line selector-max-compound-selectors, selector-max-specificity -- Copied from primer/react */
+      & > .TreeViewItemContainer .FormControl-checkbox {
+        background: var(--control-checked-bgColor-rest);
+        border-color: var(--control-checked-borderColor-rest);
+        transition: background-color, border-color 80ms cubic-bezier(0.32, 0, 0.67, 0) 0ms; /* unchecked -> checked */
+
+        /* stylelint-disable-next-line max-nesting-depth, selector-max-compound-selectors, selector-max-specificity -- Copied from primer/react */
+        &::before {
+          visibility: visible;
+          mask-image: url('data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTAiIGhlaWdodD0iMiIgdmlld0JveD0iMCAwIDEwIDIiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGZpbGwtcnVsZT0iZXZlbm9kZCIgY2xpcC1ydWxlPSJldmVub2RkIiBkPSJNMCAxQzAgMC40NDc3MTUgMC40NDc3MTUgMCAxIDBIOUM5LjU1MjI5IDAgMTAgMC40NDc3MTUgMTAgMUMxMCAxLjU1MjI4IDkuNTUyMjkgMiA5IDJIMUMwLjQ0NzcxNSAyIDAgMS41NTIyOCAwIDFaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K');
+          animation: checkmarkIn 80ms cubic-bezier(0.65, 0, 0.35, 1) forwards 80ms;
+          clip-path: none;
+        }
+      }
+    }
+  }
+
+  & .TreeViewItemToggle {
+    display: flex;
+    height: 100%;
+
+    /* The toggle should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc(var(--min-item-height) / 2 - var(--base-size-12) / 2);
+    color: var(--fgColor-muted);
+    grid-area: toggle;
+    justify-content: center;
+    align-items: flex-start;
+  }
+
+  & .TreeViewItemToggleHover:hover {
+    background-color: var(--control-transparent-bgColor-hover);
+  }
+
+  & .TreeViewItemToggleEnd {
+    border-top-left-radius: var(--borderRadius-medium);
+    border-bottom-left-radius: var(--borderRadius-medium);
+  }
+
+  & .TreeViewItemContent {
+    display: flex;
+    height: 100%;
+    padding: 0 var(--base-size-8);
+
+    /* The dynamic top and bottom padding to maintain the minimum item height for single line items */
+    /* stylelint-disable-next-line primer/spacing */
+    padding-top: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    /* stylelint-disable-next-line primer/spacing */
+    padding-bottom: calc((var(--min-item-height) - var(--custom-line-height, 1.3rem)) / 2);
+    line-height: var(--custom-line-height, var(--text-body-lineHeight-medium, 1.4285));
+    grid-area: content;
+    gap: var(--stack-gap-condensed);
+
+    & .TreeViewItemCheckbox {
+      position: relative;
+      color: var(--control-fgColor-rest);
+      text-align: left;
+      user-select: none;
+      background-color: transparent;
+      border: none;
+      border-radius: var(--borderRadius-medium);
+      transition: background 33.333ms linear;
+      touch-action: manipulation;
+      -webkit-tap-highlight-color: transparent;
+    }
+  }
+
+  & .TreeViewItemContentText {
+    flex: 1 1 auto;
+    width: 0;
+  }
+
+  &:where([data-truncate-text='true']) .TreeViewItemContentText {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &:where([data-truncate-text='false']) .TreeViewItemContentText {
+    /* stylelint-disable-next-line declaration-property-value-keyword-no-deprecated -- Copied from primer/react */
+    word-break: break-word;
+  }
+
+  & .TreeViewItemVisual {
+    display: flex;
+
+    /* The visual icons should appear vertically centered for single-line items, but remain at the top for items that wrap
+    across more lines. */
+    height: var(--custom-line-height, 1.3rem);
+    color: var(--fgColor-muted);
+    align-items: center;
+  }
+
+  & .TreeViewItemLeadingAction {
+    display: flex;
+    color: var(--fgColor-muted);
+    grid-area: leadingAction;
+
+    & > button {
+      flex-shrink: 1;
+    }
+  }
+
+  & .TreeViewItemLevelLine {
+    width: 100%;
+    height: 100%;
+
+    /*
+     * On devices without hover, the nesting indicator lines
+     * appear at all times.
+     */
+    border-color: var(--borderColor-muted);
+    border-right: var(--borderWidth-thin) solid;
+  }
+
+  /*
+   * On devices with :hover support, the nesting indicator lines
+   * fade in when the user mouses over the entire component,
+   * or when there's focus inside the component. This makes
+   * sure the component remains simple when not in use.
+   */
+  @media (hover: hover) {
+    .TreeViewItemLevelLine {
+      border-color: transparent;
+    }
+
+    &:hover .TreeViewItemLevelLine,
+    &:focus-within .TreeViewItemLevelLine {
+      border-color: var(--borderColor-muted);
+    }
+  }
+
+  & .TreeViewVisuallyHidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    /* stylelint-disable-next-line primer/spacing */
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  }
+}
+
+.TreeViewSkeletonItemContainerStyle {
+  display: flex;
+  align-items: center;
+  column-gap: 0.5rem;
+  height: 2rem;
+
+  @media (pointer: coarse) {
+    height: 2.75rem;
+  }
+
+  &:nth-of-type(5n + 1) {
+    --tree-item-loading-width: 67%;
+  }
+
+  &:nth-of-type(5n + 2) {
+    --tree-item-loading-width: 47%;
+  }
+
+  &:nth-of-type(5n + 3) {
+    --tree-item-loading-width: 73%;
+  }
+
+  &:nth-of-type(5n + 4) {
+    --tree-item-loading-width: 64%;
+  }
+
+  &:nth-of-type(5n + 5) {
+    --tree-item-loading-width: 50%;
+  }
+}
+
+.TreeItemSkeletonTextStyles {
+  width: var(--tree-item-loading-width, 67%);
+}
+
+.TreeViewFailureMessage {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.5rem;
+  width: 100%;
+  align-items: center;
+}

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

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+# The TreeView component is made up of a number of smaller components, quite a few more than have been created
+# to construct complex components in the past. The current architecture was designed to achieve reusability for
+# certain features like loading indicators, different icons for expanded and collapsed sub trees, etc. The
+# following describes how the components fit together at a high level, using React-like syntax. Each element
+# in the diagram corresponds to one of three types of object:
+#
+# 1. Elements with TitleCase tags represent components in the Primer::OpenProject::TreeView namespace, eg. <LeafNode>.
+# 2. Elements with dasherized-tags are web components/custom elements, eg. <tree-view>.
+# 3. Elements with lowercase tags are regular 'ol HTML elements, eg. <ul>.
+#
+# ### Overall structure
+#
+# <TreeView>
+#   <tree-view>
+#     <ul role="tree">
+#       <LeafNode>
+#         <Node>
+#           <li role="treeitem">
+#             ...
+#           </li>
+#         </Node>
+#       </LeafNode>
+#
+#       <SubTreeNode>
+#         <tree-view-sub-tree-node>
+#           <li role="treeitem">
+#
+#             <SubTreeContainer>
+#               <ul role="group">
+#                 <SubTree>
+#                   <LeafNode>
+#                     <Node>
+#                       <li role="treeitem">
+#                         ...
+#                       </li>
+#                     </Node>
+#                   </LeafNode>
+#
+#                   <SubTreeNode>
+#                     <tree-view-sub-tree-node>
+#                       <Node>
+#                         <li role="treeitem">
+#                           ...
+#                         </li>
+#                       </Node>
+#                       <SubTreeContainer>
+#                         <ul role="group">
+#                           ...
+#                         </ul>
+#                       </SubTreeContainer>
+#                     </tree-view-sub-tree-node>
+#                   </SubTreeNode>
+#                 </SubTree>
+#               </ul>
+#             </SubTreeContainer>
+#
+#           </li>
+#         </tree-view-sub-tree-node>
+#       </SubTreeNode>
+#     </ul>
+#   </tree-view>
+# </TreeView>
+#
+# ### Leading visuals
+#
+# TreeView nodes (i.e. both leaf and sub tree nodes) support leading and trailing visuals. At the time of this
+# writing, only octicons are supported. The single icon case is achieved by using a standard slot, but the
+# component also supports rendering distinct icons for both the expanded and collapsed states. An overview of the
+# markup for this more complicated multi-icon feature is described below.
+#
+# <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>
+#   </Node>
+# </LeafNode>
+#
+# ### Loaders
+#
+# TreeViews support two types of loader: a loading spinner and a loading skeleton.
+#
+# #### Loading spinner
+#
+# <SubTree>
+#   <SpinnerLoader>
+#     <tree-view-include-fragment>
+#       <SubTreeContainer>
+#         <Node>
+#           <Primer::Beta::Spinner />
+#         </Node>
+#         <Node>
+#           <LoadingFailureMessage />
+#         </Node>
+#       </SubTreeContainer>
+#     </tree-view-include-fragment>
+#   </SpinnerLoader>
+# </SubTree>
+#
+# #### Loading skeleton
+#
+# <SubTree>
+#   <SkeletonLoader>
+#     <tree-view-include-fragment>
+#       <SubTreeContainer>
+#         <Node>
+#           <span>
+#             <Primer::Alpha::SkeletonBox width="16px" />
+#             <Primer::Alpha::SkeletonBox width="100%" />
+#           </span>
+#           <span>
+#             ...
+#           </span>
+#           ...
+#         </Node>
+#         <Node>
+#           <LoadingFailureMessage />
+#         </Node>
+#       </SubTreeContainer>
+#     </tree-view-include-fragment>
+#   </SkeletonLoader>
+# </SubTree>
+
+module Primer
+  module OpenProject
+    # TreeView is a hierarchical list of items that may have a parent-child relationship where children
+    # can be toggled into view by expanding or collapsing their parent item.
+    #
+    # ## Terminology
+    #
+    # Consider the following tree structure:
+    #
+    # src
+    # ├ button.rb
+    # └ action_list
+    #   ├ item.rb
+    #   └ header.rb
+    #
+    # 1. **Node**. A node is an item in the tree. Nodes can either be "leaf" nodes (i.e. have no children), or "sub-tree"
+    # nodes, which do have children. In the example above, button.rb, item.rb, and header.rb are all leaf nodes, while
+    # action_list is a sub-tree node.
+    # 2. **Path**. A node's path is like its ID. It's an array of strings containing the current node's label and all the
+    # labels of its ancestors, in order. In the example above, header.rb's path is ["src", "action_list", "header.rb"].
+    #
+    # ## Static nodes
+    #
+    # The `TreeView` component allows items to be provided statically or loaded dynamically from the server.
+    # Providing items statically is done using the `leaf` and `sub_tree` slots:
+    #
+    # ```erb
+    # <%= render(Primer::OpenProject::TreeView.new) do |tree| %>
+    #   <% tree.with_sub_tree(label: "Directory") do |sub_tree| %>
+    #     <% sub_tree.with_leaf(label: "File 1")
+    #   <% end %>
+    #   <% tree.with_leaf(label: "File 2") %>
+    # <% end %>
+    # ```
+    #
+    # ## Dynamic nodes
+    #
+    # Tree nodes can also be fetched dynamically from the server and will require creating a Rails controller action
+    # to respond with the list of nodes. Unlike other Primer components, `TreeView` allows the programmer to specify
+    # loading behavior on a per-sub-tree basis, i.e. each sub-tree must specify how its nodes are loaded. To load nodes
+    # dynamically for a given sub-tree, configure it with either a loading spinner or a loading skeleton, and provide
+    # the URL to fetch nodes from:
+    #
+    # ```erb
+    # <%= render(Primer::OpenProject::TreeView.new) do |tree| %>
+    #   <% tree.with_sub_tree(label: "Directory") do |sub_tree| %>
+    #     <% sub_tree.with_loading_spinner(src: tree_view_items_path) %>
+    #   <% end %>
+    # <% end %>
+    # ```
+    #
+    # Define a controller action to serve the list of nodes. The `TreeView` component automatically includes the
+    # sub-tree's path as a GET parameter, encoded as a JSON array.
+    #
+    # ```ruby
+    # class TreeViewItemsController < ApplicationController
+    #   def show
+    #     @path = JSON.parse(params[:path])
+    #     @results = get_tree_items(starting_at: path)
+    #   end
+    # end
+    # ```
+    #
+    # Responses must be HTML fragments, eg. have a content type of `text/html+fragment`. This content type isn't
+    # available by default in Rails, so you may have to register it eg. in an initializer:
+    #
+    # ```ruby
+    # Mime::Type.register("text/fragment+html", :html_fragment)
+    # ```
+    #
+    # 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| %>
+    #   <% tree.with_leaf(...) %>
+    #   <% tree.with_sub_tree(...) do |sub_tree| %>
+    #     ...
+    #   <% end %>
+    # <% end %>
+    # ```
+    #
+    # ### JavaScript API
+    #
+    # `TreeView`s render a `<tree-view>` custom element that exposes behavior to the client.
+    #
+    # |Name                                                              |Notes                                                                                                                                             |
+    # |:-----------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------|
+    # |`getNodePath(node: Element): string[]`                            |Returns the path to the given node.                                                                                                               |
+    # |`getNodeType(node: Element): TreeViewNodeType | null`             |Returns either `"leaf"` or `"sub-tree"`.                                                                                                          |
+    # |`markCurrentAtPath(path: string[])`                               |Marks the node as the "current" node, which appears visually distinct from other nodes.                                                           |
+    # |`get currentNode(): HTMLLIElement | null`                         |Returns the current node.                                                                                                                         |
+    # |`expandAtPath(path: string[])`                                    |Expands the sub-tree at `path`.                                                                                                                   |
+    # |`collapseAtPath(path: string[])`                                  |Collapses the sub-tree at `path`.                                                                                                                 |
+    # |`toggleAtPath(path: string[])`                                    |If the sub-tree at `path` is collapsed, this function expands it, and vice-versa.                                                                 |
+    # |`checkAtPath(path: string[])`                                     |If the node at `path` has a checkbox, this function checks it.                                                                                    |
+    # |`uncheckAtPath(path: string[])`                                   |If the node at `path` has a checkbox, this function unchecks it.                                                                                  |
+    # |`toggleCheckedAtPath(path: string[])`                             |If the sub-tree at `path` is checked, this function unchecks it, and vice-versa.                                                                  |
+    # |`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).|
+    # |`nodeAtPath(path: string[], selector?: string): Element | null`   |Returns the node for the given `path`, either a leaf node or sub-tree node.                                                                       |
+    # |`subTreeAtPath(path: string[]): TreeViewSubTreeNodeElement | null`|Returns the sub-tree at the given `path`, if it exists.                                                                                           |
+    # |`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
+    #
+    # The events enumerated below include node information by way of the `TreeViewNodeInfo` object, which has the
+    # following signature:
+    #
+    # ```typescript
+    # type TreeViewNodeType = 'leaf' | 'sub-tree'
+    # type TreeViewCheckedValue = 'true' | 'false' | 'mixed'
+    #
+    # type TreeViewNodeInfo = {
+    #   node: Element
+    #   type: TreeViewNodeType
+    #   path: string[]
+    #   checkedValue: TreeViewCheckedValue
+    #   previousCheckedValue: TreeViewCheckedValue
+    # }
+    # ```
+    #
+    # |Name                         |Type                                       |Bubbles |Cancelable |
+    # |:----------------------------|:------------------------------------------|:-------|:----------|
+    # |`treeViewNodeActivated`      |`CustomEvent<TreeViewNodeInfo>`            |Yes     |No         |
+    # |`treeViewBeforeNodeActivated`|`CustomEvent<TreeViewNodeInfo>`            |Yes     |Yes        |
+    # |`treeViewNodeExpanded`       |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |
+    # |`treeViewNodeCollapsed`      |`CustomEvent<TreeViewNodeInfo>>`           |Yes     |No         |
+    # |`treeViewNodeChecked`        |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |Yes        |
+    # |`treeViewBeforeNodeChecked`  |`CustomEvent<TreeViewNodeInfo[]>`          |Yes     |No         |
+    #
+    # _Item activation_
+    #
+    # The `<tree-view>` element fires an `treeViewNodeActivated` event whenever a node is activated (eg. clicked)
+    # via the mouse or keyboard.
+    #
+    # The `treeViewBeforeNodeActivated` event fires before a node is activated. Canceling this event will prevent the
+    # node from being activated.
+    #
+    # ```typescript
+    # document.querySelector("select-panel").addEventListener(
+    #   "treeViewBeforeNodeActivated",
+    #   (event: CustomEvent<TreeViewNodeInfo>) => {
+    #     event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)
+    #   }
+    # )
+    # ```
+    #
+    # _Item checking/unchecking_
+    #
+    # The `tree-view` element fires a `treeViewNodeChecked` event whenever a node is checked or unchecked.
+    #
+    # The `treeViewBeforeNodeChecked` event fires before a node is checked or unchecked. Canceling this event will
+    # prevent the check/uncheck operation.
+    #
+    # ```typescript
+    # document.querySelector("select-panel").addEventListener(
+    #   "treeViewBeforeNodeChecked",
+    #   (event: CustomEvent<TreeViewNodeInfo[]>) => {
+    #     event.preventDefault() // Cancel the event to prevent activation (eg. expanding/collapsing)
+    #   }
+    # )
+    # ```
+    #
+    # Because checking or unchecking a sub-tree results in the checking or unchecking of all its children recursively,
+    # 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
+      # @!parse
+      #   # Adds an leaf node to the tree. Leaf nodes are nodes that do not have children.
+      #   #
+      #   # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::OpenProject::TreeView::LeafNode) %>
+      #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::OpenProject::TreeView::LeafNode) %>, or whatever class is passed as the `component_klass` argument.
+      #   def with_leaf(**system_arguments, &block)
+      #   end
+
+      # @!parse
+      #   # Adds a sub-tree node to the tree. Sub-trees are nodes that have children, which can be both leaf nodes and other sub-trees.
+      #   #
+      #   # @param component_klass [Class] The class to use instead of the default <%= link_to_component(Primer::OpenProject::TreeView::SubTreeNode) %>
+      #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::OpenProject::TreeView::SubTreeNode) %>, or whatever class is passed as the `component_klass` argument.
+      #   def with_sub_tree(**system_arguments, &block)
+      #   end
+
+      renders_many :nodes, types: {
+        leaf: {
+          renders: lambda { |component_klass: LeafNode, label:, **system_arguments|
+            component_klass.new(
+              **system_arguments,
+              path: [label],
+              label: label
+            )
+          },
+
+          as: :leaf
+        },
+
+        sub_tree: {
+          renders: lambda { |component_klass: SubTreeNode, label:, **system_arguments|
+            component_klass.new(
+              **system_arguments,
+              path: [label],
+              label: label
+            )
+          },
+
+          as: :sub_tree
+        }
+      }
+
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>.
+      def initialize(**system_arguments)
+        @system_arguments = deny_tag_argument(**system_arguments)
+
+        @system_arguments[:tag] = :ul
+        @system_arguments[:role] = :tree
+        @system_arguments[:classes] = class_names(
+          @system_arguments.delete(:classes),
+          "TreeViewRootUlStyles"
+        )
+      end
+
+      private
+
+      def before_render
+        if (first_node = nodes.first)
+          first_node.merge_system_arguments!(tabindex: 0)
+        end
+      end
+    end
+  end
+end

data/app/components/primer/primer.d.ts

@@ -33,3 +33,7 @@ import './open_project/danger_dialog_form_helper';
 import './open_project/collapsible';
 import './open_project/border_box/collapsible_header';
 import './open_project/collapsible_section';
+import './open_project/tree_view/tree_view';
+import './open_project/tree_view/tree_view_icon_pair_element';
+import './open_project/tree_view/tree_view_sub_tree_node_element';
+import './open_project/tree_view/tree_view_include_fragment_element';