@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/hooks/useChartImperativeHandle.d.ts

@@ -0,0 +1,57 @@
+export interface ChartImperativeHandleContext {
+    props: any;
+    localSymbol: any;
+    settings: any;
+    isForkRuntime: any;
+    engineInstanceRef: any;
+    dataResult: any;
+    resolvedLegacyVisibleRange: any;
+    paneState: any;
+    comparisonState: any;
+    drawingsResult: any;
+    replay: any;
+    /**
+     * W1.4 — single entitlement source for image export. When false, the public
+     * `saveAsImage()` ref method is a no-op, so a host integration cannot bypass the
+     * UI gate. Same shape as `canUseReplay` above: **required boolean, truthy check**
+     * ⇒ `undefined` counts as not granted (fail-closed).
+     */
+    canExportImage: boolean;
+    /** Called instead of exporting when the tier does not grant it. */
+    onExportBlocked?: () => void;
+    /**
+     * AUTH-03: single entitlement source for replay. Every mutating replay entry
+     * point is a no-op when false, so a Free tier cannot drive replay through the
+     * imperative ref even if it bypasses the UI gate.
+     */
+    canUseReplay: boolean;
+    replayTrading: any;
+    replayAwaitingStartBar: any;
+    setLegacyVisibleRange: any;
+    setChartType: any;
+    setIsFrozen: any;
+    isFrozen: any;
+    setAlertsModalOpen: any;
+    setReplayAwaitingStartBar: any;
+    isRemoteVisibleRangeRef: any;
+    lastRemoteRangeRef: any;
+    pendingSyncTimeRangeRef: any;
+    visibleRangeTimeoutRef: any;
+    isRemoteCrosshairRef: any;
+    isRemoteDrawingChangeRef: any;
+    syncDrawingHandlersRef: any;
+    syncViewportHandlersRef: any;
+    replayBarVisibleRef: any;
+    replayAwaitingStartBarRef: any;
+    suppressReplayTickRef: any;
+    onDataChangeCallbacks: any;
+    onIndicatorsChangeCallbacks: any;
+    containerRef: any;
+    handleSaveTemplate: any;
+    handleLoadTemplate: any;
+    legacyPaneSnapshots: any;
+    paneSnapshots: any;
+    legacyCoordinateBridge: any;
+    CHART_TYPE_MAP: any;
+}
+export declare function useChartImperativeHandle(ref: any, ctx: ChartImperativeHandleContext): void;

package/dist/dts/widget/hooks/useClockAdapter.d.ts

@@ -0,0 +1,11 @@
+import type { ClockAdapter } from "@vninvestcharts/engine-react";
+export interface UseClockAdapterOptions {
+    clockAdapter?: ClockAdapter;
+}
+export declare function useClockAdapter(options?: UseClockAdapterOptions): {
+    now: () => number;
+    requestFrame: (callback: (time: number) => void) => number;
+    cancelFrame: (id: number) => void;
+    setTimeout: (callback: () => void, delay: number) => number;
+    clearTimeout: (id: number) => void;
+};

package/dist/dts/widget/hooks/useComparisonState.d.ts

@@ -0,0 +1,29 @@
+export interface ComparisonOverlayEntry {
+    symbolId: string;
+    normalizeToBaseline: boolean;
+    visible: boolean;
+    color: string;
+    yAxis: "left" | "right";
+    lineWidth: number;
+    lineStyle: "solid" | "dashed" | "dotted";
+    fillArea: boolean;
+}
+export interface UseComparisonStateResult {
+    /** Stable per-mount identity. Feed to comparisonSeriesId to build this chart's series ids. */
+    scope: string;
+    overlays: ComparisonOverlayEntry[];
+    addSymbol: (symbolId: string, options?: {
+        normalizeToBaseline?: boolean;
+        color?: string;
+        yAxis?: "left" | "right";
+        lineWidth?: number;
+        lineStyle?: "solid" | "dashed" | "dotted";
+        fillArea?: boolean;
+    }) => void;
+    removeSymbol: (symbolId: string) => void;
+    toggleVisibility: (symbolId: string) => void;
+    updateOverlay: (symbolId: string, partial: Partial<ComparisonOverlayEntry>) => void;
+}
+export declare function createComparisonScope(): string;
+export declare function comparisonSeriesId(scope: string, symbolId: string): string;
+export declare function useComparisonState(storageId?: string | null): UseComparisonStateResult;

package/dist/dts/widget/hooks/useDialogFocus.d.ts

@@ -0,0 +1,25 @@
+import { type RefObject } from "react";
+export interface UseDialogFocusOptions {
+    /** Whether the dialog is currently open. Focus is only managed while true. */
+    open: boolean;
+    /** Escape key handler. */
+    onEscape?: () => void;
+    /** Element to focus on open. Falls back to the first focusable node. */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Disable the Tab loop (for non-modal panels). */
+    trapTab?: boolean;
+}
+/**
+ * UX-02 — shared dialog focus contract.
+ *
+ * Before this hook each dialog handled focus ad hoc, so none of them trapped
+ * Tab and none returned focus to the trigger: keyboard users were stranded
+ * inside a modal, and after closing it focus fell back to the document root.
+ *
+ * Responsibilities:
+ *  - move focus into the dialog on open (explicit target, else first focusable)
+ *  - keep Tab / Shift+Tab inside the dialog while it is open
+ *  - call `onEscape` on Escape
+ *  - restore focus to the element focused before the dialog opened
+ */
+export declare function useDialogFocus(containerRef: RefObject<HTMLElement | null>, { open, onEscape, initialFocusRef, trapTab }: UseDialogFocusOptions): void;

package/dist/dts/widget/hooks/useDrawingToolShortcuts.d.ts

@@ -0,0 +1,16 @@
+import type { PatTier } from "@vninvestcharts/engine-core";
+interface DrawingToolShortcutsOptions {
+    onToolSelect: (toolId: string) => void;
+    /** Current PAT tier for premium tool gating. Defaults to "free" when undefined. */
+    patTier?: PatTier;
+    /** Called when a premium tool is blocked via keyboard shortcut */
+    onPremiumToolClick?: (tool: string) => void;
+    /** S2.1: when false, no listener is registered (standalone-only mount). */
+    enabled?: boolean;
+    /** S4/BUG-6: Shift+M magnet cycle (non-tool action, branched before premium gate). */
+    onMagnetCycle?: () => void;
+}
+/** S4: action id reserved for magnet cycling — never a DrawingToolType. */
+export declare const MAGNET_TOGGLE_ACTION = "toggleMagnet";
+export declare function useDrawingToolShortcuts({ onToolSelect, patTier, onPremiumToolClick, enabled, onMagnetCycle }: DrawingToolShortcutsOptions): void;
+export {};

package/dist/dts/widget/hooks/useFeatureGate.d.ts

@@ -0,0 +1,28 @@
+import { SaaSFeatureFlags, TenantMetadata, AdCampaign } from '../types/saas';
+export interface UseFeatureGateReturn {
+    isLoading: boolean;
+    isValid: boolean;
+    flags: SaaSFeatureFlags;
+    tenantMetadata: TenantMetadata | null;
+    error: string | null;
+    checkFeature: (feature: keyof SaaSFeatureFlags) => boolean;
+    invalidateCache: () => void;
+    adCampaign: AdCampaign | null;
+    isAdLoading: boolean;
+    adError: string | null;
+    refetchAd: () => Promise<void>;
+    /** Whether SaaS config was successfully fetched from server. */
+    isSaaSConfigAvailable: boolean;
+    userPat: string;
+    setUserPat: (pat: string) => boolean;
+    effectivePat: string;
+    /** The offline license channel. Never shadowed by tenantPat. Empty when none. */
+    effectiveLicense: string;
+    /** CS-3: attribution for the current tier. Never empty. */
+    sources: ("license" | "server" | "server-cache" | "host" | "none")[];
+    /** CS-3: why data features are degraded, or null when fully usable. */
+    degradedReason: "no-pat" | "plan-limited" | "offline" | "grace-expired" | null;
+    /** Last server rejection detail, or null. See SaaSFeatureContextValue. */
+    serverRejectReason?: string | null;
+}
+export declare function useFeatureGate(): UseFeatureGateReturn;

package/dist/dts/widget/hooks/useFloatingChartBar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * useFloatingChartBar — pan callbacks + action passthrough for FloatingChartBar.
+ *
+ * Pan reuses the scale-overlays SSOT (`scrollbar.onWindowChange`,
+ * useScaleOverlays.ts:250-268) clamped by `clampWindow`. Zoom/fit/toggle are
+ * pure passthrough of call-site closures (imperative handle via fan-out ref,
+ * GridContainer.toggleMaximize) — zero duplicated math in this file.
+ */
+export interface FloatingBarScrollbar {
+    dataLength: number;
+    from: number;
+    to: number;
+    onWindowChange: (from: number, to: number) => void;
+}
+export interface UseFloatingChartBarInput {
+    zoomIn: () => void;
+    zoomOut: () => void;
+    fitToData: () => void;
+    scrollbar: FloatingBarScrollbar | null;
+    onToggleLayout?: () => void;
+    isSoloMode?: boolean;
+}
+export interface UseFloatingChartBarOutput {
+    onZoomIn: () => void;
+    onZoomOut: () => void;
+    onPanLeft: () => void;
+    onPanRight: () => void;
+    onFitToData: () => void;
+    onToggleLayout?: () => void;
+    isSoloMode?: boolean;
+    panDisabled: boolean;
+}
+export declare function useFloatingChartBar(input: UseFloatingChartBarInput): UseFloatingChartBarOutput;

package/dist/dts/widget/hooks/useForkRuntime.d.ts

@@ -0,0 +1,155 @@
+import { type EngineInstance, type VisibleRange as EngineVisibleRange, type EngineOverlayState, type EngineOverlayInputs, type EngineOverlayDrawingPrimitiveInput, type PaneRuntimeSnapshot, type CrosshairMode } from "@vninvestcharts/engine-core";
+import type { CrosshairPayload, ClockAdapter } from "@vninvestcharts/engine-react";
+import { type PaneDescriptor } from "../../lib/core";
+import { type EnrichedDatum } from "../../lib/core/calculators/types";
+import { type WidgetPaneRuntimeSnapshot, type WidgetRuntimeCapabilities, type ForkXAxisTick, type ForkXAxisHoverLabel } from "../utils/widgetHelpers";
+import type { MagnetSensitivity } from "@vninvestcharts/engine-drawing";
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+export interface UseForkRuntimeOptions {
+    useForkRuntime: boolean;
+    plotData: readonly EnrichedDatum[];
+    enrichedData: readonly EnrichedDatum[];
+    bars: readonly any[];
+    visiblePanes: readonly PaneDescriptor[];
+    size: {
+        width: number;
+        height: number;
+    };
+    scaleSlotDomains: Record<string, [number, number]>;
+    activeHeights: number[];
+    engineInstanceRef: React.MutableRefObject<EngineInstance | null>;
+    forkEngineInstance: EngineInstance | null;
+    setForkEngineInstance: React.Dispatch<React.SetStateAction<EngineInstance | null>>;
+    forkVisibleRange: EngineVisibleRange | null;
+    setForkVisibleRange: React.Dispatch<React.SetStateAction<EngineVisibleRange | null>>;
+    forkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    forkPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    paneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    setPaneSnapshots: React.Dispatch<React.SetStateAction<readonly WidgetPaneRuntimeSnapshot[]>>;
+    snapshotRevision: number;
+    incrementSnapshotRevision: () => void;
+    onPaneSnapshotsChange: ((snapshots: readonly WidgetPaneRuntimeSnapshot[]) => void) | undefined;
+    onVisibleDomainChange: ((domain: [Date | number, Date | number]) => void) | undefined;
+    controlledXExtents: readonly [Date | number, Date | number] | undefined;
+    internalXExtents: readonly [Date | number, Date | number] | undefined;
+    setInternalXExtents: React.Dispatch<React.SetStateAction<readonly [Date | number, Date | number] | undefined>>;
+    symbol: string | undefined;
+    localRange: string | undefined;
+    showNonTradingDays: boolean;
+    chartSurfaceReady: boolean;
+    emitCoordinateBridge: (snapshots: readonly WidgetPaneRuntimeSnapshot[], range: EngineVisibleRange | null) => void;
+    pendingForkVisibleRangeRef: React.MutableRefObject<EngineVisibleRange | null>;
+    pendingForkVisibleRangeRafRef: React.MutableRefObject<number | null>;
+    lastStableForkSpanRef: React.MutableRefObject<number | null>;
+    pendingHistoryPatchRef: React.MutableRefObject<any>;
+    lastEmittedPaneSnapshotsRef: React.MutableRefObject<readonly WidgetPaneRuntimeSnapshot[]>;
+    lastPaneSnapshotsSubscriberRef: React.MutableRefObject<((snapshots: readonly WidgetPaneRuntimeSnapshot[]) => void) | undefined>;
+    resolvedLegacyVisibleRangeRef: React.MutableRefObject<any>;
+    drawingUiEnabled: boolean;
+    isEditingText: boolean;
+    drawingWorkspace: DrawingWorkspaceController;
+    resolvedDrawings: readonly DrawingObject[];
+    resolvedSelectedDrawing: DrawingObject | null;
+    resolvedForkSingleSelection: DrawingObject | null;
+    onSelectedDrawingChange: ((drawing: DrawingObject | null) => void) | undefined;
+    magnetSensitivity: MagnetSensitivity;
+    /** P2: crosshair display mode (cross | dot | magnet). Applied to the engine on ready + change. */
+    crosshairMode?: CrosshairMode;
+    forkMovableSelectionIds: readonly string[];
+    activeForkManipulationDrawing: DrawingObject | null;
+    forkSelectionModifierPressed: boolean;
+    closeForkDrawingContextMenu: () => void;
+    setForkDrawingContextMenu: (menu: any) => void;
+    onContextMenu: ((payload: any, nativeEvent: any) => void) | undefined;
+    onClick: ((payload: any, nativeEvent: any) => void) | undefined;
+    forkAltShortcutPressedRef: React.MutableRefObject<boolean>;
+    copySelectedDrawing: () => void;
+    pasteCopiedDrawing: () => void;
+    bringSelectedToFront: () => void;
+    sendSelectedToBack: () => void;
+    updateForkReadonlySelection: (drawing: DrawingObject | null) => void;
+    updateForkReadonlySelectionByIds: (ids: readonly string[]) => void;
+    onRuntimeDegraded: ((reason: "fork-no-render-output") => void) | undefined;
+    resolvedTheme: any;
+    activeLocale: string;
+    forkCameraEnvelopeMode: string;
+    setForkCameraEnvelopeMode: React.Dispatch<React.SetStateAction<string>>;
+    handleForkVisibleRangeChange: (range: any) => void;
+    activeTimeframe: string;
+    enableCVD: boolean;
+    cvdMode: string;
+    externalCvdSeries: any[];
+    cvdData: any[];
+    whaleEvents: any[];
+    showDrawingPriceMarkers: boolean;
+    resolvedForkPriceMarkerSelection: DrawingObject | null;
+    forkOverlayState: EngineOverlayState | null;
+    setForkOverlayState: React.Dispatch<React.SetStateAction<EngineOverlayState | null>>;
+    measurementEnabled: boolean;
+    forkRenderableDrawings: readonly DrawingObject[];
+    forkPointerOwnerRef: React.MutableRefObject<any>;
+    claimForkPointerOwner: (owner: any) => void;
+    releaseForkPointerOwner: (owner: any) => void;
+    handleForkPointerDown: (event: any) => void;
+    handleForkPointerMove: (event: any) => void;
+    handleForkPointerUp: (event: any) => void;
+    handleForkPointerLeave: (event: any) => void;
+    handleForkClick: (event: any) => void;
+    handleForkContextMenu: (event: any) => void;
+    handleForkHostContextMenu: (event: any) => void;
+    clockAdapter?: ClockAdapter;
+    handleForkDrawingClick: (event: any) => void;
+    cancelForkInteraction: () => void;
+    forkSurfaceCursor: string;
+    forkPreviewRevision: number;
+    forkManipulationActive: boolean;
+    forkManipulationActiveRef?: React.MutableRefObject<boolean>;
+    forkRubberBandSelection: any;
+    forkDrawingContextMenu: any;
+    resolvedForkPrimitiveSelection: DrawingObject | null;
+    dateFormatPattern?: "yyyy-mm-dd" | "dd/mm/yyyy" | "mm/dd/yyyy";
+    onRuntimeCapabilitiesChange?: (caps: WidgetRuntimeCapabilities) => void;
+    t: (key: string) => string;
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    legacyPaneSnapshots: readonly WidgetPaneRuntimeSnapshot[];
+    legacyChartScale: import("../runtime/IRuntimeEngine").IRuntimeScale;
+    visibleDomainRef: React.MutableRefObject<[Date, Date] | null>;
+    requestVisibleHistoryWindowSync: any;
+    onPaneHover?: (paneId: string | null) => void;
+    onCrosshairChange?: (crosshair: CrosshairPayload) => void;
+    hoveredPaneId: string | null;
+    setHoveredPaneId: React.Dispatch<React.SetStateAction<string | null>>;
+    hoveredPaneIdRef: React.MutableRefObject<string | null>;
+    activeSymbol?: string;
+    adapterLabel: string;
+    forkChartRenderContextValue: any;
+    forkStockChartContextValue: any;
+    replayTradeMarkerFn?: (visibleRange: EngineVisibleRange, paneSnapshots: readonly PaneRuntimeSnapshot[]) => EngineOverlayDrawingPrimitiveInput[] | null;
+    /** When set and .current is true, wall-clock gap extension is suppressed (replay mode). */
+    replayActiveRef?: React.MutableRefObject<boolean>;
+}
+export interface UseForkRuntimeReturn {
+    forkChartRenderContextValue: any;
+    forkStockChartContextValue: any;
+    forkXAxisTicks: ForkXAxisTick[];
+    forkXAxisHoverLabel: ForkXAxisHoverLabel | undefined;
+    forkHoveredDatum: EnrichedDatum | undefined;
+    effectiveForkVisibleRange: EngineVisibleRange | null;
+    forkDrawingPrimitiveInputs: any[];
+    shouldLockForkPan: boolean;
+    forkOverlayInputs: EngineOverlayInputs;
+    engineDataSource: any;
+    runtimeCapabilities: WidgetRuntimeCapabilities;
+    paneSnapshotMap: Map<string, WidgetPaneRuntimeSnapshot>;
+    forkDrawingContextMenuDrawing: DrawingObject | null;
+    forkDrawingContextMenuItems: readonly any[];
+    forkCanvasContextMenuItems: readonly any[];
+    handleEngineReady: (engine: EngineInstance) => void;
+    handleForkOverlayStateChange: (overlayState: EngineOverlayState) => void;
+    emitHoveredPaneId: (paneId: string | null) => void;
+    handleWidgetPointerMove: (event: any) => void;
+    handleWidgetPointerLeave: () => void;
+    forkDegradeNotifiedRef: React.MutableRefObject<boolean>;
+}
+export declare function useForkRuntime({ useForkRuntime, plotData, bars, visiblePanes, scaleSlotDomains, engineInstanceRef, forkEngineInstance, setForkEngineInstance, forkVisibleRange, setForkVisibleRange, forkVisibleRangeRef, forkPaneSnapshotsRef, paneSnapshots, setPaneSnapshots, snapshotRevision, incrementSnapshotRevision, onPaneSnapshotsChange, onVisibleDomainChange, controlledXExtents, internalXExtents, setInternalXExtents, symbol, localRange, showNonTradingDays, chartSurfaceReady, emitCoordinateBridge, pendingForkVisibleRangeRef, pendingForkVisibleRangeRafRef, lastStableForkSpanRef, pendingHistoryPatchRef, lastEmittedPaneSnapshotsRef, lastPaneSnapshotsSubscriberRef, resolvedLegacyVisibleRangeRef, drawingUiEnabled, isEditingText, drawingWorkspace, resolvedDrawings, resolvedSelectedDrawing, resolvedForkSingleSelection, onSelectedDrawingChange, forkDrawingContextMenu, forkRenderableDrawings, forkPreviewRevision, forkManipulationActive, forkManipulationActiveRef, magnetSensitivity, crosshairMode, dateFormatPattern, forkMovableSelectionIds, activeForkManipulationDrawing, forkSelectionModifierPressed, closeForkDrawingContextMenu, clockAdapter, setForkDrawingContextMenu, onContextMenu, onClick, forkAltShortcutPressedRef, copySelectedDrawing, pasteCopiedDrawing, bringSelectedToFront, sendSelectedToBack, onRuntimeDegraded, resolvedTheme, setForkCameraEnvelopeMode, activeTimeframe, showDrawingPriceMarkers, resolvedForkPriceMarkerSelection, forkOverlayState, setForkOverlayState, measurementEnabled, forkPointerOwnerRef, t, containerRef, legacyPaneSnapshots, legacyChartScale, visibleDomainRef, requestVisibleHistoryWindowSync, onPaneHover, onCrosshairChange, setHoveredPaneId, hoveredPaneIdRef, activeSymbol, adapterLabel, resolvedForkPrimitiveSelection, onRuntimeCapabilitiesChange, forkChartRenderContextValue, forkStockChartContextValue, replayTradeMarkerFn, replayActiveRef, }: UseForkRuntimeOptions): UseForkRuntimeReturn;

package/dist/dts/widget/hooks/useIndicatorsShareApplier.d.ts

@@ -0,0 +1 @@
+export declare function useIndicatorsShareApplier(chartId: string | null | undefined): void;

package/dist/dts/widget/hooks/useIntersectionObserver.d.ts

@@ -0,0 +1,49 @@
+export interface IntersectionObserverOptions {
+    /** Root element for intersection calculations (default: viewport) */
+    root?: Element | null;
+    /** Margin around root (e.g., "100px 0px") */
+    rootMargin?: string;
+    /** Threshold(s) for triggering callback (0-1) */
+    threshold?: number | number[];
+    /** Freeze when visibility drops below this threshold (default: 0.5) */
+    freezeThreshold?: number;
+    /** Thaw when visibility rises above this threshold (default: 0.1) */
+    thawThreshold?: number;
+    /** Minimum time frozen before allowing thaw (ms) */
+    minFreezeDuration?: number;
+    /** Debounce time for intersection changes (ms) */
+    debounceMs?: number;
+}
+export interface IntersectionObserverResult {
+    /** Current intersection ratio (0-1) */
+    ratio: number;
+    /** Whether element is currently intersecting */
+    isIntersecting: boolean;
+    /** Whether WebGL context should be frozen */
+    isFrozen: boolean;
+    /** Whether WebGL context is thawing */
+    isThawing: boolean;
+    /** Current visibility state */
+    visibilityState: 'visible' | 'partial' | 'hidden';
+    /** Ref to attach to target element */
+    ref: (element: Element | null) => void;
+    /** Manually trigger freeze */
+    freeze: () => void;
+    /** Manually trigger thaw */
+    thaw: () => void;
+}
+export declare function useIntersectionObserver(options?: IntersectionObserverOptions): IntersectionObserverResult;
+/**
+ * Hook for WebGL canvas freeze/thaw with snapshot support
+ */
+export declare function useWebGLFreezeThaw(options?: IntersectionObserverOptions & {
+    onFreeze?: () => Promise<void>;
+    onThaw?: () => Promise<void>;
+}): IntersectionObserverResult;
+/**
+ * Hook for multiple elements with shared freeze budget
+ */
+export declare function useIntersectionObserverGroup(elements: (Element | null)[], options?: IntersectionObserverOptions & {
+    maxConcurrent?: number;
+}): IntersectionObserverResult[];
+export default useIntersectionObserver;

package/dist/dts/widget/hooks/useKeyboardAdapter.d.ts

@@ -0,0 +1,9 @@
+import type { KeyboardAdapter } from "@vninvestcharts/engine-react";
+export interface UseKeyboardAdapterOptions {
+    keyboardAdapter: KeyboardAdapter;
+    enabled?: boolean;
+}
+export declare function useKeyboardAdapter(options: UseKeyboardAdapterOptions): {
+    onKeyDown: (handler: (e: KeyboardEvent) => void) => () => void;
+    onShortcut: (combo: string, handler: () => void) => () => void;
+};

package/dist/dts/widget/hooks/useLayoutHistory.d.ts

@@ -0,0 +1,8 @@
+import type { ChartLayout } from "@vninvestcharts/engine-react";
+export declare function useLayoutHistory(initialLayout: ChartLayout): {
+    pushLayout: (layout: ChartLayout) => void;
+    undo: () => ChartLayout | null;
+    redo: () => ChartLayout | null;
+    canUndo: boolean;
+    canRedo: boolean;
+};

package/dist/dts/widget/hooks/useLicenseDiagnostics.d.ts

@@ -0,0 +1,15 @@
+export type LicenseDiagnosticReason = "insecure-context" | "subtle-unavailable" | null;
+export interface LicenseDiagnostics {
+    /** False on plain http (non-localhost). WebCrypto requires a secure context. */
+    secureContext: boolean;
+    /** False when crypto.subtle is missing for any reason. */
+    subtleAvailable: boolean;
+    /** Non-null exactly when a license cannot be verified for environmental reasons. */
+    reason: LicenseDiagnosticReason;
+}
+export declare function useLicenseDiagnostics(): LicenseDiagnostics;
+/**
+ * Pure environment probe, exported so the provider can report the same reason
+ * through `onLicenseDiagnostic` without mounting the hook. Same logic, one place.
+ */
+export declare function detectLicenseEnvironment(): LicenseDiagnosticReason;

package/dist/dts/widget/hooks/useMultiChartReplaySync.d.ts

@@ -0,0 +1,31 @@
+import type { WidgetChartHandle } from "../utils/widgetHelpers";
+export interface MultiChartReplaySyncOptions {
+    chartHandles: ReadonlyMap<string, WidgetChartHandle>;
+    charts: ReadonlyArray<{
+        id: string;
+        timeframe: string;
+    }>;
+    instanceId?: string;
+    enabled?: boolean;
+    /** R1-a: 'all' (default) = slaves follow; 'single' = each chart replays alone. */
+    mode?: "single" | "all";
+    /** F-11: called exactly once per actual master change (not per heartbeat), incl. reset to null. */
+    onMasterChange?: (masterId: string | null) => void;
+}
+export interface MultiChartReplaySyncResult {
+    masterChartId: string | null;
+    slaveChartIds: string[];
+    heartbeat: number;
+}
+export declare function electMaster(activeStates: Map<string, {
+    tfMinutes: number;
+    currentBar: number;
+    totalBars: number;
+    barTimestamp?: number;
+}>): string | null;
+export declare function replayActive(state: {
+    currentBar: number;
+    totalBars: number;
+    playing: boolean;
+}): boolean;
+export declare function useMultiChartReplaySync(options: MultiChartReplaySyncOptions): MultiChartReplaySyncResult;

package/dist/dts/widget/hooks/useMultiWorkspacePersistence.d.ts

@@ -0,0 +1,49 @@
+import { type RefObject } from "react";
+import type { ChartLayout } from "@vninvestcharts/engine-react";
+import type { MultiChartConfig, VNInvestMultiChartsProps } from "../VNInvestMultiCharts";
+import type { WidgetChartHandle } from "../utils/widgetHelpers";
+import { type WorkspaceIndexEntry, type WorkspaceScope } from "../workspace/WorkspaceStore";
+import type { PatTier } from "@vninvestcharts/engine-core";
+/** Cấu hình phạm vi lưu trữ do host hoặc test truyền vào. */
+export interface WorkspaceScopeInput {
+    /** Tier hiện tại để suy ra capability `server_workspace`. */
+    tier?: PatTier | null;
+    /** Allowlist `caps` của license (W0.6) — cũng có thể chặn `server_workspace`. */
+    licenseNarrowing?: readonly string[];
+    /** Ép dùng remote (chỉ test; EP-8 chưa tới nên sẽ ném 501). */
+    forceRemote?: boolean;
+    /** Probe backend đã sẵn sàng chưa (W0.4 `capabilityProbe`). */
+    backendReady?: boolean;
+}
+export interface MultiWorkspacePersistenceDeps {
+    layout: ChartLayout;
+    charts: MultiChartConfig[];
+    currentWorkspaceId: string | null;
+    currentWorkspaceName: string;
+    activeChartId: string | null;
+    storageAdapter: VNInvestMultiChartsProps["storageAdapter"];
+    /**
+     * W0.7 — cấu hình phạm vi lưu trữ. `null`/bỏ qua = suy ra từ `tier` + `licenseNarrowing`.
+     * Xem `resolveWorkspaceStore`; chỉ sửa factory đó khi EP-8 tới.
+     */
+    workspaceScope?: WorkspaceScopeInput;
+    onWorkspaceSave?: (workspaceId: string) => void;
+    onWorkspaceLoad?: (workspaceId: string) => void;
+    chartHandles: RefObject<Map<string, WidgetChartHandle>>;
+    setLayoutState: (layout: ChartLayout) => void;
+    setChartsState: (charts: MultiChartConfig[]) => void;
+    setCurrentWorkspaceId: (id: string | null) => void;
+    setCurrentWorkspaceName: (name: string) => void;
+    setActiveChartId: (id: string | null) => void;
+}
+export declare function useMultiWorkspacePersistence(deps: MultiWorkspacePersistenceDeps): {
+    saveWorkspace: (wsId: string) => Promise<void>;
+    loadWorkspace: (wsId: string) => Promise<void>;
+    /** Đọc index workspace đã lưu (danh sách cho UI Load). Xem giải thích ở phần cài đặt. */
+    listWorkspaces: () => Promise<readonly WorkspaceIndexEntry[]>;
+    /**
+     * W0.7 — phạm vi lưu trữ đang hoạt động. UI dùng để hiện badge
+     * "Chỉ lưu trên thiết bị này" khi scope là "local" (EP-8 chưa tới).
+     */
+    workspaceScope: WorkspaceScope;
+};

package/dist/dts/widget/hooks/usePaperTradeConfig.d.ts

@@ -0,0 +1,27 @@
+export type SizingMode = "fixed" | "percent";
+export interface UsePaperTradeConfigOptions {
+    /** Fee rate (fraction, ví dụ 0.001 = 0.1%). Default 0 (backward-compat). */
+    feeRate?: number;
+    /** H2: slippage đơn giản (bps). Default 0. */
+    slippageBps?: number;
+    /** H4: fixed qty. Default 1. */
+    defaultQty?: number;
+    /** H4: sizing mode. "fixed" = defaultQty, "percent" = % of equity. Default "fixed". */
+    sizingMode?: SizingMode;
+    /** H4: risk % of equity per trade (khi sizingMode="percent"). Default 1 = 1%. */
+    riskPercent?: number;
+    /** H4: vốn ban đầu để tính % equity. Default 10000. */
+    initialEquity?: number;
+    /** Symbol của active chart (từ context). */
+    symbol?: string;
+}
+export interface PaperTradeConfig {
+    feeRate: number;
+    slippageBps: number;
+    defaultQty: number;
+    sizingMode: SizingMode;
+    riskPercent: number;
+    initialEquity: number;
+    symbol?: string;
+}
+export declare function usePaperTradeConfig(options?: UsePaperTradeConfigOptions): PaperTradeConfig;

package/dist/dts/widget/hooks/usePaperTradeInteraction.d.ts

@@ -0,0 +1,27 @@
+import type { ReplayOrder, ReplayPosition } from "../../lib/core/replay/replayTradingTypes";
+export interface UseReplayTradingLike {
+    placeOrder: (order: Omit<ReplayOrder, "id" | "timestamp">) => void;
+    closePosition: (positionId: string) => void;
+    positions: ReplayPosition[];
+}
+export interface UsePaperTradeInteractionParams {
+    replayTrading: UseReplayTradingLike;
+    replayActive: boolean;
+    /** Khi true, Alt+click luôn chọn start bar (ngay cả sau Stop khi replayActive=false). = replay toolbar đang mở. */
+    replaySelectionEnabled?: boolean;
+    /** R2.1 CutMode: click thường chọn start bar, paper-trade bị vô hiệu hóa. */
+    isCutMode?: boolean;
+    baseOnClick?: (payload: any, nativeEvent: any) => void;
+    handleReplayStartBarSelect?: (date: Date | number) => void;
+    resolveActiveTool?: () => string | null | undefined;
+    defaultQty?: number;
+    symbol?: string;
+    feeRate?: number;
+    sizingMode?: "fixed" | "percent";
+    riskPercent?: number;
+    initialEquity?: number;
+}
+export interface UsePaperTradeInteractionResult {
+    wrappedOnClick: (payload: any, nativeEvent: any) => void;
+}
+export declare function usePaperTradeInteraction(params: UsePaperTradeInteractionParams): UsePaperTradeInteractionResult;

package/dist/dts/widget/hooks/usePatTierAuthentication.d.ts

@@ -0,0 +1,42 @@
+import { planToTier, type Capability } from "@vninvestcharts/engine-core";
+import type { VNInvestClient } from "../adapters/VNInvestClient";
+export type WidgetPatTier = ReturnType<typeof planToTier>;
+/**
+ * Whether an auth backend is explicitly configured. Explicit signals only:
+ * operator-injected client, global base override, or stored base override.
+ * The resolved-default base (page origin / placeholder) does NOT count — otherwise
+ * every standalone embed would fire doomed requests at its own origin.
+ */
+export declare function hasExplicitBackend(client?: VNInvestClient | null): boolean;
+export interface PatTierAuthInput {
+    client?: VNInvestClient | null;
+}
+export interface PatTierAuth {
+    /** Fail-closed validator for EngineHost `validatePat` (+ independent widget checks). */
+    validatePat: (pat: string) => Promise<WidgetPatTier | null>;
+    /** Widget's own server-derived tier for the current effective PAT (null = none/unknown). */
+    widgetServerTier: WidgetPatTier | null;
+    /** Last tier reported back by the engine via `onTierValidated`. */
+    serverPatTier: WidgetPatTier | null;
+    /** Tier driving toolbar gating, trademark, ads and premium overlays. Never prefix-derived. */
+    effectiveToolbarTier: WidgetPatTier;
+    /** PAT forwarded to the engine: real token only when server confirmed pro+, else "". */
+    enginePat: string;
+    /** Last server rejection detail (verbatim from /auth/me), or null. Never shown raw without mapping. */
+    serverRejectReason: string | null;
+    /** True when no auth backend is configured (pure-free standalone mode). */
+    isStandalone: boolean;
+    /**
+     * W0.6 — allowlist capability do **license ký số** thu hẹp (payload `caps`).
+     * `undefined` = license không giới hạn ⇒ dùng đầy đủ `MIN_TIER`.
+     * CHỈ có giá trị khi entitlement đến từ license, không phải từ PAT server.
+     * Dùng để gate Track A **hoàn toàn offline** (không cần `/access/capabilities`).
+     */
+    licenseCapabilities: readonly Capability[] | undefined;
+    /** Downgrade banner state (pro → free transition). */
+    showDowngradeBanner: boolean;
+    /** Engine `onTierValidated` handler. */
+    handleTierValidated: (tier: string) => void;
+    handleDismissDowngrade: () => void;
+}
+export declare function usePatTierAuthentication(input: PatTierAuthInput): PatTierAuth;