emberwick 0.2.0 → 0.3.0

package/README.md

@@ -240,16 +240,53 @@ const off = chart.subscribe('crosshair', (payload) => {
 off()  // unsubscribe
 ```
 
+| Event | Payload |
+|---|---|
 | Event | Payload |
 |---|---|
 | `'crosshair'` | `{ index, bar, price }`, or `null` when the pointer leaves the plot |
 | `'markerHover'` | The marker under the pointer, or `null` when none is |
 | `'markerClick'` | The clicked marker. Only fires on a hit, never with `null` |
-| `'visibleRange'` | **Accepted but never emitted.** See *Known gaps* |
+| `'visibleRange'` | `{ from, to, fromTime, toTime, barCount, spacing, settled }` |
 
 A drag that happens to end on top of a marker does not fire `'markerClick'` —
 panning and clicking stay distinct.
 
+### Tracking the visible range
+
+`'visibleRange'` is a **state** event rather than a notification, which makes it
+usable without any debouncing of your own:
+
+- A new subscriber is called **immediately** with the current window, so it
+  never has to wait for the user to pan before it knows what is on screen.
+- It then fires **only when the window actually changes**. Indices are
+  integers, so a slow pan at 9px/bar produces roughly one event every nine
+  frames, not one per frame.
+- `spacing` is reported but is deliberately *not* part of the change test — it
+  is a float that moves every frame of an eased zoom, and keying on it would
+  turn this into a 60/sec firehose. Use it for level-of-detail decisions.
+- `settled` *is* part of the change test, so the final event of a gesture
+  always arrives with `settled: true`. That makes "wait until the view stops
+  moving, then do the expensive thing" a safe pattern.
+
+```js
+const off = chart.subscribe('visibleRange', async (r) => {
+  // paginate backwards when the user approaches the left edge
+  if (r.from < 50 && r.settled && r.fromTime) {
+    const older = await myApi.bars({ to: r.fromTime, limit: 500 })
+    chart.setData(older.concat(chart.bars))
+  }
+})
+```
+
+Syncing a second chart is the other common use — feed `fromTime`/`toTime`
+straight into the other instance. And `chart.visibleRange()` returns the same
+payload on demand if you would rather poll than subscribe.
+
+> The chart also paginates backwards **on its own** through
+> `feed.getBars({ to })` whenever you have attached a feed. This event is for
+> when you want to drive that yourself, or to drive something other than data.
+
 ---
 
 ## Annotations
@@ -607,8 +644,6 @@ src/App.jsx, src/styles.css  the playground (not published)
 
 Honest list of what isn't there yet:
 
-- **`subscribe('visibleRange', fn)` never fires.** The event is accepted and
-  the handler is stored, but nothing emits it. Use `'crosshair'` for now.
 - **No OHLCV legend in the package.** `subscribe('crosshair', fn)` gives you
   the hovered bar; rendering the readout is still yours to do.
 - **Markers are not draggable.** They are hit-tested for hover and click, but

package/index.d.ts

@@ -179,6 +179,28 @@ export interface CrosshairPayload {
   price: number
 }
 
+/** Payload of the 'visibleRange' event, and the return of chart.visibleRange(). */
+export interface VisibleRangePayload {
+  /** First visible bar index, clamped to the loaded data. */
+  from: number
+  /** Last visible bar index, clamped to the loaded data. */
+  to: number
+  /** `bars[from].time`, or null when no bars are loaded. */
+  fromTime: number | null
+  /** `bars[to].time`, or null when no bars are loaded. */
+  toTime: number | null
+  /** Total bars currently loaded. */
+  barCount: number
+  /** Current pixels per bar — useful for level-of-detail decisions. */
+  spacing: number
+  /**
+   * False while the view is still easing. The last event of a gesture always
+   * arrives with `settled: true`, so it is safe to defer expensive work
+   * (a fetch, a re-aggregation) until you see it.
+   */
+  settled: boolean
+}
+
 /* ------------------------------------------------------------------ feed -- */
 
 export interface GetBarsRequest {
@@ -306,14 +328,20 @@ export declare class Chart {
   /** Rolling frames-per-second of the render loop. */
   readonly fps: number
 
+  /** The window currently on screen. Cheap enough to poll. */
+  visibleRange(): VisibleRangePayload
+
   /**
    * Subscribe to a chart event. Returns an unsubscribe function.
-   * NOTE: 'visibleRange' is accepted but is not currently emitted.
+   *
+   * 'visibleRange' is a state event rather than a notification: a new
+   * subscriber is called immediately with the current window, and then only
+   * when that window actually changes — so no debouncing is required.
    */
   subscribe(event: 'crosshair', fn: (payload: CrosshairPayload | null) => void): () => void
   subscribe(event: 'markerClick', fn: (marker: ResolvedMarker) => void): () => void
   subscribe(event: 'markerHover', fn: (marker: ResolvedMarker | null) => void): () => void
-  subscribe(event: 'visibleRange', fn: (range: { from: number; to: number }) => void): () => void
+  subscribe(event: 'visibleRange', fn: (range: VisibleRangePayload) => void): () => void
 
   /** Removes listeners, canvases and the render loop. */
   destroy(): void

package/index.js

@@ -1394,8 +1394,57 @@ class Chart {
     const set = this._listeners[event];
     if (!set) throw new Error(`Chart: unknown event "${event}"`);
     set.add(fn);
+    if (event === "visibleRange") {
+      const payload = this.visibleRange();
+      this._rangeKey = this._rangeIdentity(payload);
+      fn(payload);
+    }
     return () => set.delete(fn);
   }
+  // ------------------------------------------------------------------ range --
+  /**
+   * The window currently on screen. Cheap enough to poll, though
+   * subscribe('visibleRange', fn) is the better way to track it.
+   */
+  visibleRange() {
+    const { from, to } = this.ts.visibleRange();
+    return this._rangePayload(from, to);
+  }
+  _rangePayload(from, to) {
+    const n = this.bars.length;
+    return {
+      from,
+      to,
+      fromTime: n ? this.bars[from].time : null,
+      toTime: n ? this.bars[to].time : null,
+      barCount: n,
+      spacing: this.ts.spacing,
+      settled: this.ts.settled
+    };
+  }
+  _rangeIdentity(p) {
+    return `${p.from}:${p.to}:${p.fromTime}:${p.toTime}:${p.settled ? 1 : 0}`;
+  }
+  /**
+   * Fires only when the window actually changed, so a consumer can hang a
+   * fetch off it without debouncing. Two deliberate choices:
+   *
+   * - `spacing` is NOT part of the identity. It is a float that moves on every
+   *   frame of an eased zoom, so keying on it would make this a 60/sec
+   *   firehose. It is still reported, for level-of-detail decisions.
+   * - `settled` IS part of the identity, so the final event of a gesture
+   *   always arrives with settled:true. Without it, code that defers expensive
+   *   work until the view stops moving would wait forever.
+   */
+  _emitVisibleRange(from, to) {
+    const set = this._listeners.visibleRange;
+    if (!set.size) return;
+    const payload = this._rangePayload(from, to);
+    const key = this._rangeIdentity(payload);
+    if (key === this._rangeKey) return;
+    this._rangeKey = key;
+    for (const fn of set) fn(payload);
+  }
   // ----------------------------------------------------------- annotations --
   /** Replace every marker. Each `time` is resolved to its nearest bar. */
   setMarkers(markers) {
@@ -1482,6 +1531,7 @@ class Chart {
     if (redrawAll || dirty.has("overlay")) {
       drawCrosshair(this.layers.ctx.overlay, state);
     }
+    this._emitVisibleRange(from, to);
     return animating;
   }
   // ------------------------------------------------------------------- api --