compony 0.11.8 → 0.11.9

data/doc/file.README.html

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

data/doc/file.basic_component.html

@@ -0,0 +1,314 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  File: basic_component
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "basic_component";
+  relpath = '';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="file_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="_index.html">Index</a> &raquo; 
+    <span class="title">File: basic_component</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><div id='filecontents'>
+<p><a href="/README_md.html#guide--documentation">Back to the guide</a></p>
+
+<h1 id="label-What+is+a+component-3F">What is a component?</h1>
+
+<p>Compony components are nestable elements that are capable of replacing Rails’ routes, views and controllers. They structure code for data manipulation, authentication and rendering into a single class that can easily be subclassed. This is achieved with Compony’s DSL that provides a readable and overridable way to store your logic.</p>
+
+<p>Just like Rails, Compony is opinionated and you are advised to structure your code according to the examples and explanations. This makes it easier for others to dive into existing code.</p>
+
+<h1 id="label-A+basic+-28bare-29+component">A basic (bare) component</h1>
+
+<h2 id="label-Naming">Naming</h2>
+
+<p>Compony components must be named according to the pattern <code>Components::FamilyName::ComponentName</code>.</p>
+<ul><li>
+<p>The family name should be pluralized and is analog to naming a Rails controller. For instance, when you would create a <code>UsersController</code> in plain Rails, the Compony family equivalent is <code>Users</code>.</p>
+</li><li>
+<p>The component name is the Compony analog to a Rails action.</p>
+</li></ul>
+
+<p>Example: If your plain Rails <code>UsersController</code> has an action <code>show</code>, the equivalent Compony component is <code>Components::Users::Show</code> and is located under <code>app/components/users/show.rb</code>.</p>
+
+<p>If you have abstract components (i.e. components that your app never uses directly, but which you inherit from), you may name and place them arbitrarily.</p>
+
+<h2 id="label-Initialization-2C+manual+instantiation+and+rendering">Initialization, manual instantiation and rendering</h2>
+
+<p>You will rarely have to override <code>def initialize</code> of a component, as most of your code will go into the component’s <code>setup</code> block as explained below. However, when you do, make sure to forward all default arguments to the parent class, as they are essential to the component’s function:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='id identifier rubyid_some_positional_argument'>some_positional_argument</span><span class='comma'>,</span> <span class='id identifier rubyid_another'>another</span><span class='op'>=</span><span class='kw'>nil</span><span class='comma'>,</span> <span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='comma'>,</span> <span class='label'>some_keyword_argument:</span><span class='comma'>,</span> <span class='label'>yetanother:</span> <span class='int'>42</span><span class='comma'>,</span> <span class='op'>**</span><span class='id identifier rubyid_kwargs'>kwargs</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_block'>block</span><span class='rparen'>)</span>
+  <span class='kw'>super</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='comma'>,</span> <span class='op'>**</span><span class='id identifier rubyid_kwargs'>kwargs</span><span class='comma'>,</span> <span class='op'>&amp;</span><span class='id identifier rubyid_block'>block</span><span class='rparen'>)</span> <span class='comment'># Typically you should call this first
+</span>  <span class='ivar'>@foo</span> <span class='op'>=</span> <span class='id identifier rubyid_some_positional_argument'>some_positional_argument</span>
+  <span class='ivar'>@bar</span> <span class='op'>=</span> <span class='id identifier rubyid_another'>another</span>
+  <span class='ivar'>@baz</span> <span class='op'>=</span> <span class='id identifier rubyid_some_keyword_argument'>some_keyword_argument</span>
+  <span class='ivar'>@stuff</span> <span class='op'>=</span> <span class='id identifier rubyid_yetanother'>yetanother</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>Typically, your components will be instantiated and rendered by Compony through the <a href="./standalone_md.html">“standalone” feature</a>. Nonetheless, it is possible to do so manually as well, for instance if you’d like to render a component from within an existing view in your application:</p>
+
+<pre class="code ruby"><code class="ruby">&lt;% index_users_comp = Components::Users::Index.new %&gt;
+&lt;%= index_users_comp.render(controller) %&gt;
+</code></pre>
+
+<p>Note that rendering a component always requires the controller as an argument. It also possible to pass an argument <code>locals</code> that will be made available to <code>render</code> (see below):</p>
+
+<pre class="code ruby"><code class="ruby">&lt;% index_users_comp = Components::Users::Index.new %&gt;
+&lt;%= index_users_comp.render(controller, locals: { weather: :sunny }) %&gt;
+</code></pre>
+
+<h2 id="label-Setup">Setup</h2>
+
+<p>Every component must call the static method <code>setup</code> which will contain most of the code of your components. This can be achieved either by a call directly from your class, or by <a href="/doc/guide/inheritance_md.html">inheriting</a> from a component that calls <code>setup</code>. If both classes call the method, the inherited class’ <code>setup</code> is run first and the inheriting’s second, thus, the child class can override setup properties of the parent class.</p>
+
+<p>Call setup as follows:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'><span class='object_link'><a href="Components.html" title="Components (module)">Components</a></span></span><span class='op'>::</span><span class='const'>Users</span><span class='op'>::</span><span class='const'>Show</span> <span class='op'>&lt;</span> <span class='const'><span class='object_link'><a href="Compony.html" title="Compony (module)">Compony</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Compony/Component.html" title="Compony::Component (class)">Component</a></span></span>
+  <span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+    <span class='comment'># Your setup code goes here
+</span>  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>The code in setup is run at the end the component’s initialization. In this block, you will call a number of methods that define the component’s behavior and which we will explain now.</p>
+
+<h3 id="label-Labelling">Labelling</h3>
+
+<p>This defines a component’s label, both as seen from within the component and from the outside, e.g. from an <a href="/doc/guide/intents_md.html">intent</a>. You can query the label in order to display it as a title in your component. Links and buttons to components will also display the same label, allowing you to easily rename a component, including any parts of your UI that point to it.</p>
+
+<p>Labels come in different formats, short and long, with long being the default. Define them as follows if your component is about a specific object, for instance a show component for a specific user:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:short</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_user'>user</span><span class='op'>|</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span> <span class='rbrace'>}</span> <span class='comment'># Assuming your User model has a method or attribute `label`.
+</span>  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:long</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_user'>user</span><span class='op'>|</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Displaying user </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span> <span class='comment'># In practice, you&#39;d probably use I18n.t or FastGettext here to deal with translations.
+</span>
+  <span class='comment'># Or use this short hand to set both long and short label to the user&#39;s label:
+</span>  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:all</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='op'>|</span><span class='id identifier rubyid_user'>user</span><span class='op'>|</span> <span class='id identifier rubyid_user'>user</span><span class='period'>.</span><span class='id identifier rubyid_label'>label</span> <span class='rbrace'>}</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>To read the label, from within the component or from outside, proceed as follows:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='rparen'>)</span> <span class='comment'># This returns the long version: &quot;Displaying user John Doe&quot;.
+</span><span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='const'>User</span><span class='period'>.</span><span class='id identifier rubyid_first'>first</span><span class='comma'>,</span> <span class='label'>format:</span> <span class='symbol'>:short</span><span class='rparen'>)</span> <span class='comment'># This returns the short version &quot;John Doe&quot;.
+</span></code></pre>
+
+<p>It is important to note that since your label block takes an argument, you must provide the argument when reading the label. Only up to one argument is supported. Typically, label blocks of all <a href="/doc/guide/resourceful_md.html">resourceful components</a> take 1 argument while all others take 0.</p>
+
+<p>Here is an example on how labelling looks like for a component that is not about a specific object, such as an index component for users:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:long</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>List of users</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
+  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:short</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>List</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>And to read those:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_label'>label</span> <span class='comment'># &quot;List of users&quot;
+</span><span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='label'>format:</span> <span class='symbol'>:short</span><span class='rparen'>)</span> <span class='comment'># &quot;List&quot;
+</span></code></pre>
+
+<p>If you do not define any labels, Compony will fallback to the default which is using Rail’s <code>humanize</code> method to build a name from the family and component name, e.g. “index users”.</p>
+
+<p>Additionally, components can specify an icon and a color. These are not used by Compony directly and it is up to you to to define how and where to use them. Example:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_color'>color</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>#AA0000</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
+  <span class='id identifier rubyid_icon'>icon</span> <span class='lbrace'>{</span> <span class='qsymbols_beg'>%i[</span><span class='tstring_content'>fa-solid</span><span class='words_sep'> </span><span class='tstring_content'>circle</span><span class='tstring_end'>]</span></span> <span class='rbrace'>}</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>To retrieve them from outside the component, use:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_my_component'>my_component</span><span class='period'>.</span><span class='id identifier rubyid_color'>color</span> <span class='comment'># &#39;#AA0000&#39;
+</span><span class='id identifier rubyid_my_component'>my_component</span><span class='period'>.</span><span class='id identifier rubyid_icon'>icon</span> <span class='comment'># [:&#39;fa-solid&#39;, :circle]
+</span></code></pre>
+
+<h3 id="label-Providing+content">Providing content</h3>
+
+<p>Basic components do not come with default content. Instead, you must call the method <code>content</code> inside the setup block and provide a block containing your view. It will be evaluated inside a <a href="/doc/guide/internal_datastructures_md.html#requestcontext">request context</a>.</p>
+
+<p>In this block, provide the HTML to be generated using Dyny: <a href="https://github.com/kalsan/dyny">github.com/kalsan/dyny</a></p>
+
+<p>Here is an example of a component that renders a title along with a paragraph:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:all</span><span class='rparen'>)</span> <span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Welcome</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_h1'>h1</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Welcome to my basic component.</span><span class='tstring_end'>&#39;</span></span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>It&#39;s not much, but it&#39;s honest work.</span><span class='tstring_end'>&quot;</span></span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<h4 id="label-Naming+content+blocks-2C+ordering+and+overriding+them+in+subclasses">Naming content blocks, ordering and overriding them in subclasses</h4>
+
+<p>Content blocks are actually named. The <code>content</code> call adds or replaces a previously defined content block, e.g. in an earlier call to <code>setup</code> in a component’s superclass. When calling <code>content</code> without a name, it defaults to <code>main</code> and will overwrite any previous <code>main</code> content. However, you can provide your own name and refer to other names by using the <code>before:</code> keyword.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='kw'>do</span> <span class='comment'># will become :main
+</span>    <span class='id identifier rubyid_h1'>h1</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Welcome to my basic component.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:thanks</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Thank you and see you tomorrow.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:middle</span><span class='comma'>,</span> <span class='label'>before:</span> <span class='symbol'>:thanks</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This paragraph is inserted between the others.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:thanks</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Thank you and see you tonight.</span><span class='tstring_end'>&#39;</span></span> <span class='comment'># this overwrites &quot;Thank you and see you tomorrow.&quot;
+</span>  <span class='kw'>end</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:first</span><span class='comma'>,</span> <span class='label'>before:</span> <span class='symbol'>:main</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>This appears first.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>This results in:  - This appears first.  - Welcome to my basic component.  - This paragraph is inserted between the others.  - Thank you and see you tonight.</p>
+
+<p>As you see, overusing this feature can lead to messy code as it becomes unclear what happens in what order. For this reason, this feature should only be used to decouple the content of your abstract components for allowing surgical overrides in <a href="/doc/guide/inheritance_md.html">subclasses</a>.</p>
+
+<p>It is a good convention to always have one content block named <code>:main</code>, as you might want to refer to it in subclasses.</p>
+
+<h4 id="label-Nesting+content+blocks-2C+calling+a+content+block+from+another">Nesting content blocks, calling a content block from another</h4>
+
+<p>In some situations, such as in forms, it can be useful to nest content blocks. This will also allow subclasses to override a wrapper while keeping the content, and vice versa. To make this possible, you can also use the <code>content</code> keyword inside a content block. Note that unlike the call in <code>setup</code>, this call will render a content block instead of defining it. This happens inside the request context and the content block must be defined inside the current component.</p>
+
+<p>Note that you cannot call another component’s content block this way.</p>
+
+<p>Here is an example on how to use this feature, e.g. to create a bootstrap card that can be overridden with precision:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># Components::Bootstrap::Card
+</span><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='label'>hidden:</span> <span class='kw'>true</span> <span class='kw'>do</span> <span class='comment'># hidden: true will cause `render` to skip this content block. You can still use it in the nested fashion.
+</span>    <span class='id identifier rubyid_div'>div</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>I am the default content for the card</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+
+  <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:card</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_div'>div</span> <span class='label'>class:</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>card card-body</span><span class='tstring_end'>&#39;</span></span> <span class='kw'>do</span>
+      <span class='id identifier rubyid_content'>content</span> <span class='symbol'>:main</span>
+    <span class='kw'>end</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>The output is:</p>
+
+<pre class="code ruby"><code class="ruby">&lt;div class=&quot;card card-body&quot;&gt;&lt;div&gt;I am the default content for the card&lt;/div&gt;&lt;/div&gt;
+</code></pre>
+
+<p>So when you subclass this component, you can forget about the card and just overwrite <code>:main</code> as follows:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># Components::Hello::HelloCard &lt; Components::Bootstrap::Card
+</span><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_content'>content</span> <span class='kw'>do</span> <span class='comment'># hidden is still true because the old :main content block specified that already.
+</span>    <span class='id identifier rubyid_h1'>h1</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Hello</span><span class='tstring_end'>&#39;</span></span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Welcome to my site.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>The output is:</p>
+
+<pre class="code ruby"><code class="ruby">&lt;div class=&quot;card card-body&quot;&gt;&lt;h1&gt;Hello&lt;/h1&gt;&lt;p&gt;Welcome to my site.&lt;/p&gt;&lt;/div&gt;
+</code></pre>
+
+<h4 id="label-Removing+content+blocks">Removing content blocks</h4>
+
+<p>If a component’s parent class defines a content block that is undesired in a subclass component, the content block can be removed as follows:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_remove_content'>remove_content</span> <span class='symbol'>:some_content_defined_in_parent</span> <span class='comment'># This component will now behave as if this content block was never declared in its parent.
+</span><span class='kw'>end</span>
+</code></pre>
+
+<h3 id="label-Redirecting+away+-2F+Intercepting+rendering">Redirecting away / Intercepting rendering</h3>
+
+<p>Immediately before the <code>content</code> block(s) are evaluated, another chain of blocks is evaluated if present: <code>before_render</code>. If on of these blocks creates a reponse body in the Rails controller, the subsequent <code>before_render</code> blocks and all <code>content</code> blocks are skipped.</p>
+
+<p>This is useful for redirecting. Here is an example of a component that provides a restaurant’s lunch menu, but redirects to the menu overview page instead if it’s not lunch time:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_setup'>setup</span> <span class='kw'>do</span>
+  <span class='id identifier rubyid_label'>label</span><span class='lparen'>(</span><span class='symbol'>:all</span><span class='rparen'>)</span><span class='lbrace'>{</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Lunch menu</span><span class='tstring_end'>&#39;</span></span> <span class='rbrace'>}</span>
+
+  <span class='id identifier rubyid_before_render'>before_render</span> <span class='kw'>do</span>
+    <span class='id identifier rubyid_current_time'>current_time</span> <span class='op'>=</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_zone'>zone</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span>
+    <span class='kw'>if</span> <span class='id identifier rubyid_current_time'>current_time</span><span class='period'>.</span><span class='id identifier rubyid_hour'>hour</span> <span class='op'>&gt;=</span> <span class='int'>11</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_current_time'>current_time</span><span class='period'>.</span><span class='id identifier rubyid_hour'>hour</span> <span class='op'>&lt;</span> <span class='int'>14</span>
+      <span class='id identifier rubyid_flash'>flash</span><span class='period'>.</span><span class='id identifier rubyid_notice'>notice</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Sorry, it&#39;s not lunch time.</span><span class='tstring_end'>&quot;</span></span>
+      <span class='id identifier rubyid_redirect_to'>redirect_to</span> <span class='const'><span class='object_link'><a href="Compony.html" title="Compony (module)">Compony</a></span></span><span class='period'>.</span><span class='id identifier rubyid_path'><span class='object_link'><a href="Compony.html#path-class_method" title="Compony.path (method)">path</a></span></span><span class='lparen'>(</span><span class='symbol'>:index</span><span class='comma'>,</span> <span class='symbol'>:menus</span><span class='rparen'>)</span>
+    <span class='kw'>end</span>
+  <span class='kw'>end</span>
+
+  <span class='id identifier rubyid_content'>content</span> <span class='kw'>do</span> <span class='comment'># This is entirely skipped if it&#39;s not lunch time.
+</span>    <span class='id identifier rubyid_h1'>h1</span> <span class='id identifier rubyid_label'>label</span>
+    <span class='id identifier rubyid_para'>para</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>Today we have spaghetti.</span><span class='tstring_end'>&#39;</span></span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span>
+</code></pre>
+
+<p>Note how Compony’s <a href="/doc/guide/intents_md.html#componypath">path helper</a> is used to generate the path. This is the recommended approach to redirecting to a component.</p>
+
+<p>Similarly to <code>content</code>, the <code>before_render</code> method also accepts a name, defaulting to <code>:main</code>, as well as a <code>before:</code> keyword. This allows you to selectively extend and/or override <code>before_render</code> blocks in subclasses.</p>
+
+<p><a href="/README_md.html#guide--documentation">Guide index</a></p>
+</div></div>
+
+      <div id="footer">
+  Generated on Mon May 18 13:55:33 2026 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.3.5).
+</div>
+
+    </div>
+  </body>
+</html>

data/doc/file.cookbook.html

@@ -0,0 +1,189 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  File: cookbook
+  
+    &mdash; Documentation by YARD 0.9.34
+  
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+
+<script type="text/javascript">
+  pathId = "cookbook";
+  relpath = '';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="file_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+  
+    <a href="_index.html">Index</a> &raquo; 
+    <span class="title">File: cookbook</span>
+  
+</div>
+
+        <div id="search">
+  
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+  
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><div id='filecontents'>
+<p><a href="/README_md.html#guide--documentation">Back to the guide</a></p>
+
+<h1 id="label-Cookbook">Cookbook</h1>
+
+<p>Task-oriented entry point: “I want to do X — where is it?”. Every recipe lives in <a href="./patterns_md.html">Real-world patterns</a> or the guide; this page is a pure index by goal so you don’t need to know a pattern’s name. Nothing is duplicated here — only links.</p>
+
+<h2 id="label-Recipes+by+task">Recipes by task</h2>
+
+<table role="table">
+<thead>
+<tr>
+<th>I want to…</th>
+<th>See</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Share layout/chrome across all components</td>
+<td>[patterns §1 base layer](./patterns.md#1-the-app-base-component-layer)</td>
+</tr>
+<tr>
+<td>Add a CRUD screen with almost no code</td>
+<td>[patterns §2 thin leaves](./patterns.md#2-thin-leaf-components), [example.md](./example.md)</td>
+</tr>
+<tr>
+<td>List records with columns/filters/sorts</td>
+<td>[List](./pre_built_components/list.md), [patterns §3–4](./patterns.md#3-index–load_data-scope–nested-list)</td>
+</tr>
+<tr>
+<td>Scope/order what an Index shows</td>
+<td>[patterns §3](./patterns.md#3-index–load_data-scope–nested-list) (‘load_data`)</td>
+</tr>
+<tr>
+<td>Embed a child list inside a Show</td>
+<td>[patterns §4](./patterns.md#4-list-customization), [nesting.md](./nesting.md)</td>
+</tr>
+<tr>
+<td>Build a custom form + strong params</td>
+<td>[patterns §5](./patterns.md#5-custom-form–schemacop-kept-in-sync), [Form](./pre_built_components/form.md)</td>
+</tr>
+<tr>
+<td>Nested attributes in a form</td>
+<td>[patterns §5](./patterns.md#5-custom-form–schemacop-kept-in-sync), [example_advanced.md](./example_advanced.md)</td>
+</tr>
+<tr>
+<td>Autocomplete / ajax select field</td>
+<td>[patterns §6](./patterns.md#6-autocomplete-form-app-level-subclass)</td>
+</tr>
+<tr>
+<td>Split a detail page into tabs</td>
+<td>[patterns §7](./patterns.md#7-tabbed-show-via-a-mixin)</td>
+</tr>
+<tr>
+<td>Prefill/derive fields before save</td>
+<td>[patterns §8](./patterns.md#8-lifecycle-hooks-for-derived-data) (‘after_assign_attributes`)</td>
+</tr>
+<tr>
+<td>Guard/redirect before rendering</td>
+<td>[patterns §8](./patterns.md#8-lifecycle-hooks-for-derived-data), [basic_component.md](./basic_component.md#redirecting-away–intercepting-rendering)</td>
+</tr>
+<tr>
+<td>Customize the action toolbar</td>
+<td>[patterns §9](./patterns.md#9-exposed-intents-as-the-action-toolbar), [intents.md](./intents.md#exposed-intents)</td>
+</tr>
+<tr>
+<td>Disable a button with a reason</td>
+<td>[feasibility.md](./feasibility.md), [patterns §9](./patterns.md#9-exposed-intents-as-the-action-toolbar)</td>
+</tr>
+<tr>
+<td>Export CSV / PDF</td>
+<td>[patterns §10](./patterns.md#10-csv–pdf-via-respond-format)</td>
+</tr>
+<tr>
+<td>Launch a background job from a button</td>
+<td>[patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone)</td>
+</tr>
+<tr>
+<td>Toggle a boolean (activate/lock/…)</td>
+<td>[patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone)</td>
+</tr>
+<tr>
+<td>Clone/duplicate a record</td>
+<td>[patterns §11](./patterns.md#11-non-crud-job-dispatch-toggles-clone)</td>
+</tr>
+<tr>
+<td>Non-persistent / upload-only form</td>
+<td>[patterns §12](./patterns.md#12-virtual-model-for-non-persistent–upload-forms), [virtual_models.md](./virtual_models.md)</td>
+</tr>
+<tr>
+<td>Public page / inbound webhook</td>
+<td>[patterns §13](./patterns.md#13-public-endpoints–webhooks), [gotchas §14](./gotchas.md#14-public-endpoint-still-401redirecting)</td>
+</tr>
+<tr>
+<td>Custom button look</td>
+<td>[patterns §14](./patterns.md#14-custom-button-style), [intents.md](./intents.md#adding-your-own-styles)</td>
+</tr>
+<tr>
+<td>Inline-edit a card without a full page</td>
+<td>[patterns §15 turbo-frame inline edit](./patterns.md#15-inline-edit-card-with-a-turbo-frame)</td>
+</tr>
+<tr>
+<td>Multi-step wizard across components</td>
+<td>[patterns §16 multi-step wizard](./patterns.md#16-multi-step-wizard-across-components)</td>
+</tr>
+<tr>
+<td>Reorder/inline-patch without a form</td>
+<td>[patterns §17 inline PATCH](./patterns.md#17-inline-patch-without-a-form-reorder–quick-toggle)</td>
+</tr>
+<tr>
+<td>Magic-login / invite / reset / confirm link (no session)</td>
+<td>[patterns §18 signed-token capability links](./patterns.md#18-signed-token-capability-links-auth-less-onboarding–magic-links)</td>
+</tr>
+</tbody>
+</table>
+
+<p>If a goal isn’t listed, check the <a href="./dsl_reference_md.html">DSL reference</a> and <a href="./glossary_md.html">glossary</a>.</p>
+
+<p><a href="/README_md.html#guide--documentation">Guide index</a></p>
+</div></div>
+
+      <div id="footer">
+  Generated on Mon May 18 13:55:34 2026 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.34 (ruby-3.3.5).
+</div>
+
+    </div>
+  </body>
+</html>