@patternfly/quickstarts 2.2.2 → 2.3.0

package/src/QuickStartDrawer.tsx

@@ -0,0 +1,265 @@
+import './QuickStartDrawer.scss';
+import * as React from 'react';
+import { Drawer, DrawerContent, DrawerContentBody } from '@patternfly/react-core';
+import QuickStartCloseModal from './QuickStartCloseModal';
+import QuickStartPanelContent from './QuickStartPanelContent';
+import {
+  getDefaultQuickStartState,
+  QuickStartContext,
+  QuickStartContextValues,
+  useValuesForQuickStartContext,
+} from './utils/quick-start-context';
+import { QUICKSTART_ID_FILTER_KEY } from './utils/const';
+import { QuickStart, QuickStartStatus, AllQuickStartStates } from './utils/quick-start-types';
+import { getQuickStartByName } from './utils/quick-start-utils';
+
+export interface QuickStartContainerProps extends React.HTMLProps<HTMLDivElement> {
+  /** array of quick starts */
+  quickStarts: QuickStart[];
+  /** id of the currently active quick start */
+  activeQuickStartID: string;
+  /** setter for the active quick starts */
+  setActiveQuickStartID: React.Dispatch<React.SetStateAction<string>>;
+  /** quick starts state object */
+  allQuickStartStates: AllQuickStartStates;
+  /** setter for the quick starts state object */
+  setAllQuickStartStates: React.Dispatch<React.SetStateAction<AllQuickStartStates>>;
+  /** content to render within the container */
+  children?: React.ReactNode;
+  /** element to render the drawer panel into */
+  appendTo?: HTMLElement | (() => HTMLElement);
+  /** if true, the panel will take up the full browser width */
+  fullWidth?: boolean;
+  /** callback when an in-progress quick start is closed */
+  onCloseInProgress?: any;
+  /** callback when a not-in-progress quick start is closed */
+  onCloseNotInProgress?: any;
+  /** true to show footer buttons in the catalog tiles (default true) */
+  showCardFooters?: boolean;
+  /** true to use legacy drawer header variant colors */
+  useLegacyHeaderColors?: boolean;
+  /** text resources object */
+  resourceBundle?: any;
+  /** language of the current resource bundle
+   * Add custom strings: https://github.com/patternfly/patternfly-quickstarts/tree/main/packages/module#localization
+   */
+  language?: string;
+  /** if true, will show a loading spinner on the catalog page (default false) */
+  loading?: boolean;
+  /** if true, will update the browser URL with ?quickstart={ID} (default true) */
+  useQueryParams?: boolean;
+  /** if true, the TaskReview component, aka "Check your work", will be shown regardless of task status */
+  alwaysShowTaskReview?: boolean;
+  /**
+   * Additional markdown extensions and renderers to use
+   * Example usage: https://github.com/patternfly/patternfly-quickstarts/tree/main/packages/module#markdown-extensions
+   */
+  markdown?: {
+    extensions?: any[];
+    renderExtension?: (docContext: HTMLDocument, rootSelector: string) => React.ReactNode;
+  };
+  /** additional quick start context props */
+  contextProps?: QuickStartContextValues;
+}
+
+export const QuickStartContainer: React.FC<QuickStartContainerProps> = ({
+  quickStarts,
+  children,
+  activeQuickStartID,
+  allQuickStartStates,
+  setActiveQuickStartID,
+  setAllQuickStartStates,
+  appendTo,
+  fullWidth,
+  onCloseInProgress,
+  onCloseNotInProgress,
+  resourceBundle,
+  showCardFooters,
+  useLegacyHeaderColors,
+  language,
+  loading = false,
+  useQueryParams = true,
+  markdown,
+  contextProps,
+  alwaysShowTaskReview = true,
+  ...props
+}: QuickStartContainerProps) => {
+  const valuesForQuickstartContext: QuickStartContextValues = useValuesForQuickStartContext({
+    allQuickStarts: quickStarts,
+    activeQuickStartID,
+    setActiveQuickStartID,
+    allQuickStartStates,
+    setAllQuickStartStates,
+    footer: {
+      show: showCardFooters,
+    },
+    useLegacyHeaderColors,
+    language,
+    resourceBundle: {
+      ...resourceBundle,
+      // Start: "Let's go!",
+      // Continue: 'Resume',
+      // Restart: 'Start over',
+    },
+    loading,
+    useQueryParams,
+    markdown,
+    alwaysShowTaskReview,
+    ...contextProps,
+  });
+
+  React.useEffect(() => {
+    if (
+      quickStarts &&
+      JSON.stringify(quickStarts) !== JSON.stringify(valuesForQuickstartContext.allQuickStarts)
+    ) {
+      valuesForQuickstartContext.setAllQuickStarts(quickStarts);
+    }
+  }, [quickStarts, valuesForQuickstartContext]);
+
+  React.useEffect(() => {
+    if (loading !== valuesForQuickstartContext.loading) {
+      valuesForQuickstartContext.setLoading(loading);
+    }
+  }, [loading, valuesForQuickstartContext]);
+
+  const drawerProps = {
+    appendTo,
+    fullWidth,
+    onCloseInProgress,
+    onCloseNotInProgress,
+    ...props,
+  };
+
+  return (
+    <QuickStartContext.Provider value={valuesForQuickstartContext}>
+      <QuickStartDrawer {...drawerProps}>{children}</QuickStartDrawer>
+    </QuickStartContext.Provider>
+  );
+};
+
+export interface QuickStartDrawerProps extends React.HTMLProps<HTMLDivElement> {
+  quickStarts?: QuickStart[];
+  children?: React.ReactNode;
+  appendTo?: HTMLElement | (() => HTMLElement);
+  fullWidth?: boolean;
+  onCloseInProgress?: any;
+  onCloseNotInProgress?: any;
+}
+
+export const QuickStartDrawer: React.FC<QuickStartDrawerProps> = ({
+  quickStarts = [],
+  children,
+  appendTo,
+  fullWidth,
+  onCloseInProgress,
+  onCloseNotInProgress,
+  ...props
+}) => {
+  const {
+    activeQuickStartID,
+    setActiveQuickStart,
+    allQuickStarts = [],
+    activeQuickStartState,
+    allQuickStartStates,
+    setAllQuickStartStates,
+    useLegacyHeaderColors,
+  } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  const combinedQuickStarts = allQuickStarts.concat(quickStarts);
+  React.useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    // if there is a quick start param, but the quick start is not active, set it
+    // this can happen if a new browser session is opened or an incognito window for example
+    const quickStartIdFromParam = params.get(QUICKSTART_ID_FILTER_KEY) || '';
+    if (quickStartIdFromParam && activeQuickStartID !== quickStartIdFromParam) {
+      const activeQuickStart = getQuickStartByName(quickStartIdFromParam, combinedQuickStarts);
+      // don't try to load a quick start that is actually just an external resource (spec.link)
+      if (combinedQuickStarts.length > 0 && activeQuickStart && !activeQuickStart.spec.link) {
+        setActiveQuickStart(quickStartIdFromParam);
+      }
+    }
+  }, [activeQuickStartID, combinedQuickStarts, setActiveQuickStart]);
+
+  React.useEffect(() => {
+    // If activeQuickStartID was changed through prop from QuickStartContainer, need to init the state if it does not exist yet
+    if (activeQuickStartID && !allQuickStartStates[activeQuickStartID]) {
+      setAllQuickStartStates({
+        ...allQuickStartStates,
+        [activeQuickStartID]: getDefaultQuickStartState(),
+      });
+    }
+  }, [activeQuickStartID, allQuickStartStates, setAllQuickStartStates]);
+
+  const [modalOpen, setModalOpen] = React.useState<boolean>(false);
+  const activeQuickStartStatus = activeQuickStartState?.status;
+  const onClose = () => setActiveQuickStart('');
+  const handleClose = () => {
+    if (activeQuickStartStatus === QuickStartStatus.IN_PROGRESS) {
+      if (onCloseInProgress) {
+        onCloseInProgress();
+      } else {
+        setModalOpen(true);
+      }
+    } else if (onCloseNotInProgress) {
+      onCloseNotInProgress();
+    } else {
+      onClose();
+    }
+  };
+
+  const onModalConfirm = () => {
+    setModalOpen(false);
+    onClose();
+  };
+
+  const onModalCancel = () => setModalOpen(false);
+
+  const fullWidthPanelStyle = fullWidth
+    ? {
+        style: {
+          flex: 1,
+        },
+      }
+    : {};
+
+  const fullWidthBodyStyle = fullWidth
+    ? {
+        style: {
+          display: activeQuickStartID ? 'none' : 'flex',
+        },
+      }
+    : {};
+
+  const panelContent = (
+    <QuickStartPanelContent
+      quickStarts={combinedQuickStarts}
+      handleClose={handleClose}
+      activeQuickStartID={activeQuickStartID}
+      appendTo={appendTo}
+      isResizable={!fullWidth}
+      headerVariant={useLegacyHeaderColors ? '' : 'blue-white'}
+      {...fullWidthPanelStyle}
+    />
+  );
+
+  return (
+    <>
+      <Drawer isExpanded={!!activeQuickStartID} isInline {...props}>
+        {children ? (
+          <DrawerContent panelContent={panelContent} {...fullWidthBodyStyle}>
+            <DrawerContentBody className="pfext-quick-start-drawer__body">
+              {children}
+            </DrawerContentBody>
+          </DrawerContent>
+        ) : (
+          <div className="pf-c-drawer__main">{panelContent}</div>
+        )}
+      </Drawer>
+      <QuickStartCloseModal
+        isOpen={modalOpen}
+        onConfirm={onModalConfirm}
+        onCancel={onModalCancel}
+      />
+    </>
+  );
+};

package/src/QuickStartMarkdownView.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { SyncMarkdownView } from '@console/internal/components/markdown-view';
+import {
+  MarkdownCopyClipboard,
+  MarkdownHighlightExtension,
+  useInlineCopyClipboardShowdownExtension,
+  useMultilineCopyClipboardShowdownExtension,
+  useAdmonitionShowdownExtension,
+  useCodeShowdownExtension,
+} from '@console/shared';
+import { HIGHLIGHT_REGEXP } from '@console/shared/src/components/markdown-highlight-extension/highlight-consts';
+import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
+
+export const removeParagraphWrap = (markdown: string) => markdown.replace(/^<p>|<\/p>$/g, '');
+
+type QuickStartMarkdownViewProps = {
+  content: string;
+  exactHeight?: boolean;
+  className?: string;
+};
+
+const QuickStartMarkdownView: React.FC<QuickStartMarkdownViewProps> = ({
+  content,
+  exactHeight,
+  className,
+}) => {
+  const { markdown } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  const inlineCopyClipboardShowdownExtension = useInlineCopyClipboardShowdownExtension();
+  const multilineCopyClipboardShowdownExtension = useMultilineCopyClipboardShowdownExtension();
+  const admonitionShowdownExtension = useAdmonitionShowdownExtension();
+  const codeShowdownExtension = useCodeShowdownExtension();
+  return (
+    <SyncMarkdownView
+      inline
+      content={content}
+      exactHeight={exactHeight}
+      extensions={[
+        {
+          type: 'lang',
+          regex: HIGHLIGHT_REGEXP,
+          replace: (text: string, linkLabel: string, linkType: string, linkId: string): string => {
+            if (!linkLabel || !linkType || !linkId) {
+              return text;
+            }
+            return `<button class="pf-c-button pf-m-inline pf-m-link" data-highlight="${linkId}">${linkLabel}</button>`;
+          },
+        },
+        {
+          type: 'output',
+          filter: function(text) {
+            // check HTML for patterns like: <em>Status: unknown</em>{#extension-requirement-status}
+            // and replace with <em id="extension-requirement-status">Status: unknown</em>
+            return text.replace(/<em>(.*)<\/em>{#(.*)}/g, '<em id="$2">$1</em>');
+          },
+        },
+        inlineCopyClipboardShowdownExtension,
+        multilineCopyClipboardShowdownExtension,
+        admonitionShowdownExtension,
+        codeShowdownExtension,
+        ...(markdown ? markdown.extensions : []),
+      ]}
+      renderExtension={(docContext, rootSelector) => (
+        <>
+          <MarkdownHighlightExtension docContext={docContext} rootSelector={rootSelector} />
+          <MarkdownCopyClipboard docContext={docContext} rootSelector={rootSelector} />
+          {markdown &&
+            markdown.renderExtension &&
+            markdown.renderExtension(docContext, rootSelector)}
+        </>
+      )}
+      className={className}
+    />
+  );
+};
+export default QuickStartMarkdownView;

package/src/QuickStartPanelContent.scss

@@ -0,0 +1,46 @@
+.pfext-quick-start-panel-content {
+  &__header {
+    position: sticky;
+    top: 0px;
+    background: inherit;
+    z-index: var(--pf-global--ZIndex--xs);
+    &__shadow {
+      box-shadow: var(--pf-global--BoxShadow--sm-bottom);
+    }
+    &--blue-white {
+      background-color: var(--pf-global--palette--blue-400);
+      .pfext-quick-start-panel-content__title {
+        color: var(--pf-global--Color--light-100);
+      }
+      .pfext-quick-start-panel-content__duration {
+        color: var(--pf-global--Color--light-200);
+      }
+      .pfext-quick-start-panel-content__close-button {
+        button {
+          color: var(--pf-global--Color--light-100) !important;
+        }
+      }
+    }
+  }
+  &__body {
+    display: flex;
+    flex-direction: column;
+  }
+  &__title {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+  }
+  &__duration {
+    display: inline-block;
+    font-size: var(--pf-global--FontSize--md);
+    font-weight: 400;
+    line-height: 1;
+    color: #9c9c9c;
+  }
+  &__footer {
+    &__shadow {
+      box-shadow: var(--pf-global--BoxShadow--sm-top);
+    }
+  }
+}

package/src/QuickStartPanelContent.tsx

@@ -0,0 +1,153 @@
+import './QuickStartPanelContent.scss';
+import * as React from 'react';
+import {
+  DrawerActions,
+  DrawerCloseButton,
+  DrawerHead,
+  DrawerPanelBody,
+  DrawerPanelContent,
+  Title,
+} from '@patternfly/react-core';
+import { css } from '@patternfly/react-styles';
+import * as ReactDOM from 'react-dom';
+import { Shadows, useScrollShadows } from '@console/shared';
+import QuickStartController from './QuickStartController';
+import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
+import { QuickStart } from './utils/quick-start-types';
+import { camelize } from './utils/quick-start-utils';
+
+type HandleClose = () => void;
+
+type QuickStartPanelContentProps = {
+  quickStarts: QuickStart[];
+  activeQuickStartID: string;
+  handleClose: HandleClose;
+  appendTo?: HTMLElement | (() => HTMLElement);
+  isResizable?: boolean;
+  showClose?: boolean;
+  headerVariant?: '' | 'blue-white';
+};
+
+const getElement = (appendTo: HTMLElement | (() => HTMLElement)) => {
+  if (typeof appendTo === 'function') {
+    return appendTo();
+  }
+  return appendTo;
+};
+
+const useScrollTopOnTaskNumberChange = (node: HTMLElement, taskNumber: number): void => {
+  React.useEffect(() => {
+    if (node) {
+      node.scrollTo({ top: 0, behavior: 'smooth' });
+    }
+  }, [taskNumber, node]);
+};
+
+const QuickStartPanelContent: React.FC<QuickStartPanelContentProps> = ({
+  quickStarts = [],
+  handleClose,
+  activeQuickStartID,
+  appendTo,
+  isResizable = true,
+  showClose = true,
+  headerVariant = '',
+  ...props
+}) => {
+  const { getResource, activeQuickStartState } = React.useContext<QuickStartContextValues>(
+    QuickStartContext,
+  );
+  const [contentRef, setContentRef] = React.useState<HTMLDivElement>();
+  const shadows = useScrollShadows(contentRef);
+  const quickStart = quickStarts.find((qs) => qs.metadata.name === activeQuickStartID);
+  const taskNumber = activeQuickStartState?.taskNumber;
+  useScrollTopOnTaskNumberChange(contentRef, taskNumber as number);
+  const nextQuickStarts: QuickStart[] = quickStarts.filter((qs: QuickStart) =>
+    quickStart?.spec.nextQuickStart?.includes(qs.metadata.name),
+  );
+
+  const headerClasses = css('pfext-quick-start-panel-content__header', {
+    'pfext-quick-start-panel-content__header__shadow':
+      shadows === Shadows.top || shadows === Shadows.both,
+    'pfext-quick-start-panel-content__header--blue-white': headerVariant === 'blue-white',
+  });
+
+  const footerClass = css({
+    'pfext-quick-start-panel-content__footer__shadow':
+      shadows === Shadows.bottom || shadows === Shadows.both,
+  });
+
+  const getStep = () => {
+    const tasks = quickStart.spec.tasks.length;
+    if (Number.parseInt(taskNumber as string, 10) === -1) {
+      return 'intro';
+    }
+    if (Number.parseInt(taskNumber as string, 10) === tasks) {
+      return 'conclusion';
+    }
+    return Number.parseInt(taskNumber as string, 10) + 1;
+  };
+
+  const content = quickStart ? (
+    <DrawerPanelContent
+      isResizable={isResizable}
+      className="pfext-quick-start__base"
+      data-testid={`qs-drawer-${camelize(quickStart.spec.displayName)}`}
+      data-qs={`qs-step-${getStep()}`}
+      data-test="quickstart drawer"
+      {...props}
+    >
+      <div className={headerClasses}>
+        <DrawerHead>
+          <div className="pfext-quick-start-panel-content__title">
+            <Title
+              headingLevel="h1"
+              size="xl"
+              className="pfext-quick-start-panel-content__name"
+              style={{ marginRight: 'var(--pf-global--spacer--md)' }}
+            >
+              {quickStart?.spec.displayName}{' '}
+              <small className="pfext-quick-start-panel-content__duration">
+                {quickStart?.spec.durationMinutes
+                  ? getResource(
+                      '{{type}} • {{duration, number}} minutes',
+                      quickStart?.spec.durationMinutes,
+                    )
+                      .replace('{{duration, number}}', quickStart?.spec.durationMinutes)
+                      .replace('{{type}}', getResource('Type'))
+                  : getResource('Type')}
+              </small>
+            </Title>
+          </div>
+          {showClose && (
+            <DrawerActions>
+              <DrawerCloseButton
+                onClick={handleClose}
+                className="pfext-quick-start-panel-content__close-button"
+                data-testid="qs-drawer-close"
+              />
+            </DrawerActions>
+          )}
+        </DrawerHead>
+      </div>
+      <DrawerPanelBody
+        hasNoPadding
+        className="pfext-quick-start-panel-content__body"
+        data-test="content"
+      >
+        <QuickStartController
+          quickStart={quickStart}
+          nextQuickStarts={nextQuickStarts}
+          footerClass={footerClass}
+          contentRef={setContentRef}
+        />
+      </DrawerPanelBody>
+    </DrawerPanelContent>
+  ) : null;
+
+  if (appendTo) {
+    return ReactDOM.createPortal(content, getElement(appendTo));
+  }
+  return content;
+};
+
+export default QuickStartPanelContent;

package/src/__tests__/quick-start-utils.spec.tsx

@@ -0,0 +1,16 @@
+import { allQuickStarts } from '../data/quick-start-test-data';
+import { getQuickStartByName, isDisabledQuickStart } from '../utils/quick-start-utils';
+
+describe('quick-start-utils', () => {
+  it('should return the quick start corresponding to the id for getQuickStartByName function', () => {
+    const mockID = allQuickStarts[0].metadata.name;
+    const quickStart = getQuickStartByName(mockID, allQuickStarts);
+    expect(quickStart.metadata.name === mockID).toBe(true);
+  });
+
+  it('should filter out disabled quick starts', () => {
+    const disabledQuickStarts = [allQuickStarts[0].metadata.name]; // setting allQuickStart[0] as disabled
+    expect(isDisabledQuickStart(allQuickStarts[1], disabledQuickStarts)).toBe(false);
+    expect(isDisabledQuickStart(allQuickStarts[0], disabledQuickStarts)).toBe(true);
+  });
+});

package/src/catalog/Catalog/QuickStartCatalogHeader.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+export type QuickStartCatalogHeaderProps = {
+  title: string;
+  hint?: string;
+};
+
+export const QuickStartCatalogHeader: React.FC<QuickStartCatalogHeaderProps> = ({
+  title,
+  hint,
+}) => (
+  <div className="pfext-page-layout__header">
+    <h1 data-pf-content="true" className="pfext-page-layout__title">
+      {title}
+    </h1>
+    {hint && <div className="pfext-page-layout__hint">{hint}</div>}
+  </div>
+);

package/src/catalog/Catalog/QuickStartCatalogSection.tsx

@@ -0,0 +1,9 @@
+import * as React from 'react';
+
+export type QuickStartCatalogSectionProps = {
+  children: React.ReactNode;
+};
+
+export const QuickStartCatalogSection: React.FC<QuickStartCatalogSectionProps> = ({ children }) => (
+  <div className="pfext-page-layout__content">{children}</div>
+);

package/src/catalog/Catalog/QuickStartCatalogToolbar.tsx

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import { Toolbar } from '@patternfly/react-core';
+
+export type QuickStartCatalogToolbarProps = {
+  children: React.ReactNode;
+};
+
+export const QuickStartCatalogToolbar: React.FC<QuickStartCatalogToolbarProps> = ({ children }) => (
+  <Toolbar usePageInsets className="pfext-quick-start-catalog-filter__flex">
+    {children}
+  </Toolbar>
+);

package/src/catalog/Catalog/index.ts

@@ -0,0 +1,3 @@
+export * from './QuickStartCatalogHeader';
+export * from './QuickStartCatalogSection';
+export * from './QuickStartCatalogToolbar';

package/src/catalog/QuickStartCatalog.scss

@@ -0,0 +1,8 @@
+.pfext-quick-start-catalog {
+  &__gallery {
+    --pf-l-gallery--GridTemplateColumns: repeat(auto-fill, 300px) !important;
+  }
+  &__gallery-item {
+    display: inherit !important;
+  }
+}

package/src/catalog/QuickStartCatalog.tsx

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import { Gallery, GalleryItem } from '@patternfly/react-core';
+import { QuickStartContext, QuickStartContextValues } from '../utils/quick-start-context';
+import { QuickStart } from '../utils/quick-start-types';
+import { getQuickStartStatus } from '../utils/quick-start-utils';
+import QuickStartTile from './QuickStartTile';
+
+import './QuickStartCatalog.scss';
+
+type QuickStartCatalogProps = {
+  quickStarts: QuickStart[];
+};
+
+const QuickStartCatalog: React.FC<QuickStartCatalogProps> = ({ quickStarts }) => {
+  const { activeQuickStartID, allQuickStartStates } = React.useContext<QuickStartContextValues>(
+    QuickStartContext,
+  );
+
+  return (
+    <div className="pfext-page-layout__content">
+      <Gallery className="pfext-quick-start-catalog__gallery" hasGutter>
+        {quickStarts.map((quickStart) => {
+          const {
+            metadata: { name: id },
+          } = quickStart;
+
+          return (
+            <GalleryItem key={id} className="pfext-quick-start-catalog__gallery-item">
+              <QuickStartTile
+                quickStart={quickStart}
+                isActive={id === activeQuickStartID}
+                status={getQuickStartStatus(allQuickStartStates, id)}
+              />
+            </GalleryItem>
+          );
+        })}
+      </Gallery>
+    </div>
+  );
+};
+
+export default QuickStartCatalog;

package/src/catalog/QuickStartTile.scss

@@ -0,0 +1,11 @@
+.pfext-quick-start-tile {
+  height: 100%;
+  & .catalog-tile-pf-description .has-footer {
+    display: block;
+    -webkit-line-clamp: unset;
+  }
+
+  & .catalog-tile-pf-icon {
+    display: flex;
+  }
+}