# Lark Block Framework - Chart Blocks
Interactive chart blocks for Lark documents with Bitable data binding.
## Quick Start
```typescript
import { createChartBlockCreator } from '@hypelab/hype-dash/block';
// Create and register the Creator
const creator = createChartBlockCreator(LARK_API_KEY);
// In Lark environment
Creator(creator);
```
## Features
- 7 chart types (bar, line, pie, area, scatter, funnel, radar)
- Bitable data source integration
- Real-time data updates
- Interactive configuration UI
- VChart rendering engine
- Responsive design
- Custom styling options
## Files
```
src/block/
├── ChartBlockCreator.ts # Main Creator implementation
├── types.ts # TypeScript definitions
├── index.ts # Public API exports
├── block.config.json # Block metadata
├── views/
│ └── chart-block.ttml # UI template
└── README.md # This file
```
## Usage
### Basic Line Chart
```typescript
const chartConfig: ChartBlockData = {
chartType: 'line',
title: 'Views Over Time',
dataSource: {
appToken: 'FUVdb7bebaVLeMsKJgJlnsX2gzd',
tableId: 'tblAhbwMbAk9mBCJ',
fields: {
xAxis: 'Date',
yAxis: ['Views']
}
}
};
```
### Multi-Metric Bar Chart
```typescript
const chartConfig: ChartBlockData = {
chartType: 'bar',
title: 'Video Performance',
dataSource: {
appToken: APP_TOKEN,
tableId: TABLE_ID,
fields: {
xAxis: 'Video Title',
yAxis: ['Views', 'Likes', 'Comments']
}
},
options: {
showLegend: true,
colors: ['#1890ff', '#52c41a', '#faad14']
}
};
```
### Pie Chart
```typescript
const chartConfig: ChartBlockData = {
chartType: 'pie',
title: 'Engagement Types',
dataSource: {
appToken: APP_TOKEN,
tableId: TABLE_ID,
fields: {
xAxis: 'Type',
yAxis: ['Count']
}
}
};
```
## API Reference
### createChartBlockCreator(apiKey)
Create Creator configuration object.
**Parameters:**
- `apiKey` (string): Lark API authentication token
**Returns:** CreatorConfig
### createVChartSpec(chartType, data, options)
Generate VChart specification from chart type and data.
**Parameters:**
- `chartType` (BlockChartType): Chart type
- `data` (VChartDataPoint[]): Chart data points
- `options` (optional): Chart options
**Returns:** VChart specification object
### transformBitableData(records, dataSource)
Transform Bitable records into VChart data points.
**Parameters:**
- `records` (BitableRecord[]): Bitable records
- `dataSource` (BitableDataSource): Data source config
**Returns:** VChartDataPoint[]
### validateChartConfig(config)
Validate chart block configuration.
**Parameters:**
- `config` (ChartBlockData): Chart configuration
**Returns:** ValidationResult
## Types
### ChartBlockData
```typescript
interface ChartBlockData {
chartType: BlockChartType;
title?: string;
dataSource: BitableDataSource;
options?: {
showLegend?: boolean;
showDataLabels?: boolean;
colors?: string[];
animation?: boolean;
responsive?: boolean;
};
vchartSpec?: any;
}
```
### BitableDataSource
```typescript
interface BitableDataSource {
appToken: string;
tableId: string;
viewId?: string;
fields?: {
xAxis?: string;
yAxis?: string[];
series?: string;
groupBy?: string;
};
}
```
## Chart Types
| Type | Description | Use Case |
|------|-------------|----------|
| bar | Bar chart | Category comparison |
| line | Line chart | Trends over time |
| pie | Pie chart | Proportions |
| area | Area chart | Cumulative trends |
| scatter | Scatter plot | Correlations |
| funnel | Funnel chart | Conversion flows |
| radar | Radar chart | Multi-variable analysis |
## Examples
See `/examples/chart-block-example.ts` for complete examples including:
- Basic charts
- Multi-metric charts
- Grouped charts
- Custom VChart specs
- TikTok analytics dashboard
## Documentation
Full documentation: `/docs/BLOCK_FRAMEWORK_GUIDE.md`
## License
MIT License - see LICENSE file
