[Feature] EuiPage and EuiPageTemplate Updates

[cchaos]

Justification for new template structure

While implementing the original EuiPageTemplate in Kibana, we realized that it is very rigid and doesn't allow for certain configurations like:

• Prepending page contents before the page header
• Allowing full-width content areas
• Providing page header and other prop-based content outside of an actual propagated prop on the template component

This new template is based on React context to pass through unified props like paddingSize and restrictWidth while still be configurable at every level. It also removes the necessity to provide page header contents through props. It is also built as a namespaced component and therefore the context will only be passed to those that are namespaced in case of complete custom layouts.

The best way to justify is to showcase the new capabilities. Take the following layout which couldn't be achieved by the previous version of EuiPageTemplate and would need to be completely custom contents that would then no longer be tied to cascading props:

Now you can easily achieve this with the following setup:

<EuiPageTemplate bottomBorder="extended">
  {/* Sidebar content can now be instantiated anywhere and it will always be placed in the correct spot */}
  <EuiPageTemplate.Sidebar>{sidebar}</EuiPageTemplate.Sidebar>
  {/* This non-namespaced section will not be tied to the template ensuring it's display is always custom */}
  <EuiPageSection color="subdued">
    Some content before the page header
  </EuiPageSection>
  {/* Display a page header anywhere in the stack of contents */}
  <EuiPageTemplate.Header {...header} />
  {/* This template section overrides some default template props */}
  <EuiPageTemplate.Section grow={false} bottomBorder="extended">
    Some content after the page header
  </EuiPageTemplate.Section>
  {/* Empty prompts can be placed anywhere in the stack and not replace the entire page contents */}
  <EuiPageTemplate.EmptyPrompt title={<span>No spice</span>}>
    {emptyPrompt}
  </EuiPageTemplate.EmptyPrompt>
</EuiPageTemplate>

Based solely on the presence of a fixed EuiHeader, the template will also ensure the layout affords for this offset without needing to apply custom styles and use of a Sass mixin.

More example conversions to the new EuiPageTemplate

`template = default` with sidebar and a bottom bar

<EuiPageTemplate>
  <EuiPageTemplate.Sidebar>{sidebar}</EuiPageTemplate.Sidebar>
  <EuiPageTemplate.Header {...header} />
  <EuiPageTemplate.Section>{content}</EuiPageTemplate.Section>
  <EuiPageTemplate.BottomBar>{bottomBar}</EuiPageTemplate.BottomBar>
</EuiPageTemplate>

`template = centeredBody`

<EuiPageTemplate>
  <EuiPageTemplate.EmptyPrompt title={<span>No spice</span>}>
    {emptyPrompt}
  </EuiPageTemplate.EmptyPrompt>
</EuiPageTemplate>

`template = centeredContent` with sidebar

<EuiPageTemplate>
  <EuiPageTemplate.Sidebar>{sidebar}</EuiPageTemplate.Sidebar>
  <EuiPageTemplate.Header {...header} />
  <EuiPageTemplate.EmptyPrompt title={<span>No spice</span>}>
    {emptyPrompt}
  </EuiPageTemplate.EmptyPrompt>
</EuiPageTemplate>

`template = empty` (no content panelling)

{/* The default for `bottomBorder` is `extended` */}
<EuiPageTemplate panelled={false} bottomBorder={true}>
  <EuiPageTemplate.Header {...header} rightSideItems={[button]} />
  <EuiPageTemplate.Section>
    <EuiFlexGrid columns={2}>
      <EuiFlexItem>
        <EuiPanel style={{ height: 200 }} />
      </EuiFlexItem>
      <EuiFlexItem>
        <EuiPanel style={{ height: 200 }} />
      </EuiFlexItem>
      <EuiFlexItem>
        <EuiPanel style={{ height: 200 }} />
      </EuiFlexItem>
      <EuiFlexItem>
        <EuiPanel style={{ height: 200 }} />
      </EuiFlexItem>
    </EuiFlexGrid>
  </EuiPageTemplate.Section>
</EuiPageTemplate>

PR Summaries:

• [EuiPageTemplate Feature] [Docs] Create new section for “Templates” #5625
• [Page Templates Feature] EuiPage docs & toggles #5662
• [Page Templates Feature] Added EuiPageSection and updated EuiPage & EuiPageBody padding defaults #5769
  • Removed nested page header styles when within EuiPageBody (improved way of doing this coming later)
  • [NEW] EuiPageSection to replace EuiPageContent & EuiPageContentBody
  • Added exampleToggles to GuideSectionExample for easily passing through custom controls
  • Added euiPaddingStyles and euiBackgroundColorStyles global styling functions
  • Added deprecation comments to EuiPageContent and EuiPageContentBody
• [Page Template Feature] Updating EuiPageHeader to use the same paradigm as EuiPageSection #5857
  • Refactored to support same bottomBorder, restrictWidth and paddingSize props as EuiPageSection
  • Converted EuiPageHeaderContent to Emotion
  • Consolidate more styles including ensuring max-width is applied as style tag
• [Into Feature] New EuiPageTemplate as namespaced component for versatile stacking #5905
  • New EuiPageTemplate as a namespaced component
  • Deprecated old EuiPageTemplate as EuiPageTemplate_Deprecated
• [Final Feature PR] Convert to remaining page components to Emotion #5948
  • Converted EuiPageBody to Emotion
  • Deprecated all EuiPageContent components
  • Converted EuiPage to Emotion
  • Deprecated EuiPageSideBar and rename to EuiPageSideBar_Deprecated and moved new EuiPageSidebar to /page and export
  • Fixed restrictWidth styles of EuiPageContentBody
• [Feature] Converting EuiPageTemplate to use ReactContext instead of cloneChildren #5987
• [EuiPageTemplates] Some fixes for BWC #6015
  • Fixed Deprecated template’s header spacing and added docs section
  • Fixed sizing and overflow of EuiPageSidebar
    • Added height as optional prop to all euiYScroll mixins
  • [EuiPageSection] Fixed restrictWidth prop to render as style
  • [EuiPageBottomBar] Fix overflow and padding allowance
  • [EuiPageSection] Logical styles
  • Fixes from main update
    • Adds mainProps to EuiPageTemplate for allowing customization of things like id (for skip link)
  • update import replacer regex to account for aliased imports

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[kibanamachine]

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

[chandlerprall]

🚀

[cchaos]

[kibanamachine]

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