build: Enable TypeScript type checking

package.json

@@ -31,7 +31,7 @@
     "schema": "node tasks/schema.mjs",
     "stats": "node tasks/stats.js",
     "find-strings": "node tasks/find_locale_strings.js",
-    "preprocess": "node tasks/preprocess.js",
+    "preprocess": "ts-node tasks/preprocess.js",
     "use-draftlogs": "node tasks/use_draftlogs.js",
     "empty-draftlogs": "node tasks/empty_draftlogs.js",
     "empty-dist": "node tasks/empty_dist.js",
@@ -40,12 +40,14 @@
     "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",
     "test-image": "node test/image/compare_pixels_test.js",
     "test-export": "node test/image/export_test.js",
-    "test-syntax": "node tasks/test_syntax.js && npm run find-strings -- --no-output",
+    "test-syntax": "ts-node tasks/test_syntax.js && npm run find-strings -- --no-output",
     "test-bundle": "node tasks/test_bundle.js",
     "test-plain-obj": "node tasks/test_plain_obj.mjs",
     "test": "npm run test-jasmine -- --nowatch && npm run test-bundle && npm run test-image && npm run test-export && npm run test-syntax && npm run lint",
@@ -122,6 +124,8 @@
     "@biomejs/biome": "2.2.0",
     "@plotly/mathjax-v2": "npm:[email protected]",
     "@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,8 @@
     "through2": "^4.0.2",
     "transform-loader": "^0.2.4",
     "true-case-path": "^2.2.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
     "virtual-webgl": "^1.0.6"
   },
   "overrides": {

src/components/colorscale/attributes.js

@@ -2,7 +2,7 @@
 
 var colorbarAttrs = require('../colorbar/attributes');
 var counterRegex = require('../../lib/regex').counter;
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 
 var palettes = require('./scales.js').scales;
 var paletteStr = sortObjectKeys(palettes);

src/lib/clean_number.ts

@@ -0,0 +1,20 @@
+'use strict';
+
+import isNumeric from 'fast-isnumeric';
+import { BADNUM } from '../constants/numerical';
+
+// precompile for speed
+const JUNK = /^['"%,$#\s']+|[, ]|['"%,$#\s']+$/g;
+
+/**
+ * cleanNumber: remove common leading and trailing cruft
+ * Always returns either a number or BADNUM.
+ */
+function cleanNumber(v: any): number | undefined {
+    if (typeof v === 'string') v = v.replace(JUNK, '');
+    if (isNumeric(v)) return Number(v);
+
+    return BADNUM;
+}
+
+export default cleanNumber;

src/lib/index.js

@@ -105,7 +105,7 @@ lib.roundUp = searchModule.roundUp;
 lib.sort = searchModule.sort;
 lib.findIndexOfMin = searchModule.findIndexOfMin;
 
-lib.sortObjectKeys = require('./sort_object_keys');
+lib.sortObjectKeys = require('./sort_object_keys').default;
 
 var statsModule = require('./stats');
 lib.aggNums = statsModule.aggNums;
@@ -206,7 +206,7 @@ lib.pushUnique = require('./push_unique');
 
 lib.increment = require('./increment');
 
-lib.cleanNumber = require('./clean_number');
+lib.cleanNumber = require('./clean_number').default;
 
 lib.ensureNumber = function ensureNumber(v) {
     if (!isNumeric(v)) return BADNUM;

src/lib/mod.js → src/lib/mod.ts

@@ -4,22 +4,15 @@
  * sanitized modulus function that always returns in the range [0, d)
  * rather than (-d, 0] if v is negative
  */
-function mod(v, d) {
-    var out = v % d;
+export function mod(v: number, d: number) {
+    const out = v % d;
     return out < 0 ? out + d : out;
 }
 
 /**
  * sanitized modulus function that always returns in the range [-d/2, d/2]
  * rather than (-d, 0] if v is negative
  */
-function modHalf(v, d) {
-    return Math.abs(v) > (d / 2) ?
-        v - Math.round(v / d) * d :
-        v;
+export function modHalf(v: number, d: number) {
+    return Math.abs(v) > d / 2 ? v - Math.round(v / d) * d : v;
 }
-
-module.exports = {
-    mod: mod,
-    modHalf: modHalf
-};

src/lib/regex.ts

@@ -0,0 +1,21 @@
+'use strict';
+
+const NUMBER_REGEX = '([2-9]|[1-9][0-9]+)?';
+
+/**
+ * make a regex for matching counter ids/names ie xaxis, xaxis2, xaxis10...
+ *
+ * @param head: the head of the pattern, eg 'x' matches 'x', 'x2', 'x10' etc.
+ *      'xy' is a special case for cartesian subplots: it matches 'x2y3' etc
+ * @param tail: a fixed piece after the id
+ *      eg counterRegex('scene', '.annotations') for scene2.annotations etc.
+ * @param openEnded: if true, the string may continue past the match.
+ * @param matchBeginning: if false, the string may start before the match.
+ */
+export function counter(head: string, tail: string = '', openEnded: boolean, matchBeginning: boolean) {
+    const fullTail = tail + (openEnded ? '' : '$');
+    const startWithPrefix = matchBeginning === false ? '' : '^';
+    return head === 'xy'
+        ? new RegExp(startWithPrefix + 'x' + NUMBER_REGEX + 'y' + NUMBER_REGEX + fullTail)
+        : new RegExp(startWithPrefix + head + NUMBER_REGEX + fullTail);
+}

src/lib/sort_object_keys.ts

@@ -0,0 +1,7 @@
+'use strict';
+
+function sortObjectKeys(obj: Record<string, any>) {
+    return Object.keys(obj).sort();
+}
+
+export default sortObjectKeys;

src/plots/geo/layout_attributes.js

@@ -5,7 +5,7 @@ var domainAttrs = require('../domain').attributes;
 var dash = require('../../components/drawing/attributes').dash;
 var constants = require('./constants');
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 
 var geoAxesAttrs = {
     range: {

src/plots/map/constants.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 var arcgisSatHybrid = require('./styles/arcgis-sat-hybrid'); // https://github.com/___raw___/go2garret/maps/v1.0.0/LICENSE
 var arcgisSat = require('./styles/arcgis-sat');
 

src/plots/mapbox/constants.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 
 var requiredVersion = '1.13.4';
 

src/traces/scatter3d/attributes.js

@@ -11,7 +11,7 @@ var DASHES = require('../../constants/gl3d_dashes');
 var MARKER_SYMBOLS = require('../../constants/gl3d_markers');
 var extendFlat = require('../../lib/extend').extendFlat;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 
 var scatterLineAttrs = scatterAttrs.line;
 var scatterMarkerAttrs = scatterAttrs.marker;

src/traces/scattergl/attributes.js

@@ -7,7 +7,7 @@ var scatterAttrs = require('../scatter/attributes');
 var axisHoverFormat = require('../../plots/cartesian/axis_format_attributes').axisHoverFormat;
 var colorScaleAttrs = require('../../components/colorscale/attributes');
 
-var sortObjectKeys = require('../../lib/sort_object_keys');
+var sortObjectKeys = require('../../lib/sort_object_keys').default;
 var extendFlat = require('../../lib/extend').extendFlat;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 var DASHES = require('./constants').DASHES;

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

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;