ruby_ui_admin 0.1.0

data/app/components/ruby_ui_admin/views/show_tab.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Views
+    # Renders a single show tab's content as a standalone fragment (no page chrome), fetched
+    # lazily by the JS when the tab is first opened. `tab_index` is the tab's flat position
+    # across all tab groups on the show view — the same index the full page assigned.
+    class ShowTab < Phlex::HTML
+      include RubyUIAdmin::UI
+      include RailsHelpers
+      include PathHelpers
+      include Translation
+      include StructureRenderer
+      include ShowFields
+
+      def initialize(resource:, record:, tab_index:)
+        @resource = resource
+        @record = record
+        @tab_index = tab_index
+      end
+
+      def view_template
+        tab = flat_tabs[@tab_index]
+        return if tab.nil?
+
+        # Wrapped in the matching `<turbo-frame>` so the lazy frame on the show page swaps this in.
+        # `target="_top"` so links/forms inside the tab break out of the frame (else Turbo renders
+        # "Content missing" navigating within the frame to a page that has no matching frame).
+        tag(:turbo_frame, id: "rua-tab-frame-#{@tab_index}", target: "_top") do
+          render_tab_content(tab)
+        end
+      end
+
+      private
+
+      # Walks the show structure in the same depth-first order the full page renders, collecting
+      # every tab so `@tab_index` maps to the same tab the page's flat counter assigned.
+      def flat_tabs
+        tabs = []
+        collect_tabs(@resource.field_structure(view: :show), tabs)
+        tabs
+      end
+
+      def collect_tabs(items, acc)
+        items.each do |item|
+          if item.is_a?(RubyUIAdmin::Structure::Panel)
+            collect_tabs(item.items, acc)
+          elsif item.is_a?(RubyUIAdmin::Structure::TabGroup)
+            item.tabs.each do |tab|
+              acc << tab
+              collect_tabs(tab.items, acc)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/ruby_ui_admin/views/structure_renderer.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Views
+    # Walks a resource's field structure (fields + panels + tabs) and renders it.
+    # The includer defines `render_field(field)` to render a single field row/input.
+    # Bare top-level fields are grouped into a default card.
+    module StructureRenderer
+      # `wrap_bare:` controls whether loose top-level fields get their own card. It's true
+      # at the top level (so naked fields aren't unframed) and false inside a panel/tab —
+      # which already provide a card — to avoid a redundant nested card layer.
+      def render_structure(items, wrap_bare: true)
+        buffer = []
+
+        flush = lambda do
+          next if buffer.empty?
+
+          group = buffer.dup
+          buffer.clear
+          if wrap_bare
+            render RubyUI::Card.new do
+              render RubyUI::CardContent.new(class: "pt-6 space-y-4") do
+                group.each { |field| render_field(field) }
+              end
+            end
+          else
+            group.each { |field| render_field(field) }
+          end
+        end
+
+        items.each do |item|
+          if item.is_a?(RubyUIAdmin::Fields::BaseField)
+            buffer << item
+          elsif item.is_a?(RubyUIAdmin::Structure::Panel)
+            flush.call
+            render_panel(item)
+          elsif item.is_a?(RubyUIAdmin::Structure::TabGroup)
+            flush.call
+            render_tab_group(item)
+          end
+        end
+
+        flush.call
+      end
+
+      private
+
+      def render_panel(panel)
+        render RubyUI::Card.new(class: "mb-6") do
+          # Show the panel title, except when it merely repeats the name of the tab that
+          # contains it — that's pure duplication (the tab bar already labels the section),
+          # and the empty header would just push the content down. Distinct names still render.
+          if panel.name && panel.name.to_s.strip != @enclosing_tab_name.to_s.strip
+            render RubyUI::CardHeader.new do
+              render RubyUI::CardTitle.new { panel.name }
+            end
+          end
+          render RubyUI::CardContent.new(class: "pt-6 space-y-4") do
+            render_structure(panel.items, wrap_bare: false)
+          end
+        end
+      end
+
+      # Tabs render as a progressive enhancement, driven by the `rua--tabs` Stimulus controller:
+      #   * Without JS: the tab bar is hidden and the panels stack (each as a titled card).
+      #   * With JS: the controller reveals the tab bar, hides the per-panel headings, and shows
+      #     only the active panel. Keys are matched via `data-rua-tab` / `data-rua-tab-panel`.
+      def render_tab_group(group)
+        @tab_group_seq = (@tab_group_seq || 0) + 1
+        base = "rua-tab-#{@tab_group_seq}"
+
+        div(data: {controller: "rua--tabs"}, class: "mb-6") do
+          nav(data: {rua__tabs_target: "nav"}, hidden: true, class: "flex items-center gap-1 border-b border-border mb-4") do
+            group.tabs.each_with_index do |tab, index|
+              button(
+                type: "button",
+                data: {rua__tabs_target: "tab", rua_tab: "#{base}-#{index}", action: "click->rua--tabs#show"},
+                class: "px-3 py-2 -mb-px border-b-2 border-transparent text-sm font-medium text-muted-foreground hover:text-foreground"
+              ) { tab.name }
+            end
+          end
+
+          group.tabs.each_with_index do |tab, index|
+            # Flat index across all tab groups on the page — the lazy fragment endpoint uses it
+            # to locate this exact tab. Incremented for every tab (eager and lazy) so it stays
+            # aligned with the controller's identical walk of the structure.
+            flat_index = (@tab_flat_seq ||= -1) + 1
+            @tab_flat_seq = flat_index
+            # Only non-active tabs (index > 0 within their group) load lazily; the first tab is
+            # the active one and always renders eagerly so there's no flash/spinner up front.
+            lazy_url = (lazy_tabs? && index.positive?) ? tab_fragment_url(flat_index) : nil
+
+            panel_data = {rua__tabs_target: "panel", rua_tab_panel: "#{base}-#{index}"}
+
+            # The tab is just the switchable container — its children (panels) provide the
+            # cards, so we don't wrap the tab body in its own Card (which caused a redundant
+            # nested-panel layer). `wrap_bare: true` still cards loose fields inside a tab.
+            div(data: panel_data, class: "space-y-4") do
+              # Heading shown when stacked (no JS); the controller hides it since the tab bar
+              # already labels the section.
+              h3(data: {rua__tabs_target: "heading"}, class: "text-sm font-semibold uppercase tracking-wide text-muted-foreground") { tab.name }
+              # Skip a description that merely repeats the tab name — it's pure duplication
+              # (the tab bar already shows the name). Genuine, distinct descriptions still render.
+              if tab.description.present? && tab.description.to_s.strip != tab.name.to_s.strip
+                p(class: "text-sm text-muted-foreground") { tab.description }
+              end
+
+              if lazy_url
+                render_lazy_tab_frame("rua-tab-frame-#{flat_index}", lazy_url)
+              else
+                render_tab_content(tab)
+              end
+            end
+          end
+        end
+      end
+
+      # Renders a tab's inner structure, tracking the enclosing tab name so a child panel named
+      # identically to the tab can drop its redundant title (see render_panel).
+      def render_tab_content(tab)
+        prev_tab_name = @enclosing_tab_name
+        @enclosing_tab_name = tab.name
+        render_structure(tab.items, wrap_bare: true)
+        @enclosing_tab_name = prev_tab_name
+      end
+
+      # A lazy `<turbo-frame loading="lazy">`: Turbo fetches `src` when the frame becomes visible
+      # (i.e. when its tab is shown) and swaps in the matching frame from the response (ShowTab).
+      # The spinner shows until then; without JS the <noscript> notice replaces it.
+      # `target="_top"` so links/forms inside the tab content navigate the whole page (otherwise
+      # they'd try to navigate within this frame and Turbo would render "Content missing" — the
+      # target page has no matching frame id). It doesn't affect the frame's own `src` lazy load.
+      def render_lazy_tab_frame(frame_id, src)
+        tag(:turbo_frame, id: frame_id, loading: "lazy", src: src, target: "_top") do
+          div(data: {rua_tab_spinner: true}, class: "flex items-center justify-center py-12") do
+            div(class: "size-6 rounded-full border-2 border-muted border-t-foreground animate-spin", role: "status", aria_label: rua_t("tabs.loading"))
+          end
+          noscript { p(class: "text-sm text-muted-foreground py-4") { rua_t("tabs.requires_js") } }
+        end
+      end
+
+      # Overridden by the Show view to enable lazy tab loading; eager everywhere else.
+      def lazy_tabs? = false
+
+      def tab_fragment_url(_flat_index) = nil
+    end
+  end
+end

data/app/components/ruby_ui_admin/views/translation.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Views
+    # Translates framework UI strings under the `ruby_ui_admin.*` i18n namespace.
+    module Translation
+      def rua_t(key, **options)
+        I18n.t("ruby_ui_admin.#{key}", **options)
+      end
+    end
+  end
+end

data/app/controllers/ruby_ui_admin/actions_controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  # Renders an action's form (GET #show) and executes it (POST #run).
+  class ActionsController < ApplicationController
+    before_action :set_resource
+    before_action :set_action_entry
+    before_action :set_records
+
+    def show
+      action = build_action
+      authorize_action!(:act_on, on: authorization_target, policy_class: policy_class)
+
+      # `?fragment=1` returns just the form (no page chrome), wrapped in the modal's matching
+      # `<turbo-frame id=frame_id>` so Turbo swaps it in. The action's `fields` are only
+      # evaluated when the modal is actually opened (the frame is loaded).
+      if params[:fragment]
+        render RubyUIAdmin::Views::ActionForm.new(
+          resource: @resource,
+          action: action,
+          action_id: params[:action_id],
+          record_ids: @record_ids,
+          frame_id: params[:frame_id]
+        )
+      else
+        render Views::Action.new(
+          resource: @resource,
+          action: action,
+          action_id: params[:action_id],
+          record_ids: @record_ids
+        )
+      end
+    end
+
+    def run
+      action = build_action
+      authorize_action!(:act_on, on: authorization_target, policy_class: policy_class)
+
+      action.records = @records
+      action.field_values = field_values(action)
+      invoke_handle(action)
+
+      process_response(action.response)
+    end
+
+    private
+
+    def set_resource
+      resource_class = RubyUIAdmin.resource_manager.find_by_route_key(params[:resource_name])
+      raise ActionController::RoutingError, "Unknown resource #{params[:resource_name]}" if resource_class.nil?
+
+      @resource = resource_class.new.hydrate(user: current_user, params: params)
+    end
+
+    def set_action_entry
+      @entry = @resource.find_action_entry(params[:action_id])
+      raise ActionController::RoutingError, "Unknown action #{params[:action_id]}" if @entry.nil?
+    end
+
+    def set_records
+      @record_ids = Array(params[:record_ids]).reject(&:blank?)
+      @records = @record_ids.any? ? @resource.base_query.where(id: @record_ids).to_a : []
+    end
+
+    def policy_class
+      @resource.class.authorization_policy
+    end
+
+    def authorization_target
+      @records.first || @resource.model_class
+    end
+
+    def action_view
+      @records.size == 1 ? :show : :index
+    end
+
+    def build_action
+      action = @resource.instantiate_action(@entry, view: action_view, records: @records)
+      action.controller = self
+      action
+    end
+
+    # Indifferent-access so `handle` can read `fields[:csv_file]` or `fields["csv_file"]`.
+    def field_values(action)
+      submitted = params[:fields] || {}
+      values = action.get_fields.each_with_object({}) do |field, acc|
+        acc[field.id.to_s] = submitted[field.id.to_s]
+      end
+      ActiveSupport::HashWithIndifferentAccess.new(values)
+    end
+
+    # Supports both `handle(query:, fields:, current_user:, resource:, **)` and
+    # the positional `handle(args)` style (args[:records], args[:fields], ...).
+    def invoke_handle(action)
+      kwargs = {
+        query: @records,
+        records: @records,
+        fields: action.field_values,
+        current_user: current_user,
+        resource: @resource
+      }
+
+      parameters = action.method(:handle).parameters
+      keyword_kinds = parameters.map(&:first)
+
+      if (keyword_kinds & %i[key keyreq keyrest]).any?
+        if keyword_kinds.include?(:keyrest)
+          action.handle(**kwargs)
+        else
+          accepted = parameters.select { |(type, _)| %i[key keyreq].include?(type) }.map(&:last)
+          action.handle(**kwargs.slice(*accepted))
+        end
+      else
+        action.handle(kwargs)
+      end
+    end
+
+    def process_response(response)
+      case response[:type]
+      when :download
+        download = response[:download]
+        return send_data(download[:content], filename: download[:filename])
+      end
+
+      apply_flash(messages_for(response))
+
+      # 303 See Other so Turbo follows the POST→redirect as a GET visit.
+      case response[:type]
+      when :redirect
+        redirect_to resolve_path(response[:path]), status: :see_other
+      else # :reload and default
+        redirect_back fallback_location: default_back_path, status: :see_other
+      end
+    end
+
+    # An action that finishes without setting its own message still confirms it ran (Avo
+    # parity) — unless it explicitly opted out with `silent`.
+    def messages_for(response)
+      messages = Array(response[:messages])
+      return messages if messages.any? || response[:silent]
+
+      [{type: :success, body: I18n.t("ruby_ui_admin.actions.ran_successfully")}]
+    end
+
+    def apply_flash(messages)
+      Array(messages).each do |message|
+        key = (message[:type] == :error) ? :alert : :notice
+        flash[key] = message[:body]
+      end
+    end
+
+    def resolve_path(path)
+      return default_back_path if path.nil?
+
+      path.respond_to?(:call) ? instance_exec(&path) : path
+    end
+
+    def default_back_path
+      helpers.public_send("resources_#{@resource.route_key}_path")
+    end
+  end
+end

data/app/controllers/ruby_ui_admin/application_controller.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "pagy"
+# `pagy/extras/countless` is required at engine boot (see engine.rb) before host initializers.
+
+module RubyUIAdmin
+  class ApplicationController < ActionController::Base
+    include Pagy::Backend
+
+    protect_from_forgery with: :exception
+
+    around_action :with_current_context
+    before_action :authenticate_admin!
+
+    helper_method :current_user
+
+    rescue_from RubyUIAdmin::NotAuthorizedError do |error|
+      render plain: "403 Forbidden — #{error.message}", status: :forbidden
+    end
+
+    private
+
+    def with_current_context
+      RubyUIAdmin::Current.request = request
+      RubyUIAdmin::Current.user = current_user
+      RubyUIAdmin::Current.true_user = true_user
+      with_admin_locale_and_timezone { yield }
+    ensure
+      RubyUIAdmin::Current.reset
+    end
+
+    # Applies the configured timezone and locale for the duration of the request.
+    def with_admin_locale_and_timezone(&block)
+      zone = RubyUIAdmin.configuration.timezone
+      locale = RubyUIAdmin.configuration.locale
+
+      localized = lambda do
+        locale ? I18n.with_locale(locale, &block) : block.call
+      end
+
+      zone ? Time.use_zone(zone) { localized.call } : localized.call
+    end
+
+    def current_user
+      return @current_user if defined?(@current_user)
+
+      method = RubyUIAdmin.configuration.current_user_method
+      @current_user =
+        if method
+          instance_exec(self, &method)
+        else
+          # Sensible fallback for Warden/Devise hosts when no method is configured.
+          request.env["warden"]&.user
+        end
+    end
+
+    # The real (non-impersonated) user; defaults to `current_user` when no method is set.
+    def true_user
+      return @true_user if defined?(@true_user)
+
+      method = RubyUIAdmin.configuration.true_user_method
+      @true_user = method ? instance_exec(self, &method) : current_user
+    end
+    helper_method :true_user
+
+    def authenticate_admin!
+      block = RubyUIAdmin.configuration.authenticate_with
+      instance_exec(&block) if block
+    end
+
+    # Builds an authorization service for the current user.
+    def authorization_for(record = nil, policy_class: nil)
+      Services::AuthorizationService.new(current_user, record, policy_class: policy_class, true_user: true_user)
+    end
+
+    # Authorizes a rule or raises NotAuthorizedError.
+    def authorize_action!(rule, on:, policy_class: nil)
+      authorization_for(on, policy_class: policy_class).authorize_action(rule, raise_exception: true)
+    end
+  end
+end

data/app/controllers/ruby_ui_admin/dashboards_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  class DashboardsController < ApplicationController
+    def show
+      dashboard_class = RubyUIAdmin.dashboard_manager.find(params[:dashboard_id])
+      raise ActionController::RoutingError, "Unknown dashboard #{params[:dashboard_id]}" if dashboard_class.nil?
+
+      render Views::Dashboard.new(dashboard: dashboard_class.new)
+    end
+  end
+end

data/app/controllers/ruby_ui_admin/docs_controller.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  # In-app documentation browser. Renders the gem's bundled `docs/*.md` files as HTML at
+  # `<mount>/docs`. Availability is controlled by `config.docs_enabled` (default `:local`, i.e.
+  # development/test only). In local environments it's open (no auth) for convenience; in any other
+  # environment (e.g. production, when explicitly enabled) it runs behind the admin's
+  # `authenticate_admin!` gate.
+  class DocsController < ApplicationController
+    skip_before_action :authenticate_admin!, if: -> { Rails.env.local? }
+
+    # Root of the gem's Markdown documentation.
+    DOCS_ROOT = RubyUIAdmin::Engine.root.join("docs").freeze
+
+    before_action :ensure_docs_enabled!
+
+    def show
+      rel = resolve_relative_path(params[:path])
+      return head(:not_found) unless rel
+
+      abs = File.expand_path(rel, DOCS_ROOT)
+      return head(:not_found) unless safe_doc_path?(abs)
+
+      source = File.read(abs)
+      html = render_markdown(source, current_dir: File.dirname(rel))
+
+      render Views::Docs.new(
+        body_html: html,
+        title: doc_title(source) || humanize_slug(slug_for(rel)),
+        nav_groups: nav_groups,
+        current_slug: slug_for(rel)
+      )
+    rescue MissingDocsDependency => e
+      render Views::Docs.new(
+        body_html: dependency_help_html(e.message),
+        title: "Documentation",
+        nav_groups: [],
+        current_slug: nil
+      )
+    end
+
+    private
+
+    def ensure_docs_enabled!
+      head :not_found unless RubyUIAdmin.configuration.docs_enabled?
+    end
+
+    # Maps a URL path segment to a `docs/`-relative `.md` file. Returns nil for anything that
+    # isn't a plain Markdown file (defense in depth alongside `safe_doc_path?`).
+    def resolve_relative_path(path)
+      slug = path.presence || "README"
+      slug = slug.delete_suffix(".md")
+      return nil if slug.include?("\0")
+
+      "#{slug}.md"
+    end
+
+    # True only when `abs` is an existing `.md` file inside DOCS_ROOT (blocks `../` traversal).
+    def safe_doc_path?(abs)
+      root = DOCS_ROOT.to_s
+      abs.start_with?("#{root}/") && abs.end_with?(".md") && File.file?(abs)
+    end
+
+    def slug_for(rel)
+      rel.delete_suffix(".md")
+    end
+
+    # ---- Markdown ----------------------------------------------------------------------------
+
+    def render_markdown(text, current_dir:)
+      load_markdown_deps!
+
+      # No `syntax_highlighter`: kramdown still emits `<pre><code class="language-…">` for fenced
+      # blocks (styled by the view's CSS). We skip Rouge on purpose — its kramdown integration uses
+      # a deprecated formatter that warns once per code block, flooding the dev log.
+      html = Kramdown::Document.new(text, input: "GFM", hard_wrap: false, auto_ids: true).to_html
+      rewrite_internal_links(html, current_dir)
+    end
+
+    def load_markdown_deps!
+      require "kramdown"
+      require "kramdown-parser-gfm"
+    rescue LoadError
+      raise MissingDocsDependency, "kramdown"
+    end
+
+    # Rewrites relative `*.md` links so they point at the docs route instead of 404-ing.
+    # Absolute (http), anchor-only, and mailto links are left untouched.
+    def rewrite_internal_links(html, current_dir)
+      fragment = Nokogiri::HTML5.fragment(html)
+
+      fragment.css("a[href]").each do |node|
+        href = node["href"]
+        next if href.blank? || href.match?(%r{\A(?:[a-z]+:|//|/|#)})
+
+        path, anchor = href.split("#", 2)
+        next unless path&.end_with?(".md")
+
+        slug = resolve_link_slug(path, current_dir)
+        new_href = doc_href(slug)
+        new_href += "##{anchor}" if anchor.present?
+        node["href"] = new_href
+      end
+
+      fragment.to_html
+    end
+
+    # Resolves a relative `.md` link (e.g. `../fields/overview.md`) against the current doc's
+    # directory, returning a clean `docs/`-relative slug.
+    def resolve_link_slug(path, current_dir)
+      base = current_dir == "." ? "/" : "/#{current_dir}"
+      File.expand_path(path, base).delete_prefix("/").delete_suffix(".md")
+    end
+
+    def doc_href(slug)
+      slug == "README" ? docs_path : doc_path(path: slug)
+    end
+
+    # ---- Navigation --------------------------------------------------------------------------
+
+    def nav_groups
+      entries = Dir.glob(DOCS_ROOT.join("**/*.md")).sort.map do |abs|
+        rel = Pathname.new(abs).relative_path_from(DOCS_ROOT).to_s
+        slug = slug_for(rel)
+        {
+          slug: slug,
+          title: doc_title(File.read(abs)) || humanize_slug(slug),
+          href: doc_href(slug),
+          group: rel.include?("/") ? rel.split("/").first : nil
+        }
+      end
+
+      root = entries.select { |e| e[:group].nil? }
+      grouped = entries.reject { |e| e[:group].nil? }.group_by { |e| e[:group] }
+
+      result = []
+      result << {label: nil, items: root} if root.any?
+      grouped.sort.each { |dir, items| result << {label: humanize_slug(dir), items: items} }
+      result
+    end
+
+    # ---- Helpers -----------------------------------------------------------------------------
+
+    # The first level-1 heading of a Markdown document, if any.
+    def doc_title(source)
+      source[/^\#\s+(.+)$/, 1]&.strip
+    end
+
+    def humanize_slug(slug)
+      slug.split("/").last.tr("-_", " ").split.map(&:capitalize).join(" ")
+    end
+
+    def dependency_help_html(gem_name)
+      <<~HTML
+        <h1>Documentation viewer needs a Markdown renderer</h1>
+        <p>Add these to your app's <code>:development</code> group and <code>bundle install</code>:</p>
+        <pre><code>gem "kramdown"
+        gem "kramdown-parser-gfm"</code></pre>
+        <p>(Missing: <code>#{ERB::Util.html_escape(gem_name)}</code>.)</p>
+      HTML
+    end
+
+    # Raised when the Markdown gems aren't installed in the host app.
+    class MissingDocsDependency < StandardError; end
+  end
+end

data/app/controllers/ruby_ui_admin/home_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  class HomeController < ApplicationController
+    def index
+      resources = RubyUIAdmin.resource_manager.navigation_resources
+
+      # Redirect to the first resource's index, or the configured home path.
+      if (home = RubyUIAdmin.configuration.home_path)
+        redirect_to home
+      elsif resources.any?
+        redirect_to helpers.public_send("resources_#{resources.first.route_key}_path")
+      else
+        render Views::Home.new(resources: resources)
+      end
+    end
+  end
+end