[Feature] EuiPage and EuiPageTemplate Updates

scripts/a11y-testing.js

@@ -5,7 +5,8 @@ const { AxePuppeteer } = require('@axe-core/puppeteer');
 const docsPages = async (root, page) => {
   const pagesToSkip = [
     `${root}#/display/aspect-ratio`, // Has issues with the embedded audio player
-    `${root}#/layout/accordion` // Has an issue with ARIA attributes
+    `${root}#/layout/accordion`, // Has an issue with ARIA attributes
+    `${root}#/templates/page-template` // Has multiple `main` elements that we don't want to remove for bad copy/paste code
   ];
 
   return [

src-docs/src/components/guide_page/_guide_page.scss

@@ -1,26 +1,15 @@
 @import '../../../../src/global_styling/mixins/helpers';
 
-$guideSideNavWidth: 240px;
-
-#guide { // sass-lint:disable-line no-ids
-  display: flex;
-  flex-direction: column;
-  min-height: 100vh;
+@include euiHeaderAffordForFixed;
 
-  .euiBody--headerIsFixed & {
-    min-height: calc(100vh - #{$euiHeaderHeightCompensation});
-  }
+.guideBody {
+  // Override euiHeaderAffordForFixed mixin since the page template handles this now
+  padding-top: 0 !important; // sass-lint:disable-line no-important
 }
 
-@include euiHeaderAffordForFixed;
-
 .euiBody--headerIsFixed--double {
   @include euiHeaderAffordForFixed($euiHeaderHeightCompensation * 2);
 
-  #guide { // sass-lint:disable-line no-ids
-    min-height: calc(100vh - #{$euiHeaderHeightCompensation * 2});
-  }
-
   .euiHeader:not(.euiHeader--fixed) {
     // Force headers below the fullscreen.
     // This shouldn't be necessary in consuming applications because headers should always be at the top of the page

src-docs/src/components/guide_page/guide_page_chrome.js

@@ -6,7 +6,6 @@ import {
   EuiFlexGroup,
   EuiFlexItem,
   EuiSideNav,
-  EuiPageSideBar,
   EuiText,
 } from '../../../../src/components';
 
@@ -252,31 +251,29 @@ export class GuidePageChrome extends Component {
     }
 
     return (
-      <EuiPageSideBar className="guideSideNav" sticky>
-        <EuiFlexGroup
-          style={{ height: '100%' }}
-          direction="column"
-          responsive={false}
-          gutterSize="none"
+      <EuiFlexGroup
+        style={{ height: '100%' }}
+        direction="column"
+        responsive={false}
+        gutterSize="none"
+      >
+        <EuiFlexItem
+          role="search"
+          grow={false}
+          className="guideSideNav__search"
         >
-          <EuiFlexItem
-            role="search"
-            grow={false}
-            className="guideSideNav__search"
-          >
-            <EuiFieldSearch
-              fullWidth
-              placeholder="Search"
-              value={this.state.search}
-              onChange={this.onSearchChange}
-              aria-label="Search for a docs section"
-            />
-          </EuiFlexItem>
-          <EuiFlexItem className="guideSideNav__content">
-            {sideNavContent}
-          </EuiFlexItem>
-        </EuiFlexGroup>
-      </EuiPageSideBar>
+          <EuiFieldSearch
+            fullWidth
+            placeholder="Search"
+            value={this.state.search}
+            onChange={this.onSearchChange}
+            aria-label="Search for a docs section"
+          />
+        </EuiFlexItem>
+        <EuiFlexItem className="guideSideNav__content">
+          {sideNavContent}
+        </EuiFlexItem>
+      </EuiFlexGroup>
     );
   }
 }

src-docs/src/components/guide_page/guide_page_header.tsx

@@ -132,21 +132,21 @@ export const GuidePageHeader: React.FunctionComponent<GuidePageHeaderProps> = ({
       ];
 
   return (
-    <EuiHeader
-      role="region"
-      aria-label="EUI Docs app bar"
-      position="fixed"
-      theme="dark"
-      sections={[
-        {
-          items: [renderLogo(), renderVersion()],
-          borders: 'none',
-        },
-        {
-          items: rightSideItems,
-          borders: 'none',
-        },
-      ]}
-    />
+    <header aria-label="EUI Docs app bar">
+      <EuiHeader
+        position="fixed"
+        theme="dark"
+        sections={[
+          {
+            items: [renderLogo(), renderVersion()],
+            borders: 'none',
+          },
+          {
+            items: rightSideItems,
+            borders: 'none',
+          },
+        ]}
+      />
+    </header>
   );
 };

src-docs/src/components/guide_section/_utils.js

@@ -41,8 +41,15 @@ export const renderJsSourceCode = (code) => {
     // [\r\n]                  - match end of line, so the extra new line is removed via the replace operation
     /import {([^}]+)} from '@elastic\/eui';[\r\n]/g,
     (match, imports) => {
-      // remove all characters that aren't letters, numbers, or underscores from the imports
-      const namedImports = imports.match(/[a-zA-Z0-9_]+/g);
+      // Finds any word (\b\w+\b) that
+      // (?<!as\s)             - is not preceded by `as `
+      // (?!(\bas\b))          - and is not the word `as`
+      // (?!\sas)              - and is not followed by ` as`
+      // |                     - or
+      // \w+\sas\s\w+          - find any group of words that conform to the alias import pattern (`Thing as OtherThing`)
+      const namedImports = imports.match(
+        /(?<!as\s)(?!(\bas\b))(\b\w+\b)(?!\sas)|\w+\sas\s\w+/g
+      );
       elasticImports.push(...namedImports);
       return '';
     }

src-docs/src/components/guide_section/_utils.test.js

@@ -74,6 +74,22 @@ describe('renderJsSourceCode', () => {
           export default () => 'Hello world!';`)
       );
     });
+
+    it('handles aliased imports', () => {
+      expect(
+        renderJsSourceCode({
+          default: dedent(`
+            import { EuiPageTemplate_Deprecated as EuiPageTemplate } from '@elastic/eui';
+
+            export default () => 'Hello world!';`),
+        })
+      ).toEqual(
+        dedent(`
+          import { EuiPageTemplate_Deprecated as EuiPageTemplate } from '@elastic/eui';
+
+          export default () => 'Hello world!';`)
+      );
+    });
   });
 
   describe('React import', () => {

src-docs/src/components/guide_section/guide_section.tsx

@@ -7,9 +7,8 @@ import {
   EuiButton,
   EuiButtonEmpty,
   EuiFlyout,
-  EuiPageContentBody,
-  EuiPanel,
   EuiPanelProps,
+  EuiPageSection,
   CommonProps,
   useIsWithinBreakpoints,
 } from '../../../../src';
@@ -27,7 +26,12 @@ import {
 } from './guide_section_parts/guide_section_tabs';
 import classNames from 'classnames';
 
-export interface GuideSection extends CommonProps {
+export interface GuideSectionProps
+  extends CommonProps,
+    Pick<
+      GuideSectionExample,
+      'exampleToggles' | 'demoPanelProps' | 'ghostBackground'
+    > {
   id?: string;
   title?: string;
   text?: ReactNode;
@@ -36,15 +40,15 @@ export interface GuideSection extends CommonProps {
   fullScreen?: {
     slug: string;
     demo: ReactNode;
+    showButton?: boolean;
   };
-  demoPanelProps?: GuideSectionExample['demoPanelProps'];
   props?: object;
   playground?: any;
-  ghostBackground?: boolean;
   wrapText?: boolean;
   snippet?: string | string[];
   color?: EuiPanelProps['color'];
   children?: ReactNode;
+  nested?: boolean;
 }
 
 export const GuideSectionCodeTypesMap = {
@@ -74,7 +78,7 @@ export const GuideSectionCodeTypesMap = {
   },
 };
 
-export const GuideSection: FunctionComponent<GuideSection> = ({
+export const GuideSection: FunctionComponent<GuideSectionProps> = ({
   id,
   title,
   text,
@@ -86,9 +90,11 @@ export const GuideSection: FunctionComponent<GuideSection> = ({
   ghostBackground,
   wrapText = true,
   demoPanelProps,
+  exampleToggles,
   snippet,
   color,
   children,
+  nested,
   className,
 }) => {
   const { path } = useRouteMatch();
@@ -138,10 +144,12 @@ export const GuideSection: FunctionComponent<GuideSection> = ({
       });
     }
 
-    return tabs.length ? (
+    const playgroundToggle = renderPlaygroundToggle();
+
+    return tabs.length || playgroundToggle ? (
       <GuideSectionExampleTabs
         tabs={tabs}
-        rightSideControl={renderPlaygroundToggle()}
+        rightSideControl={playgroundToggle}
       />
     ) : undefined;
   };
@@ -188,62 +196,60 @@ export const GuideSection: FunctionComponent<GuideSection> = ({
   };
 
   return (
-    <EuiPanel
+    <EuiPageSection
       id={id}
       className={classNames('guideSection', className)}
       color={!isLargeBreakpoint ? 'transparent' : color || 'transparent'}
-      borderRadius="none"
-      paddingSize="l"
-      grow={false}
+      paddingSize={nested ? 'none' : 'l'}
+      restrictWidth
     >
       <EuiSpacer size={(color || title) && isLargeBreakpoint ? 'xxl' : 'xs'} />
-      <EuiPageContentBody restrictWidth>
-        <GuideSectionExampleText title={title} wrapText={wrapText}>
-          {text}
-        </GuideSectionExampleText>
-
-        {renderingPlayground && (
-          <EuiFlyout
-            onClose={() => setRenderingPlayground(false)}
-            size="l"
-            paddingSize="none"
-            closeButtonPosition="outside"
-          >
-            {renderPlayground()}
-          </EuiFlyout>
-        )}
-        {(demo || fullScreen) && (
-          <>
-            {text && <EuiSpacer />}
-            <GuideSectionExample
-              example={
-                <EuiErrorBoundary>
-                  {/* eslint-disable-next-line no-nested-ternary */}
-                  {fullScreen == null ? (
-                    <div>{demo}</div>
-                  ) : demo == null ? (
-                    <EuiButton
-                      fill
-                      iconType="fullScreen"
-                      href={`#${path}/${fullScreen.slug}`}
-                    >
-                      Fullscreen demo
-                    </EuiButton>
-                  ) : (
-                    demo
-                  )}
-                </EuiErrorBoundary>
-              }
-              tabs={renderTabs()}
-              ghostBackground={ghostBackground}
-              demoPanelProps={demoPanelProps}
-            />
-          </>
-        )}
-
-        {children}
-        <EuiSpacer size={color && isLargeBreakpoint ? 'xxl' : 'xs'} />
-      </EuiPageContentBody>
-    </EuiPanel>
+      <GuideSectionExampleText title={title} wrapText={wrapText}>
+        {text}
+      </GuideSectionExampleText>
+
+      {renderingPlayground && (
+        <EuiFlyout
+          onClose={() => setRenderingPlayground(false)}
+          size="l"
+          paddingSize="none"
+          closeButtonPosition="outside"
+        >
+          {renderPlayground()}
+        </EuiFlyout>
+      )}
+      {(demo || (fullScreen && fullScreen.showButton !== false)) && (
+        <>
+          {(nested || text) && <EuiSpacer />}
+          <GuideSectionExample
+            example={
+              <EuiErrorBoundary>
+                {/* eslint-disable-next-line no-nested-ternary */}
+                {fullScreen == null ? (
+                  <div>{demo}</div>
+                ) : demo == null ? (
+                  <EuiButton
+                    fill
+                    iconType="fullScreen"
+                    href={`#${path}/${fullScreen.slug}`}
+                  >
+                    Fullscreen demo
+                  </EuiButton>
+                ) : (
+                  demo
+                )}
+              </EuiErrorBoundary>
+            }
+            tabs={renderTabs()}
+            ghostBackground={ghostBackground}
+            demoPanelProps={demoPanelProps}
+            exampleToggles={exampleToggles}
+          />
+        </>
+      )}
+
+      {children}
+      <EuiSpacer size={color && isLargeBreakpoint ? 'xxl' : 'xs'} />
+    </EuiPageSection>
   );
 };