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[]; +};