primer_view_components 0.0.35 → 0.0.40

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

@@ -0,0 +1 @@
+import '@github/image-crop-element';

data/app/components/primer/image_crop.html.erb

@@ -0,0 +1,12 @@
+<%= render Primer::BaseComponent.new(**@system_arguments) do %>
+  <% if loading.present? %>
+    <%= loading %>
+  <% else %>
+    <%= render(Primer::SpinnerComponent.new(size: :large, flex: 1, "data-loading-slot": true)) %>
+  <% end %>
+
+  <input type="hidden" data-image-crop-input="x" name="cropped_x">
+  <input type="hidden" data-image-crop-input="y" name="cropped_y">
+  <input type="hidden" data-image-crop-input="width" name="cropped_width">
+  <input type="hidden" data-image-crop-input="height" name="cropped_height">
+<% end %>

data/app/components/primer/image_crop.js

@@ -0,0 +1 @@
+import '@github/image-crop-element';

data/app/components/primer/image_crop.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Primer
+  # A client-side mechanism to crop images.
+  class ImageCrop < Primer::Component
+    # A loading indicator that is shown while the image is loading.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    renders_one :loading, lambda { |**system_arguments|
+      system_arguments[:tag] ||= :div
+      system_arguments[:"data-loading-slot"] = true
+
+      Primer::BaseComponent.new(**system_arguments)
+    }
+
+    # @example Simple cropper
+    #   <%= render(Primer::ImageCrop.new(src: "https://github.com/koddsson.png")) %>
+    #
+    # @example Square cropper
+    #   <%= render(Primer::ImageCrop.new(src: "https://github.com/koddsson.png", rounded: false)) %>
+    #
+    # @example Cropper with a custom loader
+    #   <%= render(Primer::ImageCrop.new(src: "https://github.com/koddsson.png", rounded: false)) do |cropper| %>
+    #     <% cropper.loading(style: "width: 120px", tag: :img, src: "spinner.gif") %>
+    #   <% end %>
+    #
+    # @param src [String] The path of the image to crop.
+    # @param rounded [Boolean] If the crop mask should be a circle. Defaults to true.
+    # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+    def initialize(src:, rounded: true, **system_arguments)
+      @system_arguments = system_arguments
+      @system_arguments[:tag] = "image-crop"
+      @system_arguments[:src] = src
+      @system_arguments[:rounded] = rounded
+    end
+  end
+end

data/app/components/primer/image_crop.ts

@@ -0,0 +1 @@
+import '@github/image-crop-element'

data/app/components/primer/label_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use labels to add contextual metadata to a design.
+  # Use `Label` to add contextual metadata to a design.
   class LabelComponent < Primer::Component
     status :beta
 

data/app/components/primer/layout_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Layout to build a main/sidebar layout.
+  # Use `Layout` to build a main/sidebar layout.
   class LayoutComponent < Primer::Component
     # The main content
     #

data/app/components/primer/link_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use links for moving from one page to another. The Link component styles anchor tags with default blue styling and hover text-decoration.
+  # Use `Link` for navigating from one page to another. `Link` styles anchor tags with default blue styling and hover text-decoration.
   class LinkComponent < Primer::Component
     status :beta
 

data/app/components/primer/{markdown_component.rb → markdown.rb}

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use MarkdownComponent to wrap markdown content
-  class MarkdownComponent < Primer::Component
+  # Use `Markdown` to wrap markdown content
+  class Markdown < Primer::Component
+    status :beta
     # @example Default
-    #   <%= render(Primer::MarkdownComponent.new) do %>
+    #   <%= render(Primer::Markdown.new) do %>
     #     <p>Text can be <b>bold</b>, <i>italic</i>, or <s>strikethrough</s>. <a href="https://github.com">Links </a> should be blue with no underlines (unless hovered over).</p>
     #
     #     <p>There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs. There should be whitespace between paragraphs.</p>
@@ -235,11 +236,11 @@ module Primer
     #
     #     <p>Code can also use syntax highlighting.</p>
     #
-    #     <pre><code class="prism-code language-javascript">var foo = "bar";</code></pre>
+    #     <pre><code>var foo = "bar";</code></pre>
     #
     #     <pre><code>Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.</code></pre>
     #
-    #     <pre><code class="prism-code language-javascript">var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";</code></pre>
+    #     <pre><code>var foo = "The same thing is true for code with syntax highlighting. A single line of code should horizontally scroll if it is really long.";</code></pre>
     #
     #     <p>Inline code inside table cells should still be distinguishable.</p>
     #

data/app/components/primer/menu_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use menus to create vertical lists of navigational links.
+  # Use `Menu` to create vertical lists of navigational links.
   class MenuComponent < Primer::Component
     # Optional menu heading
     #

data/app/components/primer/octicon_component.html.erb

@@ -0,0 +1,7 @@
+<%= render(Primer::BaseComponent.new(**@system_arguments)) do %>
+  <% if @use_symbol %>
+    <use href="#octicon_<%= [@icon.symbol, @icon.height].join("_") %>"></use>
+  <% else %>
+    <%= @icon.path.html_safe %>
+  <% end %>
+<% end %>

data/app/components/primer/octicon_component.rb

@@ -1,15 +1,21 @@
 # frozen_string_literal: true
 
+require "octicons"
+
 module Primer
-  # Renders an [Octicon](https://primer.style/octicons/) with <%= link_to_system_arguments_docs %>.
+  # `Octicon` renders an <%= link_to_octicons %> with <%= link_to_system_arguments_docs %>.
+  # `Octicon` can also be rendered with the `primer_octicon` helper, which accepts the same arguments.
   class OcticonComponent < Primer::Component
     status :beta
 
     SIZE_DEFAULT = :small
+    SIZE_MEDIUM = :medium
+    SIZE_LARGE = :large
+
     SIZE_MAPPINGS = {
       SIZE_DEFAULT => 16,
-      :medium => 32,
-      :large => 64
+      SIZE_MEDIUM => 32,
+      SIZE_LARGE => 64
     }.freeze
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
@@ -23,24 +29,50 @@ module Primer
     # @example Large
     #   <%= render(Primer::OcticonComponent.new("x", size: :large)) %>
     #
-    # @param icon [String] Name of [Octicon](https://primer.style/octicons/) to use.
+    # @example Helper
+    #   <%= primer_octicon("check") %>
+    #
+    # @param icon [String] Name of <%= link_to_octicons %> to use.
     # @param size [Symbol] <%= one_of(Primer::OcticonComponent::SIZE_MAPPINGS) %>
+    # @param use_symbol [Boolean] EXPERIMENTAL (May change or be removed) - Set to true when using with <%= link_to_component(Primer::OcticonSymbolsComponent) %>.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    def initialize(icon_name = nil, icon: nil, size: SIZE_DEFAULT, **system_arguments)
-      @icon = icon_name || icon
+    def initialize(icon_name = nil, icon: nil, size: SIZE_DEFAULT, use_symbol: false, **system_arguments)
+      icon_key = icon_name || icon
+      cache_key = Primer::Octicon::Cache.get_key(symbol: icon_key, size: size, **system_arguments.slice(:height, :width))
+
       @system_arguments = system_arguments
+      @system_arguments[:tag] = :svg
+      @system_arguments[:aria] ||= {}
+      @use_symbol = use_symbol
+
+      if @system_arguments[:aria][:label] || @system_arguments[:"aria-label"]
+        @system_arguments[:role] = "img"
+      else
+        @system_arguments[:aria][:hidden] = true
+      end
+
+      if (cache_icon = Primer::Octicon::Cache.read(cache_key))
+        @icon = cache_icon
+      else
+        # Filter out classify options to prevent them from becoming invalid html attributes.
+        # Note height and width are both classify options and valid html attributes.
+        octicon_options = {
+          height: SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)]
+        }.merge(@system_arguments.slice(:height, :width))
 
-      @system_arguments[:class] = Primer::Classify.call(**@system_arguments)[:class]
-      @system_arguments[:height] ||= SIZE_MAPPINGS[size]
+        @icon = Octicons::Octicon.new(icon_key, octicon_options)
+        Primer::Octicon::Cache.set(cache_key, @icon)
+      end
 
-      # Filter out classify options to prevent them from becoming invalid html attributes.
-      # Note height and width are both classify options and valid html attributes.
-      octicon_helper_options = @system_arguments.slice(:height, :width)
-      @system_arguments = add_test_selector(@system_arguments).except(*Primer::Classify::VALID_KEYS, :classes).merge(octicon_helper_options)
+      @system_arguments[:classes] = class_names(
+        @icon.options[:class],
+        @system_arguments[:classes]
+      )
+      @system_arguments.merge!(@icon.options.except(:class, :'aria-hidden'))
     end
 
-    def call
-      octicon(@icon, { **@system_arguments })
+    def self._after_compile
+      Primer::Octicon::Cache.preload!
     end
   end
 end

data/app/components/primer/octicon_symbols_component.html.erb

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" hidden>
+  <%= symbol_tags %>
+</svg>

data/app/components/primer/octicon_symbols_component.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "octicons"
+
+module Primer
+  # OcticonSymbols renders a symbol dictionary using a list of <%= link_to_octicons %>.
+  class OcticonSymbolsComponent < Primer::Component
+    # @example Symbol dictionary
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, color: :icon_success)) %>
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, color: :text_danger)) %>
+    #   <%= render(Primer::OcticonComponent.new(icon: :check, use_symbol: true, size: :medium)) %>
+    #   <%= render(Primer::OcticonSymbolsComponent.new(icons: [{ symbol: :check }, { symbol: :check, size: :medium }])) %>
+    #
+    # @param icons [Array<Hash>] List of icons to render, in the format { symbol: :icon_name, size: :small }
+    def initialize(icons: [])
+      @icons = {}
+      icons.each do |icon|
+        symbol = icon[:symbol]
+        size = Primer::OcticonComponent::SIZE_MAPPINGS[
+          fetch_or_fallback(Primer::OcticonComponent::SIZE_OPTIONS, icon[:size] || Primer::OcticonComponent::SIZE_DEFAULT, Primer::OcticonComponent::SIZE_DEFAULT)
+        ]
+
+        cache_key = Primer::Octicon::Cache.get_key(symbol: symbol, size: size)
+
+        if (cache_icon = Primer::Octicon::Cache.read(cache_key))
+          icon_instance = cache_icon
+        else
+          icon_instance = Octicons::Octicon.new(symbol, height: size)
+
+          Primer::Octicon::Cache.set(cache_key, icon_instance)
+        end
+
+        # Don't put the same icon twice
+        @icons[[symbol, icon_instance.height]] = icon_instance if @icons[[symbol, icon_instance.height]].nil?
+      end
+    end
+
+    def render?
+      @icons.any?
+    end
+
+    def self._after_compile
+      Primer::Octicon::Cache.preload!
+    end
+
+    def symbol_tags
+      safe_join(
+        @icons.values.map do |icon|
+          content_tag(
+            :symbol,
+            icon.path.html_safe, # rubocop:disable Rails/OutputSafety
+            id: "octicon_#{icon.symbol}_#{icon.height}",
+            viewBox: icon.options[:viewBox],
+            width: icon.width,
+            height: icon.height
+          )
+        end
+      )
+    end
+  end
+end

data/app/components/primer/popover_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use popovers to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
+  # Use `Popover` to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
   #
   # By default, the popover renders with absolute positioning, meaning it should usually be wrapped in an element with a relative position in order to be positioned properly. To render the popover with relative positioning, use the relative property.
   class PopoverComponent < Primer::Component

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

@@ -1,3 +1,5 @@
-import './auto_complete_component';
+import './auto_complete/auto_complete';
+import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './image_crop';

data/app/components/primer/primer.js

@@ -1,3 +1,5 @@
-import './auto_complete_component';
+import './auto_complete/auto_complete';
+import './clipboard_copy_component';
 import './tab_container_component';
 import './time_ago_component';
+import './image_crop';

data/app/components/primer/primer.ts

@@ -1,3 +1,5 @@
-import './auto_complete_component'
+import './auto_complete/auto_complete'
+import './clipboard_copy_component'
 import './tab_container_component'
 import './time_ago_component'
+import './image_crop'

data/app/components/primer/progress_bar_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use ProgressBar to visualize task completion.
+  # Use `ProgressBar` to visualize task completion.
   class ProgressBarComponent < Primer::Component
     status :beta
 

data/app/components/primer/spinner_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use Primer::SpinnerComponent to let users know that content is being loaded.
+  # Use `Spinner` to let users know that content is being loaded.
   class SpinnerComponent < Primer::Component
     status :beta
 
@@ -27,10 +27,10 @@ module Primer
     #   <%= render(Primer::SpinnerComponent.new(size: :large)) %>
     #
     # @param size [Symbol] <%= one_of(Primer::SpinnerComponent::SIZE_MAPPINGS) %>
-    def initialize(size: DEFAULT_SIZE, **system_arguments)
+    def initialize(size: DEFAULT_SIZE, style: DEFAULT_STYLE, **system_arguments)
       @system_arguments = system_arguments
       @system_arguments[:tag] = :svg
-      @system_arguments[:style] ||= DEFAULT_STYLE
+      @system_arguments[:style] ||= style
       @system_arguments[:animation] = :rotate
       @system_arguments[:width] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]
       @system_arguments[:height] = SIZE_MAPPINGS[fetch_or_fallback(SIZE_OPTIONS, size, DEFAULT_SIZE)]

data/app/components/primer/state_component.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
-  # Component for rendering the status of an item.
+  # Use `State` for rendering the status of an item.
   class StateComponent < Primer::Component
     status :beta
 
@@ -29,7 +29,7 @@ module Primer
     SIZE_OPTIONS = SIZE_MAPPINGS.keys
 
     TAG_DEFAULT = :span
-    TAG_OPTIONS = [TAG_DEFAULT, :div, :a].freeze
+    TAG_OPTIONS = [TAG_DEFAULT, :div].freeze
 
     # @example Default
     #   <%= render(Primer::StateComponent.new(title: "title")) { "State" } %>

data/app/components/primer/subhead_component.rb

@@ -1,16 +1,28 @@
 # frozen_string_literal: true
 
 module Primer
-  # Use the Subhead component for page headings.
+  # Use `Subhead` as the start of a section. The `:heading` slot will render an `<h2>` font-sized text.
+  #
+  # - Optionally set the `:description` slot to render a short description and the `:actions` slot for a related action.
+  # - Use a succint, one-line description for the `:description` slot. For longer descriptions, omit the description slot and render a paragraph below the `Subhead`.
+  # - Use the actions slot to render a related action to the right of the heading. Use <%= link_to_component(Primer::ButtonComponent) %> or <%= link_to_component(Primer::LinkComponent) %>.
+  #
+  # @accessibility
+  #   The `:heading` slot defaults to rendering a `<div>`. Update the tag to a heading element with the appropriate level to improve page navigation for assistive technologies.
+  #   <%= link_to_heading_practices %>
   class SubheadComponent < Primer::Component
     status :beta
 
+    DEFAULT_HEADING_TAG = :div
+    HEADING_TAG_OPTIONS = [DEFAULT_HEADING_TAG, :h1, :h2, :h3, :h4, :h5, :h6].freeze
+
     # The heading
     #
+    # @param tag [Symbol] <%= one_of(Primer::SubheadComponent::HEADING_TAG_OPTIONS)%>
     # @param danger [Boolean] Whether to style the heading as dangerous.
     # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
-    renders_one :heading, lambda { |danger: false, **system_arguments|
-      system_arguments[:tag] ||= :div
+    renders_one :heading, lambda { |tag: DEFAULT_HEADING_TAG, danger: false, **system_arguments|
+      system_arguments[:tag] = fetch_or_fallback(HEADING_TAG_OPTIONS, tag, DEFAULT_HEADING_TAG)
       system_arguments[:classes] = class_names(
         system_arguments[:classes],
         "Subhead-heading",
@@ -42,7 +54,7 @@ module Primer
 
     # @example Default
     #   <%= render(Primer::SubheadComponent.new) do |component| %>
-    #     <% component.heading do %>
+    #     <% component.heading(tag: :h3) do %>
     #       My Heading
     #     <% end %>
     #     <% component.description do %>
@@ -50,6 +62,24 @@ module Primer
     #     <% end %>
     #   <% end %>
     #
+    # @example With dangerous heading
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3, danger: true) do %>
+    #       My Heading
+    #     <% end %>
+    #     <% component.description do %>
+    #       My Description
+    #     <% end %>
+    #   <% end %>
+    #
+    # @example With long description
+    #   <%= render(Primer::SubheadComponent.new) do |component| %>
+    #     <% component.heading(tag: :h3) do %>
+    #       My Heading
+    #     <% end %>
+    #   <% end %>
+    #   <p> This is a longer description that is sitting below the Subhead. It's much longer than a description that could sit comfortably in the Subhead. </p>
+    #
     # @example Without border
     #   <%= render(Primer::SubheadComponent.new(hide_border: true)) do |component| %>
     #     <% component.heading do %>