Skip to content

Commit a6c35a2

Browse files
os-zhuangclaude
os-zhuang
and
claude
authored
feat(spec)!: prune dead ReportColumnSchema/ReportGroupingSchema exports + unread report chart groupBy (#3463) (#3488)
Deep-cleanup close-out of the report-chart disposition (follow-up to #3441, umbrella #1878/#1890). After the ADR-0021 single-form cutover a dataset-bound report expresses columns/grouping as dataset measure/dimension name arrays (`values`/`rows`/`columns` = `z.array(z.string())`), so ReportColumnSchema / ReportGroupingSchema were referenced by no schema body — they survived only as public type exports and were marked @deprecated in #3441. - Remove ReportColumnSchema / ReportGroupingSchema and their type exports (ReportColumn / ReportGrouping / ReportColumnInput / ReportGroupingInput) from @objectstack/spec/ui; drop the now-orphan ResponsiveConfigSchema import. - Remove ReportChart.groupBy — the [EXPERIMENTAL — not enforced] series-split field from #3441. The dataset-bound DatasetReportRenderer plots a single xAxis×yAxis series and never read it; only the retired legacy ReportViewer fallback consumed a top-level groupBy. ReportChartSchema is non-strict, so residual chart.groupBy in stored metadata is silently stripped on parse. - Drop manifest ratchet keys ui/ReportColumn, ui/ReportGrouping; regenerate content/docs/references/ui/report.mdx and the spec API-surface snapshot. No first-party or example report authored these objects or chart.groupBy. Ships as minor per the launch-window breaking-as-minor policy; changeset carries the FROM→TO migration. Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent bbd902d commit a6c35a2

5 files changed

Lines changed: 41 additions & 81 deletions

File tree

‎.changeset/prune-report-column-grouping-schemas.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
"@objectstack/spec": minor
3+
---
4+
5+
feat(spec)!: prune the dead `ReportColumnSchema`/`ReportGroupingSchema` exports + the unread report chart `groupBy` (#3463, #1878/#1890)
6+
7+
Deep-cleanup close-out of the report-chart disposition (follow-up to #3441).
8+
After the ADR-0021 single-form cutover a dataset-bound report expresses its
9+
columns/grouping as dataset **measure/dimension name arrays** — `values`,
10+
`rows` and `columns` are `z.array(z.string())`, not object literals — so
11+
`ReportColumnSchema` / `ReportGroupingSchema` were referenced by **no schema
12+
body**. They survived only as public type exports and were marked
13+
`@deprecated` in #3441; this removes them.
14+
15+
- Deleted `ReportColumnSchema` / `ReportGroupingSchema` and their type
16+
exports `ReportColumn` / `ReportGrouping` / `ReportColumnInput` /
17+
`ReportGroupingInput` from `@objectstack/spec/ui`. The manifest ratchet
18+
keys `ui/ReportColumn` / `ui/ReportGrouping` are dropped in the same PR.
19+
- Deleted `ReportChart.groupBy` — the `[EXPERIMENTAL — not enforced]`
20+
series-split field flagged in #3441. The dataset-bound `DatasetReportRenderer`
21+
plots a single `xAxis`×`yAxis` series and never read it; only the retired
22+
legacy `ReportViewer` fallback ever consumed a top-level `groupBy`.
23+
`ReportChartSchema` is non-strict, so any residual `chart.groupBy` in stored
24+
metadata is silently stripped on parse — no tombstone needed.
25+
- Regenerated `content/docs/references/ui/report.mdx` and the spec API-surface
26+
snapshot.
27+
28+
**Migration**: nothing an author writes changes.
29+
- No first-party or example report authored `ReportColumn` / `ReportGrouping`
30+
objects or `chart.groupBy` — a dataset-bound report already expresses
31+
columns as `values` (measure names) and grouping as `rows` / `columns`
32+
(dimension names).
33+
- TypeScript consumers importing `ReportColumn` / `ReportGrouping` /
34+
`ReportColumnInput` / `ReportGroupingInput` (or the `*Schema` values) from
35+
`@objectstack/spec/ui` have no replacement type — model report columns as
36+
the dataset's measure names and grouping as its dimension names. objectui's
37+
`SpecReportColumn*` / `SpecReportGrouping*` re-exports are removed in the
38+
companion objectui change.

‎content/docs/references/ui/report.mdx‎

Lines changed: 2 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ Report Type Enum
1414
## TypeScript Usage
1515

1616
```typescript
17-
import { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';
18-
import type { JoinedReportBlock, Report, ReportChart, ReportColumn, ReportGrouping, ReportType } from '@objectstack/spec/ui';
17+
import { JoinedReportBlock, Report, ReportChart, ReportType } from '@objectstack/spec/ui';
18+
import type { JoinedReportBlock, Report, ReportChart, ReportType } from '@objectstack/spec/ui';
1919

2020
// Validate data
2121
const result = JoinedReportBlock.parse(data);
@@ -95,34 +95,6 @@ const result = JoinedReportBlock.parse(data);
9595
| **annotations** | `{ type: Enum<'line' \| 'region'>; axis: Enum<'x' \| 'y'>; value: number \| string; endValue?: number \| string; … }[]` | optional | |
9696
| **interaction** | `{ tooltips: boolean; zoom: boolean; brush: boolean; clickAction?: string }` | optional | |
9797
| **aria** | `{ ariaLabel?: string; ariaDescribedBy?: string; role?: string }` | optional | ARIA accessibility attributes |
98-
| **groupBy** | `string` | optional | [EXPERIMENTAL — not enforced] Additional series-split grouping; not read by the dataset-bound report renderer (liveness #1878/#1890) |
99-
100-
101-
---
102-
103-
## ReportColumn
104-
105-
### Properties
106-
107-
| Property | Type | Required | Description |
108-
| :--- | :--- | :--- | :--- |
109-
| **field** | `string` | ✅ | Field name |
110-
| **label** | `string` | optional | Override label |
111-
| **aggregate** | `Enum<'sum' \| 'avg' \| 'max' \| 'min' \| 'count' \| 'unique'>` | optional | Aggregation function |
112-
| **responsive** | `{ breakpoint?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>; hiddenOn?: Enum<'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'>[]; columns?: object; order?: object }` | optional | Responsive visibility for this column |
113-
114-
115-
---
116-
117-
## ReportGrouping
118-
119-
### Properties
120-
121-
| Property | Type | Required | Description |
122-
| :--- | :--- | :--- | :--- |
123-
| **field** | `string` | ✅ | Field to group by |
124-
| **sortOrder** | `Enum<'asc' \| 'desc'>` | ✅ | |
125-
| **dateGranularity** | `Enum<'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional | For date fields |
12698

12799

128100
---

‎packages/spec/api-surface.json‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3344,12 +3344,6 @@
33443344
"ReportChart (type)",
33453345
"ReportChartInput (type)",
33463346
"ReportChartSchema (const)",
3347-
"ReportColumn (type)",
3348-
"ReportColumnInput (type)",
3349-
"ReportColumnSchema (const)",
3350-
"ReportGrouping (type)",
3351-
"ReportGroupingInput (type)",
3352-
"ReportGroupingSchema (const)",
33533347
"ReportInput (type)",
33543348
"ReportNavItem (type)",
33553349
"ReportNavItemSchema (const)",

‎packages/spec/json-schema.manifest.json‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1738,8 +1738,6 @@
17381738
"ui/RecordRelatedListProps",
17391739
"ui/Report",
17401740
"ui/ReportChart",
1741-
"ui/ReportColumn",
1742-
"ui/ReportGrouping",
17431741
"ui/ReportNavItem",
17441742
"ui/ReportType",
17451743
"ui/ResponsiveConfig",

‎packages/spec/src/ui/report.zod.ts‎

Lines changed: 1 addition & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { FilterConditionSchema } from '../data/filter.zod';
77
import { ChartConfigSchema } from './chart.zod';
88
import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
99
import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
10-
import { ResponsiveConfigSchema, PerformanceConfigSchema } from './responsive.zod';
10+
import { PerformanceConfigSchema } from './responsive.zod';
1111

1212
/**
1313
* Report Type Enum
@@ -20,37 +20,6 @@ export const ReportType = z.enum([
2020
'joined' // Joined multiple blocks
2121
]);
2222

23-
/**
24-
* Report Column Schema
25-
*
26-
* @deprecated Unreferenced by the single-form (ADR-0021) report shape — a
27-
* dataset-bound report selects `values` (measure names) and `rows`/`columns`
28-
* (dimension names) as `z.array(z.string())`, not `ReportColumn` objects. Kept
29-
* only as a public type export (objectui re-exports it as `SpecReportColumn`);
30-
* slated for removal in a future governed prune (liveness #1878/#1890).
31-
*/
32-
export const ReportColumnSchema = lazySchema(() => z.object({
33-
field: z.string().describe('Field name'),
34-
label: I18nLabelSchema.optional().describe('Override label'),
35-
aggregate: z.enum(['sum', 'avg', 'max', 'min', 'count', 'unique']).optional().describe('Aggregation function'),
36-
/** Responsive visibility/priority per breakpoint */
37-
responsive: ResponsiveConfigSchema.optional().describe('Responsive visibility for this column'),
38-
}));
39-
40-
/**
41-
* Report Grouping Schema
42-
*
43-
* @deprecated Unreferenced by the single-form (ADR-0021) report shape —
44-
* grouping is expressed by dataset dimension names in `rows`/`columns`. Kept
45-
* only as a public type export (objectui re-exports it as `SpecReportGrouping`);
46-
* slated for removal in a future governed prune (liveness #1878/#1890).
47-
*/
48-
export const ReportGroupingSchema = lazySchema(() => z.object({
49-
field: z.string().describe('Field to group by'),
50-
sortOrder: z.enum(['asc', 'desc']).default('asc'),
51-
dateGranularity: z.enum(['day', 'week', 'month', 'quarter', 'year']).optional().describe('For date fields'),
52-
}));
53-
5423
/**
5524
* Report Chart Schema
5625
*
@@ -64,13 +33,6 @@ export const ReportChartSchema = lazySchema(() => ChartConfigSchema.extend({
6433
xAxis: z.string().describe('Dataset dimension name for the X-axis (bound-dataset dimension, not a raw field)'),
6534
/** Dataset **measure** name for the Y-axis (from the report's bound dataset). */
6635
yAxis: z.string().describe('Dataset measure name for the Y-axis (bound-dataset measure, not a raw field)'),
67-
/**
68-
* ⚠️ EXPERIMENTAL — NOT ENFORCED (liveness #1878/#1890). An additional
69-
* series-split grouping. The dataset-bound `DatasetReportRenderer` plots a
70-
* single `xAxis`×`yAxis` series and does not read this; only the legacy
71-
* `ReportViewer` fallback consumed a top-level `groupBy`.
72-
*/
73-
groupBy: z.string().optional().describe('[EXPERIMENTAL — not enforced] Additional series-split grouping; not read by the dataset-bound report renderer (liveness #1878/#1890)'),
7436
}));
7537

7638
/**
@@ -223,17 +185,13 @@ export type JoinedReportBlockInput = z.input<typeof JoinedReportBlockSchema>;
223185
* which allow optional fields with defaults to be omitted.
224186
*/
225187
export type Report = z.infer<typeof ReportSchema>;
226-
export type ReportColumn = z.infer<typeof ReportColumnSchema>;
227-
export type ReportGrouping = z.infer<typeof ReportGroupingSchema>;
228188
export type ReportChart = z.infer<typeof ReportChartSchema>;
229189

230190
/**
231191
* Input Types for Report Configuration
232192
* Use these when defining reports in configuration files.
233193
*/
234194
export type ReportInput = z.input<typeof ReportSchema>;
235-
export type ReportColumnInput = z.input<typeof ReportColumnSchema>;
236-
export type ReportGroupingInput = z.input<typeof ReportGroupingSchema>;
237195
export type ReportChartInput = z.input<typeof ReportChartSchema>;
238196

239197
/**

0 commit comments

Comments
 (0)