Skip to content

Commit 5a15b23

Browse files
noobshipscursoragent
noobships
and
cursoragent
committed
docs: align README and polish docs with new preset behavior
Document mount animation controls, ECharts 6 grid containment defaults, and opt-in option color token resolution guidance while updating style spec wording to match current bar rounding behavior. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 9df4554 commit 5a15b23

5 files changed

Lines changed: 63 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
# @devstool/shadcn-echarts
22

3+
## Unreleased
4+
5+
### Improvements
6+
7+
- Add mount animation controls in `Chart` via `animateOnMount` and `animateOnMountDelayMs` (default enabled) for more consistent first-load entrance animation.
8+
- Improve minimal preset tooltip precedence to avoid injecting a global formatter when chart options already define tooltip formatting semantics.
9+
- Modernize preset grid defaults for ECharts 6 by using outer-bounds containment defaults instead of relying on `grid.containLabel`.
10+
- Expand theme and preset defaults for `sunburst`, `treemap`, and `boxplot` to improve dark/light border and contrast behavior.
11+
- Add opt-in `resolveOptionColorTokens()` utility for resolving token-like color values in custom option trees.
12+
313
## 0.2.0
414

515
### Minor Changes

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,29 @@ export function MyChart() {
8888
}
8989
```
9090

91+
### First-load animation
92+
93+
Charts now animate on initial mount by default:
94+
95+
- `animateOnMount` (default `true`)
96+
- `animateOnMountDelayMs` (default `16`)
97+
98+
Disable if you want raw immediate rendering:
99+
100+
```tsx
101+
<BarChart option={option} animateOnMount={false} />
102+
```
103+
104+
### Optional: resolve color tokens in custom options
105+
106+
If you pass deeply customized option trees with CSS-token-like colors, you can pre-resolve them:
107+
108+
```ts
109+
import { resolveOptionColorTokens } from "@devstool/shadcn-echarts/themes";
110+
111+
const safeOption = resolveOptionColorTokens(option);
112+
```
113+
91114
## 2D vs 3D/WebGL Support
92115

93116
- 2D charts work out of the box with `echarts`.

‎docs/polish/presets.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export function RawEChartsExample() {
3939

4040
### Cartesian defaults
4141

42-
- `grid`: small consistent padding + `containLabel: true`
42+
- `grid`: small consistent padding + ECharts 6 outer-bounds containment defaults
4343
- `xAxis` / `yAxis`:
4444
- `axisLine.show = false`
4545
- `axisTick.show = false`
@@ -56,7 +56,7 @@ export function RawEChartsExample() {
5656
- `lineStyle.width = 2`
5757
- `areaStyle.opacity` for area charts
5858
- `bar`:
59-
- `itemStyle.borderRadius` defaults are orientation/sign-aware and round the start edge
59+
- `itemStyle.borderRadius` defaults to fully rounded corners for cleaner stacked/non-stacked bars
6060
- `barMaxWidth = 48`
6161
- `pie`:
6262
- `label.show = true`, `labelLine.show = true`
@@ -77,6 +77,15 @@ export function RawEChartsExample() {
7777
- `var(--popover)`, `var(--popover-foreground)`, `var(--border)`, `var(--muted-foreground)`
7878
- consistent radius/shadow shell for both default and custom formatter paths
7979

80+
### Mount animation defaults
81+
82+
- `animateOnMount = true`
83+
- `animateOnMountDelayMs = 16`
84+
- Behavior:
85+
- First pass applies an inert seed frame for series-based charts.
86+
- Second pass applies the full option after a short delay to guarantee visible first-load animation.
87+
- Set `animateOnMount={false}` to disable this behavior.
88+
8089
## Overriding behavior
8190

8291
If you explicitly set a field, it stays untouched.

‎docs/polish/style-spec.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ The library reads shadcn/ui CSS variables from the DOM and converts them to an E
2626
- **Series defaults (minimal, non-invasive)**
2727
- Defaults are applied as a **defaults-only merge** (never overwrite explicit user styling)
2828
- Line: `lineStyle.width = 2`, `showSymbol = false`, subtle area fills for area charts
29-
- Bar: orientation/sign-aware **start-edge** rounding, reasonable max width
29+
- Bar: fully rounded bar corners (including stacked bars), reasonable max width
3030
- Pie/treemap/sunburst: separators are subtle and token-driven (no harsh seams)
3131
- Heatmap/calendar/gauge: no hard cell borders by default; cleaner band/cell polish
3232

‎docs/polish/theming.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,24 @@ Mode resolution priority is:
4141
2. `data-theme` / `data-mode` / `data-color-scheme` on `<html>`
4242
3. `prefers-color-scheme`
4343

44+
## Opt-in option color token resolver
45+
46+
For deeply customized chart options, you can pre-resolve color fields before passing
47+
options into a chart:
48+
49+
```ts
50+
import { resolveOptionColorTokens } from '@devstool/shadcn-echarts/themes'
51+
52+
const safeOption = resolveOptionColorTokens(option)
53+
```
54+
55+
Notes:
56+
57+
- This utility is opt-in (it is not applied automatically by `Chart`).
58+
- By default, it targets token-like color strings (`var(...)`, `oklch(...)`, etc.).
59+
- Use `resolveOptionColorTokens(option, { resolveNonTokenColors: true })` to force
60+
broader color normalization.
61+
4462
## Advanced: registering themes yourself
4563

4664
You can register themes manually (useful if you want to pre-register on app startup):

0 commit comments

Comments
 (0)