active_element 0.0.9 → 0.0.11

data/rspec-documentation/pages/000-Introduction.md

@@ -0,0 +1,18 @@
+# Introduction
+
+_ActiveElement_ provides a range of rich [components](components.html) for fast, painless development of front end applications, primarily intended for (but not limited to) building administration areas.
+
+An [authorization framework](access-control.html) is provided, intended to work alongside existing frameworks such as [Devise](https://github.com/heartcombo/devise), [Pundit](https://github.com/varvet/pundit), and [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+
+## Highlights
+
+* Feature-rich [forms](components/forms.html) including a powerful [JSON form field component](components/form-fields/json.html).
+* Simple and secure [auto-suggest text search](components/form-fields/text-search.html) widgets.
+* [Tables](components/tables.html) with built-in pagination and action buttons for viewing/editing/deleting records.
+* [Decorators](decorators.html) for overriding default display fields with simple _Rails_ view partials.
+* Automated [permissions](access-control/authorization/permissions.html) that can be applied to all application endpoints with minimal effort.
+* Sensible defaults to help you build your application quickly while also allowing you to customize when needed.
+* _ActiveElement_ attempts to provide a framework of familiar patterns that work with you instead of against you. It does not attempt to do everything for you and avoids behind-the-scenes magic where possible.
+* [Bootstrap](https://getbootstrap.com/) styling with [customizable themes](themes.html).
+
+See the [Setup Guide](setup.html) and browse the rest of the documentation for full usage examples.

data/rspec-documentation/pages/005-Setup.md

@@ -0,0 +1,75 @@
+# Setup
+
+To integrate _ActiveElement_ into your _Rails_ application, follow the steps below:
+
+## Installation
+
+Install the `active_element` gem by adding the following to your `Gemfile`:
+
+```ruby
+gem 'active_element'
+```
+
+Then rebuild your bundle:
+
+```console
+$ bundle install
+```
+
+## Application Controller
+
+Inherit from `ActiveElement::ApplicationController` in the controller you want to use with _ActiveElement_. In most cases this will either be your main `ApplicationController`, or a namespaced admin area controller, e.g. `Admin::ApplicationController`. This will apply the default _ActiveElement_ layout which includes a [Navbar](components/navbar.html), [Theme Switcher](components/theme-switcher.html), and all the required _CSS_ and _Javascript_.
+
+If you want to add custom content to the layout, see the [Hooks](hooks.html) documentation.
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActiveElement::ApplicationController
+  # ...
+end
+```
+
+## Create a View
+
+We'll use `UsersController` in this example, but you can replace this with whatever controller you want to use with _ActiveElement_.
+
+Assuming your controller is defined something like this:
+
+```ruby
+# app/controllers/users_controller.rb
+
+class UsersController < ApplicationController
+  def index
+    @users = User.all
+  end
+end
+```
+
+And your routes are defined something like this:
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+  resources :users
+end
+```
+
+Edit or create `app/views/users/index.html.erb`. Add a page title and a table component:
+
+```erb
+<%# app/views/users/index.html.erb %>
+
+<%= active_element.component.page_title 'Users' %>
+
+<%= active_element.component.table collection: @users, fields: [:id, :email, :name] %>
+```
+
+Adjust the `fields` to match whatever attributes you want to display for each `User` in your table.
+
+Start your _Rails_ application and browse to `/users` to see your new users index.
+
+## Next Steps
+
+Now that you know how to render components, take a look at the [Components](components.html) section of this documentation to see what components are available and how to use them.

data/rspec-documentation/pages/010-Components/Form Fields/Check Boxes.md

@@ -0,0 +1 @@
+# Check Boxes

data/rspec-documentation/pages/010-Components/Form Fields/JSON/Controller Params.md

@@ -0,0 +1,97 @@
+# Controller Params
+
+_JSON_ fields are pre-processed by _ActiveElement_ before they arrive as controller `params`. Read the [Behind the Scenes](#behind-the-scenes) section if you want to know exactly what happens during this pre-processing.
+
+Pre-processing _JSON_ parameters means that you get a regular _Rails_ controller `params` object (i.e. an instance of `ActionController::Parameters`) with all of the _JSON_ parameters available as though they were normal form parameters, so you can use them with `params.require(...).permit(...)`, pass them to `create` or `update` and let _ActiveRecord_ translate them back to _JSON_.
+
+_ActiveElement_ does not automatically `permit` parameters but it does map types for you based on the defined [schema](schema.html). This means you don't have to manually parse dates, decimals, etc. if you need to work with them in your controller.
+
+Each mapped type is specifically chosen to be safe to serialize back into _JSON_. This _JSON_ data can then be edited by _ActiveElement's_ `json_field` in your forms, allowing you to build complex forms with minimal effort and without having to work directly with the underlying _JSON_.
+
+## Example Schema and Controller
+
+### Schema
+
+```yaml
+# config/forms/user/pets.yml
+---
+type: array
+shape:
+  type: object
+  shape:
+    fields:
+    - name: name
+      type: string
+    - name: age
+      type: integer
+    - name: animal
+      type: string
+      options:
+      - Cat
+      - Dog
+      - Polar Bear
+    - name: favorite_foods
+      type: array
+      shape:
+        type: string
+        options:
+        - Biscuits
+        - Plants
+        - Carpet
+```
+
+### Controller
+
+Below you can see that the `email` param (a regular _Rails_ `email_field` or `text_field`) is used in conjunction with the `pets` param (an _ActiveElemen_ `json_field`).
+
+See the official _Rails_ [ActionController::Parameters documentation](https://api.rubyonrails.org/classes/ActionController/Parameters.html) for more details.
+
+```ruby
+class UsersController < ActiveElement::ApplicationController
+  def update
+    @user = User.find(params[:id])
+    if user.update(user_params)
+      flash.notice = 'User updated'
+      redirect_to user_path(@user)
+    else
+      flash.alert = 'User update failed'
+      render :edit
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:email, pets: [:name, :age, :animal, favorite_foods: []])
+  end
+end
+```
+
+## Behind the Scenes
+
+_ActiveElement_ tries to avoid behind-the-scenes magic where possible but, in this case, allowing fully transparent bi-directional _JSON_ parsing and type coercion is so convenient that we make an exception. Here's what happens when you generate a form with a _JSON_ field and then submit the form back to your _Rails_ application:
+
+1. A `hidden` field `__json_fields[]` is created with its `value` set to the name of the field in dot notation, e.g. `user.pets`.
+1. Another `hidden` field `__json_field_schemas[users][pets]` is created with its `value` set to an empty string. The front end _Javascript_ updates this when the form loads with the full schema. This ensures the data and schema are always consistent, even if the schema file changes between loading the form and submitting it.
+1. Whenever the _JSON_ field is updated, the `value` for the main `input` field is set to the full state of the field's data structure, as a _JSON_ string.
+1. When the form is submitted, a `before_action` in `ActiveElement::ApplicationController` intercepts the request and parses the _JSON_ data structure for any fields listed in the `__json_fields` array.
+1. The resulting data structure (a _Ruby_ `Array` or `Hash`) is then traversed recursively, applying type coercion to any fields specified in the schema that require it, e.g. a `decimal` schema definition produces a `BigDecimal` for all applicable values in the data structure.
+1. A new `ActionController::Parameters` object is created with all the regular fields (`text_field`, etc.) included, plus the transformed data structures for the _JSON_ fields.
+1. The meta parameters `__json_fields` and `__json_field_schemas` are removed from the result. You'll see them in the logs but they won't get in the way in your controller.
+1. The `request.params` object is re-assigned to the newly-constructed `ActionController::Parameters` object and the request continues as normal.
+
+If you have worked with submitting _JSON_ to _Rails_ controllers before then you likely will have come across numerous edge cases and difficulties with handling different parameter types, deeply nested values, parser errors, etc. that required custom code to handle.
+
+_ActiveElement_ aims to remove that effort completely and provide a `params` object that is familiar and consistent with _Rails_ conventions, so all you need to do is pass the params to your _ActiveRecord_ `create`/`update` methods and everything should work seamlessly (submit a [bug report](https://github.com/bobf/active_element/issues) if it doesn't!), while also giving you the benefit of being able to work with _Ruby_ objects.
+
+For example, if you need to sort an array of objects by date before saving back to the database then it's as simple as:
+
+```ruby
+def sort_family_by_date_of_birth
+  user_params[:family].sort_by! { |family_member| family_member[:date_of_birth] }
+end
+
+def user_params
+  params.require(:user).permit(family: [:date_of_birth, :name, :relation])
+end
+```

data/rspec-documentation/pages/010-Components/Form Fields/JSON/Schema.md

@@ -0,0 +1,283 @@
+# Schema
+
+The `json_field` schema defines the shape of each _JSON_ object contained in your database.
+
+Each model attribute has its own schema definition, each stored in a separate file for easy maintenance.
+
+See the [Types](types.html) documentation for a list of all available types.
+
+The schema definition requires two parameters to be present at the top level:
+
+* `type`
+* `shape`
+
+The `type` at the top level should always be `array` or `object`.
+
+The `shape` parameter defines the structure of your _JSON_, either each element within your _JSON_ `array` or the keys within your _JSON_ `object`.
+
+`type` is required for all fields, and `shape` is required for all `array` and `object` fields, either at the top level or recursively at any point in your definition.
+
+## Array of strings
+
+An `array` of `string` objects can be defined with the following schema:
+
+```yaml
+# config/forms/user/nicknames.yml
+
+---
+type: array
+shape:
+  type: string
+```
+
+You can see this schema in action in the below example:
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new(email: 'user@example.com'),
+                                fields: [:email, :nicknames]
+end
+
+it { is_expected.to include 'user[nicknames]' }
+```
+
+If you watch the _Javascript_ console in your browser, you can see the internal state updating as you edit the content (this only occurs when `ActiveElement.debug` is set to `true` in _Javascript_).
+
+## Pre-defined options
+
+The `string` type accepts a parameter `options` which is a list of pre-defined options that will be used to render a `select` element populated with the defined options:
+
+```yaml
+# config/forms/user/permissions.yml
+---
+type: array
+shape:
+  type: string
+  options:
+  - can_make_coffee
+  - can_drink_coffee
+  - can_discuss_coffee
+```
+
+We'll use the schema from the previous example as well and create two separate `json_field` elements, and this time we'll pre-populate the `nicknames` field with some values:
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new(nicknames: ['Buster', 'Coffee Guy']),
+                                fields: [:email, :permissions, :nicknames]
+end
+
+it { is_expected.to include 'Coffee Guy' }
+```
+
+## Array of Objects
+
+To define an array of objects, set the `type` parameter of the `array`'s `shape` to `object` and specify another `shape` with a list of `fields`, each with an associated `name` and `type`.
+
+The `name` is used as the `object`'s key when the input is converted to _JSON_:
+
+```yaml
+# config/forms/user/family.yml
+---
+type: array
+shape:
+  type: object
+  shape:
+    fields:
+    - name: relation
+      type: string
+      options:
+      - Parent
+      - Sibling
+      - Spouse
+    - name: name
+      type: string
+    - name: date_of_birth
+      type: date
+```
+
+Like the previous example, we'll keep the existing fields we've defined to generate a more complex form.
+
+We've also introduced a `date` field here, which generates an _HTML5_ `date` input field (see the [Types](types.html) section for more information on each of the available types).
+
+```rspec:html
+let(:user) do
+  User.new(email: 'user@example.com',
+           nicknames: ['Buster', 'Coffee Guy'],
+           permissions: ['can_drink_coffee'])
+end
+
+subject do
+  active_element.component.form model: user,
+                                fields: [:email, :nicknames, :permissions, :family]
+end
+
+it { is_expected.to include 'Spouse' }
+```
+
+## Focus
+
+So far things are pretty easy to manage, but if we have a user with a large family then the view will quickly become very cluttered and it will be difficult for users to navigate the form.
+
+To keep things manageable, the `array` type has an extra parameter `focus`. Use this parameter to specify a list of fields from each `object` found in the `array`. The first _truthy_ value (e.g. a non-empty string) found on each field is displayed as a placeholder. You can specify as many fields as you like.
+
+This time we'll use another _JSON_ column on our `User` model: `extended_family`. We'll populate it with a few more family members and we'll specify `focus` on `name` and `estranged`. The new field `estranged` is a `boolean`, which we'll use for family members whose name we've forgotten.
+
+We'll use `Faker` to generate some random data:
+
+```yaml
+# config/forms/user/extended_family.yml
+---
+type: array
+focus:
+- name
+- estranged
+shape:
+  type: object
+  shape:
+    fields:
+    - name: relation
+      type: string
+      options:
+      - Cousin
+      - Aunt
+      - Uncle
+    - name: name
+      type: string
+    - name: date_of_birth
+      type: date
+    - name: estranged
+      type: boolean
+```
+
+```rspec:html
+let(:user) do
+  User.new(
+    email: 'user@example.com',
+    nicknames: ['Buster', 'Coffee Guy'],
+    permissions: ['can_make_coffee', 'can_drink_coffee', 'can_discuss_coffee'],
+    extended_family: extended_family
+  )
+end
+
+let(:extended_family) do
+  20.times.map do
+    estranged = (rand(3) % 3).zero?
+    { name: estranged ? nil : Faker::Name.unique.name,
+      relation: ['Cousin', 'Aunt', 'Uncle'].sample,
+      date_of_birth: Faker::Date.birthday,
+      estranged: estranged }
+  end
+end
+
+subject do
+  active_element.component.form model: user,
+                                fields: [:email, :nicknames, :permissions, :extended_family]
+end
+
+it { is_expected.to include 'Coffee Guy' }
+```
+
+## Wrapping Up
+
+Aside from the handful of special parameters for certain [Types](types.html) we've covered everything you need to know about defining a _JSON_ object schema.
+
+To wrap things up, we'll combine all of our schemas into one single `object` schema and render a form. We'll call our field `user_data` and merge all the schemas into a single file. The only thing different about this schema compared to the others is that the top-level `type` is `object` instead of `array`. Otherwise, we're re-using all of the same mechanisms described above. Each schema was copy & pasted into the new schema under the `fields` array of the top object and a `name` was assigned to each one, otherwise they're completely unchanged.
+
+Since we're in debug mode for this documentation, the state is logged to the _Javascript_ console each time you modify a form value, so you can see what would be submitted if this form were connected to a real application.
+
+Make sure you read the [Controller Parameters](controller-parameters.html) section to see how to use [Rails StrongParameters](https://api.rubyonrails.org/classes/ActionController/StrongParameters.html) in conjunction with _ActiveElement_ _JSON_ fields.
+
+### Form
+
+```rspec:html
+let(:user) do
+  User.new(
+    email: 'user@example.com',
+    user_data: {
+      nicknames: ['Buster', 'Coffee Guy'],
+      permissions: ['can_make_coffee', 'can_drink_coffee', 'can_discuss_coffee'],
+      extended_family: extended_family
+    }
+  )
+end
+
+let(:extended_family) do
+  20.times.map do
+    estranged = (rand(3) % 3).zero?
+    { name: estranged ? nil : Faker::Name.unique.name,
+      relation: ['Cousin', 'Aunt', 'Uncle'].sample,
+      date_of_birth: Faker::Date.birthday,
+      estranged: estranged }
+  end
+end
+
+subject do
+  active_element.component.form model: user, fields: [:email, :user_data]
+end
+
+it { is_expected.to include 'Coffee Guy' }
+```
+
+### Schema
+
+```yaml
+# config/forms/user/user_data.yml
+---
+type: object
+shape:
+  fields:
+  - name: nicknames
+    type: array
+    shape:
+      type: string
+
+  - name: permissions
+    type: array
+    shape:
+      type: string
+      options:
+      - can_make_coffee
+      - can_drink_coffee
+      - can_discuss_coffee
+
+  - name: family
+    type: array
+    shape:
+      type: object
+      shape:
+        fields:
+        - name: relation
+          type: string
+          options:
+          - Parent
+          - Sibling
+          - Spouse
+        - name: name
+          type: string
+        - name: date_of_birth
+          type: date
+
+  - name: extended_family
+    type: array
+    focus:
+    - name
+    - estranged
+    shape:
+      type: object
+      shape:
+        fields:
+        - name: relation
+          type: string
+          options:
+          - Cousin
+          - Aunt
+          - Uncle
+        - name: name
+          type: string
+        - name: date_of_birth
+          type: date
+        - name: estranged
+          type: boolean
+```
+

data/rspec-documentation/pages/010-Components/Form Fields/JSON/Types.md

@@ -0,0 +1,36 @@
+# Types
+
+The following _JSON_ primitives are supported in schema definitions. Note that `null` cannot be specified as a field type, but it is the default value for most types.
+
+|Type|Description|Ruby Mapping
+|-|-|
+| `object` | A key-value data construct. | `Hash` (`{}`)
+| `array` | An ordered sequence of objects of any type | `Array` (`[]`)
+| `string` | A sequence of _Unicode_ characters | `String` (`""`)
+| `boolean` | A `true` or `false` value | `TrueClass` or `FalseClass` (`true`, `false`)
+| `float` | A floating-point number | `Float` (`0.1`)
+| `null` | An empty value | `NilClass` (`nil`)
+
+And the following extensions are provided:
+
+|Type|Description|Ruby Mapping
+|-|-|
+| `date` | An [iso8601 date](https://en.wikipedia.org/wiki/ISO_8601#Dates) stored as `YYYY-MM-DD`. | `Date`
+| `datetime` | An [iso8601-1:2019 combined date and time](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) stored as `YYYY-MM-DDThh:mm:ss` | `DateTime`
+| `time` | An [iso8601-1:2019 time](https://en.wikipedia.org/wiki/ISO_8601#Times) stored as `hh:mm` | `String` ([*](#time-of-day))
+| `decimal` | An infinite-precision decimal object stored as a string, e.g. `"3.141592653589793"` | `BigDecimal`
+| `integer` | A whole number, stored as a _JSON_ `float`. | `Integer`
+
+Defining types in your schema allows you to work directly with _Ruby_ objects when the form is submitted to a controller. The `params` arrive pre-parsed in formats that match the automatic serialization that _ActiveRecord_ performs. e.g. converting a `DateTime` object to _JSON_ in _Rails_ outputs the following:
+
+```irb
+irb(main):001:0> puts({ time: Time.now.utc }.to_json)
+
+{"time":"2023-06-12T20:13:11.308Z"}
+```
+
+## Time of Day
+
+Note that _Ruby_ has no native way to store a time of day without a date, so `time` fields are coerced to `String` (`hh:mm`) when processed into controller params.
+
+You may find the [Tod](https://github.com/JackC/tod) gem useful when working with these values.

data/rspec-documentation/pages/010-Components/Form Fields/JSON.md

@@ -0,0 +1,70 @@
+# JSON
+
+A custom form field `json_field` is provided for editing _JSON_ data.
+
+The field is schema-based and expects to find a schema definition in `config/forms/<model>/<attribute>.yml`.
+
+For example, to edit a _JSON_ attribute named `permissions` on a `User` model, _ActiveElement_ requires a file named `config/forms/user/permissions.yml`.
+
+See the [Schema](json/schema.html) documentation for a detailed description of how this file should be generated.
+
+The `json_field` type will be automatically selected for _ActiveRecord_ `json` and `jsonb` columns included in the `fields` array when used in conjunction with an _ActiveRecord_ model.
+
+
+## Example Form
+
+This example is powered by the [example schema](#example-schema) below.
+
+The `pets` column on the `users` table is a `json` column so _ActiveElement_ loads the schema and generates a dynamic, interactive form component allowing users to edit the data structure without having to manually edit _JSON_.
+
+Click the **Rendered Output** tab to see it in action:
+
+```rspec:html
+let(:user) do
+  User.new(
+    email: 'user@example.com',
+    pets: [
+      { animal: 'Cat', name: 'Hercules', favorite_foods: ['Plants', 'Biscuits'] },
+      { animal: 'Dog', name: 'Samson' }
+    ]
+  )
+end
+
+subject do
+  active_element.component.form model: user, title: 'New User', fields: [:email, :pets]
+end
+
+it { is_expected.to include 'Hercules' }
+```
+
+## Example Schema
+
+The example above is powered by this schema definition:
+
+```yaml
+# config/forms/user/pets.yml
+---
+type: array
+shape:
+  type: object
+  shape:
+    fields:
+    - name: name
+      type: string
+    - name: age
+      type: integer
+    - name: animal
+      type: string
+      options:
+      - Cat
+      - Dog
+      - Polar Bear
+    - name: favorite_foods
+      type: array
+      shape:
+        type: string
+        options:
+        - Biscuits
+        - Plants
+        - Carpet
+```