@xtia/jel 0.6.4 → 0.6.5

package/README.md

@@ -137,4 +137,29 @@ element.events.mousemove
 	.apply(([x, y]) => console.log("mouse @ ", x, y));
 ```
 
-For RxJS users, events can be observed with `fromEvent(element.events, "mousemove")`.
+For RxJS users, events can be observed with `fromEvent(element.events, "mousemove")`.
+
+## Reactive styles
+
+Style properties can be emitter subscriptions:
+
+```ts
+const mousePosition$ = $(document.body).events.mousemove
+    .map(ev => ({x: ev.clientX, y: ev.clientY}));
+
+const virtualCursor = $.div({
+    classes: "virtual-cursor",
+    style: {
+        left: mousePosition$.map(v => v.x + "px"),
+        top: mousePosition$.map(v => v.y + "px")
+    }
+});
+```
+
+Emitters for this purpose can be Jel events, [@xtia/timeline](https://github.com/tiadrop/timeline) progressions, RxJS Observables or any object with either `subscribe()` or `listen()` that returns teardown logic.
+
+```ts
+import { animate } from "@xtia/timeline";
+
+button.style.opacity = animate(500).tween(0, 1);
+```

package/index.d.ts

@@ -1,4 +1,6 @@
 export { DomEntity, ElementClassDescriptor, ElementDescriptor, DOMContent, DomHelper, StyleAccessor, JelEntity } from "./internal/types";
-export { $ } from "./internal/element";
+import { $ } from "./internal/element";
 export { createEntity } from "./internal/util";
 export { createEventSource, interval } from "./internal/emitter";
+export { $ };
+export declare const $body: import(".").DomEntity<HTMLElement>;

package/index.js

@@ -1,3 +1,5 @@
-export { $ } from "./internal/element";
+import { $ } from "./internal/element";
 export { createEntity } from "./internal/util";
 export { createEventSource, interval } from "./internal/emitter";
+export { $ };
+export const $body = $(document.body);

package/internal/emitter.d.ts

@@ -1,9 +1,14 @@
 type Handler<T> = (value: T) => void;
 export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
-export declare class Emitter<T> {
+export type Listenable<T> = {
+    subscribe: (callback: (value: T) => void) => UnsubscribeFunc;
+} | {
+    listen: (callback: (value: T) => void) => UnsubscribeFunc;
+};
+export declare class EventEmitter<T> {
     protected onListen: ListenFunc<T>;
-    protected constructor(onListen: ListenFunc<T>);
+    constructor(onListen: ListenFunc<T>);
     protected transform<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
@@ -22,13 +27,13 @@ export declare class Emitter<T> {
      * @param mapFunc
      * @returns Listenable: emits transformed values
      */
-    map<R>(mapFunc: (value: T) => R): Emitter<R>;
+    map<R>(mapFunc: (value: T) => R): EventEmitter<R>;
     /**
      * Creates a chainable emitter that selectively forwards emissions along the chain
      * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
      * @returns Listenable: emits values that pass the filter
      */
-    filter(check: (value: T) => boolean): Emitter<T>;
+    filter(check: (value: T) => boolean): EventEmitter<T>;
     /**
      * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
      * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
@@ -36,7 +41,7 @@ export declare class Emitter<T> {
      * If no `compare` function is provided, values will be compared via `===`
      * @returns Listenable: emits non-repeating values
      */
-    dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>;
+    dedupe(compare?: (a: T, b: T) => boolean): EventEmitter<T>;
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
      *
@@ -48,7 +53,7 @@ export declare class Emitter<T> {
      * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
-    tap(cb: Handler<T>): Emitter<T>;
+    tap(cb: Handler<T>): EventEmitter<T>;
     /**
      * Immediately passes this emitter to a callback and returns this emitter
      *
@@ -66,39 +71,41 @@ export declare class Emitter<T> {
      * ```
      * @param cb
      */
-    fork(cb: (branch: this) => void): this;
-}
-export declare class EventEmitter<T> extends Emitter<T> {
-    constructor(listen: ListenFunc<T>);
+    fork(...cb: ((branch: this) => void)[]): this;
     debounce(ms: number): EventEmitter<T>;
     throttle(ms: number): EventEmitter<T>;
-    batch(ms: number): Emitter<T[]>;
+    batch(ms: number): EventEmitter<T[]>;
     /**
+     * Creates a chainable emitter that
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the parent
-     * until it emits, regardless of subscriptions to this link.
+     * Note: only listens to the parent while at least one downstream subscription is present
      * @param notifier
      * @returns
      */
     once(): EventEmitter<T>;
+    delay(ms: number): EventEmitter<T>;
     scan<S>(updater: (state: S, value: T) => S, initial: S): EventEmitter<S>;
     buffer(count: number): EventEmitter<T[]>;
     /**
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the parent
-     * until emission limit is reached, regardless of subscriptions to this link.
-     * @param notifier
+     * Note: only listens to the notifier while at least one downstream subscription is present
+     * @param limit
      * @returns
      */
     take(limit: number): EventEmitter<T>;
     /**
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the notifier
-     * until it emits, regardless of subscriptions to this link.
+     * Note: only listens to the notifier while at least one downstream subscription is present
      * @param notifier
      * @returns
      */
-    takeUntil(notifier: Emitter<any>): Emitter<T>;
+    takeUntil(notifier: Listenable<any>): EventEmitter<T>;
+    /**
+     * Creates a chainable emitter that forwards its parent's emissions while the predicate returns true
+     * Disconnects from the parent and becomes inert when the predicate returns false
+     * @param predicate Callback to determine whether to keep forwarding
+     */
+    takeWhile(predicate: (value: T) => boolean): EventEmitter<T>;
     /**
      * Creates a chainable emitter that immediately emits a value to every new subscriber,
      * then forwards parent emissions
@@ -106,46 +113,19 @@ export declare class EventEmitter<T> extends Emitter<T> {
      * @returns A new emitter that emits a value to new subscribers and forwards all values from the parent
      */
     immediate(value: T): EventEmitter<T>;
-    cached(): EventEmitter<T>;
-    /**
-     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
-     * @param mapFunc
-     * @returns Listenable: emits transformed values
-     */
-    map<R>(mapFunc: (value: T) => R): EventEmitter<R>;
-    /**
-     * Creates a chainable emitter that selectively forwards emissions along the chain
-     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
-     * @returns Listenable: emits values that pass the filter
-     */
-    filter(check: (value: T) => boolean): EventEmitter<T>;
     /**
-     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
-     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
-     *
-     * If no `compare` function is provided, values will be compared via `===`
-     * @returns Listenable: emits non-repeating values
-     */
-    dedupe(compare?: (a: T, b: T) => boolean): EventEmitter<T>;
-    /**
-     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
-     *
-     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
-     * All listeners attached to the returned emitter receive the same values as the parent emitter.
-     *
-     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
-     *
-     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
-     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     * Creates a chainable emitter that forwards its parent's emissions, and
+     * immediately emits the latest value to new subscribers
+     * @returns
      */
-    tap(cb: Handler<T>): EventEmitter<T>;
+    cached(): EventEmitter<T>;
 }
 /**
  * Creates a linked Emitter and emit() pair
  * @example
  * ```ts
- * function createForm(options: { onsubmit?: (data: FormData) => void }) {
- *   const submitEvents = createEventSource(options.onsubmit);
+ * function createForm(options?: { onsubmit?: (data: FormData) => void }) {
+ *   const submitEvents = createEventSource(options?.onsubmit);
  *   const form = $.form({
  *     on: {
  *       submit: (e) => {
@@ -182,4 +162,10 @@ export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLas
 export declare function interval(t: number | {
     asMilliseconds: number;
 }): EventEmitter<number>;
+export declare function timeoutx(t: number | {
+    asMilliseconds: number;
+}): EventEmitter<void>;
+export declare function timeout(t: number | {
+    asMilliseconds: number;
+}): EventEmitter<void>;
 export {};

package/internal/emitter.js

@@ -1,4 +1,4 @@
-export class Emitter {
+export class EventEmitter {
     constructor(onListen) {
         this.onListen = onListen;
     }
@@ -36,7 +36,7 @@ export class Emitter {
      */
     map(mapFunc) {
         const listen = this.transform((value, emit) => emit(mapFunc(value)));
-        return new Emitter(listen);
+        return new EventEmitter(listen);
     }
     /**
      * Creates a chainable emitter that selectively forwards emissions along the chain
@@ -45,7 +45,7 @@ export class Emitter {
      */
     filter(check) {
         const listen = this.transform((value, emit) => check(value) && emit(value));
-        return new Emitter(listen);
+        return new EventEmitter(listen);
     }
     /**
      * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
@@ -64,7 +64,7 @@ export class Emitter {
                 previous = { value };
             }
         });
-        return new Emitter(listen);
+        return new EventEmitter(listen);
     }
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
@@ -82,7 +82,7 @@ export class Emitter {
             cb(value);
             emit(value);
         });
-        return new Emitter(listen);
+        return new EventEmitter(listen);
     }
     /**
      * Immediately passes this emitter to a callback and returns this emitter
@@ -101,15 +101,10 @@ export class Emitter {
      * ```
      * @param cb
      */
-    fork(cb) {
-        cb(this);
+    fork(...cb) {
+        cb.forEach(cb => cb(this));
         return this;
     }
-}
-export class EventEmitter extends Emitter {
-    constructor(listen) {
-        super(listen);
-    }
     debounce(ms) {
         let reset = null;
         const listen = this.transform((value, emit) => {
@@ -153,20 +148,37 @@ export class EventEmitter extends Emitter {
         return new EventEmitter(listen);
     }
     /**
+     * Creates a chainable emitter that
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the parent
-     * until it emits, regardless of subscriptions to this link.
+     * Note: only listens to the parent while at least one downstream subscription is present
      * @param notifier
      * @returns
      */
     once() {
-        const { emit, listen } = createListenable();
-        const unsub = this.apply(v => {
-            unsub();
-            emit(v);
-        });
+        let parentUnsubscribe = null;
+        let completed = false;
+        const clear = () => {
+            if (parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+        };
+        const { emit, listen } = createListenable(() => {
+            if (completed)
+                return;
+            parentUnsubscribe = this.apply(v => {
+                completed = true;
+                clear();
+                emit(v);
+            });
+        }, clear);
         return new EventEmitter(listen);
     }
+    delay(ms) {
+        return new EventEmitter(this.transform((value, emit) => {
+            setTimeout(() => emit(value), ms);
+        }));
+    }
     scan(updater, initial) {
         let state = initial;
         const listen = this.transform((value, emit) => {
@@ -188,41 +200,101 @@ export class EventEmitter extends Emitter {
     }
     /**
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the parent
-     * until emission limit is reached, regardless of subscriptions to this link.
-     * @param notifier
+     * Note: only listens to the notifier while at least one downstream subscription is present
+     * @param limit
      * @returns
      */
     take(limit) {
-        const { emit, listen } = createListenable();
+        let sourceUnsub = null;
         let count = 0;
-        const unsub = this.apply(v => {
-            if (count < limit) {
-                emit(v);
-                count++;
-                if (count >= limit) {
-                    unsub();
-                }
+        let completed = false;
+        const { emit, listen } = createListenable(() => {
+            if (completed)
+                return;
+            if (!sourceUnsub) {
+                sourceUnsub = this.apply(v => {
+                    if (count < limit) {
+                        emit(v);
+                        count++;
+                        if (count >= limit) {
+                            completed = true;
+                            if (sourceUnsub) {
+                                sourceUnsub();
+                                sourceUnsub = null;
+                            }
+                        }
+                    }
+                });
+            }
+        }, () => {
+            if (sourceUnsub) {
+                sourceUnsub();
+                sourceUnsub = null;
             }
         });
         return new EventEmitter(listen);
     }
     /**
      * **Experimental**: May change in future revisions
-     * Note: potential leak - This link will remain subscribed to the notifier
-     * until it emits, regardless of subscriptions to this link.
+     * Note: only listens to the notifier while at least one downstream subscription is present
      * @param notifier
      * @returns
      */
     takeUntil(notifier) {
-        const { emit, listen } = createListenable();
-        const unsub = this.apply(v => {
-            emit(v);
-        });
-        const unsubNotifier = notifier.apply(() => {
-            unsub();
-            unsubNotifier();
-        });
+        let parentUnsubscribe = null;
+        let notifierUnsub = null;
+        let completed = false;
+        const clear = () => {
+            if (parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+            if (notifierUnsub) {
+                notifierUnsub();
+                notifierUnsub = null;
+            }
+        };
+        const { emit, listen } = createListenable(() => {
+            if (completed)
+                return;
+            parentUnsubscribe = this.apply(emit);
+            const handler = () => {
+                completed = true;
+                clear();
+            };
+            notifierUnsub = "subscribe" in notifier
+                ? notifier.subscribe(handler)
+                : notifier.listen(handler);
+        }, clear);
+        return new EventEmitter(listen);
+    }
+    /**
+     * Creates a chainable emitter that forwards its parent's emissions while the predicate returns true
+     * Disconnects from the parent and becomes inert when the predicate returns false
+     * @param predicate Callback to determine whether to keep forwarding
+     */
+    takeWhile(predicate) {
+        let parentUnsubscribe = null;
+        let completed = false;
+        const clear = () => {
+            if (parentUnsubscribe) {
+                parentUnsubscribe();
+                parentUnsubscribe = null;
+            }
+        };
+        const { emit, listen } = createListenable(() => {
+            if (completed)
+                return;
+            parentUnsubscribe = this.apply(v => {
+                if (predicate(v)) {
+                    emit(v);
+                }
+                else {
+                    completed = true;
+                    clear();
+                }
+            });
+        }, clear);
         return new EventEmitter(listen);
     }
     /**
@@ -237,6 +309,11 @@ export class EventEmitter extends Emitter {
             return this.onListen(handle);
         });
     }
+    /**
+     * Creates a chainable emitter that forwards its parent's emissions, and
+     * immediately emits the latest value to new subscribers
+     * @returns
+     */
     cached() {
         let cache = null;
         let unsub = null;
@@ -254,68 +331,13 @@ export class EventEmitter extends Emitter {
             return listen(handler);
         });
     }
-    /**
-     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
-     * @param mapFunc
-     * @returns Listenable: emits transformed values
-     */
-    map(mapFunc) {
-        const listen = this.transform((value, emit) => emit(mapFunc(value)));
-        return new EventEmitter(listen);
-    }
-    /**
-     * Creates a chainable emitter that selectively forwards emissions along the chain
-     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
-     * @returns Listenable: emits values that pass the filter
-     */
-    filter(check) {
-        const listen = this.transform((value, emit) => check(value) && emit(value));
-        return new EventEmitter(listen);
-    }
-    /**
-     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
-     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
-     *
-     * If no `compare` function is provided, values will be compared via `===`
-     * @returns Listenable: emits non-repeating values
-     */
-    dedupe(compare) {
-        let previous = null;
-        const listen = this.transform((value, emit) => {
-            if (!previous || (compare
-                ? !compare(previous.value, value)
-                : (previous.value !== value))) {
-                emit(value);
-                previous = { value };
-            }
-        });
-        return new EventEmitter(listen);
-    }
-    /**
-     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
-     *
-     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
-     * All listeners attached to the returned emitter receive the same values as the parent emitter.
-     *
-     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
-     *
-     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
-     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
-     */
-    tap(cb) {
-        const listen = this.transform((value, emit) => {
-            cb(value);
-            emit(value);
-        });
-        return new EventEmitter(listen);
-    }
 }
 /**
  * Creates a linked Emitter and emit() pair
  * @example
  * ```ts
- * function createForm(options: { onsubmit?: (data: FormData) => void }) {
- *   const submitEvents = createEventSource(options.onsubmit);
+ * function createForm(options?: { onsubmit?: (data: FormData) => void }) {
+ *   const submitEvents = createEventSource(options?.onsubmit);
  *   const form = $.form({
  *     on: {
  *       submit: (e) => {
@@ -381,3 +403,12 @@ export function interval(t) {
     }, () => clearInterval(intervalId));
     return new EventEmitter(listen);
 }
+export function timeoutx(t) {
+    return interval(t).once().map(() => { });
+}
+export function timeout(t) {
+    const ms = typeof t === "number" ? t : t.asMilliseconds;
+    const { emit, listen } = createListenable();
+    setTimeout(emit, ms);
+    return new EventEmitter(listen);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/jel",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "repository": {
     "url": "https://github.com/tiadrop/jel-ts",
     "type": "github"
@@ -15,7 +15,11 @@
     },
     "./internal/*": null
   },
-  "description": "Lightweight DOM manipulation and componentisation",
+  "scripts": {
+    "prepublishOnly": "cp ../README.md .",
+    "postpublish": "rm README.md"
+  },
+  "description": "Lightweight DOM manipulation, componentisation and reactivity",
   "keywords": [
     "dom"
   ],