grainjs 1.0.1 → 1.1.0

package/dist/esm/lib/dispose.js

@@ -1,102 +1,94 @@
+import { LLink } from './emit';
+// Internal "owner" of disposable objects which doesn't actually dispose or keep track of them. It
+// is the effective owner when creating a Disposable with `new Foo()` rather than `Foo.create()`.
+const _noopOwner = {
+    autoDispose(obj) { },
+};
+// Newly-created Disposable instances will have this as their owner. This is not a constant, it
+// is used by create() for the safe creation of Disposables.
+let _defaultDisposableOwner = _noopOwner;
 /**
- * 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:
+ * Base class for disposable objects that can own other objects.
  *
- *    https://phab.getgrist.com/w/disposal/
+ * 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
+ * `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 { ... }
+ * ```ts
+ * class Foo extends Disposable { ... }
+ * ```
  *
- * To create Foo:
- *    const foo = Foo.create(owner, ...args);
+ * 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
+ *    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, ...);
+ * 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:
- *    this.bar = this.autoDispose(createSomethingDisposable());
+ * ```ts
+ * 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
+ * ```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):
- *    this.wipeOnDispose();
+ * ```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()
+ * To dispose Foo directly: `foo.dispose()`.
  *
- * 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
+ * To determine if an object has already been disposed: `foo.isDisposed()`.
  *
- * 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 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. 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
+ * 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.
- *    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
+ * ```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:
- *    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';
-// Internal "owner" of disposable objects which doesn't actually dispose or keep track of them. It
-// is the effective owner when creating a Disposable with `new Foo()` rather than `Foo.create()`.
-const _noopOwner = {
-    autoDispose(obj) { },
-};
-// Newly-created Disposable instances will have this as their owner. This is not a constant, it
-// is used by create() for the safe creation of Disposables.
-let _defaultDisposableOwner = _noopOwner;
-/**
- * Base class for disposable objects that can own other objects. See the module documentation.
+ * ```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 class Disposable {
-    constructor() {
-        this._disposalList = new DisposalList();
-        // This registers with a temp Holder when using create(), and is a no-op when using `new Foo`.
-        _defaultDisposableOwner.autoDispose(this);
-        // Be sure to reset to no-op, so that a (non-recommended) direct call like 'new Bar()', from
-        // inside Foo's constructor doesn't use the same Holder that's temporarily holding Foo.
-        _defaultDisposableOwner = _noopOwner;
-    }
     /**
      * 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.
      */
     static create(owner, ...args) {
         const origDefaultOwner = _defaultDisposableOwner;
@@ -124,12 +116,20 @@ export class Disposable {
             _defaultDisposableOwner = origDefaultOwner;
         }
     }
-    /** Take ownership of obj, and dispose it when this.dispose() is called. */
+    constructor() {
+        this._disposalList = new DisposalList();
+        // This registers with a temp Holder when using create(), and is a no-op when using `new Foo`.
+        _defaultDisposableOwner.autoDispose(this);
+        // Be sure to reset to no-op, so that a (non-recommended) direct call like 'new Bar()', from
+        // inside Foo's constructor doesn't use the same Holder that's temporarily holding Foo.
+        _defaultDisposableOwner = _noopOwner;
+    }
+    /** Take ownership of `obj`, and dispose it when `this.dispose()` is called. */
     autoDispose(obj) {
         this.onDispose(obj.dispose, obj);
         return obj;
     }
-    /** Call the given callback when this.dispose() is called. */
+    /** Call the given callback when `this.dispose()` is called. */
     onDispose(callback, context) {
         return this._disposalList.addListener(callback, context);
     }
@@ -138,10 +138,13 @@ export class Disposable {
      * 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.
      *
@@ -158,7 +161,7 @@ export class Disposable {
         return this._disposalList === null;
     }
     /**
-     * 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.
      */
     dispose() {
@@ -187,17 +190,31 @@ export class Disposable {
 }
 /**
  * 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 {
     constructor() {
+        /** @internal */
         this._owned = null;
         this._disposalListener = undefined;
     }
+    /** `Holder.create(owner)` creates a new `Holder`. */
     static create(owner) {
         return setDisposeOwner(owner, new Holder());
     }
@@ -246,9 +263,18 @@ export class Holder {
     }
 }
 /**
- * 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 {
 }
@@ -296,11 +322,6 @@ class DisposalList extends LLink {
  * reports and swallows erros when it calls the callbacks in the list.
  */
 class DisposeListener extends LLink {
-    constructor(callback, context) {
-        super();
-        this.callback = callback;
-        this.context = context;
-    }
     static callAll(begin, end, owner) {
         while (begin !== end) {
             const lis = begin;
@@ -314,6 +335,11 @@ class DisposeListener extends LLink {
             begin = lis._next;
         }
     }
+    constructor(callback, context) {
+        super();
+        this.callback = callback;
+        this.context = context;
+    }
     dispose() {
         if (this.isDisposed()) {
             return;

package/dist/esm/lib/dispose.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../../../lib/dispose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAEH,OAAO,EAAC,KAAK,EAAC,MAAM,QAAQ,CAAC;AAwB7B,kGAAkG;AAClG,iGAAiG;AACjG,MAAM,UAAU,GAAqB;IACnC,WAAW,CAAC,GAAgB,IAAqB,CAAC;CACnD,CAAC;AAEF,+FAA+F;AAC/F,4DAA4D;AAC5D,IAAI,uBAAuB,GAAG,UAAU,CAAC;AAWzC;;GAEG;AACH,MAAM,OAAgB,UAAU;IAqC9B;QAFQ,kBAAa,GAAiB,IAAI,YAAY,EAAE,CAAC;QAGvD,8FAA8F;QAC9F,uBAAuB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1C,4FAA4F;QAC5F,uFAAuF;QACvF,uBAAuB,GAAG,UAAU,CAAC;IACvC,CAAC;IA1CD;;;;;;;OAOG;IACI,MAAM,CAAC,MAAM,CACT,KAA8C,EAAE,GAAG,IAA8B;QAE1F,MAAM,gBAAgB,GAAG,uBAAuB,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI;YACF,0DAA0D;YAC1D,uBAAuB,GAAG,MAAM,CAAC;YACjC,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;SAClD;QAAC,OAAO,CAAC,EAAE;YACV,IAAI;gBACF,yDAAyD;gBACzD,MAAM,CAAC,KAAK,EAAE,CAAC;aAChB;YAAC,OAAO,EAAE,EAAE;gBACX,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,2CAA2C,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;aAC3E;YACD,MAAM,CAAC,CAAC;SACT;gBAAS;YACR,6EAA6E;YAC7E,uEAAuE;YACvE,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,uBAAuB,GAAG,gBAAgB,CAAC;SAC5C;IACH,CAAC;IAYD,2EAA2E;IACpE,WAAW,CAAwB,GAAM;QAC9C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACjC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,6DAA6D;IACtD,SAAS,CAAI,QAA2B,EAAE,OAAW;QAC1D,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,aAAa;QAClB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,aAAa,KAAK,IAAI,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,OAAO;QACZ,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,YAAY,EAAE;YACf,sCAAsC;YACxC,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;SAChF;aAAM;YACL,IAAI,CAAC,aAAa,GAAG,IAAK,CAAC;YAC3B,YAAY,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;SACnC;IACH,CAAC;IAED;;;OAGG;IACK,cAAc;QACpB,6FAA6F;QAC7F,6FAA6F;QAC7F,yFAAyF;QACzF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YAChC,IAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;SACzB;IACH,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,MAAM;IAAnB;QAKY,WAAM,GAAW,IAAI,CAAC;QACxB,sBAAiB,GAA8B,SAAS,CAAC;IAoDnE,CAAC;IAzDQ,MAAM,CAAC,MAAM,CAAwB,KAAwC;QAClF,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,MAAM,EAAK,CAAC,CAAC;IACjD,CAAC;IAKD,yEAAyE;IAClE,WAAW,CAAC,GAAM;QACvB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAClB,IAAI,GAAG,YAAY,UAAU,EAAE;YAC7B,IAAI,CAAC,iBAAiB,GAAG,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;SACtE;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,0EAA0E;IACnE,OAAO;QACZ,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,uDAAuD;IAChD,KAAK;QACV,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,KAAK,EAAE;YACT,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,KAAK,CAAC,OAAO,EAAE,CAAC;SACjB;IACH,CAAC;IAED,+DAA+D;IACxD,GAAG,KAAa,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5C,2CAA2C;IACpC,OAAO,KAAc,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAElD,uEAAuE;IAChE,OAAO,KAAW,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAExC,sDAAsD;IAC9C,SAAS;QACf,MAAM,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,CAAC;QAChD,IAAI,gBAAgB,EAAE;YACpB,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;YACnC,gBAAgB,CAAC,OAAO,EAAE,CAAC;SAC5B;IACH,CAAC;IAEO,iBAAiB;QACvB,IAAI,CAAC,iBAAiB,GAAG,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,UAAU;CAAG;AAE9C;;GAEG;AACH,MAAM,UAAU,eAAe,CAAwB,KAAgC,EAAE,GAAM;IAC7F,IAAI,KAAK,EAAE;QAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;KAAE;IACtC,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,GAAQ;IACzB,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,YAAa,SAAQ,KAAK;IAC9B,gBAAgB,KAAK,EAAE,CAAC,CAAC,CAAC;IAEnB,WAAW,CAAI,QAA2B,EAAE,UAAc;QAC/D,MAAM,GAAG,GAAG,IAAI,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACtD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAM,EAAE,GAAG,CAAC,CAAC;QACrC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,KAAiB;QACrC,IAAI;YACF,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,KAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;SACnD;gBAAS;YACR,IAAI,CAAC,YAAY,EAAE,CAAC;SACrB;IACH,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,eAAgB,SAAQ,KAAK;IAcjC,YAAoB,QAAoB,EAAU,OAAa;QAAI,KAAK,EAAE,CAAC;QAAvD,aAAQ,GAAR,QAAQ,CAAY;QAAU,YAAO,GAAP,OAAO,CAAM;IAAa,CAAC;IAbtE,MAAM,CAAC,OAAO,CAAC,KAAY,EAAE,GAAU,EAAE,KAAiB;QAC/D,OAAO,KAAK,KAAK,GAAG,EAAE;YACpB,MAAM,GAAG,GAAG,KAAwB,CAAC;YACrC,IAAI;gBACF,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;aAChC;YAAC,OAAO,CAAC,EAAE;gBACV,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;aACnG;YACD,KAAK,GAAG,GAAG,CAAC,KAAM,CAAC;SACpB;IACH,CAAC;IAIM,OAAO;QACZ,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE;YAAE,OAAO;SAAE;QAClC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../../../lib/dispose.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/dom.js

@@ -1,21 +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';
@@ -32,6 +14,44 @@ import * as _domImpl from './domImpl';
 import * as _domMethods from './domMethods';
 import * as domevent from './domevent';
 import { dom as _dom } 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(tagString, ...args) {
@@ -73,7 +93,9 @@ export function dom(tagString, ...args) {
     dom.getData = _domMethods.getData;
     dom.replaceContent = _domComputed.replaceContent;
     dom.domComputed = _domComputed.domComputed;
+    dom.domComputedOwned = _domComputed.domComputedOwned;
     dom.maybe = _domComputed.maybe;
+    dom.maybeOwned = _domComputed.maybeOwned;
     dom.forEach = _domForEach.forEach;
     dom.create = _domComponent.create;
     dom.onElem = domevent.onElem;

package/dist/esm/lib/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../lib/dom.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../../lib/dom.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAE3B,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,YAAY,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,QAAQ,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,WAAW,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAC,GAAG,IAAI,IAAI,EAA6B,MAAM,WAAW,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,+FAA+F;AAC/F,mEAAmE;AACnE,MAAM,UAAU,GAAG,CAAsB,SAAc,EAAE,GAAG,IAA4B;IACtF,OAAO,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,mEAAmE;AACnE,WAAiB,GAAG;IACL,OAAG,GAAe,QAAQ,CAAC,GAAG,CAAC;IAC/B,QAAI,GAAc,QAAQ,CAAC,IAAI,CAAC;IAChC,UAAM,GAAY,QAAQ,CAAC,MAAM,CAAC;IAClC,QAAI,GAAc,QAAQ,CAAC,IAAI,CAAC;IAChC,WAAO,GAAW,QAAQ,CAAC,OAAO,CAAC;IAEnC,cAAU,GAAQ,WAAW,CAAC,UAAU,CAAC;IACzC,iBAAa,GAAK,WAAW,CAAC,aAAa,CAAC;IAC5C,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,mBAAe,GAAG,WAAW,CAAC,eAAe,CAAC;IAC9C,eAAW,GAAO,WAAW,CAAC,WAAW,CAAC;IAE1C,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,SAAK,GAAa,WAAW,CAAC,KAAK,CAAC;IACpC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,gBAAY,GAAM,WAAW,CAAC,YAAY,CAAC;IAC3C,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,SAAK,GAAa,WAAW,CAAC,KAAK,CAAC;IACpC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IACtC,OAAG,GAAe,WAAW,CAAC,GAAG,CAAC;IAClC,aAAS,GAAS,WAAW,CAAC,SAAS,CAAC;IACxC,YAAQ,GAAU,WAAW,CAAC,QAAQ,CAAC;IACvC,QAAI,GAAc,WAAW,CAAC,IAAI,CAAC;IACnC,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IACtC,kBAAc,GAAI,YAAY,CAAC,cAAc,CAAC;IAC9C,eAAW,GAAO,YAAY,CAAC,WAAW,CAAC;IAC3C,oBAAgB,GAAG,YAAY,CAAC,gBAAgB,CAAC;IACjD,SAAK,GAAa,YAAY,CAAC,KAAK,CAAC;IACrC,cAAU,GAAQ,YAAY,CAAC,UAAU,CAAC;IAE1C,WAAO,GAAW,WAAW,CAAC,OAAO,CAAC;IAEtC,UAAM,GAAY,aAAa,CAAC,MAAM,CAAC;IAEvC,UAAM,GAAY,QAAQ,CAAC,MAAM,CAAC;IAClC,MAAE,GAAgB,QAAQ,CAAC,EAAE,CAAC;IAC9B,eAAW,GAAO,QAAQ,CAAC,WAAW,CAAC;IACvC,WAAO,GAAW,QAAQ,CAAC,OAAO,CAAC;IACnC,aAAS,GAAS,QAAQ,CAAC,SAAS,CAAC;IACrC,cAAU,GAAQ,QAAQ,CAAC,UAAU,CAAC;IACtC,aAAS,GAAS,QAAQ,CAAC,SAAS,CAAC;AACpD,CAAC,EApDgB,GAAG,KAAH,GAAG,QAoDnB"}

package/dist/esm/lib/domComponent.js

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

package/dist/esm/lib/domComponent.js.map

@@ -1 +1 @@
-{"version":3,"file":"domComponent.js","sourceRoot":"","sources":["../../../lib/domComponent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,OAAO,EAAC,WAAW,EAAC,MAAM,WAAW,CAAC;AACtC,OAAO,EAAC,WAAW,EAAc,MAAM,eAAe,CAAC;AACvD,OAAO,EAAC,eAAe,EAAC,MAAM,cAAc,CAAC;AA0B7C,MAAM,UAAU,MAAM,CAAgC,EAAM,EAAE,GAAG,IAAwB;IACvF,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE;QAC3D,6FAA6F;QAC7F,oFAAoF;QACpF,oDAAoD;QACpD,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvC,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAEnC,MAAM,KAAK,GAAuB,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,EAA6B,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACtD,EAA4B,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7B,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"domComponent.js","sourceRoot":"","sources":["../../../lib/domComponent.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,gBAAgB,EAAc,MAAM,eAAe,CAAC;AAuB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,UAAU,MAAM,CAAgC,EAAM,EAAE,GAAG,IAAwB;IACvF,OAAO,gBAAgB,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE;QACtC,MAAM,KAAK,GAAuB,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;YACjD,EAA6B,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;YACtD,EAA4B,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC;YAClE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/lib/domComputed.js

@@ -1,5 +1,6 @@
 import { subscribeElem } from './binding';
-import { domDispose } from './domDispose';
+import { Holder, MultiHolder } from './dispose';
+import { autoDisposeElem, domDispose } from './domDispose';
 import { frag } from './domImpl';
 // Use the browser globals in a way that allows replacing them with mocks in tests.
 import { G } from './browserGlobals';
@@ -31,6 +32,19 @@ export function domComputed(valueObs, contentFunc = identity) {
             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(valueObs, contentFunc) {
+    const holder = Holder.create(null);
+    const [markerPre, markerPost, func] = domComputed(valueObs, (val) => contentFunc(MultiHolder.create(holder), val));
+    autoDisposeElem(markerPost, holder);
+    return [markerPre, markerPost, func];
+}
 function identity(arg) { return arg; }
 /**
  * Conditionally appends DOM to an element. The value may be an observable or function (from which
@@ -40,21 +54,34 @@ function identity(arg) { return arg; }
  * Note that if the observable changes between different truthy values, contentFunc gets called
  * for each value, and previous content gets destroyed. To consider all truthy values the same,
  * use an observable that returns a proper boolean, e.g.
- *
+ * ```ts
  *    dom.maybe(use => Boolean(use(fooObs)), () => dom(...));
+ * ```
  *
  * As with domComputed(), dom.maybe() may but should not be used when the argument is not an
  * observable or function. The following are equivalent:
- *
+ * ```ts
  *    dom(..., dom.maybe(myValue, () => dom(...)));
  *    dom(..., myValue ? dom(...) : null);
+ * ```
  *
  * The latter is preferred for being simpler.
  *
- * @param boolValueObs: Observable or function for a computed.
- * @param contentFunc: Called with the result of boolValueObs when it is truthy. Should return DOM.
+ * @param boolValueObs - Observable or function for a computed.
+ * @param contentFunc - Called with the result of boolValueObs when it is truthy. Should return DOM.
  */
 export function maybe(boolValueObs, contentFunc) {
     return domComputed(boolValueObs, (value) => value ? contentFunc(value) : null);
 }
+/**
+ * Like maybe(), but the callback gets an additional first argument, owner, which may be used to
+ * take ownership of objects created by the callback. These will be disposed before each new call
+ * to the callback, and when the condition becomes false or the containing DOM gets disposed.
+ * ```ts
+ *    maybeOwned(showEditor, (owner) => Editor.create(owner).renderSomething())
+ * ```
+ */
+export function maybeOwned(boolValueObs, contentFunc) {
+    return domComputedOwned(boolValueObs, (owner, value) => value ? contentFunc(owner, value) : null);
+}
 //# sourceMappingURL=domComputed.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"domComputed.js","sourceRoot":"","sources":["../../../lib/domComputed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,aAAa,EAAC,MAAM,WAAW,CAAC;AACvD,OAAO,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AACxC,OAAO,EAAoB,IAAI,EAAC,MAAM,WAAW,CAAC;AAElD,mFAAmF;AACnF,OAAO,EAAC,CAAC,EAAC,MAAM,kBAAkB,CAAC;AAMnC;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,UAAgB,EAAE,SAAe,EAAE,OAAe;IAC/E,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,UAAU,CAAC,CAAC,CAAC,CAAC;YACd,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;SACrB;QACD,IAAI,OAAO,EAAE;YACX,IAAI,CAAC,YAAY,CAAC,OAAO,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;SACnF;KACF;AACH,CAAC;AAyCD,MAAM,UAAU,WAAW,CACzB,QAA0B,EAAE,cAAkC,QAAe;IAE7E,MAAM,SAAS,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAEjD,gGAAgG;IAChG,yCAAyC;IACzC,OAAO,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,IAAU,EAAE,EAAE;YAC5C,aAAa,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;AAED,SAAS,QAAQ,CAAI,GAAM,IAAO,OAAO,GAAG,CAAC,CAAC,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,KAAK,CAAI,YAA8B,EAAE,WAA4C;IACnG,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"}
+{"version":3,"file":"domComputed.js","sourceRoot":"","sources":["../../../lib/domComputed.ts"],"names":[],"mappings":"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"}