Docs/auto bundle rename and dummy reference (#1758)

* rename BarComponentTwo to SpecialComponentNotToAutoLoadBundle in the Solution section
* Revise documentation for React component bundle loading

---------

Co-authored-by: Justin Gordon <[email protected]>

Author: ihabadham

docs/guides/file-system-based-automated-bundle-generation.md

@@ -17,6 +17,9 @@ default:
 
 For more details, see [Configuration and Code](https://github.com/shakacode/shakapacker#configuration-and-code) section in [shakapacker](https://github.com/shakacode/shakapacker/).
 
+> Example (dummy app): `nested_entries: true` with a different `source_path: client/app`. See `config/shakapacker.yml` in the dummy app.
+> [Dummy shakapacker.yml](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/shakapacker.yml)
+
 ### Configure Components Subdirectory
 
 `components_subdirectory` is the name of the matched directories containing components that will be automatically registered for use by the view helpers.
@@ -28,6 +31,9 @@ config.components_subdirectory = "ror_components"
 
 Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) helper methods provided by React on Rails.
 
+> Example (dummy app): the configured components subdirectory is named `startup` instead of `ror_components`.
+> [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb)
+
 ### Configure `auto_load_bundle` Option
 
 For automated component registry, [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call.
@@ -38,6 +44,9 @@ You can change the value in `config/initializers/react_on_rails` by updating it
 config.auto_load_bundle = true
 ```
 
+> Example (dummy app): `auto_load_bundle` is set to `true` in the same initializer.
+> [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb)
+
 ### Location of generated files
 
 Generated files will go to the following two directories:
@@ -65,6 +74,9 @@ import './../generated/server-bundle-generated.js';
 
 We recommend committing this import statement to your version control system.
 
+> Example (dummy app): see the server bundle entrypoint import.
+> [Dummy server-bundle.js](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/packs/server-bundle.js)
+
 ## Usage
 
 ### Basic usage
@@ -146,24 +158,26 @@ The tricky part is to figure out which bundles to load on any Rails view. [Shaka
 
 File-system-based automated pack generation simplifies this process with a new option for the view helpers.
 
-For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` and `BarComponentOne`, but not `BarComponentTwo` (for whatever reason), then...
+> Note: In the Background examples above, we used `BarComponentTwo`. In the Solution below, we refer to the same component as `SpecialComponentNotToAutoLoadBundle` to emphasize that it is excluded from auto-loading. You do not need to rename your files.
+
+For example, if you wanted to utilize our file-system based entrypoint generation for `FooComponentOne` and `BarComponentOne`, but not `SpecialComponentNotToAutoLoadBundle` (formerly `BarComponentTwo`) (for whatever reason), then...
 
 1. Remove generated entrypoints from parameters passed directly to `javascript_pack_tag` and `stylesheet_pack_tag`.
 2. Remove generated entrypoints from parameters passed directly to `append_javascript_pack_tag` and `append_stylesheet_pack_tag`.
 
    Your layout would now contain:
 
    ```erb
-   <%= javascript_pack_tag('BarComponentTwo') %>
-   <%= stylesheet_pack_tag('BarComponentTwo') %>
+   <%= javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
+   <%= stylesheet_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
    ```
 
 3. Create a directory structure where the components that you want to be auto-generated are within `ReactOnRails.configuration.components_subdirectory`, which should be a subdirectory of `Shakapacker.config.source_path`:
 
    ```text
    app/javascript:
      └── packs:
-     │   └── BarComponentTwo.jsx  # Internally uses ReactOnRails.register
+     │   └── SpecialComponentNotToAutoLoadBundle.jsx  # Internally uses ReactOnRails.register
      └── src:
      │   └── Foo
      │   │ └── ...
@@ -174,16 +188,17 @@ For example, if you wanted to utilize our file-system based entrypoint generatio
      │   │ └── ror_components          # configured as `components_subdirectory`
      │   │   │ └── BarComponentOne.jsx
      │   │ └── something_else
-     │   │   │ └── BarComponentTwo.jsx
+     │   │   │ └── SpecialComponentNotToAutoLoadBundle.jsx
    ```
 
    4. You no longer need to register the React components within the `ReactOnRails.configuration.components_subdirectory` nor directly add their bundles. For example, you can have a Rails view using three components:
 
       ```erb
-      <% append_javascript_pack('BarComponentTwo') %>
       <%= react_component("FooComponentOne", {}, auto_load_bundle: true) %>
       <%= react_component("BarComponentOne", {}, auto_load_bundle: true) %>
-      <%= react_component("BarComponentTwo", {}) %>
+
+      <% append_javascript_pack_tag('SpecialComponentNotToAutoLoadBundle') %>
+      <%= react_component("SpecialComponentNotToAutoLoadBundle", {}) %>
       ```
 
       If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper can be used on the Rails view, as illustrated below.
@@ -208,6 +223,8 @@ For example, if you wanted to utilize our file-system based entrypoint generatio
 
 If server rendering is enabled, the component will be registered for usage both in server and client rendering. To have separate definitions for client and server rendering, name the component files `ComponentName.server.jsx` and `ComponentName.client.jsx`. The `ComponentName.server.jsx` file will be used for server rendering and the `ComponentName.client.jsx` file for client rendering. If you don't want the component rendered on the server, you should only have the `ComponentName.client.jsx` file.
 
+> Example (dummy app): paired files such as [`ReduxApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/ReduxApp.client.jsx) and [`ReduxApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/ReduxApp.server.jsx), and [`RouterApp.client.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/RouterApp.client.jsx) and [`RouterApp.server.jsx`](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/client/app/startup/RouterApp.server.jsx).
+
 Once generated, all server entrypoints will be imported into a file named `[ReactOnRails.configuration.server_bundle_js_file]-generated.js`, which in turn will be imported into a source file named the same as `ReactOnRails.configuration.server_bundle_js_file`. If your server bundling logic is such that your server bundle source entrypoint is not named the same as your `ReactOnRails.configuration.server_bundle_js_file` and changing it would be difficult, please let us know.
 
 > [!IMPORTANT]