@xtia/jel 0.11.1 → 0.11.2

package/README.md

@@ -188,4 +188,120 @@ Emitters for this purpose can be Jel events, [@xtia/timeline](https://github.com
 import { animate } from "@xtia/timeline";
 
 button.style.opacity = animate(500).tween(0, 1);
-```
+```
+
+## Custom streams
+
+Several utilities are provided to create event streams from existing sources and custom emit logic.
+
+### `toEventEmitter(source)`
+
+Creates an `EventEmitter<T>` from an `EmitterLike<T>`, a listen function (`(Handler<T>) => UnsubscribeFunc`), or an `EventSource` + event name pair.
+
+* `EmitterLike<T>` is any object with a compatible `subscribe|listen` method
+* `EventSource` is any object with common `addEventListener/removeEventListener|on/off` methods.
+
+```ts
+import { toEventEmitter } from "@xtia/jel";
+
+// EventSource + name:
+const keypresses$ = toEventEmitter(window, "keydown");
+
+keypresses$.map(ev => ev.key)
+    .listen(key => console.log(key, "pressed"));
+
+// EmitterLike
+function logEvents(emitter: EmitterLike<any>) {
+    // this function accepts Jel's EventEmitter, as well as RxJS
+    // streams and other compatible emitters
+    toEventEmitter(emitter).listen(value => console.log(value));
+}
+```
+
+## createEventSource<T>()
+
+Creates an EventEmitter<T> and a `emit(T)` function to control it.
+
+```ts
+import { createEventSource } from "@xtia/jel";
+
+function createGame() {
+    const winEmitPair = createEventSource<string>();
+
+    // <insert game logic>
+
+    // when someone wins:
+    winEmitPair.emit("player1");
+
+    return {
+        winEvent: winEmitPair.emitter
+    };
+}
+
+const game = createGame();
+game.winEvent
+    .filter(winner => winner === me)
+    .apply(showConfetti);
+```
+
+## createEventsSource<Map>()
+
+Creates an 'events' object and a `trigger(name, Map[name])` function to trigger specific events.
+
+```ts
+import { createEventsSource } from "@xtia/jel";
+
+type EventMap = {
+    end: { winner: string },
+    update: { state: GameState },
+}
+
+function createGame() {
+    const events = createEventsSource<EventMap>();
+
+    // when game ends
+    events.trigger("end", winnerName);
+
+    return {
+        events: events.emitters,
+    }
+}
+```
+## createEventsProxy<Map>(source)
+
+Creates an 'events' object from an `EventSource`.
+
+```ts
+import { createEventsProxy } from "@xtia/jel";
+
+const windowEvents = createEventsProxy<WindowEventMap>(window);
+// (this windowEvents is exported from @xtia/jel for convenience)
+
+windowEvents.keydown
+    .filter(ev => ev.key == "Enter")
+    .apply(() => console.log("Enter pressed"));
+```
+
+## `interval(ms)`
+
+Emits a number, incremented by 1 each time, as long as any subscriptions are active.
+
+## `timeout(ms)`
+
+Emits once after the specified time.
+
+## `animationFrames`
+
+Emits *delta times* from a `requestAnimationFrame()` loop, as long as any subscriptions are active.
+
+```ts
+import { animationFrames } from "@xtia.jel";
+
+animationFrames.listen(delta => {
+    game.tick(delta);
+});
+
+## SubjectEmitter
+
+Creates a manually-controlled emitter that maintains its last emitted value (`em.value`), emits it immediately to
+and new subscription and can be updated with `em.next(value)`.

package/{internal → lib}/element.js

@@ -1,6 +1,6 @@
 import { toEventEmitter } from "./emitter.js";
 import { attribsProxy, createEventsProxy, styleProxy } from "./proxy";
-import { entityDataSymbol, isContent, isJelEntity, isReactiveSource } from "./util";
+import { entityDataSymbol, isContent, isJelEntity, isReactiveSource } from "./util.js";
 const elementWrapCache = new WeakMap();
 const recursiveAppend = (parent, c) => {
     if (c === null || c === undefined)

package/lib/helpers.d.ts

@@ -0,0 +1,4 @@
+import { DomEntity } from "./types";
+export declare const $body: DomEntity<HTMLElement>;
+export declare const windowEvents: import("./types").EventEmitterMap<WindowEventMap>;
+export declare const documentEvents: import("./types").EventEmitterMap<DocumentEventMap>;

package/lib/helpers.js

@@ -0,0 +1,5 @@
+import { $ } from "./element";
+import { createEventsProxy } from "./proxy";
+export const $body = "document" in globalThis ? $(document.body) : undefined;
+export const windowEvents = createEventsProxy(window);
+export const documentEvents = createEventsProxy(document);

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { $ } from "./element";
+export { DomEntity, ElementClassDescriptor, ElementDescriptor, DOMContent, DomHelper, StyleAccessor, JelEntity, EventEmitterMap, EmitterLike, CSSValue } from "./types";
+export { createEntity } from "./util";
+export { createEventSource, createEventsSource, interval, timeout, animationFrames, SubjectEmitter, toEventEmitter, type EventEmitter, type EventRecording, type EventRecorder, combineEmitters } from "./emitter";
+export { createEventsProxy } from "./proxy";
+export { $body, windowEvents } from "./helpers";

package/lib/index.js

@@ -0,0 +1,5 @@
+export { $ } from "./element";
+export { createEntity } from "./util";
+export { createEventSource, createEventsSource, interval, timeout, animationFrames, SubjectEmitter, toEventEmitter, combineEmitters } from "./emitter";
+export { createEventsProxy } from "./proxy";
+export { $body, windowEvents } from "./helpers";

package/package.json

@@ -1,28 +1,44 @@
 {
   "name": "@xtia/jel",
-  "version": "0.11.1",
-  "repository": {
-    "url": "https://github.com/tiadrop/jel-ts",
-    "type": "github"
-  },
+  "version": "0.11.2",
+  "description": "Lightweight DOM manipulation, componentisation and reactivity",
+  "keywords": [
+    "dom",
+    "reactive",
+    "streams",
+    "reactive-programming",
+    "frontend",
+    "ui",
+    "framework"
+  ],
+  "types": "./lib/index.d.ts",
+  "main": "./lib/index.js",
   "sideEffects": false,
-  "types": "./index.d.ts",
-  "main": "./index.js",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
     },
-    "./internal/*": null
+    "./lib/*": null
   },
   "scripts": {
-    "prepublishOnly": "cp ../README.md .",
-    "postpublish": "rm README.md"
+    "build": "tsc",
+    "watch-demo": "webpack --watch",
+    "prepublishOnly": "tsc"
   },
-  "description": "Lightweight DOM manipulation, componentisation and reactivity",
-  "keywords": [
-    "dom"
+  "repository": {
+    "url": "https://github.com/tiadrop/jel-ts",
+    "type": "github"
+  },
+  "files": [
+    "lib/"
   ],
   "author": "Aleta Lovelace",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.9.3",
+    "webpack": "^5.95.0",
+    "webpack-cli": "^5.1.4"
+  }
 }

package/index.d.ts

@@ -1,9 +0,0 @@
-import { $ } from "./internal/element";
-import { DomEntity } from "./internal/types";
-export { DomEntity, ElementClassDescriptor, ElementDescriptor, DOMContent, DomHelper, StyleAccessor, JelEntity, EventEmitterMap, EmitterLike, CSSValue } from "./internal/types";
-export { createEntity } from "./internal/util";
-export { createEventSource, createEventsSource, interval, timeout, animationFrames, SubjectEmitter, toEventEmitter, type EventEmitter, type EventRecording, type EventRecorder, combineEmitters } from "./internal/emitter";
-export { createEventsProxy } from "./internal/proxy";
-export { $ };
-export declare const $body: DomEntity<HTMLElement>;
-export declare const windowEvents: import(".").EventEmitterMap<WindowEventMap>;

package/index.js

@@ -1,8 +0,0 @@
-import { $ } from "./internal/element";
-import { createEventsProxy } from "./internal/proxy";
-export { createEntity } from "./internal/util";
-export { createEventSource, createEventsSource, interval, timeout, animationFrames, SubjectEmitter, toEventEmitter, combineEmitters } from "./internal/emitter";
-export { createEventsProxy } from "./internal/proxy";
-export { $ };
-export const $body = "document" in globalThis ? $(document.body) : undefined;
-export const windowEvents = createEventsProxy(window);