Merge pull request #1 from dknutsen/docs

Version 0.1.0 addon docs

.npmignore

@@ -29,3 +29,4 @@
 /.node_modules.ember-try/
 /bower.json.ember-try
 /package.json.ember-try
+/config/addon-docs.js

config/addon-docs.js

@@ -0,0 +1,9 @@
+/* eslint-env node */
+'use strict';
+
+const AddonDocsConfig = require('ember-cli-addon-docs/lib/config');
+
+module.exports = class extends AddonDocsConfig {
+  // See https://ember-learn.github.io/ember-cli-addon-docs/docs/deploying
+  // for details on configuration you can override here.
+};

config/deploy.js

@@ -0,0 +1,29 @@
+/* eslint-env node */
+'use strict';
+
+module.exports = function(deployTarget) {
+  let ENV = {
+    build: {}
+    // include other plugin configuration that applies to all deploy targets here
+  };
+
+  if (deployTarget === 'development') {
+    ENV.build.environment = 'development';
+    // configure other plugins for development deploy target here
+  }
+
+  if (deployTarget === 'staging') {
+    ENV.build.environment = 'production';
+    // configure other plugins for staging deploy target here
+  }
+
+  if (deployTarget === 'production') {
+    ENV.build.environment = 'production';
+    // configure other plugins for production deploy target here
+  }
+
+  // Note: if you need to build some configuration asynchronously, you can return
+  // a promise that resolves with the ENV object instead of returning the
+  // ENV object synchronously.
+  return ENV;
+};

package.json

@@ -1,11 +1,15 @@
 {
   "name": "ember-needs-async",
-  "version": "0.0.0",
-  "description": "The default blueprint for ember-cli addons.",
+  "version": "0.1.0",
+  "description": "Declarative, composable primitives for loading and rendering async data directly from templates.",
   "keywords": [
     "ember-addon"
   ],
-  "repository": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dknutsen/ember-needs-async.git"
+  },
+  "homepage": "https://dknutsen.github.io/ember-needs-async",
   "license": "MIT",
   "author": "",
   "directories": {
@@ -30,7 +34,13 @@
     "@ember/optional-features": "^0.6.4",
     "broccoli-asset-rev": "^2.7.0",
     "ember-cli": "~3.7.1",
+    "ember-cli-addon-docs": "^0.6.7",
+    "ember-cli-addon-docs-yuidoc": "^0.2.1",
     "ember-cli-dependency-checker": "^3.0.0",
+    "ember-cli-deploy": "^1.0.2",
+    "ember-cli-deploy-build": "^1.1.1",
+    "ember-cli-deploy-git": "^1.3.3",
+    "ember-cli-deploy-git-ci": "^1.0.1",
     "ember-cli-eslint": "^4.2.3",
     "ember-cli-htmlbars-inline-precompile": "^1.0.3",
     "ember-cli-inject-live-reload": "^1.8.2",

tests/dummy/app/controllers/docs/needs-async.js

@@ -0,0 +1,20 @@
+import Controller from '@ember/controller';
+import { task, timeout } from 'ember-concurrency';
+
+export default Controller.extend({
+  randomNum: task(function * () {
+    yield timeout(1000);
+    this.set('result', Math.random());
+    return this.result;
+  }).drop(),
+
+  result: null,
+
+  taskInstance: null,
+
+  actions: {
+    onClick() {
+      this.set('taskInstance', this.randomNum.perform());
+    }
+  }
+});

tests/dummy/app/controllers/index.js

@@ -1,20 +1,4 @@
 import Controller from '@ember/controller';
-import { task, timeout } from 'ember-concurrency';
 
 export default Controller.extend({
-  askQuestion: task(function * () {
-    yield timeout(1000);
-    this.set('result', Math.random());
-    return this.result;
-  }).drop(),
-
-  result: null,
-
-  taskInstance: null,
-
-  actions: {
-    onClick() {
-      this.set('taskInstance', this.askQuestion.perform());
-    }
-  }
 });

tests/dummy/app/router.js

@@ -1,13 +1,29 @@
-import EmberRouter from '@ember/routing/router';
+//import EmberRouter from '@ember/routing/router';
+import AddonDocsRouter, { docsRoute } from 'ember-cli-addon-docs/router';
 import config from './config/environment';
 
-const Router = EmberRouter.extend({
+const Router = AddonDocsRouter.extend({
   location: config.locationType,
   rootURL: config.rootURL
 });
 
 Router.map(function() {
   this.route('sandbox');
+  this.route('examples');
+  docsRoute(this, function() {
+    this.route('index');
+    this.route('usage');
+    this.route('needs-async');
+    this.route('find-record');
+    this.route('find-all');
+    this.route('peek-record');
+    this.route('peek-all');
+    this.route('belongs-to');
+    this.route('has-many');
+    this.route('async-all');
+    this.route('async-hash');
+  });
+  this.route('not-found', { path: '/*path' });
 });
 
 export default Router;

tests/dummy/app/routes/docs.js

@@ -0,0 +1,4 @@
+import Route from '@ember/routing/route';
+
+export default Route.extend({
+});

tests/dummy/app/routes/examples.js

@@ -0,0 +1,4 @@
+import Route from '@ember/routing/route';
+
+export default Route.extend({
+});

tests/dummy/app/templates/application.hbs

@@ -1,6 +1,8 @@
-<nav class="w-full h-8 bg-grey-light">
-  {{#link-to 'index'}}Main{{/link-to}}
-  {{#link-to 'sandbox'}}Sandbox{{/link-to}}
-</nav>
+{{#docs-header as |header|}}
+  {{#header.link "examples"}}Examples{{/header.link}}
+  {{!--
+  {{#header.link "sandbox"}}Sandbox{{/header.link}}
+  --}}
+{{/docs-header}}
 
 {{outlet}}

tests/dummy/app/templates/docs.hbs

@@ -0,0 +1,24 @@
+{{#docs-viewer as |viewer|}}
+  {{#viewer.nav as |nav|}}
+    {{nav.section "The Basics"}}
+    {{nav.item "Introduction" "docs.index"}}
+    {{nav.item "Usage" "docs.usage"}}
+
+    {{nav.section "Components"}}
+    {{nav.item "needs-async" "docs.needs-async"}}
+
+    {{nav.section "Helpers"}}
+    {{nav.item "find-record" "docs.find-record"}}
+    {{nav.item "find-all" "docs.find-all"}}
+    {{nav.item "peek-record" "docs.peek-record"}}
+    {{nav.item "peek-all" "docs.peek-all"}}
+    {{nav.item "belongs-to" "docs.belongs-to"}}
+    {{nav.item "has-many" "docs.has-many"}}
+    {{nav.item "async-all" "docs.async-all"}}
+    {{nav.item "async-hash" "docs.async-hash"}}
+  {{/viewer.nav}}
+
+  {{#viewer.main}}
+    {{outlet}}
+  {{/viewer.main}}
+{{/docs-viewer}}

tests/dummy/app/templates/docs/async-all.hbs

@@ -0,0 +1,28 @@
+<h1>async-all helper</h1>
+
+<p>The async-all helper takes an array of tasks and yields a task that finishes when all of the subtasks finish. It is exactly the same as the ember-concurrency all task.</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="async-all-demo.hbs"}}
+
+    <h2>Three Users</h2>
+    <NeedsAsync @needs={{async-all (array
+      (find-record "user" "1")
+      (find-record "user" "2")
+      (find-record "user" "3")
+    )}} as |States|>
+      <States.loading>
+        Loading users...
+      </States.loading>
+
+      <States.loaded as |users|>
+        {{#each users as |user|}}
+          <div>{{user.fullName}}</div>
+        {{/each}}
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="async-all-demo.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/async-hash.hbs

@@ -0,0 +1,27 @@
+<h1>async-hash helper</h1>
+
+<p>The async-hash helper takes a hash of tasks and yields a task that finishes when all of the subtasks finish. It is exactly the same as the ember-concurrency hash task.</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="async-hash-demo.hbs"}}
+    <h2>Three users with labels</h2>
+    <NeedsAsync @needs={{async-hash (hash
+      user1=(find-record "user" "1")
+      user2=(find-record "user" "2")
+      user3=(find-record "user" "3")
+    )}} as |States|>
+      <States.loading>
+        Loading...
+      </States.loading>
+
+      <States.loaded as |users|>
+        {{#each-in users as |label user|}}
+          <div>{{label}}: {{user.fullName}}</div>
+        {{/each-in}}
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="async-hash-demo.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/belongs-to.hbs

@@ -0,0 +1,34 @@
+<h1>belongs-to</h1>
+
+<p>The belongs-to helper takes a model and a relationship name and returns an ember concurrency task that resolves to the value of the relationship once loaded.</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="belongs-to-demo.hbs"}}
+
+    <h2>User Company Details</h2>
+    <NeedsAsync @needs={{find-record "user" "4"}} as |States|>
+      <States.loading>LOADING USER</States.loading>
+
+      <States.loaded as |user|>
+        <NeedsAsync @needs={{belongs-to user "company"}} as |States|>
+          <States.loading>LOADING COMPANY DATA</States.loading>
+
+          <States.loaded as |company|>
+            <div>
+              <div>{{company.name}} - {{company.motto}}</div>
+              <div>
+                {{company.street}}
+                {{company.city}}
+                {{company.state}}
+                {{company.zip}}
+              </div>
+            </div>
+          </States.loaded>
+        </NeedsAsync>
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="belongs-to-demo.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/find-all.hbs

@@ -0,0 +1,24 @@
+<h1>find-all helper</h1>
+
+<p>The find-all helper takes a model type and returns an ember concurrency task which will resolve to an array of models. It is the same as store.findAll().</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="find-all-demo.hbs"}}
+
+    <h2>All Users</h2>
+    <NeedsAsync @needs={{find-all "user"}} as |States|>
+      <States.loading>
+        Loading users...
+      </States.loading>
+
+      <States.loaded as |users|>
+        {{#each users as |user|}}
+          <div>{{user.fullName}}</div>
+        {{/each}}
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="find-all-demo.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/find-record.hbs

@@ -0,0 +1,22 @@
+<h1>find-record helper</h1>
+
+<p>The find-record helper takes a model type and an id and returns an ember concurrency task that resolves to a record. It is exactly the same as store.findRecord().</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="find-record-demo.hbs"}}
+
+    <h2>One User</h2>
+    <NeedsAsync @needs={{find-record "user" "1"}} as |States|>
+      <States.loading>
+        Loading user...
+      </States.loading>
+
+      <States.loaded as |user|>
+        <div>{{user.fullName}}</div>
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="find-record-demo.hbs"}}
+{{/docs-demo}}

tests/dummy/app/templates/docs/has-many.hbs

@@ -0,0 +1,28 @@
+<h1>has-many</h1>
+
+<p>The has-many helper takes a model and a relationship name and returns an ember concurrency task that resolves to the value of the relationship once loaded.</p>
+
+{{#docs-demo as |demo|}}
+  {{#demo.example name="has-many-demo.hbs"}}
+
+    <h2>Company Employees</h2>
+    <NeedsAsync @needs={{find-record "organization" "1"}} as |States|>
+      <States.loading>LOADING COMPANY</States.loading>
+
+      <States.loaded as |company|>
+        <NeedsAsync @needs={{has-many company "employees"}} as |States|>
+          <States.loading>LOADING USERS</States.loading>
+
+          <States.loaded as |users|>
+            {{#each users as |user|}}
+              <div>{{user.fullName}}</div>
+            {{/each}}
+          </States.loaded>
+        </NeedsAsync>
+      </States.loaded>
+    </NeedsAsync>
+
+  {{/demo.example}}
+
+  {{demo.snippet name="has-many-demo.hbs"}}
+{{/docs-demo}}

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

@@ -0,0 +1,8 @@
+# Introduction
+
+ember-needs-async is a little experiment into the idea of loading data in templates. It's very lightweight and consists of just a couple simple parts:
+
+* a `needs-async` provider component which takes a "need" (technically an ember concurrency task instance) and yields "state" provider components such as "loading", "loaded" and "error"
+* a few helpers which correspond to common Ember Data operations such as `find-record`, `has-many`, etc.
+
+These pieces together allow declarative asynchronous data fetching and rendering using only a handlebars template. While there are undoubtedly very valid criticisms of this approach and particularly this implementation, there are probably also some valid use cases for loading data in this manner. It's also fun to play around with. Check out {{#link-to "docs.usage"}}usage{{/link-to}} for the basics on how to use the addon or head over to {{#link-to "examples"}}examples{{/link-to}} to see some samples and ideas.