primer_view_components 0.43.5 → 0.44.0

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class TreeView
+      # Renders a loading skeleton for a `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::Alpha::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::Alpha::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::Alpha::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/alpha/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::Alpha::TreeView::Node.new(path: [*@container.path, :loader], data: { target: "tree-view-sub-tree-node.loadingIndicator" }, node_variant: :div)) 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::Alpha::TreeView::Node.new(path: [*@container.path, :failure_msg], data: { target: "tree-view-sub-tree-node.loadingFailureMessage" }, hidden: true, node_variant: :div)) do |node| %>
+      <% node.with_text_content do %>
+        <%= loading_failure_message %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class TreeView
+      # Renders a loading spinner for a `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::Alpha::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::Alpha::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::Alpha::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/alpha/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::Alpha::TreeView::Node.new(path: path, data: { "no-items": true }, node_variant: :div)) 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/alpha/tree_view/sub_tree.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class TreeView
+      # A `TreeView` sub-tree.
+      #
+      # This component is part of the <%= link_to_component(Primer::Alpha::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::Alpha::TreeView::LeafNode) %>
+        #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Alpha::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::Alpha::TreeView::SubTreeNode) %>
+        #   # @param system_arguments [Hash] These arguments are forwarded to <%= link_to_component(Primer::Alpha::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,
+                node_variant: node_variant,
+                path: [*path, label],
+                label: label
+              )
+            },
+
+            as: :leaf
+          },
+
+          sub_tree: {
+            renders: lambda { |component_klass: SubTreeNode, label:, **system_arguments|
+              component_klass.new(
+                **system_arguments,
+                node_variant: node_variant,
+                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::Alpha::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::Alpha::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
+
+        attr_reader :node_variant
+
+        # @param node_variant [Symbol] The variant to use for this node. <%= one_of(Primer::Alpha::TreeView::NODE_VARIANT_OPTIONS) %>
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::TreeView::SubTreeContainer) %>.
+        def initialize(node_variant:, **system_arguments)
+          @node_variant = node_variant
+
+          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/alpha/tree_view/sub_tree_container.html.erb

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

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class TreeView
+      # This component is part of the <%= link_to_component(Primer::Alpha::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/alpha/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/alpha/tree_view/sub_tree_node.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    class TreeView
+      # A `TreeView` sub-tree node.
+      #
+      # This component is part of the <%= link_to_component(Primer::Alpha::TreeView) %> component and should
+      # not be used directly.
+      class SubTreeNode < Primer::Component
+        DEFAULT_SELECT_STRATEGY = :mixed_descendants
+        SELECT_STRATEGIES = [
+          :self,
+          DEFAULT_SELECT_STRATEGY,
+          :descendants
+        ]
+
+        # @!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::Alpha::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::Alpha::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::Alpha::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, :nodes, 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 node_variant [Symbol] The variant to use for this node. <%= one_of(Primer::Alpha::TreeView::NODE_VARIANT_OPTIONS) %>
+        # @param sub_tree_component_klass [Class] The class to use for the sub-tree instead of the default <%= link_to_component(Primer::Alpha::TreeView::SubTree) %>
+        # @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::Alpha::TreeView::SubTreeNode::SELECT_STRATEGIES) %>
+        # @param system_arguments [Hash] The arguments accepted by <%= link_to_component(Primer::Alpha::TreeView::Node) %>.
+        def initialize(
+          label:,
+          path:,
+          node_variant:,
+          sub_tree_component_klass: SubTree,
+          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 = sub_tree_component_klass.new(
+            expanded: expanded,
+            path: path,
+            node_variant: node_variant,
+            **sub_tree_arguments
+          )
+
+          @node = Primer::Alpha::TreeView::Node.new(
+            **@system_arguments,
+            path: @sub_tree.path,
+            node_variant: node_variant
+          )
+
+          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

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

@@ -0,0 +1,39 @@
+import { TreeViewSubTreeNodeElement } from './tree_view_sub_tree_node_element';
+import type { TreeViewNodeType, TreeViewCheckedValue, TreeViewNodeInfo } from '../../shared_events';
+export declare class TreeViewElement extends HTMLElement {
+    #private;
+    formInputContainer: HTMLElement;
+    formInputPrototype: HTMLInputElement;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    handleEvent(event: Event): void;
+    getFormInputValueForNode(node: Element): string | null;
+    getNodePath(node: Element): string[];
+    getNodeType(node: Element): TreeViewNodeType | null;
+    markCurrentAtPath(path: string[]): void;
+    get currentNode(): HTMLLIElement | null;
+    expandAtPath(path: string[]): void;
+    collapseAtPath(path: string[]): void;
+    toggleAtPath(path: string[]): void;
+    checkAtPath(path: string[]): void;
+    uncheckAtPath(path: string[]): void;
+    toggleCheckedAtPath(path: string[]): void;
+    checkedValueAtPath(path: string[]): TreeViewCheckedValue;
+    disabledValueAtPath(path: string[]): boolean;
+    nodeAtPath(path: string[], selector?: string): Element | null;
+    subTreeAtPath(path: string[]): TreeViewSubTreeNodeElement | null;
+    leafAtPath(path: string[]): HTMLLIElement | null;
+    setNodeCheckedValue(node: Element, value: TreeViewCheckedValue): void;
+    getNodeCheckedValue(node: Element): TreeViewCheckedValue;
+    getNodeDisabledValue(node: Element): boolean;
+    setNodeDisabledValue(node: Element, disabled: boolean): void;
+    nodeHasCheckBox(node: Element): boolean;
+    nodeHasNativeAction(node: Element): boolean;
+    expandAncestorsForNode(node: HTMLElement): void;
+    infoFromNode(node: Element, newCheckedValue?: TreeViewCheckedValue): TreeViewNodeInfo | null;
+}
+declare global {
+    interface Window {
+        TreeViewElement: typeof TreeViewElement;
+    }
+}