grainjs 0.1.0 → 1.0.2

package/dist/cjs/lib/domComputed.d.ts

@@ -0,0 +1,89 @@
+import { BindableValue } from './binding';
+import { MultiHolder } from './dispose';
+import { DomArg, DomMethod } from './domImpl';
+export declare type DomComputed = [Node, Node, DomMethod];
+export declare 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 declare function replaceContent(nodeBefore: Node, nodeAfter: Node, content: DomContents): void;
+/**
+ * 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.
+ */
+export declare function domComputed(valueObs: BindableValue<Exclude<DomArg, DomMethod>>): DomComputed;
+export declare function domComputed<T>(valueObs: BindableValue<T>, contentFunc: (val: T) => DomContents): DomComputed;
+/**
+ * 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 declare function domComputedOwned<T>(valueObs: BindableValue<T>, contentFunc: (owner: MultiHolder, val: T) => DomContents): DomComputed;
+/**
+ * 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 declare function maybe<T>(boolValueObs: BindableValue<T>, contentFunc: (val: NonNullable<T>) => DomContents): DomComputed;
+/**
+ * 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 declare function maybeOwned<T>(boolValueObs: BindableValue<T>, contentFunc: (owner: MultiHolder, val: NonNullable<T>) => DomContents): DomComputed;

package/dist/cjs/lib/domComputed.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeOwned = exports.maybe = exports.domComputedOwned = exports.domComputed = exports.replaceContent = void 0;
+const binding_1 = require("./binding");
+const dispose_1 = require("./dispose");
+const domDispose_1 = require("./domDispose");
+const domImpl_1 = require("./domImpl");
+// Use the browser globals in a way that allows replacing them with mocks in tests.
+const browserGlobals_1 = require("./browserGlobals");
+/**
+ * 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.
+ */
+function replaceContent(nodeBefore, nodeAfter, content) {
+    const elem = nodeBefore.parentNode;
+    if (elem) {
+        let next;
+        for (let n = nodeBefore.nextSibling; n && n !== nodeAfter; n = next) {
+            next = n.nextSibling;
+            domDispose_1.domDispose(n);
+            elem.removeChild(n);
+        }
+        if (content) {
+            elem.insertBefore(content instanceof browserGlobals_1.G.Node ? content : domImpl_1.frag(content), nodeAfter);
+        }
+    }
+}
+exports.replaceContent = replaceContent;
+function domComputed(valueObs, contentFunc = identity) {
+    const markerPre = browserGlobals_1.G.document.createComment('a');
+    const markerPost = browserGlobals_1.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) => {
+            binding_1.subscribeElem(markerPost, valueObs, (value) => replaceContent(markerPre, markerPost, contentFunc(value)));
+        }];
+}
+exports.domComputed = domComputed;
+/**
+ * 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());
+ */
+function domComputedOwned(valueObs, contentFunc) {
+    const holder = dispose_1.Holder.create(null);
+    const [markerPre, markerPost, func] = domComputed(valueObs, (val) => contentFunc(dispose_1.MultiHolder.create(holder), val));
+    domDispose_1.autoDisposeElem(markerPost, holder);
+    return [markerPre, markerPost, func];
+}
+exports.domComputedOwned = domComputedOwned;
+function identity(arg) { 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.
+ */
+function maybe(boolValueObs, contentFunc) {
+    return domComputed(boolValueObs, (value) => value ? contentFunc(value) : null);
+}
+exports.maybe = maybe;
+/**
+ * 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());
+ */
+function maybeOwned(boolValueObs, contentFunc) {
+    return domComputedOwned(boolValueObs, (owner, value) => value ? contentFunc(owner, value) : null);
+}
+exports.maybeOwned = maybeOwned;
+//# sourceMappingURL=domComputed.js.map

package/dist/cjs/lib/domComputed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domComputed.js","sourceRoot":"","sources":["../../../lib/domComputed.ts"],"names":[],"mappings":";;;AAAA,uCAAuD;AACvD,uCAA8C;AAC9C,6CAAyD;AACzD,uCAAkD;AAElD,mFAAmF;AACnF,qDAAmC;AAUnC;;;;GAIG;AACH,SAAgB,cAAc,CAAC,UAAgB,EAAE,SAAe,EAAE,OAAoB;IACpF,MAAM,IAAI,GAAG,UAAU,CAAC,UAAU,CAAC;IACnC,IAAI,IAAI,EAAE;QACR,IAAI,IAAI,CAAC;QACT,KAAK,IAAI,CAAC,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE;YACnE,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC;YACrB,uBAAU,CAAC,CAAC,CAAC,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;SACrB;QACD,IAAI,OAAO,EAAE;YACX,IAAI,CAAC,YAAY,CAAC,OAAO,YAAY,kBAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,cAAI,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;SACnF;KACF;AACH,CAAC;AAbD,wCAaC;AAyCD,SAAgB,WAAW,CACzB,QAA0B,EAAE,cAAuC,QAAe;IAElF,MAAM,SAAS,GAAG,kBAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,kBAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAEjD,gGAAgG;IAChG,yCAAyC;IACzC,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,IAAU,EAAE,EAAE;YAC5C,uBAAa,CAAC,UAAU,EAAE,QAAQ,EAChC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAZD,kCAYC;AAED;;;;;;GAMG;AACH,SAAgB,gBAAgB,CAC9B,QAA0B,EAAE,WAAwD;IAEpF,MAAM,MAAM,GAAG,gBAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC,QAAQ,EACxD,CAAC,GAAM,EAAE,EAAE,CAAC,WAAW,CAAC,qBAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5D,4BAAe,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC;AARD,4CAQC;AAED,SAAS,QAAQ,CAAI,GAAM,IAAO,OAAO,GAAG,CAAC,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,KAAK,CAAI,YAA8B,EACnD,WAAiD;IACnD,OAAO,WAAW,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAClF,CAAC;AAHD,sBAGC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAI,YAA8B,EACxD,WAAqE;IACvE,OAAO,gBAAgB,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,KAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACrG,CAAC;AAHD,gCAGC"}

package/dist/cjs/lib/{_domDispose.d.ts → domDispose.d.ts}

@@ -1,5 +1,15 @@
 import { IDisposable } from './dispose';
 export declare type INodeFunc = (node: Node) => void;
+export declare function _disposeNode(node: Node): void;
+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 declare const domDisposeHooks: IDomDisposeHooks;
 /**
  * Run disposers associated with any descendant of elem or with elem itself. Disposers get
  * associated with elements using dom.onDispose(). Descendants are processed first.
@@ -7,9 +17,9 @@ export declare type INodeFunc = (node: 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 declare function domDispose(elem: Node): void;
+export declare function domDispose(node: Node): void;
 /**
  * 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

package/dist/cjs/lib/{_domDispose.js → domDispose.js}

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoDispose = exports.autoDisposeElem = exports.onDispose = exports.onDisposeElem = exports.domDispose = exports.domDisposeHooks = exports._disposeNode = void 0;
 /**
  * Private global disposal map. It maintains the association between DOM nodes and cleanup
  * functions added with dom.onDispose(). To support multiple disposers on one element, we use a
@@ -25,19 +26,31 @@ function _walkDom(elem, visitFunc) {
     visitFunc(elem);
 }
 // Internal helper to run all disposers for a single element.
-function _disposeElem(elem) {
-    let disposer = _disposeMap.get(elem);
+function _disposeNode(node) {
+    let disposer = _disposeMap.get(node);
     if (disposer) {
-        let key = elem;
+        let key = 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);
         } while (disposer);
     }
 }
+exports._disposeNode = _disposeNode;
+function _disposeNodeRecursive(node) {
+    _walkDom(node, exports.domDisposeHooks.disposeNode);
+}
+/**
+ * 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.
+ */
+exports.domDisposeHooks = {
+    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.
@@ -45,10 +58,10 @@ function _disposeElem(elem) {
  * 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.
  */
-function domDispose(elem) {
-    _walkDom(elem, _disposeElem);
+function domDispose(node) {
+    exports.domDisposeHooks.disposeRecursive(node);
 }
 exports.domDispose = domDispose;
 /**
@@ -91,4 +104,4 @@ function autoDispose(disposable) {
     }
 }
 exports.autoDispose = autoDispose;
-//# sourceMappingURL=_domDispose.js.map
+//# sourceMappingURL=domDispose.js.map

package/dist/cjs/lib/domDispose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domDispose.js","sourceRoot":"","sources":["../../../lib/domDispose.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,GAAuC,IAAI,OAAO,EAAE,CAAC;AAItE,4FAA4F;AAC5F,mCAAmC;AACnC,SAAS,QAAQ,CAAC,IAAU,EAAE,SAAoB;IAChD,IAAI,CAAC,GAAc,IAAI,CAAC,UAAU,CAAC;IACnC,OAAO,CAAC,EAAE;QACR,4FAA4F;QAC5F,gCAAgC;QAChC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACvB,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;KACnB;IACD,SAAS,CAAC,IAAI,CAAC,CAAC;AAClB,CAAC;AAED,6DAA6D;AAC7D,SAAgB,YAAY,CAAC,IAAU;IACrC,IAAI,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,QAAQ,EAAE;QACZ,IAAI,GAAG,GAAmB,IAAI,CAAC;QAC/B,GAAG;YACD,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACf,qEAAqE;YACrE,GAAG,GAAG,QAAQ,CAAC;YACf,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;SACjC,QAAQ,QAAQ,EAAE;KACpB;AACH,CAAC;AAZD,oCAYC;AAED,SAAS,qBAAqB,CAAC,IAAU;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAe,CAAC,WAAW,CAAC,CAAC;AAC9C,CAAC;AAOD;;;GAGG;AACU,QAAA,eAAe,GAAqB;IAC/C,WAAW,EAAE,YAAY;IACzB,gBAAgB,EAAE,qBAAqB;CACxC,CAAC;AAEF;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,IAAU;IACnC,uBAAe,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAFD,gCAEC;AAED;;;;;;;;;GASG;AACH,SAAgB,aAAa,CAAC,IAAU,EAAE,YAAuB;IAC/D,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IACpC,IAAI,YAAY,EAAE;QAChB,WAAW,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;KAC7C;AACH,CAAC;AAND,sCAMC;AACD,SAAgB,SAAS,CAAC,YAAuB;IAC/C,OAAO,CAAC,IAAU,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AAC3D,CAAC;AAFD,8BAEC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,IAAU,EAAE,UAA4B;IACtE,IAAI,UAAU,EAAE;QACd,aAAa,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;KACjD;AACH,CAAC;AAJD,0CAIC;AACD,SAAgB,WAAW,CAAC,UAA4B;IACtD,IAAI,UAAU,EAAE;QACd,OAAO,CAAC,IAAU,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;KAC1D;AACH,CAAC;AAJD,kCAIC"}

package/dist/cjs/lib/{_domForEach.d.ts → domForEach.d.ts}

@@ -1,4 +1,4 @@
-import { DomMethod } from './_domImpl';
+import { DomContents } from './domComputed';
 import { MaybeObsArray } from './obsArray';
 /**
  * Creates DOM elements for each element of an observable array. As the array is changed, children
@@ -18,4 +18,4 @@ import { MaybeObsArray } from './obsArray';
  * If you'd like to map the DOM node back to its source item, use dom.data() and dom.getData() in
  * itemCreateFunc().
  */
-export declare function forEach<T>(obsArray: MaybeObsArray<T>, itemCreateFunc: (item: T) => Node | null): DomMethod;
+export declare function forEach<T>(obsArray: MaybeObsArray<T>, itemCreateFunc: (item: T) => Node | null): DomContents;

package/dist/cjs/lib/domForEach.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forEach = void 0;
+const domComputed_1 = require("./domComputed");
+const domDispose_1 = require("./domDispose");
+const domImpl_1 = require("./domImpl");
+const obsArray_1 = require("./obsArray");
+// Use the browser globals in a way that allows replacing them with mocks in tests.
+const browserGlobals_1 = require("./browserGlobals");
+/**
+ * Creates DOM elements for each element of an observable array. As the array is changed, children
+ * are added or removed. This works for any array-valued observable, and for obsArray() and
+ * computedArray() it works more efficiently for simple changes.
+ *
+ * The given itemCreateFunc() should return a single DOM node for each item, or null to skip that
+ * item. It is called for new items whenever they are spliced in, or the array replaced. The
+ * forEach() owns the created nodes, and runs domDispose() on them when they are spliced out.
+ *
+ * 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.
+ *
+ * If you'd like to map the DOM node back to its source item, use dom.data() and dom.getData() in
+ * itemCreateFunc().
+ */
+function forEach(obsArray, itemCreateFunc) {
+    const markerPre = browserGlobals_1.G.document.createComment('a');
+    const markerPost = browserGlobals_1.G.document.createComment('b');
+    return [markerPre, markerPost, (elem) => {
+            if (Array.isArray(obsArray)) {
+                domComputed_1.replaceContent(markerPre, markerPost, obsArray.map(itemCreateFunc));
+                return;
+            }
+            const nodes = obsArray_1.computedArray(obsArray, itemCreateFunc);
+            // Be sure to dispose the newly-created array when the DOM it's associated with is gone.
+            domDispose_1.autoDisposeElem(markerPost, nodes);
+            nodes.addListener((newArr, oldArr, splice) => {
+                if (splice) {
+                    // Remove the elements that are gone.
+                    for (const node of splice.deleted) {
+                        if (node && node.parentNode === elem) {
+                            domDispose_1.domDispose(node);
+                            elem.removeChild(node);
+                        }
+                    }
+                    if (splice.numAdded > 0) {
+                        // Find a valid child immediately following the spliced out portion, for DOM insertion.
+                        const endIndex = splice.start + splice.numAdded;
+                        let nextElem = markerPost;
+                        for (let i = endIndex; i < newArr.length; i++) {
+                            const node = newArr[i];
+                            if (node && node.parentNode === elem) {
+                                nextElem = node;
+                                break;
+                            }
+                        }
+                        // Insert the new elements.
+                        const content = domImpl_1.frag(newArr.slice(splice.start, endIndex));
+                        elem.insertBefore(content, nextElem);
+                    }
+                }
+                else {
+                    domComputed_1.replaceContent(markerPre, markerPost, newArr);
+                }
+            });
+            domComputed_1.replaceContent(markerPre, markerPost, nodes.get());
+        }];
+}
+exports.forEach = forEach;
+//# sourceMappingURL=domForEach.js.map

package/dist/cjs/lib/domForEach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domForEach.js","sourceRoot":"","sources":["../../../lib/domForEach.ts"],"names":[],"mappings":";;;AAAA,+CAA0D;AAC1D,6CAAyD;AACzD,uCAA+B;AAC/B,yCAAkE;AAElE,mFAAmF;AACnF,qDAAmC;AAEnC;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,OAAO,CAAI,QAA0B,EAAE,cAAsC;IAC3F,MAAM,SAAS,GAAG,kBAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,kBAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IACjD,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,IAAU,EAAE,EAAE;YAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAC3B,4BAAc,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;gBACpE,OAAO;aACR;YAED,MAAM,KAAK,GAAwB,wBAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;YAE3E,wFAAwF;YACxF,4BAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YAEnC,KAAK,CAAC,WAAW,CAAC,CAAC,MAAwB,EAAE,MAAwB,EAAE,MAAO,EAAE,EAAE;gBAChF,IAAI,MAAM,EAAE;oBACV,qCAAqC;oBACrC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE;wBACjC,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE;4BACpC,uBAAU,CAAC,IAAI,CAAC,CAAC;4BACjB,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;yBACxB;qBACF;oBAED,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE;wBACvB,uFAAuF;wBACvF,MAAM,QAAQ,GAAW,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC;wBACxD,IAAI,QAAQ,GAAS,UAAU,CAAC;wBAChC,KAAK,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;4BAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;4BACvB,IAAI,IAAI,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE;gCACpC,QAAQ,GAAG,IAAI,CAAC;gCAChB,MAAM;6BACP;yBACF;wBAED,2BAA2B;wBAC3B,MAAM,OAAO,GAAG,cAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;wBAC3D,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;qBACtC;iBACF;qBAAM;oBACL,4BAAc,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;iBAC/C;YACH,CAAC,CAAC,CAAC;YACH,4BAAc,CAAC,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;AACL,CAAC;AA9CD,0BA8CC"}

package/dist/cjs/lib/{_domImpl.d.ts → domImpl.d.ts}

@@ -1,19 +1,21 @@
-export declare type DomMethod = (elem: Node) => DomArg | void;
-export declare type DomElementMethod = (elem: Element) => DomElementArg | void;
+export declare type DomMethod<T = Node> = (elem: T) => DomArg<T> | void;
+export declare type DomElementMethod = DomMethod<HTMLElement>;
 export interface IAttrObj {
     [attrName: string]: string | boolean | null | undefined;
 }
-export declare type DomArg = Node | string | IDomArgArray | DomMethod | void | null | undefined;
-export interface IDomArgArray extends Array<DomArg> {
-}
-export declare type DomElementArg = DomArg | IAttrObj | IDomElementArgArray | DomElementMethod;
-export interface IDomElementArgArray extends Array<DomElementArg> {
+export declare type DomArg<T = Node> = Node | string | void | null | undefined | IDomArgs<T> | DomMethod<T> | (T extends Element ? IAttrObj : never);
+export interface IDomArgs<T = Node> extends Array<DomArg<T>> {
 }
+export declare type DomElementArg = DomArg<HTMLElement>;
 /**
  * dom('tag#id.class1.class2', ...args)
  *   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;
@@ -25,21 +27,22 @@ 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 declare function dom(tagString: string, ...args: DomElementArg[]): HTMLElement;
+export declare function dom<Tag extends TagName>(tagString: Tag, ...args: IDomArgs<TagElem<Tag>>): TagElem<Tag>;
+export declare type TagName = keyof HTMLElementTagNameMap | string;
+export declare 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 declare function svg(tagString: string, ...args: DomElementArg[]): SVGElement;
+export declare function svg(tagString: string, ...args: IDomArgs<SVGElement>): SVGElement;
 /**
  * Update an element with any number of arguments, as documented in dom().
  */
-export declare function update<E extends Element>(elem: E, ...args: DomElementArg[]): E;
-export declare function update<E extends Node>(elem: E, ...args: DomArg[]): E;
+export declare function update<T extends Node, Args extends IDomArgs<T>>(elem: T, ...args: Args): T;
 /**
  * Creates a DocumentFragment processing arguments the same way as the dom() function.
  */
-export declare function frag(...args: DomArg[]): DocumentFragment;
+export declare function frag(...args: IDomArgs<DocumentFragment>): DocumentFragment;
 /**
  * Find the first element matching a selector; just an abbreviation for document.querySelector().
  */

package/dist/cjs/lib/{_domImpl.js → domImpl.js}

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const _domDispose_1 = require("./_domDispose");
-const _domMethods_1 = require("./_domMethods");
+exports.findAll = exports.find = exports.frag = exports.update = exports.svg = exports.dom = void 0;
+const domDispose_1 = require("./domDispose");
+const domMethods_1 = require("./domMethods");
 // Use the browser globals in a way that allows replacing them with mocks in tests.
 const browserGlobals_1 = require("./browserGlobals");
 // 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
@@ -17,6 +19,10 @@ const browserGlobals_1 = require("./browserGlobals");
  *   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;
@@ -90,22 +96,33 @@ function _createFromTagString(createFunc, tagString) {
     }
     return elem;
 }
+/**
+ * Update an element with any number of arguments, as documented in dom().
+ */
 function update(elem, ...args) {
     return _updateWithArgs(elem, args);
 }
 exports.update = update;
+/**
+ * Update an element with an array of arguments.
+ */
 function _updateWithArgs(elem, args) {
     for (const arg of args) {
         _updateWithArg(elem, arg);
     }
     return elem;
 }
+/**
+ * Update an element with an array of arguments, calling disposers in case of an exception. It is
+ * 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(elem, args) {
     try {
         return _updateWithArgs(elem, args);
     }
     catch (e) {
-        _domDispose_1.domDispose(elem);
+        domDispose_1.domDispose(elem);
         throw e;
     }
 }
@@ -127,7 +144,7 @@ function _updateWithArg(elem, arg) {
         elem.appendChild(arg);
     }
     else if (typeof arg === 'object') {
-        _domMethods_1.attrsElem(elem, arg);
+        domMethods_1.attrsElem(elem, arg);
     }
     else {
         elem.appendChild(browserGlobals_1.G.document.createTextNode(arg));
@@ -151,4 +168,4 @@ exports.find = find;
  */
 function findAll(selector) { return browserGlobals_1.G.document.querySelectorAll(selector); }
 exports.findAll = findAll;
-//# sourceMappingURL=_domImpl.js.map
+//# sourceMappingURL=domImpl.js.map

package/dist/cjs/lib/domImpl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domImpl.js","sourceRoot":"","sources":["../../../lib/domImpl.ts"],"names":[],"mappings":"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"}

package/dist/cjs/lib/{_domMethods.d.ts → domMethods.d.ts}

@@ -1,5 +1,5 @@
-import { DomArg, DomElementMethod, DomMethod, IAttrObj } from './_domImpl';
 import { BindableValue } from './binding';
+import { DomElementMethod, DomMethod, IAttrObj } from './domImpl';
 /**
  * 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.
@@ -60,7 +60,7 @@ export declare function prop<T>(property: string, valueObs: BindableValue<T>): D
  * @param {Element} elem: The element to update.
  * @param {Boolean} boolValue: True to show the element, false to hide it.
  */
-export declare function showElem(elem: Element, boolValue: boolean): void;
+export declare function showElem(elem: HTMLElement, boolValue: boolean): void;
 export declare function show(boolValueObs: BindableValue<boolean>): DomElementMethod;
 /**
  * The opposite of show, hiding the element when boolValue is true.
@@ -68,7 +68,7 @@ export declare function show(boolValueObs: BindableValue<boolean>): DomElementMe
  * @param {Element} elem: The element to update.
  * @param {Boolean} boolValue: True to hide the element, false to show it.
  */
-export declare function hideElem(elem: Element, boolValue: boolean): void;
+export declare function hideElem(elem: HTMLElement, boolValue: boolean): void;
 export declare function hide(boolValueObs: BindableValue<boolean>): DomElementMethod;
 /**
  * Sets or toggles the given css class className.
@@ -103,73 +103,38 @@ export declare function dataElem(elem: Node, key: string, value: any): void;
 export declare function data(key: string, valueObs: BindableValue<any>): DomMethod;
 export declare function getData(elem: Node, key: string): any;
 /**
- * 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 declare function replaceContent(nodeBefore: Node, nodeAfter: Node, content: DomArg): void;
-/**
- * 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 declare function domComputed<T extends DomArg>(valueObs: BindableValue<T>): DomMethod;
-export declare function domComputed<T>(valueObs: BindableValue<T>, contentFunc: (val: T) => DomArg): DomMethod;
+export declare 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 declare function makeTestId(prefix: string): TestId;
+/**
+ * See documentation for TestId above.
  */
-export declare function maybe<T>(boolValueObs: BindableValue<T>, contentFunc: (val: T) => DomArg): DomMethod;
+export declare const noTestId: TestId;