primer_view_components 0.0.60 → 0.0.61

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb6606f92936041aed71037f2590bdd1ea29778b963a5396f19dcf8d57b70dc5
-  data.tar.gz: 2f0525e24ddb1e5fa304220caaec413b52e4543c81196e2401a33ca4fb13fdbc
+  metadata.gz: 61a72c86047d4820bb909bb7aba73505a1401868e362831ce3cfcd44f6c65da2
+  data.tar.gz: cedb04ce42976410ad380e5d39e448fc2078f07fb3d26b3d2ce4e7d79141f6ea
 SHA512:
-  metadata.gz: 525f0e51074bc3490763836ce5060180d6222048333b53a768ae4cb287e6cff234ef69a5b570b760328fc4a26da165bf586694b3a0ecdf8287d750426c258541
-  data.tar.gz: ba7fd3fbb1ab40e214fa6be6ceda52b84875d48c49f7aa75c790d3d594049b0a183e4a94959f36a82ccafa47acdc4ee9c1e0d065f33659ceb710adabbd50e933
+  metadata.gz: 714f04473ef45b3a80c4fcad50dbcd575a981c93b990f770844e903d561dc016cc88a94b09567deaa9954680add33581bc002c6f80b3a3590d2e64faf9397c63
+  data.tar.gz: 8d982a43c2fd2a0d5fe32287c129c8d4559ae2441e3124f9f50857ccbf25e2a4a3b63426e6f5a1c24572d6d8804b90849a3e600e3680de3efdbc59c92de0293e

data/CHANGELOG.md

@@ -30,6 +30,76 @@ The category for changes related to documentation, testing and tooling. Also, fo
 
 ## main
 
+## 0.0.61
+
+### New
+
+* Adding new Alpha component: `Layout` with `main` and `sidebar` slots
+
+    *Cameron Dutro*
+
+* Add a two-column layout linter.
+
+    *Cameron Dutro*
+
+* Add the `HellipButton` component
+
+    *Amélia Chavot*, *Owen Niblock*
+
+### Updates
+
+* Bump Storybook version to include Skip to Content links for keyboard auditors
+
+    *Katie Foster @inkblotty*
+
+* Update the `HiddenTextExpander` component to use the `HellipButton`.
+
+    *Amélia Chavot*, *Owen Niblock*
+
+### Misc
+
+* Fix components not rendering in Storybook because of kebab case arguments.
+
+    *Amélia Chavot*, *Manuel Puyol*, *Owen Niblock*
+
+* Fix a typo on a command on the contribution page.
+
+    *Amélia Chavot*, *Owen Niblock*
+
+### Bug Fixes
+
+* Fix issue where tags were not self-closing when they are void elements
+
+    *Owen Niblock*
+
+### Deprecations
+
+* Deprecate `Primer::BlankslateComponent` in favor of `Primer::Beta::Blankslate`.
+
+    *Manuel Puyol*
+
+### Breaking Changes
+
+* Require an `aria-label` to be provided for the `HiddenTextExpander` component.
+
+    *Amélia Chavot*, *Owen Niblock*
+
+* Rename `force_system_arguments` to `raise_on_invalid_options` to better reflect its functionality
+
+    *Owen Niblock*
+
+* Renamed `Blankslate` `title` slot to `heading`.
+
+    *Manuel Puyol*
+
+* Removed `Blankslate` `large` variant.
+
+    *Manuel Puyol*
+
+* Renamed `Blankslate` `graphic` slot to `visual`.
+
+    *Manuel Puyol*
+
 ## 0.0.60
 
 ### Updates
@@ -535,7 +605,7 @@ The category for changes related to documentation, testing and tooling. Also, fo
 
     *Manuel Puyol*
 
-* Added a changelog authoring guide to `CHANGELOG.md`.
+* Add a changelog authoring guide to `CHANGELOG.md`.
 
     *Amélia Chavot*
 

data/app/components/primer/alpha/layout.html.erb

@@ -0,0 +1,5 @@
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
+  <% if @first_in_source == :main %><%= main %><% end %>
+  <%= sidebar %>
+  <% if @first_in_source == :sidebar %><%= main %><% end %>
+<% end %>

data/app/components/primer/alpha/layout.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # `Layout` provides foundational patterns for responsive pages.
+    # `Layout` can be used for simple two-column pages, or it can be nested to provide flexible 3-column experiences.
+    #  On smaller screens, `Layout` uses vertically stacked rows to display content.
+    #
+    # `Layout` flows as both column, when there's enough horizontal space to render both `Main` and `Sidebar`side-by-side (on a desktop of tablet device, per instance);
+    # or it flows as a row, when `Main` and `Sidebar` are stacked vertically (e.g. on a mobile device).
+    # `Layout` should always work in any screen size.
+    #
+    # @accessibility
+    #   Keyboard navigation follows the markup order. Decide carefully how the focus order should be be by deciding whether
+    #   `main` or `sidebar` comes first in code. The code order won’t affect the visual position.
+    class Layout < Primer::Component
+      FIRST_IN_SOURCE_DEFAULT = :sidebar
+      FIRST_IN_SOURCE_OPTIONS = [FIRST_IN_SOURCE_DEFAULT, :main].freeze
+
+      SIDEBAR_COL_PLACEMENT_DEFAULT = :start
+      SIDEBAR_COL_PLACEMENT_OPTIONS = [SIDEBAR_COL_PLACEMENT_DEFAULT, :end].freeze
+
+      GUTTER_DEFAULT = :default
+      GUTTER_MAPPINGS = {
+        :none => "Layout--gutter-none",
+        :condensed => "Layout--gutter-condensed",
+        :spacious => "Layout--gutter-spacious",
+        GUTTER_DEFAULT => ""
+      }.freeze
+      GUTTER_OPTIONS = GUTTER_MAPPINGS.keys.freeze
+
+      STACKING_BREAKPOINT_DEFAULT = :md
+      STACKING_BREAKPOINT_MAPPINGS = {
+        :sm => "",
+        STACKING_BREAKPOINT_DEFAULT => "Layout--flowRow-until-md",
+        :lg => "Layout--flowRow-until-lg"
+      }.freeze
+      STACKING_BREAKPOINT_OPTIONS = STACKING_BREAKPOINT_MAPPINGS.keys.freeze
+
+      SIDEBAR_ROW_PLACEMENT_DEFAULT = :start
+      SIDEBAR_ROW_PLACEMENT_OPTIONS = [SIDEBAR_ROW_PLACEMENT_DEFAULT, :end, :none].freeze
+
+      SIDEBAR_WIDTH_DEFAULT = :default
+      SIDEBAR_WIDTH_MAPPINGS = {
+        SIDEBAR_WIDTH_DEFAULT => "",
+        :narrow => "Layout--sidebar-narrow",
+        :wide => "Layout--sidebar-wide"
+      }.freeze
+      SIDEBAR_WIDTH_OPTIONS = SIDEBAR_WIDTH_MAPPINGS.keys.freeze
+
+      # The layout's main content.
+      #
+      # @param width [Symbol] <%= one_of(Primer::Alpha::Layout::Main::WIDTH_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :main, "Primer::Alpha::Layout::Main"
+
+      # The layout's sidebar.
+      #
+      # @param width [Symbol] <%= one_of(Primer::Alpha::Layout::SIDEBAR_WIDTH_OPTIONS) %>
+      # @param col_placement [Symbol] Sidebar placement when `Layout` is in column modes. <%= one_of(Primer::Alpha::Layout::SIDEBAR_COL_PLACEMENT_OPTIONS) %>
+      # @param row_placement [Symbol] Sidebar placement when `Layout` is in row mode. <%= one_of(Primer::Alpha::Layout::SIDEBAR_ROW_PLACEMENT_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :sidebar, lambda { |
+        width: SIDEBAR_WIDTH_DEFAULT,
+        col_placement: SIDEBAR_COL_PLACEMENT_DEFAULT,
+        row_placement: SIDEBAR_ROW_PLACEMENT_DEFAULT,
+        **system_arguments
+      |
+        # These classes have to be set in the parent `Layout` element, so we modify its system arguments.
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "Layout--sidebarPosition-#{fetch_or_fallback(SIDEBAR_COL_PLACEMENT_OPTIONS, col_placement, SIDEBAR_COL_PLACEMENT_DEFAULT)}",
+          "Layout--sidebarPosition-flowRow-#{fetch_or_fallback(SIDEBAR_ROW_PLACEMENT_OPTIONS, row_placement, SIDEBAR_ROW_PLACEMENT_DEFAULT)}",
+          SIDEBAR_WIDTH_MAPPINGS[fetch_or_fallback(SIDEBAR_WIDTH_OPTIONS, width, SIDEBAR_WIDTH_DEFAULT)]
+        )
+
+        Primer::Alpha::Layout::Sidebar.new(**system_arguments)
+      }
+
+      # @example Default
+      #
+      #   <%= render(Primer::Alpha::Layout.new) do |c| %>
+      #     <% c.main(border: true) { "Main" } %>
+      #     <% c.sidebar(border: true) { "Sidebar" } %>
+      #   <% end %>
+      #
+      # @example Main widths
+      #
+      #   @description
+      #     When `full`, the main column will stretch to cover all the available width.
+      #     Otherwise, the main column will try to be centered in the screen; it may appear aligned to the left when there isn't enough space.
+      #
+      #     Use smaller maximum widths in the main column to facilitate interface scanning and reading.
+      #
+      #     When flowing as a row, `Main` takes the full width.
+      #
+      #   @code
+      #     <%= render(Primer::Alpha::Layout.new) do |c| %>
+      #       <% c.main(width: :full, border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(width: :md, border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(width: :lg, border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(width: :xl, border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar widths
+      #
+      #   @description
+      #     Sets the sidebar width. The width is predetermined according to the breakpoint instead of it being percentage-based.
+      #
+      #     - `default`: [md: 256px, lg: 296px, xl: 320px]
+      #     - `narrow`: [md: 240px, lg: 256px, xl: 296px]
+      #     - `wide`: [md: 296px, lg: 320px, xl: 344px]
+      #
+      #     When flowing as a row, `Sidebar` takes the full width.
+      #
+      #   @code
+      #     <%= render(Primer::Alpha::Layout.new) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(width: :default, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(width: :narrow, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(width: :wide, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar placement
+      #
+      #   @description
+      #     Use `start` for sidebars that manipulate local navigation, while right-aligned `end` is useful for metadata and other auxiliary information.
+      #
+      #   @code
+      #     <%= render(Primer::Alpha::Layout.new) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(col_placement: :start, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new( mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(col_placement: :end, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Sidebar placement as row
+      #
+      #   @description
+      #     When flowing as a row, whether the sidebar is rendered first or last in the layout, or, if it's entirely hidden from the user.
+      #
+      #     When `hidden`, make sure the experience is not degraded on smaller screens, and the user can still access the sidebar content somehow.
+      #     For instance, the user may not see a Settings navigation sidebar when drilled down on a page, but they can still navigate to the Settings
+      #     landing page to interact with the local navigation.
+      #
+      #   @code
+      #     <%= render(Primer::Alpha::Layout.new) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(row_placement: :start, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(row_placement: :end, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(row_placement: :none, border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @example Changing when to render `Layout` as columns
+      #
+      #   @description
+      #     You can specify when the `Layout` should change from rows into columns.
+      #     Any screen size before this breakpoint will render the `Layout` in stacked rows.
+      #
+      #   @code
+      #     <%= render(Primer::Alpha::Layout.new(stacking_breakpoint: :sm)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(stacking_breakpoint: :md, mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #     <%= render(Primer::Alpha::Layout.new(stacking_breakpoint: :lg, mt: 5)) do |c| %>
+      #       <% c.main(border: true) { "Main" } %>
+      #       <% c.sidebar(border: true) { "Sidebar" } %>
+      #     <% end %>
+      #
+      # @param stacking_breakpoint [Symbol] When the `Layout` should change from rows into columns. <%= one_of(Primer::Alpha::Layout::STACKING_BREAKPOINT_OPTIONS) %>
+      # @param first_in_source [Symbol] Which element to render first in the HTML. This will change the keyboard navigation order. <%= one_of(Primer::Alpha::Layout::FIRST_IN_SOURCE_OPTIONS) %>
+      # @param gutter [Symbol] The amount of space between the main section and the sidebar. <%= one_of(Primer::Alpha::Layout::GUTTER_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(stacking_breakpoint: STACKING_BREAKPOINT_DEFAULT, first_in_source: FIRST_IN_SOURCE_DEFAULT, gutter: :default, **system_arguments)
+        @first_in_source = fetch_or_fallback(FIRST_IN_SOURCE_OPTIONS, first_in_source, FIRST_IN_SOURCE_OPTIONS)
+
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
+          "Layout",
+          STACKING_BREAKPOINT_MAPPINGS[fetch_or_fallback(STACKING_BREAKPOINT_OPTIONS, stacking_breakpoint, STACKING_BREAKPOINT_DEFAULT)],
+          GUTTER_MAPPINGS[fetch_or_fallback(GUTTER_OPTIONS, gutter, GUTTER_DEFAULT)],
+          system_arguments[:classes]
+        )
+      end
+
+      def render?
+        main.present? && sidebar.present?
+      end
+
+      # The layout's main content.
+      class Main < Primer::Component
+        WIDTH_DEFAULT = :full
+        WIDTH_OPTIONS = [WIDTH_DEFAULT, :md, :lg, :xl].freeze
+
+        TAG_DEFAULT = :div
+        TAG_OPTIONS = [TAG_DEFAULT, :main].freeze
+
+        # @param width [Symbol] <%= one_of(Primer::Alpha::Layout::Main::WIDTH_OPTIONS) %>
+        # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+        def initialize(tag: TAG_DEFAULT, width: WIDTH_DEFAULT, **system_arguments)
+          @width = fetch_or_fallback(WIDTH_OPTIONS, width, WIDTH_DEFAULT)
+
+          @system_arguments = system_arguments
+          @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+          @system_arguments[:classes] = class_names(
+            "Layout-main",
+            system_arguments[:classes]
+          )
+        end
+
+        def call
+          render(Primer::BaseComponent.new(**@system_arguments)) do
+            if @width == :full
+              content
+            else
+              render(Primer::BaseComponent.new(tag: :div, classes: "Layout-main-centered-#{@width}")) do
+                render(Primer::BaseComponent.new(tag: :div, container: @width)) do
+                  content
+                end
+              end
+            end
+          end
+        end
+      end
+
+      # The layout's sidebar content.
+      class Sidebar < Primer::Component
+        TAG_DEFAULT = :div
+        TAG_OPTIONS = [TAG_DEFAULT, :aside, :nav, :section].freeze
+
+        def initialize(tag: TAG_DEFAULT, **system_arguments)
+          @system_arguments = system_arguments
+
+          @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, TAG_DEFAULT)
+          @system_arguments[:classes] = class_names(
+            "Layout-sidebar",
+            @system_arguments[:classes]
+          )
+        end
+
+        def call
+          render(Primer::BaseComponent.new(**@system_arguments)) { content }
+        end
+      end
+    end
+  end
+end

data/app/components/primer/base_button.rb

@@ -28,11 +28,7 @@ module Primer
       @system_arguments = system_arguments
       @system_arguments[:tag] = fetch_or_fallback(TAG_OPTIONS, tag, DEFAULT_TAG)
 
-      if @system_arguments[:tag] == :button
-        @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE)
-      else
-        @system_arguments[:role] = :button
-      end
+      @system_arguments[:type] = fetch_or_fallback(TYPE_OPTIONS, type, DEFAULT_TYPE) if @system_arguments[:tag] == :button
 
       @system_arguments[:classes] = class_names(
         system_arguments[:classes],

data/app/components/primer/base_component.rb

@@ -27,6 +27,7 @@ module Primer
   class BaseComponent < Primer::Component
     status :beta
 
+    SELF_CLOSING_TAGS = [:area, :base, :br, :col, :embed, :hr, :img, :input, :link, :meta, :param, :source, :track, :wbr].freeze
     # ## HTML attributes
     #
     # System arguments include most HTML attributes. For example:
@@ -155,7 +156,7 @@ module Primer
       raise ArgumentError, "`class` is an invalid argument. Use `classes` instead." if system_arguments.key?(:class) && !Rails.env.production?
 
       if (denylist = system_arguments[:system_arguments_denylist])
-        if force_system_arguments? && !ENV["PRIMER_WARNINGS_DISABLED"]
+        if raise_on_invalid_options? && !ENV["PRIMER_WARNINGS_DISABLED"]
           # Convert denylist from:
           # { [:p, :pt] => "message" } to:
           # { p: "message", pt: "message" }
@@ -189,7 +190,11 @@ module Primer
     end
 
     def call
-      content_tag(@tag, content, @content_tag_args.merge(@result))
+      if SELF_CLOSING_TAGS.include?(@tag)
+        tag(@tag, @content_tag_args.merge(@result))
+      else
+        content_tag(@tag, content, @content_tag_args.merge(@result))
+      end
     end
   end
 end

data/app/components/primer/beta/blankslate.html.erb

@@ -0,0 +1,15 @@
+<%= wrapper do %>
+  <%= render Primer::BaseComponent.new(**@system_arguments) do %>
+    <%= visual %>
+
+    <%= heading %>
+    <%= description %>
+
+    <%= primary_action %>
+    <% if secondary_action.present? %>
+      <p>
+        <%= secondary_action %>
+      </p>
+    <% end %>
+  <% end %>
+<% end %>

data/app/components/primer/beta/blankslate.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module Primer
+  module Beta
+    # Use `Blankslate` when there is a lack of content within a page or section. Use as placeholder to tell users why something isn't there.
+    #
+    # @accessibility
+    #   - Set the `heading` level based on what is appropriate for your page hierarchy. <%= link_to_heading_practices %>
+    #   - `secondary_action` can be set to provide more information that is relevant in the context of the `Blankslate`.
+    #   - `secondary_action` text should be meaningful out of context and clearly describe the destination. Avoid using vague text like, "Learn more" or "Click here".
+    class Blankslate < Primer::Component
+      include ViewComponent::PolymorphicSlots
+
+      status :beta
+
+      VISUAL_OPTIONS = %i[icon spinner image].freeze
+
+      # Optional visual.
+      #
+      # Use:
+      #
+      # - `visual_icon` for an <%= link_to_component(Primer::OcticonComponent) %>.
+      # - `visual_image` for an <%= link_to_component(Primer::Image) %>.
+      # - `visual_spinner` for a <%= link_to_component(Primer::SpinnerComponent) %>.
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :visual, types: {
+        icon: lambda { |**system_arguments|
+          system_arguments[:mb] = 3
+          system_arguments[:size] ||= :medium
+          system_arguments[:classes] = class_names("blankslate-icon", system_arguments[:classes])
+
+          Primer::OcticonComponent.new(**system_arguments)
+        },
+        spinner: lambda { |**system_arguments|
+          system_arguments[:mb] = 3
+
+          Primer::SpinnerComponent.new(**system_arguments)
+        },
+        image: lambda { |**system_arguments|
+          system_arguments[:mb] = 3
+          system_arguments[:size] = "56x56"
+
+          Primer::Image.new(**system_arguments)
+        }
+      }
+
+      # Required heading.
+      #
+      # @param tag [String]  <%= one_of(Primer::HeadingComponent::TAG_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :heading, lambda { |tag:, **system_arguments|
+        system_arguments[:tag] = tag
+        system_arguments[:mb] = 1
+        system_arguments[:classes] = class_names("h2", system_arguments[:classes])
+
+        Primer::HeadingComponent.new(**system_arguments)
+      }
+
+      # Optional description.
+      #
+      # - The description should always be informative and actionable.
+      # - Don't use phrases like "You can".
+      #
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :description, lambda { |**system_arguments|
+        system_arguments[:tag] = :p
+
+        Primer::BaseComponent.new(**system_arguments)
+      }
+
+      # Optional primary action
+      #
+      # The `primary_action` slot renders an anchor link which is visually styled as a button to provide more emphasis to the
+      # Blankslate's primary action.
+      #
+      # @param href [String] URL to be used for the primary action.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :primary_action, lambda { |href:, **system_arguments|
+        system_arguments[:tag] = :a
+        system_arguments[:href] = href
+        system_arguments[:my] = 3
+        system_arguments[:variant] = :medium
+        system_arguments[:scheme] ||= :primary
+
+        Primer::ButtonComponent.new(**system_arguments)
+      }
+
+      # Optional secondary action
+      #
+      # The `secondary_action` slot renders a normal anchor link, which can be used to redirect the user to additional information
+      # (e.g. Help documentation).
+      #
+      # @param href [String] URL to be used for the secondary action.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      renders_one :secondary_action, lambda { |href:, **system_arguments|
+        system_arguments[:href] = href
+        # Padding is needed to increase touch area.
+        system_arguments[:p] = 3
+
+        Primer::LinkComponent.new(**system_arguments)
+      }
+
+      # @example Basic
+      #   <%= render Primer::Beta::Blankslate.new do |c| %>
+      #     <% c.heading(tag: :h2).with_content("Title") %>
+      #     <% c.description { "Description"} %>
+      #   <% end %>
+      #
+      # @example Icon
+      #   @description
+      #     Add an `icon` to give additional context. Refer to the [Octicons](https://primer.style/octicons/) documentation to choose an icon.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_icon(icon: :globe) %>
+      #       <% c.heading(tag: :h2).with_content("Title") %>
+      #       <% c.description { "Description"} %>
+      #     <% end %>
+      #
+      # @example Loading
+      #   @description
+      #     Add a [SpinnerComponent](https://primer.style/view-components/components/spinner) to the blankslate in place of an icon.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_spinner(size: :large) %>
+      #       <% c.heading(tag: :h2).with_content("Title") %>
+      #       <% c.description { "Description"} %>
+      #     <% end %>
+      #
+      # @example Using an image
+      #   @description
+      #     Add an `image` to give context that an Octicon couldn't.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_image(src: "https://github.githubassets.com/images/modules/site/features/security-icon.svg", alt: "Security - secure vault") %>
+      #       <% c.heading(tag: :h2).with_content("Title") %>
+      #       <% c.description { "Description"} %>
+      #     <% end %>
+      #
+      # @example Custom content
+      #   @description
+      #     Pass custom content to `description`.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.heading(tag: :h2).with_content("Title") %>
+      #       <% c.description do %>
+      #         <em>Your custom content here</em>
+      #       <% end %>
+      #     <% end %>
+      #
+      # @example Primary action
+      #   @description
+      #     Provide a `primary_action` to guide users to take action from the blankslate. The `primary_action` appears below the description and custom content.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_icon(icon: :book) %>
+      #       <% c.heading(tag: :h2).with_content("Welcome to the mona wiki!") %>
+      #       <% c.description { "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together."} %>
+      #       <% c.primary_action(href: "https://github.com/monalisa/mona/wiki/_new").with_content("Create the first page") %>
+      #     <% end %>
+      #
+      # @example Secondary action
+      #   @description
+      #     Add an additional `secondary_action` to help users learn more about a feature. See <%= link_to_accessibility %>. `secondary_action` will be shown at the very bottom:
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_icon(icon: :book) %>
+      #       <% c.heading(tag: :h2).with_content("Welcome to the mona wiki!") %>
+      #       <% c.description { "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together."} %>
+      #       <% c.secondary_action(href: "https://docs.github.com/en/github/building-a-strong-community/about-wikis").with_content("Learn more about wikis") %>
+      #     <% end %>
+      #
+      # @example Primary and secondary actions
+      #   @description
+      #     `primary_action` and `secondary_action` can also be used together. The `primary_action` will always be rendered before the `secondary_action`:
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new do |c| %>
+      #       <% c.visual_icon(icon: :book) %>
+      #       <% c.heading(tag: :h2).with_content("Welcome to the mona wiki!") %>
+      #       <% c.description { "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together."} %>
+      #       <% c.primary_action(href: "https://github.com/monalisa/mona/wiki/_new").with_content("Create the first page") %>
+      #       <% c.secondary_action(href: "https://docs.github.com/en/github/building-a-strong-community/about-wikis").with_content("Learn more about wikis") %>
+      #     <% end %>
+      #
+      # @example Variations
+      #   @description
+      #     There are a few variations of how the Blankslate appears: `narrow` adds a maximum width of `485px`, and `spacious` increases the padding from `32px` to `80px 40px`.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new(
+      #       narrow: true,
+      #       spacious: true,
+      #     ) do |c| %>
+      #       <% c.visual_icon(icon: :book) %>
+      #       <% c.heading(tag: :h2).with_content("Welcome to the mona wiki!") %>
+      #       <% c.description { "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together."} %>
+      #     <% end %>
+      #
+      # @example With border
+      #   @description
+      #     It's possible to add a border around the Blankslate. This will wrap the Blankslate in a BorderBox.
+      #   @code
+      #     <%= render Primer::Beta::Blankslate.new(border: true) do |c| %>
+      #       <% c.visual_icon(icon: :book) %>
+      #       <% c.heading(tag: :h2).with_content("Welcome to the mona wiki!") %>
+      #       <% c.description { "Wikis provide a place in your repository to lay out the roadmap of your project, show the current status, and document software better, together."} %>
+      #     <% end %>
+      #
+      # @param narrow [Boolean] Adds a maximum width of `485px` to the Blankslate.
+      # @param spacious [Boolean] Increases the padding from `32px` to `80px 40px`.
+      # @param border [Boolean] Adds a border around the Blankslate.
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(narrow: false, spacious: false, border: false, **system_arguments)
+        @border = border
+        @system_arguments = system_arguments
+        @system_arguments[:tag] = :div
+        @system_arguments[:classes] = class_names(
+          @system_arguments[:classes],
+          "blankslate",
+          "blankslate-narrow": narrow,
+          "blankslate-spacious": spacious
+        )
+      end
+
+      def render?
+        heading.present?
+      end
+
+      def wrapper
+        unless @border
+          yield
+          return # returning `yield` caused a double render
+        end
+
+        content_tag(:div, class: "Box") do
+          yield if block_given?
+        end
+      end
+    end
+  end
+end