[Discover] Add field types in-product help

[andreadelrio]

Summary

This is a follow-up to the work started in ON week.

• Adds a help button next to the Filter by type dropdown. This button displays a popover with information about field types.

• Field types list taken from here:
  https://github.com/elastic/kibana/blob/2f468993d425ca89e0037920df8f8aaedf61f382/src/plugins/discover/public/application/main/components/sidebar/lib/get_field_type_name.ts

Checklist

Delete any items that are not applicable to this PR.

• Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support
  - [ ] Documentation was added for features that require explanation or tutorials
• Unit or functional tests were updated or added to match the most common scenarios
• Any UI touched in this PR is usable by keyboard only (learn more about keyboard accessibility)
• Any UI touched in this PR does not create any new axe failures (run axe in browser: FF, Chrome)
  - [ ] If a plugin configuration key changed, check if it needs to be allowlisted in the cloud and added to the docker list
• This renders correctly on smaller devices using a responsive layout. (You can test this in your browser)
• This was checked for cross-browser compatibility

Risk Matrix

Delete this section if it is not applicable to this PR.

Before closing this PR, invite QA, stakeholders, and other developers to identify risks that should be tested prior to the change/feature release.

When forming the risk matrix, consider some of the following examples and how they may potentially impact the change:

Risk	Probability	Severity	Mitigation/Notes
Multiple Spaces—unexpected behavior in non-default Kibana Space.	Low	High	Integration tests will verify that all features are still supported in non-default Kibana Space and when user switches between spaces.
Multiple nodes—Elasticsearch polling might have race conditions when multiple Kibana nodes are polling for the same tasks.	High	Low	Tasks are idempotent, so executing them multiple times will not result in logical error, but will degrade performance. To test for this case we add plenty of unit tests around this logic and document manual testing procedure.
Code should gracefully handle cases when feature X or plugin Y are disabled.	Medium	High	Unit tests will verify that any feature flag or plugin combination still results in our service operational.
See more potential risk examples

For maintainers

• This was checked for breaking API changes and was labeled appropriately

[kertal]

@elasticmachine merge upstream

[cchaos]

I 😍 this extra in-page documentation. I wonder if we can keep it around instead of allowing it to be dismissed? For instance, what if the Filter by type input had an append that triggers this popover? That way, as ES continues to add support for more field types, the user will always be able to find the full list. Maybe even add a popoer footer to a full docs page?

[andreadelrio]

I 😍 this extra in-page documentation. I wonder if we can keep it around instead of allowing it to be dismissed? For instance, what if the Filter by type input had an append that triggers this popover? That way, as ES continues to add support for more field types, the user will always be able to find the full list. Maybe even add a popoer footer to a full docs page?

I think this is a good idea! I was a bit worried about users dismissing the callout and not being able to access this info afterward. The filter dropdown currently uses EuiFilterButton which doesn't support an append. I've used EuiButtonIcon instead which I think works well too.

@gchaps what should we include in the footer?

[cchaos]

☹️ These ragged lines are breaking my designer heart.

Instead of an append you could just turn it into a filter group and add another EuiFilterButton like so: https://codesandbox.io/s/youthful-bohr-uq8tnh?file=/demo.js

[andreadelrio]

@cchaos Thanks for the feedback. This is what I came up with. I had to resort to an EUI mixin (euiFocusBackground) to add a fill to the help button. Let me know if you know of a better way to achieve that.

[elizabetdev]

@andreadelrio @cchaos I just want to share some guidelines that we've been working on with @gchaps: Figma project.

It is still a work in progress but the idea is to have some guidelines to ensure consistency in the way we show product help across our products.

• In our work in progress, the icon to this use case (documentation that opens in a popover) would be the documentation icon. Figma frame.
• Because it's clickable it would show in a primary color.

Of course, these are only ideas we have... Still WIP. So feel free to ignore them and we can revisit them later on.

It would also be great to also have your thoughts on the guidelines. So feel free to add comments on the Figma project.

[andreadelrio]

@andreadelrio @cchaos I just want to share some guidelines that we've been working on with @gchaps: Figma project.

It is still a work in progress but the idea is to have some guidelines to ensure consistency in the way we show product help across our products.

• In our work in progress, the icon to this use case (documentation that opens in a popover) would be the documentation icon. Figma frame.
• Because it's clickable it would show in a primary color.

Of course, these are only ideas we have... Still WIP. So feel free to ignore them and we can revisit them later on.

It would also be great to also have your thoughts on the guidelines. So feel free to add comments on the Figma project.

This is great @miukimiu ! Thanks for bringing it up. I actually think this could also fall under the Field description - long text category as we're not explaining how a feature works but providing info on the field types. This would be a new case to consider adding to our guidelines under that category: using an append.

On a separate note and following up on the background color which I added to try to mimic the behavior of EuiFormLayout's append. I wanted to point out that because of the way this is currently built when the EuiFilterButton on the left receives focus it gets a gray background that matches the color of the "append". I don't love how that looks. @cchaos Do you think this makes it worth considering adding proper prepend/append support for EuiFilterGroup? Especially considering we're developing guidelines for this type of in-product help.

[gchaps]

Is this the complete list of field types? I thought there were more.

As for the footer, I agree that we should include a link to the ES docs.

[cchaos]

Great reference @miukimiu , thank you! We really should get those finalized.

I agree with @andreadelrio here though, that this isn't a "How this feature works" but more like a cheatsheet. I see it falling more under the category of Field description: Long content with formatting so probably just need to change this to an iInCircled icon.

[andreadelrio]

@kertal I pushed some changes to hopefully clean up the code for the table and added a separate file to keep the description texts (now i18n ready). Do you think you can help me add pagination to it? 6 rows per page would be ideal and we don't need the "Rows per page" button.

[kertal]

@kertal I pushed some changes to hopefully clean up the code for the table and added a separate file to keep the description texts (now i18n ready). Do you think you can help me add pagination to it? 6 rows per page would be ideal and we don't need the "Rows per page" button.

Thx for this great work! For sure I can help, but more likely next week. There are also some "unknown" fields like "date_range" we should explain (after researching what they're doing)

[andreadelrio]

@kertal I pushed some changes to hopefully clean up the code for the table and added a separate file to keep the description texts (now i18n ready). Do you think you can help me add pagination to it? 6 rows per page would be ideal and we don't need the "Rows per page" button.

Thx for this great work! For sure I can help, but more likely next week. There are also some "unknown" fields like "date_range" we should explain (after researching what they're doing)

@kertal awesome thanks! @gchaps is working on the remaining descriptions

[kertal]

@elasticmachine merge upstream

[andreadelrio]

@kertal please let me know if it's possible to have links inside i18n.translate like @gchaps is asking.
@cchaos thanks for your comments and PR! It looks a lot better. I felt something off with the footer and your solution is perfect. I merged your PR and addressed the rest of your feedback.

[dimaanj]

@kertal please let me know if it's possible to have links inside i18n.translate like @gchaps is asking.

Yes, there is an example here.

i18n.translate('discover.advancedSettings.disableDocumentExplorerDescription', {
  defaultMessage:
    'To use the new {documentExplorerDocs} instead of the classic view, turn off this option. ' +
    'The Document Explorer offers better data sorting, resizable columns, and a full screen view.',
  values: {
    documentExplorerDocs:
      `<a href=${docLinks.links.discover.documentExplorer}
        target="_blank" rel="noopener">` +
      i18n.translate('discover.advancedSettings.documentExplorerLinkText', {
        defaultMessage: 'Document Explorer',
      }) +
      '</a>',
  },
});

[kertal]

@kertal please let me know if it's possible to have links inside i18n.translate like @gchaps is asking.

Just wanted to add to @dmitriynj suggestion, there's another way to do it, using react components in the values property:

kibana/src/plugins/discover/public/application/main/components/document_explorer_callout/document_explorer_update_callout.tsx

Lines 66 to 80 in d0c06b0

	<FormattedMessage
	id="discover.docExplorerUpdateCallout.bodyMessage"
	defaultMessage="Experience the new {documentExplorer}. Understand the shape of your data with {fieldStatistics}."
	values={{
	fieldStatistics: (
	<span css={semiBoldStyle}>
	<FormattedMessage
	id="discover.docExplorerUpdateCallout.fieldStatistics"
	defaultMessage="Field Statistics"
	/>
	</span>
	),
	documentExplorer: (
	<span css={semiBoldStyle}>
	<FormattedMessage

FYI @jughosta , sharing i18n knowledge that's not obvious

[cchaos]

Since the pagination component is removed now, there's a lot of logic/variables you don't need either.

[kertal]

@elasticmachine merge upstream

[kertal]

Code LGTM, this is great especially for users starting with Kibana and ES, also of course for all others 🎉 . Discover is now supporting better understanding of Elasticsearch basics.

Tested locally using Safari, Firefox, Chrome, works as expected. Last thing I wondered, was the font-size in the mobile view, which seems to be large. But this might be right this way, for mobile users targeting better readability. So not a blocker, just an observation:

[andreadelrio]

@elasticmachine merge upstream

[gchaps]

LGTM!!

[cchaos]

Looks great!

[andreadelrio]

@elasticmachine merge upstream

[kibana-ci]

💚 Build Succeeded

• Buildkite Build
• Commit: 58c07f7
• Storybooks Preview
• Cloud Deployment
• Webpack Bundle Analyzer

Metrics [docs]

Module Count

Fewer modules leads to a faster build time

id	before	after	diff
discover	445	446	+1

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
discover	400.7KB	406.8KB	+6.0KB

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
core	318.9KB	319.0KB	+120.0B

Unknown metric groups

ESLint disabled line counts

id	before	after	diff
discover	35	36	+1

Total ESLint disabled count

id	before	after	diff
discover	37	38	+1

History

• 💚 Build #36962 succeeded 17b25b8
• 💔 Build #36731 failed ea7cdd2
• 💔 Build #36720 failed 24dfdba
• 💔 Build #36650 failed 1fb3afb
• 💔 Build #36342 failed 1435c12
• 💔 Build #36289 failed 66ced34

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @andreadelrio