ruby_ui_admin 0.1.0

data/app/controllers/ruby_ui_admin/resources_controller.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  class ResourcesController < ApplicationController
+    before_action :set_resource
+    before_action :set_record, only: %i[show edit update destroy]
+    before_action :alias_model_params, only: %i[create update]
+
+    def index
+      authorize_action!(:index, on: model_class, policy_class: policy_class)
+
+      query = authorization_for(model_class, policy_class: policy_class).apply_policy(@resource.base_query)
+      query = apply_scope(query)
+      query = apply_filters(query)
+      query = apply_sorting(query)
+
+      limit = RubyUIAdmin.configuration.per_page
+      countless = @resource.class.countless || RubyUIAdmin.configuration.countless_pagination?
+      @pagy, @records =
+        if countless
+          pagy_countless(query, limit: limit)
+        else
+          pagy(query, limit: limit)
+        end
+
+      render Views::Index.new(
+        resource: @resource,
+        records: @records,
+        pagy: @pagy,
+        filters: @resource.get_filters,
+        filter_values: filter_params,
+        scopes: @resource.get_scopes,
+        current_scope_key: current_scope&.key,
+        scope_param: params[:scope],
+        remove_scope_all: @resource.remove_scope_all?,
+        query_params: request.query_parameters,
+        sort_by: params[:sort_by],
+        sort_direction: sort_direction
+      )
+    end
+
+    def show
+      authorize_action!(:show, on: @record, policy_class: policy_class)
+      @resource.hydrate(record: @record, view: :show)
+
+      # `?tab=N&fragment=1` returns just one tab's content (no page chrome) for lazy tab loading,
+      # so that tab's fields/associations are only evaluated when the tab is actually opened.
+      if params[:fragment] && params[:tab]
+        render Views::ShowTab.new(resource: @resource, record: @record, tab_index: params[:tab].to_i)
+      else
+        render Views::Show.new(resource: @resource, record: @record)
+      end
+    end
+
+    def new
+      @record = @resource.new_record
+      authorize_action!(:create, on: @record, policy_class: policy_class)
+      @resource.hydrate(record: @record, view: :new)
+      @resource.apply_defaults(@record)
+
+      render Views::Form.new(resource: @resource, record: @record, view: :new)
+    end
+
+    def create
+      @record = @resource.new_record
+      authorize_action!(:create, on: @record, policy_class: policy_class)
+      @resource.hydrate(record: @record, view: :new)
+      @resource.apply_defaults(@record)
+      fill_record(@record, :new)
+
+      if @record.save
+        create_success_action
+      else
+        create_fail_action
+      end
+    end
+
+    def edit
+      authorize_action!(:update, on: @record, policy_class: policy_class)
+      @resource.hydrate(record: @record, view: :edit)
+
+      render Views::Form.new(resource: @resource, record: @record, view: :edit)
+    end
+
+    def update
+      authorize_action!(:update, on: @record, policy_class: policy_class)
+      fill_record(@record, :edit)
+
+      if @record.save
+        update_success_action
+      else
+        update_fail_action
+      end
+    end
+
+    def destroy
+      authorize_action!(:destroy, on: @record, policy_class: policy_class)
+
+      if @record.destroy
+        destroy_success_action
+      else
+        destroy_fail_action
+      end
+    end
+
+    private
+
+    # ---- Lifecycle hooks (override in a per-resource controller) ----
+
+    def create_success_action
+      redirect_to after_create_path, notice: create_success_message, status: :see_other
+    end
+
+    # Flash messages for the lifecycle hooks. Overridable; also available to host
+    # per-resource controllers.
+    def create_success_message = "#{resource_label} was successfully created."
+
+    def update_success_message = "#{resource_label} was successfully updated."
+
+    def destroy_success_message = "#{resource_label} was successfully destroyed."
+
+    def create_fail_action
+      @resource.hydrate(record: @record, view: :new)
+      render Views::Form.new(resource: @resource, record: @record, view: :new), status: :unprocessable_entity
+    end
+
+    def update_success_action
+      redirect_to after_update_path, notice: update_success_message, status: :see_other
+    end
+
+    def update_fail_action
+      @resource.hydrate(record: @record, view: :edit)
+      render Views::Form.new(resource: @resource, record: @record, view: :edit), status: :unprocessable_entity
+    end
+
+    def destroy_success_action
+      redirect_to after_destroy_path, notice: destroy_success_message, status: :see_other
+    end
+
+    def destroy_fail_action
+      redirect_to record_path(@record), alert: "#{resource_label} could not be destroyed.", status: :see_other
+    end
+
+    def after_create_path = record_path(@record)
+
+    def after_update_path = record_path(@record)
+
+    def after_destroy_path = resources_index_path
+
+    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_record
+      @record = @resource.find_record(params[:id])
+    end
+
+    def model_class
+      @resource.model_class
+    end
+
+    def policy_class
+      @resource.class.authorization_policy
+    end
+
+    def resource_label
+      @resource.model_class.model_name.human
+    end
+
+    # This engine submits form params under `params[:record]`. Mirror them under the model's
+    # param key (e.g. `params[:user]`) too, so host controllers that re-read params by the
+    # model key keep working.
+    def alias_model_params
+      return unless params[:record].present?
+
+      key = model_class.model_name.param_key
+      params[key] ||= params[:record]
+    end
+
+    def fill_record(record, view)
+      # Hydrate the resource with the record so field-level authorization is evaluated
+      # against it (only authorized fields are permitted/filled).
+      @resource.hydrate(record: record, view: view)
+
+      fields = @resource.get_fields(view: view).reject(&:readonly?)
+      attributes = params.fetch(:record, ActionController::Parameters.new).permit(*fields.flat_map(&:permit_params))
+
+      fields.each { |field| field.fill(record, attributes) }
+    end
+
+    def filter_params
+      raw = params[:filters]
+      return {} if raw.blank?
+
+      raw.respond_to?(:to_unsafe_h) ? raw.to_unsafe_h : raw.to_h
+    end
+
+    # The selected scope: explicit `?scope=` wins; `scope=all` clears it; otherwise the
+    # resource's default scope (if any) applies.
+    def current_scope
+      key = params[:scope]
+      return nil if key == "all"
+      return @resource.find_scope(key) if key.present?
+
+      @resource.default_scope_entry
+    end
+
+    def apply_scope(query)
+      scope = current_scope
+      scope ? scope.apply(query) : query
+    end
+
+    def apply_filters(query)
+      submitted = filter_params
+      @resource.get_filters.each do |filter|
+        key = filter.param_key
+        # Use the filter's `default` only when its param wasn't submitted at all (so an
+        # explicitly-cleared filter stays cleared).
+        value = submitted.key?(key) ? submitted[key] : filter.default
+        next if value.blank?
+
+        query = filter.apply(request, query, value)
+      end
+      query
+    end
+
+    def apply_sorting(query)
+      sort_by = params[:sort_by]
+      return query if sort_by.blank?
+
+      field = @resource.find_field(sort_by)
+      return query unless field&.sortable?
+
+      if (custom = field.sort_lambda)
+        # Custom sort: `sortable: -> { query.reorder(...) }` with `query`, `direction`
+        # and `resource` available as readers.
+        ExecutionContext.new(target: custom, query: query, direction: sort_direction, resource: @resource).handle
+      else
+        query.reorder(field.database_id => sort_direction)
+      end
+    end
+
+    def sort_direction
+      params[:sort_direction] == "desc" ? :desc : :asc
+    end
+
+    # Path helpers resolving the dynamic per-resource routes.
+    def resources_index_path
+      helpers.public_send("resources_#{@resource.route_key}_path")
+    end
+
+    def record_path(record)
+      helpers.public_send("resources_#{@resource.singular_route_key}_path", record)
+    end
+  end
+end

data/config/locales/ruby_ui_admin.en.yml

@@ -0,0 +1,59 @@
+en:
+  ruby_ui_admin:
+    actions:
+      new: "New %{model}"
+      show: "Show"
+      edit: "Edit"
+      destroy: "Delete"
+      create: "Create"
+      update: "Update"
+      cancel: "Cancel"
+      ran_successfully: "Action ran successfully."
+    nav:
+      sign_out: "Sign out"
+    index:
+      actions: "Actions"
+      empty: "No records found."
+      filter: "Filter"
+      clear: "Clear"
+      all: "All"
+      with_selected: "With selected:"
+      search: "Search…"
+      selected_suffix: "selected"
+      no_results: "No results."
+    confirm:
+      title: "Are you sure?"
+      message: "This action cannot be undone."
+      destroy_title: "Delete record"
+      destroy: "Delete “%{model}”? This action cannot be undone."
+      cancel: "Cancel"
+      confirm: "Delete"
+    form:
+      errors: "Please fix the following errors:"
+    fields:
+      file:
+        remove: "Remove current file"
+    booleans:
+      "true": "Yes"
+      "false": "No"
+    associations:
+      count:
+        one: "%{count} item"
+        other: "%{count} items"
+      more: "+%{count} more"
+    tabs:
+      loading: "Loading…"
+      requires_js: "This content requires JavaScript."
+    pagination:
+      showing: "Showing %{from}–%{to} of %{count}"
+      page: "Page %{page} of %{pages}"
+      page_only: "Page %{page}"
+      previous: "Previous"
+      next: "Next"
+  # Locale-aware formats used by the date/date_time fields (no explicit `format:`).
+  time:
+    formats:
+      ruby_ui_admin: "%Y-%m-%d %H:%M"
+  date:
+    formats:
+      ruby_ui_admin: "%Y-%m-%d"

data/config/locales/ruby_ui_admin.pt-BR.yml

@@ -0,0 +1,59 @@
+"pt-BR":
+  ruby_ui_admin:
+    actions:
+      new: "Novo %{model}"
+      show: "Ver"
+      edit: "Editar"
+      destroy: "Excluir"
+      create: "Criar"
+      update: "Atualizar"
+      cancel: "Cancelar"
+      ran_successfully: "Ação executada com sucesso."
+    nav:
+      sign_out: "Sair"
+    index:
+      actions: "Ações"
+      empty: "Nenhum registro encontrado."
+      filter: "Filtrar"
+      clear: "Limpar"
+      all: "Todos"
+      with_selected: "Com selecionados:"
+      search: "Pesquisar…"
+      selected_suffix: "selecionados"
+      no_results: "Nenhum resultado."
+    confirm:
+      title: "Tem certeza?"
+      message: "Esta ação não pode ser desfeita."
+      destroy_title: "Excluir registro"
+      destroy: "Excluir “%{model}”? Esta ação não pode ser desfeita."
+      cancel: "Cancelar"
+      confirm: "Excluir"
+    form:
+      errors: "Corrija os seguintes erros:"
+    fields:
+      file:
+        remove: "Remover arquivo atual"
+    booleans:
+      "true": "Sim"
+      "false": "Não"
+    associations:
+      count:
+        one: "%{count} item"
+        other: "%{count} itens"
+      more: "+%{count} mais"
+    tabs:
+      loading: "Carregando…"
+      requires_js: "Este conteúdo requer JavaScript."
+    pagination:
+      showing: "Exibindo %{from}–%{to} de %{count}"
+      page: "Página %{page} de %{pages}"
+      page_only: "Página %{page}"
+      previous: "Anterior"
+      next: "Próximo"
+  # Formatos locale-aware usados pelos campos date/date_time (sem `format:` explícito).
+  time:
+    formats:
+      ruby_ui_admin: "%d/%m/%Y %H:%M"
+  date:
+    formats:
+      ruby_ui_admin: "%d/%m/%Y"

data/config/routes/dynamic_routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Draws RESTful routes for every registered resource, e.g.:
+#   resources_posts_path, new_resources_post_path, edit_resources_post_path, ...
+# The generic ResourcesController reads params[:resource_name] to resolve the resource.
+RubyUIAdmin.resource_manager.resources.each do |resource|
+  resources resource.route_key,
+    controller: RubyUIAdmin.controller_for(resource),
+    as: "resources_#{resource.route_key}",
+    defaults: {resource_name: resource.route_key}
+end

data/config/routes.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+RubyUIAdmin::Engine.routes.draw do
+  root to: "home#index"
+
+  # In-app docs browser: renders the gem's `docs/*.md` as HTML at `<mount>/docs`.
+  # Gated by `config.docs_enabled` (default `:local` — development/test only). When enabled in
+  # production it sits behind the admin authentication gate (see DocsController).
+  if RubyUIAdmin.configuration.docs_enabled?
+    get "/docs", to: "docs#show", as: :docs
+    get "/docs/*path", to: "docs#show", as: :doc, format: false
+  end
+
+  get "/dashboards/:dashboard_id", to: "dashboards#show", as: :dashboard
+
+  # Custom actions (declared before the dynamic resource routes so the 3-segment
+  # action path takes precedence). GET renders the action form, POST runs it.
+  get "/:resource_name/actions/:action_id", to: "actions#show", as: :resource_action
+  post "/:resource_name/actions/:action_id", to: "actions#run"
+
+  # Per-resource RESTful routes, generated from the resource registry.
+  draw(:dynamic_routes)
+end

data/docs/README.md

@@ -0,0 +1,53 @@
+# RubyUI Admin — Documentation
+
+> The README covers the essentials. This folder holds the full documentation, split by topic.
+
+> **Read these inside your app.** The admin can serve this documentation rendered as HTML at
+> `<mount>/docs` (e.g. `/admin/docs`). By default (`config.docs_enabled = :local`) it's mounted in
+> development/test only; set `config.docs_enabled = true` to expose it in production too (where it
+> runs behind the admin's auth gate). Add `kramdown` + `kramdown-parser-gfm` to the bundle of the
+> target environment — see
+> [Configuration › In-app docs browser](getting-started/configuration.md#in-app-docs-browser).
+
+## Getting started
+- [Practical guide: a working admin from scratch](getting-started/practical-guide.md) — copy‑paste, start here
+- [Installation](getting-started/installation.md)
+- [Configuration](getting-started/configuration.md)
+- [Authentication](getting-started/authentication.md)
+- [Internationalization (i18n)](getting-started/internationalization.md)
+
+## Resources
+- [Overview](resources/overview.md)
+- [Tabs & panels](resources/tabs-panels.md)
+- [Index customization](resources/index-customization.md)
+- [Associations](resources/associations.md)
+- [Scopes](resources/scopes.md)
+
+## Fields
+- [Overview & field catalog](fields/overview.md)
+
+## Actions
+- [Overview](actions/overview.md)
+
+## Filters
+- [Overview & types](filters/overview.md)
+
+## Dashboards & cards
+- [Overview](dashboards/overview.md)
+
+## Authorization
+- [Authorization adapters (action_policy / Pundit / CanCanCan / custom)](authorization/adapters.md)
+- [action_policy integration](authorization/action-policy.md)
+- [Policies](authorization/policies.md)
+- [Authorization scopes](authorization/scopes.md)
+- [Field-level authorization](authorization/field-authorization.md)
+- [Explicit authorization mode](authorization/explicit-mode.md)
+
+## Customization
+- [Theming with RubyUI](customization/theming-rubyui.md)
+- [JavaScript](customization/javascript.md)
+- [Custom controllers & lifecycle hooks](customization/controllers.md)
+- [Ejecting & customizing](customization/ejecting.md)
+
+## Generators & rake tasks
+- [Overview](generators-and-tasks/overview.md)

data/docs/actions/overview.md

@@ -0,0 +1,112 @@
+# Actions — Overview
+
+Custom actions run code against one or more records (or standalone). Define them in
+`app/ruby_ui_admin/actions` under `RubyUIAdmin::Actions`, then attach them to a resource.
+
+```ruby
+module RubyUIAdmin
+  module Actions
+    class PublishPosts < RubyUIAdmin::BaseAction
+      self.name = "Publish"
+      self.message = "Publish the selected posts?"
+      self.confirm_button_label = "Publish"
+
+      def handle(query:, fields:, current_user:, **)
+        query.each { |post| post.update!(published: true) }
+        succeed "Published #{query.size} post(s)."
+      end
+    end
+  end
+end
+```
+
+Attach to a resource:
+
+```ruby
+def actions
+  action RubyUIAdmin::Actions::PublishPosts
+  action RubyUIAdmin::Actions::ImportPosts, arguments: {source: "csv"}
+end
+```
+
+## Class options
+
+| Option | Purpose |
+|---|---|
+| `self.name =` | Button / page label |
+| `self.message =` | Text (HTML allowed) shown on the confirmation page. Accepts a lambda evaluated with `records`/`record`/`resource`/`current_user`, e.g. `-> { "Publish #{records.size} posts?" }` |
+| `self.confirm_button_label =` / `self.cancel_button_label =` | Button labels |
+| `self.standalone =` | `true` for actions that need no record selection (shown on the index) |
+| `self.no_confirmation =` | Skip the confirmation page (planned) |
+| `self.visible =` | Lambda controlling where the action appears. `view` responds to both `view == :show` and predicates `view.show?` / `view.index?` (also `new?`/`edit?`/`form?`/`display?`), plus `resource`/`record` |
+
+## Form fields
+
+Declare inputs the same way as resource fields; submitted values arrive in `fields`, a
+hash with **indifferent access** (read by symbol or string). A `file`/`files` field turns the
+action form into a multipart upload automatically:
+
+```ruby
+def fields
+  field :reason, as: :text, required: true
+  field :notify, as: :boolean
+  field :csv_file, as: :file
+end
+
+def handle(args)
+  upload = args[:fields][:csv_file]   # symbol or string both work
+  # ...
+end
+```
+
+## The `handle` method
+
+Two signatures are supported:
+
+```ruby
+def handle(query:, fields:, current_user:, resource:, **); end  # keyword style
+def handle(args); end   # args[:records], args[:fields], args[:current_user], args[:resource]
+```
+
+`query` / `args[:records]` is the array of selected records (empty for standalone actions).
+
+## Response helpers
+
+Call these inside `handle`:
+
+- `succeed(text)`, `error(text)`, `inform(text)`, `warn(text)` — flash messages
+- `redirect_to(path)` — a String or a lambda (evaluated in the controller, so engine route
+  helpers like `resources_posts_path` are available)
+
+  Route helpers are also available **directly inside `handle`**: bare `*_path`/`*_url` calls
+  resolve against the engine routes first, then the host app. Use `main_app.*` for host routes
+  and `ruby_ui_admin.*` for engine routes explicitly:
+
+  ```ruby
+  redirect_to resources_posts_path                 # engine route, bare
+  succeed main_app.user_url(record)                 # host route
+  ```
+- `reload` — re-render the originating page (default)
+- `download(content, filename)` — send a file
+- `keep_modal_open` — (planned, for the modal UI)
+
+## Authorization
+
+Actions are gated by the resource policy's `act_on?` rule. If it returns false the action
+is hidden and running it is forbidden.
+
+Action buttons open an inline **modal** with the form (falling back to a dedicated
+confirmation page when JavaScript is disabled — see [JavaScript](../customization/javascript.md)).
+
+## Bulk actions
+
+Non-`standalone` actions become **bulk actions** on the index: a checkbox column appears
+(with a “select all”), and each action runs against the checked rows.
+
+- **With JS**: check rows, click the action — the selected ids are injected into the action
+  modal, which submits them to the action.
+- **Without JS**: the checkbox selection is submitted to the action's confirmation page (via
+  the HTML `form` attribute, so no nested forms), where you confirm and run.
+
+`standalone` actions ignore selection and run on their own; record actions also remain
+available on each record's show view.

data/docs/authorization/action-policy.md

@@ -0,0 +1,72 @@
+# Authorization with action_policy
+
+`ruby_ui_admin` authorizes every request through [action_policy](https://actionpolicy.evilmartians.io)
+by default, using a small set of conventional rule names per resource.
+
+> action_policy is the **default adapter**. The backend is pluggable — Pundit, CanCanCan and custom
+> adapters are also supported via `config.authorization_client`. See
+> [Authorization adapters](adapters.md).
+
+## Policies
+
+Admin policies live in `app/ruby_ui_admin/policies` (`RubyUIAdmin::Policies::*`) and inherit
+`RubyUIAdmin::BasePolicy`:
+
+```ruby
+module RubyUIAdmin
+  module Policies
+    class PostPolicy < RubyUIAdmin::BasePolicy
+      def index? = true
+      def show?  = true
+      def create? = true
+      def update? = true
+      def destroy? = user.admin?
+
+      relation_scope do |relation|
+        next relation if user.admin?
+        relation.where(published: true)
+      end
+    end
+  end
+end
+```
+
+Attach a policy to a resource with `self.authorization_policy = RubyUIAdmin::Policies::PostPolicy`.
+
+## Rule mapping
+
+| Controller action | Rule | Target |
+|---|---|---|
+| index | `index?` | model class |
+| show | `show?` | record |
+| new / create | `create?` | record |
+| edit / update | `update?` | record |
+| destroy | `destroy?` | record |
+
+Custom actions are authorized with `act_on?`. Individual fields can be hidden per user with
+`view_<field>?` (and per-view `index_/show_/edit_<field>?`) — see
+[Field-level authorization](field-authorization.md). Association attach/detach rules are
+added in a later phase.
+
+## Scopes
+
+The index query is filtered through the policy's `relation_scope`, so each user only sees
+the records they're allowed to. If a policy defines no scope, the relation is returned
+unchanged.
+
+## `explicit_authorization`
+
+- `false` (default): a rule the policy doesn't define is **allowed** (falls back to the
+  `manage?` default rule on `BasePolicy`).
+- `true`: undefined rules and missing policies are **denied** — a strict, deny-by-default mode.
+
+```ruby
+RubyUIAdmin.configure { |c| c.explicit_authorization = true }
+```
+
+## Context
+
+`BasePolicy` declares `authorize :user` (from `config.current_user_method`) and
+`authorize :true_user` (from `config.true_user_method`, falling back to the current user) —
+so rules can gate on the real user behind an impersonation. Any other context (e.g. a tenant)
+can be layered in via a custom base policy.