feat: add getInstanceApi method to ChartPro and update related compon…

[zahidhussaina2l]

Add getInstanceApi() method to expose KLineChart instance

Summary

This PR adds a new getInstanceApi() method to the ChartPro interface, allowing users to access the underlying KLineChart instance directly. This enables advanced customization and access to all native KLineChart APIs while maintaining the convenience of the ChartPro wrapper.

Motivation

Currently, the KLineChartPro wrapper provides a high-level API for common operations, but users cannot access the underlying KLineChart instance for advanced use cases such as:

• Creating custom overlays with specific configurations
• Subscribing to native chart events
• Accessing advanced data manipulation methods
• Using features not yet exposed by the ChartPro wrapper
• Direct control over chart internals for complex implementations

Changes Made

1. src/types.ts

• Added imports: Nullable and Chart from 'klinecharts'
• Extended ChartPro interface with getInstanceApi(): Nullable<Chart> method

2. src/ChartProComponent.tsx

• Modified props.ref() to include getInstanceApi: () => widget
• Exposes the internal Chart widget instance through the API

3. src/KLineChartPro.tsx

• Added Chart import from 'klinecharts'
• Implemented getInstanceApi() method that delegates to the chart API

Usage Example

import { KLineChartPro, ChartProOptions } from '@klinecharts/pro'

// Create chart instance
const chart = new KLineChartPro(options as ChartProOptions)

// Access the native KLineChart instance
const instanceApi = chart.getInstanceApi()

// Use native KLineChart methods
if (instanceApi) {
  // Create custom indicators
  instanceApi.createIndicator('MA', true, { id: 'candle_pane' })
  
  // Add custom overlays
  instanceApi.createOverlay({
    name: 'simpleAnnotation',
    points: [{ timestamp: 1614171282000, value: 15000 }]
  })
  
  // Subscribe to chart events
  instanceApi.subscribeAction('onZoom', () => {
    console.log('Chart zoomed')
  })
  
  // Get chart data
  const dataList = instanceApi.getDataList()
  
  // Export chart as image
  const imageUrl = instanceApi.getConvertPictureUrl(true, 'png')
}

Benefits

• Full API Access: Users can now access all KLineChart methods and features
• Type Safety: Method is fully typed with Nullable<Chart> return type
• Backward Compatible: No breaking changes; this is a purely additive feature
• Flexibility: Users can choose between high-level ChartPro API or low-level Chart API as needed
• Future-Proof: Provides access to new KLineChart features without requiring ChartPro updates

Testing

• ✅ TypeScript compilation successful
• ✅ Build passes (ES and UMD modules)
• ✅ Type definitions generated correctly
• ✅ Method verified in compiled output
• ✅ No breaking changes to existing API

Breaking Changes

None. This is a non-breaking additive change.

Type Definitions

The generated type definitions correctly include the new method:

export interface ChartPro {
  // ... existing methods
  getInstanceApi(): Nullable<Chart>;
}

export declare class KLineChartPro implements ChartPro {
  // ... existing methods
  getInstanceApi(): Nullable<Chart>;
}

References

For available methods on the Chart instance, see KLineChart API Documentation.