From 50a0ff235b2ea1d620c3d5a01cfe7c9cd296b939 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 13:57:13 -0700 Subject: [PATCH 01/10] Ensure callouts always receive appropriate margin-top from preceding elements - particularly for `
    / ``` -:::note Give lists an accessible name to improve their discoverability! - +:::tip Give lists an accessible label to improve their discoverability! ```

    My favorite fruit

    @@ -350,7 +347,6 @@ Here, the 3 buttons have the same accessible name. There are a few different pat ``` - ::: ### Further reading From 5d09a9af3e4171d2bf2d3b2c0bb01fd69617e574 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:25:37 -0700 Subject: [PATCH 04/10] Tweak more callouts to use the new `tip` type - more friendly and helpful to denote callouts that are more usage guidelines or nice-to-haves + remove duplicate content + minor copy tweaks --- packages/website/docs/components/display/card.mdx | 8 ++------ packages/website/docs/components/display/image.mdx | 2 +- .../docs/components/editors_and_syntax/code.mdx | 4 +--- .../website/docs/components/forms/range_sliders.mdx | 2 +- packages/website/docs/components/forms/selectable.mdx | 10 +++++----- .../website/docs/components/forms/super_select.mdx | 2 +- packages/website/docs/components/layout/bottom_bar.mdx | 4 +--- .../components/layout/page_components/overview.mdx | 4 +--- .../website/docs/components/tabular_content/tables.mdx | 2 +- .../components/templates/page_template/overview.mdx | 4 +--- 10 files changed, 15 insertions(+), 27 deletions(-) diff --git a/packages/website/docs/components/display/card.mdx b/packages/website/docs/components/display/card.mdx index ad9afd7d692..db34238ce35 100644 --- a/packages/website/docs/components/display/card.mdx +++ b/packages/website/docs/components/display/card.mdx @@ -89,9 +89,7 @@ export default () => ( Images can be added in place of, or in conjuction with, icons. Just pass a url into the `image` prop and it will expand to the edges of the card. -:::note Make sure that all images are the same proportions when used in a singular row. - -Make sure that all images are the **same proportions** when used in a singular row. +:::tip Make sure that all images are the **same proportions** when used in a singular row. Also, when passing an **element** to the `image` prop that consists solely of inline elements or does not contain an`` element, each element will require a style of `width: 100%`. @@ -293,10 +291,8 @@ export default () => ( When you have a list of cards that can be selected but **do not navigate anywhere**, you can add the `selectable` prop. The prop is an object that extends **EuiButtonEmpty**. It will apply the button as seen below, and passing `selectable.isSelected=true` will alter the styles of the card and button to look selected. -:::warning - +:::tip When providing an extra link to more details or such, be sure to stop event propagation from also selecting the card. - ::: ```tsx interactive diff --git a/packages/website/docs/components/display/image.mdx b/packages/website/docs/components/display/image.mdx index 74d91786e0c..d3042dc64a4 100644 --- a/packages/website/docs/components/display/image.mdx +++ b/packages/website/docs/components/display/image.mdx @@ -7,7 +7,7 @@ id: display_image Use **EuiImage** when you need to place a static image into a page with an optional caption. -:::note Writing meaningful image alt text +:::tip Writing meaningful image alt text This page has several examples of alt text written to aid screen reader users, as well as several examples of when _not_ to include alt text. When an image is decorative, or if the image is adequately described by surrounding text, it is better to pass an empty `""` string instead. diff --git a/packages/website/docs/components/editors_and_syntax/code.mdx b/packages/website/docs/components/editors_and_syntax/code.mdx index c63d9b5cc02..32c3d592524 100644 --- a/packages/website/docs/components/editors_and_syntax/code.mdx +++ b/packages/website/docs/components/editors_and_syntax/code.mdx @@ -5,10 +5,8 @@ id: editors_syntax_code # Code -:::note - +:::tip **EuiCode** and **EuiCodeBlock** are intended to render static lines or blocks of code in **read-only** contexts. If you need capabilities to edit, or want to print long code (e.g., printing JSON from an API), we recommend installing a version of Monaco. If you are building within the Kibana platform, you can use their [**CodeEditor**](https://github.com/elastic/kibana/tree/main/packages/shared-ux/code_editor/impl). - ::: The **EuiCode** and **EuiCodeBlock** components support [all language syntaxes](https://prismjs.com/#supported-languages) supported by the `prism` [library](https://prismjs.com/). The `language` prop can also be omitted to simply render formatted but unhighlighted code. diff --git a/packages/website/docs/components/forms/range_sliders.mdx b/packages/website/docs/components/forms/range_sliders.mdx index 9d6cbad3c3e..0b3da2b2876 100644 --- a/packages/website/docs/components/forms/range_sliders.mdx +++ b/packages/website/docs/components/forms/range_sliders.mdx @@ -5,7 +5,7 @@ id: forms_range_sliders # Range sliders -:::warning Understanding precision +:::tip Understanding precision Range sliders should only be used when **the precise value is not considered important**. If the precise value does matter, add the `showInput` prop or use a **EuiFieldNumber** instead. diff --git a/packages/website/docs/components/forms/selectable.mdx b/packages/website/docs/components/forms/selectable.mdx index 9273493f7d2..6b92af2a2fc 100644 --- a/packages/website/docs/components/forms/selectable.mdx +++ b/packages/website/docs/components/forms/selectable.mdx @@ -11,9 +11,11 @@ id: forms_selectable At its simplest, **EuiSelectable** requires an array of `options` and an `onChange` handler which passes back the altered `selectedOptions` array. The `children` is a function that return the `list` and `search` nodes. -:::note Selected options are based on the checked = on property +:::tip Selected options are based on the checked = on property -**EuiSelectable** offers the ability to **exclude** selections or **include selections for some** (mixed). Therefore, the `checked` property is one of `undefined | 'on' | 'off' | 'mixed'`, `'on'` being the default for selected options when `allowExclusions = false`. +**EuiSelectable** offers the ability to **exclude** selections or **include selections for some** (mixed). Therefore, the `checked` property is one of `undefined | 'on' | 'off' | 'mixed'`. + +`'on'` is the default for selected options when `allowExclusions = false`. ::: @@ -77,10 +79,8 @@ export default () => { To add a search component to the list, simply add the `searchable` prop. You can optionally pass in a `searchProps` object which will get passed down to the actual **EuiFieldSearch** used. In this example,`onSearch` will return a second parameter, enabling you to access the list of filtered items -:::note The search is performed as a string match against the option.label unless a separate option.searchableLabel is provided. - +:::tip The search is performed as a string match against the `option.label` unless a separate `option.searchableLabel` is provided. - ::: ```tsx interactive diff --git a/packages/website/docs/components/forms/super_select.mdx b/packages/website/docs/components/forms/super_select.mdx index 45fac22a687..9fe74c2dc67 100644 --- a/packages/website/docs/components/forms/super_select.mdx +++ b/packages/website/docs/components/forms/super_select.mdx @@ -5,7 +5,7 @@ id: forms_super_select # Super select -:::note Not sure which selection component to use? +:::tip Not sure which selection component to use? See [EUI's in-depth guide to selection components ](https://github.com/elastic/eui/discussions/7049) for more information. diff --git a/packages/website/docs/components/layout/bottom_bar.mdx b/packages/website/docs/components/layout/bottom_bar.mdx index 0cdc969b78f..a0ebc1f270d 100644 --- a/packages/website/docs/components/layout/bottom_bar.mdx +++ b/packages/website/docs/components/layout/bottom_bar.mdx @@ -5,10 +5,8 @@ id: layout_bottom_bar # Bottom bar -:::note - +:::tip **EuiPageTemplate** offers a quick way to [apply a bottom bar to your page layouts](/docs/templates/page-template#showing-a-bottom-bar). - ::: **EuiBottomBar** is a simple wrapper component that does nothing but affix a dark bar (usually filled with buttons) to the bottom of the page. Use it when you have really long pages or complicated, multi-page forms. In the case of forms, only invoke it if a form is in a savable state. diff --git a/packages/website/docs/components/layout/page_components/overview.mdx b/packages/website/docs/components/layout/page_components/overview.mdx index e18b9576486..c74aa7851e8 100644 --- a/packages/website/docs/components/layout/page_components/overview.mdx +++ b/packages/website/docs/components/layout/page_components/overview.mdx @@ -180,10 +180,8 @@ When using [**EuiEmptyPrompt**](/docs/display/empty-prompt) to replace the main -:::note - +:::tip Reminder: [**EuiPageTemplate**](/docs/templates/page-template) can handle all these configurations for you. - ::: diff --git a/packages/website/docs/components/tabular_content/tables.mdx b/packages/website/docs/components/tabular_content/tables.mdx index d6a05c6d29c..9d056e2a7b4 100644 --- a/packages/website/docs/components/tabular_content/tables.mdx +++ b/packages/website/docs/components/tabular_content/tables.mdx @@ -5,7 +5,7 @@ id: tabular_content_tables # Tables -:::note EUI provides opinionated and non-opinionated ways to build tables +:::tip EUI provides opinionated and non-opinionated ways to build tables Tables can get complicated very fast. If you're just looking for a basic table with pagination, sorting, checkbox selection, and actions then you should use **EuiBasicTable**. It's a **high level component** that removes the need to worry about constructing individual components together. You simply arrange your data in the format it asks for. diff --git a/packages/website/docs/components/templates/page_template/overview.mdx b/packages/website/docs/components/templates/page_template/overview.mdx index c19a6dd3171..2a8ae55b7e2 100644 --- a/packages/website/docs/components/templates/page_template/overview.mdx +++ b/packages/website/docs/components/templates/page_template/overview.mdx @@ -19,10 +19,8 @@ All templates should start with a wrapping `EuiPageTemplate` to control some sha With the exception of `.Sidebar` and `.BottomBar`, the stacking order of the page contents is determined by the order they are passed in. You can also override the outer props by simply applying them directly to the child element. -:::note - +:::tip If you have a fixed position [headers](/docs/layout/header#fixed-header), the template will automatically account for the padding `offset` based on the total number of page headers. If you do not want the template to calculate this, you can pass `0` in as the manual `offset`. - ::: ```tsx interactive From c21837b6a1db56ddf545ac414d1ac352c71069e6 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:31:24 -0700 Subject: [PATCH 05/10] Adjust a few more info vs warning levels IMO, a `warning` should be used if component UI/UX will break in some way if the warning is not read The `info` status can be more generic, or apply to specific techncial DX --- packages/website/docs/components/display/progress.mdx | 4 ++-- packages/website/docs/components/forms/range_sliders.mdx | 4 ++-- .../website/docs/components/navigation/collapsible_nav.mdx | 4 +--- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/packages/website/docs/components/display/progress.mdx b/packages/website/docs/components/display/progress.mdx index a0b3d9ae61c..6b1809858bc 100644 --- a/packages/website/docs/components/display/progress.mdx +++ b/packages/website/docs/components/display/progress.mdx @@ -88,9 +88,9 @@ export default () => { Using the `position` prop we can align our bar to be `fixed` or `absolute`. In both options, the background color of the base bar is dropped (since the context of width is already known from your wrapping element). For the absolute option, make sure that your wrapping element has `position: relative` applied. -:::note Note about progress bars over fixed headers +:::warning Progress bars over fixed headers -Using **EuiProgress** with a `fixed` position may result in it being overlayed when its parent wrapper has a `z-index` value lower than another fixed element, such as **EuiHeader**. In that case, wrap **EuiProgress** in an **EuiPortal** as seen on the Snippet tab. +Using the `fixed` position may result in **EuiProgress** being overlayed when its parent wrapper has a `z-index` value lower than another fixed element, such as **EuiHeader**. In this scenario, wrap **EuiProgress** in an **EuiPortal** (example below). ::: diff --git a/packages/website/docs/components/forms/range_sliders.mdx b/packages/website/docs/components/forms/range_sliders.mdx index 0b3da2b2876..f81b820e85c 100644 --- a/packages/website/docs/components/forms/range_sliders.mdx +++ b/packages/website/docs/components/forms/range_sliders.mdx @@ -98,9 +98,9 @@ export default () => { The **EuiDualRange** accepts almost all the same props as the regular **EuiRange**, with the exception of `showRange` which is on by default, and `showValue` since tooltips don't fit properly when there are two. -:::warning Retrieving field values +:::info Retrieving field values -Two-value `input[type=range]` elements are not part of the HTML5 specification. Because of this support gap, **EuiDualRange** cannot expose a native `value` property for native form to consumption. **The React `onChange` prop is the recommended method for retrieving the upper and lower values.** +Two-value `input[type=range]` elements are not part of the HTML5 specification. Because of this support gap, **EuiDualRange** does not (by default) expose a native `value` property for form consumption. The React `onChange` prop is the recommended method for retrieving the upper and lower values. **EuiDualRange** does use native inputs to help validate step values and range limits. These may be used as form values when `showInput` is in use. The alternative is to store values in `input[type=hidden]`. diff --git a/packages/website/docs/components/navigation/collapsible_nav.mdx b/packages/website/docs/components/navigation/collapsible_nav.mdx index 3486b0cf253..e17522a2b69 100644 --- a/packages/website/docs/components/navigation/collapsible_nav.mdx +++ b/packages/website/docs/components/navigation/collapsible_nav.mdx @@ -9,10 +9,8 @@ This is a high level component that creates a flyout-style navigational pane. **EuiCollapsibleNav** is a custom implementation of [**EuiFlyout**](/docs/layout/flyout); the visibility of which must still be maintained by the consuming application. An extra feature that it provides is the ability to `dock` the flyout. This affixes the flyout to the window and pushes the body content by adding left side padding. -:::note - +:::warning Docking is not possible on small screens because it would force less real estate for the page content. - ::: ```tsx interactive From b9818091fd188c0966de46b5e368f30a9483195e Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:33:16 -0700 Subject: [PATCH 06/10] Remove remaining duplicate callout titles --- packages/website/docs/components/display/card.mdx | 4 +--- .../components/elastic_charts/accessibility_features.mdx | 4 +--- packages/website/docs/components/navigation/breadcrumbs.mdx | 6 ++---- .../website/docs/components/tabular_content/data_grid.mdx | 4 +--- .../docs/components/templates/page_template/overview.mdx | 4 +--- 5 files changed, 6 insertions(+), 16 deletions(-) diff --git a/packages/website/docs/components/display/card.mdx b/packages/website/docs/components/display/card.mdx index db34238ce35..43e3e4a51eb 100644 --- a/packages/website/docs/components/display/card.mdx +++ b/packages/website/docs/components/display/card.mdx @@ -41,10 +41,8 @@ export default () => {cardNodes}; Most of the time, cards should read from top to bottom (vertical). However, in some cases, you may want the icon to be to the left of the content. In this case, add the prop `layout="horizontal"`. Works best when the icon is size `xl`. -:::danger Horizontal layouts do not work with images, footers, or textAlign. Therefore, these properties will be ignored. - +:::danger Horizontal layouts **do not** work with images, footers, or `textAlign`. Therefore, these properties will be ignored. - ::: ```tsx interactive diff --git a/packages/website/docs/components/elastic_charts/accessibility_features.mdx b/packages/website/docs/components/elastic_charts/accessibility_features.mdx index 285151c26d2..396900831f7 100644 --- a/packages/website/docs/components/elastic_charts/accessibility_features.mdx +++ b/packages/website/docs/components/elastic_charts/accessibility_features.mdx @@ -70,10 +70,8 @@ You may want to set a heading level if there are multiple charts on the page but ``` -:::warning ariaDescribedBy will override ariaDescription if both are specified. - +:::warning `ariaDescribedBy` will override `ariaDescription` if both are specified. - ::: `ariaUseDefaultSummary` is a boolean defaulted to `true`. The default summary is bare bones and only reports the chart type(s). Some chart types provide more information but today that is only Gauge and Goal charts. If you are passing in a custom description, you can disable this prop. diff --git a/packages/website/docs/components/navigation/breadcrumbs.mdx b/packages/website/docs/components/navigation/breadcrumbs.mdx index 682805719b3..b1f679abec6 100644 --- a/packages/website/docs/components/navigation/breadcrumbs.mdx +++ b/packages/website/docs/components/navigation/breadcrumbs.mdx @@ -351,10 +351,8 @@ You may also pass `popoverProps` with almost any prop that [**EuiPopover**](/doc If you need the ability to close the breadcrumb popover from within your popover content, `popoverContent` accepts a render function that will be passed a `closePopover` callback, which you can invoke to close the popover. See the Deployment breadcrumb below for example usage. -:::warning Please note that creating a breadcrumb with a popover will nullify any passed href or onClick behavior, as the only interaction the breadcrumb should have at that point is the popover toggle. - -Please note that creating a breadcrumb with a popover will nullify any passed `href` or `onClick` behavior, as the _only_ interaction the breadcrumb should have at that point is the popover toggle. - +:::warning +Creating a breadcrumb with a popover will nullify any passed `href` or `onClick` behavior, as the _only_ interaction the breadcrumb should have at that point is the popover toggle. ::: ```tsx interactive diff --git a/packages/website/docs/components/tabular_content/data_grid.mdx b/packages/website/docs/components/tabular_content/data_grid.mdx index 3c9084bbb82..1a80ddb2b24 100644 --- a/packages/website/docs/components/tabular_content/data_grid.mdx +++ b/packages/website/docs/components/tabular_content/data_grid.mdx @@ -651,9 +651,7 @@ export default () => { Creating a lot of DOM nodes is computationally expensive, and **EuiDataGrid** uses a couple wrapping divs to build each cell. To help offset the cost of larger tables, cell virtualization can be opted into by constraining the grid's height and/or width. There are two ways to enable this functionality. First, `height` and/or `width` can be passed as props, which are applied to the grid's container style. Alternatively, if **EuiDataGrid** is unable to render at the full dimensions it needs due to screen real estate or other DOM constraints, it will overflow within a scrollable container and only render the visible cells. -:::warning Never toggle the height between a value and undefined. - -Never toggle the height between a value and `undefined`. +:::warning Never toggle the height between a value and `undefined`. Similar to React's rule of not switching between a controlled and uncontrolled input, `EuiDataGrid` does not accommodate for its height switching to or from `undefined`. For demonstration purposes, the example below uses a `key` to force **EuiDataGrid** to completely remount when its height changes between constrained & constrained heights. diff --git a/packages/website/docs/components/templates/page_template/overview.mdx b/packages/website/docs/components/templates/page_template/overview.mdx index 2a8ae55b7e2..3f081f80bfe 100644 --- a/packages/website/docs/components/templates/page_template/overview.mdx +++ b/packages/website/docs/components/templates/page_template/overview.mdx @@ -162,10 +162,8 @@ It uses the `sticky` position so that it sticks to the bottom of and remains wit It will also keep its content constrained to the `restrictedWidth` value so the contents are always horizontally aligned. -:::warning For proper alignment in case of short content, at least one EuiPageTemplate.Section must have grow={true}. - +:::warning For proper alignment in case of short content, at least one **EuiPageTemplate.Section** must have `grow={true}`. - ::: ```tsx interactive From c1b821baaeac2aea8b224f10b9affd31a8b3d421 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:34:31 -0700 Subject: [PATCH 07/10] Misc callout copy improvements/tweaks --- packages/website/docs/components/display/badge.mdx | 2 +- .../website/docs/components/display/drag_and_drop.mdx | 2 +- packages/website/docs/components/display/text.mdx | 8 ++------ .../website/docs/components/display/tour/overview.mdx | 4 +--- .../website/docs/components/forms/compressed_forms.mdx | 2 +- .../docs/components/tabular_content/in_memory_tables.mdx | 6 ++++-- 6 files changed, 10 insertions(+), 14 deletions(-) diff --git a/packages/website/docs/components/display/badge.mdx b/packages/website/docs/components/display/badge.mdx index f5edb6d71b3..e6491e6455f 100644 --- a/packages/website/docs/components/display/badge.mdx +++ b/packages/website/docs/components/display/badge.mdx @@ -131,7 +131,7 @@ export default () => ( Badges can have `onClick` events applied to the badge itself or the icon within the badge. The latter option is useful for when you might use badges in other components (like a tag system with autocomplete where you need close events). -:::note onClick with iconOnClick +:::note `onClick` with `iconOnClick` When providing both these click handlers, **EuiBadge** must alter the contents so that it does not contain nested button tags. Please make note that if you provide props other than those explicit to **EuiBadge**, they will always be applied to the main `button` tag which may be inside of the outer most tag. diff --git a/packages/website/docs/components/display/drag_and_drop.mdx b/packages/website/docs/components/display/drag_and_drop.mdx index e8274bfb8cf..6db879aaff8 100644 --- a/packages/website/docs/components/display/drag_and_drop.mdx +++ b/packages/website/docs/components/display/drag_and_drop.mdx @@ -11,7 +11,7 @@ An extension of [@hello-pangea/dnd](https://github.com/hello-pangea/dnd) (which * ``: Area into which items can be dropped. Contains one or more ``. * ``: Items that can be dragged. Must be part of an `` -:::warning Consider your users, use case +:::warning Consider your users and use case Drag and drop interfaces are not well-adapted to many cases, and may be less suitable than other form types for data operations. For instance, drag and drop interaction relies heavily on spatial orientation that may not be entirely valid to all users (e.g., screen readers as the sole source of information). Similarly, users navigating by keyboard may not be afforded nuanced, dual-axis drag item manipulation. diff --git a/packages/website/docs/components/display/text.mdx b/packages/website/docs/components/display/text.mdx index ba15cf799df..97bf3c7a647 100644 --- a/packages/website/docs/components/display/text.mdx +++ b/packages/website/docs/components/display/text.mdx @@ -5,15 +5,11 @@ id: display_text # Text -**EuiText** is a generic catchall wrapper that will apply our standard typography styling and spacing to naked HTML. Because of its forced style it **only accepts raw XHTML**. - -:::note When using EuiText, keep in mind: - -When using **EuiText**, keep in mind: +**EuiText** is a generic catchall wrapper that will apply our standard typography styling and spacing to naked HTML. Because of its forced styles, it **only accepts raw XHTML**. +:::warning * All your **XHTML** elements should be direct descendants of **EuiText**. You should avoid wrapping them in a `div` or `span`. This will ensure styles are applied correctly. * Avoid nesting React components which would break their styling. - ::: **EuiText** can ensure proper line-length for readability by setting a `max-width` on the entire component. To add the max-width setting, set `grow=false`. diff --git a/packages/website/docs/components/display/tour/overview.mdx b/packages/website/docs/components/display/tour/overview.mdx index 4a2cd8eb84d..aee449b2a27 100644 --- a/packages/website/docs/components/display/tour/overview.mdx +++ b/packages/website/docs/components/display/tour/overview.mdx @@ -8,9 +8,7 @@ id: display_tour The tour components provided by EUI allow for a flexible and customizable way to showcase items on a page in an ordered manner by augmenting existing elements on the page without altering functionality. :::note - -The examples on this page, use localStorage to persist state to demonstrate starting a tour at different stages. - +The examples on this page use localStorage to persist state to demonstrate starting a tour at different stages. ::: ## Step options diff --git a/packages/website/docs/components/forms/compressed_forms.mdx b/packages/website/docs/components/forms/compressed_forms.mdx index 085172ef677..257c7569202 100644 --- a/packages/website/docs/components/forms/compressed_forms.mdx +++ b/packages/website/docs/components/forms/compressed_forms.mdx @@ -322,7 +322,7 @@ export default () => ( ## In a popover -Always use the compressed version of forms and elements when they exist inside of a[popover](/docs/layout/popover). +Always use the compressed version of forms and elements when they exist inside of a [popover](/docs/layout/popover). ```tsx interactive import React, { useState } from 'react'; diff --git a/packages/website/docs/components/tabular_content/in_memory_tables.mdx b/packages/website/docs/components/tabular_content/in_memory_tables.mdx index 180de29f218..426cb3bdf13 100644 --- a/packages/website/docs/components/tabular_content/in_memory_tables.mdx +++ b/packages/website/docs/components/tabular_content/in_memory_tables.mdx @@ -7,9 +7,11 @@ id: tabular_content_in_memory_tables The **EuiInMemoryTable** is a higher level component wrapper around **EuiBasicTable** aimed at displaying tables data when all the data is in memory. It takes the full set of data (all possible items) and based on its configuration, will display it handling all configured functionality (pagination and sorting) for you. -:::warning EuiMemoryTable relies on referential equality of a column's name +:::warning Column names must be referentially stable -**EuiMemoryTable** relies on referential equality of a column's `name` field when sorting by that column. For example, if a JSX element is created for the name every render it appears different to the table and prevents sorting. Instead, that value needs to be lifted outside of the render method and preserved between renders. +**EuiMemoryTable** relies on referential equality of a column's `name` field when sorting by that column. This particularly applies to **JSX nodes**. + +If your JSX `name` is not defined outside a component `render` cycle or is not correctly memoized with `useMemo`, it will break sorting and other in-memory comparisons. ::: From 4847acee4dd54c054f0b9ee771c46c03fb87273c Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:35:00 -0700 Subject: [PATCH 08/10] Fix incorrect docusaurus callout MDX in writing guidelines - should be using EUI components as part of the example --- .../docs/components/guidelines/writing/guidelines.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/website/docs/components/guidelines/writing/guidelines.mdx b/packages/website/docs/components/guidelines/writing/guidelines.mdx index 03d9c553918..333ad17865f 100644 --- a/packages/website/docs/components/guidelines/writing/guidelines.mdx +++ b/packages/website/docs/components/guidelines/writing/guidelines.mdx @@ -7,6 +7,7 @@ sidebar_position: 3 import { EuiCard, + EuiCallOut, EuiFlexGroup, EuiButton, EuiPanel, @@ -100,9 +101,9 @@ Proper nouns include product names, solutions, apps, feature tiers, and subscrip - :::note Building a dashboard? - Create content directly from our Dashboard app using our new integrated workflow. [Learn more](https://brand.elastic.co/302f66895/p/072ccc-naming-guide) - ::: + + Create content directly from our Dashboard app using our new integrated workflow. Learn more + For more information, view the [Elastic name guidelines.](https://brand.elastic.co/302f66895/p/072ccc-naming-guide) From 8479b41c3cf4040b5cef68fe9a306a05aa4017ed Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:35:32 -0700 Subject: [PATCH 09/10] Remove EuiDataGrid docs callout mdx nested within bullet points - just use sub-bullet-points instead --- .../tabular_content/data_grid_advanced.mdx | 21 ++++------------- .../data_grid_cells_and_popovers.mdx | 23 +++++-------------- 2 files changed, 11 insertions(+), 33 deletions(-) diff --git a/packages/website/docs/components/tabular_content/data_grid_advanced.mdx b/packages/website/docs/components/tabular_content/data_grid_advanced.mdx index 3e6e41af325..54237e9fc8b 100644 --- a/packages/website/docs/components/tabular_content/data_grid_advanced.mdx +++ b/packages/website/docs/components/tabular_content/data_grid_advanced.mdx @@ -9,22 +9,11 @@ id: tabular_content_data_grid_advanced For advanced use cases, and particularly for data grids that manage associated modals/flyouts and need to manually control their grid cell popovers & focus states, we expose certain internal methods via the `ref` prop of **EuiDataGrid**. These methods are: -* `setIsFullScreen(isFullScreen)` - controls the fullscreen state of the data grid. Accepts a true/false boolean flag. - -* `setFocusedCell({ rowIndex, colIndex })` - focuses the specified cell in the grid. - - :::warning Using this method is an accessibility requirement if your data grid toggles a modal or flyout. - - - - - Your modal or flyout should restore focus into the grid on close to prevent keyboard or screen reader users from being stranded. - - ::: - -* `openCellPopover({ rowIndex, colIndex })` - opens the specified cell's popover contents. - -* `closeCellPopover()` - closes any currently open cell popover. +* `setIsFullScreen(isFullScreen)` - controls the fullscreen state of the data grid. Accepts a true/false boolean flag. +* `setFocusedCell({ rowIndex, colIndex })` - focuses the specified cell in the grid. + * Using this method is an **accessibility requirement** if your data grid toggles a modal or flyout. Your modal or flyout should restore focus into the grid on close to prevent keyboard or screen reader users from being stranded. +* `openCellPopover({ rowIndex, colIndex })` - opens the specified cell's popover contents. +* `closeCellPopover()` - closes any currently open cell popover. :::note Handling cell location diff --git a/packages/website/docs/components/tabular_content/data_grid_cells_and_popovers.mdx b/packages/website/docs/components/tabular_content/data_grid_cells_and_popovers.mdx index 2c240efaf57..35a1340ad3f 100644 --- a/packages/website/docs/components/tabular_content/data_grid_cells_and_popovers.mdx +++ b/packages/website/docs/components/tabular_content/data_grid_cells_and_popovers.mdx @@ -404,23 +404,12 @@ If you want complete control over the rendering of the entire cell popover, use To make falling back to atoms of the default cell popover easier, several props are passed to your custom `renderCellPopover` function: -* `children` - the direct JSX output of the cell's returned `renderCellValue`. It can be used (e.g.) if you want a custom wrapper or cell actions, but default popover content. - -* `cellContentsElement` - a direct reference to the cell's HTML content node, which allows accessing the cell's `innerText` for cases where raw non-JSX text is useful (e.g. copying). - -* `cellActions` - the direct JSX output of the default popover footer and buttons. Use this prop if you want custom popover content but default cell actions.:::warning Using custom cell actions - - - - - If deliberately leaving out the default `cellActions`, you **must** re-implement your cell actions in the popover in some form. Leaving out cell actions available in the cell but not in the popover introduces UX inconsistencies and will confuse the end user. - - ::: - -* `DefaultCellPopover` - the default popover component. Use this component if you only want custom popover content for certain schemas or columns and default popover rendering for other cells. - -* `setCellPopoverProps` - this callback is passed to allow customizing the cell expansion popover. Accepts any prop that `EuiPopover` accepts, except for `button` & `closePopover`, which is controlled by the data grid. - +* `children` - the direct JSX output of the cell's returned `renderCellValue`. It can be used (e.g.) if you want a custom wrapper or cell actions, but default popover content. +* `cellContentsElement` - a direct reference to the cell's HTML content node, which allows accessing the cell's `innerText` for cases where raw non-JSX text is useful (e.g. copying). +* `cellActions` - the direct JSX output of the default popover footer and buttons. Use this prop if you want custom popover content but default cell actions. + * If deliberately leaving out the default `cellActions`, you **must** re-implement your cell actions in the popover in some form. Leaving out cell actions available in the cell but not in the popover introduces UX inconsistencies and will confuse the end user. +* `DefaultCellPopover` - the default popover component. Use this component if you only want custom popover content for certain schemas or columns and default popover rendering for other cells. +* `setCellPopoverProps` - this callback is passed to allow customizing the cell expansion popover. Accepts any prop that `EuiPopover` accepts, except for `button` & `closePopover`, which is controlled by the data grid. Take a look at the below example's demo code to see the above props in action. From 2227f34eb85ffdd587d809a38820458db980c442 Mon Sep 17 00:00:00 2001 From: Cee Chen Date: Tue, 29 Oct 2024 14:37:48 -0700 Subject: [PATCH 10/10] Remove extra newlines for docs callouts with no titles - the text is short enough IMO that this is easier readability --- packages/website/docs/components/display/aspect_ratio.mdx | 2 -- .../docs/components/elastic_charts/accessibility_features.mdx | 2 -- .../website/docs/components/elastic_charts/metric_chart.mdx | 2 -- packages/website/docs/components/forms/compressed_forms.mdx | 2 -- packages/website/docs/components/forms/date_picker.mdx | 2 -- packages/website/docs/components/layout/flyout.mdx | 2 -- packages/website/docs/components/navigation/side_nav.mdx | 2 -- packages/website/docs/components/templates/sitewide_search.mdx | 2 -- .../website/docs/components/templates/super_date_picker.mdx | 2 -- 9 files changed, 18 deletions(-) diff --git a/packages/website/docs/components/display/aspect_ratio.mdx b/packages/website/docs/components/display/aspect_ratio.mdx index 32174114187..cd9552a0b4d 100644 --- a/packages/website/docs/components/display/aspect_ratio.mdx +++ b/packages/website/docs/components/display/aspect_ratio.mdx @@ -6,9 +6,7 @@ id: display_aspect_ratio # Aspect ratio :::warning - In some cases, aspect ratio sizing may not be supported by the embed. This component will only work with ones that do, like YouTube. - ::: **EuiAspectRatio** provides a way to responsively resize a single block level child element to a specificied ratio. This is useful for things like YouTube iframes or other embeds that initially have a fixed size. If you need something similar for images, take a look at CSS's [object-fit property](https://www.w3schools.com/css/css3_object-fit.asp). diff --git a/packages/website/docs/components/elastic_charts/accessibility_features.mdx b/packages/website/docs/components/elastic_charts/accessibility_features.mdx index 396900831f7..52cce48872e 100644 --- a/packages/website/docs/components/elastic_charts/accessibility_features.mdx +++ b/packages/website/docs/components/elastic_charts/accessibility_features.mdx @@ -333,9 +333,7 @@ XY charts include: area, bar, and histogram. You can add meaning to your color segments by using the `bandLabels` prop. :::note - In version 64.1.0, semantic groupings are only available for **goal and gauge charts**. - ::: diff --git a/packages/website/docs/components/elastic_charts/metric_chart.mdx b/packages/website/docs/components/elastic_charts/metric_chart.mdx index 5bd7f7a9e87..57726cf0ada 100644 --- a/packages/website/docs/components/elastic_charts/metric_chart.mdx +++ b/packages/website/docs/components/elastic_charts/metric_chart.mdx @@ -614,9 +614,7 @@ Metric charts are composed of a series of elements that follow a specified hiera Below certain breakpoints, secondary elements such as `subtitles` are removed in order to leave as much space as possible for primary elements (`title`, `value`). Be aware of this limitation when dealing with small metrics. :::warning - Please be always aware of this limit and resize the Metric component accordingly within your interface or dashboard. - ::: ```mdx-code-block diff --git a/packages/website/docs/components/forms/compressed_forms.mdx b/packages/website/docs/components/forms/compressed_forms.mdx index 257c7569202..cb0a9fc4111 100644 --- a/packages/website/docs/components/forms/compressed_forms.mdx +++ b/packages/website/docs/components/forms/compressed_forms.mdx @@ -8,9 +8,7 @@ id: forms_compressed_forms Also known as **Editor-Style Controls**, compressed forms and controls were specifically created for use when space is at a premium. They are not intended for use when the form is the main objective of the page. They work best in editor-style applications where form controls are being used to create or edit content on the page. :::danger - Do not use compressed and non-compressed form controls in the same form. - ::: To use compressed forms, pass `display="rowCompressed"` to the EuiFormRows and `compressed=true` to the form controls themselves. diff --git a/packages/website/docs/components/forms/date_picker.mdx b/packages/website/docs/components/forms/date_picker.mdx index 3ecd7b7f3ed..9cc1853891e 100644 --- a/packages/website/docs/components/forms/date_picker.mdx +++ b/packages/website/docs/components/forms/date_picker.mdx @@ -151,9 +151,7 @@ export default () => { Locale formatting is achieved by using the `locale`,`timeFormat`, and `dateFormat` props. The latter will take any `moment()` notation. Check [Date format by country](https://en.wikipedia.org/wiki/Date_format_by_country) for formatting examples. :::warning - Moment will try to load the locale on demand when it is used. Bundlers that do not support dynamic require statements will need to explicitly import the locale, e.g. `import 'moment/locale/zh-cn'`. See the below demo JS for examples. - ::: ```tsx interactive diff --git a/packages/website/docs/components/layout/flyout.mdx b/packages/website/docs/components/layout/flyout.mdx index 609f4c59040..51308457c15 100644 --- a/packages/website/docs/components/layout/flyout.mdx +++ b/packages/website/docs/components/layout/flyout.mdx @@ -813,9 +813,7 @@ export default () => { By default, flyouts will continue to grow with the width of the window. To stop this growth at an ideal width, set `maxWidth` to `true`, or pass your own custom size. :::warning - Note that there are some caveats to providing a maxWidth that is smaller than the minWidth. - ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/side_nav.mdx b/packages/website/docs/components/navigation/side_nav.mdx index 4d44befd07e..df559e23620 100644 --- a/packages/website/docs/components/navigation/side_nav.mdx +++ b/packages/website/docs/components/navigation/side_nav.mdx @@ -76,9 +76,7 @@ Since **EuiSideNav** renders a `