Feature: sandbox page and tutorials (#2870)

* Improves PostHog error tracking on sandbox page

Updates error tracking logic to use the imported `posthog` instance instead of relying on `window.posthog`.

This ensures that the PostHog instance is correctly referenced, improving the reliability of error tracking on the sandbox page.

* Makes bookmark optional on tutorial cards

Allows tutorial cards to be displayed without a bookmark button.

This change provides the flexibility to display tutorial cards in contexts where bookmarking functionality is not desired or applicable.
Specifically, it disables the bookmark button within the tutorial cards grid list.

* Fixes tutorial card props and testing context

Corrects the type definition for the TutorialCardWithAuthElements component to properly handle optional properties.

Removes commented-out code in the instruqt-lab context test file, cleaning up the codebase and removing distractions.

* Reduces card and badge sizes for a denser UI.

Reduces padding and margins in cards and badges to create a more compact and information-dense user interface. This aims to improve content presentation by minimizing whitespace and making more content visible at a glance.

* Refactors Instruqt lab context tests

Updates tests for the Instruqt lab context to improve reliability and
reduce duplication.

- Mocks localStorage directly instead of creating a mock object.
- Uses vi.spyOn for getItem and setItem to improve test isolation.
- Adds mock for validateSandboxConfigWithDetailedErrors to isolate config validation.
- Updates mock for next/router to simplify it.

* Refactors PostHog capture calls

Simplifies PostHog event capture calls by directly importing the `posthog` instance.

This change improves code readability and reduces redundancy across multiple components and contexts.

* Improves card layouts and adds sandbox card

Refactors card layouts for better spacing and responsiveness.

Introduces a new sandbox card component for displaying sandbox environments.

Updates tutorial card list to support compact cards.

* Reduces sandbox dropdown intro size matches figma.

Reduces the size of the product icon and intro text in the sandbox dropdown for a more visually appealing presentation.

* Increases padding in sandbox card component

Improves visual spacing within the sandbox card component
by increasing the padding and margins to create a more
balanced and appealing user interface.

* Improves Instruqt lab context tests

Updates tests to use `waitFor` for asynchronous state updates,
ensuring accurate state validation and preventing race conditions.
Also, fixes a bug where the `active` state was not being set
correctly when a new lab is opened.

* Improves sandbox card layout and styling

Removes !important overrides from tutorial card styles for better CSS specificity management.

Increases the grid gap in the sandbox view to improve visual spacing.

* Tracks sandbox interactions for analytics

Implements event tracking for user interactions within the sandbox environment.

This change captures key interactions, such as clicks and hovers, to provide insights into user behavior and improve the sandbox experience. The data collected will inform decisions on sandbox discoverability, engagement, and overall user satisfaction.

* Updates sandbox event tracking

Updates the sandbox event that is tracked when the iframe loads to `sandbox_open`.

This more accurately reflects the user's action of opening the sandbox and aligns with the new event naming conventions.

* Adds sandbox event tracking to dropdown

Adds tracking for sandbox events and interactions when a user clicks on a lab within the sandbox dropdown.
This provides insights into user engagement with sandboxes.

Author: Younique98

src/components/cards-grid-list/components/tutorial-cards-grid-list/index.tsx

@@ -10,35 +10,34 @@ import {
 	TutorialCardWithAuthElements,
 } from 'components/tutorial-card'
 import s from './tutorial-cards.module.css'
+import compactStyles from 'components/tutorial-card/tutorial-card-compact.module.css'
 
 interface TutorialCardsGridListProps extends CardsGridListProps {
 	tutorials: TutorialCardPropsWithId[]
+	compact?: boolean
 }
 
-/**
- * Handles rendering a grid of Tutorial cards, and pre-fetching the
- * `isBookmarked` state for each card.
- */
-const TutorialCardsGridList = ({ tutorials, ...restProps }) => {
-	/**
-	 * Collect the `tutorialIds` and React elements to render in separate arrays
-	 * at the same time (to save on iterating over the same data twice).
-	 */
+const TutorialCardsGridList = ({
+	tutorials,
+	compact = false,
+	...restProps
+}) => {
 	const tutorialIds = []
 	const cardsGridListItems = []
 	tutorials.forEach((tutorial: TutorialCardPropsWithId) => {
 		tutorialIds.push(tutorial.id)
 		cardsGridListItems.push(
-			<div className={s.sandboxCardBox} key={tutorial.id}>
-				<TutorialCardWithAuthElements {...tutorial} />
+			<div
+				className={`${s.tutorialCardBox} ${
+					compact ? compactStyles.compactTutorialCard : ''
+				}`}
+				key={tutorial.id}
+			>
+				<TutorialCardWithAuthElements {...tutorial} hasBookmark={false} />
 			</div>
 		)
 	})
 
-	/**
-	 * Prime the `isBookmarked` queries for the tutorial cards we know we need to
-	 * render via collected `tutorialIds` array.
-	 */
 	const { isFetching, isRefetching } = useBookmarksByTutorialIds({
 		tutorialIds,
 	})

src/components/cards-grid-list/components/tutorial-cards-grid-list/tutorial-cards.module.css

@@ -1,5 +1,10 @@
-.sandboxCardBox {
-	min-height: 200px;
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+.tutorialCardBox {
+	min-height: 100px;
 	height: 100%;
 	display: flex;
 	flex-direction: column;

src/components/cards-grid-list/types.ts

@@ -9,7 +9,7 @@ interface CardsGridListProps {
 	children: ReactNode
 	isOrdered?: boolean
 	fixedColumns?: number
-	gridGap?: '16px' | '24px'
+	gridGap?: '8px' | '12px' | '16px' | '24px'
 }
 
 export type { CardsGridListProps }

src/components/dev-dot-content/mdx-components/mdx-alert/index.tsx

@@ -11,6 +11,7 @@ import { IconAlertDiamond24 } from '@hashicorp/flight-icons/svg-react/alert-diam
 import { MdxHighlight, MdxTip, MdxNote, MdxWarning } from './variants'
 import { MdxInlineAlertData, MdxInlineAlertProps } from './types'
 import s from './mdx-inline-alert.module.css'
+import posthog from 'posthog-js'
 
 const ALERT_DATA: MdxInlineAlertData = {
 	tip: { title: 'Tip', icon: <IconInfo24 />, color: 'neutral' },
@@ -73,8 +74,8 @@ export const MdxInlineAlert = withErrorBoundary(
 	MdxInlineAlertBase,
 	AlertErrorFallback,
 	(error, errorInfo) => {
-		if (typeof window !== 'undefined' && window.posthog?.capture) {
-			window.posthog.capture('mdx_component_error', {
+		if (typeof window !== 'undefined' && posthog?.capture) {
+			posthog.capture('mdx_component_error', {
 				component_name: 'MdxInlineAlert',
 				error_message: error.message,
 				error_stack: error.stack,

src/components/interactive-lab-callout/index.tsx

@@ -10,6 +10,7 @@ import { useInstruqtEmbed } from 'contexts/instruqt-lab'
 import { FC } from 'react'
 import s from './interactive-lab-callout.module.css'
 import SANDBOX_CONFIG from 'content/sandbox/sandbox.json' assert { type: 'json' }
+import { trackSandboxInteraction } from 'views/sandbox-view'
 
 interface InteractiveLabCalloutProps {
 	labId?: string
@@ -34,6 +35,9 @@ const InteractiveLabCallout: FC<InteractiveLabCalloutProps> = ({ labId }) => {
 
 	const handleStartLab = () => {
 		if (effectiveLabId) {
+			trackSandboxInteraction('click', effectiveLabId, {
+				source: 'interactive-lab-callout',
+			})
 			ctx.openLab(effectiveLabId)
 			ctx.setActive(true)
 		} else {

src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx

@@ -22,6 +22,9 @@ vi.mock('next/router', () => ({
 vi.mock('lib/posthog-events', () => ({
 	trackSandboxEvent: vi.fn(),
 	SANDBOX_EVENT: {
+		SANDBOX_STARTED: 'sandbox_started',
+		SANDBOX_OPEN: 'sandbox_open',
+		SANDBOX_CLOSED: 'sandbox_closed',
 		SANDBOX_LOADED: 'sandbox_loaded',
 		SANDBOX_ERROR: 'sandbox_error',
 		SANDBOX_RETRY: 'sandbox_retry',
@@ -133,7 +136,7 @@ describe('EmbedElement', () => {
 				screen.queryByText('Loading your sandbox...')
 			).not.toBeInTheDocument()
 
-			expect(mockTrackSandboxEvent).toHaveBeenCalledWith('sandbox_loaded', {
+			expect(mockTrackSandboxEvent).toHaveBeenCalledWith('sandbox_open', {
 				labId: 'test-lab-id',
 				page: '/test-path',
 			})

src/components/lab-embed/embed-element/index.tsx

@@ -50,7 +50,7 @@ const EmbedElement = memo(function EmbedElement(): JSX.Element {
 		}))
 
 		if (labId) {
-			trackSandboxEvent(SANDBOX_EVENT.SANDBOX_LOADED, {
+			trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 				labId,
 				page: router.asPath,
 			})

src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx

@@ -6,7 +6,7 @@
 import { render, screen, fireEvent } from '@testing-library/react'
 import SandboxDropdown from '../index'
 
-// Mock the hooks
+// Mock the hooks and functions
 const mockUserRouter = vi.fn()
 vi.mock('next/router', () => ({
 	useRouter: () => mockUserRouter(),
@@ -22,6 +22,20 @@ vi.mock('contexts/instruqt-lab', () => ({
 	useInstruqtEmbed: () => mockUseInstruqtEmbed(),
 }))
 
+const mockTrackSandboxInteraction = vi.fn()
+vi.mock('views/sandbox-view', () => ({
+	trackSandboxInteraction: (...args: unknown[]) =>
+		mockTrackSandboxInteraction(...args),
+}))
+
+const mockTrackSandboxEvent = vi.fn()
+vi.mock('lib/posthog-events', () => ({
+	trackSandboxEvent: (...args: unknown[]) => mockTrackSandboxEvent(...args),
+	SANDBOX_EVENT: {
+		SANDBOX_OPEN: 'sandbox_open',
+	},
+}))
+
 describe('SandboxDropdown', () => {
 	beforeEach(() => {
 		// Reset all mocks before each test
@@ -135,7 +149,7 @@ describe('SandboxDropdown', () => {
 		expect(mockOpenLab).toHaveBeenCalled()
 	})
 
-	it('tracks sandbox events when opening labs', () => {
+	it('tracks sandbox events and interactions when clicking a lab', () => {
 		const mockOpenLab = vi.fn()
 		const mockSetActive = vi.fn()
 		mockUseInstruqtEmbed.mockImplementation(() => ({
@@ -155,5 +169,20 @@ describe('SandboxDropdown', () => {
 
 		// Verify openLab was called
 		expect(mockOpenLab).toHaveBeenCalled()
+
+		// Verify tracking events were called
+		expect(mockTrackSandboxEvent).toHaveBeenCalledWith('sandbox_open', {
+			labId: expect.any(String),
+			page: '/',
+		})
+
+		// Verify interaction tracking
+		expect(mockTrackSandboxInteraction).toHaveBeenCalledWith(
+			'hover',
+			expect.any(String),
+			{
+				page: '/',
+			}
+		)
 	})
 })

src/components/navigation-header/components/sandbox-dropdown/index.tsx

@@ -23,6 +23,7 @@ import { SandboxLab } from 'types/sandbox'
 import { ProductSlug } from 'types/products'
 import { buildLabIdWithConfig } from 'lib/build-instruqt-url'
 import { useTheme } from 'next-themes'
+import { trackSandboxInteraction } from 'views/sandbox-view'
 
 interface SandboxDropdownProps {
 	ariaLabel: string
@@ -122,9 +123,6 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 		}
 	}
 
-	/**
-	 * Handle lab selection
-	 */
 	const handleLabClick = (lab: SandboxLab) => {
 		const labWithTrack = {
 			...lab,
@@ -133,16 +131,13 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 		const fullLabId = buildLabIdWithConfig(labWithTrack)
 		openLab(fullLabId)
 		setActive(true)
-		trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, {
+		trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, {
 			labId: fullLabId,
 			page: router.asPath,
 		})
 		setIsOpen(false)
 	}
 
-	/**
-	 * Navigate to the sandbox page
-	 */
 	const navigateToSandboxPage = (e: React.MouseEvent) => {
 		e.preventDefault()
 		router.push(`/${currentProduct.slug}/sandbox`)
@@ -206,12 +201,12 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 						<div className={s.introSandboxRow}>
 							<ProductIcon
 								productSlug={currentProduct.slug as ProductSlug}
-								size={24}
+								size={16}
 								className={s.productIcon}
 							/>
 							<Text
 								asElement="span"
-								className={`${s.sectionTitle} ${s.introSandboxTitle}`}
+								className={`${s.sectionTitle} ${s.introSandboxTitle} ${s.title}`}
 								size={200}
 								weight="semibold"
 							>
@@ -220,7 +215,7 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 						</div>
 						<Text
 							asElement="span"
-							className={`${s.introText} ${s.introSandboxText}`}
+							className={`${s.introText} ${s.introSandboxText} ${s.description}`}
 							size={100}
 							weight="regular"
 						>
@@ -230,7 +225,6 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 						</Text>
 					</button>
 
-					{/* Available Product Sandboxes Section */}
 					<Text
 						asElement="p"
 						className={s.sectionTitle}
@@ -245,7 +239,12 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => {
 							<li key={lab.labId || index} className={s.itemContainer}>
 								<button
 									className={s.sandboxItem}
-									onClick={() => handleLabClick(lab)}
+									onClick={() => {
+										handleLabClick(lab)
+										trackSandboxInteraction('hover', lab.labId, {
+											page: router.asPath,
+										})
+									}}
 									onKeyDown={handleKeyDown}
 								>
 									<div className={s.content}>

src/components/navigation-header/components/sandbox-dropdown/sandbox-dropdown.module.css

@@ -167,13 +167,16 @@
 .productIcon {
 	flex-shrink: 0;
 	color: var(--token-color-foreground-faint);
+	width: 16px;
+	height: 16px;
 }
 
 .description {
 	color: var(--token-color-foreground-faint);
 	display: block;
 	line-height: 1.5;
-	font-size: 14px;
+	font-size: 13px;
+	font-weight: 400;
 }
 
 .learnMoreLink {