aeon-dom 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# aeon-dom
+
+DOM event sources and continuous-time browser Behaviors for [Aeon](https://github.com/joshburgess/aeon).
+
+This package provides:
+
+- **`fromDOMEvent(type, target, options?)`** — convert any DOM `EventTarget` event into an `Event<E, never>`
+- **`animationFrames(scheduler)`** — `Event<DOMHighResTimeStamp, never>` driven by `requestAnimationFrame`
+- **`mousePosition(scheduler)`** — `Behavior<{x, y}, never>` tracking the cursor
+- **`windowSize(scheduler)`** — `Behavior<{width, height}, never>` tracking viewport size
+
+## Installation
+
+```bash
+pnpm add aeon-core aeon-scheduler aeon-dom
+```
+
+## Quick Start
+
+```typescript
+import { observe } from "aeon-core";
+import { DefaultScheduler } from "aeon-scheduler";
+import { fromDOMEvent } from "aeon-dom";
+
+const scheduler = new DefaultScheduler();
+
+const clicks = fromDOMEvent("click", document.body);
+observe((e) => console.log("clicked at", e.clientX, e.clientY), clicks, scheduler);
+```
+
+### Continuous Behaviors
+
+```typescript
+import { mousePosition, windowSize } from "aeon-dom";
+import { liftA2B, readBehavior } from "aeon-core";
+import { toTime } from "aeon-types";
+
+const mouse = mousePosition(scheduler);
+const size = windowSize(scheduler);
+
+const relativeX = liftA2B((m, s) => m.x / s.width, mouse, size);
+console.log(readBehavior(relativeX, toTime(performance.now())));
+```
+
+## Documentation
+
+- [Main README](https://github.com/joshburgess/aeon#readme)
+- [Getting Started](https://github.com/joshburgess/aeon/blob/main/docs/getting-started.md)
+
+## License
+
+MIT

package/dist/animationFrames.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Animation frame Event source.
+ *
+ * Emits a DOMHighResTimeStamp on each requestAnimationFrame callback.
+ */
+import type { Event as PulseEvent } from "aeon-types";
+/**
+ * An Event that emits a DOMHighResTimeStamp on each animation frame.
+ *
+ * Denotation: `[(t, timestamp) | each requestAnimationFrame callback]`
+ *
+ * Cancels the animation frame loop when disposed.
+ */
+export declare const animationFrames: PulseEvent<DOMHighResTimeStamp, never>;
+//# sourceMappingURL=animationFrames.d.ts.map

package/dist/animationFrames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animationFrames.d.ts","sourceRoot":"","sources":["../src/animationFrames.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAc,KAAK,IAAI,UAAU,EAA2B,MAAM,YAAY,CAAC;AA2B3F;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,mBAAmB,EAAE,KAAK,CAC9B,CAAC"}

package/dist/behaviors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * DOM Behaviors — continuous time-varying values derived from the DOM.
+ *
+ * These create Behaviors that are push-updated from DOM events and
+ * pull-sampled when read. Each returns [Behavior, Disposable] since
+ * they subscribe to DOM events internally.
+ */
+import type { Behavior, Disposable, Scheduler } from "aeon-types";
+/** 2D point for mouse coordinates. */
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** Dimensions for window size. */
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * A Behavior holding the current mouse position.
+ *
+ * Denotation: `t => { x: mouseX(t), y: mouseY(t) }`
+ *
+ * Push-updated from mousemove events on the given target (defaults to document).
+ * Returns [Behavior, Disposable] — dispose to stop listening.
+ */
+export declare const mousePosition: (scheduler: Scheduler, target?: EventTarget) => [Behavior<Point, never>, Disposable];
+/**
+ * A Behavior holding the current window dimensions.
+ *
+ * Denotation: `t => { width: innerWidth(t), height: innerHeight(t) }`
+ *
+ * Push-updated from resize events on window.
+ * Returns [Behavior, Disposable] — dispose to stop listening.
+ */
+export declare const windowSize: (scheduler: Scheduler) => [Behavior<Size, never>, Disposable];
+//# sourceMappingURL=behaviors.d.ts.map

package/dist/behaviors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behaviors.d.ts","sourceRoot":"","sources":["../src/behaviors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGlE,sCAAsC;AACtC,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kCAAkC;AAClC,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,SAAS,EACpB,SAAQ,WAAsB,KAC7B,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,UAAU,CAMrC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GAAI,WAAW,SAAS,KAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,UAAU,CAWnF,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DOM Event sources.
+ *
+ * Creates pulse Event streams from DOM EventTarget events.
+ */
+import type { Event as PulseEvent } from "aeon-types";
+/**
+ * Create a pulse Event from a DOM event.
+ *
+ * Denotation: `[(t, domEvent) | domEvent fires on target at time t]`
+ *
+ * Automatically removes the event listener when disposed.
+ */
+export declare function fromDOMEvent<K extends keyof HTMLElementEventMap>(type: K, target: HTMLElement, options?: AddEventListenerOptions): PulseEvent<HTMLElementEventMap[K], never>;
+export declare function fromDOMEvent<K extends keyof WindowEventMap>(type: K, target: Window, options?: AddEventListenerOptions): PulseEvent<WindowEventMap[K], never>;
+export declare function fromDOMEvent<K extends keyof DocumentEventMap>(type: K, target: Document, options?: AddEventListenerOptions): PulseEvent<DocumentEventMap[K], never>;
+export declare function fromDOMEvent(type: string, target: EventTarget, options?: AddEventListenerOptions): PulseEvent<Event, never>;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAc,KAAK,IAAI,UAAU,EAA2B,MAAM,YAAY,CAAC;AA2B3F;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,mBAAmB,EAC9D,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7C,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,cAAc,EACzD,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AACxC,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,gBAAgB,EAC3D,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC1C,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,346 @@
+'use strict';
+
+/**
+ * Internal helpers for aeon-dom.
+ *
+ * At runtime, Event<A, E> IS Source<A, E> — the opaque type brand is
+ * purely type-level. This mirrors the zero-cost identity cast in aeon-core.
+ */ /** Create an opaque Event from a Source. Zero-cost identity cast. */ const createEvent = (source)=>source;
+
+let DOMEventSource = class DOMEventSource {
+    constructor(type, target, options){
+        this.type = type;
+        this.target = target;
+        this.options = options;
+    }
+    run(sink, scheduler) {
+        const handler = (e)=>{
+            sink.event(scheduler.currentTime(), e);
+        };
+        this.target.addEventListener(this.type, handler, this.options);
+        return {
+            dispose: ()=>{
+                this.target.removeEventListener(this.type, handler, this.options);
+            }
+        };
+    }
+};
+function fromDOMEvent(type, target, options) {
+    return createEvent(new DOMEventSource(type, target, options));
+}
+
+let AnimationFrameSource = class AnimationFrameSource {
+    run(sink, scheduler) {
+        let id = 0;
+        let disposed = false;
+        const tick = (timestamp)=>{
+            if (disposed) return;
+            sink.event(scheduler.currentTime(), timestamp);
+            id = requestAnimationFrame(tick);
+        };
+        id = requestAnimationFrame(tick);
+        return {
+            dispose () {
+                disposed = true;
+                cancelAnimationFrame(id);
+            }
+        };
+    }
+};
+const ANIMATION_FRAME_SOURCE = new AnimationFrameSource();
+/**
+ * An Event that emits a DOMHighResTimeStamp on each animation frame.
+ *
+ * Denotation: `[(t, timestamp) | each requestAnimationFrame callback]`
+ *
+ * Cancels the animation frame loop when disposed.
+ */ const animationFrames = createEvent(ANIMATION_FRAME_SOURCE);
+
+/** A no-op disposable. */ const disposeNone = {
+    dispose () {}
+};
+/** Create an opaque Event from a Source. Zero-cost identity cast. */ const _createEvent = (source)=>source;
+/** Extract the Source from an opaque Event. Zero-cost identity cast. */ const _getSource = (event)=>event;
+// --- Source classes for V8 hidden class stability ---
+let EmptySource = class EmptySource {
+    constructor(){
+        this._sync = true;
+    }
+    run(sink, scheduler) {
+        sink.end(scheduler.currentTime());
+        return disposeNone;
+    }
+    syncIterate(_emit) {}
+};
+let NowSource = class NowSource {
+    constructor(value){
+        this.value = value;
+        this._sync = true;
+    }
+    run(sink, scheduler) {
+        const t = scheduler.currentTime();
+        sink.event(t, this.value);
+        sink.end(t);
+        return disposeNone;
+    }
+    syncIterate(emit) {
+        emit(this.value);
+    }
+};
+// --- Singletons for empty/never ---
+const EMPTY_SOURCE = new EmptySource();
+/**
+ * Pipe base class for sinks that forward error/end unchanged.
+ *
+ * With ES2022 target, `extends Pipe` compiles to native `class extends` —
+ * zero helpers, zero overhead. V8 devirtualizes the shared error/end
+ * methods across all sink subtypes.
+ */ let Pipe = class Pipe {
+    constructor(sink){
+        this.sink = sink;
+    }
+    error(time, err) {
+        this.sink.error(time, err);
+    }
+    end(time) {
+        this.sink.end(time);
+    }
+};
+// --- Sink classes ---
+/** Map sink: applies f to each value. */ let MapSink = class MapSink extends Pipe {
+    constructor(f, sink){
+        super(sink);
+        this.f = f;
+    }
+    event(time, value) {
+        const f = this.f;
+        this.sink.event(time, f(value));
+    }
+};
+/** Filter sink: only forwards values that pass the predicate. */ let FilterSink = class FilterSink extends Pipe {
+    constructor(predicate, sink){
+        super(sink);
+        this.predicate = predicate;
+    }
+    event(time, value) {
+        const p = this.predicate;
+        if (p(value)) {
+            this.sink.event(time, value);
+        }
+    }
+};
+/** Combined filter+map sink: filter then map in one node. */ let FilterMapSink = class FilterMapSink extends Pipe {
+    constructor(predicate, f, sink){
+        super(sink);
+        this.predicate = predicate;
+        this.f = f;
+    }
+    event(time, value) {
+        const p = this.predicate;
+        if (p(value)) {
+            const f = this.f;
+            this.sink.event(time, f(value));
+        }
+    }
+};
+/** Combined map+filter sink: map then filter in one node. */ let MapFilterSink = class MapFilterSink extends Pipe {
+    constructor(f, predicate, sink){
+        super(sink);
+        this.f = f;
+        this.predicate = predicate;
+    }
+    event(time, value) {
+        const f = this.f;
+        const mapped = f(value);
+        const p = this.predicate;
+        if (p(mapped)) {
+            this.sink.event(time, mapped);
+        }
+    }
+};
+// --- Source classes (for instanceof fusion detection) ---
+/** A map source, tagged for fusion detection via instanceof. */ let MapSource = class MapSource {
+    constructor(f, source){
+        this.f = f;
+        this.source = source;
+    }
+    run(sink, scheduler) {
+        return this.source.run(new MapSink(this.f, sink), scheduler);
+    }
+    /** Factory with fusion and algebraic simplification. */ static create(f, source) {
+        // map(f, empty()) → empty()
+        if (source instanceof EmptySource) {
+            return EMPTY_SOURCE;
+        }
+        // map(f, now(x)) → now(f(x))  — constant folding
+        if (source instanceof NowSource) {
+            return new NowSource(f(source.value));
+        }
+        // map(f, map(g, s)) → map(f∘g, s)
+        if (source instanceof MapSource) {
+            const inner = source;
+            return new MapSource((x)=>f(inner.f(x)), inner.source);
+        }
+        // map(f, filter(p, s)) → filterMap(p, f, s)
+        if (source instanceof FilterSource) {
+            const inner = source;
+            return new FilterMapSource(inner.predicate, f, inner.source);
+        }
+        return new MapSource(f, source);
+    }
+};
+/** A filter source, tagged for fusion detection via instanceof. */ let FilterSource = class FilterSource {
+    constructor(predicate, source){
+        this.predicate = predicate;
+        this.source = source;
+    }
+    run(sink, scheduler) {
+        return this.source.run(new FilterSink(this.predicate, sink), scheduler);
+    }
+    /** Factory with fusion and algebraic simplification. */ static create(predicate, source) {
+        // filter(p, empty()) → empty()
+        if (source instanceof EmptySource) {
+            return EMPTY_SOURCE;
+        }
+        // filter(p, now(x)) → p(x) ? now(x) : empty()  — constant folding
+        if (source instanceof NowSource) {
+            const val = source.value;
+            return predicate(val) ? source : EMPTY_SOURCE;
+        }
+        // filter(p, filter(q, s)) → filter(x => q(x) && p(x), s)
+        if (source instanceof FilterSource) {
+            const inner = source;
+            return new FilterSource((x)=>inner.predicate(x) && predicate(x), inner.source);
+        }
+        // filter(p, map(f, s)) → mapFilter(f, p, s)
+        if (source instanceof MapSource) {
+            const inner = source;
+            return new MapFilterSource(inner.f, predicate, inner.source);
+        }
+        return new FilterSource(predicate, source);
+    }
+};
+/** Fused filter-then-map source. */ let FilterMapSource = class FilterMapSource {
+    constructor(predicate, f, source){
+        this.predicate = predicate;
+        this.f = f;
+        this.source = source;
+    }
+    run(sink, scheduler) {
+        return this.source.run(new FilterMapSink(this.predicate, this.f, sink), scheduler);
+    }
+};
+/** Fused map-then-filter source. */ let MapFilterSource = class MapFilterSource {
+    constructor(f, predicate, source){
+        this.f = f;
+        this.predicate = predicate;
+        this.source = source;
+    }
+    run(sink, scheduler) {
+        return this.source.run(new MapFilterSink(this.f, this.predicate, sink), scheduler);
+    }
+};
+// --- Public API ---
+/**
+ * Create a fusible map Event. Detects map∘map and composes functions.
+ */ const fusedMap = (f, event)=>{
+    const source = _getSource(event);
+    return _createEvent(MapSource.create(f, source));
+};
+/**
+ * Transform each value in an Event stream.
+ *
+ * Denotation: `map(f, e) = [(t, f(v)) | (t, v) ∈ e]`
+ */ const map$1 = (f, event)=>fusedMap(f, event);
+// --- Internal tag ---
+const BEHAVIOR_KEY = Symbol("pulse/behavior");
+/** Create an opaque Behavior from a BehaviorImpl. Internal use only. */ const _createBehavior = (impl)=>({
+        [BEHAVIOR_KEY]: impl
+    });
+// --- Stepper subscription ---
+/**
+ * Subscribe a stepper behavior to an event stream.
+ * Returns a Disposable to unsubscribe.
+ */ const subscribeStepperToEvent = (stepperImpl, event, scheduler)=>{
+    const source = _getSource(event);
+    const sink = {
+        event (time, value) {
+            stepperImpl.value = value;
+            stepperImpl.time = time;
+            stepperImpl.generation++;
+        },
+        error () {},
+        end () {}
+    };
+    return source.run(sink, scheduler);
+};
+// --- Event ↔ Behavior Bridge ---
+/**
+ * Create a Behavior that holds the latest value from an Event.
+ *
+ * Denotation: `stepper(init, e) = t => latestValue(e, t) ?? init`
+ *
+ * This is the primary push→pull bridge. The returned behavior is
+ * push-updated when the event fires, and pull-sampled when read.
+ *
+ * IMPORTANT: The caller must provide a scheduler to subscribe to the event.
+ * Returns [Behavior, Disposable] — the disposable unsubscribes from the event.
+ */ const stepper = (initial, event, scheduler)=>{
+    const impl = {
+        tag: "stepper",
+        initial,
+        value: initial,
+        time: scheduler.currentTime(),
+        generation: 0
+    };
+    const disposable = subscribeStepperToEvent(impl, event, scheduler);
+    return [
+        _createBehavior(impl),
+        disposable
+    ];
+};
+
+/**
+ * A Behavior holding the current mouse position.
+ *
+ * Denotation: `t => { x: mouseX(t), y: mouseY(t) }`
+ *
+ * Push-updated from mousemove events on the given target (defaults to document).
+ * Returns [Behavior, Disposable] — dispose to stop listening.
+ */ const mousePosition = (scheduler, target = document)=>{
+    const moves = map$1((e)=>({
+            x: e.clientX,
+            y: e.clientY
+        }), fromDOMEvent("mousemove", target));
+    return stepper({
+        x: 0,
+        y: 0
+    }, moves, scheduler);
+};
+/**
+ * A Behavior holding the current window dimensions.
+ *
+ * Denotation: `t => { width: innerWidth(t), height: innerHeight(t) }`
+ *
+ * Push-updated from resize events on window.
+ * Returns [Behavior, Disposable] — dispose to stop listening.
+ */ const windowSize = (scheduler)=>{
+    const initial = typeof window !== "undefined" ? {
+        width: window.innerWidth,
+        height: window.innerHeight
+    } : {
+        width: 0,
+        height: 0
+    };
+    const resizes = map$1(()=>({
+            width: window.innerWidth,
+            height: window.innerHeight
+        }), fromDOMEvent("resize", window));
+    return stepper(initial, resizes, scheduler);
+};
+
+exports.animationFrames = animationFrames;
+exports.fromDOMEvent = fromDOMEvent;
+exports.mousePosition = mousePosition;
+exports.windowSize = windowSize;
+//# sourceMappingURL=index.cjs.map