ruby_ui_admin 0.1.0

data/docs/resources/overview.md

@@ -0,0 +1,50 @@
+# Resources — Overview
+
+A resource maps an ActiveRecord model to the admin UI. Resources live in
+`app/ruby_ui_admin/resources` and are namespaced under `RubyUIAdmin::Resources`.
+
+```ruby
+module RubyUIAdmin
+  module Resources
+    class Post < RubyUIAdmin::BaseResource
+      self.title = :title                 # attribute (or lambda) used as the record label
+      self.includes = [:user]             # eager-loaded associations
+      self.model_class = Post             # optional; inferred from the class name
+      self.index_query = -> { query.order(created_at: :desc) }  # optional default scope
+      self.authorization_policy = RubyUIAdmin::Policies::PostPolicy
+
+      def fields
+        field :id, as: :id
+        field :title, as: :text, link_to_record: true, sortable: true
+        field :body, as: :text, only_on: %i[show new edit]
+        field :published, as: :boolean
+        field :user, as: :belongs_to
+        field :created_at, as: :date_time, only_on: %i[index show]
+      end
+    end
+  end
+end
+```
+
+## Class options
+
+| Option | Purpose |
+|---|---|
+| `self.title` | Attribute symbol or lambda used as the record's display label |
+| `self.includes` | Associations to eager-load on the index query |
+| `self.model_class` | Override the inferred model class |
+| `self.index_query` | Lambda returning the default index scope (`query` is available) |
+| `self.authorization_policy` | The action_policy policy class for this resource |
+| `self.visible_on_sidebar` | Hide the resource from the sidebar when `false` |
+| `self.description` | Subtitle shown under the index title |
+| `self.record_selector` | Set `false` to hide the bulk-select checkbox column |
+| `self.row_controls` | `->(record) { ... }` rendering extra per-row controls on the index (helpers: `show_button(record)`, `edit_button(record)`, `create_button`, `control_link`) |
+| `self.row_controls_config` | Layout for the row-controls cell: `{ placement: :left/:right, float: true, show_on_hover: true }` |
+| `self.countless` | Paginate without a `COUNT` query (pagy countless) — for very large tables. Can also be enabled globally via `config.pagination` |
+| `self.remove_scope_all` | Hide the "All" scope tab (use with a default [scope](scopes.md)) |
+
+## Fields
+
+`field :name, as: :type, **options` — see the [field catalog](../fields/overview.md) for all
+types and options, and [tabs & panels](tabs-panels.md) for grouping. Fields can also be
+auto-derived from the schema with `discover_columns` / `discover_associations`.

data/docs/resources/scopes.md

@@ -0,0 +1,54 @@
+# Scopes
+
+Named scopes partition a resource's index into tabs. Define them in
+`app/ruby_ui_admin/scopes` under `RubyUIAdmin::Scopes`, then declare them on the resource.
+
+```ruby
+module RubyUIAdmin
+  module Scopes
+    class Published < RubyUIAdmin::Scopes::BaseScope
+      self.name = "Published"
+      self.description = "Only published posts"          # optional: tooltip on the scope tab
+      self.scope = -> { query.where(published: true) }   # lambda, or...
+      # self.scope = :published                          # ...a Symbol = the model's named scope
+      self.default = true            # optional: applied when no scope is selected
+      # self.visible = -> { user.admin? }  # optional: show the tab conditionally
+    end
+  end
+end
+```
+
+Attach to a resource:
+
+```ruby
+def scopes
+  scope RubyUIAdmin::Scopes::Published, default: true   # mark default at attachment
+  scope RubyUIAdmin::Scopes::Drafts
+end
+
+# Hide the "All" tab (pair with a default scope):
+self.remove_scope_all = true
+```
+
+## Behaviour
+
+- The index renders a tab bar: **All** + one tab per scope.
+- **`self.scope`** is a lambda (receiving `query` — the base relation, already narrowed by the
+  policy scope — and `params`) returning a narrowed relation, **or** a Symbol naming a model
+  scope/class method (e.g. `:published` → `Post.published`).
+- Selecting a tab reloads the index with `?scope=<key>` (the key is the underscored class
+  name, e.g. `Published` → `published`). `?scope=all` clears any scope.
+- **`self.default = true`** (or `scope Klass, default: true` at attachment) makes a scope apply
+  when no `?scope=` param is present; otherwise the index opens on **All**. The attachment option
+  wins over the class setting.
+- **`self.remove_scope_all = true`** on the resource hides the **All** tab (use with a default scope).
+- **`self.visible`** (a lambda) hides a scope's tab when it returns false.
+- Scopes compose with the policy scope and [filters](../filters/overview.md): policy scope →
+  named scope → filters → sorting. The active scope is preserved when applying filters and
+  paginating.
+
+## Generator
+
+```bash
+rails g ruby_ui_admin:scope Published
+```

data/docs/resources/tabs-panels.md

@@ -0,0 +1,65 @@
+# Tabs & Panels
+
+Group fields on the show and form views with `panel`, `tabs` and `tab`.
+
+```ruby
+def fields
+  field :id, as: :id
+
+  panel "Basic info" do
+    field :title, as: :text
+    field :status, as: :badge, options: {"draft" => :warning, "published" => :success}
+  end
+
+  tabs do
+    tab "Content", description: "The main content" do   # description shown in the panel
+      field :body, as: :textarea
+      field :metadata, as: :key_value
+    end
+
+    tab "Relations" do
+      field :user, as: :belongs_to
+      field :comments, as: :has_many
+    end
+  end
+end
+```
+
+## Behaviour
+
+- **`panel(name = nil)`** — renders its fields inside a titled card. The name can also be
+  passed as a keyword (`panel name: "Basic info"`); both forms are equivalent.
+- **`tabs`** — declares a group of tabs; only `tab` calls belong directly inside it.
+- **`tab(name, description: nil)`** — a named section inside `tabs`; can contain fields and
+  panels. A bare field placed directly inside `tabs` (not wrapped in a `tab`) is treated as
+  an implicit single-field tab.
+- Bare top-level fields (not inside a panel/tab) are grouped into a default card.
+- Containers are pruned per view: a tab/panel whose fields are all hidden on a view
+  (via `only_on` / `hide_on`) isn't rendered there.
+- The **index** view ignores grouping and shows the flattened, visible fields as columns.
+
+### Redundant-label de-duplication
+
+To avoid showing the same word twice, two labels are suppressed automatically:
+
+- A **tab `description:` that equals the tab name** isn't rendered (the tab bar already shows
+  the name).
+- A **panel `name:` that equals the name of the tab containing it** isn't rendered (so a
+  `tab "Permissions" { panel name: "Permissions" { … } }` shows the title once, not twice).
+
+Distinct descriptions and panel names still render normally.
+
+## Tab switching (JavaScript)
+
+Tabs render as **stacked, titled cards without JavaScript**. With the bundled JS, the tab bar
+is revealed, the redundant per-panel headings are hidden, and clicking a tab shows only that
+panel (no server round-trip). See [JavaScript](../customization/javascript.md#tabs).
+
+### Lazy tab loading
+
+With `config.lazy_tabs = true`, only the **first (active) tab** of each group renders up front;
+the others fetch their content the first time they're opened (showing a spinner meanwhile),
+so their fields and association queries only run on demand. This is handy for show pages with
+several heavy association tabs. Without JS the active tab still renders and the deferred tabs
+show a "requires JavaScript" notice. See
+[JavaScript › Lazy tabs](../customization/javascript.md#lazy-tabs).

data/lib/generators/ruby_ui_admin/action/action_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class ActionGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:action"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin action."
+
+      class_option :standalone, type: :boolean, default: false,
+        desc: "Action does not require selected records"
+
+      def create_action
+        template "action.rb.tt", File.join("app/ruby_ui_admin/actions", "#{file_path}.rb")
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/action/templates/action.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Actions
+    class <%= class_name %> < RubyUIAdmin::BaseAction
+      self.name = "<%= human_name %>"
+<% if options[:standalone] -%>
+      self.standalone = true
+<% end -%>
+
+      def fields
+        # field :note, as: :text
+      end
+
+      def handle(query:, fields:, current_user:, **)
+        query.each do |record|
+          # do something with each record
+        end
+
+        succeed "Done!"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/assets/assets_generator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyUIAdmin
+  module Generators
+    # Wires the admin's Stimulus controllers into the host app, tailored to its JS setup. The gem
+    # ships them flat (e.g. `rua--bulk-select_controller.js`) plus an `index.js` that imports and
+    # registers every one under the identifier its markup expects (`rua--bulk-select`,
+    # `ruby-ui--toaster`, …).
+    #
+    #   rails g ruby_ui_admin:assets
+    #
+    # - **Bundler (esbuild/jsbundling/vite):** copies the whole directory verbatim into
+    #   `app/javascript/ruby_ui_admin/` (a sibling of `controllers/`, so the host's
+    #   `eagerLoadControllersFrom("controllers", …)` doesn't re-register them under bogus names).
+    #   The bundler inlines `index.js`'s relative imports, so you just `import "./ruby_ui_admin"`.
+    # - **Importmap + Propshaft:** does NOT copy. Copied files get content-digested, and `index.js`'s
+    #   relative `./x.js` imports resolve to the *undigested* URLs Propshaft won't serve → 404. Instead
+    #   it pins the copy the engine already serves **undigested** via Rack::Static at
+    #   `<ASSETS_MOUNT_PATH>/controllers/index.js`, where relative imports work and `@hotwired/stimulus`
+    #   / `@hotwired/turbo` resolve through the host's own import map.
+    #
+    # Either way, no `stimulus:manifest:update` — the shipped `index.js` does the registration.
+    class AssetsGenerator < Rails::Generators::Base
+      namespace "ruby_ui_admin:assets"
+      source_root RubyUIAdmin::Engine.root.to_s
+
+      desc "Sets up the admin's Stimulus controllers (copies for bundlers; pins the served " \
+           "entrypoint for importmap)."
+
+      DEST = "app/javascript/ruby_ui_admin"
+      # The engine serves its controllers undigested here (see Engine's Rack::Static mount).
+      SERVED_INDEX = "#{RubyUIAdmin::ASSETS_MOUNT_PATH}/controllers/index.js"
+
+      def install
+        if importmap?
+          print_importmap_wiring
+        else
+          directory "public/ruby-ui-admin-assets/controllers", DEST
+          print_bundler_wiring
+        end
+      end
+
+      private
+
+      def print_importmap_wiring
+        say "\nImportmap detected — nothing copied (copied files get digested and index.js's", :green
+        say "relative imports would 404 under Propshaft). The engine serves them undigested; pin that:", :green
+        say "\n  # config/importmap.rb"
+        say %(  pin "ruby_ui_admin", to: "#{SERVED_INDEX}"), :yellow
+        say "\n  // app/javascript/application.js"
+        say %(  import "ruby_ui_admin"), :yellow
+        say "\n(Stimulus + Turbo must be pinned too — stimulus-rails/turbo-rails do that already.)"
+      end
+
+      def print_bundler_wiring
+        say "\nCopied the admin's Stimulus controllers to #{DEST}/.", :green
+        say "Add this import to your JavaScript entrypoint so they're registered:", :yellow
+        say "\n  // app/javascript/application.js"
+        say %(  import "./ruby_ui_admin"), :yellow
+        say "\nThen rebuild your JS bundle. No stimulus:manifest:update needed — the copied"
+        say "index.js registers every controller under the right identifier."
+      end
+
+      def importmap?
+        File.exist?(File.join(destination_root, "config/importmap.rb"))
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/card/card_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class CardGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:card"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin card. Use --type metric|chart|partial."
+
+      class_option :type, type: :string, default: "metric",
+        desc: "Card type: metric, chart or partial"
+
+      def create_card
+        template "#{card_type}_card.rb.tt", File.join("app/ruby_ui_admin/cards", "#{file_path}.rb")
+      end
+
+      private
+
+      def card_type
+        type = options[:type].to_s
+        %w[metric chart partial].include?(type) ? type : "metric"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/card/templates/chart_card.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Cards
+    class <%= class_name %> < RubyUIAdmin::Cards::ChartCard
+      self.label = "<%= human_name %>"
+
+      def query
+        # e.g. Post.group(:status).count
+        {}
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/card/templates/metric_card.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Cards
+    class <%= class_name %> < RubyUIAdmin::Cards::MetricCard
+      self.label = "<%= human_name %>"
+
+      def query
+        # e.g. User.count
+        0
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/card/templates/partial_card.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Cards
+    class <%= class_name %> < RubyUIAdmin::Cards::PartialCard
+      self.label = "<%= human_name %>"
+
+      def query
+        "<p class='text-sm text-muted-foreground'>Hello from <%= human_name %>.</p>"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/components/components_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyUIAdmin
+  module Generators
+    # Generates the RubyUI components the admin's views render, by shelling out to
+    # `ruby_ui:component` once per component (RubyUI's generator takes one at a time). Without these,
+    # the admin references `RubyUI::*` constants your app hasn't generated and blows up with a
+    # NameError — this automates installing exactly the set it needs.
+    #
+    #   rails g ruby_ui_admin:components
+    #
+    # Safe to re-run: passes `--skip`, so components you already have are left untouched.
+    class ComponentsGenerator < Rails::Generators::Base
+      namespace "ruby_ui_admin:components"
+
+      desc "Generates the RubyUI components the admin renders (via ruby_ui:component, one per command)."
+
+      # The RubyUI components the admin's views reference. These are RubyUI *group* names (what you
+      # pass to `ruby_ui:component`), not individual classes:
+      #   - Typography provides InlineLink (there is no standalone `InlineLink` component).
+      #   - Card/Table/Sidebar/Combobox each bring their whole family (CardHeader, TableRow, …).
+      #   - Sheet isn't rendered directly — it's a dependency of RubyUI's mobile Sidebar.
+      # Kept in sync with the engine by test/generators/generators_test.rb.
+      COMPONENTS = %w[
+        Card Badge Button Checkbox Combobox Typography Link Input Textarea Table Sidebar Sheet
+      ].freeze
+
+      def generate_components
+        say "Generating the #{COMPONENTS.size} RubyUI components the admin needs " \
+            "(one ruby_ui:component call each)…", :green
+
+        COMPONENTS.each do |component|
+          run "bin/rails generate ruby_ui:component #{component} --skip"
+        end
+
+        say "\nDone. Re-run any time — existing components are skipped, not overwritten.", :green
+        say "If these fail, install RubyUI first (see docs/getting-started/installation.md).", :yellow
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/controller/controller_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    # Generates a per-resource controller so you can override CRUD lifecycle hooks.
+    #   rails g ruby_ui_admin:controller Buyer
+    class ControllerGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:controller"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a per-resource controller (subclass of ResourcesController)."
+
+      def create_controller
+        template "controller.rb.tt", File.join("app/controllers/ruby_ui_admin", "#{plural_file_name}_controller.rb")
+      end
+
+      private
+
+      def plural_file_name
+        file_name.pluralize
+      end
+
+      def controller_class_name
+        "#{class_name.pluralize}Controller"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/controller/templates/controller.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  class <%= controller_class_name %> < RubyUIAdmin::ResourcesController
+    # Override CRUD lifecycle hooks as needed. Defaults live in ResourcesController.
+    #
+    # def after_create_path = resources_index_path
+    #
+    # def create_success_action
+    #   super # or: redirect_to after_create_path, notice: "Created!"
+    # end
+    #
+    # def update_success_action
+    #   redirect_to after_update_path, notice: "Updated!"
+    # end
+    #
+    # def destroy_fail_action
+    #   redirect_to resources_index_path, alert: "Could not delete."
+    # end
+    #
+    # You can also override the CRUD actions themselves (create/update/destroy)
+    # and call `super`, or reimplement them.
+  end
+end

data/lib/generators/ruby_ui_admin/dashboard/dashboard_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class DashboardGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:dashboard"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin dashboard."
+
+      def create_dashboard
+        template "dashboard.rb.tt", File.join("app/ruby_ui_admin/dashboards", "#{file_path}.rb")
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/dashboard/templates/dashboard.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Dashboards
+    class <%= class_name %> < RubyUIAdmin::BaseDashboard
+      self.name = "<%= human_name %>"
+      # self.grid_columns = 3
+
+      def cards
+        # card RubyUIAdmin::Cards::SomeMetric
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/eject/eject_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RubyUIAdmin
+  module Generators
+    # Copies an engine controller / view component / UI primitive into the host app at
+    # the same path. The host's copy shadows the engine's (Zeitwerk loads the app's file
+    # first), so you can customize it freely.
+    #
+    #   rails g ruby_ui_admin:eject --view index
+    #   rails g ruby_ui_admin:eject --view layout
+    #   rails g ruby_ui_admin:eject --controller resources
+    #   rails g ruby_ui_admin:eject --ui button
+    class EjectGenerator < Rails::Generators::Base
+      namespace "ruby_ui_admin:eject"
+      source_root RubyUIAdmin::Engine.root.to_s
+
+      desc "Copies an engine file into your app so you can customize it."
+
+      class_option :controller, type: :string, desc: "Controller to eject (e.g. resources, application, actions)"
+      class_option :view, type: :string, desc: "View component to eject (e.g. index, show, form, layout)"
+      class_option :ui, type: :string, desc: "UI primitive to eject (e.g. button, card, table, badge)"
+
+      def eject
+        path = resolve_path
+        return if path.nil?
+
+        unless File.exist?(File.join(self.class.source_root, path))
+          say "RubyUI Admin: nothing to eject at #{path}", :red
+          return
+        end
+
+        copy_file path, path
+        say "\nEjected #{path}. Edit it in your app to customize.", :green
+      end
+
+      private
+
+      def resolve_path
+        if options[:controller]
+          "app/controllers/ruby_ui_admin/#{options[:controller]}_controller.rb"
+        elsif options[:view]
+          file = (options[:view] == "layout") ? "base" : options[:view]
+          "app/components/ruby_ui_admin/views/#{file}.rb"
+        elsif options[:ui]
+          "app/components/ruby_ui_admin/ui/#{options[:ui]}.rb"
+        else
+          say "Specify what to eject: --controller NAME, --view NAME (or layout), or --ui NAME", :yellow
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/filter/filter_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module RubyUIAdmin
+  module Generators
+    class FilterGenerator < Rails::Generators::NamedBase
+      namespace "ruby_ui_admin:filter"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Generates a RubyUI Admin filter. Use --type text|select|boolean."
+
+      class_option :type, type: :string, default: "text",
+        desc: "Filter type: text, select or boolean"
+
+      def create_filter
+        template "#{filter_type}_filter.rb.tt", File.join("app/ruby_ui_admin/filters", "#{file_path}_filter.rb")
+      end
+
+      private
+
+      def filter_type
+        type = options[:type].to_s
+        %w[text select boolean].include?(type) ? type : "text"
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/filter/templates/boolean_filter.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Filters
+    class <%= class_name %>Filter < RubyUIAdmin::Filters::BooleanFilter
+      self.name = "<%= human_name %>"
+
+      def apply(request, query, value)
+        query.where(<%= singular_name %>: value == "true")
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/filter/templates/select_filter.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Filters
+    class <%= class_name %>Filter < RubyUIAdmin::Filters::SelectFilter
+      self.name = "<%= human_name %>"
+
+      def apply(request, query, value)
+        query.where(<%= singular_name %>: value)
+      end
+
+      def options
+        {
+          # "value" => "Label"
+        }
+      end
+    end
+  end
+end

data/lib/generators/ruby_ui_admin/filter/templates/text_filter.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyUIAdmin
+  module Filters
+    class <%= class_name %>Filter < RubyUIAdmin::Filters::TextFilter
+      self.name = "<%= human_name %>"
+
+      def apply(request, query, value)
+        query.where("<%= singular_name %> LIKE ?", "%#{value}%")
+      end
+    end
+  end
+end