ruby_ui_admin 0.1.0

data/docs/getting-started/installation.md

@@ -0,0 +1,201 @@
+# Installation
+
+> **The admin renders *your app's* RubyUI components and uses *your app's* assets.** So setup is
+> mostly about pointing the admin at your existing RubyUI + Tailwind + JS bundler. If your app
+> already uses RubyUI, most of this is already in place.
+
+## 1. Add the gems
+
+```ruby
+# Gemfile
+gem "ruby_ui_admin"
+
+# Prerequisite — the UI is built from your app's RubyUI components.
+gem "ruby_ui", github: "ruby-ui/ruby_ui", require: false
+```
+
+```bash
+bundle install
+```
+
+`ruby_ui_admin` depends on `phlex-rails`, `tailwind_merge`, `action_policy`, `pagy` and
+`turbo-rails` (Bundler installs them automatically). It also expects a **Tailwind build** and a
+**JavaScript bundler or importmap** in your app — the same setup RubyUI itself needs.
+
+## 2. Install RubyUI and generate its components
+
+If your app doesn't already use RubyUI, install it and generate the components the admin uses —
+at minimum: `card`, `badge`, `button`, `link`, `typography` (provides `InlineLink`), `checkbox`,
+`input`, `textarea`, `table`, `sidebar`, `sheet`, `combobox`.
+
+> **Run `phlex:install` first.** RubyUI's installer only runs `phlex:install` (which creates
+> `app/components/base.rb`) when `phlex-rails` isn't already in the bundle. Because `ruby_ui_admin`
+> depends on `phlex-rails`, it skips that step and then aborts when `app/components/base.rb` is
+> missing — leaving `RubyUI::Base` ungenerated (and `tw-animate-css` uninstalled), which breaks boot
+> when you generate components. Running `phlex:install` yourself first avoids the whole chain.
+
+```bash
+bin/rails generate phlex:install      # creates app/components/base.rb (see note above)
+bin/rails generate ruby_ui:install
+```
+
+> `ruby_ui:install` **overwrites** your Tailwind entry CSS behind an interactive prompt — run it on
+> its own (not pasted inside a larger block) and answer `Y`, then re-add your customizations (e.g. the
+> `@source` line below). On **Tailwind v4** (tailwindcss-rails 3+, the current default) that file is
+> `app/assets/tailwind/application.css`; older setups use
+> `app/assets/stylesheets/application.tailwind.css`. It also installs `tw-animate-css`;
+> if a later CSS build errors on it, add it manually (`yarn add tw-animate-css` / importmap pin) and
+> ensure your CSS imports it.
+
+Then generate the components the admin renders. The gem knows which ones it needs, so let it drive
+RubyUI's generator for you (safe to re-run — existing components are skipped):
+
+```bash
+bin/rails generate ruby_ui_admin:components
+```
+
+<details><summary>What it runs (and why not one command)</summary>
+
+RubyUI's generator takes **one component per command**, and **`InlineLink` is part of the
+`Typography` group** (a bare `ruby_ui:component InlineLink` fails silently and the admin's index
+later breaks, since it renders `RubyUI::InlineLink`). The generator loops over exactly the set the
+admin uses:
+
+```bash
+for c in Card Badge Button Checkbox Combobox Typography Link Input Textarea Table Sidebar Sheet; do
+  bin/rails generate ruby_ui:component $c --skip
+done
+# (or `bin/rails generate ruby_ui:component all` to generate everything)
+```
+</details>
+
+This drops the components into `app/components/ruby_ui/*` (as `RubyUI::*`) and copies RubyUI's
+Stimulus controllers into `app/javascript/controllers/ruby_ui/*`. **You own these files.**
+
+## 3. Wire the assets
+
+The admin doesn't ship CSS/JS — it reuses yours.
+
+**a. Tailwind** — your build must generate the utility classes the admin's views use. Rather than
+`@source`-ing the gem's `.rb` files (their absolute path differs between dev/CI/deploy, so it can't
+be committed), extract the class inventory into your **own** app tree and source that:
+
+```bash
+bin/rails ruby_ui_admin:tailwind_source
+```
+
+It writes `app/assets/tailwind/ruby_ui_admin_classes.html` (the classes scanned from the admin's
+views) and prints the line to add to your Tailwind entry CSS:
+
+```css
+/* Tailwind v4: app/assets/tailwind/application.css  (v3: app/assets/stylesheets/application.tailwind.css) */
+@source "./ruby_ui_admin_classes.html";
+```
+
+**Commit the generated file** — that stable, relative path works in every environment. **Re-run the
+task after upgrading the gem** so new classes are picked up. Also make sure your RubyUI theme defines
+the `success` / `warning` design tokens (the admin's badges/toasts use them — RubyUI ships them).
+
+**b. Stimulus controllers** — the admin needs two sets registered in your Stimulus app:
+
+1. **The admin's own `rua--*` controllers** (`tabs`, `dialog`, `bulk-select`, `row-link`,
+   `confirm`).
+2. **`ruby-ui--toaster` + `ruby-ui--toast`** — the admin renders RubyUI's **Toast** for flash
+   messages **even if your app doesn't use RubyUI Toast**, so you likely won't have these from
+   step 2. (The other `ruby-ui--*` it uses — combobox, sheet, sidebar — *do* come from your own
+   RubyUI in step 2.)
+
+The gem ships both sets, flat, under `public/ruby-ui-admin-assets/controllers/` (the toaster
+controller is patched for server-rendered flash toasts — use the gem's copy), alongside an
+`index.js` that imports and **registers each one under the identifier its markup expects**. Run the
+generator — it does the right thing for your JS setup and prints the **one line** you add:
+
+```bash
+bin/rails generate ruby_ui_admin:assets
+```
+
+**Bundler (esbuild / jsbundling / vite).** It copies the directory to `app/javascript/ruby_ui_admin/`
+(a sibling of `controllers/`, so `eagerLoadControllersFrom("controllers", …)` doesn't re-register
+them under bogus names). The bundler inlines `index.js`'s relative imports, so:
+
+```js
+// app/javascript/application.js
+import "./ruby_ui_admin"
+```
+
+**Importmap + Propshaft.** It does **not** copy — copied files get content-digested, and `index.js`'s
+relative `./x.js` imports would then resolve to undigested URLs Propshaft won't serve (404). Instead
+it pins the copy the engine already serves **undigested** (via Rack::Static), where relative imports
+work and `@hotwired/stimulus`/`@hotwired/turbo` resolve through your own import map:
+
+```ruby
+# config/importmap.rb
+pin "ruby_ui_admin", to: "/ruby-ui-admin-assets/controllers/index.js"
+# then in app/javascript/application.js:  import "ruby_ui_admin"
+```
+
+Either way that single import registers every controller (`rua--*`, `ruby-ui--toaster`/`ruby-ui--toast`,
+plus combobox/sheet/sidebar) — **no `stimulus:manifest:update`**. Rebuild your JS (bundler) afterwards.
+Don't hand-translate the files into `controllers/rua/…` folders — the manifest would derive the wrong
+identifiers.
+
+> If flash toasts don't appear after an action, it's almost always the `ruby-ui--toaster` /
+> `ruby-ui--toast` controllers missing from your bundle — re-run the generator and re-add the import.
+
+RubyUI's combobox/popover controllers depend on `@floating-ui/dom` — already present if you use
+RubyUI's combobox.
+
+## 4. Mount the engine
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount_ruby_ui_admin at: "/admin"
+end
+```
+
+Draws a RESTful route set for every resource you define (`resources_posts_path`,
+`new_resources_post_path`, `edit_resources_post_path`, …).
+
+## 5. Configure
+
+```ruby
+# config/initializers/ruby_ui_admin.rb
+RubyUIAdmin.configure do |config|
+  config.app_name = "My Admin"
+  config.per_page = 24
+
+  # Resolve the signed-in admin (the block runs in the controller context).
+  config.current_user_method { current_user }
+
+  # Optional gate run before every admin request.
+  config.authenticate_with { redirect_to main_app.login_path unless current_user&.admin? }
+
+  config.authorization_client  = :action_policy
+  config.explicit_authorization = false
+
+  # REQUIRED — the admin layout's <head>. Point it at your app's compiled CSS + JS (the same
+  # tags your application layout uses). Evaluated in the Rails view context.
+  config.head_assets = lambda do
+    safe_join([
+      stylesheet_link_tag("application", "data-turbo-track": "reload"),
+      # importmap host: use `javascript_importmap_tags` instead of the line below.
+      javascript_include_tag("application", "data-turbo-track": "reload", defer: true)
+    ])
+  end
+end
+```
+
+> Without `config.head_assets`, the admin pages render with **no styling and no JavaScript**.
+
+## 6. Define a resource
+
+Create `app/ruby_ui_admin/resources/post.rb` (see [Resources → Overview](../resources/overview.md)).
+
+---
+
+`bin/rails generate ruby_ui_admin:install` scaffolds steps **4–5** (the initializer + mount), and
+`ruby_ui_admin:assets` copies the Stimulus controllers from step **3**. The rest of steps **2–3**
+(RubyUI components + Tailwind `@source`) depend on your app's bundler/Tailwind setup and are
+manual — see [Theming with RubyUI](../customization/theming-rubyui.md) and
+[JavaScript](../customization/javascript.md).

data/docs/getting-started/internationalization.md

@@ -0,0 +1,50 @@
+# Internationalization (i18n)
+
+The admin is localized through Rails i18n. Each admin request runs inside
+`I18n.with_locale(config.locale)` when a locale is configured.
+
+```ruby
+RubyUIAdmin.configure do |config|
+  config.locale = :"pt-BR"
+  # or resolve per request from your controller, e.g. config.locale = I18n.locale
+end
+```
+
+There are two layers of translation:
+
+## 1. Framework strings (bundled)
+
+Built-in UI text — buttons, table headers, the empty state, pagination, boolean badges — is
+translated under the `ruby_ui_admin.*` namespace. The gem ships **English** and
+**Brazilian Portuguese** out of the box, auto-loaded into `I18n`.
+
+Copy them into your app to edit or add locales:
+
+```bash
+rails g ruby_ui_admin:locales   # -> config/locales/ruby_ui_admin.en.yml, ruby_ui_admin.pt-BR.yml
+```
+
+Add another language by creating `config/locales/ruby_ui_admin.<locale>.yml` with the same keys.
+
+## 2. Domain labels (your app's translations)
+
+Resource and field labels use standard Rails i18n, so they read from **your** locale files:
+
+- **Field labels** use `Model.human_attribute_name`, i.e. `activerecord.attributes.<model>.<attr>`.
+- They fall back to a humanized name when there's no translation.
+
+```yaml
+# config/locales/pt-BR.yml
+"pt-BR":
+  activerecord:
+    attributes:
+      post:
+        title: "Título"
+        published: "Publicado"
+```
+
+With the locale set to `pt-BR`, the Post resource's `title` field renders as “Título”.
+
+> Action names are plain strings you set with `self.name`; localize them by setting the name
+> from a translation in your action (e.g. `self.name = I18n.t("...")` is evaluated at load —
+> prefer a fixed string or your own lookup if you need per-request locales).

data/docs/getting-started/practical-guide.md

@@ -0,0 +1,310 @@
+# Practical guide: a working admin from scratch
+
+This is a copy‑paste walkthrough that takes a brand‑new Rails app to a functional admin with
+two associated models, configured resources, and a couple of filters. It uses a small
+**Bookshelf** domain: an `Author` that `has_many :books`.
+
+The demo skips authentication and authorization so it "just works" — see the
+[Authentication](authentication.md) and [Authorization](../authorization/action-policy.md)
+docs to wire those up for real.
+
+---
+
+## 1. Create the Rails app
+
+The admin renders RubyUI (Phlex) components styled with Tailwind, so start the app with a
+Tailwind build and a JS bundler:
+
+```bash
+rails new bookshelf --css tailwind --javascript esbuild
+cd bookshelf
+```
+
+## 2. Add the gem
+
+```ruby
+# Gemfile
+gem "ruby_ui_admin"
+
+# The admin's UI is built from your app's RubyUI components.
+gem "ruby_ui", require: false
+
+# Optional: renders the gem's docs at /admin/docs in development (see step 9).
+group :development do
+  gem "kramdown"
+  gem "kramdown-parser-gfm"
+end
+```
+
+> Until it's published to RubyGems, point at a local checkout or Git instead, e.g.
+> `gem "ruby_ui_admin", path: "../ruby_ui_admin"` or `gem "ruby_ui_admin", github: "you/ruby_ui_admin"`.
+
+```bash
+bundle install
+```
+
+Generate RubyUI and the components the admin uses (they land in `app/components/ruby_ui/*` and
+their Stimulus controllers in `app/javascript/controllers/ruby_ui/*` — you own them).
+
+> **Run `phlex:install` first.** RubyUI's installer only runs `phlex:install` (which creates
+> `app/components/base.rb`) when `phlex-rails` isn't already in the bundle. Because `ruby_ui_admin`
+> depends on `phlex-rails`, the installer skips that step, then aborts when it can't find
+> `app/components/base.rb` — leaving `RubyUI::Base` ungenerated and breaking boot. Running
+> `phlex:install` yourself first sidesteps it.
+
+```bash
+bin/rails generate phlex:install      # creates app/components/base.rb (see note above)
+bin/rails generate ruby_ui:install
+```
+
+> RubyUI's `install` overwrites your Tailwind entry CSS with an **interactive prompt** — run it on
+> its own (don't paste a whole block at once) and answer `Y`, then re-add any customizations. On
+> Tailwind v4 (the current default) that file is `app/assets/tailwind/application.css`; older setups
+> use `app/assets/stylesheets/application.tailwind.css`. If the CSS build later errors on
+> `tw-animate-css`, install it (`yarn add tw-animate-css` or pin it for importmap) and make sure your
+> CSS imports it — RubyUI's installer adds this for you when it completes successfully.
+
+Then generate the components the admin uses. The gem knows the set, so let it drive RubyUI's
+generator (safe to re-run — existing components are skipped):
+
+```bash
+bin/rails generate ruby_ui_admin:components
+```
+
+> Under the hood it loops over the set the admin renders, one per command (RubyUI's generator takes
+> one at a time), using the `Typography` group for `InlineLink` — a bare `ruby_ui:component
+> InlineLink` fails silently and the index would break later. You can also run
+> `bin/rails generate ruby_ui:component all` to generate everything.
+
+## 3. Generate two scaffolds with an association
+
+`author:references` makes `Book` belong to an `Author` (adds the foreign key and the
+`belongs_to :author`).
+
+```bash
+bin/rails generate scaffold Author name:string email:string
+bin/rails generate scaffold Book title:string published:boolean author:references
+bin/rails db:migrate
+```
+
+## 4. Complete the association
+
+The scaffold added `belongs_to :author` to `Book`. Add the other side to `Author`:
+
+```ruby
+# app/models/author.rb
+class Author < ApplicationRecord
+  has_many :books, dependent: :destroy
+
+  def to_label = name   # used as the record's display label in the admin
+end
+```
+
+```ruby
+# app/models/book.rb
+class Book < ApplicationRecord
+  belongs_to :author
+
+  def to_label = title
+end
+```
+
+## 5. Mount and configure the admin
+
+Run the install generator — it creates the initializer and mounts the engine at `/admin`:
+
+```bash
+bin/rails generate ruby_ui_admin:install
+```
+
+Then replace the generated initializer with this demo configuration (no auth, no policies):
+
+```ruby
+# config/initializers/ruby_ui_admin.rb
+RubyUIAdmin.configure do |config|
+  config.app_name  = "Bookshelf Admin"
+  config.root_path = "/admin"
+  config.per_page  = 20
+
+  # This demo has no authentication. Returning nil and disabling authorization lets the
+  # admin run without a current_user or any policies. In a real app, wire current_user_method
+  # to your auth (e.g. Devise) and set authorization_client = :action_policy + add policies.
+  config.current_user_method { nil }
+  config.authorization_client = nil
+
+  # REQUIRED — point the admin's <head> at your app's compiled CSS + JS (esbuild + Tailwind here).
+  config.head_assets = lambda do
+    safe_join([
+      stylesheet_link_tag("application", "data-turbo-track": "reload"),
+      javascript_include_tag("application", "data-turbo-track": "reload", defer: true)
+    ])
+  end
+end
+```
+
+Two more bits of wiring so the admin is styled and interactive (see
+[Installation › Wire the assets](installation.md#3-wire-the-assets)):
+
+- **Tailwind** — extract the admin's class inventory into your app and source it (the gem path
+  varies per environment, so don't hardcode it). Commit the generated file; re-run on gem upgrade:
+  ```bash
+  bin/rails ruby_ui_admin:tailwind_source   # writes app/assets/tailwind/ruby_ui_admin_classes.html
+  ```
+  ```css
+  /* Tailwind v4: app/assets/tailwind/application.css (v3: app/assets/stylesheets/application.tailwind.css) */
+  @source "./ruby_ui_admin_classes.html";
+  ```
+- **Stimulus** — copy the admin's controllers in with the generator, then add the one import it
+  prints to `app/javascript/application.js` (for esbuild here, that's `import "./ruby_ui_admin"`):
+  ```bash
+  bin/rails generate ruby_ui_admin:assets
+  ```
+  It brings the admin's own `rua--*` controllers **and** `ruby-ui--toaster`/`ruby-ui--toast` (the
+  admin uses RubyUI Toast for flash even though the component list above doesn't include it), all
+  registered under the right identifiers — no `stimulus:manifest:update` needed. Rebuild afterwards.
+  (On **Importmap + Propshaft** the generator pins the engine-served entrypoint instead of copying —
+  see [Installation › Wire the assets](installation.md#3-wire-the-assets).)
+
+The generator also added this line to your routes (mount it manually if you skipped the
+generator):
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount_ruby_ui_admin at: "/admin"
+
+  # ...your scaffolded routes (resources :authors, :books) stay as they are
+end
+```
+
+## 6. Define the resources
+
+Resources live in `app/ruby_ui_admin/resources/` and are auto‑discovered — no registration
+needed. The class name maps to the model (`Author` → `Author`).
+
+```ruby
+# app/ruby_ui_admin/resources/author.rb
+module RubyUIAdmin
+  module Resources
+    class Author < RubyUIAdmin::BaseResource
+      self.title = :name          # display label for an Author record
+
+      def fields
+        field :id,    as: :id
+        field :name,  as: :text, link_to_record: true, sortable: true
+        field :email, as: :text
+        field :books, as: :has_many   # listed on the Author's show page
+      end
+    end
+  end
+end
+```
+
+```ruby
+# app/ruby_ui_admin/resources/book.rb
+module RubyUIAdmin
+  module Resources
+    class Book < RubyUIAdmin::BaseResource
+      self.title    = :title
+      self.includes = [:author]   # eager-load to avoid N+1 on the index
+
+      def filters
+        filter RubyUIAdmin::Filters::PublishedFilter
+        filter RubyUIAdmin::Filters::AuthorFilter
+      end
+
+      def fields
+        field :title,      as: :text, link_to_record: true, sortable: true
+        field :published,  as: :boolean
+        field :author,     as: :belongs_to            # dropdown on forms, link on show/index
+        field :created_at, as: :date_time, only_on: %i[index show]
+      end
+    end
+  end
+end
+```
+
+## 7. Add a couple of filters
+
+Filters live in `app/ruby_ui_admin/filters/` and render above the index table.
+
+```ruby
+# app/ruby_ui_admin/filters/published_filter.rb
+module RubyUIAdmin
+  module Filters
+    class PublishedFilter < RubyUIAdmin::Filters::BooleanFilter
+      self.name = "Published"
+
+      def apply(_request, query, value)
+        query.where(published: value == "true")
+      end
+    end
+  end
+end
+```
+
+```ruby
+# app/ruby_ui_admin/filters/author_filter.rb
+module RubyUIAdmin
+  module Filters
+    class AuthorFilter < RubyUIAdmin::Filters::SelectFilter
+      self.name = "Author"
+
+      # options is { value => label }.
+      def options
+        ::Author.order(:name).pluck(:id, :name).to_h
+      end
+
+      def apply(_request, query, value)
+        query.where(author_id: value)
+      end
+    end
+  end
+end
+```
+
+## 8. Add some data (optional)
+
+So the admin isn't empty:
+
+```ruby
+# db/seeds.rb
+rowling = Author.create!(name: "J. K. Rowling", email: "jk@example.com")
+tolkien = Author.create!(name: "J. R. R. Tolkien", email: "jrr@example.com")
+
+rowling.books.create!(title: "Harry Potter", published: true)
+tolkien.books.create!(title: "The Hobbit", published: true)
+tolkien.books.create!(title: "Unfinished Tales", published: false)
+```
+
+```bash
+bin/rails db:seed
+```
+
+## 9. Run it
+
+Use `bin/dev` (not `bin/rails server`) so the esbuild + Tailwind watchers build your assets:
+
+```bash
+bin/dev
+```
+
+Open <http://localhost:3000/admin>. You'll get a styled admin with
+**Authors** and **Books** in the sidebar. On the Books index you'll see the **Published** and
+**Author** filters; opening a Book shows its author as a link, and an Author shows its books.
+
+> **Read the docs inside the app.** With the `kramdown` gems from step 2 installed, the admin serves
+> this documentation at <http://localhost:3000/admin/docs> (development only, by default). Without
+> those gems the page shows a notice telling you to add them. See
+> [Configuration › In-app docs browser](configuration.md#in-app-docs-browser).
+
+---
+
+## Where to go next
+
+- Group fields with [tabs & panels](../resources/tabs-panels.md), add [scopes](../resources/scopes.md)
+  and [index customization](../resources/index-customization.md).
+- Add [custom actions](../actions/overview.md) (e.g. "Publish selected books").
+- Wire real [authentication](authentication.md) and [authorization](../authorization/action-policy.md)
+  (set `authorization_client = :action_policy` and add policies).
+- Browse the full [field catalog](../fields/overview.md) and [filter types](../filters/overview.md).

data/docs/resources/associations.md

@@ -0,0 +1,66 @@
+# Associations
+
+Declare associations as fields. They render as links to the related records.
+
+```ruby
+def fields
+  field :user, as: :belongs_to                  # parent record
+  field :profile, as: :has_one
+  field :comments, as: :has_many
+  field :tags, as: :has_and_belongs_to_many
+end
+```
+
+## Display
+
+| Type | Renders |
+|---|---|
+| `belongs_to` | a link to the parent record's show page; an editable select on forms |
+| `has_one` | a link to the associated record's show page |
+| `has_many` / `has_and_belongs_to_many` | a full-width **table** of the related records (capped, with “+N more”) |
+
+Links resolve through the related model's registered resource (so a `Comment` row links to
+`/admin/comments/:id`). If no resource is registered for the related model, the label is shown
+without a link.
+
+### Collection tables (`has_many` / `has_and_belongs_to_many`)
+
+Collection associations render as a RubyUI table whose **columns are the related resource's
+index fields** (so a `comments` association shows the same columns as the Comments index), with
+each row linking to the record's show page. On the show view the table spans the full width,
+with the association name and description above it.
+
+Limit and order the columns with the `fields:` option — a list of field ids from the related
+resource:
+
+```ruby
+field :suppliers, as: :has_many, fields: %i[name identifier state buyer]
+```
+
+Without `fields:`, all of the related resource's index columns are shown. If the related model
+has no registered resource, the table falls back to a single column of record links.
+
+By default `has_one`/`has_many`/`has_and_belongs_to_many` appear **only on the show view**
+(they're hidden on index and forms); `belongs_to` appears everywhere. Override with
+`only_on:` / `hide_on:` like any field.
+
+Give related models a `to_label` (or `name`/`title`) for friendly link text; otherwise a
+`"<Model> #<id>"` label is used.
+
+## Authorization
+
+Associations are gated like any field — define `view_<association>?` (or per-view
+`show_<association>?`) on the resource policy:
+
+```ruby
+class PostPolicy < RubyUIAdmin::BasePolicy
+  def view_comments? = user.admin?   # hide the comments association from non-admins
+end
+```
+
+See [Field-level authorization](../authorization/field-authorization.md) for the full
+resolution rules. As with any field, an undefined rule means the association stays visible.
+
+> Inline association **management** (attach/detach controls and pagination within the table)
+> is planned for a later phase. Today collection associations are read-only tables on the show
+> view (capped, with a “+N more” note).

data/docs/resources/index-customization.md

@@ -0,0 +1,68 @@
+# Index customization
+
+## Custom header controls (`index_controls`)
+
+Add your own buttons/links to the index header with `self.index_controls`, a block rendered
+in the index view:
+
+```ruby
+class Post < RubyUIAdmin::BaseResource
+  self.index_controls = -> { control_link("Invite buyer", invite_path) }
+end
+```
+
+The block is evaluated inside the index component, so it has access to:
+
+- **`control_link(label, href, variant: :outline)`** — a button-styled link (`:outline` or
+  `:primary`). The common case.
+- **`create_button(label: nil)`** — a primary "New" link for this resource.
+- **Phlex element methods** (`a`, `button`, `div`, …) for full control.
+- **Route helpers** via the mounted engine proxy, e.g. `ruby_ui_admin.resources_users_path`.
+- **`@resource`** — the current resource instance.
+
+## Per-row controls (`row_controls`)
+
+`self.row_controls = ->(record) { ... }` adds controls to each row's actions cell. The block
+receives the row's `record` and is evaluated in the index component, so it has the same helpers
+plus **`show_button(record, label: nil)`** and **`edit_button(record, label: nil)`**:
+
+```ruby
+self.row_controls = ->(record) { show_button(record, label: "Preview") }
+
+# Layout of the controls cell:
+self.row_controls_config = { placement: :right, float: true, show_on_hover: true }
+```
+
+Examples:
+
+```ruby
+# Two controls, mixing the helper and raw Phlex:
+self.index_controls = lambda do
+  control_link("Export CSV", "/exports/posts.csv")
+  a(href: ruby_ui_admin.resources_users_path, class: "text-sm text-primary hover:underline") { "Manage users" }
+end
+```
+
+Custom controls render alongside the built-in **New** button and any standalone actions.
+
+> Use a `lambda`/`proc` with **no arguments** and read `@resource` directly inside the block.
+
+## Bulk selection
+
+When a resource has bulk actions, the index shows per-row selection checkboxes (plus a
+"select all"). `self.record_selector` (default `true`) controls this — set it to `false` to
+hide the selection column even when bulk actions exist:
+
+```ruby
+self.record_selector = false
+```
+
+With no bulk actions, there's nothing to select, so no checkboxes render regardless.
+
+## Reserved options (no effect yet)
+
+| Option | Intended purpose |
+|---|---|
+| `self.default_view_type` | Default index layout (`:table`, `:grid`, `:map`). Only `:table` is implemented. |
+
+Setting it is harmless; it simply has no effect today.