docs-kit 0.1.0

data/app/components/docs_ui/markdown.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "commonmarker"
+
+module DocsUI
+  # A Markdown "island" for prose authoring inside a Phlex page. Parses GFM with
+  # commonmarker (v2, comrak) and walks the AST emitting Phlex nodes — it never
+  # `raw`s commonmarker's HTML. That buys three things:
+  #
+  #   * Phlex-native escaping — author text is escaped by Phlex, so no html_safe
+  #     on free text (Critical Rule 7) and #{} in prose renders literally.
+  #   * Fenced code delegated to DocsUI::Code (Rouge, configured aliases,
+  #     plaintext fallback) — highlighted identically to a hand-written Code block.
+  #   * The exact DocsUI::Prose typography classes on the wrapper, so Markdown
+  #     prose is visually identical to hand-authored Prose.
+  #
+  #   render DocsUI::Markdown.new(<<~MD)
+  #     Write **prose** as GFM. Fenced blocks are highlighted:
+  #
+  #     ```ruby
+  #     puts "hi"
+  #     ```
+  #   MD
+  #
+  # Raw HTML in the source is dropped (the AST's html_block/html_inline nodes are
+  # skipped) — there is no config to enable it. Headings render as styled h3/h4;
+  # document structure and the TOC stay with DocsUI::Section.
+  class Markdown < Phlex::HTML
+    # Reuse Prose's child-selector typography vocabulary verbatim so Markdown and
+    # hand-authored Prose read identically.
+    CLASSES = Prose::CLASSES
+
+    # The kit table wrapper + daisyUI table classes (matches DocsUI's table look).
+    TABLE_WRAPPER = "not-prose my-4 overflow-x-auto rounded-box border border-base-300"
+    TABLE_CLASSES = "table table-sm table-zebra"
+
+    # Render source as INLINE markdown: no Prose wrapper div, and a single
+    # top-level paragraph is unwrapped so its inline children (strong/em/code/
+    # link) sit directly in the surrounding element. Used for a [:md, "…"] table
+    # cell — the cell's <td> is the container, so a block <p>/typography div would
+    # be wrong there.
+    def self.inline(source) = new(source, inline: true)
+
+    def initialize(source, inline: false)
+      # commonmarker v2 raises unless the text is UTF-8. Author heredocs already
+      # are, but nil.to_s / a US-ASCII string would crash the render — normalize
+      # at the boundary so any input parses.
+      @source = source.to_s.encode(Encoding::UTF_8)
+      @inline = inline
+    end
+
+    def view_template
+      return visit_inline(document) if @inline
+
+      div(class: CLASSES) { visit(document) }
+    end
+
+    private
+
+    def document
+      Commonmarker.parse(@source)
+    end
+
+    # Inline render: unwrap each top-level paragraph to its inline children (no
+    # <p>), so `[:md, "a **note**"]` becomes `a <strong>note</strong>` inside the
+    # cell rather than a block paragraph. Non-paragraph blocks (a stray list) still
+    # render as themselves. Adjacent blocks get a joining space so unwrapping never
+    # fuses text ("one" + "two" → "one two", not "onetwo").
+    def visit_inline(node)
+      node.each_with_index do |child, i|
+        whitespace unless i.zero?
+        child.type == :paragraph ? visit_children(child) : visit(child)
+      end
+    end
+
+    # Emit each child of a node in order.
+    def visit_children(node)
+      node.each { |child| visit(child) }
+    end
+
+    # Dispatch a node to its handler (node_<type>). A node type with no handler
+    # just recurses into its children; html_block/html_inline have handlers that
+    # drop them (see below).
+    def visit(node)
+      handler = "node_#{node.type}"
+      respond_to?(handler, true) ? send(handler, node) : visit_children(node)
+    end
+
+    def node_document(node) = visit_children(node)
+
+    def node_paragraph(node)
+      p { visit_children(node) }
+    end
+
+    # Demote so Markdown headings never collide with the page masthead/section
+    # headings: h1→h3, h2→h4, anything deeper caps at h4.
+    def node_heading(node)
+      case node.header_level
+      when 1 then h3 { visit_children(node) }
+      else h4 { visit_children(node) }
+      end
+    end
+
+    def node_text(node) = plain(node.string_content)
+
+    def node_strong(node)
+      strong { visit_children(node) }
+    end
+
+    def node_emph(node)
+      em { visit_children(node) }
+    end
+
+    def node_strikethrough(node)
+      del { visit_children(node) }
+    end
+
+    def node_code(node)
+      code { node.string_content }
+    end
+
+    # Fenced code goes through DocsUI::Code so it is highlighted (Rouge) exactly
+    # like a hand-written block. No fence language falls back to plaintext.
+    def node_code_block(node)
+      lexer = node.fence_info.to_s.strip
+      lexer = "plaintext" if lexer.empty?
+      render DocsUI::Code.new(node.string_content, lexer:)
+    end
+
+    def node_link(node)
+      a(href: node.url) { visit_children(node) }
+    end
+
+    def node_list(node)
+      node.list_type == :ordered ? ol { visit_children(node) } : ul { visit_children(node) }
+    end
+
+    # In a tight list, GFM renders items WITHOUT a <p> wrapper (and Prose styles
+    # `li` directly). Unwrap the item's paragraph children when the parent list is
+    # tight; a loose list keeps the paragraphs (spacing between items).
+    def node_item(node)
+      tight = node.parent&.list_tight
+      li do
+        node.each do |child|
+          tight && child.type == :paragraph ? visit_children(child) : visit(child)
+        end
+      end
+    end
+
+    def node_block_quote(node)
+      blockquote { visit_children(node) }
+    end
+
+    def node_thematic_break(_node) = hr
+
+    def node_softbreak(_node) = whitespace
+
+    def node_linebreak(_node) = br
+
+    # A GFM table: the first row is the header (th), the rest are body cells (td).
+    def node_table(node)
+      rows = node.to_a
+      div(class: TABLE_WRAPPER) do
+        table(class: TABLE_CLASSES) do
+          thead { table_row(rows.first, header: true) } if rows.any?
+          tbody { rows.drop(1).each { |row| table_row(row) } } if rows.length > 1
+        end
+      end
+    end
+
+    def table_row(row, header: false)
+      tr do
+        row.each do |cell|
+          if header
+            th { visit_children(cell) }
+          else
+            td { visit_children(cell) }
+          end
+        end
+      end
+    end
+
+    # Raw HTML is dropped — no live tags from author Markdown.
+    def node_html_block(_node) = nil
+    def node_html_inline(_node) = nil
+  end
+end

data/app/components/docs_ui/markdown_action.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The "Markdown" masthead affordance: a link to the current page's `.md` twin.
+  # With JS off it simply opens the raw Markdown (a working, no-JS fallback); the
+  # docs-nav controller enhances the click into copy-to-clipboard (a new target +
+  # action on the ONE controller — the single-controller rule holds).
+  #
+  #   render DocsUI::MarkdownAction.new(request.path)
+  #
+  # Rendered by DocsUI::Page when DocsKit.configuration.page_markdown_action is
+  # true (the default). The `.md` twin itself is produced by
+  # DocsKit::Controller#render_page → DocsKit::MarkdownExport.
+  class MarkdownAction < Phlex::HTML
+    LABEL = "Markdown"
+    CLASSES = "btn btn-ghost btn-xs gap-1 opacity-70 hover:opacity-100"
+
+    def initialize(path)
+      @path = path.to_s
+    end
+
+    def view_template
+      a(
+        href: md_href,
+        class: CLASSES,
+        # JS-ON: docs-nav intercepts the click, fetches the .md, copies it, and
+        # (because the browser default is prevented) never navigates away.
+        data: { docs_nav_target: "markdownLink", action: "docs-nav#copyMarkdown" }
+      ) do
+        render DocsUI::Icon.new("clipboard", class: "size-3.5")
+        plain LABEL
+      end
+    end
+
+    private
+
+    # The `.md` twin URL: the request path with a `.md` extension, preserving any
+    # query string. Idempotent — a path already ending in `.md` is left as-is.
+    def md_href
+      path, query = @path.split("?", 2)
+      path = "#{path}.md" unless path.end_with?(".md")
+      query ? "#{path}?#{query}" : path
+    end
+  end
+end

data/app/components/docs_ui/on_this_page.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # An "On this page" table of contents that auto-collects the current page's
+  # <h2>/<h3> and highlights the section you're reading (scroll-spy). It ships
+  # EMPTY — the docs-nav Stimulus controller fills it from the DOM, so a page gets
+  # a live, self-maintaining TOC with zero server-side knowledge of its headings.
+  #
+  # Three placements, same data, chosen by `mode:` (see
+  # DocsKit::Configuration::ON_PAGE_MODES):
+  #
+  #   :panel   — a fixed card pinned to the top-right of the viewport (below the
+  #              topbar). On wide screens it's always visible; on narrower screens
+  #              it collapses to a floating toggle button (docs-nav#toggleToc).
+  #   :toggle  — always the floating toggle button + dropdown (top-right).
+  #   :sidebar — a slot the controller fills under the active left-nav item.
+  #
+  # The controller hides the whole thing when the page has too few headings, so
+  # short pages show nothing (data-docs-nav-target="tocRoot" + auto-hide).
+  #
+  #   render DocsUI::OnThisPage.new(mode: :panel)
+  class OnThisPage < Phlex::HTML
+    def initialize(mode: :panel, title: "On this page")
+      @mode = mode
+      @title = title
+    end
+
+    def view_template
+      case @mode
+      when :toggle then toggle_only
+      when :sidebar then nil # the controller injects under the active nav item; no content slot
+      else panel
+      end
+    end
+
+    private
+
+    # The empty list the controller fills. `tocRoot` is what auto-hides on short
+    # pages; the docs-nav controller populates the inner list.
+    def toc_list(**attrs)
+      nav(**mix({ aria_label: @title, data: { docs_nav_target: "toc" } }, attrs)) do
+        heading
+      end
+    end
+
+    def heading
+      div(class: "mb-2 text-xs font-semibold uppercase tracking-wider text-base-content/60") { @title }
+    end
+
+    # :panel — a card fixed to the top-right of the viewport, just below the
+    # sticky topbar. Solid bg-base-300 with a border + shadow so it stands out and
+    # stays out of the way (it never overlaps the prose). On < xl it's hidden and
+    # the compact toggle button takes over instead.
+    #
+    # data-docs-nav-target="tocRoot" wraps BOTH the card and the toggle so the
+    # controller hides the whole feature at once on short pages.
+    def panel
+      div(class: "not-prose", data: { docs_nav_target: "tocRoot" }) do
+        # Wide screens: the always-visible card.
+        toc_list(
+          class: "hidden xl:block fixed right-4 top-20 z-20 max-h-[70vh] w-64 overflow-y-auto " \
+                 "rounded-box border border-base-300 bg-base-300 p-4 text-sm shadow-xl"
+        )
+        # Narrower screens: a floating toggle button that reveals the same card.
+        floating_toggle(hide_on_xl: true)
+      end
+    end
+
+    # :toggle — always the floating toggle button (no always-visible card).
+    def toggle_only
+      div(class: "not-prose", data: { docs_nav_target: "tocRoot" }) do
+        floating_toggle(hide_on_xl: false)
+      end
+    end
+
+    # A floating button pinned top-right that toggles a popover TOC card.
+    # hide_on_xl: true for :panel (hide the button at xl+, where the always-open
+    # card shows instead); false for :toggle (always show the button). The
+    # `xl:hidden` class is written as a LITERAL (never interpolated) so Tailwind's
+    # scanner keeps it — a computed "#{bp}:hidden" would be tree-shaken away.
+    def floating_toggle(hide_on_xl:)
+      wrapper = "fixed right-4 top-20 z-20"
+      wrapper += " xl:hidden" if hide_on_xl
+
+      div(class: wrapper, data: { docs_nav_target: "tocToggleWrap" }) do
+        button(
+          type: "button",
+          class: "btn btn-sm gap-1 border border-base-300 bg-base-300 shadow-lg",
+          aria_label: @title,
+          data: { action: "docs-nav#toggleToc", docs_nav_target: "tocToggleBtn" }
+        ) do
+          render DocsUI::Icon.new("list", class: "size-4")
+          span(class: "hidden sm:inline") { @title }
+        end
+        # The popover card, hidden until toggled.
+        toc_list(
+          class: "hidden mt-2 max-h-[70vh] w-64 overflow-y-auto rounded-box " \
+                 "border border-base-300 bg-base-300 p-4 text-sm shadow-xl",
+          data: { docs_nav_target: "tocPopover" }
+        )
+      end
+    end
+  end
+end

data/app/components/docs_ui/open_api_operation.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders one OpenAPI operation as a full endpoint reference, composed entirely
+  # from the existing kit — zero hand-restatement. Given a
+  # DocsKit::OpenApi::Operation it emits:
+  #
+  #   * a DocsUI::Section titled with the operation summary (id: the operationId,
+  #     so deep links + the auto-TOC resolve), described by a DocsUI::Endpoint badge;
+  #   * the operation description as Markdown prose (when present);
+  #   * a parameters DocsUI::FieldTable and a request-body DocsUI::FieldTable (each
+  #     labelled only when BOTH are present, so a single table reads clean);
+  #   * a DocsUI::ErrorTable from the 4xx/5xx responses (when any);
+  #   * the request block — the operation's x-codeSamples (a DocsUI::Example when
+  #     ≥2, a plain DocsUI::Code when exactly one), else a generated
+  #     DocsUI::RequestExample (respecting a passed clients: filter);
+  #   * a DocsUI::JsonResponse from the first 2xx example (when derivable);
+  #   * finally the caller's block, so a page can append hand-authored prose.
+  #
+  #   render DocsUI::OpenApiOperation.new(doc.operation("createInvoice"))
+  #
+  # The `operation` page helper is the friction-free front door; use this directly
+  # for bespoke composition. It reads config only through the components it composes
+  # (RequestExample pulls api_base_url/auth), never hardcodes a site value.
+  class OpenApiOperation < Phlex::HTML
+    def initialize(operation, clients: nil)
+      @operation = operation
+      @clients = clients
+    end
+
+    def view_template(&block)
+      render DocsUI::Section.new(@operation.title, id: @operation.operation_id, description: endpoint_badge) do
+        operation_description
+        field_tables
+        error_table
+        request_block
+        success_response
+        yield_content(&block)
+      end
+    end
+
+    private
+
+    def endpoint_badge
+      DocsUI::Endpoint.new(@operation.http_method, @operation.path)
+    end
+
+    def operation_description
+      description = @operation.description
+      render DocsUI::Markdown.new(description) if present?(description)
+    end
+
+    # Both FieldTables, each labelled only when the OTHER is also present (so a
+    # lone table reads clean without a redundant "Parameters"/"Body" heading).
+    def field_tables
+      params = @operation.parameter_rows
+      body = @operation.body_rows
+      both = !params.empty? && !body.empty?
+
+      field_table("Parameters", params, labelled: both)
+      field_table("Request body", body, labelled: both)
+    end
+
+    def field_table(label, rows, labelled:)
+      return if rows.empty?
+
+      # All utility classes here are already emitted elsewhere in the kit
+      # (prose.rb / header.rb / shell.rb), so no new Tailwind @source scan is
+      # needed — see Critical Rule 6.
+      h3(class: "mb-2 mt-8 text-lg font-semibold") { label } if labelled
+      render DocsUI::FieldTable.new(rows)
+    end
+
+    def error_table
+      rows = @operation.error_rows
+      render DocsUI::ErrorTable.new(rows) unless rows.empty?
+    end
+
+    # The request block: x-codeSamples win over the generated RequestExample. Two+
+    # samples → a DocsUI::Example (tabbed); exactly one → a plain DocsUI::Code
+    # (Example needs two tabs to render any); none → the generated RequestExample.
+    def request_block
+      samples = @operation.code_samples
+      case samples.length
+      when 0 then generated_request
+      when 1 then single_code_sample(samples.first)
+      else code_sample_tabs(samples)
+      end
+    end
+
+    def generated_request
+      render DocsUI::RequestExample.new(
+        method: @operation.http_method,
+        path: @operation.example_path,
+        body: @operation.example_body,
+        query: @operation.example_query,
+        clients: @clients
+      )
+    end
+
+    def single_code_sample(sample)
+      render DocsUI::Code.new(sample[:source], lexer: sample[:lang])
+    end
+
+    def code_sample_tabs(samples)
+      render DocsUI::Example.new do |ex|
+        samples.each do |sample|
+          ex.code(sample[:lang], label: sample[:label]) { sample[:source] }
+        end
+      end
+    end
+
+    def success_response
+      example = @operation.success_example
+      render DocsUI::JsonResponse.new(example) unless example.nil?
+    end
+
+    def yield_content(&block)
+      yield self if block
+    end
+
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+  end
+end

data/app/components/docs_ui/page.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The base class for a hand-authored doc page. Subclasses set the title (and
+  # optional eyebrow/lead) and implement #content with the page body, composing
+  # the doc kit (Section/Prose/Code/Callout). Page renders it inside DocsUI::Shell
+  # with a consistent masthead.
+  #
+  #   class Views::Docs::Pages::Installation < DocsUI::Page
+  #     title "Installation"
+  #     eyebrow "Guide"
+  #     def lead = "Add the gem and render your first component."
+  #     def content
+  #       render DocsUI::Section.new("Add the gem") { … }
+  #     end
+  #   end
+  class Page < Phlex::HTML
+    include Phlex::Rails::Helpers::Routes
+    # #request drives the "Markdown" masthead action's href (request.path + .md).
+    include Phlex::Rails::Helpers::Request
+    # Authored pages subclass this, so include the kit here: a page body can call
+    # DocsUI::Section(...) / DocsUI::Code(...) directly, no render ... .new.
+    include DocsUI
+    # The lowercase, block-friendly authoring helpers (md/prose/example) — the
+    # friction-free path that never trips the parens-with-blocks gotcha.
+    include DocsUI::PageHelpers
+
+    class << self
+      def title(value = nil)
+        @title = value if value
+        @title
+      end
+
+      def eyebrow(value = nil)
+        @eyebrow = value if value
+        @eyebrow
+      end
+
+      # The "On this page" auto-TOC placement for this page. Defaults to the
+      # configured DocsKit.configuration.on_page_default; set false to opt out,
+      # or :panel/:toggle/:sidebar to override per page.
+      def on_page(value = :__unset__)
+        @on_page = value unless value == :__unset__
+        defined?(@on_page) ? @on_page : DocsKit.configuration.on_page_default
+      end
+    end
+
+    def view_template
+      render DocsUI::Shell.new(title: self.class.title, on_page: self.class.on_page) do
+        # data-md-skip drops this nav from the Markdown export — it's chrome, not
+        # page content (DocsKit::MarkdownExport strips [data-md-skip]). The
+        # "Markdown" action sits opposite "← Home"; it's chrome too, so it lives
+        # inside the skipped nav and never appears in the .md twin.
+        nav(class: "mb-6 flex items-center justify-between gap-4", data: { md_skip: true }) do
+          a(href: root_path, class: "link link-hover text-sm opacity-70") { "← Home" }
+          render DocsUI::MarkdownAction.new(request.path) if markdown_action?
+        end
+
+        render DocsUI::Header.new(self.class.title, eyebrow: self.class.eyebrow) do
+          plain lead if lead
+        end
+
+        content
+      end
+    end
+
+    # Whether to show the "Markdown" masthead action — the config knob
+    # (DocsKit.configuration.page_markdown_action, default true).
+    def markdown_action? = DocsKit.configuration.page_markdown_action
+
+    # The lowercase authoring helpers md/prose/example come from DocsUI::PageHelpers
+    # (included above) — the parens-free path that never hits the constant-reference
+    # SyntaxError. The kit forms (DocsUI::Prose(), DocsUI::Example()) stay valid too.
+
+    # Override in subclasses for the lead paragraph (optional).
+    def lead = nil
+
+    # Override in subclasses with the page body.
+    def content
+      raise NotImplementedError, "#{self.class} must implement #content"
+    end
+  end
+end

data/app/components/docs_ui/page_helpers.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Lowercase, block-friendly authoring helpers mixed into DocsUI::Page. They
+  # exist so the everyday page body never trips the Ruby parens-with-blocks trap:
+  # a lowercase method call takes a block WITHOUT parens, so `prose do … end` is
+  # unambiguously a method call (the bare `DocsUI::Prose do … end` kit form parses
+  # as a constant reference — a SyntaxError). The kit forms stay valid; these are
+  # the friction-free path.
+  #
+  # Extracted from Page so they can be unit-tested against a bare Phlex host:
+  # Page itself includes Phlex::Rails::Helpers::Routes (a live Rails view context)
+  # and cannot load in the standalone suite.
+  module PageHelpers
+    # Render a block of GFM Markdown as Prose-styled prose (see DocsUI::Markdown).
+    # A lowercase method + heredoc sidesteps the parens-with-blocks gotcha:
+    #   md <<~'MD'
+    #     Write **prose** as Markdown. Single-quoted heredoc so #{} stays literal.
+    #   MD
+    def md(source)
+      render DocsUI::Markdown.new(source)
+    end
+
+    # Render hand-authored prose in a DocsUI::Prose wrapper. Lowercase, so it
+    # takes the block without parens: `prose do p { "…" } end`.
+    def prose(&)
+      render DocsUI::Prose.new(&)
+    end
+
+    # Render a multi-language code group (DocsUI::Example). Lowercase, so it takes
+    # the block without parens: `example do |ex| ex.code(:ruby) { … } end`.
+    def example(&)
+      render DocsUI::Example.new(&)
+    end
+
+    # Render one OpenAPI operation from the configured spec as a full endpoint
+    # reference (see DocsUI::OpenApiOperation) — zero hand-restatement. The
+    # operation is looked up on DocsKit.configuration.openapi_document, so
+    # `c.openapi` must be set; an unknown id raises OperationNotFound.
+    #
+    #   operation "createInvoice"                    # the whole endpoint block
+    #   operation "createInvoice", clients: %i[curl ruby]  # filter the client tabs
+    #   operation "createInvoice" do |op| op.plain "…" end # append prose inside it
+    #
+    # `id_or_method`/`path` mirror Document#operation: pass an operationId, or a
+    # verb + path for a spec whose operations have no ids.
+    def operation(id_or_method, path = nil, clients: nil, &)
+      op = DocsKit.configuration.openapi_document.operation(id_or_method, path)
+      render DocsUI::OpenApiOperation.new(op, clients: clients), &
+    end
+  end
+end

data/app/components/docs_ui/prop_table.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A props/options/params reference table: name · type · default · description,
+  # with the first column (the name) auto code-styled. A thin preset over
+  # DocsUI::Table — same cell conventions, same markup, no duplication.
+  #
+  #   render DocsUI::PropTable.new(
+  #     [
+  #       ["brand", "String", '"Docs"', "Topbar + sidebar heading."],
+  #       ["themes", "Array", "%w[dark light]", "ThemeSwitcher options."],
+  #     ]
+  #   )
+  #
+  # The default headers are Option/Type/Default/Description; pass `headers:` to
+  # override (e.g. `%w[Arg Type Default Description]` for a component's args). Cell
+  # values follow DocsUI::Table's convention (String / [:code, "x"] / [:md, "…"]);
+  # the first cell of each row is wrapped in <code> automatically unless it's
+  # already a special-cell pair.
+  class PropTable < Phlex::HTML
+    DEFAULT_HEADERS = %w[Option Type Default Description].freeze
+
+    def initialize(rows, headers: DEFAULT_HEADERS)
+      @rows = rows.map { |cells| code_first_column(cells) }
+      @headers = headers
+    end
+
+    def view_template
+      render DocsUI::Table.new(@headers, @rows)
+    end
+
+    private
+
+    # Auto-code-style the name column. A plain String first cell becomes a
+    # [:code, …] cell; a cell that's already a typed pair ([:code, …]/[:md, …]) is
+    # left as the author wrote it.
+    def code_first_column(cells)
+      first, *rest = cells
+      first = [:code, first] unless first.nil? || first.is_a?(Array)
+      [first, *rest]
+    end
+  end
+end

data/app/components/docs_ui/prose.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A typographic wrapper for hand-authored doc prose. Gives consistent reading
+  # rhythm via Tailwind's arbitrary-variant child selectors (so it does not depend
+  # on a specific typography plugin config). Authoring a doc is just writing
+  # p/ul/h3/code inside.
+  #
+  #   render DocsUI::Prose.new do
+  #     p { "Components are plain Ruby classes." }
+  #     ul { li { "…" } }
+  #   end
+  class Prose < Phlex::HTML
+    CLASSES = [
+      "max-w-none text-base-content/80 leading-relaxed",
+      "[&_p]:my-4",
+      "[&_a]:text-primary [&_a]:underline [&_a:hover]:no-underline",
+      "[&_strong]:text-base-content [&_strong]:font-semibold",
+      "[&_h3]:mt-8 [&_h3]:mb-3 [&_h3]:text-lg [&_h3]:font-semibold [&_h3]:text-base-content",
+      "[&_ul]:my-4 [&_ul]:list-disc [&_ul]:pl-6 [&_ul>li]:my-1",
+      "[&_ol]:my-4 [&_ol]:list-decimal [&_ol]:pl-6 [&_ol>li]:my-1",
+      "[&_code]:rounded [&_code]:bg-base-300 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-sm",
+      "[&_:where(pre)_code]:bg-transparent [&_:where(pre)_code]:p-0"
+    ].join(" ").freeze
+
+    def view_template(&)
+      div(class: CLASSES, &)
+    end
+  end
+end