diff --git a/docs/canvas/canvas-function-reference.asciidoc b/docs/canvas/canvas-function-reference.asciidoc index 330cc63d10548..85e9d22490497 100644 --- 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 <>. *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 <> 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 <> string. For example, `"0.0a"` or `"0%"`. |=== *Returns:* `render` diff --git a/docs/management/advanced-options.asciidoc b/docs/management/advanced-options.asciidoc index 9d4052bbd0156..c698e2db86ddb 100644 --- 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 <> format for the "bytes" format. +`format:currency:defaultPattern`:: The default <> 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 <> locale. +`format:number:defaultPattern`:: The <> for the "number" format. +`format:percent:defaultPattern`:: The <> 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. diff --git a/docs/management/managing-fields.asciidoc b/docs/management/managing-fields.asciidoc index f66976b3715d1..b54f4fe5194ad 100644 --- 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 <> 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 diff --git a/docs/management/numeral.asciidoc b/docs/management/numeral.asciidoc new file mode 100644 index 0000000000000..861277fd18478 --- /dev/null +++ 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: + +* <> +* <> +* <> +* <> + +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 <> `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 +|=== + + diff --git a/docs/user/management.asciidoc b/docs/user/management.asciidoc index 1c55ffc73ca72..34a3790529ca3 100644 --- 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[] diff --git a/package.json b/package.json index c3fe290e7934f..0f04a2fba3b65 100644 --- a/package.json +++ b/package.json @@ -123,7 +123,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", diff --git a/x-pack/legacy/plugins/canvas/i18n/constants.ts b/x-pack/legacy/plugins/canvas/i18n/constants.ts index 8aee6ca148681..4cb05b0426fa1 100644 --- 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'; diff --git a/x-pack/legacy/plugins/canvas/i18n/functions/dict/formatnumber.ts b/x-pack/legacy/plugins/canvas/i18n/functions/dict/formatnumber.ts index df306eb1c04ed..f3e8a8858fc36 100644 --- 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> = { 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', }, }), }, diff --git a/x-pack/legacy/plugins/canvas/i18n/functions/dict/metric.ts b/x-pack/legacy/plugins/canvas/i18n/functions/dict/metric.ts index 8fa98667212a5..8258226e5dfc3 100644 --- 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> = { 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', }, }), }, diff --git a/x-pack/legacy/plugins/canvas/public/lib/documentation_links.ts b/x-pack/legacy/plugins/canvas/public/lib/documentation_links.ts index a43653f420ce0..40e09ee39d714 100644 --- 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`, }); diff --git a/x-pack/package.json b/x-pack/package.json index b8fe0326903b6..96e06dd71b3fe 100644 --- 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", diff --git a/x-pack/plugins/translations/translations/ja-JP.json b/x-pack/plugins/translations/translations/ja-JP.json index 3c7d0ce47acb7..b99a54160bb65 100644 --- 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} が引数と等しくないかを戻します。", diff --git a/x-pack/plugins/translations/translations/zh-CN.json b/x-pack/plugins/translations/translations/zh-CN.json index b262be626aa53..32f648826da84 100644 --- 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} 是否不等于参数。", diff --git a/yarn.lock b/yarn.lock index 7906f363813b8..7f38495c20f4a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2037,15 +2037,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"