Prepare public v6.1.0

.github/pull_request_template.md

@@ -53,6 +53,12 @@ One of the following should be checked.
 
 ## Misc
 
+### Security Checking
+
+- [ ] This PR uses security-sensitive Web APIs.
+
+<!-- PLEASE CHECK IT AGAINST: <https://github.com/apache/echarts/wiki/Security-Checklist-for-Code-Contributors> -->
+
 ### ZRender Changes
 
 - [ ] This PR depends on ZRender changes (ecomfe/zrender#xxx).
@@ -61,10 +67,6 @@ One of the following should be checked.
 
 N.A.
 
-
-
-## Others
-
 ### Merging options
 
 - [ ] Please squash the commits into a single one when merging.

.github/workflows/ci.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Collect changed files
         run: |
           mkdir ~/tmp/
-          git diff ${{ github.event.pull_request.base.sha }} ${{ github.sha }} --diff-filter=ACM --name-only --relative '*src/**/*.ts' > ~/tmp/changed_files
+          git diff ${{ github.event.pull_request.base.sha }} ${{ github.sha }} --diff-filter=ACM --name-only --relative '*src/*.ts' '*src/**/*.ts' > ~/tmp/changed_files
           echo -e "Changed files: \n$(cat ~/tmp/changed_files)"
 
       - name: Lint

.gitignore

@@ -171,6 +171,9 @@ node_modules
 
 test/data/map/tool
 test/data/map/raw
+
+/test/types/package-lock.json
+
 theme/thumb
 pre-publish-tmp
 todo

.husky/pre-commit

@@ -3,4 +3,3 @@
 
 npm run lint
 npm run checktype
-npm run checkheader

build/pre-publish.js

@@ -239,7 +239,7 @@ async function runTsCompile(localTs, compilerOptions, srcPathList) {
         }
     });
     if (allDiagnostics.length > 0) {
-        throw new Error('TypeScript Compile Failed')
+        throw new Error('TypeScript Compile Failed');
     }
 }
 module.exports.runTsCompile = runTsCompile;
@@ -378,32 +378,43 @@ async function readFilePaths({patterns, cwd}) {
 async function bundleDTS() {
 
     const outDir = nodePath.resolve(__dirname, '../types/dist');
-    const commonConfig = {
-        onwarn(warning, rollupWarn) {
-            // Not warn circular dependency
-            if (warning.code !== 'CIRCULAR_DEPENDENCY') {
-                rollupWarn(warning);
-            }
-        },
-        plugins: [
-            dts({
-                respectExternal: true
-            })
-//             {
-//                 generateBundle(options, bundle) {
-//                     for (let chunk of Object.values(bundle)) {
-//                         chunk.code = `
-// type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
-// ${chunk.code}`
-//                     }
-//                 }
-//             }
-        ]
-    };
+
+    function createCommonConfig(opt) {
+        return {
+            onwarn(warning, rollupWarn) {
+                // Not warn circular dependency
+                if (warning.code !== 'CIRCULAR_DEPENDENCY') {
+                    rollupWarn(warning);
+                }
+            },
+            plugins: [
+                dts({
+                    respectExternal: true,
+                    // - `package.json` `{"type": "module"}` requires explicit file extensions in
+                    //  imports; otherwise `tsc` reports error TS(2834).
+                    // - When importing a `.d.ts`, a proper solution can be
+                    //  `import {xxx} from "./yyy.js"` instead of `from "./yyy.d.ts"`; otherwise
+                    //  `tsc` reports error TS(2846).
+                    // Use `explicitFileExtension: "js"` to use `.js` as the extension of a import paths.
+                    explicitFileExtension: 'js',
+                    umdExportName: opt.umdExportName,
+                })
+    //             {
+    //                 generateBundle(options, bundle) {
+    //                     for (let chunk of Object.values(bundle)) {
+    //                         chunk.code = `
+    // type Omit<T, K> = Pick<T, Exclude<keyof T, K>>;
+    // ${chunk.code}`
+    //                     }
+    //                 }
+    //             }
+            ]
+        };
+    }
 
     // Bundle chunks.
     const parts = [
-        'core', 'charts', 'components', 'renderers', 'option', 'features'
+        'all', 'core', 'charts', 'components', 'renderers', 'option', 'features'
     ];
     const inputs = {};
     parts.forEach(partName => {
@@ -412,27 +423,39 @@ async function bundleDTS() {
 
     const bundle = await rollup.rollup({
         input: inputs,
-        ...commonConfig
+        ...createCommonConfig({})
     });
-    let idx = 1;
     await bundle.write({
         dir: outDir,
         minifyInternalExports: false,
         manualChunks: (id) => {
-            // Only create one chunk.
+            // Only create one chunk. All of the public entries should import from 'shared.d.ts';
+            // otherwise TS error 2442 (Types have separate declarations of a private property)
+            // may occur.
             return 'shared';
         },
         chunkFileNames: 'shared.d.ts'
     });
 
-    // Bundle all in one
-    const bundleAllInOne = await rollup.rollup({
+    // Bundle a single, self-contained ESM `echarts/types/dist/echarts.d.ts` with no imports,
+    // for online type checkers (e.g., echarts-examples) usage.
+    const bundleStandaloneESM = await rollup.rollup({
         input: nodePath.resolve(__dirname, `../types/src/export/all.d.ts`),
-        ...commonConfig
+        ...createCommonConfig({})
     });
-    await bundleAllInOne.write({
+    await bundleStandaloneESM.write({
         file: nodePath.resolve(outDir, 'echarts.d.ts')
     });
+
+    // Bundle a UMD `echarts/types/dist/echarts.d.cts`.
+    // See section "TypeScript entries" in `echarts/package.README.md` for more details.
+    const bundleStandaloneCJS = await rollup.rollup({
+        input: nodePath.resolve(__dirname, `../types/src/export/all.d.ts`),
+        ...createCommonConfig({umdExportName: 'echarts'})
+    });
+    await bundleStandaloneCJS.write({
+        file: nodePath.resolve(outDir, 'echarts.d.cts')
+    });
 }
 
 function readTSConfig() {
@@ -451,8 +474,9 @@ function generateEntries() {
             fs.writeFileSync(nodePath.join(__dirname, `../${entryPath}.js`), jsCode, 'utf-8');
         }
 
-        // Make the d.ts in the same dir as .js, so that the can be found by tsc.
-        // package.json "types" in "exports" does not always seam to work.
+        // Create xxx.d.ts in the same dir with xxx.js, so that they can be found by `tsc`.
+        // This way is more reliable than using "types" field in `package.json` "exports"
+        // considering older versions of `tsc`.
         const dtsCode = fs.readFileSync(nodePath.join(__dirname, `/template/${entryPath}.d.ts`), 'utf-8');
         fs.writeFileSync(nodePath.join(__dirname, `../${entryPath}.d.ts`), dtsCode, 'utf-8');
     });

build/template/charts.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/charts';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/charts.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/components.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/components';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/components.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/core.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/core';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/core.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/features.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/features';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/features.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/option.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/option';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/option.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/renderers.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/dist/renderers';
+// A pseudo `.js` to redirect to `.d.ts`.
+export * from './types/dist/renderers.js';
+// See section "TypeScript entries" in `echarts/package.README.md` for more details.

build/template/ssr/client/index.d.ts

@@ -17,4 +17,6 @@
 * under the License.
 */
 
-export * from './types/index';
+// A pseudo `.js` to redirect to `.d.ts`.
+// See `package.README.json` for more details.
+export * from './types/index.js';

build/testDts.js

@@ -34,30 +34,113 @@ async function installTs() {
 }
 
 async function runTests() {
-    const compilerOptions = {
-        declaration: false,
-        importHelpers: false,
-        sourceMap: false,
-        pretty: false,
-        removeComments: false,
-        allowJs: false,
-        outDir: __dirname + '/../test/types/tmp',
-        typeRoots: [__dirname + '/../types/dist'],
-        rootDir: __dirname + '/../test/types',
-
-        // Must pass in most strict cases
-        strict: true
-    };
-    const testsList = await globby(__dirname + '/../test/types/*.ts');
+    const casesESM = await globby(__dirname + '/../test/types/esm/*.ts');
+    const casesCJS = await globby(__dirname + '/../test/types/cjs/*.ts');
+    const casesNoModule = await globby(__dirname + '/../test/types/no-module/*.ts');
 
     const tsVersions = getTypeScriptVersions();
+
+    function createCompilerOptions(overrideOptions) {
+        return {
+            declaration: false,
+            importHelpers: false,
+            sourceMap: false,
+            pretty: false,
+            removeComments: false,
+            allowJs: false,
+            rootDir: __dirname + '/../test/types',
+            outDir: __dirname + '/../test/types/tmp',
+            // Disable global types, necessary to avoid other
+            // irrelevant node_modules types interference.
+            typeRoots: [],
+            // Must pass in most strict cases
+            strict: true,
+            ...overrideOptions
+        };
+    };
+
+    async function singleTest(ts, tsVersion, tsconfigModule, tsconfigModuleResolution, testList) {
+        if (!isSupportedTSConfigModuleField(ts, tsconfigModule)) {
+            console.log(`Skip: tsVersion: ${tsVersion} does not support {"module": "${tsconfigModule}"}.`);
+            return;
+        }
+        if (!isSupportedTSConfigModuleResolutionField(ts, tsVersion, tsconfigModuleResolution)) {
+            console.log(`Skip: tsVersion: ${tsVersion} does not support {"moduleResolution": "${tsconfigModuleResolution}"}.`);
+            return;
+        }
+
+        console.log(`Testing: tsVersion: ${tsVersion}, tsconfig: {"module": "${tsconfigModule}", "moduleResolution": "${tsconfigModuleResolution}"}`);
+        await runTsCompile(ts, createCompilerOptions({
+            // noEmit: true,
+            module: tsconfigModule,
+            moduleResolution: tsconfigModuleResolution,
+        }), testList);
+    }
+
     for (const version of tsVersions) {
-        console.log(`Testing ts version ${version}`);
         const ts = require(typeScriptPath(version));
-        await runTsCompile(ts, compilerOptions, testsList);
 
-        console.log(`Finished test of ts version ${version}`);
+        // console.log(ts.ModuleKind);
+        // console.log(ts.ModuleResolutionKind);
+
+        // await singleTest(ts, version, undefined , undefined, casesESM);
+        // await singleTest(ts, version, 'None', 'classic', casesNoModule);
+        // await singleTest(ts, version, 'CommonJS', 'node', casesESM);
+        // await singleTest(ts, version, 'CommonJS', 'node', casesCJS);
+        // await singleTest(ts, version, 'ESNext', 'node', casesESM);
+        // await singleTest(ts, version, 'ESNext', 'Bundler', casesESM);
+        await singleTest(ts, version, 'NodeNext', 'NodeNext', casesESM);
+        // await singleTest(ts, version, 'NodeNext', 'NodeNext', casesCJS);
+
+        console.log(`Finished test of tsVersion ${version}`);
+    }
+}
+
+function isSupportedTSConfigModuleField(ts, moduleName) {
+    if (moduleName === undefined) {
+        return true;
+    }
+    const map = {
+        'none': 'None',
+        'commonjs': 'CommonJS',
+        'amd': 'AMD',
+        'umd': 'UMD',
+        'system': 'System',
+        'es6': 'ES2015',
+        'es2015': 'ES2015',
+        'es2020': 'ES2020',
+        'es2022': 'ES2022',
+        'esnext': 'ESNext',
+        'node16': 'Node16',
+        'nodenext': 'NodeNext',
+    };
+    const enumKey = map[moduleName.toLowerCase()];
+    return enumKey != null && ts.ModuleKind[enumKey] != null;
+}
+
+function isSupportedTSConfigModuleResolutionField(ts, tsVersion, moduleResolutionName) {
+    if (moduleResolutionName === undefined) {
+        return true;
     }
+    const map = {
+        'classic': 'Classic',
+        'node': 'NodeJs',
+        // 'nodejs': 'NodeJs', // Older TS do not support value "nodejs".
+        'node10': 'Node10',
+        'node16': 'Node16',
+        'nodenext': 'NodeNext',
+        'bundler': 'Bundler',
+    };
+    const enumKey = map[moduleResolutionName.toLowerCase()];
+
+    if (enumKey === 'NodeNext') {
+        // "NodeNext" is unstable before TSv4.7, and error will be thrown.
+        if (semver.lt(tsVersion + '.0', '4.7.0')) {
+            return false;
+        }
+    }
+
+    return enumKey != null && ts.ModuleResolutionKind[enumKey] != null;
 }
 
 function getTypeScriptVersions() {

index.d.ts

@@ -17,7 +17,18 @@
 * under the License.
 */
 
+/**
+ * @deprecated
+ * Temporarily retain it in case users reference it like this:
+ *  ```ts
+ *  /// <reference path="../node_modules/echarts/index.d.ts" />
+ *  var myChart = echarts.init(...);
+ *  ```
+ *
+ * See section "TypeScript entries" in `echarts/package.README.md` for more details.
+ */
+
 import * as echarts from './types/dist/echarts';
 // Export for UMD module.
 export as namespace echarts;
-export = echarts;
+export = echarts;