From 8ee3d21bd73f489fb35907f639a30a3c9afb2868 Mon Sep 17 00:00:00 2001 From: l2ig Date: Mon, 27 Dec 2021 00:37:16 +0100 Subject: [PATCH 1/5] feat(46907): Add ListFormat type declarations --- src/lib/es2021.intl.d.ts | 104 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/src/lib/es2021.intl.d.ts b/src/lib/es2021.intl.d.ts index 2adfe49056882..bf49316d0a420 100644 --- a/src/lib/es2021.intl.d.ts +++ b/src/lib/es2021.intl.d.ts @@ -21,4 +21,106 @@ declare namespace Intl { formatRange(startDate: number | bigint, endDate: number | bigint): string; formatRangeToParts(startDate: number | bigint, endDate: number | bigint): NumberFormatPart[]; } -} \ No newline at end of file + + /** + * The locale matching algorithm to use. + * + * [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation). + */ + type ListFormatLocaleMatcher = "lookup" | "best fit"; + + /** + * The format of output message. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#parameters). + */ + type ListFormatType = "conjunction" | "disjunction" | "unit"; + + /** + * The length of the formatted message. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#parameters). + */ + type ListFormatStyle = "long" | "short" | "narrow"; + + /** + * An object with some or all properties of the `Intl.ListFormat` constructor `options` parameter. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#parameters). + */ + interface ListFormatOptions { + /** The locale matching algorithm to use. For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation). */ + localeMatcher?: ListFormatLocaleMatcher; + /** The format of output message. */ + type?: ListFormatType; + /** The length of the internationalized message. */ + style?: ListFormatStyle; + } + + interface ListFormat { + /** + * Returns a string with a language-specific representation of the list. + * + * @param list - An iterable object, such as an Array. + * + * @throws `TypeError` if `list` includes something other than the possible values. + * + * @returns {string} A language-specific formatted string representing the elements of the list. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/format). + */ + format(list: Iterable): string; + + /** + * Returns an Array of objects representing the different components that can be used to format a list of values in a locale-aware fashion. + * + * @param list - An Array of values to be formatted according to a locale. + * + * @throws `TypeError` if `list` includes something other than the possible values. + * + * @returns {string} An Array of components which contains the formatted parts from the list. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/formatToParts). + */ + formatToParts(list: string[]): { type: "element" | "literal", value: string; }[]; + } + + const ListFormat: { + prototype: ListFormat; + + /** + * Creates [Intl.ListFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat) objects that + * enable language-sensitive list formatting. + * + * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings. + * For the general form and interpretation of the `locales` argument, + * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation). + * + * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#parameters) + * with some or all options of `ListFormatOptions`. + * + * @returns [Intl.ListFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat) object. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat). + */ + new(locales?: BCP47LanguageTag | BCP47LanguageTag[], options?: ListFormatOptions): ListFormat; + + /** + * Returns an array containing those of the provided locales that are + * supported in list formatting without having to fall back to the runtime's default locale. + * + * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings. + * For the general form and interpretation of the `locales` argument, + * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation). + * + * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/supportedLocalesOf#parameters). + * with some or all possible options. + * + * @returns An array of strings representing a subset of the given locale tags that are supported in list + * formatting without having to fall back to the runtime's default locale. + * + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/supportedLocalesOf). + */ + supportedLocalesOf(locales: BCP47LanguageTag | BCP47LanguageTag[], options?: Pick): BCP47LanguageTag[]; + }; +} From 8572065add1ad794482aa333187c70f046627be2 Mon Sep 17 00:00:00 2001 From: l2ig Date: Mon, 27 Dec 2021 11:02:08 +0100 Subject: [PATCH 2/5] feat(46907): Fix JSDoc return type --- src/lib/es2021.intl.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib/es2021.intl.d.ts b/src/lib/es2021.intl.d.ts index bf49316d0a420..a5ff9d2f6da43 100644 --- a/src/lib/es2021.intl.d.ts +++ b/src/lib/es2021.intl.d.ts @@ -78,7 +78,7 @@ declare namespace Intl { * * @throws `TypeError` if `list` includes something other than the possible values. * - * @returns {string} An Array of components which contains the formatted parts from the list. + * @returns {{ type: "element" | "literal", value: string; }[]} An Array of components which contains the formatted parts from the list. * * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/formatToParts). */ From 56ec2ff4493d8ffda7186f3e5c3f406aee7d9eb5 Mon Sep 17 00:00:00 2001 From: l2ig Date: Fri, 7 Jan 2022 16:34:10 +0100 Subject: [PATCH 3/5] feat(46907): Use correct formatToParts list parameter type description, link to Array MDN page --- src/lib/es2021.intl.d.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib/es2021.intl.d.ts b/src/lib/es2021.intl.d.ts index a5ff9d2f6da43..5d046268ede8c 100644 --- a/src/lib/es2021.intl.d.ts +++ b/src/lib/es2021.intl.d.ts @@ -61,7 +61,7 @@ declare namespace Intl { /** * Returns a string with a language-specific representation of the list. * - * @param list - An iterable object, such as an Array. + * @param list - An iterable object, such as an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). * * @throws `TypeError` if `list` includes something other than the possible values. * @@ -74,7 +74,7 @@ declare namespace Intl { /** * Returns an Array of objects representing the different components that can be used to format a list of values in a locale-aware fashion. * - * @param list - An Array of values to be formatted according to a locale. + * @param list - An iterable object, such as an [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array), to be formatted according to a locale. * * @throws `TypeError` if `list` includes something other than the possible values. * @@ -82,7 +82,7 @@ declare namespace Intl { * * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/formatToParts). */ - formatToParts(list: string[]): { type: "element" | "literal", value: string; }[]; + formatToParts(list: Iterable): { type: "element" | "literal", value: string; }[]; } const ListFormat: { From 01ed8fadb48d5075f99c5e137d38c3275142cae0 Mon Sep 17 00:00:00 2001 From: l2ig Date: Thu, 31 Mar 2022 18:06:02 +0200 Subject: [PATCH 4/5] refactor(46907): Change ListFormatLocaleMatcher MDN link to match the rest --- src/lib/es2021.intl.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib/es2021.intl.d.ts b/src/lib/es2021.intl.d.ts index 54028e8b5939e..139e2019d4842 100644 --- a/src/lib/es2021.intl.d.ts +++ b/src/lib/es2021.intl.d.ts @@ -25,7 +25,7 @@ declare namespace Intl { /** * The locale matching algorithm to use. * - * [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation). + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat#parameters). */ type ListFormatLocaleMatcher = "lookup" | "best fit"; From 094f1ec5d05475200b65555bdd9f9c34f87f3f54 Mon Sep 17 00:00:00 2001 From: l2ig Date: Thu, 31 Mar 2022 18:59:19 +0200 Subject: [PATCH 5/5] feat(46907): Add explicit undefined to ListFormatOptions --- src/lib/es2021.intl.d.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib/es2021.intl.d.ts b/src/lib/es2021.intl.d.ts index 139e2019d4842..e303d8dd34fee 100644 --- a/src/lib/es2021.intl.d.ts +++ b/src/lib/es2021.intl.d.ts @@ -50,11 +50,11 @@ declare namespace Intl { */ interface ListFormatOptions { /** The locale matching algorithm to use. For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation). */ - localeMatcher?: ListFormatLocaleMatcher; + localeMatcher?: ListFormatLocaleMatcher | undefined; /** The format of output message. */ - type?: ListFormatType; + type?: ListFormatType | undefined; /** The length of the internationalized message. */ - style?: ListFormatStyle; + style?: ListFormatStyle | undefined; } interface ListFormat {