INT-268 Update documentation to include parent/child api

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ember-foxy-forms",
   "version": "2.46.2",
-  "description": "An addon for building forms that work with ember data",
+  "description": "An Ember form library that makes the everyday use cases trivial, while providing the flexibility to handle highly unique requirements",
   "keywords": [
     "ember-addon"
   ],

tests/dummy/app/controllers/docs/advanced.js

@@ -0,0 +1,26 @@
+import Controller from '@ember/controller';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+class User {
+  @tracked name = 'user-1234';
+}
+
+class Avatar {
+  @tracked name = 'default';
+}
+
+export default class AdvancedController extends Controller {
+  @tracked user = new User();
+  @tracked avatar = new Avatar();
+
+  @action
+  async handleSubmit() {
+    alert(`Creating new user with username ${this.user.name}... user created!`);
+  }
+
+  @action
+  async handleChildSubmit() {
+    alert(`Updating avatar description to ${this.user.name}-${this.avatar.name}-avatar.jpeg... avatar description updated!`);
+  }
+}

tests/dummy/app/router.js

@@ -13,6 +13,7 @@ Router.map(function () {
     this.route('forms');
     this.route('fields');
     this.route('controls');
+    this.route('advanced');
   });
 
   this.route('not-found', { path: '/*path' });

tests/dummy/app/templates/docs.hbs

@@ -5,6 +5,7 @@
     {{nav.item "Forms" "docs.forms"}}
     {{nav.item "Fields" "docs.fields"}}
     {{nav.item "Controls" "docs.controls"}}
+    {{nav.item "Advanced" "docs.advanced"}}
   </viewer.nav>
 
   <viewer.main>

tests/dummy/app/templates/docs/advanced.md

@@ -0,0 +1,46 @@
+# Advanced Use Cases 
+
+## Child Forms
+
+Foxy Forms supports parent/child relationships to better separate concerns for more verbose scenarios. Calling submit on the parent will submit itself, and then call submit any children, breadth-first, afterward. 
+
+**NOTE**: the parent form will only call submit on children with dirty fields.
+
+**Example: product onboarding**
+
+Let's say we want to collect a new user's information during an onboarding flow, and then optionally allow the 'default' part of the avatar name to be updated. We could have two forms: one responsible for collecting general account information, and another specific to handling avatar logic.
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="advanced-usage.hbs"}}
+    <Form 
+      @for={{this.user}} 
+      @onSubmit={{this.handleSubmit}} 
+      as |f|>
+        <f.field 
+          @for="name" 
+          @using="input" 
+          @label="Username" 
+        />
+        <div style="border: 1px solid gray; padding: 0.5rem; margin: 1rem">
+          <strong>Optional: change avatar description?</strong>
+          <Form 
+            @for={{this.avatar}} 
+            @parentForm={{f.self}} 
+            @onSubmit={{this.handleChildSubmit}} 
+            as |cf|> 
+            <div style="display: flex; align-items: center;">
+              {{this.user.name}}-
+              <cf.field 
+                @for="name" 
+                @using="input" 
+                required
+              />
+              -avatar.jpeg
+            </div>
+          </Form>
+        </div>
+      <f.submit @text="Submit form" />
+    </Form>
+  {{/demo.example}}
+  {{demo.snippet "advanced-usage.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/controls.md

@@ -1,7 +1,7 @@
 # Controls
 
-Ember foxy forms comes packed with support with the default set of html5 controls, as well as a few 'emberized' ones that
-make interacting with ember-data / ember-objects a little more straight forward. They can be selected using the 'using' 
+`ember-foxy-form` comes packed with support with the default set of html5 controls, as well as a few 'emberized' ones that
+make interacting with ember-data / Ember objects a little more straight forward. They can be selected using the '@using' 
 attribute. If you provide no ```@using``` or ```@control``` attribute the form will default to using the text type. 
 
 ## Text Input Variants 
@@ -85,10 +85,10 @@ A checkbox can take an optional label attribute.
 
 ## Select 
 
-FoxyForms comes with two select controls out of the box that work with both primitive arrays (numbers and strings) or 
-ember objects. When working with objects you can specify an identifier key `@idKey` and a label key `@labelKey`
-these will be used to identify your object and to label the drop down.
-Also you can disable an option by setting `disabled: true` in your value object in values array.
+`ember-foxy-form` comes with two select controls out of the box that work with both primitive arrays (numbers and strings) or 
+Ember objects. When working with objects you can specify an identifier key `@idKey` and a label key `@labelKey`
+these will be used to identify your object and to label the drop down. Also you can disable an option by setting `disabled: true` 
+in your value object in values array.
 
 {{#docs-demo as |demo|}}
   {{#demo.example name="select-control.hbs"}}
@@ -162,9 +162,8 @@ Also you can disable an option by setting `disabled: true` in your value object
 
 ## Custom Controls
 
-You can extend form for to provide custom controls, your component must simply conform to the control interface:
-
-A form control is any component which implements the following interface.
+You can extend your form to provide your own custom controls, your component must simply conform to the 
+control interface:
 
 {{#docs-snippet name="custom-controls.js"}}
   interface FormControl {
@@ -185,16 +184,16 @@ A form control is any component which implements the following interface.
   }
 {{/docs-snippet}}
 
-If you follow this convention values will be seamlessly managed by the field / form layers. Some examples of custom controls
-we have built are: 
+If you follow this convention, values will be seamlessly managed by the field / form layers. Some examples of 
+custom controls we have built are: 
 
-- Image Select Control
-- Map Editor Control
-- Price Range Select
-- Rich Text editor
+- Image select Control
+- Map editor Control
+- Price range Select
+- Rich text editor
 - JSON editor
 
-By default Foxy Forms looks for your custom controls in the component directory form-controls of your application, 
+By default, Foxy Forms looks for your custom controls in the `components/form-controls` directory of your application, 
 but you can also specify the full path to the control.
 
 {{#docs-demo as |demo|}}

tests/dummy/app/templates/docs/fields.md

@@ -1,6 +1,6 @@
 # Fields
 
-Fields are responsible for connecting form-controls to fields.
+Fields are responsible for connecting form controls to model/object values.
 
 ## Standard and Composite Values
 
@@ -22,7 +22,7 @@ controlling a date range. This can be done by simply passing an array of keys to
 ## Specifying the control
 
 FieldFor accepts a @using parameter, which instructs it to use a particular form control for the field. It uses the following
-rubric to lookup your component based on that name.FieldFor
+rubric to lookup your component based on that name:
 
 1. It looks for a custom control in your application with a path matching ```form-controls/<@using>```
 2. It looks for a custom control in your application with a path matching ```form-controls/<@using>-control``` this affordance is for legacy projects and will be removed in version 3.0.0
@@ -183,4 +183,4 @@ fully qualified path a component that respects the display value component inter
     </Form> 
   {{/demo.example}}
   {{demo.snippet "custom-display-component.hbs"}}
-{{/docs-demo}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/forms.md

@@ -1,12 +1,9 @@
 # Form Features in detail
 
-FoxyForms is a fully featured form framework, mostly designed for dealing with ember-data models. It comes with a number
-of features that make composing UIs very simple.
+## Error Mapping
 
-## Value & Error Mapping
-
-The primary role of FoxyForms is to map errors / values from a model to various form controls. The assume structure of
-the model looks something like this:
+`ember-foxy-forms` will automatically map error (messages) from a model to form controls. It assumes the structure of
+the model is the following:
 
 {{#docs-snippet name="model.js"}}
   {
@@ -20,11 +17,11 @@ the model looks something like this:
   }
 {{/docs-snippet}}
 
-
 This schema is consistent with ember-data, JSON:API spec, and ember-model-validator.
 
-When an error is present ember foxy-forms will add error classes to the forms / fields.
+### scrollToFirstVisibleError
 
+You can configure a form to scroll its first field with an error into view on failed submission. Using the scrollToFirstVisibleError options.
 ## Automatic Submission Mode
 
 When in automatic submission mode, the form will automatically trigger the submission action when a change is committed
@@ -85,7 +82,7 @@ the confirm button. If you click the reject button the changes will be rolled ba
   {{demo.snippet "inline.hbs"}}
 {{/docs-demo}}
 
-## Notification
+## Notifications
 
 Forms can be configured to notify the user when a form either succeeds or fails. This behaviour is configurable as follows:
 
@@ -127,14 +124,6 @@ Forms can be configured to notify the user when a form either succeeds or fails.
 
 The form-for service can be extended to provide custom popups, or messages by injecting it into your application.
 
-## Errors
-
-By default ember-foxy-forms wires errors from ember-data models. 
-
-
-### scrollToFirstVisibleError
-
-You can configure a form to scroll its first field with an error into view on failed submission. Using the scrollToFirstVisibleError options.
 
 ## Navigation Guards
 
@@ -273,7 +262,7 @@ buttons: ```form-for-model-name__button-type-button```
   </Form>
 {{/docs-snippet}}
 
-Form for will automatically generate [grid-areas](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area) defined 
+Form will automatically generate [grid-areas](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area) defined 
 as inline styles on its elements. This feature can be turned on either by setting `useGridTemplate` to `true` in the 
 config or passing it as an arg. This allows you to define your form layout using the [grid-template](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template)
 syntax. 

tests/dummy/app/templates/docs/index.md

@@ -1,8 +1,27 @@
 # Introduction
 
-Hey, welcome to the docs for ember-foxy-forms, this addon was built to do away with a lot of the needless plumbing when
-building forms over data in ember. Common use cases like displaying validation errors, notifying the user on successful
-submission, can all be very tedious in a typical ember application, with ember foxy forms this is trivial!
+Forms can get *tedious*. Common use cases like displaying validation errors, or notifying the user on a successful submission
+start to not not only feel repetitive, but also error prone. 
+
+At [Food.ee](https://food.ee), we decided to get sly about this problem with `ember-foxy-forms`, an Ember form library that makes the 
+everyday use cases trivial, while providing the flexibility to handle highly unique user requirements.
+
+*💡 `ember-foxy-forms` was built with `ember-data` and `ember-model-validator` in mind, but it is not intrinsically tied to either of 
+these libraries. You can use `ember-foxy-forms` with any data store that conforms to the JSON:API spec, or without any data store at all.*
+
+
+## Overview
+
+Generally speaking, using `ember-foxy-forms` is a quick, three-step process:
+
+Supply an model or object to the form.
+
+Then, specify to the fields which values they represent.
+
+Finally, choose which form control to use for each field.
+
+
+## Basic Example
 
 ```js
 class MyRoute extends Route {
@@ -14,19 +33,24 @@ class MyRoute extends Route {
 
 ```hbs
 <Form
-  @for={{this.model}}
+  @for={{this.model}} 
   @successfulSubmitMessage="We did it!"
   @successfulDestroyMessage="Oh noes!"
   as |f|>
   <f.field @for="attribute" @using="input"/>
 </Form>
 ```
 
-## Custom Configurations
 
-## Site-wide `environment.js` overrides
+## Getting Started
+
+```bash
+yarn add -D ember-foxy-forms
+```
+
+## Global Settings
 
-You can customize the way foxy forms handles various options by adding your override to your environment file.
+You can customize the way `ember-foxy-forms` handles various options by adding your override to your environment file.
 
 ```javascript
 //environment.js

tests/dummy/app/templates/docs/usage.md

@@ -1,9 +1,7 @@
 # Usage 
 
-Below is a configurable example of the basic usage of ember-foxy-forms, it showcases all of the html5 input controls
-that can be mounted to your data model.
-
-The various features can be toggled on / off below.
+Below is an interactive demo of `ember-foxy-forms`, it showcases the kitchen sink of form controls
+that we provide for you out of the box.
 
 {{#docs-demo as |demo|}}
   {{#demo.example name="basic-usage.hbs"}}

tests/integration/components/form-for-test.js

@@ -774,12 +774,8 @@ module('Integration | Component | form for', function (hooks) {
       </Form>
     `);
 
-    assert
-      .dom('[data-test-field-for="object_foo"]')
-      .hasStyle({ gridArea: 'foo' });
-    assert
-      .dom('[data-test-form-button="submit"')
-      .hasStyle({ gridArea: 'submit' });
+    assert.dom('[data-test-field-for="object_foo"]').hasStyle({ gridArea: 'foo' });
+    assert.dom('[data-test-form-button="submit"').hasStyle({ gridArea: 'submit' });
   });
 
   test('it should append the gridTemplatePrefix to the grid areas for form fields and buttons', async function (assert) {
@@ -801,11 +797,7 @@ module('Integration | Component | form for', function (hooks) {
       </Form>
     `);
 
-    assert
-      .dom('[data-test-field-for="object_foo"]')
-      .hasStyle({ gridArea: 'ff-foo' });
-    assert
-      .dom('[data-test-form-button="submit"')
-      .hasStyle({ gridArea: 'ff-submit' });
+    assert.dom('[data-test-field-for="object_foo"]').hasStyle({ gridArea: 'ff-foo' });
+    assert.dom('[data-test-form-button="submit"').hasStyle({ gridArea: 'ff-submit' });
   });
 });