Documentation for numeral pattern formatting (#57616) (#58635)

* Documentation for Elastic Numeral formatting * Tweaks from feedback * Updates from feedback * Fix and update examples * Add TODOs * Fix typo Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
2025-04-23 17:28:26 -04:00 · 2020-02-26 16:18:37 -05:00 · 2020-02-26 16:18:37 -05:00 · 7579bff946
commit 7579bff946
parent 3a18d6ba92
14 changed files with 212 additions and 37 deletions
--- a/docs/canvas/canvas-function-reference.asciidoc
+++ b/docs/canvas/canvas-function-reference.asciidoc
@ -1244,7 +1244,7 @@ Alias: `format`
 [[formatnumber_fn]]
 === `formatnumber`

-Formats a number into a formatted number string using NumeralJS. For more information, see http://numeraljs.com/#format.
+Formats a number into a formatted number string using the <<numeral, numeral pattern syntax>>.

 *Expression syntax*
 [source,js]
@ -1276,7 +1276,7 @@ The `formatnumber` subexpression receives the same `context` as the `progress` f

 Alias: `format`
 |`string`
-|A NumeralJS format string. For example, `"0.0a"` or `"0%"`. See http://numeraljs.com/#format.
+|A <<numeral, numeral pattern>> string. For example, `"0.0a"` or `"0%"`.
 |===

 *Returns:* `string`
@ -1675,7 +1675,7 @@ Default: `${font size=48 family="'Open Sans', Helvetica, Arial, sans-serif" colo

 Alias: `format`
 |`string`
-|A NumeralJS format string. For example, `"0.0a"` or `"0%"`. See http://numeraljs.com/#format.
+|A <<numeral, numeral pattern>> string. For example, `"0.0a"` or `"0%"`.
 |===

 *Returns:* `render`
--- a/docs/management/advanced-options.asciidoc
+++ b/docs/management/advanced-options.asciidoc
@ -51,13 +51,13 @@ adapt to the interval between measurements. Keys are http://en.wikipedia.org/wik
 `fields:popularLimit`:: The top N most popular fields to show.
 `filterEditor:suggestValues`:: Set this property to `false` to prevent the filter editor from suggesting values for fields.
 `filters:pinnedByDefault`:: Set this property to `true` to make filters have a global state (be pinned) by default.
-`format:bytes:defaultPattern`:: The default http://numeraljs.com/[numeral format] for the "bytes" format.
-`format:currency:defaultPattern`:: The default http://numeraljs.com/[numeral format] for the "currency" format.
+`format:bytes:defaultPattern`:: The default <<numeral, numeral pattern>> format for the "bytes" format.
+`format:currency:defaultPattern`:: The default <<numeral, numeral pattern>> format for the "currency" format.
 `format:defaultTypeMap`:: A map of the default format name for each field type. Field types that are not explicitly
 mentioned use "\_default_".
-`format:number:defaultLocale`:: The http://numeraljs.com/[numeral language] locale.
-`format:number:defaultPattern`:: The default http://numeraljs.com/[numeral format] for the "number" format.
-`format:percent:defaultPattern`:: The default http://numeraljs.com/[numeral format] for the "percent" format.
+`format:number:defaultLocale`:: The <<numeral, numeral pattern>> locale.
+`format:number:defaultPattern`:: The <<numeral, numeral pattern>> for the "number" format.
+`format:percent:defaultPattern`:: The <<numeral, numeral pattern>> for the "percent" format.
 `histogram:barTarget`:: When date histograms use the `auto` interval, Kibana attempts to generate this number of bars.
 `histogram:maxBars`:: Date histograms are not generated with more bars than the value of this property, scaling values
 when necessary.
--- a/docs/management/managing-fields.asciidoc
+++ b/docs/management/managing-fields.asciidoc
@ -92,6 +92,9 @@ include::field-formatters/string-formatter.asciidoc[]

 Numeric fields support the `Url`, `Bytes`, `Duration`, `Number`, `Percentage`, `String`, and `Color` formatters.

+The `Bytes`, `Number`, and `Percentage` formatters enable you to choose the display formats of numbers in this field using
+the <<numeral, Elastic numeral pattern>> syntax that Kibana maintains.
+
 include::field-formatters/url-formatter.asciidoc[]

 include::field-formatters/string-formatter.asciidoc[]
@ -100,9 +103,6 @@ include::field-formatters/duration-formatter.asciidoc[]

 include::field-formatters/color-formatter.asciidoc[]

-The `Bytes`, `Number`, and `Percentage` formatters enable you to choose the display formats of numbers in this field using
-the https://adamwdraper.github.io/Numeral-js/[numeral.js] standard format definitions.
-
 [[scripted-fields]]
 === Scripted Fields

--- a/docs/management/numeral.asciidoc
+++ b/docs/management/numeral.asciidoc
@ -0,0 +1,184 @@
+[[numeral]]
+== Numeral Formatting
+
+Numeral formatting in {kib} is done through a pattern-based syntax.
+These patterns express common number formats in a concise way, similar
+to date formatting. While these patterns are originally based on Numeral.js,
+they are now maintained by {kib}.
+
+Numeral formatting patterns are used in multiple places in {kib}, including:
+
+* <<advanced-options, Advanced settings>>
+* <<field-formatters-numeric, Index pattern formatters>>
+* <<TSVB, TSVB>>
+* <<canvas, Canvas>>
+
+The simplest pattern format is `0`, and the default {kib} pattern is `0,0.[000]`.
+The numeral pattern syntax expresses:
+
+Number of decimal places:: The `.` character turns on the option to show decimal
+places using a locale-specific decimal separator, most often `.` or `,`.
+To add trailing zeroes such as `5.00`, use a pattern like `0.00`.
+To have optional zeroes, use the `[]` characters. Examples below.
+Thousands separator:: The thousands separator `,` turns on the option to group
+thousands using a locale-specific separator. The separator is most often `,` or `.`,
+and sometimes ` `.
+Accounting notation:: Putting parentheses around your format like `(0.00)` will use accounting notation to show negative numbers.
+
+The display of these patterns is affected by the <<kibana-general-settings, advanced setting>> `format:number:defaultLocale`.
+The default locale is `en`, but some examples will specify that they are using an alternate locale.
+
+Most basic examples:
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 10000.23 | 0,0 | en (English) | 10,000
+| 10000.23 | 0.0 | en (English) | 10000.2
+| 10000.23 | 0,0.0 | fr (French) | 10 000,2
+| 10000.23 | 0,0.000 | fr (French) | 10 000,230
+| 10000.23 | 0,0[.]0 | en (English) | 10,000.2
+| 10000.23 | 0.00[0] | en (English) | 10,000.23
+| -10000.23 | (0) | en (English) | (10000)
+|===
+
+[float]
+=== Percentages
+
+By adding the `%` symbol to any of the previous patterns, the value
+is multiplied by 100 and the `%` symbol is added in the place indicated.
+
+The default percentage formatter in {kib} is `0,0.[000]%`, which shows
+up to three decimal places.
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 0.43 | 0,0.[000]% | en (English) | 43.00%
+| 0.43 | 0,0.[000]% | fr (French) | 43,00%
+| 1 | 0% | en (English) | 100%
+| -0.43 | 0 % | en (English) | -43 %
+|===
+
+[float]
+=== Bytes and bits
+
+The bytes and bits formatters will shorten the input by adding a suffix like `GB` or `TB`. Bytes and bits formatters include the following suffixes:
+
+`b`:: Bytes with binary values and suffixes. 1024 = `1KB`
+`bb`:: Bytes with binary values and binary suffixes. 1024 = `1KiB`
+`bd`:: Bytes with decimal values and suffixes. 1000 = `1kB`
+`bitb`:: Bits with binary values and suffixes. 1024 = `1Kibit`
+`bitd`:: Bits with decimal values and suffixes. 1000 = `1kbit`
+
+Suffixes are not localized with this formatter.
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 2000 | 0.00b | en (English) | 1.95KB
+| 2000 | 0.00bb | en (English) | 1.95KiB
+| 2000 | 0.00bd | en (English) | 2.00kB
+| 3153654400000 | 0.00bd | en (English) | 3.15GB
+| 2000 | 0.00bitb | en (English) | 1.95Kibit
+| 2000 | 0.00bitd | en (English) | 2.00kbit
+|===
+
+[float]
+=== Currency
+
+Currency formatting is limited in {kib} due to the limitations of the pattern
+syntax. To enable currency formatting, use the symbol `$` in the pattern syntax.
+The number formatting locale will affect the result.
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 1000.234 | $0,0.00 | en (English) | $1,000.23
+| 1000.234 | $0,0.00 | fr (French) | €1 000,23
+| 1000.234 | $0,0.00 | chs (Simplified Chinese) | ¥1,000.23
+|===
+
+[float]
+=== Duration formatting
+
+Converts a value in seconds to display hours, minutes, and seconds.
+
+|===
+| **Input** | **Pattern** | **Output**
+| 25 | 00:00:00 | 0:00:25
+| 25 | 00:00 | 0:00:25
+| 238 | 00:00:00 | 0:03:58
+| 63846 | 00:00:00 | 17:44:06
+| -1 | 00:00:00 | -0:00:01
+|===
+
+[float]
+=== Displaying abbreviated numbers
+
+The `a` pattern will look for the shortest abbreviation for your
+number, and use a locale-specific display for it. The abbreviations
+`aK`, `aM`, `aB`, and `aT` can indicate that the number should be
+abbreviated to a specific order of magnitude.
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 2000000000 | 0.00a | en (English) | 2.00b
+| 2000000000 | 0.00a | ja (Japanese) | 2.00十億
+| -5444333222111 | 0,0 aK | en (English) | -5,444,333,222 k
+| -5444333222111 | 0,0 aM | en (English) | -5,444,333 m
+| -5444333222111 | 0,0 aB | en (English) | -5,444 b
+| -5444333222111 | 0,0 aT | en (English) | -5 t
+|===
+
+[float]
+=== Ordinal numbers
+
+The `o` pattern will display a locale-specific positional value like `1st` or `2nd`.
+This pattern has limited support for localization, especially in languages
+with multiple forms, such as German.
+
+|===
+| **Input** | **Pattern** | **Locale** | **Output**
+| 3 | 0o | en (English) | 3rd
+| 34 | 0o | en (English) | 34th
+| 3 | 0o | es (Spanish) | 2er
+| 3 | 0o | ru (Russian) | 3.
+|===
+
+[float]
+=== Complete number pattern reference
+
+These number formats, combined with the patterns described above,
+produce the complete set of options for numeral formatting.
+The output here is all for the `en` locale.
+
+|===
+| **Input** | **Pattern** | **Output**
+| 10000 | 0,0.0000 | 10,000.0000
+| 10000.23 | 0,0 | 10,000
+| -10000 | 0,0.0 | -10,000.0
+| 10000.1234 | 0.000 | 10000.123
+| 10000 | 0[.]00 | 10000
+| 10000.1 | 0[.]00 | 10000.10
+| 10000.123 | 0[.]00 | 10000.12
+| 10000.456 | 0[.]00 | 10000.46
+| 10000.001 | 0[.]00 | 10000
+| 10000.45 | 0[.]00[0] | 10000.45
+| 10000.456 | 0[.]00[0] | 10000.456
+| -10000 | (0,0.0000) | (10,000.0000)
+| -12300 | +0,0.0000 | -12,300.0000
+| 1230 | +0,0 | +1,230
+| 100.78 | 0 | 101
+| 100.28 | 0 | 100
+| 1.932 | 0.0 | 1.9
+| 1.9687 | 0 | 2
+| 1.9687 | 0.0 | 2.0
+| -0.23 | .00 | -.23
+| -0.23 | (.00) | (.23)
+| 0.23 | 0.00000 | 0.23000
+| 0.67 | 0.0[0000] | 0.67
+| 1.005 | 0.00 | 1.01
+| 1e35 | 000 | 1e+35
+| -1e35 | 000 | -1e+35
+| 1e-27 | 000 | 1e-27
+| -1e-27 | 000 | -1e-27
+|===
+
+
--- a/docs/user/management.asciidoc
+++ b/docs/user/management.asciidoc
@ -129,6 +129,8 @@ include::{kib-repo-dir}/management/managing-fields.asciidoc[]

 include::{kib-repo-dir}/management/managing-licenses.asciidoc[]

+include::{kib-repo-dir}/management/numeral.asciidoc[]
+
 include::{kib-repo-dir}/management/managing-remote-clusters.asciidoc[]

 include::{kib-repo-dir}/management/rollups/create_and_manage_rollups.asciidoc[]
--- a/package.json
+++ b/package.json
@ -120,7 +120,7 @@
    "@elastic/eui": "19.0.0",
    "@elastic/filesaver": "1.1.2",
    "@elastic/good": "8.1.1-kibana2",
-    "@elastic/numeral": "2.3.5",
+    "@elastic/numeral": "2.4.0",
    "@elastic/request-crypto": "^1.0.2",
    "@elastic/ui-ace": "0.2.3",
    "@hapi/wreck": "^15.0.1",
--- a/x-pack/legacy/plugins/canvas/i18n/constants.ts
+++ b/x-pack/legacy/plugins/canvas/i18n/constants.ts
@ -28,7 +28,7 @@ export const LUCENE = 'Lucene';
 export const MARKDOWN = 'Markdown';
 export const MOMENTJS = 'MomentJS';
 export const MOMENTJS_TIMEZONE_URL = 'https://momentjs.com/timezone/';
-export const NUMERALJS = 'NumeralJS';
+export const NUMERALJS = 'Numeral pattern';
 export const PDF = 'PDF';
 export const POST = 'POST';
 export const RGB = 'RGB';
--- a/x-pack/legacy/plugins/canvas/i18n/functions/dict/formatnumber.ts
+++ b/x-pack/legacy/plugins/canvas/i18n/functions/dict/formatnumber.ts
@ -12,21 +12,19 @@ import { NUMERALJS } from '../../constants';

 export const help: FunctionHelp<FunctionFactory<typeof formatnumber>> = {
  help: i18n.translate('xpack.canvas.functions.formatnumberHelpText', {
-    defaultMessage: 'Formats a number into a formatted number string using {NUMERALJS}. See {url}.',
+    defaultMessage: 'Formats a number into a formatted number string using {NUMERALJS}.',
    values: {
      NUMERALJS,
-      url: 'http://numeraljs.com/#format',
    },
  }),
  args: {
+    // TODO: Find a way to generate the docs URL here
    format: i18n.translate('xpack.canvas.functions.formatnumber.args.formatHelpText', {
-      defaultMessage:
-        'A {NUMERALJS} format string. For example, {example1} or {example2}. See {url}.',
+      defaultMessage: 'A {NUMERALJS} format string. For example, {example1} or {example2}.',
      values: {
        example1: `"0.0a"`,
        example2: `"0%"`,
        NUMERALJS,
-        url: 'http://numeraljs.com/#format',
      },
    }),
  },
--- a/x-pack/legacy/plugins/canvas/i18n/functions/dict/metric.ts
+++ b/x-pack/legacy/plugins/canvas/i18n/functions/dict/metric.ts
@ -36,14 +36,13 @@ export const help: FunctionHelp<FunctionFactory<typeof metric>> = {
        FONT_WEIGHT,
      },
    }),
+    // TODO: Find a way to generate the docs URL here
    metricFormat: i18n.translate('xpack.canvas.functions.metric.args.metricFormatHelpText', {
-      defaultMessage:
-        'A {NUMERALJS} format string. For example, {example1} or {example2}. See {url}.',
+      defaultMessage: 'A {NUMERALJS} format string. For example, {example1} or {example2}.',
      values: {
        example1: `"0.0a"`,
        example2: `"0%"`,
        NUMERALJS,
-        url: 'http://numeraljs.com/#format',
      },
    }),
  },
--- a/x-pack/legacy/plugins/canvas/public/lib/documentation_links.ts
+++ b/x-pack/legacy/plugins/canvas/public/lib/documentation_links.ts
@ -10,4 +10,7 @@ export const getDocumentationLinks = () => ({
  canvas: `${getCoreStart().docLinks.ELASTIC_WEBSITE_URL}guide/en/kibana/${
    getCoreStart().docLinks.DOC_LINK_VERSION
  }/canvas.html`,
+  numeral: `${getCoreStart().docLinks.ELASTIC_WEBSITE_URL}guide/en/kibana/${
+    getCoreStart().docLinks.DOC_LINK_VERSION
+  }/guide/numeral.html`,
 });
--- a/x-pack/package.json
+++ b/x-pack/package.json
@ -183,7 +183,7 @@
    "@elastic/filesaver": "1.1.2",
    "@elastic/maki": "6.1.0",
    "@elastic/node-crypto": "^1.0.0",
-    "@elastic/numeral": "2.3.3",
+    "@elastic/numeral": "2.4.0",
    "@kbn/babel-preset": "1.0.0",
    "@kbn/config-schema": "1.0.0",
    "@kbn/i18n": "1.0.0",
--- a/x-pack/plugins/translations/translations/ja-JP.json
+++ b/x-pack/plugins/translations/translations/ja-JP.json
@ -4586,8 +4586,6 @@
    "xpack.canvas.functions.filtersHelpText": "ワークパッドのエレメントフィルターを他 (通常データソース) で使用できるように集約します。",
    "xpack.canvas.functions.formatdate.args.formatHelpText": "{MOMENTJS} フォーマットです。例: {example}。{url} を参照。",
    "xpack.canvas.functions.formatdateHelpText": "{MOMENTJS} を使って {ISO8601} 日付文字列、または新世紀からのミリ秒での日付をフォーマットします。{url} を参照。",
-    "xpack.canvas.functions.formatnumber.args.formatHelpText": "{NUMERALJS} 文字列のフォーマットです。例: {example1} または {example2}。{url} を参照。",
-    "xpack.canvas.functions.formatnumberHelpText": "{NUMERALJS} を使って数字をフォーマットされた数字文字列にフォーマットします。{url} を参照。",
    "xpack.canvas.functions.getCell.args.columnHelpText": "値を取得する元の列の名前です。この値は入力されていないと、初めの列から取得されます。",
    "xpack.canvas.functions.getCell.args.rowHelpText": "行番号で、0 から開始します。",
    "xpack.canvas.functions.getCell.columnNotFoundErrorMessage": "列が見つかりません: 「{column}」",
@ -4633,7 +4631,6 @@
    "xpack.canvas.functions.metric.args.labelFontHelpText": "ラベルの {CSS} フォントプロパティです。例: {FONT_FAMILY} または {FONT_WEIGHT}。",
    "xpack.canvas.functions.metric.args.labelHelpText": "メトリックを説明するテキストです。",
    "xpack.canvas.functions.metric.args.metricFontHelpText": "メトリックの {CSS} フォントプロパティです。例: {FONT_FAMILY} または {FONT_WEIGHT}。",
-    "xpack.canvas.functions.metric.args.metricFormatHelpText": "{NUMERALJS} 文字列のフォーマットです。例: {example1} または {example2}。{url} を参照。",
    "xpack.canvas.functions.metricHelpText": "ラベルの上に数字を表示します。",
    "xpack.canvas.functions.neq.args.valueHelpText": "{CONTEXT} と比較される値です。",
    "xpack.canvas.functions.neqHelpText": "{CONTEXT} が引数と等しくないかを戻します。",
--- a/x-pack/plugins/translations/translations/zh-CN.json
+++ b/x-pack/plugins/translations/translations/zh-CN.json
@ -4587,8 +4587,6 @@
    "xpack.canvas.functions.filtersHelpText": "聚合 Workpad 的元素筛选以用于他处，通常用于数据源。",
    "xpack.canvas.functions.formatdate.args.formatHelpText": "{MOMENTJS} 格式。例如：{example}。请参见 {url}。",
    "xpack.canvas.functions.formatdateHelpText": "使用 {MOMENTJS} 格式化 {ISO8601} 日期字符串或自 Epoch 起以毫秒表示的日期。请参见 {url}。",
-    "xpack.canvas.functions.formatnumber.args.formatHelpText": "{NUMERALJS} 格式字符串。例如 {example1} 或 {example2}。请参见 {url}。",
-    "xpack.canvas.functions.formatnumberHelpText": "使用 {NUMERALJS} 将数字格式化为带格式数字字符串。请参见 {url}。",
    "xpack.canvas.functions.getCell.args.columnHelpText": "从其中提取值的列的名称。如果未提供，将从第一列检索值。",
    "xpack.canvas.functions.getCell.args.rowHelpText": "行编号，从 0 开始。",
    "xpack.canvas.functions.getCell.columnNotFoundErrorMessage": "找不到列：“{column}”",
@ -4634,7 +4632,6 @@
    "xpack.canvas.functions.metric.args.labelFontHelpText": "标签的 {CSS} 字体属性。例如 {FONT_FAMILY} 或 {FONT_WEIGHT}。",
    "xpack.canvas.functions.metric.args.labelHelpText": "描述指标的文本。",
    "xpack.canvas.functions.metric.args.metricFontHelpText": "指标的 {CSS} 字体属性。例如 {FONT_FAMILY} 或 {FONT_WEIGHT}。",
-    "xpack.canvas.functions.metric.args.metricFormatHelpText": "{NUMERALJS} 格式字符串。例如 {example1} 或 {example2}。请参见 {url}。",
    "xpack.canvas.functions.metricHelpText": "在标签上显示数字。",
    "xpack.canvas.functions.neq.args.valueHelpText": "与 {CONTEXT} 比较的值。",
    "xpack.canvas.functions.neqHelpText": "返回 {CONTEXT} 是否不等于参数。",
--- a/yarn.lock
+++ b/yarn.lock
@ -2708,15 +2708,10 @@
  resolved "https://registry.yarnpkg.com/@elastic/node-crypto/-/node-crypto-1.0.0.tgz#4d325df333fe1319556bb4d54214098ada1171d4"
  integrity sha512-bbjbEyILPRTRt0xnda18OttLtlkJBPuXx3CjISUSn9jhWqHoFMzfOaZ73D5jxZE2SaFZUrJYfPpqXP6qqPufAQ==

-"@elastic/numeral@2.3.3":
-  version "2.3.3"
-  resolved "https://registry.yarnpkg.com/@elastic/numeral/-/numeral-2.3.3.tgz#94d38a35bd315efa7a6918b22695128fc40a885e"
-  integrity sha512-0OyB9oztlYIq8F1LHjcNf+T089PKfYw78tgUY+q2dtox/jmb4xzFKtI9kv1hwAt5tcgBUTtUMK9kszpSh1UZaQ==
-
-"@elastic/numeral@2.3.5":
-  version "2.3.5"
-  resolved "https://registry.yarnpkg.com/@elastic/numeral/-/numeral-2.3.5.tgz#fcaeac57ddc55cd4b7f0b9c7e070c242dd5d0600"
-  integrity sha512-lJVZHPuI2csrfwDIEdKedFqNIF+5YsyqvX2soAqhu49iKOd9n7tifLRn30vP6D7oKd+6HsiGfPzT0nzdJWsexQ==
+"@elastic/numeral@2.4.0":
+  version "2.4.0"
+  resolved "https://registry.yarnpkg.com/@elastic/numeral/-/numeral-2.4.0.tgz#883197b7f4bf3c2dd994f53b274769ddfa2bf79a"
+  integrity sha512-uGBKGCNghTgUZPHClji/00v+AKt5nidPTGOIbcT+lbTPVxNB6QPpPLGWtXyrg3QZAxobPM/LAZB1mAqtJeq44Q==

 "@elastic/request-crypto@^1.0.2":
  version "1.0.2"