@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/utils/xAxisTickFormatter.d.ts

@@ -0,0 +1,33 @@
+import { type Timeframe } from "../../lib/types/adapter";
+export interface RawForkTickItem {
+    key: string;
+    x: number;
+    dataIndex: number;
+    date: Date;
+}
+export interface ForkXAxisTick {
+    key: string;
+    x: number;
+    label: string;
+}
+export declare function parseTimeframeToMinutes(timeframe: string): number;
+/**
+ * Format sequence of X-axis ticks adaptively based on tick interval,
+ * ensuring boundary transitions and zero identical adjacent labels.
+ */
+export declare function formatForkXAxisTicksSequence(ticks: readonly RawForkTickItem[], timeframe: Timeframe, pattern?: "yyyy-mm-dd" | "dd/mm/yyyy" | "mm/dd/yyyy"): ForkXAxisTick[];
+/**
+ * Format single X-axis label (for tooltips and backward compatibility)
+ */
+export declare function formatForkXAxisLabel(date: Date, timeframe: Timeframe, visibleBarCount: number, pattern?: "yyyy-mm-dd" | "dd/mm/yyyy" | "mm/dd/yyyy"): string;
+/**
+ * TradingView-style tick label with day-change awareness (follow-up V-01).
+ * Intraday: the first tick of a day shows the date, following ticks the SAME
+ * day show time only ("14:00") — adjacent duplicates like "16/09 16/09"
+ * become "16/09 14:00 18:00 17/09". Daily+ frames keep the base label.
+ * Returns the label plus the day key the caller threads to the next tick.
+ */
+export declare function resolveForkTickLabel(date: Date, timeframe: Timeframe, visibleBarCount: number, pattern?: "yyyy-mm-dd" | "dd/mm/yyyy" | "mm/dd/yyyy", prevDayKey?: string | null): {
+    label: string;
+    dayKey: string;
+};

package/dist/dts/widget/visibleRangeBridge.d.ts

@@ -0,0 +1,28 @@
+import type { VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+import type { VisibleRange } from "../lib/core";
+export interface DateBackedDatum {
+    date: Date;
+}
+export declare function clampIndex(index: number, length: number): number;
+export declare function clampToRange(value: number, min: number, max: number): number;
+export declare function asTimeValue(value: Date | number): number;
+export declare function findNearestDateIndex(data: readonly DateBackedDatum[], targetTime: number): number;
+export declare function normalizeForkVisibleRange(range: EngineVisibleRange, data: readonly DateBackedDatum[]): VisibleRange | null;
+export declare function normalizeEngineVisibleRange(visibleRange: EngineVisibleRange | null, dataLength: number): EngineVisibleRange | null;
+/**
+ * Fork runtime variant of normalizeEngineVisibleRange that preserves fractional
+ * precision. Skips Math.floor/ Math.ceil to avoid coordinate mismatch between
+ * the bridge projector (used for hit-testing) and the engine projector (used
+ * for canvas rendering) after biased zoom operations.
+ *
+ * Only enforces:
+ *  - from <= to (swapped if needed)
+ *  - finite number checks
+ *  - non-negative from (clamped to 0)
+ *
+ * Does NOT clamp to dataLength or round to integers — the fork engine maintains
+ * its own valid range and may intentionally show empty space beyond data bounds.
+ */
+export declare function normalizeVisibleRangeFork(visibleRange: EngineVisibleRange | null, _dataLength: number): EngineVisibleRange | null;
+export declare function normalizeVisibleRangeForEngine(visibleRange: EngineVisibleRange | VisibleRange | null, dataLength: number): EngineVisibleRange | null;
+export declare function resolveForkVisibleRangeFromDateExtents(extents: readonly [Date | number, Date | number], data: readonly DateBackedDatum[]): EngineVisibleRange | null;

package/dist/dts/widget/visibleRangeDiagnostics.d.ts

@@ -0,0 +1,10 @@
+type DateDomain = [Date, Date];
+type RangeLike = {
+    from: number;
+    to: number;
+};
+export declare function areVisibleDomainsEqual(left: DateDomain | null, right: DateDomain | null): boolean;
+export declare function isForkRangeTraceEnabled(): boolean;
+export declare function traceForkRange(_event: string, _payload: Record<string, unknown>): void;
+export declare function areEngineVisibleRangesEqual<T extends RangeLike>(left: T | null, right: T | null): boolean;
+export {};

package/dist/dts/widget/visibleRangePolicies.d.ts

@@ -0,0 +1,6 @@
+import type { VisibleRange as EngineVisibleRange } from "@vninvestcharts/engine-core";
+export interface OverflowHistoryQueueState {
+    overflowKey: string | null;
+    shouldForceQueue: boolean;
+}
+export declare function resolveOverflowHistoryQueueState(range: EngineVisibleRange, dataLength: number, leftBoundaryReached: boolean, rightBoundaryReached: boolean, lastOverflowKey: string | null): OverflowHistoryQueueState;

package/dist/dts/widget/workspace/WorkspaceManager.d.ts

@@ -0,0 +1,23 @@
+import { WorkspaceData } from './types';
+import type { StorageAdapter } from '@vninvestcharts/engine-react';
+export declare class WorkspaceManager {
+    private static VERSION;
+    private static autoSaveTimers;
+    static save(workspace: WorkspaceData, storageAdapter: StorageAdapter): Promise<void>;
+    static scheduleAutoSave(workspaceId: string, getWorkspaceData: () => WorkspaceData, storageAdapter: StorageAdapter, delayMs?: number): void;
+    static cancelAutoSave(workspaceId: string): void;
+    static cancelAllAutoSaves(): void;
+    static load(id: string, storageAdapter: StorageAdapter): Promise<WorkspaceData | null>;
+    static list(storageAdapter: StorageAdapter): Promise<{
+        id: string;
+        name: string;
+        updatedAt: number;
+    }[]>;
+    static addToIndex(workspace: {
+        id: string;
+        name: string;
+        updatedAt: number;
+    }, storageAdapter: StorageAdapter): Promise<void>;
+    static delete(id: string, storageAdapter: StorageAdapter): Promise<void>;
+    private static validateAndMigrate;
+}

package/dist/dts/widget/workspace/WorkspaceStore.d.ts

@@ -0,0 +1,85 @@
+import { type PatTier } from "@vninvestcharts/engine-core";
+import type { StorageAdapter } from "@vninvestcharts/engine-react";
+import type { WorkspaceData } from "./types";
+/**
+ * WorkspaceStore — lớp trừu tượng duy nhất cho **phạm vi lưu trữ workspace**
+ * (W0.7, PLAN_FRONTEND_PROPLUS_TRACKA §2.6).
+ *
+ * Vì sao cần: hiện `useMultiWorkspacePersistence.ts:109,116` gọi thẳng
+ * `WorkspaceManager.save/load` với `storageAdapter` (localStorage). UI **không có
+ * cách nào biết** dữ liệu đang nằm ở đâu ⇒ không thể trung thực với người dùng,
+ * và khi backend có workspace API (EP-8) thì phải sửa lại mọi call site.
+ *
+ * Nguyên tắc (AGENTS.md Rule 15 — cấm fake):
+ * - `scope: "local"` là **trạng thái thật**, không phải placeholder.
+ * - `RemoteWorkspaceAdapter` **ném 501**, KHÔNG fallback âm thầm về local
+ *   (fallback im lặng sẽ khiến người dùng tưởng đã sync lên cloud).
+ * - Đổi từ local sang cloud khi EP-8 tới = sửa **một dòng** factory.
+ */
+export type WorkspaceScope = "local" | "cloud";
+export interface WorkspaceIndexEntry {
+    id: string;
+    name: string;
+    updatedAt: number;
+}
+export interface WorkspaceStore {
+    readonly scope: WorkspaceScope;
+    list(): Promise<WorkspaceIndexEntry[]>;
+    load(id: string): Promise<WorkspaceData | null>;
+    save(data: WorkspaceData): Promise<void>;
+    remove(id: string): Promise<void>;
+    /** Đồng bộ nhiều thiết bị chưa có backend (EP-8). */
+    readonly supportsMultiDevice: boolean;
+}
+/** Lỗi có mã để UI hiển thị đúng thay vì nuốt im lặng. */
+export declare class WorkspaceStoreError extends Error {
+    readonly code: "not_implemented" | "conflict" | "quota_exceeded" | "unavailable";
+    constructor(message: string, code: "not_implemented" | "conflict" | "quota_exceeded" | "unavailable");
+}
+export declare class LocalWorkspaceStore implements WorkspaceStore {
+    private readonly storage;
+    readonly scope: "local";
+    readonly supportsMultiDevice = false;
+    constructor(storage?: StorageAdapter);
+    list(): Promise<WorkspaceIndexEntry[]>;
+    load(id: string): Promise<WorkspaceData | null>;
+    save(data: WorkspaceData): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+export declare class RemoteWorkspaceStore implements WorkspaceStore {
+    readonly scope: "cloud";
+    readonly supportsMultiDevice = true;
+    /**
+     * Ném **promise bị từ chối**, không throw đồng bộ.
+     *
+     * Lý do: interface khai `Promise<T>`, nên caller viết `store.list().catch(...)`
+     * phải bắt được. `throw` đồng bộ sẽ vượt qua `.catch` và làm hỏng luồng
+     * async của người gọi.
+     */
+    private unavailable;
+    list(): Promise<WorkspaceIndexEntry[]>;
+    load(_id: string): Promise<WorkspaceData | null>;
+    save(_data: WorkspaceData): Promise<void>;
+    remove(_id: string): Promise<void>;
+}
+export interface ResolveStoreInput {
+    /** Có capability `server_workspace` không (đã bao gồm narrowing của license). */
+    allowsCloud: boolean;
+    storageAdapter?: StorageAdapter | null;
+    /**
+     * Backend đã sẵn sàng chưa (probe `/core/v1/health`).
+     *
+     * Đây là điều kiện **thứ hai** bên cạnh `allowsCloud`. Cần cả hai vì:
+     * khách enterprise mà backend workspace (EP-8) chưa triển khai sẽ nhận
+     * `501` và **mất hoàn toàn tính năng lưu workspace**. Tệ hơn nhiều so với
+     * lưu local kèm badge trung thực "Chỉ lưu trên thiết bị này — dịch vụ
+     * cloud chưa sẵn sàng". Vì vậy thiếu backend ⇒ **local + badge**, không phải
+     * lỗi. Đây là degrade có kiểm soát (không phải giả lập cloud).
+     */
+    backendReady?: boolean;
+    /** Chỉ dùng cho test. */
+    forceRemote?: boolean;
+}
+export declare function resolveWorkspaceStore(input: ResolveStoreInput): WorkspaceStore;
+/** Rút gọn: suy ra `allowsCloud` từ tier + narrowing license. */
+export declare function allowsCloudWorkspace(tier: PatTier | null | undefined, narrowing?: readonly string[]): boolean;

package/dist/dts/widget/workspace/types.d.ts

@@ -0,0 +1,21 @@
+import { GridLayout } from '../grid/types';
+import { DrawingData, SyncGroupState, SymbolLinkGroupId, VisibleRangePayload } from '@vninvestcharts/engine-react';
+export interface WorkspaceData {
+    id: string;
+    name: string;
+    layout: GridLayout;
+    charts: {
+        id: string;
+        symbol: string;
+        timeframe: string;
+        visibleRange?: VisibleRangePayload;
+        symbolLinkGroup?: SymbolLinkGroupId | null;
+        engineState?: Record<string, unknown>;
+    }[];
+    drawings: DrawingData[];
+    syncGroups: SyncGroupState[];
+    activeChartId?: string | null;
+    createdAt: number;
+    updatedAt: number;
+    version: number;
+}

package/dist/externalBarsNormalization.worker.js

@@ -0,0 +1,108 @@
+// src/widget/history/externalBarsNormalization.ts
+function normalizeExternalBar(bar, index) {
+  if (!bar || typeof bar !== "object") {
+    throw new Error("Invalid bar format");
+  }
+  const record = bar;
+  let date = null;
+  const rawDate = record.date ?? record.time ?? record.timestamp ?? record.t;
+  if (rawDate instanceof Date) {
+    date = rawDate;
+  } else if (typeof rawDate === "number" || typeof rawDate === "string") {
+    date = new Date(rawDate);
+  }
+  if (!date || isNaN(date.getTime())) {
+    throw new Error(`Invalid bar date: ${JSON.stringify(rawDate)}`);
+  }
+  const openVal = record.open ?? record.o;
+  const highVal = record.high ?? record.h;
+  const lowVal = record.low ?? record.l;
+  const closeVal = record.close ?? record.c;
+  const volumeVal = record.volume ?? record.v ?? 0;
+  const open = typeof openVal === "number" ? openVal : parseFloat(String(openVal));
+  const high = typeof highVal === "number" ? highVal : parseFloat(String(highVal));
+  const low = typeof lowVal === "number" ? lowVal : parseFloat(String(lowVal));
+  const close = typeof closeVal === "number" ? closeVal : parseFloat(String(closeVal));
+  const volume = typeof volumeVal === "number" ? volumeVal : parseFloat(String(volumeVal));
+  if (isNaN(open) || isNaN(high) || isNaN(low) || isNaN(close) || isNaN(volume)) {
+    throw new Error(`Invalid OHLCV numeric values: ${JSON.stringify(bar)}`);
+  }
+  return {
+    date,
+    open,
+    high,
+    low,
+    close,
+    volume,
+    buyVolume: record.buyVolume !== void 0 ? Number(record.buyVolume) : void 0,
+    sellVolume: record.sellVolume !== void 0 ? Number(record.sellVolume) : void 0,
+    foreignBuy: record.foreignBuy !== void 0 ? Number(record.foreignBuy) : void 0,
+    foreignSell: record.foreignSell !== void 0 ? Number(record.foreignSell) : void 0,
+    openInterest: record.openInterest !== void 0 ? Number(record.openInterest) : void 0,
+    index: record.index !== void 0 ? Number(record.index) : index,
+    dataIndex: record.dataIndex !== void 0 ? Number(record.dataIndex) : index
+  };
+}
+function normalizeExternalBars(data) {
+  if (!data || !Array.isArray(data)) {
+    return {
+      bars: [],
+      invalidCount: 0,
+      firstError: null
+    };
+  }
+  const bars = [];
+  let invalidCount = 0;
+  let firstError = null;
+  for (let index = 0; index < data.length; index += 1) {
+    const bar = data[index];
+    try {
+      bars.push(normalizeExternalBar(bar, index));
+    } catch (err) {
+      invalidCount += 1;
+      if (firstError === null) {
+        const detail = err instanceof Error ? err.message : String(err);
+        firstError = `index=${index}; reason=${detail}`;
+      }
+    }
+  }
+  const sortedBars = [...bars].sort((left, right) => left.date.getTime() - right.date.getTime());
+  const dedupedBars = [];
+  for (const bar of sortedBars) {
+    const barTime = bar.date.getTime();
+    const lastBar = dedupedBars[dedupedBars.length - 1];
+    if (lastBar && lastBar.date.getTime() === barTime) {
+      dedupedBars[dedupedBars.length - 1] = bar;
+      continue;
+    }
+    dedupedBars.push(bar);
+  }
+  const normalizedBars = dedupedBars.map((bar, index) => ({
+    ...bar,
+    index,
+    dataIndex: index
+  }));
+  return {
+    bars: normalizedBars,
+    invalidCount,
+    firstError
+  };
+}
+
+// src/widget/history/externalBarsNormalization.worker.ts
+self.onmessage = (event) => {
+  const { requestId, data } = event.data;
+  try {
+    const response = {
+      requestId,
+      result: normalizeExternalBars(data)
+    };
+    self.postMessage(response);
+  } catch (error) {
+    const response = {
+      requestId,
+      error: error instanceof Error ? error.message : String(error)
+    };
+    self.postMessage(response);
+  }
+};

package/dist/iframe/index.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<!-- 
+		NOTE: frame-ancestors CSP directive MUST be set via HTTP Response Header, not meta tag.
+		Browsers ignore frame-ancestors in meta tags.
+		
+		Configure your web server (Nginx, Apache, Cloudflare, etc.) to send:
+		Content-Security-Policy: frame-ancestors 'self' https://vninvestcharts.com https://app.vninvestcharts.com https://charts.vninvestcharts.com http://localhost:3000 http://localhost:5173;
+		
+		The IframeBridge also validates origins dynamically against an allowlist for defense-in-depth.
+	-->
+	<title>VNInvestCharts Widget</title>
+	<style>
+		* {
+			margin: 0;
+			padding: 0;
+			box-sizing: border-box;
+		}
+		html, body {
+			width: 100%;
+			height: 100%;
+			overflow: hidden;
+			background: #0a0e14;
+		}
+		#root {
+			width: 100%;
+			height: 100%;
+		}
+		/* Loading state */
+		.loading {
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			width: 100%;
+			height: 100%;
+			color: #64748b;
+			font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+			font-size: 14px;
+		}
+		.loading::after {
+			content: "";
+			width: 20px;
+			height: 20px;
+			border: 2px solid #2962ff;
+			border-top-color: transparent;
+			border-radius: 50%;
+			animation: spin 0.8s linear infinite;
+			margin-left: 12px;
+		}
+		@keyframes spin {
+			to { transform: rotate(360deg); }
+		}
+	</style>
+</head>
+<body>
+	<div id="root" class="loading">Loading VNInvestCharts...</div>
+	<!-- The iframe bundle will be injected here by the build system -->
+	<script src="./vninvestchart.iframe.js"></script>
+</body>
+</html>