From fe993d8705ec2d87a872ec6859141a25b6498b06 Mon Sep 17 00:00:00 2001 From: Caroline Horn <549577+cchaos@users.noreply.github.com> Date: Wed, 30 Mar 2022 16:41:50 -0400 Subject: [PATCH] [Docs] New Templates section (#5632) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [Docs] Create new section for “Templates” - Moves Page Template, SuperDatePicker, and Searchable Sitewide Template - Fixes routes --- scripts/a11y-testing.js | 4 +- src-docs/src/routes.js | 18 +- .../auto_refresh/auto_refresh_example.js | 2 +- .../views/bottom_bar/bottom_bar_example.js | 2 +- .../views/datagrid/_row_auto_height_data.json | 4 +- .../empty_prompt/empty_prompt_example.js | 11 +- src-docs/src/views/home/home_view.js | 2 +- ...ge_example.js => page_template_example.js} | 28 ++- .../views/page_header/page_header_example.js | 2 +- src-docs/src/views/panel/panel_example.js | 4 +- .../views/selectable/selectable_example.js | 152 --------------- .../selectable_sitewide_template_example.js | 182 ++++++++++++++++++ src-docs/src/views/tabs/tabs_example.js | 2 +- 13 files changed, 233 insertions(+), 180 deletions(-) rename src-docs/src/views/page/{page_example.js => page_template_example.js} (96%) create mode 100644 src-docs/src/views/selectable/selectable_sitewide_template_example.js diff --git a/scripts/a11y-testing.js b/scripts/a11y-testing.js index 418f333c20c..bd1da2cb97a 100644 --- a/scripts/a11y-testing.js +++ b/scripts/a11y-testing.js @@ -4,13 +4,13 @@ const { AxePuppeteer } = require('@axe-core/puppeteer'); const docsPages = async (root, page) => { const pagesToSkip = [ - `${root}#/layout/page`, // Has duplicate `
` element + `${root}#/templates/page-template`, // Has duplicate `
` element `${root}#/layout/page-header`, // Has duplicate `
` element `${root}#/display/aspect-ratio`, `${root}#/forms/combo-box`, `${root}#/forms/color-selection`, `${root}#/forms/date-picker`, - `${root}#/forms/super-date-picker`, + `${root}#/templates/super-date-picker`, ]; return [ diff --git a/src-docs/src/routes.js b/src-docs/src/routes.js index f6fd11d5e54..15838c1ae02 100644 --- a/src-docs/src/routes.js +++ b/src-docs/src/routes.js @@ -26,6 +26,12 @@ import { writingExamplesSections, } from './views/guidelines/writing_examples'; +// Templates + +import { PageTemplateExample } from './views/page/page_template_example'; + +import { SitewideSearchExample } from './views/selectable/selectable_sitewide_template_example'; + // Services import { ColorPaletteExample } from './views/color_palette/color_palette_example'; @@ -163,8 +169,6 @@ import { OutsideClickDetectorExample } from './views/outside_click_detector/outs import { OverlayMaskExample } from './views/overlay_mask/overlay_mask_example'; -import { PageExample } from './views/page/page_example'; - import { PageHeaderExample } from './views/page_header/page_header_example'; import { PaginationExample } from './views/pagination/pagination_example'; @@ -439,6 +443,14 @@ const navigation = [ }, ], }, + { + name: 'Templates', + items: [ + PageTemplateExample, + SitewideSearchExample, + SuperDatePickerExample, + ].map((example) => createExample(example)), + }, { name: 'Layout', items: [ @@ -449,7 +461,6 @@ const navigation = [ HeaderExample, HorizontalRuleExample, ModalExample, - PageExample, PageHeaderExample, PanelExample, PopoverExample, @@ -520,7 +531,6 @@ const navigation = [ SearchBarExample, SelectableExample, SuggestExample, - SuperDatePickerExample, SuperSelectExample, ].map((example) => createExample(example)), }, diff --git a/src-docs/src/views/auto_refresh/auto_refresh_example.js b/src-docs/src/views/auto_refresh/auto_refresh_example.js index 53eead3917c..80574692937 100644 --- a/src-docs/src/views/auto_refresh/auto_refresh_example.js +++ b/src-docs/src/views/auto_refresh/auto_refresh_example.js @@ -37,7 +37,7 @@ export const AutoRefreshExample = { text: (

This is a component that is used by the{' '} - + EuiSuperDatePicker {' '} component to create an automatic refresh configuration. It merely diff --git a/src-docs/src/views/bottom_bar/bottom_bar_example.js b/src-docs/src/views/bottom_bar/bottom_bar_example.js index 8dad801f5c6..73756c91328 100644 --- a/src-docs/src/views/bottom_bar/bottom_bar_example.js +++ b/src-docs/src/views/bottom_bar/bottom_bar_example.js @@ -23,7 +23,7 @@ export const BottomBarExample = {

EuiPageTemplate offers a quick way to{' '} - + apply a bottom bar to your page layouts . diff --git a/src-docs/src/views/datagrid/_row_auto_height_data.json b/src-docs/src/views/datagrid/_row_auto_height_data.json index c905eb01e22..54d1bef9229 100644 --- a/src-docs/src/views/datagrid/_row_auto_height_data.json +++ b/src-docs/src/views/datagrid/_row_auto_height_data.json @@ -2391,7 +2391,7 @@ "comments": 4, "created_at": "2021-05-04T12:44:31Z", "author_association": "NONE", - "body": "## Summary\r\n\r\nUsing the super time picker in Kibana can lead to UI crashing for edge case values (see https://github.com/elastic/kibana/issues/91138).\r\n\r\n## How to reproduce\r\n\r\n1. Navigate here https://eui.elastic.co/#/forms/super-date-picker#configurations\r\n2. Select “days ago” and entering a value of 9 9s\r\n3. See error\r\n\r\nIs there a recommended way to handle this outside of the elastic/eui lib such that we can not crash and guide users to the erroneous input?\r\n\r\n## Gif\r\n\r\n![supertimepickerbug](https://user-images.githubusercontent.com/8155004/117005090-21d59380-ace7-11eb-87ec-af7897b879f9.gif)\r\n" + "body": "## Summary\r\n\r\nUsing the super time picker in Kibana can lead to UI crashing for edge case values (see https://github.com/elastic/kibana/issues/91138).\r\n\r\n## How to reproduce\r\n\r\n1. Navigate here https://eui.elastic.co/#/templates/super-date-picker#configurations\r\n2. Select “days ago” and entering a value of 9 9s\r\n3. See error\r\n\r\nIs there a recommended way to handle this outside of the elastic/eui lib such that we can not crash and guide users to the erroneous input?\r\n\r\n## Gif\r\n\r\n![supertimepickerbug](https://user-images.githubusercontent.com/8155004/117005090-21d59380-ace7-11eb-87ec-af7897b879f9.gif)\r\n" }, { "html_url": "https://github.com/elastic/eui/issues/4774", @@ -6879,7 +6879,7 @@ "comments": 0, "created_at": "2020-09-10T20:23:33Z", "author_association": "NONE", - "body": "SuperDatePicker does not properly restore relative dates\r\n\r\nSteps to reproduce:\r\n1. Go to https://elastic.github.io/eui/#/forms/super-date-picker and to the first time picker on that page\r\n2. Click start date to edit the start date and enter `15` `months ago`\r\n![image](https://user-images.githubusercontent.com/8397647/92798784-ddbd0980-f378-11ea-975b-874cdea6a1e4.png)\r\n3. Observe SuperDatePicker puts human friendly desc in start date of `~ 1 year ago` which is handy.\r\n4. Click `Update`\r\n5. Observe the time picker reflects `15 months ago` just fine.\r\n![image](https://user-images.githubusercontent.com/8397647/92799079-21177800-f379-11ea-9c5c-b68a0b70272f.png)\r\n6. Click to edit the start date again\r\n7. Observe that `1` `year ago` is populate in the time picker GUI instead of `15 months ago`. Note the underlying date is still correct (verify this by looking at the absolute date at the bottom of the picker).\r\n![image](https://user-images.githubusercontent.com/8397647/92799418-6340b980-f379-11ea-99c0-7e470bf54bd5.png)\r\n8. As a user I would expect it to restore `15 months ago` and if I manually fix it myself it causes the dialog to get stuck in \"update mode\" (see https://github.com/elastic/eui/issues/4025)\r\n" + "body": "SuperDatePicker does not properly restore relative dates\r\n\r\nSteps to reproduce:\r\n1. Go to https://elastic.github.io/eui/#/templates/super-date-picker and to the first time picker on that page\r\n2. Click start date to edit the start date and enter `15` `months ago`\r\n![image](https://user-images.githubusercontent.com/8397647/92798784-ddbd0980-f378-11ea-975b-874cdea6a1e4.png)\r\n3. Observe SuperDatePicker puts human friendly desc in start date of `~ 1 year ago` which is handy.\r\n4. Click `Update`\r\n5. Observe the time picker reflects `15 months ago` just fine.\r\n![image](https://user-images.githubusercontent.com/8397647/92799079-21177800-f379-11ea-9c5c-b68a0b70272f.png)\r\n6. Click to edit the start date again\r\n7. Observe that `1` `year ago` is populate in the time picker GUI instead of `15 months ago`. Note the underlying date is still correct (verify this by looking at the absolute date at the bottom of the picker).\r\n![image](https://user-images.githubusercontent.com/8397647/92799418-6340b980-f379-11ea-99c0-7e470bf54bd5.png)\r\n8. As a user I would expect it to restore `15 months ago` and if I manually fix it myself it causes the dialog to get stuck in \"update mode\" (see https://github.com/elastic/eui/issues/4025)\r\n" }, { "html_url": "https://github.com/elastic/eui/issues/4024", diff --git a/src-docs/src/views/empty_prompt/empty_prompt_example.js b/src-docs/src/views/empty_prompt/empty_prompt_example.js index 16a42229dfd..4b71b487f41 100644 --- a/src-docs/src/views/empty_prompt/empty_prompt_example.js +++ b/src-docs/src/views/empty_prompt/empty_prompt_example.js @@ -317,10 +317,11 @@ export const EmptyPromptExample = { <>

When using a EuiEmptyPrompt in a{' '} - EuiPageTemplate, pay attention to the - template you’re passing. The template will determine which{' '} - color and hasBorder prop you - should use to ensure consistency across our Elastic products. + EuiPageTemplate, pay + attention to the template you’re passing. The template will + determine which color and{' '} + hasBorder prop you should use to ensure + consistency across our Elastic products.

@@ -348,7 +349,7 @@ export const EmptyPromptExample = { You can then tie multiple types of empty states together to create a seamless loading to empty or loading to error experience. The following example shows how to encorprate these states with{' '} - + EuiPageTemplate {' '} using {'template="centeredContent"'}. diff --git a/src-docs/src/views/home/home_view.js b/src-docs/src/views/home/home_view.js index b2eaaf86826..b4018422aac 100644 --- a/src-docs/src/views/home/home_view.js +++ b/src-docs/src/views/home/home_view.js @@ -186,7 +186,7 @@ export const HomeView = () => (

Page layouts are modular and fit together in a precise manner, though certain parts can also be added or removed as needed. EUI provides - both the indivdual page components and an over-arching template for - easily creating some pre-defined layouts. + both the individual page components and an + over-arching template for easily creating some + pre-defined layouts.

@@ -97,6 +98,17 @@ export const PageExample = { layout.

+ + +

+ The template is a very fragile component that will cause unexpected + results if nested. +

+ ), sections: [ @@ -390,7 +402,7 @@ export const PageExample = {

Similar to the previous example, you can create a centered panel to emphasize incompleteness even with a page header. For this setup, we - recommend using setting EuiPageContent to use the{' '} + recommend setting EuiPageContent to use the{' '} subdued color as to not have nested shadows.

- Though it is not recomended for most layouts, some require the + Though it is not recommended for most layouts, some require the control of scrolling to be handled through child components. You can achieve this through nested flex groups and overflow properties; adding certain combinations of{' '} @@ -633,7 +645,7 @@ export const PageExample = { text: (

Also similar to the previous examples, you can create a centered panel - to emphasis incompleteness even with a page header. For this setup, + to emphasize incompleteness even with a page header. For this setup, You will need to use nested EuiPageContent components in order for the centering to work.

diff --git a/src-docs/src/views/page_header/page_header_example.js b/src-docs/src/views/page_header/page_header_example.js index 90ac08d10d1..70190f8b84f 100644 --- a/src-docs/src/views/page_header/page_header_example.js +++ b/src-docs/src/views/page_header/page_header_example.js @@ -35,7 +35,7 @@ export const PageHeaderExample = {

While the EuiPageHeader component can be placed anywhere within your page layout, we recommend using it within the{' '} - + EuiPageTemplate {' '} component by passing the configuration props as its{' '} diff --git a/src-docs/src/views/panel/panel_example.js b/src-docs/src/views/panel/panel_example.js index 6b934c23706..aa8724cb5bd 100644 --- a/src-docs/src/views/panel/panel_example.js +++ b/src-docs/src/views/panel/panel_example.js @@ -88,13 +88,13 @@ export const PanelExample = { EuiPanel is a building block component. Use it as a layout helper for containing content. It is also commonly used as a base for other larger components like{' '} - + EuiPage ,{' '} EuiPopover - + {' '} and{' '} EuiCard diff --git a/src-docs/src/views/selectable/selectable_example.js b/src-docs/src/views/selectable/selectable_example.js index 64fb41972e8..d64912159ed 100644 --- a/src-docs/src/views/selectable/selectable_example.js +++ b/src-docs/src/views/selectable/selectable_example.js @@ -8,18 +8,12 @@ import { EuiSelectable, EuiSelectableMessage, EuiText, - EuiSpacer, - EuiSelectableTemplateSitewide, - EuiCodeBlock, - EuiAccordion, } from '../../../../src/components'; import { EuiSelectableOptionProps, EuiSelectableOptionsList, EuiSelectableSearchProps, - Options, - MetaData, } from './props'; import Selectable from './selectable'; const selectableSource = require('!!raw-loader!./selectable'); @@ -42,10 +36,7 @@ const selectableMessagesSource = require('!!raw-loader!./selectable_messages'); import SelectableCustomRender from './selectable_custom_render'; const selectableCustomRenderSource = require('!!raw-loader!./selectable_custom_render'); -import SearchOption from './sitewide_option'; -import Search from './search'; import { EuiCallOut } from '../../../../src/components/call_out'; -const searchSource = require('!!raw-loader!./search'); export const SelectableExample = { title: 'Selectable', @@ -413,148 +404,5 @@ export const SelectableExample = { )} `, }, - { - title: 'Sitewide search template', - source: [ - { - type: GuideSectionTypes.JS, - code: searchSource, - }, - ], - text: ( - -

- EuiSelectableTemplateSitewide is an opinionated - wrapper around EuiSelectable to provide a reusable - template across the Elastic products that will share the same global - search capabilities. It creates the search input that triggers a - popover containing the list of options. -

-

Search input

-

- The search ability of EuiSelectable is still hooked up to the - options provided. It will highlight the portion of the label that - matches the search string. -

- -

Popover

-

- The popover itself allows you to display a{' '} - popoverTitle node,{' '} - popoverFooter node, or pass any of the{' '} - popoverProps to the{' '} - - EuiPopover - {' '} - component. -

-

Options

-

- The options are the most opinionated portion of - the template. Their display is determined by the props passed in and - extends the normal EuiSelectable.option type. All - parts are optional with the exception of the label (B). -

- - - - Code snippet} - > - - - {`const options: EuiSelectableTemplateSitewideOption[] = [ - { - label: 'Label', - icon: { - type: 'logoKibana' - } - avatar: { - name: 'Default', - }, - meta: [ - { - text: 'Meta', - type: 'application', - }, - { - text: 'Deployment', - type: 'deployment', - }, - { - text: 'Default display', - }, - ], - } -]`} - - - -
    -
  • - label (required): The name of the item itself. - By default, the search box will only use this to match the search - term against, but you can supply a separate{' '} - searchableLabel that combines the label and - meta data to search on. -
    • -
  • - icon: Only display the solution or - application's logo when the option links to the application - itself (Dashboard app) and not lower-level items such as - individual dashboards. Size and color are predetermined but can be - overridden. -
    • -
  • - avatar: Represents the Kibana Space that the - item is located in, if multiple spaces are - present. Type and size are predetermined but can be overridden. -
    • -
  • - meta: This bottom line should only contain - items if the option is a lower-level item (individual dashboard). - The display of which defaults to simple text, but if you pass one - of the predetermined types, they will be styled - according to the design pattern. -
    • -
- -

Selection

-

- The options themselves are simply rendered as list items with no - interactive behavior like buttons or links. You must handle the - interaction when the component passes back the altered array of - options with the selected option having{' '} - {"checked: 'on'"}. -

-

Popover toggle and responsiveness

-

- The default display is to render the search input inline which - triggers a popover with the results. Or you can decide to trigger - the whole selectable component from a single button. By passing your - own button to popoverButton, the component will - use this to trigger the popover, putting the search inside. -

-

- This is a great way to handle reducing the size of the component for - smaller screens. The component offers a helper prop called{' '} - popoverButtonBreakpoints which will only render - the popoverButton if the window size matches - named breakpoint(s). -

- - ), - props: { EuiSelectableTemplateSitewide, Options, MetaData }, - demo: , - }, ], }; diff --git a/src-docs/src/views/selectable/selectable_sitewide_template_example.js b/src-docs/src/views/selectable/selectable_sitewide_template_example.js new file mode 100644 index 00000000000..b1d12406dc6 --- /dev/null +++ b/src-docs/src/views/selectable/selectable_sitewide_template_example.js @@ -0,0 +1,182 @@ +import React, { Fragment } from 'react'; +import { Link } from 'react-router-dom'; + +import { GuideSectionTypes } from '../../components'; + +import { + EuiCode, + EuiSpacer, + EuiSelectableTemplateSitewide, + EuiCodeBlock, + EuiAccordion, + EuiCallOut, +} from '../../../../src/components'; + +import { Options, MetaData } from './props'; + +import SearchOption from './sitewide_option'; +import Search from './search'; +const searchSource = require('!!raw-loader!./search'); + +export const SitewideSearchExample = { + title: 'Sitewide search', + description: ( +

+ EuiSelectableTemplateSitewide is an opinionated wrapper + around{' '} + + EuiSelectable + {' '} + to provide a reusable template across the Elastic products that will share + the same global search capabilities. It creates the search input that + triggers a popover containing the list of options. +

+ ), + sections: [ + { + title: 'Basic setup', + source: [ + { + type: GuideSectionTypes.JS, + code: searchSource, + }, + ], + text: ( + +

Search input

+

+ The search ability of{' '} + + EuiSelectable + {' '} + is still hooked up to the options provided. It will highlight the + portion of the label that matches the search string. +

+ +

Popover

+

+ The popover itself allows you to display a{' '} + popoverTitle node,{' '} + popoverFooter node, or pass any of the{' '} + popoverProps to the{' '} + + EuiPopover + {' '} + component. +

+

Selection

+

+ The options themselves are simply rendered as list items with no + interactive behavior like buttons or links. You must handle the + interaction when the component passes back the altered array of + options with the selected option having{' '} + {"checked: 'on'"}. +

+

Popover toggle and responsiveness

+

+ The default display is to render the search input inline which + triggers a popover with the results. Or you can decide to trigger + the whole selectable component from a single button. By passing your + own button to popoverButton, the component will + use this to trigger the popover, putting the search inside. +

+

+ This is a great way to handle reducing the size of the component for + smaller screens. The component offers a helper prop called{' '} + popoverButtonBreakpoints which will only render + the popoverButton if the window size matches + named breakpoint(s). +

+ + ), + props: { EuiSelectableTemplateSitewide, Options, MetaData }, + demo: , + }, + { + title: 'Options', + text: ( + <> +

+ The options are the most opinionated portion of + the template. Their display is determined by the props passed in and + extends the normal EuiSelectable.option type. All + parts are optional with the exception of the label (A). +

+ + + + Code snippet} + > + + + {`const options: EuiSelectableTemplateSitewideOption[] = [ + { + label: 'Label', + icon: { + type: 'logoKibana' + } + avatar: { + name: 'Default', + }, + meta: [ + { + text: 'Meta', + type: 'application', + }, + { + text: 'Deployment', + type: 'deployment', + }, + { + text: 'Default display', + }, + ], + } +]`} + + + +
    +
  • + label (required): The name of the item itself. + By default, the search box will only use this to match the search + term against, but you can supply a separate{' '} + searchableLabel that combines the label and + meta data to search on. +
    • +
  • + icon: Only display the solution or + application's logo when the option links to the application + itself (Dashboard app) and not lower-level items such as + individual dashboards. Size and color are predetermined but can be + overridden. +
    • +
  • + avatar: Represents the Kibana Space that the + item is located in, if multiple spaces are + present. Type and size are predetermined but can be overridden. +
    • +
  • + meta: This bottom line should only contain + items if the option is a lower-level item (individual dashboard). + The display of which defaults to simple text, but if you pass one + of the predetermined types, they will be styled + according to the design pattern. +
    • +
+ + + ), + }, + ], +}; diff --git a/src-docs/src/views/tabs/tabs_example.js b/src-docs/src/views/tabs/tabs_example.js index 567cb907608..4bc6d0ff39e 100644 --- a/src-docs/src/views/tabs/tabs_example.js +++ b/src-docs/src/views/tabs/tabs_example.js @@ -96,7 +96,7 @@ export const TabsExample = { size is best for when placing inside popovers or other small containers. Reserve using the large size for when using as primary page navigation, like inside of{' '} - + EuiPageHeader .