Initial TS set up

plotly · camdecoster · Jan 2, 2026 · Dec 30, 2025 · Jan 2, 2026 · Jan 2, 2026
commit d4425fcc87d125afffd0cd4bf496a304986772f9
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -40,6 +40,8 @@
     "cibuild": "npm run empty-dist && npm run preprocess && node tasks/cibundle.mjs",
     "lint": "npx @biomejs/biome lint",
     "lint-fix": "npx @biomejs/biome format ./test/image/mocks --write; npx @biomejs/biome lint --write || true",
+    "typecheck": "tsc --noEmit",
+    "typecheck:watch": "tsc --noEmit --watch",
     "pretest": "node tasks/pretest.js",
     "test-jasmine": "karma start test/jasmine/karma.conf.js",
     "test-mock": "node tasks/test_mock.mjs",
@@ -122,6 +124,8 @@
     "@biomejs/biome": "2.2.0",
     "@plotly/mathjax-v2": "npm:mathjax@2.7.5",
     "@plotly/mathjax-v3": "npm:mathjax@^3.2.2",
+    "@types/d3": "3.5.34",
+    "@types/node": "^24.10.0",
     "amdefine": "^1.0.1",
     "assert": "^2.1.0",
     "browserify-transform-tools": "^1.7.0",
@@ -174,6 +178,7 @@
     "through2": "^4.0.2",
     "transform-loader": "^0.2.4",
     "true-case-path": "^2.2.1",
+    "typescript": "^5.9.3",
     "virtual-webgl": "^1.0.6"
   },
   "overrides": {

diff --git a/src/types/README.md b/src/types/README.md
@@ -0,0 +1,63 @@
+# Types Directory
+
+Centralized TypeScript type definitions for plotly.js.
+
+## Quick Import
+
+```typescript
+// Import from main index (recommended)
+import type { GraphDiv, Layout, PlotData } from '../types';
+
+// Or use path alias
+import type { GraphDiv } from '@types';
+```
+
+## Directory Structure
+
+```
+types/
+├── index.d.ts         # Main export - import from here
+├── core/              # Core Plotly types (GraphDiv, Layout, Data, Config, Events)
+├── traces/            # Trace-specific types
+├── components/        # Component-specific types
+├── plots/             # Plot-specific types
+└── lib/               # Utility types
+```
+
+## Most Common Types
+
+### GraphDiv
+```typescript
+import type { GraphDiv } from '../types';
+
+function draw(gd: GraphDiv): void {
+    const layout = gd._fullLayout;
+    const data = gd._fullData;
+}
+```
+
+### Layout
+```typescript
+import type { Layout } from '../types';
+
+function updateLayout(layout: Partial<Layout>): void {
+    layout.title = 'New Title';
+}
+```
+
+### PlotData (Traces)
+```typescript
+import type { PlotData, ScatterTrace } from '../types';
+
+function processTrace(trace: PlotData): void {
+    if (trace.type === 'scatter') {
+        const scatter = trace as ScatterTrace;
+    }
+}
+```
+
+## Adding New Types
+
+1. Create file in appropriate subdirectory
+2. Export from `index.d.ts`
+3. Use in your TypeScript files
diff --git a/src/types/components/common.d.ts b/src/types/components/common.d.ts
@@ -0,0 +1,41 @@
+/**
+ * Common component-related types
+ *
+ * Types shared across different component modules
+ */
+
+/**
+ * Component module interface
+ */
+export interface ComponentModule {
+    includeBasePlot?: (basePlotModule: string) => void;
+    layoutAttributes?: any;
+    name: string;
+    supplyLayoutDefaults?: (layoutIn: any, layoutOut: any, fullData: any) => void;
+}
+
+/**
+ * Drawing options (used by many components)
+ */
+export interface DrawingOptions {
+    duration?: number;
+    ease?: string;
+    redraw?: boolean;
+}
+
+/**
+ * SVG text utilities return type
+ */
+export interface TextBBox {
+    bottom: number;
+    height: number;
+    left: number;
+    right: number;
+    top: number;
+    width: number;
+}
+
+/**
+ * Color with alpha
+ */
+export type ColorString = string;
diff --git a/src/types/core/config.d.ts b/src/types/core/config.d.ts
@@ -0,0 +1,177 @@
+/**
+ * Config types
+ *
+ * Defines the structure of Plotly config options.
+ */
+
+/**
+ * User-provided configuration for Plotly
+ */
+export interface Config {
+    /**
+     * Whether the plot should resize on window resize
+     */
+    autosizable?: boolean;
+
+    /**
+     * Display Plotly logo on mode bar
+     */
+    displaylogo?: boolean;
+
+    /**
+     * Display the mode bar
+     */
+    displayModeBar?: boolean | 'hover';
+
+    /**
+     * What happens on double click
+     */
+    doubleClick?: 'reset' | 'autosize' | 'reset+autosize' | false;
+
+    /**
+     * Allow plot to be edited
+     */
+    editable?: boolean;
+
+    /**
+     * What can be edited
+     */
+    edits?: Partial<ConfigEdits>;
+
+    /**
+     * Whether to fill the parent container
+     */
+    fillFrame?: boolean;
+
+    /**
+     * Margin around the plot when fillFrame is true
+     */
+    frameMargins?: number;
+
+    /**
+     * Text for the "Edit in Chart Studio" link
+     */
+    linkText?: string;
+
+    /**
+     * Locale for formatting
+     */
+    locale?: string;
+
+    /**
+     * Custom locale definitions
+     */
+    locales?: { [locale: string]: any };
+
+    /**
+     * Mapbox access token
+     */
+    mapboxAccessToken?: string;
+
+    /**
+     * Custom mode bar buttons configuration
+     */
+    modeBarButtons?: any;
+
+    /**
+     * Mode bar buttons to add
+     */
+    modeBarButtonsToAdd?: any[];
+
+    /**
+     * Mode bar buttons to remove
+     */
+    modeBarButtonsToRemove?: string[];
+
+    /**
+     * Pixel ratio for WebGL plots
+     */
+    plotGlPixelRatio?: number;
+
+    /**
+     * Base URL for plotly server
+     */
+    plotlyServerURL?: string;
+
+    /**
+     * Number of operations that can be queued
+     */
+    queueLength?: number;
+
+    /**
+     * Whether to resize on window resize (alternative)
+     */
+    responsive?: boolean;
+
+    /**
+     * Enable scroll zoom
+     */
+    scrollZoom?: boolean;
+
+    /**
+     * Send data to Chart Studio
+     */
+    sendData?: boolean;
+
+    /**
+     * Background color setting function
+     */
+    setBackground?: string | ((gd: any) => void);
+
+    /**
+     * Show "Edit in Chart Studio" link
+     */
+    showLink?: boolean;
+
+    /**
+     * Show tips on first hover
+     */
+    showTips?: boolean;
+
+    /**
+     * Make the chart static - no interactivity
+     */
+    staticPlot?: boolean;
+
+    /**
+     * Options for the "Download plot as PNG" button
+     */
+    toImageButtonOptions?: Partial<ToImageButtonOptions>;
+
+    /**
+     * URL for topojson files
+     */
+    topojsonURL?: string;
+
+    /**
+     * Add watermark to images
+     */
+    watermark?: boolean;
+}
+
+/**
+ * Configuration for what can be edited
+ */
+export interface ConfigEdits {
+    annotationPosition?: boolean;
+    annotationTail?: boolean;
+    annotationText?: boolean;
+    axisTitleText?: boolean;
+    colorbarPosition?: boolean;
+    colorbarTitleText?: boolean;
+    legendPosition?: boolean;
+    legendText?: boolean;
+    shapePosition?: boolean;
+    titleText?: boolean;
+}
+
+/**
+ * Options for the "Download plot" button
+ */
+export interface ToImageButtonOptions {
+    format?: 'png' | 'svg' | 'jpeg' | 'webp';
+    filename?: string;
+    height?: number;
+    width?: number;
+    scale?: number;
+}