diff --git a/README.fr.md b/README.fr.md
index bd511172749c99..ab3df440cd3e0e 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -2,37 +2,49 @@
> Le référentiel des définitions de type TypeScript de _haute qualité_.
-_Vous pouvez également lire ce README en [Español](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.es.md), [한국어](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ko.md), [Русский](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ru.md), [简体中文](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.zh-Hans.md), [Português](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.pt.md), [Italiano](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.it.md), [日本語](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ja.md) et [Français](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.fr.md)!_
+_Vous pouvez également lire ce README en [Español](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.es.md), [한국어](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ko.md), [Русский](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ru.md), [简体中文](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.zh-Hans.md), [Português](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.pt.md), [Italiano](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.it.md), [日本語](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.ja.md) et [English](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.md)!_
_Lien vers le [Manuel de l'administrateur](./docs/admin.md)_
+## !!! Important ! Ce dépôt a récemment changé de structure ! !!!
+
+Definitely Typed est récemment passé sur un véritable monorepo `pnpm`; vous voudriez peut-être relire ce document pour connaître les changements apportés à la structure des packages dans ce dépôt.
+
+Au minimum, vous voudriez peut-être faire un `git clean -fdx` sur le dépôt (ou `node ./scripts/clean-node-modules.js` sur Windows) pour nettoyer `node_modules` et exécuter `pnpm install --filter .` pour installer la racine du workspace. Voir les sections suivantes pour plus d'informations sur `pnpm install`.
+
## État actuel
Cette section permet de suivre l'état de santé du référentiel et du processus de publication.
-Elle peut être utile aux contributeurs qui rencontrent des problèmes avec leurs PR et leurs paquets.
+Elle peut être utile aux contributeurs qui rencontrent des problèmes avec leurs PR et leurs packages.
-- Dernière version [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) proprement: [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=1&branchName=master)
-- Tous les paquets font l'objet d'une vérification de type et d'un marquage propre sur typescript@next: [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=8)
-- Tous les paquets en cours de [Publication sur npm](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) en moins d'une heure et demie : [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=5&branchName=master)
-- [typescript-bot](https://github.com/typescript-bot) a été actif sur Definitely Typed [](https://dev.azure.com/definitelytyped/DefinitelyTyped/_build/latest?definitionId=6&branchName=master)
-- Actuel [mise à jour de l'état de l'infrastructure](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/44317)
+- Dernière version [type-checked/linted](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) proprement : [](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Apush)
+- Tous les packages passent la vérification des types et du linter : [](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/CI.yml?query=branch%3Amaster+event%3Aschedule)
+- Tous les packages ont été [publié sur npm](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) en moins d'une heure et demie : [](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/watchdog-publisher.yml)
+- [typescript-bot](https://github.com/typescript-bot) a été actif sur Definitely Typed [](https://github.com/DefinitelyTyped/DefinitelyTyped/actions/workflows/watchdog-typescript-bot.yml)
+- [Mise à jour de l'état de l'infrastructure](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/44317) actuel
-Si quelque chose ne semble pas fonctionner, ou si l'un des éléments ci-dessus échoue, merci de nous le faire savoir dans [le canal Definitely Typed sur le serveur Discord de la Communauté TypeScript](https://discord.gg/typescript).
+Si quelque chose semble incorrect ou si l'un des éléments ci-dessus échoue, merci de nous le faire savoir dans [le canal Definitely Typed sur le serveur Discord de la Communauté TypeScript](https://discord.gg/typescript).
-## Qu'est-ce qu'un fichier de déclaration et comment puis-je l'obtenir ?
+## Que sont les fichiers de déclaration et comment les obtenir ?
Voir le [Manuel TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html).
### npm
-C'est la méthode préférée. Par exemple :
+C'est la méthode privilégiée. Par exemple :
```sh
npm install --save-dev @types/node
```
+Pour installer des types d'un module scopé, remplacez le `@` par deux underscore après le scope. Par exemple, pour installer des types pour `@babel/preset-env` :
+
+```sh
+npm install --save-dev @types/babel__preset-env
+```
+
Les types devraient alors être automatiquement inclus par le compilateur.
-Vous pouvez avoir besoin d'ajouter une référence `types` si vous n'utilisez pas de modules :
+Vous pourriez avoir besoin d'ajouter une référence `types` si vous n'utilisez pas de modules :
```ts
///
@@ -40,17 +52,17 @@ Vous pouvez avoir besoin d'ajouter une référence `types` si vous n'utilisez pa
Plus d'informations dans le [manuel](https://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html).
-Pour un paquet npm "foo", les typages pour celui-ci seront à "@types/foo"..
+Pour un package npm "foo", les types pour celui-ci seront dans "@types/foo".
-Si votre paquet a des typages spécifiés en utilisant la clé `types` ou `typings` dans son `package.json`, le registre npm affichera que le paquet a des bindings disponibles comme ceci :
+Si votre package spécifie des types avec la clé `types` ou `typings` dans son `package.json`, le registre npm affichera que le package a des bindings disponibles comme ceci :
-Si vous ne trouvez toujours pas les typages, recherchez simplement les fichiers ".d.ts" dans le paquet et incluez-les manuellement avec une commande `/// `.
+Si vous ne trouvez toujours pas les types, recherchez simplement les fichiers ".d.ts" dans le package et incluez-les manuellement avec `/// `.
### Support de version
-Definitely Typed ne teste que les paquets sur des versions de TypeScript datant de moins de 2 ans.
+Definitely Typed ne teste que les packages sur des versions de TypeScript datant de moins de 2 ans.
@@ -58,7 +70,7 @@ Definitely Typed ne teste que les paquets sur des versions de TypeScript datant
Anciennes versions de TypeScript
-Les paquets `@types` ont des étiquettes pour les versions de TypeScript qu'ils supportent explicitement, de sorte que vous pouvez généralement obtenir des versions plus anciennes de paquets qui précèdent la fenêtre de 2 ans.
+Les packages `@types` ont des tags pour les versions de TypeScript qu'ils supportent explicitement, de sorte que vous pouvez généralement obtenir des versions plus anciennes des packages qui précèdent la fenêtre de 2 ans.
Par exemple, si vous lancez `npm dist-tags @types/react`, vous verrez que TypeScript 2.5 peut utiliser les types pour react@16.0, alors que TypeScript 2.6 et 2.7 peuvent utiliser les types pour react@16.4 :
| Tag | Version |
@@ -77,7 +89,7 @@ Par exemple, si vous lancez `npm dist-tags @types/react`, vous verrez que TypeSc
- ~~[Typings](https://github.com/typings/typings)~~ (utilisez les alternatives préférées, typings est déprécié)
- ~~[NuGet](https://nuget.org/packages?q=DefinitelyTyped)~~ (utilisez les alternatives préférées, la publication des types DT de Nuget a été désactivée)
-Vous pouvez avoir besoin d'ajouter le manuel [references](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html).
+Vous pourriez avoir besoin d'ajouter le manuel [references](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html).
@@ -96,13 +108,13 @@ declare module "libname" {
}
```
-#### Test d'édition d'un paquet existant
+#### Test d'édition d'un package existant
Vous pouvez éditer les types directement dans `node_modules/@types/foo/index.d.ts` pour valider vos changements, puis apporter les changements à ce repo avec les étapes ci-dessous.
Alternativement, vous pouvez utiliser [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) pour étendre les types existants du module DT ou utiliser la technique `declare module` ci-dessus qui remplacera la version dans `node_modules`.
-#### Ajouter des tests à un nouveau paquet
+#### Ajouter des tests à un nouveau package
Ajoutez-le à votre `tsconfig.json` :
@@ -115,128 +127,208 @@ Créez `types/foo/index.d.ts` contenant les déclarations pour le module "foo".
Vous devriez maintenant être capable d'importer `"foo"` dans votre code et il sera dirigé vers la nouvelle définition de type.
Ensuite, compilez _et_ exécutez le code pour vous assurer que votre définition de type correspond bien à ce qui se passe à l'exécution.
-Une fois que vous avez testé vos définitions avec du code réel, faites un [PR](#faire-une-demande-de-pull-request)
-puis suivez les instructions pour [modifier un paquet existant](#modifier-un-paquet-existant) ou
-[créer un nouveau paquet](#créer-un-nouveau-paquet).
+Une fois que vous avez testé vos définitions avec du code réel, faites une [PR](#faire-une-demande-de-pull-request)
+puis suivez les instructions pour [modifier un package existant](#modifier-un-package-existant) ou
+[créer un nouveau package](#créer-un-nouveau-package).
### Faire une demande de pull request
-Une fois que vous avez testé votre paquet, vous pouvez le partager sur Definitely Typed.
+Une fois que vous avez testé votre package, vous pouvez le partager sur Definitely Typed.
-Tout d'abord, [fork](https://guides.github.com/activities/forking/) ce dépôt, [clone](#partial-clone), installez [node](https://nodejs.org/), et lancez `npm install`. Si vous utilisez `npm` v7, vous devez ajouter le drapeau `--legacy-peer-deps` à la commande.
+Tout d'abord, [forkez](https://guides.github.com/activities/forking/) ce dépôt, [clonez](#partial-clone) le,
+installez [node](https://nodejs.org/), et lancez `npm install`. Notez que `pnpm install` installera _l'intégralité_
+du dépôt, y compris des packages que vous ne modifiez peut-être pas. Si vous souhaitez installer uniquement un sous-ensemble,
+vous pouvez lancer `pnpm install -w --filter "{./types/foo}..."` pour installer `@types/foo` et
+toutes ses dépendances. Si vous avez besoin de lancer des tests de packages qui _dépendent_ de `@types/foo`, vous pouvez lancer `pnpm install -w --filter "...{./types/foo}..."` pour récupérer tous les packages associés nécessaires aux tests.
-Nous utilisons un robot pour permettre à un grand nombre de pull requests vers DefinitelyTyped d'être traitées entièrement en libre-service. Vous pouvez en savoir plus sur [pourquoi et comment ici](https://devblogs.microsoft.com/typescript/changes-to-how-we-manage-definitelytyped/). Voici une référence pratique montrant le cycle de vie de pull request à DT :
+> [!NOTE]
+> Si vous utilisez Windows, vous constaterez peut-être que `git clean` ne supprime pas le répertoire `node_modules` ou se bloque lors de cette opération. Si vous devez supprimer `node_modules`, vous pouvez lancer `pnpm clean-node-modules` pour réinitialiser le dépôt.
-
+Nous utilisons un bot pour permettre à un grand nombre de pull requests de DefinitelyTyped d'être traitées entièrement en libre-service. Vous pouvez en savoir plus sur [pourquoi et comment ici](https://devblogs.microsoft.com/typescript/changes-to-how-we-manage-definitelytyped/). Voici une référence pratique montrant le cycle de vie de pull request à DT :
+
+
#### Partial clone
-Vous pouvez cloner l'ensemble du dépôt comme d'habitude, mais il est volumineux et comprend un énorme répertoire de paquets de type.
+Vous pouvez cloner l'ensemble du dépôt comme d'habitude, mais il est volumineux et comprend un énorme répertoire de packages de type.
-Vous pouvez cloner l'ensemble du dépôt [comme d'habitude](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository), mais il est volumineux et comprend un énorme répertoire de paquets de type. Cela prendra du temps à cloner et peut s'avérer inutilement lourd.
+Vous pouvez cloner l'ensemble du dépôt [comme d'habitude](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository), mais il est volumineux et comprend un énorme répertoire de packages de type. Cela prendra du temps à cloner et peut s'avérer inutilement lourd.
-Pour un clone plus facile à gérer qui inclut _seulement_ les paquets de type qui vous concernent, vous pouvez utiliser les fonctionnalités de git [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout), [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt), et [`--depth`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). Cela réduira le temps de clonage et améliorera les performances de git.
+Pour un clone plus facile à gérer qui inclut _seulement_ les packages de type qui vous concernent, vous pouvez utiliser les fonctionnalités de git [`sparse-checkout`](https://git-scm.com/docs/git-sparse-checkout), [`--filter`](https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---filterltfilter-specgt), et [`--depth`](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt). Cela réduira le temps de clonage et améliorera les performances de git.
> :warning: Ceci nécessite au minimum [git version 2.27.0](https://git-scm.com/downloads), qui est probablement plus récent que la version par défaut sur la plupart des machines. Des procédures plus complexes sont disponibles dans les versions plus anciennes, mais ne sont pas couvertes par ce guide.
-1. `git clone --sparse --filter=blob:none --depth=1 `
+1. `git clone --sparse --filter=blob:none `
- `--sparse` initialise le fichier sparse-checkout afin que le répertoire de travail ne contienne au départ que les fichiers situés à la racine du référentiel.
- `--filter=blob:none` exclura des fichiers, les récupérant uniquement en cas de besoin.
- - `--depth=1` améliorera encore la vitesse de clonage en tronquant l'historique des livraisons, mais il peut causer des problèmes, comme le résume le tableau suivant [ici](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).
2. `git sparse-checkout add types/ types/ ...`
-#### Modifier un paquet existant
+#### Modifier un package existant
-- `cd types/`
-- Apporter des modifications. N'oubliez pas d' [éditer les tests](#mon-paquet-teststs).
- Si vous apportez des modifications radicales, n'oubliez pas de [mettre à jour une version majeure](#si-une-bibliothèque-est-mise-à-jour-vers-une-nouvelle-version-majeure-comportant-des-changements-importants-comment-dois-je-mettre-à-jour-son-paquet-de-déclarations-de-types-).
-- [Run `npm test `](#exécution-des-tests).
+- Apporter des modifications. N'oubliez pas d'[éditer les tests](#mon-package-teststs).
+ Si vous apportez des modifications radicales, n'oubliez pas de [mettre à jour la version majeure](#si-une-bibliothèque-est-mise-à-jour-vers-une-nouvelle-version-majeure-comportant-des-changements-importants-comment-dois-je-mettre-à-jour-son-package-de-déclarations-de-types-).
+- [Run `npm test `](#exécution-des-tests).
-Quand vous faites une PR pour éditer un paquet existant, `dt-bot` devrait @-mentionner les auteurs précédents.
-S'il ne le fait pas, vous pouvez le faire vous-même dans le commentaire associé à la PR.
+Quand vous faites une PR pour éditer un package existant, `dt-bot` devrait @-mentionner les auteurs du package.
+S'il ne le fait pas, vous pouvez le faire vous-même dans un commentaire associé à la PR.
-#### Créer un nouveau paquet
+#### Créer un nouveau package
-Si vous êtes l'auteur de la bibliothèque et que votre paquetage est écrit en TypeScript, [regroupez les fichiers de déclaration autogénérés](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) dans votre paquetage au lieu de publier sur Definitely Typed.
+Si vous êtes l'auteur de la lib et que votre package est écrit en TypeScript, [regroupez les fichiers de déclaration autogénérés](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) dans votre package au lieu de le publier sur Definitely Typed.
+Vous pouvez également générer des fichiers de déclaration à partir de fichiers JavaScript, en utilisant JSDoc pour les annotations de type.
-Si vous ajoutez des typages pour un paquetage npm, créez un répertoire avec le même nom.
-Si le paquet pour lequel vous ajoutez des typages n'est pas sur npm, assurez-vous que le nom que vous choisissez pour lui n'entre pas en conflit avec le nom d'un paquet sur npm.
-(Vous pouvez utiliser `npm info ` pour vérifier l'existence du paquet ``).
+Si vous ajoutez des typages pour un package npm, créez un répertoire avec le même nom.
+Si le package pour lequel vous ajoutez des typages n'est pas sur npm, assurez-vous que le nom que vous choisissez pour lui n'entre pas en conflit avec le nom d'un package sur npm.
+(Vous pouvez utiliser `npm info ` pour vérifier l'existence du package ``).
-Votre paquet doit avoir cette structure :
+Votre package doit avoir cette structure :
-| Fichier | Objectif |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `index.d.ts` | Il contient les typages du paquet. |
-| [`-tests.ts`](#mon-paquet-teststs) | Il contient un exemple de code qui teste les typages. Ce code _ne_ s'exécute pas, mais il est vérifié. |
-| [`tsconfig.json`](#tsconfigjson) | Cela vous permet d'exécuter `tsc` à l'intérieur du paquet. |
-| [`.eslintrc.json`](#linter-eslintrcjson) | (Rarement) Nécessaire uniquement pour désactiver les règles de lint écrites pour eslint. |
+| Fichier | Objectif |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `index.d.ts` | Il contient les typages du package. |
+| [`-tests.ts`](#mon-package-teststs) | Il contient un exemple de code qui teste les typages. Ce code _ne_ s'exécute pas, mais il est vérifié. |
+| [`tsconfig.json`](#tsconfigjson) | Cela vous permet d'exécuter `tsc` à l'intérieur du package. |
+| [`.eslintrc.json`](#linter-eslintrcjson) | (Rarement) Nécessaire uniquement pour désactiver les règles de lint écrites pour eslint. |
+| [`package.json`](#packagejson) | Contient les métadonnées du package, y compris son nom, sa version et ses dépendances. |
+| [`.npmignore`](#npmignore) | Spécifie quels fichiers doivent être inclus dans le package. |
-Vous pouvez les générer en lançant `npx dts-gen --dt --name --template module` si vous avez npm ≥ 5.2.0, `npm install -g dts-gen` et `dts-gen --dt --name --template module` dans le cas contraire.
-Voir toutes les options à [dts-gen](https://github.com/microsoft/DefinitelyTyped-tools/tree/main/packages/dts-gen).
+Vous pouvez les générer en lançant `npx dts-gen --dt --name --template module`.
+Voir toutes les options sur [dts-gen](https://github.com/microsoft/DefinitelyTyped-tools/tree/main/packages/dts-gen).
Si vous avez des fichiers `.d.ts` en plus de `index.d.ts`, assurez-vous qu'ils sont référencés soit dans `index.d.ts` soit dans les tests.
Les membres de Definitely Typed surveillent régulièrement les nouveaux PRs, bien qu'il faille garder à l'esprit que le nombre d'autres PRs peut ralentir les choses.
-Pour un bon exemple de paquet, voir [base64-js](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/base64-js).
+Pour un bon exemple de package, voir [base64-js](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/base64-js).
-#### Supprimer un paquet
+#### Supprimer un package
-Lorsqu'un paquet [bundles](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) ses propres types, les types doivent être supprimés de Definitely Typed pour éviter toute confusion.
+Lorsqu'un package [bundles](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) à ses propres types, les types doivent être supprimés de Definitely Typed pour éviter toute confusion.
-Vous pouvez le supprimer en lançant `npm run not-needed -- []`.
+Vous pouvez le supprimer en lançant `npm run not-needed -- []`.
-- `` : C'est le nom du répertoire à supprimer.
-- `` : Un stub sera publié dans `@types/` avec cette version. Elle doit être supérieure à toute version actuellement publiée, et doit être une version de `` sur npm.
-- `` : Nom du paquet npm qui remplace Definitely Typed types. Habituellement, il est identique à ``, dans ce cas vous pouvez l'omettre.
+- `` : C'est le nom du répertoire à supprimer.
+- `` : Un stub sera publié dans `@types/` avec cette version. Elle doit être supérieure à toute version actuellement publiée, et doit être une version de `` sur npm.
+- `` : Nom du package npm qui remplace les types de Definitely Typed. Habituellement, il est identique à ``, dans ce cas vous pouvez l'omettre.
-Tous les autres paquets de Definitely Typed qui référencent le paquet supprimé doivent être mis à jour pour référencer les types regroupés.
-Vous pouvez obtenir cette liste en regardant les erreurs de `npm run test-all`.
-Pour corriger les erreurs, [ajoutez un `package.json`](#packagejson) avec `"dependencies" : { "" : "x.y.z" }`.
-Par exemple :
+Si un package n'a jamais été sur Definitely Typed, il n'a pas besoin d'être ajouté à `notNeededPackages.json`.
-```json
-{
- "private": true,
- "dependencies": {
- "": "^2.6.0"
- }
-}
-```
+#### Exécution des tests
-Lorsque vous ajoutez un `package.json` aux dépendances de ``, vous devez également ouvrir une PR pour ajouter `` [à allowedPackageJsonDependencies.txt dans DefinitelyTyped-tools](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt).
+Testez vos modifications en lançant `npm test ` où `` est le nom de votre package.
+Vous devez l'exécuter depuis le répertoire DefinitelyTyped car les `package.json` individuels ne définissent pas de scripts de test.
-Si un paquet n'a jamais été sur Definitely Typed, il n'a pas besoin d'être ajouté à `notNeededPackages.json`.
+Ce script utilise [dtslint](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) pour lancer le compilateur TypeScript sur vos fichiers dts.
-#### Exécution des tests
+Une fois que tous vos changements sont prêts, lancez `npm run test-all` pour voir comment vos changements affectent les autres modules.
-Testez vos modifications en lançant `npm test ` où `` est le nom de votre paquetage.
+##### @arethetypeswrong/cli (`attw`) checks
-Ce script utilise [dtslint](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/dtslint) pour lancer le compilateur TypeScript sur vos fichiers dts.
+dtslint inclut des vérifications de format de module et de configuration `package.json` à partir de [@arethetypeswrong/cli](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/packages/cli). Les vérifications ne s'exécutent que si un package d'implémentation compatible avec SemVer-major peut être trouvé sur npm pour être comparé au package DefinitelyTyped. (Les packages DefinitelyTyped marqués comme `nonNpm` dans leur `package.json` sont ignorés.)
-Une fois que tous vos changements sont prêts, utilisez `npm run test-all` pour voir comment vos changements affectent les autres modules.
+De nombreux packages échouent actuellement aux vérifications `attw` et doivent être corrigés. Pour nous permettre de progresser de manière incrémentale, les vérifications `attw` échouées ne font pas échouer l'exécution de `dtslint` lorsque le package est listé dans `failingPackages` dans [`attw.json`](./attw.json), mais elles seront toujours signalées dans la sortie de `pnpm test my-package`. Si vous corrigez le package, retirez-le de `failingPackages` afin que les vérifications `attw` puissent commencer à faire échouer les exécutions de `dtslint`.
-#### Nommer
+Tous les problèmes signalés par `attw` ont une documentation liée dans la sortie. Voici quelques règles générales pour éviter les problèmes :
-Si vous ajoutez des typages pour un paquetage npm, créez un répertoire portant le même nom.
-Si le paquet pour lequel vous ajoutez des typages n'est pas sur npm, assurez-vous que le nom que vous choisissez pour lui n'entre pas en conflit avec le nom d'un paquet sur npm.
-(Vous pouvez utiliser `npm info ` pour vérifier l'existence du paquet ``).
+- Le `package.json` dans le package DefinitelyTyped doit avoir des champs `type` et `exports` correspondants si le package d'implémentation les utilise dans son `package.json`. Par exemple, si un `package.json` d'implémentation ressemble à :
-Si un paquet non-npm entre en conflit avec un paquet npm existant, essayez d'ajouter -browser à la fin du nom pour obtenir `-browser`.
+ ```json
+ {
+ "name": "my-package",
+ "version": "1.0.1",
+ "type": "module",
+ "main": "dist/cjs/index.cjs",
+ "exports": {
+ ".": {
+ "import": "./dist/esm/index.js",
+ "require": "./dist/cjs/index.cjs"
+ },
+ "./subpath": {
+ "import": "./dist/esm/subpath.js",
+ "require": "./dist/cjs/subpath.cjs"
+ }
+ }
+ }
+ ```
-#### `-tests.ts`
+ alors le `package.json` dans DefinitelyTyped devrait ressembler à ceci :
+
+ ```json5
+ {
+ "name": "@types/my-package",
+ "version": "1.0.9999",
+ "type": "module",
+ "types": "index.d.ts",
+ "exports": {
+ ".": {
+ "import": "./index.d.ts",
+ "require": "./index.d.cts"
+ },
+ "./subpath": {
+ "import": "./subpath.d.ts",
+ "require": "./subpath.d.cts"
+ }
+ }
+ }
+ ```
-Il devrait y avoir un fichier `-tests.ts`, qui est considéré comme votre fichier de test, avec tous les fichiers `*.ts` qu'il importe.
-Si vous ne voyez aucun fichier de test dans le dossier du module, créez un fichier `-tests.ts`.
-Ces fichiers sont utilisés pour valider l'API exportée depuis les fichiers `*.d.ts` qui sont livrés en tant que `@types/`.
+ Notez que chaque sous-chemin `exports` est reflété, et chaque fichier JavaScript a un fichier de déclaration correspondant avec une extension de fichier correspondante à un fichier `.d.ts` d'un fichier `.js`, et non un fichier `.mjs` ou `.cjs` !
-Les changements apportés aux fichiers `*.d.ts` doivent inclure un changement correspondant au fichier `*.ts` qui montre l'API utilisée, afin que quelqu'un ne casse pas accidentellement le code dont vous dépendez.
-Si vous ne voyez aucun fichier de test dans le dossier du module, créez un fichier `-tests.ts`
+- Lorsque le package d'implémentation utilise `module.exports = ...`, le package DefinitelyTyped doit utiliser `export =`, et non `export default`. (Alternativement, si le `module.exports` est juste un objet de propriétés nommées, le package DefinitelyTyped peut utiliser une série d'exports nommés.) L'obstacle le plus courant pour corriger ce problème est la confusion sur la façon d'exporter des types en plus de l'exportation principale. Par exemple, supposons que ces types utilisent incorrectement `export default` :
+
+ ```ts
+ export interface Options {
+ // ...
+ }
+ export default function doSomething(options: Options): void;
+ ```
+
+ Changer `export default` en `export =` crée une erreur :
+ ```ts
+ export interface Options {
+ // ...
+ }
+ declare function doSomething(options: Options): void;
+ export = doSomething;
+ // ^^^^^^^^^^^^^^^^^
+ // Error: An export assignment cannot be used in a module with other exported elements.
+ ```
+
+ Pour résoudre cela, déplacez les types à l'intérieur d'un namespace portant le même nom que la fonction :
+
+ ```ts
+ declare namespace doSomething {
+ export interface Options {
+ // ...
+ }
+ }
+ declare function doSomething(options: doSomething.Options): void;
+ export = doSomething;
+ ```
+
+Si vous avez besoin d'aide pour résoudre un problème, veuillez demander dans le canal DefinitelyTyped sur le [serveur Discord de la communauté TypeScript](https://discord.gg/typescript).
+
+#### Nommage
+
+Si vous ajoutez des types pour un package npm, créez un répertoire portant le même nom.
+Si le package pour lequel vous ajoutez des types n'est pas sur npm, assurez-vous que le nom que vous choisissez pour lui n'entre pas en conflit avec le nom d'un package sur npm.
+(Vous pouvez utiliser `npm info ` pour vérifier l'existence du package ``).
+
+Dans de rares occasions, `nonNpm` peut être défini sur `"conflict"`, ce qui indique qu'il existe un package sur npm avec le même nom, mais que les types sont intentionnellement en conflit avec ce package.
+Cela peut être vrai pour les packages qui définissent un environnement comme `@types/node` ou pour des packages factices comme `aws-lambda`. Évitez d'utiliser `"conflict"` autant que possible.
+
+#### `-tests.ts`
+
+Il devrait y avoir un fichier `-tests.ts`, qui est considéré comme votre fichier de test, avec tous les fichiers `*.ts` qu'il importe.
+Si vous ne voyez aucun fichier de test dans le dossier du module, créez un fichier `-tests.ts`.
+Ces fichiers sont utilisés pour valider l'API exportée depuis les fichiers `*.d.ts` qui sont livrés en tant que `@types/`.
+Ils ne sont pas eux-mêmes expédiés.
+
+Les changements apportés aux fichiers `*.d.ts` doivent inclure un changement correspondant au fichier `*.ts` qui montre l'API utilisée, afin que quelqu'un ne casse pas accidentellement le code dont vous dépendez.
Par exemple, cette modification d'une fonction dans un fichier `.d.ts` ajoute un nouveau paramètre à une fonction :
`index.d.ts`:
@@ -246,7 +338,7 @@ Par exemple, cette modification d'une fonction dans un fichier `.d.ts` ajoute un
+ export function twoslash(body: string, config?: { version: string }): string
```
-`-tests.ts`:
+`-tests.ts`:
```diff
import {twoslash} from "./"
@@ -263,7 +355,7 @@ const result = twoslash("//")
Si vous vous demandez par où commencer avec le code de test, les exemples dans le README du module sont un bon point de départ.
-Vous pouvez [valider vos changements](#exécution-des-tests) avec `npm test ` depuis la racine de ce repo, qui prend en compte les fichiers modifiés.
+Vous pouvez [valider vos changements](#exécution-des-tests) avec `npm test ` depuis la racine de ce repo, qui prend en compte les fichiers modifiés.
Utilisez `$ExpectType` pour affirmer qu'une expression est d'un type donné, et `@ts-expect-error` pour affirmer qu'il s'agit d'une erreur de compilation. Exemples :
@@ -279,7 +371,7 @@ Pour plus de détails, voir le readme de [dtslint](https://github.com/Microsoft/
##### Linter: `.eslintrc.json`
-Vous devez désactiver des règles spécifiques uniquement sur des lignes spécifiques :
+Si, pour une raison quelconque, une règle de lint doit être désactivée, désactivez-la pour une ligne spécifique :
```ts
// eslint-disable-next-line no-const-enum
@@ -291,11 +383,12 @@ const enum Enum { // eslint-disable-line no-const-enum
}
```
-Vous pouvez toujours désactiver les règles avec un fichier .eslintrc.json, mais vous ne devriez pas le faire dans les nouveaux paquets.
+Vous pouvez toujours désactiver les règles avec un fichier `.eslintrc.json`, mais vous ne devriez pas le faire dans les nouveaux packages.
+Désactiver les règles pour l'ensemble du package rend la révision plus difficile.
#### `tsconfig.json`
-`tsconfig.json` doit avoir `noImplicitAny`, `noImplicitThis`, `strictNullChecks`, et `strictFunctionTypes` mis à `true`.
+`tsconfig.json` doit avoir `noImplicitAny`, `noImplicitThis`, `strictNullChecks`, et `strictFunctionTypes` défini à `true`.
Vous pouvez éditer le fichier `tsconfig.json` pour ajouter de nouveaux fichiers de test, pour ajouter `"target" : "es6"` (nécessaire pour les fonctions asynchrones), pour ajouter à `"lib"`, ou pour ajouter l'option de compilateur `"jsx"`.
@@ -316,7 +409,7 @@ TL;DR : `esModuleInterop` et `allowSyntheticDefaultImports` ne sont _pas autoris
> import Component from "./component";
> ```
>
-> Puisque la validité à la compilation de l'import dans `dex.d.ts` dépend de paramètres de compilation spécifiques, dont les utilisateurs de vos types n'héritent pas, l'utilisation de ce pattern dans DefinitelyTyped forcerait les utilisateurs à changer leurs propres paramètres de compilation, ce qui pourrait être incorrect pour leur environnement d'exécution. Au lieu de cela, vous devez écrire un import CJS pour un export CJS afin d'assurer une compatibilité généralisée et indépendante de la configuration :
+> Puisque la validité à la compilation de l'import dans `index.d.ts` dépend de paramètres de compilation spécifiques, dont les utilisateurs de vos types n'héritent pas, l'utilisation de ce pattern dans DefinitelyTyped forcerait les utilisateurs à changer leurs propres paramètres de compilation, ce qui pourrait être incorrect pour leur environnement d'exécution. Au lieu de cela, vous devez écrire un import CJS pour un export CJS afin d'assurer une compatibilité généralisée et indépendante de la configuration :
>
> ```ts
> // index.d.ts
@@ -326,65 +419,125 @@ TL;DR : `esModuleInterop` et `allowSyntheticDefaultImports` ne sont _pas autoris
#### `package.json`
-En général, vous n'en aurez pas besoin.
-L'éditeur de paquets de DefinitelyTyped crée un `package.json` pour les paquets qui n'ont pas de dépendances en dehors de DefinitelyTyped.
-Un `package.json` peut être inclus pour spécifier des dépendances qui ne sont pas d'autres paquets `@types`.
-[Pikaday en est un bon exemple](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)
-Même si vous écrivez votre propre `package.json`, vous ne pouvez spécifier que des dépendances ; d'autres champs comme `"description"` ne sont pas autorisés.
-Vous devez également ajouter la dépendance à [la liste des paquets autorisés](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt).
-Cette liste est mise à jour par un humain, ce qui nous permet de nous assurer que les paquets `@types` ne dépendent pas de paquets malveillants.
+Ce fichier est requis et doit suivre ce modèle :
-Dans le rare cas où un paquet `@types` est supprimé et retiré en faveur des types fournis par le paquet source ET que vous avez besoin de dépendre de l'ancien paquet `@types` retiré, vous pouvez ajouter une dépendance sur un paquet `@types`.
-Assurez-vous d'expliquer cela lors de l'ajout à la liste des paquets autorisés afin que le mainteneur humain sache ce qui se passe.
+```json5
+{
+ "private": true,
+ "name": "@types/PACKAGE-NAME",
+ "version": "1.2.9999",
+ "projects": [
+ "https://aframe.io/"
+ ],
+ "dependencies": {
+ "@types/DEPENDENCY-1": "*",
+ "@types/DEPENDENCY-2": "*"
+ },
+ "devDependencies": {
+ "@types/PACKAGE-NAME": "workspace:."
+ },
+ "owners": [
+ {
+ "name": "Your Name Here",
+ "githubUsername": "ghost"
+ }
+ ]
+}
+```
-La deuxième raison de créer votre propre package.json est de spécifier les modules ES.
-Si le paquet d'implémentation utilise ESM et spécifie `"type" : "module"`, alors vous devez ajouter un package.json avec la même chose :
+Un `package.json` spécifie _toutes_ les dépendances, y compris les autres packages `@types`.
+
+Vous devez ajouter les dépendances non-`@types` à [la liste des dépendances externes autorisées](https://github.com/microsoft/DefinitelyTyped-tools/blob/master/packages/definitions-parser/allowedPackageJsonDependencies.txt).
+[Pikaday est un bon exemple.](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/pikaday/package.json)
+Ces ajouts sont approuvés par un mainteneur, ce qui nous donne l'occasion de nous assurer que les packages `@types` ne dépendent pas de packages malveillants.
+
+Si le package d'implémentation utilise ESM et spécifie `"type" : "module"`, alors vous devez ajouter un package.json avec la même chose :
```json
{
- "private": true,
"type": "module"
}
```
-Ceci s'applique également si le paquet d'implémentation a `exports` dans son package.json.
+Ceci s'applique également si le package d'implémentation a `exports` dans son package.json.
-#### `OTHER_FILES.txt`
+##### Peer dependencies
-Si un fichier n'est ni testé ni référencé dans `index.d.ts`, ajoutez-le à un fichier nommé `OTHER_FILES.txt`. Ce fichier est une liste d'autres fichiers qui doivent être inclus dans le paquetage typings, un fichier par ligne.
+Definitely Typed autorise les `peerDependencies` dans `package.json`.
+Les peer dependencies peuvent aider à prévenir les situations où un gestionnaire de package installe de manière inattendue des versions trop récentes ou plusieurs versions du même package.
+Cependant, les peer dependencies ont des inconvénients ; les gestionnaires de packages diffèrent dans leur gestion des peer dependencies (par exemple, `yarn` ne les installe pas automatiquement, `npm` nécessite `--legacy-peer-deps` pour les incompatibilités).
+Ainsi, les PR introduisant de nouvelles peer dependencies nécessitent l'approbation d'un mainteneur et doivent être limitées à des circonstances spécifiques.
+
+**En général, les packages de types ne devraient avoir une peer dependency que si le package en amont a une peer dependency sur le même package (ou ses types).**
+Par exemple, un package DT pour un composant React peut spécifier une peer dependency sur `@types/react@*`, car le consommateur aura besoin d'installer `@types/react` pour utiliser JSX en premier lieu.
+Si le consommateur installe `@types/react@16` dans son projet, mais qu'une version plus récente de `@types/react` est disponible sur npm, la peer dependency peut aider le gestionnaire de packages à choisir `@types/react@16` au lieu de cette version plus récente.
+De même, `chai-as-promised` a une peer dependency sur `chai`, donc `@types/chai-as-promised` devrait avoir une peer dependency sur `@types/chai`.
+
+Il existe certains cas où le package en amont n'a pas de peer dependency sur le package de types, mais une peer dependency est toujours appropriée.
+Ce sont généralement des cas où le package en amont étend un autre package et suppose qu'il existe, donc _devrait_ avoir déclaré une peer dependency car il étend un autre package, mais ne l'a pas fait.
+Par exemple, `chai-match-pattern` étend `chai`, mais ne déclare pas de peer dependency sur `chai`, mais en a besoin pour fonctionner. `@types/chai-match-pattern` devrait avoir une peer dependency sur `@types/chai`.
+
+Si un package expose simplement des types d'un autre package dans le cadre de son API en raison d'une dépendance régulière dans le package en amont, il _ne devrait pas_ utiliser une peer dependency.
+Par exemple, `express` a `qs` dans ses `"dependencies"`. Lorsque les utilisateurs installent `express`, ils n'ont pas besoin d'installer manuellement `qs`. De même, `@types/express` a `@types/qs` dans ses `"dependencies"`.
+Il serait incorrect de déclarer `@types/qs` comme une peer dependency de `@types/express`, car cela obligerait certains consommateurs en aval à installer manuellement `@types/qs`.
+
+#### `.npmignore`
+
+Ce fichier définit quels fichiers doivent être inclus dans chaque package `@types`. Il doit prendre une forme spécifique. Pour les packages avec une seule version dans le dépôt :
+
+```ignore
+*
+!**/*.d.ts
+!**/*.d.cts
+!**/*.d.mts
+!**/*.d.*.ts
+```
+
+Ce qui signifie "ignorer tous les fichiers, mais ne pas ignorer les fichiers de déclaration". Pour les packages qui ont plus d'une version dans le dépôt, la version "la plus récente" (au niveau supérieur) devrait contenir quelque chose comme :
+
+```ignore
+*
+!**/*.d.ts
+!**/*.d.cts
+!**/*.d.mts
+!**/*.d.*.ts
+/v15/
+/v16/
+/v17/
+```
+
+Ce qui est identique au précédent `.npmignore` mais en ignorant chaque répertoire enfant versionné.
+
+La CI échouera si ce fichier contient des contenus incorrects et fournira la valeur attendue. Peu importe ce que contient ce fichier, le publisher ne publiera que les fichiers de déclaration.
#### Erreurs courantes
- Tout d'abord, suivez les conseils du [manuel](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html).
-- Formatage : Utilisez 4 espaces. Prettier est installé sur ce repo, vous pouvez donc lancer `npm run prettier -- --write 'path/to/package/**/*.ts'`. [Lorsque vous utilisez des assertions](https://github.com/SamVerschueren/tsd#assertions), ajoutez l'exclusion `// prettier-ignore` pour marquer les lignes de code comme exclues du formatage :
- ```tsx
- // prettier-ignore
- // @ts-expect-error
- const incompleteThemeColorModes: Theme = { colors: { modes: { papaya: {
- ```
-- `function sum(nums : number[]) : number` : Utilisez `ReadonlyArray` si une fonction n'écrit pas dans ses paramètres.
+- Formatage : [dprint](https://dprint.dev) est configuré sur ce dépôt, vous pouvez donc lancer `pnpm dprint fmt -- 'path/to/package/**/*.ts'`.
+ - Envisagez d'utiliser le fichier `.vscode/settings.template.json` de VS Code (ou l'équivalent pour d'autres éditeurs) pour formater à la sauvegarde avec l'[extension dprint pour VS Code](https://marketplace.visualstudio.com/items?itemName=dprint.dprint).
+- `function sum(nums: number[]): number`: Utilisez `ReadonlyArray` si une fonction n'écrit pas dans ses paramètres.
- `interface Foo { new(): Foo; }`:
- Cela définit un type d'objets qui peuvent être modifiés. Vous voudrez probablement `declare class Foo { constructor() ; }`.
+ Cela définit un type d'objets qui peuvent être modifiés. Vous voudrez probablement `declare class Foo { constructor(); }`.
- `const Class: { new(): IClass; }`:
- Il est préférable d'utiliser une déclaration de classe `class Class { constructor() ; }` plutôt qu'une constante modifiable.
+ Il est préférable d'utiliser une déclaration de classe `class Class { constructor(); }` plutôt qu'une constante modifiable.
- `getMeAT(): T`:
Si un paramètre de type n'apparaît dans les types d'aucun paramètre, il ne s'agit pas vraiment d'une fonction générique, mais simplement d'une assertion de type déguisée.
- Il est préférable d'utiliser une assertion de type réel, par exemple `getMeAT() as number`.
- Exemple où un paramètre de type est acceptable : `function id(value : T) : T;`.
- Exemple où il n'est pas acceptable : `function parseJson(json : string) : T;`.
+ Il est préférable d'utiliser une assertion de type réelle, par exemple `getMeAT() as number`.
+ Exemple où un paramètre de type est acceptable : `function id(value: T): T;`.
+ Exemple où il n'est pas acceptable : `function parseJson(json: string): T;`.
Exception : `new Map()` est OK.
-- L'utilisation des types `Function` et `Object` n'est presque jamais une bonne idée. Dans 99% des cas, il est possible de spécifier un type plus spécifique. Les exemples sont `(x : number) => number` pour les [fonctions](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-type-expressions) et `{ x : number, y : number }` pour les objets. S'il n'y a aucune certitude sur le type, [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) est le bon choix, pas `Object`. Si la seule chose connue à propos du type est qu'il s'agit d'un objet, utilisez le type [`object`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#object-type), pas `Object` ou `{ [key : string] : any }`.
+- L'utilisation des types `Function` et `Object` n'est presque jamais une bonne idée. Dans 99% des cas, il est possible de spécifier un type plus spécifique. Les exemples sont `(x: number) => number` pour les [fonctions](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-type-expressions) et `{ x: number, y: number }` pour les objets. S'il n'y a aucune certitude sur le type, [`any`](https://www.typescriptlang.org/docs/handbook/basic-types.html#any) est le bon choix, pas `Object`. Si la seule chose connue à propos du type est qu'il s'agit d'un objet, utilisez le type [`object`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#object-type), pas `Object` ou `{ [key: string]: any }`.
- `var foo: string | any`:
Lorsque `any` est utilisé dans un type union, le type résultant est toujours `any`. Ainsi, bien que la partie `string` de cette annotation de type puisse _look_ utile, elle n'offre en fait aucune vérification de type supplémentaire par rapport à l'utilisation simple de `any`.
Selon l'intention, les alternatives acceptables pourraient être `any`, `string`, ou `string | object`.
-### Définition des propriétaires
+### Propriétaires de définition
> TL;DR : ne pas modifier `.github/CODEOWNERS`, toujours modifier la liste des propriétaires dans `package.json`.
DT a le concept de "propriétaires de définition" qui sont des personnes qui veulent maintenir la qualité des types d'un module particulier.
-- En vous ajoutant à la liste, vous serez notifié (via votre nom d'utilisateur GitHub) chaque fois que quelqu'un fera une pull request ou une issue concernant le paquet.
+- En vous ajoutant à la liste, vous serez notifié (via votre nom d'utilisateur GitHub) chaque fois que quelqu'un fera une pull request ou une issue concernant le package.
- Vos reviews de PR auront une plus grande importance pour [le bot](https://github.com/microsoft/DefinitelyTyped-tools/tree/main/packages/mergebot) qui maintient ce repo.
- Les mainteneurs de DT font confiance aux propriétaires des définitions pour assurer un écosystème stable, ne vous ajoutez pas à la légère.
@@ -413,7 +566,7 @@ Definitely Typed est l'un des dépôts les plus actifs sur GitHub. Vous vous êt
## FAQ
-#### Quelle est la relation exacte entre ce dépôt et les paquets `@types` sur npm ?
+#### Quelle est la relation exacte entre ce dépôt et les packages `@types` sur npm ?
La branche `master` est automatiquement publiée dans le scope `@types` sur npm grâce à [DefinitelyTyped-tools](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher).
@@ -434,22 +587,31 @@ Les modifications apportées à ces projets peuvent avoir des effets considérab
Ces modules requièrent à la fois l'approbation d'un mainteneur de DT et le soutien enthousiaste des propriétaires du module. La barre pour réussir cela peut être assez haute, et souvent les PRs peuvent s'essouffler parce qu'il n'y a pas de champion.
Si vous constatez que personne ne s'engage, essayez de réduire la portée de votre PR.
-#### Mon PR est fusionné ; quand le paquet npm `@types` sera-t-il mis à jour ?
+#### Mon PR est fusionné ; quand le package npm `@types` sera-t-il mis à jour ?
-Les paquets npm devraient être mis à jour dans les minutes qui suivent. Si cela fait plus d'une heure, mentionnez le numéro de PR sur [le canal Definitely Typed sur le serveur Discord de la communauté TypeScript](https://discord.gg/typescript) et le mainteneur actuel demandera au bon membre de l'équipe d'enquêter.
+Les packages npm devraient être mis à jour dans les minutes qui suivent. Si cela fait plus d'une heure, mentionnez le numéro de PR sur [le canal Definitely Typed sur le serveur Discord de la communauté TypeScript](https://discord.gg/typescript) et le mainteneur actuel demandera au bon membre de l'équipe d'enquêter.
#### J'écris une définition qui dépend d'une autre définition. Dois-je utiliser `` ou un import ?
Si le module auquel vous faites référence est un module externe (qui utilise `export`), utilisez un import.
Si le module auquel vous faites référence est un module ambiant (qui utilise `declare module`, ou qui déclare simplement des globaux), utilisez ``.
-#### Certains paquets n'ont pas de `tslint.json`, et certains `tsconfig.json` n'ont pas `"noImplicitAny" : true`, `"noImplicitThis" : true`, ou `"strictNullChecks" : true`.
+#### Certains packages n'ont pas de `tslint.json`, et certains `tsconfig.json` n'ont pas `"noImplicitAny" : true`, `"noImplicitThis" : true`, ou `"strictNullChecks" : true`.
Alors ils sont faux, et nous ne l'avons pas encore remarqué. Vous pouvez nous aider en soumettant une demande d'extraction pour les corriger.
-#### Puis-je modifier/renforcer les paramètres de formatage des modules ?
+#### Les fichiers sont-ils formatés automatiquement ?
-Non. Nous avons déjà essayé de rendre le formatage du code de DT cohérent, mais nous sommes arrivés à une impasse en raison de la forte activité sur le repo. Nous incluons les paramètres de formatage via [`.editorconfig`](.editorconfig). Ceux-ci sont exclusivement destinés à l'outillage de votre éditeur, leurs paramètres n'entrent pas en conflit et nous ne prévoyons pas de les modifier. Nous ne prévoyons pas non plus d'imposer un style spécifique dans le repo. Nous voulons garder les barrières aux contributions basses.
+Oui, en utilisant [dprint](https://dprint.dev).
+Nous recommandons d'utiliser une [extension dprint pour votre éditeur](https://dprint.dev/install/#editor-extensions).
+
+Alternativement, vous pouvez activer un hook git qui formatera automatiquement votre code. Exécutez `pnpm run setup-hooks`. Ensuite, lorsque vous committez, la commande `dprint fmt` sera exécutée sur les fichiers modifiés. Si vous utilisez le [clone partiel](#partial-clone), assurez-vous d'appeler `git sparse-checkout add .husky` pour vérifier les hooks git avant d'exécuter le script `setup-hooks`.
+
+Les pull requests n'ont pas besoin d'un formatage correct pour être fusionnées.
+Tout code non formaté sera automatiquement reformaté après avoir été fusionné.
+
+> 💡 Si vous utilisez VS Code, nous vous suggérons de copier le fichier `.vscode/settings.template.json` vers `.vscode/settings.json`.
+> Ce modèle définit l'[extension dprint pour VS Code](https://marketplace.visualstudio.com/items?itemName=dprint.dprint) comme le formateur par défaut dans le dépôt.
#### Puis-je demander une définition ?
@@ -459,19 +621,19 @@ Voici les [définitions actuellement demandées](https://github.com/DefinitelyTy
Si les types font partie d'un standard web, ils doivent être ajoutés à [TypeScript-DOM-lib-generator](https://github.com/Microsoft/TypeScript-DOM-lib-generator) afin qu'ils puissent faire partie de la `lib.dom.d.ts` par défaut.
-#### Qu'en est-il des définitions de type sans paquet correspondant ?
+#### Qu'en est-il des définitions de type sans package correspondant ?
S'il n'y a pas de code Javascript source du tout, par exemple si vous écrivez des types d'aide ou des types pour une spécification, vous devriez publier les types vous-même, pas sur Definitely Typed.
-Parce qu'ils sont destinés à fournir des types pour du code Javascript existant, les paquets `@types` ne sont pas destinés à être importés directement.
-En d'autres termes, vous ne devriez pas créer un paquet Definitely Typed destiné à être utilisé comme `import type { ... } from "@types/foo"`.
+Parce qu'ils sont destinés à fournir des types pour du code Javascript existant, les packages `@types` ne sont pas destinés à être importés directement.
+En d'autres termes, vous ne devriez pas créer un package Definitely Typed destiné à être utilisé comme `import type { ... } from "@types/foo"`.
Vous ne devez pas non plus vous attendre à écrire `import type { ... } from "foo"` quand il n'y a pas de `foo` installé.
C'est différent de fournir des types pour une bibliothèque Javascript uniquement pour le navigateur ou des types pour un environnement entier comme node, bun, et al.
Là, les types sont résolus soit implicitement, soit en utilisant `/// `.
-#### Dois-je ajouter un espace de noms vide à un paquetage qui n'exporte pas de module pour utiliser les importations de style ES6 ??
+#### Dois-je ajouter un espace de noms vide à un package qui n'exporte pas de module pour utiliser les importations de style ES6 ??
-Certains paquets, comme [chai-http](https://github.com/chaijs/chai-http), exportent une fonction.
+Certains packages, comme [chai-http](https://github.com/chaijs/chai-http), exportent une fonction.
Importer ce module avec un import de style ES6 de la forme `import * as foo from "foo";` conduit à l'erreur :
@@ -486,14 +648,14 @@ Néanmoins, si vous voulez utiliser un import par défaut comme `import foo from
- vous pouvez utiliser l'option de compilation [`--allowSyntheticDefaultImports`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-8.html#support-for-default-import-interop-with-systemjs) si votre module d'exécution supporte un schéma d'interopérabilité pour les modules non-ECMAScript, c'est-à-dire si les importations par défaut fonctionnent dans votre environnement (par exemple Webpack, SystemJS, esm).
- vous pouvez utiliser l'option de compilation [`--esModuleInterop`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---esmoduleinterop) si vous voulez que TypeScript prenne en charge l'interopérabilité non-ECMAScript (depuis TypeScript 2.7).
-#### Un paquet utilise `export =`, mais je préfère utiliser les importations par défaut. Puis-je remplacer `export =` par `export default` ?
+#### Un package utilise `export =`, mais je préfère utiliser les importations par défaut. Puis-je remplacer `export =` par `export default` ?
Comme dans la question précédente, il faut utiliser les options [`--allowSyntheticDefaultImports`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-1-8.html#support-for-default-import-interop-with-systemjs)
ou [`--esModuleInterop`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-7.html#support-for-import-d-from-cjs-form-commonjs-modules-with---esmoduleinterop)
du compilateur.
Ne changez pas la définition du type si elle est correcte.
-Pour un paquet npm, `export =` est correct si `node -p 'require("foo")'` fonctionne pour importer un module, et `export default` est correct si `node -p 'require("foo").default'` fonctionne pour importer un module.
+Pour un package npm, `export =` est correct si `node -p 'require("foo")'` fonctionne pour importer un module, et `export default` est correct si `node -p 'require("foo").default'` fonctionne pour importer un module.
#### Je souhaite utiliser les fonctionnalités des toutes nouvelles versions de TypeScript.
@@ -504,7 +666,7 @@ Vous trouverez une explication détaillée de cette fonctionnalité dans la [doc
Voici un petit exemple pour commencer :
-1. Vous devrez ajouter un fichier `package.json` à votre définition de paquet, avec le contenu suivant :
+1. Vous devrez ajouter `typesVersions` au `package.json` :
```json
{
@@ -517,112 +679,101 @@ Voici un petit exemple pour commencer :
```
2. Créez le sous-répertoire mentionné dans le champ `typesVersions` à l'intérieur de votre répertoire de types (`ts3.6/` dans cet exemple).
- `ts3.6/` supportera les versions 3.6 et inférieures de TypeScript, donc copiez les types et les tests existants dans ce répertoire.
-
- Vous devrez supprimer l'en-tête de définition de `ts3.6/index.d.ts` puisque seule la racine `index.d.ts` est supposée l'avoir.
-
-3. Définissez les options `baseUrl` et `typeRoots` dans `ts3.6/tsconfig.json` avec les chemins corrects, qui devraient ressembler à ceci :
- ```json
- {
- "compilerOptions": {
- "baseUrl": "../../",
- "typeRoots": ["../../"]
- }
- }
- ```
+ `ts3.6/` supportera les versions de TypeScript 3.6 et inférieures, alors copiez-y les types et tests existants.
-4. À la racine du paquet, ajoutez les fonctionnalités TypeScript 3.7 que vous souhaitez utiliser.
- Lors de l'installation du paquet, TypeScript 3.6 et moins démarrera à partir de `ts3.6/index.d.ts`, tandis que TypeScript 3.7 et plus démarrera à partir de `index.d.ts`.
+3. De retour à la racine du package, ajoutez les fonctionnalités de TypeScript 3.7 que vous souhaitez utiliser.
+ Lorsque les gens installeront le package, TypeScript 3.6 et inférieures commenceront à partir de `ts3.6/index.d.ts`, tandis que TypeScript 3.7 et supérieures commenceront à partir de `index.d.ts`.
- Vous pouvez prendre l'exemple de [bluebird](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/f2512c2cf7cdcf9a487d989e288174e49b7839ab/types/bluebird).
+ Vous pouvez consulter [bluebird](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/f2512c2cf7cdcf9a487d989e288174e49b7839ab/types/bluebird) pour un exemple.
#### Je souhaite ajouter une API DOM qui n'est pas présente par défaut dans TypeScript.
Cela pourrait être dans [TypeScript-DOM-lib-generator](https://github.com/Microsoft/TypeScript-DOM-lib-generator#readme). Voir les lignes directrices à cet endroit.
Si le standard est encore à l'état de projet, il a sa place ici.
Utilisez un nom commençant par `dom-` et incluez un lien vers le standard comme lien "Project" dans l'en-tête.
-Lorsqu'il sort du mode brouillon, nous pouvons le retirer de Definitely Typed et déprécier le paquetage `@types` associé.
+Lorsqu'il sort du mode brouillon, nous pouvons le retirer de Definitely Typed et déprécier le packageage `@types` associé.
-#### Comment les versions des paquets Definitely Typed sont-elles liées aux versions de la bibliothèque correspondante ?
+#### Comment les versions des packages Definitely Typed sont-elles liées aux versions de la bibliothèque correspondante ?
_REMARQUE : la discussion dans cette section suppose une certaine familiarité avec le [Semantic versioning](https://semver.org/)_.
-Chaque paquet Definitely Typed est versionné lorsqu'il est publié sur npm.
-L'outil [DefinitelyTyped-tools](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) (l'outil qui publie les paquets `@types` sur npm) définira la version du paquet de déclaration en utilisant le numéro de version `major.minor` listé dans la première ligne de son fichier `index.d.ts`.
-Par exemple, voici les premières lignes de [Node's type declarations](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/node/index.d.ts) pour la version `10.12.x` au moment de l'écriture :
+Chaque package de Definitely Typed est versionné lorsqu'il est publié sur npm.
+L'outil [DefinitelyTyped-tools](https://github.com/microsoft/DefinitelyTyped-tools/tree/master/packages/publisher) (l'outil qui publie les packages `@types` sur npm) définira la version du package de déclaration en utilisant le numéro de version `major.minor.9999` indiqué dans `package.json`.
+Par exemple, voici les premières lignes des déclarations de type de Node pour la version `20.8.x` au moment de la rédaction :
-```js
-// Type definitions for Node.js 10.12
-// Project: https://nodejs.org/
-// Definitions by: Microsoft TypeScript
-// Definitely Typed
-// Alberto Schiabel
+```json
+{
+ "private": true,
+ "name": "@types/node",
+ "version": "20.8.9999"
+}
```
-Parce que `10.12` est à la fin de la première ligne, la version npm du paquet `@types/node` sera aussi `10.12.x`.
-Notez que le commentaire de la première ligne du fichier `index.d.ts` ne doit contenir que la version `major.minor` (par exemple `10.12`) et ne doit pas contenir de version de correctif (par exemple `10.12.4`).
-C'est parce que seuls les numéros de version majeure et mineure sont alignés entre les paquets de bibliothèques et les paquets de déclarations de types.
-Le numéro de version du patch du paquet de déclaration de type (par exemple `.0` dans `10.12.0`) est initialisé à zéro par Definitely Typed et est incrémenté à chaque fois qu'un nouveau paquet `@types/node` est publié sur npm pour la même version majeure/mineure de la bibliothèque correspondante.
+Comme la version est indiquée comme `20.8.9999`, la version npm du package `@types/node` sera également `20.8.x`.
+Notez que la version dans `package.json` ne doit contenir que la version `major.minor` (par exemple `10.12`) suivie de `.9999`.
+Cela est dû au fait que seuls les numéros de version majeure et mineure sont alignés entre les packages de bibliothèque et les packages de déclaration de type. (Le `.9999` est utilisé pour s'assurer que les packages locaux `@types` sont toujours les plus récents pendant le développement local.)
+Le numéro de version patch du package de déclaration de type (par exemple `.0` dans `20.8.0`) est initialisé à zéro par Definitely Typed et est incrémenté chaque fois qu'un nouveau package `@types/node` est publié sur npm pour la même version majeure/mineure de la bibliothèque correspondante.
-Il arrive que les versions des paquets de déclarations de type et les versions des paquets de bibliothèques ne soient pas synchronisées.
-Voici quelques raisons courantes, classées par ordre de gêne pour les utilisateurs d'une bibliothèque.
+Parfois, les versions des packages de déclaration de type et des packages de bibliothèque peuvent être désynchronisées.
+Voici quelques raisons courantes pour lesquelles cela peut se produire, classées par ordre de gêne pour les utilisateurs d'une bibliothèque.
Seul le dernier cas est généralement problématique.
-- Comme indiqué ci-dessus, la version du patch du paquet de déclaration de type n'est pas liée à la version du patch de la bibliothèque.
- Cela permet à Definitely Typed de mettre à jour en toute sécurité les déclarations de types pour la même version majeure/mineure d'une bibliothèque.
-- Si vous mettez à jour un paquet pour une nouvelle fonctionnalité, n'oubliez pas de mettre à jour le numéro de version pour qu'il corresponde à la version de la bibliothèque.
- Si les utilisateurs s'assurent que les versions correspondent entre les paquets JavaScript et leurs paquets `@types` respectifs, alors `npm update` devrait fonctionner.
-- Il est fréquent que les mises à jour des paquets de déclarations de types soient en retard par rapport aux mises à jour des bibliothèques, car ce sont souvent les utilisateurs des bibliothèques, et non les mainteneurs, qui mettent à jour Definitely Typed lorsque de nouvelles fonctionnalités des bibliothèques sont publiées.
- Il peut donc y avoir un décalage de plusieurs jours, semaines ou même mois avant qu'un membre utile de la communauté n'envoie un PR pour mettre à jour le paquet de déclaration de type pour une nouvelle version de la bibliothèque.
- Si vous êtes affecté par cela, vous pouvez être le changement que vous voulez voir dans le monde et vous pouvez être ce membre utile de la communauté !
+- Comme indiqué ci-dessus, la version patch du package de déclaration de type est indépendante de la version patch de la bibliothèque.
+ Cela permet à Definitely Typed de mettre à jour en toute sécurité les déclarations de type pour la même version majeure/mineure d'une bibliothèque.
+- Si vous mettez à jour un package pour de nouvelles fonctionnalités, n'oubliez pas de mettre à jour le numéro de version pour qu'il corresponde à cette version de la bibliothèque.
+ Si les utilisateurs s'assurent que les versions correspondent entre les packages JavaScript et leurs packages `@types` respectifs, alors `npm update` devrait généralement fonctionner correctement.
+- Il est courant que les mises à jour des packages de déclaration de type soient en retard par rapport aux mises à jour des bibliothèques, car ce sont souvent les utilisateurs des bibliothèques, et non les mainteneurs, qui mettent à jour Definitely Typed lorsque de nouvelles fonctionnalités de bibliothèque sont publiées.
+ Il peut donc y avoir un décalage de quelques jours, semaines ou même mois avant qu'un membre de la communauté n'envoie une PR pour mettre à jour le package de déclaration de type pour une nouvelle version de la bibliothèque.
+ Si cela vous impacte, vous pouvez être le changement que vous voulez voir dans le monde et être ce membre de la communauté utile !
-:exclamation: Si vous mettez à jour les déclarations de type pour une bibliothèque, mettez toujours la version `major.minor` dans la première ligne de `index.d.ts` pour qu'elle corresponde à la version de la bibliothèque que vous documentez ! :exclamation:
+:exclamation: Si vous mettez à jour les déclarations de type pour une bibliothèque, définissez toujours la version `major.minor` dans `package.json` pour qu'elle corresponde à la version de la bibliothèque que vous documentez ! :exclamation:
-#### Si une bibliothèque est mise à jour vers une nouvelle version majeure comportant des changements importants, comment dois-je mettre à jour son paquet de déclarations de types ?
+#### Si une bibliothèque est mise à jour vers une nouvelle version majeure comportant des changements importants, comment dois-je mettre à jour son package de déclarations de types ?
-Le [Semantic versioning](https://semver.org/) requiert que les versions avec des changements importants doivent incrémenter le numéro de la version majeure.
-Par exemple, une bibliothèque qui supprime une fonction exportée publiquement après sa version `3.5.8` doit augmenter sa version à `4.0.0` dans sa prochaine version.
-De plus, lorsque la version `4.0.0` de la bibliothèque est sortie, son paquet Definitely Typed Type Declaration doit aussi être mis à jour en `4.0.0`, en incluant tous leschangements importants dans l'API de la bibliothèque.
+[La gestion sémantique des versions](https://semver.org/) exige que les versions avec des changements majeurs doivent incrémenter le numéro de version majeure.
+Par exemple, une bibliothèque qui supprime une fonction exportée publiquement après sa version `3.5.8` doit passer à la version `4.0.0` lors de sa prochaine publication.
+De plus, lorsque la version `4.0.0` de la bibliothèque est publiée, le package de déclarations de type Definitely Typed doit également être mis à jour à `4.0.0`, y compris tous les changements majeurs de l'API de la bibliothèque.
-De nombreuses bibliothèques disposent d'une large base installée de développeurs (y compris les responsables d'autres paquets utilisant cette bibliothèque comme dépendance) qui ne passeront pas immédiatement à une nouvelle version comportant des changements radicaux, car il peut s'écouler des mois avant qu'un responsable n'ait le temps de réécrire le code pour l'adapter à la nouvelle version.
-En attendant, les utilisateurs des anciennes versions de la bibliothèque peuvent toujours vouloir mettre à jour les déclarations de type pour les anciennes versions.
+De nombreuses bibliothèques ont une grande base d'utilisateurs (y compris les mainteneurs d'autres packages utilisant cette bibliothèque comme dépendance) qui ne passeront pas immédiatement à une nouvelle version avec des changements majeurs, car il peut s'écouler des mois avant qu'un mainteneur ait le temps de réécrire le code pour s'adapter à la nouvelle version.
+En attendant, les utilisateurs des anciennes versions de la bibliothèque peuvent toujours vouloir mettre à jour les déclarations de type pour les versions plus anciennes.
-Si vous avez l'intention de continuer à mettre à jour l'ancienne version des déclarations de types d'une bibliothèque, vous pouvez créer un nouveau sous-dossier (par exemple `/v2/`) nommé pour la version actuelle (bientôt "ancienne"), et copier les fichiers existants de la version actuelle dans ce sous-dossier.
+Si vous avez l'intention de continuer à mettre à jour les déclarations de type de l'ancienne version d'une bibliothèque, vous pouvez créer un nouveau sous-dossier (par exemple `/v2/`) nommé d'après la version actuelle (bientôt "ancienne") et y copier les fichiers existants de la version actuelle.
-Comme le dossier racine doit toujours contenir les déclarations de type de la dernière ("nouvelle") version, vous devrez apporter quelques modifications aux fichiers de votre sous-répertoire de l'ancienne version pour vous assurer que les références de chemin relatif pointent vers le sous-répertoire, et non vers la racine.
+Lors de la création d'un nouveau dossier de version, assurez-vous que le champ version de `package.json` a été mis à jour ; `pnpm` résoudra automatiquement ce package versionné chaque fois que nécessaire. Si d'autres packages dans le dépôt doivent dépendre de cette nouvelle version, assurez-vous que leurs `package.json` soient également mis à jour.
-1. Mise à jour des chemins relatifs dans `tsconfig.json` ainsi que dans `tslint.json`.
-2. Ajouter des règles de correspondance des chemins pour s'assurer que les tests s'exécutent avec la version prévue.
+Par exemple, si nous créons `types/history/v2`, son `package.json` ressemblerait à ceci :
+
+```json
+{
+ "private": true,
+ "name": "@types/history",
+ "version": "2.4.9999"
+}
+```
-Par exemple, la bibliothèque [`history`](https://github.com/ReactTraining/history/) a introduit des changements entre les versions `2.x` et `3.x`.
-Parce que beaucoup d'utilisateurs consomment encore l'ancienne version `2.x`, un mainteneur qui voulait mettre à jour les déclarations de type pour cette bibliothèque vers `3.x` a ajouté un dossier `v2` dans le référentiel history qui contient les déclarations de type pour l'ancienne version.
-Au moment où j'écris ces lignes, le dossier [history v2 `tsconfig.json`](https://github.com/%44efinitelyTyped/DefinitelyTyped/blob/1253faabf5e0d2c5470db6ea87795d7f96fef7e2/types/history/v2/tsconfig.json) ressemble à peu près à ceci :
+Un autre package peut sélectionner cette version en spécifiant :
```json
{
- "compilerOptions": {
- "baseUrl": "../../",
- "typeRoots": ["../../"],
- "paths": {
- "history": ["history/v2"]
- }
- },
- "files": [
- "index.d.ts",
- "history-tests.ts"
- ]
+ "private": true,
+ "name": "@types/browser-sync",
+ "version": "2.26.9999",
+ "dependencies": {
+ "@types/history": "^2"
+ }
}
```
-S'il y a d'autres paquets dans Definitely Typed qui sont incompatibles avec la nouvelle version, vous devrez ajouter des correspondances de chemin vers l'ancienne version.
-Vous devrez aussi le faire récursivement pour les paquets qui dépendent de l'ancienne version.
+De plus, `/// ` ne fonctionnera pas avec le mappage de chemin, donc les dépendances doivent utiliser `import`.
-Par exemple, `browser-sync` dépend de `micromatch@2`, donc [browser-sync `tsconfig.json`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/browser-sync/tsconfig.json) a un chemin vers `"micromatch" : ["micromatch/v2" ]`.
-Transitivement, `browser-sync-webpack-plugin` (qui dépend de `browser-sync`) avait aussi besoin d'ajouter le même chemin (`"micromatch" : [ "micromatch/v2" ]`) dans son `tsconfig.json` jusqu'à ce que sa dépendance `browser-sync` soit mise à jour vers la dernière version.
+#### Comment fonctionnent les changements de type majeurs si les packages de déclaration de type suivent de près la version du package de la bibliothèque ?
-De plus, `/// ` ne fonctionnera pas avec la correspondance des chemins, donc les dépendances doivent utiliser `import`.
+Les packages `@types` typent toujours les packages de la même version, donc `@types/foo@5.4.x` sont pour `foo@5.4.x`.
+En conséquence, tous les changements, qu'ils soient majeurs ou non, sont publiés en tant que révisions de correctifs, sauf s'ils sont accompagnés d'une augmentation majeure/mineure pour changer la version du package ciblé (coïncidence ou non).
-#### Comment puis-je écrire des définitions pour des paquets qui peuvent être utilisés globalement et en tant que module ?
+En ce qui concerne les changements majeurs, les mainteneurs de DT prennent en compte la popularité du package, les avantages du changement proposé, l'effort nécessaire pour que les utilisateurs corrigent leur code, et si le changement pourrait raisonnablement être retardé jusqu'à ce qu'il puisse être synchronisé avec une augmentation majeure de la bibliothèque en amont.
+
+#### Comment puis-je écrire des définitions pour des packages qui peuvent être utilisés globalement et en tant que module ?
Le manuel TypeScript contient d'excellentes [informations générales sur l'écriture de définitions](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html), ainsi que [cet exemple de fichier de définition](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html) qui montre comment créer une définition en utilisant la syntaxe de module de style ES6, tout en spécifiant également les objets mis à la disposition de la portée globale. Cette technique est démontrée en pratique dans la [définition de `big.js`](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/big.js/index.d.ts), qui est une bibliothèque qui peut être chargée globalement via une balise script sur une page web, ou importée via require ou des importations de style ES6.
@@ -630,21 +781,9 @@ Pour tester comment votre définition peut être utilisée à la fois lorsqu'ell
Il suffit de tester uniquement les éléments accessibles globalement dans le fichier de test global et d'exercer pleinement la définition dans le fichier de test du module, ou vice versa.
-#### Qu'en est-il des paquets délimités ?
-
-Les types pour un paquetage scopé `@foo/bar` devraient aller dans `types/foo__bar`. Notez le double trait de soulignement.
-
-Quand `dts-gen` est utilisé pour échafauder un paquet scopé, la propriété `paths` doit être adaptée manuellement dans le `tsconfig.json` généré pour référencer correctement le paquet scopé :
+#### Qu'en est-il des packages scopés ?
-```json
-{
- "compilerOptions": {
- "paths": {
- "@foo/*": ["foo__*"]
- }
- }
-}
-```
+Les types pour un package avec un scope `@foo/bar` doivent être placés dans `types/foo__bar`. Notez le double underscore.
## Licence
diff --git a/types/async-alpine/.npmignore b/types/async-alpine/.npmignore
new file mode 100644
index 00000000000000..93e307400a5456
--- /dev/null
+++ b/types/async-alpine/.npmignore
@@ -0,0 +1,5 @@
+*
+!**/*.d.ts
+!**/*.d.cts
+!**/*.d.mts
+!**/*.d.*.ts
diff --git a/types/async-alpine/async-alpine-tests.ts b/types/async-alpine/async-alpine-tests.ts
new file mode 100644
index 00000000000000..a127c451516f27
--- /dev/null
+++ b/types/async-alpine/async-alpine-tests.ts
@@ -0,0 +1,47 @@
+/**
+ * Typescript definition tests for async-alpine module
+ *
+ * Note: These tests are intended to test the definitions only
+ * in the sense of typing and call signature consistency. They
+ * are not intended as functional tests.
+ */
+
+import Alpine, { type DirectiveCallback } from "alpinejs";
+import AsyncAlpine, { type AlpineAsyncOptions } from "async-alpine";
+
+// init plugin
+Alpine.plugin(AsyncAlpine);
+
+// setup options
+const options: AlpineAsyncOptions = {
+ defaultStrategy: "idle",
+ keepRelativeURLs: false,
+};
+Alpine.asyncOptions(options);
+
+// listen plugin events
+window.addEventListener("async-alpine:load", (event) => {
+ console.log("async-alpine:load", event.detail.id);
+});
+
+// usage: data
+Alpine.asyncData(
+ "myComponent",
+ () => import("./async-alpine_async-component-tests.js"),
+);
+
+// usage: url
+Alpine.asyncUrl("myComponent", "./async-alpine_async-component-tests.ts");
+
+// usage: alias
+Alpine.asyncAlias("./[name].ts");
+Alpine.asyncAlias((name) => import(`/${name}.ts`));
+
+// directive with async data
+function directive(): DirectiveCallback {
+ return (el) => {
+ el._x_async = "init";
+ el._x_async = undefined;
+ };
+}
+directive();
diff --git a/types/async-alpine/async-alpine_async-component-tests.ts b/types/async-alpine/async-alpine_async-component-tests.ts
new file mode 100644
index 00000000000000..7db73659274d4c
--- /dev/null
+++ b/types/async-alpine/async-alpine_async-component-tests.ts
@@ -0,0 +1,13 @@
+interface ComponentState {
+ message: string;
+ init(): void;
+}
+
+export default function myComponent(): ComponentState {
+ return {
+ message: "",
+ init() {
+ this.message = "my component has initialised!";
+ },
+ };
+}
diff --git a/types/async-alpine/index.d.ts b/types/async-alpine/index.d.ts
new file mode 100644
index 00000000000000..0431ef4a7ddbdc
--- /dev/null
+++ b/types/async-alpine/index.d.ts
@@ -0,0 +1,31 @@
+import type { AlpineComponent, PluginCallback } from "alpinejs";
+
+declare global {
+ interface WindowEventMap {
+ "async-alpine:load": CustomEvent<{ id: string }>;
+ }
+}
+
+export interface AlpineAsyncOptions {
+ defaultStrategy?: "eager" | "idle" | "visible" | string;
+ keepRelativeURLs?: boolean;
+}
+
+declare module "alpinejs" {
+ interface Alpine {
+ asyncOptions(opts: AlpineAsyncOptions): void;
+ asyncData(
+ name: string,
+ download: (name: string) => AlpineComponent,
+ ): void;
+ asyncUrl(name: string, url: string): void;
+ asyncAlias(path: string | ((name: string) => any)): void;
+ }
+
+ interface XAttributes {
+ _x_async: "init" | "await" | "loaded";
+ }
+}
+
+declare const asyncAlpinePlugin: PluginCallback;
+export default asyncAlpinePlugin;
diff --git a/types/async-alpine/package.json b/types/async-alpine/package.json
new file mode 100644
index 00000000000000..65d64de8bec18b
--- /dev/null
+++ b/types/async-alpine/package.json
@@ -0,0 +1,21 @@
+{
+ "private": true,
+ "type": "module",
+ "name": "@types/async-alpine",
+ "version": "2.0.9999",
+ "projects": [
+ "https://github.com/Accudio/async-alpine"
+ ],
+ "dependencies": {
+ "@types/alpinejs": "*"
+ },
+ "devDependencies": {
+ "@types/async-alpine": "workspace:."
+ },
+ "owners": [
+ {
+ "name": "Bastien Robert",
+ "githubUsername": "bastienrobert"
+ }
+ ]
+}
diff --git a/types/async-alpine/tsconfig.json b/types/async-alpine/tsconfig.json
new file mode 100644
index 00000000000000..6aedcbc1c7a884
--- /dev/null
+++ b/types/async-alpine/tsconfig.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "module": "node16",
+ "lib": [
+ "es6",
+ "dom"
+ ],
+ "noImplicitAny": true,
+ "noImplicitThis": true,
+ "strictNullChecks": false,
+ "strictFunctionTypes": true,
+ "types": [],
+ "noEmit": true,
+ "forceConsistentCasingInFileNames": true
+ },
+ "files": [
+ "index.d.ts",
+ "async-alpine-tests.ts",
+ "async-alpine_async-component-tests.ts"
+ ]
+}
diff --git a/types/chrome/index.d.ts b/types/chrome/index.d.ts
index d5553e34aa8797..25b384d1d96475 100644
--- a/types/chrome/index.d.ts
+++ b/types/chrome/index.d.ts
@@ -14,7 +14,8 @@ declare namespace chrome {
// Accessibility Features
////////////////////
/**
- * Use the chrome.accessibilityFeatures API to manage Chrome's accessibility features. This API relies on the ChromeSetting prototype of the type API for getting and setting individual accessibility features. In order to get feature states the extension must request `accessibilityFeatures.read` permission. For modifying feature state, the extension needs `accessibilityFeatures.modify` permission. Note that `accessibilityFeatures.modify` does not imply `accessibilityFeatures.read` permission.
+ * Use the `chrome.accessibilityFeatures` API to manage Chrome's accessibility features. This API relies on the ChromeSetting prototype of the type API for getting and setting individual accessibility features. In order to get feature states the extension must request `accessibilityFeatures.read` permission. For modifying feature state, the extension needs `accessibilityFeatures.modify` permission. Note that `accessibilityFeatures.modify` does not imply `accessibilityFeatures.read` permission.
+ *
* Permissions: "accessibilityFeatures.read", "accessibilityFeatures.modify"
*/
export namespace accessibilityFeatures {
@@ -139,9 +140,11 @@ declare namespace chrome {
// Action
////////////////////
/**
- * Use the chrome.action API to control the extension's icon in the Google Chrome toolbar.
+ * Use the `chrome.action` API to control the extension's icon in the Google Chrome toolbar.
+ * The action icons are displayed in the browser toolbar next to the omnibox. After installation, these appear in the extensions menu (the puzzle piece icon). Users can pin your extension icon to the toolbar.
+ *
+ * Manifest: "action"
* @since Chrome 88, MV3
- * Manifest: "action": {...}
*/
export namespace action {
/** @deprecated Use BadgeColorDetails instead. */
@@ -444,9 +447,9 @@ declare namespace chrome {
// Alarms
////////////////////
/**
- * Use the chrome.alarms API to schedule code to run periodically or at a specified time in the future.
- * @since Chrome 22
- * Permissions: "alarms"
+ * Use the `chrome.alarms` API to schedule code to run periodically or at a specified time in the future.
+ *
+ * Permissions: "alarms"
*/
export namespace alarms {
export interface AlarmCreateInfo {
@@ -570,11 +573,9 @@ declare namespace chrome {
// Audio
////////////////////
/**
- * The chrome.audio API is provided to allow users to get information about and control the audio devices attached to the system.
- * This API is currently only available in kiosk mode for ChromeOS.
+ * The `chrome.audio` API is provided to allow users to get information about and control the audio devices attached to the system. This API is currently only available in kiosk mode for ChromeOS.
*
* Permissions: "audio"
- *
* @platform ChromeOS only
* @since Chrome 59
*/
@@ -758,9 +759,9 @@ declare namespace chrome {
// Bookmarks
////////////////////
/**
- * Use the chrome.bookmarks API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page.
- * @since Chrome 5
- * Permissions: "bookmarks"
+ * Use the `chrome.bookmarks` API to create, organize, and otherwise manipulate bookmarks. Also see Override Pages, which you can use to create a custom Bookmark Manager page.
+ *
+ * Permissions: "bookmarks"
*/
export namespace bookmarks {
/** A node (either a bookmark or a folder) in the bookmark tree. Child nodes are ordered within their parent folder. */
@@ -1030,9 +1031,11 @@ declare namespace chrome {
// Browser Action
////////////////////
/**
- * Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can also have a tooltip, a badge, and a popup.
- * @since Chrome 5
- * Manifest: "browser_action": {...}
+ * Use browser actions to put icons in the main Google Chrome toolbar, to the right of the address bar. In addition to its icon, a browser action can have a tooltip, a badge, and a popup.
+ *
+ * Manifest: "browser_action"
+ *
+ * MV2 only
*/
export namespace browserAction {
export interface BadgeBackgroundColorDetails {
@@ -1209,9 +1212,9 @@ declare namespace chrome {
// Browsing Data
////////////////////
/**
- * Use the chrome.browsingData API to remove browsing data from a user's local profile.
- * @since Chrome 19
- * Permissions: "browsingData"
+ * Use the `chrome.browsingData` API to remove browsing data from a user's local profile.
+ *
+ * Permissions: "browsingData"
*/
export namespace browsingData {
export interface OriginTypes {
@@ -1484,8 +1487,8 @@ declare namespace chrome {
////////////////////
/**
* Use the commands API to add keyboard shortcuts that trigger actions in your extension, for example, an action to open the browser action or send a command to the extension.
- * @since Chrome 25
- * Manifest: "commands": {...}
+ *
+ * Manifest: "commands"
*/
export namespace commands {
export interface Command {
@@ -1518,9 +1521,9 @@ declare namespace chrome {
// Content Settings
////////////////////
/**
- * Use the chrome.contentSettings API to change settings that control whether websites can use features such as cookies, JavaScript, and plugins. More generally speaking, content settings allow you to customize Chrome's behavior on a per-site basis instead of globally.
- * @since Chrome 16
- * Permissions: "contentSettings"
+ * Use the `chrome.contentSettings` API to change settings that control whether websites can use features such as cookies, JavaScript, and plugins. More generally speaking, content settings allow you to customize Chrome's behavior on a per-site basis instead of globally.
+ *
+ * Permissions: "contentSettings"
*/
export namespace contentSettings {
type ScopeEnum = "regular" | "incognito_session_only";
@@ -1843,9 +1846,9 @@ declare namespace chrome {
// Context Menus
////////////////////
/**
- * Use the chrome.contextMenus API to add items to Google Chrome's context menu. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages.
- * @since Chrome 6
- * Permissions: "contextMenus"
+ * Use the `chrome.contextMenus` API to add items to Google Chrome's context menu. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages.
+ *
+ * Permissions: "contextMenus"
*/
export namespace contextMenus {
export interface OnClickData {
@@ -2046,9 +2049,11 @@ declare namespace chrome {
// Cookies
////////////////////
/**
- * Use the chrome.cookies API to query and modify cookies, and to be notified when they change.
- * @since Chrome 6
- * Permissions: "cookies", host permissions
+ * Use the `chrome.cookies` API to query and modify cookies, and to be notified when they change.
+ *
+ * Permissions: "cookies"
+ *
+ * Manifest: "host_permissions"
*/
export namespace cookies {
/** A cookie's 'SameSite' state (https://tools.ietf.org/html/draft-west-first-party-cookies). 'no_restriction' corresponds to a cookie set with 'SameSite=None', 'lax' to 'SameSite=Lax', and 'strict' to 'SameSite=Strict'. 'unspecified' corresponds to a cookie set without the SameSite attribute. **/
@@ -2255,9 +2260,9 @@ declare namespace chrome {
// Debugger
////////////////////
/**
- * The chrome.debugger API serves as an alternate transport for Chrome's remote debugging protocol. Use chrome.debugger to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, etc. Use the Debuggee tabId to target tabs with sendCommand and route events by tabId from onEvent callbacks.
- * @since Chrome 18
- * Permissions: "debugger"
+ * The `chrome.debugger` API serves as an alternate transport for Chrome's remote debugging protocol. Use `chrome.debugger` to attach to one or more tabs to instrument network interaction, debug JavaScript, mutate the DOM and CSS, and more. Use the {@link Debuggee} `tabId` to target tabs with `sendCommand` and route events by `tabId` from `onEvent` callbacks.
+ *
+ * Permissions: "debugger"
*/
export namespace _debugger {
/** Debuggee identifier. Either tabId or extensionId must be specified */
@@ -2390,13 +2395,14 @@ declare namespace chrome {
}
export { _debugger as debugger };
+
////////////////////
// Declarative Content
////////////////////
/**
- * Use the chrome.declarativeContent API to take actions depending on the content of a page, without requiring permission to read the page's content.
- * @since Chrome 33
- * Permissions: "declarativeContent"
+ * Use the `chrome.declarativeContent` API to take actions depending on the content of a page, without requiring permission to read the page's content.
+ *
+ * Permissions: "declarativeContent"
*/
export namespace declarativeContent {
export interface PageStateUrlDetails {
@@ -2486,6 +2492,14 @@ declare namespace chrome {
////////////////////
// Declarative Web Request
////////////////////
+ /**
+ * Use the `chrome.declarativeWebRequest` API to intercept, block, or modify requests in-flight. It is significantly faster than the chrome.webRequest API because you can register rules that are evaluated in the browser rather than the JavaScript engine, which reduces roundtrip latencies and allows higher efficiency.
+ *
+ * Permissions: "declarativeWebRequest"
+ *
+ * MV2 only
+ * @deprecated Check out the {@link declarativeNetRequest} API instead
+ */
export namespace declarativeWebRequest {
export interface HeaderFilter {
nameEquals?: string | undefined;
@@ -2596,9 +2610,9 @@ declare namespace chrome {
// DesktopCapture
////////////////////
/**
- * Desktop Capture API that can be used to capture content of screen, individual windows or tabs.
- * @since Chrome 34
- * Permissions: "desktopCapture"
+ * The Desktop Capture API captures the content of the screen, individual windows, or individual tabs.
+ *
+ * Permissions: "desktopCapture"
*/
export namespace desktopCapture {
/** Contains properties that describe the stream. */
@@ -2637,8 +2651,9 @@ declare namespace chrome {
// Dev Tools - Inspected Window
////////////////////
/**
- * Use the chrome.devtools.inspectedWindow API to interact with the inspected window: obtain the tab ID for the inspected page, evaluate the code in the context of the inspected window, reload the page, or obtain the list of resources within the page.
- * @since Chrome 18
+ * Use the `chrome.devtools.inspectedWindow` API to interact with the inspected window: obtain the tab ID for the inspected page, evaluate the code in the context of the inspected window, reload the page, or obtain the list of resources within the page.
+ *
+ * Manifest: "devtools_page"
*/
export namespace devtools.inspectedWindow {
/** A resource within the inspected page, such as a document, a script, or an image. */
@@ -2765,8 +2780,9 @@ declare namespace chrome {
// Dev Tools - Network
////////////////////
/**
- * Use the chrome.devtools.network API to retrieve the information about network requests displayed by the Developer Tools in the Network panel.
- * @since Chrome 18
+ * Use the `chrome.devtools.network` API to retrieve the information about network requests displayed by the Developer Tools in the Network panel.
+ *
+ * Manifest: "devtools_page"
*/
export namespace devtools.network {
/** Represents a HAR entry for a specific finished request. */
@@ -2810,8 +2826,8 @@ declare namespace chrome {
// Dev Tools - Performance
////////////////////
/**
- * The chrome.devtools.performance API allows developers to interact with the recording features of the Performance panel in Chrome DevTools. You can use this API to get notifications when recording starts or stops.
- * @since Chrome 128
+ * Use the `chrome.devtools.performance` API to listen to recording status updates in the Performance panel in DevTools.
+ * @since Chrome 129
*/
export namespace devtools.performance {
export interface ProfilingStartedEvent extends chrome.events.Event<() => void> {}
@@ -2828,8 +2844,9 @@ declare namespace chrome {
// Dev Tools - Panels
////////////////////
/**
- * Use the chrome.devtools.panels API to integrate your extension into Developer Tools window UI: create your own panels, access existing panels, and add sidebars.
- * @since Chrome 18
+ * Use the `chrome.devtools.panels` API to integrate your extension into Developer Tools window UI: create your own panels, access existing panels, and add sidebars.
+ *
+ * Manifest: "devtools_page"
*/
export namespace devtools.panels {
export interface PanelShownEvent extends chrome.events.Event<(window: Window) => void> {}
@@ -3022,10 +3039,12 @@ declare namespace chrome {
// Document Scan
////////////////////
/**
- * Use the chrome.documentScan API to discover and retrieve images from attached paper document scanners.
+ * Use the `chrome.documentScan` API to discover and retrieve images from attached document scanners.
+ * The Document Scan API is designed to allow apps and extensions to view the content of paper documents on an attached document scanner.
+ *
+ * Permissions: "documentScan"
+ * @platform ChromeOS only
* @since Chrome 44
- * Permissions: "documentScan"
- * Important: This API works only on Chrome OS.
*/
export namespace documentScan {
export interface DocumentScanOptions {
@@ -3054,7 +3073,7 @@ declare namespace chrome {
// DOM
////////////////////
/**
- * Use the chrome.dom API to programmatically access shadow root in an HTMLElement.
+ * Use the `chrome.dom` API to access special DOM APIs for Extensions
* @since Chrome 88
*/
export namespace dom {
@@ -3067,12 +3086,12 @@ declare namespace chrome {
}
////////////////////
- // Dev Tools - Downloads
+ // Downloads
////////////////////
/**
- * Use the chrome.downloads API to programmatically initiate, monitor, manipulate, and search for downloads.
- * @since Chrome 31
- * Permissions: "downloads"
+ * Use the `chrome.downloads` API to programmatically initiate, monitor, manipulate, and search for downloads.
+ *
+ * Permissions: "downloads"
*/
export namespace downloads {
export interface HeaderNameValuePair {
@@ -3472,11 +3491,12 @@ declare namespace chrome {
// Enterprise Platform Keys
////////////////////
/**
- * Use the chrome.enterprise.platformKeys API to generate hardware-backed keys and to install certificates for these keys. The certificates will be managed by the platform and can be used for TLS authentication, network access or by other extension through chrome.platformKeys.
- * @since Chrome 37
- * Permissions: "enterprise.platformKeys"
- * Important: This API works only on Chrome OS.
- * Note: This API is only for extensions pre-installed by policy.
+ * Use the `chrome.enterprise.platformKeys` API to generate keys and install certificates for these keys. The certificates will be managed by the platform and can be used for TLS authentication, network access or by other extension through {@link chrome.platformKeys}.
+ *
+ * Permissions: "enterprise.platformKeys"
+ *
+ * Note: Only available to policy installed extensions.
+ * @platform ChromeOS only
*/
export namespace enterprise.platformKeys {
export interface Token {
@@ -3647,11 +3667,13 @@ declare namespace chrome {
// Enterprise Device Attributes
////////////////////
/**
- * Use the chrome.enterprise.deviceAttributes API to read device attributes.
- * Permissions: "enterprise.deviceAttributes"
+ * Use the `chrome.enterprise.deviceAttributes` API to read device attributes.
+ *
+ * Permissions: "enterprise.deviceAttributes"
+ *
+ * Note: Only available to policy installed extensions.
+ * @platform ChromeOS only
* @since Chrome 46
- * Important: This API works only on Chrome OS.
- * Note: This API is only for extensions pre-installed by policy.
*/
export namespace enterprise.deviceAttributes {
/**
@@ -3700,12 +3722,11 @@ declare namespace chrome {
// Enterprise Hardware Platform
////////////////////
/**
- * Use the chrome.enterprise.hardwarePlatform API to get the manufacturer and model of the hardware platform where the browser runs.
+ * Use the `chrome.enterprise.hardwarePlatform` API to get the manufacturer and model of the hardware platform where the browser runs.
*
* Permissions: "enterprise.hardwarePlatform"
*
- * Note: This API is only for extensions pre-installed by policy.
- * @platform ChromeOS only
+ * Note: Only available to policy installed extensions.
* @since Chrome 71
*/
export namespace enterprise.hardwarePlatform {
@@ -3726,8 +3747,12 @@ declare namespace chrome {
// Enterprise Networking Attributes
////////////////////
/**
- * Use the chrome.enterprise.networkingAttributes API to read information about your current network. Note: This API is only available to extensions force-installed by enterprise policy.
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.enterprise.networkingAttributes` API to read information about your current network. Note: This API is only available to extensions force-installed by enterprise policy.
+ *
+ * Permissions: "enterprise.networkingAttributes"
+ *
+ * Note: Only available to policy installed extensions.
+ * @platform ChromeOS only
* @since Chrome 85
*/
export namespace enterprise.networkingAttributes {
@@ -3751,8 +3776,7 @@ declare namespace chrome {
// Events
////////////////////
/**
- * The chrome.events namespace contains common types used by APIs dispatching events to notify you when something interesting happens.
- * @since Chrome 21
+ * The `chrome.events` namespace contains common types used by APIs dispatching events to notify you when something interesting happens.
*/
export namespace events {
/** Filters URLs for various criteria. See event filtering. All criteria are case sensitive. */
@@ -3893,8 +3917,7 @@ declare namespace chrome {
// Extension
////////////////////
/**
- * The chrome.extension API has utilities that can be used by any extension page. It includes support for exchanging messages between an extension and its content scripts or between extensions, as described in detail in Message Passing.
- * @since Chrome 5
+ * The `chrome.extension` API has utilities that can be used by any extension page. It includes support for exchanging messages between an extension and its content scripts or between extensions, as described in detail in Message Passing.
*/
export namespace extension {
export interface FetchProperties {
@@ -4014,10 +4037,10 @@ declare namespace chrome {
// File Browser Handler
////////////////////
/**
- * Use the chrome.fileBrowserHandler API to extend the Chrome OS file browser. For example, you can use this API to enable users to upload files to your website.
- * @since Chrome 12
- * Permissions: "fileBrowserHandler"
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.fileBrowserHandler` API to extend the Chrome OS file browser. For example, you can use this API to enable users to upload files to your website.
+ *
+ * Permissions: "fileBrowserHandler"
+ * @platform ChromeOS only
*/
export namespace fileBrowserHandler {
export interface SelectionParams {
@@ -4067,10 +4090,10 @@ declare namespace chrome {
// File System Provider
////////////////////
/**
- * Use the chrome.fileSystemProvider API to create file systems, that can be accessible from the file manager on Chrome OS.
- * @since Chrome 40
- * Permissions: "fileSystemProvider"
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.fileSystemProvider` API to create file systems, that can be accessible from the file manager on Chrome OS.
+ *
+ * Permissions: "fileSystemProvider"
+ * @platform ChromeOS only
*/
export namespace fileSystemProvider {
export interface OpenedFileInfo {
@@ -4599,9 +4622,9 @@ declare namespace chrome {
// Font Settings
////////////////////
/**
- * Use the chrome.fontSettings API to manage Chrome's font settings.
- * @since Chrome 22
- * Permissions: "fontSettings"
+ * Use the `chrome.fontSettings` API to manage Chrome's font settings.
+ *
+ * Permissions: "fontSettings"
*/
export namespace fontSettings {
/** Represents a font name. */
@@ -4824,9 +4847,9 @@ declare namespace chrome {
// Google Cloud Messaging
////////////////////
/**
- * Use chrome.gcm to enable apps and extensions to send and receive messages through the Google Cloud Messaging Service.
- * @since Chrome 35
- * Permissions: "gcm"
+ * Use `chrome.gcm` to enable apps and extensions to send and receive messages through Firebase Cloud Messaging (FCM).
+ *
+ * Permissions: "gcm"
*/
export namespace gcm {
export interface OutgoingMessage {
@@ -4906,9 +4929,9 @@ declare namespace chrome {
// History
////////////////////
/**
- * Use the chrome.history API to interact with the browser's record of visited pages. You can add, remove, and query for URLs in the browser's history. To override the history page with your own version, see Override Pages.
- * @since Chrome 5
- * Permissions: "history"
+ * Use the `chrome.history` API to interact with the browser's record of visited pages. You can add, remove, and query for URLs in the browser's history. To override the history page with your own version, see Override Pages.
+ *
+ * Permissions: "history"
*/
export namespace history {
/** An object encapsulating one visit to a URL. */
@@ -5040,8 +5063,9 @@ declare namespace chrome {
// i18n
////////////////////
/**
- * Use the chrome.i18n infrastructure to implement internationalization across your whole app or extension.
- * @since Chrome 5
+ * Use the `chrome.i18n` infrastructure to implement internationalization across your whole app or extension.
+ *
+ * Manifest: "default_locale"
*/
export namespace i18n {
/** Holds detected ISO language code and its percentage in the input string */
@@ -5103,9 +5127,9 @@ declare namespace chrome {
// Identity
////////////////////
/**
- * Use the chrome.identity API to get OAuth2 access tokens.
- * Permissions: "identity"
- * @since Chrome 29
+ * Use the `chrome.identity` API to get OAuth2 access tokens.
+ *
+ * Permissions: "identity"
*/
export namespace identity {
/** @since Chrome 32 */
@@ -5278,9 +5302,9 @@ declare namespace chrome {
// Idle
////////////////////
/**
- * Use the chrome.idle API to detect when the machine's idle state changes.
- * Permissions: "idle"
- * @since Chrome 6
+ * Use the `chrome.idle` API to detect when the machine's idle state changes.
+ *
+ * Permissions: "idle"
*/
export namespace idle {
export type IdleState = "active" | "idle" | "locked";
@@ -5321,9 +5345,10 @@ declare namespace chrome {
// Input - IME
////////////////////
/**
- * Use the chrome.input.ime API to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window.
- * Permissions: "input"
- * @since Chrome 21
+ * Use the `chrome.input.ime` API to implement a custom IME for Chrome OS. This allows your extension to handle keystrokes, set the composition, and manage the candidate window.
+ *
+ * Permissions: "input"
+ * @platform ChromeOS only
*/
export namespace input.ime {
/** See http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent */
@@ -5801,8 +5826,12 @@ declare namespace chrome {
export var onReset: InputResetEvent;
}
+ ////////////////////
+ // Instance ID
+ ////////////////////
/**
- * Use chrome.instanceID to access the Instance ID service.
+ * Use `chrome.instanceID` to access the Instance ID service.
+ *
* Permissions: "gcm"
* @since Chrome 44
*/
@@ -5885,10 +5914,11 @@ declare namespace chrome {
// LoginState
////////////////////
/**
- * Use the chrome.loginState API to read and monitor the login state.
+ * Use the `chrome.loginState` API to read and monitor the login state.
+ *
* Permissions: "loginState"
+ * @platform ChromeOS only
* @since Chrome 78
- * Important: This API works only on Chrome OS.
*/
export namespace loginState {
export interface SessionStateChangedEvent extends chrome.events.Event<(sessionState: SessionState) => void> {}
@@ -5913,9 +5943,9 @@ declare namespace chrome {
// Management
////////////////////
/**
- * The chrome.management API provides ways to manage the list of extensions/apps that are installed and running. It is particularly useful for extensions that override the built-in New Tab page.
- * Permissions: "management"
- * @since Chrome 8
+ * The `chrome.management` API provides ways to manage installed apps and extensions.
+ *
+ * Permissions: "management"
*/
export namespace management {
/** Information about an installed extension, app, or theme. */
@@ -6233,7 +6263,7 @@ declare namespace chrome {
}
////////////////////
- // Notifications
+ // Networking
////////////////////
/**
* Use the networking.config API to authenticate to captive portals.
@@ -6283,12 +6313,11 @@ declare namespace chrome {
////////////////////
// Notifications
- // https://developer.chrome.com/extensions/notifications
////////////////////
/**
- * Use the chrome.notifications API to create rich notifications using templates and show these notifications to users in the system tray.
- * Permissions: "notifications"
- * @since Chrome 28
+ * Use the `chrome.notifications` API to create rich notifications using templates and show these notifications to users in the system tray.
+ *
+ * Permissions: "notifications"
*/
export namespace notifications {
export type TemplateType = "basic" | "image" | "list" | "progress";
@@ -6472,9 +6501,10 @@ declare namespace chrome {
// Offscreen
////////////////////
/**
- * Use the offscreen API to create and manage offscreen documents.
- * @since Chrome 109, MV3
+ * Use the `offscreen` API to create and manage offscreen documents.
+ *
* Permissions: "offscreen"
+ * @since Chrome 109, MV3
*/
export namespace offscreen {
/** The reason(s) the extension is creating the offscreen document. */
@@ -6562,8 +6592,8 @@ declare namespace chrome {
////////////////////
/**
* The omnibox API allows you to register a keyword with Google Chrome's address bar, which is also known as the omnibox.
- * Manifest: "omnibox": {...}
- * @since Chrome 9
+ *
+ * Manifest: "omnibox"
*/
export namespace omnibox {
/** A suggest result. */
@@ -6626,9 +6656,11 @@ declare namespace chrome {
// Page Action
////////////////////
/**
- * Use the chrome.pageAction API to put icons inside the address bar. Page actions represent actions that can be taken on the current page, but that aren't applicable to all pages.
- * Manifest: "page_action": {...}
- * @since Chrome 5
+ * Use the `chrome.pageAction` API to put icons in the main Google Chrome toolbar, to the right of the address bar. Page actions represent actions that can be taken on the current page, but that aren't applicable to all pages. Page actions appear grayed out when inactive.
+ *
+ * Manifest: "page_action"
+ *
+ * MV2 only
*/
export namespace pageAction {
export interface PageActionClickedEvent extends chrome.events.Event<(tab: chrome.tabs.Tab) => void> {}
@@ -6717,9 +6749,9 @@ declare namespace chrome {
// Page Capture
////////////////////
/**
- * Use the chrome.pageCapture API to save a tab as MHTML.
- * Permissions: "pageCapture"
- * @since Chrome 18
+ * Use the `chrome.pageCapture` API to save a tab as MHTML.
+ *
+ * Permissions: "pageCapture"
*/
export namespace pageCapture {
export interface SaveDetails {
@@ -6744,8 +6776,7 @@ declare namespace chrome {
// Permissions
////////////////////
/**
- * Use the chrome.permissions API to request declared optional permissions at run time rather than install time, so users understand why the permissions are needed and grant only those that are necessary.
- * @since Chrome 16
+ * Use the `chrome.permissions` API to request declared optional permissions at run time rather than install time, so users understand why the permissions are needed and grant only those that are necessary.
*/
export namespace permissions {
export interface Permissions {
@@ -6798,9 +6829,10 @@ declare namespace chrome {
// Platform Keys
////////////////////
/**
- * Use the chrome.platformKeys API to access client certificates managed by the platform. If the user or policy grants the permission, an extension can use such a certficate in its custom authentication protocol. E.g. this allows usage of platform managed certificates in third party VPNs (see chrome.vpnProvider).
- * Permissions: "platformKeys"
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.platformKeys` API to access client certificates managed by the platform. If the user or policy grants the permission, an extension can use such a certficate in its custom authentication protocol. E.g. this allows usage of platform managed certificates in third party VPNs (see chrome.vpnProvider).
+ *
+ * Permissions: "platformKeys"
+ * @platform ChromeOS only
* @since Chrome 45
*/
export namespace platformKeys {
@@ -6896,9 +6928,9 @@ declare namespace chrome {
// Power
////////////////////
/**
- * Use the chrome.power API to override the system's power management features.
+ * Use the `chrome.power` API to override the system's power management features.
+ *
* Permissions: "power"
- * @since Chrome 27
*/
export namespace power {
export enum Level {
@@ -6928,8 +6960,9 @@ declare namespace chrome {
// Printer Provider
////////////////////
/**
- * The chrome.printerProvider API exposes events used by print manager to query printers controlled by extensions, to query their capabilities and to submit print jobs to these printers.
- * Permissions: "printerProvider"
+ * The `chrome.printerProvider` API exposes events used by print manager to query printers controlled by extensions, to query their capabilities and to submit print jobs to these printers.
+ *
+ * Permissions: "printerProvider"
* @since Chrome 44
*/
export namespace printerProvider {
@@ -6996,12 +7029,12 @@ declare namespace chrome {
// Printing
////////////////////
/**
- * Use the chrome.printing API to send print jobs to printers installed on Chromebook.
+ * Use the `chrome.printing` API to send print jobs to printers installed on Chromebook.
- * Permissions: "printing"
- * @platform ChromeOS only
- * @since Chrome 81
- */
+ * Permissions: "printing"
+ * @platform ChromeOS only
+ * @since Chrome 81
+ */
export namespace printing {
export interface GetPrinterInfoResponse {
/** Printer capabilities in [CDD format](https://developers.google.com/cloud-print/docs/cdd#cdd-example). The property may be missing. */
@@ -7149,11 +7182,11 @@ declare namespace chrome {
// Printing Metrics
////////////////////
/**
- * Use the chrome.printingMetrics API to fetch data about printing usage.
+ * Use the `chrome.printingMetrics` API to fetch data about printing usage.
*
* Permissions: "printingMetrics"
*
- * Note: This API is only for extensions pre-installed by policy.
+ * Note: Only available to policy installed extensions.
* @platform ChromeOS only
* @since Chrome 79
*/
@@ -7279,10 +7312,10 @@ declare namespace chrome {
// Privacy
////////////////////
/**
- * Use the chrome.privacy API to control usage of the features in Chrome that can affect a user's privacy. This API relies on the ChromeSetting prototype of the type API for getting and setting Chrome's configuration.
- * Permissions: "privacy"
- * The Chrome Privacy Whitepaper gives background detail regarding the features which this API can control.
- * @since Chrome 18
+ * Use the `chrome.privacy` API to control usage of the features in Chrome that can affect a user's privacy. This API relies on the ChromeSetting prototype of the type API for getting and setting Chrome's configuration.
+ * Note: The Chrome Privacy Whitepaper gives background detail regarding the features which this API can control.
+ *
+ * Permissions: "privacy"
*/
export namespace privacy {
/**
@@ -7342,9 +7375,9 @@ declare namespace chrome {
// Proxy
////////////////////
/**
- * Use the chrome.proxy API to manage Chrome's proxy settings. This API relies on the ChromeSetting prototype of the type API for getting and setting the proxy configuration.
- * Permissions: "proxy"
- * @since Chrome 13
+ * Use the `chrome.proxy` API to manage Chrome's proxy settings. This API relies on the ChromeSetting prototype of the type API for getting and setting the proxy configuration.
+ *
+ * Permissions: "proxy"
*/
export namespace proxy {
/** An object holding proxy auto-config information. Exactly one of the fields should be non-empty. */
@@ -7419,10 +7452,11 @@ declare namespace chrome {
// Search
////////////////////
/**
- * Use the chrome.search API to search via the default provider.
- * Permissions: "search"
+ * Use the `chrome.search` API to search via the default provider.
+ *
+ * Permissions: "search"
+ * @since Chrome 87
*/
-
export namespace search {
export type Disposition = "CURRENT_TAB" | "NEW_TAB" | "NEW_WINDOW";
@@ -7724,8 +7758,7 @@ declare namespace chrome {
// Runtime
////////////////////
/**
- * Use the chrome.runtime API to retrieve the background page, return details about the manifest, and listen for and respond to events in the app or extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.
- * @since Chrome 22
+ * Use the `chrome.runtime` API to retrieve the service worker, return details about the manifest, and listen for and respond to events in the extension lifecycle. You can also use this API to convert the relative path of URLs to fully-qualified URLs.
*/
export namespace runtime {
/** This will be defined during an API method callback if there was an error */
@@ -8600,7 +8633,8 @@ declare namespace chrome {
// Scripting
////////////////////
/**
- * Use the chrome.scripting API to execute script in different contexts.
+ * Use the `chrome.scripting` API to execute script in different contexts.
+ *
* Permissions: "scripting"
* @since Chrome 88, MV3
*/
@@ -8852,9 +8886,9 @@ declare namespace chrome {
// Sessions
////////////////////
/**
- * Use the chrome.sessions API to query and restore tabs and windows from a browsing session.
- * Permissions: "sessions"
- * @since Chrome 37
+ * Use the `chrome.sessions` API to query and restore tabs and windows from a browsing session.
+ *
+ * Permissions: "sessions"
*/
export namespace sessions {
export interface Filter {
@@ -8956,9 +8990,9 @@ declare namespace chrome {
// Storage
////////////////////
/**
- * Use the chrome.storage API to store, retrieve, and track changes to user data.
- * Permissions: "storage"
- * @since Chrome 20
+ * Use the `chrome.storage` API to store, retrieve, and track changes to user data.
+ *
+ * Permissions: "storage"
*/
export namespace storage {
/** NoInfer for old TypeScript versions */
@@ -9267,9 +9301,9 @@ declare namespace chrome {
// System CPU
////////////////////
/**
- * Use the system.cpu API to query CPU metadata.
+ * Use the `system.cpu` API to query CPU metadata.
+ *
* Permissions: "system.cpu"
- * @since Chrome 32
*/
export namespace system.cpu {
export interface ProcessorUsage {
@@ -9318,9 +9352,9 @@ declare namespace chrome {
// System Memory
////////////////////
/**
- * The chrome.system.memory API.
- * Permissions: "system.memory"
- * @since Chrome 32
+ * The `chrome.system.memory` API.
+ *
+ * Permissions: "system.memory"
*/
export namespace system.memory {
export interface MemoryInfo {
@@ -9344,9 +9378,9 @@ declare namespace chrome {
// System Storage
////////////////////
/**
- * Use the chrome.system.storage API to query storage device information and be notified when a removable storage device is attached and detached.
- * Permissions: "system.storage"
- * @since Chrome 30
+ * Use the `chrome.system.storage` API to query storage device information and be notified when a removable storage device is attached and detached.
+ *
+ * Permissions: "system.storage"
*/
export namespace system.storage {
export interface StorageUnitInfo {
@@ -9418,9 +9452,9 @@ declare namespace chrome {
// System Display //
////////////////////
/**
- * Use the system.display API to query display metadata.
+ * Use the `system.display` API to query display metadata.
+ *
* Permissions: "system.display"
- * @since Chrome 30
*/
export namespace system.display {
export enum LayoutPosition {
@@ -9896,11 +9930,11 @@ declare namespace chrome {
// SystemLog
////////////////////
/**
- * Use the chrome.systemLog API to record Chrome system logs from extensions.
+ * Use the `chrome.systemLog` API to record Chrome system logs from extensions.
*
* Permissions: "systemLog"
*
- * Note: This API is only for extensions pre-installed by policy.
+ * Note: Only available to policy installed extensions.
* @platform ChromeOS only
* @since Chrome 125
*/
@@ -9921,9 +9955,9 @@ declare namespace chrome {
// TabCapture
////////////////////
/**
- * Use the chrome.tabCapture API to interact with tab media streams.
- * Permissions: "tabCapture"
- * @since Chrome 31
+ * Use the `chrome.tabCapture` API to interact with tab media streams.
+ *
+ * Permissions: "tabCapture"
*/
export namespace tabCapture {
export interface CaptureInfo {
@@ -9990,9 +10024,9 @@ declare namespace chrome {
// Tabs
////////////////////
/**
- * Use the chrome.tabs API to interact with the browser's tab system. You can use this API to create, modify, and rearrange tabs in the browser.
+ * Use the `chrome.tabs` API to interact with the browser's tab system. You can use this API to create, modify, and rearrange tabs in the browser.
+ *
* Permissions: The majority of the chrome.tabs API can be used without declaring any permission. However, the "tabs" permission is required in order to populate the url, title, and favIconUrl properties of Tab.
- * @since Chrome 5
*/
export namespace tabs {
/**
@@ -10124,7 +10158,7 @@ declare namespace chrome {
*/
groupId: number;
/**
- * The last time the tab was accessed as the number of milliseconds since epoch.
+ * The last time the tab became active in its window as the number of milliseconds since epoch.
* @since Chrome 121
*/
lastAccessed?: number | undefined;
@@ -11224,8 +11258,9 @@ declare namespace chrome {
// Tab Groups
////////////////////
/**
- * Use the chrome.tabGroups API to interact with the browser's tab grouping system. You can use this API to modify and rearrange tab groups in the browser. To group and ungroup tabs, or to query what tabs are in groups, use the chrome.tabs API.
- * Permissions: "tabGroups"
+ * Use the `chrome.tabGroups` API to interact with the browser's tab grouping system. You can use this API to modify and rearrange tab groups in the browser. To group and ungroup tabs, or to query what tabs are in groups, use the `chrome.tabs` API.
+ *
+ * Permissions: "tabGroups"
* @since Chrome 89, MV3
*/
export namespace tabGroups {
@@ -11361,9 +11396,9 @@ declare namespace chrome {
// Top Sites
////////////////////
/**
- * Use the chrome.topSites API to access the top sites that are displayed on the new tab page.
- * Permissions: "topSites"
- * @since Chrome 19
+ * Use the `chrome.topSites` API to access the top sites (i.e. most visited sites) that are displayed on the new tab page. These do not include shortcuts customized by the user.
+ *
+ * Permissions: "topSites"
*/
export namespace topSites {
/** An object encapsulating a most visited URL, such as the URLs on the new tab page. */
@@ -11388,9 +11423,9 @@ declare namespace chrome {
// Text to Speech
////////////////////
/**
- * Use the chrome.tts API to play synthesized text-to-speech (TTS). See also the related ttsEngine API, which allows an extension to implement a speech engine.
- * Permissions: "tts"
- * @since Chrome 14
+ * Use the `chrome.tts` API to play synthesized text-to-speech (TTS). See also the related ttsEngine API, which allows an extension to implement a speech engine.
+ *
+ * Permissions: "tts"
*/
export namespace tts {
/** An event from the TTS engine to communicate the status of an utterance. */
@@ -11521,9 +11556,9 @@ declare namespace chrome {
// Text to Speech Engine
////////////////////
/**
- * Use the chrome.ttsEngine API to implement a text-to-speech(TTS) engine using an extension. If your extension registers using this API, it will receive events containing an utterance to be spoken and other parameters when any extension or Chrome App uses the tts API to generate speech. Your extension can then use any available web technology to synthesize and output the speech, and send events back to the calling function to report the status.
- * Permissions: "ttsEngine"
- * @since Chrome 14
+ * Use the `chrome.ttsEngine` API to implement a text-to-speech(TTS) engine using an extension. If your extension registers using this API, it will receive events containing an utterance to be spoken and other parameters when any extension or Chrome App uses the {@link tts} API to generate speech. Your extension can then use any available web technology to synthesize and output the speech, and send events back to the calling function to report the status.
+ *
+ * Permissions: "ttsEngine"
*/
export namespace ttsEngine {
export interface SpeakOptions {
@@ -11573,8 +11608,7 @@ declare namespace chrome {
// Types
////////////////////
/**
- * The chrome.types API contains type declarations for Chrome.
- * @since Chrome 13
+ * The `chrome.types` API contains type declarations for Chrome.
*/
export namespace types {
/**
@@ -11685,9 +11719,10 @@ declare namespace chrome {
// VPN Provider
////////////////////
/**
- * Use the chrome.vpnProvider API to implement a VPN client.
- * Permissions: "vpnProvider"
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.vpnProvider` API to implement a VPN client.
+ *
+ * Permissions: "vpnProvider"
+ * @platform ChromeOS only
* @since Chrome 43
*/
export namespace vpnProvider {
@@ -11776,9 +11811,10 @@ declare namespace chrome {
// Wallpaper
////////////////////
/**
- * Use the chrome.wallpaper API to change the ChromeOS wallpaper.
- * Permissions: "wallpaper"
- * Important: This API works only on Chrome OS.
+ * Use the `chrome.wallpaper` API to change the ChromeOS wallpaper.
+ *
+ * Permissions: "wallpaper"
+ * @platform ChromeOS only
* @since Chrome 43
*/
export namespace wallpaper {
@@ -11810,9 +11846,9 @@ declare namespace chrome {
// Web Navigation
////////////////////
/**
- * Use the chrome.webNavigation API to receive notifications about the status of navigation requests in-flight.
- * Permissions: "webNavigation"
- * @since Chrome 16
+ * Use the `chrome.webNavigation` API to receive notifications about the status of navigation requests in-flight.
+ *
+ * Permissions: "webNavigation"
*/
export namespace webNavigation {
export interface GetFrameDetails {
@@ -12023,9 +12059,11 @@ declare namespace chrome {
// Web Request
////////////////////
/**
- * Use the chrome.webRequest API to observe and analyze traffic and to intercept, block, or modify requests in-flight.
- * Permissions: "webRequest", host permissions
- * @since Chrome 17
+ * Use the `chrome.webRequest` API to observe and analyze traffic and to intercept, block, or modify requests in-flight.
+ *
+ * Permissions: "webRequest"
+ *
+ * Manifest: "host_permissions"
*/
export namespace webRequest {
interface WebRequestEvent
@@ -12433,9 +12471,9 @@ declare namespace chrome {
// Windows
////////////////////
/**
- * Use the chrome.windows API to interact with browser windows. You can use this API to create, modify, and rearrange windows in the browser.
+ * Use the `chrome.windows` API to interact with browser windows. You can use this API to create, modify, and rearrange windows in the browser.
+ *
* Permissions: The chrome.windows API can be used without declaring any permission. However, the "tabs" permission is required in order to populate the url, title, and favIconUrl properties of Tab objects.
- * @since Chrome 5
*/
export namespace windows {
export interface Window {
@@ -12768,6 +12806,17 @@ declare namespace chrome {
export var onBoundsChanged: WindowReferenceEvent;
}
+ ////////////////////
+ // declarativeNetRequest
+ ////////////////////
+ /**
+ * The `chrome.declarativeNetRequest` API is used to block or modify network requests by specifying declarative rules. This lets extensions modify network requests without intercepting them and viewing their content, thus providing more privacy.
+ *
+ * Permissions: "declarativeNetRequest", "declarativeNetRequestWithHostAccess", "declarativeNetRequestFeedback"
+ *
+ * Manifest: "host_permissions"
+ * @since Chrome 84
+ */
export namespace declarativeNetRequest {
/** Ruleset ID for the dynamic rules added by the extension. */
export const DYNAMIC_RULESET_ID: "_dynamic";
@@ -13596,9 +13645,10 @@ declare namespace chrome {
// SidePanel
////////////////////
/**
- * @since Chrome 114, MV3
- * https://developer.chrome.com/docs/extensions/reference/api/sidePanel
+ * Use the `chrome.sidePanel` API to host content in the browser's side panel alongside the main content of a webpage.
+ *
* Permissions: "sidePanel"
+ * @since Chrome 114, MV3
*/
export namespace sidePanel {
export interface GetPanelOptions {
@@ -13739,15 +13789,15 @@ declare namespace chrome {
): Promise;
}
- // Type definitions for chrome.userScripts API
-
+ ////////////////////
+ // User Scripts
+ ////////////////////
/**
- * Availability: Chrome 120 beta. Manifest v3.
- * https://developer.chrome.com/docs/extensions/reference/api/userScripts
+ * Use the `userScripts` API to execute user scripts in the User Scripts context.
+ *
* Permissions: "userScripts"
- * Description: "A user script is a bit of code injected into a web page to modify its appearance or behavior. Scripts are either created by users or downloaded from a script repository or a user script extension.""
+ * @since Chrome 120, MV3
*/
-
export namespace userScripts {
/**
* Execution environment for a user script.
diff --git a/types/react-speech-recognition/index.d.ts b/types/react-speech-recognition/index.d.ts
index 54ac1cb8ea8910..cf59f05a38c8ca 100644
--- a/types/react-speech-recognition/index.d.ts
+++ b/types/react-speech-recognition/index.d.ts
@@ -37,6 +37,7 @@ export function useSpeechRecognition(options?: SpeechRecognitionOptions): {
listening: boolean;
resetTranscript: () => void;
browserSupportsSpeechRecognition: boolean;
+ browserSupportsContinuousListening: boolean;
isMicrophoneAvailable: boolean;
};
diff --git a/types/react/experimental.d.ts b/types/react/experimental.d.ts
index 7dfb64fee9d6d0..006af56481dbdc 100644
--- a/types/react/experimental.d.ts
+++ b/types/react/experimental.d.ts
@@ -136,6 +136,21 @@ declare module "." {
* Assigns the {@link https://developer.chrome.com/blog/view-transitions-update-io24#view-transition-class `view-transition-class`} class to the underlying DOM node.
*/
className?: string | undefined;
+ /**
+ * Combined with {@link className} if this `` or its parent Component is mounted and there's no other with the same name being deleted.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ enter?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} if this `` or its parent Component is unmounted and there's no other with the same name being deleted.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ exit?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} there are no updates to the content inside this boundary itself but the boundary has resized or moved due to other changes to siblings.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ layout?: "none" | (string & {}) | undefined;
/**
* "auto" will automatically assign a view-transition-name to the inner DOM node.
* That way you can add a View Transition to a Component without controlling its DOM nodes styling otherwise.
@@ -165,6 +180,16 @@ declare module "." {
*/
onUpdate?: (instance: ViewTransitionInstance) => void;
ref?: Ref | undefined;
+ /**
+ * Combined with {@link className} if this `` is being mounted and another instance with the same name is being unmounted elsewhere.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ share?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} if the content of this `` has changed either due to DOM mutations or because an inner child has resized.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ update?: "none" | (string & {}) | undefined;
}
/**
diff --git a/types/react/test/experimental.tsx b/types/react/test/experimental.tsx
index 4101b6267df35b..1a893b3e9711c1 100644
--- a/types/react/test/experimental.tsx
+++ b/types/react/test/experimental.tsx
@@ -143,7 +143,14 @@ function viewTransitionTests() {
const ViewTransition = React.unstable_ViewTransition;
;
- ;
+ ;
;
;
// autocomplete should display "auto"
diff --git a/types/react/ts5.0/experimental.d.ts b/types/react/ts5.0/experimental.d.ts
index 7dfb64fee9d6d0..006af56481dbdc 100644
--- a/types/react/ts5.0/experimental.d.ts
+++ b/types/react/ts5.0/experimental.d.ts
@@ -136,6 +136,21 @@ declare module "." {
* Assigns the {@link https://developer.chrome.com/blog/view-transitions-update-io24#view-transition-class `view-transition-class`} class to the underlying DOM node.
*/
className?: string | undefined;
+ /**
+ * Combined with {@link className} if this `` or its parent Component is mounted and there's no other with the same name being deleted.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ enter?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} if this `` or its parent Component is unmounted and there's no other with the same name being deleted.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ exit?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} there are no updates to the content inside this boundary itself but the boundary has resized or moved due to other changes to siblings.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ layout?: "none" | (string & {}) | undefined;
/**
* "auto" will automatically assign a view-transition-name to the inner DOM node.
* That way you can add a View Transition to a Component without controlling its DOM nodes styling otherwise.
@@ -165,6 +180,16 @@ declare module "." {
*/
onUpdate?: (instance: ViewTransitionInstance) => void;
ref?: Ref | undefined;
+ /**
+ * Combined with {@link className} if this `` is being mounted and another instance with the same name is being unmounted elsewhere.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ share?: "none" | (string & {}) | undefined;
+ /**
+ * Combined with {@link className} if the content of this `` has changed either due to DOM mutations or because an inner child has resized.
+ * `"none"` is a special value that deactivates the view transition name under that condition.
+ */
+ update?: "none" | (string & {}) | undefined;
}
/**
diff --git a/types/react/ts5.0/test/experimental.tsx b/types/react/ts5.0/test/experimental.tsx
index eee7144d9a04d8..e7739ec60113ca 100644
--- a/types/react/ts5.0/test/experimental.tsx
+++ b/types/react/ts5.0/test/experimental.tsx
@@ -146,7 +146,14 @@ function viewTransitionTests() {
const ViewTransition = React.unstable_ViewTransition;
;
- ;
+ ;
;
;
// autocomplete should display "auto"