1 | /*! *****************************************************************************
|
2 | Copyright (c) Microsoft Corporation. All rights reserved.
|
3 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
4 | this file except in compliance with the License. You may obtain a copy of the
|
5 | License at http://www.apache.org/licenses/LICENSE-2.0
|
6 |
|
7 | THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
8 | KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
|
9 | WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
|
10 | MERCHANTABLITY OR NON-INFRINGEMENT.
|
11 |
|
12 | See the Apache Version 2.0 License for specific language governing permissions
|
13 | and limitations under the License.
|
14 | ***************************************************************************** */
|
15 |
|
16 |
|
17 |
|
18 | /// <reference no-default-lib="true"/>
|
19 |
|
20 |
|
21 | declare namespace Intl {
|
22 |
|
23 | /**
|
24 | * [BCP 47 language tag](http://tools.ietf.org/html/rfc5646) definition.
|
25 | *
|
26 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
|
27 | *
|
28 | * [Wikipedia](https://en.wikipedia.org/wiki/IETF_language_tag).
|
29 | */
|
30 | type BCP47LanguageTag = string;
|
31 |
|
32 | /**
|
33 | * Unit to use in the relative time internationalized message.
|
34 | *
|
35 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format#Parameters).
|
36 | *
|
37 | * [Specification](https://tc39.es/ecma402/#sec-singularrelativetimeunit).
|
38 | */
|
39 | type RelativeTimeFormatUnit =
|
40 | | "year" | "years"
|
41 | | "quarter" | "quarters"
|
42 | | "month" | "months"
|
43 | | "week" | "weeks"
|
44 | | "day" | "days"
|
45 | | "hour" | "hours"
|
46 | | "minute" | "minutes"
|
47 | | "second" | "seconds"
|
48 | ;
|
49 |
|
50 | /**
|
51 | * The locale matching algorithm to use.
|
52 | *
|
53 | * [MDN](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
|
54 | *
|
55 | * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
|
56 | */
|
57 | type RelativeTimeFormatLocaleMatcher = "lookup" | "best fit";
|
58 |
|
59 | /**
|
60 | * The format of output message.
|
61 | *
|
62 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
63 | *
|
64 | * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
|
65 | */
|
66 | type RelativeTimeFormatNumeric = "always" | "auto";
|
67 |
|
68 | /**
|
69 | * The length of the internationalized message.
|
70 | *
|
71 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
72 | *
|
73 | * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
|
74 | */
|
75 | type RelativeTimeFormatStyle = "long" | "short" | "narrow";
|
76 |
|
77 | /**
|
78 | * An object with some or all of properties of `options` parameter
|
79 | * of `Intl.RelativeTimeFormat` constructor.
|
80 | *
|
81 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters).
|
82 | *
|
83 | * [Specification](https://tc39.es/ecma402/#sec-InitializeRelativeTimeFormat).
|
84 | */
|
85 | interface RelativeTimeFormatOptions {
|
86 | localeMatcher?: RelativeTimeFormatLocaleMatcher;
|
87 | numeric?: RelativeTimeFormatNumeric;
|
88 | style?: RelativeTimeFormatStyle;
|
89 | }
|
90 |
|
91 | /**
|
92 | * An object with properties reflecting the locale
|
93 | * and formatting options computed during initialization
|
94 | * of the `Intel.RelativeTimeFormat` object
|
95 | *
|
96 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions#Description).
|
97 | *
|
98 | * [Specification](https://tc39.es/ecma402/#table-relativetimeformat-resolvedoptions-properties)
|
99 | */
|
100 | interface ResolvedRelativeTimeFormatOptions {
|
101 | locale: BCP47LanguageTag;
|
102 | style: RelativeTimeFormatStyle;
|
103 | numeric: RelativeTimeFormatNumeric;
|
104 | numberingSystem: string;
|
105 | }
|
106 |
|
107 | /**
|
108 | * An object representing the relative time format in parts
|
109 | * that can be used for custom locale-aware formatting.
|
110 | *
|
111 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts#Using_formatToParts).
|
112 | *
|
113 | * [Specification](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts).
|
114 | */
|
115 | interface RelativeTimeFormatPart {
|
116 | type: string;
|
117 | value: string;
|
118 | unit?: RelativeTimeFormatUnit;
|
119 | }
|
120 |
|
121 | interface RelativeTimeFormat {
|
122 | /**
|
123 | * Formats a value and a unit according to the locale
|
124 | * and formatting options of the given
|
125 | * [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
|
126 | * object.
|
127 | *
|
128 | * While this method automatically provides the correct plural forms,
|
129 | * the grammatical form is otherwise as neutral as possible.
|
130 | * It is the caller's responsibility to handle cut-off logic
|
131 | * such as deciding between displaying "in 7 days" or "in 1 week".
|
132 | * This API does not support relative dates involving compound units.
|
133 | * e.g "in 5 days and 4 hours".
|
134 | *
|
135 | * @param value - Numeric value to use in the internationalized relative time message
|
136 | *
|
137 | * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
|
138 | * to use in the relative time internationalized message.
|
139 | * Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
|
140 | * `"day"`, `"hour"`, `"minute"`, `"second"`.
|
141 | * Plural forms are also permitted.
|
142 | *
|
143 | * @throws `RangeError` if `unit` was given something other than `unit` possible values
|
144 | *
|
145 | * @returns Internationalized relative time message as string
|
146 | *
|
147 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/format).
|
148 | *
|
149 | * [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.format).
|
150 | */
|
151 | format(
|
152 | value: number,
|
153 | unit: RelativeTimeFormatUnit,
|
154 | ): string;
|
155 |
|
156 | /**
|
157 | * A version of the format method which it returns an array of objects
|
158 | * which represent "parts" of the object,
|
159 | * separating the formatted number into its constituent parts
|
160 | * and separating it from other surrounding text.
|
161 | * These objects have two properties:
|
162 | * `type` a NumberFormat formatToParts type, and `value`,
|
163 | * which is the String which is the component of the output.
|
164 | * If a "part" came from NumberFormat,
|
165 | * it will have a unit property which indicates the `unit` being formatted;
|
166 | * literals which are part of the larger frame will not have this property.
|
167 | *
|
168 | * @param value - Numeric value to use in the internationalized relative time message
|
169 | *
|
170 | * @param unit - [Unit](https://tc39.es/ecma402/#sec-singularrelativetimeunit)
|
171 | * to use in the relative time internationalized message.
|
172 | * Possible values are: `"year"`, `"quarter"`, `"month"`, `"week"`,
|
173 | * `"day"`, `"hour"`, `"minute"`, `"second"`.
|
174 | * Plural forms are also permitted.
|
175 | *
|
176 | * @throws `RangeError` if `unit` was given something other than `unit` possible values
|
177 | *
|
178 | * @returns Array of [FormatRelativeTimeToParts](https://tc39.es/ecma402/#sec-FormatRelativeTimeToParts)
|
179 | *
|
180 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/formatToParts).
|
181 | *
|
182 | * [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.prototype.formatToParts).
|
183 | */
|
184 | formatToParts(
|
185 | value: number,
|
186 | unit: RelativeTimeFormatUnit,
|
187 | ): RelativeTimeFormatPart[];
|
188 |
|
189 | /**
|
190 | * Provides access to the locale and options computed during initialization of this `Intl.RelativeTimeFormat` object.
|
191 | *
|
192 | * @returns A new object with properties reflecting the locale
|
193 | * and formatting options computed during initialization
|
194 | * of the `Intel.RelativeTimeFormat` object.
|
195 | *
|
196 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/resolvedOptions).
|
197 | *
|
198 | * [Specification](https://tc39.es/ecma402/#sec-intl.relativetimeformat.prototype.resolvedoptions)
|
199 | */
|
200 | resolvedOptions(): ResolvedRelativeTimeFormatOptions;
|
201 | }
|
202 |
|
203 | /**
|
204 | * The [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
|
205 | * object is a constructor for objects that enable language-sensitive relative time formatting.
|
206 | *
|
207 | * Part of [Intl object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
|
208 | * namespace and the [ECMAScript Internationalization API](https://www.ecma-international.org/publications/standards/Ecma-402.htm).
|
209 | *
|
210 | * [Compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat#Browser_compatibility).
|
211 | *
|
212 | * [Polyfills](https://github.com/tc39/proposal-intl-relative-time#polyfills).
|
213 | */
|
214 | const RelativeTimeFormat: {
|
215 | /**
|
216 | * Constructor creates [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat)
|
217 | * objects
|
218 | *
|
219 | * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
|
220 | * For the general form and interpretation of the locales argument,
|
221 | * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
|
222 | *
|
223 | * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
|
224 | * with some or all of options of the formatting.
|
225 | * An object with some or all of the following properties:
|
226 | * - `localeMatcher` - The locale matching algorithm to use.
|
227 | * Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
|
228 | * For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
|
229 | * - `numeric` - The format of output message.
|
230 | * Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
|
231 | * The `"auto"` value allows to not always have to use numeric values in the output.
|
232 | * - `style` - The length of the internationalized message. Possible values are:
|
233 | * `"long"` (default, e.g., in 1 month),
|
234 | * `"short"` (e.g., in 1 mo.)
|
235 | * or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
|
236 | *
|
237 | * @returns [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat) object.
|
238 | *
|
239 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat).
|
240 | *
|
241 | * [Specification](https://tc39.es/ecma402/#sec-intl-relativetimeformat-constructor).
|
242 | */
|
243 | new(
|
244 | locales?: BCP47LanguageTag | BCP47LanguageTag[],
|
245 | options?: RelativeTimeFormatOptions,
|
246 | ): RelativeTimeFormat;
|
247 |
|
248 | /**
|
249 | * Returns an array containing those of the provided locales
|
250 | * that are supported in date and time formatting
|
251 | * without having to fall back to the runtime's default locale.
|
252 | *
|
253 | * @param locales - A string with a [BCP 47 language tag](http://tools.ietf.org/html/rfc5646), or an array of such strings.
|
254 | * For the general form and interpretation of the locales argument,
|
255 | * see the [`Intl` page](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation).
|
256 | *
|
257 | * @param options - An [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#Parameters)
|
258 | * with some or all of options of the formatting.
|
259 | * An object with some or all of the following properties:
|
260 | * - `localeMatcher` - The locale matching algorithm to use.
|
261 | * Possible values are `"lookup"` and `"best fit"`; the default is `"best fit"`.
|
262 | * For information about this option, see [Intl page](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation).
|
263 | * - `numeric` - The format of output message.
|
264 | * Possible values are: `"always"` (default, e.g., `1 day ago`) or `"auto"` (e.g., `yesterday`).
|
265 | * The `"auto"` value allows to not always have to use numeric values in the output.
|
266 | * - `style` - The length of the internationalized message. Possible values are:
|
267 | * `"long"` (default, e.g., in 1 month),
|
268 | * `"short"` (e.g., in 1 mo.)
|
269 | * or `"narrow"` (e.g., in 1 mo.). The narrow style could be similar to the short style for some locales.
|
270 | *
|
271 | * @returns An array containing those of the provided locales
|
272 | * that are supported in date and time formatting
|
273 | * without having to fall back to the runtime's default locale.
|
274 | *
|
275 | * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/supportedLocalesOf).
|
276 | *
|
277 | * [Specification](https://tc39.es/ecma402/#sec-Intl.RelativeTimeFormat.supportedLocalesOf).
|
278 | */
|
279 | supportedLocalesOf(
|
280 | locales: BCP47LanguageTag | BCP47LanguageTag[],
|
281 | options?: RelativeTimeFormatOptions,
|
282 | ): BCP47LanguageTag[];
|
283 | };
|
284 |
|
285 | interface NumberFormatOptions {
|
286 | notation?: string;
|
287 | unit?: string;
|
288 | unitDisplay?: string;
|
289 | }
|
290 |
|
291 | interface ResolvedNumberFormatOptions {
|
292 | notation?: string;
|
293 | unit?: string;
|
294 | unitDisplay?: string;
|
295 | }
|
296 | }
|