Adds API references

omniscientjs · Jul 21, 2015 · c7fd624 · c7fd624
1 parent 1739a74
commit c7fd624
Show file tree

Hide file tree

Showing 4 changed files with 274 additions and 0 deletions.
diff --git a/api.md b/api.md
@@ -0,0 +1,151 @@
+
+### `decorator.ignore(fields, decoratee)`
+
+Decorate a component and define props fields that should be ignored by
+the should component update. This could be values of complex objects such as
+eventemitters for communicating throuch a channel with parents, callbacks,
+csps, etc.
+
+Require the decorator by doing:
+```js
+var ignore = require('omnipotent/decorator/ignore');
+// or
+var ignore = require('omnipotent').decorator.ignore;
+```
+
+### Examples:
+```js
+var struct = immstruct({
+  hero: 'Natasha Romanoff',
+  ignorable: 'Cain Marko'
+});
+
+var Title = component('View', ({hero, ignore}) =>
+  {hero.deref()} vs. {ignore.deref()});
+
+var IgnoredTitle = ignore('ignorable', Title);
+
+function render() {
+  React.render(
+    IgnoredTitle({ hero: struct.cursor('hero'), ignore: struct.cursor('ignorable') }),
+    document.getElementById('content')
+  );
+}
+
+render();
+struct.on('swap', render);
+
+// Will update
+struct.cursor().set('hero', 'Natalia Romanova');
+// Will not update
+struct.cursor().set('ignorable', 'Juggernaut');
+// Will update
+struct.cursor().set('hero', 'Black Widow');
+```
+
+
+### Parameters
+
+| param       | type         | description                         |
+| ----------- | ------------ | ----------------------------------- |
+| `fields`    | String,Array | - Property names to ignore on props |
+| `decoratee` | Component    | - Component to decorate             |
+
+
+
+**Returns** `Component`, React Component
+
+
+### `decorator.observer(structure, fields, decoratee)`
+
+The `observer` decorator is a very useful one if you need horizontal data
+dependencies. If you require one of your components to get injected data
+automatically and update everytime that data changes.
+
+Fields passed to observer should be defined as the following:
+```js
+{
+  namePassedAsProps: ['nested', 'key', 'path'],
+  anotherNamePassedAsProps: 'shallowKeyPath'
+}
+```
+
+Require the decorator by doing:
+
+```js
+var observer = require('omnipotent/decorator/observer');
+// or
+var observer = require('omnipotent').decorator.observer;
+```
+
+### Examples:
+```jsx
+var structure = immstruct({ hero { name: 'Natalia Romanova' } });
+
+var Title = component('View', ({hero}) => {name.deref()});
+
+var ObservedTitle = observer(structure, {
+  hero: ['hero', 'name'] // key path in structure
+}, Title);
+
+render(ObservedTitle({}));
+
+// Update structure and component
+structure.cursor('hero').set('name', 'Black Widow');
+
+// Also for things like async fetch
+fetch('./hero.json')
+  .then(r => r.json())
+  .then(d => structure.cursor().set('hero', Immutable.Map(d));
+```
+
+
+### Parameters
+
+| param       | type                                             | description                                       |
+| ----------- | ------------------------------------------------ | ------------------------------------------------- |
+| `structure` | ImmstructStructure                               | - Immstruct Structure to get references from      |
+| `fields`    | { name: <code>string</code>/<code>Array</code> } | - Object mapping of names and key paths to inject |
+| `decoratee` | Component                                        | - Component to decorate                           |
+
+
+
+**Returns** `Component`, React Component
+
+
+### `helper.jsxComponent(displayName, mixins, render)`
+
+Helper to create components that are always JSX components. Making it easier
+to use JSX by default.
+
+Require the helper by doing:
+
+```js
+var component = require('omnipotent/helper/jsx-component');
+// or
+var component = require('omnipotent').jsxComponent;
+```
+
+
+### Parameters
+
+| param         | type         | description                                                                                          |
+| ------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
+| `displayName` | String       | Component's display name. Used when debug()'ing and by React                                         |
+| `mixins`      | Array,Object | React mixins. Object literals with functions, or array of object literals with functions.            |
+| `render`      | Function     | Properties that do not trigger update when changed. Can be cursors, object and immutable structures  |
+
+
+### Properties
+
+| property                | type     | description                        |
+| ----------------------- | -------- | ---------------------------------- |
+| `shouldComponentUpdate` | Function | Get default shouldComponentUpdate  |
+
+
+
+**Returns** `Component`, React Component
+
+## Private members 
+
+
diff --git a/decorator/ignore.js b/decorator/ignore.js
@@ -4,6 +4,56 @@ var React = require('react');
 var component = require('omniscient');
 var shouldUpdate = require('omniscient/shouldupdate');
 
+/**
+ * Decorate a component and define props fields that should be ignored by
+ * the should component update. This could be values of complex objects such as
+ * eventemitters for communicating throuch a channel with parents, callbacks,
+ * csps, etc.
+ *
+ * Require the decorator by doing:
+ * ```js
+ * var ignore = require('omnipotent/decorator/ignore');
+ * // or
+ * var ignore = require('omnipotent').decorator.ignore;
+ * ```
+ *
+ * ### Examples:
+ * ```js
+ * var struct = immstruct({
+ *   hero: 'Natasha Romanoff',
+ *   ignorable: 'Cain Marko'
+ * });
+ *
+ * var Title = component('View', ({hero, ignore}) =>
+ *   <h1>{hero.deref()} vs. {ignore.deref()}</h1>);
+ *
+ * var IgnoredTitle = ignore('ignorable', Title);
+ *
+ * function render() {
+ *   React.render(
+ *     IgnoredTitle({ hero: struct.cursor('hero'), ignore: struct.cursor('ignorable') }),
+ *     document.getElementById('content')
+ *   );
+ * }
+ *
+ * render();
+ * struct.on('swap', render);
+ *
+ * // Will update
+ * struct.cursor().set('hero', 'Natalia Romanova');
+ * // Will not update
+ * struct.cursor().set('ignorable', 'Juggernaut');
+ * // Will update
+ * struct.cursor().set('hero', 'Black Widow');
+ * ```
+ *
+ * @param {String|Array} fields - Property names to ignore on props
+ * @param {Component} decoratee - Component to decorate
+ *
+ * @api public
+ * @module decorator.ignore
+ * @returns {Component} React Component
+ */
 module.exports = function (fields, Decoratee) {
   fields = arrify(fields);
   var isJSX = !Decoratee.jsx;

diff --git a/decorator/observer.js b/decorator/observer.js
@@ -4,6 +4,57 @@ var React = require('react');
 var component = require('omniscient');
 var assign = require('lodash.assign');
 
+
+/**
+ * The `observer` decorator is a very useful one if you need horizontal data
+ * dependencies. If you require one of your components to get injected data
+ * automatically and update everytime that data changes.
+ *
+ * Fields passed to observer should be defined as the following:
+ * ```js
+ * {
+ *   namePassedAsProps: ['nested', 'key', 'path'],
+ *   anotherNamePassedAsProps: 'shallowKeyPath'
+ * }
+ * ```
+ *
+ * Require the decorator by doing:
+ *
+ * ```js
+ * var observer = require('omnipotent/decorator/observer');
+ * // or
+ * var observer = require('omnipotent').decorator.observer;
+ * ```
+ *
+ * ### Examples:
+ * ```jsx
+ * var structure = immstruct({ hero { name: 'Natalia Romanova' } });
+ *
+ * var Title = component('View', ({hero}) => <h1>{name.deref()}</h1>);
+ *
+ * var ObservedTitle = observer(structure, {
+ *   hero: ['hero', 'name'] // key path in structure
+ * }, Title);
+ *
+ * render(ObservedTitle({}));
+ *
+ * // Update structure and component
+ * structure.cursor('hero').set('name', 'Black Widow');
+ *
+ * // Also for things like async fetch
+ * fetch('./hero.json')
+ *   .then(r => r.json())
+ *   .then(d => structure.cursor().set('hero', Immutable.Map(d));
+ * ```
+ *
+ * @param {ImmstructStructure} structure - Immstruct Structure to get references from
+ * @param {{ name : string|Array }} fields - Object mapping of names and key paths to inject
+ * @param {Component} decoratee - Component to decorate
+ *
+ * @api public
+ * @module decorator.observer
+ * @returns {Component} React Component
+ */
 module.exports = function observer (structure, fields, Decoratee) {
   var isJSX = !Decoratee.jsx;
   var unobservers = [];

diff --git a/helper/jsx-component.js b/helper/jsx-component.js
@@ -2,6 +2,28 @@
 
 var omniscient = require('omniscient');
 
+/**
+ * Helper to create components that are always JSX components. Making it easier
+ * to use JSX by default.
+ *
+ * Require the helper by doing:
+ *
+ * ```js
+ * var component = require('omnipotent/helper/jsx-component');
+ * // or
+ * var component = require('omnipotent').jsxComponent;
+ * ```
+ *
+ * @param {String} displayName Component's display name. Used when debug()'ing and by React
+ * @param {Array|Object} mixins React mixins. Object literals with functions, or array of object literals with functions.
+ * @param {Function} render Properties that do not trigger update when changed. Can be cursors, object and immutable structures
+ *
+ * @property {Function} shouldComponentUpdate Get default shouldComponentUpdate
+ *
+ * @api public
+ * @module helper.jsxComponent
+ * @returns {Component} React Component
+ */
 module.exorts = omniscient.withDefaults({
   jsx: true
 });