brut 0.0.1 → 0.0.2

data/doc-src/handlers.md

@@ -0,0 +1,83 @@
+# 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

@@ -0,0 +1,265 @@
+# 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

@@ -0,0 +1,183 @@
+# 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.