Merge branch 'master' of https://github.com/elastic/kibana into alert…

…ing/telemetry-for-predefined-rule-ids

.github/CODEOWNERS

@@ -45,6 +45,7 @@
 /examples/ui_actions_explorer/ @elastic/kibana-app-services
 /examples/url_generators_examples/ @elastic/kibana-app-services
 /examples/url_generators_explorer/ @elastic/kibana-app-services
+/examples/field_formats_example/ @elastic/kibana-app-services
 /packages/elastic-datemath/ @elastic/kibana-app-services
 /packages/kbn-interpreter/ @elastic/kibana-app-services
 /src/plugins/bfetch/ @elastic/kibana-app-services

examples/field_formats_example/README.md

@@ -0,0 +1,10 @@
+## Field formats example
+
+Field formats is a service used by index patterns for applying custom formatting to values in a document.
+Field formats service can also be used separately from index patterns.
+
+This example plugin shows:
+
+1. How field formats can be used for formatting values
+2. How to create a custom field format and make it available in index pattern field editor
+3. How to create a custom editor for a custom field formatter

examples/field_formats_example/kibana.json

@@ -0,0 +1,12 @@
+{
+  "id": "fieldFormatsExample",
+  "version": "1.0.0",
+  "kibanaVersion": "kibana",
+  "ui": true,
+  "owner": {
+    "name": "App Services",
+    "githubTeam": "kibana-app-services"
+  },
+  "description": "A plugin that demonstrates field formats usage",
+  "requiredPlugins": ["developerExamples", "fieldFormats", "indexPatternFieldEditor", "data"]
+}

examples/field_formats_example/public/app.tsx

@@ -0,0 +1,208 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import {
+  EuiBasicTable,
+  EuiCallOut,
+  EuiCode,
+  EuiCodeBlock,
+  EuiLink,
+  EuiPage,
+  EuiPageBody,
+  EuiPageContent,
+  EuiPageContentBody,
+  EuiPageHeader,
+  EuiPageHeaderSection,
+  EuiSpacer,
+  EuiText,
+  EuiTitle,
+} from '@elastic/eui';
+import { FieldFormatsStart } from '../../../src/plugins/field_formats/public';
+import * as example1 from './examples/1_using_existing_format';
+import * as example2 from './examples/2_creating_custom_formatter';
+// @ts-ignore
+import example1SampleCode from '!!raw-loader!./examples/1_using_existing_format';
+// @ts-ignore
+import example2SampleCode from '!!raw-loader!./examples/2_creating_custom_formatter';
+// @ts-ignore
+import example3SampleCode from '!!raw-loader!./examples/3_creating_custom_format_editor';
+
+export interface Deps {
+  fieldFormats: FieldFormatsStart;
+
+  /**
+   * Just for demo purposes
+   */
+  openIndexPatternNumberFieldEditor: () => void;
+}
+
+const UsingAnExistingFieldFormatExample: React.FC<{ deps: Deps }> = (props) => {
+  const sample = example1.getSample(props.deps.fieldFormats);
+
+  return (
+    <>
+      <EuiText>
+        <p>
+          This example shows how to use existing field formatter to format values. As an example, we
+          have a following sample configuration{' '}
+          <EuiCode>{JSON.stringify(example1.sampleSerializedFieldFormat)}</EuiCode> representing a{' '}
+          <EuiCode>bytes</EuiCode>
+          field formatter with a <EuiCode>0.00b</EuiCode> pattern.
+        </p>
+      </EuiText>
+      <EuiSpacer size={'s'} />
+      <EuiCodeBlock>{example1SampleCode}</EuiCodeBlock>
+      <EuiSpacer size={'s'} />
+      <EuiBasicTable
+        data-test-subj={'example1 sample table'}
+        items={sample}
+        textOnly={true}
+        columns={[
+          {
+            field: 'raw',
+            name: 'Raw value',
+            'data-test-subj': 'example1 sample raw',
+          },
+          {
+            field: 'formatted',
+            name: 'Formatted value',
+            'data-test-subj': 'example1 sample formatted',
+          },
+        ]}
+      />
+    </>
+  );
+};
+
+const CreatingCustomFieldFormat: React.FC<{ deps: Deps }> = (props) => {
+  const sample = example2.getSample(props.deps.fieldFormats);
+
+  return (
+    <>
+      <EuiText>
+        <p>
+          This example shows how to create a custom field formatter. As an example, we create a
+          currency formatter and then display some values as <EuiCode>USD</EuiCode>.
+        </p>
+      </EuiText>
+      <EuiSpacer size={'s'} />
+      <EuiCodeBlock>{example2SampleCode}</EuiCodeBlock>
+      <EuiSpacer size={'s'} />
+      <EuiBasicTable
+        items={sample}
+        textOnly={true}
+        data-test-subj={'example2 sample table'}
+        columns={[
+          {
+            field: 'raw',
+            name: 'Raw value',
+            'data-test-subj': 'example2 sample raw',
+          },
+          {
+            field: 'formatted',
+            name: 'Formatted value',
+            'data-test-subj': 'example2 sample formatted',
+          },
+        ]}
+      />
+      <EuiSpacer size={'s'} />
+
+      <EuiCallOut
+        title="Seamless integration with index patterns!"
+        color="success"
+        iconType="indexManagementApp"
+      >
+        <p>
+          Currency formatter that we&apos;ve just created is already integrated with index patterns.
+          It can be applied to any <EuiCode>numeric</EuiCode> field of any index pattern.{' '}
+          <EuiLink onClick={() => props.deps.openIndexPatternNumberFieldEditor()}>
+            Open index pattern field editor to give it a try.
+          </EuiLink>
+        </p>
+      </EuiCallOut>
+    </>
+  );
+};
+
+const CreatingCustomFieldFormatEditor: React.FC<{ deps: Deps }> = (props) => {
+  return (
+    <>
+      <EuiText>
+        <p>
+          This example shows how to create a custom field formatter editor. As an example, we will
+          create a format editor for the currency formatter created in the previous section. This
+          custom editor will allow to select either <EuiCode>USD</EuiCode> or <EuiCode>EUR</EuiCode>{' '}
+          currency.
+        </p>
+      </EuiText>
+      <EuiSpacer size={'s'} />
+      <EuiCodeBlock>{example3SampleCode}</EuiCodeBlock>
+      <EuiSpacer size={'s'} />
+
+      <EuiCallOut
+        title="Check the result in the index pattern field editor!"
+        color="primary"
+        iconType="indexManagementApp"
+      >
+        <p>
+          Currency formatter and its custom editor are integrated with index patterns. It can be
+          applied to any <EuiCode>numeric</EuiCode> field of any index pattern.{' '}
+          <EuiLink onClick={() => props.deps.openIndexPatternNumberFieldEditor()}>
+            Open index pattern field editor to give it a try.
+          </EuiLink>
+        </p>
+      </EuiCallOut>
+    </>
+  );
+};
+
+export const App: React.FC<{ deps: Deps }> = (props) => {
+  return (
+    <EuiPage>
+      <EuiPageBody style={{ maxWidth: 1200, margin: '0 auto' }}>
+        <EuiPageHeader>
+          <EuiPageHeaderSection>
+            <EuiTitle size="l">
+              <h1>Field formats examples</h1>
+            </EuiTitle>
+          </EuiPageHeaderSection>
+        </EuiPageHeader>
+        <EuiPageContent>
+          <EuiPageContentBody style={{ maxWidth: 800, margin: '0 auto' }}>
+            <section>
+              <EuiTitle size="m">
+                <h2>Using an existing field format</h2>
+              </EuiTitle>
+              <EuiSpacer />
+              <UsingAnExistingFieldFormatExample deps={props.deps} />
+            </section>
+            <EuiSpacer />
+            <EuiSpacer />
+            <section>
+              <EuiTitle size="m">
+                <h2>Creating a custom field format</h2>
+              </EuiTitle>
+              <EuiSpacer />
+              <CreatingCustomFieldFormat deps={props.deps} />
+            </section>
+            <EuiSpacer />
+            <EuiSpacer />
+            <section>
+              <EuiTitle size="m">
+                <h2>Creating a custom field format editor</h2>
+              </EuiTitle>
+              <EuiSpacer />
+              <CreatingCustomFieldFormatEditor deps={props.deps} />
+            </section>
+          </EuiPageContentBody>
+        </EuiPageContent>
+      </EuiPageBody>
+    </EuiPage>
+  );
+};

examples/field_formats_example/public/examples/1_using_existing_format.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { SerializedFieldFormat } from '../../../../src/plugins/field_formats/common';
+import { FieldFormatsStart } from '../../../../src/plugins/field_formats/public';
+
+// 1. Assume we have an existing field format configuration serialized and saved somewhere
+// In this case it is `bytes` field formatter with a configured `'0.00b'` pattern
+// NOTE: the `params` field is not type checked and a consumer has to know the `param` format that a particular `formatId` expects,
+// https://github.com/elastic/kibana/issues/108158
+export const sampleSerializedFieldFormat: SerializedFieldFormat<{ pattern: string }> = {
+  id: 'bytes',
+  params: {
+    pattern: '0.00b',
+  },
+};
+
+export function getSample(fieldFormats: FieldFormatsStart) {
+  // 2. we create a field format instance from an existing configuration
+  const fieldFormat = fieldFormats.deserialize(sampleSerializedFieldFormat);
+
+  // 3. now we can use it to convert values
+  const pairs = [1000, 100000, 100000000].map((value) => ({
+    raw: value,
+    formatted: fieldFormat.convert(value),
+  }));
+
+  return pairs;
+}

examples/field_formats_example/public/examples/2_creating_custom_formatter.ts

@@ -0,0 +1,64 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { KBN_FIELD_TYPES } from '@kbn/field-types';
+import { FieldFormat, SerializedFieldFormat } from '../../../../src/plugins/field_formats/common';
+import { FieldFormatsSetup, FieldFormatsStart } from '../../../../src/plugins/field_formats/public';
+
+// 1. Create a custom formatter by extending {@link FieldFormat}
+export class ExampleCurrencyFormat extends FieldFormat {
+  static id = 'example-currency';
+  static title = 'Currency (example)';
+
+  // 2. Specify field types that this formatter supports
+  static fieldType = KBN_FIELD_TYPES.NUMBER;
+
+  // Or pass an array in case supports multiple types
+  // static fieldType = [KBN_FIELD_TYPES.NUMBER, KBN_FIELD_TYPES.DATE];
+
+  // 3. This formats support a `currency` param. Use `EUR` as a default.
+  getParamDefaults() {
+    return {
+      currency: 'EUR',
+    };
+  }
+
+  // 4. Implement a conversion function
+  textConvert = (val: unknown) => {
+    if (typeof val !== 'number') return `${val}`;
+
+    return new Intl.NumberFormat(undefined, {
+      style: 'currency',
+      currency: this.param('currency'),
+    }).format(val);
+  };
+}
+
+export function registerExampleFormat(fieldFormats: FieldFormatsSetup) {
+  // 5. Register a field format. This should happen in setup plugin lifecycle phase.
+  fieldFormats.register([ExampleCurrencyFormat]);
+}
+
+// 6. Now let's apply the formatter to some sample values
+export function getSample(fieldFormats: FieldFormatsStart) {
+  const exampleSerializedFieldFormat: SerializedFieldFormat<{ currency: string }> = {
+    id: 'example-currency',
+    params: {
+      currency: 'USD',
+    },
+  };
+
+  const fieldFormat = fieldFormats.deserialize(exampleSerializedFieldFormat);
+
+  const pairs = [1000, 100000, 100000000].map((value) => ({
+    raw: value,
+    formatted: fieldFormat.convert(value),
+  }));
+
+  return pairs;
+}

examples/field_formats_example/public/examples/3_creating_custom_format_editor.tsx

@@ -0,0 +1,52 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import { EuiFormRow, EuiSelect } from '@elastic/eui';
+import {
+  FieldFormatEditor,
+  FieldFormatEditorFactory,
+  IndexPatternFieldEditorSetup,
+} from '../../../../src/plugins/index_pattern_field_editor/public';
+import { ExampleCurrencyFormat } from './2_creating_custom_formatter';
+
+// 1. Create an editor component
+// NOTE: the `params` field is not type checked and a consumer has to know the `param` format that a particular `formatId` expects,
+// https://github.com/elastic/kibana/issues/108158
+const ExampleCurrencyFormatEditor: FieldFormatEditor<{ currency: string }> = (props) => {
+  return (
+    <EuiFormRow label={'Currency'}>
+      <EuiSelect
+        defaultValue={props.formatParams.currency}
+        options={[
+          { text: 'EUR', value: 'EUR' },
+          { text: 'USD', value: 'USD' },
+        ]}
+        onChange={(e) => {
+          props.onChange({
+            currency: e.target.value,
+          });
+        }}
+      />
+    </EuiFormRow>
+  );
+};
+
+// 2. Make sure it has a `formatId` that corresponds to format's id
+ExampleCurrencyFormatEditor.formatId = ExampleCurrencyFormat.id;
+
+// 3. Wrap editor component in a factory. This is needed to support and encourage code-splitting.
+const ExampleCurrencyFormatEditorFactory: FieldFormatEditorFactory<{
+  currency: string;
+}> = async () => ExampleCurrencyFormatEditor;
+ExampleCurrencyFormatEditorFactory.formatId = ExampleCurrencyFormatEditor.formatId;
+
+export function registerExampleFormatEditor(indexPatternFieldEditor: IndexPatternFieldEditorSetup) {
+  // 4. Register a field editor. This should happen in setup plugin lifecycle phase.
+  indexPatternFieldEditor.fieldFormatEditors.register(ExampleCurrencyFormatEditorFactory);
+}