brut 0.0.20 → 0.0.21

data/doc-src/javascript.md

@@ -1,265 +0,0 @@
-# JavaScript and Front End Behavior
-
-Brut does not prevent you from using any front-end framework you like.  You can certainly install React and reference it in
-`app/src/front_end/javascript/index.js`.  However, Brut would like to humbly request that you not do this.
-
-Brut is based around server-generated HTML and the web platform.  This means that Brut would like you to use custom elements for any
-client-side behavior you need, and to do so with progressive enhancement.
-
-To that end, Brut includes BrutJS, which is a set of custom elements and ancillary JavaScript you can use to build client-side
-behavior.
-
-By default, your `index.js` will look like this:
-
-    import { BrutCustomElements } from "brut-js"
-    import Example from "./Example"
-
-    document.addEventListener("DOMContentLoaded", () => {
-      BrutCustomElements.define()
-      Example.define()
-    })
-
-`BrutCustomElements` and `BrutCustomElements.define()` will set up the custom elements bundled with Brut.  `Example` shows you how to
-build your own custom elements.
-
-## Some Useful Brut Elements
-
-Please refer to BrutJS's documentation for everything that is included, but here are a few highlights that you will find usefule.
-
-### Client Side Form Support
-
-{file:doc-src/forms.md Forms} outlines Brut's server-side form support.  Brut provides custom elements to allow you to unify client
-and server side constraint validations, and make the process a bit easier to manage with CSS.
-
-First, surrounding a form with a `<brut-form>` will place `data-submitted` onto the `<form>` *only* when the user attempts to submit the
-form.  You can use this in your CSS to prevent showing error messages before a user has submitted.
-
-Second, you can use `<brut-cv-messages>` and `<brut-cv>` to control the error messages that are shown when the browser detects
-constraint violations.  This works with `<brut-i18n-translation>` to show translated strings.
-
-Consider this ERB
-
-    <label>
-      <%= 
-        component(
-          Brut::FrontEnd::Components::Inputs::TextField.for_form_input(form:, input_name: :name)
-        )
-      %>
-      <span>Name</span>
-      <%= constraint_violations(form:,input_name: :name) %>
-    </label>
-
-{Brut::FrontEnd::Component::Helpers#constraint_violations} will render the built-in {Brut::FrontEnd::Components::ConstraintViolations}
-component.  Along with `for_form_input`, the following HTML will be generated:
-
-    <label>
-      <input type="text" name="name" required>
-      <span>Name</span>
-      <brut-cv-messages input-name="name">
-      </brut-cv-messages>
-    </label>
-
-When any element of the form causes a validity event to be fired, `<brut-form>` will locate the appropriate `<brut-cv-messages>` and
-insert the appropriate `<brut-cv>` elements.  Suppose the user submitted this form. Since the `name` input is required, the form
-submission wouldn't happen, and the resulting HTML would look like so:
-
-    <label>
-      <input type="text" name="name" required>
-      <span>Name</span>
-      <brut-cv-messages input-name="name">
-        <brut-cv input-name="name" key="valueMissing"></brut-cv>
-      </brut-cv-messages>
-    </label>
-
-Now, assuming your layout used `<brut-i18n-translation>` custom elements, for example like so:
-
-    <brut-i18n-translation key="general.cv.fe.valueMissing">%{field} is required</brut-i18n-translation>
-
-The `<brut-cv>` custom element will find this and replace its `textContent`, resulting   in the following HTML:
-
-    <label>
-      <input type="text" name="name" required>
-      <span>Name</span>
-      <brut-cv-messages input-name="name">
-        <brut-cv input-name="name" key="valueMissing">
-          This field is required
-        </brut-cv>
-      </brut-cv-messages>
-    </label>
-
-You can now use CSS to style client-side validations *and* control the content shown to the user.  If there are server-side constraint
-violations, The `ConstraintViolations` component would render them (as well as server-generated translations), for example if a name
-was given, but it's taken already, `ConstraintViolations` would render this HTML:
-
-    <label>
-      <input type="text" name="name" required value="foo">
-      <span>Name</span>
-      <brut-cv-messages input-name="name">
-        <brut-cv input-name="name" server-side>
-          This value has been taken
-        </brut-cv>
-      </brut-cv-messages>
-    </label>
-
-### Confirming Dangerous Actions
-
-Often, you want to use JavaScript to confirm the submission of a form whose action is considered dangerous to the user or hard to undo.
-This can be achieved with `<brut-confirm-submit>`
-
-    <form>
-      <input type="text" name="name" required>
-      <brut-confirm-submit message="This will delete the app">
-        <button>Delete App</button>
-      </brut-confirm-submit>
-    </form>
-
-By default, this will use the browser's built-in `window.confirm`, however you can also use a `<dialog>` element as well.
-
-If the generated HTML includes a `<dialog>`, you can surround it with `<brut-confirmation-dialog>` to indicate it should be used for
-confirmation.  The `<dialog>` should have an `<h1>` where the message will be placed and two buttons, one with `value="ok"` and one
-with `value="cancel"`.
-
-
-    <brut-confirmation-dialog>
-      <dialog>
-        <h1></h1>
-        <button value="ok">Do It!</button>
-        <button value="cancel">Nevermind</button>
-      </dialog>
-    </brut-confirmation-dialog>
-
-When the `<brut-confirm-submit>`'s `<button>` is clicked, this `<dialog>` is shown with the message inserted.  If the user hits the
-button with `value` of `"ok"`, the form submission goes through. Otherwise, it doesn't.  The dialog is then hidden.
-
-### Ajax Form Submission
-
-To submit a form via Ajax, you can use `<brut-ajax-submit>` around the `<button>` that should submit the form with Ajax.  This element
-attempts to provide a fault-tolerant user experience and will set various attributes on itself to allow you to change styling during
-the various phases of the request.
-
-If the submission works, it will fire a `brut:submitok` event that your custom code can receive and do whatever makes the most sense
-in that case.
-
-If the submission fails with a 422, your server should return a series of `<brut-cv>` custom elements.  If it does, this will be
-inserted into the correct `<brut-cv-messages>` elements to dynamically create error messages.  The element will then fire a
-`brut:submitinvalid` event you can catch and handle to do something custom.
-
-If the submission times out or fails in some other way, Brut will submit the form the old-fashioned way.
-
-### Client-Side, Accessible Tabs
-
-Many UIs involve a set of tabs that switch between different views.  While HTML has no built-in support for this, Brut's `<brut-tabs>`
-custom element can captialize on the various ARIA roles required to design a tabbed interface and provide all the JavaScript behavior
-necessary.  See that element's documentation for an extended example.
-
-## Building Your Own Custom Elements
-
-Because custom elements are part of the web platform, Brut encourages you to use them to add client-side behavior.  As a
-demonstration of this working, there is an `Example` element set up when you created your app.  Assuming your app's prefix was `cc`
-when you created it, the `Example` element works like so:
-
-      <cc-example transform="upper">
-        Here is some text
-      </cc-example>
-
-When the browser renders this—assuming JavaScript is enabled—it will render the following:
-
-      <cc-example transform="upper">
-        HERE IS SOME TEXT
-      </cc-example>
-
-You wouldn't want to do this, but this simple element demonstrates both how to make your own and that custom elements in your app are
-properly configured.
-
-This element is very close to a vanilla custom element, but it extends `BaseCustomElement`, which is provided by BrutJS, which includes
-z few quality-of-life improvements. Let's walk through the code.
-
-First, we extends `BaseCustomElement` (which extends `HTMLElement`) and define a static attribute, `tagName` that will be the
-element's tag name you can use in your HTML:
-
-    import { BaseCustomElement } from "brut-js"
-
-    class Example extends BaseCustomElement {
-      static tagName = "cc-example"
-
-Next, we'll define the attributes of our element using `observedAttributes`, which is part of the custom element spec (and not
-specific to BrutJS):
-
-      static observedAttributes = [
-        "transform",
-        "show-warnings",
-      ]
-
-The `show-warnings` attribute, if placed on the element's HTML, configures `this.logger` from `BaseCustomElement` to allow output of debug messages. This allows you to easily debug your element's behavior in development, but remove them from production.  We'll see that in a bit.
-
-Next, we'll set a private attribute to hold a default value for the `transform` HTML attribute. It can be named anything:
-
-      #transform = "upper"
-
-Now, we want to know when `transform` changes.  Normally, you'd implement `attributeChangedCallback` and check its `name` parameter.
-`BaseCustomElement` allows you to do this more directly by creating a `xxxChangedCallback` method for each attribute in
-`observedAttributes` that you want to know about.  For `transform`, that means implementing `transformChangedCallback`:
-
-      transformChangedCallback({newValue}) {
-        this.#transform = newValue
-      }
-
-Next, we implement the bulk of the element's behavior.  Because there are many lifecycle events that may require modifying the
-element, `BaseCustomElement` consolidates all of those events and calls the method `update()`.  `update()` should be idempotent
-and should examine the element's state (as well as the document's, if necessary) and update the element however it makes sense.
-
-For this example, we want to grab the content, examine the value for `transform` and change the content:
-
-      update() {
-        const content = this.textContent
-        if (this.#transform == "upper") {
-          this.textContent = content.toLocaleUpperCase()
-        }
-        else if (this.#transform == "lower") {
-          this.textContent = content.toLocaleLowerCase()
-        }
-        else {
-          this.logger.info("We only support upper or lower, but got %s",this.#transform)
-        }
-      }
-
-Notice the last line where we call `this.logger.info`.  If `show-warnings` is omitted from the HTML, this message isn't shown anywhere. If `show-warnings` *is* present, this message will show up in the console.  This can be useful for understanding why your element isn't working.
-
-Lastly, we export the class:
-
-    }
-    export default Example
-
-By virtue of having extended `BaseCustomElement`, the static `define()` method will set it up as a custom element with the browser.
-
-## Testing Custom Elements
-
-Sometimes, system tests are sufficient to ensure your custom element code is working.  If not, Brut (via BrutJS) provides a way to
-test your element in isolation.
-
-These tests use JSDom which, while not perfect, allows the tests to run reasonably quickly.  Each test begins with `withHTML` to
-define the markup that is being tested.  This is followed by `test` which accepts a function that performs the test.
-
-Rather than have a DSL to provide access to your element's state, you can use the browser's API (as provided by JSDom) to check
-whatever it is you need to check:
-
-    import { withHTML } from "./SpecHelper.js"
-
-    describe("<cc-example>", () => {
-      withHTML(`
-      <cc-example>This is some Text</cc-example>
-      `).test("upper case by default", ({document,assert}) => {
-        const element = document.querySelector("cc-example")
-        assert.equal(element.textContent,"THIS IS SOME TEXT")
-      })
-      withHTML(`
-      <cc-example transform="lower">This is some Text</cc-example>
-      `).test("lower case when asked", ({document,assert}) => {
-        const element = document.querySelector("cc-example")
-        assert.equal(element.textContent,"this is some text")
-      })
-    })
-
-Note that `test`'s second argument—the function that performs the test—is called with objects you can use to perform the test. In this
-case, the `document` is passed in as-is the `assert` method.
-

data/doc-src/keyword-injection.md

@@ -1,183 +0,0 @@
-# Keyword Injection
-
-Brut is desiged around classes and objects, as compared to modules and DSLs.  Almost everything you do when creating your app is to
-create a class that has an initializer and implements one or more methods.  But, these initalizers and methods often need information
-from the request that Brut is managing.
-
-In a basic Rack or Sinatra app, you would access stuff like query parameters or the session by using Rack's API.  This can be tedious
-and error-prone.  Brut will inject certain values into your class based on the keyword arguments of the initializer or method.
-
-For example, a {file:doc-src/pages.md Page} requires you to implement an initializer. That initializer's keyword arguments define what
-information is needed. Brut provides that information when it creates the object. This is a form of dependency injection and it can simplify your code if used effectively.
-
-Consider this route:
-
-    page "/widgets/:id"
-
-Brut will expect to find `WidgetsByIdPage`.  Your initializer can declare `id:` as a keyword arg and this will be passed when the
-class is created:
-
-    class WidgetsByIdPage < AppPage
-      def initialize(id:)
-        @widget = DB::Widget.find(id)
-      end
-    end
-
-There are many more values that can made available.  For example, suppose you accept the query string parameter "compact" that
-controls some rendering of the page.  To access it, declare it as a keyword arg (being sure to set a default value since it may not be available):
-
-    class WidgetsByIdPage < AppPage
-      def initialize(id:, compact: false)
-        @widget  = DB::Widget.find(id)
-        @compact = compact
-      end
-    end
-
-## Standard Injectible Information
-
-In any request, the following information is available to be injected:
-
-* `session:` - An instance of your app's {Brut::FrontEnd::Session} subclass for the current visitor's session.
-* `flash:` - An instance of your app's {Brut::FrontEnd::Flash} subclass.
-* `xhr:` - true if this was an Ajax request.
-* `body:` - the body submitted, if any.
-* `csrf_token:` - The current CSRF token.
-* `clock:` - A {Clock} to be used to access the current time in the visitor's time zone.
-* `http_*` - any parameter that starts with `http_` is assumed to be for an HTTP header. For example, `http_accept_language` would be
-given the value for the "Accept-Language" header.  See the section on HTTP headers below.
-* `env:` - The Rack env.  This is discouraged, but available if you can't get what you want directly
-
-Depending on the context, other information is available:
-
-* `form:` - If a form was submitted, this is the {Brut::FrontEnd::Form} subclass containing the data. See {file:doc-src/forms.md Forms}.
-* Any query string paramter - Remember, these should have default values or Brut will raise an error if they are not provided.
-* Any route parameter - These should not have default values, since they are required for Brut to match the route.
-
-A {Brut::FrontEnd::RouteHook} is slightly different. Only the following data is available to be injected:
-
-* `:request_context` - The current request context, thought it may be `nil` depending on when the hook runs
-* `session:` - An instance of your app's {Brut::FrontEnd::Session} subclass for the current visitor's session.
-* `:request` - The Rack request
-* `:response` - The Rack response
-* `env:` - The Rack env.
-
-### HTTP Headers
-
-Since any header can be sent with a request, Brut allows you to access them, including non-standard ones.  Rack (which is based on CGI), provides access to all HTTP headers in the `env` by taking the header name, replacing dashes ("-") with underscores ("\_"), and prepending `http_` to the name, then uppercasing it.  Thus, "User-Agent" becomes `HTTP_USER_AGENT`.
-
-Because Ruby parameters and variables must start with a lower-case letter, Brut uses the lowercased version of the Rack/CGI variable.
-Thus, to receive the "User-Agent", you would declare the keyword parameter `http_user_agent`.
-
-Further, because headers come from the client and may not be under your control, the value that is actually injected depends on a few
-things:
-
-* If your keyword arg is required, i.e. there is no default value:
-  - If the header was not provided, `nil` is injected.
-  - If the header *was* provided, it's value is injected, even if it's the empty string.
-* If your keyword arg is optional, i.e.  it has a default value
-  - If the header was not provided, no value is injected, and your code will receive the default value.
-  - If the header *was* provided, it's value is injected, even if it's the empty string.
-
-### Ordering and Disambiguation
-
-You are discouraged from using builtin keys for your own data or request parameters.  For example, you should not have a query string
-parameter named `env` as this conflicts with the builtin `env` that Brut will inject.
-
-Since you can inject your own data (see below), you are free to corrupt the request context.  Please don't do this. Brut may actively
-prevent this in the future.
-
-You can also use the request context to put your own data that can be injected.
-
-## Injecting Custom Data
-
-The general lifecycle of a request is that any before hook is run, then the page or action is triggered, then after actions.  Thus, to
-inject your own data, such as the currently authenticated visitor, you would use a before hook:
-
-    class AppSession < Brut::FrontEnd::Session
-      def logged_in?
-        !!self.authenticated_account
-      end
-      def authenticated_account
-        # look up the account data model 
-        # based on e.g. self[:account_id]
-      end
-    end
-
-    class AuthBeforeHook < Brut::FrontEnd::RouteHook
-      def before(request_context:,session:,request:,env:)
-        if session.logged_in?
-          request_context[:authenticated_account] = session.authenticated_account
-        end
-        continue
-      end
-    end
-
-Once you do this, you can use `authenticated_account:` as a keyword argument to any page, handler, or global component:
-
-    class DashboardPage < AppPage
-      def initialize(authenticated_account:)
-        @widgets = authenticated_account.widgets # e.g.
-      end
-    end
-
-While this won't handle authorization for you, you can be sure that when `DashboardPage` is used, there is an `authenticated_account`
-available.
-
-## `nil` and Empty Strings
-
-When a keyword argument has no default value, Brut will require that value to exist and be available for injection. If the keyword is
-not one of the canned always-available values, it will look in the request context, then in the query string.
-
-If the request has the keyword as a key, *it will inject whatever value it finds, including `nil`*.  In general, you should avoid
-injecting `nil` when you actually intend to not have a value.
-
-For example, the `AuthBeforeHook` above, you could implement it like so:
-
-      request_context[:authenticated_account] = session.authenticated_account
-
-The problem is that if the visitor is not logged in, the `:authenticated_account` *will* have a value, and that value will be `nil`.
-This is almost certainly not what you want.
-
-For query string parameters, the HTTP spec says that they are strings.  Thus, if a query string parameter is present in ther request
-URL, it will *always* have a value and *never* be `nil`.  If the paramter doesn't have a value after the `=` (e.g. for `foo` in `?foo=&bar=quux`), the value will be the empty string.
-
-This means you must write code to explicitly handle the cases you care about.
-
-## When Values Aren't Available
-
-When a value is not available for injection, and the keyword doesn't provide a default, Brut will raise an error.  This is because
-such a situation represents a design error.
-
-For example, the `DashboardPage` above requires an `authenticated_account`.  Your app should never route a logged-out visitor to that
-page.  This allows the `DashboardPage` to avoid having to check for `nil` and figure out what to do.
-
-This is most relevant for query string parameters, since they can be easily manipulated by the visitor in their browser.  Query string
-parameters should always have a default value, even if it's `nil`.
-
-*Path* parameters (like `:id` in `WidgetsByIdPage`) should *never* have a default value as their absence means a different URL was
-requested.  For example, `/widgets` would trigger a `WidgetsPage`. *Only* if the `:id` path parameter is present would the
-`WidgetsByIdPage` be triggered, so it's safe to omit the default value for `id:` (and pointless to include one).
-
-See {file:docs-src/route-hooks.md}
-
-## Design For Injection
-
-Consider a method like so:
-
-    def create_widget(name:, organization: nil, quantity: 10)
-
-Outside of Brut, the way to interpret this arguments is as follows:
-
-* `name` is required
-* `organization` is optional
-* `quantity` has a default value of 10 if not provided
-
-Any method or intializer that will be keyword-injected should be designed with this in mind.  Thus, the following guidelines will be
-helpful in managing your app:
-
-* **Choose arguments based on the needs of the class:**
-  - If a value is optional, default it to either `nil` or a symbol that indicates what happens when the value is omitted
-  - If an optional value has a default, use that (this should be rare for pages, handlers, components, and hooks)
-  - Otherwise, do not provide a default for the keyword
-* **Do not inject `nil` into the request context.** When your code requires a value for a keyword, you want to rely on that value being non-nil.  Thus, avoid injecting `nil` into the request context. Brut will allow it as a sort-of escape hatch, but you should design your app to avoid it
-* **Be careful injecting global data.**  The request context instance is per request, but you could certainly put global data into it. For example, you may put an initialized API client into the request context as a convieniece. **Be careful** because your app is multi-threaded.  Any object that is not scoped to the request must be thread-safe.

data/doc-src/pages.md

@@ -1,210 +0,0 @@
-# Pages and Components
-
-A website is made up of pages.  Even a web *app* has pages.  Thus, the most basic way to create dynamic behavior with Brut is the
-*page*.  In Brut, a page is a URL, a subclass of {Brut::FrontEnd::Page}, and an ERB template.  The template is rendered in the context
-of an instance of the class whenever the URL is requested.
-
-## Overview of Rendering Pages
-
-In your `app.rb`, you first declare a page using the {Brut::SinatraHelpers::ClassMethods#page} method (inside the block given to {Brut::Framework::App.routes}):
-
-    class App < Brut::Framework::App
-
-      routes do
-
-        page "/sign_in"
-      end
-    end
-
-The name of the route must start with a `/` and the rest of the route determines the name of the page.  In the example above, Brut
-will expect to find a class named `SignInPage`, which should be located in `app/src/front_end/pages`.  You can create it with
-`bin/scaffold`:
-
-    > bin/scaffold page SignInPage
-
-The page class must subclass {Brut::FrontEnd::Page}.  You write a constructor to accept whatever your page needs to assemble the data
-needed to render it.
-
-The HTML is generated based on an ERB file located in `app/src/front_end/pages`.  In this example, that's
-`app/src/front_end/pages/sign_in_page.html.erb`.  That ERB is executed with an instance of the page class as context.  That means you
-can references any methods or ivars.
-
-## Creating a Page Class
-
-{Brut::FrontEnd::Page#render} is called by Brut and expects to receive HTML, which it will send as the body of the response. `render`
-manages the ERB rendering, so the bulk of your page's logic will be in other methods.  The constructor is where any data you need is
-provided.
-
-A page's `initialize` method must accept only keyword arguments and those keywords are used by Brut to determine what data needs to be
-passed in.  This technique, called *{file:doc-src/keyword-injection.md Keyword Injection}*, is used in several other places in Brut.
-
-When the page's URL is requested, an instance of your page class is created, passing in the values needed.  Beyond that, however, your page class is a normal Ruby class. You can save data to instance variables, implement attributes or other methods. Basically, whatever logic your page needs to render will exist in the page class.
-
-## Implementing Your ERB
-
-ERB is part of the Ruby standard library that allows the creation of dynamic templates.  Brut's ERB is close to this implementation, but has a few additional features that make working with HTML a bit safer.
-
-### Your Page is the Only Context
-
-The instance of your page class is the only context available to the ERB.  There is no set of global helpers that are injected, nor
-are there any modules added when the page is rendered.  Anything you need to do in your ERB must be available to the page class you've
-created.
-
-The reason for this is to keep things simple.  If your page's HTML needs access to a lot of stuff, your page class will be the source
-of truth as to where that stuff comes from.  You will always be able to figure out where methods are defined by looking at the page
-class or any of its ancestors.  You are free to `include` as many modules as you like, or dump lots of methods into your `AppPage`
-base class. But you don't have to.
-
-### All Strings are HTML-Escaped
-
-Any instance of a `String` is HTML-escaped by Brut before being inserted into the HTML being generated by the ERB.  This is, generally, what you want to have happen.  If you have a string that you believe is safe and does not need to be escaped, you can prevent HTML-escaping in one of two ways:
-
-* Call {Brut::FrontEnd::Component#html_safe!} on the string
-
-        <%= html_safe!(get_value) %>
-
-* Wrap the string in a {Brut::FrontEnd::Templates::HTMLSafeString}.
-
-        def get_value
-          Brut::FrontEnd::Templates::HTMLSafeString.from_string(some_value)
-        end
-
-  This is what `html_safe!` does and this is what Brut does internally. Brut doesn't monkey-patch `String`. A `String` is always
-  considered unsafe, and an `HTMLSafeString` is always considered safe.
-
-Both of these methods are verbose, but this is on purpose.  You generally don't want un-escaped HTML going into your HTML, but if you
-do, you may find it better to create a component (see below), or use {Brut::FrontEnd::Component::Helpers#html_tag} to generate markup.
-
-### Pages Have Layouts
-
-The page's ERB is rendered in the context of a *layout*.  A Layout works similar to how it works in Rails. It's intended to hold HTML
-needed by every page of your app. A minimal layout might look like so:
-
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <meta charset="utf-8">
-        <%= component(Brut::FrontEnd::Components::PageIdentifier.new(self.page_name)) %>
-        <link rel="preload" as="style" href="<%= asset_path('/css/styles.css') %>">
-        <link rel="stylesheet"         href="<%= asset_path('/css/styles.css') %>">
-        <script defer src="<%= asset_path('/js/app.js') %>"></script>
-      </head>
-      <body>
-        <%= yield %>
-      </body>
-    </html>
-
-The layout is rendered in the context of the page class, so every page must provide whatever features are needed by the layout. This
-is usually done by adding globally-used functions to `AppPage`, which is the base class of all your app's pages.
-
-A page can use another layout by overriding {Brut::FrontEnd::Page#layout}.  The string returned must match a file in
-`app/src/front_end/layouts/`.
-
-### There Are No Partials
-
-Rails partials are not part of ERB, and Brut does not include this feature. Instead, you would use *Components*.
-
-## Decompose and Re-Use with Components
-
-*Components* in Brut are very similar to the View Components library, though somewhat simpler.  A component is a class and an ERB
-template.  That template is rendered in the context of an instance of the class.  That class is created the same way a page is and has
-a `render` method that works just like a page's.
-
-This is all because {Brut::FrontEnd::Page} extends {Brut::FrontEnd::Component}.  A page adds the concept of a layout, but generally a
-page and a component are the same thing.
-
-### Using Components
-
-The main difference from your perspective is that generally *you* create instances of components.  This means that your page must have
-access to any data a component needs.  When you've created your component instance, use {Brut::FrontEnd::Component#component} to
-render it:
-
-    <%= component(Button.new(type: :danger, label: "Cancel Subscription")) %>
-
-### Components with Templates
-
-The most common way to use a component is with an ERB template. It is expected to be in `app/src/front_end/components`.  For the
-hypothetical `Button` component above, Brut would expect `app/src/front_end/components/button.html.erb` to exist as a template.
-
-Just like a page, the component's ERB is rendered in the context of the component only.
-
-Sometimes, components are simple enough that you don't need HTML.
-
-### Components That Render Themselves
-
-While overriding `render` in a page is generally discouraged, {Brut::FrontEnd::Component#render} can be overridden if you want to
-generate HTML yourself.  The best way to do that is with {Brut::FrontEnd::Component::Helpers#html_tag}, though you can always return a
-`String` or {Brut::FrontEnd::Templates::HTMLSafeString} that you've created yourself. Just remeber that all `String` instances will be
-HTML-escaped.
-
-As an example, here is how you might have a Markdown component that renders Markdown as HTML:
-
-    class MarkdownComponent < AppComponent
-      def initialize(markdown:)
-        @markdown = markdown
-        @renderer = Redcarpet::Markdown.new(
-          Redcarpet::Render::HTML.new(
-            filter_html: true,
-            no_images: true,
-            no_styles: true,
-            safe_links_only: true,
-          ),
-          fenced_code_blocks: true,
-          autolink: true,
-          quote: true,
-        )
-      end
-
-      def render
-       html_safe!(@renderer.render(@markdown.to_s))
-      end
-    end
-
-
-### Global Components
-
-While a component is just a class with an initializer, sometimes you need a component that is generally useful on any page, but that
-you don't want to initialize.  For example, if your component needs access to the flash, but your page does not, you don't want your
-page to require a flash just to pass to the component.  In that case, a *global component* can be used and Brut will instantiate it.
-
-{Brut::FrontEnd::Component#component} can be given a class, and Brut will use keyword injection to create it.  Consider a generic
-flash component:
-
-    class GlobalFlash < AppComponent
-
-      attr_reader :flash
-
-      def initialize(flash:)
-        @flash = flash
-      end
-    end
-
-You can use this anywhere like so:
-
-    <%= component(GlobalFlash) %>
-
-Because the flash is availble from the {Brut::FrontEnd::RequestContext}, Brut can create this component when needed.
-
-## Testing Pages and Components
-
-Pages and Components are classes with a constructor you create and a well-defined primary method called `render`.  This means you can
-test them conventionally, since they can be directly created in your tests.
-
-That said, you likely want to test the generated HTML and not the methods of the class.  All tests of a page or component have the
-methods in {Brut::SpecSupport::ComponentSupport} available.  Of particular interest is
-{Brut::SpecSupport::ComponentSupport#render_and_parse}.
-
-This method accepts an instance of a page or component, parses the resulting HTML with Nokogiri, and returns a
-{Brut::SpecSupport::EnhancedNode}, which wraps a `Nokogiri::XML::Node` or `Nokogiri::XML::Element`, depending on what was parsed.  You
-can then use Nokogiri's API locate elements and assert on them.
-
-To keep close to the web platform, it's recommended to use CSS selectors either via {Brut::SpecSupport::EnhancedNode#e} or {Brut::SpecSupport::EnhancedNode#e!} (both of which wrap Nokogiri's `css` method).
-
-Instead of creating another API for accessing HTML content, the Nokogiri API should be used directly.  You can create custom matchers
-as needed for common assertions.  Brut includes a few that you will find useful:
-
-* `have_link_to`
-* `have_html_attribute`
-* `have_i18n_string`
-
-