ariadne_view_components 0.0.58 → 0.0.64

data/lib/ariadne/yard/docs_helper.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  # :nodoc:
+  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.nil?
+          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(/Ariadne::|Component/, "")
+
+        m = name_with_status.match(/(?<status>Beta|Alpha|Deprecated)?(?<_colons>::)?(?<name>.*)/)
+        [m[:status]&.downcase, m[:name].gsub("::", ""), m[:name]]
+      end
+
+      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 pretty_value(val)
+        case val
+        when nil
+          "`nil`"
+        when Symbol
+          "`:#{val}`"
+        else
+          "`#{val}`"
+        end
+      end
+    end
+
+    DocsHelper.extend(DocsHelper)
+  end
+end
+# :nocov:

data/lib/ariadne/yard/info_arch_docs_helper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # Helper methods to use for info arch yard documentation
+    module InfoArchDocsHelper
+      include DocsHelper
+
+      def link_to_component(component)
+        "{{#link_to_component}}#{component}{{/link_to_component}}"
+      end
+
+      def link_to_system_arguments_docs
+        "{{link_to_system_arguments_docs}}"
+      end
+
+      def link_to_typography_docs
+        "{{link_to_typography_docs}}"
+      end
+
+      def link_to_accessibility
+        "{{link_to_accessibility}}"
+      end
+
+      def link_to_octicons
+        "{{link_to_octicons}}"
+      end
+    end
+  end
+end

data/lib/ariadne/yard/lookbook_docs_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # Helper methods for documentation generated in Lookbook pages.
+    module LookbookDocsHelper
+      # Adheres to the same signature as Ariadne::Yard::DocsHelper#link_to_component so link_to_component
+      # may be used in a Gatsby or Lookbook context and produce the correct link for each platform.
+      #
+      # @param component [Class] The component class to link to.
+      # @return [String] The link, either in HTML or markdown format.
+      def link_to_component(component)
+        backend = Ariadne::Yard::LookbookPagesBackend.new(Ariadne::Yard::Registry.make, nil)
+        component_ref = Ariadne::Yard::ComponentManifest.ref_for(component)
+        page = backend.page_for(component_ref)
+
+        # If the page_path method is available, we're being rendered into HTML by Lookbook
+        # and should emit an HTML <a> tag. No page_path means we're being rendered into
+        # markdown by LookbookPagesBackend and should emit a markdown + ERB link that
+        # Lookbook will eventually render on page load.
+        if respond_to?(:page_path)
+          link_to(page.docs.short_name, page_path(page.page_id.to_sym.inspect))
+        else
+          # rubocop:disable Rails/OutputSafety
+          "[#{page.docs.short_name}](<%= page_path(#{page.page_id.to_sym.inspect}) %>)".html_safe
+          # rubocop:enable Rails/OutputSafety
+        end
+      end
+    end
+  end
+end

data/lib/ariadne/yard/lookbook_pages_backend.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # A single Lookbook page.
+    class LookbookPage
+      include DocsHelper
+
+      PREVIEW_MAP = {
+        Ariadne::Alpha::TextField => [:single_text_field_form, :multi_text_field_form],
+        Ariadne::Alpha::TextArea => [],
+        Ariadne::Alpha::Select => [:select_form],
+        Ariadne::Alpha::MultiInput => [:multi_input_form],
+        Ariadne::Alpha::RadioButton => [:radio_button_with_nested_form],
+        Ariadne::Alpha::RadioButtonGroup => [:radio_button_group_form],
+        Ariadne::Alpha::CheckBox => [:check_box_with_nested_form],
+        Ariadne::Alpha::CheckBoxGroup => [:check_box_group_form],
+        Ariadne::Alpha::SubmitButton => [:submit_button_form],
+        Ariadne::Alpha::FormButton => [:submit_button_form],
+      }.freeze
+
+      attr_reader :component_ref, :backend, :docs
+
+      def initialize(component_ref, backend, docs)
+        @component_ref = component_ref
+        @backend = backend
+        @docs = docs
+      end
+
+      def page_id
+        @page_id ||= docs.short_name.dasherize.underscore.tap do |page_id|
+          page_id << "_input" unless page_id.end_with?("_input")
+        end
+      end
+
+      def generate
+        path = File.expand_path(
+          File.join(
+            "..",
+            "..",
+            "..",
+            "previews",
+            "pages",
+            "forms",
+            "inputs",
+            "#{docs.short_name.dasherize.underscore}.md.erb",
+          ),
+          __dir__,
+        )
+
+        docs.non_slot_methods.select do |mtd|
+          [component.name, "Ariadne::Forms::Dsl::InputMethods"].include?(mtd.parent.title)
+        end
+
+        preview_methods = PREVIEW_MAP[component]
+        preview_methods.map do |preview_method|
+          if Ariadne::FormsPreview.instance_methods.exclude?(preview_method)
+            raise "Preview '#{preview_method}' does not exist in Ariadne::FormsPreview"
+          end
+          # rubocop:enable Style/IfUnlessModifier
+
+          "<%= embed Ariadne::FormsPreview, #{preview_method.inspect} %>"
+        end
+        # rubocop:disable Security/Eval
+        File.open(path, "w") do |f|
+          f.write(eval(Erubi::Engine.new(<<~ERB, trim: true).src))
+            ---
+            title: <%= docs.title.underscore.titleize %>
+            id: <%= page_id %>
+            ---
+
+            <%= docs.base_docstring %>
+
+            ## Usage
+
+            ```ruby
+            <%= docs.tags(:form_usage).first.text %>
+            ```
+
+            <% specific_args = specific_args_from(docs.params) %>
+            <% unless specific_args.empty? %>
+            ## Arguments
+
+            <%= generate_args_table(specific_args) %>
+            <% end %>
+
+            ## Common arguments
+
+            <%= generate_args_table(common_args_from(docs.params)) %>
+
+            <% unless documented_methods.empty? %>
+            ## Methods
+
+              <% documented_methods.each do |method_docs| %>
+            ### `#<%= method_docs.signature.sub(/def /, "") %>`
+
+            <%= method_docs.base_docstring %>
+
+                <% param_tags = method_docs.tags(:param) %>
+
+                <% if param_tags.any? %>
+
+            <%= generate_args_table(param_tags) %>
+                <% end %>
+              <% end %>
+            <% end %>
+
+            <% unless preview_methods.empty? %>
+            ## Examples
+
+            <%= preview_erbs.join("\n") %>
+            <% end %>
+          ERB
+        end
+        # rubocop:enable Security/Eval
+      end
+
+      private
+
+      def registry
+        backend.registry
+      end
+
+      def generate_args_table(params)
+        rows = params.map do |tag|
+          description = backend.view_context.render(inline: tag.text.squish)
+          parts = [
+            "`#{tag.name}`",
+            tag.types.join(", "),
+            description,
+          ]
+
+          "| #{parts.join(" | ")} |"
+        end
+
+        <<~MARKDOWN
+          | Name | Type | Description |
+          | :- | :- | :- |
+          #{rows.join("\n")}
+        MARKDOWN
+      end
+
+      def common_args_from(params)
+        params.select { |param| common_form_input_argument_names.include?(param.name) }
+      end
+
+      def specific_args_from(params)
+        params.reject { |param| common_form_input_argument_names.include?(param.name) }
+      end
+
+      def common_form_input_argument_names
+        @common_form_input_argument_names ||= begin
+          macro = registry.yard_registry[".macro.form_input_arguments"]
+          parser = ::YARD::Docstring.parser
+          parser.parse(macro.macro_data)
+          parser
+            .tags
+            .select { |tag| tag.tag_name == "param" }
+            .map(&:name)
+        end
+      end
+
+      def component
+        component_ref.klass
+      end
+    end
+
+    # Backend that generates Lookbook pages.
+    class LookbookPagesBackend < Backend
+      attr_reader :registry, :manifest
+
+      def initialize(registry, manifest)
+        @registry = registry
+        @manifest = manifest
+      end
+
+      def generate
+        each_component do |component_ref|
+          page_for(component_ref).generate
+        end
+        generate_system_args_docs
+      end
+
+      def page_for(component_ref)
+        docs = registry.find(component_ref.klass)
+        LookbookPage.new(component_ref, self, docs)
+      end
+
+      def view_context
+        @view_context ||= super.tap do |vc|
+          vc.singleton_class.include(LookbookDocsHelper)
+        end
+      end
+
+      private
+
+      def each_component(&block)
+        manifest.each(&block)
+      end
+
+      def generate_system_args_docs
+        docs = registry.find(Ariadne::BaseComponent)
+
+        path = File.expand_path(
+          File.join(
+            "..", "..", "..", "previews", "pages", "system-arguments.md.erb"
+          ),
+          __dir__,
+        )
+
+        data = {
+          "description_md" => docs.base_docstring.to_s,
+          "args_md" => view_context.render(inline: docs.constructor.base_docstring),
+        }
+
+        frontmatter = {
+          "title" => "System arguments",
+          "id" => "system_arguments",
+          "data" => data,
+        }
+
+        File.write(
+          path, <<~ERB
+            #{YAML.dump(frontmatter)}
+            ---
+            <%= @page.data[:description_md].html_safe %>
+            <%= @page.data[:args_md].html_safe %>
+          ERB
+        )
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard/registry.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "view_component/test_helpers"
+
+module Ariadne
+  module Yard
+    # A wrapper around a YARD class reference that provides convenience methods
+    # for extracting component parameters, accessibility status, etc.
+    class RegistryEntry
+      include DocsHelper
+
+      attr_reader :component, :docs
+
+      delegate_missing_to :docs
+
+      def initialize(component, docs)
+        @component = component
+        @docs = docs
+      end
+
+      def metadata
+        @metadata ||= begin
+          status_module, short_name, class_name = status_module_and_short_name(component)
+          status = component.status.to_s
+          a11y_reviewed = component.audited_at.nil? ? "false" : "true"
+
+          {
+            title: class_name,
+            class_name: class_name,
+            component_id: short_name.underscore,
+            status: status.capitalize,
+            status_module: status_module,
+            short_name: short_name,
+            a11y_reviewed: a11y_reviewed,
+          }
+        end
+      end
+
+      def constructor
+        docs.meths.find(&:constructor?)
+      end
+
+      def params
+        constructor&.tags(:param) || []
+      end
+
+      def slot_methods
+        public_methods.select { |mtd| slot_method?(mtd) }
+      end
+
+      def non_slot_methods
+        public_methods.reject { |mtd| slot_method?(mtd) }
+      end
+
+      def slot_method?(mtd)
+        mtd[:renders_one] || mtd[:renders_many]
+      end
+
+      def public_methods
+        # Returns: only public methods that belong to this class (i.e. no inherited methods)
+        # excluding the constructor
+        @public_methods ||= docs.meths.reject do |mtd|
+          mtd.tag(:private) || mtd.name == :initialize
+        end
+      end
+
+      def title
+        metadata[:title]
+      end
+
+      def component_id
+        metadata[:component_id]
+      end
+
+      def status
+        metadata[:status]
+      end
+
+      def status_module
+        metadata[:status_module]
+      end
+
+      def short_name
+        metadata[:short_name]
+      end
+
+      def a11y_reviewed?
+        metadata[:a11y_reviewed]
+      end
+
+      def manifest_entry
+        @manifest_entry ||= ComponentManifest.ref_for(component)
+      end
+    end
+
+    # Wrapper around an instance of YARD::Registry that provides easy access to component
+    # documentation.
+    class Registry
+      class << self
+        include ViewComponent::TestHelpers
+        include Ariadne::ViewHelper
+        include Ariadne::Yard::DocsHelper
+
+        def make
+          registry = ::YARD::RegistryStore.new
+          registry.load!(File.expand_path(File.join("..", "..", "..", ".yardoc"), __dir__))
+
+          new(registry)
+        end
+      end
+
+      attr_reader :yard_registry
+
+      def initialize(yard_registry)
+        @yard_registry = yard_registry
+      end
+
+      def find(component)
+        return entries[component] if entries.include?(component)
+
+        return unless (docs = yard_registry.get(component.name))
+
+        entries[component] = RegistryEntry.new(component, docs)
+      end
+
+      private
+
+      def entries
+        @entries ||= {}
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard/renders_many_handler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # YARD Handler to parse `renders_many` calls.
+    class RendersManyHandler < ::YARD::Handlers::Ruby::Base
+      handles method_call(:renders_many)
+      namespace_only
+
+      process do
+        name = statement.parameters.first.jump(:tstring_content, :ident).source
+        object = ::YARD::CodeObjects::MethodObject.new(namespace, name)
+        register(object)
+        parse_block(statement.last, owner: object)
+
+        object.dynamic = true
+        object[:renders_many] = true
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard/renders_one_handler.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # YARD Handler to parse `renders_one` calls.
+    class RendersOneHandler < ::YARD::Handlers::Ruby::Base
+      handles method_call(:renders_one)
+      namespace_only
+
+      process do
+        name = statement.parameters.first.jump(:tstring_content, :ident).source
+        object = ::YARD::CodeObjects::MethodObject.new(namespace, name)
+        register(object)
+        parse_block(statement.last, owner: object)
+
+        object.dynamic = true
+        object[:renders_one] = true
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "yard"
+
+module Ariadne
+  # :nodoc:
+  module Yard
+    autoload :Backend,            "primer/yard/backend"
+    autoload :ComponentManifest,  "primer/yard/component_manifest"
+    autoload :ComponentRef,       "primer/yard/component_ref"
+    autoload :DocsHelper,         "primer/yard/docs_helper"
+    autoload :InfoArchDocsHelper, "primer/yard/info_arch_docs_helper"
+    autoload :Registry,           "primer/yard/registry"
+    autoload :RendersManyHandler, "primer/yard/renders_many_handler"
+    autoload :RendersOneHandler,  "primer/yard/renders_one_handler"
+
+    ::YARD::Tags::Library.define_tag("Snapshot preview", :snapshot)
+  end
+end