[Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905

cchaos · 2022-05-17T17:16:52Z

Warning: DO NOT LOOK AT THE COMMIT HISTORY 🙈

New template components

`EuiPageTemplate`

This new version of the component is a namespaced component that clones the direct children, checking for if they're specifically one of the namespaced components and then clones and applies specific 'global' styling attributes to them based on top-level props and the full configuration of other existing components. If a child is not a namespaced component, it will get wrapped in a page section.

Note
This component no longer utilizes the general template prop to establish what type of layout should be rendered but just decides it based on the content passed in. But of course any configuration can be customized with top-level props.

The template specific versions of these child components are prefixed with _ because they should not be used as standalone components. They should always be used via their namespaced component similar to how EuiSplitPanel is handled.

For full details, read through the new documentation page: https://eui.elastic.co/pr_5905/#/templates/page-template

`_EuiPageOuter` as the overall wrapping component

The props are similar to that of EuiPage but without restrictWidth. It does add a responsive prop for customizing the breakpoints at which to shift to mobile view.

`_EuiPageInner` as the overall wrapping component for the main contents (not including sidebar)

The props are similar to EuiPageBody but without restrictWidth and panelProps as it doesn't extend EuiPanel. It does add a border prop which is mainly controlled by the template to add a single left-side border if a pagesidebar exists to provide definition of space.

`_EuiPageSidebar` as EuiPageTemplate.Sidebar

Note
Still trying to decide if this should become the new version of EuiPageSidebar and deprecate the old one.

This component is similar to the existing EuiPageSideBar in that it doesn't do much but handle some padding and sticky position behavior. However, this version is more customizable, relying less on Sass vars/mixins to allow customizing:

sticky.offset: Manual customization of the top offset for sticky sidebars, otherwise if sticky=true it will calculate it's top position based on the new data-fixed-headers quantity applied to the body element.
minWidth: Passed to the style tag, defaults to 260px
responsive: Allows customizing the array of breakpoint names in which to show the mobile version

`EuiPageHeader` as EuiPageTemplate.Header

Extends the existing EuiPageHeader passing through props like paddingSize and restrictWidth to match those of top-level props.

`EuiPageSection` as EuiPageTemplate.Section

Extends the existing EuiPageSection passing through props like paddingSize and restrictWidth to match those of top-level props. I also took the opportunity to fix the output of the class list of EuiPageSection.

`_EuiPageEmptyPrompt` as EuiPageTemplate.EmptyPrompt

This component basically just wraps an EuiEmptyPrompt with a EuiPageSection, extending the props of both. It does allow easily providing the body content as the children. The main piece here is that it will always center the prompt in the section and handles the configuration of how to display the page section vs empty prompt based on the panelled and color values.

eui/src/components/page_template/empty_prompt/page_empty_prompt.tsx

Lines 31 to 35 in ccfc902

    
             /** 
        
              * If panelled = true, then either the section or empty prompt must be plain; 
        
              * If color is anything but plain, then it must be the section that is plain; 
        
              * If panelled = true, but color is undefined, then default to the empty prompt being plain; 
        
              */

`_EuiPageBottomBar` as EuiPageTemplate.BottomBar

This component extends EuiBottomBar, but wraps the children in an EuiPageSection to allow restricting the width similar to the rest of the page contents and allowing the same paddingSize values.

Deprecations

The original EuiPageTemplate has been deprecated and renamed to EuiPageTemplateProps_Deprecated to reflect that. To continue using the deprecated version, consumers will need to change their import to:

@import { EuiPageTemplateProps_Deprecated as EuiPageTemplateProps } from '@elastic/eui';

Other fixes/additions

Fixed logicalStyle() to return the same value type as was passed in (instead of converting to string)
~~Added logicalUnit for vh and vw~~

Documentation

All of the old template docs have been deleted and re-written for the new component. They've also moved to their own docs folder page_template/. They no longer showcase a "custom" build vs "template" build because the template is fully customizable. The page components examples have been simplified in their organization.

I've updated any usage of the deprecated version in other docs files to use the new template version.

Todo

✅ A11y: Page section roles

Right now the struggle is not being able to contain a role="header" inside of a role="main" element, otherwise I could blanket change the inner components (the wrapper of all page contents) in a <main> element. But since EuiPageHeader renders as a <header> element, this breaks the nesting rule.

Checklist

Checked in both light and dark modes
Checked in mobile
Checked in Chrome, Safari, Edge, and Firefox
Props have proper autodocs and playground toggles
Added documentation
~~[ ] Checked Code Sandbox works for any docs examples~~
Added or updated jest and cypress tests
~~[ ] Checked for breaking changes and labeled appropriately~~
Checked for accessibility including keyboard-only and screenreader modes
Updated the Figma library counterpart
A changelog entry exists and is marked appropriately

Setup pattern for demo toggles

…tes/page_docs_toggles # Conflicts: # scripts/a11y-testing.js # src-docs/src/views/page/page_template_example.js # src-docs/src/views/panel/panel_example.js

…eature_page_templates/page_docs_toggles # Conflicts: # scripts/a11y-testing.js # src-docs/src/views/page/page_template_example.js # src-docs/src/views/panel/panel_example.js

- Removed nested page header styles when within EuiPageBody (improved way of doing this coming later)

…ough to examples

Still could use some cleanup

…page_now/page_docs_toggles

…ugh custom controls Update EuiPage’s example usage to use GuideSection directly

# Conflicts: # src-docs/src/views/page/page_example.js

and added EuiPageSidebar description to first example

…`demo`

…ge/template_demo_toggles

# Conflicts: # src-docs/src/views/page/page_simple.tsx # src-docs/src/views/page/page_template.tsx

kibanamachine · 2022-05-31T16:52:04Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

Co-authored-by: Elizabet Oliveira <elizabet.oliveira@elastic.co>

Doing so made it impossible to change things like centering contents. The guidance now is to always use a page component.

cchaos · 2022-05-31T17:12:48Z

Update: I've update the template to no longer auto-wrap non-namespaced children with a section element. I found this was causing trouble being able to create full-height layouts / custom layouts if you don't have access to the top template. Example was when I updated the 404 page.

kibanamachine · 2022-05-31T17:35:37Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

The multiple `main` elements cause errors, but we don’t want consumers to change these so we don’t want to change the copy/paste code.

…ge/template_demo_toggles

kibanamachine · 2022-05-31T18:44:24Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

kibanamachine · 2022-05-31T19:44:47Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

kibanamachine · 2022-05-31T21:09:25Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

miukimiu

Thanks, @cchaos for making the suggested changes.

I tested locally in Chrome, Safari, Edge, and Firefox LGMT! 🎉

cchaos · 2022-06-01T13:45:41Z

Jenkins, test this

kibanamachine · 2022-06-01T14:13:39Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

thompsongl

Code changes LGTM!

kibanamachine · 2022-06-01T18:29:17Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

cchaos · 2022-06-01T18:52:03Z

Thank you both!!

cchaos · 2022-06-01T18:52:50Z

I forgot about a changelog, so I'll add that real quick (even though its a feature branch) then merge

kibanamachine · 2022-06-01T19:27:06Z

Preview documentation changes for this PR: https://eui.elastic.co/pr_5905/

cchaos added 30 commits February 15, 2022 17:33

[Docs] Add EuiPage doc sections

3764894

Setup pattern for demo toggles

Added playground

d8e705c

Merge remote-tracking branch 'upstream/main' into feature_page_templa…

899453a

…tes/page_docs_toggles # Conflicts: # scripts/a11y-testing.js # src-docs/src/views/page/page_template_example.js # src-docs/src/views/panel/panel_example.js

Merge remote-tracking branch 'upstream/feature/page_templates' into f…

4d434e5

…eature_page_templates/page_docs_toggles # Conflicts: # scripts/a11y-testing.js # src-docs/src/views/page/page_template_example.js # src-docs/src/views/panel/panel_example.js

[Breaking] Changing padding defaults of EuiPage & EuiPageBody

4e99f0d

- Removed nested page header styles when within EuiPageBody (improved way of doing this coming later)

[NEW] EuiPageSection to replace EuiPageContent & EuiPageContentBody

cd2c512

[WIP] Added template toggle to Page Template examples

cb0f027

[WIP] Moar better Template toggles

6f69a87

[Messy but working] Passing pageHeader & optional sidebar props thr…

a1f7702

…ough to examples

Finalize new docs sections and best _demo setup

7c35ec1

Still could use some cleanup

Merge remote-tracking branch 'upstream/feature/page_templates' into _…

c305078

…page_now/page_docs_toggles

Added exampleToggles to GuideSectionExample for easily passing thro…

d5e031e

…ugh custom controls Update EuiPage’s example usage to use GuideSection directly

Merge branch '_page_now/page_docs_toggles' into _page_next/page_section

aa69b90

# Conflicts: # src-docs/src/views/page/page_example.js

Updating Page section to include Page body

b7dadc1

Updated PageSection to new format

0d79081

Added Page configurations section

fb2100d

and added EuiPageSidebar description to first example

Updates to table

032e084

Merge branch '_page_next/page_section' into _page/template_demo_toggles

0aa14e1

Converted all composed folder to .tsx

09cc6e3

Converted all template folder to .tsx

5a8b846

GuideSectionProps added fullScreen.showButton to hide button if no …

d667bc0

…`demo`

Using new GuideSection pattern for toggles template demos

1453090

Fixed up all the example sections

22c4404

Merge remote-tracking branch upstream/feature/page_templates into _pa…

e11d4e0

…ge/template_demo_toggles

Merge remote-tracking branch upstream/feature/page_templates into _pa…

b3b553a

…ge/template_demo_toggles

Duplicate whole page folder as page_template

038202d

Initial setup (with stubbed names) of neste component

a25c450

# Conflicts: # src-docs/src/views/page/page_simple.tsx # src-docs/src/views/page/page_template.tsx

Simplify EuiPage

62ae168

Rename new EuiPage to _EuiPageOuter and dont export

76ef833

Create _EuiPageSidebar that’s more easily configurable

730785b

cchaos and others added 5 commits May 31, 2022 13:01

Apply copy fixes from code review

cb9f581

Co-authored-by: Elizabet Oliveira <elizabet.oliveira@elastic.co>

Fixed docs 404 page (updated to use empty prompt pattern)

b5c4013

Removed auto-wrapping of non-namespaced children

baed5d9

Doing so made it impossible to change things like centering contents. The guidance now is to always use a page component.

More copy fixes

8e3cbae

Use document.body.dataset

ddd3b97

cchaos requested a review from miukimiu May 31, 2022 18:08

cchaos added 2 commits May 31, 2022 14:18

Skipping page template from a11y testing

3192538

The multiple `main` elements cause errors, but we don’t want consumers to change these so we don’t want to change the copy/paste code.

Merge remote-tracking branch upstream/feature/page_templates into _pa…

a6a2883

…ge/template_demo_toggles

Fixed usages of mixins from main

3c96ed3

refactor for ts error

ed037c8

miukimiu approved these changes Jun 1, 2022

View reviewed changes

thompsongl self-requested a review June 1, 2022 14:08

add missing comma

6807c12

thompsongl approved these changes Jun 1, 2022

View reviewed changes

cl

e91bb7d

cchaos merged commit 1cad3be into elastic:feature/page_templates Jun 1, 2022

cchaos deleted the _page/template_demo_toggles branch June 1, 2022 19:53

cchaos mentioned this pull request Aug 8, 2022

[Feature] EuiPage and EuiPageTemplate Updates #5768

Merged

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905

[Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905

cchaos commented May 17, 2022 •

edited

Loading

kibanamachine commented May 31, 2022

cchaos commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

miukimiu left a comment

cchaos commented Jun 1, 2022

kibanamachine commented Jun 1, 2022

thompsongl left a comment

kibanamachine commented Jun 1, 2022

cchaos commented Jun 1, 2022

cchaos commented Jun 1, 2022

kibanamachine commented Jun 1, 2022

	/**
	* If panelled = true, then either the section or empty prompt must be plain;
	* If color is anything but plain, then it must be the section that is plain;
	* If panelled = true, but color is undefined, then default to the empty prompt being plain;
	*/

[Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905

[Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905

Conversation

cchaos commented May 17, 2022 • edited Loading

New template components

EuiPageTemplate

_EuiPageOuter as the overall wrapping component

_EuiPageInner as the overall wrapping component for the main contents (not including sidebar)

_EuiPageSidebar as EuiPageTemplate.Sidebar

EuiPageHeader as EuiPageTemplate.Header

EuiPageSection as EuiPageTemplate.Section

_EuiPageEmptyPrompt as EuiPageTemplate.EmptyPrompt

_EuiPageBottomBar as EuiPageTemplate.BottomBar

Deprecations

Other fixes/additions

Documentation

Todo

✅ A11y: Page section roles

Checklist

kibanamachine commented May 31, 2022

cchaos commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

kibanamachine commented May 31, 2022

miukimiu left a comment

Choose a reason for hiding this comment

cchaos commented Jun 1, 2022

kibanamachine commented Jun 1, 2022

thompsongl left a comment

Choose a reason for hiding this comment

kibanamachine commented Jun 1, 2022

cchaos commented Jun 1, 2022

cchaos commented Jun 1, 2022

kibanamachine commented Jun 1, 2022

cchaos commented May 17, 2022 •

edited

Loading

`EuiPageTemplate`

`_EuiPageOuter` as the overall wrapping component

`_EuiPageInner` as the overall wrapping component for the main contents (not including sidebar)

`_EuiPageSidebar` as EuiPageTemplate.Sidebar

`EuiPageHeader` as EuiPageTemplate.Header

`EuiPageSection` as EuiPageTemplate.Section

`_EuiPageEmptyPrompt` as EuiPageTemplate.EmptyPrompt

`_EuiPageBottomBar` as EuiPageTemplate.BottomBar