@patternfly/quickstarts 0.0.0

package/src/QuickStartCatalogPage.tsx

@@ -0,0 +1,195 @@
+import * as React from 'react';
+import {
+  Button,
+  Divider,
+  EmptyState,
+  EmptyStateBody,
+  EmptyStateIcon,
+  Text,
+  EmptyStateFooter,
+  EmptyStateActions,
+  EmptyStateHeader,
+} from '@patternfly/react-core';
+import SearchIcon from '@patternfly/react-icons/dist/js/icons/search-icon';
+import { EmptyBox, LoadingBox, clearFilterParams } from '@console/internal/components/utils';
+import QuickStartCatalog from './catalog/QuickStartCatalog';
+import QuickStartCatalogFilter from './catalog/Toolbar/QuickStartCatalogFilter';
+import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
+import { QuickStart } from './utils/quick-start-types';
+import { filterQuickStarts } from './utils/quick-start-utils';
+
+export interface QuickStartCatalogPageProps {
+  quickStarts?: QuickStart[];
+  showFilter?: boolean;
+  sortFnc?: (q1: QuickStart, q2: QuickStart) => number;
+  title?: string;
+  hint?: string;
+  showTitle?: boolean;
+}
+
+export const QuickStartCatalogEmptyState = ({ clearFilters }) => {
+  const { getResource } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  return (
+    <EmptyState>
+      <EmptyStateHeader
+        titleText={<>{getResource('No results found')}</>}
+        icon={<EmptyStateIcon icon={SearchIcon} />}
+        headingLevel="h4"
+      />
+      <EmptyStateBody>
+        {getResource(
+          'No results match the filter criteria. Remove filters or clear all filters to show results.',
+        )}
+      </EmptyStateBody>
+
+      <EmptyStateFooter>
+        <EmptyStateActions>
+          <Button variant="link" onClick={clearFilters} data-test="clear-filter button">
+            {getResource('Clear all filters')}
+          </Button>
+        </EmptyStateActions>
+      </EmptyStateFooter>
+    </EmptyState>
+  );
+};
+
+export const QuickStartCatalogPage: React.FC<QuickStartCatalogPageProps> = ({
+  quickStarts,
+  showFilter,
+  sortFnc = (q1, q2) => q1.spec.displayName.localeCompare(q2.spec.displayName),
+  title,
+  hint,
+  showTitle = true,
+}) => {
+  const sortFncCallback = React.useCallback(sortFnc, [sortFnc]);
+  const {
+    allQuickStarts = [],
+    setAllQuickStarts,
+    allQuickStartStates,
+    getResource,
+    filter,
+    setFilter,
+    loading,
+  } = React.useContext<QuickStartContextValues>(QuickStartContext);
+
+  React.useEffect(() => {
+    // passed through prop, not context
+    if (quickStarts && JSON.stringify(quickStarts) !== JSON.stringify(allQuickStarts)) {
+      setAllQuickStarts(quickStarts);
+    }
+  }, [quickStarts, allQuickStarts, setAllQuickStarts]);
+
+  const initialFilteredQuickStarts = showFilter
+    ? filterQuickStarts(
+        allQuickStarts,
+        filter.keyword,
+        filter.status.statusFilters,
+        allQuickStartStates,
+      ).sort(sortFncCallback)
+    : allQuickStarts;
+
+  const [filteredQuickStarts, setFilteredQuickStarts] = React.useState(initialFilteredQuickStarts);
+  React.useEffect(() => {
+    const filteredQs = showFilter
+      ? filterQuickStarts(
+          allQuickStarts,
+          filter.keyword,
+          filter.status.statusFilters,
+          allQuickStartStates,
+        ).sort(sortFncCallback)
+      : allQuickStarts;
+    // also needs a check whether the content of the QS changed
+    if (
+      filteredQs.length !== filteredQuickStarts.length ||
+      JSON.stringify(filteredQs) !== JSON.stringify(filteredQuickStarts)
+    ) {
+      setFilteredQuickStarts(filteredQs);
+    }
+  }, [
+    allQuickStarts,
+    allQuickStartStates,
+    showFilter,
+    filter.keyword,
+    filter.status.statusFilters,
+    sortFncCallback,
+    filteredQuickStarts,
+  ]);
+
+  const clearFilters = () => {
+    setFilter('keyword', '');
+    setFilter('status', []);
+    clearFilterParams();
+    setFilteredQuickStarts(
+      allQuickStarts.sort((q1, q2) => q1.spec.displayName.localeCompare(q2.spec.displayName)),
+    );
+  };
+
+  const onSearchInputChange = (searchValue) => {
+    const result = filterQuickStarts(
+      allQuickStarts,
+      searchValue,
+      filter.status.statusFilters,
+      allQuickStartStates,
+    ).sort((q1, q2) => q1.spec.displayName.localeCompare(q2.spec.displayName));
+    if (searchValue !== filter.keyword) {
+      setFilter('keyword', searchValue);
+    }
+    if (result.length !== filteredQuickStarts.length) {
+      setFilteredQuickStarts(result);
+    }
+  };
+
+  const onStatusChange = (statusList) => {
+    const result = filterQuickStarts(
+      allQuickStarts,
+      filter.keyword,
+      statusList,
+      allQuickStartStates,
+    ).sort((q1, q2) => q1.spec.displayName.localeCompare(q2.spec.displayName));
+    if (JSON.stringify(statusList) !== JSON.stringify(filter.status)) {
+      setFilter('status', statusList);
+    }
+    if (result.length !== filteredQuickStarts.length) {
+      setFilteredQuickStarts(result);
+    }
+  };
+
+  if (loading) {
+    return <LoadingBox />;
+  }
+
+  if (!allQuickStarts || allQuickStarts.length === 0) {
+    return <EmptyBox label={getResource('Quick Starts')} />;
+  }
+
+  return (
+    <div className="pfext-quick-start__base">
+      {showTitle && (
+        <div className="pfext-page-layout__header">
+          <Text component="h1" className="pfext-page-layout__title" data-test="page-title">
+            {title || getResource('Quick Starts')}
+          </Text>
+          {hint && <div className="pfext-page-layout__hint">{hint}</div>}
+        </div>
+      )}
+      {showTitle && <Divider component="div" />}
+      {showFilter && (
+        <>
+          <QuickStartCatalogFilter
+            quickStartsCount={filteredQuickStarts.length}
+            onSearchInputChange={onSearchInputChange}
+            onStatusChange={onStatusChange}
+          />
+          <Divider component="div" />
+        </>
+      )}
+      <>
+        {filteredQuickStarts.length === 0 ? (
+          <QuickStartCatalogEmptyState clearFilters={clearFilters} />
+        ) : (
+          <QuickStartCatalog quickStarts={filteredQuickStarts} />
+        )}
+      </>
+    </div>
+  );
+};

package/src/QuickStartCloseModal.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { Button, Flex, FlexItem, ModalVariant } from '@patternfly/react-core';
+import { Modal } from '@console/shared';
+import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
+
+interface QuickStartCloseModalProps {
+  isOpen: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+const QuickStartCloseModal: React.FC<QuickStartCloseModalProps> = ({
+  isOpen,
+  onConfirm,
+  onCancel,
+}) => {
+  const { getResource } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  return (
+    <Modal
+      className="pfext-quick-start-drawer__modal pfext-quick-start__base"
+      isOpen={isOpen}
+      variant={ModalVariant.small}
+      showClose={false}
+      data-test="leave-quickstart"
+      title={getResource('Leave quick start?')}
+      footer={
+        <Flex>
+          <FlexItem align={{ default: 'alignRight' }}>
+            <Button variant="secondary" data-test="cancel button" onClick={onCancel}>
+              {getResource('Cancel')}
+            </Button>
+          </FlexItem>
+          <FlexItem>
+            <Button variant="primary" data-test="leave button" onClick={onConfirm}>
+              {getResource('Leave')}
+            </Button>
+          </FlexItem>
+        </Flex>
+      }
+      isFullScreen
+    >
+      {getResource('Your progress will be saved.')}
+    </Modal>
+  );
+};
+
+export default QuickStartCloseModal;

package/src/QuickStartController.tsx

@@ -0,0 +1,111 @@
+import * as React from 'react';
+import QuickStartContent from './controller/QuickStartContent';
+import QuickStartFooter from './controller/QuickStartFooter';
+import { QuickStartContext, QuickStartContextValues } from './utils/quick-start-context';
+import { QuickStart, QuickStartStatus, QuickStartTaskStatus } from './utils/quick-start-types';
+
+interface QuickStartControllerProps {
+  quickStart: QuickStart;
+  nextQuickStarts?: QuickStart[];
+  footerClass: string;
+  contentRef: React.Ref<HTMLDivElement>;
+}
+
+const QuickStartController: React.FC<QuickStartControllerProps> = ({
+  quickStart,
+  nextQuickStarts,
+  contentRef,
+  footerClass,
+}) => {
+  const {
+    metadata: { name },
+    spec: { tasks = [] },
+  } = quickStart;
+  const totalTasks = tasks?.length;
+  const {
+    activeQuickStartState,
+    setActiveQuickStart,
+    setQuickStartTaskNumber,
+    setQuickStartTaskStatus,
+    nextStep,
+    previousStep,
+  } = React.useContext<QuickStartContextValues>(QuickStartContext);
+  const status = activeQuickStartState?.status as QuickStartStatus;
+  const taskNumber = activeQuickStartState?.taskNumber as number;
+  const allTaskStatuses = tasks.map(
+    (task, index) => activeQuickStartState[`taskStatus${index}`],
+  ) as QuickStartTaskStatus[];
+
+  const handleQuickStartChange = React.useCallback(
+    (quickStartId: string) => setActiveQuickStart(quickStartId),
+    [setActiveQuickStart],
+  );
+
+  const handleTaskStatusChange = React.useCallback(
+    (newTaskStatus: QuickStartTaskStatus) => setQuickStartTaskStatus(newTaskStatus),
+    [setQuickStartTaskStatus],
+  );
+
+  const getQuickStartActiveTask = React.useCallback(() => {
+    let activeTaskNumber = 0;
+    while (
+      activeTaskNumber !== totalTasks &&
+      activeQuickStartState[`taskStatus${activeTaskNumber}`] === QuickStartTaskStatus.SUCCESS
+    ) {
+      activeTaskNumber++;
+    }
+    return activeTaskNumber;
+  }, [totalTasks, activeQuickStartState]);
+
+  const handleQuickStartContinue = React.useCallback(() => {
+    const activeTaskNumber = getQuickStartActiveTask();
+    setQuickStartTaskNumber(name, activeTaskNumber);
+  }, [getQuickStartActiveTask, setQuickStartTaskNumber, name]);
+
+  const handleNext = React.useCallback(() => {
+    if (status === QuickStartStatus.COMPLETE && taskNumber === totalTasks) {
+      return handleQuickStartChange('');
+    }
+
+    if (status !== QuickStartStatus.NOT_STARTED && taskNumber === -1) {
+      return handleQuickStartContinue();
+    }
+
+    return nextStep(totalTasks);
+  }, [handleQuickStartChange, nextStep, status, taskNumber, totalTasks, handleQuickStartContinue]);
+
+  const handleBack = React.useCallback(() => previousStep(), [previousStep]);
+
+  const handleTaskSelect = React.useCallback(
+    (selectedTaskNumber: number) => {
+      setQuickStartTaskNumber(name, selectedTaskNumber);
+    },
+    [name, setQuickStartTaskNumber],
+  );
+
+  return (
+    <>
+      <QuickStartContent
+        quickStart={quickStart}
+        nextQuickStarts={nextQuickStarts}
+        taskNumber={taskNumber}
+        allTaskStatuses={allTaskStatuses}
+        onTaskSelect={handleTaskSelect}
+        onTaskReview={handleTaskStatusChange}
+        onQuickStartChange={handleQuickStartChange}
+        ref={contentRef}
+      />
+      <QuickStartFooter
+        status={status}
+        taskNumber={taskNumber}
+        totalTasks={totalTasks}
+        onNext={handleNext}
+        onBack={handleBack}
+        footerClass={footerClass}
+        quickStartId={quickStart.metadata.name}
+      />
+    </>
+  );
+};
+
+export default QuickStartController;

package/src/QuickStartDrawer.scss

@@ -0,0 +1,11 @@
+.pfext-quick-start-drawer {
+  &__body {
+    display: flex;
+    flex-direction: column;
+    z-index: 0;
+    position: relative;
+  }
+  &__modal > .pf-v5-c-modal-box__footer {
+    display: block;
+  }
+}

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: Document, 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-v5-c-drawer__main">{panelContent}</div>
+        )}
+      </Drawer>
+      <QuickStartCloseModal
+        isOpen={modalOpen}
+        onConfirm={onModalConfirm}
+        onCancel={onModalCancel}
+      />
+    </>
+  );
+};