compony 0.7.1 → 0.8.0

data/doc/guide/intents.md

@@ -0,0 +1,167 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Intents
+
+An intent is a gateway to a component, along with relevant context. It encapsulates tools used to generate paths, checking [feasibility](/doc/guide/feasibility.md) and rendering links and buttons pointing other components within your application.
+
+To instanciate an intent, use either the raw `Compony.intent` method or one of the [helpers](#helpers). All methods that use intents under the hood have a similar interface, especially regarding the first two positional arguments. The most commonly used forms are:
+
+- `Compony.intent(:index, :users)`: point to a component by its comp and family name
+- `Compony.intent(:show, User.first)`: pass the intent a single model and let it figure out the family name from `model_name`
+- `Compony.intent(:list, current_user.quotes)`: pass the intent an active record collection and let it figure out the family name from `model_name`
+- `Compony.intent(Components::Users::Index)`: point to a component by giving its class as a single argument
+
+The returned intent can then be used to:
+
+- Retrieve the target component class using `intent.comp_class`
+- Build an instance of the target component using `intent.comp`
+    - If a model was given when building the intent, such as in the second form above, the comp instance will contain it as `@data`.
+- Retrieve the `path` to the target component (only works for standalone components; will automatically set ID parameter if a model was given)
+- Retrieve the `name` that can be used to store the intent in a hash or similar
+- Retrieve the `label` that can be used to refer to the component (if a model was given, passes it to the target component's label block)
+- Check for [feasibility](/doc/guide/feasibility.md) using `feasible?`
+- Render a [button](#buttons-and-styles) to the target component which automatically includes all of the above along with the suitable behavior using `render` and passing a controller
+
+An intent's behavior can be customized by passing some of the following keyword arguments when building it:
+
+- `standalone_name` allows you to point to another endpoint within your target component, which is especially useful for generating paths. Keep in mind that within each standalone name, multiple HTTP methods can exist. This argument defaults to `nil`, which is the main endpoint created by `standalone`.
+- `method` defines the HTTP verb within the standalone configuration that should be addressed. Defaults to `:get`, but can be overriden to be `:patch`, `:put`, `:post` or `:delete`. When generating a button, the `turbo_method` will be automatically be derived from this argument.
+- `name` overrides the auto-generated name of the intent, affecting the result of the reader of the same name.
+- `label` accepts two forms:
+    - When passing a String, it will be returned as-is when returning the label, also affecting buttons generated by this intent.
+    - When passing a Hash, any included key-value pair will be used as keyword arguments to the `label` reader method.
+- `path` allows altering generated paths and accepts either a String or a Hash just like `label`.
+- `data` and `data_class` will be given to the target component if/when it gets instanciated. This is used to point to [resourceful](/doc/guide/resourceful.md) components. If a model was passed as the second positional argument (instead of a family name), it will become `data` and this argument can be omitted. If `data` responds to `model_name`, it will be considered a model-like class.
+- `feasibility_target` and `feasibility_action` can be given to alter the behavior of the `feasible?` reader.
+- Any further arguments are passed to the initializer of the button if/when the intent gets rendered.
+
+## Helpers
+
+In practice, you will rarely call `Compony.intent` directly, and likely never `Compony::Intent.new`. Instead, you will be interacting with one of the following helpers that will instanciate an intent under the hood and thus all accept similar arguments as those described above:
+
+### `Compony.path`
+
+This helper is useful when generating paths without rendering any HTML, such as when redirecting. Internally, this builds an intent which will in turn use the target component's `path` block to generate a Rails path (String) pointing to the correct location. Any keyword arguments are passed to the intent's `path` method, allowing you to override the model (to refer to [resourceful](/doc/guide/resourceful.md) target components), as well as specifying a `standalone_name` or pass extra arguments to the target component's `path` block.
+
+Examples:
+
+```ruby
+redirect_to Compony.path(:index, :users) # Redirects to /users
+redirect_to Compony.path(:show, @data.author) # Redirects to something like /authors/42
+redirect_to Compony.path(:thank_you, @data) # Redirects to something like /feedbacks/42/thank_you
+redirect_to Compony.path(:step_2, :registrations, accept_terms: :yes) # Redirects to something like /registrations/step_2?accept_terms=yes
+```
+
+### `render_intent`
+
+This is the preferred way of quickly rendering [links or buttons to components](#buttons-and-styles) from other parts of your application. The method is implemented twice:
+
+- When called from within a `content` block of a component, the method implemented in the `RequestContext` is used, which automatically detects the component from which it is called and passes it as `parent_comp` to the rendered button.
+- When called from a regular Rails view, the Rails helper method is used, which instanciates a button without passing a `parent_comp`.
+
+Use the `button` argument to customize the generated button. Example:
+
+```ruby
+setup do
+  content do
+    div render_intent(:show, User.first, button: { style: :link, label: { format: :short } })`
+  end
+end
+```
+
+In the example above, there is a lot more going on than it seems. Due to the [specified style](#buttons-and-styles), a plain HTML link will be generated, pointing to the component `Components::Users::Show` and instanciating it with the first user as `@data`. Assuming that component inherits from `Compony::Components::Show` and did not override label or path, the link will be labelled "Show" (which is the default short format label generated by Compony's default [pre-built Show component](/doc/guide/pre_built_components/show.md)), and the `href` will be `/users/:id` where ID will automatically be `User.first`'s ID (e.g. `/users/1`). However, if `:show` was [prevented](/doc/guide/feasibility.md), the link will be strikethrough, non-clickable, greyed out and have a title explaining why it can't be clicked. Further, if the current user does not have [authorization](/doc/guide/standalone.md) to display the target user, the link will not show up at all, and no HTML will be generated within the `div`.
+
+### `render_sub_comp`
+
+This is used within a component's `content` block to instanciate another component and [nest it within](/doc/guide/nesting.md). Internally, the current component's `sub_comp` method is used and all arguments are passed to that.
+
+For example, let us consider you want to build your user management's Show component to include the list of quotes belonging to the displayed user. Assuming you have already built `Components::Quotes::List` for quotes' Index component, this helper allows you to simply write:
+
+```ruby
+class Components::Users::Show < Compony::Components::Show
+  setup do
+    # ...
+    content :quotes do
+      concat render_sub_comp(:list, @data.quotes)
+    end
+  end
+end
+```
+
+This implicitely builds an intent which auto-detects the family name `:quotes` from `@data.quotes`, which is an active record collection and thus implements `model_name`. The List component is then instanciated with its `@data` being that very collection and the users's Show component as `parent_comp`, resulting in the proper nesting and display of the desired resources.
+
+### `Compony.comp_class_for`
+
+This helper is useful for checking whether a component is implemented. For instance, when implementing [abstract components to inherit from later](/doc/guide/inheritance.md), you can check for `if Compony.comp_class_for(:destroy, family_name)` to only provide some functionality of a Destroy component exists for the current family.
+
+This method also has its sibling `Compony.comp_class_for!`, which will fail if no such component could be found. It is however mostly used internally.
+
+## Buttons and styles
+
+Button components are used as presenters for intents, hyperlinks to other components or submit buttons. They are a central way to define how buttons all over the application should look like. Their interface is adapted to intents, creating a standardized "slim waist" that greatly simplifies linking between components. Note that the term "button" refers to how they look and not how they are actually implemented - actual HTML buttons have several disadvantages (e.g. requiring drop-in forms and not responding to Ctrl+Click or middle-click when the user would prefer a new tab).
+
+Compony comes with two button styles:
+
+- `:css_button` is the default button style and creates a div that looks similar to a HTML button rendered in Firefox. If the class `disabled` is given, it is greyed out.
+- `:link` is mostly just a regular `<a>` tag, but will appear greyed out and strikethrough if the class `disabled` is given.
+
+All button styles support the following keyword arguments to their initializer:
+
+- `label` is a String which will be displayed as the text of the link or button.
+- `href` is the url/path that the button points to. If `nil`, will change to `javascript:void(0)`.
+- `method` takes a HTTP verb will generate a suitable `turbo_method` data attribute.
+- `class` will mostly let be as-is, but checked for the `disabled` class - if given, the style will be ovewritten.
+
+Note that since buttons are full components, they can be [nested](/doc/guide/nesting.md) into another component by providing `parent_comp`. If called from within a component's `content` block, the helper `render_intent` does this automatically.
+
+As implicitely mentioned above, Compony buttons are referenced to by a name called a style (`:css_button` actually points to `Compony::Components::Buttons::CssButton`). When rendering an intent, the style can be passed as an argument: `render_intent(:show, User.first, button: { style: :link })` and the intent will automatically instanciate the desired component class.
+
+Note: it is possible to use a button component to submit a form. In order to achieve this, you must implement a hidden submit button (for handling keyboard Enter and Return), as well as pass `onclick: "this.closest('form').requestSubmit(); return false;"` as an argument. See the pre-built Form component's implementation for an example.
+
+### Adding your own styles
+
+In your application, you will likely want to implement your own button styles. Create a component (e.g. `Components::Commons::MyButton`) and inherit from `Compony::Components::Buttons::Link`. Override the method `prepare_opts!` and don't forget to call `super` first. Then, go through any `@comp_args` that might be of interest to you and mutate `@comp_args[:style]` and/or `@comp_args[:class]` to suit your needs. Make sure to handle the class `disabled`, as intents will set them if the intent is not feasible. Note that if a user is lacking authorization to perform an intent, the intent will not even instanciate the button.
+
+Once your button class is ready, register it in `config/initializers/compony.rb` with: `Compony.register_button_style :my_button, '::Components::Commons::MyButton'`. You can also change the default button style there using: `Compony.default_button_style = :my_button`.
+
+If you have multiple kinds of buttons (e.g. dropdown items, pill-style buttons, compact forms etc.), you should create a separate style and button component class for every kind. This will make it easy to refer to them by supplying something like `button: { style: :dropdown_item }` in `render_intent`.
+
+## Exposed intents
+
+Components can expose a set of intents to be displayed elsewhere. Those can either be rendered by the parent comp, or by the application layout itself in case the component exposing them is currently `root_comp` (see the chapter about [standalone](/doc/guide/standalone.md)). This is useful if you have something like an actions toolbar that changes depending on the currently contained component.
+
+To expose an intent, proceed as shown in the following example:
+
+```ruby
+# ...
+class Components::Quotes::Show < Compony::Components::Show
+  setup do
+    exposed_intents do
+      add :index, family_name, label: 'Show all', name: :index
+      remove :destroy
+    end
+  end
+end
+```
+
+In this example, the shown component exposes an intent pointing to the Index component of it's own family (`:users`). The `:name` argument causes the new intent to be just named `:index` rather than `:index_users`. This is for the sake of the example and would allow a component inheriting from this component to use `exposed_intents { remove :index }` rather than `exposed_intents { remove :index_users }`.
+
+Similarly, this component removes the exposed intent `:destroy` which it whould otherwise inherit from `Comopony::Components::Show`. Every call to `exposed_intents` overrides properties set in previous calls by the same component, primarly useful for [reusing components by inheritance](/doc/guide/inheritance.md).
+
+In order to replace an existing intent defined by a previous call to `exposed_intents` (e.g. in a parent class), simply call `add` again and make sure the intent's name matches that of the one to override. `add` also accepts the `before:` keyword, allowing you to reorder intents or insert a new one into a specific place in the intent list.
+
+Note that the `add` method has full intent argument support and thus also accepts parameters related to the button (e.g. `style`), path generation, feasibility etc.
+
+### Rendering exposed intents
+
+You can render exposed intents in the parent component or in the application layout. To do so, call `component.exposed_intents`, loop across them and call `.render(controller)` on each (perhaps inside a `div` tag or whatever suits your needs).
+
+Example in `layouts/application.html.erb`
+
+```erb
+<% Compony.root_comp&.exposed_intents&.each do |intent| %>
+  <div class="root-intent"><%= intent.render(controller) %>
+<% end %>
+```
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/internal_datastructures.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Internal datastructures
 
@@ -42,4 +42,6 @@ RequestContext further provides the following methods on its own:
 - `evaluate_with_backfire` is `evaluate` with enabled backfiring.
 - `component` returns the component the RequestContext was instantiated with.
 - `request_context` returns self. This is for disambiguation purposes.
-- Any call to an unknown method will first be evaluated as a potential hit in `locals`. Only if no matching local is found, Dslblend takes over.
+- Any call to an unknown method will first be evaluated as a potential hit in `locals`. Only if no matching local is found, Dslblend takes over.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/model_fields.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Model fields
 
@@ -59,4 +59,6 @@ Example:
 Compony.model_field_namespaces = ['MyCustomModelFields', 'Compony::ModelFields']
 ```
 
-You can then implement `MyCustomModelFields::Animal`, `MyCustomModelFields::String` etc. You can then use `field :fav_animal, :animal` in your model.
+You can then implement `MyCustomModelFields::Animal`, `MyCustomModelFields::String` etc. You can then use `field :fav_animal, :animal` in your model.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/nesting.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Nesting
 
@@ -12,7 +12,7 @@ Nesting occurs when a component is being rendered. It is perfectly feasible to u
 
 Note that only the root component runs authentication and authorization. Thus, be careful which components you nest.
 
-To create a sub-component, use `sub_comp` in a component's content block. Any keyword arguments given will be passed to the sub-component. It is strictly recommended to exclusively use `sub_comp` (or its [resourceful](./resourceful.md) pendent) to nest components, as this method makes a component aware of its exact nesting.
+To create a sub-component, use `render_sub_comp` in a component's content block. Any keyword arguments given will be passed to the sub-component. It is strictly recommended to exclusively use `render_sub_comp`, `sub_comp` or its [resourceful](./resourceful.md#nesting-resourceful-components) pendent to nest components, as this method makes a component aware of its exact nesting.
 
 Here is a simple example of a component that displays numbers as binary:
 
@@ -129,4 +129,6 @@ The number 4 has the binary form 100. Enter a number and press ENTER: [4]
 The number 8 has the binary form 1000. Enter a number and press ENTER: [8]
 ```
 
-Note that this example is completely stateless, as all the info is encoded in the URL.
+Note that this example is completely stateless, as all the info is encoded in the URL.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/ownership.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Ownership
 
@@ -11,11 +11,13 @@ In Compony, if a model class is owned by another, it means that:
 
 - The owned model has a non-optional `belongs_to` relation ship to its owner.
 - The owned model class has no Index component.
-- Pre-built components (more on them later) offer root actions to the owner model and redirect to its Show component instead of to the current object's Index component.
+- [Pre-built components](/doc/guide/pre_built_components.md) offer [exposed intents](/doc/guide/intents.md#exposed-intents) to the owner model and redirect to its Show component instead of to the current object's Index component.
 
 To mark a model as owned by another, write the following code **in the model**:
 
 ```ruby
 # app/models/permission.rb
 owned_by :user
-```
+```
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/pre_built_components/destroy.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: Destroy
@@ -12,11 +12,11 @@ This component is the Compony equivalent to a typical Rails controller's `destro
   - if present: the data's Show component
   - otherwise: the data's Index component
 
-Authorization checks for `destroy` even in GET. The reason is that users that aren't able to destroy a resource shouldn't even arrive at the page asking them whether they want to do so, unable to click the only button due to lacking permissions. This also causes any `compony_link` and `compony_button` to Destroy components to be hidden if the user is unable to destroy the corresponding resource.
+Authorization checks for `destroy` even in GET. The reason is that users that aren't able to destroy a resource shouldn't even arrive at the page asking them whether they want to do so, unable to click the only button due to lacking permissions. This also causes any [intents](/doc/guide/intents.md) to Destroy components to be hidden if the user is unable to destroy the corresponding resource.
 
 This component largely follows the [resourceful lifecycle](/doc/guide/resourceful.md#complete-resourceful-lifecycle). As can be expected, the resource is loaded by `Resourceful`'s default load block and `store_data` is implemented to destroy the resource.
 
-If the resource is [owned](/doc/guide/ownership.md), the component provides a `:back_to_owner` root action in the form of a cancel button.
+If the resource is [owned](/doc/guide/ownership.md), the component provides a `:back_to_owner` [exposed intent](/doc/guide/intents.md#exposed-intents) in the form of a cancel button.
 
 The following DSL methods are implemented to allow for convenient overrides of default logic:
 

data/doc/guide/pre_built_components/edit.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: Edit

data/doc/guide/pre_built_components/form.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: Form

data/doc/guide/pre_built_components/index.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: Index

data/doc/guide/pre_built_components/list.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: List

data/doc/guide/pre_built_components/new.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: New
@@ -13,7 +13,7 @@ This component is the Compony equivalent to a typical Rails controller's `new` a
   - otherwise, if the resource is owned by another resource class: the owner's Show component
   - otherwise, the data's Index component
 
-Authorization checks for `create` even in GET. The reason is that it makes no sense to present an empty form to a user who cannot create a new record. This also causes any `compony_link` and `compony_button` to New components to be hidden to users lacking the permission.
+Authorization checks for `create` even in GET. The reason is that it makes no sense to present an empty form to a user who cannot create a new record. This also causes any [intents](/doc/guide/intents.md) to New components to be hidden to users lacking the permission.
 
 This component follows the [resourceful lifecycle](/doc/guide/resourceful.md#complete-resourceful-lifecycle). `load_data` is set to create a new record and `store_data` attempts to create it. Parameters are validated in `assign_attributes` using a Schemacop schema that is generated from the form. The schema corresponds to Rail's typical strong parameter structure for forms. For example, a user's New component would look for a parameter `user` holding a hash of attributes (e.g. `user[first_name]=Tom`).
 

data/doc/guide/pre_built_components/show.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: Show

data/doc/guide/pre_built_components/with_form.md

@@ -1,4 +1,4 @@
-- [Back to the guide](/README.md#guide)
+- [Back to the guide](/README.md#guide--documentation)
 - [List of pre-built components](/doc/guide/pre_built_components.md)
 
 # Pre-built components: WithForm

data/doc/guide/pre_built_components.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Pre-built components shipped with Compony
 
@@ -8,7 +8,6 @@ The pre-built components can be found in the module `Compony::Components`. As yo
 
 In the following, the pre-built components currently shipped with Compony are presented:
 
-- [Button](./pre_built_components/button.md): This component class gets instanciated whenever using `Compony.button` or `compony_button`.
 - [Show](./pre_built_components/show.md): Compony's equivalent to Rail's `show` controller action
 - [Index](./pre_built_components/index.md): Compony's equivalent to Rail's `index` controller action
 - [List](./pre_built_components/list.md): Compony's equivalent to Rail's `_list` partial
@@ -16,4 +15,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/new.md): Compony's equivalent to Rail's `edit` and `update` controller action
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/resourceful.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Resourceful components
 
@@ -66,7 +66,7 @@ class Components::Users::Destroy < Compony::Component
     label(:long) { |data| "Delete #{data.label}" }
     content do
       h1 "Are you sure to delete #{@data.label}?"
-      div compony_button(:destroy, @data, label: 'Yes, delete', method: :delete)
+      div render_intent(:destroy, @data, label: 'Yes, delete', method: :delete)
     end
   end
 end
@@ -98,4 +98,6 @@ The rule of thumb thus becomes:
 
 - When a resourceful component instantiates a resourceful sub-component, use `resourceful_sub_comp` in the parent component.
 - When a resourceful component instantiates a non-resourceful sub-component, use `sub_comp`.
-- The situation where a non-resourceful component instantiates a resourceful component should not occur. Instead, make your parent component resourceful, even if it doesn't use the data itself. By housing a resourceful sub-comp, the parent component's nature inherently becomes resourceful and you should use the Resourceful mixin.
+- The situation where a non-resourceful component instantiates a resourceful component should not occur. Instead, make your parent component resourceful, even if it doesn't use the data itself. By housing a resourceful sub-comp, the parent component's nature inherently becomes resourceful and you should use the Resourceful mixin.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/standalone.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Standalone (routing to components)
 
@@ -133,4 +133,12 @@ end
 scope '(:lang)', lang: /([a-z]{2})?/i do
   get 'welcome', to: 'compony#your_component'
 end
-```
+```
+
+## Customizing path generation
+
+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.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/virtual_models.md

@@ -1,4 +1,4 @@
-[Back to the guide](/README.md#guide)
+[Back to the guide](/README.md#guide--documentation)
 
 # Unleashing virtual models through Compony's `ActiveType` integration
 
@@ -26,4 +26,6 @@ Why this works: As your `Components::Reports::Request` inherits from Compony's `
 
 Note: it is even possible to combine this pattern with Rails' `accepts_nested_attributes_for` and `simple_form`'s `f.simple_fields_for` call, where the nested object is a real database-backed model. Even though the component's resource is purely virtual, Rails will create or update the nested model when Compony calls `save` on the parent resource. This allows for very fast implementation of business logic creating multiple objects from a single form post by wrapping the resources in a virtual model.
 
-If you intend to use this technique in combination with `ActiveStorage`, you must also override the `store_data` block to just validate the model instead of saving it, as the hook creating the attachment is bound to fail (the virtual model does not exist in the database and thus cannot be referenced from `ActiveStorage::Attachment`). For the same reason, you cannot call `blob.download`, but must find the file's tempfile in the request parameters in order to process the file attached by the user.
+If you intend to use this technique in combination with `ActiveStorage`, you must also override the `store_data` block to just validate the model instead of saving it, as the hook creating the attachment is bound to fail (the virtual model does not exist in the database and thus cannot be referenced from `ActiveStorage::Attachment`). For the same reason, you cannot call `blob.download`, but must find the file's tempfile in the request parameters in order to process the file attached by the user.
+
+[Guide index](/README.md#guide--documentation)

data/doc/index.html

@@ -71,7 +71,7 @@
 
 <h1 id="label-About+Compony">About Compony</h1>
 
-<p>Compony is a Gem that allows you to write your Rails application in component-style fashion. It combines a controller action and route along with its view into a single Ruby class. This allows writing much DRYer code, using inheritance even in views and much easier refactoring for your Rails applications, helping you to keep the code clean as the application evolves.</p>
+<p>Compony is a Gem that allows you to write your Rails application in <strong>component-style</strong> fashion. It combines a controller action and route along with its view into a single Ruby class. Along with the DSL approach and a powerful model mixin, Compony <strong>makes your application’s code more semantic</strong>, allows writing <strong>much DRYer code</strong>, using inheritance even in views and <strong>much easier refactoring</strong> for your Rails applications, helping you to <strong>keep the code clean as the application evolves</strong>.</p>
 
 <p>Compony’s key aspects:</p>
 <ul><li>
@@ -79,17 +79,18 @@
 </li><li>
 <p>Refactor common logic into your own components and inherit from them to DRY up your code.</p>
 </li><li>
-<p>Compony’s powerful model mixin allows you to define metadata in your models and react to them. Examples:</p>
-</li><li>
+<p>Compony’s model mixin allows you to define metadata in your models and react to them, resulting in more semantic code. Examples:</p>
+<ul><li>
 <p>Compony fields capture attributes that should be made visible in your UI. They allow you to implement formatting behavior and parameter sanitization for various types, e.g. URLs, phone numbers, colors etc. ready to be used in your lists, detail panels, or forms.</p>
 </li><li>
 <p>Compony’s feasibility framework allows you to prohibit actions based on conditions, along with an error message. This causes all buttons pointing to that action to be disabled with a meaningful error message.</p>
+</li></ul>
 </li><li>
 <p>Compony only structures your code, but provides no style whatsoever. It is like a bookshelf rather than a reader’s library. You still implement your own layouts, CSS and Javascript to define the behavior of your front-end.</p>
 </li><li>
-<p>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>
+<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 and fully supports Stimulus and Turbo Drive. Turbo Frames and Streams are not yet targeted, so Compony is currently meant for websites where every click triggers a “full page load” (in quotes because they are not actually full page loads due to Turbo Drive).</p>
+<p>Compony is built for Rails 7, 7.1 and 8, and fully supports Stimulus and Turbo Drive. Turbo Frames and Streams are not yet targeted, but can be used alongside, just like with any Rails application.</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>
@@ -98,7 +99,7 @@
 
 <p>I am actively using this framework in various applications and both performance and reliability are good. However, the project is experimental and lacking peer reviews and especially automatic testing, such as unit and integration tests. Also, expect there to be (<a href="/CHANGELOG_md.html">documented</a>) breaking changes in the future, as the API will likely be further refined, resulting in renamings and deprecation of various methods.</p>
 
-<h2 id="label-Related+projects">Related projects</h2>
+<h2 id="label-Other+projects+exploring+similar+concepts">Other projects exploring similar concepts</h2>
 
 <p>A project with a similar aim, but a different approach, is <a href="https://github.com/phlex-ruby/phlex">Phlex</a>.</p>
 
@@ -122,11 +123,9 @@
 </li><li>
 <p><a href="./doc/guide/resourceful_md.html">Resourceful components</a>: How to create components that deal with Rails-style resources</p>
 </li><li>
-<p><a href="./doc/guide/helpers_md.html">Compony helpers, links and buttons</a>: Important tools for concise Compony programming</p>
-</li><li>
-<p><a href="./doc/guide/root_actions_md.html">Root actions</a>: How to provide context-sensitive buttons to your application</p>
+<p><a href="./doc/guide/intents_md.html">Intents</a>: How to point to a component and provide custom components for rendering intents</p>
 </li><li>
-<p><a href="./doc/guide/feasibility_md.html">Feasibility</a>: Disabiling buttons based on context (contains <code>prevent</code>)</p>
+<p><a href="./doc/guide/feasibility_md.html">Feasibility</a>: Disabiling intents based on context (contains <code>prevent</code>)</p>
 </li><li>
 <p><a href="./doc/guide/ownership_md.html">Ownership</a>: Informing Compony that a resource is conceptually part of another resource</p>
 </li><li>
@@ -143,8 +142,6 @@
 <ul><li>
 <p><a href="./doc/guide/pre_built_components_md.html">Introduction</a></p>
 </li><li>
-<p><a href="./doc/guide/pre_built_components/button_md.html">Button</a>: This component class gets instanciated whenever using <code>Compony.button</code> or <code>compony_button</code>.</p>
-</li><li>
 <p><a href="./doc/guide/pre_built_components/show_md.html">Show</a>: Compony’s equivalent to Rail’s <code>show</code> controller action</p>
 </li><li>
 <p><a href="./doc/guide/pre_built_components/index_md.html">Index</a>: Compony’s equivalent to Rail’s <code>index</code> controller action</p>
@@ -189,11 +186,7 @@
 </li><li>
 <p>At this point, I haven’t gotten into Turbo Streams and Turbo Frames. It would be interesting to extend Compony such it also makes writing applications using these features much easier.</p>
 </li><li>
-<p>Feasibility:</p>
-</li><li>
-<p>The feasibility framework does not yet enforce prevention, but only has effects on buttons. Actions should be structured more explicitly such that prevention becomes as tight as authorization.</p>
-</li><li>
-<p>Feasibility for links is not yet implemented.</p>
+<p>The feasibility framework does not yet enforce prevention, but only has effects on buttons.</p>
 </li><li>
 <p>Compony is not compatible with <code>tailwindcss-rails</code>. This is likely due to Tailwind automatically removing any CSS that is not used by the application and the usage detection not picking up Compony components, as their content is not provided in views.</p>
 </li></ul>
@@ -206,7 +199,7 @@
 </div></div>
 
       <div id="footer">
-  Generated on Thu Nov 20 12:44:23 2025 by
+  Generated on Thu Nov 27 16:02:21 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.34 (ruby-3.3.5).
 </div>