emberwick 0.1.1 → 0.3.0

package/README.md

@@ -10,6 +10,8 @@ point it at your own market data.
   to new bounds, zoom is cursor-anchored and eased, panning has inertia.
 - **Fast on big data.** One `requestAnimationFrame` loop, dirty-flag driven,
   with visible-range culling — 500k bars loaded costs only the ~200 on screen.
+- **Annotated.** Nine marker shapes, price lines and shaded zones, with
+  collision-aware stacking and hit-testing for hover and click.
 
 ---
 
@@ -25,10 +27,6 @@ npm install emberwick
 import { createChart, RandomFeed } from 'emberwick'
 ```
 
-> **Not published yet.** The package builds and packs (`npm run release`), but
-> it has not been pushed to the registry, and the name has not been confirmed
-> available — run `npm view emberwick` before relying on it.
-
 ### From a CDN, no build step
 
 ```html
@@ -213,7 +211,15 @@ const chart = createChart(el, {
 | `append(bar)` | Open a new candle |
 | `setFeed(feed)` | `async` — loads history, then subscribes. Detaches any previous feed |
 | `detachFeed()` | Unsubscribe, keep the bars on screen |
-| `subscribe('crosshair', fn)` | Returns an unsubscribe fn. See events below |
+| `subscribe(event, fn)` | Returns an unsubscribe fn. See events below |
+| `setMarkers(markers)` | Replace every marker |
+| `getMarkers()` | Current markers, normalised, each with its resolved bar index |
+| `addMarker(marker)` | Append one marker |
+| `removeMarker(id)` | Remove by id |
+| `clearMarkers()` | Remove all markers |
+| `setPriceLines(lines)` | Replace every horizontal price line |
+| `setZones(zones)` | Replace every shaded region |
+| `markerAt(x, y)` | Hit-test plot coordinates, returns a marker or `null` |
 | `setTheme(partial)` | Merge theme keys and repaint |
 | `setPriceMode(mode)` | `'linear'` or `'log'` |
 | `setAnimate(bool)` | Toggle live-candle easing |
@@ -234,7 +240,137 @@ const off = chart.subscribe('crosshair', (payload) => {
 off()  // unsubscribe
 ```
 
-`'crosshair'` is the only event that currently fires. See *Known gaps* below.
+| 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'` | `{ 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
+
+Three independent collections, each replaced wholesale. Zones paint behind the
+candles; price lines and markers paint in front.
+
+```js
+chart.setMarkers([
+  { time: 1717070400000, shape: 'arrowUp',   text: 'BUY 120',
+    data: { orderId: 'A-7741' } },
+  { time: 1717074000000, shape: 'flag',      text: 'Earnings', color: '#c084fc' },
+  { time: 1717077600000, shape: 'arrowDown', text: 'SELL 160' },
+])
+
+chart.setPriceLines([
+  { price: 148.20, title: 'target', color: '#26a69a' },
+  { price: 141.05, title: 'stop', lineStyle: 'dotted' },
+])
+
+chart.setZones([
+  { from: 143.5, to: 145.9, label: 'value area' },
+])
+
+chart.subscribe('markerClick', (m) => openTicket(m.data.orderId))
+```
+
+### Markers
+
+A marker is pinned to a **timestamp**, not a bar index, and resolves to the
+nearest bar. Load an older page of history and every marker re-resolves, so
+nothing drifts off its candle.
+
+| Field | Default | Notes |
+|---|---|---|
+| `time` | *required* | ms since epoch, snapped to the closest bar |
+| `id` | generated | Needed for `removeMarker(id)` |
+| `shape` | `'circle'` | See the list below |
+| `position` | shape-dependent | `'aboveBar'`, `'belowBar'`, `'inBar'`, `'atPrice'` |
+| `price` | — | Only used when `position` is `'atPrice'` |
+| `color` | `theme.up` / `theme.down` | Down-pointing shapes default to the down colour |
+| `text` | — | Short caption. For `'label'` it is drawn inside the pill |
+| `textColor` | theme | Caption colour |
+| `size` | `1` | Scale factor |
+| `data` | — | Anything. Handed straight back on hover and click |
+
+Shapes: `arrowUp`, `arrowDown`, `triangleUp`, `triangleDown`, `circle`,
+`square`, `diamond`, `flag`, `label`.
+
+Position defaults follow the trading convention: up-pointing shapes sit
+*below* the bar, down-pointing shapes *above* it, everything else above.
+
+**Overlap and density.** Markers sharing a bar are stacked rather than drawn on
+top of each other. Below about 3px per bar, dense runs thin to roughly one
+marker per 4px — a thousand trades stay legible and stay fast. A marker on the
+forming candle anchors to the animated values, so it flows with the live bar.
+
+### Price lines
+
+| Field | Default | Notes |
+|---|---|---|
+| `price` | *required* | |
+| `color` | `theme.textStrong` | |
+| `lineStyle` | `'dashed'` | `'solid'`, `'dashed'`, `'dotted'` |
+| `lineWidth` | `1` | |
+| `title` | — | Pill drawn at the left end |
+| `axisLabel` | `true` | Price tag on the axis |
+
+### Zones
+
+Supply `from`/`to` for a **price band** spanning the full width, or
+`fromTime`/`toTime` for a **time band** spanning the full height.
+
+```js
+chart.setZones([
+  { from: 143.5, to: 145.9, label: 'value area' },
+  { fromTime: 1717070400000, toTime: 1717074000000,
+    color: 'rgba(239,83,80,0.07)', border: 'rgba(239,83,80,0.3)' },
+])
+```
+
+Autoscale fits the **bars**, not the annotations — a price line far outside the
+data range is simply off-screen. Derive extreme values from the visible range
+if you need them guaranteed visible.
 
 ---
 
@@ -475,9 +611,12 @@ npm run build:umd    # minified UMD      -> dist-lib/umd/emberwick.umd.js
 npm run pack:lib     # manifest + README + .d.ts into dist-lib/
 npm run size         # gzipped size budget check
 npm run release      # all four, in order
-npm publish dist-lib # publish the assembled directory
+npm publish ./dist-lib   # publish the assembled directory — note the ./
 ```
 
+> The leading `./` is required. `npm publish dist-lib` makes npm look for a
+> *registry package* named `dist-lib` and fail with `E404`.
+
 Publishing from `dist-lib/` keeps the playground, the build configs and the
 app's private `package.json` out of the artifact. `package.lib.json` is the
 manifest that becomes the published `package.json`.
@@ -505,13 +644,10 @@ 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.
-- **Not published to npm.** The package builds and packs, but it has not been
-  pushed, and the name is unverified — check `npm view emberwick` first.
-- **The library builds are unverified.** `npm run build:lib` / `build:umd`
-  have not been executed here; this environment only runs the app build. Run
-  `npm run release` locally before publishing.
+- **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
+  there is no drag-to-move or editing interaction.
 - **No indicators or drawing tools.** SMA/EMA/RSI/MACD, multi-pane layout and
   trendlines are planned but not implemented.
 - **Candlesticks only.** No Heikin-Ashi, line, area or baseline series yet.

package/index.d.ts

@@ -40,6 +40,97 @@ export interface Theme {
   timeAxisHeight: number
 }
 
+/* --------------------------------------------------------------- markers -- */
+
+export type MarkerShape =
+  | 'arrowUp'
+  | 'arrowDown'
+  | 'triangleUp'
+  | 'triangleDown'
+  | 'circle'
+  | 'square'
+  | 'diamond'
+  | 'flag'
+  | 'label'
+
+export type MarkerPosition = 'aboveBar' | 'belowBar' | 'inBar' | 'atPrice'
+
+/** A point annotation pinned to the bar nearest `time`. */
+export interface Marker<T = unknown> {
+  /** Stable id. Generated when omitted; required for removeMarker(). */
+  id?: string
+  /** ms since epoch — snapped to the closest bar. */
+  time: number
+  /** Only used when position is 'atPrice'. */
+  price?: number
+  /** Default 'circle'. */
+  shape?: MarkerShape
+  /**
+   * Default depends on the shape: up shapes sit below the bar, down shapes
+   * above it, everything else above.
+   */
+  position?: MarkerPosition
+  /** Defaults to theme.up, or theme.down for the down-pointing shapes. */
+  color?: string
+  textColor?: string
+  /** Short caption. For shape 'label' it is drawn inside the pill. */
+  text?: string
+  /** Scale factor. Default 1. */
+  size?: number
+  /** Passed straight back to you on hover/click. */
+  data?: T
+}
+
+/** A marker after normalisation, as returned by getMarkers(). */
+export interface ResolvedMarker<T = unknown> extends Marker<T> {
+  id: string
+  shape: MarkerShape
+  position: MarkerPosition
+  size: number
+  /** Bar index the marker resolved to, or -1 when there are no bars. */
+  index: number
+}
+
+export type LineStyle = 'solid' | 'dashed' | 'dotted'
+
+/** A horizontal line at a fixed price. */
+export interface PriceLine {
+  id?: string
+  price: number
+  /** Defaults to theme.textStrong. */
+  color?: string
+  /** Default 'dashed'. */
+  lineStyle?: LineStyle
+  /** Default 1. */
+  lineWidth?: number
+  /** Optional pill drawn at the left end. */
+  title?: string
+  titleColor?: string
+  /** Price tag on the axis. Default true. */
+  axisLabel?: boolean
+  tagTextColor?: string
+}
+
+/**
+ * A shaded region: supply `from`/`to` for a price band spanning the full
+ * width, or `fromTime`/`toTime` for a time band spanning the full height.
+ */
+export interface Zone {
+  id?: string
+  from?: number
+  to?: number
+  fromTime?: number
+  toTime?: number
+  /** Fill. Use rgba(). Default a faint theme-green wash. */
+  color?: string
+  /** Optional 1px outline. */
+  border?: string
+  label?: string
+  labelColor?: string
+}
+
+/* --------------------------------------------------------------- options -- */
+
 export interface TimeScaleOptions {
   /** Pixels per bar. Default 9. */
   spacing?: number
@@ -73,6 +164,10 @@ export interface ChartOptions {
   animate?: boolean
   /** Bars requested from the feed on setFeed(). Default 1500. */
   initialBars?: number
+  /** Initial markers; equivalent to calling setMarkers() after construction. */
+  markers?: Marker[]
+  priceLines?: PriceLine[]
+  zones?: Zone[]
   timeScale?: TimeScaleOptions
   priceScale?: PriceScaleOptions
 }
@@ -84,6 +179,30 @@ 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 {
   symbol: string
   timeframe: number
@@ -147,6 +266,8 @@ export declare class RandomFeed extends DataFeed {
   stop(): void
 }
 
+/* ---------------------------------------------------------------- scales -- */
+
 export declare class TimeScale {
   constructor(opts?: TimeScaleOptions)
   visibleRange(): { from: number; to: number }
@@ -168,6 +289,8 @@ export declare class PriceScale {
   readonly hi: number
 }
 
+/* ----------------------------------------------------------------- chart -- */
+
 export declare class Chart {
   constructor(container: HTMLElement, options?: ChartOptions)
 
@@ -181,6 +304,19 @@ export declare class Chart {
   setFeed(feed: Feed): Promise<void>
   detachFeed(): void
 
+  /** Replace every marker. */
+  setMarkers(markers: Marker[]): void
+  /** Current markers, normalised, each with its resolved bar index. */
+  getMarkers(): ResolvedMarker[]
+  addMarker(marker: Marker): void
+  /** Removes by id — including ids generated for you. */
+  removeMarker(id: string): void
+  clearMarkers(): void
+  setPriceLines(lines: PriceLine[]): void
+  setZones(zones: Zone[]): void
+  /** Topmost marker under a plot-relative point, else null. */
+  markerAt(x: number, y: number): ResolvedMarker | null
+
   setTheme(theme: Partial<Theme>): void
   setPriceMode(mode: PriceMode): void
   setAnimate(on: boolean): void
@@ -192,17 +328,27 @@ 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: 'visibleRange', fn: (range: { from: number; to: number }) => void): () => void
+  subscribe(event: 'markerClick', fn: (marker: ResolvedMarker) => void): () => void
+  subscribe(event: 'markerHover', fn: (marker: ResolvedMarker | null) => void): () => void
+  subscribe(event: 'visibleRange', fn: (range: VisibleRangePayload) => void): () => void
 
   /** Removes listeners, canvases and the render loop. */
   destroy(): void
 
   readonly bars: Bar[]
+  readonly priceLines: PriceLine[]
+  readonly zones: Zone[]
   readonly ts: TimeScale
   readonly ps: PriceScale
 }
@@ -214,6 +360,8 @@ export declare const defaultTheme: Theme
 export declare const lightTheme: Theme
 export declare const version: string
 
+/* ------------------------------------------------------------- utilities -- */
+
 /** Seeded PRNG used by RandomFeed. */
 export declare function mulberry32(seed: number): () => number