[EUI+] Reorganize Forms category #8184

cee-chen · 2024-11-23T01:16:21Z

Summary

I was crunched for time, so sadly the git commit history on this PR is something of a tragedy. Apologies! Feel free to chop up/take and use this PR for whatever you want. I categorized the various form controls into sections based primarily on usage type:

Overall sections:

Individual subcategories:

Selection components overview

The biggest thing I really wanted to add to this PR (other than shuffling pages around) was to convert #7049 into an actual page on our docs site instead of needing a separate wiki for it:

And I think this PR succeeds fairly well at that! 🤞 (although there are some TODO comments in the mdx file that I did not have time to improve on)

QA

Entire Forms category of component docs: https://eui.elastic.co/pr_8184/new-docs/docs/forms/layouts/guidelines/

General checklist

N/A, docs changes only

packages/website/docs/components/forms/form_layouts/prepend_append.mdx

- Remove top level link/doc and add more sublevel items - give described form group its own page - move compressed forms to this section - remove "in a popover" example from form rows - compressed forms already have this example and explicitly state non-compressed forms should not be used in popovers - remove guideline CTA to its own page??

I gave up on git history, sorry :|||

- was previously at the top of a single page with basic controls, will need to spread it out a bit more now - there are more components that can take EuiFormRow (and some that can't), we probably need to audit which at some point. this is not meant to be a perfect solution

- they fit under the general layout guideline text, so might as well move them here?

+ add a demo for nativate invalidation checking

+ some copy/link updates

+ updates etc

+ remove various callouts/links to it - in theory now that the components are grouped together, it should be easy to decide which to use - (opinionated, feel free to revert) remove images of various components, not sure how useful it is on the actual docs site

…o its own section + move EuiFormFieldset to the label section (feels like that's where it makes more sense)

packages/website/docs/components/forms/selection/overview.mdx

weronikaolejniczak · 2025-02-11T12:07:47Z

@tkajtoch @mgadewoll @acstll I'd appreciate your review and let me know what you think about the changes, maybe you have some more suggestions 🙏🏻

@mgadewoll I had a conflict in color picker docs, I was able to boil the changes down to this PR. Could you take a look whether I resolved the conflicts correctly and all is as expected?

Testing notes

I was:

judging the logical order of subcategories and pages,
comparing content between the old docs and the new docs,
testing redirections on each page,
comparing examples and previews visually (in case there are visual regressions),
checking the prop list, if all components are considered,
checking whether the content was not duplicated or removed.

Form layouts ✅

Forms > Form layouts > Described form groups

Screenshot

EuiTextBlock doesn't redirect anywhere.

Form validation ✅

Text controls ✅

Forms > Text controls > Inline edit > Customizing read and edit modes

Screenshot

All of these redirections do not work as expected.

Numeric controls ❌

Forms > Numeric controls > Range sliders > Props

Screenshot

The EuiInputPopover redirects to homepage.

Selection controls ❌

Main page

Screenshot

I feel this alert from the old docs belongs on the main "Selection controls" page.

Forms > Selection controls > Multiple selections

Screenshot

The EuiComboBox redirection is not working as expected.

Category structure

I feel that the structure for checkboxes and radios is not logical. They are packed in the main page, and as a subpage there's "Switches" (although originally, they're all on the same page. Additionally, I don't see the need for distinguishing this subcategory of "Checkboxes and Radios", and how Switches fall into that (they're neither Checkbox or Radio).

I would suggest to put all the pages on the same level.

Screenshot

Forms > Selection controls > Checkboxes and radios > Switches

Screenshot

The guidelines tab and EuiFormRow redirections don't work.

Forms > Selection controls > Basic select

Screenshot

The EuiRadioGroup redirection doesn't work.

Forms > Selection controls > Super select

Screenshot

etc... -> etc.

> Props

Screenshot

The EuiInputPopover redirection doesn't work.

Forms > Selection controls > Combo box

There's quite a lot of headers on the same level. I think some can be grouped into higher level, e.g. "Selection" headers.

Screenshot

Additionally, some content is missing from the old docs, like the alert and:

If you're unsure of which selection component to use, see EUI's in-depth guide to selection components(external, opens in a new tab or window) for more information.

Screenshot

This alert seems repetitive? We could say this about all controls, right? Not ComboBox specifically.

> Truncation

Screenshot

The EuiTextTruncate redirection doesn't work. (The whole Utilities section is missing, it will be added on: #8190)

Forms > Selection controls > Selectable

The redirections: EuiComboBox, EuiFilterGroup and EuiTextTruncate don't work.

(The whole Utilities section is missing, it will be added on: #8190)

Search and filter controls ✅

Forms > Search and filter controls > Filter group

Screenshot

The EuiSelectable redirection doesn't work.

Date and time controls ❌

Main page

Screenshot

Feels to me like EuiDatePicker belongs to a subpage of "Date and time controls", alongside "Date picker range".

Forms > Date and time controls

Screenshot

This section seems to belong in EuiDatePickerRange instead. Also, not sure why it belongs under "Locale"?

Forms > Date and time controls > Super date picker > Elastic pattern with KQL

Screenshot

The EuiSearchBar redirection doesn't work.

Other controls ✅

Forms > Other controls > Color palette picker

Screenshot

The EuiColorPalettePicker redirection doesn't work.

weronikaolejniczak · 2025-02-11T16:56:35Z

There are few issues I left, either I don't know how to fix it or I believe it should not be fixed on this PR:

EuiInputPopover redirection - the link is in the JSDoc (packages/eui/src/components/form/range/types.ts) which I would break by updating it to the new docs structure (/docs/layout/popover#popover-attached-to-input-element). Probably should be done after we release or we create a redirection when /#/layout/popover#popover-attached-to-input-element is visited on the new page? This way we preserve inbound links.
Structural decisions for "checkboxes and radios", "date picker" and pages content like moving the alert to the main "Selection controls" page.

Those are decisions I don't feel confident making on my own.

mgadewoll

I checked the forms docs: The new structure works well and from what I can tell almost all content is there (just missing latest changes to color picker docs for appended titles)

⚠️ But I did find a lot of links that didn't work as expected. From what I can tell, any absolute link (e.g. like /docs/... or /#/) does not work in the PR environment as we are on different sub directories.
I guess we might want to update to relative paths to ensure links work in any environment 🤔

List of links I found for forms:

packages/website/docs/components/forms/selection/overview.mdx

packages/website/docs/components/forms/form_layouts/described_form_group.mdx

packages/website/docs/components/forms/form_layouts/form_label.mdx

packages/website/docs/components/forms/other/color_picker.mdx

weronikaolejniczak · 2025-02-13T15:14:21Z

buildkite test this

weronikaolejniczak · 2025-02-13T16:01:46Z

@mgadewoll Docs deployed, the latest color palette picker changes are there:

Could you take a look again, compare to this PR? Thanks!

weronikaolejniczak · 2025-02-17T11:30:17Z

@acstll @mgadewoll I updated all links in the Forms category:

I used <a> tag for external links to open them in a new tab (0e79d69),
I changed absolute links (/docs/, /#/) to relative path files (df543c3),
I changed relative URL links to relative path files (885201a and
78cff5a, except for packages/website/docs/components/forms/form_layouts/described_form_group.mdx:39 because it's in a JSX block).

To find all Markdown links I used this regexp: \[([^\]]+)\]\(([^)]+)\) and filtered by the forms folder.

Additionally, I added a section about the links to README.md (to document our decision; ADR would be an overkill). I'll merge the latest changes because I have merged another EUI+ PR and I'll trigger the build on this one.

I'd like to ask you to do a quick sanity check, pretty please 🙏🏻

weronikaolejniczak · 2025-02-17T15:21:48Z

buildkite test this

kibanamachine · 2025-02-17T15:46:31Z

Preview staging links for this PR:

Docs site: https://eui.elastic.co/pr_8184/
Storybook: https://eui.elastic.co/pr_8184/storybook
New docs: https://eui.elastic.co/pr_8184/new-docs

elasticmachine · 2025-02-17T15:47:12Z

💚 Build Succeeded

Buildkite Build
Commit: 7060c45

History

💚 Build elastic/eui#3447 succeeded 6412414
💚 Build elastic/eui#3255 succeeded 6642ca2
💚 Build elastic/eui#3254 succeeded 9a51bfc
💚 Build elastic/eui#3253 succeeded c87b1e3
💚 Build elastic/eui#3248 succeeded 46c82bd
💚 Build elastic/eui#3129 succeeded 4cab393

cc @weronikaolejniczak

mgadewoll

🚢 🐈‍⬛ Thanks for the updates!
The changes look good to me and the links in forms work as expected 🎉

packages/website/README.md

cee-chen added documentation Issues or PRs that only affect documentation - will not need changelog entries skip-changelog labels Nov 23, 2024

cee-chen force-pushed the website/reorg-4 branch from 4cab393 to 46c82bd Compare December 13, 2024 10:20

cee-chen mentioned this pull request Dec 13, 2024

[EUI+] Reorganise the document pages #8163

Closed

12 tasks

cee-chen changed the title ~~[EUI+] Reorganize Forms category (WIP)~~ [EUI+] Reorganize Forms category Dec 13, 2024

cee-chen marked this pull request as ready for review December 14, 2024 02:52

cee-chen requested a review from a team as a code owner December 14, 2024 02:52

JasonStoltz assigned weronikaolejniczak Jan 14, 2025

weronikaolejniczak linked an issue Jan 27, 2025 that may be closed by this pull request

[EUI+] Reorganise the document pages #8163

Closed

12 tasks

weronikaolejniczak reviewed Feb 11, 2025

View reviewed changes

packages/website/docs/components/forms/form_layouts/prepend_append.mdx Outdated Show resolved Hide resolved

cee-chen added 10 commits February 11, 2025 10:40

rearrange all the things

de3c501

I gave up on git history, sorry :|||

Add missing form control guidelines

9da194b

- they fit under the general layout guideline text, so might as well move them here?

[text] reorganize basic controls to top-level page

cb7b3c5

[numeric] reorganize basic control to top level

b150e25

+ add a demo for nativate invalidation checking

[date] reorganize date picker to top-most page

a0bf980

+ some copy/link updates

[search] reorganize search and filtering docs

e8e2a65

+ updates etc

[selection] add missing checkbox/radio guidelines + split up switch t…

667bfa0

…o its own section + move EuiFormFieldset to the label section (feels like that's where it makes more sense)

weronikaolejniczak force-pushed the website/reorg-4 branch from 6642ca2 to 667bfa0 Compare February 11, 2025 09:46

weronikaolejniczak reviewed Feb 11, 2025

View reviewed changes

packages/website/docs/components/forms/selection/overview.mdx Show resolved Hide resolved

weronikaolejniczak reviewed Feb 11, 2025

View reviewed changes

packages/website/docs/components/forms/selection/overview.mdx Show resolved Hide resolved

fix(website): add space in text for prepend_append

72d3556

weronikaolejniczak added 5 commits February 11, 2025 13:23

fix(website): fix EuiTextBlock redirection

2b813fb

fix(website): fix inline edit customizing read and edit modes redirects

929fac4

fix(website): fix EuiSelectable redirection

2bbfa99

fix(website): fix EuiSearchBar redirection

46e293d

fix(website): remove redundant link

693c3c0

weronikaolejniczak added 6 commits February 11, 2025 17:17

fix(website): fix combo-box redirection, remove .mdx

294308a

fix(website): fix Switch page redirections

699c21f

fix(website): fix EuiRadioGroup redirection

67cd6f9

fix(website): remove redundant ellipsis in super select content

dcc142e

feat(website): group similar sections under the same header

721c9d9

fix(website): move section to date picker range

883ab19

Merge branch 'main' into website/reorg-4

6412414

weronikaolejniczak requested review from acstll, tkajtoch and mgadewoll February 12, 2025 15:04

mgadewoll reviewed Feb 13, 2025

View reviewed changes

weronikaolejniczak added 5 commits February 17, 2025 11:20

fix(website): update external links to use anchor tag

0e79d69

fix(website): update absolute links to relative file paths

df543c3

fix(website): use relative file paths in forms selection overview

885201a

fix(website): update relative URL links to relative path files

78cff5a

chore(website): add a section about links to README.md

4fa2870

Merge branch 'main' into website/reorg-4

7060c45

weronikaolejniczak requested a review from mgadewoll February 17, 2025 12:08

mgadewoll approved these changes Feb 18, 2025

View reviewed changes

packages/website/README.md Show resolved Hide resolved

weronikaolejniczak merged commit f884faa into elastic:main Feb 18, 2025
5 checks passed

This was referenced Mar 6, 2025

[EUI+] Broken subcategory names #8408

Merged

[EUI+] Fix typos #8412

Merged

mgadewoll mentioned this pull request Mar 20, 2025

fix(website): fix broken homepage links #8483

Merged

2 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EUI+] Reorganize Forms category #8184

[EUI+] Reorganize Forms category #8184

cee-chen commented Nov 23, 2024 •

edited

Loading

weronikaolejniczak commented Feb 11, 2025 •

edited

Loading

weronikaolejniczak commented Feb 11, 2025 •

edited

Loading

mgadewoll left a comment

weronikaolejniczak commented Feb 13, 2025

weronikaolejniczak commented Feb 13, 2025

weronikaolejniczak commented Feb 17, 2025

weronikaolejniczak commented Feb 17, 2025

kibanamachine commented Feb 17, 2025

elasticmachine commented Feb 17, 2025

mgadewoll left a comment

[EUI+] Reorganize Forms category #8184

[EUI+] Reorganize Forms category #8184

Conversation

cee-chen commented Nov 23, 2024 • edited Loading

Summary

Selection components overview

QA

General checklist

weronikaolejniczak commented Feb 11, 2025 • edited Loading

Testing notes

Form layouts ✅

Form validation ✅

Text controls ✅

Numeric controls ❌

Selection controls ❌

Search and filter controls ✅

Date and time controls ❌

Other controls ✅

weronikaolejniczak commented Feb 11, 2025 • edited Loading

mgadewoll left a comment

Choose a reason for hiding this comment

weronikaolejniczak commented Feb 13, 2025

weronikaolejniczak commented Feb 13, 2025

weronikaolejniczak commented Feb 17, 2025

weronikaolejniczak commented Feb 17, 2025

kibanamachine commented Feb 17, 2025

elasticmachine commented Feb 17, 2025

💚 Build Succeeded

History

mgadewoll left a comment

Choose a reason for hiding this comment

cee-chen commented Nov 23, 2024 •

edited

Loading

weronikaolejniczak commented Feb 11, 2025 •

edited

Loading

weronikaolejniczak commented Feb 11, 2025 •

edited

Loading