ember-sortable 2.4.0 → 4.0.0

package/MIGRATION_GUIDE_MODIFIERS.md

@@ -5,16 +5,20 @@
 To use modifiers, you must use angle-bracket syntax
 
 ### New Root component
-1. Instead of using `sortable-group` as a component, use `sortable-group` as a modifier 
-any element. You no longer need to tell `sortable-group` about the models, so the `each`
-uses the models directly.
+
+1. Instead of using `sortable-group` as a component, use `sortable-group` as a modifier
+   any element. You no longer need to tell `sortable-group` about the models, so the `each`
+   uses the models directly.
 
 **Old Component**
+
 ```hbs
 {{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
   {{#each group.model as |item|}}
 ```
+
 **New Component**
+
 ```hbs
 <ol {{sortable-group onChange=(action "reorderItems")}}>
   {{#each model.items as |item|}}
@@ -23,19 +27,21 @@ uses the models directly.
 2. Each `item` can be represented by any dom element or component using angle-bracket syntax
 
 **Old Component**
+
 ```hbs
-{{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
+{{#sortable-group model=model.items onChange=(action 'reorderItems') as |group|}}
   {{#each group.model as |item|}}
     {{#group.item model=item}}
-       {{tem.name}}
+      {{tem.name}}
     {{/group.item}}
   {{/each}}
 {{/sortable-group}}
 ```
 
 **New Component with modifier**
+
 ```hbs
-<ol {{sortable-group onChange=(action "reorderItems")}}>
+<ol {{sortable-group onChange=(action 'reorderItems')}}>
   {{#each model.items as |item|}}
     <li {{sortable-item model=item}}>
       {{tem.name}}
@@ -47,6 +53,7 @@ uses the models directly.
 3. The Handle is also any element with a `sortable-handle` applied to it.
 
 **Old Component**
+
 ```hbs
 {{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
   {{#each group.model as |modelItem|}}
@@ -61,28 +68,28 @@ uses the models directly.
 ```
 
 **New Component with modifier**
+
 ```hbs
-<ol {{sortable-group onChange=(action "reorderItems")}}>
+<ol {{sortable-group onChange=(action 'reorderItems')}}>
   {{#each model.items as |item|}}
     <li {{sortable-item model=item}}>
       {{tem.name}}
-      <span class="handle" {{sortable-handle}}>&varr;</span>
+      <span class='handle' {{sortable-handle}}>&varr;</span>
     </li>
   {{/each}}
 </ol>
 ```
 
-4. The modifier `groupModel` property is no longer supported. The equivalent can 
-be accomplished by the `action` helper or the new `fn` helper.
+4. The modifier `groupModel` property is no longer supported. The equivalent can
+   be accomplished by the `action` helper or the new `fn` helper.
 
 ```hbs
-<ol {{sortable-group onChange=(action "reorderItems" model)}}>
+<ol {{sortable-group onChange=(action 'reorderItems' model)}}>
   {{#each model.items as |item|}}
     <li {{sortable-item model=item}}>
       {{tem.name}}
-      <span class="handle" {{sortable-handle}}>&varr;</span>
+      <span class='handle' {{sortable-handle}}>&varr;</span>
     </li>
   {{/each}}
 </ol>
 ```
-

package/MIGRATION_GUIDE_V2.md

@@ -5,16 +5,20 @@
 [High Order Components](#Higher Order Components) or [Modifiers](/MIGRATION_GUIDE_MODIFIERS.md)
 
 ### Higher Order Components
+
 `Ember-sortable` can now be built using [higher order components](https://v4.chriskrycho.com/2018/higher-order-components-in-emberjs.html)
 
 1. The array of models are now yielded out by `sortable-group`
 
 **V1**
+
 ```hbs
 {{#sortable-group onChange=(action "reorderItems") as |group|}}
   {{#each model.items as |item|}}
 ```
+
 **V2**
+
 ```hbs
 {{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
   {{#each group.model as |item|}}
@@ -23,23 +27,25 @@
 2. Each `item` can be represented by the yielded `sortable-item` instead of directly using `sortable-item` and passing the `group` manually.
 
 **V1**
+
 ```hbs
-{{#sortable-group onChange=(action "reorderItems") as |group|}}
+{{#sortable-group onChange=(action 'reorderItems') as |group|}}
   {{#each model.items as |item|}}
-    {{#sortable-item model=item group=group handle=".handle"}}
+    {{#sortable-item model=item group=group handle='.handle'}}
       {{item.name}}
-      <span class="handle">&varr;</span>
+      <span class='handle'>&varr;</span>
     {{/sortable-item}}
   {{/each}}
 {{/sortable-group}}
 ```
 
 **V2**
+
 ```hbs
-{{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
+{{#sortable-group model=model.items onChange=(action 'reorderItems') as |group|}}
   {{#each group.model as |item|}}
     {{#group.item model=item}}
-    ...
+      ...
     {{/group.item}}
   {{/each}}
 {{/sortable-group}}
@@ -48,18 +54,20 @@
 3. It is recommended to use the yielded `sortable-handle` instead of referencing `handle` by `class`, as it guarantees accessibility support.
 
 **V1**
+
 ```hbs
-{{#sortable-group onChange=(action "reorderItems") as |group|}}
+{{#sortable-group onChange=(action 'reorderItems') as |group|}}
   {{#each model.items as |item|}}
-    {{#sortable-item model=item group=group handle=".handle"}}
+    {{#sortable-item model=item group=group handle='.handle'}}
       {{item.name}}
-      <span class="handle">&varr;</span>
+      <span class='handle'>&varr;</span>
     {{/sortable-item}}
   {{/each}}
 {{/sortable-group}}
 ```
 
 **V2**
+
 ```hbs
 {{#sortable-group model=model.items onChange=(action "reorderItems") as |group|}}
   {{#each group.model as |modelItem|}}
@@ -76,6 +84,7 @@
 4. `groupModel` is still supported via `groupModel` instead of `model`
 
 **V1**
+
 ```hbs
 {{#sortable-group model=model onChange=(action "reorderItems") as |group|}}
   {{#each model.items as |item|}}
@@ -84,6 +93,7 @@
 ```
 
 **V2**
+
 ```hbs
 {{#sortable-group groupModel=model model=model.items onChange=(action "reorderItems") as |group|}}
   {{#each group.model as |item|}}
@@ -94,6 +104,7 @@
 ### Modifiers
 
 ### Accessibility support
+
 1. Keyboard navigation is built into `ember-sortable`.
 2. `a11yItemName`, `a11yAnnouncementConfig`, `itemVisualClass`, `handleVisualClass` can be supplied to enhance the accessibility experience.
 3. Refer to [Accessibility Section](/README.md#Accessibility) for more details.
@@ -103,6 +114,7 @@
 ```
 
 ### Testing
+
 1. The `drag` and `reorder` test helpers are no longer global `async` helpers. They are now importable.
 
 Refer to [Testing Section](/README.md#Testing) for more details.

package/README.md

@@ -12,16 +12,21 @@ Sortable UI primitives for Ember.
 
 [Check out the demo](https://adopted-ember-addons.github.io/ember-sortable/demo/)
 
-## `2.2.0` modifier support
-*Note* `2.2.0` and above contains both component and modifiers invocation capabilities. This means that you will see a signficant size increase for `ember-sortable`, but it should help you with migrations to `modifier`, which is the path forward when we introduce  `v3.x.x`
+## v2 -> v3 Migration
+
+The component versions have been removed and you must use the modifier.
+The modifier version does not support `groupModel`, use the currying of the `fn` helper.
 
 ## v1 -> v2 Migration
+
 If you are migrating from `1.x.x` to `2.x.x`,
 For components, please read this [migration guide](/MIGRATION_GUIDE_V2.md).
 For modifiers, please read this [migration guide](/MIGRATION_GUIDE_MODIFIERS.md).
 
 ## Requirements
 
+In version 3.0.0+, Node.js v12 or above And Ember.js v3.24 or above
+
 In version 2.0.0+, our `closest` polyfill seems to break some app's `production` build. To mitigate this, the `closest` polyfill will only enabled if it doesn't break the `production` build (if the `polyfill` file is recognized by the build). Affected apps will need to supply their own [closest](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest#Polyfill) polyfill to ensure compatibility with IE. This issue is tracked [here](https://github.com/adopted-ember-addons/ember-sortable/issues/333).
 
 We require the `ember-decorators-polyfill` to be installed if you are using this addon with versions of Ember < 3.10.0.
@@ -38,34 +43,19 @@ $ ember install ember-sortable
 
 ## Usage
 
-### component
-```hbs
-{{! app/templates/my-route.hbs }}
-
-<SortableGroup @model={{this.model.items}} @onChange={{this.reorderItems}} as |group|>
-  {{#each group.model as |modelItem|}}
-    <group.item @model={{modelItem}} as |item|>
-      {{modelItem.name}}
-      <item.handle>
-        <span class="handle">&varr;</span>
-      </item.handle>
-    </group.item>
-  {{/each}}
-</SortableGroup>
-```
-
-### modifier
 ```hbs
-{{! app/templates/my-route.hbs }}
+{{! app/components/my-list/template.hbs }}
 
-<ol {{sortable-group onChange=(action "reorderItems")}}>
-  {{#each model.items as |modelItem|}}
-    <li {{sortable-item model=modelItem}}>
-      {{modelItem.name}}
-      <span class="handle" {{sortable-handle}}>&varr;</span>
+<ol {{sortable-group onChange=this.reorderItems}}>
+  {{#each this.items as |item|}}
+    <li {{sortable-item model=item}}>
+      {{item}}
+      <span class='handle' {{sortable-handle}}>&varr;</span>
     </li>
   {{/each}}
 </ol>
+
+<p>The last dragged item was: {{this.lastDragged}}</p>
 ```
 
 The `onChange` action is called with two arguments:
@@ -74,75 +64,39 @@ The `onChange` action is called with two arguments:
 - The model you just dragged
 
 ```js
-// app/routes/my-route.js
+// app/components/my-list/component.js
 
-export default Ember.Route.extend({
-  actions: {
-    reorderItems(itemModels, draggedModel) {
-      this.set('currentModel.items', itemModels);
-      this.set('currentModel.justDragged', draggedModel);
-    }
-  }
-});
-```
+export default class MyList extends Component {
+  @tracked lastDragged;
+  @tracked items = ['Coal Ila', 'Askaig', 'Bowmore'];
 
-### Declaring a “group model”
-
-When `groupModel` is set on the `sortable-group`, the `onChange` action is called
-with that group model as the first argument:
-
-```hbs
-{{! app/templates/my-route.hbs }}
-
-{{#sortable-group groupModel=model model=model.items onChange=(action "reorderItems") as |group|}}
-  {{#each group.model as |modelItem|}}
-    {{#group.item model=modelItem as |item|}}
-      {{modelItem.name}}
-      {{#item.handle}}
-        <span class="handle">&varr;</span>
-      {{/item.handle}}
-    {{/group.item}}
-  {{/each}}
-{{/sortable-group}}
-```
-
-```js
-// app/routes/my-route.js
-
-export default Ember.Route.extend({
-  actions: {
-    reorderItems(groupModel, itemModels, draggedModel) {
-      groupModel.set('items', itemModels);
-    }
+  @action
+  reorderItems(itemModels, draggedModel) {
+    this.items = itemModels;
+    this.lastDragged = draggedModel;
   }
-});
+}
 ```
 
 The modifier version does not support `groupModel`, use the currying of `action` or the `fn` helper.
 
 ```hbs
-{{! app/templates/my-route.hbs }}
+{{! app/components/my-list/template.hbs }}
 
-<ol {{sortable-group onChange=(action "reorderItems" model)}}>
-  {{#each model.items as |modelItem|}}
-    <li {{sortable-item model=modelItem}}>
-      {{modelItem.name}}
-      <span class="handle" {{sortable-handle}}>&varr;</span>
+<ol {{sortable-group onChange=(fn this.reorderItems model)}}>
+  {{#each this.items as |item|}}
+    <li {{sortable-item model=item}}>
+      {{item}}
+      <span class='handle' {{sortable-handle}}>&varr;</span>
     </li>
   {{/each}}
 </ol>
 ```
 
-
 ### Changing sort direction
 
 To change sort direction, define `direction` on `sortable-group` (default is `y`):
 
-component
-```hbs
-{{#sortable-group direction="x" onChange=(action "reorderItems") as |group|}}
-```
-modifier
 ```hbs
 <ol {{sortable-group direction="x" onChange=(action "reorderItems")}>
 ```
@@ -156,11 +110,6 @@ In `x` case: elements before current one jump to the left, and elements after cu
 
 To change this property, define `spacing` on `sortable-item` (default is `0`):
 
-component
-```hbs
-{{#sortable-item spacing=15}}
-```
-modifier
 ```hbs
 <li {{sortable-item spacing=15}}>
 ```
@@ -171,11 +120,6 @@ modifier
 If specified, sorting will not start until after mouse is dragged beyond distance.
 Can be used to allow for clicks on elements within a handle.
 
-component
-```hbs
-{{#sortable-item distance=30}}
-```
-modifier
 ```hbs
 <li {{sortable-item distance=30}}>
 ```
@@ -184,7 +128,6 @@ modifier
 
 The `disabled` attribute allows you to disable sorting for the entire group and its child items.
 
-modifier
 ```hbs
 <li {{sortable-group disabled=true}}>
 ```
@@ -210,7 +153,7 @@ transition of `.125s` in the default case:
 
 ```css
 .sortable-item {
-  transition: all .125s;
+  transition: all 0.125s;
 }
 ```
 
@@ -251,59 +194,39 @@ When the action is called, the item's model will be provided as the only
 argument.
 
 ```js
-// app/routes/my-route.js
-
-export default Ember.Route.extend({
-  actions: {
-    dragStarted(item) {
-      console.log(`Item started dragging: ${item.get('name')}`);
-    },
-    dragStopped(item) {
-      console.log(`Item stopped dragging: ${item.get('name')}`);
-    }
+// app/components/my-list/component.js
+
+export default class MyRoute extends Route {
+  @action
+  dragStarted(item) {
+    console.log(`Item started dragging: ${item}`);
+  },
+  @action
+  dragStopped(item) {
+    console.log(`Item stopped dragging: ${item}`);
   }
-});
+}
 ```
 
-component
-```hbs
-  {{#sortable-item
-    onDragStart=(action "dragStarted")
-    onDragStop=(action "dragStopped")
-    model=modelItem
-    as |item|
-  }}
-    {{modelItem.name}}
-    {{#item.handle}}
-      <span class="handle">&varr;</span>
-    {{/item.handle}}
-  {{/sortable-item}}
-```
-modifier
 ```hbs
-  <li {{#sortable-item
-    onDragStart=(action "dragStarted")
-    onDragStop=(action "dragStopped")
-    model=modelItem
-    }}
-  >
-    {{modelItem.name}}
-    <span class="handle" {{sortable-handle}}>&varr;</span>
-  </li>
+<li {{sortable-item onDragStart=this.dragStarted onDragStop=this.dragStopped model=item}}>
+  {{item}}
+  <span class='handle' {{sortable-handle}}>&varr;</span>
+</li>
 ```
 
-### Multiple Ember-Sortables renders simultaneously (Modifier version)
+### Multiple Ember-Sortables renders simultaneously
 
-The modifier version uses a service behind the scenes for communication between the group and the items and to maintain state. It does this seemlessly when the elements are rendered on the screen. However, if there are two sortables rendered at the same time, either in the same component or different components, the state management does not know which items belong to which group.
+There is a service behind the scenes for communication between the group and the items and to maintain state. It does this seemlessly when the elements are rendered on the screen. However, if there are two sortables rendered at the same time, either in the same component or different components, the state management does not know which items belong to which group.
 
 Both the `{{sortable-group}}` and `{{sortable-item}}` take an additional argument `groupName`. Should you encounter this conflict, assign a `groupName` to the group and items. You only need to do this for one of the sortables in conflict, but you can on both if you wish.
 
 ```hbs
-<ol {{sortable-group groupName="products" onChange=(action "reorderItems" model)}}>
-  {{#each model.items as |modelItem|}}
-    <li {{sortable-item groupName="products" model=modelItem}}>
-      {{modelItem.name}}
-      <span class="handle" {{sortable-handle}}>&varr;</span>
+<ol {{sortable-group groupName='products' onChange=this.reorderItems}}>
+  {{#each this.items as |item|}}
+    <li {{sortable-item groupName='products' model=item}}>
+      {{item}}
+      <span class='handle' {{sortable-handle}}>&varr;</span>
     </li>
   {{/each}}
 </ol>
@@ -312,21 +235,21 @@ Both the `{{sortable-group}}` and `{{sortable-item}}` take an additional argumen
 Ensure that the same name is passed to both the group and the items, this would be best accomplished by creating property on the component and referring to that property. If you are able to use the `{{#let}}` helper (useful in template only components), using `{{#let}}` makes the usage clearer.
 
 ```hbs
-{{#let "products" as | myGroupName |}}
-  <ol {{sortable-group groupName=myGroupName onChange=(action "reorderItems" model)}}>
-    {{#each model.items as |modelItem|}}
-      <li {{sortable-item groupName=myGroupName model=modelItem}}>
-        {{modelItem.name}}
-        <span class="handle" {{sortable-handle}}>&varr;</span>
+{{#let 'products' as |myGroupName|}}
+  <ol {{sortable-group groupName=myGroupName onChange=this.reorderItems}}>
+    {{#each this.items as |item|}}
+      <li {{sortable-item groupName=myGroupName model=item}}>
+        {{item}}
+        <span class='handle' {{sortable-handle}}>&varr;</span>
       </li>
     {{/each}}
   </ol>
 {{/let}}
 ```
 
-
 ### Disabling Drag (Experimental)
-`sortable-item` (component and modifier) exposes an optional `disabled` (previously `isDraggingDisabled`) flag that you can use to disable reordering for that particular item. Disabling and item won't prevent it from changing position in the array. The user can still move other non-disabled items to over it.
+
+`sortable-item` exposes an optional `disabled` (previously `isDraggingDisabled`) flag that you can use to disable reordering for that particular item. Disabling and item won't prevent it from changing position in the array. The user can still move other non-disabled items to over it.
 
 This flag is intended as an utility to make your life easier with 3 main benefits:
 
@@ -341,40 +264,35 @@ No data is mutated by `sortable-group` or `sortable-item`. In the spirit of “d
 Each item takes a `model` property. This should be fairly self-explanatory but it’s important to note that it doesn’t do anything with this object besides keeping a reference for later use in `onChange`.
 
 ### Accessibility
+
 The `sortable-group` has support for the following accessibility functionality:
 
 #### Built-in Functionalities
 
-##### Semantic HTML
-
-component
-- `sortable-group`
-  an ordered list, `ol`, by default.
-- `sortable-item`
-  a list item, `li`, by default.
-
-The modifier version can be attached to to any element that makes sense,
-
 ##### Keyboard Navigation
+
 There are 4 modes during keyboard navigation:
+
 - **ACTIVATE**
   enables the keyboard navigation.
-  Activate via  `ENTER/SPACE`
+  Activate via `ENTER/SPACE`
 - **MOVE**
   enables item(s) to be moved up, down, left, or right based on `direction`.
-  Activate via  `ARROW UP/DOWN/LEFT/RIGHT`
+  Activate via `ARROW UP/DOWN/LEFT/RIGHT`
 - **CONFIRM**
   submits the new sort order, invokes the `onChange` action.
-  Activate via  `ENTER/SPACE`.
+  Activate via `ENTER/SPACE`.
 - **CANCEL**
   cancels the new sort order, reverts back to the old sort order.
-  Activate via  `ESCAPE` or when `focus` is lost.
+  Activate via `ESCAPE` or when `focus` is lost.
 
 ##### Focus Management
+
 - When `focus` is on a `item` or `handle`, user can effectively select the `item` via `ENTER/SPACE`. This is the `ACTIVATE` mode.
 - While `ACTIVATE`, the `focus` is locked on `sortable-group` container and will not be lost until `CONFIRM`, `CANCEL`, or `focus` is lost.
 
 #### User configurable
+
 ##### Screen Reader
 
 The default language for `ember-sortable` is English. Any language can be supported by passing in the configuration below in the appropriate language.
@@ -383,6 +301,7 @@ The default language for `ember-sortable` is English. Any language can be suppor
   a name for the item. Defaults to `item`.
 - **a11yAnnouncementConfig**
   a map of `action enums` to `functions` that takes the following `config`, which is exposed by `sortable-group`.
+
 ```javascript
 a11yAnnounceConfig = {
   a11yItemName, // name associated with the name
@@ -390,11 +309,13 @@ a11yAnnounceConfig = {
   maxLength, // length of the items
   direction, // x or y
   delta, // +1 means down or right, -1 means up or left
-}
+};
 ```
+
 and returns a `string` constructed from the `config`.
 
 **Default value**
+
 ```javascript
 {
   ACTIVATE: function({ a11yItemName, index, maxLength, direction }) {
@@ -422,6 +343,7 @@ and returns a `string` constructed from the `config`.
 ```
 
 ##### Visual Indicator
+
 - **handleVisualClass**
   This class will be added to the `sortable-handle` during `ACTIVATE` and `MOVE` operations. This allows you to add custom styles such as `visual arrows` via `pseudo` classes.
 
@@ -432,9 +354,9 @@ and returns a `string` constructed from the `config`.
 
 `ember-sortable` exposes some acceptance test helpers:
 
-* [`drag`][drag]: Drags elements by an offset specified in pixels.
-* [`reorder`][reorder]: Reorders elements to the specified state.
-* [`keyboard`][keyboard]: Keycode constants for quick.
+- [`drag`][drag]: Drags elements by an offset specified in pixels.
+- [`reorder`][reorder]: Reorders elements to the specified state.
+- [`keyboard`][keyboard]: Keycode constants for quick.
 
 [drag]: addon-test-support/helpers/drag.js
 [reorder]: addon-test-support/helpers/reorder.js
@@ -443,32 +365,35 @@ and returns a `string` constructed from the `config`.
 To include them in your application, you can import them:
 
 ```js
-import { drag, reorder }  from 'ember-sortable/test-support/helpers';
-import { ENTER_KEY_CODE, SPACE_KEY_CODE, ESCAPE_KEY_CODE, ARROW_KEY_CODES } from "ember-sortable/test-support/utils/keyboard";
+import { drag, reorder } from 'ember-sortable/test-support/helpers';
+import {
+  ENTER_KEY_CODE,
+  SPACE_KEY_CODE,
+  ESCAPE_KEY_CODE,
+  ARROW_KEY_CODES,
+} from 'ember-sortable/test-support/utils/keyboard';
 ```
 
 ### Examples
+
 `Reorder`
+
 ```js
-await reorder(
-  'mouse',
-  '[data-test-vertical-demo-handle]',
-  ...order
-);
+await reorder('mouse', '[data-test-vertical-demo-handle]', ...order);
 ```
 
 `Drag`
+
 ```js
-await drag('mouse', '[data-test-scrollable-demo-handle] .handle', () => { return {dy: itemHeight() * 2 + 1, dx: undefined}});
+await drag('mouse', '[data-test-scrollable-demo-handle] .handle', () => {
+  return { dy: itemHeight() * 2 + 1, dx: undefined };
+});
 ```
 
 `Keyboard`
+
 ```js
-await triggerKeyEvent(
-  '[data-test-vertical-demo-handle]',
-  'keydown',
-  ENTER_KEY_CODE
-);
+await triggerKeyEvent('[data-test-vertical-demo-handle]', 'keydown', ENTER_KEY_CODE);
 ```
 
 ## Developing