openproject-primer_view_components 0.64.1 → 0.65.0

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # A generic `TreeView` node.
+      #
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class Node < Primer::Component
+        # Generic leading action slot
+        renders_one :leading_action
+
+        # Generic leading visual slot
+        renders_one :leading_visual
+
+        # Generic trailing visual slot
+        renders_one :trailing_visual
+
+        # Generic toggle button slot
+        renders_one :toggle
+
+        # Generic text content slot (for node's label)
+        renders_one :text_content
+
+        # Wether or not this node is the current node.
+        #
+        # @return [Boolean]
+        attr_reader :current
+        alias current? current
+
+        # This node's checked state.
+        #
+        # @return [String]
+        attr_reader :checked
+
+        # This node's select variant (i.e. check box variant).
+        #
+        # @return [Symbol]
+        attr_reader :select_variant
+
+        DEFAULT_SELECT_VARIANT = :none
+        SELECT_VARIANT_OPTIONS = [
+          :multiple,
+          DEFAULT_SELECT_VARIANT
+        ].freeze
+
+        DEFAULT_CHECKED_STATE = false
+        CHECKED_STATES = [
+          DEFAULT_CHECKED_STATE,
+          true,
+          "mixed"
+        ]
+
+        # @param path [Array<String>] 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.
+        # @param current [Boolean] Whether or not this node is the current node. The current node is styled differently than regular nodes and is the first element that receives focus when tabbing to the `TreeView` component.
+        # @param select_variant [Symbol] Controls the type of checkbox that appears. <%= one_of(Primer::OpenProject::TreeView::Node::SELECT_VARIANT_OPTIONS) %>
+        # @param checked [Boolean | String] The checked state of the node's checkbox. <%= one_of(Primer::OpenProject::TreeView::Node::CHECKED_STATES) %>
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::ActionList) %>.
+        def initialize(
+          path:,
+          current: false,
+          select_variant: DEFAULT_SELECT_VARIANT,
+          checked: DEFAULT_CHECKED_STATE,
+          **system_arguments
+        )
+          @system_arguments = deny_tag_argument(**system_arguments)
+
+          @path = path
+          @current = current
+          @select_variant = fetch_or_fallback(SELECT_VARIANT_OPTIONS, select_variant, DEFAULT_SELECT_VARIANT)
+          @checked = fetch_or_fallback(CHECKED_STATES, checked, DEFAULT_CHECKED_STATE)
+
+          @system_arguments[:tag] = :li
+          @system_arguments[:role] = :treeitem
+          @system_arguments[:tabindex] = current? ? 0 : -1
+          @system_arguments[:classes] = class_names(
+            @system_arguments.delete(:classes),
+            "TreeViewItem"
+          )
+
+          @system_arguments[:aria] = merge_aria(
+            @system_arguments, {
+              aria: {
+                level: level,
+                selected: false,
+                checked: checked,
+                labelledby: content_id
+              }
+            }
+          )
+
+          @system_arguments[:data] = merge_data(
+            @system_arguments,
+            { data: { path: @path.to_json } }
+          )
+
+          return unless current?
+
+          @system_arguments[:aria] = merge_aria(
+            @system_arguments,
+            { aria: { current: true } }
+          )
+        end
+
+        # The numeric depth of this node.
+        #
+        # @return [Integer] This node's depth.
+        def level
+          @level ||= @path.size
+        end
+
+        # Merges the given arguments into the current hash of system arguments provided when the component was
+        # initially constructed. This method can be used to add additional arguments just before rendering.
+        #
+        # @param other_arguments [Hash] The other hash of system arguments to merge into the current one.
+        def merge_system_arguments!(**other_arguments)
+          @system_arguments[:aria] = merge_aria(
+            @system_arguments,
+            other_arguments
+          )
+
+          @system_arguments[:data] = merge_data(
+            @system_arguments,
+            other_arguments
+          )
+
+          @system_arguments.merge!(**other_arguments)
+        end
+
+        private
+
+        def before_render
+          if leading_visual?
+          end
+
+          if leading_action?
+            @system_arguments[:data] = merge_data(
+              @system_arguments,
+              { data: { "has-leading-action": true } }
+            )
+          end
+        end
+
+        def content_id
+          @content_id ||= "#{base_id}-content"
+        end
+
+        def base_id
+          @base_id ||= self.class.generate_id
+        end
+      end
+    end
+  end
+end

data/app/components/primer/open_project/tree_view/skeleton_loader.html.erb

@@ -0,0 +1,23 @@
+<% unless loading_failure_message? %>
+  <% with_loading_failure_message  # set the default %>
+<% end %>
+
+<%= render(Primer::BaseComponent.new(tag: :"tree-view-include-fragment", src: @src, loading: :lazy, data: { target: "tree-view-sub-tree-node.subTree tree-view-sub-tree-node.includeFragment", path: @container.path.to_json }, hidden: @container.expanded?, accept: "text/fragment+html")) do %>
+  <%= render(@container) do %>
+    <%= render(Primer::OpenProject::TreeView::Node.new(path: [*@container.path, :loader])) do |node| %>
+      <% node.with_text_content do %>
+        <div data-target="tree-view-sub-tree-node.loadingIndicator">
+          <% @count.times do %>
+            <span class="TreeViewSkeletonItemContainerStyle TreeViewItemSkeleton">
+              <%= render(Primer::OpenProject::SkeletonBox.new(width: "16px")) %>
+              <%= render(Primer::OpenProject::SkeletonBox.new(width: "100%", classes: "TreeItemSkeletonTextStyles")) %>
+            </span>
+          <% end %>
+        </div>
+        <div data-target="tree-view-sub-tree-node.loadingFailureMessage" hidden>
+          <%= loading_failure_message %>
+        </div>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # Renders a loading skeleton for a `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class SkeletonLoader < Primer::Component
+        # The failure message that appears if loading nodes from the server fails.
+        #
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::LoadingFailureMessage) %>.
+        renders_one :loading_failure_message, lambda { |**system_arguments|
+          system_arguments[:retry_button_arguments] ||= {}
+          system_arguments[:retry_button_arguments][:data] = merge_data(
+            system_arguments[:retry_button_arguments],
+            data: { target: "tree-view-sub-tree-node.retryButton" }
+          )
+
+          LoadingFailureMessage.new(**system_arguments)
+        }
+
+        # @param src [String] The URL to fetch nodes from.
+        # @param count [Integer] The number of skeleton nodes to render.
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::SubTreeContainer) %>.
+        def initialize(src:, count: 3, **system_arguments)
+          @src = src
+          @count = count
+
+          @container = SubTreeContainer.new(**system_arguments, expanded: true)
+        end
+      end
+    end
+  end
+end

data/app/components/primer/open_project/tree_view/spinner_loader.html.erb

@@ -0,0 +1,20 @@
+<% unless loading_failure_message? %>
+  <% with_loading_failure_message  # set the default %>
+<% end %>
+
+<%= render(Primer::BaseComponent.new(tag: :"tree-view-include-fragment", src: @src, loading: :lazy, data: { target: "tree-view-sub-tree-node.subTree tree-view-sub-tree-node.includeFragment", path: @container.path.to_json }, hidden: @container.expanded?, accept: "text/fragment+html")) do %>
+  <%= render(@container) do %>
+    <%= render(Primer::OpenProject::TreeView::Node.new(path: [*@container.path, :loader], data: { target: "tree-view-sub-tree-node.loadingIndicator" })) do |node| %>
+      <% node.with_text_content { "Loading..." } %>
+      <% node.with_leading_visual do %>
+        <%= render(Primer::Beta::Spinner.new(size: :small, wrapper_arguments: { classes: "TreeViewItemVisual" })) %>
+      <% end %>
+    <% end %>
+
+    <%= render(Primer::OpenProject::TreeView::Node.new(path: [*@container.path, :failure_msg], data: { target: "tree-view-sub-tree-node.loadingFailureMessage" }, hidden: true)) do |node| %>
+      <% node.with_text_content do %>
+        <%= loading_failure_message %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # Renders a loading spinner for a `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class SpinnerLoader < Primer::Component
+        # The failure message that appears if loading nodes from the server fails.
+        #
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::LoadingFailureMessage) %>.
+        renders_one :loading_failure_message, lambda { |**system_arguments|
+          system_arguments[:retry_button_arguments] ||= {}
+          system_arguments[:retry_button_arguments][:data] = merge_data(
+            system_arguments[:retry_button_arguments],
+            data: { target: "tree-view-sub-tree-node.retryButton" }
+          )
+
+          LoadingFailureMessage.new(**system_arguments)
+        }
+
+        # @param src [String] The URL to fetch nodes from.
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::SubTreeContainer) %>.
+        def initialize(src:, **system_arguments)
+          @src = src
+          @container = SubTreeContainer.new(**system_arguments, expanded: true)
+        end
+      end
+    end
+  end
+end

data/app/components/primer/open_project/tree_view/sub_tree.html.erb

@@ -0,0 +1,21 @@
+<% if defer? %>
+  <%= loader %>
+<% else %>
+  <% unless no_items_message? %>
+    <% with_no_items_message { "No items" }  # set the default %>
+  <% end %>
+
+  <%= render(@container) do %>
+    <% if nodes.empty? %>
+      <%= render(Primer::OpenProject::TreeView::Node.new(path: path, data: { "no-items": true })) do |node| %>
+        <% node.with_text_content do %>
+          <%= no_items_message %>
+        <% end %>
+      <% end %>
+    <% else %>
+      <% nodes.each do |node| %>
+        <%= node %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # A `TreeView` sub-tree.
+      #
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class SubTree < 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: [*path, label],
+                label: label
+              )
+            },
+
+            as: :leaf
+          },
+
+          sub_tree: {
+            renders: lambda { |component_klass: SubTreeNode, label:, **system_arguments|
+              component_klass.new(
+                **system_arguments,
+                path: [*path, label],
+                label: label
+              )
+            },
+
+            as: :sub_tree
+          }
+        }
+
+        # @!parse
+        #   # Adds a loader to this sub-tree that displays a spinner animation while nodes are fetched from the server.
+        #   #
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::SpinnerLoader) %>.
+        #   def with_loading_spinner(**system_arguments, &block)
+        #   end
+
+        # @!parse
+        #   # Adds a loader to this sub-tree that displays a skeleton animation while nodes are fetched from the server.
+        #   #
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::SkeletonLoader) %>.
+        #   def with_loading_spinner(**system_arguments, &block)
+        #   end
+
+        renders_one :loader, types: {
+          spinner: {
+            renders: lambda { |**system_arguments|
+              SpinnerLoader.new(**system_arguments, path: path)
+            },
+
+            as: :loading_spinner
+          },
+
+          skeleton: {
+            renders: lambda { |**system_arguments|
+              SkeletonLoader.new(**system_arguments, path: path)
+            },
+
+            as: :loading_skeleton
+          }
+        }
+
+        # The message to display if this sub-tree contains no children.
+        renders_one :no_items_message
+
+        delegate :path, :expanded?, to: :@container
+
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::SubTreeContainer) %>.
+        def initialize(**system_arguments)
+          system_arguments[:data] = merge_data(
+            system_arguments,
+            { data: { target: "tree-view-sub-tree-node.subTree" } }
+          )
+
+          @container = SubTreeContainer.new(**system_arguments)
+        end
+
+        def defer?
+          loader?
+        end
+      end
+    end
+  end
+end

data/app/components/primer/open_project/tree_view/sub_tree_container.html.erb

@@ -0,0 +1,3 @@
+<%= render(Primer::BaseComponent.new(**@system_arguments)) do %>
+  <%= content %>
+<% end %>

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class SubTreeContainer < Primer::Component
+        # The path to this node
+        #
+        # @return [Array<String>]
+        attr_reader :path
+
+        # Whether or not this sub-tree node renders expanded.
+        #
+        # @return [Boolean]
+        attr_reader :expanded
+
+        alias expanded? expanded
+
+        # @param path [Array<String>] The path to this node.
+        # @param expanded [Boolean] Whether or not this sub-tree node renders expanded.
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(path:, expanded: false, **system_arguments)
+          @system_arguments = deny_tag_argument(**system_arguments)
+          @path = path
+          @expanded = expanded
+
+          @system_arguments[:tag] = :ul
+          @system_arguments[:role] = :group
+          @system_arguments[:p] = 0
+          @system_arguments[:m] = 0
+          @system_arguments[:style] = "list-style: none;"
+          @system_arguments[:hidden] = !expanded?
+        end
+      end
+    end
+  end
+end

data/app/components/primer/open_project/tree_view/sub_tree_node.html.erb

@@ -0,0 +1,49 @@
+<tree-view-sub-tree-node>
+  <%= render(@node) do |node| %>
+    <% if leading_action? %>
+      <% node.with_leading_action do %>
+        <%= leading_action %>
+      <% end %>
+    <% end %>
+    <% if leading_visual? %>
+      <% node.with_leading_visual do %>
+        <%= leading_visual %>
+      <% end %>
+    <% end %>
+    <% if trailing_visual? %>
+      <% node.with_trailing_visual do %>
+        <%= trailing_visual %>
+      <% end %>
+    <% end %>
+
+    <% node.with_text_content { @label } %>
+
+    <% node.with_toggle do %>
+      <div
+        data-target="tree-view-sub-tree-node.toggleButton"
+        class="TreeViewItemToggle TreeViewItemToggleHover TreeViewItemToggleEnd">
+        <%= render(
+          Primer::Beta::Octicon.new(
+            icon: :"chevron-down",
+            size: :xsmall,
+            data: { target: "tree-view-sub-tree-node.expandedToggleIcon" },
+            hidden: !@sub_tree.expanded?,
+            style: "pointer-events: none;"
+          )
+        ) %>
+
+        <%= render(
+          Primer::Beta::Octicon.new(
+            icon: :"chevron-right",
+            size: :xsmall,
+            data: { target: "tree-view-sub-tree-node.collapsedToggleIcon" },
+            hidden: @sub_tree.expanded?,
+            style: "pointer-events: none;"
+          )
+        ) %>
+      </div>
+    <% end %>
+
+    <%= render(@sub_tree) %>
+  <% end %>
+</tree-view-sub-tree-node>

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

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Primer
+  module OpenProject
+    class TreeView
+      # A `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::OpenProject::TreeView) %> component and should
+      # not be used directly.
+      class SubTreeNode < Primer::Component
+        DEFAULT_SELECT_STRATEGY = :descendants
+        SELECT_STRATEGIES = [
+          :self,
+          DEFAULT_SELECT_STRATEGY
+        ]
+
+        # @!parse
+        #   # Adds a leading visual icon rendered to the left of the node's label.
+        #   #
+        #   # @param label [String] A label describing the visual, displayed only to screen readers.
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::Icon) %>.
+        #   def with_leading_visual_icon(label: nil, **system_arguments, &block)
+        #   end
+
+        # @!parse
+        #   # Adds a pair of leading visual icon rendered to the left of the node's label.
+        #   #
+        #   # @param label [String] A label describing the visual, displayed only to screen readers.
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::IconPair) %>.
+        #   def with_leading_visual_icons(label: nil, **system_arguments, &block)
+        #   end
+
+        renders_one :leading_visual, types: {
+          icon: lambda { |label: nil, **system_arguments|
+            merge_system_arguments!(
+              aria: { describedby: leading_visual_label_id }
+            )
+
+            Visual.new(
+              id: leading_visual_label_id,
+              label: label,
+              visual: Icon.new(**system_arguments)
+            )
+          },
+
+          icons: lambda { |label: nil, **system_arguments|
+            merge_system_arguments!(
+              aria: { describedby: leading_visual_label_id }
+            )
+
+            system_arguments[:data] = merge_data(
+              system_arguments,
+              { data: { target: "tree-view-sub-tree-node.iconPair" } }
+            )
+
+            Visual.new(
+              id: leading_visual_label_id,
+              label: label,
+              visual: IconPair.new(
+                **system_arguments,
+                expanded: @sub_tree.expanded?,
+              )
+            )
+          }
+        }
+
+        # @!parse
+        #   # Adds a leading action rendered to the left of the node's label and any leading visuals or checkboxes.
+        #   #
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Beta::IconButton) %>.
+        #   def with_leading_action_button(**system_arguments, &block)
+        #   end
+
+        renders_one :leading_action, types: {
+          button: lambda { |**system_arguments|
+            LeadingAction.new(
+              action: Primer::Beta::IconButton.new(
+                scheme: :invisible,
+                **system_arguments
+              )
+            )
+          }
+        }
+
+        # @!parse
+        #   # Adds a trailing visual icon rendered to the right of the node's label.
+        #   #
+        #   # @param label [String] A label describing the visual, displayed only to screen readers.
+        #   # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::Icon) %>.
+        #   def with_trailing_visual_icon(label: nil, **system_arguments, &block)
+        #   end
+
+        renders_one :trailing_visual, types: {
+          icon: lambda { |**system_arguments|
+            label = system_arguments.delete(:label)
+
+            Visual.new(
+              id: nil,
+              visual: Icon.new(**system_arguments),
+              label: label
+            )
+          }
+        }
+
+        delegate :with_leaf, :with_sub_tree, :with_loading_spinner, :with_loading_skeleton, to: :@sub_tree
+        delegate :current?, :merge_system_arguments!, to: :@node
+
+        # @param label [String] The node's label, i.e. it's textual content.
+        # @param path [Array<String>] 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.
+        # @param expanded [Boolean] Whether or not this sub-tree should be rendered expanded.
+        # @param select_strategy [Symbol] What should happen when this sub-tree node is checked. <%= one_of(Primer::OpenProject::TreeView::SubTreeNode::SELECT_STRATEGIES) %>
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::OpenProject::TreeView::Node) %>.
+        def initialize(label:, path:, expanded: false, select_strategy: DEFAULT_SELECT_STRATEGY, **system_arguments)
+          @label = label
+          @system_arguments = system_arguments
+          @select_strategy = fetch_or_fallback(SELECT_STRATEGIES, select_strategy, DEFAULT_SELECT_STRATEGY)
+
+          @system_arguments[:aria] = merge_aria(
+            @system_arguments,
+            { aria: { expanded: expanded } }
+          )
+
+          @system_arguments[:data] = merge_data(
+            @system_arguments, {
+              data: {
+                target: "tree-view-sub-tree-node.node",
+                "node-type": "sub-tree"
+              }
+            }
+          )
+
+          sub_tree_arguments = @system_arguments.delete(:sub_tree_arguments) || {}
+
+          @sub_tree = SubTree.new(
+            expanded: expanded,
+            path: path,
+            **sub_tree_arguments
+          )
+
+          @node = Primer::OpenProject::TreeView::Node.new(**@system_arguments, path: @sub_tree.path)
+
+          return if @node.select_variant == :none
+
+          @node.merge_system_arguments!(
+            data: {
+              "select-strategy": @select_strategy
+            }
+          )
+        end
+
+        def render_in(*args, &block)
+          super.tap do
+            # check this _after_ rendering so @sub_tree's slots are defined
+            if @node.select_variant != :none && @sub_tree.defer?
+              raise ArgumentError, "TreeView does not currently support select variants for sub-trees loaded asynchronously."
+            end
+          end
+        end
+
+        private
+
+        def base_id
+          @base_id ||= self.class.generate_id
+        end
+
+        def leading_visual_label_id
+          @leading_visual_id ||= "#{base_id}-leading-visual-label"
+        end
+      end
+    end
+  end
+end