compony 0.11.8 → 0.11.9

data/doc/guide/pre_built_components/index.md

@@ -3,4 +3,67 @@
 
 # Pre-built components: Index
 
-This stanalone component is resourceful, holds a collection of records and corresponds to Rail's `index` controller action. It is a wrapper for the [`List` component](./list.md).
+`Compony::Components::Index` is a resourceful standalone component corresponding to Rails'
+`index` controller action. It holds a collection of records and is a thin wrapper that
+nests the [`List`](./list.md) component of the same family.
+
+## What it does by default
+
+The shipped `setup` (see `lib/compony/components/index.rb`) is deliberately minimal:
+
+- **Route:** `standalone path: family_name` with a `verb :get` authorized by
+  `can?(:index, data_class)`, e.g. `/users`.
+- **Label:** `label(:all) { data_class.model_name.human(count: 2) }` — e.g. "Users".
+- **Data:** `load_data { @data = data_class.accessible_by(controller.current_ability) }`
+  — the full [CanCanCan](https://github.com/CanCanCommunity/cancancan)-scoped collection.
+- **Exposed intent:** adds a `:new` intent (unless the model is
+  [owned](/doc/guide/ownership.md) by another).
+- **Content:** `concat render_sub_comp(:list, @data)` — delegates all rendering to the
+  family's `List`.
+
+So with both an `Index` and a `List` component present, a family lists out of the box:
+
+```ruby
+class Components::Users::Index < Compony::Components::Index; end
+class Components::Users::List  < Compony::Components::List
+  setup { columns :name, :email }
+end
+```
+
+## Typical overrides
+
+Narrow or order the collection:
+
+```ruby
+class Components::Users::Index < Compony::Components::Index
+  setup do
+    load_data { @data = User.accessible_by(current_ability).active.order(:name) }
+  end
+end
+```
+
+Customize the action toolbar via [exposed intents](/doc/guide/intents.md#exposed-intents):
+
+```ruby
+setup do
+  exposed_intents do
+    add :index, :users, label: 'CSV', name: :csv, path: { format: :csv }
+    add :import, :users, method: :post, before: :new
+  end
+end
+```
+
+Add a second standalone route serving an alternative `List`:
+
+```ruby
+setup do
+  standalone path: 'users/archived'
+  content :main, hidden: true do
+    concat render_sub_comp(:list, @data.archived)
+  end
+end
+```
+
+In practice apps put the layout/markup chrome in a `BaseComponents::Index` and inherit
+from that — see [Real-world patterns](../patterns.md#3-index--load_data-scope--nested-list).
+For column/filter/sort configuration, see [`List`](./list.md).

data/doc/guide/pre_built_components/list.md

@@ -3,12 +3,116 @@
 
 # Pre-built components: List
 
-This resourceful component displays a table / list of records. It is meant to be nested within another component, typically [`Index`](./index.md) of the same family or [`Show`](./show.md) of another family. Compony's implementation of this component features:
+`Compony::Components::List` is a resourceful component that renders a table/list of
+records. It is **not** standalone — it is meant to be nested, typically inside
+[`Index`](./index.md) of the same family or [`Show`](./show.md) of an owning family, via
+`render_sub_comp(:list, collection)`.
 
-- Inferrence of rows from model fields as well as custom rows
-- Row actions for each displayed record
-- Pagination
-- Sorting: if the Ransack gem is installed and at least one sorting column has been specified, the component can automatically generate a select input for sorting as well as sorting links.
-- Filtering / Searching: if the Ransack gem is installed and at least one filter has been specified, the component can automatically generate a filter / search form that works with Ransack.
+Features: field-inferred or custom columns, per-row intents, pagination, and — when the
+[Ransack](https://github.com/activerecord-hackery/ransack) gem is present and at least one
+sort/filter is declared — sorting links, a sort select, and a filter/search form.
 
-This component serves as a base block for building powerful management interfaces. Consult the component's class to learn about the various methods you can use in `setup` in order to customize the behavior. You will likely want to implement your own custom base component based on this component and overwrite the `content` blocks that you would like to customize.
+## Column DSL
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `column` | `column(:name, label: nil, class: nil, link_opts: {}) { \|record\| ... }` | Add/define a column. No block → model-field column (auto label, value via `value_for`, only if `:index` permitted). Block is instance-exec'd per row and renders the cell. |
+| `columns` | `columns(:a, :b, as_title: false, **kw)` | Bulk `column`. `as_title: true` marks title columns (shown as the card heading in mobile/card layouts). |
+| `skip_column` | `skip_column(:name)` | Hide a (possibly inherited) column. |
+
+```ruby
+class Components::Orders::List < Compony::Components::List
+  setup do
+    columns :number, :customer, as_title: true
+    columns :total, :created_at
+    column :status, class: 'text-end' do |order|
+      span order.status.label, class: "badge bg-#{order.status.key}"
+    end
+  end
+end
+```
+
+## Filtering & sorting (Ransack)
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `filter` | `filter(:name, label: nil) { \|f\| ... }` | Add a filter. No block → field filter or a Ransack predicate string (e.g. `:id_eq`). Block gets the Ransack search form and renders label + input. |
+| `filters` | `filters(:a, :b, **kw)` | Bulk `filter`. |
+| `sort` | `sort(:name, label: nil)` | Add a sort criterion (must be Ransack-sortable). Generates one sort link + asc/desc entries. |
+| `sorts` | `sorts(:a, :b)` | Bulk `sort`. |
+| `default_sorting` | `default_sorting('id desc')` | Default Ransack sort applied when none chosen. |
+
+```ruby
+setup do
+  filters :number, :status
+  filter :overdue, label: 'Overdue' do |f|
+    concat f.check_box(:overdue_eq, {}, true, false)
+  end
+  sorts :number, :created_at
+  default_sorting 'created_at desc'
+end
+```
+
+## Per-row intents
+
+`row_intents` opens the [intent management DSL](/doc/guide/intents.md#exposed-intents)
+(`add`/`remove`, `before:`) applied to each row's record:
+
+```ruby
+setup do
+  row_intents do
+    remove :destroy
+    add :archive, ->(record) { record }, method: :patch, before: :edit
+  end
+end
+```
+
+## Toggles, paging, styling
+
+All have matching constructor kwargs so a nesting parent can override per render
+(`render_sub_comp(:list, coll, skip_pagination: true, skip_columns: [:order])`).
+
+| DSL | Default | Purpose |
+| --- | --- | --- |
+| `pagination(bool)` | on | Enable/disable paging (off loads all rows). |
+| `results_per_page(n)` | 20 | Rows per page. |
+| `filtering(bool)` | on | Enable/disable the filter form. |
+| `sorting(bool)` / `sorting_in_filter(bool)` / `sorting_links(bool)` | on | Toggle sort UIs. |
+| `filter_label_class` / `filter_input_class` / `filter_select_class` / `filter_item_wrapper_class` | — | CSS classes for filter form elements. |
+
+Constructor `skip_*` kwargs: `skip_pagination`, `skip_filtering`, `skip_sorting`,
+`skip_sorting_in_filter`, `skip_sorting_links`, `skip_columns:`, `skip_row_intents:`,
+`skip_filters:`, `results_per_page:`, `default_sorting:`.
+
+## Customizing rendering
+
+`List` exposes named `content` blocks (`:data`, `:filter`, `:pagination`, `:sorting_links`,
+…) that you override — almost always once, in an app `BaseComponents::List`, to fit your UI
+framework, then inherited everywhere:
+
+```ruby
+module BaseComponents
+  class List < Compony::Components::List
+    setup do
+      filter_input_class 'form-control'
+      content :filter, hidden: true do
+        # Bootstrap-styled filter form wrapper
+      end
+      content :data, hidden: true do
+        # Bootstrap table / responsive cards
+      end
+    end
+  end
+end
+```
+
+Embedding a child list inside a Show, dropping the FK column and preserving the active tab
+across filter submits:
+
+```ruby
+concat render_sub_comp(:list, @data.line_items,
+                       skip_columns: [:order],
+                       params_in_filter: [param_name('tab')])
+```
+
+See [Real-world patterns](../patterns.md#4-list-customization) for the recurring app setup.

data/doc/guide/pre_built_components/show.md

@@ -3,6 +3,61 @@
 
 # Pre-built components: Show
 
-This resourceful component corresponds to a typical Rails controller's `show` action and presents `@data` which is typically a model instance.
+`Compony::Components::Show` is a resourceful standalone component corresponding to a Rails
+`show` action. It loads `@data` by `:id` and presents its fields.
 
-To use it, create a component of the style `Components::Users::Show` and inherit from `Compony::Components::Show`. By default, this will display all permitted fields along with their labels. Consult the component's class to learn about the methods you can use in `setup` in order to customize the behavior.
+## What it does by default
+
+From `lib/compony/components/show.rb`:
+
+- **Route:** `standalone path: "/#{family_name}/:id"` with an `:id` constraint that accepts
+  integer **or** UUID ids, `verb :get` authorized by `can?(:show, @data)`.
+- **Labels:** long = `data.label`; short = a generic translated "Show".
+- **Exposed intents:** `:edit` and `:destroy` for `@data`, plus a `:back_to_owner` intent
+  if the model is [owned](/doc/guide/ownership.md).
+- **Content blocks:**
+  - `:label` → `h2 component.label`
+  - `:main` → renders the `:data` block (override `:main` to wrap `:data` in a card etc.)
+  - `:data` (hidden) → if no columns were declared, calls `all_field_columns(@data)`, then
+    renders a two-column table of label/value per permitted field.
+
+```ruby
+class Components::Users::Show < Compony::Components::Show; end   # fully functional
+```
+
+## Column DSL
+
+`Show` shares a `column`/`columns` DSL with [`List`](./list.md) (here "column" means an
+attribute row, since Show renders one record).
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `column` | `column(:name, label: nil, class: nil, link_opts: {}, link_to_component: :show) { \|record\| ... }` | Add/define one attribute row. Without a block, treated as a model field; the block (instance-exec'd per record) supplies the value. |
+| `columns` | `columns(:a, :b, **shared_kwargs)` | Bulk `column`. |
+| `all_field_columns` | `all_field_columns(@data)` | Add a column for every model field (the default when none declared). |
+| `skip_column` | `skip_column(:name)` | Drop an inherited column. When nesting Show in a parent, prefer the constructor's `skip_columns:` kwarg. |
+
+Field columns are only rendered if the current ability permits `:show` on that attribute;
+a `nil` value hides the row.
+
+```ruby
+class Components::Users::Show < Compony::Components::Show
+  setup do
+    columns :name, :email, :created_at
+    column :status do |user|                       # custom computed row
+      user.active? ? 'Active' : 'Disabled'
+    end
+    skip_column :created_at                         # if inherited and unwanted
+
+    content do                                      # wrap :data in app chrome
+      div class: 'card card-body' do
+        content :data
+      end
+    end
+  end
+end
+```
+
+UUID/string ids work out of the box thanks to the route constraint. For nesting a Show (or
+its `:data`) inside another component see [Nesting](/doc/guide/nesting.md); for the app
+base-layer approach see [Real-world patterns](../patterns.md#1-the-app-base-component-layer).

data/doc/guide/pre_built_components/with_form.md

@@ -3,16 +3,63 @@
 
 # Pre-built components: WithForm
 
-`Compony::Components::WithForm` is an abstract base class for components that render a form. Those components can further be resourceful, but don't have to be. If a component inherits from WithForm, it is always twinned with another component that will provide the form.
+`Compony::Components::WithForm` is the abstract base for components that render and submit
+a form. It is **twinned** with a [`Form`](./form.md) component: WithForm provides the
+route, authorization and resource handling; the Form provides the inputs and param schema.
+[`New`](./new.md) and [`Edit`](./edit.md) both inherit from WithForm — you rarely subclass
+it directly, but understanding the twinning explains how they work.
 
-WithForm adds the following DSL methods:
+A WithForm component may be resourceful (New/Edit are) but does not have to be.
 
-- `form_comp_class` sets the class that will be instantiated by `form_comp`
-- `form_comp` returns an instance of the Form component twinned with this component. If `form_comp_class` was never set, it will default to loading the component named `Form` in the same family as this component.
-- `submit_verb` takes a symbol containing a verb, e.g. `:patch`. It defines this component's standalone verb that should be called when the twinned Form component is submitted.
-- `submit_path` defaults to this component's standalone path. You can override this to submit the form to another component, should you need it.
+## How the twinning works
 
-The following other pre-built components implement `WithForm`:
+- `form_comp` returns the Form instance, built lazily. It defaults to the component named
+  `Form` in the **same family**, instantiated with this component as `parent_comp` and
+  passed `submit_verb`, `submit_path` and `cancancan_action`.
+- The Form renders inside this component's `content` (e.g. New/Edit do
+  `concat form_comp.render(controller, data: @data)`).
+- The form's `<form>` posts back to `submit_path` using `submit_verb`; that same component
+  handles the submit verb (POST for New, PATCH for Edit) and runs the resourceful
+  lifecycle (`assign_attributes` → `store_data` → `respond`).
 
-- [`New`](new.md)
-- [`Edit`](edit.md)
+## DSL methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `submit_verb` | `submit_verb(:patch)` | HTTP verb the twinned form submits with. Mandatory (New sets `:post`, Edit `:patch`). |
+| `form_comp_class` | `form_comp_class(Components::Users::SignupForm)` | Use a specific Form class instead of the same-family `Form`. |
+| `submit_path` | `submit_path { Compony.path(:create, :users) }` | Override where the form submits. Block is given the controller; defaults to this component's own path. |
+| `form_cancancan_action` | `form_cancancan_action(:edit)` | CanCanCan action used by the Form for per-field `permitted_attributes` (New sets `:new`, Edit `:edit`). Pass `nil` to disable per-field auth. |
+| `form_comp` | `form_comp` | (Not DSL — a reader.) The Form instance; override in a subclass for full control. |
+
+## Example: a custom non-default form
+
+```ruby
+class Components::Users::Signup < Compony::Components::New
+  setup do
+    standalone path: 'signup' do
+      skip_authentication!
+      verb :get  do authorize { true } end
+      verb :post do authorize { true } end
+    end
+    form_comp_class Components::Users::SignupForm   # not the default Users::Form
+    on_created_redirect_path { Compony.path(:show, @data) }
+  end
+end
+
+class Components::Users::SignupForm < Compony::Components::Form
+  setup do
+    form_fields do
+      concat field(:email)
+      concat pw_field(:password)
+    end
+    schema_field :email
+    schema_pw_field :password
+  end
+end
+```
+
+For the full submit/redirect behavior see [`New`](./new.md) and [`Edit`](./edit.md); for
+the form input/schema DSL see [`Form`](./form.md); for the lifecycle hooks see
+[Resourceful](/doc/guide/resourceful.md). Multi-step and clone flows that reuse this
+machinery are in [Real-world patterns](../patterns.md#11-non-crud-job-dispatch-toggles-clone).

data/doc/guide/pre_built_components.md

@@ -4,7 +4,12 @@
 
 Compony comes with a few pre-built components that cover the most common cases that can be speed up development. They are meant to be inherited from and the easiest way to do this is by using the [provided Rails generators](./generators.md) `rails g component ...`.
 
-The pre-built components can be found in the module `Compony::Components`. As you can see, there is no Show and no Index component. The reason is that these will depend a lot on your application's UI framework (e.g. Bootstrap) and thus the benefits a UI-agnostic base component can provide are minimal. Additionally, these components are very easy to implement, as is illustrated in the example at the beginning of this documentation.
+The pre-built components can be found in the module `Compony::Components`. They ship a
+sensible, UI-agnostic default (plain HTML, no styling) — you typically inherit from them
+in an app base layer that adds your UI framework's markup (see
+[Real-world patterns](./patterns.md#1-the-app-base-component-layer)). `Show` and `Index`
+are intentionally minimal because their presentation depends heavily on your UI framework;
+they are easy to override (see the [example](./example.md)).
 
 In the following, the pre-built components currently shipped with Compony are presented:
 
@@ -15,6 +20,6 @@ In the following, the pre-built components currently shipped with Compony are pr
 - [WithForm](./pre_built_components/with_form.md): A base class for components containing and submitting forms
 - [Form](./pre_built_components/form.md): Compony's equivalent to Rail's `_form` partial
 - [New](./pre_built_components/new.md): Compony's equivalent to Rail's `new` and `create` controller action
-- [Edit](./pre_built_components/new.md): Compony's equivalent to Rail's `edit` and `update` controller action
+- [Edit](./pre_built_components/edit.md): Compony's equivalent to Rail's `edit` and `update` controller action
 
 [Guide index](/README.md#guide--documentation)

data/doc/guide/standalone.md

@@ -139,6 +139,21 @@ end
 
 By implementing `path do ... end` inside the `setup` method of a component, you can override the way paths to that component are generated. Customizing the path generation will affect all mentioned methods mentioned here involving paths, such as `Compony.path`, `render_intent` etc.
 
-This is an advanced usage. Refer to the default implementation of `Component`'s `path_block` to see an example.
+The block runs **outside** the request context, so build URLs via
+`Rails.application.routes.url_helpers` (not `controller`/`helpers`). It is given an optional
+model, positional path-helper args, the `standalone_name:` kwarg, and any extra kwargs.
+
+This is an advanced usage. Refer to the default implementation of `Component`'s `path_block`
+to see the baseline example.
+
+Where overriding `path` is genuinely useful:
+
+- **Inject a derived/looked-up param.** Callers pass a high-level argument and the block
+  turns it into concrete path params.
+- **Mint a signed token into the URL** so an unauthenticated link can authorize itself —
+  a full worked recipe is in
+  [Real-world patterns §18 (signed-token capability links)](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links)
+  (magic login, password reset, invite/confirm links).
+- **Custom slugs / vanity paths** that differ from the Rails route helper's default shape.
 
 [Guide index](/README.md#guide--documentation)

data/doc/index.html

@@ -90,7 +90,7 @@
 </li><li>
 <p>Compony seamlessly integrates with Rails and does not interfere with existing code. Using Compony, you <strong>can</strong> write your application as components, but it is still possible to have regular routes, controllers and views side-to-side to it. This way, you can migrate your applications to Compony little by little and enter and leave the Compony world as you please. It is also possible to render Compony components from regular views and vice versa.</p>
 </li><li>
-<p>Compony is built for Rails 7, 7.1 and 8, and fully supports Stimulus and Turbo Drive. It is also compatible Turbo Frames and Streams, but there are not many helpers specifically targetting theme at this point..</p>
+<p>Compony requires Rails &gt;= 7.2.1 and Ruby &gt;= 3.3.5 (see <a href="./doc/integrations_md.html">doc/integrations.md</a> for all dependencies), and fully supports Stimulus and Turbo Drive. It is also compatible Turbo Frames and Streams, but there are not many helpers specifically targetting theme at this point..</p>
 </li><li>
 <p>Compony uses <a href="https://github.com/CanCanCommunity/cancancan">CanCanCan</a> for authorization but does not provide an authentication mechanism. You can easily build your own by creating login/logout components that manage cookies, and configure Compony to enforce authentication using the <code>Compony.authentication_before_action</code> setter. I have also successfully tested Compony to work with <a href="https://github.com/heartcombo/devise">Devise</a>.</p>
 </li></ul>
@@ -109,8 +109,29 @@
 <ul><li>
 <p><a href="./doc/guide/example_md.html">Self-contained example</a> for those who like to dive straight into code</p>
 </li><li>
+<p><a href="./doc/guide/example_advanced_md.html">Advanced example</a>: custom form, feasibility, CSV export, virtual-model launch form</p>
+</li><li>
 <p><a href="./doc/guide/installation_md.html">Installation</a> (start here)</p>
 </li><li>
+<p>Quick reference (also handy for AI coding assistants):</p>
+<ul><li>
+<p><a href="./doc/guide/dsl_reference_md.html">DSL reference</a>: every DSL method with signature and context</p>
+</li><li>
+<p><a href="./doc/guide/glossary_md.html">Glossary</a>: one-line definitions of Compony vocabulary</p>
+</li><li>
+<p><a href="./doc/guide/gotchas_md.html">Gotchas</a>: known anti-patterns with symptom, cause, fix</p>
+</li><li>
+<p><a href="./doc/guide/patterns_md.html">Real-world patterns</a>: idioms distilled from production apps</p>
+</li><li>
+<p><a href="./doc/guide/cookbook_md.html">Cookbook</a>: recipes indexed by task (“I want to do X”)</p>
+</li><li>
+<p><a href="./doc/integrations_md.html">Integrations</a>: companion gems — required, optional, app-side</p>
+</li><li>
+<p><a href="./CLAUDE_md.html">Agent primer</a> and <a href="./doc/llms.txt">doc/llms.txt</a>: orientation for LLM-based tools</p>
+</li><li>
+<p><a href="./doc/guide/maintaining_md.html">Maintaining</a>: release &amp; docs policy (for gem contributors)</p>
+</li></ul>
+</li><li>
 <p>Concepts and usage:</p>
 <ul><li>
 <p><a href="./doc/guide/basic_component_md.html">A basic component</a>: Basic concepts relevant for all components</p>
@@ -135,7 +156,7 @@
 </li><li>
 <p><a href="./doc/guide/internal_datastructures_md.html">Internal datastructures</a>: Noteworthy datastructures provided by Compony</p>
 </li><li>
-<p><a href="./doc/guide/internal_datastructures_md.html">Virtual models</a>: Unleashing non-persistent interactions through Compony’s <code>ActiveType</code> integration</p>
+<p><a href="./doc/guide/virtual_models_md.html">Virtual models</a>: Unleashing non-persistent interactions through Compony’s <code>ActiveType</code> integration</p>
 </li></ul>
 </li><li>
 <p>Pre-built components shipped with Compony</p>
@@ -156,7 +177,7 @@
 </li><li>
 <p><a href="./doc/guide/pre_built_components/new_md.html">New</a>: Compony’s equivalent to Rail’s <code>new</code> and <code>create</code> controller action</p>
 </li><li>
-<p><a href="./doc/guide/pre_built_components/new_md.html">Edit</a>: Compony’s equivalent to Rail’s <code>edit</code> and <code>update</code> controller action</p>
+<p><a href="./doc/guide/pre_built_components/edit_md.html">Edit</a>: Compony’s equivalent to Rail’s <code>edit</code> and <code>update</code> controller action</p>
 </li></ul>
 </li></ul>
 
@@ -199,7 +220,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Fri May 15 10:29:33 2026 by
+  Generated on Mon May 18 13:55:32 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.3.5).
 </div>

data/doc/integrations.md

@@ -0,0 +1,61 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Integrations & companion gems
+
+What Compony pulls in, what it optionally lights up, and what you are expected to add
+yourself. The authoritative source for hard dependencies and their version constraints is
+the `:gemspec` task in [`Rakefile`](/Rakefile) (it generates `compony.gemspec`); the table
+below mirrors it and must be updated together with it (see
+[maintaining.md](/doc/guide/maintaining.md)).
+
+## Hard runtime dependencies (installed automatically)
+
+| Gem | Constraint | Why Compony needs it |
+| --- | --- | --- |
+| `rails` | `>= 7.2.1` | Routing, controllers, views Compony plugs into. |
+| `request_store` | `>= 1.7` | Per-request storage (e.g. `Compony.root_comp`). |
+| `dyny` | `>= 0.0.3` | HTML-as-Ruby templating used in `content` blocks. |
+| `schemacop` | `>= 3.0.17` | Strong-param schema validation behind `schema_field` / `schema_line`. |
+| `simple_form` | `>= 5.3.1` | The form builder behind the Form component's `field`. |
+| `dslblend` | `>= 0.0.3` | Powers the `RequestContext` multi-provider DSL. |
+| `anchormodel` | `>= 0.3.0` | `anchormodel` model-field type + enum-like associations. |
+| `cancancan` | `~> 3.6.1` | Authorization: `authorize { can?(...) }`, `accessible_by`, per-field `permitted_attributes`. |
+
+The Ruby floor is `>= 3.3.5` (`required_ruby_version`).
+
+> Version note: the gemspec requires `rails >= 7.2.1`. If the README's prose mentions an
+> older range, the gemspec wins — keep them in sync when bumping (see maintaining.md).
+
+## Optional — presence unlocks a feature
+
+These are **not** declared dependencies; Compony detects them and enables behavior if they
+are in the host app's bundle.
+
+| Gem | Unlocks |
+| --- | --- |
+| `active_type` | `Compony::VirtualModel` (loaded only if `ActiveType::Object` is defined). Non-persistent / upload / wizard forms — [patterns §12](/doc/guide/patterns.md#12-virtual-model-for-non-persistent--upload-forms), [virtual_models.md](/doc/guide/virtual_models.md). |
+| `ransack` | List filtering, sorting links and the sort select in [`List`](/doc/guide/pre_built_components/list.md). Without it, declare no `filter`/`sort` and those UIs stay off. |
+
+## App-side companions (you add these)
+
+Compony is UI- and auth-agnostic; these are conventional choices in real apps, pulled in
+by your app, not by Compony.
+
+| Concern | Typical choice | Used by |
+| --- | --- | --- |
+| Authentication | Devise, or a custom login component + `Compony.authentication_before_action=` | Compony ships **no** auth ([README](/README.md)); token-link flows → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links) |
+| Turbo / Stimulus | `turbo-rails`, `stimulus-rails` | Compony fully supports Turbo Drive; inline-edit → [patterns §15](/doc/guide/patterns.md#15-inline-edit-card-with-a-turbo-frame), ajax PATCH → [patterns §17](/doc/guide/patterns.md#17-inline-patch-without-a-form-reorder--quick-toggle) |
+| Select / date inputs | TomSelect, Flatpickr (as registered `simple_form` inputs) | `field(:x, as: :tom_select/:flatpickr_*)` — [patterns §5–6](/doc/guide/patterns.md#5-custom-form--schemacop-kept-in-sync) |
+| i18n | Rails I18n and/or FastGettext | Component labels; gem ships `config/locales/{de,en,fr}.yml` |
+| File handling | ActiveStorage (+ a variant/processor) | Attachment fields, virtual-model uploads — [patterns §12](/doc/guide/patterns.md#12-virtual-model-for-non-persistent--upload-forms) |
+| PDF / CSV | Prawn / wicked_pdf, Ruby `CSV` | Export endpoints — [patterns §10](/doc/guide/patterns.md#10-csv--pdf-via-respond-format) |
+| Signed tokens | `jwt` | Capability links — [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links) |
+
+Incompatibility: `tailwindcss-rails` purges Compony component CSS (component HTML is not in
+`app/views`); see [gotchas.md #13](/doc/guide/gotchas.md#13-tailwindcss-rails-purges-compony-styles).
+
+## Development dependencies
+
+`yard >= 0.9.28` (docs), `rubocop >= 1.48`, `rubocop-rails >= 2.18.0` (lint).
+
+[Guide index](/README.md#guide--documentation)

data/doc/llms.txt

@@ -0,0 +1,62 @@
+# Compony
+
+> Compony is a Ruby on Rails gem for writing apps in component style: one Ruby class
+> bundles a route, a controller action, and a view (Dyny). Components are subclassable,
+> giving inheritance for views and controller logic, DRY CRUD via pre-built components,
+> a model mixin for fields and feasibility, and an intent system for linking components.
+
+Read CLAUDE.md first for the mental model and the public API surface. Source of truth for
+behavior is the Ruby source under lib/compony/; the guide pages below explain intent.
+
+## Agent entrypoints
+
+- [Agent primer](/CLAUDE.md): mental model, public API table, source layout, conventions.
+- [DSL reference](/doc/guide/dsl_reference.md): every setup/standalone/form/list DSL method with signature and context.
+- [Glossary](/doc/guide/glossary.md): one-line definitions of Compony vocabulary.
+- [Gotchas](/doc/guide/gotchas.md): numbered anti-patterns — symptom, cause, fix.
+- [Real-world patterns](/doc/guide/patterns.md): 18 recurring idioms from production apps (base layer, thin leaves, tabs, exports, jobs, virtual models, webhooks, turbo-frame inline edit, multi-step wizard, inline PATCH, signed-token capability links).
+- [Cookbook](/doc/guide/cookbook.md): pure task→pointer index ("I want to do X") into patterns/guide; no duplicated content.
+- [Integrations](/doc/integrations.md): companion gems — hard runtime deps (versions), optional feature-unlocking gems, app-side companions.
+- [Maintaining](/doc/guide/maintaining.md): contributor/AI policy — CHANGELOG per change, release steps, .yardopts, dependency + anonymization rules.
+
+## Guide — concepts
+
+- [README](/README.md): what Compony is, key aspects, caveats, guide index.
+- [Self-contained example](/doc/guide/example.md): full small app (model, Show, Destroy, New, Form, Edit, Index).
+- [Advanced example](/doc/guide/example_advanced.md): custom form, virtual fields, CSV export, exposed intents, feasibility, before_render guard.
+- [Installation](/doc/guide/installation.md): setup steps.
+- [Basic component](/doc/guide/basic_component.md): naming, setup, labelling, content blocks, before_render.
+- [Standalone](/doc/guide/standalone.md): routing, verbs, authorize, respond, formats, scopes, constraints.
+- [Inheritance](/doc/guide/inheritance.md): DRYing via base components.
+- [Nesting](/doc/guide/nesting.md): sub_comp, embedding components.
+- [Resourceful](/doc/guide/resourceful.md): @data auto-loading, load_data.
+- [Intents](/doc/guide/intents.md): Compony.path, render_intent, render_sub_comp, buttons/styles, exposed_intents.
+- [Feasibility](/doc/guide/feasibility.md): prevent, feasible?, disabling buttons.
+- [Ownership](/doc/guide/ownership.md): owned_by, owner-aware redirects.
+- [Model fields](/doc/guide/model_fields.md): field types, value_for, auto-generated UI.
+- [Generators](/doc/guide/generators.md): rails g component / components.
+- [Internal datastructures](/doc/guide/internal_datastructures.md): RequestContext, MethodAccessibleHash.
+- [Virtual models](/doc/guide/virtual_models.md): non-persistent ActiveType-backed models.
+
+## Guide — pre-built components
+
+- [Introduction](/doc/guide/pre_built_components.md): overview of shipped CRUD components.
+- [Show](/doc/guide/pre_built_components/show.md): Rails show equivalent.
+- [Index](/doc/guide/pre_built_components/index.md): Rails index equivalent.
+- [List](/doc/guide/pre_built_components/list.md): Rails _list partial equivalent (columns, filters, sorts, pagination).
+- [Destroy](/doc/guide/pre_built_components/destroy.md): Rails destroy equivalent.
+- [WithForm](/doc/guide/pre_built_components/with_form.md): base for form-submitting components.
+- [Form](/doc/guide/pre_built_components/form.md): Rails _form partial equivalent (form_fields, schema_*).
+- [New](/doc/guide/pre_built_components/new.md): Rails new+create equivalent.
+- [Edit](/doc/guide/pre_built_components/edit.md): Rails edit+update equivalent.
+
+## Source (behavior source of truth)
+
+- lib/compony.rb: Compony.* module methods (public API).
+- lib/compony/component.rb: base Component DSL (setup, content, before_render, exposed_intents).
+- lib/compony/intent.rb: Intent — path, label, feasibility, button rendering.
+- lib/compony/component_mixins/resourceful.rb: @data lifecycle hooks.
+- lib/compony/component_mixins/default/standalone/: routing DSL (standalone/verb/respond/authorize).
+- lib/compony/components/: pre-built component implementations.
+- lib/compony/model_mixin.rb: model-side field/prevent/owned_by.
+- lib/compony/virtual_model.rb: VirtualModel base.

data/doc/top-level-namespace.html

@@ -102,7 +102,7 @@
 </div>
 
       <div id="footer">
-  Generated on Fri May 15 10:29:33 2026 by
+  Generated on Mon May 18 13:55:34 2026 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.3.5).
 </div>

data/lib/compony/component.rb

@@ -123,7 +123,12 @@ module Compony
     # Overrides how the path to this component should be generated.
     # The block will be given the following args: a model (optional), pos. args for the path helper, the kwarg `standalone_name` and kwargs for the path helper.
     # The block is expected to return a Rails path. It is not given `controller` or `helpers`, instead use: `Rails.application.routes.url_helpers`.
-    # For an example, refer to the initializer of this class, where the default block is defined.
+    # For the default block, refer to the initializer of this class.
+    # Useful when callers should pass a higher-level argument that is translated into path params here, e.g. minting a
+    # signed token into the URL so an unauthenticated link can authorize itself. Worked examples:
+    # see `doc/guide/standalone.md` ("Customizing path generation") and `doc/guide/patterns.md` §18 (signed-token capability links).
+    # @return [void] when defining (block given); otherwise the generated Rails path String.
+    # @api public
     def path(*, **, &block)
       if block_given?
         # Assignment via DSL
@@ -214,8 +219,8 @@ module Compony
     end
 
     # DSL method
-    # If a block is given: Enters the DSL where exposed intents can be added or removed (use from {Component#setup} within the component).
-    # If no block is given: Builds the declared intents and returns them (use from a {RequestContest} outside the component).
+    # If a block is given: Enters the DSL where exposed intents can be added or removed (use from {Compony::Component.setup} within the component).
+    # If no block is given: Builds the declared intents and returns them (use from a {Compony::RequestContext} outside the component).
     def exposed_intents(&block)
       if block_given?
         # Enter DSL