Skip to content

types

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

types

README.md

TypeScript in plotly.js

This directory documents the TypeScript conversion in progress.

Doc Audience
SETUP.md First-time contributor — toolchain overview, npm scripts
ARCHITECTURE.md Anyone working with types — directory layout, public/private split
CONVERTING_ATTRIBUTES.md Contributor doing conversion work — step-by-step recipe
GENERATOR.md Maintainer extending or debugging the type generator

Status

  • TypeScript build infrastructure: ✅ done
  • Public type surface in src/types/: ✅ done
  • AttributeMap validation machinery: ✅ done
  • Schema-based type generator: ✅ done — all trace types + layout + shared interfaces
  • Consumer entry point (lib/index.d.ts, wired via package.json#types): ✅ done
  • CI gates (typecheck + schema-typegen-diff-check): ✅ done
  • First attribute file converted (modebar): ✅ done
  • Conversion of remaining files: 🚧 in progress

Open conversion TODOs

  • src/fonts/ploticon.js — convert so DefaultIcons and IconsMap in src/types/core/api.d.ts can be derived from the module (type DefaultIcons = keyof typeof Ploticon) instead of maintained as a hand-written union that can drift. Consumers need .default appended per the established conversion pattern.

  • Add dimensionality to data_array in the JS attribute sources. The schema's data_array valType carries no shape info, but several attributes are genuinely 2D (heatmap/contour/contourcarpet z, surface z and surfacecolor, 2D text/customdata/hovertext on those traces) or 3D (image.z). The generator currently emits the loose union Datum[] | Datum[][] | TypedArray for every data_array so 2D/3D usage typechecks, but the trade-off is that 1D-only fields also accept 2D arrays.

The published consumer surface lives at lib/index.d.ts. This src/types/ directory is the authoring location — internal types live here, public types are re-exported through lib/index.d.ts to consumers.

Generated types

The following are auto-generated from plot-schema.json by tasks/generate_schema_types.mjs:

  • 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.)
  • Animation / frame / edits interfaces (AnimationOpts, Frame, Edits)
  • An _internal namespace with helpers like _internal.Marker, _internal.AutoRangeOptions that aren't meant as direct public surface

Run npm run schema to regenerate. The output lives at src/types/generated/schema.d.ts. See GENERATOR.md for the generator's internals.

How to help

If you want to convert a component attribute file:

  1. Read CONVERTING_ATTRIBUTES.md
  2. Pick a component file from the priority list at the bottom of that doc
  3. Claim it in a PR description
  4. Follow the recipe
  5. Submit a PR

Each conversion is a single self-contained commit.