diff --git a/.agents/plans/NEXT_MAJOR_PLAN.md b/.agents/plans/NEXT_MAJOR_PLAN.md
new file mode 100644
index 00000000..b60755dc
--- /dev/null
+++ b/.agents/plans/NEXT_MAJOR_PLAN.md
@@ -0,0 +1,25 @@
+# Next major release plan
+
+Planned breaking changes and migration notes for ChartKit 10.
+
+## Indicator types
+
+Remove deprecated `content.current` and item-level `color` from the widget contract;
+use required `value` and `value.color`. Make `IndicatorWidgetData` describe the modern
+configuration and align `ChartKitWidget['indicator']['data']` with
+`ChartKitProps<'indicator'>['data']` without a compatibility union.
+
+Clean up all indicator types, including duplicate config/normalized shapes,
+value types, formatter contracts, and exports. Keep legacy types and conversion
+in migration tooling, separate from the renderer. Update the adapter, stories,
+[indicator guide](../../docs/indicator.md), and
+[migration guide](../../docs/indicator-migration.md); verify public declarations,
+migration, and rendering before release.
+
+## Single indicator configuration — discuss
+
+Consider accepting one config directly: ``
+instead of `data={{data: [config]}}`. **Open question; discuss before implementing.**
+Check consumers with multiple items, define their migration and empty-input
+behavior, and decide where `defaultColor` belongs. Never silently select the first
+item. If deferred, retain the array and complete the type cleanup independently.
diff --git a/docs/indicator-migration.md b/docs/indicator-migration.md
new file mode 100644
index 00000000..ed22f93b
--- /dev/null
+++ b/docs/indicator-migration.md
@@ -0,0 +1,76 @@
+# Indicator configuration migration (Draft)
+
+**Draft: ChartKit 10 has not been released.**
+
+## Indicator configuration
+
+| v9 | v10 |
+| ----------------- | ------------- |
+| `content.current` | `value` |
+| Item `color` | `value.color` |
+
+Before:
+
+```ts
+const data: IndicatorWidgetData = {
+ data: [
+ {
+ title: 'Revenue',
+ content: {current: {value: 1539577}},
+ color: 'var(--g-color-text-positive)',
+ },
+ ],
+};
+```
+
+After (v10):
+
+```ts
+const data: IndicatorWidgetData = {
+ data: [
+ {
+ title: 'Revenue',
+ value: {
+ value: 1539577,
+ color: 'var(--g-color-text-positive)',
+ },
+ },
+ ],
+};
+```
+
+## Public types in v10
+
+Keep `IndicatorWidgetData` and `IndicatorWidgetDataItem` as the public names for
+the configuration without deprecated fields. Their imports from
+`@gravity-ui/chartkit/indicator` do not need to change.
+
+Use `LegacyIndicatorWidgetData` and `LegacyIndicatorWidgetDataItem` for the old
+configuration accepted by the migration adapter.
+
+In v9, `IndicatorWidgetData` and `IndicatorWidgetDataItem` keep the legacy
+contract with required `content.current`. Existing interfaces can still extend
+them, and existing code can read `item.content.current` without a guard.
+
+Use `ChartKitProps<'indicator'>['data']` for input containing `value`
+or a mix of new and legacy items. The types without deprecated fields remain
+internal until the major release.
+
+`title`, `size`, `nowrap`, `defaultColor`, and `formatNumber` use the same options.
+
+In v9 configurations containing both forms, `value` takes precedence over
+`content.current`. If `value.color` is omitted, the item-level `color` is
+used; an explicitly empty `value.color` uses `defaultColor`.
+
+The main-value formatter receives `value` instead of `content.current`.
+The new `value` configuration declares `value`, `color`, `formatNumber`, and `numberFormat`.
+In v9, arbitrary formatter metadata remains supported through the legacy
+`content.current` configuration.
+
+When converting legacy data, metadata named `color`, `formatNumber`, or
+`numberFormat` is removed or replaced. The adapter reports `resolution: 'review'`
+for each field; update any widget formatter that depends on it before using the
+migrated configuration. Legacy metadata is ignored when `value` is also supplied.
+
+`migrateIndicatorData` is internal and is not exported from the package.
+See the [indicator guide](indicator.md) for configuration and formatting options.
diff --git a/gulpfile.js b/gulpfile.js
index b72677ad..f205f309 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -187,9 +187,10 @@ task('styles-components', () => {
// ships in the npm tarball.
task('copy-docs', (done) => {
const {buildDocs} = require('@gravity-ui/readme-validator');
- buildDocs({
+ const outDir = path.join(__dirname, 'build', 'docs');
+ const {sections} = buildDocs({
rootDir: __dirname,
- outDir: path.join(__dirname, 'build', 'docs'),
+ outDir,
sources: [
{
title: 'Guides',
@@ -200,6 +201,22 @@ task('copy-docs', (done) => {
},
],
});
+ const drafts = sections
+ .flatMap(({entries}) => entries)
+ .filter(({name}) => /\(draft\)$/i.test(name));
+ if (drafts.length) {
+ const indexPath = path.join(outDir, 'INDEX.md');
+ const index = fs.readFileSync(indexPath, 'utf8').split('\n');
+ fs.writeFileSync(
+ indexPath,
+ index
+ .filter((line) => !drafts.some(({rel}) => line.includes(`](./${rel})`)))
+ .join('\n'),
+ );
+ for (const {rel} of drafts) {
+ fs.rmSync(path.join(outDir, rel));
+ }
+ }
done();
});
diff --git a/scripts/check-build.mjs b/scripts/check-build.mjs
index 6b7168c8..275b3800 100644
--- a/scripts/check-build.mjs
+++ b/scripts/check-build.mjs
@@ -260,6 +260,8 @@ const CONSUMER_CHECKS = `
export const widget: ChartKitWidget['yagr']['widget'] = 123;
// @ts-expect-error a number is not a charts configuration: the adapter types must not degrade to any
export const migrated = migrateChartDataV1(123);
+// @ts-expect-error the indicator adapter is internal
+import {migrateIndicatorData} from '${name}/indicator';
// @ts-expect-error the normalized indicator configuration is internal
import type {NormalizedIndicatorWidgetConfig} from '${name}/indicator';
// @ts-expect-error the shared value shape is internal
diff --git a/src/plugins/indicator/migration/__tests__/migrate-indicator-data.test.ts b/src/plugins/indicator/migration/__tests__/migrate-indicator-data.test.ts
new file mode 100644
index 00000000..965f6f23
--- /dev/null
+++ b/src/plugins/indicator/migration/__tests__/migrate-indicator-data.test.ts
@@ -0,0 +1,107 @@
+import {migrateIndicatorData} from '../migrate-indicator-data';
+
+describe('migrateIndicatorData', () => {
+ test('converts legacy fields, reports their paths and is idempotent', () => {
+ const modern = {value: {value: 0}};
+ const input = {
+ data: [modern, {content: {current: {value: 1200}}, color: 'blue'}],
+ };
+
+ const {data, warnings} = migrateIndicatorData(input);
+
+ expect(data.data).toEqual([modern, {value: {value: 1200, color: 'blue'}}]);
+ expect(data.data?.[0]).toBe(modern);
+ expect(warnings).toEqual([
+ {
+ code: 'indicator-content',
+ path: ['data', 1, 'content'],
+ message: 'Use value instead of content.current.',
+ replacement: 'value',
+ resolution: 'automatic',
+ },
+ {
+ code: 'indicator-color',
+ path: ['data', 1, 'color'],
+ message: 'Use value.color instead of the item color.',
+ replacement: 'value.color',
+ resolution: 'automatic',
+ },
+ ]);
+
+ const repeated = migrateIndicatorData(data);
+ expect(repeated.data).toBe(data);
+ expect(repeated.warnings).toEqual([]);
+ });
+
+ test.each([{}, {data: [{value: {value: 42}}]}])(
+ 'preserves configurations without legacy fields: %j',
+ (input) => {
+ const result = migrateIndicatorData(input);
+ expect(result.data).toBe(input);
+ expect(result.warnings).toEqual([]);
+ },
+ );
+
+ test.each([
+ {field: 'color', metadata: 'USD'},
+ {field: 'formatNumber', metadata: vi.fn()},
+ {field: 'numberFormat', metadata: {currency: 'USD'}},
+ ])('requires review when migrating legacy $field metadata', ({field, metadata}) => {
+ const current = Object.freeze({value: 42, [field]: metadata});
+ const input = {data: [{value: {value: 0}}, {content: {current}}]};
+
+ const {data, warnings} = migrateIndicatorData(input);
+
+ expect(data.data?.[1]?.value).toEqual({value: 42});
+ expect(input.data[1].content?.current).toBe(current);
+ expect(warnings).toContainEqual({
+ code: 'indicator-formatter-metadata',
+ path: ['data', 1, 'content', 'current', field],
+ message: `Legacy formatter metadata "${field}" is removed or replaced during migration. Update any widget formatNumber callback that depends on it.`,
+ resolution: 'review',
+ });
+ if (typeof metadata === 'function') {
+ expect(metadata).not.toHaveBeenCalled();
+ }
+ });
+
+ test('does not require review for legacy metadata overridden by value', () => {
+ const value = {value: 42};
+ const input = {data: [{value, content: {current: {value: 10, color: 'USD'}}}]};
+
+ const {data, warnings} = migrateIndicatorData(input);
+
+ expect(data.data?.[0]?.value).toBe(value);
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0].resolution).toBe('automatic');
+ });
+
+ test('reports every metadata conflict when the item color replaces legacy metadata', () => {
+ const current = {value: 42, color: 'USD', formatNumber: 'custom', numberFormat: 'currency'};
+
+ const {data, warnings} = migrateIndicatorData({
+ data: [{content: {current}, color: 'blue'}],
+ });
+
+ expect(data.data?.[0]?.value).toEqual({value: 42, color: 'blue'});
+ expect(
+ warnings.filter(({resolution}) => resolution === 'review').map(({path}) => path),
+ ).toEqual([
+ ['data', 0, 'content', 'current', 'color'],
+ ['data', 0, 'content', 'current', 'formatNumber'],
+ ['data', 0, 'content', 'current', 'numberFormat'],
+ ]);
+ expect(current.color).toBe('USD');
+ expect(migrateIndicatorData(data).warnings).toEqual([]);
+ });
+
+ test('preserves non-conflicting formatter metadata without requiring review', () => {
+ const current = {value: 42, currency: 'USD'};
+
+ const {data, warnings} = migrateIndicatorData({data: [{content: {current}}]});
+
+ expect(data.data?.[0]?.value).toBe(current);
+ expect(warnings).toHaveLength(1);
+ expect(warnings[0].resolution).toBe('automatic');
+ });
+});
diff --git a/src/plugins/indicator/migration/migrate-indicator-data.ts b/src/plugins/indicator/migration/migrate-indicator-data.ts
new file mode 100644
index 00000000..2ad222a8
--- /dev/null
+++ b/src/plugins/indicator/migration/migrate-indicator-data.ts
@@ -0,0 +1,48 @@
+import type {MigrationResult, MigrationWarning} from '../../shared/migration';
+import {normalizeIndicatorData} from '../normalize';
+import type {IndicatorWidgetConfig, NormalizedIndicatorWidgetConfig} from '../types';
+
+type IndicatorMigrationWarning = MigrationWarning<
+ 'indicator-content' | 'indicator-color' | 'indicator-formatter-metadata'
+>;
+
+/** Normalize configuration and collect diagnostics for an explicit migration. */
+export function migrateIndicatorData(
+ input: IndicatorWidgetConfig,
+): MigrationResult {
+ const data = normalizeIndicatorData(input);
+ const warnings: IndicatorMigrationWarning[] = [];
+ input.data?.forEach((item, index) => {
+ if ('content' in item) {
+ warnings.push({
+ code: 'indicator-content',
+ path: ['data', index, 'content'],
+ message: 'Use value instead of content.current.',
+ replacement: 'value',
+ resolution: 'automatic',
+ });
+ if (!item.value && item.content) {
+ for (const field of ['color', 'formatNumber', 'numberFormat']) {
+ if (field in item.content.current) {
+ warnings.push({
+ code: 'indicator-formatter-metadata',
+ path: ['data', index, 'content', 'current', field],
+ message: `Legacy formatter metadata "${field}" is removed or replaced during migration. Update any widget formatNumber callback that depends on it.`,
+ resolution: 'review',
+ });
+ }
+ }
+ }
+ }
+ if ('color' in item) {
+ warnings.push({
+ code: 'indicator-color',
+ path: ['data', index, 'color'],
+ message: 'Use value.color instead of the item color.',
+ replacement: 'value.color',
+ resolution: 'automatic',
+ });
+ }
+ });
+ return {data, warnings};
+}
diff --git a/src/plugins/shared/migration.ts b/src/plugins/shared/migration.ts
new file mode 100644
index 00000000..da348a7d
--- /dev/null
+++ b/src/plugins/shared/migration.ts
@@ -0,0 +1,12 @@
+export type MigrationWarning = {
+ code: TCode;
+ path: (string | number)[];
+ message: string;
+ replacement?: string;
+ resolution: 'automatic' | 'review';
+};
+
+export type MigrationResult = {
+ data: TData;
+ warnings: TWarning[];
+};