@arcgis/core/intl/substitute.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * The formatting options for date values.
 *
 * @since 5.0
 * @see [SubstituteOptions](https://developers.arcgis.com/javascript/latest/references/core/intl/substitute/#SubstituteOptions)
 * @example
 * const dateFormat = {
 *   type: "date",
 *   intlOptions: {
 *     year: "numeric",
 *     month: "numeric",
 *     day: "numeric",
 *     hour: "numeric",
 *     minute: "numeric"
 *   }
 * };
 *
 * let data = {
 *   time: Date.now()
 * };
 *
 * intl.substitute("Date: {time}", data, {
 *   format: {
 *     time: dateFormat
 *   }
 * });
 */
export interface DateTimeFormatOptions {
  /**
   * The type of this format. The value is always `"date"`.
   *
   * @since 5.0
   */
  type: "date";
  /**
   * The date format options for the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) object.
   *
   * @since 5.0
   */
  intlOptions?: Intl.DateTimeFormatOptions;
}

/**
 * The formatting options for numeric values.
 *
 * @since 5.0
 * @see [SubstituteOptions](https://developers.arcgis.com/javascript/latest/references/core/intl/substitute/#SubstituteOptions)
 * @example
 * // Formats a number with a fixed number of fraction digits
 * const numberFormat = {
 *   type: "number",
 *   intlOptions: {
 *     style: "decimal",
 *     useGrouping: true,
 *     minimumFractionDigits: 2,
 *     maximumFractionDigits: 2
 *   }
 * });
 *
 * let data = {
 *   value: 10
 * };
 *
 * intl.substitute("A number: {value}", data, {
 *   value: numberFormat
 * });
 * @example
 * // Formats a number as currency, in Euros.
 * const currencyFormat = {
 *   type: "number",
 *   intlOptions: {
 *     style: "currency",
 *     currency: "EUR",
 *     currencyDisplay: "symbol"
 *   }
 * };
 *
 * let data = {
 *   amount: 14
 * };
 *
 * intl.substitute("Amount: {amount}", data, {
 *   amount: currencyFormat
 * });
 * @example
 * // Formats a number as a percentage.
 * const percentFormat = {
 *   type: "number",
 *   intlOptions: {
 *     style: "percent"
 *   }
 * };
 *
 * let data = {
 *   growth: 0.5
 * };
 *
 * intl.substitute("Growth: {growth}", data, {
 *   growth: percentFormat
 * });
 */
export interface NumberFormatOptions {
  /**
   * The type of this format. The value is always `"number"`.
   *
   * @since 5.0
   */
  type: "number";
  /**
   * The Intl number format options for the [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) object.
   *
   * @since 5.0
   */
  intlOptions?: Intl.NumberFormatOptions;
}

/**
 * An object to specify substitution options.
 *
 * Use the [SubstituteOptions.format](https://developers.arcgis.com/javascript/latest/references/core/intl/substitute/#SubstituteOptions) property to define the formatting for each value referenced in the string template.
 * `format` is a key-value pair object. Each key can either be:
 *   - a property of the `data` parameter or [substitute()](https://developers.arcgis.com/javascript/latest/references/core/intl/#substitute)
 *   - a named formatter than can be referenced in the template string.
 *
 * In the following example, the `time` property from `data` will be formatted as a date with each component in numeric format.
 *
 * ```js
 * const data = {
 *   time: Date.now()
 * };
 *
 * intl.substitute("Date: {time}", data, {
 *   format: {
 *     time: {
 *       type: "date",
 *       intlOptions: {
 *         year: "numeric",
 *         month: "numeric",
 *         day: "numeric",
 *         hour: "numeric",
 *         minute: "numeric"
 *       }
 *     }
 *   }
 * });
 * ```
 *
 * The following example uses a named formatter to format the `time` property twice with different formatting options.
 *
 * ```js
 * const data = {
 *   time: Date.now()
 * };
 *
 * intl.substitute("In {time:monthFormat} of {time:yearFormat}", data, {
 *   format: {
 *     monthFormat: {
 *       type: "date",
 *       intlOptions: {
 *         month: "long"
 *       }
 *     },
 *     yearFormat: {
 *       type: "date",
 *       intlOptions: {
 *         year: "numeric"
 *       }
 *     }
 *   }
 * });
 * ```
 *
 * @since 5.0
 * @see [substitute()](https://developers.arcgis.com/javascript/latest/references/core/intl/#substitute)
 */
export interface SubstituteOptions {
  /**
   * A hashmap of string keys to formatting options.
   *
   * @since 5.0
   */
  format?: Record<string, NumberFormatOptions | DateTimeFormatOptions | undefined>;
}