Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .agents/plans/NEXT_MAJOR_PLAN.md
Original file line number Diff line number Diff line change
@@ -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: `<ChartKit type="indicator" data={config} />`
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.
76 changes: 76 additions & 0 deletions docs/indicator-migration.md
Original file line number Diff line number Diff line change
@@ -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.
21 changes: 19 additions & 2 deletions gulpfile.js
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
const map = file.sourceMap;
if (map) {
if (!file.contents.toString('utf8').endsWith('\n')) {
file.contents = Buffer.concat([file.contents, Buffer.from('\n')]);

Check warning on line 31 in gulpfile.js

View workflow job for this annotation

GitHub Actions / Verify Files

Assignment to property of function parameter 'file'
}
map.file = path.basename(file.relative);
map.sourceRoot = path.relative(
Expand Down Expand Up @@ -187,9 +187,10 @@
// 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',
Expand All @@ -200,6 +201,22 @@
},
],
});
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();
});

Expand Down
2 changes: 2 additions & 0 deletions scripts/check-build.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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');
});
});
48 changes: 48 additions & 0 deletions src/plugins/indicator/migration/migrate-indicator-data.ts
Original file line number Diff line number Diff line change
@@ -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<NormalizedIndicatorWidgetConfig, IndicatorMigrationWarning> {
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};
}
12 changes: 12 additions & 0 deletions src/plugins/shared/migration.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
export type MigrationWarning<TCode extends string = string> = {
code: TCode;
path: (string | number)[];
message: string;
replacement?: string;
resolution: 'automatic' | 'review';
};

export type MigrationResult<TData, TWarning extends MigrationWarning = MigrationWarning> = {
data: TData;
warnings: TWarning[];
};
Loading