Merge pull request #7868 from plotly/cam/7867/generate-data-union-type

refactor: Generate union of data types

Author: camdecoster

src/types/ARCHITECTURE.md

@@ -51,7 +51,9 @@ The split:
       FontArray, ColorBar, HoverLabel, Domain, Pattern, TickFormatStops,
       LegendGroupTitle).
     - **Per-trace data interfaces** for all trace types (BarData, ScatterData,
-      IndicatorData, etc.).
+      IndicatorData, etc.), plus the **`Data` discriminated union** over all
+      of them (`Partial<BarData> | Partial<ScatterData> | …`) — narrowed via
+      the `type` field.
     - **Layout component interfaces** (LayoutAxis, Legend, Scene,
       Annotation, Shape, Slider, UpdateMenu, etc.) and the Layout
       interface itself.
@@ -85,7 +87,7 @@ This split is reflected in the types:
 | User-facing | Internal | Where defined |
 |---|---|---|
 | `Layout` | `FullLayout` | `Layout` in `generated/schema.d.ts`; `FullLayout` in `core/layout.internal.d.ts` |
-| `Data` (union over `type`) | `FullData` | `Data` in `core/data.d.ts` (union of schema `*Data` interfaces); `FullData = Data & FullDataInternals` in `core/data.internal.d.ts` |
+| `Data` (union over `type`) | `FullData` | `Data` in `generated/schema.d.ts` (union of schema `*Data` interfaces); `FullData = Data & FullDataInternals` in `core/data.internal.d.ts` |
 | (n/a) | `GraphDiv` (the `gd` param) | `core/graph-div.internal.d.ts` — DOM element with `_fullLayout`, `_fullData`, `calcdata`, etc. |
 
 `FullData` is the discriminated union of schema trace types intersected with
@@ -106,7 +108,6 @@ src/types/
 ├── core/                         # hand-written types for the core API
 │   ├── api.d.ts                  # public API function signatures (newPlot, etc.)
 │   ├── config.d.ts               # Config, ToImgopts (Edits re-exported from generated)
-│   ├── data.d.ts                 # Data union (over all schema `*Data` interfaces)
 │   ├── data.internal.d.ts        # CalcData, FullData
 │   ├── events.d.ts               # PlotMouseEvent, PlotlyHTMLElement, etc.
 │   ├── graph-div.internal.d.ts   # GraphDiv, GraphContext
@@ -173,6 +174,8 @@ src/types/generated/schema.d.ts
     │ // Trace interfaces
     │ export interface ScatterData { marker?: _internal.Marker; ... }
     │ export interface BarData { ... }
+    │ // Discriminated union over all traces
+    │ export type Data = Partial<BarData> | Partial<ScatterData> | ...;
     │ // Layout
     │ export interface LayoutAxis { autorangeoptions?: _internal.AutoRangeOptions; ... }
     │ export interface Layout { ... }

src/types/GENERATOR.md

@@ -8,6 +8,7 @@ types into `src/types/generated/schema.d.ts`:
   TransitionEasing, TraceType — plus a deprecated `PlotType` alias)
 - Shared sub-interfaces (Font, ColorBar, HoverLabel, etc.)
 - Data interfaces for each trace type (BarData, ScatterData, IndicatorData, etc.)
+  and the `Data` discriminated union over all of them
 - Layout component interfaces (LayoutAxis, Legend, Scene, Annotation, etc.)
   and the Layout interface itself
 - Animation / frame / edits interfaces (AnimationOpts, Frame, Edits)
@@ -90,7 +91,11 @@ so the automatic extractor skips them, but they need to be named for
 ### Phase 3: Trace interfaces
 
 Each trace gets an interface (`ScatterData`, `BarData`, etc.) whose
-properties reference shared types where fingerprints match.
+properties reference shared types where fingerprints match. After all
+trace interfaces are emitted, the generator also emits the discriminated
+union `Data = Partial<BarData> | Partial<BarpolarData> | …` covering every
+trace — narrowed via the `type` field. Adding or removing a trace in the
+schema flows through automatically.
 
 ### Phase 4: Layout types
 
@@ -191,6 +196,7 @@ src/types/generated/schema.d.ts
 │                                                        AutoRangeOptions,
 │                                                        Lighting, ErrorY)
 ├── Trace interfaces (ScatterData, BarData, ... — 49 traces)
+├── Data union (`Partial<*Data>` over every trace, discriminated by `type`)
 ├── Layout component interfaces (LayoutAxis, Legend, Scene, Annotation, etc.)
 ├── Layout interface
 └── Animation / frames / config (AnimationOpts, Frame, Edits, ConfigBase)

src/types/README.md

@@ -48,6 +48,7 @@ The following are **auto-generated from `plot-schema.json`** by
 - Common enum aliases (Calendar, Dash, AxisType, PatternShape, XRef, YRef,
   TransitionEasing, TraceType — and a deprecated `PlotType` alias)
 - Data interfaces for each trace type (BarData, ScatterData, IndicatorData, etc.)
+  and the `Data` discriminated union over all of them
 - Layout component interfaces (LayoutAxis, Legend, Scene, Annotation,
   Shape, Slider, UpdateMenu, etc.) and the Layout interface itself
 - Shared sub-interfaces (Font, ColorBar, HoverLabel, LegendGroupTitle, etc.)

src/types/core/api.d.ts

@@ -2,9 +2,8 @@
  * Public API function types for Plotly.js
  */
 
-import type { AnimationOpts, Frame, Layout } from '../generated/schema';
+import type { AnimationOpts, Data, Frame, Layout } from '../generated/schema';
 import type { Config, DownloadImgopts, ToImgopts } from './config';
-import type { Data } from './data';
 import type { PlotlyHTMLElement } from './events';
 import type { Icon, Template } from './layout';
 

src/types/core/data.d.ts

@@ -8,6 +8,7 @@
 import type {
     AnimationFrameOpts,
     Annotation,
+    Data,
     Frame,
     Layout,
     LayoutAxis,
@@ -16,7 +17,6 @@ import type {
 } from '../generated/schema';
 import type { Datum } from '../lib/common';
 import type { Config } from './config';
-import type { Data } from './data';
 
 // ---------------------------------------------------------------------------
 // Point / datum types in events

src/types/core/events.d.ts

@@ -6,9 +6,8 @@
  * Commonly referred to as `gd` in the codebase.
  */
 
-import type { Layout } from '../generated/schema';
+import type { Data, Layout } from '../generated/schema';
 import type { Config } from './config';
-import type { Data } from './data';
 import type { CalcData, FullData } from './data.internal';
 import type { FullLayout } from './layout.internal';
 

src/types/core/graph-div.internal.d.ts

@@ -8,8 +8,7 @@
  * literal utilities, and deprecated aliases.
  */
 
-import type { Layout } from '../generated/schema';
-import type { Data, TraceType } from './data';
+import type { Data, Layout, TraceType } from '../generated/schema';
 import type { PlotlyHTMLElement } from './events';
 
 // ---------------------------------------------------------------------------

src/types/core/layout.d.ts

@@ -12091,6 +12091,65 @@ export interface WaterfallData {
     zorder?: number;
 }
 
+/**
+ * Union of every trace shape. All fields are optional via `Partial<…>` —
+ * narrow with the `type` discriminator before accessing trace-specific
+ * attributes:
+ *
+ *     if (trace.type === 'bar') { trace.marker?.cornerradius }
+ *     if (trace.type === 'pie') { trace.marker?.colors }
+ */
+export type Data =
+    | Partial<BarData>
+    | Partial<BarpolarData>
+    | Partial<BoxData>
+    | Partial<CandlestickData>
+    | Partial<CarpetData>
+    | Partial<ChoroplethData>
+    | Partial<ChoroplethmapData>
+    | Partial<ChoroplethmapboxData>
+    | Partial<ConeData>
+    | Partial<ContourData>
+    | Partial<ContourcarpetData>
+    | Partial<DensitymapData>
+    | Partial<DensitymapboxData>
+    | Partial<FunnelData>
+    | Partial<FunnelareaData>
+    | Partial<HeatmapData>
+    | Partial<HistogramData>
+    | Partial<Histogram2dData>
+    | Partial<Histogram2dcontourData>
+    | Partial<IcicleData>
+    | Partial<ImageData>
+    | Partial<IndicatorData>
+    | Partial<IsosurfaceData>
+    | Partial<Mesh3dData>
+    | Partial<OhlcData>
+    | Partial<ParcatsData>
+    | Partial<ParcoordsData>
+    | Partial<PieData>
+    | Partial<SankeyData>
+    | Partial<ScatterData>
+    | Partial<Scatter3dData>
+    | Partial<ScattercarpetData>
+    | Partial<ScattergeoData>
+    | Partial<ScatterglData>
+    | Partial<ScattermapData>
+    | Partial<ScattermapboxData>
+    | Partial<ScatterpolarData>
+    | Partial<ScatterpolarglData>
+    | Partial<ScattersmithData>
+    | Partial<ScatterternaryData>
+    | Partial<SplomData>
+    | Partial<StreamtubeData>
+    | Partial<SunburstData>
+    | Partial<SurfaceData>
+    | Partial<TableData>
+    | Partial<TreemapData>
+    | Partial<ViolinData>
+    | Partial<VolumeData>
+    | Partial<WaterfallData>;
+
 // ---------------------------------------------------------------------------
 // Layout component interfaces
 // ---------------------------------------------------------------------------

src/types/generated/schema.d.ts

@@ -11,7 +11,6 @@ export * from './lib/common';
 // Core types (public)
 export * from './core/api';
 export * from './core/config';
-export * from './core/data';
 export * from './core/events';
 export * from './core/layout';