ariadne_view_components 0.0.59 → 0.0.65

data/lib/ariadne/view_components/engine.rb

@@ -2,8 +2,6 @@
 
 require "rails/engine"
 
-require "view_component"
-
 require "tailwind_merge"
 
 module Ariadne
@@ -17,7 +15,7 @@ module Ariadne
       isolate_namespace Ariadne::ViewComponents
 
       config.autoload_paths = ["#{root}/lib"]
-      config.eager_load_paths = ["#{root}/app/components", "#{root}/app/helpers", "#{root}/app/lib"]
+      config.eager_load_paths = ["#{root}/app/components", "#{root}/app/forms", "#{root}/app/helpers", "#{root}/app/lib"]
 
       config.ariadne_view_components = ActiveSupport::OrderedOptions.new
 
@@ -31,9 +29,28 @@ module Ariadne
         app.config.assets.precompile += ["ariadne_view_components"] if app.config.respond_to?(:assets)
       end
 
-      initializer "ariadne_view_components.importmap", before: "importmap" do |app|
-        if Rails.application.respond_to?(:importmap)
-          app.config.importmap.paths << Engine.root.join("config/importmap.rb")
+      initializer "ariadne_view_components.eager_load_actions" do
+        ActiveSupport.on_load(:after_initialize) do
+          if Rails.application.config.eager_load
+            Ariadne::Forms::Base.compile!
+            Ariadne::Forms::Base.descendants.each(&:compile!)
+            Ariadne::Forms::BaseComponent.descendants.each(&:compile!)
+            Ariadne::Heroicon::Cache.preload!
+          end
+        end
+      end
+
+      initializer "ariadne.forms.helpers" do
+        ActiveSupport.on_load(:action_controller_base) do
+          begin
+            require "ariadne/form_helper"
+          rescue LoadError # rubocop:disable Lint/SuppressedException
+          end
+
+          helper Ariadne::FormHelper
+
+          # make ariadne_form_with available to view components also
+          ViewComponent::Base.prepend(Ariadne::FormHelper)
         end
       end
 
@@ -46,7 +63,7 @@ module Ariadne
       end
 
       config.after_initialize do |_app|
-        Ariadne::ViewComponents.tailwind_merger = TailwindMerge::Merger.new
+        Ariadne::ViewComponents.tailwind_merger = TailwindMerge::Merger.new(config: { prefix: "ariadne-" })
       end
     end
   end

data/lib/ariadne/view_components/version.rb

@@ -3,6 +3,6 @@
 # :nocov:
 module Ariadne
   module ViewComponents
-    VERSION = "0.0.59"
+    VERSION = "0.0.65"
   end
 end

data/lib/ariadne/view_components.rb

@@ -47,7 +47,7 @@ module Ariadne
         require "json"
 
         File.open(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]), "w") do |f|
-          f.write(JSON.pretty_generate(send("generate_#{stats}")))
+          f.write(JSON.pretty_generate(send(:"generate_#{stats}")))
           f.write($INPUT_RECORD_SEPARATOR)
         end
       end

data/lib/ariadne/yard/backend.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # Shared functionality for generating documentation from YARD comments.
+    class Backend
+      include DocsHelper
+
+      private
+
+      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(Ariadne::ViewHelper)
+          vc
+        end
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard/component_manifest.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # The set of documented components (and associated metadata).
+    class ComponentManifest
+      COMPONENTS = {
+        Ariadne::Heading::Component => {},
+        # Primer::Beta::IconButton => {},
+        # Primer::Beta::Button => {},
+        # Primer::Alpha::SegmentedControl => {},
+        # Primer::Alpha::Layout => {},
+        # Primer::Alpha::HellipButton => {},
+        # Primer::Alpha::Image => {},
+        # 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::BlankslateComponent => {},
+        # 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::Alpha::Navigation::Tab => {},
+        # 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::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 },
+        # Primer::Alpha::Overlay => { js: true },
+        # Primer::Alpha::ActionMenu => { 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::Group => { js: true, examples: false },
+
+        # Primer::Beta::NavList => { js: true },
+        # Primer::Beta::NavList::Item => { js: true, examples: false },
+        # Primer::Beta::NavList::Group => { 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 },
+        # Primer::Alpha::TextArea => { form_component: true, published: false },
+        # Primer::Alpha::Select => { form_component: true, published: false },
+        # Primer::Alpha::MultiInput => { form_component: true, js: true, published: false },
+        # Primer::Alpha::RadioButton => { form_component: true, published: false },
+        # Primer::Alpha::RadioButtonGroup => { form_component: true, published: false },
+        # Primer::Alpha::CheckBox => { form_component: true, published: false },
+        # Primer::Alpha::CheckBoxGroup => { form_component: true, published: false },
+        # Primer::Alpha::SubmitButton => { form_component: true, published: false },
+        # Primer::Alpha::FormButton => { form_component: true, published: false }
+      }.freeze
+
+      include Enumerable
+
+      def initialize(components)
+        @components = components
+      end
+
+      def each
+        return to_enum(__method__) unless block_given?
+
+        @components.each do |klass|
+          yield self.class.ref_for(klass)
+        end
+      end
+
+      def where(**attrs)
+        self.class.where(@components, **attrs)
+      end
+
+      class << self
+        def where(components = COMPONENTS, **desired_attrs)
+          new(
+            components.each_with_object([]) do |(klass, component_attrs), memo|
+              matches = desired_attrs.all? do |name, desired_value|
+                component_attrs.fetch(name, ComponentRef::ATTR_DEFAULTS[name]) == desired_value
+              end
+
+              memo << klass if matches
+            end,
+          )
+        end
+
+        def all
+          new(COMPONENTS.keys)
+        end
+
+        def ref_for(klass)
+          ref_cache[klass] ||= ComponentRef.new(klass, COMPONENTS.fetch(klass, {}))
+        end
+
+        private
+
+        def ref_cache
+          @ref_cache ||= {}
+        end
+      end
+    end
+  end
+end
+# :nocov:

data/lib/ariadne/yard/component_ref.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# :nocov:
+module Ariadne
+  module Yard
+    # :nodoc:
+    class ComponentRef
+      ATTR_DEFAULTS = {
+        js: false,
+        examples: true,
+        form_component: false,
+      }.freeze
+
+      attr_reader :klass, :attrs
+
+      def initialize(klass, attrs)
+        @klass = klass
+        @attrs = attrs
+      end
+
+      def requires_js?
+        @attrs.fetch(:js, ATTR_DEFAULTS[:js])
+      end
+
+      def should_have_examples?
+        @attrs.fetch(:examples, ATTR_DEFAULTS[:examples])
+      end
+
+      def form_component?
+        @attrs.fetch(:form_component, ATTR_DEFAULTS[:form_component])
+      end
+
+      def source_url
+        @source_url ||= begin
+          path = klass.name.split("::").map(&:underscore).join("/")
+          "https://github.com/primer/view_components/tree/main/app/components/#{path}.rb"
+        end
+      end
+
+      def lookbook_url
+        @lookbook_url ||= begin
+          path = klass.name.underscore.gsub("_component", "")
+          "https://ariadne.style/view-components/lookbook/inspect/#{path}/default/"
+        end
+      end
+    end
+  end
+end
+# :nocov:

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: