grainjs 1.0.1 → 1.1.0

package/lib/binding.ts

@@ -10,6 +10,13 @@ import {IKnockoutReadObservable, InferKoType} from './kowrap';
 import {BaseObservable} from './observable';
 import {subscribe, UseCBOwner} from './subscribe';
 
+/**
+ * Any of the value types that DOM methods know how to subscribe to: a plain value (like a
+ * string); an Observable (including a Computed); a knockout observable; a function.
+ *
+ * If a function, it's used to create a `Computed`, and will be called with a context function
+ * `use`, allowing it to depend on other observable values (see documentation for `Computed`).
+ */
 export type BindableValue<T> = BaseObservable<T> | ComputedCallback<T> | T | IKnockoutReadObservable<T>;
 
 export type ComputedCallback<T> = (use: UseCBOwner, ...args: any[]) => T;
@@ -64,8 +71,8 @@ export function subscribeBindable<T>(
 }
 
 /**
- * Subscribes a callback to valueObs (which may be a value, observable, or function) using
- * subscribe(), and disposes the subscription with the passed-in element.
+ * Subscribes a callback to `valueObs` (which may be a value, observable, or function) using
+ * `subscribeBindable()`, and ties the disposal of this subscription to the passed-in element.
  */
 export function subscribeElem<T>(elem: Node, valueObs: BindableValue<T>,
                                  callback: (newVal: T, oldVal?: T) => void): void {

package/lib/browserGlobals.ts

@@ -27,6 +27,8 @@ export interface IBrowserGlobals {
   window: typeof window;
 }
 
+export interface IBrowserGlobalsLax extends IBrowserGlobals {window: any};
+
 function _updateGlobals(dest: IBrowserGlobals, source: IBrowserGlobals): void {
   dest.DocumentFragment  = source.DocumentFragment;
   dest.Element           = source.Element;
@@ -48,7 +50,7 @@ const _globalsStack: IBrowserGlobals[] = [initial];
 /**
  * Replace globals with those from the given object. Use popGlobals() to restore previous values.
  */
-export function pushGlobals(globals: IBrowserGlobals): void {
+export function pushGlobals(globals: IBrowserGlobalsLax): void {
   _globalsStack.push(globals);
   _updateGlobals(G, globals);
 }

package/lib/computed.ts

@@ -1,51 +1,68 @@
+import {DepItem} from './_computed_queue';
+import {IDisposableOwnerT, setDisposeOwner} from './dispose';
+import {BaseObservable as Obs, Observable} from './observable';
+import {ISubscribable, Subscription, UseCBOwner as UseCB} from './subscribe';
+
+function _noWrite(): never {
+  throw new Error("Can't write to non-writable computed");
+}
+
+/** @internal */
+type Owner<T> = IDisposableOwnerT<Computed<T>>|null;
+
 /**
- * computed.js implements a computed observable, whose value depends on other observables and gets
+ * `Computed` implements a computed observable, whose value depends on other observables and gets
  * recalculated automatically when they change.
  *
- * E.g. if we have some existing observables (which may themselves be instances of `computed`),
+ * E.g. if we have some existing observables (which may themselves be instances of `Computed`),
  * we can create a computed that subscribes to them explicitly:
- *  let obs1 = observable(5), obs2 = observable(12);
- *  let computed1 = computed(obs1, obs2, (use, v1, v2) => v1 + v2);
+ * ```ts
+ * const obs1 = Observable.create(null, 5), obs2 = Observable.create(null, 12);
+ * const computed1 = Computed.create(null, obs1, obs2, (use, v1, v2) => v1 + v2);
+ * ```
  *
  * or implicitly by using `use(obs)` function:
- *  let computed2 = computed(use => use(obs1) + use(obs2));
+ * ```ts
+ * const computed2 = Computed.create(null, use => use(obs1) + use(obs2));
+ * ```
  *
- * In either case, computed1.get() and computed2.get() will have the value 17. If obs1 or obs2 is
- * changed, computed1 and computed2 will get recomputed automatically.
+ * In either case, `computed1.get()` and `computed2.get()` will have the value 17. If `obs1` or
+ * `obs2` is changed, `computed1` and `computed2` will get recomputed automatically.
  *
  * Creating a computed allows any number of dependencies to be specified explicitly, and their
- * values will be passed to the read() callback. These may be combined with automatic dependencies
- * detected using use(). Note that constructor dependencies have less overhead.
- *
- *  let val = computed(...deps, ((use, ...depValues) => READ_CALLBACK));
+ * values will be passed to the `read()` callback. These may be combined with automatic dependencies
+ * detected using `use()`. Note that constructor dependencies have less overhead.
+ * ```ts
+ * const val = Computed.create(null, ...deps, ((use, ...depValues) => READ_CALLBACK));
+ * ```
  *
  * You may specify a `write` callback by calling `onWrite(WRITE_CALLBACK)`, which will be called
- * whenever set() is called on the computed by its user. If a `write` bacllback is not specified,
+ * whenever `set()` is called on the computed by its user. If a `write` bacllback is not specified,
  * calling `set` on a computed observable will throw an exception.
  *
- * Note that pureComputed.js offers a variation of computed() with the same interface, but which
+ * Note that `PureComputed` offers a variation of `Computed` with the same interface, but which
  * stays unsubscribed from dependencies while it itself has no subscribers.
  *
  * A computed may be used with a disposable value using `use.owner` as the value's owner. E.g.
- *    let val = computed((use) => Foo.create(use.owner, use(a), use(b)));
+ * ```ts
+ * const val = Computed.create(null, ((use) => Foo.create(use.owner, use(a), use(b)));
+ * ```
  *
- * When the computed() is re-evaluated, and when it itself is disposed, it disposes the previously
- * owned value. Note that only the pattern above works, i.e. use.owner may only be used to take
+ * When the `Computed` is re-evaluated, and when it itself is disposed, it disposes the previously
+ * owned value. Note that only the pattern above works, i.e. `use.owner` may only be used to take
  * ownership of the same disposable that the callback returns.
  */
-
-import {DepItem} from './_computed_queue';
-import {IDisposableOwnerT, setDisposeOwner} from './dispose';
-import {BaseObservable as Obs, Observable} from './observable';
-import {ISubscribable, Subscription, UseCBOwner as UseCB} from './subscribe';
-
-function _noWrite(): never {
-  throw new Error("Can't write to non-writable computed");
-}
-
-type Owner<T> = IDisposableOwnerT<Computed<T>>|null;
-
 export class Computed<T> extends Observable<T> {
+  /**
+   * Creates a new Computed, owned by the given owner.
+   * @param owner - Object to own this Computed, or null to handle disposal manually.
+   * @param observables - Zero or more observables on which this computes depends. The callback
+   *        will get called when any of these changes.
+   * @param callback - Read callback that will be called with `(use, ...values)`,
+   *    i.e. the `use` function and values for all of the `...observables`. The callback is called
+   *    immediately and whenever any dependency changes.
+   * @returns The newly created `Computed` observable.
+   */
   // Still need repetitive declarations to support varargs that are not the final argument.
   public static create<T>(
     owner: Owner<T>, cb: (use: UseCB) => T): Computed<T>;
@@ -64,17 +81,6 @@ export class Computed<T> extends Observable<T> {
   public static create<T, A, B, C, D, E>(
     owner: Owner<T>, a: Obs<A>, b: Obs<B>, c: Obs<C>, d: Obs<D>, e: Obs<E>,
     cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): Computed<T>;
-
-  /**
-   * Creates a new Computed, owned by the given owner.
-   * @param owner: Object to own this Computed, or null to handle disposal manually.
-   * @param ...observables: Zero or more observables on which this computes depends. The callback
-   *        will get called when any of these changes.
-   * @param callback: Read callback that will be called with (use, ...values),
-   *    i.e. the `use` function and values for all of the ...observables. The callback is called
-   *    immediately and whenever any dependency changes.
-   * @returns {Computed} The newly created computed observable.
-   */
   public static create<T>(owner: IDisposableOwnerT<Computed<T>>|null, ...args: any[]): Computed<T> {
     const readCb = args.pop();
     return setDisposeOwner(owner, new Computed<T>(readCb, args));
@@ -84,9 +90,7 @@ export class Computed<T> extends Observable<T> {
   private _write: (value: T) => void;
   private _sub: Subscription;
 
-  /**
-   * Internal constructor for a Computed observable. You should use computed() function instead.
-   */
+  // Internal constructor for a Computed observable. You should use computed() function instead.
   constructor(callback: (use: UseCB, ...args: any[]) => T, dependencies: ISubscribable[]) {
     // At initialization we force an undefined value even though it's not of type T: it gets set
     // to a proper value during the creation of new Subscription, which calls this._read.
@@ -98,6 +102,7 @@ export class Computed<T> extends Observable<T> {
 
   /**
    * Used by subscriptions to keep track of dependencies.
+   * @internal
    */
   public _getDepItem(): DepItem {
     return this._sub._getDepItem();
@@ -106,7 +111,7 @@ export class Computed<T> extends Observable<T> {
   /**
    * "Sets" the value of the computed by calling the write() callback if one was provided in the
    * constructor. Throws an error if there was no such callback (not a "writable" computed).
-   * @param {Object} value: The value to pass to the write() callback.
+   * @param value - The value to pass to the write() callback.
    */
   public set(value: T): void { this._write(value); }
 
@@ -133,9 +138,14 @@ export class Computed<T> extends Observable<T> {
 }
 
 /**
- * This is the type-checking interface for computed(), which allows TypeScript to do helpful
- * type-checking when using it. We can only support a fixed number of argumnets (explicit
- * dependencies), but 5 should almost always be enough.
+ * Creates a new Computed.
+ * @param observables - The initial params, of which there may be zero or more, are
+ *    observables on which this computed depends. When any of them change, the `read()` callback
+ *    will be called with the values of these observables as arguments.
+ * @param readCallback - Read callback that will be called with `(use, ...values)`,
+ *    i.e. the `use` function and values for all of the `...observables`. The callback is called
+ *    immediately and whenever any dependency changes.
+ * @returns The newly created `Computed` observable.
  */
 export function computed<T>(cb: (use: UseCB) => T): Computed<T>;
 
@@ -159,16 +169,6 @@ export function computed<T, A, B, C, D, E>(
   a: Obs<A>, b: Obs<B>, c: Obs<C>, d: Obs<D>, e: Obs<E>,
   cb: (use: UseCB, a: A, b: B, c: C, d: D, e: E) => T): Computed<T>;
 
-/**
- * Creates a new Computed.
- * @param {Observable} ...observables: The initial params, of which there may be zero or more, are
- *    observables on which this computed depends. When any of them change, the read() callback
- *    will be called with the values of these observables as arguments.
- * @param {Function} readCallback: Read callback that will be called with (use, ...values),
- *    i.e. the `use` function and values for all of the ...observables. The callback is called
- *    immediately and whenever any dependency changes.
- * @returns {Computed} The newly created computed observable.
- */
 export function computed(...args: any[]): Computed<any> {
   const readCb = args.pop();
   return new Computed<any>(readCb, args);

package/lib/dispose.ts

@@ -1,75 +1,3 @@
-/**
- * dispose.js provides tools to objects that needs to dispose resources, such as destroy DOM, and
- * unsubscribe from events. The motivation with examples is presented here:
- *
- *    https://phab.getgrist.com/w/disposal/
- *
- * Disposable is a class for components that need cleanup (e.g. maintain DOM, listen to events,
- * subscribe to anything). It provides a .dispose() method that should be called to destroy the
- * component, and .onDispose()/.autoDispose() methods that the component should use to take
- * responsibility for other pieces that require cleanup.
- *
- * To define a disposable class:
- *    class Foo extends Disposable { ... }
- *
- * To create Foo:
- *    const foo = Foo.create(owner, ...args);
- * This is better than `new Foo` for two reasons:
- *    1. If Foo's constructor throws an exception, any disposals registered in that constructor
- *       before the exception are honored.
- *    2. It ensures you specify the owner of the new instance (but you can use null to skip it).
- *
- * In Foo's constructor (or rarely methods), take ownership of other Disposable objects:
- *    this.bar = Bar.create(this, ...);
- *
- * For objects that are not instances of Disposable but have a .dispose() methods, use:
- *    this.bar = this.autoDispose(createSomethingDisposable());
- *
- * To call a function on disposal (e.g. to add custom disposal logic):
- *    this.onDispose(() => this.myUnsubscribeAllMethod());
- *    this.onDispose(this.myUnsubscribeAllMethod, this);    // slightly more efficient
- *
- * To mark this object to be wiped out on disposal (i.e. set all properties to null):
- *    this.wipeOnDispose();
- * See the documentation of that method for more info.
- *
- * To dispose Foo directly:
- *    foo.dispose();
- * To determine if an object has already been disposed:
- *    foo.isDisposed()
- *
- * If you need to replace an owned object, or release, or dispose it early, use a Holder:
- *    this._holder = Holder.create(this);
- *    Bar.create(this._holder, 1);      // creates new Bar(1)
- *    Bar.create(this._holder, 2);      // creates new Bar(2) and disposes previous object
- *    this._holder.clear();             // disposes contained object
- *    this._holder.release();           // releases contained object
- *
- * If you need a container for multiple objects and dispose them all together, use a MultiHolder:
- *    this._mholder = MultiHolder.create(null);
- *    Bar.create(this._mholder, 1);     // create new Bar(1)
- *    Bar.create(this._mholder, 2);     // create new Bar(2)
- *    this._mholder.dispose();          // disposes both objects
- *
- * If creating your own class with a dispose() method, do NOT throw exceptions from dispose().
- * These cannot be handled properly in all cases. Read here about the same issue in C++:
- *    http://bin-login.name/ftp/pub/docs/programming_languages/cpp/cffective_cpp/MAGAZINE/SU_FRAME.HTM#destruct
- *
- * Using a parametrized (generic) class as a Disposable is tricky. E.g.
- *    class Bar<T> extends Disposable { ... }
- *    // Bar<T>.create(...)   <-- doesn't work
- *    // Bar.create<T>(...)   <-- doesn't work
- *    // Bar.create(...)      <-- works, but with {} for Bar's type parameters
- *
- * The solution is to expose the constructor type using a helper method:
- *    class Bar<T> extends Disposable {
- *      // Note the tuple below which must match the constructor parameters of Bar<U>.
- *      public static ctor<U>(): IDisposableCtor<Bar<U>, [U, boolean]> { return this; }
- *      constructor(a: T, b: boolean) { ... }
- *    }
- *    Bar.ctor<T>().create(...)   // <-- works, creates Bar<T>, and does type-checking!
- */
-
 import {LLink} from './emit';
 
 /**
@@ -80,7 +8,7 @@ export interface IDisposable {
 }
 
 /**
- * Anything with .autoDispose() can be the owner of a disposable object. This is a type-specific
+ * Anything with `.autoDispose()` can be the owner of a disposable object. This is a type-specific
  * class that can only own a disposable object of type T.
  */
 export interface IDisposableOwnerT<T extends IDisposable> {
@@ -114,16 +42,87 @@ export interface IDisposableCtor<Derived, CtorArgs extends any[]> {
 }
 
 /**
- * Base class for disposable objects that can own other objects. See the module documentation.
+ * Base class for disposable objects that can own other objects.
+ *
+ * For background and motivation, see [Disposables](/dispose).
+ *
+ * `Disposable` is a class for components that need cleanup (e.g. maintain DOM, listen to events,
+ * subscribe to anything). It provides a `.dispose()` method that should be called to destroy the
+ * component, and `.onDispose()` / `.autoDispose()` methods that the component should use to take
+ * responsibility for other pieces that require cleanup.
+ *
+ * To define a disposable class:
+ * ```ts
+ * class Foo extends Disposable { ... }
+ * ```
+ *
+ * To create `Foo`:
+ * ```ts
+ * const foo = Foo.create(owner, ...args);
+ * ```
+ * This is better than `new Foo` for two reasons:
+ *    1. If `Foo`'s constructor throws an exception, any disposals registered in that constructor
+ *       before the exception are honored.
+ *    2. It ensures you specify the owner of the new instance (but you can use null to skip it).
+ *
+ * In `Foo`'s constructor (or rarely methods), take ownership of other Disposable objects:
+ * ```ts
+ * this.bar = Bar.create(this, ...);
+ * ```
+ *
+ * For objects that are not instances of Disposable but have a .dispose() methods, use:
+ * ```ts
+ * this.bar = this.autoDispose(createSomethingDisposable());
+ * ```
+ *
+ * To call a function on disposal (e.g. to add custom disposal logic):
+ * ```ts
+ * this.onDispose(() => this.myUnsubscribeAllMethod());
+ * this.onDispose(this.myUnsubscribeAllMethod, this);
+ * ```
+ *
+ * To mark this object to be wiped out on disposal (i.e. set all properties to null):
+ * ```ts
+ * this.wipeOnDispose();
+ * ```
+ * See the documentation of that method for more info.
+ *
+ * To dispose Foo directly: `foo.dispose()`.
+ *
+ * To determine if an object has already been disposed: `foo.isDisposed()`.
+ *
+ * If you need to replace an owned object, or release, or dispose it early, use a
+ * [`Holder`](#Holder) or [`MultiHolder`](#MultiHolder).
+ *
+ * If creating your own class with a `dispose()` method, do NOT throw exceptions from `dispose()`.
+ * These cannot be handled properly in all cases.
+ *
+ * Using a parametrized (generic) class as a Disposable is tricky. E.g.
+ * ```ts
+ * class Bar<T> extends Disposable { ... }
+ * // Bar<T>.create(...)   <-- doesn't work
+ * // Bar.create<T>(...)   <-- doesn't work
+ * // Bar.create(...)      <-- works, but with {} for Bar's type parameters
+ * ```
+ *
+ * The solution is to expose the constructor type using a helper method:
+ * ```ts
+ * class Bar<T> extends Disposable {
+ *   // Note the tuple below which must match the constructor parameters of Bar<U>.
+ *   public static ctor<U>(): IDisposableCtor<Bar<U>, [U, boolean]> { return this; }
+ *   constructor(a: T, b: boolean) { ... }
+ * }
+ * Bar.ctor<T>().create(...)   // <-- works, creates Bar<T>, and does type-checking!
+ * ```
  */
 export abstract class Disposable implements IDisposable, IDisposableOwner {
   /**
    * Create Disposable instances using `Class.create(owner, ...)` rather than `new Class(...)`.
    *
    * This reminds you to provide an owner, and ensures that if the constructor throws an
-   * exception, dispose() gets called to clean up the partially-constructed object.
+   * exception, `dispose()` gets called to clean up the partially-constructed object.
    *
-   * Owner may be null if intend to ensure disposal some other way.
+   * Owner may be `null` if you intend to ensure disposal some other way.
    */
   public static create<T extends new (...args: any[]) => any>(
     this: T, owner: IDisposableOwnerT<InstanceType<T>>|null, ...args: ConstructorParameters<T>): InstanceType<T> {
@@ -161,14 +160,14 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
     _defaultDisposableOwner = _noopOwner;
   }
 
-  /** Take ownership of obj, and dispose it when this.dispose() is called. */
+  /** Take ownership of `obj`, and dispose it when `this.dispose()` is called. */
   public autoDispose<T extends IDisposable>(obj: T): T {
     this.onDispose(obj.dispose, obj);
     return obj;
   }
 
-  /** Call the given callback when this.dispose() is called. */
-  public onDispose<T>(callback: (this: T) => void, context?: T): DisposeListener {
+  /** Call the given callback when `this.dispose()` is called. */
+  public onDispose<T>(callback: (this: T) => void, context?: T): IDisposable {
     return this._disposalList.addListener(callback, context);
   }
 
@@ -177,10 +176,13 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
    * recommended to call this early in the constructor.
    *
    * This makes disposal more costly, but has certain benefits:
+   *
    * - If anything still refers to the object and uses it, we'll get an early error, rather than
    *   silently keep going, potentially doing useless work (or worse) and wasting resources.
+   *
    * - If anything still refers to the object (even without using it), the fields of the object
    *   can still be garbage-collected.
+   *
    * - If there are circular references involving this object, they get broken, making the job
    *   easier for the garbage collector.
    *
@@ -199,7 +201,7 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
   }
 
   /**
-   * Clean up `this` by disposing all owned objects, and calling onDispose() callbacks, in reverse
+   * Clean up `this` by disposing all owned objects, and calling `onDispose()` callbacks, in reverse
    * order to that in which they were added.
    */
   public dispose(): void {
@@ -229,19 +231,33 @@ export abstract class Disposable implements IDisposable, IDisposableOwner {
 
 /**
  * Holder keeps a single disposable object. If given responsibility for another object using
- * holder.autoDispose() or Foo.create(holder, ...), it automatically disposes the currently held
+ * `holder.autoDispose()` or `Foo.create(holder, ...)`, it automatically disposes the currently held
  * object. It also disposes it when the holder itself is disposed.
  *
- * If the object is an instance of Disposable, the holder will also notice when the object gets
+ * If the object is an instance of `Disposable`, the holder will also notice when the object gets
  * disposed from outside of it, in which case the holder will become empty again.
+ *
+ * If you need a container for multiple objects and dispose them all together, use a `MultiHolder`:
+ *
+ * :::info Example
+ * ```ts
+ * this._holder = Holder.create(this);
+ * Bar.create(this._holder, 1);      // creates new Bar(1), assuming it's a Disposable
+ * Bar.create(this._holder, 2);      // creates new Bar(2) and disposes previous object
+ * this._holder.clear();             // disposes contained object
+ * this._holder.release();           // releases contained object
+ * ```
+ * :::
  */
 export class Holder<T extends IDisposable> implements IDisposable, IDisposableOwner {
+  /** `Holder.create(owner)` creates a new `Holder`. */
   public static create<T extends IDisposable>(owner: IDisposableOwnerT<Holder<T>>|null): Holder<T> {
     return setDisposeOwner(owner, new Holder<T>());
   }
 
+  /** @internal */
   protected _owned: T|null = null;
-  private _disposalListener: DisposeListener|undefined = undefined;
+  private _disposalListener: IDisposable|undefined = undefined;
 
   /** Take ownership of a new object, disposing the previously held one. */
   public autoDispose(obj: T): T {
@@ -296,9 +312,18 @@ export class Holder<T extends IDisposable> implements IDisposable, IDisposableOw
 }
 
 /**
- * MultiHolder keeps multiple disposable object. It disposes all held object when the holder
- * itself is disposed. It's actually nothing more than the Disposable base class itself, just
+ * `MultiHolder` keeps multiple disposable objects. It disposes all held object when the holder
+ * itself is disposed. It's actually nothing more than the `Disposable` base class itself, just
  * exposed with a clearer name that describes its purpose.
+ *
+ * :::info Example
+ * ```ts
+ * this._mholder = MultiHolder.create(null);
+ * Bar.create(this._mholder, 1);     // create new Bar(1)
+ * Bar.create(this._mholder, 2);     // create new Bar(2)
+ * this._mholder.dispose();          // disposes both objects
+ * ```
+ * :::
  */
 export class MultiHolder extends Disposable {}
 

package/lib/dom.ts

@@ -1,22 +1,3 @@
-/**
- * dom.js provides a way to build a DOM tree easily.
- *
- * E.g.
- *  import {dom} from 'grainjs';
- *  dom('a#link.c1.c2', {'href': url}, 'Hello ', dom('span', 'world'));
- *    creates Node <a id="link" class="c1 c2" href={{url}}Hello <span>world</span></a>.
- *
- *  dom.frag(dom('span', 'Hello'), ['blah', dom('div', 'world')])
- *    creates document fragment with <span>Hello</span>blah<div>world</div>.
- *
- * DOM can also be created and modified inline during creation:
- *  dom('a#id.c1',
- *      dom.cls('c2'), dom.attr('href', url),
- *      dom.text('Hello '), dom('span', dom.text('world')))
- *    creates Node <a id="link" class="c1 c2" href={{url}}Hello <span>world</span></a>,
- *    identical to the first example above.
- */
-
 // We keep various dom-related functions organized in private modules, but they are exposed here.
 export * from './domImpl';
 export * from './domComponent';
@@ -37,6 +18,44 @@ import * as domevent from './domevent';
 
 import {dom as _dom, IDomArgs, TagElem, TagName} from './domImpl';
 
+/**
+ * `dom()` provides a way to build a DOM tree easily.
+ *
+ * The first argument is a string consisting of a lowercase tag name (e.g. `"div"`), with optional
+ * `"#foo"` suffix to add the ID `'foo'`, and zero or more `".bar"` suffixes to add a CSS class
+ * `'bar'`.
+ *
+ * The rest of the arguments are optional and may be any number, of these types:
+ *
+ * @param Nodes - become children of the created element
+ * @param strings - become text node children
+ * @param objects - Literal objects to set string attributes on the element.
+ *    E.g. `{title: "foo"}`.
+ * @param null - The values `null` and `undefined` values are ignored completely.
+ * @param Arrays - flattened with each item processed recursively
+ * @param functions - called with the element being built as the argument, for a chance to modify
+ *    the element as it's being created. Return values are processed recursively.
+ * @param functions - "dom methods" are a expressions such as `dom.attr('href', url)` or
+ *    `dom.hide(obs)`, which are special cases of the "functions" category.
+ *
+ * @example
+ * ```ts
+ * import {dom} from 'grainjs';
+ * dom('a', {href: url, className: 'myclass'}, 'Hello ', dom('strong', 'world'));
+ * ```
+ * creates HTML element `<a href={{url}} class="myclass">Hello <strong>world</strong></a>`.
+ *
+ * @example
+ * Here's an example equivalent to the one above, using dom methods `dom.cls`, `dom.attr`,
+ * `dom.text`. In reality, these methods are useful with observable values rather than constant
+ * strings.
+ * ```ts
+ *  dom('a', dom.attr('href', url), dom.cls('myclass'),
+ *      dom.text('Hello '), dom('strong', dom.text('world')));
+ * ```
+ *
+ * @see [DOM & Observables](/basics).
+ */
 // We just want to re-export _domImpl.dom, but to allow adding methods to it in a typesafe way,
 // TypeScript wants us to declare a real function in the same file.
 export function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagElem<Tag>>): TagElem<Tag> {
@@ -44,7 +63,7 @@ export function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagEl
 }
 
 // Additionally export all methods as properties of dom() function.
-export namespace dom {      // tslint:disable-line:no-namespace
+export namespace dom {      // eslint-disable-line @typescript-eslint/no-namespace
   export const svg             = _domImpl.svg;
   export const frag            = _domImpl.frag;
   export const update          = _domImpl.update;
@@ -81,7 +100,9 @@ export namespace dom {      // tslint:disable-line:no-namespace
   export const getData         = _domMethods.getData;
   export const replaceContent  = _domComputed.replaceContent;
   export const domComputed     = _domComputed.domComputed;
+  export const domComputedOwned = _domComputed.domComputedOwned;
   export const maybe           = _domComputed.maybe;
+  export const maybeOwned      = _domComputed.maybeOwned;
 
   export const forEach         = _domForEach.forEach;