ariadne_view_components 0.0.93.1 → 0.0.94

data/lib/ariadne/static/generate_structure.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Ariadne
+  module Static
+    # :nodoc:
+    module GenerateStructure
+      SKIP_METHODS = [:call, :before_render].freeze
+
+      # This class generates the JSON structure for the Ariadne documentation.
+      class << self
+        def call
+          components = Ariadne::BaseComponent.descendants.sort_by(&:name) - [Ariadne::BaseComponent]
+
+          component_docs = components.each_with_object({}) do |component, memo|
+            docs = registry.find(component)
+
+            preview_data = previews.find do |preview|
+              preview["component"] == docs.metadata[:title]
+            end
+
+            arg_data = args.find do |component_args|
+              component_args["component"] == docs.metadata[:title]
+            end
+
+            slot_docs = docs.slot_methods.map do |slot_method|
+              param_tags = slot_method.tags(:param)
+
+              description = if slot_method.base_docstring.to_s.present?
+                render_erb_ignoring_markdown_code_fences(slot_method.base_docstring).force_encoding("UTF-8")
+              else
+                ""
+              end
+
+              {
+                "name" => slot_method.name,
+                "description" => description,
+                "parameters" => serialize_params(param_tags, component),
+              }
+            end
+
+            mtds = docs.non_slot_methods.select do |mtd|
+              next false if mtd.base_docstring.to_s.blank?
+              next false if SKIP_METHODS.include?(mtd.name)
+
+              method_location, = mtd.files.first
+              class_location, = docs.docs.files.first
+
+              method_location == class_location
+            end
+
+            method_docs = mtds.map do |mtd|
+              param_tags = mtd.tags(:param)
+
+              {
+                "name" => mtd.name,
+                "description" => render_erb_ignoring_markdown_code_fences(mtd.base_docstring),
+                "parameters" => serialize_params(param_tags, component),
+              }
+            end
+
+            description =
+              if component == Ariadne::BaseComponent
+                docs.base_docstring
+              else
+                render_erb_ignoring_markdown_code_fences(docs.base_docstring)
+              end
+
+            accessibility_docs =
+              if (accessibility_tag_text = docs.tags(:accessibility)&.first&.text)
+                render_erb_ignoring_markdown_code_fences(accessibility_tag_text)
+              end
+
+            behavior_docs =
+              if (behavior_tag_text = docs.tags(:behaviors)&.first&.text)
+                render_erb_ignoring_markdown_code_fences(behavior_tag_text)
+              end
+
+            memo[component.name] = {
+              "fully_qualified_name" => component.name,
+              "description" => description,
+              "accessibility_docs" => accessibility_docs,
+              "behavior_docs" => behavior_docs,
+              "is_form_component" => docs.manifest_entry.form_component?,
+              "requires_js" => docs.manifest_entry.requires_js?,
+              **arg_data,
+              "slots" => slot_docs,
+              "methods" => method_docs,
+              "previews" => (preview_data || {}).fetch("examples", []),
+              "subcomponents" => [],
+            }
+          end
+
+          Ariadne::BaseComponent.descendants.sort_by(&:name).each do |component|
+            fq_class = component.name.to_s.split("::")
+            fq_class.shift # remove Ariadne::
+            type = fq_class.shift # remove {UI,Form,*}::
+
+            parent, *child = *fq_class
+
+            next if child.empty? || child.length < 2
+
+            parent_class = "Ariadne::#{type}".constantize
+            parent_class = parent_class.const_get(parent)
+
+            parent_docs = component_docs["#{parent_class}::Component"]
+            next unless parent_docs
+
+            if (child_docs = component_docs.delete(component.name))
+              parent_docs["subcomponents"] << child_docs
+            end
+          end
+
+          toc_categories = {
+            "UI" => [],
+            "Form" => [],
+            "Layout" => [],
+            "Behaviors" => [],
+          }
+
+          component_docs.values.each do |component|
+            type, name = component["short_name"].split("::", 2)
+            next unless toc_categories[type] # not a required category
+
+            # removes children from toc, like `Ariadne::UI::Accordion::Item`,
+            # by not adding the component to the TOC if it has more than one level of nesting
+            next if name.include?("::")
+
+            slug = component["short_name"].gsub("::", "/").downcase
+
+            toc_categories[type] << {
+              "name" => name,
+              "slug" => slug,
+            }
+
+            File.open(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[:toc]), "w") do |f|
+              f.write(JSON.pretty_generate(toc_categories))
+              f.write($INPUT_RECORD_SEPARATOR)
+            end
+          end
+          component_docs.values
+        end
+
+        def serialize_params(param_tags, component)
+          param_tags.map do |tag|
+            default_value = Ariadne::Yard::DocsHelper.pretty_default_value(tag, component)
+
+            {
+              "name" => tag.name,
+              "type" => tag.types&.join(", ") || "",
+              "default" => default_value,
+              "description" => render_erb_ignoring_markdown_code_fences(tag.text.squish),
+            }
+          end
+        end
+
+        def previews
+          @previews ||= JSON.parse(Static.read(:previews))
+        end
+
+        def args
+          @args ||= Ariadne::Static::GenerateArguments.call(view_context: view_context)
+        end
+
+        def view_context
+          @view_context ||= ApplicationController.new.tap { |c| c.request = ActionDispatch::TestRequest.create }.view_context.tap do |vc|
+            vc.singleton_class.include(Ariadne::Yard::StructureDocsHelper)
+            vc.singleton_class.include(Ariadne::ViewHelper)
+          end
+        end
+
+        def generate_args_table(args)
+          rows = args.map do |arg|
+            parts = [
+              "`#{arg.name}`",
+              arg.type,
+              arg.description.squish,
+            ]
+
+            "| #{parts.join(" | ")} |"
+          end
+
+          <<~MARKDOWN
+            | Name | Type | Description |
+            | :- | :- | :- |
+            #{rows.join("\n")}
+          MARKDOWN
+        end
+
+        # Renders ERB code to a string, ignoring markdown code fences. For example, consider the
+        # following ERB code inside a markdown document:
+        #
+        # ### Heading
+        # ```erb
+        # <%= render(SomeComponent.new) %>
+        # ```
+        #
+        # <%= some_func(a, b) %>
+        #
+        # The ERB renderer does not understand that the fenced code, i.e. the part inside the triple
+        # backticks, should not be rendered. It sees the ERB tags both inside and outside the fence
+        # and renders them both.
+        #
+        # This method renders ERB tags in a markdown string, ignoring any fenced code blocks, so as
+        # to prevent rendering fenced ERB code.
+        #
+        def render_erb_ignoring_markdown_code_fences(markdown_str)
+          return view_context.render(inline: markdown_str) if markdown_str.exclude?("```")
+
+          # identify all fenced code blocks in markdown string
+          code_ranges = find_fenced_code_ranges_in(markdown_str)
+
+          # replace code fences with placeholders
+          de_fenced_markdown_str = markdown_str.dup.tap do |memo|
+            code_ranges.reverse_each.with_index do |code_range, idx|
+              memo[code_range] = "<!--codefence#{idx}-->"
+            end
+          end
+
+          # Render ERB tags. The only ones left will explicitly exist _outside_ markdown code fences.
+          rendered_str = view_context.render(inline: de_fenced_markdown_str)
+
+          # replace placeholders with original code fences
+          code_ranges.reverse_each.with_index do |code_range, idx|
+            rendered_str.sub!("<!--codefence#{idx}-->", markdown_str[code_range])
+          end
+
+          rendered_str
+        end
+
+        def find_fenced_code_ranges_in(str)
+          doc = Kramdown::Document.new(str)
+          line_starts = find_line_starts_in(str)
+
+          [].tap do |code_ranges|
+            each_codespan_in(doc.root) do |node|
+              options = node.options
+              delimiter = options[:codespan_delimiter]
+              next unless delimiter.start_with?("```")
+
+              start_pos = line_starts[options[:location]]
+              end_pos = start_pos + node.value.size + delimiter.size
+              end_pos = str.index("```", end_pos) + 3
+
+              code_ranges << (start_pos...end_pos)
+            end
+          end
+        end
+
+        def find_line_starts_in(str)
+          line_counter = 2
+
+          { 1 => 0 }.tap do |memo|
+            str.scan(/\r?\n/) do
+              memo[line_counter] = Regexp.last_match.end(0)
+              line_counter += 1
+            end
+          end
+        end
+
+        def each_codespan_in(node, &block)
+          return unless node.respond_to?(:children)
+
+          node.children.each do |child|
+            yield child if child.type == :codespan
+            each_codespan_in(child, &block)
+          end
+        end
+
+        def registry
+          @registry ||= Ariadne::Yard::Registry.make
+        end
+      end
+    end
+  end
+end

data/lib/ariadne/static.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# :nocov:
+
+require "json"
+
+module Ariadne
+  # :nodoc:
+  module Static
+    DEFAULT_STATIC_PATH = File.join("docs", "src", "_data", "ariadne_view_components").freeze
+
+    FILE_NAMES = {
+      constants: "constants.json",
+      audited_at: "audited_at.json",
+      arguments: "arguments.json",
+      previews: "previews.json",
+      structure: "structure.json",
+      toc: "toc.json",
+    }.freeze
+
+    class << self
+      # Returns a hash mapping component names to an array of the constants defined inside
+      # the component's class.
+      def generate_constants
+        Static::GenerateConstants.call
+      end
+
+      # Returns a hash mapping component names to the date on which the component passed
+      # an accessibility audit.
+      def generate_audited_at
+        Static::GenerateAuditedAt.call
+      end
+
+      # Returns an array of hashes, one per Ariadne component, that contains some metadata and
+      # a list of the arguments accepted by the component's constructor. Arguments are enumerated
+      # with their value, data type, and docstring.
+      def generate_arguments
+        Static::GenerateArguments.call
+      end
+
+      # Returns an array of hashes, one per Ariadne component, that contains some metadata and
+      # an array of all the component's previews. The preview data contains the Lookbook URL
+      # to each preview and its name.
+      def generate_previews
+        Static::GeneratePreviews.call
+      end
+
+      # Returns an array of hashes, one per Ariadne component, that contains all the data needed
+      # for the new primer.style docsite.
+      def generate_structure
+        Static::GenerateStructure.call
+      end
+
+      # Generates the requested stat hash and outputs it to a file.
+      def dump(stats)
+        File.open(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]), "w") do |f|
+          f.write(JSON.pretty_generate(send(:"generate_#{stats}")))
+          f.write($INPUT_RECORD_SEPARATOR)
+        end
+      end
+
+      # Returns the contents of the stat file.
+      def read(stats)
+        File.read(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]))
+      end
+    end
+  end
+end

data/lib/ariadne/view_components/constants.rb

@@ -8,7 +8,7 @@ module Ariadne
     class Constants
       CONSTANTS = JSON.parse(
         File.read(
-          File.join(File.dirname(__FILE__), "../../../static/constants.json"),
+          File.join(File.dirname(__FILE__), "../../../docs/src/_data/ariadne_view_components/constants.json"),
         ),
       ).freeze
 
@@ -37,7 +37,7 @@ module Ariadne
         end
 
         private def format_array(values, symbolize)
-          val = values.select(&:present?)
+          val = values.compact_blank
 
           return val.map { |v| symbolize_value(v) } if symbolize
 

data/lib/ariadne/view_components/version.rb

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

data/lib/ariadne/view_components.rb

@@ -2,60 +2,9 @@
 
 require "ariadne/view_components/version"
 require "ariadne/view_components/engine"
-require "ariadne/view_components/constants"
-require "ariadne/view_components/commands"
 
 module Ariadne
   # :nodoc:
   module ViewComponents
-    DEFAULT_STATIC_PATH = File.expand_path("static")
-    FILE_NAMES = {
-      statuses: "statuses.json",
-      constants: "constants.json",
-      audited_at: "audited_at.json",
-    }.freeze
-
-    class << self
-      # generate_statuses returns a hash mapping component name to
-      # the component's status sorted alphabetically by the component name.
-      def generate_statuses
-        Ariadne::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-          mem[component.to_s] = component.status.to_s
-        end
-      end
-
-      # generate_audited_at returns a hash mapping component name to
-      # the day the component has passed an accessibility audit.
-      def generate_audited_at
-        Ariadne::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-          mem[component.to_s] = component.audited_at.to_s
-        end
-      end
-
-      # generate_constants returns a hash mapping component name to
-      # all of its constants.
-      def generate_constants
-        Ariadne::Component.descendants.sort_by(&:name).each_with_object({}) do |component, mem|
-          mem[component.to_s] = component.constants(false).sort.index_with do |constant|
-            component.const_get(constant)
-          end
-        end
-      end
-
-      # dump generates the requested stat hash and outputs it to a file.
-      def dump(stats)
-        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($INPUT_RECORD_SEPARATOR)
-        end
-      end
-
-      # read returns a JSON string matching the output of the corresponding stat.
-      def read(stats)
-        File.read(File.join(DEFAULT_STATIC_PATH, FILE_NAMES[stats]))
-      end
-    end
   end
 end

data/lib/ariadne/yard/component_manifest.rb

@@ -6,95 +6,95 @@ module Ariadne
     # 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 },
+        Ariadne::UI::Typography::Component => {},
+        # Ariadne::Beta::IconButton => {},
+        # Ariadne::Beta::Button => {},
+        # Ariadne::Alpha::SegmentedControl => {},
+        # Ariadne::Alpha::Layout => {},
+        # Ariadne::Alpha::HellipButton => {},
+        # Ariadne::Alpha::Image => {},
+        # Ariadne::Alpha::OcticonSymbols => {},
+        # Ariadne::Alpha::ImageCrop => { js: true },
+        # Ariadne::IconButton => { js: true },
+        # Ariadne::Beta::AutoComplete => { js: true },
+        # Ariadne::Beta::AutoComplete::Item => {},
+        # Ariadne::Beta::Avatar => {},
+        # Ariadne::Beta::AvatarStack => {},
+        # Ariadne::Beta::BaseButton => {},
+        # Ariadne::Alpha::Banner => { js: true },
+        # Ariadne::Beta::Blankslate => {},
+        # Ariadne::BlankslateComponent => {},
+        # Ariadne::Beta::BorderBox => {},
+        # Ariadne::Beta::BorderBox::Header => {},
+        # Ariadne::Box => {},
+        # Ariadne::Beta::Breadcrumbs => {},
+        # Ariadne::ButtonComponent => { js: true },
+        # Ariadne::Beta::ButtonGroup => {},
+        # Ariadne::Alpha::ButtonMarketing => {},
+        Ariadne::UI::ClipboardCopy::Component => { js: true },
+        # Ariadne::Beta::CloseButton => {},
+        # Ariadne::Beta::Counter => {},
+        # Ariadne::Beta::Details => {},
+        # Ariadne::Alpha::Dialog => {},
+        # Ariadne::Alpha::Dropdown => { js: true },
+        # Ariadne::Beta::Flash => {},
+        # Ariadne::Beta::Heading => {},
+        # Ariadne::Alpha::HiddenTextExpander => {},
+        # Ariadne::Beta::Label => {},
+        # Ariadne::LayoutComponent => {},
+        # Ariadne::Beta::Link => { js: true },
+        # Ariadne::Beta::Markdown => {},
+        # Ariadne::Alpha::Menu => {},
+        # Ariadne::Navigation::TabComponent => {},
+        # Ariadne::Alpha::Navigation::Tab => {},
+        # Ariadne::Beta::Octicon => {},
+        # Ariadne::Beta::Popover => {},
+        # Ariadne::Beta::ProgressBar => {},
+        # Ariadne::Beta::State => {},
+        # Ariadne::Beta::Spinner => {},
+        # Ariadne::Beta::Subhead => {},
+        # Ariadne::Alpha::TabContainer => { js: true },
+        # Ariadne::Beta::Text => {},
+        # Ariadne::Beta::TimelineItem => {},
+        # Ariadne::Tooltip => {},
+        # Ariadne::Truncate => {},
+        # Ariadne::Beta::Truncate => {},
+        # Ariadne::Alpha::UnderlineNav => {},
+        # Ariadne::Alpha::UnderlinePanels => { js: true },
+        # Ariadne::Alpha::TabNav => {},
+        # Ariadne::Alpha::TabPanels => { js: true },
+        # Ariadne::Alpha::Tooltip => { js: true },
+        # Ariadne::Alpha::ToggleSwitch => { js: true },
+        # Ariadne::Alpha::Overlay => { js: true },
+        # Ariadne::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 },
+        # Ariadne::Alpha::NavList => { js: true },
+        # Ariadne::Alpha::NavList::Item => { js: true, examples: false },
+        # Ariadne::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 },
+        # Ariadne::Beta::NavList => { js: true },
+        # Ariadne::Beta::NavList::Item => { js: true, examples: false },
+        # Ariadne::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 },
+        # Ariadne::Alpha::ActionList => { js: true, examples: false },
+        # Ariadne::Alpha::ActionList::Divider => { examples: false },
+        # Ariadne::Alpha::ActionList::Heading => { examples: false },
+        # Ariadne::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 }
+        Ariadne::Form::TextField::Component => { form_component: true },
+        # Ariadne::Alpha::TextArea => { form_component: true, published: false },
+        # Ariadne::Alpha::Select => { form_component: true, published: false },
+        # Ariadne::Alpha::MultiInput => { form_component: true, js: true, published: false },
+        # Ariadne::Alpha::RadioButton => { form_component: true, published: false },
+        # Ariadne::Alpha::RadioButtonGroup => { form_component: true, published: false },
+        # Ariadne::Alpha::CheckBox => { form_component: true, published: false },
+        # Ariadne::Alpha::CheckBoxGroup => { form_component: true, published: false },
+        # Ariadne::Alpha::SubmitButton => { form_component: true, published: false },
+        # Ariadne::Alpha::FormButton => { form_component: true, published: false }
       }.freeze
 
       include Enumerable

data/lib/ariadne/yard/component_ref.rb

@@ -33,7 +33,7 @@ module Ariadne
       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"
+          "https://github.com/yettoapp/ariadne/tree/main/app/components/#{path}.rb"
         end
       end