primer_view_components 0.0.119 → 0.0.120

data/app/components/primer/alpha/modal_dialog.js

@@ -86,6 +86,7 @@ export class ModalDialogElement extends HTMLElement {
                 return;
             this.setAttribute('open', '');
             (_a = __classPrivateFieldGet(this, _ModalDialogElement_instances, "a", _ModalDialogElement_overlayBackdrop_get)) === null || _a === void 0 ? void 0 : _a.classList.remove('Overlay--hidden');
+            document.body.style.paddingRight = `${window.innerWidth - document.body.clientWidth}px`;
             document.body.style.overflow = 'hidden';
             if (__classPrivateFieldGet(this, _ModalDialogElement_focusAbortController, "f").signal.aborted) {
                 __classPrivateFieldSet(this, _ModalDialogElement_focusAbortController, new AbortController(), "f");
@@ -98,6 +99,7 @@ export class ModalDialogElement extends HTMLElement {
                 return;
             this.removeAttribute('open');
             (_b = __classPrivateFieldGet(this, _ModalDialogElement_instances, "a", _ModalDialogElement_overlayBackdrop_get)) === null || _b === void 0 ? void 0 : _b.classList.add('Overlay--hidden');
+            document.body.style.paddingRight = '0';
             document.body.style.overflow = 'initial';
             __classPrivateFieldGet(this, _ModalDialogElement_focusAbortController, "f").abort();
             // if #openButton is a child of a menu, we need to focus a suitable child of the menu

data/app/components/primer/alpha/modal_dialog.ts

@@ -81,6 +81,7 @@ export class ModalDialogElement extends HTMLElement {
       if (this.open) return
       this.setAttribute('open', '')
       this.#overlayBackdrop?.classList.remove('Overlay--hidden')
+      document.body.style.paddingRight = `${window.innerWidth - document.body.clientWidth}px`
       document.body.style.overflow = 'hidden'
       if (this.#focusAbortController.signal.aborted) {
         this.#focusAbortController = new AbortController()
@@ -91,6 +92,7 @@ export class ModalDialogElement extends HTMLElement {
       if (!this.open) return
       this.removeAttribute('open')
       this.#overlayBackdrop?.classList.add('Overlay--hidden')
+      document.body.style.paddingRight = '0'
       document.body.style.overflow = 'initial'
       this.#focusAbortController.abort()
       // if #openButton is a child of a menu, we need to focus a suitable child of the menu

data/lib/primer/deprecations.yml

@@ -17,24 +17,11 @@ deprecations:
     autocorrect: true
     replacement: "Primer::Beta::Blankslate"
 
-  - component: "Primer::BoxComponent"
-    autocorrect: true
-    replacement: "Primer::Box"
-
   - component: "Primer::ButtonComponent"
     autocorrect: false
     replacement: "Primer::Beta::Button"
     guide: "https://primer.style/view-components/guides/primer_button_component"
 
-  - component: "Primer::ClipboardCopy"
-    autocorrect: true
-    replacement: "Primer::Beta::ClipboardCopy"
-
-  - component: "Primer::DropdownMenuComponent"
-    autocorrect: false
-    replacement: "Primer::Beta::Dropdown"
-    guide: "https://primer.style/view-components/guides/primer_dropdown_menu_component"
-
   - component: "Primer::Dropdown"
     autocorrect: true
     replacement: "Primer::Alpha::Dropdown"

data/lib/primer/view_components/linters/button_component_migration_counter.rb

@@ -18,9 +18,9 @@ module ERBLint
       # CloseButton component has preference when this class is seen in conjunction with `btn`.
       DISALLOWED_CLASSES = %w[close-button].freeze
       CLASSES = %w[btn btn-link].freeze
-      MESSAGE = "We are migrating buttons to use [Primer::ButtonComponent](https://primer.style/view-components/components/button), please try to use that instead of raw HTML."
+      MESSAGE = "We are migrating buttons to use [Primer::Beta::Button](https://primer.style/view-components/components/beta/button), please try to use that instead of raw HTML."
       ARGUMENT_MAPPER = ArgumentMappers::Button
-      COMPONENT = "Primer::ButtonComponent"
+      COMPONENT = "Primer::Beta::Button"
     end
   end
 end

data/lib/primer/view_components/version.rb

@@ -6,7 +6,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 0
-      PATCH = 119
+      PATCH = 120
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/lib/primer/view_components.rb

@@ -54,5 +54,10 @@ module Primer
     def self.read(stats)
       File.read(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]))
     end
+
+    # primer/view_components root directory.
+    def self.root
+      Pathname(File.expand_path(File.join("..", ".."), __dir__))
+    end
   end
 end

data/lib/primer/yard/backend.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module YARD
+    # Shared functionality for generating documentation from YARD comments.
+    class Backend
+      include DocsHelper
+
+      private
+
+      def pretty_default_value(tag, component)
+        params = tag.object.parameters.find { |param| [tag.name.to_s, "#{tag.name}:"].include?(param[0]) }
+        default = tag.defaults&.first || params&.second
+
+        return "N/A" unless default
+
+        constant_name = "#{component.name}::#{default}"
+        constant_value = default.safe_constantize || constant_name.safe_constantize
+
+        return pretty_value(default) if constant_value.nil?
+
+        pretty_value(constant_value)
+      end
+
+      def view_context
+        @view_context ||= begin
+          # Rails controller for rendering arbitrary ERB
+          vc = ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context
+          vc.singleton_class.include(DocsHelper)
+          vc.singleton_class.include(Primer::ViewHelper)
+          vc
+        end
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/component_manifest.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Primer
+  module YARD
+    # The set of documented components (and associated metadata).
+    class ComponentManifest
+      COMPONENTS = {
+        Primer::Beta::RelativeTime => {},
+        Primer::Beta::IconButton => {},
+        Primer::Beta::Button => {},
+        Primer::Alpha::SegmentedControl => {},
+        Primer::Alpha::Layout => {},
+        Primer::Alpha::HellipButton => {},
+        Primer::Alpha::Image => {},
+        Primer::LocalTime => { js: true },
+        Primer::Alpha::OcticonSymbols => {},
+        Primer::Alpha::ImageCrop => { js: true },
+        Primer::IconButton => { js: true },
+        Primer::Beta::AutoComplete => { js: true },
+        Primer::Beta::AutoComplete::Item => {},
+        Primer::Beta::Avatar => {},
+        Primer::Beta::AvatarStack => {},
+        Primer::Beta::BaseButton => {},
+        Primer::Alpha::Banner => { js: true },
+        Primer::Beta::Blankslate => {},
+        Primer::Beta::BorderBox => {},
+        Primer::Beta::BorderBox::Header => {},
+        Primer::Box => {},
+        Primer::Beta::Breadcrumbs => {},
+        Primer::ButtonComponent => { js: true },
+        Primer::Beta::ButtonGroup => {},
+        Primer::Alpha::ButtonMarketing => {},
+        Primer::Beta::ClipboardCopy => { js: true },
+        Primer::Beta::CloseButton => {},
+        Primer::Beta::Counter => {},
+        Primer::Beta::Details => {},
+        Primer::Alpha::Dialog => {},
+        Primer::Alpha::Dropdown => { js: true },
+        Primer::Beta::Flash => {},
+        Primer::Beta::Heading => {},
+        Primer::Alpha::HiddenTextExpander => {},
+        Primer::Beta::Label => {},
+        Primer::LayoutComponent => {},
+        Primer::Beta::Link => { js: true },
+        Primer::Beta::Markdown => {},
+        Primer::Alpha::Menu => {},
+        Primer::Navigation::TabComponent => {},
+        Primer::Beta::Octicon => {},
+        Primer::Beta::Popover => {},
+        Primer::Beta::ProgressBar => {},
+        Primer::Beta::State => {},
+        Primer::Beta::Spinner => {},
+        Primer::Beta::Subhead => {},
+        Primer::Alpha::TabContainer => { js: true },
+        Primer::Beta::Text => {},
+        Primer::TimeAgoComponent => { js: true },
+        Primer::Beta::TimelineItem => {},
+        Primer::Tooltip => {},
+        Primer::Truncate => {},
+        Primer::Beta::Truncate => {},
+        Primer::Alpha::UnderlineNav => {},
+        Primer::Alpha::UnderlinePanels => { js: true },
+        Primer::Alpha::TabNav => {},
+        Primer::Alpha::TabPanels => { js: true },
+        Primer::Alpha::Tooltip => { js: true },
+        Primer::Alpha::ToggleSwitch => { js: true },
+
+        # Examples can be seen in the NavList docs
+        Primer::Alpha::NavList => { js: true },
+        Primer::Alpha::NavList::Item => { js: true, examples: false },
+        Primer::Alpha::NavList::Section => { js: true, examples: false },
+
+        # ActionList is a base component that should not be used by itself, and thus
+        # does not have examples of its own
+        Primer::Alpha::ActionList => { js: true, examples: false },
+        Primer::Alpha::ActionList::Divider => { examples: false },
+        Primer::Alpha::ActionList::Heading => { examples: false },
+        Primer::Alpha::ActionList::Item => { examples: false },
+
+        # Forms
+        Primer::Alpha::TextField => { form_component: true }
+      }.freeze
+
+      class << self
+        def each(&block)
+          COMPONENTS.keys.each(&block)
+        end
+
+        def components_with_docs
+          @components_with_docs ||= COMPONENTS.keys
+        end
+
+        def all_components
+          @all_components ||= Primer::Component.descendants - [Primer::BaseComponent]
+        end
+
+        def components_without_docs
+          @components_without_docs ||= all_components - components_with_docs
+        end
+
+        def components_with_examples
+          @components_with_examples ||= COMPONENTS.keys.select do |c|
+            COMPONENTS[c].fetch(:examples, true)
+          end
+        end
+
+        def components_requiring_js
+          @components_requiring_js ||= COMPONENTS.keys.select do |c|
+            COMPONENTS[c].fetch(:js, false)
+          end
+        end
+
+        def form_components
+          @form_components ||= COMPONENTS.keys.select do |c|
+            COMPONENTS[c].fetch(:form_component, false)
+          end
+        end
+      end
+    end
+  end
+end
+# :nocov:

data/lib/primer/yard/docs_helper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+module Primer
+  module YARD
+    # Helper methods to use for yard documentation
+    module DocsHelper
+      def one_of(enumerable, lower: false, sort: true)
+        # Sort the array if requested
+        if sort
+          enumerable = enumerable.sort do |a, b|
+            a.instance_of?(b.class) ? a <=> b : a.class.to_s <=> b.class.to_s
+          end
+        end
+
+        values =
+          case enumerable
+          when Hash
+            enumerable.map do |key, value|
+              "#{pretty_value(key)} (#{pretty_value(value)})"
+            end
+          else
+            enumerable.map do |key|
+              pretty_value(key)
+            end
+          end
+
+        prefix = "One of"
+        prefix = prefix.downcase if lower
+
+        "#{prefix} #{values.to_sentence(two_words_connector: ' or ', last_word_connector: ', or ')}."
+      end
+
+      def link_to_accessibility
+        "[Accessibility](#accessibility)"
+      end
+
+      def link_to_system_arguments_docs
+        "[System arguments](/system-arguments)"
+      end
+
+      def link_to_typography_docs
+        "[Typography](/system-arguments#typography)"
+      end
+
+      def link_to_component(component)
+        status_module, short_name, class_name = status_module_and_short_name(component)
+        status_path = status_module.nil? ? "" : "#{status_module}/"
+
+        "[#{class_name}](/components/#{status_path}#{short_name.downcase})"
+      end
+
+      def link_to_octicons
+        "[Octicon](https://primer.style/octicons/)"
+      end
+
+      def link_to_heading_practices
+        "[Learn more about best heading practices (WAI Headings)](https://www.w3.org/WAI/tutorials/page-structure/headings/)"
+      end
+
+      def status_module_and_short_name(component)
+        name_with_status = component.name.gsub(/Primer::|Component/, "")
+
+        m = name_with_status.match(/(?<status>Beta|Alpha|Deprecated)?(?<_colons>::)?(?<name>.*)/)
+        [m[:status]&.downcase, m[:name].gsub("::", ""), m[:name]]
+      end
+
+      def pretty_value(val)
+        case val
+        when nil
+          "`nil`"
+        when Symbol
+          "`:#{val}`"
+        else
+          "`#{val}`"
+        end
+      end
+    end
+  end
+end

data/lib/primer/yard/legacy_gatsby_backend.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+# rubocop:disable Naming/MethodParameterName
+
+# :nocov:
+
+require "primer/yard/component_manifest"
+require "primer/yard/backend"
+
+module Primer
+  module YARD
+    # Backend that generates documentation for the legacy, Gatsby-powered PVC docsite.
+    class LegacyGatsbyBackend < Backend
+      class << self
+        def parse_example_tag(tag)
+          name = tag.name
+          description = nil
+          code = nil
+
+          if tag.text.include?("@description")
+            splitted = tag.text.split(/@description|@code/)
+            description = splitted.second.gsub(/^[ \t]{2}/, "").strip
+            code = splitted.last.gsub(/^[ \t]{2}/, "").strip
+          else
+            code = tag.text
+          end
+
+          [name, description, code]
+        end
+      end
+
+      attr_reader :registry
+
+      def initialize(registry)
+        @registry = registry
+      end
+
+      def generate
+        args_for_components = []
+        errors = []
+
+        each_component do |component|
+          docs = registry.find(component)
+          status_path = docs.status_module.nil? ? "" : "#{docs.status_module}/"
+
+          metadata = docs.metadata.merge(
+            source: source_url(component),
+            lookbook: lookbook_url(component),
+            path: "docs/content/components/#{status_path}#{docs.short_name.downcase}.md",
+            example_path: example_path(component),
+            require_js_path: require_js_path(component)
+          )
+
+          path = Pathname.new(metadata[:path])
+          path.dirname.mkpath unless path.dirname.exist?
+
+          File.open(path, "w") do |f|
+            f.puts("---")
+            f.puts("title: #{metadata[:title]}")
+            f.puts("componentId: #{metadata[:component_id]}")
+            f.puts("status: #{metadata[:status]}")
+            f.puts("source: #{metadata[:source]}")
+            f.puts("a11yReviewed: #{metadata[:a11y_reviewed]}")
+            f.puts("lookbook: #{metadata[:lookbook]}") if preview_exists?(component)
+            f.puts("---")
+            f.puts
+            f.puts("import Example from '#{metadata[:example_path]}'")
+
+            if docs.requires_js?
+              f.puts("import RequiresJSFlash from '#{metadata[:require_js_path]}'")
+              f.puts
+              f.puts("<RequiresJSFlash />")
+            end
+
+            f.puts
+            f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
+            f.puts
+            f.puts(view_context.render(inline: docs.base_docstring))
+
+            if docs.tags(:deprecated).any?
+              f.puts
+              f.puts("## Deprecation")
+              docs.tags(:deprecated).each do |tag|
+                f.puts
+                f.puts view_context.render(inline: tag.text)
+              end
+            end
+
+            if docs.tags(:accessibility).any?
+              f.puts
+              f.puts("## Accessibility")
+              docs.tags(:accessibility).each do |tag|
+                f.puts
+                f.puts view_context.render(inline: tag.text)
+              end
+            end
+
+            errors << { component.name => { arguments: "No argument documentation found" } } unless docs.params.any?
+
+            f.puts
+            f.puts("## Arguments")
+            f.puts
+            f.puts("| Name | Type | Default | Description |")
+            f.puts("| :- | :- | :- | :- |")
+
+            documented_params = docs.params.map(&:name)
+            component_params = component.instance_method(:initialize).parameters.map { |p| p.last.to_s }
+
+            if (documented_params & component_params).size != component_params.size
+              err = { arguments: {} }
+              (component_params - documented_params).each do |arg|
+                err[:arguments][arg] = "Not documented"
+              end
+
+              errors << { component.name => err }
+            end
+
+            args = []
+            docs.params.each do |tag|
+              default_value = pretty_default_value(tag, component)
+
+              args << {
+                "name" => tag.name,
+                "type" => tag.types.join(", "),
+                "default" => default_value,
+                "description" => view_context.render(inline: tag.text.squish)
+              }
+
+              f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{default_value} | #{view_context.render(inline: tag.text.squish)} |")
+            end
+
+            component_args = {
+              "component" => metadata[:title],
+              "status" => component.status.to_s,
+              "source" => metadata[:source],
+              "lookbook" => metadata[:lookbook],
+              "parameters" => args
+            }
+
+            args_for_components << component_args
+
+            if docs.slot_methods.any?
+              f.puts
+              f.puts("## Slots")
+
+              docs.slot_methods.each do |slot_docs|
+                emit_method(slot_docs, component, f)
+              end
+            end
+
+            example_tags = docs.constructor.tags(:example)
+
+            if example_tags.any?
+              f.puts
+              f.puts("## Examples")
+
+              example_tags.each do |tag|
+                name, description, code = parse_example_tag(tag)
+                f.puts
+                f.puts("### #{name}")
+                if description
+                  f.puts
+                  f.puts(view_context.render(inline: description.squish))
+                end
+                f.puts
+                html = view_context.render(inline: code)
+                f.puts("<Example src=\"#{html.tr('"', "\'").delete("\n")}\" />")
+                f.puts
+                f.puts("```erb")
+                f.puts(code.to_s)
+                f.puts("```")
+              end
+            elsif manifest.components_with_examples.include?(component)
+              errors << { component.name => { example: "No examples found" } }
+            end
+          end
+        end
+
+        # Build system arguments docs from BaseComponent
+        system_args_docs = registry.find(Primer::BaseComponent)
+
+        File.open("docs/content/system-arguments.md", "w") do |f|
+          f.puts("---")
+          f.puts("title: System arguments")
+          f.puts("---")
+          f.puts
+          f.puts("<!-- Warning: AUTO-GENERATED file, do not edit. Add code comments to your Ruby instead <3 -->")
+          f.puts
+          f.puts(system_args_docs.base_docstring)
+          f.puts
+
+          f.puts(view_context.render(inline: system_args_docs.constructor.base_docstring))
+        end
+
+        [args_for_components, errors]
+      end
+
+      private
+
+      def emit_method(method_docs, component, f)
+        f.puts
+        f.puts("### `#{method_docs.name}`")
+
+        if method_docs.base_docstring.to_s.present?
+          f.puts
+          f.puts(view_context.render(inline: method_docs.base_docstring))
+        end
+
+        param_tags = method_docs.tags(:param)
+        if param_tags.any?
+          f.puts
+          f.puts("| Name | Type | Default | Description |")
+          f.puts("| :- | :- | :- | :- |")
+        end
+
+        param_tags.each do |tag|
+          f.puts("| `#{tag.name}` | `#{tag.types.join(', ')}` | #{pretty_default_value(tag, component)} | #{view_context.render(inline: tag.text)} |")
+        end
+      end
+
+      def each_component(&block)
+        manifest.components_with_docs.sort_by(&:name).each(&block)
+      end
+
+      def manifest
+        Primer::YARD::ComponentManifest
+      end
+
+      def source_url(component)
+        path = component.name.split("::").map(&:underscore).join("/")
+
+        "https://github.com/primer/view_components/tree/main/app/components/#{path}.rb"
+      end
+
+      def lookbook_url(component)
+        path = component.name.underscore.gsub("_component", "")
+
+        "https://primer.style/view-components/lookbook/inspect/#{path}/default/"
+      end
+
+      def example_path(component)
+        example_path = "../../src/@primer/gatsby-theme-doctocat/components/example"
+        example_path = "../#{example_path}" if status_module?(component)
+        example_path
+      end
+
+      def require_js_path(component)
+        require_js_path = "../../src/@primer/gatsby-theme-doctocat/components/requires-js-flash"
+        require_js_path = "../#{require_js_path}" if status_module?(component)
+        require_js_path
+      end
+
+      def preview_exists?(component)
+        path = component.name.underscore
+
+        File.exist?("previews/#{path}_preview.rb")
+      end
+
+      def status_module?(component)
+        (%w[Alpha Beta] & component.name.split("::")).any?
+      end
+
+      def parse_example_tag(tag)
+        self.class.parse_example_tag(tag)
+      end
+    end
+  end
+end
+# :nocov:
+
+# rubocop:enable Naming/MethodParameterName