diff --git a/website/docs/02_components/display/aspect_ratio/_category_.yml b/website/docs/02_components/display/aspect_ratio/_category_.yml new file mode 100644 index 00000000000..ffbabcbae63 --- /dev/null +++ b/website/docs/02_components/display/aspect_ratio/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_aspect_ratio_overview diff --git a/website/docs/02_components/display/aspect_ratio/overview.mdx b/website/docs/02_components/display/aspect_ratio/overview.mdx new file mode 100644 index 00000000000..9dc9dae718f --- /dev/null +++ b/website/docs/02_components/display/aspect_ratio/overview.mdx @@ -0,0 +1,22 @@ +--- +id: component_aspect_ratio_overview +title: Aspect ratio +export_name: EuiAspectRatio +slug: /components/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 specified 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://developer.mozilla.org/en-US/docs/Web/CSS/object-fit). + + + + diff --git a/website/docs/02_components/display/avatar/_category_.yml b/website/docs/02_components/display/avatar/_category_.yml new file mode 100644 index 00000000000..d34a7c08cf3 --- /dev/null +++ b/website/docs/02_components/display/avatar/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_avatar_overview diff --git a/website/docs/02_components/display/avatar/overview.mdx b/website/docs/02_components/display/avatar/overview.mdx new file mode 100644 index 00000000000..700c5bd424c --- /dev/null +++ b/website/docs/02_components/display/avatar/overview.mdx @@ -0,0 +1,48 @@ +--- +id: component_avatar_overview +title: Avatar +export_name: EuiAvatar +slug: /components/avatar +--- + +The **EuiAvatar** component typically creates a user icon. +It will accept `name` (required) and `image` props and will configure the display and accessibility as needed. +By default, the background colors come from the set of colors used for visualizations. +Otherwise, you can pass a hex value to the `color` prop. + + + +## Initials + +The initials displayed in the avatar try to be smart based on the name prop. +If the name contains spaces, it will display the first character of each word, **always maxing out at 2 characters**. +You can customize this by passing a combination of `initialsLength` and/or `initials` props. +However, the avatar will still always max out at 2 characters. + + + +## Types + +The avatar `type`, which primarily defines the shape, is keyworded and can be `"user"` (default) +or `"space"` (for workspaces). + + + +## Icons + +Icons can also be displayed instead of initials or images. When simply passing an `iconType`, +it will both size and color appropriately based on the other **EuiAvatar** props. +To customize these specifically, pass `iconSize` and `iconColor`. + +If your icon has multiples or custom colors like a logo, you can keep the default `iconColor` by passing `null`. +Otherwise, it will get the appropriate contrast acceptable variant. +Just ensure that you also are providing an accessible background color to match that of the icon's color. + + + +## Disabled + +While **EuiAvatar** doesn't accept any interactive behaviors itself, you can create a visually presented disabled +avatar by adding `isDisabled` when placed within a disabled element. + + diff --git a/website/docs/02_components/display/badge/_category_.yml b/website/docs/02_components/display/badge/_category_.yml new file mode 100644 index 00000000000..e611d904dc1 --- /dev/null +++ b/website/docs/02_components/display/badge/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_badge_overview diff --git a/website/docs/02_components/display/badge/overview.mdx b/website/docs/02_components/display/badge/overview.mdx new file mode 100644 index 00000000000..bfdf4e5a5cd --- /dev/null +++ b/website/docs/02_components/display/badge/overview.mdx @@ -0,0 +1,74 @@ +--- +id: component_badge_overview +title: Badge +export_name: + - EuiBadge + - EuiBadgeGroup + - EuiBetaBadge + - EuiNotificationBadge +slug: /components/badge +--- + +**EuiBadges** are used to focus on important bits of information. Although they will automatically space themselves +if you use them in a repetitive fashion it is good form to wrap them using a **EuiBadgeGroup** so that they will +wrap when width is constrained (as seen below). + + + +## Badge with Icon + +Badges can use icons on the left and right (default) sides. + + + +## Badge with onClick events + +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` + +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. + +::: + + + +## Badge for health status + +Badges can work as health status indicators in places where there are a lot of repeated statuses, e.g. in tables. + + + +## Badge with href + +Badges can also be made to render anchor tags by passing an `href`. + + + +## Badge groups and truncation + +Badges, like buttons, will only every be a single line of text. This means text will not wrap, but be truncated if the badge's width reaches that of its parent's. + +For this reason, badges also auto-apply the inner text of the badge to the `title` attribute of the element to provide default browser tooltips with the full badge text. + +To ensure proper wrapping, truncation and spacing of multiple badges, it is advisable to wrap them in a **EuiBadgeGroup**. + + + +## Beta badge type + +The **EuiBetaBadge** was created specifically to call out modules that are not in GA. Generally the labels used are "Beta" or "Lab". They require an extra `tooltipContent` to describe the purpose of the badge. You can pass an optional `title` prop to populate the tooltip title or html title attribute but by default it will use the `label`. + +If you pass in an `iconType`, only the icon will be used in the badge itself and the label will be applied as the title. Only use an icon when attaching the beta badge to small components. Beta badges can also be made clickable by passing `href` or `onClick` as needed. + +They can also be used in conjunction with [**EuiCards**](#/display/card) and [**EuiKeyPadMenuItems**](#/navigation/key-pad-menu). + + + +## Notification badge type + +Used to showcase the number of notifications, alerts, or hidden selections. This badge type is commonly used in the [**EuiHeader**](#/layout/header) and [**EuiFilterButton**](#/forms/filter-group) components. + + diff --git a/website/docs/02_components/display/callout/overview.mdx b/website/docs/02_components/display/callout/overview.mdx index 138e69717b8..c7bba48a5a2 100644 --- a/website/docs/02_components/display/callout/overview.mdx +++ b/website/docs/02_components/display/callout/overview.mdx @@ -1,6 +1,54 @@ --- -title: Callout id: component_callout_overview +title: Callout export_name: EuiCallOut slug: /components/callout --- + +**EuiCallOut** contains a message directly related to content on the page. +This includes general information, success, warning, and error messages. + +**Keep these guidelines in mind:** + +* Minimize the number of callouts per page. +* Stack callouts in the order in which they require users' attention: error, warning, info, and then success. +* Offer only one action per callout and ensure it's an action users can perform quickly. +* If the callout has a permanent spot in the UI, but needs to be less obstructive, + set the `size` property to `s` (small). +* Use an `iconType` if it adds context. + +## Info + +Use **EuiCallOut** to communicate general information to the user. + + + +## Success + +Use this callout to notify the user of an action that successfully completed. +Use success callouts sparingly—callouts are typically used for things that are broken rather than things that succeed. + + + +## Warning + +Use this callout to warn the user against decisions they might regret. +You should receive a warning message when the program detects that **something is not behaving right, +but it didn't cause any termination**. + + + +## Danger + +Use this callout to let the user know that something went wrong. For example if you want to communicate an error. +You should receive an error message when the issue is **terminal, this doesn't always mean that the operation +stops completely, but the task is not complete**. + + + +## Dismissible callouts + +To render a cross icon in the top right hand corner, pass an `onDismiss` callback that handles +conditionally rendering your callout. + + diff --git a/website/docs/02_components/display/card/_category_.yml b/website/docs/02_components/display/card/_category_.yml new file mode 100644 index 00000000000..d7b2791b0b7 --- /dev/null +++ b/website/docs/02_components/display/card/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_card_overview diff --git a/website/docs/02_components/display/card/overview.mdx b/website/docs/02_components/display/card/overview.mdx new file mode 100644 index 00000000000..b1c2be79dda --- /dev/null +++ b/website/docs/02_components/display/card/overview.mdx @@ -0,0 +1,118 @@ +--- +id: component_card_overview +title: Card +export_name: + - EuiCard + - EuiCheckableCard +slug: /components/card +--- + +**EuiCard** is a content-oriented component built on top of [**EuiPanel**](#/layout/panel). +Be sure to check out the [guidelines for properly nesting panels](#/layout/panel/guidelines). + +## Basic card + +At its core an **EuiCard** should contain a `title`,`description`, and an `icon`. +You can make the whole card clickable by giving it an `onClick` handler or `href`. + +For accessibility and heading hierarchy, a card's title element is a `span` by default. +However, this can be changed via the `titleElement` prop without altering the visual size. + + + +## Layout + +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. + +::: + + + +## Images + +Images can be added in place of, or in conjunction with, icons. Just pass an 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. + +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%`. + +::: + + + +## Footer + +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. + +::: + + + +## Beta badge + +If the card links to or references a module that is not GA (beta, lab, etc.), you can add a `betaBadgeProps.label` +and `betaBadgeProps.tooltipContent` to the card, and it will properly create and position an **EuiBetaBadge**. +If you want to change the title of the tooltip, supply a `betaBadgeProps.title` prop. + + + +## Selectable + +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 + +When providing an extra link to more details or such, be sure to stop event propagation from also selecting the card. + +::: + + + +## Checkable + +**EuiCheckableCard** wraps an **EuiRadio** or **EuiCheckbox** with a more-prominent panel, +allowing for children to be displayed. + +:::warning + +When used as a radio group, you must provide a `fieldset` with a `legend` for accessibility. + +::: + + + +## Custom children + +In the event that you need **more than** just paragraph text for the `description`, you can supplement with anything +you need as the `children` of the component. You can also completely replace the description with custom children, +but **EuiCard** at least one of these. + + + +## Plain and other colors + +If you need a card with no borders or shadows pass `display="plain"`. This is a good option to avoid nested panels. +Adding an interaction to the card will provide the clickable styling on hover. The `display` prop also accepts all +other **EuiPanel** colors like `'transparent'`. + +For non-interactive cards, reduce or eliminate the padding as needed to suit your layout with the prop `paddingSize`. + + diff --git a/website/docs/02_components/display/comment_list/_category_.yml b/website/docs/02_components/display/comment_list/_category_.yml new file mode 100644 index 00000000000..11f0c355266 --- /dev/null +++ b/website/docs/02_components/display/comment_list/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_comment_list_overview diff --git a/website/docs/02_components/display/comment_list/overview.mdx b/website/docs/02_components/display/comment_list/overview.mdx new file mode 100644 index 00000000000..8c2f7b54704 --- /dev/null +++ b/website/docs/02_components/display/comment_list/overview.mdx @@ -0,0 +1,92 @@ +--- +id: component_comment_list_overview +title: Comment list +export_name: + - EuiCommentList + - EuiComment +slug: /components/comment-list +--- + +The **EuiCommentList** is a timeline component built on top of [**EuiTimeline**](#/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`. + +::: + +## Basic comment list + +Use **EuiCommentList** to display a list of **EuiComments**. +Pass an array of **EuiComment** objects and **EuiCommentList** will generate a comment thread. + + + +## Comment + +The **EuiComment** is flexible and adapts the design according to the props passed. + + + +The following demo shows how you can combine different props to create different types of comments events like +a regular, update, update with a danger background and a custom one. + + + +## Timeline avatar + +The timeline icon is a very important part of the comment: + +* By default, each **EuiComment** shows an avatar with the `userAvatar` icon. A `timelineAvatarAriaLabel` should + be provided when using this default option. +* You can customize your avatar by passing to the `timelineAvatar` any of the icon types that + [**EuiIcon**](#/display/icons) supports. The icon will show inside a `subdued` avatar. Consider this option when + showing a system update. Providing a `timelineAvatarAriaLabel` is recommended. +* You can further customize the timeline icon by passing to the `timelineAvatar` a [**EuiAvatar**](#/display/avatar). + + + +## Comment event actions + +There are scenarios where you might want to allow the user to perform `actions` related to each comment. +Some common `actions` include: editing, deleting, sharing and copying. To add custom `actions` to a comment, +use the `actions` prop. These will be placed to the right of the metadata in the comment's header. We recommend +using a [**EuiButtonIcon**](#/navigation/button) to trigger an action. When having multiple actions, consider +grouping them in a nested menu system using a [**EuiPopover**](#/layout/popover) with +a [**EuiContextMenu**](#/navigation/context-menu). + + + +## A comment system + +The below example uses a list of **EuiComments**, a [**EuiMarkdownEditor**](#/editors-syntax/markdown-editor), +and a [**EuiMarkdownFormat**](#/editors-syntax/markdown-format) to create a simple comment system. + +* Each comment renders in a **EuiComment**. +* We use the **EuiMarkdownEditor** to post the `EuiComment.children`. This means the content uses Markdown. +* When the new **EuiComment** is posted, we use the **EuiMarkdownFormat** to wrap the `EuiComment.children` + and render the Markdown correctly. + +When dealing with asynchronous events like posting a message we recommend setting the **EuiMarkdownEditor** to +a `readOnly` state and the "Add comment" **EuiButton** to a `isLoading` state. This will ensure users understand +that the content cannot be changed while the comment is being submitted. + + diff --git a/website/docs/02_components/display/description_list/_category_.yml b/website/docs/02_components/display/description_list/_category_.yml new file mode 100644 index 00000000000..bc8e9b3121e --- /dev/null +++ b/website/docs/02_components/display/description_list/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_description_list_overview diff --git a/website/docs/02_components/display/description_list/overview.mdx b/website/docs/02_components/display/description_list/overview.mdx new file mode 100644 index 00000000000..46c9f36220a --- /dev/null +++ b/website/docs/02_components/display/description_list/overview.mdx @@ -0,0 +1,83 @@ +--- +id: component_description_list_overview +title: Description list +export_name: + - EuiDescriptionList + - EuiDescriptionListTitle + - EuiDescriptionListDescription +slug: /components/description-list +--- + +**EuiDescriptionList** is a component for listing pairs of information together. You can use the component on its own, +passing in an object for the list. + +You can also use the **EuiDescriptionListTitle** and **EuiDescriptionListDescription** components separately +to build a list manually. + + + +## Reverse style + +Setting the `textStyle` prop to `reverse` will reverse the text styles of the `title` and `description` elements +so that the description is more prominent. This works best for key/value type content. + +Adding this property to the `inline` type will not change anything. + + + +## As columns + +Using the prop `type` set to `column` description lists can be presented in an inline, column format. + + + +To return to the typical row format on smaller screens set `type` to `responsiveColumn`. +The following list will only show the column format on larger screens. + + + +The optional `columnWidths` prop allows customizing specific column widths (e.g. `['100px', '200px']`). +The first array value applies to the title column, and the second applies to the description column. + +Passing numbers instead of CSS width strings will use a ratio of widths. For example, `[1, 3]` will render +a description column 3x the width of the title column. In other words, titles will have a width +of 25% descriptions will have a width of 75%. + +For advanced usage, column width strings also accept +[CSS grid special units, sizing, keywords, and sizing functions](https://css-tricks.com/snippets/css/complete-guide-grid/#aa-special-units-functions). + + + +## Inline + +Using a prop `type` set to `inline` description lists can be presented in an inline, blob format. +This is useful for JSON code blocks. Inline description lists are sized smaller than normal lists due +to their compact nature. + + + +## Customizing appearance + +### Alignment & Compression + +Utilize the `align` and `compressed` props to refine the presentation of your description list. +These are compatible with both column and inline types. + +### Vertical spacing + +Modify the `rowGutterSize` prop to control the vertical spacing between `EuiDescriptionList` elements. +This will not affect inline list types. + +### Horizontal spacing + +Adjust the spacing between the title and description with the `columnGutterSize` prop. +This will not affect inline or row types. + + + +## Passing className + +When using the `listItems` prop to pass an object of items and you need to also add a `className` +(or other available prop) to the individual pieces, you can use the `titleProps` and `descriptionProps` to do so. + + diff --git a/website/docs/02_components/display/drag_and_drop/_category_.yml b/website/docs/02_components/display/drag_and_drop/_category_.yml new file mode 100644 index 00000000000..66115508d8d --- /dev/null +++ b/website/docs/02_components/display/drag_and_drop/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_drag_and_drop_overview diff --git a/website/docs/02_components/display/drag_and_drop/overview.mdx b/website/docs/02_components/display/drag_and_drop/overview.mdx new file mode 100644 index 00000000000..38f1890e25b --- /dev/null +++ b/website/docs/02_components/display/drag_and_drop/overview.mdx @@ -0,0 +1,145 @@ +--- +id: component_drag_and_drop_overview +title: Drag and drop +export_name: + - EuiDragDropContext + - EuiDroppable + - EuiDraggable +slug: /components/drag-and-drop +--- + +An extension of [@hello-pangea/dnd](https://github.com/hello-pangea/dnd) (which is an actively maintained fork +of [react-beautiful-dnd](https://github.com/atlassian/react-beautiful-dnd)) with a compatible API and built-in +style opinions. Functionality results from 3 components working together: + +* ``: Section of your application containing the draggable elements and the drop targets. +* ``: 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 + +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. + +EUI (largely due to the great work already in @hello-pangea/dnd) has and will continue to ensure accessibility +where possible. With that in mind, keep your users' working context in mind. + +::: + +## Just the facts + +**EuiDraggable** makes very few assumptions about what content it contains. To give affordance to draggable elements +and to ensure a consistent experience, child elements must be able to accept a border and drop shadow +(automatically applied via CSS). No other style opinions are applied, however. + +Similarly, **EuiDroppable** must accept a background color overlay (automatically applied via CSS), +but has no other restrictions. + +All **EuiDragDropContext** elements are discrete and isolated; **EuiDroppables** and **EuiDraggables** cannot +be shared/transferred between instances. Also, **EuiDragDropContexts** cannot be nested. It is recommended that +a single, high-level **EuiDragDropContext** is used and **EuiDroppables** account for categorical and functional +separation (see later examples). + +**EuiDragDropContext** handles all events but makes no assumptions about the result of a drop event. +As such, the following event handlers are available: + +* `onBeforeDragStart` +* `onDragStart` +* `onDragUpdate` +* `onDragEnd` (required) + +EUI also provides methods for helping to deal to common action types: + +* `reorder`: change an item's location in a droppable area +* `copy`: create a duplicate of an item in a different droppable area +* `move`: move an item to a different droppable area + + + +## Simple item reorder + +The simplest case, demonstrating a single **EuiDroppable** with `reorder` behavior. + +Notice the ability to change rendered content based on dragging state. **EuiDraggable** `children` is a render prop +that mush return a `ReactElement`. The `snapshot` parameter on that function has state data that can be used +to alter appearance or behavior (e.g., `isDragging`). + + + +## Custom drag handle + +By default, the entire element surface can initiate a drag. To specify an element within as the handle and create +a containing group, set `customDragHandle=true` and `hasInteractiveChildren=true` on the **EuiDraggable**. + +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 receives`provided.dragHandleProps`. + +::: + +## Interactive elements + +**EuiDraggable** can contain interactive elements such as buttons and form fields. Interactive elements require +`customDragHandle=true` and `hasInteractiveChildren=true` on the **EuiDraggable**. These props will maintain drag +functionality and accessibility, while enabling click, keypress, etc., events on the interactive child elements. + + + +## Move between lists + +By default, all **EuiDroppable** elements are of the same type and will accept **EuiDraggable** elements from +others in the same **EuiDragDropContext**. + +The EUI `move` method is demonstrated in this example. + + + +## Distinguish droppable areas by type + +Setting the `type` prop on an **EuiDroppable** element will ensure that it will only accept **EuiDraggable** elements +from the same type of **EuiDroppable**. + +Notice that the enabled, compatible **EuiDroppable** elements have a visual change that indicates they can accept +the actively moving/focused **EuiDraggable** element. + + + +## Copyable items + +For cases where collections of **EuiDraggable** elements are static or can be used in multiple places set +`cloneDraggables=true` on the parent **EuiDroppable**. The **EuiDroppable** becomes disabled (does not accept +new **EuiDraggable** elements) in this scenario to avoid mixed content intentions. + +The EUI `copy` method is available and demonstrated in the example below. Note that the data point used +as `draggableId` in **EuiDraggable** must change to allow for real duplication. + +`isRemovable` is used in the example for cloned items. This API is likely to change, but currently provides +the visual changes with drop-to-remove interactions. + + + +## Kitchen sink + +**EuiDraggables** in **EuiDroppables**, **EuiDroppables** in **EuiDraggables**, custom drag handles, horizontal +movement, vertical movement, flexbox, panel inception, you name it. + + + +## Using drag and drop in popovers + +**EuiDraggables** use fixed positioning to render and animate the item being dragged. +This positioning logic does not work as expected when used inside of containers that have their own +[stacking context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context). + +This behavior particularly affects [**EuiPopover**](#/layout/popover). If using drag and drop UX within a popover, +you **must** include the `` prop for items to properly render while being dragged. + + diff --git a/website/docs/02_components/display/empty_prompt/_category_.yml b/website/docs/02_components/display/empty_prompt/_category_.yml new file mode 100644 index 00000000000..a33adcd95a1 --- /dev/null +++ b/website/docs/02_components/display/empty_prompt/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_empty_prompt_overview diff --git a/website/docs/02_components/display/empty_prompt/overview.mdx b/website/docs/02_components/display/empty_prompt/overview.mdx new file mode 100644 index 00000000000..d9b7c334882 --- /dev/null +++ b/website/docs/02_components/display/empty_prompt/overview.mdx @@ -0,0 +1,95 @@ +--- +id: component_empty_prompt_overview +title: Empty prompt +export_name: EuiEmptyPrompt +slug: /components/empty-prompt +--- + +The **EuiEmptyPrompt** is the building block to create an empty state. You can use it as a placeholder +for any type of empty content. They are especially helpful for replacing entire pages or parts of a product +that contain no content. + +Be sure to read the full [empty prompt usage guidelines](#/guidelines/empty-prompt). + +While no one piece of content is required, each **EuiEmptyPrompt** should contain at least +a `title` (wrapped in an HTML heading element) and/or a `description`. They usually contain one or more +`actions` that promotes the primary call-to-actions. You can also provide a `footer` to direct users +towards making informed decisions. + + + +## Less content, more actions + +You can remove parts of the prompt to simplify it. You can also provide an array of multiple actions. +Be sure to list primary actions first and secondary actions as empty buttons. + + + +## Panel options + +The **EuiEmptyPrompt** is wrapped by [**EuiPanel**](#/layout/panel). By default, the panel is set to `transparent` +but you can customize other panel options like `color`, `hasBorder` and `paddingSize`. Changing the `color` prop will +also attempt to adjust the `iconColor` and `footer` color. + +Read the [usage guidelines](#/guidelines/empty-prompt) to better understand when to use certain panel props. + + + +## Title sizes and icon colors + +Other customization options include changing the `titleSize` to any of the [**EuiTitle** sizes](#/display/title) +and `iconColor`. When using an application or solution logo as the `iconType`, you can reset to the multi-tone +colors with `iconColor="default"` + + + +## Loading and error prompts + +Empty prompts can also be used to emulate loading and error states, by utilizing the same patterns. + +For **loading** states, instead of passing a `iconType`, you can provide a custom `icon` +and pass in one of our [loading components](#/display/loading). + + + +For **error** states, you can simply set the `color` to `danger`. + + + +## Layout + +You can supply a `layout` of either `"horizontal"` or `"vertical"` with the default being `vertical`. +When creating empty states we want the content to be short and straight to the point. So most of the time, +the `vertical` layout is enough. All the content will be center aligned and this type of text alignment +only works with small content. + +When you have longer body text with multiple calls to action, you can use the `horizontal` layout. +This layout works best when you can provide a larger graphic like an illustration as the `icon`. For consistency, +we recommend providing the illustration using a [**EuiImage**](#/display/image) with `size="fullWidth"`. + + + +## More types of empty states + +**EuiEmptyPrompt** can be used for more than just **empty** pages. The following example showcases different types +of empty states that you can create with the **EuiEmptyPrompt**. +For a full list see the [usage guidelines](#/guidelines/empty-prompt). + + + +## Using in a page template + +When using a **EuiEmptyPrompt** in a [**EuiPageTemplate**](#/templates/page-template), +we recommend using the namespaced component so the template can determine which how to display the empty prompt based +on the rest of the template configuration. + +The following example shows the usage +of the [**EuiPageTemplate.EmptyPrompt**](#/templates/page-template#empty-pages-or-content) namespaced component. + + + +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 incorporate these states with +[**EuiPageTemplate.EmptyPrompt**](#/templates/page-template#empty-pages-or-content). + + diff --git a/website/docs/02_components/display/health/_category_.yml b/website/docs/02_components/display/health/_category_.yml new file mode 100644 index 00000000000..03fffc40069 --- /dev/null +++ b/website/docs/02_components/display/health/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_health_overview diff --git a/website/docs/02_components/display/health/overview.mdx b/website/docs/02_components/display/health/overview.mdx new file mode 100644 index 00000000000..d6c7d562231 --- /dev/null +++ b/website/docs/02_components/display/health/overview.mdx @@ -0,0 +1,20 @@ +--- +id: component_health_overview +title: Health +export_name: EuiHealth +slug: /components/health +--- + +The **EuiHealth** component should be used when showing comparative health of listed objects (like servers, +HTTP response status codes (as per convenience), nodes, indexes, etc.). Because icons are vague and bulky +and color alone does not work, color plus text provides a recognizable, lightweight combo that works +in most situations. + + + +## Text sizes + +Match the text size of **EuiHealth** to your context by passing `xs / s / m / inherit` to the `textSize` prop. +The `inherit` style will get its font size from the parent element. + + diff --git a/website/docs/02_components/display/icon/_category_.yml b/website/docs/02_components/display/icon/_category_.yml new file mode 100644 index 00000000000..a2d5edbad02 --- /dev/null +++ b/website/docs/02_components/display/icon/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_icon_overview diff --git a/website/docs/02_components/display/icon/overview.mdx b/website/docs/02_components/display/icon/overview.mdx new file mode 100644 index 00000000000..22c894e6041 --- /dev/null +++ b/website/docs/02_components/display/icon/overview.mdx @@ -0,0 +1,114 @@ +--- +id: component_icon_overview +title: Icon +export_name: EuiIcon +slug: /components/icon +--- + +# Icons + +**EuiIcon** is a handy component for using our custom glyphs and logos. +The `type` prop accepts either an enumerated name from one of the sets below, +a location to a custom SVG asset, or a React Element. + + + +:::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`. + +::: + +## Glyphs + +Glyphs are small, monochromatic icons that typically should always use the default size of `size="m"`. +They are named according to their appearance or the action they represent. For example, `star`, `play`, etc. + +If you would like to contribute to our growing list of glyphs, you can follow +[these guidelines](https://github.com/elastic/eui/blob/main/wiki/contributing-to-eui/developing/creating-icons.md). + + + +## Editor controls + +Editor icons relate to the visual styling of elements and are commonly used within **EuiButtonGroup** components. + + + +## Elastic logos + +These logos are restricted in use to Elastic products or when referencing Elastic products. +They are multicolor with some internal paths having a class of `.euiIcon__fillNegative` to handle flipping colors +for dark mode. The only other colors most of them support are ghost and text which turn them into a solid shape. + + + +## Apps + +App logos are logos for Elastic Apps, and can contain multiple colors. Normally the Elastic Design team +creates those icons. They are not meant to be used outside of Elastic, because they represent our apps. +App logos are usually displayed at `32x32` or above and can contain multiple colors. + + + +### Machine learning icons + +Machine learning has some specific icons for job creation. Again, these are made for `32x32`. + + + +## Tokens + +Tokens are most commonly used to visually signify field or code types. An **EuiToken** accepts any valid **EuiIcon** +as its `iconType` property. However, icons designed specifically for use in the **EuiToken** are prefixed +with "token" in their name and have pre-defined styles. + + + +## Custom tokens + +By default, an `iconType` with the token prefix (i.e. those listed above) will have predefined styles. +However, any valid `iconType` can be passed and, in either case, the `shape`, `size`, `color`, and `fill` can be customized. + + + +## Sizes + +Use the `size` prop to automatically size your icons. Medium is the default, and will output a `16x16` icon. + + + +## Colors + +The default behavior of icons is to inherit from the text color. You can use the `color` prop to assign +a custom color which accepts a named color from our palette +or a valid [CSS color data type](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) which +will be passed down through the inline-style `fill`  property. **We recommend relying on the EUI named color +palette** unless the custom color is initiated by the user (like as a graph color). + +Two-tone icons, like our app style icons, will behave similarly to normal glyphs when provided a specific color +by applying the color to **all** the shapes within. You can force the icon to match the parent's text color by +passing `color="inherit"` to the icon. + + + +## Custom SVGs + +The `type` prop can accept a valid enum, string or React SVG Element. When using a custom SVG, please make sure +it sits on a square canvas and preferably utilizes one of EUI's sizes (`16x16` or `32x32`). + +When using custom SVGs for simple glyphs, **remove all fill attributes** on the SVG and utilize the CSS helpers +if you have complex logos that need to work with theming. + +:::warning + +Important considerations when importing SVGs as components + +When importing an SVG as a component like `import { ReactComponent as ReactLogo } from './logo.svg';`, +keep in mind that the component will not support the `title` prop. The `title` prop is designed to only work with +our icons or SVGs imported as images or passed as a Data URL. So, if you're importing your SVG as a component, +be sure to use an `aria-label` instead of a `title` prop to enhance accessibility and avoid potential issues. + +::: diff --git a/website/docs/02_components/display/image/_category_.yml b/website/docs/02_components/display/image/_category_.yml new file mode 100644 index 00000000000..ef341ac64af --- /dev/null +++ b/website/docs/02_components/display/image/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_image_overview diff --git a/website/docs/02_components/display/image/overview.mdx b/website/docs/02_components/display/image/overview.mdx new file mode 100644 index 00000000000..2854de904b9 --- /dev/null +++ b/website/docs/02_components/display/image/overview.mdx @@ -0,0 +1,63 @@ +--- +id: component_image_overview +title: Image +export_name: EuiImage +slug: /components/image +--- + +Use **EuiImage** when you need to place a static image into a page with an optional caption. + +:::note 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. + +When an image is not already sufficiently described, the alt text passed should help non-visual users understand +the purpose of the image within the context of the overall page. +See [WebAIM](https://webaim.org/techniques/alttext/) for a more detailed guide to writing effective alt text. + +::: + + + +## Click an image for a fullscreen version + +Apply the `allowFullScreen` prop to make the image clickable and show a fullscreen version. +Note that the second image also passes `fullScreenIconColor="dark"` to change icon color to better contrast +against the light background of that image. + + + +## Images can be sized + +Images can be sized by passing the `size` prop a value of `s / m / l / xl / original / fullWidth / number / string`. +This size sets the **maximum** length of the longest edge of the image, whether that is height or width, and scales it. +Only the provided sizing values will also increase the size of a smaller image. + + + +## Supporting SVG images + +If you are using an SVG source within `EuiImage`, the SVG image may not show up! While this is surprising to the user, +if your image doesn't have a width or viewbox set, it is behaving in accordance with the SVG spec. + +In order to work with an SVG image that lacks a defined size, you'll want to set a `size` prop. +If you are using the `allowFullScreen` prop as well, you will also want to add a `width` prop. + + + +## Float images within text + +When using `EuiImage` within `EuiText` it is often useful to apply floats. Almost always you'll want to pair +the `float` prop usage, with a `margin` prop usage to give space around your image. Margins, when used in combo +with floats, will adjust depending upon the position of the float. + +:::warning Be careful with floats + +Floats should only be used on images within **large** bodies of text. +Specifically, we only suggest using them with `EuiText` which comes automatically clears floats. + +::: + + diff --git a/website/docs/02_components/display/list_group/_category_.yml b/website/docs/02_components/display/list_group/_category_.yml new file mode 100644 index 00000000000..98564da992d --- /dev/null +++ b/website/docs/02_components/display/list_group/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_list_group_overview diff --git a/website/docs/02_components/display/list_group/overview.mdx b/website/docs/02_components/display/list_group/overview.mdx new file mode 100644 index 00000000000..1b389ac680f --- /dev/null +++ b/website/docs/02_components/display/list_group/overview.mdx @@ -0,0 +1,72 @@ +--- +id: component_list_group_overview +title: List group +export_name: + - EuiListGroup + - EuiListGroupItems + - EuiPinnableListGroup +slug: /components/list-group +--- + +The **EuiListGroup** component is used to present **EuiListGroupItems** in a neatly formatted list. +Use the `flush` and `bordered` properties for full-width and bordered presentations, respectively. + +Adjust the `gutterSize` prop to increase or decrease the spacing between items. + + + +## List of links + +Display **EuiListGroupItems** as links by providing an `href` value and change their state with +the `isActive` and `isDisabled` properties. + +If your link is external or will open in a new tab, you can manually set the `external` property. +However, just like with the [**EuiLink**](#/navigation/link) component, setting `target="_blank"` defaults to `external={true}`. + +As is done in this example, the **EuiListGroup** component can also accept an array of items +via the `listItems` property. + + + +## Secondary link actions + +The `extraAction` property adds a secondary icon button to any list item. It accepts several properties +of its own, including `color`, `onClick`, `iconType`, and `alwaysShow`, and can be used for actions +such as pinning, favoriting, or deleting an item. + + + +## Text wrapping and tooltips + +Optional props `showToolTip` and `wrapLines` can be used to augment the display of list items. +Use these when lists are inside small containers where it is likely that the content will be truncated. + +Similarly, `toolTipText` can be used to provide tooltip text. +By default, the tooltip will have the text same as the `label`. + +You can also use `toolTipProps` to customize tooltip placement, title, and other behaviors. + + + +## List item color and size + +**EuiListGroupItems** will get by default the color `text`. You can enforce a different color of `primary`, `text`, +or `subdued` with the `color` prop. Or provide the prop directly to **EuiListGroup**. + +They also accept options for text size; `'xs' | 's' | 'm' | 'l'`. + + + +## Pinnable list group + +**EuiPinnableListGroup** is simply an extra wrapper around an [**EuiListGroup**](#/display/list-group) +that provides visual indicators for **pinning**. + +Pinning is the concept that users can click a pin icon and add it to a subset of links +(most likely shown in different list group). By providing an `onPinClick` handler, the component will automatically +add the pin action to the item. However, the consuming application must manage the `listItems`and their `pinned` state. + +In order to get the full benefit of using **EuiPinnableListGroup**, the component only supports providing +list items via the `listItem` prop and does not support `children`. + + diff --git a/website/docs/02_components/display/loading/_category_.yml b/website/docs/02_components/display/loading/_category_.yml new file mode 100644 index 00000000000..3870c6c84cf --- /dev/null +++ b/website/docs/02_components/display/loading/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_loading_overview diff --git a/website/docs/02_components/display/loading/overview.mdx b/website/docs/02_components/display/loading/overview.mdx new file mode 100644 index 00000000000..fea868ef5db --- /dev/null +++ b/website/docs/02_components/display/loading/overview.mdx @@ -0,0 +1,39 @@ +--- +id: component_loading_overview +title: Loading +export_name: + - EuiLoadingElastic + - EuiLoadingLogo + - EuiLoadingSpinner +slug: /components/loading +--- + +Use loading indicators sparingly and opt for showing actual [progress](#/display/progress#progress-with-values) +over infinite spinners. It is ok to use multiple loaders on a page if each section is progressively loaded. +However, if the entire page is loaded at once, use a single, larger loading indicator. + +## Elastic + +The **EuiLoadingElastic** loader is great for full page or Elastic product loading screens. + + + +## Logos + +**EuiLoadingLogo** accepts any of our [**EuiIcon**](#/display/icons#elastic-logos) logos. +It should only be used in very large panels, like fullscreen pages. + + + +## Chart + +To indicate that a visualization is loading, use **EuiLoadingChart**. +The multicolor version should be used sparingly, and only when a single large visualization is being loaded. + + + +## Spinner + +**EuiLoadingSpinner** is a simple spinner for most loading contexts. + + diff --git a/website/docs/02_components/display/progress/_category_.yml b/website/docs/02_components/display/progress/_category_.yml new file mode 100644 index 00000000000..dac1bbb9ee5 --- /dev/null +++ b/website/docs/02_components/display/progress/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_progress_overview diff --git a/website/docs/02_components/display/progress/overview.mdx b/website/docs/02_components/display/progress/overview.mdx new file mode 100644 index 00000000000..14770ff14b8 --- /dev/null +++ b/website/docs/02_components/display/progress/overview.mdx @@ -0,0 +1,64 @@ +--- +id: component_progress_overview +title: Progress +export_name: EuiProgress +slug: /components/progress +--- + +The **EuiProgress** component by default will display in an indeterminate loading state (rendered as a single div) +until you define a `max` and `value` prop. The `size` prop refers to its vertical height. +It will always stretch `100%` to its container. + + + +## Progress with values + +Once the `max` and `value` props are set, it will act as a determinate progress bar. +This is rendered using an HTML5 `progress` tag. + + + +## Progress can have absolute or fixed positions + +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 + +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. + +::: + + + +## Sizes + +You can adjust the `size` of both determinate and indeterminate progress bars. + + + +## Colors + +**EuiProgress** supports a few options for `color`. You can pass any value from our basic color set +or from our visualization palette (`vis0` through `vis9`). To learn more about color usage, +go to the [Colors](#/theming/colors/values) page. + +Additionally, you can pass any valid color string like a hex value or named color. +Each `valueText` renders with a high contrast version of the color. + + + +## Progress for charts + +Determinate progress bar can be used as simple bar charts. Use them with the `label` and `valueText` props +to show the data corresponding to each bar. + +Setting `valueText={true}` will add a % sign next to the `value` passed. If you want to display +a custom `valueText`, you can pass a node instead. + + diff --git a/website/docs/02_components/display/skeleton/_category_.yml b/website/docs/02_components/display/skeleton/_category_.yml new file mode 100644 index 00000000000..7bb4779d265 --- /dev/null +++ b/website/docs/02_components/display/skeleton/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_skeleton_overview diff --git a/website/docs/02_components/display/skeleton/overview.mdx b/website/docs/02_components/display/skeleton/overview.mdx new file mode 100644 index 00000000000..9971faf95b6 --- /dev/null +++ b/website/docs/02_components/display/skeleton/overview.mdx @@ -0,0 +1,79 @@ +--- +id: component_skeleton_overview +title: Skeleton +export_name: + - EuiSkeleton + - EuiSkeletonText + - EuiSkeletonTitle + - EuiSkeletonCircle + - EuiSkeletonRectangle + - EuiSkeletonLoading +slug: /components/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 + +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 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 + +Use **EuiSkeletonText** to display a placeholder for multiple lines of text. + + + +## Title + +Use **EuiSkeletonTitle** to display a placeholder for heading titles. + + + +## Circle + +Use **EuiSkeletonCircle** to display a circular preview, mainly for avatars. + + + +## Rectangle + +**EuiSkeletonRectangle** allows you define a large and customizable shape via its `width`, `height`, +and `borderRadius` props. + + + +## Combining multiple skeletons + +**EuiSkeletonLoading** is a light wrapper around the **EuiSkeleton** components that handles loading accessibility +and flipping between skeleton and loaded content. + +As you may have noticed in the previous demos, toggling multiple skeletons to their loaded state all at once triggers +multiple queued screen reader announcements, which can be annoying to SR users. + +To circumvent this, use **EuiSkeletonLoading** to handle a single parent-level `isLoading` state. **EuiSkeleton** +children passed to the `loadingContent` should not have their own `isLoading` props or children. + + + +## Customizing screen reader announcements + +**EuiSkeleton** components assume that the page starts as loading and transitions to loaded, and the default +screen reader experience is set up accordingly (`announceLoadedStatus={true}`). + +In scenarios where that is not the case (i.e., transitioning to loading), you can customize what statuses +are announced to screen readers by setting `announceLoadingStatus` to true, or `announceLoadedStatus` to false. +Submitting the below example announces a loading status, but not a loaded status. + +As an optional escape hatch, `ariaLiveProps` is also available and accepts +any [**EuiScreenReaderLive**](#/utilities/accessibility#screen-reader-live-region) props. + + diff --git a/website/docs/02_components/display/stat/_category_.yml b/website/docs/02_components/display/stat/_category_.yml new file mode 100644 index 00000000000..a719059d7c3 --- /dev/null +++ b/website/docs/02_components/display/stat/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_stat_overview diff --git a/website/docs/02_components/display/stat/overview.mdx b/website/docs/02_components/display/stat/overview.mdx new file mode 100644 index 00000000000..8ceb3c35836 --- /dev/null +++ b/website/docs/02_components/display/stat/overview.mdx @@ -0,0 +1,56 @@ +--- +id: component_stat_overview +title: Stat +export_name: EuiStat +slug: /components/stat +--- + +**EuiStat** can be used to display prominent text or number values. +It consists of `title` and `description` elements with several visual styling properties (examples below). + + + +## Color variants + +`title` can be altered using the color property. By default, it will appear in `full` color. +For proper color contrast, only a limited set of EUI colors are offered. See the Props tab above +for a list of available colors. + + + +## Text alignment + +**EuiStat** also offers alignment options. By default, text will be left aligned. + + + +## Title size + +`title` uses the **EuiTitle** component and thus uses the same sizing property values +(applied via the `titleSize` property). Although all **EuiTitle** sizes are available, suggested sizes +include `'l' | 'm' | 's' | 'xs' | 'xxs' | 'xxxs'`. By default, the size is set to large `'l'`. +The `description` label cannot be re-sized via component properties. + + + +## Reverse the order + +You can reverse the order of the `description` and `title` text by setting the `reverse` property to true. +By default, the description (label) is displayed above the title (value). + + + +## Stat loading + +If you apply the `isLoading` prop, the title will indicate the loading status by swapping the provided title +with two flashing dashes. + + + +## Component variants + +In the following example, you can see variants of how the **EuiStat** component can be assembled. +This component is very helpful for constructing single-value visualizations and summaries for different dashboards +and page layouts and for communicating trends over time. + + diff --git a/website/docs/02_components/display/text/overview.mdx b/website/docs/02_components/display/text/overview.mdx index 05f84908f9d..22a8070284c 100644 --- a/website/docs/02_components/display/text/overview.mdx +++ b/website/docs/02_components/display/text/overview.mdx @@ -1,6 +1,46 @@ --- id: component_text_overview title: Text -export_name: EuiText +export_name: + - EuiText + - EuiTextColor + - EuiTextAlign slug: /components/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: + +* 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`. + + + +## Text can come in various sizes + +Using the `size` prop on **EuiText** you can get smaller sizes of text than the default. +This demo compares the scaling for all sizes. The goal is that the every line-height lands on the `4px` baseline grid. + + + +## Coloring text + +There are two ways to color text. Either individually by applying **EuiTextColor** on individual text objects, +or by passing the `color` prop directly on **EuiText** for a blanket approach across the entirety of your text. + + + +## Alignment + +There are two ways to align text. Either individually by applying **EuiTextAlign** on individual text objects, +or by passing the `textAlign` prop directly on **EuiText** for a blanket approach across the entirety of your text. + + diff --git a/website/docs/02_components/display/timeline/_category_.yml b/website/docs/02_components/display/timeline/_category_.yml new file mode 100644 index 00000000000..a299b34defc --- /dev/null +++ b/website/docs/02_components/display/timeline/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_timeline_overview diff --git a/website/docs/02_components/display/timeline/overview.mdx b/website/docs/02_components/display/timeline/overview.mdx new file mode 100644 index 00000000000..8e752992990 --- /dev/null +++ b/website/docs/02_components/display/timeline/overview.mdx @@ -0,0 +1,58 @@ +--- +id: component_timeline_overview +title: Timeline +export_name: + - EuiTimeline + - EuiTimelineItem +slug: /components/timeline +--- + +The **EuiTimeline** component standardizes the way a timeline thread is displayed. +Pass an array of **EuiTimelineItem** objects and **EuiTimeline** will generate a timeline thread. + +This component allows you to create any type of timeline, but for more specific use cases you should consider: + +* [**EuiSteps**](#/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**](#/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**. + +::: + + + +## Timeline item + +Each **EuiTimelineItem** has two parts: an icon on the left side and an event on the right side. +To create an item you need the following props: + +* `icon`: main icon that appears on the left side. Can be passed as any `IconType` string or custom node + (e.g. [**EuiAvatar**](#/display/avatar)). It is recommended not to use an element larger than 40x40. +* `children`: any node as the event content. + + + +## A timeline thread with multiple items + +You can create a timeline thread by rendering multiple **EuiTimelineItem** components in a **EuiTimeline**. +Following this structure ensures that timeline styles are applied correctly and appropriate semantic elements +are used to assist with screen readers. + +When passing an `icon` and `children` prop to each item, there are some design considerations to take into account: + +* `icon`: use icons of the same size to create a better visual consistency. +* `children`: when your content is just one line of text, the recommendation is to use a [**EuiText**](#/display/text) + as a wrapper. For multi-line content consider using a [**EuiPanel**](#/layout/panel) + or a [**EuiSplitPanel**](#/layout/panel#split-panels) instead. For other types of components like editors, + the recommendation is to pass the children without any wrapper. + +The following example shows how to display multiple **EuiTimelineItem**s and how you can use a **EuiSplitPanel** +as the content wrapper. + + diff --git a/website/docs/02_components/display/title/overview.mdx b/website/docs/02_components/display/title/overview.mdx index d028d01fdf6..6c38a460599 100644 --- a/website/docs/02_components/display/title/overview.mdx +++ b/website/docs/02_components/display/title/overview.mdx @@ -4,3 +4,9 @@ title: Title export_name: EuiTitle slug: /components/title --- + +**EuiTitle** styles the page, section, and content headings we use in Kibana. They can contain any markup, +but usually contain a heading tag of some sort. Unlike **EuiText** they are margin neutral and more suitable +for general layout design. + + diff --git a/website/docs/02_components/display/toast/_category_.yml b/website/docs/02_components/display/toast/_category_.yml new file mode 100644 index 00000000000..596f9bc5008 --- /dev/null +++ b/website/docs/02_components/display/toast/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_toast_overview diff --git a/website/docs/02_components/display/toast/overview.mdx b/website/docs/02_components/display/toast/overview.mdx new file mode 100644 index 00000000000..7520c48d3f8 --- /dev/null +++ b/website/docs/02_components/display/toast/overview.mdx @@ -0,0 +1,52 @@ +--- +id: component_toast_overview +title: Toast +export_name: EuiToast +slug: /components/toast +--- + +Be sure to read the full [toast usage guidelines](#/guidelines/toast). + +## Toast list + + + +## Default + +**EuiToast** allows for small notes that appear in the bottom right of the screen. +They should be used for ephemeral, live actions (think **save complete** or **something +just finished right now**). + +They should not be used for historical actions (**your report built 30 minutes ago**). +This means that a user should never be greeted with toasts when starting a session. +Toasts should be brief and avoid long paragraphs of text or titling. + + + +## Info + +For informative messages use `type="info"`. + + + +## Success + +For success messages use `color="success"`. + + + +## Warning + +Use this callout to warn the user against decisions they might regret. Show a warning message when the program +detects that **something is not behaving right, but it didn't cause any termination.** For warning messages +use `color="warning"`. + + + +## Danger + +Use this callout to let the user know that something went wrong. For example if you want to communicate an error. +You should show an error message when the issue is **terminal, this doesn't always mean that the operation stops +completely, but the task is not complete**. For errors messages use `color="danger"`. + + diff --git a/website/docs/02_components/display/tooltip/_category_.yml b/website/docs/02_components/display/tooltip/_category_.yml new file mode 100644 index 00000000000..f8b4bf300fe --- /dev/null +++ b/website/docs/02_components/display/tooltip/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_tooltip_overview diff --git a/website/docs/02_components/display/tooltip/overview.mdx b/website/docs/02_components/display/tooltip/overview.mdx new file mode 100644 index 00000000000..f73e7e4cfa4 --- /dev/null +++ b/website/docs/02_components/display/tooltip/overview.mdx @@ -0,0 +1,60 @@ +--- +id: component_tooltip_overview +title: Tooltip +export_name: + - EuiToolTip + - EuiIconTip +slug: /components/tooltip +--- + +Generally, tooltips should provide short, **non-essential**, contextual information, usually naming or describing +with more detail. If you need interactive content or anything other than text, +we recommend using [**EuiPopover**](#/layout/popover) instead. + +:::warning + +Putting anything other than plain text in a tooltip is lost on screen readers. + +::: + +Wrap **EuiToolTip** around any item that you need a tooltip for and provide the `content` and optionally +the `title`. The `position` prop will take a suggested position, but will change it if the tooltip gets +too close to the edge of the screen. + +:::warning + +Anchoring a tooltip to a non-interactive element makes it difficult for keyboard-only and screen reader users to read. + +::: + + + +## Wrapping components + +**EuiToolTip** wraps its children in a `` element that is `display: inline-block`. +If you are wrapping a block-level child (e.g. a `
`), you may need to change this by passing +`display="block"` but the resulting DOM may be in violation of the HTML5 spec. + +It also applies `onFocus` and `onBlur` props the the cloned `children`. If you pass in a custom component, +then you’ll need to make sure these props are applied to the root element rendered by your component. +The best way to do that is to follow +[EUI’s guidelines on pass-through props](https://github.com/elastic/eui/blob/main/wiki/contributing-to-eui/developing/props.md#pass-through-props). + + + +## Tooltip on a fixed element + +Tooltips even work on `position: fixed;` elements. Add the `repositionOnScroll` boolean prop to ensure the tooltip +realigns to the fixed anchor on scroll. + + + +## IconTip + +You can use **EuiIconTip** to explain options, other controls, or entire parts of the user interface. +When possible, surface explanations inline within the UI, and only hide them behind a **EuiIconTip** as a last resort. + +It accepts all the same props as **EuiToolTip**. For convenience, you can also specify optional +icon `size`, `type`, and `color` props. + + diff --git a/website/docs/02_components/display/tour/_category_.yml b/website/docs/02_components/display/tour/_category_.yml new file mode 100644 index 00000000000..32c67cd159e --- /dev/null +++ b/website/docs/02_components/display/tour/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_tour_overview diff --git a/website/docs/02_components/display/tour/overview.mdx b/website/docs/02_components/display/tour/overview.mdx new file mode 100644 index 00000000000..d4b5e5d21a4 --- /dev/null +++ b/website/docs/02_components/display/tour/overview.mdx @@ -0,0 +1,70 @@ +--- +id: component_tour_overview +title: Tour +export_name: + - EuiTour + - EuiTourStep +slug: /components/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. + +::: + +## Step options + +The **EuiTourStep** component is the base for building a feature tour or an individual popover for onboarding. + +All content and actions including titles, headings, and buttons are customizable via props. + + + +### Using DOM selector as anchor location + +Instead of wrapping the target element, use the `anchor` prop to specify a DOM node. Accepted values include +an HTML element, a function returning an HTML element, or a DOM query selector. + + + +## Standalone steps + +Each **EuiTourStep** can be configured independently via props. In this case, each component is stateless +and needs to be paired with some form of state management for navigation. The later examples showcase other ways +to handle state management via **useEuiTour** and **EuiTour**. + + + +## Managed state with the useEuiTour custom hook + +Use the **useEuiTour** hook for minimal state management using a predefined React reducer. Pass an array of steps +consisting of accepted props, and an object of global configuration. The result is a full configuration object +for each step, a set of reducer actions to perform state changes, and an up-to-date state object derived from +the internal reducer. + + + +## Managed state via EuiTour render prop component + +Use the **EuiTour** render prop component for minimal state management. +This is an alternative to the **useEuiTour** hook for React class components, +or use cases where a single wrapping component can be used. + + + +## Passive tour + +Use the **EuiTour** to provide sequential help without the user performing any actions +(e.g. filling out a form or copying a text). In this scenario, consider using two buttons, **Close tour** and **Next**. + + + +## Fullscreen demo + +Unlike the other examples on this page, this example does not use `localStorage` to persist state. + + diff --git a/website/docs/02_components/layout/flyout/overview.mdx b/website/docs/02_components/layout/flyout/overview.mdx index e2a0da7d6e9..507788ba601 100644 --- a/website/docs/02_components/layout/flyout/overview.mdx +++ b/website/docs/02_components/layout/flyout/overview.mdx @@ -62,7 +62,7 @@ at smaller window widths. You can adjust this minimum breakpoint with `pushMinBr Push flyouts require manual accessibility management Push flyouts do not use a focus trap, do not close on Escape keypress, do not inherit -a [dialog role(opens in a new tab or window)](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role), +a [dialog role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role), and do not include any of the default screen reader guidance that overlay flyouts contain out-of-the-box. Please be cautious when using push flyouts, and make sure you are managing your own focus and screen reader UX. diff --git a/website/docs/02_components/navigation/link/overview.mdx b/website/docs/02_components/navigation/link/overview.mdx index 9f836266831..b1758f3d6d4 100644 --- a/website/docs/02_components/navigation/link/overview.mdx +++ b/website/docs/02_components/navigation/link/overview.mdx @@ -28,5 +28,5 @@ be set to`disabled` which disables the click behavior, and removes the link styl To make links more secure for users, **EuiLink** and other components that accept an `href` prop become disabled if that `href` uses the `javascript:` protocol. This helps protect consuming applications from cross-site scripting (XSS) attacks and mirrors React's -[planned behavior(opens in a new tab or window)](https://github.com/facebook/react/blob/940f48b999a3131e77b2545bd7ae252ef27ae6d1/packages/react-dom/src/shared/sanitizeURL.js#L37) +[planned behavior](https://github.com/facebook/react/blob/940f48b999a3131e77b2545bd7ae252ef27ae6d1/packages/react-dom/src/shared/sanitizeURL.js#L37) to prevent rendering of `javascript:` links.