ruby_ui_admin 0.1.0

data/docs/authorization/adapters.md

@@ -0,0 +1,101 @@
+# Authorization adapters
+
+Authorization is **pluggable**. The admin checks every request through an *adapter*, selected with
+`config.authorization_client`:
+
+```ruby
+RubyUIAdmin.configure do |config|
+  config.authorization_client = :action_policy   # default
+  # config.authorization_client = :pundit
+  # config.authorization_client = :cancancan
+  # config.authorization_client = MyApp::CustomAdapter
+  # config.authorization_client = nil            # disable authorization entirely
+end
+```
+
+Internally `RubyUIAdmin::Services::AuthorizationService` is a thin facade that resolves the adapter
+(`RubyUIAdmin::Authorization.adapter_class`) and delegates to it, so controllers, views and
+resources stay backend-agnostic.
+
+## Built-in adapters
+
+| Value | Backend | Requires gem | Policy resolution |
+|---|---|---|---|
+| `:action_policy` (default) | [action_policy](https://actionpolicy.evilmartians.io) | — (gem dependency) | per-resource `authorization_policy` (`RubyUIAdmin::BasePolicy` subclass) |
+| `:pundit` | [Pundit](https://github.com/varvet/pundit) | `pundit` | per-resource `authorization_policy`, else Pundit inference |
+| `:cancancan` | [CanCanCan](https://github.com/CanCanCommunity/cancancan) | `cancancan` | a single global `Ability` (`config.cancancan_ability_class`) |
+
+`:pundit`/`:cancancan` are loaded **lazily** — the gem only requires them when selected, so they're
+optional dependencies you add to your own `Gemfile`.
+
+## Capability matrix
+
+| Capability | action_policy | Pundit | CanCanCan |
+|---|---|---|---|
+| CRUD (`index`/`show`/`new`/`edit`/`create`/`update`/`destroy`) | ✅ | ✅ | ✅ |
+| Record scope on the index | ✅ `relation_scope` | ✅ policy `Scope` | ✅ `accessible_by` |
+| Field-level rules (`view_<field>?`, …) | ✅ | ✅ (if the policy defines them) | ❌ not supported (all fields visible) |
+| Custom action auth (`act_on?`) | ✅ | ✅ (if defined) | ⚠️ via the mapped action / `:manage` |
+| `true_user` (impersonation context) | ✅ | ❌ (policies get `user` only) | ❌ (Ability gets `user` only) |
+| `explicit_authorization` fallback (undefined rule → allowed/denied) | ✅ | ✅ | ❌ (CanCanCan denies whatever the Ability doesn't grant) |
+
+> **Recommendation:** use `:action_policy` (or `:pundit`) if you need field-level rules,
+> impersonation context, or the `explicit_authorization` fallback. `:cancancan` covers CRUD +
+> record scoping; field-level authorization is silently skipped (every field stays visible).
+
+## Using Pundit
+
+Add `gem "pundit"`, set `config.authorization_client = :pundit`, and point each resource's
+`authorization_policy` at a Pundit policy (one that responds to `index?`/`show?`/… and, optionally,
+a `Scope`). Rules the policy doesn't define fall back to `explicit_authorization`. Pundit policies
+receive only `user` — `true_user` is not passed.
+
+## Using CanCanCan
+
+Add `gem "cancancan"`, set `config.authorization_client = :cancancan`, and define a single
+`Ability` (override the class with `config.cancancan_ability_class` if it isn't named `Ability`):
+
+```ruby
+class Ability
+  include CanCan::Ability
+  def initialize(user)
+    can :manage, :all if user&.admin?
+    can :read, Post, published: true
+  end
+end
+```
+
+The index scope follows the Ability's rules (`accessible_by`). Note the limitations in the matrix:
+no field-level rules, and `explicit_authorization` has no effect (grant access in the Ability).
+
+## Writing a custom adapter
+
+Subclass `RubyUIAdmin::Authorization::Adapter` and implement the four backend methods. The base
+provides the context (`user`, `true_user`, `record`, `policy_class`), `allowed?`, `normalize_rule`
+and `handle_missing_policy`:
+
+```ruby
+module MyApp
+  class CustomAdapter < RubyUIAdmin::Authorization::Adapter
+    # Authorize a rule (`:show`, `:update`, `:act_on`, `:view_<field>`…). Return a boolean; raise
+    # RubyUIAdmin::NotAuthorizedError when denied and raise_exception is true.
+    def authorize_action(rule, record: nil, raise_exception: true)
+      # ... your logic, using `user` / `true_user` / `policy_class` ...
+    end
+
+    # Apply a record scope to the index relation (return it unchanged when there's no scope).
+    def apply_policy(scope) = scope
+
+    # Does the resolved policy respond to this rule (for the given record)?
+    def has_rule?(rule, record: nil) = false
+
+    # Does the policy CLASS explicitly define this rule? (field-level: undefined ⇒ visible)
+    def defines_rule?(rule) = false
+  end
+end
+
+RubyUIAdmin.configure { |c| c.authorization_client = MyApp::CustomAdapter }
+```
+
+A custom adapter class is used as-is. To expose it under a symbol instead, add it to
+`RubyUIAdmin::Authorization::REGISTRY`.

data/docs/authorization/explicit-mode.md

@@ -0,0 +1,45 @@
+# Explicit authorization mode
+
+`config.explicit_authorization` controls what happens when authorization can't find an
+explicit answer.
+
+```ruby
+RubyUIAdmin.configure do |config|
+  config.explicit_authorization = false # default
+end
+```
+
+## What it affects
+
+### Resource & action rules
+
+For `index?/show?/create?/update?/destroy?/act_on?`, a rule the policy doesn't define falls
+back to the policy's default rule (`manage?`), which `RubyUIAdmin::BasePolicy` ties to this
+flag:
+
+| `explicit_authorization` | Undefined rule | No policy resolved at all |
+|---|---|---|
+| `false` (default) | **allowed** | **allowed** |
+| `true` | **denied** | **denied** |
+
+So `true` is a strict, deny-by-default posture: every allowed action must be declared in a
+policy. This matches a security-first setup.
+
+### Field rules
+
+Field/association visibility (`view_<field>?`) is **not** governed by this flag. A field is
+always visible unless a policy explicitly defines its rule and returns false. This is
+deliberate — turning on `explicit_authorization` must not silently hide every unconfigured
+field. See [Field-level authorization](field-authorization.md).
+
+## Disabling authorization
+
+Set `config.authorization_client = nil` to turn authorization off entirely (all rules pass,
+scopes are not applied). Useful for a trusted internal tool, or while bootstrapping.
+
+## Choosing a mode
+
+- **`false`** — convenient: define only the rules that restrict access; everything else is
+  open. Good default for small teams / trusted admins.
+- **`true`** — strict: nothing is permitted unless a policy says so. Prefer this when the
+  admin is exposed to many roles and you want fail-closed behaviour.

data/docs/authorization/field-authorization.md

@@ -0,0 +1,53 @@
+# Field-level authorization
+
+You can hide individual fields per user by defining rules on the resource's policy. This
+applies everywhere a field would appear: the index columns, the show view, **and** the
+new/edit forms — including param permitting, so an unauthorized field can't be submitted.
+
+## Rules
+
+For a field `:views_count`, define one of these on the resource policy:
+
+```ruby
+module RubyUIAdmin
+  module Policies
+    class PostPolicy < RubyUIAdmin::BasePolicy
+      # Generic visibility (all views):
+      def view_views_count? = user.admin?
+
+      # Or per-view (most specific wins):
+      def index_views_count? = user.admin?   # index column
+      def show_views_count?  = true          # show view
+      def edit_views_count?  = user.admin?   # new + edit forms
+    end
+  end
+end
+```
+
+### Resolution order
+
+For a field `<id>` in a given view, the first **defined** rule wins:
+
+| View | Rules checked (in order) |
+|---|---|
+| index | `index_<id>?` → `view_<id>?` |
+| show | `show_<id>?` → `view_<id>?` |
+| new | `new_<id>?` → `edit_<id>?` → `view_<id>?` |
+| edit | `edit_<id>?` → `view_<id>?` |
+
+For association fields the `<id>` is the association name (e.g. `view_comments?`).
+
+## Default behaviour
+
+- A field is **visible** unless a matching rule is defined **and returns false**.
+- An **undefined** rule means "no opinion" — the field stays visible. This is deliberate:
+  enabling [`explicit_authorization`](action-policy.md) does **not** silently hide every
+  unconfigured field (only resource/action authorization is affected by that flag).
+- Field authorization only runs when the resource has an explicit
+  `self.authorization_policy` and `authorization_client` isn't `nil`.
+
+## Security
+
+Because the same check filters the fields used for **param permitting and assignment**, a
+field hidden from a user is also stripped from `create`/`update` — they can't set it by
+crafting a request.

data/docs/authorization/policies.md

@@ -0,0 +1,62 @@
+# Policies
+
+Authorization is handled by [action_policy](https://actionpolicy.evilmartians.io). Admin
+policies live in `app/ruby_ui_admin/policies` (`RubyUIAdmin::Policies::*`) and inherit
+`RubyUIAdmin::BasePolicy`. Attach one to a resource with `self.authorization_policy`.
+
+```ruby
+# app/ruby_ui_admin/resources/post.rb
+class Post < RubyUIAdmin::BaseResource
+  self.authorization_policy = RubyUIAdmin::Policies::PostPolicy
+end
+
+# app/ruby_ui_admin/policies/post_policy.rb
+module RubyUIAdmin
+  module Policies
+    class PostPolicy < RubyUIAdmin::BasePolicy
+      def index?  = true
+      def show?   = true
+      def create? = user.admin?
+      def update? = user.admin? || record.user_id == user.id
+      def destroy? = user.admin?
+      def act_on? = user.admin?      # gate custom actions
+    end
+  end
+end
+```
+
+## 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 | `act_on?` | record(s) / model class |
+
+Field- and association-level rules (`view_<field>?`, `show_<field>?`, …) are covered in
+[Field-level authorization](field-authorization.md).
+
+## Defaults
+
+`RubyUIAdmin::BasePolicy` wires action_policy's default rule (`manage?`) to
+[`explicit_authorization`](explicit-mode.md): a rule you don't define falls back to `manage?`,
+which is allowed when `explicit_authorization` is false (the default) and denied when true.
+
+`authorize :user` is declared with `allow_nil: true`, so rules must guard a possibly-nil user
+(`user&.admin?`) when the admin can be reached without a signed-in user.
+
+## Context
+
+The `user` comes from `config.current_user_method`. `true_user` (the real user behind an
+impersonation) is also available, resolved from `config.true_user_method` (defaults to the
+current user) — gate on it with `true_user&.admin?`. To pass *additional* context (e.g. an
+account), declare it in a custom base policy and provide it — see the
+[action_policy docs](https://actionpolicy.evilmartians.io/#/authorization_context).
+
+## The current user
+
+`RubyUIAdmin::Current.user` exposes the resolved user during a request. In views, use
+`authorized_to?(:rule, record, policy_class:)` to show/hide buttons and links.

data/docs/authorization/scopes.md

@@ -0,0 +1,48 @@
+# Authorization scopes
+
+A policy's **scope** filters the index query so each user only sees the records they're
+allowed to — action_policy's equivalent of Pundit's `policy_scope`. Define it with
+`relation_scope` in the resource policy.
+
+```ruby
+module RubyUIAdmin
+  module Policies
+    class PostPolicy < RubyUIAdmin::BasePolicy
+      relation_scope do |relation|
+        next relation if user.admin?
+
+        relation.where(user_id: user.id)   # members see only their own
+      end
+    end
+  end
+end
+```
+
+## How it's applied
+
+On the index, the query flows through:
+
+```
+model.all → policy relation_scope → named scope → filters → sorting → pagination
+```
+
+So the authorization scope runs first and can't be bypassed by filters or named scopes.
+
+- If the policy defines **no** `relation_scope`, the relation is returned unchanged (all
+  records, subject to the other steps).
+- If `config.authorization_client` is `nil`, scoping is skipped entirely.
+
+## Not the same as named scopes
+
+This is **record-level authorization**, distinct from [named index scopes](../resources/scopes.md)
+(the tab bar). Both narrow the index query, but:
+
+- **Authorization scope** (`relation_scope`) is enforced for security and always applied.
+- **Named scopes** are user-facing tabs the user chooses between; they compose *after* the
+  authorization scope.
+
+## Using a scope elsewhere
+
+Because the index uses the policy scope, a user who isn't allowed to see a record also can't
+reach it through the index. Direct access (show/edit) is still guarded by the per-record
+rules (`show?`, `update?`, …).

data/docs/customization/controllers.md

@@ -0,0 +1,62 @@
+# Custom controllers & lifecycle hooks
+
+Each resource is served by a generic `RubyUIAdmin::ResourcesController`. To customize CRUD
+behaviour for one resource, generate a per-resource controller:
+
+```bash
+rails g ruby_ui_admin:controller Buyer
+# => app/controllers/ruby_ui_admin/buyers_controller.rb
+#    class RubyUIAdmin::BuyersController < RubyUIAdmin::ResourcesController
+```
+
+When that file exists, the resource's routes point to it automatically (otherwise they use
+the generic controller). Restart the server after adding a new controller so routes redraw.
+
+## Lifecycle hooks
+
+Override any of these (defaults live in `ResourcesController`):
+
+| Hook | Default | When |
+|---|---|---|
+| `create_success_action` | redirect to `after_create_path`, flash notice | record saved on create |
+| `create_fail_action` | re-render the form (422) | validation failed on create |
+| `update_success_action` | redirect to `after_update_path`, flash notice | record saved on update |
+| `update_fail_action` | re-render the form (422) | validation failed on update |
+| `destroy_success_action` | redirect to `after_destroy_path`, flash notice | record destroyed |
+| `destroy_fail_action` | redirect to the record, flash alert | `destroy` returned false |
+| `after_create_path` / `after_update_path` | the record's show page | used by the success actions |
+| `after_destroy_path` | the resource index | used by destroy success |
+
+```ruby
+module RubyUIAdmin
+  class BuyersController < RubyUIAdmin::ResourcesController
+    # Custom redirect + flash after update
+    def update_success_action
+      redirect_to resources_index_path, notice: "Buyer updated."
+    end
+
+    # Delete asynchronously instead of inline
+    def destroy_fail_action
+      Buyers::DeleteBuyerJob.perform_later(buyer: @record)
+      redirect_to resources_index_path, notice: "Deletion started in the background."
+    end
+  end
+end
+```
+
+Inside hooks you have the usual controller context: `@record`, `@resource`, `params`,
+`current_user`, `redirect_to`/`render`, `flash`, and the path helpers `resources_index_path`
+and `record_path(record)`.
+
+## Overriding the CRUD actions
+
+You can also override `create`, `update`, `destroy` (etc.) directly and call `super`:
+
+```ruby
+def create
+  # custom param munging…
+  super
+end
+```
+
+Prefer the [eject generator](ejecting.md) for changing the generic controller or views.

data/docs/customization/ejecting.md

@@ -0,0 +1,55 @@
+# Ejecting & customizing
+
+When configuration isn't enough, you can **eject** any engine file into your app and edit it.
+A copy placed at the same path in your app's `app/` shadows the engine's version (Zeitwerk
+loads your app's file first), so the framework picks up your customization automatically.
+
+## The generator
+
+```bash
+# View components (app/components/ruby_ui_admin/views/*)
+rails g ruby_ui_admin:eject --view index        # the index table/page
+rails g ruby_ui_admin:eject --view show
+rails g ruby_ui_admin:eject --view form
+rails g ruby_ui_admin:eject --view layout       # alias for the Base layout (sidebar/topbar)
+rails g ruby_ui_admin:eject --view field_value  # how field values render
+rails g ruby_ui_admin:eject --view field_input  # how form inputs render
+
+# Controllers (app/controllers/ruby_ui_admin/*)
+rails g ruby_ui_admin:eject --controller resources    # CRUD behaviour
+rails g ruby_ui_admin:eject --controller application  # base controller (auth hooks, etc.)
+
+# The admin's own UI components (app/components/ruby_ui_admin/ui/*) — to restyle
+rails g ruby_ui_admin:eject --ui icon
+rails g ruby_ui_admin:eject --ui pagination
+rails g ruby_ui_admin:eject --ui select
+```
+
+The file is copied verbatim to the same relative path in your app. Edit it there.
+
+> **Restyling RubyUI primitives** (button, table, badge, card, sidebar, …): those aren't ejected
+> from the gem — the admin renders **your app's** `RubyUI::*` components, so just edit them in
+> `app/components/ruby_ui/*` (where RubyUI generated them). `--ui` only covers the components the
+> gem owns: `icon`, `pagination`, `select`, and the `toast_*` family.
+
+## How overriding works
+
+The engine's controllers and Phlex components are autoloaded Ruby classes (e.g.
+`RubyUIAdmin::Views::Index`, `RubyUIAdmin::ResourcesController`). Because your app's autoload
+paths take precedence over an engine's, a file at the identical path in your app defines the
+same class and **wins** — no configuration or monkey-patching required.
+
+## Common customizations
+
+| Goal | Eject |
+|---|---|
+| Change the sidebar/top bar/branding | `--view layout` |
+| Tweak the index table markup | `--view index` |
+| Change how a field type renders | `--view field_value` / `--view field_input` |
+| Override CRUD redirects/messages | `--controller resources` |
+| Add an authentication/authorization hook | `--controller application` |
+| Restyle a RubyUI primitive (button/table/badge/…) | edit your app's `app/components/ruby_ui/*` |
+| Restyle an admin-owned component (icon/pagination/select/toast) | `--ui icon` / `--ui pagination` / … |
+
+> Eject only what you need — every ejected file is a copy you now maintain. Prefer
+> [configuration](../getting-started/configuration.md) when it covers your use case.

data/docs/customization/javascript.md

@@ -0,0 +1,161 @@
+# JavaScript
+
+The admin's interactive behaviour is built with native **Hotwire** — **Stimulus controllers** plus
+**Turbo** (Drive + Frames) — that **progressively enhance** the server-rendered HTML. Everything
+works without JavaScript; Hotwire only improves a few interactions.
+
+## How it's delivered
+
+The admin renders **your host app's RubyUI components**, so the JavaScript comes from **your app's
+bundler/importmap** — the admin doesn't ship its own runtime. It needs two sets of controllers
+registered:
+
+- The admin's own controllers, prefixed **`rua--*`**: `rua--tabs`, `rua--dialog` (action modals),
+  `rua--bulk-select`, `rua--row-link`, `rua--confirm` (delete confirmation).
+- **`ruby-ui--toaster` / `ruby-ui--toast`** — the admin renders RubyUI Toast for flash messages
+  **even if your app doesn't use RubyUI Toast**, so you probably won't already have these (the
+  toaster is patched for server-rendered flash). The other `ruby-ui--*` it uses (`ruby-ui--sidebar`
+  /`ruby-ui--sheet`, `ruby-ui--combobox`, …) are the same ones you already use for RubyUI elsewhere
+  — combobox/popover depend on `@floating-ui/dom`, so make sure it's available.
+
+**Don't wire these by hand.** The gem ships them flat under
+`public/ruby-ui-admin-assets/controllers/` plus an `index.js` that registers each under the right
+identifier. The `ruby_ui_admin:assets` generator copies the whole directory into your app and tells
+you the one import to add:
+
+```bash
+bin/rails generate ruby_ui_admin:assets
+# Bundler (esbuild/jsbundling/vite): copies to app/javascript/ruby_ui_admin/,
+#   then add to application.js:  import "./ruby_ui_admin"
+# Importmap + Propshaft: does NOT copy — pins the engine-served (undigested) entrypoint:
+#   config/importmap.rb:  pin "ruby_ui_admin", to: "/ruby-ui-admin-assets/controllers/index.js"
+#   application.js:       import "ruby_ui_admin"
+```
+
+Why importmap doesn't copy: Propshaft content-digests copied files, but `index.js`'s relative
+`./x.js` imports resolve to the *undigested* URLs (import maps only remap bare specifiers), which
+Propshaft won't serve → 404. The engine serves the same files **undigested** via Rack::Static, so
+relative imports work there and `@hotwired/stimulus`/`@hotwired/turbo` resolve through your own
+import map.
+
+Avoid translating the files into `controllers/rua/…` folders and running
+`stimulus:manifest:update` — the manifest would derive the wrong identifiers. The shipped `index.js`
+already registers everything correctly; you just import it.
+
+> Symptom: if flash toasts don't appear after an action, `ruby-ui--toaster` / `ruby-ui--toast`
+> are missing from your bundle — re-run `ruby_ui_admin:assets` and re-add the import.
+
+You wire these (plus your stylesheet) into the admin layout through **`config.head_assets`**:
+
+```ruby
+RubyUIAdmin.configure do |config|
+  config.head_assets = lambda do
+    safe_join([
+      stylesheet_link_tag("application", "data-turbo-track": "reload"),
+      javascript_importmap_tags # or javascript_include_tag("application", type: "module")
+    ])
+  end
+end
+```
+
+`config.head_assets` is a proc evaluated in the Rails view context, so it can call the usual asset
+helpers. When it's `nil`, the layout emits no assets (the page still renders, just unstyled and
+without enhancement). `config.javascript` is a convenience flag your proc can read to skip the JS
+tags.
+
+> **Turbo is on.** Navigation uses Turbo Drive (no full-page reloads), so POST→redirect responses
+> use **303 See Other** and the toaster region is re-rendered each visit (it is intentionally not
+> `turbo-permanent`) so flash messages always appear. Lazy tabs and the action modal load through
+> **Turbo Frames**. Caveat: if your *host* app uses Turbo + importmap, the link into the engine must
+> be a full page load (`data-turbo="false"` on that link) so the engine's own importmap applies.
+
+## What it enhances
+
+### Tabs (`rua--tabs`)
+
+Tab groups (`tabs do … end` in a resource) render as stacked, titled cards **without JS**. The
+controller reveals the tab bar, hides the redundant per-panel headings, and shows only the active
+panel. Switching tabs is instant and needs no server round-trip.
+
+#### Lazy tabs
+
+When `config.lazy_tabs` is on, non-active tabs render only a `<turbo-frame loading="lazy" src="…">`
+(a spinner until it loads). Turbo fetches the fragment URL when the tab becomes visible (the show
+action returns just that tab's content wrapped in the matching `<turbo-frame id>`), and swaps it in
+— no custom fetch; the `rua--tabs` controller only switches panels. Without JS the deferred tabs
+show a `<noscript>` "requires JavaScript" notice. See
+[Tabs & Panels › Lazy tab loading](../resources/tabs-panels.md#lazy-tab-loading).
+
+### Action modals (`rua--dialog`)
+
+A custom action trigger opens an inline **modal** whose body is a `<turbo-frame>` holding the
+action's form (loaded lazily, so the action's fields aren't evaluated until the modal opens).
+**Non-bulk** modals carry a static `src` + `loading="lazy"` (Turbo loads them when the dialog
+becomes visible); **bulk** modals have no server-side `src` — `rua--dialog#open` sets it from the
+currently checked rows, so reopening with a different selection refetches. The form carries
+`data-turbo-frame="_top"`, so submitting breaks out into a full Turbo visit (POST→303→redirect+flash)
+rather than reloading just the frame. Without JS the same trigger is a plain link to the action's
+page, so actions always work. The modal closes on the ✕ button, the backdrop, the cancel link, or
+the Escape key.
+
+### Bulk selection (`rua--bulk-select`)
+
+On index tables with bulk actions, the controller reveals the "select all" checkbox (hidden
+without JS) and toggles the per-row record checkboxes; the checked ids are submitted with a bulk
+action. Without JS there is no client-side selection.
+
+### Row links (`rua--row-link`)
+
+With `config.click_row_to_view_record`, clicking an index row (or a row in a `has_many`
+association table) navigates to the record's show page — ignoring clicks on links/buttons/inputs
+so row controls keep working. Without JS rows aren't clickable (the per-row show/edit links remain).
+
+### Delete confirmation (`rua--confirm`)
+
+The **Delete** control opens a confirmation **AlertDialog** (shared, on `<body>`) before
+submitting; confirming submits the delete form. Without JS the form submits directly, so deletion
+still works.
+
+### Notifications (Toast) — `ruby-ui--toaster` / `ruby-ui--toast`
+
+Flash messages (`notice` / `alert`, and any `succeed`/`error`/`inform`/`warn` from an action)
+render through the genuine **RubyUI Toast** component (vendored under `RubyUIAdmin::UI::Toast*`).
+Toasts appear **bottom-right**, with a variant-coloured left border and icon, stack, auto-dismiss,
+and can be swiped or closed. Flash key → variant: `notice`/`success` → **success** (green),
+`alert`/`error` → **error** (red), plus `warning`/`info`. You can also raise them from your own JS:
+
+```js
+RubyUI.toast.success("Saved")
+RubyUI.toast.error("Something went wrong", { description: "Try again." })
+```
+
+Without JS, a `<noscript>` fallback shows the messages as badges so they're never lost.
+
+### Sidebar — `ruby-ui--sidebar`
+
+The left navigation is the genuine **RubyUI Sidebar** (`RubyUIAdmin::UI::Sidebar*`). It is **fixed
+and expanded by default**; the top-bar trigger collapses it to an **icon rail** (`collapsible: :icon`)
+and the choice is **persisted in a cookie** (`sidebar_state`, 7 days). Below `768px` it becomes a
+**drawer** (a RubyUI Sheet). Without JS the sidebar simply renders expanded.
+
+## Markup hooks
+
+The controllers are driven by standard Stimulus attributes (`data-controller`,
+`data-action`, `data-<id>-target`, `data-<id>-<name>-param/value`) plus a few `data-rua-*` markers
+(handy if you eject/customize views):
+
+| Hook | Purpose |
+|---|---|
+| `[data-controller="rua--tabs"]` | tab group; targets `tab`/`panel`/`nav`/`heading`, action `click->rua--tabs#show` |
+| `[data-rua-tab="key"]` / `[data-rua-tab-panel="key"]` | button↔panel key matching |
+| `<turbo-frame id="rua-tab-frame-N" loading="lazy" src="/url">` | a deferred tab panel; Turbo loads it when the tab is shown (`config.lazy_tabs`) |
+| `[data-controller="rua--dialog"]` | manages action modals; trigger `click->rua--dialog#open` + `…-id-param`/`…-bulk-param`, close via `click->rua--dialog#close` |
+| `[data-rua-dialog="id"]` + inner `<turbo-frame>` | the modal; the frame loads the form (`[data-rua-frame-base]` on bulk frames is the base URL the controller appends checked ids to) |
+| `[data-controller="rua--bulk-select"]` | table bulk selection; target `selectAll`, action `change->rua--bulk-select#toggleAll`; `[data-rua-row-select]` marks a record checkbox |
+| `[data-controller="rua--row-link"]` | clickable row; `…-url-value` + `click->rua--row-link#navigate` |
+| `[data-controller="rua--confirm"]` (on `<body>`) | shared confirm AlertDialog; targets `dialog`/`title`/`message`; trigger `click->rua--confirm#request` + `…-message-param`/`…-heading-param`; `#confirm`/`#cancel` |
+| `[data-controller="ruby-ui--toaster"]` / `…--toast` | the RubyUI Toast region/items |
+| `[data-controller="ruby-ui--sidebar"]` + `[data-sidebar="trigger"]` | the RubyUI Sidebar (collapse + mobile drawer) |
+| `[data-controller="ruby-ui--combobox"]` | the RubyUI Combobox (searchable filters and actions menu) |
+
+> Progressive enhancement is intentional: the whole admin is usable with JavaScript disabled.

data/docs/customization/theming-rubyui.md

@@ -0,0 +1,80 @@
+# Theming with RubyUI
+
+The admin renders **your host app's RubyUI (Phlex) components**, so it inherits your app's RubyUI
+theme automatically — there's no separate admin theme to keep in sync.
+
+## How styling is delivered
+
+The admin renders the same `RubyUI::*` components you generated into your app, which emit Tailwind
+utility classes. Styling comes from **your app's Tailwind build** — there is no admin-specific
+stylesheet. You must ensure your Tailwind content/sources cover:
+
+- `app/components/ruby_ui/**` (your RubyUI components), and
+- the admin's own views (the engine's `app/components/ruby_ui_admin/**`), so the classes used by
+  the admin's layout/lists/forms are generated.
+
+Then point the admin layout at your compiled CSS via `config.head_assets` (see
+[JavaScript › head assets](javascript.md)). Because the admin uses your RubyUI components, any
+RubyUI design tokens they rely on (e.g. `success` / `warning` colors) must be defined in your
+theme.
+
+## Design tokens
+
+RubyUI components resolve colors through CSS variables (design tokens) defined in your app's
+RubyUI stylesheet — typically:
+
+```css
+:root {
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+  --muted: #f4f4f5;       --muted-foreground: #71717a;
+  --border: #e4e4e7;      --input: #e4e4e7;       --ring: #18181b;
+  --primary: #18181b;     --primary-foreground: #fafafa;
+  --secondary: #f4f4f5;   --secondary-foreground: #18181b;
+  --accent: #f4f4f5;      --accent-foreground: #18181b;
+  --destructive: #ef4444;
+  --popover: #ffffff;     --popover-foreground: #0a0a0a;
+  /* Sidebar (left navigation) */
+  --sidebar: #fafafa;             --sidebar-foreground: #3f3f46;
+  --sidebar-accent: #f4f4f5;      --sidebar-accent-foreground: #18181b;
+  --sidebar-border: #e5e7eb;      --sidebar-ring: #3b82f6;
+}
+```
+
+Utilities like `bg-background`, `text-muted-foreground`, `border-border`, `bg-primary/90`,
+`bg-sidebar`, `text-sidebar-accent-foreground` resolve through these variables, so re-theming
+is a matter of changing the token values. The `--sidebar-*` tokens style the left navigation
+independently from the page (so you can give it its own surface colour).
+
+## Dark mode
+
+A `.dark` variant is included. Add the `dark` class to a parent element (e.g. `<html>`) to
+switch. The tokens above have dark overrides bundled.
+
+## Make sure your Tailwind build covers the admin
+
+Because the admin renders with your app's RubyUI components and its own Phlex views, your
+Tailwind build's content/sources must include both, or admin pages will be missing styles:
+
+- `app/components/ruby_ui/**` — your RubyUI components, and
+- the admin's views — the engine's `app/components/ruby_ui_admin/**` (in the installed gem).
+
+Rather than hardcode the gem's path in `@source` (it varies per environment), run
+`bin/rails ruby_ui_admin:tailwind_source` to extract the admin's class inventory into
+`app/assets/tailwind/ruby_ui_admin_classes.html`, `@source` that (commit it; re-run on upgrade), then
+expose the compiled stylesheet to the admin layout through `config.head_assets`.
+
+## Integrating with the host's own Tailwind build (advanced)
+
+If you'd rather own the build (e.g. to override tokens app-wide or share your design system),
+point your host Tailwind v4 entry at the engine's components and define the tokens yourself:
+
+```css
+@import "tailwindcss";
+@source "./ruby_ui_admin_classes.html"; /* generated by rake ruby_ui_admin:tailwind_source */
+/* define the :root tokens above (or reuse your existing RubyUI tokens) */
+```
+
+Then disable the bundled stylesheet by ejecting the layout, or simply let both load (the host
+build wins by load order). Apps that already use RubyUI (with the same token vocabulary) only
+need the `@source` line.