compony 0.7.0 → 0.7.1

data/doc/guide/helpers.md

@@ -0,0 +1,156 @@
+[Back to the guide](/README.md#guide)
+
+# Compony helpers, links and buttons
+
+When pointing to or instantiating a component, writing the whole class name would be cumbersome. For this reason, Compony has several helpers that will retrieve the correct class for you. The most important ones are explained in this subsection. The terms are defined as follows:
+
+- Component name or constant: For a component `Components::Users::Show`, this would be `'Show'`, `'show'`, or `:show`
+- Family name or constant: For a component `Components::Users::Show`, this would be `'Users'`, `'users'`, or `:users`
+- Model: an instance of a class that implements the `model_name` method in the same way as `ActiveRecord::Base` does. For helpers that support giving models, Compony will use `model_name` to auto-infer the family name. This requires you to name the component according to convention, i.e. the family name must match the model's pluralized camelized `model_name`.
+
+## Getting the class of a component
+
+- `Compony.comp_class_for(comp_name_or_cst, model_or_family_name_or_cst)` returns the class or nil if not found.
+- `Compony.comp_class_for!(comp_name_or_cst, model_or_family_name_or_cst)` returns the class. If the class is not found, an error will be raised.
+
+Example:
+
+```ruby
+my_component = Compony.comp_class_for!(:show, User.first).new
+my_component.class # Components::Users::Show
+```
+
+### Getting a path to a component
+
+- `Compony.path(comp_name_or_cst, model_or_family_name_or_cst)` returns the route to a component. Additional positional and keyword arguments will be passed to the Rails helper.
+
+If a model is given, its ID will automatically be added as the `id` parameter when generating the route. This means:
+
+- To generate a path to a non-resourceful component, pass the family name.
+- To generate a path to a resourceful component, prefer passing an instance instead of a family name.
+
+Examples:
+
+```ruby
+link_to 'User overview', Compony.path(:index, :users) # -> 'users/index'
+link_to 'See user page', Compony.path(:show, User.first) # -> 'users/show/1'
+link_to 'See user page', Compony.path(:show, :users, id: 1) # -> 'users/show/1'
+```
+
+Note that the generated paths in the example are just for illustration purposes. The paths point to whatever path you configure in the target component's default standalone config. Also, this example is not how you should generate links to components, as is explained in the next subsection.
+
+### 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`, `compony_link`, `Compony.button`, `compony_button` etc.
+
+This is an advanced usage. Refer to the default implementation of `Component`'s `path_block` to see an exmple.
+
+## Generating a link to a component
+
+In order to allow a user to visit another component, don't implement your links and buttons manually. Instead, use Compony's links and buttons, as those extract information from the target component, avoiding redundant code and making refactoring much easier.
+
+Compony comes with the view helper `compony_link` that is available in any of your views, including a component's `content` blocks. The link's label is inferred from the component the link points to. `compony_link` is used as follows:
+
+- To generate a link to a non-resourceful component, pass the family name.
+- To generate a link to a resourceful component, prefer passing an instance instead of a family name. More precisely, you must pass an instance if the component's label requires an argument.
+
+Any additional arguments passed to `compony_link` will be given to Rails' `link_to` method, allowing you to set parameters, HTTP method, terget, rel etc.
+
+Examples:
+
+```ruby
+compony_link(:index, :users) # "View all users" -> 'users/index'
+compony_link(Components::Users::Index) # same as above
+compony_link(:index, :users, label_opts: { format: :short }) # "All" -> 'users/index'
+compony_link(:show, User.first) # "View John Doe" -> 'users/show/1'
+compony_link(:destroy, User.first, method: :delete) # "Delete John Doe" -> 'users/destroy/1'
+
+# NOT working:
+compony_link(:show, :users, id: 1) # Error: The label for the Users::Show component takes an argument which was not provided (the user's label)
+```
+
+## Generating a button to a component
+
+Compony buttons are components that render a button to another component. While the view helper `compony_button` works similar to `compony_link`, you can also manually instantiate a button and work with it like with any other component.
+
+Similar to links, Compony buttons take a component name and either a family or model. The label, path, method and title (i.e. tooltip) can be overwritten by passing the respective arguments as shown below.
+
+Compony buttons have a type that is either `:button` or `:submit`. While the first works like a link redirecting the user elsewhere, the second is used for submitting forms. It can be used inside a `form_for` or `simple_form_for`.
+
+A compony button figures out on it's own whether it's clickable or not:
+
+- Buttons can be disabled explicitly by passing `enabled: false` as a parameter.
+- If a user is not authorized to access the component a button is pointing to, the button is not displayed.
+- If the target component should not be accessible due to a prevention in the [feasibility framework](./feasibility.md), the button is disabled and a tooltip is shown explaining why the button is not clickable.
+
+Do not directly instantiate `Compony::Components::Button`. Instead, use `Compony.button`:
+
+```ruby
+my_button = Compony.button(:index, :users) # "View all users" -> 'users/index'
+my_button = Compony.button(:index, :users, label_opts: { format: :short }) # "All" -> 'users/index'
+my_button = Compony.button(:index, :users, label: 'Back') # "Back" -> 'users/index'
+my_button = Compony.button(:show, User.first) # "View John Doe" -> 'users/show/1'
+my_button = Compony.button(:new, :users, label: 'New customer', params: { user: { type: 'customer' } }) # "New customer" -> 'users/new?user[type]=customer'
+my_button = Compony.button(:new, :users, label: 'New customer', params: { user: { type: 'customer' } }, method: :post) # Instantly creates user.
+my_button = Compony.button(label: 'I point to a plain Rails route', path: 'some/path') # Specifying a custom path
+my_button = Compony.button(label: 'Nothing happens if you click me') # javascript:void()
+my_button = Compony.button(label: 'Not implemented yet', enabled: false) # Disabled button
+
+# `enabled` and `path` can also be provided with a callable (block or lambda) to defer evaluation until when the button is rendered.
+# The lambdas will be called in the button's `before_render` and given the controller, allowing you to query request specific data.
+my_button = Compony.button(label: 'I point to a plain Rails route', path: ->{ |controller| controller.helpers.some_rails_path })
+my_button = Compony.button(:index, :users, enabled: -> { |controller| controller.current_ability.can?(:read, :index_pages) })
+```
+
+A Compony button can be rendered like any other component:
+
+```erb
+<%= my_button.render(controller) %>
+```
+
+However, it is much easier to just use the appropriate view helper instead, which takes the same arguments as `Compony.button`:
+
+```ruby
+compony_button(:index, :users)
+```
+
+If you need to render many buttons that share a parameter, the call `Compony.with_button_defaults` allows you to DRY up your code:
+
+```ruby
+# Assuming this is inside a Dyny view context and each button should be inside a div.
+# Without with_button_defaults:
+  div compony_button(:new, :documents, label_opts: { format: :short }, method: :post)
+  div compony_button(:new, :letters, label_opts: { format: :short }, method: :post)
+  div compony_button(:new, :articles, label_opts: { format: :short }, method: :post)
+
+# Equivalent using with_button_defaults:
+Compony.with_button_defaults(label_opts: { format: :short }, method: :post) do
+  div compony_button(:new, :documents)
+  div compony_button(:new, :letters)
+  div compony_button(:new, :articles)
+end
+```
+
+### Implementing custom buttons
+
+Plain HTML buttons are not exactly eye candy, so you will likely want to implement your button kind with black jack and icons. For this reason, the button instantiated by Compony's button helpers can be customized.
+
+To build your own button class, inherit as follows:
+
+```ruby
+class MyButton < Compony::Components::Button
+  def initialize(*args, **kwargs, &block) # Add extra arguments here
+    super(*args, **kwargs, &block)
+    # Add extra initialization code here
+  end
+
+  # Add/replace before_render/content here. Be careful to not overwrite code you depend on. Check Compony's button's code for details.
+end
+```
+
+Then, in the Compony initializer, register your custom button class to have Compony instantiate it whenever `Compony.button` or another helper is called:
+
+```ruby
+# config/initializers/compony.rb
+Compony.button_component_class = 'MyButton'
+```

data/doc/guide/inheritance.md

@@ -0,0 +1,62 @@
+[Back to the guide](/README.md#guide)
+
+# Inheritance
+
+Compony's key advantage is that you can write DRYer code with it. To achieve this, you are encouraged to create abstract components, implement common functionality there and inherit from them in other components.
+
+Examples:
+
+- Perhaps you have code shared in all of your `New` components. In this case, create `BaseComponents::New` and inherit from `Compony::Components::New`. In `setup` of your base component, you can now perform all the configurations needed. Now you may inherit from it: `class Components::Users::New < BaseComponents::New`.
+- Perhaps you often implement the same kind of component, for instance an index component displaying a filterable list. In this case, create `BaseComponents::Index` and inherit as follows: `class Components::Users::Index < BaseComponents::Index`.
+
+## Behavior
+
+When inheriting from another component class, `setup` can be called in the child as well in order to overwrite specified configurations. The parent's `setup` block will be run first, then the child's, then the grand-child's and so on.
+
+Omit any configuration that you want to keep from the parent class. For instance, if your parent's setup looks like this:
+
+```ruby
+setup do
+  standalone path: 'foo/bar' do
+    layout 'funky'
+    verb :get do
+      authorize { true }
+    end
+  end
+  content do
+    h1 'Test'
+  end
+end
+```
+
+Assuming you want to implement a child class that only differs by layout and adds more content below "test", you can implement:
+
+```ruby
+setup do
+  standalone do
+    layout 'dark'
+  end
+  content :below do
+    para 'This will appear below "Test".'
+  end
+end
+```
+
+## Un-exposing a component
+
+If a component's parent class is [standalone](./standalone.md) but the child should not be, use `clear_standalone!`:
+
+```ruby
+setup do
+  clear_standalone!
+end
+```
+
+## Best practice
+
+Compony has the following convention:
+
+- implement a custom base component in the directory `app/compony/base_components/your_component.rb`
+- name the class `BaseComponents::YourComponent` where `BaseComponents` is typically a module simple meant for namespacing
+
+When respecting these conventions, compony's generators will automatically make generated classes inherit from the suitable base component if one is available. In the example above, `rails g component Users::Index` will automatically make the generated class inherit from `BaseComponent::Index`.

data/doc/guide/installation.md

@@ -0,0 +1,45 @@
+[Back to the guide](/README.md#guide)
+
+# Installation
+
+## Installing Compony
+
+First, add Compony to your Gemfile:
+
+```ruby
+gem 'compony'
+```
+
+Then run `bundle install`.
+
+Create the directory `app/components`.
+
+In `app/models/application_record.rb`, add the following line below `primary_abstract_class`:
+
+```ruby
+include Compony::ModelMixin
+```
+
+## Installing CanCanCan
+
+Create the file `app/models/ability.rb` with the following content:
+
+```ruby
+class Ability
+  include CanCan::Ability
+
+  def initialize(_user)
+    can :manage, :all
+  end
+end
+```
+
+This is an initial dummy ability that allows anyone to do anything. Most likely, you will want to adjust the file. For documentation, refer to [https://github.com/CanCanCommunity/cancancan/](https://github.com/CanCanCommunity/cancancan/).
+
+## Optional: installing anchormodel
+
+To take advantage of the anchormodel integration, follow the installation instructions under [https://github.com/kalsan/anchormodel/](https://github.com/kalsan/anchormodel/).
+
+## Optional: installing `active_type`
+
+To take advantage of [virtual models](./virtual_models.md) through the `active_type` integration, follow the instructions under [https://github.com/makandra/active_type](https://github.com/makandra/active_type)

data/doc/guide/internal_datastructures.md

@@ -0,0 +1,45 @@
+[Back to the guide](/README.md#guide)
+
+# Internal datastructures
+
+Compony has a few internal data structures that are worth mentioning. Especially when building your own UI framework on top of Compony, these might come in handy.
+
+## MethodAccessibleHash
+
+This is a simpler and safer version of [OpenStruct](https://github.com/ruby/ostruct), allowing you to access a hash's keys via method accessors.
+
+Usage example:
+
+```ruby
+default_options = { foo: :bar }
+options = Compony::MethodAccessibleHash.new(default_options)
+options[:color] = :green
+options.foo # => :bar
+options.color # => green
+```
+
+This part of Compony is also made available under the MIT license at: [https://gist.github.com/kalsan/87826048ea0ade92ab1be93c0919b405](https://gist.github.com/kalsan/87826048ea0ade92ab1be93c0919b405).
+
+## RequestContext
+
+The content blocks, as well as Form's `form_fields` block all run within a `Compony::RequestContext`, which encapsulates useful methods for accessing data within a request. RequestContext is a Dslblend object and contains all the magic described in [https://github.com/kalsan/dslblend](https://github.com/kalsan/dslblend).
+
+The main provider (refer to the Dslblend documentation to find out what that means) is set to the component. Additional providers are controller's helpers, the controller itself, as well as custom additional providers that can be fed to RequestContext in the initializer.
+
+To instantiate a RequestContext, the following arguments must be given:
+
+- The first argument must be the component instantiating the RequestContext.
+- The second argument must be the controller holding the current HTTP request.
+- Optional: any further arguments will be given to Dslblend as additional providers.
+- Optional: the keyword argument `helpers` can be given to overwrite the `helpers` context. If not given, the helpers will be extracted from the controller.
+- Optional: the keyword argument `locals` can be given a hash of local assigns to be made available within the context.
+
+RequestContext further provides the following methods on its own:
+
+- `controller` returns the controller.
+- `helpers` returns the helpers (either from the initializer or the controller).
+- `local_assigns` returns the locals that can be given to the RequestContext on instantiation through the `locals` keyword argument.
+- `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.

data/doc/guide/model_fields.md

@@ -0,0 +1,62 @@
+[Back to the guide](/README.md#guide)
+
+# Model fields
+
+Compony fields are your models' attributes that you wish to expose in your application's UI. They are a central place to store important information about those attributes, accessible from everywhere and without the need for a database connection.
+
+Every Compony field must define at least a name and type. Compony types and ActiveRecord types are similar but not equivalent. While ActiveRecord uses types for storing data in the DB, Compony fields use them for presenting it. For instance, the Compony "string" type covers any kind of string, including ActiveRecord's "string", "text" etc. Similarly, Compony has no "numeric" type - use "integer" or "decimal" instead, depending on whether or not you want to show decimals or not. There are additional field types like "color", "url" etc. You can find a complete list of all Compony field types in the module `Compony::ModelFields`.
+
+Compony fields support Postgres arrays (non-nested).
+
+A particularly interesting model field is `Association` which handles `belongs_to`, `has_many` and `has_one` associations, automatically resolving the association's nature and providing links to the appropriate component.
+
+Every Compony field can further take an arbitrary amount of additional named arguments. Those can be retrieved by calling `YourRailsModel.fields[:field_name].extra_attrs`.
+
+
+Here is an example call to fields for a User model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  field :first_name, :string
+  field :last_name, :string
+  field :user_role, :anchormodel
+  field :website, :url
+  field :created_at, :datetime
+  field :updated_at, :datetime
+end
+```
+
+All fields declared this way are automatically exported as Rails Model attributes. Note that this also means that you should never declare `password` and `password_confirmation` as a Compony field, as you will get the ArgumentError "One or more password arguments are required" otherwise. Read more about handling password fields in the section about `Compony::Components::Form`.
+
+Compony fields provide the following features:
+
+- a label that lets you generate a name for the column: `User.fields[:first_name].label`
+- `value_for`: given a model instance, formats the data (e.g. a field of type "url" will produce a link).
+- Features for forms:
+  - `simpleform_input` auto-generates in input for a simple form (from the `simple_form` gem).
+  - `simpleform_input_hidden` auto-generates a hidden input.
+  - `schema_line` auto-generates a DSL call for Schemacop v3 (from the `schemacop` gem), which is useful for parameter validation.
+
+You can then use these fields in other components, for instance a list as described in the example at the top of this guide:
+
+```ruby
+User.fields.values.each do |field|
+  span do
+    concat "#{field.label}: #{field.value_for(user)} " # Display the field's label and apply it to value
+  end
+end
+```
+
+## Implementing your own fields
+
+You can implement your own model fields. Make sure they are all within the same namespace and inherit at least from `Compony::ModelFields::Base`. To enable them, write an initializer that overwrites the array `Compony.model_field_namespaces`. Namespaces listed in the array are prioritized from first to last. If a field (e.g. `String`) exists in multiple declared namespaces, the first will be used. This allows you to overwrite Compony fields.
+
+Example:
+
+```ruby
+# config/initializers/compony.rb
+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.

data/doc/guide/nesting.md

@@ -0,0 +1,132 @@
+[Back to the guide](/README.md#guide)
+
+# Nesting
+
+Components can be arbitrarily nested. This means that any component exposing content can instantiate an arbitrary number of sub-components that will be rendered as part of its own content. This results in a component tree. Sub-components are aware of the nesting and even of their position within the parent. The topmost component is called the **root component** and it's the only component that must be standalone. If you instead render the topmost component from a custom view, there is conceptually no root component, but Compony has no way to detect this special case.
+
+Nesting is orthogonal to inheritance, they are two entirely different concepts. For disambiguating "parent component", we will make an effort to apply that term to nesting only, while writing "parent component class" if inheritance is meant.
+
+Sub-components are particularly useful for DRYing up your code, e.g. when a visual element is used in multiple places of your application or even multiple times on the same page.
+
+Nesting occurs when a component is being rendered. It is perfectly feasible to use an otherwise standalone component as a sub-component. Doing so simply plugs it into the content of another component and any arguments can be given to its constructor.
+
+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.
+
+Here is a simple example of a component that displays numbers as binary:
+
+```ruby
+# app/components/numbers/binary.rb
+class Components::Nestings::Binary < Compony::Component
+  def initialize(*args, number: nil, **kwargs, &block)
+    @number = nil # If this component is initialized with the argument `number`, it will be stored in the component instance.
+  end
+  setup do
+    # standalone and other configs are omitted in this example.
+    content do
+      # If the initializer did not store `number`, check whether the Rails request contains the parameter `number`:
+      # Note: do not do that, as we will demonstrate below.
+      @number ||= params[:number].presence&.to_i || 0
+      # Display the number as binary
+      para "The number #{@number} has the binary form #{@number.to_s(2)}."
+    end
+  end
+end
+```
+
+If used standalone, the number can be set by using a GET parameter, e.g. `?number=5`. The result is something like this:
+
+```text
+The number 5 has the binary form 101.
+```
+
+Now, let's write a component that displays three different numbers side-by-side:
+
+```ruby
+# app/components/numbers/binary_comparator.rb
+class Components::Nestings::BinaryComparator < Compony::Component
+  setup do
+    # standalone and other configs are omitted in this example.
+    content do
+      concat sub_cop(Components::Nestings::Binary, number: 1).render(controller)
+      concat sub_cop(Components::Nestings::Binary, number: 2).render(controller)
+      concat sub_cop(Components::Nestings::Binary, number: 3).render(controller)
+    end
+  end
+end
+```
+
+The result is something like this:
+
+```text
+The number 1 has the binary form 1.
+The number 2 has the binary form 10.
+The number 3 has the binary form 11.
+```
+
+However, this is static and no fun. We cannot use the HTTP GET parameter any more because all three `Binary` sub-components listen to the same parameter `number`. To fix this, we will need to scope the parameter using the `param_name` as explained in the next subsection.
+
+## Proper parameter naming for (nested) components
+
+As seen above, components can be arbitrarily nested, making it harder to identify which HTTP GET parameter in the request is intended for which component. To resolve this, Compony provides nesting-aware scoping of parameter names:
+
+- Each component has an `index`, given to it by the `sub_comp` call in the parent, informing it witch n-th child of the parent it is.
+  - For instance, in the example above, the three `Binary` components have indices 0, 1 and 2.
+- Each component has an `id` which corresponds to `"#{family_name}_#{comp_name}_#{@index}"`.
+  - For instance, the last `Binary` component from the example above has ID `nestings_binary_2`.
+  - The `BinaryComparator` has ID `nestings_binary_comparator_0`.
+- Each component has a `path` indicating its exact position in the nesting tree as seen from the root component.
+  - In the example above, the last `Binary` component has path `nestings_binary_comparator_0/nestings_binary_2`.
+  - `BinaryComparator` has path `nestings_binary_comparator_0`.
+- Each component provides the method `param_name` that takes the name of a parameter name and prepends the first 5 characters of the component's SHA1-hashed path to it.
+  - For instance, if `param_name(:number)` is called on the last `Binary` component, the output is `a9f3d_number`.
+  - If the same method is called on the first `Binary` component, the output is `f6e86_number`.
+
+In short, `param_name` should be used to prefix every parameter that is used in a component that could potentially be nested. It is good practice to apply it to all components. `param_name` has two important properties:
+
+- From the param name alone, it is not possible to determine to which component the parameter belongs. However:
+- `param_name` is consistent across reloads of the same URL (given that the components are still the same) and thus each component will be able to identify its own parameters and react to them.
+
+With that in mind, let's adjust our `Binary` component. In this example, we will assume that we have implemented yet another component called `NumberChooser` that provides a number input with a Stimulus controller attached. That controller is given the parameter as a String value, such that the it can set the appropriate HTTP GET param and trigger a full page reload to the `BinaryComparator` component.
+
+Further, we can drop the custom initializer from the `Binary` component, as the number to display is exclusively coming from the HTTP GET param. The resulting code looks something like:
+
+```ruby
+# app/components/numbers/binary_comparator.rb
+class Components::Nestings::BinaryComparator < Compony::Component
+  setup do
+    # standalone and other configs are omitted in this example.
+    content do
+      3.times do
+        concat sub_cop(Components::Nestings::Binary).render(controller)
+      end
+    end
+  end
+end
+
+# app/components/numbers/binary.rb
+class Components::Nestings::Binary < Compony::Component
+  setup do
+    # standalone and other configs are omitted in this example.
+    content do
+      # This is where we use param_name to retrieve the parameter for this component, regardless whether it's standalone or used as a sub-comp.
+      @number ||= params[param_name(:number)].presence&.to_i || 0
+      # Display the number as binary
+      para "The number #{@number} has the binary form #{@number.to_s(2)}."
+      # Display the number input that will reload the page to adjust to the user input. We give it the param_name such that it can set params accordingly.
+      concat sub_comp(Components::Nestings::NumberChooser, param_name: param_name(:number))
+    end
+  end
+end
+```
+
+The result for the URL `path/to/binary_comparator?a9f3d_number=2&e70b4_number=4&a9f3d_number=8` is something like this:
+
+```text
+The number 2 has the binary form 10. Enter a number and press ENTER: [2]
+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.

data/doc/guide/ownership.md

@@ -0,0 +1,21 @@
+[Back to the guide](/README.md#guide)
+
+# Ownership
+
+Ownership is a concept that captures the nature of data to be presented by Compony. It means that an object only makes sense within the context of another that it belongs to. Owned objects have therefore no index component, because they don't have meaning on their own. For instance:
+
+- typically NOT owned: visitors and vouchers: while a voucher can `belong_to` a visitor, the voucher can be managed on it's own. Vouchers can have their own index page which makes it possible to search for a given voucher code across all vouchers.
+- typically owned: users and their permissions: a permission only makes sense with respect to its associated user and having a list of all permissions across the system would rarely be a use case. In this case, we consider the `Permission` model to be conceptually **owned by** the `User` model.
+
+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.
+
+To mark a model as owned by another, write the following code **in the model**:
+
+```ruby
+# app/models/permission.rb
+owned_by :user
+```

data/doc/guide/pre_built_components/button.md

@@ -0,0 +1,8 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Button
+
+As stated earlier, buttons are just regular components that rendered in-place. They don't make use of nesting logic (and presumably never will), and thus they are rendered as-is, without `sub_comp`.
+
+You will rarely (or probably never) instantiate a button on your own, but use helpers like `Compony.button` or `compony_button`. For this reason, the documentation for instantiating buttons is located in the [section documenting helpers](/doc/guide/helpers.md).

data/doc/guide/pre_built_components/destroy.md

@@ -0,0 +1,25 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Destroy
+
+This component is the Compony equivalent to a typical Rails controller's `destroy` action.
+
+`Compony::Components::Destroy` is a resourceful standalone component that listens to two verbs:
+
+- GET will cause the Destroy component to ask if the resource should be destroyed, along with a button pointing to the DELETE verb. If the record does not exist, a HTTP 404 code is returned.
+- DELETE will `destroy!` the resource, show a flash and redirect to:
+  - 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.
+
+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.
+
+The following DSL methods are implemented to allow for convenient overrides of default logic:
+
+- The block `on_destroyed` is evaluated between successful record destruction and responding. By default, it is not implemented and doing so is optional. This would be a suitable location for hooks that update state after a resource was destroyed (like an `after_destroy` hook, but only executed if a record was destroyed by this component). Do not redirect or render here, use the next blocks instead.
+- The block given in `on_destroyed_respond` is evaluated after destruction and by default shows a flash, then redirects. The redirection is performed with HTTP code 303 ("see other") in oder to force a GET request. This is required for the component to work with Turbo. Overwrite this block if you need to completely customize all logic that happens after destruction. If this block is overwritten, `on_destroyed_redirect_path` will not be called.
+- `on_destroyed_redirect_path` is evaluated as the second step of `on_destroyed_respond` and redirects to the resource's Show or Index component as described above. Overwrite this block in order to redirect to another component instead, while keeping the default flash provided by `on_destroyed_respond`.

data/doc/guide/pre_built_components/edit.md

@@ -0,0 +1,27 @@
+- [Back to the guide](/README.md#guide)
+- [List of pre-built components](/doc/guide/pre_built_components.md)
+
+# Pre-built components: Edit
+
+This component is the Compony equivalent to a typical Rails controller's `edit` and `update` actions.
+
+`Compony::Components::Edit` is a resourceful standalone component based on [`WithForm`](./with_form.md) that listens to two verbs:
+
+- GET will cause the Edit component to load a record given by ID and render the form based on that record. If the record does not exist, a HTTP 404 code is returned.
+- PATCH (equivalent to a `update` action in a controller) will attempt to save the resource. If that fails, the form is rendered again with a HTTP 422 code ("unprocessable entity"). If the update succeeds, a flash is shown and the user is redirected:
+  - if present: the data's Show component
+  - otherwise, if the resource is owned by another resource class: the owner's Show component
+  - otherwise, the data's Index component
+
+Unlike in New and Destroy, Edit's authorization checks for `edit` in GET and for `update` in PATCH. This enables you to "abuse" an Edit component to double as a Show component. Users having only `:read` permission will not see any links or buttons pointing to an Edit component. Users having only `:edit` permissions can see the form (including the data) but not submit it. Users having `:write` permissions can edit and update the Resource, in accordance to CanCanCan's `:write` alias.
+
+This component follows the [resourceful lifecycle](/doc/guide/resourceful.md#complete-resourceful-lifecycle). 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 Edit component would look for a parameter `user` holding a hash of attributes (e.g. `user[first_name]=Tom`).
+
+In case you overwrite `store_data`, make sure to set `@update_succeeded` to true if storing was successful (and to set it to false otherwise).
+
+The following DSL calls are implemented to allow for convenient overrides of default logic:
+
+- The block `on_update_failed_respond` is run if `@update_succeeded` is not true. By default, it logs all error messages with level `warn` and renders the component again through HTTP 422, causing Turbo to correctly display the page. Error messages are displayed by the form inputs.
+- The block `on_updated` is evaluated between successful record creation and responding. By default, it is not implemented and doing so is optional. This would be a suitable location for hooks that update state after a resource was updated (like an `after_update` hook, but only executed if a record was updated by this component). Do not redirect or render here, use the next blocks instead.
+- The block given in `on_updated_respond` is evaluated after successful creation and by default shows a flash, then redirects. Overwrite this block if you need to completely customize all logic that happens after creation. If this block is overwritten, `on_updated_redirect_path` will not be called.
+- `on_updated_redirect_path` is evaluated as the second step of `on_updated_respond` and redirects to the resource's Show, its owner's Show, or its own Index component as described above. Overwrite this block in order to redirect ot another component instead, while keeping the default flash provided by `on_updated_respond`.