aberdeen 0.2.3 → 0.4.0

package/dist/aberdeen.d.ts

@@ -1,9 +1,17 @@
 /**
- * Schedule a DOM read operation to be executed in Aberdeen's internal task queue.
+ * Normally, changes to `Store`s are reacted to asynchronously, in an (optimized)
+ * batch, after a timeout of 0s. Calling `runQueue()` will do so immediately
+ * and synchronously. Doing so may be helpful in cases where you need some DOM
+ * modification to be done synchronously.
  *
- * This function is used to batch DOM read operations together, avoiding unnecessary
- * layout recalculations and improving browser performance. A DOM read operation should
- * only *read* from the DOM, such as measuring element dimensions or retrieving computed styles.
+ * This function is re-entrant, meaning it is safe to call `runQueue` from a
+ * function that is called due to another (automatic) invocation of `runQueue`.
+ */
+export declare function runQueue(): void;
+/**
+ * A promise-like object that you can `await`. It will resolve *after* the current batch
+ * of DOM-write operations has completed. This is the best time to retrieve DOM properties
+ * that dependent on a layout being completed, such as `offsetHeight`.
  *
  * By batching DOM reads separately from DOM writes, this prevents the browser from
  * interleaving layout reads and writes, which can force additional layout recalculations.
@@ -13,15 +21,16 @@
  * Unlike `setTimeout` or `requestAnimationFrame`, this mechanism ensures that DOM read
  * operations happen before any DOM writes in the same queue cycle, minimizing layout thrashing.
  *
- * @param func The function to be executed as a DOM read operation.
+ * See `transitions.js` for some examples.
  */
-export declare function scheduleDomReader(func: () => void): void;
+export declare const DOM_READ_PHASE: {
+    then: (fulfilled: () => void) => any;
+};
 /**
- * Schedule a DOM write operation to be executed in Aberdeen's internal task queue.
- *
- * This function is used to batch DOM write operations together, avoiding unnecessary
- * layout recalculations and improving browser performance. A DOM write operation should
- * only *write* to the DOM, such as modifying element properties or applying styles.
+ * A promise-like object that you can `await`. It will resolve *after* the current
+ * DOM_READ_PHASE has completed (if any) and after any DOM triggered by Aberdeen
+ * have completed. This is a good time to do little manual DOM tweaks that depend
+ * on a *read phase* first, like triggering transitions.
  *
  * By batching DOM writes separately from DOM reads, this prevents the browser from
  * interleaving layout reads and writes, which can force additional layout recalculations.
@@ -31,34 +40,35 @@ export declare function scheduleDomReader(func: () => void): void;
  * Unlike `setTimeout` or `requestAnimationFrame`, this mechanism ensures that DOM write
  * operations happen after all DOM reads in the same queue cycle, minimizing layout thrashing.
  *
- * @param func The function to be executed as a DOM write operation.
- */
-export declare function scheduleDomWriter(func: () => void): void;
-/**
- * A data store that automatically subscribes the current scope to updates
- * whenever data is read from it.
- *
- * Supported data types are: `string`, `number`, `boolean`, `undefined`, `null`,
- * `Array`, `object` and `Map`. The latter three will always have `Store` objects as
- * values, creating a tree of `Store`-objects.
+ * See `transitions.js` for some examples.
  */
+export declare const DOM_WRITE_PHASE: {
+    then: (fulfilled: () => void) => any;
+};
+export interface Store {
+    /**
+     * Return a `Store` deeper within the tree by resolving the given `path`,
+     * subscribing to every level.
+     * In case `undefined` is encountered while resolving the path, a newly
+     * created `Store` containing `undefined` is returned. In that case, the
+     * `Store`'s [[`isDetached`]] method will return `true`.
+     * In case something other than a collection is encountered, an error is thrown.
+     */
+    (...path: any[]): Store;
+}
 export declare class Store {
     /**
-     * Create a new store with the given `value` as its value. Defaults to `undefined` if no value is given.
-     * When the value is a plain JavaScript object, an `Array` or a `Map`, it will be stored as a tree of
-     * `Store`s. (Calling {@link Store.get} on the store will recreate the original data strucure, though.)
-     *
-     * @example
-     * ```
-     * let emptyStore = new Store()
-     * let numStore = new Store(42)
-     * let objStore = new Store({x: {alice: 1, bob: 2}, y: [9,7,5,3,1]})
-     * ```
-    */
+     * Create a new `Store` with `undefined` as its initial value.
+     */
     constructor();
+    /**
+     * Create a new `Store`.
+     * @param value The initial value. Plain objects, arrays and `Map`s, are converted
+     * into a tree of nested `Store`s. When another `Store` is included somewhere in that
+     * input tree, a reference is made.
+     */
     constructor(value: any);
     /**
-     *
      * @returns The index for this Store within its parent collection. This will be a `number`
      * when the parent collection is an array, a `string` when it's an object, or any data type
      * when it's a `Map`.
@@ -67,135 +77,124 @@ export declare class Store {
      * ```
      * let store = new Store({x: 123})
      * let subStore = store.ref('x')
-     * assert(subStore.get() === 123)
-     * assert(subStore.index() === 'x') // <----
+     * subStore.get() // 123
+     * subStore.index() // 'x'
      * ```
      */
     index(): any;
     /**
-     * @returns Resolves `path` and then retrieves the value that is there, subscribing
-     * to all read `Store` values. If `path` does not exist, `undefined` is returned.
-     * @param path - Any path terms to resolve before retrieving the value.
-     * @example
-     * ```
-     * let store = new Store({a: {b: {c: {d: 42}}}})
-     * assert('a' in store.get())
-     * assert(store.get('a', 'b') === {c: {d: 42}})
-     * ```
+     * Retrieve the value for store, subscribing the observe scope to changes.
+     *
+     * @param depth Limit the depth of the retrieved data structure to this positive integer.
+     *    When `depth` is `1`, only a single level of the value at `path` is unpacked. This
+     *    makes no difference for primitive values (like strings), but for objects, maps and
+     *    arrays, it means that each *value* in the resulting data structure will be a
+     *    reference to the `Store` for that value.
+     *
+     * @returns The resulting value (or `undefined` if the `Store` does not exist).
+     */
+    get(depth?: number): any;
+    /**
+     * Exactly like {@link Store.get}, except that when executed from an observe scope,
+     * we will not subscribe to changes in the data retrieved data.
      */
-    get(...path: any[]): any;
+    peek(depth?: number): any;
     /**
-     * Like {@link Store.get}, but doesn't subscribe to changes.
+     * Like {@link Store.get}, but with return type checking.
+     *
+     * @param expectType A string specifying what type the.get is expected to return. Options are:
+     *    "undefined", "null", "boolean", "number", "string", "function", "array", "map"
+     *    and "object". If the store holds a different type of value, a `TypeError`
+     *    exception is thrown.
+     * @returns
      */
-    peek(...path: any[]): any;
+    getTyped(expectType: String, depth?: number): any;
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `number`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getNumber(...path: any[]): number;
+    getNumber(): number;
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `string`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getString(...path: any[]): string;
+    getString(): string;
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `boolean`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getBoolean(...path: any[]): boolean;
+    getBoolean(): boolean;
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `function`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getFunction(...path: any[]): (Function);
+    getFunction(): (Function);
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `array`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getArray(...path: any[]): any[];
+    getArray(depth?: number): any[];
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `object`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getObject(...path: any[]): object;
+    getObject(depth?: number): object;
     /**
      * @returns Like {@link Store.get}, but throws a `TypeError` if the resulting value is not of type `map`.
      * Using this instead of just {@link Store.get} is especially useful from within TypeScript.
      */
-    getMap(...path: any[]): Map<any, any>;
+    getMap(depth?: number): Map<any, any>;
     /**
-     * Like {@link Store.get}, but the first parameter is the default value (returned when the Store
+     * Like {@link Store.get}, but with a default value (returned when the Store
      * contains `undefined`). This default value is also used to determine the expected type,
      * and to throw otherwise.
      *
      * @example
      * ```
-     * let store = {x: 42}
-     * assert(getOr(99, 'x') == 42)
-     * assert(getOr(99, 'y') == 99)
-     * getOr('hello', x') # throws TypeError (because 42 is not a string)
+     * let store = new Store({x: 42})
+     * store('x').getOr(99) // 42
+     * store('y').getOr(99) // 99
+     * store('x').getOr('hello') // throws TypeError (because 42 is not a string)
      * ```
      */
-    getOr<T>(defaultValue: T, ...path: any[]): T;
-    /** Retrieve a value, subscribing to all read `Store` values. This is a more flexible
-     * form of the {@link Store.get} and {@link Store.peek} methods.
-     *
-     * @returns The resulting value, or `undefined` if the `path` does not exist.
-     */
-    query(opts: {
-        /**  The value for this path should be retrieved. Defaults to `[]`, meaning the entire `Store`. */
-        path?: any[];
-        /** A string specifying what type the query is expected to return. Options are:
-         *  "undefined", "null", "boolean", "number", "string", "function", "array", "map"
-         *  and "object". If the store holds a different type of value, a `TypeError`
-         *  exception is thrown. By default (when `type` is `undefined`) no type checking
-         *  is done.
-         */
-        type?: string;
-        /** Limit the depth of the retrieved data structure to this positive integer.
-        *  When `depth` is `1`, only a single level of the value at `path` is unpacked. This
-        *  makes no difference for primitive values (like strings), but for objects, maps and
-        *  arrays, it means that each *value* in the resulting data structure will be a
-        *  reference to the `Store` for that value.
-        */
-        depth?: number;
-        /** Return this value when the `path` does not exist. Defaults to `undefined`. */
-        defaultValue?: any;
-        /** When peek is `undefined` or `false`, the current scope will automatically be
-         * subscribed to changes of any parts of the store being read. When `true`, no
-         * subscribers will be performed.
-         */
-        peek?: boolean;
-    }): any;
+    getOr<T>(defaultValue: T): T;
     /**
-     * Checks if the specified collection is empty, and subscribes the current scope to changes of the emptiness of this collection.
+     * Checks if the collection held in `Store` is empty, and subscribes the current scope to changes of the emptiness of this collection.
      *
-     * @param path Any path terms to resolve before retrieving the value.
-     * @returns When the specified collection is not empty `true` is returned. If it is empty or if the value is undefined, `false` is returned.
+     * @returns When the collection is not empty `true` is returned. If it is empty or if the value is undefined, `false` is returned.
      * @throws When the value is not a collection and not undefined, an Error will be thrown.
      */
-    isEmpty(...path: any[]): boolean;
+    isEmpty(): boolean;
     /**
-     * Returns the number of items in the specified collection, and subscribes the current scope to changes in this count.
+     * Returns the number of items in the collection held in Store, and subscribes the current scope to changes in this count.
      *
-     * @param path Any path terms to resolve before retrieving the value.
      * @returns The number of items contained in the collection, or 0 if the value is undefined.
      * @throws When the value is not a collection and not undefined, an Error will be thrown.
      */
-    count(...path: any[]): number;
+    count(): number;
     /**
-     * Returns a strings describing the type of the store value, subscribing to changes of this type.
+     * Returns a strings describing the type of the `Store` value, subscribing to changes of this type.
      * Note: this currently also subscribes to changes of primitive values, so changing a value from 3 to 4
      * would cause the scope to be rerun. This is not great, and may change in the future. This caveat does
      * not apply to changes made *inside* an object, `Array` or `Map`.
      *
-     * @param path Any path terms to resolve before retrieving the value.
      * @returns Possible options: "undefined", "null", "boolean", "number", "string", "function", "array", "map" or "object".
      */
-    getType(...path: any[]): string;
+    getType(): string;
     /**
-     * Sets the value to the last given argument. Any earlier argument are a Store-path that is first
-     * resolved/created using {@link Store.makeRef}.
+     * Returns a new `Store` that will always hold either the value of `whenTrue` or the value
+     * of `whenFalse` depending on whether the original `Store` is truthy or not.
+     *
+     * @param whenTrue The value set to the return-`Store` while `this` is truthy. This can be
+     *     any type of value. If it's a `Store`, the return-`Store` will reference the same
+     *     data (so *no* deep copy will be made).
+     * @param whenFalse Like `whenTrue`, but for falsy values (false, undefined, null, 0, "").
+     * @returns A store holding the result value. The value will keep getting updated while
+     * the observe context from which `if()` was called remains active.
+     */
+    if(whenTrue: any[], whenFalse?: any[]): Store;
+    /**
+     * Sets the `Store` value to the given argument.
      *
      * When a `Store` is passed in as the value, its value will be copied (subscribing to changes). In
      * case the value is an object, an `Array` or a `Map`, a *reference* to that data structure will
@@ -205,118 +204,119 @@ export declare class Store {
      *
      * If you intent to make a copy instead of a reference, call {@link Store.get} on the origin `Store`.
      *
+     * @returns The `Store` itself, for chaining other methods.
      *
      * @example
      * ```
      * let store = new Store() // Value is `undefined`
      *
-     * store.set('x', 6) // Causes the store to become an object
-     * assert(store.get() == {x: 6})
+     * store.set(6)
+     * store.get() // 6
      *
-     * store.set('a', 'b', 'c', 'd') // Create parent path as objects
-     * assert(store.get() == {x: 6, a: {b: {c: 'd'}}})
+     * store.set({}) // Change  value to an empty object
+     * store('a', 'b', 'c').set('d') // Create parent path as objects
+     * store.get() // {x: 6, a: {b: {c: 'd'}}}
      *
      * store.set(42) // Overwrites all of the above
-     * assert(store.get() == 42)
+     * store.get() // 42
      *
-     * store.set('x', 6) // Throw Error (42 is not a collection)
+     * store('x').set(6) // Throw Error (42 is not a collection)
      * ```
      */
-    set(...pathAndValue: any[]): void;
+    set(newValue: any): Store;
     /**
      * Sets the `Store` to the given `mergeValue`, but without deleting any pre-existing
      * items when a collection overwrites a similarly typed collection. This results in
      * a deep merge.
      *
+     * @returns The `Store` itself, for chaining other methods.
+     *
      * @example
      * ```
      * let store = new Store({a: {x: 1}})
      * store.merge({a: {y: 2}, b: 3})
-     * assert(store.get() == {a: {x: 1, y: 2}, b: 3})
+     * store.get() // {a: {x: 1, y: 2}, b: 3}
      * ```
      */
-    merge(...pathAndValue: any): void;
+    merge(mergeValue: any): Store;
     /**
      * Sets the value for the store to `undefined`, which causes it to be omitted from the map (or array, if it's at the end)
      *
+     * @returns The `Store` itself, for chaining other methods.
+     *
      * @example
      * ```
      * let store = new Store({a: 1, b: 2})
-     * store.delete('a')
-     * assert(store.get() == {b: 2})
+     * store('a').delete()
+     * store.get() // {b: 2}
      *
      * store = new Store(['a','b','c'])
-     * store.delete(1)
-     * assert(store.get() == ['a', undefined, 'c'])
-     * store.delete(2)
-     * assert(store.get() == ['a'])
+     * store(1).delete()
+     * store.get() // ['a', undefined, 'c']
+     * store(2).delete()
+     * store.get() // ['a']
+     * store.delete()
+     * store.get() // undefined
      * ```
      */
-    delete(...path: any): void;
+    delete(): Store;
     /**
      * Pushes a value to the end of the Array that is at the specified path in the store.
      * If that store path is `undefined`, an Array is created first.
      * The last argument is the value to be added, any earlier arguments indicate the path.
      *
+     * @returns The index at which the item was appended.
+     * @throws TypeError when the store contains a primitive data type.
+     *
      * @example
      * ```
      * let store = new Store()
      * store.push(3) // Creates the array
      * store.push(6)
-     * assert(store.get() == [3,6])
+     * store.get() // [3,6]
      *
      * store = new Store({myArray: [1,2]})
-     * store.push('myArray', 3)
-     * assert(store.get() == {myArray: [1,2,3]})
+     * store('myArray').push(3)
+     * store.get() // {myArray: [1,2,3]}
      * ```
      */
-    push(...pathAndValue: any[]): number;
+    push(newValue: any): number;
     /**
      * {@link Store.peek} the current value, pass it through `func`, and {@link Store.set} the resulting
      * value.
      * @param func The function transforming the value.
+     * @returns The `Store` itself, for chaining other methods.
      */
-    modify(func: (value: any) => any): void;
-    /**
-     * Return a `Store` deeper within the tree by resolving the given `path`,
-     * subscribing to every level.
-     * In case `undefined` is encountered while resolving the path, a newly
-     * created `Store` containing `undefined` is returned. In that case, the
-     * `Store`'s {@link Store.isDetached} method will return `true`.
-     * In case something other than a collection is encountered, an error is thrown.
-     */
-    ref(...path: any[]): Store;
-    /**
-     * Similar to `ref()`, but instead of returning `undefined`, new objects are created when
-     * a path does not exist yet. An error is still thrown when the path tries to index an invalid
-     * type.
-     * Unlike `ref`, `makeRef` does *not* subscribe to the path levels, as it is intended to be
-     * a write-only operation.
-     *
-     * @example
-     * ```
-     * let store = new Store() // Value is `undefined`
-     *
-     * let ref = store.makeRef('a', 'b', 'c')
-     * assert(store.get() == {a: {b: {}}}
-     *
-     * ref.set(42)
-     * assert(store.get() == {a: {b: {c: 42}}}
-     *
-     * ref.makeRef('d') // Throw Error (42 is not a collection)
-     * ```
-     */
-    makeRef(...path: any[]): Store;
+    modify(func: (value: any) => any): Store;
     /**
      * Iterate the specified collection (Array, Map or object), running the given code block for each item.
      * When items are added to the collection at some later point, the code block will be ran for them as well.
      * When an item is removed, the {@link Store.clean} handlers left by its code block are executed.
      *
-     *
-     *
-     * @param pathAndFuncs
+     * @param renderer The function to be called for each item. It receives the item's `Store` object as its only argument.
+     * @param makeSortKey An optional function that, given an items `Store` object, returns a value to be sorted on.
+     *   This value can be a number, a string, or an array containing a combination of both. When undefined is returned,
+     *   the item is *not* rendered. If `makeSortKey` is not specified, the output will be sorted by `index()`.
+     */
+    onEach(renderer: (store: Store) => void, makeSortKey?: (store: Store) => any): void;
+    /**
+     * Derive a new `Store` from this `Store`, by reactively passing its value
+     * through the specified function.
+     * @param func Your function. It should accept a the input store's value, and return
+     *   a result to be reactively set to the output store.
+     * @returns The output `Store`.
+     * @example
+     * ```javascript
+     * const store = new Store(21)
+     * const double = store.derive(v => v*2)
+     * double.get() // 42
+     *
+     * store.set(100)
+     * runQueue() // Or after a setTimeout 0, due to batching
+     * double.get() // 200
+     * ```
      */
-    onEach(...pathAndFuncs: any): void;
+    derive(func: (value: any) => any): Store;
     /**
      * Applies a filter/map function on each item within the `Store`'s collection,
      * and reactively manages the returned `Map` `Store` to hold any results.
@@ -324,8 +324,8 @@ export declare class Store {
      * @param func - Function that transform the given store into an output value or
      * `undefined` in case this value should be skipped:
      *
-     * @returns - A map `Store` with the values returned by `func` and the corresponding
-     * keys from the original map, array or object `Store`.
+     * @returns - A array/map/object `Store` with the values returned by `func` and the
+     * corresponding keys from the original map, array or object `Store`.
      *
      * When items disappear from the `Store` or are changed in a way that `func` depends
      * upon, the resulting items are removed from the output `Store` as well. When multiple
@@ -349,108 +349,136 @@ export declare class Store {
      * input items produce the same output keys, this may lead to unexpected results.
      */
     multiMap(func: (store: Store) => any): Store;
-    /**
-     * @returns Returns `true` when the `Store` was created by {@link Store.ref}ing a path that
-     * does not exist.
-     */
-    isDetached(): boolean;
     /**
     * Dump a live view of the `Store` tree as HTML text, `ul` and `li` nodes at
     * the current mount position. Meant for debugging purposes.
+    * @returns The `Store` itself, for chaining other methods.
     */
-    dump(): void;
+    dump(): Store;
 }
 /**
- * Create a new DOM element, and insert it into the DOM at the position held by the current scope.
- * @param tag - The tag of the element to be created and optionally dot-separated class names. For example: `h1` or `p.intro.has_avatar`.
- * @param rest - The other arguments are flexible and interpreted based on their types:
- *   - `string`: Used as textContent for the element.
- *   - `object`: Used as attributes, properties or event listeners for the element. See {@link Store.prop} on how the distinction is made and to read about a couple of special keys.
- *   - `function`: The render function used to draw the scope of the element. This function gets its own `Scope`, so that if any `Store` it reads changes, it will redraw by itself.
- *   - `Store`: Presuming `tag` is `"input"`, `"textarea"` or `"select"`, create a two-way binding between this `Store` value and the input element. The initial value of the input will be set to the initial value of the `Store`, or the other way around if the `Store` holds `undefined`. After that, the `Store` will be updated when the input changes and vice versa.
- * @example
- * node('aside.editorial', 'Yada yada yada....', () => {
- *	 node('a', {href: '/bio'}, () => {
- *		 node('img.author', {src: '/me.jpg', alt: 'The author'})
- *	 })
+ * Modifies the *parent* DOM element in the current reactive scope, or adds
+ * new DOM elements to it.
+ *
+ * @param args - Arguments that define how to modify/create elements.
+ *
+ * ### String arguments
+ * Create new elements with optional classes and text content:
+ * ```js
+ * $('div.myClass')              // <div class="myClass"></div>
+ * $('span.c1.c2:Hello')         // <span class="c1 c2">Hello</span>
+ * $('p:Some text')              // <p>Some text</p>
+ * $('.my-thing')                // <div class="my-thing"></div>
+ * $('div', 'span', 'p.cls')     // <div><span<p class="cls"></p></span></div>
+ * $(':Just some text!')		 // Just some text! (No new element, just a text node)
+ * ```
+ *
+ * ### Object arguments
+ * Set properties, attributes, events and special features:
+ * ```js
+ * // Classes (dot prefix)
+ * $('div', {'.active': true})           // Add class
+ * $('div', {'.hidden': false})          // Remove (or don't add) class
+ * $('div', {'.selected': myStore})      // Reactively add/remove class
+ *
+ * // Styles (dollar prefixed and camel-cased CSS properties)
+ * $('div', {$color: 'red'})             // style.color = 'red'
+ * $('div', {$marginTop: '10px'})        // style.marginTop = '10px'
+ * $('div', {$color: myColorStore})      // Reactively change color
+ *
+ * // Events (function values)
+ * $('button', {click: () => alert()})   // Add click handler
+ *
+ * // Properties (boolean values, `selectedIndex`, `value`)
+ * $('input', {disabled: true})          // el.disabled = true
+ * $('input', {value: 'test'})           // el.value = 'test'
+ * $('select', {selectedIndex: 2})       // el.selectedIndex = 2
+ *
+ * // Transitions
+ * $('div', {create: 'fade-in'})         // Add class on create
+ * $('div', {create: el => {...}})       // Run function on create
+ * $('div', {destroy: 'fade-out'})       // Add class before remove
+ * $('div', {destroy: el => {...}})      // Run function before remove
+ *
+ * // Content
+ * $('div', {html: '<b>Bold</b>'})       // Set innerHTML
+ * $('div', {text: 'Plain text'})        // Add text node
+ * const myElement = document.createElement('video')
+ * $('div', {element: myElement})        // Add existing DOM element
+ *
+ * // Regular attributes (everything else)
+ * $('div', {title: 'Info'})             // el.setAttribute('title', 'info')
+ * ```
+ *
+ * When a `Store` is passed as a value, a seperate observe-scope will
+ * be created for it, such that when the `Store` changes, only *that*
+ * UI property will need to be updated.
+ * So in the following example, when `colorStore` changes, only the
+ * `color` CSS property will be updated.
+ * ```js
+ * $('div', {
+ *   '.active': activeStore,             // Reactive class
+ *   $color: colorStore,                 // Reactive style
+ *   text: textStore                     // Reactive text
  * })
+ * ```
+ *
+ * ### Two-way input binding
+ * Set the initial value of an <input> <textarea> or <select> to that
+ * of a `Store`, and then start reflecting user changes to the former
+ * in the latter.
+ * ```js
+ * $('input', {bind: myStore})           // Binds input.value
+ * ```
+ * This is a special case, as changes to the `Store` will *not* be
+ * reflected in the UI.
+ *
+ * ### Function arguments
+ * Create child scopes that re-run on observed `Store` changes:
+ * ```js
+ * $('div', () => {
+ *   $(myStore.get() ? 'span' : 'p')     // Reactive element type
+ * })
+ * ```
+ * When *only* a function is given, `$` behaves exactly like {@link Store.observe},
+ * except that it will only work when we're inside a `mount`.
+ *
+ * @throws {ScopeError} If called outside an observable scope.
+ * @throws {Error} If invalid arguments are provided.
  */
-export declare function node(tag?: string | Element, ...rest: any[]): void;
-/**
- * Convert an HTML string to one or more DOM elements, and add them to the current DOM scope.
- * @param html - The HTML string. For example `"<section><h2>Test</h2><p>Info..</p></section>"`.
- */
-export declare function html(html: string): void;
-/**
- * Add a text node at the current Scope position.
- */
-export declare function text(text: string): void;
+export declare function $(...args: (string | (() => void) | false | null | undefined | {
+    [key: string]: any;
+})[]): void;
 /**
- * Set properties and attributes for the containing DOM element. Doing it this way
- * as opposed to setting them directly from node() allows changing them later on
- * without recreating the element itself. Also, code can be more readable this way.
- * Note that when a nested `observe()` is used, properties set this way do NOT
- * automatically revert to their previous values.
- *
- * Here's how properties are handled:
- * - If `name` is `"create"`, `value` should be either a function that gets
- *   called with the element as its only argument immediately after creation,
- *   or a string being the name of a CSS class that gets added immediately
- *   after element creation, and removed shortly afterwards. This allows for
- *   reveal animations. However, this is intentionally *not* done
- *   for elements that are created as part of a larger (re)draw, to prevent
- *   all elements from individually animating on page creation.
- * - If `name` is `"destroy"`, `value` should be a function that gets called
- *   with the element as its only argument, *instead of* the element being
- *   removed from the DOM (which the function will presumably need to do
- *   eventually). This can be used for a conceal animation.
- *   As a convenience, it's also possible to provide a string instead of
- *   a function, which will be added to the element as a CSS class, allowing
- *   for simple transitions. In this case, the DOM element in removed 2 seconds
- *   later (currently not configurable).
- *   Similar to `"create"` (and in this case doing anything else would make little
- *   sense), this only happens when the element being is the top-level element
- *   being removed from the DOM.
- * - If `value` is a function, it is registered as an event handler for the
- *   `name` event.
- * - If `name` is `"class"` or `"className"` and the `value` is an
- *   object, all keys of the object are either added or removed from `classList`,
- *   depending on whether `value` is true-like or false-like.
- * - If `value` is a boolean *or* `name` is `"value"`, `"className"` or
- *   `"selectedIndex"`, it is set as a DOM element *property*.
- * - If `name` is `"text"`, the `value` is set as the element's `textContent`.
- * - If `name` is `"style"` and `value` is an object, each of its
- *   key/value pairs are assigned to the element's `.style`.
- * - In other cases, the `value` is set as the `name` HTML *attribute*.
+ * Set a custome error handling function, thast is called when an error occurs during rendering
+ * while in a reactive scope. The default implementation logs the error to the console, and then
+ * just returns `true`, which causes an 'Error' message to be displayed in the UI. When this function
+ * returns `false`, the error is suppressed. This mechanism exists because rendering errors can occur
+ * at any time, not just synchronous when making a call to Aberdeen, thus normal exception handling
+ * is not always possible.
+ *
+ * @param handler The handler function, getting an `Error` as its argument, and returning `false`
+ *    if it does *not* want an error message to be added to the DOM.
+ *    When `handler is `undefined`, the default error handling will be reinstated.
  *
  * @example
- * ```
- * node('input', () => {
- *	   prop('type', 'password')
- *	   prop('readOnly', true)
- *	   prop('class', 'my-class')
- *	   prop('class', {
- *	   		'my-disabled-class': false,
- *	   		'my-enabled-class': true,
- *	   })
- *	   prop({
- *	   		class: 'my-class',
- *	   		text: 'Here is something to read...',
- *	   		style: {
- *	   			backgroundColor: 'red',
- *	   			fontWeight: 'bold',
- *	   		},
- *	   		create: aberdeen.fadeIn,
- *	   		destroy: 'my-fade-out-class',
- *	   		click: myClickHandler,
- *	   })
+ * ```javascript
+ * //
+ * setErrorHandler(error => {
+ *    // Tell our developers about the problem.
+ * 	  fancyErrorLogger(error)
+ *    // Add custom error message to the DOM.
+ *    try {
+ *        $('.error:Sorry, something went wrong!')
+ *    } catch() {} // In case there is no parent element.
+ *    // Don't add default error message to the DOM.
+ * 	  return false
  * })
  * ```
  */
-export declare function prop(name: string, value: any): void;
-export declare function prop(props: object): void;
+export declare function setErrorHandler(handler?: (error: Error) => boolean | undefined): void;
 /**
- * Return the browser Element that `node()`s would be rendered to at this point.
+ * Return the browser Element that nodes would be rendered to at this point.
  * NOTE: Manually changing the DOM is not recommended in most cases. There is
  * usually a better, declarative way. Although there are no hard guarantees on
  * how your changes interact with Aberdeen, in most cases results will not be
@@ -497,10 +525,10 @@ export declare function observe(func: () => void): number | undefined;
  */
 export declare function immediateObserve(func: () => void): number | undefined;
 /**
- * Like {@link Store.observe}, but allow the function to create DOM elements using {@link Store.node}.
+ * Reactively run the function, adding any DOM-elements created using {@link $} to the given parent element.
 
  * @param func - The function to be (repeatedly) executed, possibly adding DOM elements to `parentElement`.
- * @param parentElement - A DOM element that will be used as the parent element for calls to `node`.
+ * @param parentElement - A DOM element that will be used as the parent element for calls to `$`.
  * @returns The mount id (usable for `unmount`) if this is a top-level mount.
  *
  * @example
@@ -509,7 +537,7 @@ export declare function immediateObserve(func: () => void): number | undefined;
  * setInterval(() => store.modify(v => v+1), 1000)
  *
  * mount(document.body, () => {
- * 	   node('h2', `${store.get()} seconds have passed`)
+ * 	   $(`h2:${store.get()} seconds have passed`)
  * })
  * ```
  *
@@ -519,21 +547,21 @@ export declare function immediateObserve(func: () => void): number | undefined;
  * let colors = new Store(new Map())
  *
  * mount(document.body, () => {
- * 	// This function will never rerun (as it does not read any `Store`s)
- * 	node('button', '<<', {click: () => selected.modify(n => n-1)})
- * 	node('button', '>>', {click: () => selected.modify(n => n+1)})
- *
- * 	observe(() => {
- * 		// This will rerun whenever `selected` changes, recreating the <h2> and <input>.
- * 		node('h2', '#'+selected.get())
- * 		node('input', {type: 'color', value: '#ffffff'}, colors.ref(selected.get()))
- * 	})
- *
- * 	observe(() => {
- * 		// This function will rerun when `selected` or the selected color changes.
- * 		// It will change the <body> background-color.
- * 		prop({style: {backgroundColor: colors.get(selected.get()) || 'white'}})
- * 	})
+ *   // This function will never rerun (as it does not read any `Store`s)
+ *   $('button:<<', {click: () => selected.modify(n => n-1)})
+ *   $('button:>>', {click: () => selected.modify(n => n+1)})
+ *
+ *   observe(() => {
+ *     // This will rerun whenever `selected` changes, recreating the <h2> and <input>.
+ *     $('h2', {text: '#' + selected.get()})
+ *     $('input', {type: 'color', value: '#ffffff' bind: colors(selected.get())})
+ *   })
+ *
+ *   observe(() => {
+ *     // This function will rerun when `selected` or the selected color changes.
+ *     // It will change the <body> background-color.
+ *     $({$backgroundColor: colors.get(selected.get()) || 'white'})
+ *   })
  * })
  * ```
 */
@@ -566,8 +594,8 @@ export declare function unmount(id?: number): void;
  * for `count()` however.
  */
 export declare function peek<T>(func: () => T): T;
-/**
- * Run a function, while *not* causing reactive effects for any changes it makes to `Store`s.
- * @param func The function to be executed once immediately.
- */
-export declare function inhibitEffects(func: () => void): void;
+declare global {
+    interface String {
+        replaceAll(from: string, to: string): string;
+    }
+}