brut 0.0.29 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b77e4a2a30122b1805ecf5cb52a5313bb137c188364a6baac62270918cd1640
-  data.tar.gz: 393ad694666d889d5672fb592e7f188e19f78f519f19fbd4a5edb1af32ef5d21
+  metadata.gz: ac39a29b335413475986e02cf9baa658bc44fa2e67e6dbd60dfafa7e4b9c8a2f
+  data.tar.gz: 155a9b104168bd18fe08fd8286576d63305d243d6025a4a1fcbcf1611611a8ed
 SHA512:
-  metadata.gz: 769c54918d2cb9a3e40e007d954c70ef6ec4033bb1a159d616cc4680aaf5b5d650e0335d729a5acc10b0d9f96574c4dfe5ec5f563bbd82828c6878ea4a532338
-  data.tar.gz: 510b4299c42f476f61110382afdb26c1c71ae8f6aecf16f95bebcf30bb5ac14b0817b08bb0787e3b9b541be59add9e35d4d60df78debbe0627b371aa4639ce00
+  metadata.gz: 6126e575575511de23bd9ffe1429f05fa017664c66f7de07fa93b000edfb4f4dfd7c619d76d02d28e69cb70bfe163c4023d7a79cc53e1e41e3a44b5882cd0fd8
+  data.tar.gz: d38e331cd221d1a3bbd666b83a0d3e2df5a17fd4cbdccc47da7ca0df484d8ff46fb91c2f159c9da4fefcb8c829b98a8de4a040f013676170befecc0bcc45c3d1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.29)
+    brut (0.1.0)
       concurrent-ruby
       i18n
       irb

data/README.md

@@ -3,6 +3,8 @@
 Brut is a way to make web apps with Ruby, captializing on the knowledge you have—HTTP, HTML, CSS, JavaScript, SQL—without requiring
 *too* much extra stuff to learn.
 
+![Brut Logo in the style of the Washington DC Metro.  It has the metro brown background with all text in white Helvetica.  Centered at the top is "BrutRB". Below that, in the style of metro stops is "Ruby", next to a red dot with "RB" in it, "HTML/CSS/JS" next to an orange dot with "WP" in it, "Phlex" next to a blue dot with "PL" in it, and "RSpec" next to a green dot with "RS" in it.](brutrb.com/images/LogoStop.png)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -19,6 +21,26 @@ Or install it yourself as:
 
     $ gem install brut
 
+## Getting Started
+
+[Please note there is extensive documentation](https://brutrb.com), however to get started, you can use [mkbrut](https://github.com/thirdtank/mkrbut):
+
+```
+docker run --pull always \
+           -v "$PWD":"$PWD" \
+           -w "$PWD" 
+           -it \
+           thirdtank/mkbrut \
+           mkbrut your-new-app
+```
+
+If you have Ruby 3.4 installed somewhere, you can use this via RubyGems as well:
+
+```
+> gem install mkbrut
+> mkbrut your-new-app
+```
+
 ## Developing
 
 The dev environment is managed by Docker and you are encouraged to use this. It's set up so you can edit your code on your computer
@@ -45,6 +67,5 @@ with your editor, but all commands are run inside Docker, which should be more c
 
         dx/exec bin/setup --no-credentials
 
-   The `--no-credentials` means that you will not be able to push to GitHub or RubyGems from within the Docker container. This
-   ability is only needed by maintainers to push new versions of the gem. You can push to GitHub from your computer.
+   The `--no-credentials` means that you will not be able to push to GitHub or RubyGems from within the Docker container. This ability is only needed by maintainers to push new versions of the gem. You can push to GitHub from your computer.
 

data/brutrb.com/.vitepress/config.mjs

@@ -6,6 +6,33 @@ import jsdocLinker from './plugins/jsdocLinker'
 export default defineConfig({
   title: "Brut RB",
   description: "Documentation for the Brut.RB web framework.",
+  head: [
+    ["link", { rel: "icon", href: "/favicon.ico" }],
+    [
+      "meta", {
+        property: "og:title",
+        content: "BrutRB Documentation"
+      }
+    ],
+    [
+      "meta", {
+        property: "og:type",
+        content: "website"
+      }
+    ],
+    [
+      "meta", {
+        property: "og:image",
+        content: "https://github.com/thirdtank/brut/blob/main/assets/SocialImage.png?raw=true"
+      }
+    ],
+    ["script", {
+      defer: "",
+      "data-domain": "brutrb.com",
+      src: "https://plausible.io/js/script.js"
+    }
+    ],
+  ],
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     search: {
@@ -27,10 +54,11 @@ export default defineConfig({
         items: [
           { text: "Getting Started", link: "/getting-started" },
           { text: "Concepts", link: "/overview" },
-          { text: "Documentation Conventions", link: "/doc-conventions" },
-          { text: "Tutorial", link: "/tutorial" },
+          { text: "Features", link: "/features" },
+          { text: "Directory Structure", link: "/dir-structure" },
           { text: "Dev Environment", link: "/dev-environment" },
-          { text: "AI Declaration", link: "/ai" },
+          { text: "Tutorial", link: "/tutorial" },
+          { text: "Documentation Conventions", link: "/doc-conventions" },
         ]
       },
       {
@@ -41,6 +69,7 @@ export default defineConfig({
           { text: "Pages", link: "/pages" },
           { text: "Layouts", link: "/layouts" },
           { text: "Forms", link: "/forms" },
+          { text: "Form Constraints", link: "/form-constraints" },
           { text: "Handlers and Actions", link: "/handlers" },
           { text: "Components", link: "/components" },
           { text: "Flash and Session", link: "/flash-and-session" },
@@ -98,12 +127,20 @@ export default defineConfig({
         collapsed: true,
         items: [
           { text: "Authentication", link: "/recipes/authentication" },
-          { text: "Form Validations", link: "/recipes/form-validations" },
-          { text: "Database Migrations", link: "/recipes/database-migrations" },
-          { text: "Ajax Form Submission", link: "/recipes/ajax-form" },
-          { text: "Custom Telemetry", link: "/recipes/telemetry" },
-          { text: "CLI App/Task", link: "/recipes/cli-app" },
+          { text: "Alternate Layouts", link: "/recipes/alternate-layouts" },
+          { text: "Blank Layouts", link: "/recipes/blank-layouts" },
+          { text: "Custom Flash Class", link: "/recipes/custom-flash" },
+          { text: "Indexed Form Elements", link: "/recipes/indexed-forms" },
+          { text: "Text Field Component", link: "/recipes/text-field-component" },
         ],
+      },
+      {
+        text: "Meta",
+        collapsed: false,
+        items: [
+          { text: "Why?!", link: "/why" },
+          { text: "AI Declaration", link: "/ai" },
+        ]
       }
     ],
 

data/brutrb.com/.vitepress/theme/style.css

@@ -44,6 +44,7 @@
  * -------------------------------------------------------------------------- */
 
 :root {
+  --vp-c-text-1: #362400;
   --vp-c-default-1: var(--vp-c-gray-1);
   --vp-c-default-2: var(--vp-c-gray-2);
   --vp-c-default-3: var(--vp-c-gray-3);
@@ -54,9 +55,9 @@
   --blue-vp-c-brand-3: #4C0606;
   --blue-vp-c-brand-soft: #FFF9F9;
 
-  --vp-c-brand-1: #362400;
-  --vp-c-brand-2: #F1A100;
-  --vp-c-brand-3: #281B00;
+  --vp-c-brand-1: #001842;
+  --vp-c-brand-2: #6B84B1;
+  --vp-c-brand-3: #0443B1;
   --vp-c-brand-soft: #FFF1D6;
 
 
@@ -115,8 +116,8 @@
   --vp-home-hero-name-color: transparent;
   --vp-home-hero-name-background: -webkit-linear-gradient(
     120deg,
-    #333333 30%,
-    #d14141
+    #D67402 20%,
+    #11AC0E
   );
 
   --vp-home-hero-image-background-image: linear-gradient(

data/brutrb.com/ai.md

@@ -52,22 +52,17 @@ documentation, is produced by a machine, although spelling and grammar correctio
 
 We expect an LLM to be able to digest this documentation and source code and provide alternate analysis of how Brut works and how to use it.  We hope such analysis is correct and useful, however that cannot be guaranteed, so this documentation is the second best source of truth, the source code being the best.
 
-## Logo
+## Logos
 
-The logo is level 4 - ChatGPT created it. I'd love to have a real person make a better one.  I just needed
-something to get this launched.  Please reach out if you want to make a better one + other assets. I'm
-willing to pay a real person.
+While the various logos look like someone typed "make me a logo in the style of the Washington, DC Metro", if you look closely, you will see the telltale sings that they were made by a person…a person who is not a professional designer.
 
-## AI Completions Should Be Viewed with Skepticism
+As such, these are all Level 1.
 
-Due to how LLMs work, there is naturally nothing in any model about Brut.  Anything an
-existing model tells you about Brut is **100% untrustworthy**.  We hope to allow LLMs to consume Brut's
-code, documentation, and examples, so it can be an additional source of help, but currently that is not
-the case.
+## AI Information about Brut Should Be Viewed with Skepticism
 
-**Do not ask an LLM about Brut** until this part of the documentation changes.
-
-For completion-based AI suggestions, **view them with skepticism**.  In my
-experience, completions from e.g. GitHub CoPilot work OK when replicating a pattern
-in the file you are editing, but suggestions in a freshly-opened file tend to be
-entirely imaginary or Rails-based.  Beware.
+* **Answers from an LLM about Brut are likely incorrect.** LLMs will certainly not
+have been trained on information about Brut, since it is new.
+* **Code Completions of Brut Code are suspect.** I have observed that e.g. GitHub
+CoPilot is capable for properly completing Brut code if there is enough context, but
+it is not capable of, say, creating a component from scratch. **Review all Code
+Completions Carefully**.

data/brutrb.com/assets.md

@@ -46,14 +46,7 @@ JavaScript is on line 1 of `app.js`.  This is not helpful for diagnosing issues.
 *SourceMaps* are separate files that translate the minified files back to normal ones, so you can see a normal
 stack trace with the actual line numbers of your source files.
 
-There are many ways to create source maps and if you've used a tool like WebPack, you'll recall that many of them
-don't produce usable source maps.  Brut uses esbuild's facility for this, with a focus on correctness. When
-you see a line number and a source file in your browser, you can be sure it's accurate.
-
-The tradeoff is that it can take longer to produce than producing an inaccurate one. I'm not sure who wants
-inaccurate source maps, but Brut does not support this. In practice, esbuild is quite fast, so it should not make
-a practical difference in your day to day work.
-
+Brut's configuration of esbuild is to produce sourcemaps.
 
 ## Fonts
 
@@ -93,7 +86,7 @@ end
 ## SVGs
 
 You can place `.svg` files in `app/src/front_end/images` if you wish to use them in `<img>` tags.  However, if
-you place svgs in `app/src/front_end/svgs`, they can be inlined into your HTML via `inline_svg`.  In this case,
+you place svgs in `app/src/front_end/svgs`, they can be inlined into your HTML via `inline_svg`, provided by `Brut::FrontEnd::Component::Helpers` and included in all components and pages.  In this case,
 there is no need for a build step, since the SVG source is included directly in your HTML. This works well
 for icons.
 

data/brutrb.com/brut-js.md

@@ -73,7 +73,7 @@ improvements):
 * Default implementations of `connectedCallback` and `attributeChangedCallback` that call the template method `update`, thus allowing your element to centralize its logic in one place, regardless of how a state change was triggered.
 * Static `define()` method that defines your element based on its static `tagName` field. This allows richer interaction of elements, as you can do e.g. `document.querySelector(SomeOtherElement.tagName)`  and better navigate changes to your code over time.
 
-If you are familiary with the API for autonomous custom elements, `BaseCustomElement` doesn't require
+If you are familiar with the API for autonomous custom elements, `BaseCustomElement` doesn't require
 learning much more.  What you know already will be leveraged.
 
 ### Removing BrutJS
@@ -81,10 +81,20 @@ learning much more.  What you know already will be leveraged.
 To remove BrutJS from your app, modify `app/src/front_end/js/index.js` to remove the `import` and call to
 `define()`.  You can then remove it from your `package.json`.
 
-**Note** If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.
+> [!NOTE]
+> If you remove it like this, several features will not work, including locale detection, client-side observability, and client-side form validation UX.
 
 ## Recommnded Practices
 
+### Leaving BrutJS In Your App
+
+BrutJS provides useful tools unrelated to single-page apps, or reactivity, or
+whatever else you might be concerned with in your client-side code.  These features
+can work alongside whatever framework you want to use. Leave them in unless they are
+causing a specific problem.
+
+### You Probably Don't Need a Single-Page App
+
 Consider this decision tree from Alex Russell's [If Not React, Then
 What?](https://infrequently.org/2024/11/if-not-react-then-what/):
 

data/brutrb.com/cli.md

@@ -117,7 +117,7 @@ All of this means that the bulk of CLI-specific code you will write is specifyin
 
 Every CLI app is a class that extends `Brut::CLI::App`. This class should contain one inner class for each subcommand. Those classes should extend `Brut::CLI::App`.
 
-Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in a hash (see below).
+Inside your `Brut::CLI::App` class, you can call a few class methods to declare aspects of the UI. In particular, `opts` returns the `OptionParser` in play that you can use to declare global options.  Unlike `OptionParser`'s `on` method, Brut's does not require providing a block. Brut will store the runtime options in an object (see below).
 
 ```ruby
 class MyAppCLI < Brut::CLI::App
@@ -132,7 +132,7 @@ This code means your app's global options are `--dry-run`, which will not accept
 
 Declaring subcommands provides a similar API.  Let's say our app has a "status" subcommand, and a "run" subcommand.
 
-```ruby
+```ruby {7-11,13-16}
 class MyAppCLI < Brut::CLI::App
   description "My awesome command line app"
 
@@ -189,7 +189,7 @@ end
 
 ### Implementing `execute`
 
-Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all you data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
+Once `execute` is called, your app's internals will have been setup and bootstrapped. That means all your data models can access the database, and any other setup will have ocurred. Generally, `execute` can then have whatever code makes sense.
 
 That said, `execute` has access to a few values to understand the command line invocation and to support testing.
 
@@ -220,23 +220,19 @@ use that affect its behavior.
 
 Currently, Brut doesn't provide a way to create this file, but it's relatively straightforward.  It's almost entirely boilerplate except for your class:
 
-```ruby {14}
+```ruby {9}
 #!/usr/bin/env ruby
 
 require "bundler"
 Bundler.require
 require "pathname"
-
-require "brut/cli"
-
-APP_PATH = File.join(File.dirname($0),"..","app","src")
-$: << APP_PATH
-require "cli/my_app"
+require "brut/cli/apps/db"
 
 exit Brut::CLI.app(
-  MyAppCLI,
-  project_root: Pathname($0).dirname / ".."
-)
+      Brut::CLI::Apps::DB,
+      project_root: Pathname($0).dirname / ".."
+     )
+
 ```
 
 ## Testing

data/brutrb.com/components.md

@@ -12,136 +12,159 @@ Components in Brut are Phlex Components: a class that can hold data and use that
 
 ### Simple Component
 
-For example, suppose you want a re-usable button component whose HTML would look like so:
 
-```html
-<button class="button button__small button__red">
-  Delete Files
-</button>
-```
+For example, suppose you want a re-usable button that can be gray, green, or red, and have an optional `formaction`.
 
-Your button can be large (the default) or small, and could be gray (default), green, or red.  Your button could also have an optional `formaction` attribute. Let's also suppose the label could be a string or embedded HTML.
 
-Your constructor would need to accept the size, color, label, and formaction.
-
-You can create a scaffold via `bin/scaffold`:
+You can create a component with `bin/scaffold component`:
 
 ```
-> bin/scaffold component Button
+bin/scaffold component button
+# => app/src/front_end/components/button_component.rb
+# => specs/front_end/components/button_component.spec.rb
 ```
 
-You'll first implement the initializer, like so:
+Component inititalizers are called by you when you use them, so you can define it
+how you like.  Brut uses keyword arguments by convention.
 
 ```ruby
-# app/src/front_end/components/button.rb
-class Button < AppComponent
-  def initialize(
-    size: :large,
-    color: :gray,
-    formaction: nil,
-    label: :use_block
-  )
-    @size       = size
+# app/src/front_end/components/button_component.rb
+class ButtonComponent < AppComponent
+  def initialize(color: :gray,
+                 formaction: nil)
     @color      = color
     @formaction = formaction
-    @label      = label
   end
 end
 ```
 
-This initializer is rather simplistic. You may want to validate the values here to prevent the construction of an invalid component.
-
-Now, implement `view_template`.  This method will receive a block if one is given when the component is used. We'll see an example in a minute.
+Since it's a Phlex component, implement `view_template` to generate the HTML you
+like.  Our `view_template` will `yield` so the button's contents can be controlled
+by the caller.  Note that the CSS here is [BrutCSS](/brut-css/index.html), but it
+can be anything you are using in your oapp.
 
 ```ruby
-# app/src/front_end/components/button.rb
-class Button < AppComponent
+# app/src/front_end/components/button_component.rb
+class ButtonComponent < AppComponent
 
   # ...
 
   def view_template
     attributes = {
       class: [
-        "button",
-        "button__#{@size}",
-        "button__#@{color}",
+        "tc",               # centered text
+        "br-3",             # border radius @ 3rd step of scale
+        "bn",               # no border
+        "f-3",              # font size @ 3rd step of scale
+        "ph-4",             # horizontal padding @ 4th step of scale
+        "pv-2",             # vertical padding @ 2nd step of scale
+        "bg-#{@color}-800", # background is second lighest of scale
+        "#{@color}-300",    # text is third darkest of scale
       ],
-      formaction: @formaction,
+      formaction: @formaction
     }
 
     button(**attributes) do
-      if @label == :use_block
-        yield
-      else
-        @label
-      end
+      yield
     end
   end
 end
 ```
 
-If you've never used Phlex before, it's refreshingly straightforward:
+Here are two examples of how you'd use this component and the HTML that would be
+generated:
+
+::: code-group
+
+```ruby
+render ButtonComponent(color: :green) do
+  "Click Here"
+end
+```
+
+```html
+<button class="tc br-3 bn f-3 ph-4 pv-2 bg-green-800 green-300">
+  Click Here
+<button>
+```
 
-* There's a method for each  HTML element.
-* The method's parameters produce attributes in the HTML that is generated.
-* If a parameter's value is an array (like `class:`), the values are joined with strings to form the atttribute's value in HTML.
-* If the element can have inner content, whatever happens inside a yielded block becomes that inner content.
+:::
 
-To use this component, we can call `render` in either the `view_template` of another component or the `page_template` of a [page](/pages):
+::: code-group
 
 ```ruby
-def view_template
-  form do
-    render Button.new(label: "Submit")
-    render Button.new(label: "Nevermind", size: :small, color: :red)
-    render Button.new(color: :green) do
-      img(src: "/images/ok.png", alt: "OK icon")
-    end
-  end
+render ButtonComponent(color: :red, formaction: DeleteWidget.routing) do
+  "Delete Widget"
 end
 ```
 
-Note that the block passed to `render` is the block available when `yield` is called inside `view_template`.
+```html
+<button class="tc br-3 bn f-3 ph-4 pv-2 bg-red-800 green-300"
+        formaction="/delete_widget">
+  Delete Widget
+<button>
+```
+:::
 
-There are two special types of components beyond what we have just seen.  *Global* Components and *Page private* components.
+One issue with components is that you must pass them all their initializer arguments
+to use them.  This means that if your component needs access to, say, the session,
+any page or component that uses your component must also require the session to
+be passed in.
+
+Brut provides a partial solution to this called *global components*.
 
 ### Global Components
 
-As we saw above, creating a component is just like creating any Ruby class: you call `.new` on it.  If you create a component that uses request-level data, such as the flash or session, it would mean that any page or component that used *that* component would need to accept the flash or session as a parameter to its initializer, even if it it was otherwise not needed.
+A global component can be created by Brut using [keyword
+injection](/keyword-injection). This means that, in our example above, a page that
+uses your component does not need to be given the session.  It can have Brut inject
+it.
 
-In those cases, `global_component` can be used to leverage [keyword injection](/keyword-injection) to have Brut create the component.  That way, its initializer's parameters don't need to be passed into the page or component using the global component.
+This provides a partial solution to so-called "prop drilling".
 
-Suppose we had a component to display the flash:
+In [the features overview](/features), we saw a basic component for rendering a
+flash:
 
 ```ruby
-class FlashMessage < AppComponent
-
+# components/flash_component.rb
+class FlashComponent < AppComponent
   def initialize(flash:)
-    @flash = flash
+    if flash.notice?
+      @message_key = flash.notice
+      @role = :info
+    elsif flash.alert?
+      @message_key = flash.alert
+      @role = :alert
+    end
   end
 
+  def any_message? = !@message_key.nil?
+
   def view_template
-    if @flash.notice?
-      div(role: "status") { @flash.notice }
-    elsif @flash.alert?
-      div(role: "alert") { @flash.alert }
+    if any_message?
+      div(role: @role) do
+        t([ :flash, @message_key ])
+      end
     end
   end
 end
 ```
 
-To use it without having to instantiate it, call `global_component` with the component's class:
+Instead of requiring each user of this component to manually inject the flash, we
+can call `global_component`, provided by `Brut::FrontEnd::Component::Helpers`, which
+is included in all pages and components.
 
 ```ruby
-class HomePage < AppPage
-  def page_template
-    header do
-      global_component(FlashMessage) # note: render not required
-    end
+def view_template
+  header do
+    global_component(FlashComponent)
   end
 end
 ```
 
+Components used in layouts will tend to be global components, to avoid creating odd
+dependencies between pages.
+
 > [!IMPORTANT]
 > Brut currently requires an all-or-nothing approach to global components. Either 
 > the component can be injected with all its initializer parameters or it must
@@ -157,9 +180,19 @@ Often, components are helpful to simplifying a page's template or managing re-us
 
 Brut provides a way to create a *page private* component that exists as an inner class of a page.  It's not truly private, since it's still a Ruby class anyone can use, but it's form and source location communicate intent.
 
-Suppose our `HomePage` has a list of widgets on it, but we want each widget's HTML managed by a separate component:
+They can be created with `bin/scaffold`:
 
-```ruby
+```
+bin/scaffold component --page HomePage Widget
+# => app/src/front_end/page/home_page/widget_component.rb
+# => specs/front_end/page/home_page/widget_component.spec.rb
+```
+
+The class will be an inner class of `HomePage` in this example, `HomePage::WidgetComponent`. You build them and use them like normal:
+
+::: code-group
+
+```ruby [Page]
 class HomePage < AppPage
   def page_template
     header do
@@ -176,16 +209,7 @@ class HomePage < AppPage
 end
 ```
 
-`HomePage::WidgetListItem` can be created like so:
-
-```
-bin/scaffold component --page=HomePage WidgetListItem
-```
-
-This will create `app/src/front_end/pages/home_page/widget_list_item.rb`, which you can then implement like a normal component:
-
-```ruby
-# app/src/front_end/pages/home_page/widget_list_item.rb
+```ruby [Page Private Component]
 class HomePage::WidgetListItem < AppComponent
   def initialize(widget:)
     @widget = widget
@@ -200,27 +224,25 @@ class HomePage::WidgetListItem < AppComponent
 end
 ```
 
-The only special thing about a page private component is that it can access the page's I18n translations. As we'll discussion in [I18n](/i18n), The `t` method will try to locate translations based on the page on which `t` is called.  A page private component will also trigger this behavior, but a normal component will not.
-
-For example, the following code will look for `pages.HomePage.status.«status»` when generated the `<h3>`:
+:::
 
-```ruby {10}
-# app/src/front_end/pages/home_page/widget_list_item.rb
-class HomePage::WidgetListItem < AppComponent
-  def initialize(widget:)
-    @widget = widget
-  end
+The main difference between a page-private component and a normal component's
+behavior is how [I18n](/i18n) strings are resolved.  In short, given this:
 
-  def view_template
-    li do
-      h2 { @widget.name }
-      h3 { t([ :status, @widget.status ]) }
-      p { @widget.description }
-    end
-  end
+```ruby
+p do
+  t(:hello)
 end
 ```
 
+In a normal component named `WidgetComponent`, the keys searched for translations
+would be `"components.WidgetComponent.hello"` and `"hello"` .  For the page-private
+component `HomePage::WidgetComponent`, the keys searched would be
+`"pages.HomePage.hello"` and `"hello"`.  This means that page private components can
+access a page's translations.
+
+
+
 ## Testing
 
 Test widgets exactly as you would [pages](/pages#testing). The only difference is that components always render HTML and have no `before_generate` concept.