@idux/charts-core 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @idux/charts-core
 
+## 1.2.1
+
+### Patch Changes
+
+- ab38e82: Fix gradient tooltip markers and preserve light and dark tooltip styles when mounting outside the chart. Correct multi-axis and time-axis units, respect injected line themes, and align Gauge, Radar, and rose-chart presentation.
+
+## 1.2.0
+
+### Minor Changes
+
+- 879376a: Add CHART_THEME_TOKEN for reactive application-wide chart themes, with explicit per-chart themes taking precedence.
+
+  Use a dark loading mask for dark chart themes while retaining explicit loading overrides.
+
+  Let chart tooltips inherit theme surfaces, retaining the light Seer background.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,84 @@
+# @idux/charts-core
+
+English | [简体中文](README.zh.md)
+
+The foundation of iDux Charts: the generic `IxChart` component, chart lifecycle composables, themes, types, and utilities. Use it for direct ECharts options or custom chart components.
+
+For the unified entry point and shared tooltip styles, use [`@idux/charts`](https://github.com/IDuxFE/idux-charts/blob/main/packages/charts/README.md).
+
+## Installation
+
+```bash
+npm install @idux/charts-core echarts
+```
+
+Supports Vue 2 (including Vue 2.6) and Vue 3. Use in an existing Vue project with peer dependencies Vue `^2.6.0 || ^3.2.5` and ECharts `^5.4.3 || ^6.0.0`. Vue 2.6 also requires `@vue/composition-api >=1.6.2` and plugin registration before creating the application.
+
+```bash
+npm install @vue/composition-api
+```
+
+```ts
+// Vue 2.6
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+
+Vue.use(VueCompositionAPI)
+```
+
+## Quick start
+
+This example uses Vue 3 `<script setup>` with a locally imported component. The container must have a nonzero width and height.
+
+```vue
+<script setup lang="ts">
+import { use } from 'echarts/core'
+import { LineChart } from 'echarts/charts'
+import { IxChart, type ChartProps } from '@idux/charts-core'
+
+use([LineChart])
+
+const option: ChartProps = {
+  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'] },
+  yAxis: { type: 'value' },
+  series: [{ type: 'line', data: [123, 324, 156, 244, 188] }],
+}
+</script>
+
+<template>
+  <div style="height: 320px">
+    <IxChart v-bind="option" />
+  </div>
+</template>
+```
+
+`IxChart` takes ECharts options directly through `v-bind`, rather than a separate `option` prop. It registers the SVG renderer, Grid, Legend, Tooltip, Title, DataZoom, LabelLayout, and UniversalTransition. Register custom series or additional components with `use` from `echarts/core`. For Canvas, also register `CanvasRenderer` and pass `initOption: { renderer: 'canvas' }`.
+
+## Core API
+
+- `IxChart`: supports `autoResize` (enabled by default), `loading`, `theme`, `group`, `initOption`, `setOptionOpts`, and `onReady`.
+- `useChart(options, listeners?)`: manages initialization, reactive updates, events, resizing, and disposal. Call it in component `setup`; it returns `containerRef` and `chartRef`.
+- `seerTheme`: the built-in theme, registered as the default theme `seer`.
+- `useTooltipsFormatter`, `useReactiveAttrs`, `createInstall`, and `withChartProps`: helpers for custom charts.
+- `ChartProps`, `ChartPublicProps`, and `ChartOption`: public configuration types.
+
+This package does not ship a separate CSS file. Shared HTML tooltip styles are provided by `@idux/charts/dist/style.css`.
+
+## Application themes
+
+Use `CHART_THEME_TOKEN` to provide an application-wide theme name/object or a reactive ref. Explicit `theme` props override it; otherwise charts fall back to `seer`. Changing the inherited theme recreates the chart, following the existing theme lifecycle. For generated plot labels and graphics, also configure `PLOT_THEME_TOKEN` from `@idux/charts-plots` (or `@idux/charts`).
+
+## TypeScript
+
+`*ChartProps` types describe chart configuration and allow extension fields. `*ChartPublicProps` expose named public properties while preserving their types and optionality for component type adapters. See the [repository README](https://github.com/IDuxFE/idux-charts/blob/main/README.md#typescript-prop-types) for adapter details.
+
+## Documentation
+
+- [iDux Charts](https://charts.idux.site)
+- [Configuration guide](https://github.com/IDuxFE/idux-charts/blob/main/packages/site/src/0-guide/GettingStarted.page.md)
+- [Vue 2 / Vue 3 playgrounds](https://github.com/IDuxFE/idux-charts/blob/main/playgrounds/README.md)
+- [Repository and development](https://github.com/IDuxFE/idux-charts/blob/main/README.md)
+
+## License
+
+MIT © 2023-present IDuxFE

package/README.zh.md

@@ -0,0 +1,84 @@
+# @idux/charts-core
+
+[English](README.md) | 简体中文
+
+iDux Charts 的基础层，提供通用 `IxChart`、图表生命周期组合式函数、主题、类型及工具，适合直接使用 ECharts 配置或开发自定义图表组件。
+
+如需统一入口及共享提示框样式，可使用 [`@idux/charts`](https://github.com/IDuxFE/idux-charts/blob/main/packages/charts/README.zh.md)。
+
+## 安装
+
+```bash
+npm install @idux/charts-core echarts
+```
+
+支持 Vue 2（含 Vue 2.6）和 Vue 3。在已有 Vue 项目中使用，依赖版本为 Vue `^2.6.0 || ^3.2.5` 和 ECharts `^5.4.3 || ^6.0.0`。Vue 2.6 还需安装 `@vue/composition-api >=1.6.2`，并在创建应用前注册插件。
+
+```bash
+npm install @vue/composition-api
+```
+
+```ts
+// Vue 2.6
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+
+Vue.use(VueCompositionAPI)
+```
+
+## 快速上手
+
+以下示例使用 Vue 3 的 `<script setup>`，局部导入组件即可使用。容器必须具有有效的宽度和高度。
+
+```vue
+<script setup lang="ts">
+import { use } from 'echarts/core'
+import { LineChart } from 'echarts/charts'
+import { IxChart, type ChartProps } from '@idux/charts-core'
+
+use([LineChart])
+
+const option: ChartProps = {
+  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'] },
+  yAxis: { type: 'value' },
+  series: [{ type: 'line', data: [123, 324, 156, 244, 188] }],
+}
+</script>
+
+<template>
+  <div style="height: 320px">
+    <IxChart v-bind="option" />
+  </div>
+</template>
+```
+
+`IxChart` 的 ECharts 配置通过 `v-bind` 直接传入，不使用单独的 `option` 属性。默认注册 SVG 渲染器、Grid、Legend、Tooltip、Title、DataZoom，以及 LabelLayout、UniversalTransition。自定义系列或额外组件需要通过 `echarts/core` 的 `use` 注册；使用 Canvas 时也需注册 `CanvasRenderer`，并传入 `initOption: { renderer: 'canvas' }`。
+
+## 核心 API
+
+- `IxChart`：支持 `autoResize`（默认开启）、`loading`、`theme`、`group`、`initOption`、`setOptionOpts` 和 `onReady`。
+- `useChart(options, listeners?)`：管理初始化、响应式更新、事件、尺寸变化和销毁，返回 `containerRef` 与 `chartRef`；在组件 `setup` 中调用。
+- `seerTheme`：内置主题，默认主题名称为 `seer`。
+- `useTooltipsFormatter`、`useReactiveAttrs`、`createInstall`、`withChartProps`：自定义图表开发工具。
+- `ChartProps`、`ChartPublicProps`、`ChartOption`：公开配置类型。
+
+此包不提供独立 CSS 文件；共享 HTML 提示框样式由 `@idux/charts/dist/style.css` 提供。
+
+## 应用级主题
+
+可用 `CHART_THEME_TOKEN` 提供应用级主题名称、对象或响应式 ref。显式 `theme` 属性优先，未配置时回退到 `seer`。注入主题变化沿用已有主题生命周期，重新创建图表实例。对于配置生成器绘制的文字和辅助图形，还需配置 `@idux/charts-plots`（或 `@idux/charts`）导出的 `PLOT_THEME_TOKEN`。
+
+## TypeScript
+
+`*ChartProps` 用于图表配置，允许扩展字段；`*ChartPublicProps` 提供具名公开属性类型，保留属性的类型及可选性，便于编写组件类型适配。具体适配说明见[仓库 README](https://github.com/IDuxFE/idux-charts/blob/main/README.zh.md#typescript-属性类型)。
+
+## 文档
+
+- [iDux Charts](https://charts.idux.site)
+- [配置指南](https://github.com/IDuxFE/idux-charts/blob/main/packages/site/src/0-guide/GettingStarted.page.md)
+- [Vue 2 / Vue 3 示例项目](https://github.com/IDuxFE/idux-charts/blob/main/playgrounds/README.zh.md)
+- [仓库与开发指南](https://github.com/IDuxFE/idux-charts/blob/main/README.zh.md)
+
+## 许可证
+
+MIT © 2023-present IDuxFE

package/dist/composables/index.d.ts

@@ -1,4 +1,4 @@
 export { useChart } from './useChart';
-export { useTooltipsFormatter } from './useTooltips';
+export { useTooltipsFormatter, getTooltipsColor } from './useTooltips';
 export * from './useStripe';
 export { useReactiveAttrs } from './useReactiveAttrs';

package/dist/composables/tooltipTheme.d.ts

@@ -0,0 +1,8 @@
+import { EChartsType } from 'echarts/core';
+import { ChartProps } from '../types';
+/** Keep theme state on the tooltip itself, including portals created by appendTo. */
+export declare function createTooltipTheme(getContainer: () => HTMLElement | undefined): {
+    prepare(options: ChartProps): ChartProps;
+    sync(instance: EChartsType): void;
+    rendered: () => void;
+};

package/dist/composables/useTooltips.d.ts

@@ -1,6 +1,27 @@
+import { Color } from 'echarts';
+interface GradientColorStop {
+    offset?: number;
+    color?: string;
+}
+interface GradientLikeColor {
+    colorStops?: GradientColorStop[];
+}
 export interface TooltipsFormatItem {
     name: string;
     value: string | number;
-    color?: string;
+    /**
+     * 图例色块颜色，支持普通颜色字符串（如 `#458FFF`）
+     * 或渐变对象（如 `itemStyle.color` 配置的 linear 渐变），
+     * 传入渐变时优先取最不透明的色标，同透明度下取更深的颜色。
+     */
+    color?: string | GradientLikeColor;
 }
+/**
+ * 提取用于 tooltip 色块展示的颜色。
+ *
+ * 柱体、折线等图形常配置为线性渐变，此时 hover 提示中的竖杠
+ * 需要与图形中更深的颜色保持一致，因此优先选择最不透明的色标，同透明度时取亮度最低的颜色。
+ */
+export declare function getTooltipsColor(color?: Color | GradientLikeColor | null): string;
 export declare function useTooltipsFormatter(title: string, list: TooltipsFormatItem[]): string;
+export {};