@invinite-org/chartlang-adapter-kit 1.3.0 → 1.5.0

package/dist/interaction/viewController.js

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 Invinite. Licensed under the MIT License.
+// See the LICENSE file in the repo root for full license text.
+const DEFAULT_MIN_SPAN = 1;
+const DEFAULT_MAX_SPAN_FACTOR = 1;
+// Clamp a candidate window: bound its span to [minSpan, maxSpan] (maxSpan =
+// dataSpan * maxSpanFactor), then shift it to sit inside [dataMin, dataMax]
+// when it fits, or pin it to the full data range when it is at least as wide
+// as the data. The single clamp shared by zoom / pan / resolve.
+function clampWindow(win, dataMin, dataMax, minSpan, maxSpanFactor) {
+    const dataSpan = Math.max(0, dataMax - dataMin);
+    const maxSpan = dataSpan * maxSpanFactor;
+    let span = win.xMax - win.xMin;
+    if (maxSpan > 0 && span > maxSpan)
+        span = maxSpan;
+    if (span < minSpan)
+        span = minSpan;
+    const center = (win.xMin + win.xMax) / 2;
+    let xMin = center - span / 2;
+    let xMax = center + span / 2;
+    if (span <= dataSpan) {
+        if (xMin < dataMin) {
+            xMax += dataMin - xMin;
+            xMin = dataMin;
+        }
+        if (xMax > dataMax) {
+            xMin -= xMax - dataMax;
+            xMax = dataMax;
+        }
+        return { xMin, xMax };
+    }
+    return { xMin: dataMin, xMax: dataMax };
+}
+/**
+ * Build a {@link ViewController}. Pass `opts` to tune the zoom-in floor
+ * (`minSpan`) and zoom-out ceiling (`maxSpanFactor`); both default to a
+ * "1 ms floor, all-data ceiling" policy.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const view = createViewController({ minSpan: 2, maxSpanFactor: 1 });
+ *     view.zoomAt(50, 0.5, 0, 100); // zoom in 2× about x=50
+ *     void view.resolveXWindow(0, 100);
+ */
+export function createViewController(opts) {
+    const minSpan = opts?.minSpan ?? DEFAULT_MIN_SPAN;
+    const maxSpanFactor = opts?.maxSpanFactor ?? DEFAULT_MAX_SPAN_FACTOR;
+    let held;
+    let interacted = false;
+    const base = (dataMin, dataMax) => held ?? { xMin: dataMin, xMax: dataMax };
+    return {
+        get userInteracted() {
+            return interacted;
+        },
+        resolveXWindow(dataMin, dataMax) {
+            if (!interacted || held === undefined)
+                return { xMin: dataMin, xMax: dataMax };
+            return clampWindow(held, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        zoomAt(pivotX, factor, dataMin, dataMax) {
+            interacted = true;
+            const b = base(dataMin, dataMax);
+            const span = b.xMax - b.xMin;
+            const frac = span === 0 ? 0.5 : (pivotX - b.xMin) / span;
+            const newSpan = span * factor;
+            const xMin = pivotX - frac * newSpan;
+            held = clampWindow({ xMin, xMax: xMin + newSpan }, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        panBy(deltaWorldX, dataMin, dataMax) {
+            interacted = true;
+            const b = base(dataMin, dataMax);
+            held = clampWindow({ xMin: b.xMin + deltaWorldX, xMax: b.xMax + deltaWorldX }, dataMin, dataMax, minSpan, maxSpanFactor);
+        },
+        reset() {
+            held = undefined;
+            interacted = false;
+        },
+    };
+}
+/**
+ * Fold the y range of every candidate whose `x` falls inside `win` — the
+ * shared "auto-fit the price scale to the visible window" helper (matching
+ * lightweight-charts' auto price scale). Non-finite `lo`/`hi` rows are
+ * skipped. Returns `undefined` when no finite in-window candidate is seen,
+ * so the caller keeps its own degenerate-range fallback. Horizontal lines
+ * (no `x`) are folded in by the caller, not here.
+ *
+ * @since 1.6
+ * @stable
+ * @example
+ *     const r = yRangeInWindow([{ x: 5, lo: 1, hi: 3 }], { xMin: 0, xMax: 10 });
+ *     // r === { yMin: 1, yMax: 3 }
+ *     void r;
+ */
+export function yRangeInWindow(candidates, win) {
+    let yMin = Number.POSITIVE_INFINITY;
+    let yMax = Number.NEGATIVE_INFINITY;
+    for (const c of candidates) {
+        if (c.x < win.xMin || c.x > win.xMax)
+            continue;
+        if (!Number.isFinite(c.lo) || !Number.isFinite(c.hi))
+            continue;
+        if (c.lo < yMin)
+            yMin = c.lo;
+        if (c.hi > yMax)
+            yMax = c.hi;
+    }
+    if (!Number.isFinite(yMin) || !Number.isFinite(yMax))
+        return undefined;
+    return { yMin, yMax };
+}
+//# sourceMappingURL=viewController.js.map

package/dist/interaction/viewController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewController.js","sourceRoot":"","sources":["../../src/interaction/viewController.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Invinite. Licensed under the MIT License.\n// See the LICENSE file in the repo root for full license text.\n\n/**\n * A visible window into the world x axis (bar times in UTC ms). The two\n * self-scaled adapters (canvas2d, konva) resolve one per frame from a\n * {@link ViewController} and feed `xMin`/`xMax` into their `Viewport`.\n *\n * @since 1.6\n * @stable\n * @example\n *     const win: XWindow = { xMin: 0, xMax: 100 };\n *     void win;\n */\nexport type XWindow = { readonly xMin: number; readonly xMax: number };\n\n/**\n * Construction options for {@link createViewController}. `minSpan` is the\n * smallest world-x span a zoom-in can reach (so the window never collapses\n * to a point); `maxSpanFactor` is the largest span a zoom-out can reach as\n * a multiple of the current data span (default `1` ⇒ cannot zoom out past\n * \"all data visible\").\n *\n * @since 1.6\n * @stable\n * @example\n *     const opts: ViewControllerOpts = { minSpan: 1, maxSpanFactor: 1 };\n *     void opts;\n */\nexport type ViewControllerOpts = {\n    readonly minSpan?: number;\n    readonly maxSpanFactor?: number;\n};\n\n/**\n * Stateful, library-agnostic pan/zoom controller for an adapter that\n * computes its own x scale every frame. It holds a user x-window plus a\n * `userInteracted` flag: until the user wheels or drags, {@link\n * ViewController.resolveXWindow} returns the full data range (auto-follow\n * live bars); after the first interaction it returns the held window\n * (re-clamped as data grows), so live frames stop snapping the view back.\n *\n * All transforms are pure functions of the current state + the supplied\n * data bounds — there is no DOM or library coupling. The example adapters\n * wire DOM events to {@link ViewController.zoomAt} / {@link\n * ViewController.panBy} / {@link ViewController.reset} via {@link\n * attachInteraction}.\n *\n * @since 1.6\n * @stable\n * @example\n *     const view = createViewController();\n *     view.resolveXWindow(0, 100); // { xMin: 0, xMax: 100 } (auto-follow)\n *     view.panBy(10, 0, 100);\n *     view.userInteracted; // true\n */\nexport type ViewController = {\n    /** `true` once the user has zoomed or panned (auto-follow is paused). */\n    readonly userInteracted: boolean;\n    /**\n     * The x-window to render this frame: `[dataXMin, dataXMax]` while not\n     * interacted (auto-follow), else the held window clamped into the\n     * current data bounds.\n     */\n    resolveXWindow(dataXMin: number, dataXMax: number): XWindow;\n    /** Zoom by `factor` (`<1` in, `>1` out) about a world-x pivot. */\n    zoomAt(pivotX: number, factor: number, dataXMin: number, dataXMax: number): void;\n    /** Pan the window by a signed world-x delta. */\n    panBy(deltaWorldX: number, dataXMin: number, dataXMax: number): void;\n    /** Clear the held window + flag so the view auto-follows again. */\n    reset(): void;\n};\n\nconst DEFAULT_MIN_SPAN = 1;\nconst DEFAULT_MAX_SPAN_FACTOR = 1;\n\n// Clamp a candidate window: bound its span to [minSpan, maxSpan] (maxSpan =\n// dataSpan * maxSpanFactor), then shift it to sit inside [dataMin, dataMax]\n// when it fits, or pin it to the full data range when it is at least as wide\n// as the data. The single clamp shared by zoom / pan / resolve.\nfunction clampWindow(\n    win: XWindow,\n    dataMin: number,\n    dataMax: number,\n    minSpan: number,\n    maxSpanFactor: number,\n): XWindow {\n    const dataSpan = Math.max(0, dataMax - dataMin);\n    const maxSpan = dataSpan * maxSpanFactor;\n    let span = win.xMax - win.xMin;\n    if (maxSpan > 0 && span > maxSpan) span = maxSpan;\n    if (span < minSpan) span = minSpan;\n    const center = (win.xMin + win.xMax) / 2;\n    let xMin = center - span / 2;\n    let xMax = center + span / 2;\n    if (span <= dataSpan) {\n        if (xMin < dataMin) {\n            xMax += dataMin - xMin;\n            xMin = dataMin;\n        }\n        if (xMax > dataMax) {\n            xMin -= xMax - dataMax;\n            xMax = dataMax;\n        }\n        return { xMin, xMax };\n    }\n    return { xMin: dataMin, xMax: dataMax };\n}\n\n/**\n * Build a {@link ViewController}. Pass `opts` to tune the zoom-in floor\n * (`minSpan`) and zoom-out ceiling (`maxSpanFactor`); both default to a\n * \"1 ms floor, all-data ceiling\" policy.\n *\n * @since 1.6\n * @stable\n * @example\n *     const view = createViewController({ minSpan: 2, maxSpanFactor: 1 });\n *     view.zoomAt(50, 0.5, 0, 100); // zoom in 2× about x=50\n *     void view.resolveXWindow(0, 100);\n */\nexport function createViewController(opts?: ViewControllerOpts): ViewController {\n    const minSpan = opts?.minSpan ?? DEFAULT_MIN_SPAN;\n    const maxSpanFactor = opts?.maxSpanFactor ?? DEFAULT_MAX_SPAN_FACTOR;\n    let held: XWindow | undefined;\n    let interacted = false;\n\n    const base = (dataMin: number, dataMax: number): XWindow =>\n        held ?? { xMin: dataMin, xMax: dataMax };\n\n    return {\n        get userInteracted(): boolean {\n            return interacted;\n        },\n        resolveXWindow(dataMin: number, dataMax: number): XWindow {\n            if (!interacted || held === undefined) return { xMin: dataMin, xMax: dataMax };\n            return clampWindow(held, dataMin, dataMax, minSpan, maxSpanFactor);\n        },\n        zoomAt(pivotX: number, factor: number, dataMin: number, dataMax: number): void {\n            interacted = true;\n            const b = base(dataMin, dataMax);\n            const span = b.xMax - b.xMin;\n            const frac = span === 0 ? 0.5 : (pivotX - b.xMin) / span;\n            const newSpan = span * factor;\n            const xMin = pivotX - frac * newSpan;\n            held = clampWindow(\n                { xMin, xMax: xMin + newSpan },\n                dataMin,\n                dataMax,\n                minSpan,\n                maxSpanFactor,\n            );\n        },\n        panBy(deltaWorldX: number, dataMin: number, dataMax: number): void {\n            interacted = true;\n            const b = base(dataMin, dataMax);\n            held = clampWindow(\n                { xMin: b.xMin + deltaWorldX, xMax: b.xMax + deltaWorldX },\n                dataMin,\n                dataMax,\n                minSpan,\n                maxSpanFactor,\n            );\n        },\n        reset(): void {\n            held = undefined;\n            interacted = false;\n        },\n    };\n}\n\n/**\n * One candidate row for {@link yRangeInWindow}: a world `x` (bar time) plus\n * the low / high values to fold into the y range when `x` is inside the\n * window. Bars pass `{ x: time, lo: low, hi: high }`; a scalar series point\n * passes `lo === hi === value`.\n *\n * @since 1.6\n * @stable\n * @example\n *     const c: WindowYInput = { x: 10, lo: 99, hi: 101 };\n *     void c;\n */\nexport type WindowYInput = { readonly x: number; readonly lo: number; readonly hi: number };\n\n/**\n * Fold the y range of every candidate whose `x` falls inside `win` — the\n * shared \"auto-fit the price scale to the visible window\" helper (matching\n * lightweight-charts' auto price scale). Non-finite `lo`/`hi` rows are\n * skipped. Returns `undefined` when no finite in-window candidate is seen,\n * so the caller keeps its own degenerate-range fallback. Horizontal lines\n * (no `x`) are folded in by the caller, not here.\n *\n * @since 1.6\n * @stable\n * @example\n *     const r = yRangeInWindow([{ x: 5, lo: 1, hi: 3 }], { xMin: 0, xMax: 10 });\n *     // r === { yMin: 1, yMax: 3 }\n *     void r;\n */\nexport function yRangeInWindow(\n    candidates: Iterable<WindowYInput>,\n    win: XWindow,\n): { readonly yMin: number; readonly yMax: number } | undefined {\n    let yMin = Number.POSITIVE_INFINITY;\n    let yMax = Number.NEGATIVE_INFINITY;\n    for (const c of candidates) {\n        if (c.x < win.xMin || c.x > win.xMax) continue;\n        if (!Number.isFinite(c.lo) || !Number.isFinite(c.hi)) continue;\n        if (c.lo < yMin) yMin = c.lo;\n        if (c.hi > yMax) yMax = c.hi;\n    }\n    if (!Number.isFinite(yMin) || !Number.isFinite(yMax)) return undefined;\n    return { yMin, yMax };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invinite-org/chartlang-adapter-kit",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "license": "MIT",
   "description": "SDK for writing chartlang adapters in consumer repos",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./canvas": {
+      "types": "./dist/canvas/index.d.ts",
+      "import": "./dist/canvas/index.js"
     }
   },
   "files": [
@@ -21,6 +25,9 @@
   "dependencies": {
     "@invinite-org/chartlang-core": "^1.2.0"
   },
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true