TypeScript type defintions docs for website

Author: slowcheetah

docs/web/docs/features/web-standards/base64-utility-methods.md

@@ -12,11 +12,14 @@ function btoa(data: string): string;
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```ts
+```plaintext
 core-js(-pure)/stable|actual|full/atob
 core-js(-pure)/stable|actual|full/btoa
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/web/atob-btoa`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/atob-btoa.d.ts)
+
 ## Examples
 ```js
 btoa('hi, core-js');      // => 'aGksIGNvcmUtanM='

docs/web/docs/features/web-standards/iterable-dom-collections.md

@@ -50,14 +50,17 @@ class [DOMTokenList, NodeList] {
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```
+```plaintext
 core-js(-pure)/stable|actual|full/dom-collections/iterator
 core-js/stable|actual|full/dom-collections/entries
 core-js/stable|actual|full/dom-collections/keys
 core-js/stable|actual|full/dom-collections/values
 core-js/stable|actual|full/dom-collections/for-each
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/web/iterable-dom-collections`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/iterable-dom-collections.d.ts)
+
 ## Examples
 ```js
 for (let { id } of document.querySelectorAll('*')) {

docs/web/docs/features/web-standards/queuemicrotask.md

@@ -10,10 +10,13 @@ function queueMicrotask(fn: Function): void;
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```ts
+```plaintext
 core-js(-pure)/stable|actual|full/queue-microtask
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/web/queue-microtask`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/queue-microtask.d.ts)
+
 ## Example
 ```js
 queueMicrotask(() => console.log('called as microtask'));

docs/web/docs/features/web-standards/setimmediate.md

@@ -10,11 +10,14 @@ function clearImmediate(id: number): void;
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```ts
+```plaintext
 core-js(-pure)/stable|actual|full/set-immediate
 core-js(-pure)/stable|actual|full/clear-immediate
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/web/efficient-script-yielding`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/efficient-script-yielding.d.ts)
+
 ## Examples
 ```js
 setImmediate((arg1, arg2) => {

docs/web/docs/features/web-standards/structured-clone.md

@@ -10,8 +10,11 @@ function structuredClone(value: Serializable, { transfer?: Sequence<Transferable
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```ts
-core-js(-pure)/stable|actual|full/structured-clone
+[`@core-js/types/web/structured-clone`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/structured-clone.d.ts)
+
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+```plaintext
+@core-js/types/web/structured-clone
 ```
 
 ## Examples

docs/web/docs/features/web-standards/url-and-urlsearchparams.md

@@ -46,14 +46,17 @@ class URLSearchParams {
 ```
 
 ## [Entry points]({docs-version}/docs/usage#h-entry-points)
-```ts
+```plaintext
 core-js/proposals/url
 core-js(-pure)/stable|actual|full/url
 core-js(-pure)/stable|actual|full/url/can-parse
 core-js/stable|actual|full/url/to-json
 core-js(-pure)/stable|actual|full/url-search-params
 ```
 
+## [TypeScript type definitions]({docs-version}/docs/typescript-type-definitions)
+[`@core-js/types/web/url-to-json`](https://github.com/zloirock/core-js/blob/v4-types/packages/core-js-types/src/base/web/url-to-json.d.ts)
+
 ## Examples
 ```js
 URL.canParse('https://login:[email protected]:8080/?a=1&b=2&a=3&c=4#fragment'); // => true

docs/web/docs/menu.json

@@ -7,6 +7,10 @@
     "title": "Supported engines and compatibility data",
     "url": "{docs-version}/docs/engines"
   },
+  {
+    "title": "TypeScript type definitions",
+    "url": "{docs-version}/docs/typescript-type-definitions"
+  },
   {
     "title": "Features",
     "children": [

docs/web/docs/typescript-type-definitions.md

@@ -0,0 +1,115 @@
+# TypeScript Type Definitions
+
+This package contains types for the global and pure versions of `core-js`.
+Although `core-js` is a JavaScript standard library polyfill, the built-in TypeScript types are often not sufficient.
+Additional types are needed for:
+- features that are already in JavaScript but not yet in TypeScript’s standard types;
+- proposals, including those already implemented in JavaScript engines;
+- explicit imports of features from the pure version.
+
+It is shipped as a separate package because we cannot guarantee stable behavior with future TypeScript releases, including minor ones.
+
+## Installation
+```sh
+npm install --save @core-js/[email protected]
+```
+
+## Usage
+Add to your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@core-js/types"
+    ]
+  }
+}
+```
+or import it directly in your files:
+```ts
+import '@core-js/types';
+```
+`@core-js/types` includes all types and entry points for the global version, but it is recommended to select only the subset you actually use.
+
+### Usage of subsets
+There are four main subsets:
+- `@core-js/types/actual` - types for all actual features, including stable ECMAScript, web standards and Stage 3 ECMAScript proposals;
+- `@core-js/types/es` - types for stable ECMAScript features only;
+- `@core-js/types/stable` - types for stable ECMAScript and web standards features;
+- `@core-js/types/full` - types for all features, including proposals.
+
+You can import them the same way as the main package. For example, to use only the stable subset, add this to your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@core-js/types/stable"
+    ]
+  }
+}
+```
+or import it directly in your files:
+```ts
+import '@core-js/types/stable';
+```
+
+### Usage of specific features
+If you need types only for specific features, you can import them like this:
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@core-js/types/proposals/joint-iteration",
+      "@core-js/types/web/structured-clone"
+    ]
+  }
+}
+```
+or import them directly in your files:
+```ts
+import '@core-js/types/proposals/joint-iteration';
+import '@core-js/types/web/structured-clone';
+```
+You can find types for specific features on the corresponding pages in the [documentation](https://core-js.io/{docs-version}/docs/).
+
+## Types for the pure version
+### Base usage
+Add this to your `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "types": [
+      "@core-js/types/pure"
+    ]
+  }
+}
+```
+Then, when you import from the pure entry points, the corresponding types are picked up automatically:
+```ts
+import $findLast from '@core-js/pure/full/array/find-last';
+
+$findLast([1, 3, 4, 2], v => v > 2); // => 4
+```
+
+### Namespace usage in the pure version
+If you need to use multiple methods from the same namespace, you can add `@core-js/types/pure` to `tsconfig.json` and import the entire namespace:
+```ts
+import $array from '@core-js/pure/full/array';
+
+$array.findLast([1, 3, 4, 2], v => v > 2);
+$array.flatMap([1, 2, 3], x => [x, x * 2]);
+```
+(note that this is not recommended since tree shaking does not properly work in this case)
+
+## DOM types
+Some of the global types for web standards work correctly only with the DOM lib.
+You need to add DOM types to the `lib` section of your `tsconfig.json` in addition to `@core-js/types`. For example:
+```json
+{
+  "compilerOptions": {
+    "types": ["@core-js/types"],
+    "lib": ["esnext", "dom"]
+  }
+}
+```
+In the pure version, you can use these types without adding the DOM lib.

website/src/js/main.js

@@ -4,12 +4,14 @@ import javascript from 'highlight.js/lib/languages/javascript';
 import typescript from 'highlight.js/lib/languages/typescript';
 import json from 'highlight.js/lib/languages/json';
 import bash from 'highlight.js/lib/languages/bash';
+import plaintext from 'highlight.js/lib/languages/plaintext';
 import RunButtonPlugin from './hljs-run.js';
 
 hljs.registerLanguage('js', javascript);
 hljs.registerLanguage('ts', typescript);
 hljs.registerLanguage('json', json);
 hljs.registerLanguage('sh', bash);
+hljs.registerLanguage('plaintext', plaintext);
 
 let initialized = false;
 function init() {