grainjs 1.0.1 → 1.1.0

package/lib/domComponent.ts

@@ -1,65 +1,5 @@
-/**
- * UI components that can be inserted into dom().
- *
- * Components are created and inserted using dom.create():
- *
- *    dom('div',
- *      dom.create(MyWidget, ...myArgs),        // Calls MyWidget.create(owner, ...myArgs)
- *      dom.create(createMyWidget, ...myArgs),  // Calls createMyWidget(owner, ...myArgs)
- *    )
- *
- * The first argument may be a function, which is called directly, or a class with a .create()
- * static method, in which case that's what gets called.
- *
- * In both cases, the call gets a first argument of `owner` followed by the rest of the arguments
- * to dom.create(). The `owner` is a MultiHolder that will own this component. This works
- * naturally with any class that derives from Disposable, since it then has a suitable static
- * create() method.
- *
- * Function-based components may use owner to easily handle disposal. For example:
- *
- *    dom.create(createMyWidget)
- *    function createMyWidget(owner) {
- *      const foo = Foo.create(owner);
- *      return dom('div', foo.getTitle());
- *    }
- *
- * The `owner` argument is the main benefit of dom.create(). Logically, the owner is the DOM where
- * the component is attached. When the parent DOM element is disposed, so is the component.
- *
- *    [Explanation] To understand why the syntax is such, consider a potential alternative such as:
- *
- *       dom('div', _insert_(new Comp1()), _insert_(new Comp2(...args)))
- *
- *    In both cases, the constructor for Comp1 runs before the constructor for Comp2. What happens
- *    when Comp2's constructor throws an exception? In the second case, nothing yet owns the
- *    created Comp1 component, and it will never get cleaned up. With dom.create(), the DOM
- *    gets ownership of Comp1 early enough and will dispose it.
- *
- * A function component may return DOM directly. A class component returns the class instance,
- * which must have a .buildDom() method which will be called right after the constructor to get
- * the DOM. Note that buildDom is only called once.
- *
- * A function component may also return an object with .buildDom(). So these are equivalent:
- *
- *    dom.create(MyWidget)
- *    dom.create((owner) => MyWidget.create(owner))
- *
- * Note that ownership should be handled using the `owner` argument. Don't do this:
- *
- *    // NON-EXAMPLE: Nothing will dispose the created object:
- *    // dom.create(() => new MyWidget());
- *
- * The returned DOM may includes Nodes, strings, and domComputed() values, as well as arrays of
- * any of these. In other words, any DomArg goes except DomMethods. All the DOM returned will be
- * disposed when the containing element is disposed, followed by the `owner` itself.
- */
 import {MultiHolder} from './dispose';
-import {domComputed, DomComputed} from './domComputed';
-import {autoDisposeElem} from './domDispose';
-
-export type DomContents = Node | string | DomComputed | void | null | undefined | IDomContentsArray;
-export interface IDomContentsArray extends Array<DomContents> {}
+import {domComputedOwned, DomContents} from './domComputed';
 
 export interface IDomComponent {
   buildDom(): DomContents;
@@ -78,23 +18,81 @@ export interface IDomCreateClass<Args extends any[]> {
 }
 export type IDomCreator<Args extends any[]> = IDomCreateFunc<Args> | IDomCreateClass<Args>;
 
-type DomCreatorArgs<T> =
+export type DomCreatorArgs<T> =
   T extends (owner: MultiHolder, ...args: infer P) => any ? P :
   (T extends new (...args: infer P) => any ? P : never);
 
+/**
+ * UI components that can be inserted into `dom()`.
+ *
+ * Components are created and inserted using `dom.create()`:
+ * ```ts
+ * dom('div',
+ *   dom.create(MyWidget, ...myArgs),        // Calls MyWidget.create(owner, ...myArgs)
+ *   dom.create(createMyWidget, ...myArgs),  // Calls createMyWidget(owner, ...myArgs)
+ * )
+ * ```
+ *
+ * The first argument may be a function, which is called directly, or a class with a `.create()`
+ * static method, in which case that's what gets called.
+ *
+ * In both cases, the call gets a first argument of `owner` followed by the rest of the arguments
+ * to `dom.create()`. The `owner` is a `MultiHolder` that will own this component. This works
+ * naturally with any class that derives from Disposable, since it then has a suitable static
+ * `create()` method.
+ *
+ * Function-based components may use owner to easily handle disposal. For example:
+ * ```ts
+ * dom.create(createMyWidget)
+ * function createMyWidget(owner) {
+ *   const foo = Foo.create(owner);
+ *   return dom('div', foo.getTitle());
+ * }
+ * ```
+ *
+ * The `owner` argument is the main benefit of `dom.create()`. Logically, the owner is the DOM where
+ * the component is attached. When the parent DOM element is disposed, so is the component.
+ *
+ * :::info Explanation
+ *
+ * To understand why the syntax is such, consider a potential alternative such as:
+ * ```ts
+ * dom('div', _insert_(new Comp1()), _insert_(new Comp2(...args)))
+ * ```
+ *
+ * In both cases, the constructor for Comp1 runs before the constructor for Comp2. What happens
+ * when Comp2's constructor throws an exception? In the second case, nothing yet owns the
+ * created Comp1 component, and it will never get cleaned up. With `dom.create()`, the DOM
+ * gets ownership of Comp1 early enough and will dispose it.
+ *
+ * :::
+ *
+ * A function component may return DOM directly. A class component returns the class instance,
+ * which must have a `.buildDom()` method which will be called right after the constructor to get
+ * the DOM. Note that buildDom is only called once.
+ *
+ * A function component may also return an object with `.buildDom()`. So these are equivalent:
+ * ```ts
+ * dom.create(MyWidget)
+ * dom.create((owner) => MyWidget.create(owner))
+ * ```
+ *
+ * Note that ownership should be handled using the `owner` argument. Don't do this:
+ * ```ts
+ * // NON-EXAMPLE: Nothing will dispose the created object:
+ * // dom.create(() => new MyWidget());
+ * ```
+ *
+ * The returned DOM may includes Nodes, strings, and `domComputed()` values, as well as arrays of
+ * any of these. In other words, any `DomArg` goes except `DomMethods`. All the DOM returned will be
+ * disposed when the containing element is disposed, followed by the `owner` itself.
+ */
 export function create<Fn extends IDomCreator<any[]>>(fn: Fn, ...args: DomCreatorArgs<Fn>): DomContents {
-  const [markerPre, markerPost, func] = domComputed(null, () => {
-    // Note that the callback to domComputed() is not called until the markers have been attached
-    // to the parent element. We attach the MultiHolder's disposal to markerPost the way
-    // domComputed() normally attaches its own bindings.
-    const owner = MultiHolder.create(null);
-    autoDisposeElem(markerPost, owner);
-
+  return domComputedOwned(null, (owner) => {
     const value: DomComponentReturn = ('create' in fn) ?
       (fn as IDomCreateClass<any[]>).create(owner, ...args) :
       (fn as IDomCreateFunc<any[]>)(owner, ...args);
     return (value && typeof value === 'object' && 'buildDom' in value) ?
       value.buildDom() : value;
   });
-  return [markerPre, markerPost, func];
 }

package/lib/domComputed.ts

@@ -1,5 +1,6 @@
 import {BindableValue, subscribeElem} from './binding';
-import {domDispose} from './domDispose';
+import {Holder, MultiHolder} from './dispose';
+import {autoDisposeElem, domDispose} from './domDispose';
 import {DomArg, DomMethod, frag} from './domImpl';
 
 // Use the browser globals in a way that allows replacing them with mocks in tests.
@@ -9,12 +10,16 @@ import {G} from './browserGlobals';
 // name for use in places where a DomComputed is suitable but a general DomArg is not.
 export type DomComputed = [Node, Node, DomMethod];
 
+export type DomContents = Node | string | DomComputed | void | null | undefined | IDomContentsArray;
+export interface IDomContentsArray extends Array<DomContents> {}
+
+
 /**
  * Replaces the content between nodeBefore and nodeAfter, which should be two siblings within the
  * same parent node. New content may be anything allowed as an argument to dom(), including null
  * to insert nothing. Runs disposers, if any, on all removed content.
  */
-export function replaceContent(nodeBefore: Node, nodeAfter: Node, content: DomArg): void {
+export function replaceContent(nodeBefore: Node, nodeAfter: Node, content: DomContents): void {
   const elem = nodeBefore.parentNode;
   if (elem) {
     let next;
@@ -39,37 +44,44 @@ export function replaceContent(nodeBefore: Node, nodeAfter: Node, content: DomAr
  * changes, previous content is disposed and removed, and new content added in its place.
  *
  * The following are roughly equivalent:
- *  (A) domComputed(nlinesObs, nlines => nlines > 1 ? dom('textarea') : dom('input'));
- *  (B) domComputed(use => use(nlinesObs) > 1 ? dom('textarea') : dom('input'));
- *  (C) domComputed(use => use(nlinesObs) > 1, isTall => isTall ? dom('textarea') : dom('input'));
+ * ```ts
+ * // (A)
+ * domComputed(nlinesObs, nlines => nlines > 1 ? dom('textarea') : dom('input'))
+ * // (B)
+ * domComputed(use => use(nlinesObs) > 1 ? dom('textarea') : dom('input'))
+ * // (C)
+ * domComputed(use => use(nlinesObs) > 1, isTall => isTall ? dom('textarea') : dom('input'))
+ * ```
  *
  * Here, (C) is best. Both (A) and (B) would rebuild DOM for any change in nlinesObs, but (C)
  * encapsulates meaningful changes in the observable, and only recreates DOM when necessary.
  *
  * Syntax (B), without the second argument, may be useful in cases of DOM depending on several
  * observables, e.g.
+ * ```ts
+ * domComputed(use => use(readonlyObs) ? dom('div') :
+ *     (use(nlinesObs) > 1 ? dom('textarea') : dom('input')))
+ * ```
  *
- *    domComputed(use => use(readonlyObs) ? dom('div') :
- *                          (use(nlinesObs) > 1 ? dom('textarea') : dom('input')));
- *
- * If the argument is not an observable, domComputed() may but should not be used. The following
+ * If the argument is not an observable, `domComputed()` may but should not be used. The following
  * are equivalent:
- *
- *    dom(..., domComputed(listValue, list => `Have ${list.length} items`), ...)
- *    dom(..., `Have ${listValue.length} items`, ...)
+ * ```ts
+ * dom(..., domComputed(listValue, list => `Have ${list.length} items`), ...);
+ * dom(..., `Have ${listValue.length} items`, ...);
+ * ```
  *
  * In this case, the latter is preferred as the clearly simpler one.
  *
- * @param valueObs: Observable or function for a computed.
- * @param contentFunc: Function called with the result of valueObs as the input, and
+ * @param valueObs - Observable or function for a computed.
+ * @param contentFunc - Function called with the result of valueObs as the input, and
  *    returning DOM as output. If omitted, defaults to the identity function.
  */
 // Note that DomMethod is excluded because it prevents typescript from inferring the type of
 // the first argument when it's a function (and it's not useful).
 export function domComputed(valueObs: BindableValue<Exclude<DomArg, DomMethod>>): DomComputed;
-export function domComputed<T>(valueObs: BindableValue<T>, contentFunc: (val: T) => DomArg): DomComputed;
+export function domComputed<T>(valueObs: BindableValue<T>, contentFunc: (val: T) => DomContents): DomComputed;
 export function domComputed<T>(
-  valueObs: BindableValue<T>, contentFunc: (val: T) => DomArg = identity as any,
+  valueObs: BindableValue<T>, contentFunc: (val: T) => DomContents = identity as any,
 ): DomComputed {
   const markerPre = G.document.createComment('a');
   const markerPost = G.document.createComment('b');
@@ -82,6 +94,23 @@ export function domComputed<T>(
   }];
 }
 
+/**
+ * Like domComputed(), but the callback gets an additional first argument, owner, which may be
+ * used to take ownership of objects created by the callback. These will be disposed before each
+ * new call to the callback, and when the containing DOM is disposed.
+ *
+ * `domComputedOwned(valueObs, (owner, value) => Editor.create(owner, value).renderSomething())`
+ */
+export function domComputedOwned<T>(
+  valueObs: BindableValue<T>, contentFunc: (owner: MultiHolder, val: T) => DomContents
+): DomComputed {
+  const holder = Holder.create(null);
+  const [markerPre, markerPost, func] = domComputed(valueObs,
+    (val: T) => contentFunc(MultiHolder.create(holder), val));
+  autoDisposeElem(markerPost, holder);
+  return [markerPre, markerPost, func];
+}
+
 function identity<T>(arg: T): T { return arg; }
 
 /**
@@ -92,20 +121,36 @@ function identity<T>(arg: T): T { return arg; }
  * Note that if the observable changes between different truthy values, contentFunc gets called
  * for each value, and previous content gets destroyed. To consider all truthy values the same,
  * use an observable that returns a proper boolean, e.g.
- *
+ * ```ts
  *    dom.maybe(use => Boolean(use(fooObs)), () => dom(...));
+ * ```
  *
  * As with domComputed(), dom.maybe() may but should not be used when the argument is not an
  * observable or function. The following are equivalent:
- *
+ * ```ts
  *    dom(..., dom.maybe(myValue, () => dom(...)));
  *    dom(..., myValue ? dom(...) : null);
+ * ```
  *
  * The latter is preferred for being simpler.
  *
- * @param boolValueObs: Observable or function for a computed.
- * @param contentFunc: Called with the result of boolValueObs when it is truthy. Should return DOM.
+ * @param boolValueObs - Observable or function for a computed.
+ * @param contentFunc - Called with the result of boolValueObs when it is truthy. Should return DOM.
  */
-export function maybe<T>(boolValueObs: BindableValue<T>, contentFunc: (val: NonNullable<T>) => DomArg): DomComputed {
+export function maybe<T>(boolValueObs: BindableValue<T>,
+    contentFunc: (val: NonNullable<T>) => DomContents): DomComputed {
   return domComputed(boolValueObs, (value) => value ? contentFunc(value!) : null);
 }
+
+/**
+ * Like maybe(), but the callback gets an additional first argument, owner, which may be used to
+ * take ownership of objects created by the callback. These will be disposed before each new call
+ * to the callback, and when the condition becomes false or the containing DOM gets disposed.
+ * ```ts
+ *    maybeOwned(showEditor, (owner) => Editor.create(owner).renderSomething())
+ * ```
+ */
+export function maybeOwned<T>(boolValueObs: BindableValue<T>,
+    contentFunc: (owner: MultiHolder, val: NonNullable<T>) => DomContents): DomComputed {
+  return domComputedOwned(boolValueObs, (owner, value) => value ? contentFunc(owner, value!) : null);
+}

package/lib/domDispose.ts

@@ -29,6 +29,7 @@ function _walkDom(elem: Node, visitFunc: INodeFunc): void {
 }
 
 // Internal helper to run all disposers for a single element.
+/** @internal */
 export function _disposeNode(node: Node): void {
   let disposer = _disposeMap.get(node);
   if (disposer) {
@@ -68,21 +69,22 @@ export const domDisposeHooks: IDomDisposeHooks = {
  * It is automatically called if one of the function arguments to dom() throws an exception during
  * element creation. This way any onDispose() handlers set on the unfinished element get called.
  *
- * @param {Node} node: The element to run disposers on.
+ * @param node - The element to run disposers on.
  */
 export function domDispose(node: Node): void {
   domDisposeHooks.disposeRecursive(node);
 }
 
 /**
- * Associate a disposerFunc with a DOM element. It will be called when the element is disposed
- * using domDispose() on it or any of its parents. If onDispose is called multiple times, all
- * disposerFuncs will be called in reverse order.
- * @param {Element} elem: The element to associate the disposer with.
- * @param {Function} disposerFunc(elem): Will be called when domDispose() is called on the
- *    element or its ancestor.
+ * Associate a disposer function with a DOM element. It will be called when the element is disposed
+ * using `domDispose()` on it or any of its parents. If called multiple times, all
+ * disposer functions will be called in reverse order.
+ *
  * Note that it is not necessary usually to dispose event listeners attached to an element (e.g.
- * with dom.on()) since their lifetime is naturally limited to the lifetime of the element.
+ * with `dom.on()`) since their lifetime is naturally limited to the lifetime of the element.
+ *
+ * @param elem - The element to associate the disposer with.
+ * @param disposerFunc - Will be called when `domDispose()` is called on the element or its ancestor.
  */
 export function onDisposeElem(elem: Node, disposerFunc: INodeFunc): void {
   const prevDisposer = _disposeMap.get(elem);
@@ -91,21 +93,36 @@ export function onDisposeElem(elem: Node, disposerFunc: INodeFunc): void {
     _disposeMap.set(disposerFunc, prevDisposer);
   }
 }
+
+/**
+ * Associate a disposer function with a DOM element. It will be called when the element is disposed
+ * using `domDispose()` on it or any of its parents. If called multiple times, all
+ * disposer functions will be called in reverse order.
+ *
+ * @param disposerFunc - Will be called when `domDispose()` is called on the element or its ancestor.
+ */
 export function onDispose(disposerFunc: INodeFunc) {
   return (elem: Node) => onDisposeElem(elem, disposerFunc);
 }
 
 /**
- * Make the given element own the disposable, and call its dispose method when domDispose() is
+ * Make the given element own the disposable, and call its dispose method when `domDispose()` is
  * called on the element or any of its parents.
- * @param {Element} elem: The element to own the disposable.
- * @param {Disposable} disposable: Anything with a .dispose() method.
+ * @param elem - The element to own the disposable.
+ * @param disposable - Anything with a `.dispose()` method.
  */
 export function autoDisposeElem(elem: Node, disposable: IDisposable|null) {
   if (disposable) {
     onDisposeElem(elem, () => disposable.dispose());
   }
 }
+
+/**
+ * Make the given element own the disposable, and call its dispose method when `domDispose()` is
+ * called on the element or any of its parents.
+ *
+ * @param disposable - Anything with a `.dispose()` method.
+ */
 export function autoDispose(disposable: IDisposable|null) {
   if (disposable) {
     return (elem: Node) => autoDisposeElem(elem, disposable);

package/lib/domForEach.ts

@@ -1,6 +1,6 @@
-import {replaceContent} from './domComputed';
+import {DomContents, replaceContent} from './domComputed';
 import {autoDisposeElem, domDispose} from './domDispose';
-import {DomMethod, frag} from './domImpl';
+import {frag} from './domImpl';
 import {computedArray, MaybeObsArray, ObsArray} from './obsArray';
 
 // Use the browser globals in a way that allows replacing them with mocks in tests.
@@ -18,19 +18,20 @@ import {G} from './browserGlobals';
  * If the created nodes are removed from their parent externally, forEach() will cope with it, but
  * will consider these elements as no longer owned, and will not run domDispose() on them.
  *
- * Note that itemCreateFunc() does not receive an index: an index would only be correct at the
- * time the item is created, and would not reflect further changes to the array.
+ * Note that itemCreateFunc() is called with an index as the second argument, but that index is
+ * only accurate at the time of the call, and will stop reflecting the true index if more items
+ * are inserted or removed before it.
  *
  * If you'd like to map the DOM node back to its source item, use dom.data() and dom.getData() in
  * itemCreateFunc().
  */
-export function forEach<T>(obsArray: MaybeObsArray<T>, itemCreateFunc: (item: T) => Node|null): DomMethod {
-  return (elem: Node) => {
-    const markerPre = G.document.createComment('a');
-    const markerPost = G.document.createComment('b');
-    elem.appendChild(markerPre);
-    elem.appendChild(markerPost);
-
+export function forEach<T>(
+  obsArray: MaybeObsArray<T>,
+  itemCreateFunc: (item: T, index: number) => Node|null
+): DomContents {
+  const markerPre = G.document.createComment('a');
+  const markerPost = G.document.createComment('b');
+  return [markerPre, markerPost, (elem: Node) => {
     if (Array.isArray(obsArray)) {
       replaceContent(markerPre, markerPost, obsArray.map(itemCreateFunc));
       return;
@@ -72,5 +73,5 @@ export function forEach<T>(obsArray: MaybeObsArray<T>, itemCreateFunc: (item: T)
       }
     });
     replaceContent(markerPre, markerPost, nodes.get());
-  };
+  }];
 }

package/lib/domImpl.ts

@@ -17,6 +17,10 @@ import {G} from './browserGlobals';
 export type DomMethod<T = Node> = (elem: T) => DomArg<T>|void;
 export type DomElementMethod = DomMethod<HTMLElement>;
 
+/**
+ * Object mapping attribute names to attribute values. When applied to a DOM element, null and
+ * undefined values are omitted, and booleans are either omitted or set to empty string.
+ */
 export interface IAttrObj {
   [attrName: string]: string|boolean|null|undefined;
 }
@@ -51,14 +55,14 @@ export type DomElementArg = DomArg<HTMLElement>;
  *   to add the ID 'foo', and zero or more .bar suffixes to add a CSS class 'bar'.
  *
  *   NOTE that better typings are available when a tag is used directly, e.g.
- *      dom('input', {id: 'foo'}, (elem) => ...) --> elem has type HTMLInputElement
- *      dom('input#foo',          (elem) => ...) --> elem has type HTMLElement
+ *      `dom('input', {id: 'foo'}, (elem) => ...)` -- elem has type HTMLInputElement
+ *      `dom('input#foo',          (elem) => ...)` -- elem has type HTMLElement
  *
  * The rest of the arguments are optional and may be:
  *
  *   Nodes - which become children of the created element;
  *   strings - which become text node children;
- *   objects - of the form {attr: val} to set additional attributes on the element;
+ *   objects - of the form `{attr: val}` to set additional attributes on the element;
  *   Arrays - which are flattened with each item processed recursively;
  *   functions - which are called with elem as the argument, for a chance to modify the
  *       element as it's being created. Return values are processed recursively.
@@ -93,11 +97,11 @@ function _createElementSvg(tag: string): SVGElement {
 /**
  * Internal helper to parse tagString, create an element using createFunc with the given tag, and
  * set its id and classes from the tagString.
- * @param {Funtion} createFunc(tag): Function that should create an element given a tag name.
+ * @param createFunc(tag) - Function that should create an element given a tag name.
  *    It is passed in to allow creating elements in different namespaces (e.g. plain HTML vs SVG).
- * @param {String} tagString: String of the form "tag#id.class1.class2" where id and classes are
+ * @param tagString - String of the form "tag#id.class1.class2" where id and classes are
  *    optional.
- * @return {Element} The result of createFunc(), possibly with id and class attributes also set.
+ * @returns {Element} The result of createFunc(), possibly with id and class attributes also set.
  */
 function _createFromTagString<E extends Element>(createFunc: (tag: string) => E, tagString: string): E {
   // We do careful hand-written parsing rather than use a regexp for speed. Using a regexp is
@@ -179,7 +183,26 @@ function _updateWithArg<T extends Node>(elem: T, arg: DomArg<T>): void {
 }
 
 /**
- * Creates a DocumentFragment processing arguments the same way as the dom() function.
+ * Creates a `DocumentFragment`, processing arguments in the same way as the `dom()` function.
+ *
+ * It's rarely needed since an array of `dom()` arguments is treated the same as a
+ * `DocumentFragment` in most cases.
+ *
+ * @example
+ * ```ts
+ * dom.frag(dom('span', 'Hello'), ' good ', dom('div', 'world'))
+ * ```
+ * creates document fragment with `<span>Hello</span> good <div>world</div>`.
+ *
+ * @example
+ * These two examples are equivalent:
+ * ```ts
+ * const world1 = () => dom.frag(' good ', dom('div', 'world'));
+ * dom('div', 'Hello', world1);
+ *
+ * const world2 = () => [' good ', dom('div', 'world')];
+ * dom('div', 'Hello', world2);
+ * ```
  */
 export function frag(...args: IDomArgs<DocumentFragment>): DocumentFragment {
   const elem = G.document.createDocumentFragment();