Merge pull request #7984 from plotly/v4.0

chore: Add v4.0 changes to default branch

Author: camdecoster

.github/actions/setup-workspace/action.yml

@@ -1,17 +1,12 @@
 name: 'Setup Workspace'
 description: 'Setup Node.js, install dependencies, and download build artifacts'
 
-inputs:
-  node-version:
-    description: 'Node.js version to use'
-    default: '18'
-
 runs:
   using: 'composite'
   steps:
     - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
       with:
-        node-version: ${{ inputs.node-version }}
+        node-version-file: '.nvmrc'
         cache: 'npm'
 
     - name: Install dependencies

.github/workflows/ci.yml

@@ -14,9 +14,6 @@ concurrency:
   group: ci-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
-env:
-  NODE_VERSION: '18'
-
 jobs:
   detect-changes:
     runs-on: ubuntu-latest
@@ -60,7 +57,7 @@ jobs:
 
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Install dependencies
@@ -94,33 +91,33 @@ jobs:
       - uses: ./.github/actions/setup-workspace
       - uses: ./.github/actions/setup-chrome
 
-      - name: Run hover_label test in UTC timezone
+      - name: Run hover test in UTC timezone
         uses: ./.github/actions/run-xvfb
         env:
           TZ: 'UTC'
         with:
-          run: npm run test-jasmine hover_label
+          run: npm run test-jasmine hover
 
-      - name: Run hover_label test in Europe/Berlin timezone
+      - name: Run hover test in Europe/Berlin timezone
         uses: ./.github/actions/run-xvfb
         env:
           TZ: 'Europe/Berlin'
         with:
-          run: npm run test-jasmine hover_label
+          run: npm run test-jasmine hover
 
-      - name: Run hover_label test in Asia/Tokyo timezone
+      - name: Run hover test in Asia/Tokyo timezone
         uses: ./.github/actions/run-xvfb
         env:
           TZ: 'Asia/Tokyo'
         with:
-          run: npm run test-jasmine hover_label
+          run: npm run test-jasmine hover
 
-      - name: Run hover_label test in America/Toronto timezone
+      - name: Run hover test in America/Toronto timezone
         uses: ./.github/actions/run-xvfb
         env:
           TZ: 'America/Toronto'
         with:
-          run: npm run test-jasmine hover_label
+          run: npm run test-jasmine hover
 
   no-gl-jasmine:
     needs: install-and-cibuild
@@ -270,9 +267,9 @@ jobs:
           chrome-version: 'stable'
 
       - name: Run noCI tests
-        uses: coactions/setup-xvfb@b6b4fcfb9f5a895edadc3bc76318fae0ac17c8b3 # v1
+        uses: ./.github/actions/run-xvfb
         with:
-          run: ./tasks/noci_test.sh jasmine
+          run: npm run test-jasmine -- --tags=noCI,noCIdep --nowatch
 
   # ============================================================
   # Image baseline generation and comparison
@@ -579,6 +576,26 @@ jobs:
       - name: Run syntax tests on source files
         run: .github/scripts/test.sh source-syntax
 
+  typecheck:
+    needs: install-and-cibuild
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: ./.github/actions/setup-workspace
+
+      - name: Type-check TypeScript sources
+        run: npm run typecheck
+
+  generated-types-drift:
+    needs: install-and-cibuild
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: ./.github/actions/setup-workspace
+
+      - name: Verify generated types are in sync with schema
+        run: npm run schema-typegen-diff-check
+
   # ============================================================
   # Standalone jobs (no dependencies on install-and-cibuild)
   # ============================================================
@@ -593,7 +610,7 @@ jobs:
 
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Set up build environment
@@ -624,7 +641,7 @@ jobs:
 
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
-          node-version: ${{ env.NODE_VERSION }}
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Set up build environment

.github/workflows/publish-dist.yml

@@ -25,7 +25,7 @@ jobs:
 
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
-          node-version: '22.14.0'
+          node-version-file: '.nvmrc'
           cache: 'npm'
 
       - name: Set up build environment

.gitignore

@@ -7,6 +7,9 @@ build/*
 dist/*.LICENSE.txt
 dist/*.css
 
+# Ignore local dev mocks/baselines
+test/image/**/dev_*.*
+
 npm-debug.log*
 *.sublime*
 *~
@@ -16,3 +19,4 @@ tags
 !.github/
 !.gitignore
 !.npmignore
+!.nvmrc

.nvmrc

@@ -0,0 +1 @@
+22.23.0

CHANGELOG.md

@@ -9,6 +9,54 @@ To see all merged commits on the master branch that will be part of the next plo
 
 where X.Y.Z is the semver of most recent plotly.js release.
 
+## [4.0.0-rc.0] -- 2026-07-21
+
+### Added
+- Add `minscale`, `maxscale` geo plot attributes [[#7371](https://github.com/plotly/plotly.js/pull/7371)], with thanks to @mojoaxel for the contribution!
+- Enable TypeScript compatibility within the library and start exporting types [[#7680](https://github.com/plotly/plotly.js/pull/7680)]
+- Add `quiver` trace type to visualize vector fields using arrows [[#7710](https://github.com/plotly/plotly.js/pull/7710)], with thanks to @degzhaus for the contribution!
+- Use dashed markers in legend for shape traces with dash configured [[#7845](https://github.com/plotly/plotly.js/pull/7845)]
+- Add `sort` option to Sankey links and nodes [[#7873](https://github.com/plotly/plotly.js/pull/7873)], with thanks to @adamreeve for the contribution!
+- Add support for MathJax v4 [[#7898](https://github.com/plotly/plotly.js/pull/7898)]
+
+### Removed
+- **Breaking**: Remove `scattermapbox`, `choroplethmapbox`, `densitymapbox` trace types, the `mapbox` subplot, and the `mapboxAccessToken` config option [[#7860](https://github.com/plotly/plotly.js/pull/7860)]
+  - These traces have been deprecated since v3. Use the equivalent `*map` traces going forward.
+- **Breaking**: Drop support for MathJax v2 [[#7898](https://github.com/plotly/plotly.js/pull/7898)]
+  - MathJax v3 and v4 are now supported in plotly.js
+- Remove config attributes `showLink`, `linkText`, `sendData`, `showSources`, and `showEditInChartStudio`, as well as trace attribute `stream`, since all of these were associated with Chart Studio and are no longer needed [[#7812](https://github.com/plotly/plotly.js/pull/7812)]
+- Remove all `*src` attributes, as well as `layout.hidesources` attribute, from the schema [[#7829](https://github.com/plotly/plotly.js/pull/7829)]
+- Remove internal `trace._fullInput` property and other dead code related to the removed `transforms` feature. No user-facing changes expected [[#7834](https://github.com/plotly/plotly.js/pull/7834)]
+
+### Changed
+- **Breaking**: Switch color processing library from [TinyColor](https://github.com/bgrins/TinyColor) to [color](https://github.com/Qix-/color) [[#7536](https://github.com/plotly/plotly.js/pull/7536)]
+  - `rgb()`/`rgba()` strings with decimal 0–1 fractions are no longer supported
+  - `hsv()` color strings are no longer permitted
+  - Color calculations may differ slightly (by a few RGB units)
+  - New color formats are now supported: '#ff0000aa', '#f00a', 'rgb(255 0 0)', 'rgba(255 0 0 / 0.5)', 'hsl(0 100% 50% / 0.5)', 'hsla(0, 100%, 50%, 0.5)', 'hwb(0, 0%, 0%)' 
+ - **Breaking**: Set default `layout.axis.tickmode` to `'sync'` when axis is overlaying [[#7684](https://github.com/plotly/plotly.js/pull/7684)]
+- **Breaking**: Change `splom.axis.matches` default from `false` to `true` [[#7843](https://github.com/plotly/plotly.js/pull/7843)]
+- **Breaking**: Replace `country-regex` with `country-iso-search` to search for country names in choropleth, scattergeo traces [[#7856](https://github.com/plotly/plotly.js/pull/7856)]
+  - The vast majority of country names are handled exactly the same with the new library; a small number of legacy entries have been removed
+- **Breaking**: Update minimum required Node version to 22 [[#7861](https://github.com/plotly/plotly.js/pull/7861)]
+- **Breaking:** Change `layout.geo.fitbounds` default from `false` to `'locations'` [[#7895](https://github.com/plotly/plotly.js/pull/7895)]
+  - `geo` subplots will now auto-fit the initial view to the trace data 
+  - Set `fitbounds: false` explicitly to opt out
+- Enable `scattermap` icons to render in color, upgrade Maki icons version to 8.2, and standardize scattermap legend icons to circles [[#7825](https://github.com/plotly/plotly.js/pull/7825)]
+- Use plot title as default filename for "Download plot" button [[#7828](https://github.com/plotly/plotly.js/pull/7828)]
+- Change signature of `plots.graphJson()` function to remove `mode` argument [[#7829](https://github.com/plotly/plotly.js/pull/7829)]
+- Upgrade `plotly/d3-sankey` to 0.12.3. [[#7830](https://github.com/plotly/plotly.js/pull/7830)], with thanks to @adamreeve for the contribution!
+- Update `plot_config` to show the "Upload to Cloud" button by default, and set the default server URL to cloud.plotly.com via [[#7909](https://github.com/plotly/plotly.js/pull/7909)]
+
+### Fixed
+- Fix `histogram` autobin size for single-point traces in `overlay` mode on data updates via `Plotly.react` [[#7507](https://github.com/plotly/plotly.js/pull/7507)], with thanks to @Lexachoc for the contribution!
+ - Format tick labels correctly for small numbers in exponential notation [[#7768](https://github.com/plotly/plotly.js/pull/7768)], with thanks to @Hasnaathussain for the contribution!
+- Fix crash when ordering categories by value (e.g. `sum descending`) with `null` coordinates [[#7855](https://github.com/plotly/plotly.js/pull/7855)]
+ - Fix `scattermap`, `densitymap` traces not showing all points by dynamically computing `center`, `zoom` values [[#7884](https://github.com/plotly/plotly.js/pull/7884), [#7913](https://github.com/plotly/plotly.js/pull/7913)], with thanks to @palmerusaf and @DhruvGarg111 for the contributions!
+ - Fix GeoJSON bounding-box computation for `choropleth` and `scattergeo` traces whose geometry crosses the antimeridian [[#7891](https://github.com/plotly/plotly.js/pull/7891)]
+- Snap cartesian axis tick values to multiple of delta so custom `tickformat` (e.g. `"~r"`) no longer shows floating-point artifacts [[#7901](https://github.com/plotly/plotly.js/pull/7901)], with thanks to @arieleli01212 and @kirthi-b for the contribution!
+
+
 ## [3.7.0] -- 2026-07-03
 
 ### Changed

CONTRIBUTING.md

@@ -78,7 +78,7 @@ We use the following [labels](https://github.com/plotly/plotly.js/labels) to tra
 #### Prerequisites
 
 - git
-- [node.js](https://nodejs.org/en/). We recommend using node.js v18.x.
+- [node.js](https://nodejs.org/en/). We recommend using node.js v22.x.
   Upgrading and managing node versions can be easily done using
   [`nvm`](https://github.com/nvm-sh/nvm) or its Windows alternatives.
 - [`npm`](https://www.npmjs.com/) v10.x and up to ensure that the
@@ -405,8 +405,10 @@ All traces modules set:
   This object is used to generate the plot-schema JSON.
 - `_module.supplyDefaults`: Takes in input trace settings and coerces them into "full" settings
   under `gd._fullData`. This one is called during the figure-wide `Plots.supplyDefaults` routine.
-  Note that the `supplyDefaults` method performance should scale with the number of attributes (**not** the
-  number of data points - so it should not loop over any data arrays).
+  As a rule, `supplyDefaults` performance should scale with the number of attributes rather than
+  the number of data points, so avoid looping over data arrays in this function. That being said,
+  there are a few exceptions to this rule due to technical requirements (`fitbounds` on map subplots).
+  The same guidance applies to `_module.supplyLayoutDefaults`.
 - `_module.calc`: Converts inputs data into "calculated" (or sanitized) data. This one is called during
   the figure-wide `Plots.doCalcdata` routine. The `calc` method is allowed to
   scale with the number of data points and is in general more costly than `supplyDefaults`.
@@ -432,7 +434,7 @@ Other methods used by some trace modules:
   selections.
 - `_module.convert`: Sometimes separated from `_module.plot` or `_module.calc` to convert the
   plotly.js settings to another framework e.g. to `gl-plot3d` for `gl3d` traces, to
-  `mapbox-gl` for `mapbox` traces. This split can make the logic easier to test.
+  `maplibre-gl` for `map` traces. This split can make the logic easier to test.
   If you make a `convert`, you should call it from either `calc` or `plot`.
 
 ## Coding style

CUSTOM_BUNDLE.md

@@ -5,8 +5,9 @@ Make sure you have the versions of node/npm that's recommended:
 - plotly.js before 2.5: Node 12/npm 6
 - plotly.js from 2.5: Node 16/npm 8
 - plotly.js from 2.35: Node 18/npm 10
+- plotly.js from 4.0: Node 22/npm 10
 
-To download a specific node version look [here](https://nodejs.org/en/download/package-manager).
+To download a specific node version look [here](https://nodejs.org/en/download).
 
 Note: For CI, it's faster to do `git clone --depth 1` to only get one commit.
 

README.md

@@ -95,17 +95,23 @@ While non-minified source files may contain characters outside UTF-8, it is reco
 > Please note that as of v2 the "plotly-latest" outputs (e.g. https://cdn.plot.ly/plotly-latest.min.js) will no longer be updated on the CDN, and will stay at the last v1 patch v1.58.5. Therefore, to use the CDN with plotly.js v2 and higher, you must specify an exact plotly.js version.
 
 ### MathJax
-You can load either version two or version three of MathJax files. For example:
+plotly.js supports using MathJax v3 or v4 to render mathematical expressions within plots.
+
+MathJax is not included in the plotly.js bundle, so it must be loaded separately as a script on the webpage.
+
+For MathJax v4:
 ```html
-<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-AMS-MML_SVG.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/mathjax@4.1.3/tex-svg.js"></script>
 ```
 
+For MathJax v3:
 ```html
 <script src="https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js"></script>
 ```
 
-> When using MathJax version 3, it is also possible to use `chtml` output on the other parts of the page in addition to `svg` output for the plotly graph.
-Please refer to `devtools/test_dashboard/index-mathjax3chtml.html` to see an example.
+When MathJax is available, any string contained within `$..$` signs will be rendered using the MathJax engine. This applies to plot titles, axis labels, tick label text, and annotations.
+
+plotly.js's use of the MathJax `svg` renderer should not prevent using other MathJax renderers elsewhere on the page, nor will it affect the global MathJax config. See `devtools/test_dashboard/index-mathjax3chtml.html` for an example of a webpage which uses the MathJax `chtml` renderer in the main page, and also displays Plotly charts containing MathJax equations rendered as `svg`.
 
 ### Need to have several WebGL graphs on a page?
 You may simply load the [virtual-webgl](https://github.com/greggman/virtual-webgl) script for WebGL 1 (not WebGL 2) before loading other scripts.

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.0/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.5/schema.json",
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "files": {
     "maxSize": 10000000,
@@ -17,6 +17,7 @@
       "!**/stackgl_modules",
       "!**/node_modules",
       "!**/build",
+      "!**/.venv/**",
       "!**/tasks/test_amdefine.js",
       "!**/tasks/test_requirejs.js",
       "!**/test/jasmine/assets/jquery-1.8.3.min.js"
@@ -25,9 +26,9 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": false,
+      "preset": "none",
       "complexity": {
-        "noExtraBooleanCast": "error",
+        "noExtraBooleanCast": "off",
         "noUselessCatch": "error",
         "useLiteralKeys": "error",
         "noAdjacentSpacesInRegex": "error"