Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(46907): Add Intl.ListFormat type declarations #47254

Merged
merged 6 commits into from
Apr 5, 2022
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 103 additions & 1 deletion src/lib/es2021.intl.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,106 @@ declare namespace Intl {
formatRange(startDate: number | bigint, endDate: number | bigint): string;
formatRangeToParts(startDate: number | bigint, endDate: number | bigint): NumberFormatPart[];
}
}

/**
* The locale matching algorithm to use.
*
* [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
predetermined marked this conversation as resolved.
Show resolved Hide resolved
*/
type ListFormatLocaleMatcher = "lookup" | "best fit";
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One final comment: I'm noticing that none of the options above have defined types (or make use of the new ones); is that intentional? Is it more "correct" to not have defined types for any of them? Or do they need to be fixed to have defined types too?

(I'm also noticing that there are some silly things above like "best fit" | "best fit".)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd rather not touch it in this PR, but create a follow-up PR in the next days instead.

  • Create named types for the options above, remove duplicate "best fit"
  • Investigate if ResolvedDateTimeFormatOptions is even correct (at a first glance, it seems wrong, but might be to match some unique browser behavior?)

Feel free to disagree, I can also tackle them here

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sure a second PR is fine, I just wasn't sure (I have no major knowledge of these types) whether or not it's normal to have top level declared type names or not.


/**
* 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;
predetermined marked this conversation as resolved.
Show resolved Hide resolved
}

interface ListFormat {
/**
* Returns a string with a language-specific representation of the list.
*
* @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.
*
* @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>): 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 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.
*
* @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).
*/
formatToParts(list: Iterable<string>): { type: "element" | "literal", value: string; }[];
predetermined marked this conversation as resolved.
Show resolved Hide resolved
}

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<ListFormatOptions, "localeMatcher">): BCP47LanguageTag[];
};
}