docs(all) added docs for helpers and added a few tests/assertions

packages/form-helpers/README.md

@@ -6,14 +6,113 @@ A collection of form control related utilities for working with forms.
 
 ```sh
 # npm
-npm install @open-wc/form-utils
+npm install @open-wc/form-helpers
 
 # yarn
-yarn add @open-wc/form-utils
+yarn add @open-wc/form-helpers
 ```
 
 ### Implicit form submit
+The `submit` helper is a useful helper for firing the forms `submit` event – as a preventable event – only when the form's validity reports back as truthy (meaning the form has all valid values in its inputs) and calling the provided form's `submit()` method if the submit event is not `defaultPrevented`.
+```html
+<form id="someForm" @submit="${submitHandler}">
+  <input required>
+</form>
+```
+```js
+import { submit } from '@open-wc/form-helpers';
+
+let submitted = false;
+const form = document.querySelector('#someForm');
+const input = document.querySelector('input');
+
+input.addEventListener( 'keypress', ($event) => {
+  if($event.keyCode === 13) { // Enter key
+    submit(form); // submit event is emitted, and form's submit() method is called if the `submit` event is not `defaultPrevented`
+    console.log(submitted) // submitted will be false if the input doesn't have a value AND is required
+  }
+});
+
+function submitHandler(event) {
+  // the event is not prevented, so the form will be submitted
+  submitted = true;
+};
+```
 
 ### Parse form values
+The `formValues` helper is a useful function for parsing out the values of a form's inputs in an object format.
+
+```js
+import { formValues } from '@open-wc/form-helpers';
+```
+
+Given a form like:
+```html
+<form>
+  <input name="foo" value="one">
+  <input name="bar" value="two">
+  <input name="baz" value="1">
+  <input name="baz" value="2">
+</form>
+```
+
+parsing the form's values can be performed as such:
+
+```js
+import { formValues } from '@open-wc/form-helpers';
+
+const form = document.querySelector('form');
+
+console.log(formValues(form))
+
+// Output: 
+// {
+//   foo: 'one', 
+//   bar: 'two',
+//   baz: ['1', '2']
+// }
+```
+
+### Parse form object
+The `parseFormObject` helper enables deeper nesting and organization of inputs in a form by inspecting the `name` attribute on each input element and analyzing according to dot notation.
+
+```js
+import { parseFormAsObject } from '@open-wc/form-helpers';
+```
+
+Given a form like
+```html
+<form>
+  <input name="one.a" value="a">
+  <input name="one.b" value="b">
+  <input name="two" value="2">
+  <input name="foo.bar.baz" value="baz">
+  <input name="foo.bar.qux" value="qux">
+  <input name="three" value="three">
+  <input name="three" value="tres">
+</form>
+```
+parsing the form values as a deeply nested object can be perfomed as such:
+```js
+import { parseFormAsObject } from '@open-wc/form-helpers';
+
+const form = document.querySelector('form');
+
+console.log(parseFormAsObject(form))
 
-### Parse form object
+// Output: 
+// {
+//   one: {
+//     a: 'a',
+//     b: 'b',
+//   },
+//   two: '2',
+//   foo: {
+//     bar: {
+//       baz: 'baz',
+//       qux: 'qux'
+//     }
+//   },
+//   three: ['three', 'tres']
+// }
+```

packages/form-helpers/tests/submit.test.ts

@@ -1,34 +1,67 @@
 import { aTimeout, expect, fixture, fixtureCleanup, html } from '@open-wc/testing';
+import * as sinon from 'sinon';
 import { submit } from '../src';
 
 let submitted = false;
-const submitCallback = (event: Event) => {
+const submitCallbackPrevented = (event: Event) => {
   event.preventDefault();
   submitted = true;
 };
+const submitCallback = (event: Event) => {
+  submitted = true;
+};
 
 describe('The submit form helper', () => {
   let form: HTMLFormElement;
+  let formSubmitStub: sinon.SinonSpy;
 
   beforeEach(async () => {
     form = await fixture<HTMLFormElement>(html`<form @submit="${submitCallback}">
       <input>
     </form>`);
+    formSubmitStub = sinon.stub(form, 'submit').callsFake(() => {});
     submitted = false;
   });
 
-  afterEach(fixtureCleanup);
+  afterEach(() => {
+    sinon.restore();
+    fixtureCleanup();
+  });
 
   it('will submit a form that is valid', async () => {
     submit(form);
     await aTimeout(0);
     expect(submitted).to.be.true;
+    // form.submit() is called
+    expect(formSubmitStub.callCount).to.equal(1);
   });
 
-  it('will not submit a form that is invalid', async () => {
+  it('will not fire the submit event for a form that is invalid', async () => {
     const input = form.querySelector<HTMLInputElement>('input')!;
     input.required = true;
     submit(form);
     expect(submitted).to.be.false;
   });
+
+  it('will not submit a form that is invalid', async () => {
+    const input = form.querySelector<HTMLInputElement>('input')!;
+    input.required = true;
+    submit(form);
+
+    expect(formSubmitStub.callCount).to.equal(0);
+  });
+
+  it('will not submit a form when the submit event is `defaultPrevented`', async () => {
+    form = await fixture<HTMLFormElement>(html`<form @submit="${submitCallbackPrevented}">
+      <input>
+    </form>`);
+
+    formSubmitStub = sinon.stub(form, 'submit').callsFake(() => {});
+
+    submit(form);
+
+    expect(formSubmitStub.callCount).to.equal(0);
+  });
+
+
 });

packages/form-helpers/tsconfig.json

@@ -1,7 +1,7 @@
 {
-    "extends": "../../tsconfig.json",
-    "compilerOptions": {
-        "rootDir": "src",
-        "outDir": "lib"
-    }
-}
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  }
+}