grainjs 0.1.0 → 1.0.2

package/lib/domComputed.ts

@@ -0,0 +1,146 @@
+import {BindableValue, subscribeElem} from './binding';
+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.
+import {G} from './browserGlobals';
+
+// The type returned by domComputed(). It's actually an example of DomArg, but is given its own
+// 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: DomContents): void {
+  const elem = nodeBefore.parentNode;
+  if (elem) {
+    let next;
+    for (let n = nodeBefore.nextSibling; n && n !== nodeAfter; n = next) {
+      next = n.nextSibling;
+      domDispose(n);
+      elem.removeChild(n);
+    }
+    if (content) {
+      elem.insertBefore(content instanceof G.Node ? content : frag(content), nodeAfter);
+    }
+  }
+}
+
+/**
+ * Appends dynamic DOM content to an element. The value may be an observable or function (from
+ * which a computed is created), whose value will be passed to `contentFunc` which should return
+ * DOM content. If the contentFunc is omitted, it defaults to identity, i.e. it's OK for the
+ * observable or function to return DOM directly.
+ *
+ * The DOM content returned may be an element, string, array, or null. Whenever the observable
+ * 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'));
+ *
+ * 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.
+ *
+ *    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
+ * are equivalent:
+ *
+ *    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
+ *    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) => DomContents): DomComputed;
+export function domComputed<T>(
+  valueObs: BindableValue<T>, contentFunc: (val: T) => DomContents = identity as any,
+): DomComputed {
+  const markerPre = G.document.createComment('a');
+  const markerPost = G.document.createComment('b');
+
+  // Function is added after markerPre and markerPost, so that it runs once they have already been
+  // attached to elem (the parent element).
+  return [markerPre, markerPost, (elem: Node) => {
+    subscribeElem(markerPost, valueObs,
+      (value) => replaceContent(markerPre, markerPost, contentFunc(value)));
+  }];
+}
+
+/**
+ * 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; }
+
+/**
+ * Conditionally appends DOM to an element. The value may be an observable or function (from which
+ * a computed is created), whose value -- if truthy -- will be passed to `contentFunc` which
+ * should return DOM content. If the value is falsy, DOM content is removed.
+ *
+ * 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.
+ *
+ *    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:
+ *
+ *    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.
+ */
+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.
+ *
+ *    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 → domDispose.ts}

@@ -18,7 +18,7 @@ export type INodeFunc = (node: Node) => void;
 // Internal helper to walk the DOM tree, calling visitFunc(elem) on all descendants of elem.
 // Descendants are processed first.
 function _walkDom(elem: Node, visitFunc: INodeFunc): void {
-  let c = elem.firstChild;
+  let c: Node|null = elem.firstChild;
   while (c) {
     // Note: this might be better done using an explicit stack, but in practice DOM trees aren't
     // so deep as to cause problems.
@@ -29,13 +29,13 @@ function _walkDom(elem: Node, visitFunc: INodeFunc): void {
 }
 
 // Internal helper to run all disposers for a single element.
-function _disposeElem(elem: Node): void {
-  let disposer = _disposeMap.get(elem);
+export function _disposeNode(node: Node): void {
+  let disposer = _disposeMap.get(node);
   if (disposer) {
-    let key: Node|INodeFunc = elem;
+    let key: Node|INodeFunc = node;
     do {
       _disposeMap.delete(key);
-      disposer(elem);
+      disposer(node);
       // Find the next disposer; these are chained when there are multiple.
       key = disposer;
       disposer = _disposeMap.get(key);
@@ -43,6 +43,24 @@ function _disposeElem(elem: Node): void {
   }
 }
 
+function _disposeNodeRecursive(node: Node): void {
+  _walkDom(node, domDisposeHooks.disposeNode);
+}
+
+export interface IDomDisposeHooks {
+  disposeRecursive: (node: Node) => void;
+  disposeNode: (node: Node) => void;
+}
+
+/**
+ * Support for extending dom disposal. This is very low-level, and needs utmost care. Any
+ * disposers set should take care of calling the original versions of the disposers.
+ */
+export const domDisposeHooks: IDomDisposeHooks = {
+  disposeNode: _disposeNode,
+  disposeRecursive: _disposeNodeRecursive,
+};
+
 /**
  * Run disposers associated with any descendant of elem or with elem itself. Disposers get
  * associated with elements using dom.onDispose(). Descendants are processed first.
@@ -50,10 +68,10 @@ function _disposeElem(elem: Node): void {
  * 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 {Element} elem: The element to run disposers on.
+ * @param {Node} node: The element to run disposers on.
  */
-export function domDispose(elem: Node): void {
-  _walkDom(elem, _disposeElem);
+export function domDispose(node: Node): void {
+  domDisposeHooks.disposeRecursive(node);
 }
 
 /**

package/lib/{_domForEach.ts → domForEach.ts}

@@ -1,6 +1,6 @@
-import {domDispose} from './_domDispose';
-import {DomMethod, frag} from './_domImpl';
-import {replaceContent} from './_domMethods';
+import {DomContents, replaceContent} from './domComputed';
+import {autoDisposeElem, domDispose} from './domDispose';
+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.
@@ -24,19 +24,20 @@ import {G} from './browserGlobals';
  * 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) => 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;
     }
 
     const nodes: ObsArray<Node|null> = computedArray(obsArray, itemCreateFunc);
+
+    // Be sure to dispose the newly-created array when the DOM it's associated with is gone.
+    autoDisposeElem(markerPost, nodes);
+
     nodes.addListener((newArr: Array<Node|null>, oldArr: Array<Node|null>, splice?) => {
       if (splice) {
         // Remove the elements that are gone.
@@ -68,5 +69,5 @@ export function forEach<T>(obsArray: MaybeObsArray<T>, itemCreateFunc: (item: T)
       }
     });
     replaceContent(markerPre, markerPost, nodes.get());
-  };
+  }];
 }

package/lib/{_domImpl.ts → domImpl.ts}

@@ -1,5 +1,5 @@
-import {domDispose} from './_domDispose';
-import {attrsElem} from './_domMethods';
+import {domDispose} from './domDispose';
+import {attrsElem} from './domMethods';
 
 // Use the browser globals in a way that allows replacing them with mocks in tests.
 import {G} from './browserGlobals';
@@ -14,23 +14,30 @@ import {G} from './browserGlobals';
 // is more flexible and robust, and only suffers from slightly more verbosity. E.g.
 // `dom('div', dom.attr('href', url))`.
 
-export type DomMethod = (elem: Node) => DomArg|void;
-export type DomElementMethod = (elem: Element) => DomElementArg|void;
+export type DomMethod<T = Node> = (elem: T) => DomArg<T>|void;
+export type DomElementMethod = DomMethod<HTMLElement>;
 
 export interface IAttrObj {
   [attrName: string]: string|boolean|null|undefined;
 }
 
-// Type of argument to dom-building functions, that work for any Node.
-export type DomArg = Node | string | IDomArgArray | DomMethod | void | null | undefined;
-export interface IDomArgArray extends Array<DomArg> {}
+// Type of argument to dom-building functions. Allows IAttrObj when applied to an Element.
+//
+// Note that DomArg<A> differs from DomArg<B> in what callbacks are accepted, so DomArg<Element>
+// can be assigned to DomArg<HTMLInputElement>, but not vice versa. When writing a function that
+// accepts DomArgs and applies them to an element, use the most specific DomArg type that works
+// for that element, e.g. DomArg<HTMLInputElement> if possible, then DomElementArg, then DomArg.
+export type DomArg<T = Node> = Node | string | void | null | undefined |
+  IDomArgs<T> | DomMethod<T> | (T extends Element ? IAttrObj : never);
 
-// More options are allowed when dom-building functions are used on an Element.
-export type DomElementArg = DomArg | IAttrObj | IDomElementArgArray | DomElementMethod;
-export interface IDomElementArgArray extends Array<DomElementArg> {}
+export interface IDomArgs<T = Node> extends Array<DomArg<T>> {}
+
+// Alias for backward compatibility.
+export type DomElementArg = DomArg<HTMLElement>;
 
 // The goal of the above declarations is to get help from TypeScript in detecting incorrect usage:
-//  import {text, hide} from './_domMethods';
+// (See test/types/dom.ts for a test of this.)
+//  import {text, hide} from './domMethods';
 //  dom('div', text('hello'));        // OK
 //  dom('div', hide(true));           // OK
 //  dom('div', {title: 'hello'});     // OK
@@ -43,6 +50,10 @@ export interface IDomElementArgArray extends Array<DomElementArg> {}
  *   The first argument is a string consisting of a tag name, with optional #foo suffix
  *   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
+ *
  * The rest of the arguments are optional and may be:
  *
  *   Nodes - which become children of the created element;
@@ -54,15 +65,18 @@ export interface IDomElementArgArray extends Array<DomElementArg> {}
  *   "dom methods" - expressions such as `dom.attr('href', url)` or `dom.hide(obs)`, which
  *       are actually special cases of the "functions" category.
  */
-export function dom(tagString: string, ...args: DomElementArg[]): HTMLElement {
-  return _updateWithArgsOrDispose(_createFromTagString(_createElementHtml, tagString), args);
+export function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagElem<Tag>>): TagElem<Tag> {
+  return _updateWithArgsOrDispose(_createFromTagString(_createElementHtml, tagString) as TagElem<Tag>, args);
 }
 
+export type TagName = keyof HTMLElementTagNameMap|string;
+export type TagElem<T extends TagName> = T extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[T] : HTMLElement;
+
 /**
  * svg('tag#id.class1.class2', ...args)
  *  Same as dom(...), but creates an SVG element.
  */
-export function svg(tagString: string, ...args: DomElementArg[]): SVGElement {
+export function svg(tagString: string, ...args: IDomArgs<SVGElement>): SVGElement {
   return _updateWithArgsOrDispose(_createFromTagString(_createElementSvg, tagString), args);
 }
 
@@ -116,18 +130,14 @@ function _createFromTagString<E extends Element>(createFunc: (tag: string) => E,
 /**
  * Update an element with any number of arguments, as documented in dom().
  */
-export function update<E extends Element>(elem: E, ...args: DomElementArg[]): E;
-export function update<E extends Node>(elem: E, ...args: DomArg[]): E;
-export function update(elem: any, ...args: DomElementArg[]): Node {
+export function update<T extends Node, Args extends IDomArgs<T>>(elem: T, ...args: Args): T {
   return _updateWithArgs(elem, args);
 }
 
 /**
  * Update an element with an array of arguments.
  */
-function _updateWithArgs<E extends Element>(elem: E, args: DomElementArg[]): E;
-function _updateWithArgs<E extends Node>(elem: E, args: DomArg[]): E;
-function _updateWithArgs(elem: any, args: DomElementArg[]): Node {
+function _updateWithArgs<T extends Node>(elem: T, args: IDomArgs<T>): T {
   for (const arg of args) {
     _updateWithArg(elem, arg);
   }
@@ -139,9 +149,7 @@ function _updateWithArgs(elem: any, args: DomElementArg[]): Node {
  * an internal helper to be used whenever elem is a newly-created element. If elem is an existing
  * element which the user already knows about, then _updateWithArgs should be called.
  */
-function _updateWithArgsOrDispose<E extends Element>(elem: E, args: DomElementArg[]): E;
-function _updateWithArgsOrDispose<E extends Node>(elem: E, args: DomArg[]): E;
-function _updateWithArgsOrDispose(elem: any, args: DomElementArg[]): Node {
+function _updateWithArgsOrDispose<T extends Node>(elem: T, args: IDomArgs<T>): T {
   try {
     return _updateWithArgs(elem, args);
   } catch (e) {
@@ -150,11 +158,9 @@ function _updateWithArgsOrDispose(elem: any, args: DomElementArg[]): Node {
   }
 }
 
-function _updateWithArg(elem: Element, arg: DomElementArg): void;
-function _updateWithArg(elem: Node, arg: DomArg): void;
-function _updateWithArg(elem: any, arg: DomElementArg): void {
+function _updateWithArg<T extends Node>(elem: T, arg: DomArg<T>): void {
   if (typeof arg === 'function') {
-    const value: DomArg = (arg as DomMethod)(elem);
+    const value: DomArg<T> = arg(elem);
     // Skip the recursive call in the common case when the function returns nothing.
     if (value !== undefined && value !== null) {
       _updateWithArg(elem, value);
@@ -166,7 +172,7 @@ function _updateWithArg(elem: any, arg: DomElementArg): void {
   } else if (arg instanceof G.Node) {
     elem.appendChild(arg);
   } else if (typeof arg === 'object') {
-    attrsElem(elem, arg);
+    attrsElem(elem as any, arg);
   } else {
     elem.appendChild(G.document.createTextNode(arg));
   }
@@ -175,9 +181,9 @@ function _updateWithArg(elem: any, arg: DomElementArg): void {
 /**
  * Creates a DocumentFragment processing arguments the same way as the dom() function.
  */
-export function frag(...args: DomArg[]): DocumentFragment {
+export function frag(...args: IDomArgs<DocumentFragment>): DocumentFragment {
   const elem = G.document.createDocumentFragment();
-  return _updateWithArgsOrDispose(elem, args);
+  return _updateWithArgsOrDispose<DocumentFragment>(elem, args);
 }
 
 /**

package/lib/{_domMethods.ts → domMethods.ts}

@@ -1,6 +1,6 @@
-import {autoDisposeElem, domDispose, onDisposeElem} from './_domDispose';
-import {DomArg, DomElementMethod, DomMethod, frag, IAttrObj} from './_domImpl';
-import {BindableValue, subscribe as subscribeBinding} from './binding';
+import {BindableValue, subscribeElem as _subscribe} from './binding';
+import {onDisposeElem} from './domDispose';
+import {DomElementMethod, DomMethod, IAttrObj} from './domImpl';
 
 // Use the browser globals in a way that allows replacing them with mocks in tests.
 import {G} from './browserGlobals';
@@ -11,15 +11,6 @@ import {G} from './browserGlobals';
  */
 const _dataMap: WeakMap<Node, {[key: string]: any}> = new WeakMap();
 
-/**
- * Internal helper that binds the callback to valueObs, which may be a value, observble, or
- * function, and attaches a disposal callback to the passed-in element.
- */
-function _subscribe<T>(elem: Node, valueObs: BindableValue<T>,
-                       callback: (newVal: T, oldVal?: T) => void): void {
-  autoDisposeElem(elem, subscribeBinding(valueObs, callback));
-}
-
 /**
  * Sets multiple attributes of a DOM element. The `attrs()` variant takes no `elem` argument.
  * Null and undefined values are omitted, and booleans are either omitted or set to empty string.
@@ -124,8 +115,8 @@ export function prop<T>(property: string, valueObs: BindableValue<T>): DomMethod
  * @param {Element} elem: The element to update.
  * @param {Boolean} boolValue: True to show the element, false to hide it.
  */
-export function showElem(elem: Element, boolValue: boolean): void {
-  (elem as HTMLElement).style.display = boolValue ? '' : 'none';
+export function showElem(elem: HTMLElement, boolValue: boolean): void {
+  elem.style.display = boolValue ? '' : 'none';
 }
 export function show(boolValueObs: BindableValue<boolean>): DomElementMethod {
   return (elem) =>
@@ -138,8 +129,8 @@ export function show(boolValueObs: BindableValue<boolean>): DomElementMethod {
  * @param {Element} elem: The element to update.
  * @param {Boolean} boolValue: True to hide the element, false to show it.
  */
-export function hideElem(elem: Element, boolValue: boolean): void {
-  (elem as HTMLElement).style.display = boolValue ? 'none' : '';
+export function hideElem(elem: HTMLElement, boolValue: boolean): void {
+  elem.style.display = boolValue ? 'none' : '';
 }
 export function hide(boolValueObs: BindableValue<boolean>): DomElementMethod {
   return (elem) =>
@@ -226,103 +217,42 @@ export function getData(elem: Node, key: string) {
 }
 
 /**
- * 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 {
-  const elem = nodeBefore.parentNode;
-  if (elem) {
-    let next;
-    for (let n = nodeBefore.nextSibling; n && n !== nodeAfter; n = next) {
-      next = n.nextSibling;
-      domDispose(n);
-      elem.removeChild(n);
-    }
-    if (content) {
-      elem.insertBefore(content instanceof G.Node ? content : frag(content), nodeAfter);
-    }
-  }
-}
-
-/**
- * Appends dynamic DOM content to an element. The value may be an observable or function (from
- * which a computed is created), whose value will be passed to `contentFunc` which should return
- * DOM content. If the contentFunc is omitted, it defaults to identity, i.e. it's OK for the
- * observable or function to return DOM directly.
- *
- * The DOM content returned may be an element, string, array, or null. Whenever the observable
- * changes, previous content is disposed and removed, and new content added in its place.
+ * A very simple setup to identify DOM elements for testing purposes. Here's the recommended
+ * usage.
  *
- * These are roughly equivalent:
- *  (A) domComputed(nlinesObs, nlines => nlines > 1 ? dom('textarea') : dom('input'));
- *  (B) domComputed(use => use(nlinesObs) > 1, isTall => isTall ? dom('textarea') : dom('input'));
- *  (C) domComputed(use => use(nlinesObs) > 1 ? dom('textarea') : dom('input'));
+ *   // In the component to be tested.
+ *   import {noTestId, TestId} from 'grainjs';
  *
- * Here, (B) is best. It encapsulates meaningful changes in the observable, and separates DOM
- * creation, so that DOM is only recreated when necessary. Between (A) and (C), (A) should be
- * preferred. Both (A) and (C) would rebuild DOM for any change in nlinesObs, but in (C), it's too
- * easy to use `use` more than necessary and cause inadvertent rebuilding of DOM.
+ *   function myComponent(myArgs, testId: TestId = noTestId) {
+ *     return dom(..., testId("some-name"),
+ *       dom(..., testId("another-name"), ...),
+ *     );
+ *   }
  *
- * Syntax (C), without the last argument, may be useful in cases of DOM depending on several
- * observables, e.g.
+ * In the fixture code using this component:
  *
- *    domComputed(use => use(readonlyObs) ? dom('div') :
- *                          (use(nlinesObs) > 1 ? dom('textarea') : dom('input')));
+ *   import {makeTestId} from 'grainjs';
  *
- * If the argument is not an observable, domComputed() may but should not be used. The following
- * are equivalent:
+ *   dom(..., myComponent(myArgs, makeTestId('test-mycomp-'), ...)
  *
- *    dom(..., domComputed(listValue, list => list.map(x => dom('div', x))), ...)
- *    dom(..., listValue.map(x => dom('div', x)), ...)
+ * In the webdriver test code:
  *
- * In this case, the latter is preferred as the clearly simpler one.
+ *   driver.find('.test-my-comp-some-name')
+ *   driver.find('.test-my-comp-another-name')
  *
- * @param {Element} elem: The element to which to append the DOM content.
- * @param {Object} valueObs: Observable or function for a computed.
- * @param [Function] contentFunc: Function called with the result of valueObs as the input, and
- *    returning DOM as output. If omitted, defaults to the identity function.
+ * When myComponent() is created with testId argument omitted, the testId() calls are no-ops. When
+ * makeTestId('test-foo-') is passed in, testId() calls simply add a css class with that prefix.
  */
-export function domComputed<T extends DomArg>(valueObs: BindableValue<T>): DomMethod;
-export function domComputed<T>(valueObs: BindableValue<T>, contentFunc: (val: T) => DomArg): DomMethod;
-export function domComputed<T>(valueObs: BindableValue<T>, contentFunc?: (val: T) => DomArg): DomMethod {
-  const _contentFunc: (val: T) => DomArg = contentFunc || (identity as any);
-  return (elem: Node) => {
-    const markerPre = G.document.createComment('a');
-    const markerPost = G.document.createComment('b');
-    elem.appendChild(markerPre);
-    elem.appendChild(markerPost);
-    _subscribe(elem, valueObs,
-      (value) => replaceContent(markerPre, markerPost, _contentFunc(value)));
-  };
-}
-
-function identity<T>(arg: T): T { return arg; }
+export type TestId = (name: string) => DomElementMethod|null;
 
 /**
- * Conditionally appends DOM to an element. The value may be an observable or function (from which
- * a computed is created), whose value -- if truthy -- will be passed to `contentFunc` which
- * should return DOM content. If the value is falsy, DOM content is removed.
- *
- * 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.
- *
- *    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:
- *
- *    dom(..., dom.maybe(myValue, () => dom(...)));
- *    dom(..., myValue ? dom(...) : null);
- *
- * The latter is preferred for being simpler.
- *
- * @param {Element} elem: The element to which to append the DOM content.
- * @param {Object} boolValueObs: Observable or function for a computed.
- * @param [Function] contentFunc: Function called with the result of boolValueObs when it is
- *    truthy. Should returning DOM as output.
+ * See documentation for TestId above.
  */
-export function maybe<T>(boolValueObs: BindableValue<T>, contentFunc: (val: T) => DomArg): DomMethod {
-  return domComputed(boolValueObs, (value) => value ? contentFunc(value) : null);
+export function makeTestId(prefix: string): TestId {
+  return clsPrefix.bind(null, prefix);
 }
+
+/**
+ * See documentation for TestId above.
+ */
+export const noTestId: TestId = (name: string) => null;