Update dummy app documentation and write 3.x to 4.x migration guide

README.md

@@ -155,7 +155,7 @@ and if it is disabled (boolean).
 `<XSelect>` 4.0 ships with an entirely new test helper that goes
 beyond just allowing you to select an option. It allows you to
 interact with your `<select>` element in all different ways. For
-example in tests if you need to assert your first options `disabled`
+example, if you need to assert your first option is `disabled`
 or not:
 
 ```javascript
@@ -174,7 +174,7 @@ Import the select interactor:
 
 ``` javascript
 // you can name the import whatever you want
-import XSelect from "yourappname/tests/helpers/x-select";
+import XSelectInteractor from "yourappname/tests/helpers/x-select";
 ```
 
 At the top of your test file you need to initialize the
@@ -184,7 +184,7 @@ available to all tests in the file. Here's an example in Qunit:
 
 ``` javascript
 module("Acceptance | Your Test", function(hooks) {
-  let xselect = new XSelect('.selector-for-select');
+  let xselect = new XSelectInteractor('.selector-for-select');
   setupApplicationTest(hooks);
   // ...
 });
@@ -195,7 +195,7 @@ selecting!
 
 ``` javascript
 module("Acceptance | Your Test", function(hooks) {
-  let xselect = new XSelect('.selector-for-select');
+  let xselect = new XSelectInteractor('.selector-for-select');
   // ...
 
   test('Selecting an option', async (assert) => {
@@ -212,7 +212,7 @@ You can do more than just select options with this helper.
 
 ``` javascript
 module('Acceptance | Your Test', function(hooks) {
-  let xselect = new XSelect('.selector-for-select');
+  let xselect = new XSelectInteractor('.selector-for-select');
   // ...
 
   test('Selecting an option', async (assert) => {
@@ -265,7 +265,7 @@ Example usage might be:
 ```
 
 ``` javascript
-let xselect = new XSelect('.x-select');
+let xselect = new XSelectInteractor('.x-select');
 
 xselect.options(0).value; //=> "hello world"
 xselect.options(0).text; //=> "Hello World!"

tests/dummy/app/router.js

@@ -11,7 +11,10 @@ Router.map(function() {
   this.route('actions');
   this.route('testing');
   this.route('examples');
-  this.route('migration-guide');
+  this.route('migration-guide', function() {
+    this.route('2-to-3');
+    this.route('3-to-4');
+  });
 
   this.route('test-bed', function() {
     this.route('single');

tests/dummy/app/styles/_variables.scss

@@ -7,6 +7,7 @@ $french-rose: #F74D7B;
 $picton-blue: #26ABE8;
 $regent-gray: #7E8BA0;
 $shuttle-gray: #555D6B;
+$gallery: #EBEBEB;
 $trout: #4B5360;
 $white: #FFFFFF;
 

tests/dummy/app/styles/app.scss

@@ -65,5 +65,11 @@ pre {
   margin-top: 1em;
   padding: 10px 0;
   border-radius: 4px;
-  background-color: #ebebeb;
+  background-color: $gallery;
+}
+
+code {
+  padding: 3px 0;
+  border-radius: 4px;
+  background-color: $gallery;
 }

tests/dummy/app/templates/actions.hbs

@@ -2,7 +2,7 @@
 
 {{format-markdown
   "
-  `x-select` provides actions that fire on different event types. These actions
+  `<XSelect>` provides actions that fire on different event types. These actions
   will be kebob-cased event names:
   - `on-change`
   - `on-blur`
@@ -12,7 +12,7 @@
 
   #### on-blur
 
-  `on-blur` fires anytime the `blur` event is triggered on the x-select
+  `on-blur` fires anytime the `blur` event is triggered on the `<XSelect>`
   component. When the action fires it sends two arguments: the value and the
   DOM event.
 
@@ -24,7 +24,7 @@
 
   #### on-focus-out
 
-  `on-focus-out` fires anytime the `focusOut` event is triggered on the x-select
+  `on-focus-out` fires anytime the `focusOut` event is triggered on the `<XSelect>`
   component. When the action fires it sends two arguments: the value and the
   DOM event.
 
@@ -36,7 +36,7 @@
 
   #### on-click
 
-  `on-click` fires when x-select is clicked. When the action fires it sends two
+  `on-click` fires when `<XSelect>` is clicked. When the action fires it sends two
   arguments: the value and the DOM event.
 
   ```js
@@ -59,25 +59,28 @@
 
   Most of the time all you need is the value that has been selected, but
   sometimes your action requires more context than just that. In those
-  cases, you can associate arbitrary attributes with the component
-  itself and use them later inside your action handler. For example:
+  cases, you can pass any arguments you need from the template. For
+  example:
 
   ```handlebars
-  {{#x-select on-change=(action 'didMakeSelection') default='something' as |xs|}}
+  <XSelect @on-click={{action 'didMakeSelection' isXSelectRequired}} @required={{isXSelectRequired}} as |xs|>
     <option>Nothing</option>
-    {{#xs.option value=something}}Something{{/xs.option}}
-  {{/x-select}}
+    <xs.option value={{something}}>Something</xs.option>
+  </XSelect>
   ```
+
   then, inside your action handler:
 
   ```js
-  export default Ember.Route.extend({
+  import Controller from '@ember/controller';
+
+  export default Controller.extend({
     actions: {
-      didMakeSelection: function(selection, component) {
-        if (selection) {
-          this.set('selection', selection)
+      didMakeSelection(value, event, isXSelectRequired) {
+        if (!value & isXSelectRequired) {
+          this.set('error', 'You must fill out this field');
         } else {
-          this.set('selection', component.get('default'))
+          this.set('selection', value);
         }
       }
     }

tests/dummy/app/templates/application.hbs

@@ -21,7 +21,7 @@
             </li>
             <li class="nav-item">
               {{#link-to "migration-guide" class="nav-link"}}
-                Migration Guide
+                Migration Guides
               {{/link-to}}
             </li>
           </ul>

tests/dummy/app/templates/introduction.hbs

@@ -1,40 +1,39 @@
 <h1>Emberx-select</h1>
 {{format-markdown
   "
-  ### Installation
-  ```bash
-  ember install emberx-select
-  ```
-
-  ## Introduction
-
-  x-select is a component based on the native html select.
+  A select component based on the native html select.
 
   We've tried other select components, and were missing the reliability,
   maintainability, and accessbility of the native html `<select>`.
-
-  `x-select` is a drop-in component to let you use any
+  `<XSelect>` is a drop-in component to let you use any
   object for your selectable options. You can use it out of the box, or
   as a building block of something more ambitious.
 
-  The goal of `x-select` is to let you see how it works and style it
+  The goal of `<XSelect>` is to let you see how it works and style it
   right in your template, rather than passing in a ball of configuration
   or wrapping a hard-coded, inaccessible jQuery plugin.
 
+
+  ## Installation
+
+  ```
+  ember install emberx-select
+  ```
+
   By allowing arbitrary html to appear in the template of the select
   element, you can use it just like you would normally. This means
   things like having `<optgroup>` tags inside your select, or even plain
   old `<option>` elements to represent things like empty values.
 
-  `x-select` thinly wraps a native `<select>` element so that it can be object
+  `<XSelect>` thinly wraps a native `<select>` element so that it can be object
   and binding aware. It is used in conjuction with the `x-option`
   component to construct select boxes. E.g.
 
   ```handlebars
-  {{#x-select value=currentValue on-change=(action 'selectPerson') as |xs|}}
-    {{#xs.option value=fred}}Fred Flintstone{{/xs.option}}
-    {{#xs.option value=bob}}Bob Newhart{{/xs.option}} {{! currentValue = bob }}
-  {{/x-select}}
+  <XSelect @value={{bob}} @on-change={{action 'selectPerson'}} as |xs|>
+    <xs.option @value={{fred}}>Fred Flintstone</xs.option>
+    <xs.option @value={{bob}}>Bob Newhart</xs.option>
+  </XSelect>
   ```
 
   Whenever the select tag receives a change event, it will fire the

tests/dummy/app/templates/migration-guide/3-to-4.hbs

@@ -0,0 +1,90 @@
+<h1>Migrating from 3.x to 4.x</h1>
+
+<p>
+  emberx-select 4.x doesn't introduce too many breaking changes. This major version is mostly to align x-select with ember best practices (like removing jQuery).
+</p>
+
+<p>
+  There are a few breaking changes in this release:
+</p>
+
+{{format-markdown
+  "
+  - Removed jQuery from component usage
+  - Action handers no longer pass a jQuery event. They now pass a native DOM event.
+  - `sendAction` has been removed. That means `{{#x-select action='myAction'}}` will no longer work
+  - Completely revamped the test helper
+"
+}}
+
+<h2>Removing sendAction</h2>
+
+{{format-markdown
+  "
+  [Ember deprecated `sendAction`](https://emberjs.com/blog/2018/10/07/ember-3-4-released.html#toc_deprecations-2) in v3.4. `<XSelect>` had two places where `sendAction` was used. One internally and one through the default `action` property:
+
+  ```handlebars
+  {{#x-select action=\"myAction\"}} ... {{/x-select}}
+  ```
+
+  In `<XSelect>` v4.x we removed the default `action` property. You should now implement `on-change` instead. In fact, `action` was called from `on-change` for all of `<XSelect>`s life. So the above example becomes:
+
+  ```handlebars
+  {{#x-select on-change=(action \"myAction\")}} ... {{/x-select}}
+  ```
+
+  or in Ember v3.4:
+
+  ```html
+  <XSelect @on-change={{action \"myAction\"}}> ... </XSelect>
+  ```
+  "
+}}
+
+<h2>New test helper</h2>
+
+<p>
+  Migrating from the 3.x to 4.x x-select test helper is fairly simple, but still breaking change. There are a couple differences. There's no longer a named import, you have to initialize the helper, and it does way more than selecting options now.
+</p>
+
+{{format-markdown
+  "
+  The old test helper import looked like this:
+
+  ```javascript
+  import { select } from 'yourappname/tests/helpers/x-select';
+  ```
+
+  The test helper import in 4.x is now:
+
+  ```javascript
+  import XSelectInteractor from 'yourappname/tests/helpers/x-select';
+  ```
+
+  To use the new test helper you have to initialize it at the top of your test file:
+
+  ``` javascript
+  module(\"Acceptance | Your Test\", function(hooks) {
+    let xselect = new XSelectInteractor('.selector-for-select');
+    setupApplicationTest(hooks);
+    // ...
+  });
+  ```
+
+  Once it's initialized you can select an option:
+
+  ``` javascript
+  test(\"Selecting an option\", async function(assert) {
+    await xselect.select('My Option');
+    // for multiple selects pass an array
+    // await xselect.select(['My Option', 'Another Option']);
+
+    // ...
+  });
+  ```
+  "
+}}
+
+<p>
+  Checkout the {{#link-to 'testing'}}testing documentation{{/link-to}} for more information on the new test helper.
+</p>

tests/dummy/app/templates/migration-guide/index.hbs

@@ -0,0 +1,6 @@
+<h1>Migrating major releases</h1>
+
+<p>emberx-select has had a couple of major version releases. In order to help you migrate easily we have put together a couple of guides. Going from 2.x to 3.x has the most amount of changes. Going from 3.x to 4.x is farily simple.</p>
+
+<p>{{#link-to 'migration-guide.2-to-3'}}Migrating from 2.x to 3.x{{/link-to}}</p>
+<p>{{#link-to 'migration-guide.3-to-4'}}Migrating from 3.x to 4.x{{/link-to}}</p>