[guides] Finalize Guides for v2.0.0-beta.1 (#549)

* [guides] Finalize Guides for v2.0.0-beta.1

This PR updates the docs app for the first beta of v2. Changes include:

- Converting all curly bracket invocations to angle brackets
- Adding missing guides pages
- Adding API docs
- Shifting examples -> guides (better terminology)
- Adding/updating intro and landing pages

There is also one minor behavioral change, we've dropped the `CellProxy`
construct. In writing the guides it became apparent that it was leaky,
and the perf benefits are questionable. For now, cell metas are POJOs.

* add section on usage without angle brackets

* address comments

* fix data test selector

addon/components/-private/row-wrapper.js

@@ -9,12 +9,11 @@ import { argument } from '@ember-decorators/argument';
 
 import { computed } from '@ember-decorators/object';
 
-import CellProxy from '../../-private/cell-proxy';
 import { objectAt } from '../../-private/utils/array';
 
-class CellWrapper extends EmberObject {
-  _cellMeta = CellProxy.create();
+import { guidFor } from '@ember/object/internals';
 
+class CellWrapper extends EmberObject {
   @computed('rowValue', 'columnValue.valuePath')
   get cellValue() {
     let row = get(this, 'rowValue');
@@ -25,22 +24,18 @@ class CellWrapper extends EmberObject {
 
   @computed('rowValue', 'columnValue.valuePath')
   get cellMeta() {
-    let { _cellMeta } = this;
     let row = get(this, 'rowValue');
+    let rowId = guidFor(row);
     let valuePath = get(this, 'columnValue.valuePath');
     let cellMetaCache = get(this, 'cellMetaCache');
 
-    set(_cellMeta, 'row', row);
-    set(_cellMeta, 'valuePath', valuePath);
-    set(_cellMeta, 'cellMetaCache', cellMetaCache);
-
-    return _cellMeta;
-  }
+    let cellId = `${rowId}:${valuePath}`;
 
-  destroy() {
-    this._cellMeta.destroy();
+    if (!cellMetaCache.has(cellId)) {
+      cellMetaCache.set(cellId, EmberObject.create());
+    }
 
-    super.destroy(...arguments);
+    return cellMetaCache.get(cellId);
   }
 }
 

addon/components/ember-table/component.js

@@ -16,13 +16,32 @@ import {
 
 import layout from './template';
 
+/**
+  The primary Ember Table component. This component represents the root of the
+  table, and manages high level state of all of its subcomponents. It does not
+  have any arguments or actions itself - instead, all of those concerns are
+  delegated to its children, who communicate to each other via the API.
+
+  ```hbs
+  <EmberTable as |t|>
+    <t.head @columns={{columns}} />
+    <t.body @rows={{rows}} />
+    <t.foot @rows={{footerRows}} />
+  </EmberTable>
+  ```
+
+  @yield {object} t - the API object yielded by the table
+  @yield {Component} t.head - The table header component
+  @yield {Component} t.body - The table body component
+  @yield {Component} t.foot - The table footer component
+*/
 @classNames('ember-table')
 export default class EmberTable extends Component {
   layout = layout;
 
   @service userAgent;
 
-  @attribute dataTestEmberTable = true;
+  @attribute('data-test-ember-table') dataTestEmberTable = true;
 
   didInsertElement() {
     super.didInsertElement(...arguments);

addon/components/ember-tbody/component.js

@@ -14,10 +14,35 @@ import CollapseTree, { SELECT_MODE } from '../../-private/collapse-tree';
 import layout from './template';
 import { assert } from '@ember/debug';
 
+/**
+  The table body component. This component manages the main bulk of the rows of
+  the table, provided occlusion for them and managing their behavior. It yields
+  a template for each row, and an API that contains a row component, the row
+  value, and the meta object for the row.
+
+  ```hbs
+  <EmberTable as |t|>
+    <t.head @columns={{columns}} />
+
+    <t.body @rows={{rows}} as |b|>
+      <b.row>
+    </t.body>
+  </EmberTable>
+  ```
+
+  @yield {object} b - the API object yielded by the table body
+  @yield {Component} b.row - The table row component
+
+  @yield {object} b.rowValue - The value for the currently yielded row
+  @yield {object} b.rowMeta - The meta for the currently yielded row
+*/
 @tagName('tbody')
 export default class EmberTBody extends Component {
   layout = layout;
 
+  /**
+    The API object passed in by the table
+  */
   @argument
   @required
   @type('object')

addon/components/ember-tbody/template.hbs

@@ -28,7 +28,11 @@
     as |api|
   }}
     {{#if hasBlock}}
-      {{yield (hash api=api
+      {{yield (hash
+        rowValue=api.rowValue
+        rowMeta=api.rowMeta
+        cells=api.cells
+        rowSelectionMode=api.rowSelectionMode
 
         row=(component "ember-tr" api=api)
       )}}

addon/components/ember-td/component.js

@@ -4,48 +4,76 @@ import { htmlSafe } from '@ember/string';
 import { action, computed } from '@ember-decorators/object';
 import { readOnly, equal } from '@ember-decorators/object/computed';
 import { tagName, attribute, className } from '@ember-decorators/component';
-import { service } from '@ember-decorators/service';
 import { argument } from '@ember-decorators/argument';
 import { type, optional } from '@ember-decorators/argument/type';
 import { Action } from '@ember-decorators/argument/types';
 
 import layout from './template';
 import { SELECT_MODE } from '../../-private/collapse-tree';
 
+/**
+  The table cell component. This component manages cell level concerns, yields
+  the cell value, column value, row value, and all of their associated meta
+  objects.
+
+  ```hbs
+  <EmberTable as |t|>
+    <t.head @columns={{columns}} />
+
+    <t.body @rows={{rows}} as |b|>
+      <b.row as |r|>
+        <r.cell as |cellValue columnValue rowValue cellMeta columnMeta rowMeta|>
+
+        </r.cell>
+      </b.row>
+    </t.body>
+  </EmberTable>
+  ```
+
+  @yield {any} cellValue - The value of the cell
+  @yield {object} columnValue - The column definition
+  @yield {object} rowValue - The row definition
+
+  @yield {object} cellMeta - The meta object associated with the cell
+  @yield {object} columnMeta - The meta object associated with the column
+  @yield {object} rowMeta - The meta object associated with the row
+*/
 @tagName('td')
 export default class EmberTd extends Component {
   layout = layout;
 
-  @service fastboot;
-
+  /**
+    The API object passed in by the table row
+  */
   @argument
   @type('object')
   api;
 
+  /**
+    Action sent when the user clicks this element
+  */
   @argument
   @type(optional(Action))
   onClick;
 
+  /**
+    Action sent when the user double clicks this element
+  */
   @argument
   @type(optional(Action))
   onDoubleClick;
 
-  @computed('api.api')
-  get unwrappedApi() {
-    return this.get('api.api') || this.get('api');
-  }
-
-  @readOnly('unwrappedApi.cellValue') cellValue;
-  @readOnly('unwrappedApi.cellMeta') cellMeta;
+  @readOnly('api.cellValue') cellValue;
+  @readOnly('api.cellMeta') cellMeta;
 
-  @readOnly('unwrappedApi.columnValue') columnValue;
-  @readOnly('unwrappedApi.columnMeta') columnMeta;
+  @readOnly('api.columnValue') columnValue;
+  @readOnly('api.columnMeta') columnMeta;
 
-  @readOnly('unwrappedApi.rowValue') rowValue;
-  @readOnly('unwrappedApi.rowMeta') rowMeta;
+  @readOnly('api.rowValue') rowValue;
+  @readOnly('api.rowMeta') rowMeta;
 
-  @readOnly('unwrappedApi.rowSelectionMode') rowSelectionMode;
-  @readOnly('unwrappedApi.checkboxSelectionMode') checkboxSelectionMode;
+  @readOnly('api.rowSelectionMode') rowSelectionMode;
+  @readOnly('api.checkboxSelectionMode') checkboxSelectionMode;
 
   @className
   @equal('columnMeta.index', 0)
@@ -100,7 +128,7 @@ export default class EmberTd extends Component {
       style += `right: ${Math.round(this.get('columnMeta.offsetRight'))}px;`;
     }
 
-    if (!this.get('fastboot.isFastBoot') && this.element) {
+    if (typeof FastBoot === 'undefined' && this.element) {
       // Keep any styling added by the Sticky polyfill
       style += `position: ${this.element.style.position};`;
       style += `top: ${this.element.style.top};`;

addon/components/ember-tfoot/component.js

@@ -6,6 +6,29 @@ import { tagName } from '@ember-decorators/component';
 
 import layout from './template';
 
+/**
+  The table footer component. This component manages any footer rows which may
+  be attached to the table, and has the same API as EmberTBody. It does not
+  provide occlusion, because the number of footer rows is expected to be
+  relatively small.
+
+  ```hbs
+  <EmberTable as |t|>
+    <t.head @columns={{columns}} />
+    <t.body @rows={{rows}} />
+
+    <t.foot @rows={{footerRows}} as |f|>
+      <f.row>
+    </t.foot>
+  </EmberTable>
+  ```
+
+  @yield {object} f - the API object yielded by the table footer
+  @yield {Component} f.row - The table row component
+
+  @yield {object} f.rowValue - The value for the currently yielded row
+  @yield {object} f.rowMeta - The meta for the currently yielded row
+*/
 @tagName('tfoot')
 export default class EmberTFoot extends EmberTBody {
   layout = layout;

addon/components/ember-tfoot/template.hbs

@@ -15,7 +15,10 @@
   }}
     {{#if hasBlock}}
       {{yield (hash
-        api=api
+        rowValue=api.rowValue
+        rowMeta=api.rowMeta
+        cells=api.cells
+        rowSelectionMode=api.rowSelectionMode
 
         row=(component "ember-tr" api=api)
       )}}