wickchart 1.0.0 → 1.2.0

package/README.md

@@ -17,6 +17,7 @@ npm install wickchart
 import 'wickchart';                       // registers <wick-chart>
 import WickChart from 'wickchart';         // for WickChart.registerIndicator(...)
 import { encodeStateQuery } from 'wickchart/core';  // pure helpers
+import { WickChart } from 'wickchart/react';        // React bindings (optional)
 ```
 
 Or straight from a CDN — no install, no build:
@@ -86,7 +87,14 @@ bet:
 
 The demo site is deployed to GitHub Pages:
 **https://benyblack.github.io/wickchart/** — a landing page with a live hero
-chart, the full interactive demo, and the zero-JavaScript declarative page.
+chart, the full interactive demo, the zero-JavaScript declarative page, and a
+[React demo](./demo/react.html) driven entirely by React state.
+
+**Full documentation lives at
+[benyblack.github.io/wickchart/docs.html](./docs.html)** — every attribute,
+method, event, the WickScript reference, overlays (with a live JSON
+playground), feeds, theming and framework bindings, each with runnable
+examples. This README covers the same ground in plain markdown.
 
 ## Run the demo locally
 
@@ -105,6 +113,101 @@ with graceful fallback to synthetic data if it isn't.
 
 ---
 
+## Frameworks
+
+`<wick-chart>` is framework-agnostic — attributes, one `data` property,
+standard DOM events. The one opinionated wrapper ships as `wickchart/react`,
+which turns that contract into idiomatic React with proper event
+subscription/cleanup. `react` is an **optional** peer dependency: nothing
+changes if you never import `wickchart/react`.
+
+### React
+
+```bash
+npm install wickchart react
+```
+
+```jsx
+import { WickChart, useWickChart } from 'wickchart/react';
+
+// drop-in component — props map 1:1 onto the element
+export function PriceChart({ bars, onRange }) {
+  return (
+    <WickChart
+      type="candles"
+      indicators="sma:20 ema:50 volume"
+      volshading
+      label="BTC · 1h"
+      data={bars}                 // bars are assigned as a property
+      onRange={onRange}           // subscribes to wick:range
+      onAlert={(e) => toast(`crossed ${e.detail.price}`)}
+      style={{ height: 420 }}
+    />
+  );
+}
+
+// or the hook, when you need the imperative API
+function PracticeChart({ bars }) {
+  const { ref, chart } = useWickChart({ data: bars, indicators: 'sma:20' });
+  // chart.getDataWindow(), chart.addAlert(...), chart.getState() … after mount
+  return <wick-chart ref={ref} style={{ height: 420 }} />;
+}
+```
+
+Rules of thumb:
+
+- **Pass a fresh array** to `data` when the bars change — the binding compares
+  by reference, and reassignment is what triggers a redraw (don't mutate).
+  The same rule applies to `overlays` (see
+  [Server-side overlays](#server-side-overlays-zones--levels)).
+- **String/number/boolean props become attributes** (`type`, `indicators`,
+  `volshading`, …); `className`/`style`/`id` reach React as usual.
+- **`onXxx` subscribes to `wick:xxx`** with cleanup on unmount; an
+  `events={{ range: fn }}` object works too.
+- Works the same on React 16.8 → 19 — no custom-element event caveats.
+
+No build step? The [React demo](./demo/react.html) runs straight off a CDN
+import map — `react` and `react-dom` from esm.sh, the bindings from the
+package source.
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import 'wickchart';
+const chart = ref(null);
+const bars = ref([]);
+onMounted(async () => {
+  bars.value = await loadBars();
+  chart.value.data = bars.value;
+  chart.value.addEventListener('wick:range', (e) => console.log(e.detail));
+});
+</script>
+
+<template>
+  <wick-chart ref="chart" type="candles" indicators="sma:20"
+              style="height: 420px"></wick-chart>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  import 'wickchart';
+  let el;
+  let bars = [];
+  $: if (el && bars.length) el.data = bars;
+</script>
+
+<wick-chart bind:this={el} type="candles" indicators="sma:20"
+            on:wick:alert={(e) => console.log(e.detail)}
+            style="height: 420px"></wick-chart>
+```
+
+---
+
 ## Data format
 
 Bars are plain objects; `time` accepts **milliseconds or seconds** (auto-detected).
@@ -132,6 +235,7 @@ chart.setData([
 | `profile`     | off        | Volume profile overlay (POC + 70% value area)       |
 | `annotations` | off        | Smart annotations (volume spikes, gaps, pivots, RSI divergences) |
 | `volshading`  | off        | Volatility-regime background shading (see below)    |
+| `overlays`    | –          | JSON array of server-side zones & levels (see below) |
 
 \* `indicators=""` disables everything, including volume. Token syntax:
 `name[:param[/param…]][@color]` — e.g. `sma:20@#ff0000`, `macd:12/26/9`.
@@ -249,6 +353,69 @@ classifies everything as normal. The pieces are exported from
 `wickchart/core` (`calcRealizedVol`, `volRegimeBands`, `percentileOfSorted`)
 if you want to build on them.
 
+### Server-side overlays (zones & levels)
+
+Draw analysis from your own API straight onto the chart: supply/demand
+**zones** (time × price rectangles) and horizontal **levels**, rendered
+behind the candles. Zones without a `to` extend into future space past the
+last bar, like TradingView drawings.
+
+```js
+const res = await fetch('https://api.example.com/analysis?symbol=BTC');
+chart.setOverlays(await res.json());
+```
+
+```js
+[
+  // zone: from/to are timestamps (ms or s); null → chart edge
+  { type: 'zone', from: 1753920000000, priceFrom: 33000, priceTo: 35600,
+    color: '#ef5350', alpha: 0.25, label: 'demand' },
+  { type: 'zone', from: 1753920000000,                    // no `to` → extends
+    priceFrom: 37700, priceTo: 40900, color: '#26a69a' }, // to the right edge
+  // level: horizontal price line, full width by default
+  { type: 'level', price: 28700, color: '#3f51b5', label: 'S1' },
+  { type: 'level', price: 22800, color: '#3f51b5', dash: true },
+]
+```
+
+- `addOverlay(o)` upserts one (by `id`), `removeOverlay(id)`,
+  `clearOverlays()`, and `chart.overlays` reads them back.
+- Colors accept hex / `rgb()` / CSS names plus the palette keys
+  `up` | `down` | `accent`; `alpha` clamps to 0.02–0.8 (default 0.22).
+- Timestamps snap to bars (before the first bar clamps left, after the last
+  clamps right); invalid entries are dropped, never thrown — it's API data.
+- Fully declarative, too — the same JSON as an attribute:
+
+```html
+<wick-chart overlays='[{"type":"level","price":28700,"color":"#3f51b5","label":"S1"}]'></wick-chart>
+```
+
+The React binding takes `overlays` as a prop (fresh array → re-apply), and
+`normalizeOverlays` / `barIndexForTime` / `resolveOverlayColor` are exported
+from `wickchart/core`.
+
+### Scenario mode — ghost paths & volatility cones
+
+Project what-if into future space: a ghost path of hypothetical prices plus
+a volatility cone (±1σ/±2σ bands widening with √h from realized vol).
+
+```js
+chart.setScenario({
+  path: [64000, 65500, 66800, 68000], // prices for future bars 1..N
+  cone: true,                         // σ-bands from realized vol (default)
+  label: 'bull case',
+  color: 'up',                        // up | down | accent or safe colors
+});
+chart.setScenario({ horizon: 48 });   // cone-only projection
+chart.clearScenario();
+```
+
+Setting a scenario reserves future space on the right so the cone stays
+visible; the horizon defaults to the path length (1–500) and `levels` are σ
+multipliers (default `[1, 2]`). Like overlays, scenarios are analysis data —
+excluded from shareable state, and the same shape a server-side model could
+push. `calcVolCone` / `normalizeScenario` are exported from `wickchart/core`.
+
 ### AI-ready data window — `getDataWindow()`
 
 One call turns whatever is on screen into a compact, LLM-pasteable summary.
@@ -266,6 +433,31 @@ s.volPctile; // 84 → hot regime relative to the window itself
 s.patterns;  // [{ time, note }] — most recent first
 ```
 
+### AI agent interface — the chart as a tool surface
+
+The chart can publish its own **tool manifest** and accept validated
+tool-calls, so any LLM can operate it with zero glue code — the chart never
+touches the network; you supply the model call.
+
+```js
+chart.aiTools();    // manifest: get_data_window, set_indicators, set_overlays, add_alert, …
+chart.aiPrompt();   // system prompt demanding JSON [{tool, args}] ops
+chart.aiContext();  // grounding: current state + visible-window summary
+chart.applyAI(ops); // validated dispatcher — per-op {ok, result} / {ok:false, error}
+
+const { results } = await chart.ask(
+  'add RSI, mark the demand zone, and alert me on volume spikes',
+  { run: async (payload) => (await callMyLLM(payload)).ops }
+);
+```
+
+Every op is whitelisted and its args validated (indicator names checked
+against the registry, overlays through the sanitizer, enums enforced) — LLM
+output is treated as untrusted input, and a bad op returns an error the
+model can self-correct from instead of throwing. The
+[docs page](./docs.html) has a live playground driving `applyAI()` with an
+offline demo agent (no network, no keys).
+
 `text` renders like:
 
 ```
@@ -390,10 +582,17 @@ chart.addAlert({ price: 65000, direction: 'above' }); // 'above' | 'below' | 'cr
 chart.addEventListener('wick:alert', (e) => {
   console.log('crossed!', e.detail.id, e.detail.price);
 });
+
+// scripted alerts — any WickScript predicate, fired on its false→true edge
+chart.addAlert({ when: 'crossup(rsi(close,14), 30)' });
+chart.addAlert({ when: 'volume > sma(volume,20) * 3', once: false }); // re-arms
 ```
 
 The P&L chip recalculates on every streamed bar. Alerts are edge-triggered
 (fire once per crossing) and one-shot by default (`once: false` to re-arm).
+Scripted alerts are evaluated locally on every streamed bar — the event
+carries the triggering close as `price` plus the `when` source; an invalid
+predicate is rejected (`addAlert` returns `null`), never thrown.
 
 ### Stats & measure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wickchart",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "<wick-chart> — a modern, dependency-free financial charting web component. Candles, line & area charts, crosshair, zoom/pan, indicators (incl. a safe expression mini-language), live streaming via <wick-feed>, theming.",
   "type": "module",
   "main": "src/wick-chart.js",
@@ -18,6 +18,10 @@
     "./feed": {
       "types": "./types/wick-feed.d.ts",
       "default": "./src/wick-feed.js"
+    },
+    "./react": {
+      "types": "./types/react.d.ts",
+      "default": "./src/react.js"
     }
   },
   "files": [
@@ -25,14 +29,23 @@
     "types"
   ],
   "sideEffects": [
-    "src/wick-chart.js"
+    "src/wick-chart.js",
+    "src/react.js"
   ],
+  "peerDependencies": {
+    "react": ">=16.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "scripts": {
     "dev": "npx --yes serve . -l 5173",
     "test": "node --test \"tests/*.test.mjs\"",
     "build:types": "node -e \"require('fs').rmSync('types', { recursive: true, force: true });\" && tsc -p tsconfig.json",
     "prepack": "npm run build:types",
-    "ci": "npm run build:types && npm test && node --check src/wick-chart.js && node --check src/wick-feed.js && node --check src/core.js && node --check demo/app.js"
+    "ci": "npm run build:types && npm test && node --check src/wick-chart.js && node --check src/wick-feed.js && node --check src/core.js && node --check src/react.js && node --check src/react-core.js && node --check demo/app.js"
   },
   "keywords": [
     "chart",
@@ -52,6 +65,10 @@
     "url": "git+https://github.com/benyblack/wickchart.git"
   },
   "devDependencies": {
+    "@types/react": "^19.1.0",
+    "jsdom": "^26.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
     "typescript": "^7.0.2"
   }
 }