diff --git a/website/docs/02_components/forms/_category_.yml b/website/docs/02_components/forms/_category_.yml new file mode 100644 index 00000000000..6c8166c52b8 --- /dev/null +++ b/website/docs/02_components/forms/_category_.yml @@ -0,0 +1,3 @@ +label: Forms +collapsed: false +position: 4 diff --git a/website/docs/02_components/forms/auto_refresh/_category_.yml b/website/docs/02_components/forms/auto_refresh/_category_.yml new file mode 100644 index 00000000000..0c1fe763e4d --- /dev/null +++ b/website/docs/02_components/forms/auto_refresh/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_auto_refresh_overview diff --git a/website/docs/02_components/forms/auto_refresh/overview.mdx b/website/docs/02_components/forms/auto_refresh/overview.mdx new file mode 100644 index 00000000000..eeb67eb2663 --- /dev/null +++ b/website/docs/02_components/forms/auto_refresh/overview.mdx @@ -0,0 +1,25 @@ +--- +id: component_auto_refresh_overview +title: Auto refresh +slug: /components/auto-refresh +--- + +This is a component that is used by the [**EuiSuperDatePicker**](#/templates/super-date-picker) component +to create an automatic refresh configuration. It merely provides a common UI pattern but the actual refresh +counter is maintained by you. It `isPaused` by default and the `refreshInterval` is set in milliseconds. + + + +## Auto refresh button + +If you're looking for a more compact version, you can use **EuiAutoRefreshButton**, +which is the same button that is appended to **EuiSuperDatePicker**. +For even more compactness, add `shortHand={true}` to reduce the active unit to a single letter. + + + +## Refresh interval + +For even more customizablity, you can use the **EuiRefreshInterval** component which simply provides the form inputs. + + diff --git a/website/docs/02_components/forms/color_selection/_category_.yml b/website/docs/02_components/forms/color_selection/_category_.yml new file mode 100644 index 00000000000..773045ba6d3 --- /dev/null +++ b/website/docs/02_components/forms/color_selection/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_color_selection_overview diff --git a/website/docs/02_components/forms/color_selection/overview.mdx b/website/docs/02_components/forms/color_selection/overview.mdx new file mode 100644 index 00000000000..f0f9855c45b --- /dev/null +++ b/website/docs/02_components/forms/color_selection/overview.mdx @@ -0,0 +1,114 @@ +--- +id: component_color_selection_overview +title: Color selection +export_name: + - EuiColorPicker + - EuiColorPalettePicker +slug: /components/color-selection +--- + +Two components exist to aid color selection: **EuiColorPicker** and **EuiColorPalettePicker**. + +## Color picker + +Color input component allowing for multiple methods of entry and selection. + +Direct text entry will match hexadecimal (hex) and RGB(a) colors, and output will return both hex and RGBa values. +Spatial selection involves HSV manipulation, which is converted to hex. + +Swatches allow consumers to predefine preferred or suggested choices. +The swatches must also be entered in hex or RGBa format. + + + +## Color palette picker + +Use **EuiColorPalettePicker** to select palettes to apply colors to data visualization like maps and charts. + +Use the `palettes` prop to pass your palettes as an array `strings` or an array of `ColorStops` in the form +of `{ stop: number, color: string }`. For each object, you should pass a palette (array of hex values) +and specify the `type`. Use `fixed` palettes for categorical data and `gradient` palettes for continuous data. + + + +## Color palette display + +Use **EuiColorPaletteDisplay** to show the palette in use for a data visualization. + +Use the palette prop to pass your palette as an array of color `strings` or an array of `ColorStops` +in the form of `{ stop: number, color: string }`. Use `fixed` palettes for categorical data +and `gradient` palettes for continuous data. + +In cases you need to apply a palette, it's recommended to use +the [**EuiColorPalettePicker**](#/forms/color-selection#color-palette-picker). + + + +## Format selection + +Format selection does _not_ limit the format of text input the picker will allow, but instead attempts +to keep consistency during HSV selection. By default, the color picker will automatically +use the last input value format. Notice in following the examples how hue and saturation selection behave differently. + +Swatches will always show the "as-authored" color value, as will the value provided via the `color` prop. + + + +## Alpha channel (opacity) selection + +To allow color opacity via alpha channel, set `showAlpha=true`. +This will also display a range slider allowing manual opacity updates. + + + +## Custom color swatches + +By default, the colors provided are the ten color-blind safe visualization colors. +You can however pass in your own color set with the `swatches` prop. + + + +## Limited selection modes + +By default, both swatch selection and the gradient color map will be rendered. +Use the `mode` prop to pass `swatch` for swatch-only selection, or pass `picker` for gradient map and hue slider +selection without swatches. + + + +## Custom button + +Available only in **EuiColorPicker**. You can optionally use a custom button as the trigger for selection +using the `button` prop. Please remember to add accessibility to this component, +using proper button markup and aria labeling. + +Additionally, use the `secondaryInputDisplay` prop to show a secondary or alternative color value input. +Options include `top` and `bottom` placement. + + + +## Empty state + +For instances where an "empty" color picker has meaning other than transparent color value, +use the `placeholder` prop to provide context. Removing color selection and returning to the default state +can be made easier by setting `isClearable=true`. + + + +## Inline + +Available only in **EuiColorPicker**. Set the `display` prop to `inline` to display the color picker +without an input or popover. Note that the `button` prop will be ignored in this case. + + + +## Containers + +Demonstrating that both color selection components can exist in portal containers and that their popover +positioning works in nested contexts. + + + +## Option toggling + + diff --git a/website/docs/02_components/navigation/combo_box/_category_.yml b/website/docs/02_components/forms/combo_box/_category_.yml similarity index 100% rename from website/docs/02_components/navigation/combo_box/_category_.yml rename to website/docs/02_components/forms/combo_box/_category_.yml diff --git a/website/docs/02_components/navigation/combo_box/overview.mdx b/website/docs/02_components/forms/combo_box/overview.mdx similarity index 100% rename from website/docs/02_components/navigation/combo_box/overview.mdx rename to website/docs/02_components/forms/combo_box/overview.mdx diff --git a/website/docs/02_components/forms/compressed_forms/_category_.yml b/website/docs/02_components/forms/compressed_forms/_category_.yml new file mode 100644 index 00000000000..8176b440416 --- /dev/null +++ b/website/docs/02_components/forms/compressed_forms/_category_.yml @@ -0,0 +1,4 @@ +link: + type: doc + id: component_compressed_forms_overview +position: 4 diff --git a/website/docs/02_components/forms/compressed_forms/overview.mdx b/website/docs/02_components/forms/compressed_forms/overview.mdx new file mode 100644 index 00000000000..2216213d27a --- /dev/null +++ b/website/docs/02_components/forms/compressed_forms/overview.mdx @@ -0,0 +1,58 @@ +--- +id: component_compressed_forms_overview +title: Compressed forms +slug: /components/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. + + + +## Column layout + +Editor-style controls can be displayed in a two column layout for even better use of limited space, +just pass `display="columnCompressed"` to align the labels and inputs side by side. + +**EuiSwitches** are a special case in which so you must pass `"columnCompressedSwitch"` +to the EuiFormRow as the display property. + + + +## Contextual help + +When using compressed, horizontal form styles, it is best not to overload the UI with expansive help text. +If it's short and part of the validation, use `helpText`. However, if it's an explanation of the control, +consider wraping the label with an [**EuiToolTip**](#/display/tooltip) and appending the `questionInCircle` icon to it. + + + +## In a popover + +Always use the compressed version of forms and elements when they exist inside a [popover](#/layout/popover). + + + +## Complex example + +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`. + +::: + + diff --git a/website/docs/02_components/forms/date_picker/_category_.yml b/website/docs/02_components/forms/date_picker/_category_.yml new file mode 100644 index 00000000000..eecb55824f0 --- /dev/null +++ b/website/docs/02_components/forms/date_picker/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_date_picker_overview diff --git a/website/docs/02_components/forms/date_picker/overview.mdx b/website/docs/02_components/forms/date_picker/overview.mdx new file mode 100644 index 00000000000..7a5d8b9b19e --- /dev/null +++ b/website/docs/02_components/forms/date_picker/overview.mdx @@ -0,0 +1,101 @@ +--- +id: component_date_picker_overview +title: Date picker +export_name: EuiDatePicker +slug: /components/date-picker +--- + +At its most bare the **EuiDatePicker** only requires props for `selected` and `onChange`. +It depends on [moment](https://momentjs.com/docs/) for all of its formatting. + + + +## Date picker states + +Examples of how the input can appear within a form. This should match our other form styles. + + + +## Time selection + +Two props control time selection. `showTimeSelect` will make time selection appear next to the calendar +and `showTimeSelectOnly` will exclude the calendar and make the time selection the only thing you see. +Make sure to adjust your `dateFormat` and `timeFormat` values to match. + + + +## Locale + +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. + +::: + + + +## Date picker range + +To create a single date range control, use **EuiDatePickerRange** and pass individual **EuiDatePicker** components +into the `startDateControl` and `endDateControl` props. You can control the state of both inputs as direct props +on **EuiDatePickerRange** as well as control each individually. Date specific props need to applied +to the individual components. + + + +### Dynamic `minDate` and `maxDate` + +By using `minDate` and `maxDate`, and updating the values based on `startDate` and `endDate`, +users get immediate feedback on what range values are allowed. + + + +## Only allow specific dates and times + +Use the `minDate`, `maxDate`, `minTime`, and `maxTime` props to specify specific ranges the `selected` code +must fall into. You can also use the `excludeDates` and`excludeTimes` property to disallow a specific +array of items from selection. + + + +## Open to a specific date + +Use `openToDate` to default selection to a specific date. + + + +## Custom input + +Use `customInput` to pass a custom input to trigger your calendar. + + + +## UTC offsets + +Use `utcOffset` to apply an offset to the datetime. + + + +## Date picker inline + +Use the `inline` prop to display the date picker directly in the page instead of inside a popover. +This prop works for both **EuiDatePicker** as well as **EuiDatePickerRange**. +If you do not need the default inline shadow effect, apply the `shadow={false}` prop. + + + +## Custom classes + +Custom classes can be passed to various bits of the calendar and input. + +* `className` will pass onto the input. +* `calendarClassName` will pass onto the calendar itself. +* `dayClassName` will pass onto specified days. +* `popperClassName` will pass onto the popover. + + diff --git a/website/docs/02_components/forms/expression/_category_.yml b/website/docs/02_components/forms/expression/_category_.yml new file mode 100644 index 00000000000..59bf4d7ac82 --- /dev/null +++ b/website/docs/02_components/forms/expression/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_expression_overview diff --git a/website/docs/02_components/forms/expression/overview.mdx b/website/docs/02_components/forms/expression/overview.mdx new file mode 100644 index 00000000000..19f4c426007 --- /dev/null +++ b/website/docs/02_components/forms/expression/overview.mdx @@ -0,0 +1,52 @@ +--- +id: component_expression_overview +title: Expression +export_name: EuiExpression +slug: /components/expression +--- + +Use the **EuiExpression** component to surface expressions. It requires both a `description` (left side) +and `value` (right side). Optionally, you can pass it an `onClick` function that will convert it to a button +and add some additional styling to indicate that it is clickable. + + + +## Colors + +You can pass a `color` prop but it will only color the `description`. + + + +## Stringing a bunch together + +If the expression is more than one description and value, you can string multiple expressions together, +and they should inline together and wrap at logical points. + + + +## Column display + +There might be cases where displaying multiple **EuiExpression**s in a paragraph is not ideal. +For example, when both the `description` and the `value` are variable or when their text is quite long. +To use a column display instead, pass `display="columns"`. + +In column display, each expression is its own line and the `description` column is aligned to the right. +The default width for the `description` is 20%, but you can customize this with the`descriptionWidth` prop. +When displaying a group of **EuiExpression**s, make sure to set the same width for all descriptions. + + + +## Invalid state + +Set `isInvalid` to true to display **EuiExpression**'s error state. +This state will override the `color` prop with danger. + + + +## Truncate text + +To truncate **EuiExpression**'s content, pass `textWrap="truncate"`. +Text truncation only works properly if the prop types of `description` and `value` are strings. +If you're using nodes, use the `.eui-textTruncate` utility class on all their sub-children. + + diff --git a/website/docs/02_components/forms/filter_group/_category_.yml b/website/docs/02_components/forms/filter_group/_category_.yml new file mode 100644 index 00000000000..89e8a0341cb --- /dev/null +++ b/website/docs/02_components/forms/filter_group/_category_.yml @@ -0,0 +1,3 @@ +link: + type: doc + id: component_filter_group_overview diff --git a/website/docs/02_components/forms/filter_group/overview.mdx b/website/docs/02_components/forms/filter_group/overview.mdx new file mode 100644 index 00000000000..824c8bb2878 --- /dev/null +++ b/website/docs/02_components/forms/filter_group/overview.mdx @@ -0,0 +1,43 @@ +--- +id: component_filter_group_overview +title: Filter group +export_name: + - EuiFilterGroup + - EuiFilterButtons +slug: /components/filter-group +--- + +## Filter buttons + +Use **EuiFilterGroup** to wrap **EuiFilterButtons** into a container that looks nice against form fields (like search). +These buttons are used in two different patterns. The most simplest use is that of an on/off pattern to show whether +a filter is on. Add the prop `withNext` to remove the border between it and the next EuiFilterButton +to visually group similar or opposite style filters. + +Add the prop `withNext` to remove the border between it and the next EuiFilterButton to visually group similar +or opposite style filters. + +Set `hasActiveFilters` to true when the filter is active. + + + +## Multi-select + +To provide a long list of grouped filters, we recommend wrapping the filter button within +an [**EuiPopover**](#/layout/popover) and passing the items to a searchable [**EuiSelectable**](#/forms/selectable). + +### Indicating number of filters + +By passing a number to `numFilters` you can express the number of filters available. +When the user has applied these filter add the prop `hasActiveFilters` as before and this will change +the coloring of the indicator. You can also supply a number to `numActiveFilters` which will change +the number displayed. + + + +## Layout + +By default, the bar is auto-widthed based on its contents. To expand the bar to fill its parent's width +add `fullWidth`. This will also set each button to grow. If you do not want the button to grow, set `grow=false`. + + diff --git a/website/docs/02_components/forms/form_controls/_category_.yml b/website/docs/02_components/forms/form_controls/_category_.yml new file mode 100644 index 00000000000..9902d5d74f1 --- /dev/null +++ b/website/docs/02_components/forms/form_controls/_category_.yml @@ -0,0 +1,4 @@ +link: + type: doc + id: component_form_controls_overview +position: 1 diff --git a/website/docs/02_components/forms/form_controls/overview.mdx b/website/docs/02_components/forms/form_controls/overview.mdx new file mode 100644 index 00000000000..091f1072cc7 --- /dev/null +++ b/website/docs/02_components/forms/form_controls/overview.mdx @@ -0,0 +1,139 @@ +--- +id: component_form_controls_overview +title: Form controls +export_name: + - EuiFieldText + - EuiFieldSearch + - EuiFieldNumber + - EuiFieldPassword + - EuiSelect + - EuiTextArea + - EuiFilePicker +slug: /components/form-controls +--- + +EUI provides different types of basic form controls: [**EuiFieldText**](#/forms/form-controls#text-field), +[**EuiFieldSearch**](#/forms/form-controls#search-field), [**EuiFieldNumber**](#/forms/form-controls#number-field), +[**EuiFieldPassword**](#/forms/form-controls#password-field), [**EuiSelect**](#/forms/form-controls#select), +[**EuiTextArea**](#/forms/form-controls#textarea), and [**EuiFilePicker**](#/forms/form-controls#file-picker). + +:::warning + +Wrap each of your from controls in a **EuiFormRow** + +Use the [**EuiFormRow**](#/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. + +::: + +## Text field + +This component renders a basic HTML `` element. +Use a **EuiFieldText** to allow users to enter or edit text. + + + +## Search field + +This component renders a basic HTML `` element. +Use a **EuiFieldSearch** to allow users to enter search queries. + + + +## Number field + +This component renders a basic HTML `` element. +Use a **EuiFieldNumber** to allow users to enter numbers. + + + +## Password field + +Use a **EuiFieldPassword** to allow users to enter a password. +By default, it renders a basic HTML `` where the content is obfuscated. +When users type in the field the characters are presented as asterisks. + +You can change this default behavior by passing `type="dual"` so that users can toggle between showing +and obfuscating the content. This option makes the experience more user-friendly and accessible. + + + +## Select + +This component renders a basic HTML `