compony 0.11.8 → 0.11.9

data/doc/guide/patterns.md

@@ -0,0 +1,681 @@
+[Back to the guide](/README.md#guide--documentation)
+
+# Real-world patterns
+
+Conventions distilled from a range of production Compony apps. These are *idioms*, not
+framework requirements — but they recur consistently and are worth adopting. Every example
+uses a neutral domain (`Account`, `Order`, `LineItem`, `Document`). Where a pattern relies
+on a companion gem (CanCanCan, ActiveType, simple_form, a date/select input) that is
+called out.
+
+For exact method signatures see [dsl_reference.md](/doc/guide/dsl_reference.md); for
+footguns see [gotchas.md](/doc/guide/gotchas.md).
+
+## 1. The app base-component layer
+
+Almost every non-trivial app inserts one abstract layer between Compony's pre-built
+components and the concrete ones. Concrete components inherit from the app layer, never
+from Compony directly. This centralizes layout, button styling, and chrome so the whole
+app's look changes in one place.
+
+```ruby
+# app/components/base_components/show.rb  (a common location; app/compony/ is also used)
+module BaseComponents
+  class Show < Compony::Components::Show
+    setup do
+      standalone { layout :backend }     # app-wide Rails layout for all non-publicly accessible components
+      button(:icon) { :eye }
+      content :main, hidden: true        # concrete comps fill :main…
+      content :wrapper do                # …chrome lives here, inherited
+        div class: 'card card-body' do
+          content :main
+        end
+      end
+    end
+  end
+end
+
+# app/components/orders/show.rb
+class Components::Orders::Show < BaseComponents::Show
+end                                      # fully functional, empty body
+```
+
+Recurring forms of this layer: `BaseComponents::{Index,Show,New,Edit,Destroy,List}`. The
+`content :main, hidden: true` + `content :wrapper` pair is the standard way to let
+children override the inner content while inheriting the outer chrome (see
+[basic_component.md](/doc/guide/basic_component.md#nesting-content-blocks-calling-a-content-block-from-another)).
+
+Teams sometimes add their own helper DSL on top of this layer (CSV/PDF helpers, archive
+toggles, etc.). Keep such helpers in the app base layer, not in concrete components.
+
+## 2. Thin leaf components
+
+Concrete CRUD components are usually empty — all behavior is inherited. Add a `setup` block
+only to deviate.
+
+```ruby
+class Components::Orders::Destroy < BaseComponents::Destroy; end
+class Components::Orders::New     < BaseComponents::New;     end
+class Components::Orders::Edit    < BaseComponents::Edit;    end
+```
+
+This is the single most common pattern. Prefer it over hand-written endpoints
+([gotchas.md #15](/doc/guide/gotchas.md#15-hand-rolled-endpoint-where-a-pre-built-crud-component-exists)).
+
+## 3. Index = `load_data` scope + nested `:list`
+
+Index components rarely render rows themselves; they load a scope and embed the family's
+List via `render_sub_comp`.
+
+```ruby
+class Components::Orders::Index < BaseComponents::Index
+  setup do
+    load_data { @data = Order.accessible_by(current_ability).order(created_at: :desc) }
+    content do
+      h1 Order.model_name.human(count: 2)
+      concat render_sub_comp(:list, @data)
+    end
+  end
+end
+```
+
+- `accessible_by(current_ability)` is the CanCanCan scoping idiom — pair it with the
+  `authorize` block so list and access rules agree.
+- `concat` is mandatory around `render_sub_comp`/`render_intent`
+  ([gotchas.md #2](/doc/guide/gotchas.md#2-render_intent--render_sub_comp-output-not-appearing)).
+
+## 4. List customization
+
+This pattern is typically combined with a customized `BaseComponents::List` that adds styling and
+features to the pre-built list component.
+
+```ruby
+class Components::Orders::List < BaseComponents::List
+  setup do
+    columns :number, :customer, as_title: true   # as_title -> card title on mobile
+    columns :total, :created_at
+    column :status do |order|                     # computed/custom cell
+      span order.status.label, class: "badge bg-#{order.status.key}"
+    end
+    filters :number, :status
+    sorts :number, :created_at
+    default_sorting 'created_at desc'
+  end
+end
+```
+
+Embedding a child list inside a Show, dropping the redundant FK column and preserving the
+active tab across filter submits:
+
+```ruby
+concat render_sub_comp(:list, @data.line_items, skip_columns: [:order],
+                                                 params_in_filter: [param_name('tab')])
+```
+
+`skip_*` options (`skip_pagination:`, `skip_filtering:`, `skip_columns:`, …) are
+constructor kwargs passed through `render_sub_comp`, useful for read-only embeds.
+
+## 5. Custom form + Schemacop, kept in sync
+
+`form_fields` (rendering) and `schema_*` (param whitelist) must mirror each other.
+
+```ruby
+class Components::Orders::Form < Compony::Components::Form
+  setup do
+    form_fields do
+      concat field(:number)
+      concat field(:customer, as: :tom_select)        # association name, not _id
+      concat field(:placed_at, as: :flatpickr_datetime)
+      concat pw_field(:access_code)
+      concat field(:internal_ref, hidden: true)        # submitted, not shown
+      div class: 'row' do                               # arbitrary Dyny layout
+        div field(:first_name), class: 'col'
+        div field(:last_name),  class: 'col'
+      end
+    end
+
+    schema_fields :number, :customer, :placed_at, :internal_ref
+    schema_pw_field :access_code
+  end
+end
+```
+
+- `as: :tom_select` / `as: :flatpickr_date(time)` are app-registered simple_form inputs
+  (TomSelect, Flatpickr) — a good choice for selects and date pickers.
+- Use the **association name** in `field`/`schema_field`; `_id` is added automatically
+  ([gotchas.md #4](/doc/guide/gotchas.md#4-schema_field-with-the-foreign-key-name)).
+- Nested attributes: `f.simple_fields_for(:line_items)` in `form_fields` plus a raw
+  `schema_line { ary? :line_items_attributes do ... end }`.
+- Multilang fields: `field(:title, multilang: true).each { |i| concat i }` paired with
+  `schema_field :title, multilang: true`.
+
+Wire a non-default form into New/Edit with `form_comp_class`:
+
+```ruby
+class Components::Orders::QuickAdd < Compony::Components::New
+  setup { form_comp_class Components::Orders::QuickAddForm }
+end
+```
+
+## 6. Autocomplete form (app-level subclass)
+
+Compony does not ship autocomplete, but a very common app pattern is an
+`AutocompleteForm` base (subclass of `Compony::Components::Form`) exposing an extra
+`standalone` JSON endpoint for an ajax select. Shape:
+
+```ruby
+class BaseComponents::AutocompleteForm < Compony::Components::Form
+  # class-level `autocomplete(field) { |query, ability| ...collection... }` that
+  # registers an extra `standalone :autocomplete_<field>` returning
+  # [{ text:, value:, icon: }] JSON, consumed by a TomSelect Stimulus controller.
+end
+
+class Components::Orders::Form < BaseComponents::AutocompleteForm
+  setup do
+    form_fields { concat field(:customer, as: :tom_select) }
+    schema_field :customer
+    autocomplete(:customer) { |q, ability| Customer.accessible_by(ability).search(q) }
+  end
+end
+```
+
+If you need autocomplete, build this base once and reuse it.
+
+## 7. Tabbed Show via a mixin
+
+Detail pages are split into tabs with a small app mixin that adds a `tab` DSL and renders
+a tab bar into `:main`. Each tab body typically renders `content :data` or a nested list.
+
+```ruby
+class Components::Orders::Show < BaseComponents::Show
+  include ComponentMixins::Tabs
+
+  setup do
+    tab(:overview, _('Overview')) { content :data }
+    tab(:items,    _('Items'))    { concat render_sub_comp(:list, @data.line_items,
+                                                           skip_columns: [:order]) }
+  end
+end
+```
+
+The mixin keys the active tab off a prefixed param (`param_name('tab')`) so multiple
+tabbed components can coexist. Compony has no built-in tabs — copy the mixin per app.
+
+## 8. Lifecycle hooks for derived data
+
+- **`after_assign_attributes`** — fill defaults / context after params are assigned,
+  before validation: `@data.account_id ||= current_user.account_id`.
+- **`before_render`** — verb-independent guards and precomputation. Redirect and the
+  content chain is skipped:
+  ```ruby
+  before_render do
+    redirect_to Compony.path(:show, @data) if @data.locked?
+  end
+  ```
+- **`load_data`** — narrow the scope (`accessible_by`, `includes`, ordering).
+- **`store_data`** — override persistence (virtual models, file handling, bulk import).
+- **`on_{created,updated,destroyed}_redirect_path`** — control where success lands, e.g.
+  `Compony.path(:show, @data.parent)` for owned records.
+
+## 9. Exposed intents as the action toolbar
+
+Concrete components tailor the header toolbar by `add`/`remove` on inherited intents.
+
+```ruby
+exposed_intents do
+  remove :destroy
+  add :show, @data, label: 'PDF', name: :pdf, path: { format: :pdf },
+      feasibility_action: :pdf
+  add :archive, @data, method: :patch, before: :destroy
+end
+```
+
+- `path: { format: :pdf }` points a button at a format endpoint (see pattern 10).
+- `feasibility_action:` ties the button's enabled state to a model `prevent`
+  ([feasibility.md](/doc/guide/feasibility.md)).
+- State-dependent toolbars (archived vs active) are done by branching inside the
+  `exposed_intents` block on `@data`.
+- Generating one intent per enum value is common:
+  `Period.all.each { |p| add :new, :prices, name: :"new_#{p.key}", path: { price: { period: p.key } } }`.
+
+## 10. CSV / PDF via `respond :format`
+
+A format export is the same component with an extra `respond` branch and an exposed intent
+pointing at it. Because overriding `respond` skips the default `authorize`, re-check there
+([gotchas.md #3](/doc/guide/gotchas.md#3-overriding-respond-skips-authorization)).
+
+```ruby
+standalone path: 'orders' do
+  verb :get do
+    authorize { can?(:read, Order) }
+    respond :csv do
+      can?(:read, Order) or raise CanCan::AccessDenied
+      send_data(OrderCsv.new(@data).to_csv, filename: 'orders.csv', type: 'text/csv')
+    end
+    respond :pdf do
+      can?(:read, @data) or raise CanCan::AccessDenied
+      send_data(OrderPdf.new(@data).render, filename: @data.pdf_name,
+                type: 'application/pdf')
+    end
+  end
+end
+# exposed_intents { add :index, :orders, label: 'CSV', path: { format: :csv } }
+```
+
+## 11. Non-CRUD: job dispatch, toggles, clone
+
+**Job dispatch** — POST-only custom component, enqueue, flash, redirect:
+
+```ruby
+class Components::Orders::ScheduleSync < Compony::Component
+  setup do
+    standalone path: 'orders/schedule_sync' do
+      verb :post do
+        authorize { can?(:create, Order) }
+        respond do
+          SyncOrdersJob.perform_later
+          flash.notice = _('Queued — give it a few minutes.')
+          redirect_to Compony.path(:index, :orders)
+        end
+      end
+    end
+    label(:all) { _('Sync now') }
+    button(:icon) { :rotate }
+  end
+end
+```
+
+Expose it from Index: `exposed_intents { add :schedule_sync, :orders, method: :post }`.
+
+**State toggle** — inherit `Edit`, flip in `after_assign_attributes`, dynamic label:
+
+```ruby
+class Components::Accounts::ToggleActive < Compony::Components::Edit
+  setup do
+    standalone path: 'accounts/:id/toggle_active' do
+      verb :patch do authorize { can?(:toggle_active, @data) } end
+    end
+    label(:long) { |a| a.active? ? _('Deactivate') : _('Activate') }
+    after_assign_attributes { @data.active = !@data.active }
+  end
+end
+```
+
+**Clone** — inherit `New`, load + dup the source in `load_data`, redirect to the copy:
+
+```ruby
+class Components::Orders::Clone < Compony::Components::New
+  setup do
+    standalone path: 'orders/:id/clone'
+    load_data do
+      source = Order.find(params[:id])
+      authorize!(:read, source)          # CanCanCan bang form
+      @data = source.dup
+    end
+    on_created_redirect_path { Compony.path(:show, @data) }
+  end
+end
+```
+
+## 12. Virtual model for non-persistent / upload forms
+
+Inherit `New`, back it with a `Compony::VirtualModel`, take over the response. `@data.save`
+is a no-op so business logic goes in `on_created_respond` (or `store_data`).
+
+```ruby
+class Components::Documents::Import < Compony::Components::New
+  class VirtualModel < Compony::VirtualModel
+    attribute :id, :bigint
+    belongs_to :account
+    has_one_attached :file
+    field :account, :association
+    field :file,    :attachment
+    validates :file, presence: true
+  end
+
+  setup do
+    standalone path: 'documents/import'
+    data_class VirtualModel
+    form_comp_class Components::Documents::ImportForm
+
+    # ActiveStorage on a virtual model: validate only, read the tempfile yourself.
+    store_data do
+      @create_succeeded = @data.validate
+      next unless @create_succeeded
+      tempfile = params.dig(:documents_virtual_model, :file)&.tempfile
+      DocumentImporter.call(account: @data.account, io: tempfile)
+    end
+
+    on_created_respond do
+      flash.notice = _('Imported.')
+      redirect_to Compony.path(:index, :documents)
+    end
+  end
+end
+```
+
+See [virtual_models.md](/doc/guide/virtual_models.md) and
+[gotchas.md #12](/doc/guide/gotchas.md#12-activestorage-attachment-on-a-virtual-model).
+
+## 13. Public endpoints & webhooks
+
+```ruby
+class Components::Public::Webhook < Compony::Component
+  setup do
+    standalone path: '/webhooks/orders' do
+      skip_authentication!
+      skip_forgery_protection!
+      verb :post do
+        authorize { true }                       # still mandatory
+        respond do
+          expected = "Bearer #{ENV.fetch('WEBHOOK_TOKEN')}"
+          got      = request.headers['Authorization'].to_s
+          unless ActiveSupport::SecurityUtils.secure_compare(got, expected)
+            sleep 1                               # crude timing equalization
+            next controller.head(:unauthorized)
+          end
+          OrderWebhook.process!(request.params)
+          controller.head :accepted
+        end
+      end
+    end
+  end
+end
+```
+
+A login-aware redirect splitter is the same shape with `verb :get` + `before_render`
+choosing a `Compony.path` by `current_user`.
+
+## 14. Custom button style
+
+Register one app button style and refer to it everywhere via `style:`.
+
+```ruby
+class Components::Commons::BootstrapButton < Compony::Components::Buttons::Link
+  protected
+  def prepare_opts!
+    super
+    classes = (@comp_opts[:class] || '').split
+    classes << 'btn' << "btn-#{@comp_opts[:color] || :primary}"
+    @comp_opts[:class] = classes.join(' ')
+  end
+end
+# config/initializers/compony.rb
+# Compony.register_button_style :bootstrap, '::Components::Commons::BootstrapButton'
+# Compony.default_button_style = :bootstrap
+```
+
+Make a separate style per visual kind (dropdown item, pill, compact) and select with
+`render_intent(:show, @data, style: :compact)`.
+
+## 15. Inline-edit card with a Turbo Frame
+
+A Show panel where the Edit form swaps in place (no full-page nav) and swaps back on save.
+Wrap both the Show content and the Edit form in a **same-named** `turbo_frame_tag`; Turbo
+Drive then scopes navigation to that frame. Distinct from the `render_sub_comp(:list, …,
+turbo_frame:)` use in [nesting.md](/doc/guide/nesting.md) (there the frame isolates a
+nested list's own search/filter params; here it is the inline-edit boundary for one
+record's Show/Edit pair).
+
+```ruby
+# One frame name shared by the Show panel and the Edit form.
+def card_frame(record) = :"#{record.model_name.singular}_#{record.id}_card"
+
+class Components::Accounts::Show < Compony::Components::Show
+  setup do
+    content :data do
+      turbo_frame_tag card_frame(@data) do      # Dyny: Rails view helper
+        # …render fields…
+        concat render_intent(:edit, @data, label: { format: :short })
+      end
+    end
+  end
+end
+
+class Components::Accounts::Edit < Compony::Components::Edit
+  setup do
+    content do
+      turbo_frame_tag card_frame(@data) do      # same frame name
+        concat form_comp.render(controller, data: @data)
+      end
+    end
+    # Default on_updated_redirect_path → Show; Turbo replaces just the frame.
+  end
+end
+```
+
+- Frame name must match exactly; deriving it from the record id keeps it unique when
+  several cards render on one page.
+- A failed save re-renders Edit with HTTP 422 — keep the `turbo_frame_tag` wrapper in the
+  Edit content so errors render in-frame too.
+
+## 16. Multi-step wizard across components
+
+A create/edit flow split over several steps, each its own component, advancing on save.
+Chain steps with `on_updated_redirect_path` (or `on_created_redirect_path`) and render a
+step indicator via a shared mixin (same mechanism as the tabs mixin in §7).
+
+```ruby
+module OrderWizard
+  extend ActiveSupport::Concern
+  STEPS = %i[details_edit shipping_edit confirm_edit].freeze
+
+  included do
+    setup do
+      content :wizard_nav, before: :main do
+        ol class: 'wizard' do
+          OrderWizard::STEPS.each do |step|
+            li step.to_s.delete_suffix('_edit'),
+               class: (component.comp_name.to_sym == step ? 'active' : nil)
+          end
+        end
+      end
+    end
+  end
+end
+
+class Components::Orders::DetailsEdit < Compony::Components::Edit
+  include OrderWizard
+  setup do
+    standalone path: 'orders/:id/details'
+    on_updated_redirect_path { Compony.path(:shipping_edit, @data) }   # → next step
+  end
+end
+
+class Components::Orders::ShippingEdit < Compony::Components::Edit
+  include OrderWizard
+  setup do
+    standalone path: 'orders/:id/shipping'
+    on_updated_redirect_path { Compony.path(:confirm_edit, @data) }
+  end
+end
+# …ConfirmEdit redirects to Show when done.
+```
+
+- Each step is a normal resourceful component on the same model — partial validation per
+  step is just per-step `schema_field`s in each step's Form.
+- For a *non-persistent* wizard (nothing saved until the end), back the components with a
+  [VirtualModel](/doc/guide/virtual_models.md) and carry state in its attributes (§12).
+- `comp_name` drives the active-step highlight, so the mixin needs no per-step config.
+
+## 17. Inline PATCH without a form (reorder / quick toggle)
+
+A JS front-end (drag-to-sort, an inline checkbox) issues a small PATCH that mutates state
+and returns no body. Add a **named** extra `standalone` with `verb :patch`, validate with
+Schemacop directly, and `head :ok`. No Form component involved.
+
+```ruby
+class Components::Orders::Show < Compony::Components::Show
+  setup do
+    # Main route inherited from Show. Companion endpoint for reordering line items:
+    standalone :reorder, path: 'orders/:id/reorder' do
+      verb :patch do
+        authorize { can?(:update, @data) }
+        respond do                       # overriding respond skips default authorize…
+          can?(:update, @data) or raise CanCan::AccessDenied   # …so re-check here
+          params = Schemacop::Schema3.new(:hash) do
+            ary! :ordered_ids do
+              list :integer
+            end
+          end.validate!(controller.request.params)
+          @data.line_items.reorder_by!(params[:ordered_ids])
+          controller.head :ok
+        end
+      end
+    end
+  end
+end
+```
+
+The route is `reorder_show_orders_comp` (see
+[standalone naming](/doc/guide/standalone.md#naming-of-exposed-routes)); point your
+Stimulus controller's PATCH at
+`Compony.path(:show, @data, standalone_name: :reorder)`.
+
+- This is the [gotchas.md #3](/doc/guide/gotchas.md#3-overriding-respond-skips-authorization)
+  case: the custom `respond` replaces the default that runs `authorize`, so authorize
+  again inside it.
+- Keep companion endpoints in the *same* component as the screen they serve — what extra
+  named `standalone`s are for
+  ([standalone.md](/doc/guide/standalone.md#exposing-multiple-paths-in-the-same-component-calling-standalone-multiple-times)),
+  not a reason for a new component.
+- Return `head :ok` (or small JSON) — no Compony content to render for an ajax-only verb.
+
+## 18. Signed-token capability links (auth-less onboarding / magic links)
+
+Goal: an emailed link that lets an unauthenticated visitor perform one bounded action —
+invite acceptance, magic login, password reset, email confirmation — without a session.
+The trick: override Compony's `path do … end` to **mint a signed JWT** and carry it as a
+`token` query param, then gate a `skip_authentication!` standalone with
+`authorize { token_valid?(params) }`. A small mixin centralizes encode/decode.
+
+> **Security — read before copying.** Such a link *is* the capability; anyone holding the
+> URL can perform the action. It is only safe if every one of these holds:
+> - **Expiry is mandatory.** Put `exp` in the payload and verify it. A capability link
+>   without a TTL is a permanent account-takeover primitive (it leaks via referrer
+>   headers, proxy logs, mail forwarding, browser history). Pair short TTLs with a resend
+>   flow.
+> - **Pin the algorithm and verify the signature** — `JWT.decode(token, secret, true,
+>   { algorithm: 'HS512' })`. Never accept `alg: none`; never leave verification off.
+> - **Fail closed.** Rescue `JWT::DecodeError` (its subclasses cover bad signature,
+>   malformed token and expiry) and return `nil`/`false` so `authorize` denies with 403 —
+>   not a 500.
+> - **Use a dedicated signing secret**, not `secret_key_base`, so rotating it doesn't also
+>   invalidate every session (and vice-versa).
+> - Still provide an `authorize` block: `skip_authentication!` removes *authentication*,
+>   not authorization ([gotchas.md #14](/doc/guide/gotchas.md#14-public-endpoint-still-401redirecting)).
+
+```ruby
+# app/component_mixins/with_token.rb
+module WithToken
+  extend ActiveSupport::Concern
+  TOKEN_TTL = 14.days
+
+  def encode_token(payload)
+    JWT.encode(payload.merge(exp: TOKEN_TTL.from_now.to_i), token_secret, 'HS512')
+  end
+
+  # Memoized; returns the payload (indifferent access) or nil. Fails closed.
+  def token_data(params = nil)
+    return @token_data if @token_data
+    return nil if params.blank?
+    @token = params[:token]
+    return nil if @token.blank?
+    @token_data = JWT.decode(@token, token_secret, true, { algorithm: 'HS512' })
+                     .first.with_indifferent_access
+  rescue JWT::DecodeError   # bad sig / malformed / expired — all subclasses
+    nil
+  end
+
+  def token_secret
+    Rails.application.credentials.capability_token_secret.presence ||
+      Rails.application.credentials.secret_key_base   # fallback until set
+  end
+end
+```
+
+Override `path` so links self-mint a token (callers pass the subject, not the token):
+
+```ruby
+class Components::Invites::Accept < Compony::Components::New
+  include WithToken
+
+  class VirtualModel < Compony::VirtualModel
+    attribute :password, :string
+    attribute :account_id          # carried for validation only
+    field :password, :string
+    def label = 'Invite'
+  end
+
+  setup do
+    # Building a path to this component mints the token from the given account.
+    path do |*args, account: nil, token: nil, **kwargs|
+      if token.blank?
+        fail('Missing kwarg :account in path') if account.nil?
+        token = encode_token(account_id: account.id)
+      end
+      next Rails.application.routes.url_helpers
+              .send("#{path_helper_name}_path", *args, token:, **kwargs)
+    end
+
+    standalone path: '/invites/accept' do
+      skip_authentication!
+      verb :get  do authorize { token_valid?(params) } end
+      verb :post do authorize { token_valid?(params) } end
+    end
+
+    data_class VirtualModel
+    form_cancancan_action nil
+    submit_path { Compony.path(self.class, @data, token: @token) }
+    after_assign_attributes { @data.account_id = token_data(params)[:account_id] }
+
+    store_data do
+      @create_succeeded = @data.validate
+      next unless @create_succeeded
+      Account.find(token_data[:account_id]).update!(password: @data.password)
+    end
+    on_created_respond { redirect_to Compony.path(:show, :sessions) }
+  end
+
+  # Shape-check the decoded payload; anything off → false → 403 (never 500).
+  def token_valid?(params)
+    data = token_data(params)
+    return false if data.blank?
+    Schemacop::Schema3.new(:hash) do
+      int! :account_id, cast_str: true
+      int? :exp
+    end.validate!(data)
+    true
+  rescue Schemacop::Exceptions::ValidationError
+    false                                # token signed for a different flow
+  end
+end
+```
+
+Notes:
+
+- `Compony.path(:accept, :invites, account: some_account)` returns the full tokenized URL —
+  email that. The token, not a session, authorizes the request.
+- `path do` runs outside the request context; build URLs via
+  `Rails.application.routes.url_helpers`, not `controller`/`helpers` (see
+  [standalone.md](/doc/guide/standalone.md#customizing-path-generation)).
+- Reuse the mixin for every link flow (magic login, password reset, email confirm); encode
+  a flow discriminator or rely on the per-component payload shape-check to stop a token
+  minted for one flow being replayed against another.
+- One signed boolean in the payload (e.g. `confirmed: true`) is tamper-proof since the
+  client cannot re-sign — handy for multi-hop confirm flows.
+
+## Good habits
+
+- **CanCanCan everywhere:** `authorize { can?(...) }`, scope with
+  `Model.accessible_by(current_ability)`, bang form `authorize!(:read, record)` for
+  ad-hoc checks in `load_data`.
+- **Always `Compony.path` / `render_intent`,** never hardcoded routes or `button_to`
+  ([gotchas.md #11](/doc/guide/gotchas.md#11-redirect_to-with-a-hardcoded-path), [#15](/doc/guide/gotchas.md#15-hand-rolled-endpoint-where-a-pre-built-crud-component-exists)).
+- **Place a resourceful component in the family of the model it acts on,** not the family
+  it is reached from; pass parent context via path params.
+- **Keep virtual/form-only fields off models** — use ActiveType/VirtualModel
+  ([gotchas.md #16](/doc/guide/gotchas.md#16-attr_accessor-on-a-model-for-form-only-fields)).
+- **`concat`** around every `render_intent`/`render_sub_comp`/`field` in a block.
+
+[Guide index](/README.md#guide--documentation)

data/doc/guide/pre_built_components/edit.md

@@ -21,7 +21,7 @@ In case you overwrite `store_data`, make sure to set `@update_succeeded` to true
 
 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_update_failed` 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`.