docs-kit 0.1.0

data/app/components/docs_ui/request_example.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # One structured request declaration → one code tab per configured API client.
+  # Declare method/path/body once and every client (curl, javascript, ruby,
+  # python by default; plus whatever a site adds) renders its own snippet, in a
+  # DocsUI::Example so the sticky global language preference keeps working.
+  #
+  #   render DocsUI::RequestExample.new(
+  #     method: :post, path: "/v1/webhook_endpoints",
+  #     body: { url: "https://example.com/hook", events: ["payment.paid"] }
+  #   )
+  #
+  #   # only some tabs, in a chosen order:
+  #   render DocsUI::RequestExample.new(method: :get, path: "/v1/things", clients: %i[curl ruby])
+  #
+  # The base URL and an example auth header come from config
+  # (DocsKit.configuration.api_base_url / #api_auth_header); the client set comes
+  # from #api_clients (defaults + site overrides). This replaces the per-client
+  # heredoc a docs page used to hand-write once per endpoint per language.
+  class RequestExample < Phlex::HTML
+    def initialize(method:, path:, body: nil, query: nil, headers: {}, clients: nil)
+      @method = method
+      @path = path
+      @body = body
+      @query = query || {}
+      @headers = headers || {}
+      @clients = clients
+    end
+
+    def view_template
+      request = build_request
+      selected = selected_clients
+
+      render DocsUI::Example.new do |ex|
+        selected.each do |token, client|
+          ex.code(
+            token,
+            lexer: client.lexer,
+            label: client.label,
+            filename: client.filename_for(request)
+          ) { client.render(request) }
+        end
+      end
+    end
+
+    private
+
+    # The request struct handed to every client template: config base URL + path,
+    # config auth header merged into the headers.
+    def build_request
+      config = DocsKit.configuration
+      DocsKit::ApiRequest.new(
+        method: @method,
+        path: @path,
+        url: "#{config.api_base_url}#{@path}",
+        query: @query,
+        headers: merged_headers(config.api_auth_header),
+        body: @body
+      )
+    end
+
+    # The site's example Authorization header (if any) merged into the per-request
+    # headers. The header line is "Name: value"; split it into a { name => value }
+    # entry so templates can format it per language.
+    def merged_headers(auth_header)
+      return @headers if auth_header.nil? || auth_header.strip.empty?
+
+      name, value = auth_header.split(":", 2).map(&:strip)
+      return @headers if value.nil? || value.empty?
+
+      { name => value }.merge(@headers)
+    end
+
+    # The { token => ApiClient } tabs to render, in order: the configured full map,
+    # or just the requested `clients:` tokens (in the given order), skipping any
+    # unknown token so a typo degrades to fewer tabs rather than raising.
+    def selected_clients
+      configured = DocsKit.configuration.api_clients
+      return configured if @clients.nil?
+
+      @clients.filter_map { |token| [token.to_sym, configured[token.to_sym]] if configured.key?(token.to_sym) }.to_h
+    end
+  end
+end

data/app/components/docs_ui/search_box.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The topbar docs-search affordance: a plain GET form to config.search_path (the
+  # JS-off path — Enter lands on the server-rendered results page) that the ONE
+  # docs-nav controller enhances into a keyboard-shortcut palette. The shortcuts
+  # come from config.search_shortcuts (default "/" and "mod+k"): this component
+  # renders one <kbd> hint per shortcut AND emits the parsed list as JSON on the
+  # scope, so the badges and the key bindings share one source and can't drift.
+  # The results dropdown is server-rendered here EMPTY and hidden; docs-nav fills
+  # it from `search.json?q=` as the reader types and toggles it. The form still
+  # submits normally if JS dies mid-typing, so search never depends on JavaScript.
+  #
+  # Rendered by DocsUI::Shell only when DocsKit.configuration.search_enabled?.
+  #
+  # The dropdown/menu/hidden classes are render-time LITERALS (never
+  # interpolated), so Tailwind's scan of this file keeps them; the CSS also
+  # @source inline()s them belt-and-suspenders, since they only appear at render
+  # time (like the Drawer classes).
+  class SearchBox < Phlex::HTML
+    def view_template
+      # data-docs-nav-target="searchScope" roots the palette so the shortcut keys
+      # can focus the input, and the results dropdown is a sibling.
+      # data-docs-nav-shortcuts-value carries the parsed shortcut list as JSON so
+      # docs-nav binds each configured key without hardcoding any.
+      # min-w-0 (not flex-none) so the box SHRINKS on a narrow topbar instead of
+      # pushing the theme switcher off-screen — on a 390px phone the brand +
+      # search + switcher otherwise overflow. The input carries daisyUI's default
+      # min-width, so it too needs min-w-0 + a modest responsive max-width.
+      div(
+        class: "dropdown min-w-0",
+        data: { docs_nav_target: "searchScope", docs_nav_shortcuts_value: shortcuts_json }
+      ) do
+        form(
+          action: config.search_path, method: "get", role: "search",
+          class: "flex min-w-0 items-center", data: { action: "submit->docs-nav#submitSearch" }
+        ) do
+          label(class: "input input-sm flex min-w-0 max-w-[40vw] items-center gap-2 sm:max-w-none") do
+            render DocsUI::Icon.new("search", class: "size-4 opacity-60")
+            search_input
+            shortcut_hint
+          end
+        end
+        results_dropdown
+      end
+    end
+
+    private
+
+    def config = DocsKit.configuration
+
+    def search_input
+      input(
+        type: "search", name: "q", placeholder: "Search…", autocomplete: "off",
+        aria_label: "Search docs", class: "grow bg-transparent",
+        data: {
+          docs_nav_target: "searchInput",
+          action: "input->docs-nav#performSearch keydown->docs-nav#navigateResults"
+        }
+      )
+    end
+
+    # The configured shortcuts (DocsKit::Shortcut list) — drives both the visible
+    # <kbd> badges and the JSON docs-nav binds against, so they can never drift.
+    def shortcuts = config.search_shortcuts
+
+    # The shortcut list as JSON for docs-nav's Value API (data-docs-nav-shortcuts-
+    # value). Each entry is { key, mod, ctrl, shift, alt, meta } — everything the
+    # controller needs to match a keydown without hardcoding any key.
+    def shortcuts_json = shortcuts.map(&:to_h).to_json
+
+    # The keyboard-shortcut hint the reader SEES — one <kbd> badge per configured
+    # shortcut, rendered from DocsKit.configuration.search_shortcuts. A badge's
+    # label is the parsed Shortcut#label ("/", "Ctrl K", "S", …); a mod-chord
+    # badge is tagged data-hint=modifier so docs-nav swaps just its label to ⌘ on
+    # mac — it never changes the key BINDING. Nothing renders when the site
+    # configures no shortcuts. aria-hidden: the badges are decorative (the input
+    # has aria-label).
+    #
+    # The class strings are render-time LITERALS so Tailwind's file scan keeps
+    # them (kbd/kbd-sm are also @source inline'd in the CSS, belt-and-suspenders).
+    def shortcut_hint
+      return if shortcuts.empty?
+
+      span(class: "ml-1 hidden items-center gap-1 sm:flex", aria_hidden: "true") do
+        shortcuts.each { |shortcut| shortcut_badge(shortcut) }
+      end
+    end
+
+    def shortcut_badge(shortcut)
+      kbd(
+        class: "kbd kbd-sm opacity-60",
+        data: { docs_nav_target: "shortcutHint", hint: (shortcut.mod? ? "modifier" : "static") }
+      ) { shortcut.label }
+    end
+
+    # The palette results list — server-rendered EMPTY + hidden; docs-nav fills it.
+    def results_dropdown
+      ul(
+        class: "dropdown-content menu bg-base-200 rounded-box z-40 mt-1 hidden max-h-96 " \
+               "w-80 flex-nowrap overflow-y-auto p-2 shadow-2xl",
+        data: { docs_nav_target: "searchResults" }
+      )
+    end
+  end
+end

data/app/components/docs_ui/search_results.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The server-rendered search results — the JS-off path. A plain page body (the
+  # host renders it inside DocsUI::Shell) that echoes the query, lists the hits
+  # grouped by page, and links each result to its section anchor. With JavaScript
+  # off this IS the search UX; the docs-nav palette is a progressive enhancement
+  # over the same DocsKit::SearchController that renders this.
+  #
+  #   render DocsUI::SearchResults.new(query: params[:q], hits: index.search(params[:q]))
+  #
+  # hits are DocsKit::SearchHit value objects (already ranked, snippet pre-marked
+  # and HTML-safe). A blank query prompts the reader; a query with no hits renders
+  # guidance instead of an empty list.
+  class SearchResults < Phlex::HTML
+    def initialize(query:, hits:)
+      @query = query.to_s
+      @hits = hits
+    end
+
+    def view_template
+      div(class: "mx-auto max-w-3xl") do
+        header
+        if @query.strip.empty?
+          prompt
+        elsif @hits.empty?
+          empty_state
+        else
+          results
+        end
+      end
+    end
+
+    private
+
+    def header
+      h1(class: "mb-2 text-3xl font-bold tracking-tight") { "Search" }
+      return if @query.strip.empty?
+
+      p(class: "mb-8 text-base-content/60") do
+        plain "#{result_count} for "
+        span(class: "font-semibold text-base-content") { "“#{@query}”" }
+      end
+    end
+
+    def result_count
+      n = @hits.size
+      "#{n} result#{'s' unless n == 1}"
+    end
+
+    # Blank query — the bare /docs/search page. Tell the reader what to do.
+    def prompt
+      p(class: "text-base-content/60") { "Type a query above to search the docs." }
+    end
+
+    # A query that matched nothing — guidance, not a dead end.
+    def empty_state
+      div(class: "rounded-box border border-base-300 bg-base-200 p-6 text-center") do
+        p(class: "mb-1 font-medium") { "No results for “#{@query}”." }
+        p(class: "text-sm text-base-content/60") { "Try fewer or more general words." }
+      end
+    end
+
+    # Hits grouped by page: one heading per page, each hit a linked card with its
+    # section label + highlighted snippet. group_by preserves first-seen (rank)
+    # order, so the best-scoring page leads.
+    def results
+      div(class: "space-y-8") do
+        @hits.group_by(&:page_title).each do |page_title, page_hits|
+          section(class: "space-y-2") do
+            h2(class: "text-sm font-semibold uppercase tracking-wider text-base-content/60") { page_title }
+            page_hits.each { |hit| result_row(hit) }
+          end
+        end
+      end
+    end
+
+    def result_row(hit)
+      a(
+        href: hit.href,
+        class: "block rounded-box border border-base-300 bg-base-100 p-4 transition " \
+               "hover:border-primary hover:bg-base-200"
+      ) do
+        # A page-intro hit (no section) is the page overview; label it so as not
+        # to duplicate the page-group heading above it.
+        span(class: "block font-medium text-primary") { hit.section_title || "Overview" }
+        # The snippet is a gem-produced, pre-escaped HTML string (the matched term
+        # wrapped in <mark>, everything else escaped by SearchIndex::Snippet), so
+        # it's trusted markup — raw(safe) is the same idiom DocsUI::Code uses for
+        # its highlighted output. NEVER pass user/config free text here unescaped.
+        p(class: "mt-1 text-sm text-base-content/70") { raw(safe(hit.snippet)) }
+      end
+    end
+  end
+end

data/app/components/docs_ui/section.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # 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.
+  class Section < Phlex::HTML
+    def initialize(title, id: nil, description: nil)
+      @title = title
+      @explicit_id = id
+      @description = description
+    end
+
+    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
+
+    private
+
+    def heading
+      h2(class: "group mb-2 text-2xl font-semibold tracking-tight") do
+        a(href: "##{@id}", class: "no-underline") do
+          plain @title
+          span(class: "ml-2 text-base-content/30 opacity-0 transition group-hover:opacity-100") { "#" }
+        end
+      end
+    end
+
+    # The optional description, rendered under the title. Three accepted forms:
+    #   * a Phlex component instance (e.g. DocsUI::Endpoint) → rendered in place;
+    #   * a proc/lambda → instance_exec'd so it can emit rich Phlex markup;
+    #   * a String → plain, Phlex-escaped text.
+    # A Phlex component also responds to #call, so it MUST be matched before the
+    # callable branch (else it would be instance_exec'd, not rendered).
+    def description
+      return unless @description
+
+      p(class: "mb-4 text-base leading-relaxed text-base-content/70") do
+        case @description
+        when Phlex::SGML then render @description
+        else @description.respond_to?(:call) ? instance_exec(&@description) : plain(@description)
+        end
+      end
+    end
+
+    # ActiveSupport's #parameterize when available (Rails host), else a minimal
+    # ASCII slug so the component works in isolated Phlex tests too.
+    def slugify(text)
+      return text.parameterize if text.respond_to?(:parameterize)
+
+      text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+
+    # De-duplicate the anchor id across every Section on the page. Phlex's render
+    # `context` is a Hash shared by the whole render tree, so sibling sections see
+    # the same used-id counter without any shared parent state. A title that
+    # slugifies to "" (e.g. "C++" → "c" is fine, but "+++" → "") falls back to
+    # "section"; colliding bases get a "-1", "-2", … sequence suffix so in-page
+    # anchors and the auto-TOC/scroll-spy resolve to distinct headings.
+    def unique_id(base)
+      base = "section" if base.empty?
+      used = (context[:__docs_ui_section_ids__] ||= Hash.new(0))
+      n = used[base]
+      used[base] += 1
+      n.zero? ? base : "#{base}-#{n}"
+    end
+  end
+end

data/app/components/docs_ui/shell.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The site shell — the full HTML document. A Phlex layout built on the daisyUI
+  # Drawer: a sticky topbar, a sidebar always visible on desktop (lg:drawer-open)
+  # that toggles as an overlay on mobile, and the page content in a scrollable
+  # main. Loads Turbo + (when present) the phlex-reactive Stimulus controller via
+  # the importmap tags, and the daisyUI-compiled Tailwind build.
+  #
+  # Shell IS the full <html> document, so controllers render the page view with
+  # `layout: false` (see DocsKit::Controller#render_page) to avoid double <html>
+  # nesting. phlex-rails still renders through a real view context, so CSRF,
+  # dom_id, url helpers, and the reactive token signer all work inside components.
+  #
+  #   render DocsUI::Shell.new(title: "Installation") { page_body }
+  class Shell < Phlex::HTML
+    include Phlex::Rails::Helpers::CSRFMetaTags
+    include Phlex::Rails::Helpers::CSPMetaTag
+    include Phlex::Rails::Helpers::ContentSecurityPolicyNonce
+    include Phlex::Rails::Helpers::StylesheetLinkTag
+    include Phlex::Rails::Helpers::JavaScriptImportmapTags
+    include DaisyUI
+
+    DRAWER_ID = "site-drawer"
+
+    # on_page: the auto-TOC placement for this page (:panel/:toggle/:sidebar or
+    # false). Threaded to the sidebar's docs-nav controller; :panel/:toggle also
+    # render an "On this page" slot inside the content column.
+    def initialize(title: nil, on_page: false)
+      @title = title
+      @on_page = DocsKit.configuration.normalize_on_page(on_page)
+    end
+
+    def view_template(&)
+      doctype
+      html(lang: "en", data: { theme: config.default_theme }) do
+        render_head
+        # The docs-nav controller lives on <body> — the shared ancestor of BOTH
+        # the sidebar (collapse persistence, :sidebar TOC injection) and the
+        # content column (:panel/:toggle TOC slot + scroll-spy). Scoping it to the
+        # sidebar alone would put the content-column TOC out of its reach.
+        body(
+          class: "bg-base-100 text-base-content",
+          data: {
+            controller: "docs-nav",
+            docs_nav_storage_key_value: config.nav_storage_key,
+            docs_nav_on_page_value: (@on_page || "").to_s
+          }
+        ) do
+          shell(&)
+        end
+      end
+    end
+
+    private
+
+    def config = DocsKit.configuration
+
+    # The request's CSP nonce, or nil when there's no Rails view context (an
+    # isolated Phlex render, or a host that doesn't nonce script-src). The
+    # phlex-rails value helper delegates to view_context, which raises without
+    # one, so guard on its presence — a nil result makes Phlex omit the
+    # attribute, keeping the un-nonced markup unchanged.
+    def csp_nonce = view_context && content_security_policy_nonce
+
+    # panel/toggle render their TOC in the content column; sidebar mode is
+    # injected by the controller under the active nav link (no content slot).
+    def content_toc? = %i[panel toggle].include?(@on_page)
+
+    def render_head
+      head do
+        title { [@title, config.title_suffix].compact.join(" · ") }
+        meta(charset: "utf-8")
+        meta(name: "viewport", content: "width=device-width,initial-scale=1")
+        csrf_meta_tags
+        csp_meta_tag
+        # Turbo morphs page-level navigations so a re-render preserves scroll and
+        # focus, matching the in-place feel of reactive components.
+        meta(name: "turbo-refresh-method", content: "morph")
+        meta(name: "turbo-refresh-scroll", content: "preserve")
+        config.stylesheets.each { |sheet| stylesheet_link_tag(sheet, data: { turbo_track: "reload" }) }
+        theme_restore_script
+        javascript_importmap_tags
+      end
+    end
+
+    # Restore the persisted theme BEFORE first paint so there's no flash of the
+    # server default before the docs-nav controller runs. Reads the same
+    # localStorage key the controller writes (docs-kit:<site>:theme). Runs on
+    # initial load and on Turbo page renders (turbo:load).
+    #
+    # Carries the request's CSP nonce so the inline script is allowed under a
+    # nonce-based script-src (Rails' default when script-src is in
+    # content_security_policy_nonce_directives). Off a request there is no nonce
+    # (see #csp_nonce) and Phlex omits a nil-valued attribute, so the no-nonce
+    # markup is byte-identical to before.
+    def theme_restore_script
+      key = "docs-kit:#{config.nav_storage_key}:theme"
+      script(nonce: csp_nonce) do
+        raw(safe(<<~JS))
+          (function(){
+            function apply(){
+              try{
+                var t = localStorage.getItem(#{key.to_json});
+                if (t) document.documentElement.setAttribute("data-theme", t);
+              }catch(e){}
+            }
+            apply();
+            document.addEventListener("turbo:load", apply);
+          })();
+        JS
+      end
+    end
+
+    # The daisyUI Drawer app-shell. Desktop: sidebar always open (lg:drawer-open).
+    # Mobile: sidebar hidden, toggled by the hamburger in the topbar.
+    def shell(&block)
+      Drawer(id: DRAWER_ID, class: "lg:drawer-open min-h-screen") do |drawer|
+        drawer.toggle
+
+        drawer.content(class: "flex flex-col min-h-screen") do
+          topbar
+          main(class: "flex-1 overflow-auto px-4 py-8 md:px-8") do
+            # The :panel/:toggle "On this page" is position:fixed to the viewport's
+            # top-right (below the topbar), so it never overlaps the prose. Render
+            # it here so it's inside the docs-nav controller scope; the controller
+            # fills it from the page headings.
+            render DocsUI::OnThisPage.new(mode: @on_page) if content_toc?
+            # id="docs-content" is the stable extraction anchor for the Markdown
+            # export (DocsKit::MarkdownExport walks this subtree). The topbar,
+            # sidebar, and TOC live OUTSIDE it, so they never bleed into the .md.
+            div(id: "docs-content", class: "mx-auto max-w-4xl", &block)
+          end
+        end
+
+        drawer.side(class: "z-40") do
+          drawer.overlay
+          render DocsUI::Sidebar.new
+        end
+      end
+    end
+
+    # Sticky topbar: hamburger (mobile only), brand, search, theme switcher.
+    def topbar
+      div(class: "navbar bg-base-200 border-b border-base-300 sticky top-0 z-30 px-4") do
+        div(class: "flex-1 items-center gap-2") do
+          label(for: DRAWER_ID, class: "btn btn-square btn-ghost btn-sm lg:hidden",
+                aria_label: "Open menu") { render DocsUI::Icon.new("menu", class: "size-5") }
+          a(href: config.brand_href, class: "btn btn-ghost text-lg font-bold") { config.brand }
+        end
+        render DocsUI::SearchBox.new if config.search_enabled?
+        div(class: "flex-none items-center") do
+          # Config-driven repo/social links (config.topbar_links) render as
+          # icon-only ghost buttons BEFORE the switcher; nothing when unset.
+          render DocsUI::TopbarLinks.new
+          render DocsUI::ThemeSwitcher.new
+        end
+      end
+    end
+  end
+end

data/app/components/docs_ui/sidebar.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # The drawer sidebar: a brand header (with an optional version badge) over the
+  # nav, driven entirely by DocsKit.configuration.nav_groups. Renders inside the
+  # daisyUI drawer-side (DocsUI::Shell owns responsive visibility), so this is just
+  # the panel content.
+  #
+  # nav_groups is an ordered Hash:
+  #   { "Heading" => { "Subgroup" => [DocsKit::NavItem, ...] } }
+  class Sidebar < Phlex::HTML
+    include Phlex::Rails::Helpers::Request
+    include DaisyUI
+
+    # Suppress the browser's native <details> disclosure triangle on nav summaries.
+    # daisyUI draws its OWN rotating chevron (li>details>summary::after), so the
+    # native marker would render a SECOND, non-rotating caret stacked next to it.
+    # daisyUI only hides the old ::-webkit-details-marker; modern browsers (and
+    # Safari) also need list-none + the standard ::marker reset. Literal classes —
+    # Tailwind tree-shakes interpolated ones.
+    MARKER_RESET = "list-none [&::-webkit-details-marker]:hidden [&::marker]:content-none"
+
+    def view_template
+      # The docs-nav Stimulus controller lives on <body> (DocsUI::Shell) so it spans
+      # this sidebar AND the content column. Here it drives collapse persistence
+      # and, in :sidebar mode, hosts the injected page TOC. With JS off the server
+      # renders every <details open>, so the sidebar is simply fully expanded.
+      div(class: "bg-base-200 flex min-h-full w-72 flex-col") do
+        header_section
+        div(class: "flex-1 overflow-y-auto px-2 pb-6") do
+          Menu(class: "w-full gap-1") do
+            nav_groups.each { |heading, grouped| nav_group(heading, grouped) }
+          end
+        end
+      end
+    end
+
+    private
+
+    def config = DocsKit.configuration
+    def nav_groups = config.nav_groups
+
+    def header_section
+      div(class: "flex min-h-16 items-center gap-2 px-4") do
+        a(href: config.brand_href, class: "text-lg font-bold text-base-content") { config.brand }
+        badge = config.version_badge_text
+        span(class: "badge badge-sm badge-ghost") { badge } if badge
+      end
+    end
+
+    # A top-level collapsible group (e.g. "Docs") holding collapsible sub-groups
+    # (e.g. "Guide", "Examples"). `grouped` is a { subgroup => [items] } Hash.
+    def nav_group(heading, grouped)
+      return if grouped.nil? || grouped.empty?
+
+      li do
+        details(open: true) do
+          summary(class: "text-xs font-semibold uppercase tracking-wider text-base-content/50 #{MARKER_RESET}") do
+            heading
+          end
+          ul do
+            grouped.each { |subgroup, items| nav_subgroup(subgroup, items) }
+          end
+        end
+      end
+    end
+
+    # A collapsible sub-group: its title is a <summary> so the whole section folds
+    # away. daisyUI's Menu renders nested li>details as an accordion natively.
+    #
+    # NOTE: a collapsible summary must NOT carry `.menu-title` — daisyUI reserves
+    # that for a STATIC (non-<details>) heading and its layout rule for the
+    # rotating caret is `summary:not(.menu-title)`. A `.menu-title` summary loses
+    # the grid layout, so its chevron drops below-left of the label instead of
+    # right-aligning like the top-level group's. Style it as a plain summary
+    # (matching daisyUI's own collapsible-submenu example) so both carets align.
+    def nav_subgroup(subgroup, items)
+      li do
+        details(open: true) do
+          summary(class: "text-xs font-medium text-base-content/60 #{MARKER_RESET}") { subgroup }
+          ul do
+            items.each { |item| li { nav_link(item) } }
+          end
+        end
+      end
+    end
+
+    def nav_link(item)
+      a(href: item.href, class: link_classes(item.href)) do
+        render DocsUI::Icon.new(item.icon, class: "size-4 shrink-0") if item.icon
+        span(class: "truncate") { item.label }
+      end
+    end
+
+    def link_classes(href)
+      active = current_path == href
+      ["flex items-center gap-3", (active ? "menu-active font-medium" : nil)].compact
+    end
+
+    def current_path
+      request&.path
+    rescue StandardError
+      nil
+    end
+  end
+end