Skip to content

Commit

Permalink
[EUI+] Polish pass on all docs callouts (#8107)
Browse files Browse the repository at this point in the history
  • Loading branch information
cee-chen authored Oct 31, 2024
1 parent 75b0559 commit 54bf470
Show file tree
Hide file tree
Showing 48 changed files with 93 additions and 218 deletions.
2 changes: 2 additions & 0 deletions packages/docusaurus-theme/src/components/call_out/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ const getStyles = (theme: UseEuiTheme, variant: VARIANTS) => {

return {
note: css`
margin-block-start: var(--eui-theme-content-vertical-spacing);
&:not(:last-child) {
margin-block-end: ${euiTheme.size.xl};
}
Expand Down
2 changes: 0 additions & 2 deletions packages/website/docs/components/display/aspect_ratio.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion packages/website/docs/components/display/badge.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
20 changes: 5 additions & 15 deletions packages/website/docs/components/display/card.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,8 @@ export default () => <EuiFlexGroup gutterSize="l">{cardNodes}</EuiFlexGroup>;

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
Expand Down Expand Up @@ -89,9 +87,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`<img />` element, each element will require a style of `width: 100%`.

Expand Down Expand Up @@ -155,10 +151,8 @@ export default () => (

Footers can contain any number of elements and will always align to the bottom of the card. However, if you supply a footer containing a **EuiButton** you **must not** also give it an `onClick`.

:::warning When using footers to display generic "Go" buttons, you must provide an aria-label to the button itself that refers back to the title of the card.

:::note Accessibility requirement
When using footers to display generic "Go" buttons, you must provide an `aria-label` to the button itself that refers back to the title of the card.

:::

```tsx interactive
Expand Down Expand Up @@ -295,10 +289,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
Expand Down Expand Up @@ -422,10 +414,8 @@ export default () => {
};
```

:::warning When used as a radio group, you must provide a fieldset with a legend for accessibility.

:::note Accessibility requirement
When used as a radio group, you must provide a `fieldset` with a `legend` for accessibility.

:::

```tsx interactive
Expand Down
6 changes: 2 additions & 4 deletions packages/website/docs/components/display/comment_list.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,8 @@ id: display_comment_list

The **EuiCommentList** is a timeline component built on top of [**EuiTimeline**](/docs/display/timeline). It allows you to display comments or logged actions that either a user or a system has performed.

:::warning

For accessibility, it is highly recommended to provide a descriptive `aria-label` or the ID of an external label to the `aria-labelledby` prop of the **EuiCommentList**. A `timelineAvatarAriaLabel` should be provided for every **EuiComment** with or without a `timelineAvatar` as `IconType`.

:::note Accessibility recommendation
Provide a descriptive `aria-label` or the ID of an external label to the `aria-labelledby` prop of the **EuiCommentList**. A `timelineAvatarAriaLabel` should be provided for every **EuiComment** with or without a `timelineAvatar` as `IconType`.
:::

## Basic comment list
Expand Down
6 changes: 2 additions & 4 deletions packages/website/docs/components/display/drag_and_drop.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ An extension of [@hello-pangea/dnd](https://github.com/hello-pangea/dnd) (which
* `<EuiDroppable />`: Area into which items can be dropped. Contains one or more `<EuiDraggable />`.
* `<EuiDraggable />`: Items that can be dragged. Must be part of an `<EuiDroppable />`

:::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.

Expand Down Expand Up @@ -143,10 +143,8 @@ By default the entire element surface can initiate a drag. To specify an element

The `provided` parameter on the **EuiDraggable** `children` render prop has all data required for functionality. Along with the `customDragHandle` flag,`provided.dragHandleProps` needs to be added to the intended handle element.

:::note Icon-only custom drag handles require an accessible label. Add an aria-label="Drag handle" attribute to your React component or HTML element that receivesprovided.dragHandleProps.

:::note Accessibility requirement
**Icon-only** custom drag handles require an accessible label. Add an `aria-label="Drag handle"` attribute to your React component or HTML element that receives`provided.dragHandleProps`.

:::

```tsx interactive
Expand Down
6 changes: 2 additions & 4 deletions packages/website/docs/components/display/icons/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,8 @@ import { EuiCodeBlock, EuiSpacer, EuiSplitPanel, EuiToken } from '@elastic/eui';
<EuiIcon type="grid" />
```

:::warning For better accessibility it's always recommended to give a descriptive title based on the icon use.

If no title is provided the icon is going to be purely decorative and it will get by default an `aria-hidden=true`.

:::note Accessibility recommendation
If possible, provide a descriptive title based on the icon use. If no title is provided, the icon is considered purely decorative, and it will default to `aria-hidden=true`.
:::

## Glyphs
Expand Down
2 changes: 1 addition & 1 deletion packages/website/docs/components/display/image.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions packages/website/docs/components/display/progress.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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).

:::

Expand Down
6 changes: 1 addition & 5 deletions packages/website/docs/components/display/skeleton.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,8 @@ id: display_skeleton

The **EuiSkeleton** components are placeholder components for content which has yet to load. They provide meaningful previews, avoid layout content shifts, and add accessible announcements to screen readers when content is done loading.

:::note Using the contentAriaLabel prop

Using the `contentAriaLabel` prop

:::note Accessibility recommendation
The `contentAriaLabel` prop should be used to help describe the type of content that is loading to screen reader users. If you do not provide a descriptive label and have have multiple loading skeletons on the page, screen reader users may hear a multitude of “Loaded” messages in a row, with no meaningful indication of what actually loaded.

:::

## Text
Expand Down
8 changes: 2 additions & 6 deletions packages/website/docs/components/display/text.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
4 changes: 1 addition & 3 deletions packages/website/docs/components/display/timeline.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,8 @@ This component allows you to create any type of timeline, but for more specific
* [**EuiSteps**](/docs/navigation/steps): a timeline that allows you to present instructional content that must be conducted in a particular order and might contain progress indications.
* [**EuiCommentList**](/docs/display/comment-list): a timeline that allows you to display comments or logging actions that either a user or a system has performed.

:::warning For accessibility, it is required to wrap your EuiTimelineItem's with a EuiTimeline. It is highly recommended to provide a descriptive aria-label, or a text node ID of an external label to the aria-labelledby prop of the EuiTimeline.

:::note Accessibility requirement
For accessibility, it is required to wrap your **EuiTimelineItem**'s with a **EuiTimeline**. It is highly recommended to provide a descriptive `aria-label`, or a text node ID of an external label to the `aria-labelledby` prop of the **EuiTimeline**.

:::

```tsx interactive
Expand Down
4 changes: 1 addition & 3 deletions packages/website/docs/components/display/tour/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 1 addition & 3 deletions packages/website/docs/components/editors_and_syntax/code.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,8 @@ You may want to set a heading level if there are multiple charts on the page but
</Chart>
```

:::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.
Expand Down Expand Up @@ -335,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**.

:::

<Demo scope={{ ...ElasticCharts, useChartBaseTheme }}>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 2 additions & 6 deletions packages/website/docs/components/forms/combo_box.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,8 @@ id: forms_combo_box

Use a **EuiComboBox** when the input has so many options that the user needs to be able to search them, the user needs to be able to select multiple options, and/or the user should have the ability to specify a custom value in addition to selecting from a predetermined list. If you're unsure of which selection component to use, see [EUI's in-depth guide to selection components](https://github.com/elastic/eui/discussions/7049) for more information.

:::note You must add an accessible label to each instance of EuiComboBox

You must add an accessible label to each instance of **EuiComboBox**

Labels can be created by wrapping the combo box in an **EuiFormRow** with a `label`, adding an `aria-label` prop, or passing a text node ID to the `aria-labelledby` prop.

:::note Accessibility requirement
Add an accessible label to each instance of **EuiComboBox**. Labels can be created by wrapping the combo box in an **EuiFormRow** with a `label`, adding an `aria-label` prop, or passing a text node ID to the `aria-labelledby` prop.
:::

```tsx interactive
Expand Down
8 changes: 2 additions & 6 deletions packages/website/docs/components/forms/compressed_forms.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -322,7 +320,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';
Expand Down Expand Up @@ -410,10 +408,8 @@ export default () => {

This is an example of how to combine compressed form controls with from rows, labels, prepend and appends in a column layout.

:::warning Pay close attention to the patterns of using htmlFor and aria-label. For best results, each form control that is not wrapped in an EuiFormRow should be supplied an id.

:::note Accessibility recommendation
Pay close attention to the patterns of using `htmlFor` and `aria-label`. For best results, each form control that is not wrapped in an EuiFormRow should be supplied an `id`.

:::

```tsx interactive
Expand Down
2 changes: 0 additions & 2 deletions packages/website/docs/components/forms/date_picker.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,10 @@ id: forms_form_controls

EUI provides different types of basic form controls: [**EuiFieldText**](/docs/forms/form-controls#text-field), [**EuiFieldSearch**](/docs/forms/form-controls#search-field), [**EuiFieldNumber**](/docs/forms/form-controls#number-field), [**EuiFieldPassword**](/docs/forms/form-controls#password-field), [**EuiSelect**](/docs/forms/form-controls#select), [**EuiTextArea**](/docs/forms/form-controls#textarea), and [**EuiFilePicker**](/docs/forms/form-controls#file-picker).

:::warning Wrap each of your from controls in a EuiFormRow

Wrap each of your from controls in a **EuiFormRow**

Use the [**EuiFormRow**](/docs/forms/form-layouts#form-and-form-rows) component to easily associate form components with labels, help text, and error text. For accessibility, you must provide a `label`, `aria-label` , or a text node ID of an external label to the `aria-labelledby` prop.
:::note Accessibility requirement
You must provide a `label`, `aria-label`, or valid `aria-labelledby` prop to all form controls.

To easily meet this requirement, we recommend wrapping your form controls in the [**EuiFormRow**](/docs/forms/form-layouts#form-and-form-rows) component, which automatically associates form controls with labels, help text, and error text.
:::

## Text field
Expand Down
6 changes: 3 additions & 3 deletions packages/website/docs/components/forms/range_sliders.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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]`.

Expand Down
Loading

0 comments on commit 54bf470

Please sign in to comment.