Class: DocsUI::Section

Inherits:
Phlex::HTML
  • Object
show all
Defined in:
app/components/docs_ui/section.rb

Overview

A titled doc section with an anchor (so the heading is linkable) and an optional description rendered under the title, before the body. Use inside a Page; compose with Prose for the text.

# plain section
render DocsUI::Section.new("Add the gem") { render DocsUI::Prose.new { … } }

# with a one-line description (a muted lead under the title)
render DocsUI::Section.new("Overview", description: "What this endpoint does.") do
render DocsUI::Prose.new { … }
end

# richer description (e.g. an API endpoint) — pass a block as `description:`
render DocsUI::Section.new("Create a message", description: -> {
code(class: "badge badge-sm") { "POST" }; plain " /v1/messages"
}) { render DocsUI::Prose.new { … } }

# or pass a renderable Phlex component directly (e.g. DocsUI::Endpoint)
render DocsUI::Section.new("Create a message",
description: DocsUI::Endpoint.new(:post, "/v1/messages")) { … }

The description is rendered only when present, so plain sections are unchanged.

Instance Method Summary collapse

Constructor Details

#initialize(title, id: nil, description: nil) ⇒ Section

Returns a new instance of Section.



27
28
29
30
31
 
# File 'app/components/docs_ui/section.rb', line 27

def initialize(title, id: nil, description: nil)
  @title = title
  @explicit_id = id
  @description = description
end

Instance Method Details

#view_template ⇒ Object 



33
34
35
36
37
38
39
40
41
42
 
# File 'app/components/docs_ui/section.rb', line 33

def view_template(&)
  # Resolve the anchor id at render time so it can be de-duplicated against
  # sibling sections sharing this page's render context (see #resolve_id).
  @id = @explicit_id || unique_id(slugify(@title))
  section(id: @id, class: "mb-10 scroll-mt-20") do
    heading
    description
    yield
  end
end