ref(onboarding): Introduce content blocks

static/app/components/onboarding/gettingStartedDoc/contentBlocks/defaultBlocks.tsx

@@ -0,0 +1,108 @@
+import {css} from '@emotion/react';
+import styled from '@emotion/styled';
+
+import {Alert} from 'sentry/components/core/alert';
+import {useRendererContext} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/rendererContext';
+import type {
+  BlockRenderer,
+  ContentBlock,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/types';
+import {
+  CssVariables,
+  renderBlocks,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/utils';
+import {
+  OnboardingCodeSnippet,
+  TabbedCodeSnippet,
+} from 'sentry/components/onboarding/gettingStartedDoc/onboardingCodeSnippet';
+
+const baseBlockStyles = css`
+  :not(:last-child) {
+    margin-bottom: var(${CssVariables.BLOCK_SPACING});
+  }
+`;
+
+function AlertBlock({
+  alertType,
+  text,
+  showIcon,
+  system,
+  trailingItems,
+}: Extract<ContentBlock, {type: 'alert'}>) {
+  return (
+    <div css={baseBlockStyles}>
+      <Alert
+        type={alertType}
+        showIcon={showIcon}
+        system={system}
+        trailingItems={trailingItems}
+      >
+        {text}
+      </Alert>
+    </div>
+  );
+}
+
+function CodeBlock(block: Extract<ContentBlock, {type: 'code'}>) {
+  if ('code' in block) {
+    return (
+      <div css={baseBlockStyles}>
+        <OnboardingCodeSnippet language={block.language}>
+          {block.code}
+        </OnboardingCodeSnippet>
+      </div>
+    );
+  }
+
+  const tabsWithValues = block.tabs.map(tab => ({
+    ...tab,
+    value: tab.label,
+  }));
+
+  return (
+    <div css={baseBlockStyles}>
+      <TabbedCodeSnippet tabs={tabsWithValues} />
+    </div>
+  );
+}
+
+function ConditionalBlock({
+  condition,
+  content,
+}: Extract<ContentBlock, {type: 'conditional'}>) {
+  const {renderer} = useRendererContext();
+
+  if (condition) {
+    return renderBlocks(content, renderer);
+  }
+
+  return null;
+}
+
+function CustomBlock(block: Extract<ContentBlock, {type: 'custom'}>) {
+  return <CustomBlockWrapper>{block.content}</CustomBlockWrapper>;
+}
+
+const CustomBlockWrapper = styled('div')`
+  ${baseBlockStyles}
+`;
+
+function TextBlock(block: Extract<ContentBlock, {type: 'text'}>) {
+  return <TextBlockWrapper>{block.text}</TextBlockWrapper>;
+}
+
+const TextBlockWrapper = styled('div')`
+  ${baseBlockStyles}
+
+  code:not([class*='language-']) {
+    color: ${p => p.theme.pink400};
+  }
+`;
+
+export const defaultBlocks: BlockRenderer = {
+  text: TextBlock,
+  code: CodeBlock,
+  custom: CustomBlock,
+  alert: AlertBlock,
+  conditional: ConditionalBlock,
+};

static/app/components/onboarding/gettingStartedDoc/contentBlocks/renderer.tsx

@@ -0,0 +1,65 @@
+import {useMemo} from 'react';
+import styled from '@emotion/styled';
+
+import {defaultBlocks} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/defaultBlocks';
+import {RendererContext} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/rendererContext';
+import type {
+  BlockRenderer,
+  ContentBlock,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/types';
+import {
+  CssVariables,
+  renderBlocks,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/utils';
+import {space} from 'sentry/styles/space';
+
+interface Props {
+  /**
+   * The content blocks to be rendered.
+   */
+  contentBlocks: Array<ContentBlock | null | undefined>;
+  /**
+   * The class name to be applied to the root element.
+   */
+  className?: string;
+  /**
+   * A custom renderer for the content blocks.
+   * If not provided, the default renderer will be used.
+   * The renderer object must have a key for each content block type.
+   */
+  renderer?: Partial<BlockRenderer>;
+  /**
+   * The spacing between the content blocks.
+   * Available as a CSS variable `var(${CssVariables.BLOCK_SPACING})` for styling of child elements.
+   */
+  spacing?: string;
+}
+
+const NO_RENDERER = {};
+const DEFAULT_SPACING = space(2);
+
+export function ContentBlocksRenderer({
+  contentBlocks,
+  renderer: customRenderer = NO_RENDERER,
+  spacing = DEFAULT_SPACING,
+  className,
+}: Props) {
+  const renderer = useMemo(
+    () => ({
+      ...defaultBlocks,
+      ...customRenderer,
+    }),
+    [customRenderer]
+  );
+  return (
+    <RendererContext value={{renderer}}>
+      <Wrapper className={className} spacing={spacing}>
+        {renderBlocks(contentBlocks, renderer)}
+      </Wrapper>
+    </RendererContext>
+  );
+}
+
+const Wrapper = styled('div')<{spacing: string}>`
+  ${CssVariables.BLOCK_SPACING}: ${p => p.spacing};
+`;

static/app/components/onboarding/gettingStartedDoc/contentBlocks/rendererContext.tsx

@@ -0,0 +1,18 @@
+import {createContext, useContext} from 'react';
+
+import type {BlockRenderer} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/types';
+
+export const RendererContext = createContext<
+  | undefined
+  | {
+      renderer: BlockRenderer;
+    }
+>(undefined);
+
+export const useRendererContext = () => {
+  const context = useContext(RendererContext);
+  if (!context) {
+    throw new Error('useRendererContext must be used within a RendererContext');
+  }
+  return context;
+};

static/app/components/onboarding/gettingStartedDoc/contentBlocks/types.tsx

@@ -0,0 +1,70 @@
+import type {AlertProps} from 'sentry/components/core/alert';
+import type {CodeSnippetTab} from 'sentry/components/onboarding/gettingStartedDoc/onboardingCodeSnippet';
+
+type BaseBlock<T extends string> = {
+  type: T;
+};
+
+/**
+ * Renders the Alert component
+ */
+type AlertBlock = BaseBlock<'alert'> & {
+  alertType: AlertProps['type'];
+  text: React.ReactNode;
+  type: 'alert';
+  icon?: AlertProps['icon'];
+  showIcon?: AlertProps['showIcon'];
+  system?: AlertProps['system'];
+  trailingItems?: AlertProps['trailingItems'];
+};
+
+// The value of the tab is omitted and inferred from the label in the renderer
+type CodeTabWithoutValue = Omit<CodeSnippetTab, 'value'>;
+type SingleCodeBlock = BaseBlock<'code'> & Omit<CodeTabWithoutValue, 'label'>;
+type MultipleCodeBlock = BaseBlock<'code'> & {
+  tabs: CodeTabWithoutValue[];
+};
+/**
+ * Code blocks can either render a single code snippet or multiple code snippets in a tabbed interface.
+ */
+type CodeBlock = SingleCodeBlock | MultipleCodeBlock;
+
+/**
+ * Conditional blocks are used to render content based on a condition.
+ */
+type ConditionalBlock = BaseBlock<'conditional'> & {
+  condition: boolean;
+  content: ContentBlock[];
+};
+
+/**
+ * Text blocks are used to render one paragraph of text.
+ */
+type TextBlock = BaseBlock<'text'> & {
+  /**
+   * Only meant for text or return values of translation functions (t, tct, tn).
+   *
+   * **Do not** use this with custom react elements but instead use the `custom` block type.
+   */
+  text: React.ReactNode;
+};
+
+/**
+ * Custom blocks can be used to render any content that is not covered by the other block types.
+ */
+type CustomBlock = BaseBlock<'custom'> & {
+  content: React.ReactNode;
+};
+
+export type ContentBlock =
+  | AlertBlock
+  | CodeBlock
+  | ConditionalBlock
+  | CustomBlock
+  | TextBlock;
+
+export type BlockRenderer = {
+  [key in ContentBlock['type']]: (
+    block: Extract<ContentBlock, {type: key}>
+  ) => React.ReactNode;
+};

static/app/components/onboarding/gettingStartedDoc/contentBlocks/utils.tsx

@@ -0,0 +1,27 @@
+import type {
+  BlockRenderer,
+  ContentBlock,
+} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/types';
+
+export enum CssVariables {
+  BLOCK_SPACING = '--block-spacing',
+}
+
+export function renderBlocks(
+  contentBlocks: Array<ContentBlock | null | undefined>,
+  renderer: BlockRenderer
+) {
+  return contentBlocks.map((block, index) => {
+    if (!block) {
+      return null;
+    }
+    // Need to cast here as ts bugs out on the return type and does not allow assigning the key prop
+    const RendererComponent = renderer[block.type] as (
+      block: ContentBlock
+    ) => React.ReactNode;
+
+    // The index actually works well as a key here
+    // as long as the conditional block is used instead of JS logic to edit the blocks array
+    return <RendererComponent {...block} key={index} />;
+  });
+}

static/app/components/onboarding/gettingStartedDoc/onboardingCodeSnippet.tsx

@@ -1,9 +1,10 @@
-import {Fragment, useCallback, useState} from 'react';
+import {Fragment, useCallback, useMemo, useState} from 'react';
 import {createPortal} from 'react-dom';
 import beautify from 'js-beautify';
 
 import {CodeSnippet} from 'sentry/components/codeSnippet';
 import {AuthTokenGenerator} from 'sentry/components/onboarding/gettingStartedDoc/authTokenGenerator';
+import {PACKAGE_LOADING_PLACEHOLDER} from 'sentry/utils/gettingStartedDocs/getPackageVersion';
 
 interface OnboardingCodeSnippetProps
   extends Omit<React.ComponentProps<typeof CodeSnippet>, 'onAfterHighlight'> {}
@@ -39,11 +40,18 @@ export function OnboardingCodeSnippet({
     setAuthTokenNodes(replaceTokensWithSpan(element));
   }, []);
 
+  const partialLoading = useMemo(
+    () => children.includes(PACKAGE_LOADING_PLACEHOLDER),
+    [children]
+  );
+
   return (
     <Fragment>
       <CodeSnippet
         dark
         language={language}
+        hideCopyButton={partialLoading}
+        disableUserSelection={partialLoading}
         {...props}
         onAfterHighlight={handleAfterHighlight}
       >

static/app/components/onboarding/gettingStartedDoc/replay/tracePropagationMessage.tsx

@@ -1,5 +1,6 @@
 import {Alert} from 'sentry/components/core/alert';
 import ExternalLink from 'sentry/components/links/externalLink';
+import type {ContentBlock} from 'sentry/components/onboarding/gettingStartedDoc/types';
 import {tct} from 'sentry/locale';
 
 export default function TracePropagationMessage() {
@@ -16,3 +17,16 @@ export default function TracePropagationMessage() {
     </Alert>
   );
 }
+
+export const tracePropagationBlock: ContentBlock = {
+  type: 'alert',
+  alertType: 'info',
+  text: tct(
+    `To see replays for backend errors, ensure that you have set up trace propagation. To learn more, [link:read the docs].`,
+    {
+      link: (
+        <ExternalLink href="https://docs.sentry.io/product/explore/session-replay/web/getting-started/#replays-for-backend-errors" />
+      ),
+    }
+  ),
+};

static/app/components/onboarding/gettingStartedDoc/step.tsx

@@ -3,6 +3,7 @@ import {Fragment, useState} from 'react';
 import styled from '@emotion/styled';
 
 import {Button} from 'sentry/components/core/button';
+import {ContentBlocksRenderer} from 'sentry/components/onboarding/gettingStartedDoc/contentBlocks/renderer';
 import {
   OnboardingCodeSnippet,
   TabbedCodeSnippet,
@@ -64,17 +65,22 @@ export function Step({
   title,
   type,
   configurations,
+  content,
   additionalInfo,
   description,
   onOptionalToggleClick,
   collapsible = false,
   trailingItems,
   codeHeader,
   ...props
-}: React.HTMLAttributes<HTMLDivElement> & OnboardingStep) {
+}: Omit<React.HTMLAttributes<HTMLDivElement>, 'content'> & OnboardingStep) {
   const [showOptionalConfig, setShowOptionalConfig] = useState(false);
 
-  const config = (
+  const config = content ? (
+    <ContentWrapper>
+      <ContentBlocksRenderer contentBlocks={content} />
+    </ContentWrapper>
+  ) : (
     <ContentWrapper>
       {description && <Description>{description}</Description>}