compony 0.11.8 → 0.11.9

data/doc/file_list.html

@@ -49,6 +49,166 @@
   </li>
   
 
+  <li id="object_CHANGELOG" class="even">
+    <div class="item"><span class="object_link"><a href="file.CHANGELOG.html" title="CHANGELOG">CHANGELOG</a></span></div>
+  </li>
+  
+
+  <li id="object_installation" class="odd">
+    <div class="item"><span class="object_link"><a href="file.installation.html" title="installation">installation</a></span></div>
+  </li>
+  
+
+  <li id="object_example" class="even">
+    <div class="item"><span class="object_link"><a href="file.example.html" title="example">example</a></span></div>
+  </li>
+  
+
+  <li id="object_example_advanced" class="odd">
+    <div class="item"><span class="object_link"><a href="file.example_advanced.html" title="example_advanced">example_advanced</a></span></div>
+  </li>
+  
+
+  <li id="object_basic_component" class="even">
+    <div class="item"><span class="object_link"><a href="file.basic_component.html" title="basic_component">basic_component</a></span></div>
+  </li>
+  
+
+  <li id="object_standalone" class="odd">
+    <div class="item"><span class="object_link"><a href="file.standalone.html" title="standalone">standalone</a></span></div>
+  </li>
+  
+
+  <li id="object_inheritance" class="even">
+    <div class="item"><span class="object_link"><a href="file.inheritance.html" title="inheritance">inheritance</a></span></div>
+  </li>
+  
+
+  <li id="object_nesting" class="odd">
+    <div class="item"><span class="object_link"><a href="file.nesting.html" title="nesting">nesting</a></span></div>
+  </li>
+  
+
+  <li id="object_resourceful" class="even">
+    <div class="item"><span class="object_link"><a href="file.resourceful.html" title="resourceful">resourceful</a></span></div>
+  </li>
+  
+
+  <li id="object_intents" class="odd">
+    <div class="item"><span class="object_link"><a href="file.intents.html" title="intents">intents</a></span></div>
+  </li>
+  
+
+  <li id="object_feasibility" class="even">
+    <div class="item"><span class="object_link"><a href="file.feasibility.html" title="feasibility">feasibility</a></span></div>
+  </li>
+  
+
+  <li id="object_ownership" class="odd">
+    <div class="item"><span class="object_link"><a href="file.ownership.html" title="ownership">ownership</a></span></div>
+  </li>
+  
+
+  <li id="object_model_fields" class="even">
+    <div class="item"><span class="object_link"><a href="file.model_fields.html" title="model_fields">model_fields</a></span></div>
+  </li>
+  
+
+  <li id="object_generators" class="odd">
+    <div class="item"><span class="object_link"><a href="file.generators.html" title="generators">generators</a></span></div>
+  </li>
+  
+
+  <li id="object_internal_datastructures" class="even">
+    <div class="item"><span class="object_link"><a href="file.internal_datastructures.html" title="internal_datastructures">internal_datastructures</a></span></div>
+  </li>
+  
+
+  <li id="object_virtual_models" class="odd">
+    <div class="item"><span class="object_link"><a href="file.virtual_models.html" title="virtual_models">virtual_models</a></span></div>
+  </li>
+  
+
+  <li id="object_pre_built_components" class="even">
+    <div class="item"><span class="object_link"><a href="file.pre_built_components.html" title="pre_built_components">pre_built_components</a></span></div>
+  </li>
+  
+
+  <li id="object_show" class="odd">
+    <div class="item"><span class="object_link"><a href="file.show.html" title="show">show</a></span></div>
+  </li>
+  
+
+  <li id="object_index" class="even">
+    <div class="item"><span class="object_link"><a href="file.index.html" title="index">index</a></span></div>
+  </li>
+  
+
+  <li id="object_list" class="odd">
+    <div class="item"><span class="object_link"><a href="file.list.html" title="list">list</a></span></div>
+  </li>
+  
+
+  <li id="object_destroy" class="even">
+    <div class="item"><span class="object_link"><a href="file.destroy.html" title="destroy">destroy</a></span></div>
+  </li>
+  
+
+  <li id="object_with_form" class="odd">
+    <div class="item"><span class="object_link"><a href="file.with_form.html" title="with_form">with_form</a></span></div>
+  </li>
+  
+
+  <li id="object_form" class="even">
+    <div class="item"><span class="object_link"><a href="file.form.html" title="form">form</a></span></div>
+  </li>
+  
+
+  <li id="object_new" class="odd">
+    <div class="item"><span class="object_link"><a href="file.new.html" title="new">new</a></span></div>
+  </li>
+  
+
+  <li id="object_edit" class="even">
+    <div class="item"><span class="object_link"><a href="file.edit.html" title="edit">edit</a></span></div>
+  </li>
+  
+
+  <li id="object_dsl_reference" class="odd">
+    <div class="item"><span class="object_link"><a href="file.dsl_reference.html" title="dsl_reference">dsl_reference</a></span></div>
+  </li>
+  
+
+  <li id="object_glossary" class="even">
+    <div class="item"><span class="object_link"><a href="file.glossary.html" title="glossary">glossary</a></span></div>
+  </li>
+  
+
+  <li id="object_gotchas" class="odd">
+    <div class="item"><span class="object_link"><a href="file.gotchas.html" title="gotchas">gotchas</a></span></div>
+  </li>
+  
+
+  <li id="object_patterns" class="even">
+    <div class="item"><span class="object_link"><a href="file.patterns.html" title="patterns">patterns</a></span></div>
+  </li>
+  
+
+  <li id="object_cookbook" class="odd">
+    <div class="item"><span class="object_link"><a href="file.cookbook.html" title="cookbook">cookbook</a></span></div>
+  </li>
+  
+
+  <li id="object_integrations" class="even">
+    <div class="item"><span class="object_link"><a href="file.integrations.html" title="integrations">integrations</a></span></div>
+  </li>
+  
+
+  <li id="object_maintaining" class="odd">
+    <div class="item"><span class="object_link"><a href="file.maintaining.html" title="maintaining">maintaining</a></span></div>
+  </li>
+  
+
 
       </ul>
     </div>

data/doc/guide/cookbook.md

@@ -0,0 +1,41 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Cookbook
+
+Task-oriented entry point: "I want to do X — where is it?". Every recipe lives in
+[Real-world patterns](./patterns.md) or the guide; this page is a pure index by goal so
+you don't need to know a pattern's name. Nothing is duplicated here — only links.
+
+## Recipes by task
+
+| I want to… | See |
+| --- | --- |
+| Share layout/chrome across all components | [patterns §1 base layer](./patterns.md#1-the-app-base-component-layer) |
+| Add a CRUD screen with almost no code | [patterns §2 thin leaves](./patterns.md#2-thin-leaf-components), [example.md](./example.md) |
+| List records with columns/filters/sorts | [List](./pre_built_components/list.md), [patterns §3–4](./patterns.md#3-index--load_data-scope--nested-list) |
+| Scope/order what an Index shows | [patterns §3](./patterns.md#3-index--load_data-scope--nested-list) (`load_data`) |
+| Embed a child list inside a Show | [patterns §4](./patterns.md#4-list-customization), [nesting.md](./nesting.md) |
+| Build a custom form + strong params | [patterns §5](./patterns.md#5-custom-form--schemacop-kept-in-sync), [Form](./pre_built_components/form.md) |
+| Nested attributes in a form | [patterns §5](./patterns.md#5-custom-form--schemacop-kept-in-sync), [example_advanced.md](./example_advanced.md) |
+| Autocomplete / ajax select field | [patterns §6](./patterns.md#6-autocomplete-form-app-level-subclass) |
+| Split a detail page into tabs | [patterns §7](./patterns.md#7-tabbed-show-via-a-mixin) |
+| Prefill/derive fields before save | [patterns §8](./patterns.md#8-lifecycle-hooks-for-derived-data) (`after_assign_attributes`) |
+| Guard/redirect before rendering | [patterns §8](./patterns.md#8-lifecycle-hooks-for-derived-data), [basic_component.md](./basic_component.md#redirecting-away--intercepting-rendering) |
+| Customize the action toolbar | [patterns §9](./patterns.md#9-exposed-intents-as-the-action-toolbar), [intents.md](./intents.md#exposed-intents) |
+| Disable a button with a reason | [feasibility.md](./feasibility.md), [patterns §9](./patterns.md#9-exposed-intents-as-the-action-toolbar) |
+| Export CSV / PDF | [patterns §10](./patterns.md#10-csv--pdf-via-respond-format) |
+| Launch a background job from a button | [patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone) |
+| Toggle a boolean (activate/lock/…) | [patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone) |
+| Clone/duplicate a record | [patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone) |
+| Non-persistent / upload-only form | [patterns §12](./patterns.md#12-virtual-model-for-non-persistent--upload-forms), [virtual_models.md](./virtual_models.md) |
+| Public page / inbound webhook | [patterns §13](./patterns.md#13-public-endpoints--webhooks), [gotchas §14](./gotchas.md#14-public-endpoint-still-401redirecting) |
+| Custom button look | [patterns §14](./patterns.md#14-custom-button-style), [intents.md](./intents.md#adding-your-own-styles) |
+| Inline-edit a card without a full page | [patterns §15 turbo-frame inline edit](./patterns.md#15-inline-edit-card-with-a-turbo-frame) |
+| Multi-step wizard across components | [patterns §16 multi-step wizard](./patterns.md#16-multi-step-wizard-across-components) |
+| Reorder/inline-patch without a form | [patterns §17 inline PATCH](./patterns.md#17-inline-patch-without-a-form-reorder--quick-toggle) |
+| Magic-login / invite / reset / confirm link (no session) | [patterns §18 signed-token capability links](./patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links) |
+
+If a goal isn't listed, check the [DSL reference](./dsl_reference.md) and
+[glossary](./glossary.md).
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/dsl_reference.md

@@ -0,0 +1,155 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# DSL reference
+
+Flat lookup of every Compony DSL method, its calling context, signature, and a one-line
+description. This page is generated from `# DSL method` markers in the source — when in
+doubt the Ruby source under `lib/compony/` is authoritative. "Context" says where the call
+is legal.
+
+Contexts:
+
+- **class** — directly in the component class body.
+- **setup** — inside `setup do ... end`.
+- **standalone** — inside `standalone do ... end`.
+- **verb** — inside `verb :x do ... end`.
+- **form_fields** — inside a Form component's `form_fields do ... end`.
+- **content** — inside a `content do ... end` block (a RequestContext).
+- **model** — in an `ActiveRecord`/model class that `include`s the model mixin.
+
+## Component definition
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `setup` | class | `setup { block }` | Main config block. Runs at end of init; parent runs before child. |
+| `label` | setup | `label(:short/:long/:all) { \|model\| ... }` | Component title + link/button text. Resourceful comps take 1 block arg. |
+| `color` | setup | `color { '#AA0000' }` | Component color (not used by Compony itself). |
+| `icon` | setup | `icon { %i[fa-solid circle] }` | Component icon (not used by Compony itself). |
+| `content` | setup | `content(name = :main, before: nil, hidden: false) { block }` | Define/replace a named view block (Dyny). `hidden: true` = don't auto-render. Non-obvious use: hidden `:main` + `:wrapper` chrome → [patterns §1](/doc/guide/patterns.md#1-the-app-base-component-layer). |
+| `content` | content | `content(:name)` | Render another content block of the *same* component (nesting). [patterns §1](/doc/guide/patterns.md#1-the-app-base-component-layer). |
+| `remove_content` | setup | `remove_content(:name)` | Remove an inherited content block (returns false if absent). |
+| `remove_content!` | setup | `remove_content!(:name)` | Same, raises if the block was not found. |
+| `before_render` | setup | `before_render(name = :main, before: nil) { block }` | Pre-content hook. If it sets a response body (e.g. redirect), content is skipped. Non-obvious uses: verb-independent guard → [patterns §8](/doc/guide/patterns.md#8-lifecycle-hooks-for-derived-data); wizard step nav → [patterns §16](/doc/guide/patterns.md#16-multi-step-wizard-across-components). |
+| `exposed_intents` | setup | `exposed_intents { add ...; remove ... }` | Declare intents the layout/parent renders. See `add`/`remove`, and the toolbar pattern → [patterns §9](/doc/guide/patterns.md#9-exposed-intents-as-the-action-toolbar). |
+| `path` | setup | `path { \|model, *args, standalone_name:, **kw\| ... }` | Override path generation for this component (advanced). Runs outside the request context — build URLs via `Rails.application.routes.url_helpers`. Non-obvious use: mint a signed token into the URL → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links); see also [standalone.md](/doc/guide/standalone.md#customizing-path-generation). |
+
+`exposed_intents` DSL (inside its block):
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `add` | `add(comp, model_or_family, before: nil, **intent_opts)` | Add/replace an exposed intent (keyed by intent name). |
+| `remove` | `remove(:intent_name)` | Remove a previously added exposed intent. |
+
+## Standalone (routing)
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `standalone` | setup | `standalone(name = nil, path:, constraints: nil, scope: nil, scope_args: {}) { ... }` | Generate a Rails route. Non-obvious use: a *named* extra `standalone` for an ajax companion endpoint of the same screen → [patterns §17](/doc/guide/patterns.md#17-inline-patch-without-a-form-reorder--quick-toggle). |
+| `verb` | standalone | `verb(:get/:post/:patch/:put/:delete/...) { ... }` | Config one HTTP verb. Up to once per verb per standalone. |
+| `skip_authentication!` | standalone | `skip_authentication!` | Disable app authentication for this standalone (still need `authorize`). Non-obvious use: token-gated auth-less links → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links). |
+| `skip_forgery_protection!` | standalone | `skip_forgery_protection!` | Disable CSRF for this standalone's action. Non-obvious use: inbound webhooks → [patterns §13](/doc/guide/patterns.md#13-public-endpoints--webhooks). |
+| `layout` | standalone | `layout('layouts/backend')` | Rails layout for this standalone. Defaults to `layouts/application`. Centralize in the base layer → [patterns §1](/doc/guide/patterns.md#1-the-app-base-component-layer). |
+| `authorize` | verb | `authorize { can?(:read, @data) }` | **Mandatory.** Truthy = access; falsy → `CanCan::AccessDenied`. Non-obvious use: validate a signed token → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links). |
+| `respond` | verb | `respond(format = nil) { ... }` | Override the controller response (e.g. send_data, render json, redirect). Overriding `nil` format **skips `authorize`** — re-check yourself. Non-obvious uses: CSV/PDF export → [patterns §10](/doc/guide/patterns.md#10-csv--pdf-via-respond-format); ajax-only PATCH → [patterns §17](/doc/guide/patterns.md#17-inline-patch-without-a-form-reorder--quick-toggle). |
+
+## Resourceful lifecycle hooks
+
+Available in **setup** (global, all verbs) on resourceful components; the same names also
+work inside a **verb** block to override for one path+verb.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `data_class` | `data_class(NewClass = nil)` | Set/get the model class. Defaults to family name singularized+constantized. Non-obvious use: point at a `VirtualModel` → [patterns §12](/doc/guide/patterns.md#12-virtual-model-for-non-persistent--upload-forms). |
+| `load_data` | `load_data { @data = ... }` | Override record loading. Default: `data_class.find(params[:id])`. Runs before `authorize`. Non-obvious uses: Index scope → [patterns §3](/doc/guide/patterns.md#3-index--load_data-scope--nested-list); load+dup for clone → [patterns §11](/doc/guide/patterns.md#11-non-crud-job-dispatch-toggles-clone). |
+| `after_load_data` | `after_load_data { ... }` | Runs after `load_data`, before `authorize`. Refine an AR relation here. |
+| `assign_attributes` | `assign_attributes { ... }` | Assign validated params onto `@data`. Pre-built forms supply a default. |
+| `after_assign_attributes` | `after_assign_attributes { ... }` | After `assign_attributes`, before `store_data`. Prefill/derive fields here → [patterns §8](/doc/guide/patterns.md#8-lifecycle-hooks-for-derived-data); seed from a token → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links). |
+| `store_data` | `store_data { @data.save }` | Persist `@data`. Override for virtual models / uploads → [patterns §12](/doc/guide/patterns.md#12-virtual-model-for-non-persistent--upload-forms), or to enqueue work / multi-record txn → [patterns §11](/doc/guide/patterns.md#11-non-crud-job-dispatch-toggles-clone). |
+
+## Form component DSL
+
+`class Components::X::Form < Compony::Components::Form`
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `form_fields` | setup | `form_fields { ... }` | **Mandatory.** Block holding the form inputs (Dyny + `field`/`f`). |
+| `field` | form_fields | `field(:name, multilang: false, **simple_form_opts)` | Render a simple_form input inferred from the model field. `as:`/`hidden:` supported. |
+| `pw_field` | form_fields | `pw_field(:password, **opts)` | Password input; checks `:set_password` ability. |
+| `f` | form_fields | `f` | The underlying `simple_form` builder (for `f.rich_text_area` etc.). |
+| `collect` | form_fields | `collect(...)` | Wrap a collection in Rails-compatible format (Anchormodel helper). |
+| `schema_field` | setup | `schema_field(:name, multilang: false)` | Whitelist one field in the Schemacop param schema. For associations use the **association name**, not `_id`. |
+| `schema_fields` | setup | `schema_fields(:a, :b, ...)` | Mass `schema_field`. |
+| `schema_pw_field` | setup | `schema_pw_field(:password)` | Whitelist a password param (checks `:set_password`). |
+| `schema_line` | setup | `schema_line { str? :foo }` | Add a raw Schemacop3 line (nested attrs, custom shapes) → [patterns §5](/doc/guide/patterns.md#5-custom-form--schemacop-kept-in-sync). |
+| `schema` | setup | `schema(:wrapper_key) { ... }` | Replace the whole schema + wrapper key (fully manual). |
+| `form_params` | setup | `form_params(**opts)` | Extra kwargs passed to `simple_form_for`. |
+| `disable!` | setup | `disable!` | Render all inputs disabled. |
+| `skip_autofocus` | setup | `skip_autofocus` | Don't autofocus the first field. |
+
+WithForm / New / Edit wiring (in the New/Edit component's `setup`):
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `submit_verb` | `submit_verb(:patch)` | HTTP verb the form submits with (`:post` for New, `:patch` for Edit). |
+| `form_comp_class` | `form_comp_class(Components::X::MyForm)` | Use a custom Form component instead of `Components::<Family>::Form`. Non-obvious uses: non-default form → [patterns §5](/doc/guide/patterns.md#5-custom-form--schemacop-kept-in-sync); token-gated signup → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links). |
+| `form_cancancan_action` | `form_cancancan_action(:edit)` | CanCanCan action used for per-field `permitted_attributes`. Pass `nil` to disable per-field auth (e.g. token-gated forms → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links)). |
+| `submit_path` | `submit_path { Compony.path(...) }` | Override where the form POSTs/PATCHes to. Non-obvious use: carry a token through submit → [patterns §18](/doc/guide/patterns.md#18-signed-token-capability-links-auth-less-onboarding--magic-links). |
+| `on_created` / `on_updated` | `on_created { ... }` | Post-save, pre-respond hook (success). |
+| `on_created_respond` / `on_updated_respond` | `... { ... }` | Override the success response (default: flash + redirect). |
+| `on_created_redirect_path` / `on_updated_redirect_path` | `... { path }` | Override the success redirect target. Non-obvious use: chain wizard steps → [patterns §16](/doc/guide/patterns.md#16-multi-step-wizard-across-components). |
+| `on_create_failed_respond` / `on_update_failed` | `... { ... }` | Override the validation-failure response. |
+| `on_destroyed` / `on_destroyed_respond` / `on_destroyed_redirect_path` | `... { ... }` | Destroy component equivalents. |
+
+## List / Index component DSL
+
+`Compony::Components::List` (nest in Index or owner Show); `Compony::Components::Index`.
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `column` | setup | `column(:name, label: nil, class: nil, link_opts: {}) { \|record\| ... }` | Add/define a column; block renders the cell. |
+| `columns` | setup | `columns(:a, :b, as_title: false)` | Add several field-based columns. `as_title: true` = card title on mobile. |
+| `filter` | setup | `filter(:name, label: nil) { \|f\| ... }` | Add/define a filter; block customizes the input. |
+| `filters` | setup | `filters(:a, :b)` | Add several filters. |
+| `sort` | setup | `sort(:name, label: nil)` | Add a sort option. |
+| `sorts` | setup | `sorts(:a, :b)` | Add several sort options. |
+| `default_sorting` | setup | `default_sorting('id desc')` | Default Ransack sort string. |
+| `row_intents` | setup | `row_intents(**opts) { add/remove }` | Per-row action buttons (intent DSL) → [patterns §4](/doc/guide/patterns.md#4-list-customization). |
+| `pagination` | setup | `pagination(false)` | Enable/disable pagination (caution: loads all rows). |
+| `results_per_page` | setup | `results_per_page(20)` | Rows per page when paginating. |
+| `filtering` | setup | `filtering(false)` | Enable/disable filtering entirely. |
+| `sorting` | setup | `sorting(false)` | Enable/disable both sorting links and in-filter sorting. |
+| `sorting_in_filter` / `sorting_links` | setup | `sorting_links(false)` | Toggle one sorting UI independently. |
+| `filter_label_class` / `filter_input_class` / `filter_select_class` | setup | `filter_input_class('...')` | CSS classes for filter form elements. |
+| `skip_column` | setup | `skip_column(:name)` | Remove an inherited column (Show/List). |
+
+Many of these also accept `skip_*` kwargs on the constructor when the List is nested via
+`render_sub_comp` (e.g. `render_sub_comp(:list, coll, skip_pagination: true)`).
+
+## Model mixin (in your `ApplicationRecord` models)
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `field` | model (class) | `field(:name, :type, multilang: false, **attrs)` | Declare a UI-relevant attribute + its type/formatting. |
+| `prevent` | model (class) | `prevent(:destroy, 'msg') { condition }` | Feasibility: block returns truthy → action prevented (buttons disabled). |
+| `owned_by` | model (class) | `owned_by(:invoice)` | Mark this model as owned by another; adjusts redirects/top actions. |
+| `skip_autodetect_feasibilities` | model (class) | `skip_autodetect_feasibilities` | Don't auto-derive `:destroy` preventions from `dependent:` associations. |
+| `feasible?` | model (instance) | `record.feasible?(:destroy)` | True if no prevention blocks the action. |
+| `feasibility_messages` | model (instance) | `record.feasibility_messages(:destroy)` | Array of reasons (like `errors`). |
+| `full_feasibility_messages` | model (instance) | `record.full_feasibility_messages(:destroy)` | Joined human string (like `full_messages`). |
+
+`label` is not a DSL method but **every Compony model must implement `def label`** (or have
+a `label` column) — used for titles and link text.
+
+## Intent / navigation helpers
+
+Used from `content` blocks or controllers — see [intents.md](/doc/guide/intents.md).
+
+| Method | Context | Signature | Description |
+| --- | --- | --- | --- |
+| `Compony.intent` | anywhere | `Compony.intent(:show, model, **opts)` | Build an `Intent`. |
+| `Compony.path` | anywhere | `Compony.path(:index, :users, **opts)` | Rails path string (redirects). |
+| `render_intent` | content | `render_intent(:edit, model, style:, label:, button:)` | Render a link/button to a component. Wrap in `concat`. |
+| `render_sub_comp` | content | `render_sub_comp(:list, @data.quotes, **opts)` | Instantiate + nest another component. Wrap in `concat`. |
+| `Compony.comp_class_for` | anywhere | `Compony.comp_class_for(:show, family)` | Comp class or `nil`. |
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/example_advanced.md

@@ -0,0 +1,209 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Advanced example
+
+[example.md](/doc/guide/example.md) shows the basics. This one combines patterns you hit in
+real apps: a custom form, feasibility, exposed intents, a CSV export endpoint, a
+`before_render` guard, and a virtual-model launch form for a background job.
+
+Domain: invoicing. An `Invoice` has line items, can be locked, exported as CSV, and a
+background "send reminders" job can be launched from a non-persistent form.
+
+## The models
+
+```ruby
+# app/models/invoice.rb
+class Invoice < ApplicationRecord
+  has_many :line_items, dependent: :destroy
+  accepts_nested_attributes_for :line_items, allow_destroy: true
+  belongs_to :customer
+
+  field :number,   :string
+  field :customer, :association
+  field :total,    :decimal
+  field :locked,   :boolean
+  field :issued_at, :datetime
+
+  def label = number
+
+  # Feasibility: a locked invoice must not be edited or destroyed.
+  # Back every important prevention with a real validation (see note in feasibility.md).
+  prevent %i[edit destroy], 'the invoice is locked' do
+    locked?
+  end
+  validate { errors.add(:base, 'invoice is locked') if locked_was && locked? }
+end
+
+# app/models/line_item.rb
+class LineItem < ApplicationRecord
+  belongs_to :invoice
+  field :description, :string
+  field :amount,      :decimal
+  def label = description
+end
+```
+
+## Index with a CSV export endpoint and exposed intents
+
+One component, two routes: the HTML list and a `.csv` download. The CSV intent is exposed
+so the layout renders a "Download CSV" button in the page header.
+
+```ruby
+class Components::Invoices::Index < Compony::Component
+  include Compony::ComponentMixins::Resourceful
+
+  setup do
+    label(:all) { 'Invoices' }
+
+    standalone path: 'invoices' do
+      verb :get do
+        authorize { can?(:read, Invoice) }
+        # Default (HTML) response renders content. CSV gets its own response:
+        respond :csv do
+          authorize_csv = can?(:read, Invoice) or raise CanCan::AccessDenied # respond skips authorize!
+          send_data(InvoiceCsv.new(@data).to_csv, filename: 'invoices.csv', type: 'text/csv')
+        end
+      end
+    end
+
+    load_data { @data = Invoice.accessible_by(current_ability).order(issued_at: :desc) }
+
+    exposed_intents do
+      add :index, :invoices, label: 'Download CSV', name: :csv, path: { format: :csv }
+      add :request_reminders, :invoices, label: 'Send reminders', method: :get
+    end
+
+    content do
+      concat render_intent(:new, :invoices, button: { label: { format: :short } })
+      concat render_sub_comp(:list, @data)
+    end
+  end
+end
+```
+
+Notes:
+
+- `respond :csv` handles `GET /invoices.csv`. Because overriding `respond` **skips the
+  default `authorize`** (see [gotchas.md](/doc/guide/gotchas.md#3-overriding-respond-skips-authorization)),
+  the CSV branch re-checks the ability itself.
+- `path: { format: :csv }` on the exposed intent makes its button point at `.csv`.
+- The layout renders exposed intents of `Compony.root_comp` — see
+  [intents.md](/doc/guide/intents.md#rendering-exposed-intents).
+
+## A custom Form with nested line items
+
+`Edit`/`New` look for `Components::Invoices::Form` by default. We write it with
+`accepts_nested_attributes_for` via `simple_form`'s `simple_fields_for`, and whitelist the
+nested params with a raw `schema_line`.
+
+```ruby
+class Components::Invoices::Form < Compony::Components::Form
+  setup do
+    form_fields do
+      concat field(:number)
+      concat field(:customer, as: :tom_select) # association name, NOT customer_id
+      concat field(:issued_at, as: :flatpickr_datetime)
+      concat(f.simple_fields_for(:line_items) do |lf|
+        concat lf.input(:description)
+        concat lf.input(:amount)
+      end)
+    end
+
+    schema_fields :number, :customer, :issued_at
+    # Nested attributes need a manual Schemacop line:
+    schema_line do
+      ary? :line_items_attributes do
+        list :hash do
+          int? :id
+          str? :description
+          num? :amount
+          boo? :_destroy
+        end
+      end
+    end
+  end
+end
+```
+
+`schema_field :customer` (association name) lets Compony add `customer_id` automatically —
+passing `:customer_id` here would not work
+([gotchas.md](/doc/guide/gotchas.md#4-schema_field-with-the-foreign-key-name)).
+
+## Edit: thin, plus a guard and a custom redirect
+
+`Edit` inherits all CRUD wiring. We only add a `before_render` guard (independent of HTTP
+verb) and override where a successful save lands.
+
+```ruby
+class Components::Invoices::Edit < Compony::Components::Edit
+  setup do
+    before_render do
+      if @data.locked?
+        flash.alert = 'This invoice is locked.'
+        redirect_to Compony.path(:show, @data)
+      end
+    end
+
+    on_updated_redirect_path { Compony.path(:show, @data) }
+  end
+end
+```
+
+The `prevent :edit` in the model already greys out the edit button with a tooltip; the
+`before_render` guard plus the model validation stop a hand-crafted request
+([feasibility.md](/doc/guide/feasibility.md) explains why all three layers are needed).
+
+`Components::Invoices::New`, `Show`, `Destroy` can stay empty — the pre-built parents do
+the work.
+
+## A virtual-model launch form for a background job
+
+"Send reminders" should pop a small form (which customers? how many days overdue?) and, on
+submit, queue a job — nothing is persisted. Inherit `New`, back it with a
+`Compony::VirtualModel`, and take over `on_created_respond`.
+
+```ruby
+class Components::Invoices::RequestReminders < Compony::Components::New
+  class VirtualModel < Compony::VirtualModel
+    attribute :min_days_overdue, :integer, default: 7
+    attribute :only_locked,      :boolean, default: false
+    field :min_days_overdue, :integer
+    field :only_locked,      :boolean
+    validates :min_days_overdue, numericality: { greater_than: 0 }
+    def label = 'Reminder request'
+  end
+
+  class Form < Compony::Components::Form
+    setup do
+      form_fields do
+        concat field(:min_days_overdue)
+        concat field(:only_locked)
+      end
+      schema_fields :min_days_overdue, :only_locked
+    end
+  end
+
+  setup do
+    standalone path: 'invoices/request_reminders' # avoid clashing with the New route
+    data_class VirtualModel
+    form_comp_class Components::Invoices::RequestReminders::Form
+    label(:all) { 'Send reminders' }
+
+    # @data.save is a no-op (virtual). on_created_respond fires only after validations pass.
+    on_created_respond do
+      SendRemindersJob.perform_later(min_days_overdue: @data.min_days_overdue,
+                                     only_locked:      @data.only_locked)
+      flash.notice = 'Reminders queued — give it a few minutes.'
+      redirect_to Compony.path(:index, :invoices)
+    end
+  end
+end
+```
+
+Why it works: inheriting `New` gives the `new`/`create` flow. On submit Compony validates,
+re-renders the form with errors on failure, otherwise calls `@data.save` (a no-op on a
+virtual model) and runs `on_created_respond`, where you regain control. For ActiveStorage
+on a virtual model, also override `store_data` to only `validate` — see
+[virtual_models.md](/doc/guide/virtual_models.md).
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/generators.md

@@ -10,6 +10,6 @@ To make your life easier and coding faster, Compony comes with two generators:
 
 ### Support for custom base components
 
-Generators will automatically detect your `BaseComponents` (see [Inheritance: best practice](./doc/guide/inheritance.md#best-practice)).
+Generators will automatically detect your `BaseComponents` (see [Inheritance: best practice](./inheritance.md#best-practice)).
 
 [Guide index](/README.md#guide--documentation)

data/doc/guide/glossary.md

@@ -0,0 +1,42 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Glossary
+
+One-line definitions of Compony vocabulary. Deeper treatment is linked.
+
+| Term | Definition |
+| --- | --- |
+| **Component** | A Ruby class (`Components::Family::Name`) bundling a route, controller action and view. See [basic_component.md](/doc/guide/basic_component.md). |
+| **Family** | The plural namespace grouping a model's components, analogous to a Rails controller (`Users`). |
+| **Comp name** | The component's own name, analogous to a Rails action (`show`). |
+| **`setup`** | Class-level block holding nearly all component config; parent's runs before child's. |
+| **Content block** | A named (`:main` default) view block rendered via Dyny inside a RequestContext. |
+| **`before_render`** | Hook chain run before content; if it sets a response body (e.g. redirect) content is skipped. |
+| **Standalone** | A `standalone` config that makes Compony emit a Rails route for the component. See [standalone.md](/doc/guide/standalone.md). |
+| **Standalone name** | Identifier for one of several routes a component exposes; `nil` = the main one. |
+| **Verb** | An HTTP method config inside a standalone (`verb :get do ... end`). |
+| **`authorize`** | Mandatory per-verb block; truthy grants access, falsy raises `CanCan::AccessDenied`. |
+| **`respond`** | Per-verb block overriding the controller response; overriding it skips the default authorize step. |
+| **Resourceful** | A component that auto-loads a record/relation into `@data` (mixin or pre-built parent). See [resourceful.md](/doc/guide/resourceful.md). |
+| **`@data`** | The record (or AR relation) a resourceful component operates on. |
+| **`data_class`** | The model class a resourceful component expects; defaults from the family name. |
+| **Lifecycle hooks** | `load_data → after_load_data → authorize → assign_attributes → after_assign_attributes → store_data`. |
+| **Intent** | A gateway object to a target component carrying context (model, path, feasibility, label). See [intents.md](/doc/guide/intents.md). |
+| **Exposed intent** | An intent a component declares for its parent/layout to render (e.g. an actions toolbar). |
+| **`Compony.path`** | Helper that builds a Rails path string via an intent (use for redirects). |
+| **`render_intent`** | Content/view helper that renders a link or button to another component. |
+| **`render_sub_comp`** | Content helper that instantiates and nests another component. |
+| **Sub comp / parent comp** | A component instantiated inside another; the outer one is its `parent_comp`. |
+| **Root comp** | The top component of the current render tree (no parent); `Compony.root_comp`. |
+| **RequestContext** | Dslblend object content blocks run in: providers are the component, controller, helpers. See [internal_datastructures.md](/doc/guide/internal_datastructures.md). |
+| **Backfire** | Dslblend mechanism copying instance vars set in a block back onto the component. |
+| **Button / style** | A presenter component for an intent; `style` (`:css_button`, `:link`, custom) selects the class. |
+| **Feasibility** | Framework where model `prevent` blocks disable buttons/links to an action with a reason. See [feasibility.md](/doc/guide/feasibility.md). |
+| **`prevent`** | Model class DSL declaring a feasibility prevention for one or more actions. |
+| **Field** | A model-level declaration (`field :name, :type`) of a UI-relevant attribute and its formatting. See [model_fields.md](/doc/guide/model_fields.md). |
+| **Ownership / `owned_by`** | Declares a model conceptually part of another, adjusting redirects/top actions. See [ownership.md](/doc/guide/ownership.md). |
+| **Virtual model** | A non-persistent ActiveType-backed model usable as a form target. See [virtual_models.md](/doc/guide/virtual_models.md). |
+| **Dyny** | The HTML-as-Ruby templating gem content blocks are written in ([repo](https://github.com/kalsan/dyny)). |
+| **Abstract component** | A component never routed directly, only inherited from (e.g. an app's `BaseComponents::*`). |
+
+[Guide index](/README.md#guide--documentation)