Import of Intl.Locale from microsoft#39664

orta · orta · commit ad15e541b097 · 2021-08-30T21:42:16.000+01:00
diff --git a/src/lib/es2020.intl.d.ts b/src/lib/es2020.intl.d.ts
@@ -4,16 +4,13 @@ declare namespace Intl {
      * [Unicode BCP 47 Locale Identifiers](https://unicode.org/reports/tr35/#Unicode_Language_and_Locale_Identifiers) definition.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
-     *
      */
     type UnicodeBCP47LocaleIdentifier = string;
 
     /**
      * Unit to use in the relative time internationalized message.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format#Parameters).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-singularrelativetimeunit).
      */
     type RelativeTimeFormatUnit =
         | "year" | "years"
@@ -30,40 +27,42 @@ declare namespace Intl {
      * The locale matching algorithm to use.
      *
      * [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
      */
     type RelativeTimeFormatLocaleMatcher = "lookup" | "best fit";
 
     /**
      * The format of output message.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
      */
     type RelativeTimeFormatNumeric = "always" | "auto";
 
     /**
      * The length of the internationalized message.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
      */
     type RelativeTimeFormatStyle = "long" | "short" | "narrow";
 
+    /**
+     * [BCP 47 language tag](http://tools.ietf.org/html/rfc5646) definition.
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+     */
+    type BCP47LanguageTag = string;
+
     /**
      * An object with some or all of properties of `options` parameter
      * of `Intl.RelativeTimeFormat` constructor.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
      */
     interface RelativeTimeFormatOptions {
+        /** 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?: RelativeTimeFormatLocaleMatcher;
+        /** The format of output message. */
         numeric?: RelativeTimeFormatNumeric;
+        /** The length of the internationalized message. */
         style?: RelativeTimeFormatStyle;
     }
 
@@ -73,8 +72,6 @@ declare namespace Intl {
      * of the `Intel.RelativeTimeFormat` object
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions#Description).
-     *
-     * [Specification](https://tc39.es/ecma402/#table-relativetimeformat-resolvedoptions-properties)
      */
     interface ResolvedRelativeTimeFormatOptions {
         locale: UnicodeBCP47LocaleIdentifier;
@@ -88,8 +85,6 @@ declare namespace Intl {
      * that can be used for custom locale-aware formatting.
      *
      * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts#Using_formatToParts).
-     *
-     * [Specification](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts).
      */
     interface RelativeTimeFormatPart {
         type: string;
@@ -106,75 +101,41 @@ declare namespace Intl {
          *
          * While this method automatically provides the correct plural forms,
          * the grammatical form is otherwise as neutral as possible.
+         *
          * It is the caller's responsibility to handle cut-off logic
          * such as deciding between displaying "in 7 days" or "in 1 week".
          * This API does not support relative dates involving compound units.
          * e.g "in 5 days and 4 hours".
          *
          * @param value -  Numeric value to use in the internationalized relative time message
          *
-         * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
-         *  to use in the relative time internationalized message.
-         *  Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
-         *  `"day"`, `"hour"`, `"minute"`, `"second"`.
-         *  Plural forms are also permitted.
+         * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit) to use in the relative time internationalized message.
          *
          * @throws `RangeError` if `unit` was given something other than `unit` possible values
          *
-         * @returns Internationalized relative time message as string
+         * @returns {string} Internationalized relative time message as string
          *
          * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format).
-         *
-         * [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.format).
          */
-        format(
-            value: number,
-            unit: RelativeTimeFormatUnit,
-        ): string;
+        format(value: number, unit: RelativeTimeFormatUnit): string;
 
         /**
-         *  A version of the format method which it returns an array of objects
-         *  which represent "parts" of the object,
-         *  separating the formatted number into its constituent parts
-         *  and separating it from other surrounding text.
-         *  These objects have two properties:
-         * `type` a NumberFormat formatToParts type, and `value`,
-         *  which is the String which is the component of the output.
-         *  If a "part" came from NumberFormat,
-         *  it will have a unit property which indicates the `unit` being formatted;
-         *  literals which are part of the larger frame will not have this property.
+         *  Returns an array of objects representing the relative time format in parts that can be used for custom locale-aware formatting.
          *
          *  @param value - Numeric value to use in the internationalized relative time message
          *
-         *  @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
-         *   to use in the relative time internationalized message.
-         *   Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
-         *   `"day"`, `"hour"`, `"minute"`, `"second"`.
-         *   Plural forms are also permitted.
+         *  @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit) to use in the relative time internationalized message.
          *
          *  @throws `RangeError` if `unit` was given something other than `unit` possible values
          *
-         *  @returns Array of [FormatRelativeTimeToParts](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts)
-         *
          *  [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts).
-         *
-         *  [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.formatToParts).
          */
-        formatToParts(
-            value: number,
-            unit: RelativeTimeFormatUnit,
-        ): RelativeTimeFormatPart[];
+        formatToParts(value: number, unit: RelativeTimeFormatUnit): RelativeTimeFormatPart[];
 
         /**
          * Provides access to the locale and options computed during initialization of this `Intl.RelativeTimeFormat` object.
          *
-         * @returns A new object with properties reflecting the locale
-         *  and formatting options computed during initialization
-         *  of the `Intel.RelativeTimeFormat` object.
-         *
          * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions).
-         *
-         * [Specification](https://tc39.es/ecma402/#sec-intl.relativetimeformat.prototype.resolvedoptions)
          */
         resolvedOptions(): ResolvedRelativeTimeFormatOptions;
     }
@@ -187,37 +148,21 @@ declare namespace Intl {
      * namespace and the [ECMAScript Internationalization API](https://www.ecma-international.org/publications/standards/Ecma-402.htm).
      *
      * [Compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat#Browser_compatibility).
-     *
-     * [Polyfills](https://github.com/tc39/proposal-intl-relative-time#polyfills).
      */
     const RelativeTimeFormat: {
         /**
-         * Constructor creates [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
-         * objects
+         * Creates [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) objects
          *
          * @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/RelativeTimeFormat/RelativeTimeFormat#Parameters)
-         *  with some or all of options of the formatting.
-         *  An object with some or all of the following properties:
-         *  - `localeMatcher` - The locale matching algorithm to use.
-         *    Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
-         *    For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
-         *  - `numeric` - The format of output message.
-         *    Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
-         *    The `"auto"` value allows to not always have to use numeric values in the output.
-         *  - `style` - The length of the internationalized message. Possible values are:
-         *    `"long"` (default, e.g., in 1 month),
-         *    `"short"` (e.g., in 1 mo.)
-         *    or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
+         *  with some or all of options of `RelativeTimeFormatOptions`.
          *
          * @returns [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) object.
          *
          * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
-         *
-         * [Specification](https://tc39.es/ecma402/#sec-intl-relativetimeformat-constructor).
          */
         new(
             locales?: UnicodeBCP47LocaleIdentifier | UnicodeBCP47LocaleIdentifier[],
@@ -235,25 +180,12 @@ declare namespace Intl {
          *
          * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
          *  with some or all of options of the formatting.
-         *  An object with some or all of the following properties:
-         *  - `localeMatcher` - The locale matching algorithm to use.
-         *    Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
-         *    For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
-         *  - `numeric` - The format of output message.
-         *    Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
-         *    The `"auto"` value allows to not always have to use numeric values in the output.
-         *  - `style` - The length of the internationalized message. Possible values are:
-         *    `"long"` (default, e.g., in 1 month),
-         *    `"short"` (e.g., in 1 mo.)
-         *    or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
          *
          * @returns An array containing those of the provided locales
          *  that are supported in date and time 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/RelativeTimeFormat/supportedLocalesOf).
-         *
-         * [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.supportedLocalesOf).
          */
         supportedLocalesOf(
             locales?: UnicodeBCP47LocaleIdentifier | UnicodeBCP47LocaleIdentifier[],
@@ -262,19 +194,19 @@ declare namespace Intl {
     };
 
     interface NumberFormatOptions {
-        compactDisplay?: string;
-        notation?: string;
-        signDisplay?: string;
-        unit?: string;
-        unitDisplay?: string;
+        compactDisplay?: "short" | "long";
+        notation?: "standard" | "scientific" | "engineering" | "compact";
+        signDisplay?: "auto" | "never" | "always";
+        unit?: NumberFormatUnit;
+        unitDisplay?: "short" | "long" | "narrow";
     }
 
     interface ResolvedNumberFormatOptions {
-        compactDisplay?: string;
-        notation?: string;
-        signDisplay?: string;
-        unit?: string;
-        unitDisplay?: string;
+        compactDisplay?: "short" | "long";
+        notation?: "standard" | "scientific" | "engineering" | "compact";
+        signDisplay?: "auto" | "never" | "always";
+        unit?: NumberFormatUnit;
+        unitDisplay?: "short" | "long" | "narrow";
     }
 
     interface DateTimeFormatOptions {
@@ -286,4 +218,58 @@ declare namespace Intl {
         hourCycle?: "h11" | "h12" | "h23" | "h24";
         fractionalSecondDigits?: 0 | 1 | 2 | 3;
     }
+
+    type LocaleHourCycleKey = "h12" | "h23" | "h11" | "h24";
+    type LocaleCollationCaseFirst = "upper" | "lower" | "false";
+
+    interface LocaleOptions {
+        /** A string containing the language, and the script and region if available. */
+        baseName?: string;
+        /** The part of the Locale that indicates the locale's calendar era. */
+        calendar?: string;
+        /** Flag that defines whether case is taken into account for the locale's collation rules. */
+        caseFirst?: LocaleCollationCaseFirst;
+        /** The collation type used for sorting */
+        collation?: string;
+        /** The time keeping format convention used by the locale. */
+        hourCycle?: LocaleHourCycleKey;
+        /** The primary language subtag associated with the locale. */
+        language?: string;
+        /** The numeral system used by the locale. */
+        numberingSystem?: string;
+        /** Flag that defines whether the locale has special collation handling for numeric characters. */
+        numeric?: boolean;
+        /** The region of the world (usually a country) associated with the locale. Possible values are region codes as defined by ISO 3166-1. */
+        region?: string;
+        /** The script used for writing the particular language used in the locale. Possible values are script codes as defined by ISO 15924. */
+        script?: string;
+    }
+
+    interface Locale extends LocaleOptions {
+        /** Gets the most likely values for the language, script, and region of the locale based on existing values. */
+        maximize(): Locale;
+        /** Attempts to remove information about the locale that would be added by calling `Locale.maximize()`. */
+        minimize(): Locale;
+        /** Returns the locale's full locale identifier string. */
+        toString(): BCP47LanguageTag;
+    }
+
+    /**
+     * Constructor creates [Intl.Locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale)
+     * objects
+     *
+     * @param tag - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646).
+     *  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/Locale/Locale#Parameters)
+     *  with some or all of options of the locale.
+     *
+     * @returns [Intl.Locale](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) object.
+     *
+     * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale).
+     */
+    const Locale: {
+        new (tag?: BCP47LanguageTag, options?: LocaleOptions): Locale;
+    };
 }
