commit beginnings of this humble add-on

README.md

@@ -1,6 +1,69 @@
-# Ember-scroll-operator
+# ember-scroll-operator
 
-This README outlines the details of collaborating on this Ember addon.
+This ember-cli addon provides two route mixins that will handle scroll preservation and resetting. Read more for details.
+
+## Theme music
+
+<iframe width="420" height="315" src="https://www.youtube.com/embed/cA9gUspn6gc" frameborder="0" allowfullscreen></iframe>
+
+Please mentally replace the word 'smooth' with 'scroll'.
+
+## ScrollOperatorMixin
+
+This will save the scrolling position of a route. When the route is re-entered, it will automatically scroll to the previously saved position *only if accessed by the browser's forward and back buttons*. Accessing the route via link-to or address bar will not trigger this behavior. This is by design in order to more closely emulate the HTML experience.
+
+```
+import ScrollOperatorMixin from 'ember-scroll-operator/mixins/scroll-operator';
+
+export default Ember.Route.extend(ScrollOperatorMixin, {
+
+  // If any of the following methods are implemented in your route, be sure to
+  // include a call to the parent to make sure the mixin is included.
+
+  activate() {
+    this._super(...arguments);
+    // existing code
+  },
+
+  deactivate() {
+    this._super(...arguments);
+    // existing code
+  },
+
+  beforeModel() {
+    this._super(...arguments);
+    // existing code
+  },
+
+  setupController() {
+    this._super(...arguments);
+    // existing code
+  },
+
+});
+```
+
+## ResetScrollMixin
+
+A simple mixin to ensure that a route is always scrolled to the top when accessed.
+
+```
+import ResetScrollMixin from 'ember-scroll-operator/mixins/reset-scroll';
+
+export default Ember.Route.extend(ResetScrollMixin, {
+
+  // If the following methods are implemented in your route, be sure to include
+  // a call to the parent to make sure the mixin is included.
+
+  activate() {
+    this._super(...arguments);
+    // existing code
+  },
+
+});
+```
+
+# Development Setup
 
 ## Installation
 
@@ -24,3 +87,7 @@ This README outlines the details of collaborating on this Ember addon.
 * `ember build`
 
 For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/).
+
+# Credits
+
+Thanks to @gdub22 for their insight on determining when transitions are triggered by the browser's back/forward buttons ([related](https://github.com/emberjs/ember.js/issues/3087#issuecomment-22064811)).

addon/mixins/reset-scroll.js

@@ -0,0 +1,10 @@
+import Ember from 'ember';
+
+export default Ember.Mixin.create({
+  /**
+   * Scroll to top when route is entered.
+   */
+  activate() {
+    Ember.$(window).scrollTop(0);
+  },
+});

addon/mixins/scroll-operator.js

@@ -0,0 +1,60 @@
+import Ember from 'ember';
+
+export default Ember.Mixin.create({
+  scrollingTimeout: 100,
+
+  /**
+   * Attach on-scroll handler to window/document. Handler will call _scrollTop
+   * on scroll.
+   */
+  activate() {
+    const onScroll = () => {
+      Ember.run.debounce(this, this._setScrollTop, this.scrollingTimeout);
+    };
+    Ember.$(document).on('touchmove.scrollable', onScroll);
+    Ember.$(window).on('scroll.scrollable', onScroll);
+  },
+
+  /**
+   * Detach on-scroll handlers on route exit.
+   */
+  deactivate() {
+    Ember.$(document).off('.scrollable');
+    Ember.$(window).off('.scrollable');
+  },
+
+  /**
+   * On entering route, decide whether we want to resume previous scrolling
+   * position or not based on transition.
+   */
+  beforeModel(transition) {
+    if (!this._didTransitionViaBackOrForward(transition) && this.controller) {
+      this.controller.set('currentPosition', 0);
+    }
+  },
+
+  /**
+   * Scroll to currentPosition value. Uses run-loop's next helper to ensure it
+   * happens after model hooks have been fully executed.
+   */
+  setupController(controller) {
+    Ember.run.next(null, () => {
+      Ember.$(window).scrollTop(controller.getWithDefault('currentPosition', 0));
+    });
+  },
+
+  /**
+   * Set currentPosition to $(window).scrollTop value.
+   */
+  _setScrollTop() {
+    this.set('controller.currentPosition', Ember.$(window).scrollTop());
+  },
+
+  /**
+   * Determine if transition is triggered by browser forward/back buttons.
+   * Credit: https://github.com/emberjs/ember.js/issues/3087
+   */
+  _didTransitionViaBackOrForward(transition) {
+    return transition && transition.sequence > 1 && transition.hasOwnProperty('urlMethod');
+  },
+});

app/mixins/reset-scroll.js

@@ -0,0 +1,4 @@
+import Ember from 'ember';
+import ResetScrollMixin from 'ember-scroll-operator/mixins/reset-scroll';
+
+export default ResetScrollMixin;

app/mixins/scroll-operator.js

@@ -0,0 +1,4 @@
+import Ember from 'ember';
+import ScrollOperatorMixin from 'ember-scroll-operator/mixins/scroll-operator';
+
+export default ScrollOperatorMixin;

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ember-scroll-operator",
-  "version": "0.0.0",
-  "description": "The default blueprint for ember-cli addons.",
+  "version": "0.0.1",
+  "description": "Handle the preservation of scrolling positions when traversing routes via the browser's back and forward buttons.",
   "directories": {
     "doc": "doc",
     "test": "tests"
@@ -40,7 +40,10 @@
     "loader.js": "^4.0.0"
   },
   "keywords": [
-    "ember-addon"
+    "ember-addon",
+    "scrolling",
+    "scroll position",
+    "browser history"
   ],
   "dependencies": {
     "ember-cli-babel": "^5.1.5"

tests/unit/mixins/reset-scroll-test.js

@@ -0,0 +1,12 @@
+import Ember from 'ember';
+import ResetScrollMixin from 'ember-scroll-operator/mixins/reset-scroll';
+import { module, test } from 'qunit';
+
+module('Unit | Mixin | reset scroll');
+
+// Replace this with your real tests.
+test('it works', function(assert) {
+  let ResetScrollObject = Ember.Object.extend(ResetScrollMixin);
+  let subject = ResetScrollObject.create();
+  assert.ok(subject);
+});

tests/unit/mixins/scroll-operator-test.js

@@ -0,0 +1,12 @@
+import Ember from 'ember';
+import ScrollOperatorMixin from 'ember-scroll-operator/mixins/scroll-operator';
+import { module, test } from 'qunit';
+
+module('Unit | Mixin | scroll operator');
+
+// Replace this with your real tests.
+test('it works', function(assert) {
+  let ScrollOperatorObject = Ember.Object.extend(ScrollOperatorMixin);
+  let subject = ScrollOperatorObject.create();
+  assert.ok(subject);
+});