brut 0.0.13 → 0.0.21

data/doc-src/handlers.md

@@ -1,83 +0,0 @@
-# Handlers
-
-In Brut, a *handler* responds to an HTTP request that *isn't* inteded to render a web page.  Primarily, a handler is used to process a
-form submission, but a handler can also respond to an Ajax request.  A handler is like a controller in Rails, however in Brut, a
-handler is a class you implement that has a method that receives arguments and a return value that controls the response (unlike controllers in Rails).
-
-## Defining a Route to be Handled
-
-There are three ways to define a route that requires a handler, `form`, `action`, and `path`.
-
-    
-    class App < Brut::Framework::App
-
-      routes do
-
-        form   "/new_widget"
-        action "/archive_widget/:id"
-        path   "/payment_received", method: :get
-      end
-    end
-
-`form` indicates you have a form you are going to render in HTML and process its submission.  The use of `form` requires that you have
-a {Brut::FrontEnd::Form} defined (see {file:doc-src/forms.md}) as well as a handler.  The names are conventional based on the route.
-In the example above, Brut will expect `NewWidgetForm` and `NewWidgetHandler` to exist.
-
-You can create these with `bin/scaffold`:
-
-    bin/scaffold form NewWidget
-
-`action` is used when you have a form to submit, but it has no user controls to collect the data to submit.  This is akin to Rails'
-`button_to` where the URL describes everything needed to handle a user's action.  In the example above, you can imagine a form with a
-method to `/archive_widget/<%= widget.id %>` that has a button labeled "Archive Widget".  All that's needed is to submit to the
-server.
-
-In that case, only a handler is required.  The name is again conventional. In this case, `ArchiveWidgetWithId`.  You can create this
-with `bin/scaffold`
-
-    bin/scaffold handler ArchiveWidthWithId
-
-The last case, `path`, is for arbitray routes.  It works the same way as `action`, but requires a `method:` to declare the HTTP
-method.
-
-## Implementing a Handler
-
-Regardless of how you declare a route, all handlers must inherit {Brut::FrontEnd::Handler} (though realistically, they will inherit
-`AppHandler`, which inherets `Brut::FrontEnd::Handler`) and implement `handle`.
-
-`handle` can accept keyword arguments that are injected by Brut according to the rules outlined in {file:/doc-src/keyword-injection.md Keyword Injection}.  Note that handlers that process forms should declare `form:` as a keyword argument. They will be given an instantiated instance of their form, based on the values in the form submission from the browser.
-
-The return value of the method determines what will happen:
-
-* `URI` - the visitor is redirected to this URI. Typically, you'd achieve this with the {Brut::FrontEnd::HandlingResults#redirect_to}
-helper.
-* {Brut::FrontEnd::Component} - this component's HTML is rendered. Note that since {Brut::FrontEnd::Page} is a subclass of
-`Brut::FrontEnd::Component}, returning a page instance will render that entire page.  This is useful when re-rendering a page with
-form errors.
-  - You can also return a two-element array with the first element being a component and the second being a `Brut::FrontEnd::HttpStatus`.  This will render the component's HTML but use the given status as the HTTP status.
-* {Brut::FrontEnd::HttpStatus} - this status is returned with no content. Typically, you'd achieve this with the {Brut::FrontEnd::HandlingResults#http_status}
-* {Brut::FrontEnd::Download} - a file will be downloaded
-
-## Hooks
-
-See {file:/doc-src/hooks.md} for more discussiong, but implementing `before_handle` will allow you to run code before `handle` is
-called.  This feature is mostly useful for a base class or module to share re-usable logic.
-
-## Testing Handlers
-
-Since a handler is just a class, you can test it conventionally, but there are a few things to keep in mind that can make testing your
-handler easier.
-
-First is that you should call `handle!`, not `handle`.  The public interface of a handler is `handle!`—`handle` is a template method.
-`handle!` will call `before_render`, so you should still call `handle!`, even if you are testing the logic in `before_render`.
-
-You can also simplify your expectations with the following matchers:
-
-* `have_redirected_to` - asserts that the handler redirected to the given URL. It can be given a `URI` or a page class.
-* `have_rendered`- asserts that the handler renders the given component or page.  It expects the page or component class.
-* `have_returned_http_status` - asserts that the handler returned the given HTTP status.  This works for a lot of return values that
-the handler can return:
-  - If the handler returned a `URI`, the matcher will match on a 302 and fail otherwise
-  - If the handler returns an HTTP status code, the matcher's code must match (or the code must be omitted)
-  - If the handler returns anything else, the matcher will match on a 200 and fail otherwise
-

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.