From 9c19be9a8d8de208665a57595c5a5d61abbeb217 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 21 Jan 2025 16:32:59 -0800 Subject: [PATCH 01/53] refactor and fix commit error --- next-env.d.ts | 1 + .../utils/get-nav-items.ts | 7 ++ src/contexts/instruqt-lab/index.tsx | 36 ++++--- src/data/playground-config.json | 23 +++++ src/data/terraform.json | 19 +++- src/data/vault.json | 17 ++++ src/pages/[productSlug]/playground/index.tsx | 27 ++++++ src/types/products.ts | 7 ++ src/views/playground/index.tsx | 39 ++++++++ src/views/playground/server.ts | 97 +++++++++++++++++++ tsconfig.json | 9 +- 11 files changed, 266 insertions(+), 16 deletions(-) create mode 100644 src/data/playground-config.json create mode 100644 src/pages/[productSlug]/playground/index.tsx create mode 100644 src/views/playground/index.tsx create mode 100644 src/views/playground/server.ts diff --git a/next-env.d.ts b/next-env.d.ts index 4f11a03dc6..fd36f9494e 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,5 +1,6 @@ /// /// +/// // NOTE: This file should not be edited // see https://nextjs.org/docs/basic-features/typescript for more information. diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index 198bb78f6e..e15f434bf3 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -146,6 +146,13 @@ export function getNavItems(currentProduct: ProductData): NavItem[] { } } + if (currentProduct.instruqtId) { + items.push({ + label: 'Playground', + url: `/${currentProduct.slug}/playground`, + }) + } + /** * For Terraform, add a "Registry" item */ diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index 8914b28692..b2186eed93 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -23,6 +23,8 @@ interface InstruqtContextProps { interface InstruqtProviderProps { labId: string children: ReactNode + defaultActive?: boolean + isPlayground?: boolean } const InstruqtContext = createContext>({}) @@ -34,23 +36,31 @@ export const useInstruqtEmbed = (): Partial => export default function InstruqtProvider({ labId, children, + defaultActive = false, + isPlayground = false, }: InstruqtProviderProps): JSX.Element { - const [active, setActive] = useState(false) + const [active, setActive] = useState(defaultActive) return ( - {children} - {active && ( -
- - - -
+ {isPlayground ? ( + children + ) : ( + <> + {children} + {active && ( +
+ + + +
+ )} + )} ) diff --git a/src/data/playground-config.json b/src/data/playground-config.json new file mode 100644 index 0000000000..90a660ebda --- /dev/null +++ b/src/data/playground-config.json @@ -0,0 +1,23 @@ +{ + "terraform": { + "labId": "hashicorp-learn/tracks/terraform-build-your-first-configuration" + }, + "vault": { + "labId": "hashicorp-learn/tracks/vault-basics" + }, + "consul": { + "labId": "hashicorp-learn/tracks/consul-template-automate-reverse-proxy-config" + }, + "nomad": { + "labId": "hashicorp-learn/tracks/nomad-basics" + }, + "packer": { + "labId": "hashicorp-learn/tracks/packer-get-started-hcp" + }, + "waypoint": { + "labId": "hashicorp-learn/tracks/waypoint-get-started-docker" + }, + "boundary": { + "labId": "hashicorp-learn/tracks/boundary-basics" + } +} diff --git a/src/data/terraform.json b/src/data/terraform.json index 1c6de4f9c6..c9475beff8 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -151,5 +151,22 @@ "path": "registry", "productSlugForLoader": "terraform-docs-common" } - ] + ], + "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", + "playgroundConfig": { + "sidebarLinks": [ + { + "title": "Install Terraform", + "href": "/terraform/install" + }, + { + "title": "Get Started with Terraform", + "href": "/terraform/tutorials/aws-get-started" + }, + { + "title": "Terraform documentation", + "href": "/terraform/docs" + } + ] + } } diff --git a/src/data/vault.json b/src/data/vault.json index e6bb0fe83c..03ef95d705 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -174,5 +174,22 @@ "href": "/vault/tutorials/custom-secrets-engine" } ] + }, + "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", + "playgroundConfig": { + "sidebarLinks": [ + { + "title": "Install Vault", + "href": "/vault/install" + }, + { + "title": "Get Started with Vault", + "href": "/vault/tutorials/get-started" + }, + { + "title": "Vault Documentation", + "href": "/vault/docs" + } + ] } } diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx new file mode 100644 index 0000000000..a2a1677dea --- /dev/null +++ b/src/pages/[productSlug]/playground/index.tsx @@ -0,0 +1,27 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { GetStaticPaths } from 'next' +import { PRODUCT_DATA_MAP } from 'data/product-data-map' +import { getStaticProps } from 'views/playground/server' +import PlaygroundView from 'views/playground' + +export default PlaygroundView + +export const getStaticPaths: GetStaticPaths = async () => { + // Only generate paths for products that have an instruqtId + const paths = Object.values(PRODUCT_DATA_MAP) + .filter((product) => product.instruqtId) + .map((product) => ({ + params: { productSlug: product.slug }, + })) + + return { + paths, + fallback: false, + } +} + +export { getStaticProps } diff --git a/src/types/products.ts b/src/types/products.ts index b3259e0939..590e6a5d98 100644 --- a/src/types/products.ts +++ b/src/types/products.ts @@ -148,6 +148,13 @@ interface ProductData extends Product { } basePaths: string[] rootDocsPaths: RootDocsPath[] + instruqtId?: string + playgroundConfig?: { + sidebarLinks: { + title: string + href: string + }[] + } /** * When configuring docsNavItems, authors have the option to specify * the full data structure, or use a string that matches a rootDocsPath.path diff --git a/src/views/playground/index.tsx b/src/views/playground/index.tsx new file mode 100644 index 0000000000..3bd00f1228 --- /dev/null +++ b/src/views/playground/index.tsx @@ -0,0 +1,39 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { ProductData } from 'types/products' +import { BreadcrumbLink } from 'components/breadcrumb-bar' +import { SidebarProps } from 'components/sidebar/types' +import SidebarSidecarLayout from 'layouts/sidebar-sidecar' +import InstruqtProvider from 'contexts/instruqt-lab' +import EmbedElement from 'components/lab-embed/embed-element' + +interface PlaygroundViewProps { + product: ProductData + labId: string + layoutProps: { + breadcrumbLinks: BreadcrumbLink[] + navLevels: SidebarProps[] + } +} + +export default function PlaygroundView({ + product, + labId, + layoutProps, +}: PlaygroundViewProps) { + return ( + +
+ + + +
+ + ) +} diff --git a/src/views/playground/server.ts b/src/views/playground/server.ts new file mode 100644 index 0000000000..db9656165e --- /dev/null +++ b/src/views/playground/server.ts @@ -0,0 +1,97 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { GetStaticProps } from 'next' +import { PRODUCT_DATA_MAP } from 'data/product-data-map' +import { ProductData } from 'types/products' +import { BreadcrumbLink } from 'components/breadcrumb-bar' +import { SidebarProps } from 'components/sidebar/types' +import { + generateTopLevelSidebarNavData, + generateProductLandingSidebarNavData, +} from 'components/sidebar/helpers' + +interface PlaygroundPageProps { + product: ProductData + labId: string + layoutProps: { + breadcrumbLinks: BreadcrumbLink[] + navLevels: SidebarProps[] + } +} + +export const getStaticProps: GetStaticProps = async ({ + params, +}) => { + const productSlug = params?.productSlug as string + const product = PRODUCT_DATA_MAP[productSlug] + + // Only show playground page if product has an instruqtId + if (!product || !product.instruqtId) { + return { + notFound: true, + } + } + + const breadcrumbLinks = [ + { title: 'Developer', url: '/' }, + { title: product.name, url: `/${productSlug}` }, + { title: 'Playground', url: `/${productSlug}/playground` }, + ] + + const sidebarNavDataLevels = [ + generateTopLevelSidebarNavData(product.name), + generateProductLandingSidebarNavData(product), + ] + + // Add playground links if configured + if (product.playgroundConfig?.sidebarLinks) { + const playgroundMenuItems = [ + { + title: `${product.name} Playground`, + fullPath: `/${productSlug}/playground`, + theme: product.slug, + isActive: true, + }, + { + divider: true, + }, + { + heading: 'Resources', + }, + ...product.playgroundConfig.sidebarLinks.map((link) => ({ + title: link.title, + path: link.href, + href: link.href, + isActive: false, + })), + ] + sidebarNavDataLevels.push({ + backToLinkProps: { + text: `${product.name} Home`, + href: `/${product.slug}`, + }, + title: 'Playground', + menuItems: playgroundMenuItems, + showFilterInput: false, + visuallyHideTitle: true, + levelButtonProps: { + levelUpButtonText: `${product.name} Home`, + levelDownButtonText: 'Previous', + }, + }) + } + + return { + props: { + product, + labId: product.instruqtId, + layoutProps: { + breadcrumbLinks, + navLevels: sidebarNavDataLevels, + }, + }, + } +} diff --git a/tsconfig.json b/tsconfig.json index 51ef1da429..8590e3c4fd 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -23,8 +23,13 @@ "@components/*": ["components/*"] }, "types": ["vitest/globals", "@testing-library/jest-dom"], - "strictNullChecks": false + "strictNullChecks": false, + "plugins": [ + { + "name": "next" + } + ] }, - "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"], + "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], "exclude": ["node_modules", "scripts/migrate-io/templates"] } From 06d62599ff72ce05ba26e9e6a87c1c34c7276593 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 11 Mar 2025 09:42:01 -0700 Subject: [PATCH 02/53] add multiple lab support for playgrounds --- .../utils/get-nav-items.ts | 2 +- src/data/nomad.json | 27 +++ src/data/terraform.json | 18 +- src/data/vault.json | 17 +- .../playground/[playgroundId].tsx | 181 ++++++++++++++++++ src/pages/[productSlug]/playground/index.tsx | 168 +++++++++++++++- src/types/products.ts | 9 +- src/views/playground/server.ts | 8 +- 8 files changed, 416 insertions(+), 14 deletions(-) create mode 100644 src/pages/[productSlug]/playground/[playgroundId].tsx diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index e15f434bf3..114862afe2 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -146,7 +146,7 @@ export function getNavItems(currentProduct: ProductData): NavItem[] { } } - if (currentProduct.instruqtId) { + if (currentProduct.playgroundConfig?.labs?.length) { items.push({ label: 'Playground', url: `/${currentProduct.slug}/playground`, diff --git a/src/data/nomad.json b/src/data/nomad.json index b4ec3ec91b..76485a6711 100644 --- a/src/data/nomad.json +++ b/src/data/nomad.json @@ -102,5 +102,32 @@ ], "integrationsConfig": { "description": "A curated collection of official, partner, and community Nomad Integrations." + }, + + "playgroundConfig": { + "description": "Learn how to manage your workloads with Nomad.", + "sidebarLinks": [ + { + "title": "Install Nomad", + "href": "/nomad/install" + }, + { + "title": "Get Started with Nomad", + "href": "/nomad/tutorials/get-started" + }, + { + "title": "Nomad documentation", + "href": "/nomad/docs" + } + ], + "labs": [ + { + "id": "nomad-sandbox", + "name": "Nomad sandbox", + "instruqtId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", + "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", + "products": ["nomad", "consul"] + } + ] } } diff --git a/src/data/terraform.json b/src/data/terraform.json index c9475beff8..9bc211a2f7 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -152,8 +152,8 @@ "productSlugForLoader": "terraform-docs-common" } ], - "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", "playgroundConfig": { + "description": "Learn how to create infrastructure with Terraform", "sidebarLinks": [ { "title": "Install Terraform", @@ -167,6 +167,22 @@ "title": "Terraform documentation", "href": "/terraform/docs" } + ], + "labs": [ + { + "id": "create-infrastructure", + "name": "Create Infrastructure", + "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", + "description": "Learn how to create infrastructure with Terraform", + "products": ["terraform"] + }, + { + "id": "vault-sandbox", + "name": "Vault Playground (test)", + "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", + "description": "Learn how to manage your secrets with Vault", + "products": ["vault"] + } ] } } diff --git a/src/data/vault.json b/src/data/vault.json index 03ef95d705..4a4bd6190d 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -175,7 +175,6 @@ } ] }, - "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", "playgroundConfig": { "sidebarLinks": [ { @@ -190,6 +189,22 @@ "title": "Vault Documentation", "href": "/vault/docs" } + ], + "labs": [ + { + "id": "vault-sandbox", + "name": "Vault Playground (test)", + "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", + "description": "Learn how to manage your secrets with Vault", + "products": ["vault"] + }, + { + "id": "create-infrastructure", + "name": "Create Infrastructure", + "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", + "description": "Learn how to create infrastructure with Terraform", + "products": ["terraform"] + } ] } } diff --git a/src/pages/[productSlug]/playground/[playgroundId].tsx b/src/pages/[productSlug]/playground/[playgroundId].tsx new file mode 100644 index 0000000000..ae10e1b731 --- /dev/null +++ b/src/pages/[productSlug]/playground/[playgroundId].tsx @@ -0,0 +1,181 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { GetStaticPaths, GetStaticProps } from 'next' +import { PRODUCT_DATA_MAP } from 'data/product-data-map' +import SidebarSidecarLayout from 'layouts/sidebar-sidecar' +import InstruqtProvider from 'contexts/instruqt-lab' +import EmbedElement from 'components/lab-embed/embed-element' +import { + generateTopLevelSidebarNavData, + generateProductLandingSidebarNavData, +} from 'components/sidebar/helpers' + +interface PlaygroundPageProps { + product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] + playgroundId: string + playgroundName: string + playgroundDescription: string + layoutProps: { + breadcrumbLinks: { title: string; url: string }[] + navLevels: any[] + } +} + +export default function PlaygroundView({ + product, + playgroundId, + playgroundName, + playgroundDescription, + layoutProps, +}: PlaygroundPageProps) { + return ( + +
+

{playgroundName}

+

+ {playgroundDescription} +

+
+
+ + + +
+ + ) +} + +export const getStaticPaths: GetStaticPaths = async () => { + const paths = [] + + // Generate paths for each product's playgrounds + Object.values(PRODUCT_DATA_MAP).forEach((product) => { + if (product.playgroundConfig?.labs) { + product.playgroundConfig.labs.forEach((playground) => { + paths.push({ + params: { + productSlug: product.slug, + playgroundId: playground.id, + }, + }) + }) + } + }) + + return { + paths, + fallback: false, + } +} + +export const getStaticProps: GetStaticProps = async ({ + params, +}) => { + const productSlug = params?.productSlug as string + const playgroundId = params?.playgroundId as string + const product = PRODUCT_DATA_MAP[productSlug] + + // Only show playground page if product has labs configured + if (!product || !product.playgroundConfig?.labs) { + return { + notFound: true, + } + } + + const playground = product.playgroundConfig.labs.find( + (p) => p.id === playgroundId + ) + if (!playground) { + return { + notFound: true, + } + } + + const breadcrumbLinks = [ + { title: 'Developer', url: '/' }, + { title: product.name, url: `/${productSlug}` }, + { title: 'Playground', url: `/${productSlug}/playground` }, + { + title: playground.name, + url: `/${productSlug}/playground/${playgroundId}`, + }, + ] + + const sidebarNavDataLevels = [ + generateTopLevelSidebarNavData(product.name), + generateProductLandingSidebarNavData(product), + ] + + // Add playground links + const playgroundMenuItems = [ + { + title: `${product.name} Playground`, + fullPath: `/${productSlug}/playground`, + theme: product.slug, + isActive: false, + }, + { + divider: true, + }, + { + heading: 'Playgrounds', + }, + ...product.playgroundConfig.labs.map((p) => ({ + title: p.name, + path: `/${productSlug}/playground/${p.id}`, + href: `/${productSlug}/playground/${p.id}`, + isActive: p.id === playgroundId, + })), + ] + + if (product.playgroundConfig.sidebarLinks) { + playgroundMenuItems.push( + { + divider: true, + }, + { + heading: 'Resources', + }, + ...product.playgroundConfig.sidebarLinks.map((link) => ({ + title: link.title, + path: link.href, + href: link.href, + isActive: false, + })) + ) + } + + sidebarNavDataLevels.push({ + backToLinkProps: { + text: `${product.name} Home`, + href: `/${product.slug}`, + }, + title: 'Playground', + menuItems: playgroundMenuItems, + showFilterInput: false, + visuallyHideTitle: true, + levelButtonProps: { + levelUpButtonText: `${product.name} Home`, + levelDownButtonText: 'Previous', + }, + }) + + return { + props: { + product, + playgroundId: playground.instruqtId, + playgroundName: playground.name, + playgroundDescription: playground.description, + layoutProps: { + breadcrumbLinks, + navLevels: sidebarNavDataLevels, + }, + }, + } +} diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index a2a1677dea..e32edd1d94 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -3,17 +3,84 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { GetStaticPaths } from 'next' +import { GetStaticPaths, GetStaticProps } from 'next' import { PRODUCT_DATA_MAP } from 'data/product-data-map' -import { getStaticProps } from 'views/playground/server' -import PlaygroundView from 'views/playground' +import SidebarSidecarLayout from 'layouts/sidebar-sidecar' +import { + generateTopLevelSidebarNavData, + generateProductLandingSidebarNavData, +} from 'components/sidebar/helpers' +import CardLink from 'components/card-link' +import { + CardTitle, + CardDescription, + CardFooter, +} from 'components/card/components' +import CardsGridList from 'components/cards-grid-list' +import { BrandedHeaderCard } from 'views/product-integrations-landing/components/branded-header-card' +import { CardBadges } from 'components/tutorial-collection-cards' +import { ProductOption } from 'lib/learn-client/types' -export default PlaygroundView +interface PlaygroundPageProps { + product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] + layoutProps: { + breadcrumbLinks: { title: string; url: string }[] + navLevels: any[] + } +} + +export default function PlaygroundView({ + product, + layoutProps, +}: PlaygroundPageProps) { + return ( + + + + {product.playgroundConfig.description && ( +

+ {product.playgroundConfig.description} +

+ )} + +
+ + {product.playgroundConfig.labs.map((playground) => ( + + + {playground.description && ( + + )} + + ProductOption[slug] + )} + /> + + + ))} + +
+ + ) +} export const getStaticPaths: GetStaticPaths = async () => { - // Only generate paths for products that have an instruqtId + // Only generate paths for products that have labs configured const paths = Object.values(PRODUCT_DATA_MAP) - .filter((product) => product.instruqtId) + .filter((product) => product.playgroundConfig?.labs) .map((product) => ({ params: { productSlug: product.slug }, })) @@ -24,4 +91,91 @@ export const getStaticPaths: GetStaticPaths = async () => { } } -export { getStaticProps } +export const getStaticProps: GetStaticProps = async ({ + params, +}) => { + const productSlug = params?.productSlug as string + const product = PRODUCT_DATA_MAP[productSlug] + + // Only show playground page if product has labs configured + if (!product || !product.playgroundConfig?.labs) { + return { + notFound: true, + } + } + + const breadcrumbLinks = [ + { title: 'Developer', url: '/' }, + { title: product.name, url: `/${productSlug}` }, + { title: 'Playground', url: `/${productSlug}/playground` }, + ] + + const sidebarNavDataLevels = [ + generateTopLevelSidebarNavData(product.name), + generateProductLandingSidebarNavData(product), + ] + + // Add playground links + const playgroundMenuItems = [ + { + title: `${product.name} Playground`, + fullPath: `/${productSlug}/playground`, + theme: product.slug, + isActive: true, + }, + { + divider: true, + }, + { + heading: 'Playgrounds', + }, + ...product.playgroundConfig.labs.map((playground) => ({ + title: playground.name, + path: `/${productSlug}/playground/${playground.id}`, + href: `/${productSlug}/playground/${playground.id}`, + isActive: false, + })), + ] + + if (product.playgroundConfig.sidebarLinks) { + playgroundMenuItems.push( + { + divider: true, + }, + { + heading: 'Resources', + }, + ...product.playgroundConfig.sidebarLinks.map((link) => ({ + title: link.title, + path: link.href, + href: link.href, + isActive: false, + })) + ) + } + + sidebarNavDataLevels.push({ + backToLinkProps: { + text: `${product.name} Home`, + href: `/${product.slug}`, + }, + title: 'Playground', + menuItems: playgroundMenuItems, + showFilterInput: false, + visuallyHideTitle: true, + levelButtonProps: { + levelUpButtonText: `${product.name} Home`, + levelDownButtonText: 'Previous', + }, + }) + + return { + props: { + product, + layoutProps: { + breadcrumbLinks, + navLevels: sidebarNavDataLevels, + }, + }, + } +} diff --git a/src/types/products.ts b/src/types/products.ts index 590e6a5d98..55bd2ce04e 100644 --- a/src/types/products.ts +++ b/src/types/products.ts @@ -148,12 +148,19 @@ interface ProductData extends Product { } basePaths: string[] rootDocsPaths: RootDocsPath[] - instruqtId?: string playgroundConfig?: { sidebarLinks: { title: string href: string }[] + description?: string + labs?: { + id: string + name: string + instruqtId: string + description: string + products: ProductSlug[] + }[] } /** * When configuring docsNavItems, authors have the option to specify diff --git a/src/views/playground/server.ts b/src/views/playground/server.ts index db9656165e..7946817d24 100644 --- a/src/views/playground/server.ts +++ b/src/views/playground/server.ts @@ -28,13 +28,15 @@ export const getStaticProps: GetStaticProps = async ({ const productSlug = params?.productSlug as string const product = PRODUCT_DATA_MAP[productSlug] - // Only show playground page if product has an instruqtId - if (!product || !product.instruqtId) { + // Only show playground page if product has labs configured + if (!product || !product.playgroundConfig?.labs?.length) { return { notFound: true, } } + const defaultLab = product.playgroundConfig.labs[0] + const breadcrumbLinks = [ { title: 'Developer', url: '/' }, { title: product.name, url: `/${productSlug}` }, @@ -87,7 +89,7 @@ export const getStaticProps: GetStaticProps = async ({ return { props: { product, - labId: product.instruqtId, + labId: defaultLab.instruqtId, layoutProps: { breadcrumbLinks, navLevels: sidebarNavDataLevels, From 3543851e648a32ba9cde3cd5938fc87c3505085d Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 11 Mar 2025 10:03:54 -0700 Subject: [PATCH 03/53] update playground page to support multiple labs using the existing component --- src/contexts/instruqt-lab/index.tsx | 32 ++-- src/data/terraform.json | 2 +- src/data/vault.json | 2 +- .../playground/[playgroundId].tsx | 181 ------------------ src/pages/[productSlug]/playground/index.tsx | 69 ++++--- src/views/playground/index.tsx | 39 ---- src/views/playground/server.ts | 99 ---------- 7 files changed, 48 insertions(+), 376 deletions(-) delete mode 100644 src/pages/[productSlug]/playground/[playgroundId].tsx delete mode 100644 src/views/playground/index.tsx delete mode 100644 src/views/playground/server.ts diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index b2186eed93..b23f8f9989 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -24,7 +24,6 @@ interface InstruqtProviderProps { labId: string children: ReactNode defaultActive?: boolean - isPlayground?: boolean } const InstruqtContext = createContext>({}) @@ -37,30 +36,23 @@ export default function InstruqtProvider({ labId, children, defaultActive = false, - isPlayground = false, }: InstruqtProviderProps): JSX.Element { const [active, setActive] = useState(defaultActive) return ( - {isPlayground ? ( - children - ) : ( - <> - {children} - {active && ( -
- - - -
- )} - + {children} + {active && ( +
+ + + +
)} ) diff --git a/src/data/terraform.json b/src/data/terraform.json index 9bc211a2f7..dd7d9e82f5 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -173,7 +173,7 @@ "id": "create-infrastructure", "name": "Create Infrastructure", "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", - "description": "Learn how to create infrastructure with Terraform", + "description": "Learn how to create infrastructure", "products": ["terraform"] }, { diff --git a/src/data/vault.json b/src/data/vault.json index 4a4bd6190d..0fcad57b00 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -202,7 +202,7 @@ "id": "create-infrastructure", "name": "Create Infrastructure", "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", - "description": "Learn how to create infrastructure with Terraform", + "description": "Learn how to create infrastructure", "products": ["terraform"] } ] diff --git a/src/pages/[productSlug]/playground/[playgroundId].tsx b/src/pages/[productSlug]/playground/[playgroundId].tsx deleted file mode 100644 index ae10e1b731..0000000000 --- a/src/pages/[productSlug]/playground/[playgroundId].tsx +++ /dev/null @@ -1,181 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: MPL-2.0 - */ - -import { GetStaticPaths, GetStaticProps } from 'next' -import { PRODUCT_DATA_MAP } from 'data/product-data-map' -import SidebarSidecarLayout from 'layouts/sidebar-sidecar' -import InstruqtProvider from 'contexts/instruqt-lab' -import EmbedElement from 'components/lab-embed/embed-element' -import { - generateTopLevelSidebarNavData, - generateProductLandingSidebarNavData, -} from 'components/sidebar/helpers' - -interface PlaygroundPageProps { - product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] - playgroundId: string - playgroundName: string - playgroundDescription: string - layoutProps: { - breadcrumbLinks: { title: string; url: string }[] - navLevels: any[] - } -} - -export default function PlaygroundView({ - product, - playgroundId, - playgroundName, - playgroundDescription, - layoutProps, -}: PlaygroundPageProps) { - return ( - -
-

{playgroundName}

-

- {playgroundDescription} -

-
-
- - - -
- - ) -} - -export const getStaticPaths: GetStaticPaths = async () => { - const paths = [] - - // Generate paths for each product's playgrounds - Object.values(PRODUCT_DATA_MAP).forEach((product) => { - if (product.playgroundConfig?.labs) { - product.playgroundConfig.labs.forEach((playground) => { - paths.push({ - params: { - productSlug: product.slug, - playgroundId: playground.id, - }, - }) - }) - } - }) - - return { - paths, - fallback: false, - } -} - -export const getStaticProps: GetStaticProps = async ({ - params, -}) => { - const productSlug = params?.productSlug as string - const playgroundId = params?.playgroundId as string - const product = PRODUCT_DATA_MAP[productSlug] - - // Only show playground page if product has labs configured - if (!product || !product.playgroundConfig?.labs) { - return { - notFound: true, - } - } - - const playground = product.playgroundConfig.labs.find( - (p) => p.id === playgroundId - ) - if (!playground) { - return { - notFound: true, - } - } - - const breadcrumbLinks = [ - { title: 'Developer', url: '/' }, - { title: product.name, url: `/${productSlug}` }, - { title: 'Playground', url: `/${productSlug}/playground` }, - { - title: playground.name, - url: `/${productSlug}/playground/${playgroundId}`, - }, - ] - - const sidebarNavDataLevels = [ - generateTopLevelSidebarNavData(product.name), - generateProductLandingSidebarNavData(product), - ] - - // Add playground links - const playgroundMenuItems = [ - { - title: `${product.name} Playground`, - fullPath: `/${productSlug}/playground`, - theme: product.slug, - isActive: false, - }, - { - divider: true, - }, - { - heading: 'Playgrounds', - }, - ...product.playgroundConfig.labs.map((p) => ({ - title: p.name, - path: `/${productSlug}/playground/${p.id}`, - href: `/${productSlug}/playground/${p.id}`, - isActive: p.id === playgroundId, - })), - ] - - if (product.playgroundConfig.sidebarLinks) { - playgroundMenuItems.push( - { - divider: true, - }, - { - heading: 'Resources', - }, - ...product.playgroundConfig.sidebarLinks.map((link) => ({ - title: link.title, - path: link.href, - href: link.href, - isActive: false, - })) - ) - } - - sidebarNavDataLevels.push({ - backToLinkProps: { - text: `${product.name} Home`, - href: `/${product.slug}`, - }, - title: 'Playground', - menuItems: playgroundMenuItems, - showFilterInput: false, - visuallyHideTitle: true, - levelButtonProps: { - levelUpButtonText: `${product.name} Home`, - levelDownButtonText: 'Previous', - }, - }) - - return { - props: { - product, - playgroundId: playground.instruqtId, - playgroundName: playground.name, - playgroundDescription: playground.description, - layoutProps: { - breadcrumbLinks, - navLevels: sidebarNavDataLevels, - }, - }, - } -} diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index e32edd1d94..e80ec36d8a 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -4,22 +4,26 @@ */ import { GetStaticPaths, GetStaticProps } from 'next' +import { useState } from 'react' import { PRODUCT_DATA_MAP } from 'data/product-data-map' import SidebarSidecarLayout from 'layouts/sidebar-sidecar' +import InstruqtProvider from 'contexts/instruqt-lab' +import EmbedElement from 'components/lab-embed/embed-element' import { generateTopLevelSidebarNavData, generateProductLandingSidebarNavData, } from 'components/sidebar/helpers' -import CardLink from 'components/card-link' import { CardTitle, CardDescription, CardFooter, } from 'components/card/components' +import Card from 'components/card' import CardsGridList from 'components/cards-grid-list' import { BrandedHeaderCard } from 'views/product-integrations-landing/components/branded-header-card' import { CardBadges } from 'components/tutorial-collection-cards' import { ProductOption } from 'lib/learn-client/types' +import { MenuItem } from 'components/sidebar/types' interface PlaygroundPageProps { product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] @@ -33,6 +37,8 @@ export default function PlaygroundView({ product, layoutProps, }: PlaygroundPageProps) { + const [selectedPlayground, setSelectedPlayground] = useState(null) + return ( {product.playgroundConfig.labs.map((playground) => ( - setSelectedPlayground(playground)} + style={{ cursor: 'pointer' }} > - - {playground.description && ( - - )} - - ProductOption[slug] - )} - /> - - + + + {playground.description && ( + + )} + + ProductOption[slug] + )} + /> + + + ))} + + {selectedPlayground && ( +
+ + + +
+ )} ) } @@ -116,35 +132,18 @@ export const getStaticProps: GetStaticProps = async ({ ] // Add playground links - const playgroundMenuItems = [ + const playgroundMenuItems: MenuItem[] = [ { title: `${product.name} Playground`, fullPath: `/${productSlug}/playground`, theme: product.slug, isActive: true, }, - { - divider: true, - }, - { - heading: 'Playgrounds', - }, - ...product.playgroundConfig.labs.map((playground) => ({ - title: playground.name, - path: `/${productSlug}/playground/${playground.id}`, - href: `/${productSlug}/playground/${playground.id}`, - isActive: false, - })), ] if (product.playgroundConfig.sidebarLinks) { playgroundMenuItems.push( - { - divider: true, - }, - { - heading: 'Resources', - }, + { heading: 'Resources' }, ...product.playgroundConfig.sidebarLinks.map((link) => ({ title: link.title, path: link.href, diff --git a/src/views/playground/index.tsx b/src/views/playground/index.tsx deleted file mode 100644 index 3bd00f1228..0000000000 --- a/src/views/playground/index.tsx +++ /dev/null @@ -1,39 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: MPL-2.0 - */ - -import { ProductData } from 'types/products' -import { BreadcrumbLink } from 'components/breadcrumb-bar' -import { SidebarProps } from 'components/sidebar/types' -import SidebarSidecarLayout from 'layouts/sidebar-sidecar' -import InstruqtProvider from 'contexts/instruqt-lab' -import EmbedElement from 'components/lab-embed/embed-element' - -interface PlaygroundViewProps { - product: ProductData - labId: string - layoutProps: { - breadcrumbLinks: BreadcrumbLink[] - navLevels: SidebarProps[] - } -} - -export default function PlaygroundView({ - product, - labId, - layoutProps, -}: PlaygroundViewProps) { - return ( - -
- - - -
- - ) -} diff --git a/src/views/playground/server.ts b/src/views/playground/server.ts deleted file mode 100644 index 7946817d24..0000000000 --- a/src/views/playground/server.ts +++ /dev/null @@ -1,99 +0,0 @@ -/** - * Copyright (c) HashiCorp, Inc. - * SPDX-License-Identifier: MPL-2.0 - */ - -import { GetStaticProps } from 'next' -import { PRODUCT_DATA_MAP } from 'data/product-data-map' -import { ProductData } from 'types/products' -import { BreadcrumbLink } from 'components/breadcrumb-bar' -import { SidebarProps } from 'components/sidebar/types' -import { - generateTopLevelSidebarNavData, - generateProductLandingSidebarNavData, -} from 'components/sidebar/helpers' - -interface PlaygroundPageProps { - product: ProductData - labId: string - layoutProps: { - breadcrumbLinks: BreadcrumbLink[] - navLevels: SidebarProps[] - } -} - -export const getStaticProps: GetStaticProps = async ({ - params, -}) => { - const productSlug = params?.productSlug as string - const product = PRODUCT_DATA_MAP[productSlug] - - // Only show playground page if product has labs configured - if (!product || !product.playgroundConfig?.labs?.length) { - return { - notFound: true, - } - } - - const defaultLab = product.playgroundConfig.labs[0] - - const breadcrumbLinks = [ - { title: 'Developer', url: '/' }, - { title: product.name, url: `/${productSlug}` }, - { title: 'Playground', url: `/${productSlug}/playground` }, - ] - - const sidebarNavDataLevels = [ - generateTopLevelSidebarNavData(product.name), - generateProductLandingSidebarNavData(product), - ] - - // Add playground links if configured - if (product.playgroundConfig?.sidebarLinks) { - const playgroundMenuItems = [ - { - title: `${product.name} Playground`, - fullPath: `/${productSlug}/playground`, - theme: product.slug, - isActive: true, - }, - { - divider: true, - }, - { - heading: 'Resources', - }, - ...product.playgroundConfig.sidebarLinks.map((link) => ({ - title: link.title, - path: link.href, - href: link.href, - isActive: false, - })), - ] - sidebarNavDataLevels.push({ - backToLinkProps: { - text: `${product.name} Home`, - href: `/${product.slug}`, - }, - title: 'Playground', - menuItems: playgroundMenuItems, - showFilterInput: false, - visuallyHideTitle: true, - levelButtonProps: { - levelUpButtonText: `${product.name} Home`, - levelDownButtonText: 'Previous', - }, - }) - } - - return { - props: { - product, - labId: defaultLab.instruqtId, - layoutProps: { - breadcrumbLinks, - navLevels: sidebarNavDataLevels, - }, - }, - } -} From 2e947f87445fa6dac5e6c9978b53359de6e1ce40 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 11 Mar 2025 10:09:08 -0700 Subject: [PATCH 04/53] fix playground bug --- src/contexts/instruqt-lab/index.tsx | 2 +- src/pages/[productSlug]/playground/index.tsx | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index b23f8f9989..ec014a6a87 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -22,7 +22,7 @@ interface InstruqtContextProps { interface InstruqtProviderProps { labId: string - children: ReactNode + children?: ReactNode defaultActive?: boolean } diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index e80ec36d8a..479cee0289 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -84,9 +84,10 @@ export default function PlaygroundView({ {selectedPlayground && (
- - - +
)} From c438edc81f485b9a12ee88704bf4e2daadd5bfe3 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 11 Mar 2025 10:52:53 -0700 Subject: [PATCH 05/53] update terraform sandbox --- src/data/terraform.json | 15 ++++----------- src/data/vault.json | 8 ++++---- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/src/data/terraform.json b/src/data/terraform.json index dd7d9e82f5..c2b823d2a0 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -170,18 +170,11 @@ ], "labs": [ { - "id": "create-infrastructure", - "name": "Create Infrastructure", - "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", - "description": "Learn how to create infrastructure", + "id": "terraform-sandbox", + "name": "Terraform Sandbox", + "instruqtId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE", + "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", "products": ["terraform"] - }, - { - "id": "vault-sandbox", - "name": "Vault Playground (test)", - "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", - "description": "Learn how to manage your secrets with Vault", - "products": ["vault"] } ] } diff --git a/src/data/vault.json b/src/data/vault.json index 0fcad57b00..7643c207e7 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -199,10 +199,10 @@ "products": ["vault"] }, { - "id": "create-infrastructure", - "name": "Create Infrastructure", - "instruqtId": "hashicorp-learn/tracks/create-terraform-infrastructure?token=em__EA8k5ywxqiOejXd", - "description": "Learn how to create infrastructure", + "id": "terraform-sandbox", + "name": "Terraform Sandbox", + "instruqtId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE", + "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", "products": ["terraform"] } ] From f2768b010a2808b8b8c4ecd67a77efcfd600b973 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 11 Mar 2025 14:15:10 -0700 Subject: [PATCH 06/53] embed terminal persist across pages --- .../dropdown-menu/dropdown-menu.module.css | 2 +- .../components/playground-dropdown/index.tsx | 315 ++++++++++++++++++ .../playground-dropdown.module.css | 166 +++++++++ .../components/playground-item/index.tsx | 78 +++++ .../playground-item.module.css | 63 ++++ .../components/product-page-content/index.tsx | 21 ++ .../utils/get-nav-items.ts | 16 +- src/contexts/instruqt-lab/index.tsx | 83 ++++- src/data/playground-config.json | 54 +-- src/data/playground.json | 86 +++++ src/data/terraform.json | 9 - src/data/vault.json | 16 - src/pages/[productSlug]/playground/index.tsx | 206 +++++++++--- .../playground/playground.module.css | 115 +++++++ src/pages/_app.tsx | 31 +- src/views/tutorial-view/index.tsx | 29 +- 16 files changed, 1163 insertions(+), 127 deletions(-) create mode 100644 src/components/navigation-header/components/playground-dropdown/index.tsx create mode 100644 src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css create mode 100644 src/components/navigation-header/components/playground-item/index.tsx create mode 100644 src/components/navigation-header/components/playground-item/playground-item.module.css create mode 100644 src/data/playground.json create mode 100644 src/pages/[productSlug]/playground/playground.module.css diff --git a/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css b/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css index 2ad48faf30..c54d2b3ae7 100644 --- a/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css +++ b/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css @@ -91,7 +91,7 @@ } .itemGroupLabel { - margin-bottom: 12px; + margin-bottom: 8px; padding-left: 8px; padding-right: 8px; } diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/playground-dropdown/index.tsx new file mode 100644 index 0000000000..dca9c75b1e --- /dev/null +++ b/src/components/navigation-header/components/playground-dropdown/index.tsx @@ -0,0 +1,315 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { Fragment, KeyboardEvent, useRef, useState } from 'react' +import { useId } from '@react-aria/utils' +import classNames from 'classnames' +import { IconChevronDown16 } from '@hashicorp/flight-icons/svg-react/chevron-down-16' +import { IconArrowRight16 } from '@hashicorp/flight-icons/svg-react/arrow-right-16' +import { IconChevronRight16 } from '@hashicorp/flight-icons/svg-react/chevron-right-16' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import useOnClickOutside from 'hooks/use-on-click-outside' +import useOnEscapeKeyDown from 'hooks/use-on-escape-key-down' +import useOnFocusOutside from 'hooks/use-on-focus-outside' +import useOnRouteChangeStart from 'hooks/use-on-route-change-start' +import { useRouter } from 'next/router' +import { useCurrentProduct } from 'contexts' +import Text from 'components/text' +import PlaygroundItem from '../playground-item' +import { + NavigationHeaderIcon, + NavigationHeaderItem, +} from 'components/navigation-header/types' +import { ProductSlug } from 'types/products' +import PLAYGROUND_CONFIG from 'data/playground-config.json' +import s from './playground-dropdown.module.css' + +// Define the type to match the structure in playground-config.json +type PlaygroundLab = { + id?: string + labId: string + title: string + description: string + products: string[] +} + +interface PlaygroundDropdownProps { + ariaLabel: string + label: string +} + +const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { + const uniqueId = useId() + const router = useRouter() + const currentProduct = useCurrentProduct() + const { openLab } = useInstruqtEmbed() + const menuRef = useRef() + const activatorButtonRef = useRef() + const [isOpen, setIsOpen] = useState(false) + const [otherPlaygroundsOpen, setOtherPlaygroundsOpen] = useState(false) + const menuId = `playground-dropdown-menu-${uniqueId}` + + // Item data from playground config + const labs = PLAYGROUND_CONFIG.labs as PlaygroundLab[] + + // Filter labs for current product and other products + const currentProductLabs = labs.filter((lab) => + lab.products.includes(currentProduct.slug) + ) + + const otherProductLabs = labs.filter( + (lab) => !lab.products.includes(currentProduct.slug) + ) + + // Handles closing the menu if there is a click outside of it and it is open. + useOnClickOutside([menuRef], () => setIsOpen(false), isOpen) + + // Handles closing the menu if focus moves outside of it and it is open. + useOnFocusOutside([menuRef], () => setIsOpen(false), isOpen) + + // Handles closing the menu if Esc is pressed while navigating with a keyboard and the menu is focused. + useOnEscapeKeyDown( + [menuRef], + () => { + setIsOpen(false) + activatorButtonRef.current.focus() + }, + isOpen + ) + + // if the disclosure is open, handle closing it on `routeChangeStart` + useOnRouteChangeStart({ + handler: () => setIsOpen(false), + shouldListen: isOpen, + }) + + /** + * Handles the menu being activated via a hover. + * Opens the menu. + */ + const handleMouseEnter = () => { + setIsOpen(true) + } + + /** + * Handles a keydown event on the activator button. + * Opens the menu for specific keystroke patterns. + */ + const handleKeyDown = (event: KeyboardEvent) => { + if (!isOpen) { + const { isDown, isEnter, isSpace } = deriveKeyEventState(event) + if (isDown || isEnter || isSpace) { + event.preventDefault() + setIsOpen(true) + } + } + } + + /** + * Handle lab selection + */ + const handleLabClick = (lab: PlaygroundLab) => { + openLab(lab.labId) + setIsOpen(false) + } + + /** + * Navigate to the playground page when clicking on the label + */ + const handleLabelClick = (e: React.MouseEvent) => { + e.preventDefault() + e.stopPropagation() + router.push(`/${currentProduct.slug}/playground`) + } + + /** + * Navigate to the playground page + */ + const navigateToPlaygroundPage = (e: React.MouseEvent) => { + e.preventDefault() + router.push(`/${currentProduct.slug}/playground`) + setIsOpen(false) + } + + /** + * Toggle the other playgrounds accordion + */ + const toggleOtherPlaygrounds = (e: React.MouseEvent) => { + e.preventDefault() + setOtherPlaygroundsOpen(!otherPlaygroundsOpen) + } + + return ( +
setIsOpen(false)} + > +
+ +
+
+
+ {/* Introduction to Playgrounds */} +
+ + HashiCorp Playgrounds + + + Interactive environments where you can experiment with HashiCorp + products without any installation or setup. Perfect for learning, + testing, and exploring features in a safe sandbox. + + + {/* Learn more link */} + + + Learn more about Playgrounds + + + +
+ + {/* Divider */} +
+ + {/* Available Product Playgrounds Section */} + + Available {currentProduct.name} Playgrounds + + +
    + {currentProductLabs.map((lab, index) => ( +
  • + handleLabClick(lab), + }} + /> +
    • + ))} +
+ + {/* Other Playgrounds Accordion (only show if there are other playgrounds) */} + {otherProductLabs.length > 0 && ( + <> +
+ + + + {otherPlaygroundsOpen && ( +
    + {otherProductLabs.map((lab, index) => ( +
  • + handleLabClick(lab), + }} + /> +
    • + ))} +
+ )} + + )} +
+
+
+ ) +} + +export default PlaygroundDropdown + +// Helper function extracted from NavigationHeaderDropdownMenu +function deriveKeyEventState(event: KeyboardEvent) { + const isDown = event.key === 'ArrowDown' + const isUp = event.key === 'ArrowUp' + const isLeft = event.key === 'ArrowLeft' + const isRight = event.key === 'ArrowRight' + const isEnter = event.key === 'Enter' + const isEscape = event.key === 'Escape' + const isHome = event.key === 'Home' + const isEnd = event.key === 'End' + const isSpace = event.key === ' ' + const isTab = event.key === 'Tab' + + return { + isDown, + isUp, + isLeft, + isRight, + isEnter, + isEscape, + isHome, + isEnd, + isSpace, + isTab, + } +} diff --git a/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css b/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css new file mode 100644 index 0000000000..9bc0791f26 --- /dev/null +++ b/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css @@ -0,0 +1,166 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +.root { + position: relative; + display: inline-block; +} + +.activatorContainer { + display: inline-flex; + padding-bottom: 16px; + padding-top: 16px; +} + +.activator { + display: flex; + align-items: center; + gap: 6px; + background: transparent; + border: none; + cursor: pointer; + padding: 8px 10px; + border-radius: 5px; + color: var(--token-color-foreground-primary); + font-size: 0.875rem; + font-weight: 500; +} + +.label { + font-size: 0.875rem; + font-weight: 500; + color: var(--token-color-foreground-primary); + transition: color 0.2s; + + .activator:hover &, + .activator:focus &, + .activator[aria-expanded='true'] & { + color: var(--token-color-foreground-strong); + } +} + +.activatorTrailingIcon { + width: 16px; + height: 16px; + display: inline-block; + color: var(--token-color-foreground-strong); + transition: transform 0.2s ease-in-out; + + .activator[aria-expanded='true'] & { + transform: rotate(180deg); + } +} + +.dropdownContainer { + position: absolute; + top: 100%; + left: 0; + background-color: var(--token-color-surface-primary); + border-radius: 6px; + box-shadow: var(--token-elevation-higher-box-shadow); + z-index: -1; + margin-top: 0; + min-width: 32rem; + max-height: 80vh; + overflow-y: auto; +} + +.dropdownContainerInner { + padding: 16px; +} + +.introSection { + margin-bottom: 16px; +} + +.sectionTitle { + margin-bottom: 8px; + color: var(--token-color-foreground-strong); +} + +.introText { + color: var(--token-color-foreground-primary); + max-width: 90%; + line-height: 1.5; + margin-bottom: 8px; +} + +.divider { + border: none; + height: 1px; + background-color: var(--token-color-border-primary); + margin: 16px 0; +} + +.labsList { + list-style: none; + padding: 0; + margin: 12px 0 0 0; + display: flex; + flex-direction: column; +} + +.itemContainer { + margin: 0; + padding: 0; +} + +.learnMoreLink { + display: flex; + align-items: center; + gap: 6px; + padding: 4px 0; + text-decoration: none; + color: var(--token-color-foreground-primary); + transition: color 0.2s; + font-size: 0.875rem; + + &:hover, + &:focus { + color: var(--token-color-foreground-strong); + text-decoration: none; + } +} + +.learnMoreIcon { + width: 14px; + height: 14px; + color: var(--token-color-foreground-primary); + transition: transform 0.2s, color 0.2s; + + .learnMoreLink:hover &, + .learnMoreLink:focus & { + transform: translateX(4px); + color: var(--token-color-foreground-strong); + } +} + +.accordionButton { + display: flex; + align-items: center; + justify-content: space-between; + width: 100%; + background: transparent; + border: none; + padding: 8px 0; + cursor: pointer; + text-align: left; + + &:hover .sectionTitle, + &:focus .sectionTitle { + color: var(--token-color-foreground-strong); + } +} + +.accordionIcon { + width: 16px; + height: 16px; + color: var(--token-color-foreground-primary); + transition: transform 0.2s ease-in-out; +} + +.accordionIconOpen { + transform: rotate(90deg); +} diff --git a/src/components/navigation-header/components/playground-item/index.tsx b/src/components/navigation-header/components/playground-item/index.tsx new file mode 100644 index 0000000000..2c75dc09f3 --- /dev/null +++ b/src/components/navigation-header/components/playground-item/index.tsx @@ -0,0 +1,78 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { useCallback } from 'react' +import ProductIcon from 'components/product-icon' +import Text from 'components/text' +import { NavigationHeaderIcon } from 'components/navigation-header/types' +import { ProductSlug } from 'types/products' +import s from './playground-item.module.css' + +interface PlaygroundItemProps { + item: { + label: string + description: string + icon?: NavigationHeaderIcon + products: string[] + path?: string + ariaLabel?: string + labId: string + onClick?: () => void + } +} + +const PlaygroundItem = ({ item }: PlaygroundItemProps) => { + const { label, description, products, onClick } = item + + const handleClick = useCallback( + (e) => { + e.preventDefault() + onClick?.() + }, + [onClick] + ) + + return ( + +
+
+ + {label} + +
+ {products.map((product, index) => ( + + ))} +
+
+ + {description} + +
+ + ) +} + +export default PlaygroundItem diff --git a/src/components/navigation-header/components/playground-item/playground-item.module.css b/src/components/navigation-header/components/playground-item/playground-item.module.css new file mode 100644 index 0000000000..36aa3d8325 --- /dev/null +++ b/src/components/navigation-header/components/playground-item/playground-item.module.css @@ -0,0 +1,63 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +.playgroundItem { + align-items: flex-start; + border-radius: 5px; + color: var(--token-color-foreground-primary); + display: flex; + padding: 8px; + text-decoration: none; + width: 100%; + + &:not(:last-child) { + margin-bottom: 2px; + } + + &:hover { + background-color: var(--token-color-surface-faint); + + & .title { + color: var(--token-color-foreground-strong); + } + } +} + +.content { + display: flex; + flex-direction: column; + flex: 1; +} + +.titleRow { + display: flex; + align-items: center; + width: 100%; +} + +.title { + color: var(--token-color-foreground-primary); + font-size: 0.9375rem; +} + +.description { + color: var(--token-color-foreground-primary); + opacity: 0.8; + margin-top: 4px; + font-size: 0.875rem; +} + +.productIcons { + display: flex; + gap: 4px; + align-items: center; + margin-left: 8px; + + & .productIcon { + width: 16px; + height: 16px; + color: var(--token-color-foreground-faint); + } +} diff --git a/src/components/navigation-header/components/product-page-content/index.tsx b/src/components/navigation-header/components/product-page-content/index.tsx index d79ef52322..7280c311f7 100644 --- a/src/components/navigation-header/components/product-page-content/index.tsx +++ b/src/components/navigation-header/components/product-page-content/index.tsx @@ -9,6 +9,8 @@ import { IconHashicorp24 } from '@hashicorp/flight-icons/svg-react/hashicorp-24' // Global imports import { useCurrentProduct } from 'contexts' import * as NavigationMenu from '@radix-ui/react-navigation-menu' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import PLAYGROUND_CONFIG from 'data/playground-config.json' // Local imports import { @@ -20,6 +22,7 @@ import { import { ProductIconTextLink } from './components' import { getNavItems, getProductsDropdownItems, NavItem } from './utils' import { navigationData, navPromo, sidePanelContent } from 'lib/products' +import PlaygroundDropdown from '../playground-dropdown' import s from './product-page-content.module.css' const ProductPageHeaderContent = () => { @@ -27,6 +30,12 @@ const ProductPageHeaderContent = () => { const allProductsItems = getProductsDropdownItems() const productNavItems = getNavItems(currentProduct) + // Check if the current product has playground support + const supportedPlaygroundProducts = PLAYGROUND_CONFIG.products || [] + const hasPlayground = + PLAYGROUND_CONFIG.labs?.length > 0 && + supportedPlaygroundProducts.includes(currentProduct.slug) + return ( <>
@@ -54,6 +63,18 @@ const ProductPageHeaderContent = () => { {productNavItems.map((navItem: NavItem) => { const ariaLabel = `${currentProduct.name} ${navItem.label}` const isSubmenu = 'items' in navItem + const isPlayground = navItem.label === 'Playground' + + if (isPlayground && hasPlayground) { + return ( +
  • + +
    • + ) + } return (
  • diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index 114862afe2..104605d570 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -3,11 +3,15 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { NavigationHeaderIcon } from 'components/navigation-header/types' +import { + NavigationHeaderIcon, + NavigationHeaderItem, +} from 'components/navigation-header/types' import { getDocsNavItems } from 'lib/docs/get-docs-nav-items' import { getIsEnabledProductIntegrations } from 'lib/integrations/get-is-enabled-product-integrations' import { ProductData } from 'types/products' import { NavItem } from './types' +import PLAYGROUND_CONFIG from 'data/playground-config.json' const TRY_CLOUD_ITEM_PRODUCT_SLUGS = [ 'boundary', @@ -146,7 +150,15 @@ export function getNavItems(currentProduct: ProductData): NavItem[] { } } - if (currentProduct.playgroundConfig?.labs?.length) { + /** + * Add Playground item if there are any labs configured + * and the current product is in the supported products list + */ + const supportedPlaygroundProducts = PLAYGROUND_CONFIG.products || [] + if ( + PLAYGROUND_CONFIG.labs?.length && + supportedPlaygroundProducts.includes(currentProduct.slug) + ) { items.push({ label: 'Playground', url: `/${currentProduct.slug}/playground`, diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index ec014a6a87..b726c7e9ad 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -10,39 +10,91 @@ import { ReactNode, Dispatch, SetStateAction, + useEffect, + useCallback, } from 'react' +import dynamic from 'next/dynamic' import EmbedElement from 'components/lab-embed/embed-element' import Resizable from 'components/lab-embed/resizable' interface InstruqtContextProps { - labId: string + labId: string | null active: boolean setActive: Dispatch> + openLab: (labId: string) => void + closeLab: () => void } interface InstruqtProviderProps { - labId: string children?: ReactNode - defaultActive?: boolean } -const InstruqtContext = createContext>({}) +const STORAGE_KEY = 'instruqt-lab-state' + +const InstruqtContext = createContext({ + labId: null, + active: false, + setActive: () => {}, + openLab: () => {}, + closeLab: () => {}, +}) InstruqtContext.displayName = 'InstruqtContext' -export const useInstruqtEmbed = (): Partial => +export const useInstruqtEmbed = (): InstruqtContextProps => useContext(InstruqtContext) -export default function InstruqtProvider({ - labId, - children, - defaultActive = false, -}: InstruqtProviderProps): JSX.Element { - const [active, setActive] = useState(defaultActive) +function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { + const [isClient, setIsClient] = useState(false) + const [labId, setLabId] = useState(null) + const [active, setActive] = useState(false) + + // Only run on client side + useEffect(() => { + setIsClient(true) + try { + const stored = localStorage.getItem(STORAGE_KEY) + if (stored) { + const { active: storedActive, storedLabId } = JSON.parse(stored) + setLabId(storedLabId) + setActive(storedActive) + } + } catch (e) { + console.warn('Failed to restore Instruqt lab state:', e) + } + }, []) + + // Persist state changes to localStorage + useEffect(() => { + if (!isClient) return + + try { + localStorage.setItem( + STORAGE_KEY, + JSON.stringify({ + active, + storedLabId: labId, + }) + ) + } catch (e) { + console.warn('Failed to persist Instruqt lab state:', e) + } + }, [active, labId, isClient]) + + const openLab = useCallback((newLabId: string) => { + setLabId(newLabId) + setActive(true) + }, []) + + const closeLab = useCallback(() => { + setActive(false) + }, []) return ( - + {children} - {active && ( + {isClient && active && labId && (
    ) } + +// Export a client-side only version of the provider +export default dynamic(() => Promise.resolve(InstruqtProvider), { + ssr: false, +}) diff --git a/src/data/playground-config.json b/src/data/playground-config.json index 90a660ebda..a0ad7d0316 100644 --- a/src/data/playground-config.json +++ b/src/data/playground-config.json @@ -1,23 +1,35 @@ { - "terraform": { - "labId": "hashicorp-learn/tracks/terraform-build-your-first-configuration" - }, - "vault": { - "labId": "hashicorp-learn/tracks/vault-basics" - }, - "consul": { - "labId": "hashicorp-learn/tracks/consul-template-automate-reverse-proxy-config" - }, - "nomad": { - "labId": "hashicorp-learn/tracks/nomad-basics" - }, - "packer": { - "labId": "hashicorp-learn/tracks/packer-get-started-hcp" - }, - "waypoint": { - "labId": "hashicorp-learn/tracks/waypoint-get-started-docker" - }, - "boundary": { - "labId": "hashicorp-learn/tracks/boundary-basics" - } + "products": ["terraform", "vault", "consul", "nomad"], + "labs": [ + { + "title": "Terraform Sandbox", + "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", + "products": ["terraform"], + "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE" + }, + { + "title": "Vault Playground (test)", + "description": "Learn how to manage your secrets with Vault", + "products": ["vault"], + "labId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB" + }, + { + "title": "Nomad sandbox", + "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", + "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", + "products": ["nomad", "consul"] + }, + { + "title": "Sandbox environment for Consul (Service discovery)", + "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", + "labId": "/hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", + "products": ["consul"] + }, + { + "title": "Sandbox environment for Consul (Service mesh)", + "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", + "labId": "/hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM", + "products": ["consul"] + } + ] } diff --git a/src/data/playground.json b/src/data/playground.json new file mode 100644 index 0000000000..43deafbc2b --- /dev/null +++ b/src/data/playground.json @@ -0,0 +1,86 @@ +{ + "terraform": { + "description": "Learn infrastructure as code with hands-on labs", + "labs": [ + { + "id": "terraform-basics", + "labId": "hashicorp-learn/tracks/terraform-build-your-first-configuration", + "title": "Build Your First Configuration", + "description": "Learn the basics of Terraform configuration language", + "products": ["terraform"] + } + ] + }, + "vault": { + "description": "Explore secrets management and data protection", + "labs": [ + { + "id": "vault-basics", + "labId": "hashicorp-learn/tracks/vault-basics", + "title": "Vault Basics", + "description": "Learn the fundamentals of HashiCorp Vault", + "products": ["vault"] + } + ] + }, + "consul": { + "description": "Practice service networking and discovery", + "labs": [ + { + "id": "consul-template", + "labId": "hashicorp-learn/tracks/consul-template-automate-reverse-proxy-config", + "title": "Automate Reverse Proxy Configuration", + "description": "Learn to automate proxy configuration with Consul Template", + "products": ["consul"] + } + ] + }, + "nomad": { + "description": "Get started with workload orchestration", + "labs": [ + { + "id": "nomad-basics", + "labId": "hashicorp-learn/tracks/nomad-basics", + "title": "Nomad Basics", + "description": "Learn the basics of HashiCorp Nomad", + "products": ["nomad"] + } + ] + }, + "packer": { + "description": "Learn machine image automation", + "labs": [ + { + "id": "packer-hcp", + "labId": "hashicorp-learn/tracks/packer-get-started-hcp", + "title": "Get Started with HCP Packer", + "description": "Build and manage machine images with HCP Packer", + "products": ["packer"] + } + ] + }, + "waypoint": { + "description": "Explore application deployment patterns", + "labs": [ + { + "id": "waypoint-docker", + "labId": "hashicorp-learn/tracks/waypoint-get-started-docker", + "title": "Get Started with Docker", + "description": "Deploy applications with Waypoint and Docker", + "products": ["waypoint"] + } + ] + }, + "boundary": { + "description": "Practice secure remote access", + "labs": [ + { + "id": "boundary-basics", + "labId": "hashicorp-learn/tracks/boundary-basics", + "title": "Boundary Basics", + "description": "Learn the fundamentals of HashiCorp Boundary", + "products": ["boundary"] + } + ] + } +} diff --git a/src/data/terraform.json b/src/data/terraform.json index c2b823d2a0..f6ebddc5ae 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -167,15 +167,6 @@ "title": "Terraform documentation", "href": "/terraform/docs" } - ], - "labs": [ - { - "id": "terraform-sandbox", - "name": "Terraform Sandbox", - "instruqtId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE", - "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", - "products": ["terraform"] - } ] } } diff --git a/src/data/vault.json b/src/data/vault.json index 7643c207e7..17b820473c 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -189,22 +189,6 @@ "title": "Vault Documentation", "href": "/vault/docs" } - ], - "labs": [ - { - "id": "vault-sandbox", - "name": "Vault Playground (test)", - "instruqtId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB", - "description": "Learn how to manage your secrets with Vault", - "products": ["vault"] - }, - { - "id": "terraform-sandbox", - "name": "Terraform Sandbox", - "instruqtId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE", - "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", - "products": ["terraform"] - } ] } } diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index 479cee0289..687d09e062 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -4,11 +4,10 @@ */ import { GetStaticPaths, GetStaticProps } from 'next' -import { useState } from 'react' +import { useState, useEffect, useMemo } from 'react' import { PRODUCT_DATA_MAP } from 'data/product-data-map' import SidebarSidecarLayout from 'layouts/sidebar-sidecar' -import InstruqtProvider from 'contexts/instruqt-lab' -import EmbedElement from 'components/lab-embed/embed-element' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' import { generateTopLevelSidebarNavData, generateProductLandingSidebarNavData, @@ -24,6 +23,10 @@ import { BrandedHeaderCard } from 'views/product-integrations-landing/components import { CardBadges } from 'components/tutorial-collection-cards' import { ProductOption } from 'lib/learn-client/types' import { MenuItem } from 'components/sidebar/types' +import { ProductSlug } from 'types/products' +import PLAYGROUND_CONFIG from 'data/playground-config.json' +import ProductIcon from 'components/product-icon' +import s from './playground.module.css' interface PlaygroundPageProps { product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] @@ -31,13 +34,31 @@ interface PlaygroundPageProps { breadcrumbLinks: { title: string; url: string }[] navLevels: any[] } + availablePlaygrounds: { + title: string + description: string + products: string[] + labId: string + }[] + otherPlaygrounds: { + title: string + description: string + products: string[] + labId: string + }[] } export default function PlaygroundView({ product, layoutProps, + availablePlaygrounds, + otherPlaygrounds, }: PlaygroundPageProps) { - const [selectedPlayground, setSelectedPlayground] = useState(null) + const { openLab } = useInstruqtEmbed() + + const handleLabClick = (labId: string) => { + openLab(labId) + } return ( - {product.playgroundConfig.description && ( -

    - {product.playgroundConfig.description} +

    +

    + HashiCorp Playgrounds provide interactive environments where you can + experiment with HashiCorp products without any installation or setup. + They're perfect for:

    - )} -
    - - {product.playgroundConfig.labs.map((playground) => ( +
      +
    • Learning how products work in a real environment
      • +
    • + Testing configurations and commands without affecting your systems +
      • +
    • Exploring product features in a safe sandbox
      • +
    • Following along with tutorials and documentation
      • +
    + +

    + Each playground comes pre-configured with everything you need to start + using the product immediately. Just click on a playground below to + launch it in your browser. +

    + + {/*
    +

    Getting Started

    +

    + When you launch a playground, you'll be presented with a terminal interface where you can + interact with the pre-configured environment. The playground runs in your browser and + doesn't require any downloads or installations. +

    +

    + Each playground session lasts for up to 1 hour, giving you plenty of time to experiment. + Your work isn't saved between sessions, so be sure to copy any important configurations + before your session ends. +

    +
    */} +
    + +

    Available {product.name} playgrounds

    + +

    + When you launch a playground, you'll be presented with a terminal + interface where you can interact with the pre-configured environment. + The playground runs in your browser and doesn't require any downloads or + installations. +

    +

    + Each playground session lasts for up to 1 hour, giving you plenty of + time to experiment. Your work isn't saved between sessions, so be sure + to copy any important configurations before your session ends. +

    + + {availablePlaygrounds.length > 0 ? ( + + {availablePlaygrounds.map((lab, index) => (
    setSelectedPlayground(playground)} - style={{ cursor: 'pointer' }} + key={index} + className={s.playgroundCard} + onClick={() => handleLabClick(lab.labId)} > - - {playground.description && ( - - )} +
    + +
    + {lab.products.map((productSlug, idx) => ( + + ))} +
    +
    + - ProductOption[slug] - )} - /> +
    ))}     -
    + ) : ( +

    + There are currently no playgrounds available for {product.name}. Check + back later or explore other product playgrounds. +

    + )} - {selectedPlayground && ( -
    - -
    + {otherPlaygrounds.length > 0 && ( + <> +

    Other playgrounds

    +

    + Explore playgrounds for other HashiCorp products that you might find + useful. +

    + + + {otherPlaygrounds.map((lab, index) => ( +
    handleLabClick(lab.labId)} + > + +
    + +
    + {lab.products.map((productSlug, idx) => ( + + ))} +
    +
    + + + + +     +
    + ))} +     + )}     ) } export const getStaticPaths: GetStaticPaths = async () => { - // Only generate paths for products that have labs configured - const paths = Object.values(PRODUCT_DATA_MAP) - .filter((product) => product.playgroundConfig?.labs) - .map((product) => ({ - params: { productSlug: product.slug }, + // Get the list of supported products from playground-config.json + const supportedProducts = PLAYGROUND_CONFIG.products || [] + + // Generate paths for all products that are in the supported products list + const paths = supportedProducts + .filter((productSlug) => PRODUCT_DATA_MAP[productSlug]) // Ensure the product exists in PRODUCT_DATA_MAP + .map((productSlug) => ({ + params: { productSlug }, })) return { @@ -113,14 +226,25 @@ export const getStaticProps: GetStaticProps = async ({ }) => { const productSlug = params?.productSlug as string const product = PRODUCT_DATA_MAP[productSlug] + const supportedProducts = PLAYGROUND_CONFIG.products || [] - // Only show playground page if product has labs configured - if (!product || !product.playgroundConfig?.labs) { + // Only show playground page if product is in the supported products list + if (!product || !supportedProducts.includes(productSlug)) { return { notFound: true, } } + // Filter playgrounds that are relevant to this product + const availablePlaygrounds = PLAYGROUND_CONFIG.labs.filter((lab) => + lab.products.includes(productSlug) + ) + + // Filter playgrounds that are NOT relevant to this product + const otherPlaygrounds = PLAYGROUND_CONFIG.labs.filter( + (lab) => !lab.products.includes(productSlug) + ) + const breadcrumbLinks = [ { title: 'Developer', url: '/' }, { title: product.name, url: `/${productSlug}` }, @@ -142,7 +266,7 @@ export const getStaticProps: GetStaticProps = async ({ }, ] - if (product.playgroundConfig.sidebarLinks) { + if (product.playgroundConfig?.sidebarLinks) { playgroundMenuItems.push( { heading: 'Resources' }, ...product.playgroundConfig.sidebarLinks.map((link) => ({ @@ -176,6 +300,8 @@ export const getStaticProps: GetStaticProps = async ({ breadcrumbLinks, navLevels: sidebarNavDataLevels, }, + availablePlaygrounds, + otherPlaygrounds, }, } } diff --git a/src/pages/[productSlug]/playground/playground.module.css b/src/pages/[productSlug]/playground/playground.module.css new file mode 100644 index 0000000000..6f5546e12c --- /dev/null +++ b/src/pages/[productSlug]/playground/playground.module.css @@ -0,0 +1,115 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +.menuContainer { + margin-top: 32px; + display: flex; + justify-content: center; +} + +.playgroundDropdown { + min-width: 480px; + max-height: 80vh; + overflow-y: auto; +} + +.playgroundIntro { + margin: 32px 0; +} + +.sectionHeading { + font-size: 1.5rem; + font-weight: 600; + margin-bottom: 16px; + color: var(--token-color-foreground-strong); +} + +.subSectionHeading { + font-size: 1.25rem; + font-weight: 600; + margin-bottom: 12px; + color: var(--token-color-foreground-strong); +} + +.introText { + font-size: 1rem; + line-height: 1.6; + margin-bottom: 16px; + color: var(--token-color-foreground-primary); +} + +.featureList { + margin: 16px 0; + padding-left: 24px; + + & li { + margin-bottom: 8px; + line-height: 1.5; + } +} + +.gettingStartedInfo { + margin-top: 32px; + padding-top: 24px; +} + +.playgroundCard { + cursor: pointer; + transition: transform 0.2s ease, box-shadow 0.2s ease; + + &:hover { + transform: translateY(-2px); + box-shadow: var(--token-elevation-high-box-shadow); + } +} + +.cardHeader { + display: flex; + justify-content: space-between; + align-items: flex-start; + margin-bottom: 8px; +} + +.productIcons { + display: flex; + gap: 4px; + margin-left: 12px; +} + +.productIcon { + color: var(--token-color-foreground-faint); +} + +.launchButton { + background-color: var(--token-color-palette-neutral-200); + border: none; + border-radius: 4px; + padding: 8px 16px; + font-size: 0.875rem; + font-weight: 500; + color: var(--token-color-foreground-primary); + cursor: pointer; + transition: background-color 0.2s ease; + + &:hover { + background-color: var(--token-color-palette-neutral-300); + } +} + +.noPlaygrounds { + margin: 32px 0; + padding: 24px; + background-color: var(--token-color-surface-faint); + border-radius: 4px; + text-align: center; + color: var(--token-color-foreground-primary); +} + +.helpText { + font-size: 1rem; + line-height: 1.6; + margin-bottom: 16px; + color: var(--token-color-foreground-primary); +} diff --git a/src/pages/_app.tsx b/src/pages/_app.tsx index a3a33283b8..627ea2edaf 100644 --- a/src/pages/_app.tsx +++ b/src/pages/_app.tsx @@ -28,6 +28,7 @@ import useAnchorLinkAnalytics from '@hashicorp/platform-util/anchor-link-analyti // Global imports import { CurrentProductProvider, DeviceSizeProvider } from 'contexts' +import InstruqtProvider from 'contexts/instruqt-lab' import { makeDevAnalyticsLogger } from 'lib/analytics' import { DevDotClient } from 'views/error-views' import HeadMetadata from 'components/head-metadata' @@ -86,20 +87,22 @@ export default function App({ - - - import('lib/framer-motion-features').then( - (mod) => mod.default - ) - } - strict={process.env.NODE_ENV === 'development'} - > - - - - - + + + + import('lib/framer-motion-features').then( + (mod) => mod.default + ) + } + strict={process.env.NODE_ENV === 'development'} + > + + + + + + diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index 74131d2231..5c0ee2e2eb 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -12,7 +12,7 @@ import { useProgressBatchQuery } from 'hooks/progress/use-progress-batch-query' import { useTutorialProgressRefs } from 'hooks/progress' import useCurrentPath from 'hooks/use-current-path' import { useMobileMenu } from 'contexts' -import InstruqtProvider from 'contexts/instruqt-lab' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' import { TutorialLite } from 'lib/learn-client/types' import SidebarSidecarLayout from 'layouts/sidebar-sidecar' import { @@ -124,6 +124,7 @@ function TutorialView({ const currentPath = useCurrentPath({ excludeHash: true, excludeSearch: true }) const [collectionViewSidebarSections, setCollectionViewSidebarSections] = useState(null) + const { openLab, closeLab } = useInstruqtEmbed() // variables const { @@ -142,7 +143,7 @@ function TutorialView({ ) const hasVideo = Boolean(video) const isInteractive = Boolean(handsOnLab) - const InteractiveLabWrapper = isInteractive ? InstruqtProvider : Fragment + const InteractiveLabWrapper = isInteractive ? Fragment : Fragment const nextPreviousData = getNextPrevious({ currentCollection: collectionCtx.current, currentTutorialSlug: slug, @@ -227,6 +228,15 @@ function TutorialView({ collectionTutorialIds, }) + // Handle lab opening/closing when tutorial changes + useEffect(() => { + if (isInteractive && handsOnLab?.id) { + openLab(handsOnLab.id) + } else { + closeLab() + } + }, [isInteractive, handsOnLab, openLab, closeLab]) + return ( <> @@ -243,14 +253,7 @@ function TutorialView({ ) : null } - sidecarSlot={} + sidecarSlot={ + outlineItems?.length > 0 && ( + + ) + } mainWidth={layoutProps.mainWidth} > Date: Tue, 11 Mar 2025 14:16:24 -0700 Subject: [PATCH 07/53] update text color --- src/pages/[productSlug]/playground/playground.module.css | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pages/[productSlug]/playground/playground.module.css b/src/pages/[productSlug]/playground/playground.module.css index 6f5546e12c..f529e86a11 100644 --- a/src/pages/[productSlug]/playground/playground.module.css +++ b/src/pages/[productSlug]/playground/playground.module.css @@ -43,6 +43,7 @@ .featureList { margin: 16px 0; padding-left: 24px; + color: var(--token-color-foreground-primary); & li { margin-bottom: 8px; From de144d481ec2de55a820d366c2f06c8ebe5e590b Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 12 Mar 2025 09:12:37 -0700 Subject: [PATCH 08/53] fix playground configuration, fix consul --- .../components/playground-dropdown/index.tsx | 4 +- .../components/product-page-content/index.tsx | 2 +- .../utils/get-nav-items.ts | 2 +- src/data/playground-config.json | 35 ------ src/data/playground.json | 117 +++++------------- src/pages/[productSlug]/playground/index.tsx | 4 +- 6 files changed, 39 insertions(+), 125 deletions(-) delete mode 100644 src/data/playground-config.json diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/playground-dropdown/index.tsx index dca9c75b1e..73accba106 100644 --- a/src/components/navigation-header/components/playground-dropdown/index.tsx +++ b/src/components/navigation-header/components/playground-dropdown/index.tsx @@ -23,10 +23,10 @@ import { NavigationHeaderItem, } from 'components/navigation-header/types' import { ProductSlug } from 'types/products' -import PLAYGROUND_CONFIG from 'data/playground-config.json' +import PLAYGROUND_CONFIG from 'data/playground.json' import s from './playground-dropdown.module.css' -// Define the type to match the structure in playground-config.json +// Define the type to match the structure in playground.json type PlaygroundLab = { id?: string labId: string diff --git a/src/components/navigation-header/components/product-page-content/index.tsx b/src/components/navigation-header/components/product-page-content/index.tsx index 7280c311f7..6165588204 100644 --- a/src/components/navigation-header/components/product-page-content/index.tsx +++ b/src/components/navigation-header/components/product-page-content/index.tsx @@ -10,7 +10,7 @@ import { IconHashicorp24 } from '@hashicorp/flight-icons/svg-react/hashicorp-24' import { useCurrentProduct } from 'contexts' import * as NavigationMenu from '@radix-ui/react-navigation-menu' import { useInstruqtEmbed } from 'contexts/instruqt-lab' -import PLAYGROUND_CONFIG from 'data/playground-config.json' +import PLAYGROUND_CONFIG from 'data/playground.json' // Local imports import { diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index 104605d570..d38e3fdfd9 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -11,7 +11,7 @@ import { getDocsNavItems } from 'lib/docs/get-docs-nav-items' import { getIsEnabledProductIntegrations } from 'lib/integrations/get-is-enabled-product-integrations' import { ProductData } from 'types/products' import { NavItem } from './types' -import PLAYGROUND_CONFIG from 'data/playground-config.json' +import PLAYGROUND_CONFIG from 'data/playground.json' const TRY_CLOUD_ITEM_PRODUCT_SLUGS = [ 'boundary', diff --git a/src/data/playground-config.json b/src/data/playground-config.json deleted file mode 100644 index a0ad7d0316..0000000000 --- a/src/data/playground-config.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "products": ["terraform", "vault", "consul", "nomad"], - "labs": [ - { - "title": "Terraform Sandbox", - "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", - "products": ["terraform"], - "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE" - }, - { - "title": "Vault Playground (test)", - "description": "Learn how to manage your secrets with Vault", - "products": ["vault"], - "labId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB" - }, - { - "title": "Nomad sandbox", - "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", - "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", - "products": ["nomad", "consul"] - }, - { - "title": "Sandbox environment for Consul (Service discovery)", - "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", - "labId": "/hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", - "products": ["consul"] - }, - { - "title": "Sandbox environment for Consul (Service mesh)", - "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", - "labId": "/hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM", - "products": ["consul"] - } - ] -} diff --git a/src/data/playground.json b/src/data/playground.json index 43deafbc2b..d379f0b52b 100644 --- a/src/data/playground.json +++ b/src/data/playground.json @@ -1,86 +1,35 @@ { - "terraform": { - "description": "Learn infrastructure as code with hands-on labs", - "labs": [ - { - "id": "terraform-basics", - "labId": "hashicorp-learn/tracks/terraform-build-your-first-configuration", - "title": "Build Your First Configuration", - "description": "Learn the basics of Terraform configuration language", - "products": ["terraform"] - } - ] - }, - "vault": { - "description": "Explore secrets management and data protection", - "labs": [ - { - "id": "vault-basics", - "labId": "hashicorp-learn/tracks/vault-basics", - "title": "Vault Basics", - "description": "Learn the fundamentals of HashiCorp Vault", - "products": ["vault"] - } - ] - }, - "consul": { - "description": "Practice service networking and discovery", - "labs": [ - { - "id": "consul-template", - "labId": "hashicorp-learn/tracks/consul-template-automate-reverse-proxy-config", - "title": "Automate Reverse Proxy Configuration", - "description": "Learn to automate proxy configuration with Consul Template", - "products": ["consul"] - } - ] - }, - "nomad": { - "description": "Get started with workload orchestration", - "labs": [ - { - "id": "nomad-basics", - "labId": "hashicorp-learn/tracks/nomad-basics", - "title": "Nomad Basics", - "description": "Learn the basics of HashiCorp Nomad", - "products": ["nomad"] - } - ] - }, - "packer": { - "description": "Learn machine image automation", - "labs": [ - { - "id": "packer-hcp", - "labId": "hashicorp-learn/tracks/packer-get-started-hcp", - "title": "Get Started with HCP Packer", - "description": "Build and manage machine images with HCP Packer", - "products": ["packer"] - } - ] - }, - "waypoint": { - "description": "Explore application deployment patterns", - "labs": [ - { - "id": "waypoint-docker", - "labId": "hashicorp-learn/tracks/waypoint-get-started-docker", - "title": "Get Started with Docker", - "description": "Deploy applications with Waypoint and Docker", - "products": ["waypoint"] - } - ] - }, - "boundary": { - "description": "Practice secure remote access", - "labs": [ - { - "id": "boundary-basics", - "labId": "hashicorp-learn/tracks/boundary-basics", - "title": "Boundary Basics", - "description": "Learn the fundamentals of HashiCorp Boundary", - "products": ["boundary"] - } - ] - } + "products": ["terraform", "vault", "consul", "nomad"], + "labs": [ + { + "title": "Terraform Sandbox", + "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", + "products": ["terraform"], + "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE" + }, + { + "title": "Vault Playground (test)", + "description": "Learn how to manage your secrets with Vault", + "products": ["vault"], + "labId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB" + }, + { + "title": "Nomad sandbox", + "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", + "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", + "products": ["nomad", "consul"] + }, + { + "title": "Sandbox environment for Consul (Service discovery)", + "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", + "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", + "products": ["consul"] + }, + { + "title": "Sandbox environment for Consul (Service mesh)", + "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", + "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM", + "products": ["consul"] + } + ] } diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index 687d09e062..f4d5cb8046 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -24,7 +24,7 @@ import { CardBadges } from 'components/tutorial-collection-cards' import { ProductOption } from 'lib/learn-client/types' import { MenuItem } from 'components/sidebar/types' import { ProductSlug } from 'types/products' -import PLAYGROUND_CONFIG from 'data/playground-config.json' +import PLAYGROUND_CONFIG from 'data/playground.json' import ProductIcon from 'components/product-icon' import s from './playground.module.css' @@ -205,7 +205,7 @@ export default function PlaygroundView({ } export const getStaticPaths: GetStaticPaths = async () => { - // Get the list of supported products from playground-config.json + // Get the list of supported products from playground.json const supportedProducts = PLAYGROUND_CONFIG.products || [] // Generate paths for all products that are in the supported products list From fc2c9f159da27617df184d95aacdc56f61b366af Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 12 Mar 2025 09:13:48 -0700 Subject: [PATCH 09/53] remove extraneous config --- src/data/nomad.json | 27 --------------------------- src/data/terraform.json | 19 +------------------ src/data/vault.json | 16 ---------------- 3 files changed, 1 insertion(+), 61 deletions(-) diff --git a/src/data/nomad.json b/src/data/nomad.json index 76485a6711..b4ec3ec91b 100644 --- a/src/data/nomad.json +++ b/src/data/nomad.json @@ -102,32 +102,5 @@ ], "integrationsConfig": { "description": "A curated collection of official, partner, and community Nomad Integrations." - }, - - "playgroundConfig": { - "description": "Learn how to manage your workloads with Nomad.", - "sidebarLinks": [ - { - "title": "Install Nomad", - "href": "/nomad/install" - }, - { - "title": "Get Started with Nomad", - "href": "/nomad/tutorials/get-started" - }, - { - "title": "Nomad documentation", - "href": "/nomad/docs" - } - ], - "labs": [ - { - "id": "nomad-sandbox", - "name": "Nomad sandbox", - "instruqtId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", - "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", - "products": ["nomad", "consul"] - } - ] } } diff --git a/src/data/terraform.json b/src/data/terraform.json index f6ebddc5ae..1c6de4f9c6 100644 --- a/src/data/terraform.json +++ b/src/data/terraform.json @@ -151,22 +151,5 @@ "path": "registry", "productSlugForLoader": "terraform-docs-common" } - ], - "playgroundConfig": { - "description": "Learn how to create infrastructure with Terraform", - "sidebarLinks": [ - { - "title": "Install Terraform", - "href": "/terraform/install" - }, - { - "title": "Get Started with Terraform", - "href": "/terraform/tutorials/aws-get-started" - }, - { - "title": "Terraform documentation", - "href": "/terraform/docs" - } - ] - } + ] } diff --git a/src/data/vault.json b/src/data/vault.json index 17b820473c..e6bb0fe83c 100644 --- a/src/data/vault.json +++ b/src/data/vault.json @@ -174,21 +174,5 @@ "href": "/vault/tutorials/custom-secrets-engine" } ] - }, - "playgroundConfig": { - "sidebarLinks": [ - { - "title": "Install Vault", - "href": "/vault/install" - }, - { - "title": "Get Started with Vault", - "href": "/vault/tutorials/get-started" - }, - { - "title": "Vault Documentation", - "href": "/vault/docs" - } - ] } } From ddf846856c2b23a33961d82368da05292f4f11eb Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 12 Mar 2025 09:20:41 -0700 Subject: [PATCH 10/53] prevent instruqt pane from closing when going to individual tutorials page --- .../dropdown-menu/dropdown-menu.module.css | 2 +- .../components/playground-dropdown/index.tsx | 3 +++ src/contexts/instruqt-lab/index.tsx | 24 +++++++++++++++---- src/views/tutorial-view/index.tsx | 4 +++- 4 files changed, 27 insertions(+), 6 deletions(-) diff --git a/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css b/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css index c54d2b3ae7..2ad48faf30 100644 --- a/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css +++ b/src/components/navigation-header/components/dropdown-menu/dropdown-menu.module.css @@ -91,7 +91,7 @@ } .itemGroupLabel { - margin-bottom: 8px; + margin-bottom: 12px; padding-left: 8px; padding-right: 8px; } diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/playground-dropdown/index.tsx index 73accba106..7bd9ea1ba3 100644 --- a/src/components/navigation-header/components/playground-dropdown/index.tsx +++ b/src/components/navigation-header/components/playground-dropdown/index.tsx @@ -113,6 +113,9 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { const handleLabClick = (lab: PlaygroundLab) => { openLab(lab.labId) setIsOpen(false) + + // Don't navigate away - just open the lab in the current page + // This prevents issues with lab state being lost during navigation } /** diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index b726c7e9ad..1126b785c1 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -14,6 +14,7 @@ import { useCallback, } from 'react' import dynamic from 'next/dynamic' +import { useRouter } from 'next/router' import EmbedElement from 'components/lab-embed/embed-element' import Resizable from 'components/lab-embed/resizable' @@ -47,6 +48,7 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { const [isClient, setIsClient] = useState(false) const [labId, setLabId] = useState(null) const [active, setActive] = useState(false) + const router = useRouter() // Only run on client side useEffect(() => { @@ -80,13 +82,27 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { } }, [active, labId, isClient]) - const openLab = useCallback((newLabId: string) => { - setLabId(newLabId) - setActive(true) - }, []) + // Listen for route changes to preserve lab state during navigation + useEffect(() => { + // This effect runs when the route changes + // We don't need to do anything special here, just ensure + // the component doesn't unmount during navigation + }, [router.asPath]) + + const openLab = useCallback( + (newLabId: string) => { + // Only update if the lab ID is different or the panel is not active + if (newLabId !== labId || !active) { + setLabId(newLabId) + setActive(true) + } + }, + [labId, active] + ) const closeLab = useCallback(() => { setActive(false) + // Note: We don't clear the labId here to allow reopening the same lab }, []) return ( diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index 5c0ee2e2eb..295cae0e55 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -232,7 +232,9 @@ function TutorialView({ useEffect(() => { if (isInteractive && handsOnLab?.id) { openLab(handsOnLab.id) - } else { + } else if (!isInteractive) { + // Only close the lab if this tutorial is not interactive + // This prevents closing the lab when navigating between pages closeLab() } }, [isInteractive, handsOnLab, openLab, closeLab]) From d49c701d052c68f5b6b686a2be15e3a89aceb514 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 13 Mar 2025 10:18:30 -0700 Subject: [PATCH 11/53] remove min height to ensure embeded element works even when reduced --- src/components/lab-embed/embed-element/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/lab-embed/embed-element/index.tsx b/src/components/lab-embed/embed-element/index.tsx index c22716a85d..6ba8a5dfcc 100644 --- a/src/components/lab-embed/embed-element/index.tsx +++ b/src/components/lab-embed/embed-element/index.tsx @@ -30,7 +30,7 @@ export default function EmbedElement(): JSX.Element { height="100%" sandbox="allow-same-origin allow-scripts allow-popups allow-forms allow-modals" src={`https://play.instruqt.com/embed/${labId}`} - style={{ height: 'inherit', minHeight: '640px' }} + style={{ height: 'inherit' }} className={classNames(s.baseEmbedElement, { [s.hide]: !active })} /> ) From 741dde813ab7948bcdecaddfa090d4d23eabd428 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 20:05:10 -0700 Subject: [PATCH 12/53] fix build error --- .../utils/__tests__/get-nav-items.test.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts index a8d37ce10e..b964cee222 100644 --- a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts +++ b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts @@ -234,6 +234,10 @@ describe('getNavItems', () => { ], "label": "Documentation", }, + { + "label": "Playground", + "url": "/terraform/playground", + }, { "label": "Registry", "opensInNewTab": true, From c7079321f30cffdd85d058121c7b299e6158f54c Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 22:10:01 -0700 Subject: [PATCH 13/53] fix behavior and styles for playgrounds dropdown, add playground to resources for relevant products --- .../components/playground-dropdown/index.tsx | 213 ++++++++++-------- .../playground-dropdown.module.css | 167 +++++++++----- .../components/product-page-content/index.tsx | 18 +- .../product-page-content.module.css | 5 + .../helpers/generate-resources-nav-items.ts | 15 ++ 5 files changed, 266 insertions(+), 152 deletions(-) diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/playground-dropdown/index.tsx index 7bd9ea1ba3..da36a09719 100644 --- a/src/components/navigation-header/components/playground-dropdown/index.tsx +++ b/src/components/navigation-header/components/playground-dropdown/index.tsx @@ -5,26 +5,22 @@ import { Fragment, KeyboardEvent, useRef, useState } from 'react' import { useId } from '@react-aria/utils' -import classNames from 'classnames' import { IconChevronDown16 } from '@hashicorp/flight-icons/svg-react/chevron-down-16' import { IconArrowRight16 } from '@hashicorp/flight-icons/svg-react/arrow-right-16' import { IconChevronRight16 } from '@hashicorp/flight-icons/svg-react/chevron-right-16' +import { useRouter } from 'next/router' +import { useCurrentProduct } from 'contexts' import { useInstruqtEmbed } from 'contexts/instruqt-lab' import useOnClickOutside from 'hooks/use-on-click-outside' import useOnEscapeKeyDown from 'hooks/use-on-escape-key-down' import useOnFocusOutside from 'hooks/use-on-focus-outside' import useOnRouteChangeStart from 'hooks/use-on-route-change-start' -import { useRouter } from 'next/router' -import { useCurrentProduct } from 'contexts' +import deriveKeyEventState from 'lib/derive-key-event-state' import Text from 'components/text' -import PlaygroundItem from '../playground-item' -import { - NavigationHeaderIcon, - NavigationHeaderItem, -} from 'components/navigation-header/types' -import { ProductSlug } from 'types/products' +import ProductIcon from 'components/product-icon' import PLAYGROUND_CONFIG from 'data/playground.json' import s from './playground-dropdown.module.css' +import { ProductSlug } from 'types/products' // Define the type to match the structure in playground.json type PlaygroundLab = { @@ -86,45 +82,62 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { }) /** - * Handles the menu being activated via a hover. - * Opens the menu. + * Handles click interaction with the activator button. When clicked, if the + * menu is: + * - open, then it will be closed + * - closed, then it will be opened */ - const handleMouseEnter = () => { - setIsOpen(true) + const handleClick = () => { + setIsOpen(!isOpen) } /** - * Handles a keydown event on the activator button. - * Opens the menu for specific keystroke patterns. + * Handles the behavior that should happen when a key is pressed down. + * Currently used by both the activator button and each menu item anchor + * element. Currently only handles what happens when the Escape is pressed + * because all other keyboard interaction is handled by default interactions + * with these elements. + * + * On Escape: + * - the menu is closed, if it is open + * - the activator button is given focus */ - const handleKeyDown = (event: KeyboardEvent) => { - if (!isOpen) { - const { isDown, isEnter, isSpace } = deriveKeyEventState(event) - if (isDown || isEnter || isSpace) { - event.preventDefault() - setIsOpen(true) - } + const handleKeyDown = (e: KeyboardEvent) => { + const { isEscapeKey } = deriveKeyEventState(e) + if (isEscapeKey) { + setIsOpen(false) + activatorButtonRef.current.focus() } } /** - * Handle lab selection + * Handles the start of a mouse hover interaction with the activator button. + * When the mouse pointer hovers over the activator button, the menu will be + * opened if it is not already open. */ - const handleLabClick = (lab: PlaygroundLab) => { - openLab(lab.labId) - setIsOpen(false) + const handleMouseEnter = () => { + if (!isOpen) { + setIsOpen(true) + } + } - // Don't navigate away - just open the lab in the current page - // This prevents issues with lab state being lost during navigation + /** + * Handles the end of a mouse hover interaction with the entire menu. If the + * menu is open, and the mouse moves outside the bounds either the activator + * button or the dropdown menu list, then the menu will be closed. + */ + const handleMouseLeave = () => { + if (isOpen) { + setIsOpen(false) + } } /** - * Navigate to the playground page when clicking on the label + * Handle lab selection */ - const handleLabelClick = (e: React.MouseEvent) => { - e.preventDefault() - e.stopPropagation() - router.push(`/${currentProduct.slug}/playground`) + const handleLabClick = (lab: PlaygroundLab) => { + openLab(lab.labId) + setIsOpen(false) } /** @@ -145,23 +158,26 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { } return ( -
    setIsOpen(false)} - > -
    +
    +
    @@ -197,6 +213,7 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { href={`/${currentProduct.slug}/playground`} className={s.learnMoreLink} onClick={navigateToPlaygroundPage} + onKeyDown={handleKeyDown} > Learn more about Playgrounds @@ -221,17 +238,33 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => {
      {currentProductLabs.map((lab, index) => (
    • - handleLabClick(lab), - }} - /> +
      • ))}
    @@ -244,6 +277,7 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { @@ -265,17 +299,35 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => {
      {otherProductLabs.map((lab, index) => (
    • - handleLabClick(lab), - }} - /> +
      • ))}
    @@ -289,30 +341,3 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { } export default PlaygroundDropdown - -// Helper function extracted from NavigationHeaderDropdownMenu -function deriveKeyEventState(event: KeyboardEvent) { - const isDown = event.key === 'ArrowDown' - const isUp = event.key === 'ArrowUp' - const isLeft = event.key === 'ArrowLeft' - const isRight = event.key === 'ArrowRight' - const isEnter = event.key === 'Enter' - const isEscape = event.key === 'Escape' - const isHome = event.key === 'Home' - const isEnd = event.key === 'End' - const isSpace = event.key === ' ' - const isTab = event.key === 'Tab' - - return { - isDown, - isUp, - isLeft, - isRight, - isEnter, - isEscape, - isHome, - isEnd, - isSpace, - isTab, - } -} diff --git a/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css b/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css index 9bc0791f26..994070e713 100644 --- a/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css +++ b/src/components/navigation-header/components/playground-dropdown/playground-dropdown.module.css @@ -4,67 +4,65 @@ */ .root { + width: fit-content; position: relative; - display: inline-block; } -.activatorContainer { - display: inline-flex; +.activatorWrapper { padding-bottom: 16px; padding-top: 16px; } .activator { - display: flex; + /* Composition */ + composes: g-focus-ring-from-box-shadow-dark from global; + + /* CSS properties */ align-items: center; - gap: 6px; - background: transparent; - border: none; - cursor: pointer; - padding: 8px 10px; + background-color: transparent; border-radius: 5px; - color: var(--token-color-foreground-primary); - font-size: 0.875rem; - font-weight: 500; + border: 0; + display: flex; + padding-bottom: 8px; + padding-left: var(--header-menu-item-padding-left-right); + padding-right: var(--header-menu-item-padding-left-right); + padding-top: 8px; + + &[aria-expanded='true'] { + & .activatorText { + color: var(--token-color-foreground-primary); + } + + & .activatorTrailingIcon { + color: var(--token-color-foreground-primary); + transform: rotate(-180deg); + } + } } -.label { - font-size: 0.875rem; - font-weight: 500; +.activatorText { color: var(--token-color-foreground-primary); - transition: color 0.2s; - - .activator:hover &, - .activator:focus &, - .activator[aria-expanded='true'] & { - color: var(--token-color-foreground-strong); - } + margin-right: 6px; } .activatorTrailingIcon { - width: 16px; - height: 16px; - display: inline-block; color: var(--token-color-foreground-strong); - transition: transform 0.2s ease-in-out; - .activator[aria-expanded='true'] & { - transform: rotate(180deg); + /* Only enable animation if query is supported and value is no-preference */ + @media (prefers-reduced-motion: no-preference) { + transition: transform 0.2s ease-in-out; } } .dropdownContainer { - position: absolute; - top: 100%; - left: 0; background-color: var(--token-color-surface-primary); - border-radius: 6px; + border-bottom-left-radius: 6px; + border-bottom-right-radius: 6px; box-shadow: var(--token-elevation-higher-box-shadow); - z-index: -1; - margin-top: 0; - min-width: 32rem; - max-height: 80vh; - overflow-y: auto; + position: absolute; + width: max-content; + min-width: 280px; + max-width: 480px; } .dropdownContainerInner { @@ -78,11 +76,11 @@ .sectionTitle { margin-bottom: 8px; color: var(--token-color-foreground-strong); + font-size: 14px; } .introText { color: var(--token-color-foreground-primary); - max-width: 90%; line-height: 1.5; margin-bottom: 8px; } @@ -97,9 +95,10 @@ .labsList { list-style: none; padding: 0; - margin: 12px 0 0 0; + margin: 8px 0 0 0; display: flex; flex-direction: column; + gap: 2px; } .itemContainer { @@ -107,50 +106,109 @@ padding: 0; } -.learnMoreLink { +.playgroundItem { + /* Composition */ + composes: g-focus-ring-from-box-shadow from global; + + /* CSS Properties */ + align-items: flex-start; + border-radius: 5px; + color: var(--token-color-foreground-primary); display: flex; - align-items: center; - gap: 6px; - padding: 4px 0; + gap: 8px; + padding: 8px; text-decoration: none; + width: 100%; + background: transparent; + border: none; + cursor: pointer; + text-align: left; + + &:hover .title { + color: var(--token-color-foreground-strong); + text-decoration: underline; + } +} + +.content { + flex: 1; + min-width: 0; /* Allows text truncation */ +} + +.titleRow { + display: flex; + align-items: center; + gap: 8px; + margin-bottom: 4px; +} + +.title { color: var(--token-color-foreground-primary); transition: color 0.2s; - font-size: 0.875rem; + font-size: 14px; +} + +.description { + color: var(--token-color-foreground-faint); + display: block; + line-height: 1.5; + font-size: 14px; +} - &:hover, - &:focus { +.learnMoreLink { + /* Composition */ + composes: g-focus-ring-from-box-shadow from global; + + /* CSS Properties */ + align-items: center; + border-radius: 5px; + color: var(--token-color-foreground-primary); + display: flex; + padding: 8px; + text-decoration: none; + width: 100%; + font-size: 14px; + + &:hover { color: var(--token-color-foreground-strong); - text-decoration: none; + text-decoration: underline; } } .learnMoreIcon { width: 14px; height: 14px; + margin-left: 6px; color: var(--token-color-foreground-primary); transition: transform 0.2s, color 0.2s; - .learnMoreLink:hover &, - .learnMoreLink:focus & { + .learnMoreLink:hover & { transform: translateX(4px); color: var(--token-color-foreground-strong); } } .accordionButton { - display: flex; + /* Composition */ + composes: g-focus-ring-from-box-shadow from global; + + /* CSS Properties */ align-items: center; - justify-content: space-between; + border-radius: 5px; + color: var(--token-color-foreground-primary); + display: flex; + padding: 8px; + text-decoration: none; width: 100%; background: transparent; border: none; - padding: 8px 0; cursor: pointer; + justify-content: space-between; text-align: left; - &:hover .sectionTitle, - &:focus .sectionTitle { + &:hover .sectionTitle { color: var(--token-color-foreground-strong); + text-decoration: underline; } } @@ -159,6 +217,7 @@ height: 16px; color: var(--token-color-foreground-primary); transition: transform 0.2s ease-in-out; + flex-shrink: 0; } .accordionIconOpen { diff --git a/src/components/navigation-header/components/product-page-content/index.tsx b/src/components/navigation-header/components/product-page-content/index.tsx index 6165588204..b2894376e9 100644 --- a/src/components/navigation-header/components/product-page-content/index.tsx +++ b/src/components/navigation-header/components/product-page-content/index.tsx @@ -36,6 +36,12 @@ const ProductPageHeaderContent = () => { PLAYGROUND_CONFIG.labs?.length > 0 && supportedPlaygroundProducts.includes(currentProduct.slug) + // Get playground labs for the current product + const labs = PLAYGROUND_CONFIG.labs || [] + const currentProductLabs = labs.filter((lab) => + lab.products.includes(currentProduct.slug) + ) + return ( <>
    @@ -68,10 +74,14 @@ const ProductPageHeaderContent = () => { if (isPlayground && hasPlayground) { return (
  • - +
    + + + +
    • ) } diff --git a/src/components/navigation-header/components/product-page-content/product-page-content.module.css b/src/components/navigation-header/components/product-page-content/product-page-content.module.css index 2c2d67a904..58b9063bb7 100644 --- a/src/components/navigation-header/components/product-page-content/product-page-content.module.css +++ b/src/components/navigation-header/components/product-page-content/product-page-content.module.css @@ -12,6 +12,11 @@ } } +.navDropdown { + position: relative; + display: inline-block; +} + .productsDropdownIcon { color: var(--token-color-foreground-strong); display: block; diff --git a/src/components/sidebar/helpers/generate-resources-nav-items.ts b/src/components/sidebar/helpers/generate-resources-nav-items.ts index 3c89709169..d0e319924c 100644 --- a/src/components/sidebar/helpers/generate-resources-nav-items.ts +++ b/src/components/sidebar/helpers/generate-resources-nav-items.ts @@ -9,6 +9,7 @@ import { VALID_EDITION_SLUGS_FOR_FILTERING, VALID_PRODUCT_SLUGS_FOR_FILTERING, } from 'views/tutorial-library/constants' +import PLAYGROUND_CONFIG from 'data/playground.json' /** * Note: these ResourceNav types could probably be abstracted up or lifted out, @@ -136,6 +137,11 @@ function generateResourcesNavItems( productSlug?: ProductSlug ): ResourceNavItem[] { const additionalResources = generateAdditionalResources(productSlug) + const supportedPlaygroundProducts = PLAYGROUND_CONFIG.products || [] + const hasPlayground = + productSlug && + PLAYGROUND_CONFIG.labs?.length > 0 && + supportedPlaygroundProducts.includes(productSlug) return [ { heading: 'Resources' }, @@ -145,6 +151,15 @@ function generateResourcesNavItems( href: getTutorialLibraryUrl(productSlug), }, ...getCertificationsLink(productSlug), + // Add Playground link if the product supports it + ...(hasPlayground + ? [ + { + title: 'Playground', + href: `/${productSlug}/playground`, + }, + ] + : []), { title: 'Community Forum', href: productSlug From a6ae6b053871fe67b728d6b63ad7194d2edb09b3 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 22:22:46 -0700 Subject: [PATCH 14/53] fix tutorial-view behavior, should load tutorial lab instead of playground by default --- src/views/tutorial-view/index.tsx | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index 295cae0e55..b2b702c304 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -124,7 +124,7 @@ function TutorialView({ const currentPath = useCurrentPath({ excludeHash: true, excludeSearch: true }) const [collectionViewSidebarSections, setCollectionViewSidebarSections] = useState(null) - const { openLab, closeLab } = useInstruqtEmbed() + const { openLab, closeLab, setActive } = useInstruqtEmbed() // variables const { @@ -231,13 +231,29 @@ function TutorialView({ // Handle lab opening/closing when tutorial changes useEffect(() => { if (isInteractive && handsOnLab?.id) { - openLab(handsOnLab.id) + try { + // Get the current lab state + const storedState = localStorage.getItem('instruqt-lab-state') + const currentState = storedState ? JSON.parse(storedState) : null + + // If we're loading a different lab, or there's no current lab + if ( + !currentState?.storedLabId || + currentState.storedLabId !== handsOnLab.id + ) { + // Load the new lab but keep it closed initially + openLab(handsOnLab.id) + } + // If it's the same lab, do nothing to preserve the user's open/closed preference + } catch (e) { + console.warn('Failed to handle lab state:', e) + } } else if (!isInteractive) { // Only close the lab if this tutorial is not interactive // This prevents closing the lab when navigating between pages closeLab() } - }, [isInteractive, handsOnLab, openLab, closeLab]) + }, [isInteractive, handsOnLab, openLab, closeLab, setActive]) return ( <> From f62b8bda404442f37b79d4de12b0c71f0892125e Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 22:23:11 -0700 Subject: [PATCH 15/53] fix tutorial-view behavior, should load tutorial lab instead of playground by default --- src/views/tutorial-view/index.tsx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index b2b702c304..4b800791ec 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -241,7 +241,6 @@ function TutorialView({ !currentState?.storedLabId || currentState.storedLabId !== handsOnLab.id ) { - // Load the new lab but keep it closed initially openLab(handsOnLab.id) } // If it's the same lab, do nothing to preserve the user's open/closed preference From 94b2fe276ed734402f1e6014c8298211eb3010c5 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 22:29:04 -0700 Subject: [PATCH 16/53] fix ci tests --- .../utils/__tests__/get-nav-items.test.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts index b964cee222..08096abeac 100644 --- a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts +++ b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts @@ -234,10 +234,10 @@ describe('getNavItems', () => { ], "label": "Documentation", }, - { - "label": "Playground", - "url": "/terraform/playground", - }, + { + "label": "Playground", + "url": "/terraform/playground", + }, { "label": "Registry", "opensInNewTab": true, From a23cce2c917b6cc901c375e2f16376beaee22cdc Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 19 Mar 2025 22:31:28 -0700 Subject: [PATCH 17/53] fix more ci tests --- .../utils/__tests__/get-nav-items.test.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts index 08096abeac..ebf9a8d6cd 100644 --- a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts +++ b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts @@ -43,6 +43,10 @@ describe('getNavItems', () => { "label": "CLI", "url": "/nomad/commands", }, + { + "label": "Playground", + "url": "/nomad/playground", + }, { "label": "Integrations", "url": "/nomad/integrations", From 0165c8aefc1abab3eac101e483ac450ddfb11ad3 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 20 Mar 2025 00:09:53 -0700 Subject: [PATCH 18/53] posthog tracking experiment --- src/components/lab-embed/resizable/index.tsx | 12 ++++++----- .../components/playground-dropdown/index.tsx | 5 +++++ src/contexts/instruqt-lab/index.tsx | 21 ++++++++++++++----- src/lib/analytics.ts | 15 +++++++++++++ src/pages/[productSlug]/playground/index.tsx | 8 ++++--- 5 files changed, 48 insertions(+), 13 deletions(-) diff --git a/src/components/lab-embed/resizable/index.tsx b/src/components/lab-embed/resizable/index.tsx index 8e9cc6c773..07882952f3 100644 --- a/src/components/lab-embed/resizable/index.tsx +++ b/src/components/lab-embed/resizable/index.tsx @@ -8,6 +8,7 @@ import CSS from 'csstype' import classNames from 'classnames' import Resizer from './components/resizer' import s from './resizable.module.css' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' interface ResizableProps { panelActive: boolean @@ -24,6 +25,7 @@ export default function Resizable({ style, initialHeight = 400, }: ResizableProps) { + const { closeLab } = useInstruqtEmbed() // State for resizable panel while in `panel`-mode const minimumHeight = 300 const maximumHeight = 910 @@ -31,9 +33,9 @@ export default function Resizable({ const [moveMouseY, setMoveMouseY] = useState(0) const [height, setHeight] = useState(initialHeight) const [previousHeight, setPreviousHeight] = useState(initialHeight) - const [isResizing, setResizing] = useState(false) + const [isResizing, setIsResizing] = useState(false) - const resizableDiv = useRef() + const resizableDiv = useRef(null) useEffect(() => { if (resizableDiv.current) { @@ -51,7 +53,7 @@ export default function Resizable({ // Track the fact that we are resizing // This keeps our cursor on our `` // This adds a class to the content our mouse may otherwise wander into via `pointer-events: none` - setResizing(true) + setIsResizing(true) // Once we're clientside add the event listeners needed during a resize addListeners() } @@ -63,7 +65,7 @@ export default function Resizable({ function stopResize() { // We stopped resizing so it'd be great to be able to use the content inside the resizable ref ;) - setResizing(false) + setIsResizing(false) // We no longer want our event listeners removeListeners() } @@ -92,7 +94,7 @@ export default function Resizable({ data-resizing={String(isResizing)} > setPanelActive(!panelActive)} + onClosePanel={() => closeLab()} onMouseDown={enableResize} style={style} /> diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/playground-dropdown/index.tsx index da36a09719..431ed99a6c 100644 --- a/src/components/navigation-header/components/playground-dropdown/index.tsx +++ b/src/components/navigation-header/components/playground-dropdown/index.tsx @@ -11,6 +11,7 @@ import { IconChevronRight16 } from '@hashicorp/flight-icons/svg-react/chevron-ri import { useRouter } from 'next/router' import { useCurrentProduct } from 'contexts' import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import { trackPlaygroundEvent } from 'lib/analytics' import useOnClickOutside from 'hooks/use-on-click-outside' import useOnEscapeKeyDown from 'hooks/use-on-escape-key-down' import useOnFocusOutside from 'hooks/use-on-focus-outside' @@ -137,6 +138,10 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { */ const handleLabClick = (lab: PlaygroundLab) => { openLab(lab.labId) + trackPlaygroundEvent('playground_started', { + labId: lab.labId, + page: router.asPath, + }) setIsOpen(false) } diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index 1126b785c1..8e3832a14e 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -17,6 +17,7 @@ import dynamic from 'next/dynamic' import { useRouter } from 'next/router' import EmbedElement from 'components/lab-embed/embed-element' import Resizable from 'components/lab-embed/resizable' +import { trackPlaygroundEvent } from 'lib/analytics' interface InstruqtContextProps { labId: string | null @@ -84,10 +85,14 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { // Listen for route changes to preserve lab state during navigation useEffect(() => { - // This effect runs when the route changes - // We don't need to do anything special here, just ensure - // the component doesn't unmount during navigation - }, [router.asPath]) + // Track when a playground is open while navigating to different pages + if (active && labId) { + trackPlaygroundEvent('playground_open', { + labId, + page: router.asPath, + }) + } + }, [router.asPath, active, labId]) const openLab = useCallback( (newLabId: string) => { @@ -101,9 +106,15 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { ) const closeLab = useCallback(() => { + if (active && labId) { + trackPlaygroundEvent('playground_closed', { + labId, + page: router.asPath, + }) + } setActive(false) // Note: We don't clear the labId here to allow reopening the same lab - }, []) + }, [active, labId, router.asPath]) return ( { + if (window?.posthog?.capture) { + window.posthog.capture(eventName, properties) + } +} + export { safeAnalyticsTrack, trackProductDownload } diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/playground/index.tsx index f4d5cb8046..90249cf2f1 100644 --- a/src/pages/[productSlug]/playground/index.tsx +++ b/src/pages/[productSlug]/playground/index.tsx @@ -4,10 +4,10 @@ */ import { GetStaticPaths, GetStaticProps } from 'next' -import { useState, useEffect, useMemo } from 'react' import { PRODUCT_DATA_MAP } from 'data/product-data-map' import SidebarSidecarLayout from 'layouts/sidebar-sidecar' import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import { trackPlaygroundEvent } from 'lib/analytics' import { generateTopLevelSidebarNavData, generateProductLandingSidebarNavData, @@ -20,8 +20,6 @@ import { import Card from 'components/card' import CardsGridList from 'components/cards-grid-list' import { BrandedHeaderCard } from 'views/product-integrations-landing/components/branded-header-card' -import { CardBadges } from 'components/tutorial-collection-cards' -import { ProductOption } from 'lib/learn-client/types' import { MenuItem } from 'components/sidebar/types' import { ProductSlug } from 'types/products' import PLAYGROUND_CONFIG from 'data/playground.json' @@ -58,6 +56,10 @@ export default function PlaygroundView({ const handleLabClick = (labId: string) => { openLab(labId) + trackPlaygroundEvent('playground_started', { + labId, + page: `/${product.slug}/playground`, + }) } return ( From b2763f53c11bff270be9760afe21641cf3beb5cb Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 20 Mar 2025 00:14:40 -0700 Subject: [PATCH 19/53] revert hcanges to typing --- src/views/tutorial-view/index.tsx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index 4b800791ec..a28bdbb627 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -270,7 +270,14 @@ function TutorialView({ Date: Thu, 20 Mar 2025 00:29:55 -0700 Subject: [PATCH 20/53] debugging posthog logs in dev preview --- src/hooks/use-posthog-analytics.ts | 1 + src/views/tutorial-view/index.tsx | 6 +----- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/src/hooks/use-posthog-analytics.ts b/src/hooks/use-posthog-analytics.ts index 01c6acc2a7..7e3060bdf7 100644 --- a/src/hooks/use-posthog-analytics.ts +++ b/src/hooks/use-posthog-analytics.ts @@ -37,6 +37,7 @@ export default function usePostHogPageAnalytics(): void { useEffect(() => { // Ensures code only runs if PostHog has been initialized + console.log('window?.posthog', window?.posthog) if (!window?.posthog) return window.posthog.config.capture_pageview = false diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index a28bdbb627..11563c4201 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -288,11 +288,7 @@ function TutorialView({ /> ) : null } - sidecarSlot={ - outlineItems?.length > 0 && ( - - ) - } + sidecarSlot={} mainWidth={layoutProps.mainWidth} > Date: Thu, 20 Mar 2025 09:02:27 -0700 Subject: [PATCH 21/53] playground -> sandbox --- .../components/product-page-content/index.tsx | 28 ++-- .../utils/__tests__/get-nav-items.test.ts | 8 +- .../utils/get-nav-items.ts | 14 +- .../index.tsx | 70 ++++----- .../sandbox-dropdown.module.css} | 2 +- .../index.tsx | 8 +- .../sandbox-item.module.css} | 2 +- .../helpers/generate-resources-nav-items.ts | 18 +-- src/contexts/instruqt-lab/index.tsx | 8 +- src/data/{playground.json => sandbox.json} | 0 src/lib/analytics.ts | 6 +- src/pages/[productSlug]/playground/index.tsx | 141 +++++++----------- .../playground/playground.module.css | 8 +- src/types/products.ts | 14 -- 14 files changed, 140 insertions(+), 187 deletions(-) rename src/components/navigation-header/components/{playground-dropdown => sandbox-dropdown}/index.tsx (82%) rename src/components/navigation-header/components/{playground-dropdown/playground-dropdown.module.css => sandbox-dropdown/sandbox-dropdown.module.css} (99%) rename src/components/navigation-header/components/{playground-item => sandbox-item}/index.tsx (89%) rename src/components/navigation-header/components/{playground-item/playground-item.module.css => sandbox-item/sandbox-item.module.css} (98%) rename src/data/{playground.json => sandbox.json} (100%) diff --git a/src/components/navigation-header/components/product-page-content/index.tsx b/src/components/navigation-header/components/product-page-content/index.tsx index b2894376e9..3c4043c548 100644 --- a/src/components/navigation-header/components/product-page-content/index.tsx +++ b/src/components/navigation-header/components/product-page-content/index.tsx @@ -9,8 +9,7 @@ import { IconHashicorp24 } from '@hashicorp/flight-icons/svg-react/hashicorp-24' // Global imports import { useCurrentProduct } from 'contexts' import * as NavigationMenu from '@radix-ui/react-navigation-menu' -import { useInstruqtEmbed } from 'contexts/instruqt-lab' -import PLAYGROUND_CONFIG from 'data/playground.json' +import SANDBOX_CONFIG from 'data/sandbox.json' // Local imports import { @@ -22,7 +21,7 @@ import { import { ProductIconTextLink } from './components' import { getNavItems, getProductsDropdownItems, NavItem } from './utils' import { navigationData, navPromo, sidePanelContent } from 'lib/products' -import PlaygroundDropdown from '../playground-dropdown' +import SandboxDropdown from '../sandbox-dropdown' import s from './product-page-content.module.css' const ProductPageHeaderContent = () => { @@ -30,14 +29,14 @@ const ProductPageHeaderContent = () => { const allProductsItems = getProductsDropdownItems() const productNavItems = getNavItems(currentProduct) - // Check if the current product has playground support - const supportedPlaygroundProducts = PLAYGROUND_CONFIG.products || [] - const hasPlayground = - PLAYGROUND_CONFIG.labs?.length > 0 && - supportedPlaygroundProducts.includes(currentProduct.slug) + // Check if the current product has sandbox support + const supportedSandboxProducts = SANDBOX_CONFIG.products || [] + const hasSandbox = + SANDBOX_CONFIG.labs?.length > 0 && + supportedSandboxProducts.includes(currentProduct.slug) - // Get playground labs for the current product - const labs = PLAYGROUND_CONFIG.labs || [] + // Get sandbox labs for the current product + const labs = SANDBOX_CONFIG.labs || [] const currentProductLabs = labs.filter((lab) => lab.products.includes(currentProduct.slug) ) @@ -69,17 +68,14 @@ const ProductPageHeaderContent = () => { {productNavItems.map((navItem: NavItem) => { const ariaLabel = `${currentProduct.name} ${navItem.label}` const isSubmenu = 'items' in navItem - const isPlayground = navItem.label === 'Playground' + const isSandbox = navItem.label === 'Sandbox' - if (isPlayground && hasPlayground) { + if (isSandbox && hasSandbox) { return (
  • - +
    • diff --git a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts index ebf9a8d6cd..586a8f5e5f 100644 --- a/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts +++ b/src/components/navigation-header/components/product-page-content/utils/__tests__/get-nav-items.test.ts @@ -44,8 +44,8 @@ describe('getNavItems', () => { "url": "/nomad/commands", }, { - "label": "Playground", - "url": "/nomad/playground", + "label": "Sandbox", + "url": "/nomad/sandbox", }, { "label": "Integrations", @@ -239,8 +239,8 @@ describe('getNavItems', () => { "label": "Documentation", }, { - "label": "Playground", - "url": "/terraform/playground", + "label": "Sandbox", + "url": "/terraform/sandbox", }, { "label": "Registry", diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index d38e3fdfd9..9a90aaee86 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -11,7 +11,7 @@ import { getDocsNavItems } from 'lib/docs/get-docs-nav-items' import { getIsEnabledProductIntegrations } from 'lib/integrations/get-is-enabled-product-integrations' import { ProductData } from 'types/products' import { NavItem } from './types' -import PLAYGROUND_CONFIG from 'data/playground.json' +import SANDBOX_CONFIG from 'data/sandbox.json' const TRY_CLOUD_ITEM_PRODUCT_SLUGS = [ 'boundary', @@ -151,17 +151,17 @@ export function getNavItems(currentProduct: ProductData): NavItem[] { } /** - * Add Playground item if there are any labs configured + * Add Sandbox item if there are any labs configured * and the current product is in the supported products list */ - const supportedPlaygroundProducts = PLAYGROUND_CONFIG.products || [] + const supportedSandboxProducts = SANDBOX_CONFIG.products || [] if ( - PLAYGROUND_CONFIG.labs?.length && - supportedPlaygroundProducts.includes(currentProduct.slug) + SANDBOX_CONFIG.labs?.length && + supportedSandboxProducts.includes(currentProduct.slug) ) { items.push({ - label: 'Playground', - url: `/${currentProduct.slug}/playground`, + label: 'Sandbox', + url: `/${currentProduct.slug}/sandbox`, }) } diff --git a/src/components/navigation-header/components/playground-dropdown/index.tsx b/src/components/navigation-header/components/sandbox-dropdown/index.tsx similarity index 82% rename from src/components/navigation-header/components/playground-dropdown/index.tsx rename to src/components/navigation-header/components/sandbox-dropdown/index.tsx index 431ed99a6c..158bdc8008 100644 --- a/src/components/navigation-header/components/playground-dropdown/index.tsx +++ b/src/components/navigation-header/components/sandbox-dropdown/index.tsx @@ -11,7 +11,7 @@ import { IconChevronRight16 } from '@hashicorp/flight-icons/svg-react/chevron-ri import { useRouter } from 'next/router' import { useCurrentProduct } from 'contexts' import { useInstruqtEmbed } from 'contexts/instruqt-lab' -import { trackPlaygroundEvent } from 'lib/analytics' +import { trackSandboxEvent } from 'lib/analytics' import useOnClickOutside from 'hooks/use-on-click-outside' import useOnEscapeKeyDown from 'hooks/use-on-escape-key-down' import useOnFocusOutside from 'hooks/use-on-focus-outside' @@ -19,12 +19,12 @@ import useOnRouteChangeStart from 'hooks/use-on-route-change-start' import deriveKeyEventState from 'lib/derive-key-event-state' import Text from 'components/text' import ProductIcon from 'components/product-icon' -import PLAYGROUND_CONFIG from 'data/playground.json' -import s from './playground-dropdown.module.css' +import SANDBOX_CONFIG from 'data/sandbox.json' +import s from './sandbox-dropdown.module.css' import { ProductSlug } from 'types/products' -// Define the type to match the structure in playground.json -type PlaygroundLab = { +// Define the type to match the structure in sandbox.json +type SandboxLab = { id?: string labId: string title: string @@ -32,12 +32,12 @@ type PlaygroundLab = { products: string[] } -interface PlaygroundDropdownProps { +interface SandboxDropdownProps { ariaLabel: string label: string } -const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { +const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => { const uniqueId = useId() const router = useRouter() const currentProduct = useCurrentProduct() @@ -45,11 +45,11 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { const menuRef = useRef() const activatorButtonRef = useRef() const [isOpen, setIsOpen] = useState(false) - const [otherPlaygroundsOpen, setOtherPlaygroundsOpen] = useState(false) - const menuId = `playground-dropdown-menu-${uniqueId}` + const [otherSandboxesOpen, setOtherSandboxesOpen] = useState(false) + const menuId = `sandbox-dropdown-menu-${uniqueId}` - // Item data from playground config - const labs = PLAYGROUND_CONFIG.labs as PlaygroundLab[] + // Item data from sandbox config + const labs = SANDBOX_CONFIG.labs as SandboxLab[] // Filter labs for current product and other products const currentProductLabs = labs.filter((lab) => @@ -136,9 +136,9 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { /** * Handle lab selection */ - const handleLabClick = (lab: PlaygroundLab) => { + const handleLabClick = (lab: SandboxLab) => { openLab(lab.labId) - trackPlaygroundEvent('playground_started', { + trackSandboxEvent('sandbox_started', { labId: lab.labId, page: router.asPath, }) @@ -146,20 +146,20 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { } /** - * Navigate to the playground page + * Navigate to the sandbox page */ - const navigateToPlaygroundPage = (e: React.MouseEvent) => { + const navigateToSandboxPage = (e: React.MouseEvent) => { e.preventDefault() - router.push(`/${currentProduct.slug}/playground`) + router.push(`/${currentProduct.slug}/sandbox`) setIsOpen(false) } /** - * Toggle the other playgrounds accordion + * Toggle the other sandboxes accordion */ - const toggleOtherPlaygrounds = (e: React.MouseEvent) => { + const toggleOtherSandboxes = (e: React.MouseEvent) => { e.preventDefault() - setOtherPlaygroundsOpen(!otherPlaygroundsOpen) + setOtherSandboxesOpen(!otherSandboxesOpen) } return ( @@ -192,7 +192,7 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { style={{ display: isOpen ? 'block' : 'none' }} >
    - {/* Introduction to Playgrounds */} + {/* Introduction to Sandboxes */}
    { size={200} weight="semibold" > - HashiCorp Playgrounds + HashiCorp Sandboxes { {/* Learn more link */} - Learn more about Playgrounds + Learn more about Sandboxes @@ -230,21 +230,21 @@ const PlaygroundDropdown = ({ ariaLabel, label }: PlaygroundDropdownProps) => { {/* Divider */}
    - {/* Available Product Playgrounds Section */} + {/* Available Product Sandboxes Section */} - Available {currentProduct.name} Playgrounds + Available {currentProduct.name} Sandboxes
      {currentProductLabs.map((lab, index) => (
    - {/* Other Playgrounds Accordion (only show if there are other playgrounds) */} + {/* Other Sandboxes Accordion (only show if there are other sandboxes) */} {otherProductLabs.length > 0 && ( <>
    - {otherPlaygroundsOpen && ( + {otherSandboxesOpen && (
      {otherProductLabs.map((lab, index) => (

    - Each playground comes pre-configured with everything you need to start - using the product immediately. Just click on a playground below to - launch it in your browser. + Each sandbox comes pre-configured with everything you need to start + using the product immediately. Just click on a sandbox below to launch + it in your browser.

    - - {/*
    -

    Getting Started

    -

    - When you launch a playground, you'll be presented with a terminal interface where you can - interact with the pre-configured environment. The playground runs in your browser and - doesn't require any downloads or installations. -

    -

    - Each playground session lasts for up to 1 hour, giving you plenty of time to experiment. - Your work isn't saved between sessions, so be sure to copy any important configurations - before your session ends. -

    -
    */}
    -

    Available {product.name} playgrounds

    +

    Available {product.name} sandboxes

    - When you launch a playground, you'll be presented with a terminal - interface where you can interact with the pre-configured environment. - The playground runs in your browser and doesn't require any downloads or - installations. + When you launch a sandbox, you'll be presented with a terminal interface + where you can interact with the pre-configured environment. The sandbox + runs in your browser and doesn't require any downloads or installations.

    - Each playground session lasts for up to 1 hour, giving you plenty of - time to experiment. Your work isn't saved between sessions, so be sure - to copy any important configurations before your session ends. + Each sandbox session lasts for up to 1 hour, giving you plenty of time + to experiment. Your work isn't saved between sessions, so be sure to + copy any important configurations before your session ends.

    - {availablePlaygrounds.length > 0 ? ( + {availableSandboxes.length > 0 ? ( - {availablePlaygrounds.map((lab, index) => ( + {availableSandboxes.map((lab, index) => (
    handleLabClick(lab.labId)} > @@ -148,32 +133,32 @@ export default function PlaygroundView({
    - +
    ))} ) : ( -

    - There are currently no playgrounds available for {product.name}. Check - back later or explore other product playgrounds. +

    + There are currently no sandboxes available for {product.name}. Check + back later or explore other product sandboxes.

    )} - {otherPlaygrounds.length > 0 && ( + {otherSandboxes.length > 0 && ( <> -

    Other playgrounds

    +

    Other sandboxes

    - Explore playgrounds for other HashiCorp products that you might find + Explore sandboxes for other HashiCorp products that you might find useful.

    - {otherPlaygrounds.map((lab, index) => ( + {otherSandboxes.map((lab, index) => (
    handleLabClick(lab.labId)} > @@ -192,9 +177,7 @@ export default function PlaygroundView({
    - +
    @@ -207,8 +190,8 @@ export default function PlaygroundView({ } export const getStaticPaths: GetStaticPaths = async () => { - // Get the list of supported products from playground.json - const supportedProducts = PLAYGROUND_CONFIG.products || [] + // Get the list of supported products from sandbox.json + const supportedProducts = SANDBOX_CONFIG.products || [] // Generate paths for all products that are in the supported products list const paths = supportedProducts @@ -223,34 +206,34 @@ export const getStaticPaths: GetStaticPaths = async () => { } } -export const getStaticProps: GetStaticProps = async ({ +export const getStaticProps: GetStaticProps = async ({ params, }) => { const productSlug = params?.productSlug as string const product = PRODUCT_DATA_MAP[productSlug] - const supportedProducts = PLAYGROUND_CONFIG.products || [] + const supportedProducts = SANDBOX_CONFIG.products || [] - // Only show playground page if product is in the supported products list + // Only show sandbox page if product is in the supported products list if (!product || !supportedProducts.includes(productSlug)) { return { notFound: true, } } - // Filter playgrounds that are relevant to this product - const availablePlaygrounds = PLAYGROUND_CONFIG.labs.filter((lab) => + // Filter sandboxes that are relevant to this product + const availableSandboxes = SANDBOX_CONFIG.labs.filter((lab) => lab.products.includes(productSlug) ) - // Filter playgrounds that are NOT relevant to this product - const otherPlaygrounds = PLAYGROUND_CONFIG.labs.filter( + // Filter sandboxes that are NOT relevant to this product + const otherSandboxes = SANDBOX_CONFIG.labs.filter( (lab) => !lab.products.includes(productSlug) ) const breadcrumbLinks = [ { title: 'Developer', url: '/' }, { title: product.name, url: `/${productSlug}` }, - { title: 'Playground', url: `/${productSlug}/playground` }, + { title: 'Sandbox', url: `/${productSlug}/sandbox` }, ] const sidebarNavDataLevels = [ @@ -258,35 +241,23 @@ export const getStaticProps: GetStaticProps = async ({ generateProductLandingSidebarNavData(product), ] - // Add playground links - const playgroundMenuItems: MenuItem[] = [ + // Add sandbox links + const sandboxMenuItems: MenuItem[] = [ { - title: `${product.name} Playground`, - fullPath: `/${productSlug}/playground`, + title: `${product.name} Sandbox`, + fullPath: `/${productSlug}/sandbox`, theme: product.slug, isActive: true, }, ] - if (product.playgroundConfig?.sidebarLinks) { - playgroundMenuItems.push( - { heading: 'Resources' }, - ...product.playgroundConfig.sidebarLinks.map((link) => ({ - title: link.title, - path: link.href, - href: link.href, - isActive: false, - })) - ) - } - sidebarNavDataLevels.push({ backToLinkProps: { text: `${product.name} Home`, href: `/${product.slug}`, }, - title: 'Playground', - menuItems: playgroundMenuItems, + title: 'Sandbox', + menuItems: sandboxMenuItems, showFilterInput: false, visuallyHideTitle: true, levelButtonProps: { @@ -302,8 +273,8 @@ export const getStaticProps: GetStaticProps = async ({ breadcrumbLinks, navLevels: sidebarNavDataLevels, }, - availablePlaygrounds, - otherPlaygrounds, + availableSandboxes, + otherSandboxes, }, } } diff --git a/src/pages/[productSlug]/playground/playground.module.css b/src/pages/[productSlug]/playground/playground.module.css index f529e86a11..10f71f81df 100644 --- a/src/pages/[productSlug]/playground/playground.module.css +++ b/src/pages/[productSlug]/playground/playground.module.css @@ -9,13 +9,13 @@ justify-content: center; } -.playgroundDropdown { +.sandboxDropdown { min-width: 480px; max-height: 80vh; overflow-y: auto; } -.playgroundIntro { +.sandboxIntro { margin: 32px 0; } @@ -56,7 +56,7 @@ padding-top: 24px; } -.playgroundCard { +.sandboxCard { cursor: pointer; transition: transform 0.2s ease, box-shadow 0.2s ease; @@ -99,7 +99,7 @@ } } -.noPlaygrounds { +.noSandboxes { margin: 32px 0; padding: 24px; background-color: var(--token-color-surface-faint); diff --git a/src/types/products.ts b/src/types/products.ts index 55bd2ce04e..b3259e0939 100644 --- a/src/types/products.ts +++ b/src/types/products.ts @@ -148,20 +148,6 @@ interface ProductData extends Product { } basePaths: string[] rootDocsPaths: RootDocsPath[] - playgroundConfig?: { - sidebarLinks: { - title: string - href: string - }[] - description?: string - labs?: { - id: string - name: string - instruqtId: string - description: string - products: ProductSlug[] - }[] - } /** * When configuring docsNavItems, authors have the option to specify * the full data structure, or use a string that matches a rootDocsPath.path From e1b3a578c9912bb008a359e5f454fbbaceadf829 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 20 Mar 2025 09:11:26 -0700 Subject: [PATCH 22/53] rename straggler to sandbox --- src/pages/[productSlug]/{playground => sandbox}/index.tsx | 0 .../playground.module.css => sandbox/sandbox.module.css} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename src/pages/[productSlug]/{playground => sandbox}/index.tsx (100%) rename src/pages/[productSlug]/{playground/playground.module.css => sandbox/sandbox.module.css} (100%) diff --git a/src/pages/[productSlug]/playground/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx similarity index 100% rename from src/pages/[productSlug]/playground/index.tsx rename to src/pages/[productSlug]/sandbox/index.tsx diff --git a/src/pages/[productSlug]/playground/playground.module.css b/src/pages/[productSlug]/sandbox/sandbox.module.css similarity index 100% rename from src/pages/[productSlug]/playground/playground.module.css rename to src/pages/[productSlug]/sandbox/sandbox.module.css From f722721a32b615f876be0b91133e4f531b328fc9 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 24 Mar 2025 14:00:29 -0700 Subject: [PATCH 23/53] Use enum instead of string Co-authored-by: Robert Main <50675045+rmainwork@users.noreply.github.com> --- src/lib/analytics.ts | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/lib/analytics.ts b/src/lib/analytics.ts index 9903a75eda..26338dc362 100644 --- a/src/lib/analytics.ts +++ b/src/lib/analytics.ts @@ -144,8 +144,13 @@ const trackProductDownload = ({ /** * Tracks sandbox events using PostHog */ +export enum SANDBOX_EVENT = { + SANDBOX_STARTED = 'sandbox_started', + SANDBOX_OPEN = 'sandbox_open', + SANDBOX_CLOSED = 'sandbox_closed', +} export const trackSandboxEvent = ( - eventName: 'sandbox_started' | 'sandbox_open' | 'sandbox_closed', + eventName: `${SANDBOX_EVENT}`, properties: { labId: string page: string From a5d8721a3cd13981be872cd3122f8a80d62fd2bd Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 24 Mar 2025 14:03:50 -0700 Subject: [PATCH 24/53] move posthog events to dedicated lib, use enum instead of string for consistency --- .../components/sandbox-dropdown/index.tsx | 4 +-- src/contexts/instruqt-lab/index.tsx | 6 ++--- src/lib/analytics.ts | 20 -------------- src/lib/posthog-events.ts | 26 +++++++++++++++++++ src/pages/[productSlug]/sandbox/index.tsx | 4 +-- 5 files changed, 33 insertions(+), 27 deletions(-) create mode 100644 src/lib/posthog-events.ts diff --git a/src/components/navigation-header/components/sandbox-dropdown/index.tsx b/src/components/navigation-header/components/sandbox-dropdown/index.tsx index 158bdc8008..4fb4af8b13 100644 --- a/src/components/navigation-header/components/sandbox-dropdown/index.tsx +++ b/src/components/navigation-header/components/sandbox-dropdown/index.tsx @@ -11,7 +11,7 @@ import { IconChevronRight16 } from '@hashicorp/flight-icons/svg-react/chevron-ri import { useRouter } from 'next/router' import { useCurrentProduct } from 'contexts' import { useInstruqtEmbed } from 'contexts/instruqt-lab' -import { trackSandboxEvent } from 'lib/analytics' +import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' import useOnClickOutside from 'hooks/use-on-click-outside' import useOnEscapeKeyDown from 'hooks/use-on-escape-key-down' import useOnFocusOutside from 'hooks/use-on-focus-outside' @@ -138,7 +138,7 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => { */ const handleLabClick = (lab: SandboxLab) => { openLab(lab.labId) - trackSandboxEvent('sandbox_started', { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, { labId: lab.labId, page: router.asPath, }) diff --git a/src/contexts/instruqt-lab/index.tsx b/src/contexts/instruqt-lab/index.tsx index 96a2b8d7b8..21dc1feb2e 100644 --- a/src/contexts/instruqt-lab/index.tsx +++ b/src/contexts/instruqt-lab/index.tsx @@ -17,7 +17,7 @@ import dynamic from 'next/dynamic' import { useRouter } from 'next/router' import EmbedElement from 'components/lab-embed/embed-element' import Resizable from 'components/lab-embed/resizable' -import { trackSandboxEvent } from 'lib/analytics' +import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' interface InstruqtContextProps { labId: string | null @@ -87,7 +87,7 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { useEffect(() => { // Track when a sandbox is open while navigating to different pages if (active && labId) { - trackSandboxEvent('sandbox_open', { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_OPEN, { labId, page: router.asPath, }) @@ -107,7 +107,7 @@ function InstruqtProvider({ children }: InstruqtProviderProps): JSX.Element { const closeLab = useCallback(() => { if (active && labId) { - trackSandboxEvent('sandbox_closed', { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_CLOSED, { labId, page: router.asPath, }) diff --git a/src/lib/analytics.ts b/src/lib/analytics.ts index 26338dc362..5688326772 100644 --- a/src/lib/analytics.ts +++ b/src/lib/analytics.ts @@ -141,24 +141,4 @@ const trackProductDownload = ({ }) } -/** - * Tracks sandbox events using PostHog - */ -export enum SANDBOX_EVENT = { - SANDBOX_STARTED = 'sandbox_started', - SANDBOX_OPEN = 'sandbox_open', - SANDBOX_CLOSED = 'sandbox_closed', -} -export const trackSandboxEvent = ( - eventName: `${SANDBOX_EVENT}`, - properties: { - labId: string - page: string - } -): void => { - if (window?.posthog?.capture) { - window.posthog.capture(eventName, properties) - } -} - export { safeAnalyticsTrack, trackProductDownload } diff --git a/src/lib/posthog-events.ts b/src/lib/posthog-events.ts new file mode 100644 index 0000000000..36c29e1819 --- /dev/null +++ b/src/lib/posthog-events.ts @@ -0,0 +1,26 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +/** + * Tracks sandbox events using PostHog + */ + +export enum SANDBOX_EVENT { + SANDBOX_STARTED = 'sandbox_started', + SANDBOX_OPEN = 'sandbox_open', + SANDBOX_CLOSED = 'sandbox_closed', +} + +export const trackSandboxEvent = ( + eventName: `${SANDBOX_EVENT}`, + properties: { + labId: string + page: string + } +): void => { + if (window?.posthog?.capture) { + window.posthog.capture(eventName, properties) + } +} diff --git a/src/pages/[productSlug]/sandbox/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx index abeebd4ed2..a3e0b64e83 100644 --- a/src/pages/[productSlug]/sandbox/index.tsx +++ b/src/pages/[productSlug]/sandbox/index.tsx @@ -7,7 +7,7 @@ import { GetStaticPaths, GetStaticProps } from 'next' import { PRODUCT_DATA_MAP } from 'data/product-data-map' import SidebarSidecarLayout from 'layouts/sidebar-sidecar' import { useInstruqtEmbed } from 'contexts/instruqt-lab' -import { trackSandboxEvent } from 'lib/analytics' +import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' import { generateTopLevelSidebarNavData, generateProductLandingSidebarNavData, @@ -56,7 +56,7 @@ export default function SandboxView({ const handleLabClick = (labId: string) => { openLab(labId) - trackSandboxEvent('sandbox_started', { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_STARTED, { labId, page: `/${product.slug}/sandbox`, }) From a4fc9bd83820c1d16908b10938f48e1abc3ed8c8 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 24 Mar 2025 14:11:43 -0700 Subject: [PATCH 25/53] remove interactivelabwrapper since we moved instruqt provider into main app layout --- src/hooks/use-posthog-analytics.ts | 1 - src/views/tutorial-view/index.tsx | 134 ++++++++---------- .../tutorial-view/index.tsx | 86 ++++++----- .../tutorial-view/index.tsx | 86 ++++++----- 4 files changed, 143 insertions(+), 164 deletions(-) diff --git a/src/hooks/use-posthog-analytics.ts b/src/hooks/use-posthog-analytics.ts index 7e3060bdf7..01c6acc2a7 100644 --- a/src/hooks/use-posthog-analytics.ts +++ b/src/hooks/use-posthog-analytics.ts @@ -37,7 +37,6 @@ export default function usePostHogPageAnalytics(): void { useEffect(() => { // Ensures code only runs if PostHog has been initialized - console.log('window?.posthog', window?.posthog) if (!window?.posthog) return window.posthog.config.capture_pageview = false diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index 11563c4201..d8c3678161 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -143,7 +143,6 @@ function TutorialView({ ) const hasVideo = Boolean(video) const isInteractive = Boolean(handsOnLab) - const InteractiveLabWrapper = isInteractive ? Fragment : Fragment const nextPreviousData = getNextPrevious({ currentCollection: collectionCtx.current, currentTutorialSlug: slug, @@ -263,78 +262,71 @@ function TutorialView({ ) : null} - - - - ) : null - } - sidecarSlot={} - mainWidth={layoutProps.mainWidth} - > - - - - {hasVideo && video.id && !video.videoInline && ( - - )} - + - - - - } + mainWidth={layoutProps.mainWidth} + > + + + + {hasVideo && video.id && !video.videoInline && ( + - {layoutProps.isCertificationPrep && ( - - )} - - - - + )} + + + + + + {layoutProps.isCertificationPrep && ( + + )} + + + ) } diff --git a/src/views/validated-patterns/tutorial-view/index.tsx b/src/views/validated-patterns/tutorial-view/index.tsx index f505abdae6..98d0516f39 100644 --- a/src/views/validated-patterns/tutorial-view/index.tsx +++ b/src/views/validated-patterns/tutorial-view/index.tsx @@ -45,7 +45,6 @@ export default function ValidatedPatternsTutorialView({ const featuredInWithoutCurrent = collectionCtx.featuredIn?.filter( (c) => c.id !== collectionCtx.current.id ) - const InteractiveLabWrapper = isInteractive ? InstruqtProvider : Fragment const canonicalCollectionSlug = tutorial.collectionCtx.default.slug const canonicalUrl = generateCanonicalUrl(canonicalCollectionSlug, slug) @@ -54,52 +53,47 @@ export default function ValidatedPatternsTutorialView({ - - - } - breadcrumbLinks={layoutProps.breadcrumbLinks} - sidebarNavDataLevels={layoutProps.navLevels} - mainWidth="narrow" - sidecarTopSlot={ - variant ? ( - - ) : null - } - > - + } + breadcrumbLinks={layoutProps.breadcrumbLinks} + sidebarNavDataLevels={layoutProps.navLevels} + mainWidth="narrow" + sidecarTopSlot={ + variant ? ( + + ) : null + } + > + + {video?.id && !video.videoInline && ( + - {video?.id && !video.videoInline && ( - - )} - - - - - - + )} + + + + + ) } diff --git a/src/views/well-architected-framework/tutorial-view/index.tsx b/src/views/well-architected-framework/tutorial-view/index.tsx index bfda50402c..7a81d3e773 100644 --- a/src/views/well-architected-framework/tutorial-view/index.tsx +++ b/src/views/well-architected-framework/tutorial-view/index.tsx @@ -45,7 +45,6 @@ export default function WellArchitectedFrameworkTutorialView({ const featuredInWithoutCurrent = collectionCtx.featuredIn?.filter( (c) => c.id !== collectionCtx.current.id ) - const InteractiveLabWrapper = isInteractive ? InstruqtProvider : Fragment const canonicalCollectionSlug = tutorial.collectionCtx.default.slug const canonicalUrl = generateCanonicalUrl(canonicalCollectionSlug, slug) @@ -54,52 +53,47 @@ export default function WellArchitectedFrameworkTutorialView({ - - - } - breadcrumbLinks={layoutProps.breadcrumbLinks} - sidebarNavDataLevels={layoutProps.navLevels} - mainWidth="narrow" - sidecarTopSlot={ - variant ? ( - - ) : null - } - > - + } + breadcrumbLinks={layoutProps.breadcrumbLinks} + sidebarNavDataLevels={layoutProps.navLevels} + mainWidth="narrow" + sidecarTopSlot={ + variant ? ( + + ) : null + } + > + + {video?.id && !video.videoInline && ( + - {video?.id && !video.videoInline && ( - - )} - - - - - - + )} + + + + + ) } From 44a7722c07cf7882a6c6bb7cf389b8c9e83d2b88 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 1 Apr 2025 09:49:04 -0700 Subject: [PATCH 26/53] Update src/data/sandbox.json Co-authored-by: Brian McClain --- src/data/sandbox.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/data/sandbox.json b/src/data/sandbox.json index d379f0b52b..ec221992c4 100644 --- a/src/data/sandbox.json +++ b/src/data/sandbox.json @@ -3,7 +3,7 @@ "labs": [ { "title": "Terraform Sandbox", - "description": "Get started quickly with a container-based sandbox host. Choose a container when you need a fast, lightweight Linux system", + "description": "Get started quickly with Terraform. This sandbox includes Docker and LocalStack preinstalled to test your Terraform configuration.", "products": ["terraform"], "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE" }, From 6c43e35900d8e523b3e3f1375ec3d0671c4322ca Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 1 Apr 2025 13:05:01 -0700 Subject: [PATCH 27/53] add test cases --- .../__tests__/embed-element.test.tsx | 67 +++++ .../resizable/__tests__/resizable.test.tsx | 149 ++++++++++++ .../resizable/components/resizer.tsx | 37 ++- .../__tests__/sandbox-dropdown.test.tsx | 169 +++++++++++++ .../__tests__/sandbox-item.test.tsx | 75 ++++++ .../generate-resources-nav-items.test.ts | 87 +++++++ .../__tests__/instruqt-lab.test.tsx | 228 ++++++++++++++++++ 7 files changed, 808 insertions(+), 4 deletions(-) create mode 100644 src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx create mode 100644 src/components/lab-embed/resizable/__tests__/resizable.test.tsx create mode 100644 src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx create mode 100644 src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx create mode 100644 src/components/sidebar/helpers/__tests__/generate-resources-nav-items.test.ts create mode 100644 src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx diff --git a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx new file mode 100644 index 0000000000..b1199959bb --- /dev/null +++ b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx @@ -0,0 +1,67 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { render, screen } from '@testing-library/react' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import EmbedElement from '../index' + +// Mock the useInstruqtEmbed hook +const mockUseInstruqtEmbed = vi.fn() +vi.mock('contexts/instruqt-lab', () => ({ + useInstruqtEmbed: () => mockUseInstruqtEmbed(), +})) + +describe('EmbedElement', () => { + beforeEach(() => { + vi.clearAllMocks() + mockUseInstruqtEmbed.mockImplementation(() => ({ + active: true, + labId: 'test-lab-id', + })) + }) + + it('renders an iframe with the correct props', () => { + render() + + const iframe = screen.getByTitle('Instruqt') + expect(iframe).toBeInTheDocument() + expect(iframe.tagName).toBe('IFRAME') + expect(iframe).toHaveAttribute( + 'src', + 'https://play.instruqt.com/embed/test-lab-id' + ) + expect(iframe).toHaveAttribute( + 'sandbox', + 'allow-same-origin allow-scripts allow-popups allow-forms allow-modals' + ) + }) + + it('has proper focus behavior when mounted', () => { + const { container } = render() + + const iframe = screen.getByTitle('Instruqt') + expect(document.activeElement).toBe(iframe) + }) + + it('has the correct styles when active', () => { + render() + + const iframe = screen.getByTitle('Instruqt') + expect(iframe.className).not.toContain('_hide_') + }) + + it('has the correct styles when not active', () => { + // Mock the hook to return active: false + mockUseInstruqtEmbed.mockImplementation(() => ({ + active: false, + labId: 'test-lab-id', + })) + + render() + + const iframe = screen.getByTitle('Instruqt') + expect(iframe.className).toContain('_hide_') + }) +}) diff --git a/src/components/lab-embed/resizable/__tests__/resizable.test.tsx b/src/components/lab-embed/resizable/__tests__/resizable.test.tsx new file mode 100644 index 0000000000..6c57d68314 --- /dev/null +++ b/src/components/lab-embed/resizable/__tests__/resizable.test.tsx @@ -0,0 +1,149 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { render, screen, fireEvent } from '@testing-library/react' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import Resizable from '../index' +import s from '../resizable.module.css' + +// Mock the useInstruqtEmbed hook +const mockUseInstruqtEmbed = vi.fn() +vi.mock('contexts/instruqt-lab', () => ({ + useInstruqtEmbed: () => mockUseInstruqtEmbed(), +})) + +describe('Resizable', () => { + const mockSetPanelActive = vi.fn() + const mockCloseLab = vi.fn() + + beforeEach(() => { + vi.clearAllMocks() + mockUseInstruqtEmbed.mockImplementation(() => ({ + closeLab: mockCloseLab, + })) + }) + + it('renders children when panel is active', () => { + render( + +
    Child content
    +     + ) + + expect(screen.getByTestId('test-child')).toBeInTheDocument() + }) + + it('does not render children when panel is not active', () => { + render( + +
    Child content
    +     + ) + + // Check that the main resizable container has the 'hide' class + const resizableContainer = screen + .getByTestId('test-child') + .closest('div._resizable_17d1f1') + expect(resizableContainer).toHaveClass(s.hide) + + // Also ensure the child itself is not directly queried if hidden by parent + expect(screen.queryByTestId('test-child')).toBeInTheDocument() // It should exist in the DOM + }) + + it('has the correct initial height', () => { + render( + +
    Child content
    +     + ) + + const resizableDiv = screen + .getByTestId('test-child') + .closest('div[data-resizing]') + expect(resizableDiv).toHaveStyle('height: 500px') + }) + + it('calls closeLab when close button is clicked', () => { + render( + +
    Child content
    +     + ) + + const closeButton = screen.getByRole('button', { name: /close/i }) + fireEvent.click(closeButton) + + expect(mockCloseLab).toHaveBeenCalled() + }) + + it('starts resizing when resizer is clicked', () => { + render( + +
    Child content
    +     + ) + + const resizer = screen.getByRole('button', { name: /resize/i }) + fireEvent.mouseDown(resizer, { screenY: 100 }) + + const resizableDiv = screen + .getByTestId('test-child') + .closest('div[data-resizing]') + expect(resizableDiv).toHaveAttribute('data-resizing', 'true') + }) + + it('changes height during resizing', () => { + render( + +
    Child content
    +     + ) + + const resizer = screen.getByRole('button', { name: /resize/i }) + fireEvent.mouseDown(resizer, { screenY: 500 }) + + // Simulate mouse move + fireEvent.mouseMove(window, { screenY: 450 }) + + const resizableDiv = screen + .getByTestId('test-child') + .closest('div[data-resizing]') + expect(resizableDiv).toHaveStyle('height: 450px') + + // Simulate mouse up to stop resizing + fireEvent.mouseUp(window) + expect(resizableDiv).toHaveAttribute('data-resizing', 'false') + }) +}) diff --git a/src/components/lab-embed/resizable/components/resizer.tsx b/src/components/lab-embed/resizable/components/resizer.tsx index 595d4b2047..ca22066027 100644 --- a/src/components/lab-embed/resizable/components/resizer.tsx +++ b/src/components/lab-embed/resizable/components/resizer.tsx @@ -6,8 +6,9 @@ import { MouseEventHandler } from 'react' import CSS from 'csstype' import { IconX24 } from '@hashicorp/flight-icons/svg-react/x-24' -import InlineSvg from '@hashicorp/react-inline-svg' -import ResizeBar from './img/resize_bar.svg?include' +// Removing the InlineSvg import which is causing issues in tests +// import InlineSvg from '@hashicorp/react-inline-svg' +// import ResizeBar from './img/resize_bar.svg?include' import s from './resizer.module.css' interface ResizerProps { @@ -31,10 +32,38 @@ export default function Resizer({ className={s.resizer} onMouseDown={onMouseDown} onMouseUp={onMouseUp} + role="button" + aria-label="Resize panel" + tabIndex={0} > - + {/* Replace InlineSvg with direct SVG for testing */} + + + + - diff --git a/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx b/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx new file mode 100644 index 0000000000..16eb0c175d --- /dev/null +++ b/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx @@ -0,0 +1,169 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { render, screen, fireEvent } from '@testing-library/react' +import { useRouter } from 'next/router' +import { useCurrentProduct } from 'contexts' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import SandboxDropdown from '../index' +import SANDBOX_CONFIG from 'data/sandbox.json' + +// Mock the hooks +const mockUserRouter = vi.fn() +vi.mock('next/router', () => ({ + useRouter: () => mockUserRouter(), +})) + +const mockUseCurrentProduct = vi.fn() +vi.mock('contexts', () => ({ + useCurrentProduct: () => mockUseCurrentProduct(), +})) + +const mockUseInstruqtEmbed = vi.fn() +vi.mock('contexts/instruqt-lab', () => ({ + useInstruqtEmbed: () => mockUseInstruqtEmbed(), +})) + +describe('SandboxDropdown', () => { + beforeEach(() => { + // Reset all mocks before each test + vi.clearAllMocks() + + // Setup default mock implementations + mockUserRouter.mockImplementation(() => ({ + asPath: '/', + events: { + on: vi.fn(), + off: vi.fn(), + }, + })) + + mockUseCurrentProduct.mockImplementation(() => ({ + name: 'Vault', + slug: 'vault', + })) + + mockUseInstruqtEmbed.mockImplementation(() => ({ + openLab: vi.fn(), + })) + }) + + it('renders the sandbox dropdown with correct label', () => { + render() + expect( + screen.getByRole('button', { name: 'Sandbox menu' }) + ).toBeInTheDocument() + }) + + it('opens and closes on click', () => { + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Click to open + fireEvent.click(button) + expect(screen.getByText('HashiCorp Sandboxes')).toBeInTheDocument() + + // Click to close + fireEvent.click(button) + + // Check the dropdown container's display style + const dropdown = document.querySelector('[class*="dropdownContainer"]') + expect(dropdown).toHaveStyle('display: none') + }) + + it('closes on escape key', () => { + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + expect(screen.getByText('HashiCorp Sandboxes')).toBeInTheDocument() + + // Press escape + fireEvent.keyDown(button, { key: 'Escape' }) + + // Check the dropdown container's display style + const dropdown = document.querySelector('[class*="dropdownContainer"]') + expect(dropdown).toHaveStyle('display: none') + }) + + it('closes on click outside', () => { + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + expect(screen.getByText('HashiCorp Sandboxes')).toBeInTheDocument() + + // Click outside + fireEvent.mouseDown(document.body) + + // Check the dropdown container's display style + const dropdown = document.querySelector('[class*="dropdownContainer"]') + expect(dropdown).toHaveStyle('display: none') + }) + + it('displays available sandboxes for current product', () => { + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + + // Check for available sandboxes section + expect(screen.getByText(/Available.*Sandboxes/)).toBeInTheDocument() + }) + + it('displays other sandboxes section', () => { + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + + // Check for other sandboxes section + expect(screen.getByText('Other Sandboxes')).toBeInTheDocument() + }) + + it('opens lab when clicking a sandbox item', () => { + const mockOpenLab = vi.fn() + mockUseInstruqtEmbed.mockImplementation(() => ({ + openLab: mockOpenLab, + })) + + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + + // Find a sandbox item and click it + const sandboxItem = screen.getByText('Vault Playground (test)') + fireEvent.click(sandboxItem.closest('button')) + + // Verify openLab was called + expect(mockOpenLab).toHaveBeenCalled() + }) + + it('tracks sandbox events when opening labs', () => { + const mockOpenLab = vi.fn() + mockUseInstruqtEmbed.mockImplementation(() => ({ + openLab: mockOpenLab, + })) + + render() + const button = screen.getByRole('button', { name: 'Sandbox menu' }) + + // Open dropdown + fireEvent.click(button) + + // Find a sandbox item and click it + const sandboxItem = screen.getByText('Vault Playground (test)') + fireEvent.click(sandboxItem.closest('button')) + + // Verify openLab was called + expect(mockOpenLab).toHaveBeenCalled() + }) +}) diff --git a/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx b/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx new file mode 100644 index 0000000000..5b5586900d --- /dev/null +++ b/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx @@ -0,0 +1,75 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { render, screen, fireEvent } from '@testing-library/react' +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import SandboxItem from '../index' + +// Mock the hooks +const mockUseInstruqtEmbed = vi.fn() +vi.mock('contexts/instruqt-lab', () => ({ + useInstruqtEmbed: () => mockUseInstruqtEmbed(), +})) + +describe('SandboxItem', () => { + const mockItem = { + label: 'Test Sandbox', + description: 'Test Description', + labId: 'test-lab-id', + products: ['vault'], + onClick: vi.fn(), + } + + beforeEach(() => { + vi.clearAllMocks() + mockUseInstruqtEmbed.mockImplementation(() => ({ + openLab: vi.fn(), + })) + }) + + it('renders sandbox item with title and description', () => { + render() + + expect(screen.getByText('Test Sandbox')).toBeInTheDocument() + expect(screen.getByText('Test Description')).toBeInTheDocument() + }) + + it('renders product icon', () => { + render() + + // Find SVG element instead of trying to find by role="img" + const icon = document.querySelector('svg') + expect(icon).toBeInTheDocument() + expect(icon.parentElement.className).toContain('productIcon') + }) + + it('calls onClick handler when clicked', () => { + render() + + const item = screen.getByRole('link') + fireEvent.click(item) + + expect(mockItem.onClick).toHaveBeenCalled() + }) + + it('tracks sandbox event when clicked', () => { + render() + + const item = screen.getByRole('link') + fireEvent.click(item) + + // Verify event tracking (you'll need to implement this based on your tracking setup) + // expect(mockTrackEvent).toHaveBeenCalledWith('sandbox_opened', {...}) + }) + + it('applies correct styles when hovered', () => { + render() + + const item = screen.getByRole('link') + fireEvent.mouseEnter(item) + + expect(item.className).toContain('playground') + }) +}) diff --git a/src/components/sidebar/helpers/__tests__/generate-resources-nav-items.test.ts b/src/components/sidebar/helpers/__tests__/generate-resources-nav-items.test.ts new file mode 100644 index 0000000000..aa05f33c67 --- /dev/null +++ b/src/components/sidebar/helpers/__tests__/generate-resources-nav-items.test.ts @@ -0,0 +1,87 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { generateResourcesNavItems } from '../generate-resources-nav-items' +import { ProductSlug } from 'types/products' +import SANDBOX_CONFIG from 'data/sandbox.json' + +describe('generateResourcesNavItems', () => { + it('includes sandbox items in the resources navigation', () => { + // Sample product data + const productSlug = 'vault' as ProductSlug + + // Generate the navigation items + const navItems = generateResourcesNavItems(productSlug) + + // Find the sandbox item + const sandboxItem = navItems.find( + (item) => 'title' in item && item.title === 'Sandbox' + ) + + // Verify the sandbox item exists and has the correct properties + expect(sandboxItem).toBeDefined() + expect('href' in sandboxItem).toBe(true) + expect(sandboxItem['href']).toBe('/vault/sandbox') + }) + + it('handles products with no available sandboxes', () => { + // Sample product data for a product with no sandboxes + const productSlug = 'non-existent-product' as ProductSlug + + // Generate the navigation items + const navItems = generateResourcesNavItems(productSlug) + + // Find the sandbox item + const sandboxItem = navItems.find( + (item) => 'title' in item && item.title === 'Sandbox' + ) + + // Verify the sandbox item doesn't exist for unsupported products + expect(sandboxItem).toBeUndefined() + }) + + it('includes sandbox link for supported products', () => { + // Mock the supported products in SANDBOX_CONFIG + const originalProducts = SANDBOX_CONFIG.products + const productSlug = 'nomad' as ProductSlug + + // Generate the navigation items + const navItems = generateResourcesNavItems(productSlug) + + // Find the sandbox item + const sandboxItem = navItems.find( + (item) => 'title' in item && item.title === 'Sandbox' + ) + + // Verify the sandbox item exists for supported products + expect(sandboxItem).toBeDefined() + if (sandboxItem && 'href' in sandboxItem) { + expect(sandboxItem.href).toBe('/nomad/sandbox') + } + }) + + it('includes common resource links for all products', () => { + const productSlug = 'vault' as ProductSlug + + // Generate the navigation items + const navItems = generateResourcesNavItems(productSlug) + + // Find common resources + const tutorialLibrary = navItems.find( + (item) => 'title' in item && item.title === 'Tutorial Library' + ) + const communityForum = navItems.find( + (item) => 'title' in item && item.title === 'Community Forum' + ) + const support = navItems.find( + (item) => 'title' in item && item.title === 'Support' + ) + + // Verify common resources exist + expect(tutorialLibrary).toBeDefined() + expect(communityForum).toBeDefined() + expect(support).toBeDefined() + }) +}) diff --git a/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx b/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx new file mode 100644 index 0000000000..3a95f07e8e --- /dev/null +++ b/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx @@ -0,0 +1,228 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { render, screen, fireEvent, act } from '@testing-library/react' +import { useRouter } from 'next/router' +import InstruqtProvider, { useInstruqtEmbed } from '../index' +import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' + +// Mock dependencies +const mockRouter = vi.fn() +vi.mock('next/router', () => ({ + useRouter: () => mockRouter(), +})) + +vi.mock('lib/posthog-events', () => ({ + trackSandboxEvent: vi.fn(), + SANDBOX_EVENT: { + SANDBOX_OPEN: 'sandbox_open', + SANDBOX_CLOSED: 'sandbox_closed', + }, +})) + +// Mock localStorage +const mockLocalStorage = { + getItem: vi.fn(), + setItem: vi.fn(), +} + +Object.defineProperty(window, 'localStorage', { + value: mockLocalStorage, +}) + +describe('InstruqtEmbed Context', () => { + beforeEach(() => { + vi.clearAllMocks() + + mockRouter.mockImplementation(() => ({ + asPath: '/test-path', + events: { + on: vi.fn(), + off: vi.fn(), + }, + })) + + // Clear localStorage mock implementation + mockLocalStorage.getItem.mockReset() + mockLocalStorage.setItem.mockReset() + }) + + it('provides default context values', async () => { + const TestComponent = () => { + const context = useInstruqtEmbed() + return ( +
    + {context.labId || 'no-lab'} + + {context.active ? 'active' : 'inactive'} + +
    + ) + } + + render( + + + + ) + + expect(await screen.findByTestId('lab-id')).toHaveTextContent('no-lab') + expect(await screen.findByTestId('active')).toHaveTextContent('inactive') + }) + + it('restores state from localStorage on mount', async () => { + mockLocalStorage.getItem.mockImplementation(() => + JSON.stringify({ + active: true, + storedLabId: 'stored-lab-id', + }) + ) + + const TestComponent = () => { + const context = useInstruqtEmbed() + return ( +
    + {context.labId || 'no-lab'} + + {context.active ? 'active' : 'inactive'} + +
    + ) + } + + render( + + + + ) + + expect(mockLocalStorage.getItem).toHaveBeenCalledWith('instruqt-lab-state') + expect(await screen.findByTestId('lab-id')).toHaveTextContent( + 'stored-lab-id' + ) + expect(await screen.findByTestId('active')).toHaveTextContent('active') + }) + + it('persists state changes to localStorage', async () => { + const TestComponent = () => { + const { openLab } = useInstruqtEmbed() + return + } + + render( + + + + ) + + // Open lab + fireEvent.click(await screen.findByText('Open Lab')) + + // Check localStorage was called to save the new state + expect(mockLocalStorage.setItem).toHaveBeenCalledWith( + 'instruqt-lab-state', + JSON.stringify({ + active: true, + storedLabId: 'new-lab-id', + }) + ) + }) + + it('tracks sandbox events when opening a lab', async () => { + const TestComponent = () => { + const { openLab } = useInstruqtEmbed() + return + } + + render( + + + + ) + + fireEvent.click(await screen.findByText('Open Lab')) + + // Change route to trigger the tracking + act(() => { + // We don't need to actually change the asPath since the test is checking + // the call with the current path, which is still '/test-path' + mockRouter.mockImplementation(() => ({ + asPath: '/test-path', + events: { + on: vi.fn(), + off: vi.fn(), + }, + })) + }) + + expect(trackSandboxEvent).toHaveBeenCalledWith(SANDBOX_EVENT.SANDBOX_OPEN, { + labId: 'test-lab-id', + page: '/test-path', + }) + }) + + it('tracks sandbox events when closing a lab', async () => { + const TestComponent = () => { + const { openLab, closeLab } = useInstruqtEmbed() + return ( + <> + + + + ) + } + + render( + + + + ) + + // First open a lab + fireEvent.click(await screen.findByTestId('open')) + + // Then close it + fireEvent.click(await screen.findByTestId('close')) + + expect(trackSandboxEvent).toHaveBeenCalledWith( + SANDBOX_EVENT.SANDBOX_CLOSED, + { + labId: 'test-lab-id', + page: '/test-path', + } + ) + }) + + // Commenting out this test as it depends on EmbedElement which is challenging to mock properly + /* + it('renders EmbedElement when lab is active', () => { + const TestComponent = () => { + const { openLab } = useInstruqtEmbed() + return ( + + ) + } + + render( + + + + ) + + // Check no embed is present initially + expect(screen.queryByTitle('Instruqt')).not.toBeInTheDocument() + + // Open lab + fireEvent.click(screen.getByText('Open Lab')) + + // Check embed element is now present + expect(screen.getByTitle('Instruqt')).toBeInTheDocument() + }) + */ +}) From 8ac2ff52f9c4e5d586e70aa52065913e749965f5 Mon Sep 17 00:00:00 2001 From: stellarsquall Date: Wed, 2 Apr 2025 10:26:22 -0600 Subject: [PATCH 28/53] adds boundary sandbox --- src/data/sandbox.json | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/data/sandbox.json b/src/data/sandbox.json index ec221992c4..db4c5f297a 100644 --- a/src/data/sandbox.json +++ b/src/data/sandbox.json @@ -1,5 +1,5 @@ { - "products": ["terraform", "vault", "consul", "nomad"], + "products": ["terraform", "vault", "boundary", "consul", "nomad"], "labs": [ { "title": "Terraform Sandbox", @@ -13,6 +13,12 @@ "products": ["vault"], "labId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB" }, + { + "title": "Boundary Sandbox", + "description": "Learn how to manage a Boundary cluster, configure and connect to targets, and set up target credentials.", + "products": ["boundary"], + "labId": "hashicorp-learn/tracks/boundary-sandbox?token=em_YHsmJu4K1Wk3hwht" + }, { "title": "Nomad sandbox", "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", From 2f759739d5c692d36609f3f24ace1bb59c18e820 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 2 Apr 2025 21:39:08 -0700 Subject: [PATCH 29/53] update sandbox labids --- src/data/sandbox.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/data/sandbox.json b/src/data/sandbox.json index db4c5f297a..267086913d 100644 --- a/src/data/sandbox.json +++ b/src/data/sandbox.json @@ -5,13 +5,13 @@ "title": "Terraform Sandbox", "description": "Get started quickly with Terraform. This sandbox includes Docker and LocalStack preinstalled to test your Terraform configuration.", "products": ["terraform"], - "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_7UQwSJt0EbYq9YlE" + "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_3vgTsBqCLq2blqtQ" }, { - "title": "Vault Playground (test)", + "title": "Vault Sandbox", "description": "Learn how to manage your secrets with Vault", "products": ["vault"], - "labId": "hashicorp-learn/tracks/vault-sandbox?token=em_usmVkoZLWz8SAXNB" + "labId": "hashicorp-learn/tracks/vault-cluster-sandbox?token=em_MmJD6C6DhTpGm9Ab" }, { "title": "Boundary Sandbox", @@ -20,22 +20,22 @@ "labId": "hashicorp-learn/tracks/boundary-sandbox?token=em_YHsmJu4K1Wk3hwht" }, { - "title": "Nomad sandbox", + "title": "Nomad Sandbox", "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", - "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", - "products": ["nomad", "consul"] + "products": ["nomad", "consul"], + "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc" }, { - "title": "Sandbox environment for Consul (Service discovery)", + "title": "Consul Sandbox (Service discovery)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", - "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", - "products": ["consul"] + "products": ["consul"], + "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD" }, { - "title": "Sandbox environment for Consul (Service mesh)", + "title": "Consul Sandbox (Service mesh)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", - "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM", - "products": ["consul"] + "products": ["consul"], + "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM" } ] } From 6db0b4143dc6c358eada4eb691b66a4916ad405a Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 2 Apr 2025 21:51:14 -0700 Subject: [PATCH 30/53] improve copy for launchign sandbox in the dropdown --- .eslintrc.js | 5 +++++ src/pages/[productSlug]/sandbox/index.tsx | 4 +++- 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 .eslintrc.js diff --git a/.eslintrc.js b/.eslintrc.js new file mode 100644 index 0000000000..c5830895cd --- /dev/null +++ b/.eslintrc.js @@ -0,0 +1,5 @@ +module.exports = { + root: true, + extends: './node_modules/@hashicorp/platform-cli/config/.eslintrc.js', + /* Specify overrides here */ +} diff --git a/src/pages/[productSlug]/sandbox/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx index a3e0b64e83..988c0fa2cc 100644 --- a/src/pages/[productSlug]/sandbox/index.tsx +++ b/src/pages/[productSlug]/sandbox/index.tsx @@ -96,7 +96,9 @@ export default function SandboxView({

    -

    Available {product.name} sandboxes

    +

    + Available {product.name} sandboxes. Click to launch the sandbox. +

    When you launch a sandbox, you'll be presented with a terminal interface From 02a98b7326fbd8b2375401124ea46422ff3be822 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 3 Apr 2025 09:59:49 -0700 Subject: [PATCH 31/53] revert changes --- .eslintrc.js | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 .eslintrc.js diff --git a/.eslintrc.js b/.eslintrc.js deleted file mode 100644 index c5830895cd..0000000000 --- a/.eslintrc.js +++ /dev/null @@ -1,5 +0,0 @@ -module.exports = { - root: true, - extends: './node_modules/@hashicorp/platform-cli/config/.eslintrc.js', - /* Specify overrides here */ -} From 985407672a869859326e4b5dc1f9a384bb3ce59f Mon Sep 17 00:00:00 2001 From: danielehc <40759828+danielehc@users.noreply.github.com> Date: Thu, 17 Apr 2025 19:18:47 +0200 Subject: [PATCH 32/53] Change Consul lab URL --- src/data/sandbox.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/data/sandbox.json b/src/data/sandbox.json index 267086913d..a627c72293 100644 --- a/src/data/sandbox.json +++ b/src/data/sandbox.json @@ -29,13 +29,13 @@ "title": "Consul Sandbox (Service discovery)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], - "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD" + "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD" }, { "title": "Consul Sandbox (Service mesh)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], - "labId": "hashicorp-learn/tracks/consul-sandbox-lab?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM" + "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM" } ] } From 04bb67f1218b670b9dc751c37739bb8efba21d8d Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 30 Apr 2025 16:25:43 -0700 Subject: [PATCH 33/53] add and render docs for sandboxes --- public/img/sandbox/hashicorp.png | Bin 0 -> 2489 bytes .../components/product-page-content/index.tsx | 2 +- .../utils/get-nav-items.ts | 2 +- .../__tests__/sandbox-dropdown.test.tsx | 4 - .../components/sandbox-dropdown/index.tsx | 2 +- .../generate-resources-nav-items.test.ts | 2 +- .../helpers/generate-resources-nav-items.ts | 2 +- src/content/sandbox/docs/boundary.mdx | 274 ++++++++++++++++++ src/content/sandbox/docs/consul.mdx | 263 +++++++++++++++++ src/content/sandbox/docs/nomad.mdx | 217 ++++++++++++++ src/content/sandbox/docs/terraform.mdx | 58 ++++ src/content/sandbox/docs/vault.mdx | 132 +++++++++ src/{data => content/sandbox}/sandbox.json | 15 +- src/pages/[productSlug]/sandbox/index.tsx | 164 +++++++---- .../[productSlug]/sandbox/sandbox.module.css | 50 ++++ src/types/next-mdx-remote.d.ts | 28 ++ src/types/sandbox.ts | 29 ++ 17 files changed, 1178 insertions(+), 66 deletions(-) create mode 100644 public/img/sandbox/hashicorp.png create mode 100644 src/content/sandbox/docs/boundary.mdx create mode 100644 src/content/sandbox/docs/consul.mdx create mode 100644 src/content/sandbox/docs/nomad.mdx create mode 100644 src/content/sandbox/docs/terraform.mdx create mode 100644 src/content/sandbox/docs/vault.mdx rename src/{data => content/sandbox}/sandbox.json (86%) create mode 100644 src/types/next-mdx-remote.d.ts create mode 100644 src/types/sandbox.ts diff --git a/public/img/sandbox/hashicorp.png b/public/img/sandbox/hashicorp.png new file mode 100644 index 0000000000000000000000000000000000000000..7c7104bb6ad5aaaa6a184b38233c4a6544f70396 GIT binary patch literal 2489 zcmb7``9ISQ0LLd!9yd=tLvH2X-BzpKJVW@zkG0x_Lf5YlKdbLNC;(xbOM36pg+Bgm-}Z1 z?OZVYSy7I*&gLIJeE6x$%gYN33-j~yGcz+QD=RNvya){q4G0Lx$;qM7Xb1$t-rgPt zgMq=|!NI|pn3%D#v97MJhYugRxw)B|nlcy+GMNm8LKPGg%FD~~c)X8~PfbltUtb>@ zjh2y-ArJ^S94;avLRD2&S65e5RCLRwNC*VtJwhQ(oudlA=6^{n))$ROssH}CupkjO zYuS1t73{>9QnkB1_@t`YeeUnuCaD_$N}X^1FTqZ&|H)AZsNsk;ZSEbaXrsmNXvhh^ zDb>GpOL2fCo%UDyyB4yzg&#yA8ZdhjTb)Md(&r6Rvq{Yenlbq})zm-&_x&+9E|8dS zl`2KKMeXcJwt4`C_sC%nAi)ecNK)I&?p&u9<>9yu8|&CGE94Aj-f1K%kqE7s7V$(^ zHkYP|+Rz*S) z;c*%PBdokHGqEa=vHSnd5tS^9jg?<{Pc`n`yx0H-)GlFkaIUW9o!nScQ{%HTgt`W= z#n!wk4CYp4eD*ApDyz!ca)58uA@*>bu@(9;8zxZ0K24|e*B{?LaU?lqZx$YMH&?b_ zaa^dsw)w?9T|PV{wef&IEZ$U&Z2VT!VPA?yxfiMYb^Snv0-{z-#s@mMI4K{-r_?_K z0BbUF>YH$eR=!Rtn}tew(sK5OTCKKgLx}SsKkEG{u>63;g&LihD0yM*z=<WnEygvG73WT{0P2^G>N)f#z zn)&^X&&{#hSA?->y8av8f7bFtx|{_4(>&0nb(F_GdtnFT;|x-Gdn}OF`y06uijAgD z@M!BY(nr{zuhX^g%1m{0inTVA`uNT#o{Hj7N?H4x%t<%$l6;M7+u#V366TpvnI*h+ zl}-pFr1Y>uSPUd9@pThWIDO`--bk5I-g4@l+M-C4(s)J-h`3zZzG5>Wouf_W)AB&h(#x!#e+ES|mU{<1#Tfw=1E%E4jGClWHT z2JZYN0>EO$fy<4d(B3+v^SeiB(EM$8pz0R2InLMcC&PSJ7l11o^^)0BPQY5@?&fE5-Q>p0;~o0H!cA$h9`2Rt%sK{a5I7(G+GY=!#&wO zPZEax4ij(|b1!lxc^yx!+0^#zc-&y=Yzku5!@qBOP?pC;AFbB7ARZ@#;j6@np4kB< z-o5RX2G?BXYLbVU$l7%syuU%6l=6eS^Q`l{Y8QrquB^)8CW-eu)->(IUjRtcV3HIk z>4cH6POZ6O=*4~WvY;MVFnBka$%j|Iq>oc5vhz&yR(KYv5is_yR_t#Nkrow}ZGK+K z8@Uo;-z(zWz#qqHA=5a6xjv@}TGL?(=dh>}mL%7rTv%3CPh`&gnmnVOM{31`!+pMP zxBscCi`ng*F%X zbxERlTIumfIiOW~!2FgmyP+#L`Hr*7BknCD5-|-C^7*a}?s&<75hnps9!Pg6qC-N@&ix=yXQzSVCPS z(d(GFJG$t?4R}VU2z98!y(G=Ic;rjkC#Dr^wSd&Ir1hNH#c0eN_m8p%c6aaXeYL_q z=M7xp_U6*5psXDwm&*?IjaHtN-|&@K*?ovV56`Z~d+nwujnkoV=X0jQ1f{<%bymPN zEkVyazXvKqQJ6QGIp4H}9`%zfH3WL#rYW`uo58D{KWeWBTN_3sef1VQ$RKC?#BYbX zDNbObfdk#3a#(kZ+|1B^gNKjwE&o}E^S~7C3bMuay}4nvg&XO{kRZq&5|gGa^AWlK z-Ox1Cr@33X)8*+ao+OQnI{tZNwN*$j%8@OxREvWHcB04tTkaw5sn?`OHuwdBZAULR zM7;@sQKeZX==1d`kifn+f&$aAUoNraa98En@Qa`B$U|o13y^MNuq%D|1*B`IJ%)Fp zJganXse7^yUPSMgZGs&-6Vsn0Kml>9AWRr?#w`JFL2}assTfQL)#eFfl^W7%7p3bc zzJSray7k63Q`-QpL-gg>vYVIJsi$12GxygJcl?6eXuz{kzInZ*&m~P { it('includes sandbox items in the resources navigation', () => { diff --git a/src/components/sidebar/helpers/generate-resources-nav-items.ts b/src/components/sidebar/helpers/generate-resources-nav-items.ts index bf95782c77..c9fba36160 100644 --- a/src/components/sidebar/helpers/generate-resources-nav-items.ts +++ b/src/components/sidebar/helpers/generate-resources-nav-items.ts @@ -9,7 +9,7 @@ import { VALID_EDITION_SLUGS_FOR_FILTERING, VALID_PRODUCT_SLUGS_FOR_FILTERING, } from 'views/tutorial-library/constants' -import SANDBOX_CONFIG from 'data/sandbox.json' +import SANDBOX_CONFIG from 'content/sandbox/sandbox.json' /** * Note: these ResourceNav types could probably be abstracted up or lifted out, diff --git a/src/content/sandbox/docs/boundary.mdx b/src/content/sandbox/docs/boundary.mdx new file mode 100644 index 0000000000..207ba9852d --- /dev/null +++ b/src/content/sandbox/docs/boundary.mdx @@ -0,0 +1,274 @@ + + + + + + + + +This environment is not production-ready as it does not follow our recommendations for production-ready cluster deployments. Please refer to the [Install Boundary](/boundary/docs/install-boundary) documentation and the [Boundary Enterprise Deployment Guide](/boundary/tutorials/enterprise/ent-deployment-guide) pages for more information. + +This is a development and testing environment. It provides the learner an opportunity to interact with a Boundary Community Edition cluster, and sets up a target the learner can configure for access using Boundary. This environment can serve as a companion to the documentation, or a place to experiment with the product. + + + +**Overview** +The Boundary cluster contains one controller server and one worker, each with Boundary installed and running. A PostgreSQL database is running on the Boundary controller. + +The Boundary target is an Ubuntu 24.04 server with the openssh-server and postgresql-server packages installed. SSH is configured to allow for password access for the following users: + +- Danielle: + - username: `danielle` + - password: `danielle_password` +- Oliver: + - username: `oliver` + - password: `oliver_password` +- Steve: + - username: `steve` + - password: `steve_password` + +This sandbox also configures a postgres database that is available on port `5432`: + +- name: `northwind` + - username: `postgres` + - password: `postgres` + +**Access the Boundary Admin UI** + +You can log in to the Boundary Admin UI in the tab named `Boundary Admin UI`. You can switch to the `Boundary Admin UI` tab. + +To log into the Boundary Admin UI, use the following credentials for the admin user: + +- Username: `global-admin` +- Password: `password` + +Or log in as the unprivileged user: + +- Username: `user` +- Password: `password` + +**Within Boundar, the following resources are configured:** + +- Org: `sandbox org` +- Project: `sandbox project` +- Host Catalogs: + - `ubuntu-target-host-catalog` + - `controller-host-catalog` +- Credential Store: + - `ubuntu-target-creds` +- Targets: + - `northwind-db` + - `ubuntu-target-ssh` + - `boundary-db` + + +You can access these targets from the Boundary workstation by configuring the CLI. + +**CLI Access** +The shell in the [`boundary-workstation` tab](tab-0) has the Boundary, Vault, and Terraform CLI tools installed. + +The sandbox automatically sets the following environment variables: +- `BOUNDARY_ADDR=http://boundary-controller:9200` +- `VAULT_ADDR=http://vault-server:8200` + +You can log into Boundary from the CLI using the admin credentials: + +- Username: `global-admin` +- Password: `password` + +```shell-session +$ boundary authenticate +Please enter the login name (it will be hidden): +Please enter the password (it will be hidden): +Authentication information: + Account ID: acctpw_sC5a4GP9JA + Auth Method ID: ampw_CzkwJb5RRR + Expiration Time: Thu, 03 Apr 2025 01:36:55 UTC + User ID: u_UURrzGLCik +The token name "default" was successfully stored in the chosen keyring and is not displayed here. +``` + +After authentication, you can connect to targets using the `boundary connect` command. +To connect to the `northwind` database on the `ubuntu-target` host: + +```shell-session +$ boundary connect postgres northwind +Credentials are being brokered but no -dbname parameter provided. psql may misinterpret another parameter as the database name. +psql (16.8 (Ubuntu 16.8-0ubuntu0.24.04.1)) +SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off) +Type "help" for help. +postgres=# +``` + +When you connect to the `ubuntu-target` host it will display the available brokered credentials for the `oliver` and `danielle` users, and automatically select one of them to log you in as. Copy and paste or type the user's password to connect: + +```shell-session +$ boundary connect ssh ubuntu-target +Credentials: + Credential Source Description: Credentials for oliver user on ubuntu-target host + Credential Source ID: credup_XuqoTfBGrj + Credential Source Name: oliver-creds + Credential Store ID: csst_iHuwhwzstA + Credential Store Type: static + Credential Type: username_password + Secret: + password: oliver_password + username: oliver + Credential Source Description: Credentials for danielle user on ubuntu-target host + Credential Source ID: credup_po69wMQRNN + Credential Source Name: danielle-creds + Credential Store ID: csst_iHuwhwzstA + Credential Store Type: static + Credential Type: username_password + Secret: + password: danielle_password + username: danielle +The authenticity of host 'hst_hi2n8ghvx8 ([127.0.0.1]:45223)' can't be established. +ED25519 key fingerprint is SHA256:kCPyzCG/O2ckQ5zvoxT1O9NTgNz+KNnTf+fDildd0QI. +This key is not known by any other names. +Are you sure you want to continue connecting (yes/no/[fingerprint])? yes +Warning: Permanently added 'hst_hi2n8ghvx8' (ED25519) to the list of known hosts. +oliver@hst_hi2n8ghvx8's password: +oliver@ubuntu-target$ +``` + +You can also select a user to authenticate as by passing additional login +parameters to `boundary connect ssh`: + +```shell-session +$ boundary connect ssh ubuntu-target -username danielle +Credentials: + Credential Source Description: Credentials for oliver user on ubuntu-target host + Credential Source ID: credup_XuqoTfBGrj + Credential Source Name: oliver-creds + Credential Store ID: csst_iHuwhwzstA + Credential Store Type: static + Credential Type: username_password + Secret: + password: oliver_password + username: oliver + Credential Source Description: Credentials for danielle user on ubuntu-target host + Credential Source ID: credup_po69wMQRNN + Credential Source Name: danielle-creds + Credential Store ID: csst_iHuwhwzstA + Credential Store Type: static + Credential Type: username_password + Secret: + password: danielle_password + username: danielle +danielle@hst_hi2n8ghvx8's password: +danielle@ubuntu-target$ +``` + +**Vault integration** + +You can optionally set up Vault to act as a credential broker for Boundary. You can access the Vault server from the Boundary workstation, where the `VAULT_ADDR=https://vault-server:8200` environment variable is set. + +To learn more about setting up a Vault credential library, check out the [Vault credential brokering quickstart](/boundary/tutorials/credential-management/community-vault-cred-brokering-quickstart) tutorial. + +**Troubleshooting and experimenting** + +You can access the targets and databases directly without using Boundary. +For example, you can SSH into the ubuntu-target as the Oliver user: + +```shell-session +$ ssh oliver@ubuntu-target +oliver@hst_hi2n8ghvx8's password: +oliver@boundary-target$ +``` + +Or you can access the northwind database on the ubuntu-target with `psql`: + +```shell-session +$ psql -h ubuntu-target -d northwind -p 5432 -U postgres +psql (16.8 (Ubuntu 16.8-0ubuntu0.24.04.1)) +SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off) +Type "help" for help. +postgres=# +``` + +This bypasses Boundary, allows you to experiment with the target configuration. Note that you do not have root access to the target or other sandboxes. You can execute `systemctl` and `journalctl` on the controller and worker servers to restart the Boundary service if you make a configuration change, and view logs. + + + + +This sandbox contains: + +- A Boundary controller server with Boundary installed and running. A PostgreSQL + database is running on the Boundary controller. +- A Boundary worker server with Boundary installed and running. The worker is + pre-registered to the Boundary controller. +- A target Ubuntu 24.04 server with the openssh-server and postgresql-server + packages installed. SSH is configured to allow for password access for three + demo users. +- An optional Vault server to integrate with Boundary. +- A workstation server running Ubuntu 24.04 with the Boundary, Vault, Terraform, + and Postgres client CLI tools installed. + + + +``` +┌──────────────┐ ┌──────────────┐ +│ │ ┌─────────────────┐ │ │ +│ Target │ │ │ │ Vault Server │ +│(SSH, Postges)◄───────┤ Boundary Worker ├──────► (optional) │ +│ │ │ │ │ │ +└──────────────┘ └──────▲──┬───────┘ └──────────────┘ + │ │ + │ │ + ┌─────────────┘ └──────────────────┐ + │ │ + │ │ + │ +┌──── Boundary Control Plane ───┐ │ +│ │ │ +│ Controller │ ┌──────────▼───────────┐ +│ ◄────────► Boundary Workstation │ +│ (Postges Database) │ └──────────────────────┘ +│ │ +└───────────────────────────────┘ +``` + + + +This environment is not a production-ready. + +To learn more about Boundary's architecture, refer to the [Recommended architecture](/boundary/docs/install-boundary/architecture/recommended-architecture) section of the Boundary documentation. + + + + +This environment is not production-ready, as it does not follow recommendations for production cluster deployments. Refer to these resources for more information: + +- [Install Boundary](/boundary/docs/install-boundary) +- [Boundary reference architecture](/boundary/tutorials/enterprise/ent-reference-architecture) +- [Boundary Enterprise deployment guide](/boundary/tutorials/enterprise/ent-deployment-guide) +- [Vault with integrated storage reference architecture](/vault/tutorials/day-one-raft/raft-reference-architecture) +- [Vault with integrated storage deployment guide](/vault/tutorials/day-one-raft/raft-deployment-guide) +- [Harden Vault server deployments](/vault/tutorials/archive/production-hardening) + +**Community edition** + +The Boundary Sandbox uses the Boundary and Vault Community editions. This means you cannot use enterprise features here. + +**TLS** + +TLS is not enabled for any of the components in this sandbox environment. + +**Platform limitations** + +Because of the limitations of this platform: + +1. All servers are located in the same network. In a real-world example, the + Boundary control plane, target server, Vault cluster, and workstation would + be on separate, isolated networks. The Boundary worker is then placed on the + same network as the targets it provides access to, such as the SSH, database, + or Vault servers in this lab. +1. All servers can be accessed directly by SSH using their hostnames, bypassing Boundary. +1. The workstation and other servers do not allow root-level access. + + + + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/consul.mdx b/src/content/sandbox/docs/consul.mdx new file mode 100644 index 0000000000..944c833feb --- /dev/null +++ b/src/content/sandbox/docs/consul.mdx @@ -0,0 +1,263 @@ + + + + + + + + +This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. + +It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. + + + +This is a 3-node Consul community edition datacenter running in a Docker environment. + +Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. + +One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. + +**Architecture** + +Click on the "Architecture" tab to find a diagram of the deployed scenario. + +**Configuration and logs** + +You can find container data, configuration, and logs in the `var` directory. + +You can get an overview of the content using the `tree` command. + +```shell-session +$ tree /root/repository/var +``` + +**Access the nodes** + +The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: + +```shell-session +$ ssh -i certs/id_rsa admin@localhost -p 2222 +``` + +You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. + +**Interact with Consul** + +From the bastion host, you can directly interact with Consul. First, load necessary environment variables. + +```shell-session +$ source assets/scenario/env-consul.env +``` + +After that you can directly use Consul CLI to interact with your datacenter. + +```shell-session +$ consul members +``` + +You can also use the `Consul UI` tab to interact with Consul. + +If you want to login to the UI, use the token present in the `env-consul.env` file. + + + + +This sandbox has the following architecture: + + + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Consul Datacenter DC1 │ +│ │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ +│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-nginx-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-0 │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ +│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ +│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ +│ │ ┼──► consul-server-1 │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ +│ │ │ │ │ │ │ │ │ +│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ +│ │ │ │ │ │ │ │ │ +│ │ └───────────────────┘ │ │ │ │ │ +│ │ │ │ ┌────────────▼────────────┐ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-db-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ └─────────────────────────┘ │ │ +│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────┘ + + + ┌─────────────────────┐ + │ │ + │ Bastion Host │ + │ │ + └─────────────────────┘ +``` + + + + + + +The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. + +The command to start Consul on each node is: + +```shell-session +$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & +``` + +The command starts Consul in the background to not lock the terminal. + + + + + + + + + + + + + +This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. + +It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. + + + +This is a 3-node Consul community edition datacenter running in a Docker environment. + +Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. + +One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. + +**Architecture** + +Click on the "Architecture" tab to find a diagram of the deployed scenario. + +**Configuration and logs** + +You can find container data, configuration, and logs in the `var` directory. + +You can get an overview of the content using the `tree` command. + +```shell-session +$ tree /root/repository/var +``` + +**Access the nodes** + +The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: + +```shell-session +$ ssh -i certs/id_rsa admin@localhost -p 2222 +``` + +You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. + +**Interact with Consul** + +From the bastion host, you can directly interact with Consul. First, load necessary environment variables. + +```shell-session +$ source assets/scenario/env-consul.env +``` + +After that you can directly use Consul CLI to interact with your datacenter. + +```shell-session +$ consul members +``` + +You can also use the `Consul UI` tab to interact with Consul. + +If you want to login to the UI, use the token present in the `env-consul.env` file. + + + + +This sandbox has the following architecture: + + + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Consul Datacenter DC1 │ +│ │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ +│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-nginx-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-0 │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ +│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ +│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ +│ │ ┼──► consul-server-1 │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ +│ │ │ │ │ │ │ │ │ +│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ +│ │ │ │ │ │ │ │ │ +│ │ └───────────────────┘ │ │ │ │ │ +│ │ │ │ ┌────────────▼────────────┐ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-db-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ └─────────────────────────┘ │ │ +│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────┘ + + + ┌─────────────────────┐ + │ │ + │ Bastion Host │ + │ │ + └─────────────────────┘ +``` + + + + + + +The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. + +The command to start Consul on each node is: + +```shell-session +$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & +``` + +The command starts Consul in the background to not lock the terminal. + + + + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/nomad.mdx b/src/content/sandbox/docs/nomad.mdx new file mode 100644 index 0000000000..00a9f53949 --- /dev/null +++ b/src/content/sandbox/docs/nomad.mdx @@ -0,0 +1,217 @@ + + + + + + + + +This environment is not production-ready since it does not follow our +recommendations for production-ready cluster deployments. Please refer to the +Installing Nomad for Production and Consul VM production patterns pages for +more information. + +- [Installing Nomad for Production](/nomad/docs/install/production) +- [Consul VM production patterns](/consul/tutorials/production-vms) + +This goal of this sandbox is to serve as a development and testing environment. +It is "production-lite" — the Nomad cluster enables TLS and access control lists +(ACLs) for security but uses management and root tokens to simplify development +and testing. We do not recommend using management or root tokens in production. + + + +This is a Nomad cluster made up of one server and one client node. The server +and client nodes are each running the Nomad agent and Consul agent. Both agents +are configured with ACLs, gossip encryption, and TLS encryption. +The server node includes a running single-node Vault cluster that has been +initialized and unsealed. The client node has a scoped token for reading secrets +from Vault. You can also read Vault secrets from a Nomad jobspec. + +**Quick Start** + +This sandbox already configures tokens for Nomad, Consul, and Vault so you can +interact with the respective tools via the CLI. + +```shell-session +$ env | grep "NOMAD\|CONSUL\|VAULT" +``` + +You can find the Nomad and Consul management tokens in /ops/configs/tokens and +use them to log in to the web UIs. + +```shell-session +$ cat /ops/configs/tokens/nomad_mgmt.token +$ cat /ops/configs/tokens/consul_mgmt.token +``` + +You can find the Vault's unseal key, certificates, and root token in /ops/configs/vault. + +```shell-session +$ cat /ops/configs/vault/vault_root.token +``` + +This sandbox includes sample Nomad jobs. Use the following commands to submit +the jobs to Nomad: + +```shell-session +$ nomad job run /ops/configs/jobspecs/2048.hcl +$ nomad job run /ops/configs/jobspecs/terramino.hcl +$ nomad job run /ops/configs/jobspecs/hashicups.hcl +``` + + + + +**Infrastructure:** + +- Server node (node-01-server) + - n1-standard-2 VM (2 vCPU, 7.5GB RAM, 128GB disk) + - Nomad agent configured and running + - Access pre-configured with environment variables (NOMAD_*) + - Management token saved to NOMAD_TOKEN + - Consul agent configured and running + - Access pre-configured with environment variables (CONSUL_*) + - Management token saved to CONSUL_TOKEN + - Vault agent configured and running + - Access pre-configured with environment variables (VAULT_*) + - Root token saved to VAULT_TOKEN + +- Client node (node-02-client) + - n1-standard-2 VM (2 vCPU, 7.5GB RAM, 128GB disk) + - Nomad agent configured and running + - Consul agent configured and running + - Vault access pre-configured with environment variables (VAULT_*) + - Nomad drivers: `docker`, `exec`, `java`, `raw_exec` + +**Directory structure:** + +Environment related files are in the `/ops` directory. + + + +``` +/ops +└── configs + ├── agentfiles + │ ├── consul_server.hcl + │ └── nomad_server.hcl + ├── env-info + │ ├── ARCHITECTURE + │ ├── LIMITATIONS + │ └── README + ├── jobspecs + │ ├── 2048.hcl + │ ├── hashicups.hcl + │ └── terramino.hcl + ├── tokens + │ ├── consul_agent_server.token + │ ├── consul_dns.token + │ ├── consul_gossip_key + │ ├── consul_mgmt.token + │ ├── nomad_gossip_key + │ ├── nomad_mgmt.token + │ └── nomad_node_join.token + └── vault + ├── data + ├── dev-app-secrets.token + ├── unseal.key + ├── vault-cert.pem + ├── vault-key.pem + ├── vault-server.hcl + └── vault_root.token +``` + + + +Logs are output to the /tmp directory. + +```shell-session +$ ls /tmp +├── consul.log +├── nomad.log +└── vault.log +``` + +**HashiCorp applications:** + +The sandbox includes the following HashiCorp applications: + +- Nomad + - One server node and one client node + - ACLs enabled + - Gossip encryption enabled + - TLS encryption enabled + +- Consul + - One server node and one client node + - ACLs enabled + - Gossip encryption enabled + - TLS encryption enabled + - DNS configured (.consul domain) + +- Vault + - TLS encryption enabled + - Initialized and unsealed + +**Agent configuration and start process:** + +The agent files for Nomad and Consul exist in the /ops/configs/agentfiles +directory. Changes can be made to the agent configuration files and then the +tools can be restarted with the commands below. + +```shell-session +$ pkill nomad +$ nomad agent \ + -config=/ops/configs/agentfiles/nomad_server.hcl \ + >> /tmp/nomad.log 2>&1 & +``` + +```shell-session +$ pkill consul +$ consul agent \ + -config-file=/ops/configs/agentfiles/consul_server.hcl \ + >> /tmp/consul.log 2>&1 & +``` + +**Example Nomad applications:** + +The sandbox includes the following example applications: + +- `/ops/configs/jobspecs/2048.hcl`: Web-based game deployed in a single Docker container accessible on port 3333. +- `/ops/configs/jobspecs/terramino.hcl`: Web-based game deployed in three tiers accessible on port 4444. +- `/ops/configs/jobspecs/hashicups.hcl`: Web-based multi-tier coffee application accessible on port 3001. + +**Instruqt Scenario Tabs** + +The sandbox includes the following Instruqt scenario tabs: + +- Terminal shell (node-01-server) +- Visual code editor (node-01-server) +- Terminal shell (node-02-client) +- Nomad web UI (port 6443) +- Consul web UI (port 8443) +- Web browser open to port 3001 of node-02-client + - Default port for 2048.hcl application access +- Web browser open to port 3333 of node-02-client + - Default port for terramino.hcl application access +- Web browser open to port 4444 of node-02-client + - Default port for hashicups.hcl application access + + + + +The cluster is made up of one server one and one client node which is not what +we recommend for production environments. + +The Vault cluster is single-node. We do not recommend this for production +environments. + +Nomad jobspecs must be configured to use one of the ports exposed through the +Instruqt web browser tabs interface: `3001`, `3333`, or `4444`. + + + + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/terraform.mdx b/src/content/sandbox/docs/terraform.mdx new file mode 100644 index 0000000000..045da30e7e --- /dev/null +++ b/src/content/sandbox/docs/terraform.mdx @@ -0,0 +1,58 @@ + + + + + + +This sandbox includes the following preinstalled tools and services: + +- Terraform +- Docker +- LocalStack +- AWS CLI + +For more information, click on the "Architecture" tab. + +**Use LocalStack** + +LocalStack is a local AWS emulator that you can run the Terraform and the AWS CLI against to test your configuration and mock the deployment of resources. This sandbox includes a file named `localstack_overrides.tf` that configures the AWS provider in your configuration to point to LocalStack instead of trying to reach AWS. For the limitations of what APIs you can call using LocalStack, click on the "Limitations" tab. + +**Use AWS** + +If you would like you deploy resources to AWS, you can delete the `localstack_overrides.tf` file and configure the AWS provider using the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. + + + +Once the timer on the sandbox expires, this environment will be halted. If you have any resources managed by a local state file, this sandbox will not clean up those resources. Make sure to run `terraform destroy` before leaving the sandbox if you have configured the AWS provider to deploy real resources to your own AWS account. + + + + + + +This sandbox includes the following preinstalled tools and services: + +- **Terraform:** The Terraform CLI is installed locally and placed in the environment's PATH. To see which version of Terraform is installed in this sandbox, run the `terraform version` command. + +- **Docker:** Docker is already running with the default configuration. The Docker daemon socket file is located at `/var/run/docker.sock`. + +- **LocalStack:** LocalStack is already running in the local Docker instance. Additionally, the `localstack_override.tf` file is included to automatically configure your AWS provider to point to LocalStack rather than AWS. You do not need to make any changes to your configuration to connect to LocalStack. + +- **AWS CLI:** This sandbox has the `aws` command aliased to the `awslocal` CLI, the tool to make AWS CLI calls to LocalStack. You can use this tool just as you would the normal `aws` CLI. For example, the following command will communicate with LocalStack to get a list of the EC2 instances it currently has mocked. + + ```shell-session + $ aws ec2 describe-instances + ``` + + + + +![Hashicorp Logo](/img/sandbox/hashicorp.png) + +This sandbox is configured to use LocalStack, a local AWS API emulator. This sandbox uses the free edition of LocalStack, which has limitations on which resources it will allow you to deploy. For more information on which resources are included in the free version, refer to the [AWS service feature coverage](https://docs.localstack.cloud/user-guide/aws/feature-coverage/) documentation. + + + + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/vault.mdx b/src/content/sandbox/docs/vault.mdx new file mode 100644 index 0000000000..11978b206b --- /dev/null +++ b/src/content/sandbox/docs/vault.mdx @@ -0,0 +1,132 @@ + + + + + + +This is a 5-node Vault Community edition cluster with a reverse proxy running in a Docker environment. This environment initializes Vault with a Shamir seal, and one unseal key for convenience and simplicity. + +You can find container data, configuration, logs, and the plugins directory in the `/home/learner/sandbox-vault/containers` directory. Here are the contents of the `vault_sandbox_1` container directory as an example: + + + +``` +. +├── certs +│ ├── server_cert.pem +│ ├── server_key.pem +│ └── vault_sandbox_ca.pem +├── config +│ └── server.hcl +├── logs +│ └── vault_audit.log +└── plugins +``` + + + +You can browse these files from the Code Editor tab as well. + +If you need to directly access a container, you can use 'docker exec'. For example, to get a shell session in vault-1, use: + +```shell-session +$ docker exec -i -t vault-1 sh +``` + +Export one of the following to address the Vault cluster node you need to communicate with (reverse proxy by default): + +- `export VAULT_ADDR=https://localhost:8443` # Active node via reverse proxy +- `export VAULT_ADDR=https://localhost:8200` # Vault node 1 +- `export VAULT_ADDR=https://localhost:8220` # Vault node 2 +- `export VAULT_ADDR=https://localhost:8230` # Vault node 3 +- `export VAULT_ADDR=https://localhost:8240` # Vault node 4 +- `export VAULT_ADDR=https://localhost:8250` # Vault node 5 + +You can access the Vault UI for each node with the tabs labeled Vault 1 UI through Vault 5 UI. + +The environment enables Vault server telemetry from the active node to Prometheus, and you can use Grafana to access a dashboard in the Grafana tab with these credentials: + +- Username: `admin` +- Password: `2LearnVault` + + + + +The sandbox is composed of 5 Vault Docker containers, and a reverse proxy container. Not shown are the Prometheus and Grafana containers which handle telemetry metrics. + + + +``` + + localhost :8230 localhost:8240 + ┌──────────┐ ┌──────────┐ + │ │ │ │ + │ │ │ │ + │ vault-3 ├────────────────────────────────────────┤ vault-4 │ + │ │ │ │ + │ │ │ │ + └────┬─────┘ └─────┬────┘ + │ localhost:8220 localhost:8230 │ + │ ┌──────────┐ ┌──────────┐ │ + │ │ │ │ │ │ + │ │ │ │ │ │ + └────────┤ vault-2 │ │ vault-5 ├────────┘ + │ │ │ │ + │ │ │ │ + └────┬─────┘ └─────┬────┘ + │ │ + │ │ + │ localhost:8200 │ + │ ┌──────────┐ │ + │ │ │ │ + │ │ │ │ + └──────┤ vault-1 ├──────┘ + │ │ + │ │ + └─────┬────┘ + │ + │ + │ + │ + │ + │ + ┌─────┴────┐ + │ │ + https://localhost:8443 │ reverse │ + (proxy to active node) │ proxy │ + │ │ + └──────────┘ +``` + + + + + + +Vault Sandbox is a development and testing environment configured as "production-lite", and has limitations that you should be aware of. + +**Not production ready** + +This environment is not production-ready, as it does not follow recommendations for production cluster deployments. Refer to these resources for more information: + +- [Vault with integrated storage reference architecture](/vault/tutorials/day-one-raft/raft-reference-architecture) +- [Vault with integrated storage deployment guide](/vault/tutorials/day-one-raft/raft-deployment-guide) +- [Harden server deployments](/vault/tutorials/archive/production-hardening) + +**Community edition** + +Be aware that Vault Sandbox uses the Vault Community edition, and this imposes the limitation that you cannot use enterprise features here. + +**TLS** + +Vault Sandbox features mutual TLS between cluster nodes. You should be aware that the environment dynamically generates TLS material used to enable TLS with a 24 hour time to live. + +**Root token** + +Vault Sandbox uses and exposes the initial root token value for ease of development and testing. You should not rely on root token use for production implementations. + + + + + + \ No newline at end of file diff --git a/src/data/sandbox.json b/src/content/sandbox/sandbox.json similarity index 86% rename from src/data/sandbox.json rename to src/content/sandbox/sandbox.json index a627c72293..864028c876 100644 --- a/src/data/sandbox.json +++ b/src/content/sandbox/sandbox.json @@ -5,31 +5,36 @@ "title": "Terraform Sandbox", "description": "Get started quickly with Terraform. This sandbox includes Docker and LocalStack preinstalled to test your Terraform configuration.", "products": ["terraform"], - "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_3vgTsBqCLq2blqtQ" + "labId": "hashicorp-learn/tracks/terraform-sandbox?token=em_3vgTsBqCLq2blqtQ", + "documentation": "terraform.mdx" }, { "title": "Vault Sandbox", "description": "Learn how to manage your secrets with Vault", "products": ["vault"], - "labId": "hashicorp-learn/tracks/vault-cluster-sandbox?token=em_MmJD6C6DhTpGm9Ab" + "labId": "hashicorp-learn/tracks/vault-cluster-sandbox?token=em_MmJD6C6DhTpGm9Ab", + "documentation": "vault.mdx" }, { "title": "Boundary Sandbox", "description": "Learn how to manage a Boundary cluster, configure and connect to targets, and set up target credentials.", "products": ["boundary"], - "labId": "hashicorp-learn/tracks/boundary-sandbox?token=em_YHsmJu4K1Wk3hwht" + "labId": "hashicorp-learn/tracks/boundary-sandbox?token=em_YHsmJu4K1Wk3hwht", + "documentation": "boundary.mdx" }, { "title": "Nomad Sandbox", "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", "products": ["nomad", "consul"], - "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc" + "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", + "documentation": "nomad.mdx" }, { "title": "Consul Sandbox (Service discovery)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], - "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD" + "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", + "documentation": "consul.mdx" }, { "title": "Consul Sandbox (Service mesh)", diff --git a/src/pages/[productSlug]/sandbox/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx index 988c0fa2cc..11c53edfd9 100644 --- a/src/pages/[productSlug]/sandbox/index.tsx +++ b/src/pages/[productSlug]/sandbox/index.tsx @@ -22,9 +22,17 @@ import CardsGridList from 'components/cards-grid-list' import { BrandedHeaderCard } from 'views/product-integrations-landing/components/branded-header-card' import { MenuItem } from 'components/sidebar/types' import { ProductSlug } from 'types/products' -import SANDBOX_CONFIG from 'data/sandbox.json' +import { SandboxLab, SandboxConfig } from 'types/sandbox' +import SANDBOX_CONFIG from 'content/sandbox/sandbox.json' assert { type: 'json' } import ProductIcon from 'components/product-icon' +import { serialize } from 'lib/next-mdx-remote/serialize' +import DevDotContent from 'components/dev-dot-content' +import getDocsMdxComponents from 'views/docs-view/utils/get-docs-mdx-components' +import fs from 'fs' +import path from 'path' import s from './sandbox.module.css' +import docsViewStyles from 'views/docs-view/docs-view.module.css' +import classNames from 'classnames' interface SandboxPageProps { product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] @@ -32,18 +40,29 @@ interface SandboxPageProps { breadcrumbLinks: { title: string; url: string }[] navLevels: any[] } - availableSandboxes: { - title: string - description: string - products: string[] - labId: string - }[] - otherSandboxes: { - title: string - description: string - products: string[] - labId: string - }[] + availableSandboxes: SandboxLab[] + otherSandboxes: SandboxLab[] +} + +// Helper function to read and serialize MDX content +async function getMdxContent(filePath: string | undefined, productSlug: ProductSlug) { + if (!filePath) return null + try { + const fullPath = path.join(process.cwd(), 'src/content/sandbox/docs', filePath) + const fileContent = await fs.promises.readFile(fullPath, 'utf8') + return await serialize(fileContent, { + mdxOptions: { + remarkPlugins: [], + rehypePlugins: [], + }, + scope: { + product: productSlug, + }, + }) + } catch (error) { + console.error(`Error reading MDX file ${filePath}:`, error) + return null + } } export default function SandboxView({ @@ -53,6 +72,7 @@ export default function SandboxView({ otherSandboxes, }: SandboxPageProps) { const { openLab } = useInstruqtEmbed() + const docsMdxComponents = getDocsMdxComponents(product.slug) const handleLabClick = (labId: string) => { openLab(labId) @@ -62,6 +82,22 @@ export default function SandboxView({ }) } + const renderDocumentation = (documentation?: SandboxLab['documentation']) => { + if (!documentation) return null + + return ( +

    + +
    + ) + } + return (

    - Available {product.name} sandboxes. Click to launch the sandbox. + Available {product.name} sandboxes

    @@ -112,35 +148,44 @@ export default function SandboxView({

    {availableSandboxes.length > 0 ? ( - - {availableSandboxes.map((lab, index) => ( -
    handleLabClick(lab.labId)} - > - -
    - -
    - {lab.products.map((productSlug, idx) => ( - - ))} -
    + <> + + {availableSandboxes.map((lab, index) => ( +
    +
    handleLabClick(lab.labId)} + > + +
    + +
    + {lab.products.map((productSlug, idx) => ( + + ))} +
    +
    + + + + +
    - - - - - +
    + ))} +     + + {availableSandboxes.map((lab, index) => ( +
    + {lab.documentation && renderDocumentation(lab.documentation)}
    ))} - + ) : (

    There are currently no sandboxes available for {product.name}. Check @@ -192,12 +237,10 @@ export default function SandboxView({ } export const getStaticPaths: GetStaticPaths = async () => { - // Get the list of supported products from sandbox.json const supportedProducts = SANDBOX_CONFIG.products || [] - // Generate paths for all products that are in the supported products list const paths = supportedProducts - .filter((productSlug) => PRODUCT_DATA_MAP[productSlug]) // Ensure the product exists in PRODUCT_DATA_MAP + .filter((productSlug) => PRODUCT_DATA_MAP[productSlug]) .map((productSlug) => ({ params: { productSlug }, })) @@ -215,22 +258,40 @@ export const getStaticProps: GetStaticProps = async ({ const product = PRODUCT_DATA_MAP[productSlug] const supportedProducts = SANDBOX_CONFIG.products || [] - // Only show sandbox page if product is in the supported products list if (!product || !supportedProducts.includes(productSlug)) { return { notFound: true, } } - // Filter sandboxes that are relevant to this product - const availableSandboxes = SANDBOX_CONFIG.labs.filter((lab) => - lab.products.includes(productSlug) + // Process available sandboxes and their documentation + const availableSandboxes = await Promise.all( + (SANDBOX_CONFIG as SandboxConfig).labs + .filter((lab) => lab.products.includes(productSlug)) + .map(async (lab) => { + const { title, description, products, labId, documentation } = lab + if (documentation) { + // Handle the MDX file + return { + title, + description, + products, + labId, + documentation: await getMdxContent(documentation, productSlug as ProductSlug), + } + } + return { title, description, products, labId } + }) ) - // Filter sandboxes that are NOT relevant to this product - const otherSandboxes = SANDBOX_CONFIG.labs.filter( - (lab) => !lab.products.includes(productSlug) - ) + const otherSandboxes = (SANDBOX_CONFIG as SandboxConfig).labs + .filter((lab) => !lab.products.includes(productSlug)) + .map(({ title, description, products, labId }) => ({ + title, + description, + products, + labId, + })) const breadcrumbLinks = [ { title: 'Developer', url: '/' }, @@ -243,7 +304,6 @@ export const getStaticProps: GetStaticProps = async ({ generateProductLandingSidebarNavData(product), ] - // Add sandbox links const sandboxMenuItems: MenuItem[] = [ { title: `${product.name} Sandbox`, diff --git a/src/pages/[productSlug]/sandbox/sandbox.module.css b/src/pages/[productSlug]/sandbox/sandbox.module.css index 10f71f81df..cfef747164 100644 --- a/src/pages/[productSlug]/sandbox/sandbox.module.css +++ b/src/pages/[productSlug]/sandbox/sandbox.module.css @@ -114,3 +114,53 @@ margin-bottom: 16px; color: var(--token-color-foreground-primary); } + +.tabs { + display: flex; + gap: 0; + border-bottom: 1px solid var(--token-color-border-primary); + background-color: var(--token-color-surface-primary); + border-top-left-radius: var(--token-border-radius-medium); + border-top-right-radius: var(--token-border-radius-medium); +} + +.tab { + padding: 0.75rem 1.25rem; + font-size: var(--token-typography-body-200-font-size); + line-height: var(--token-typography-body-200-line-height); + font-weight: var(--token-typography-body-200-font-weight); + cursor: pointer; + border: none; + background: none; + color: var(--token-color-foreground-primary); + position: relative; + transition: color 0.2s ease; +} + +.tab:hover { + color: var(--token-color-foreground-strong); +} + +.tabActive { + color: var(--token-color-foreground-strong); + font-weight: var(--token-typography-font-weight-medium); +} + +.tabActive::after { + content: ''; + position: absolute; + bottom: -1px; + left: 0; + right: 0; + height: 2px; + background-color: var(--token-color-palette-blue-200); +} + +.tabContent { + display: none; + padding: 1.5rem; +} + +.tabContentActive { + display: block; +} diff --git a/src/types/next-mdx-remote.d.ts b/src/types/next-mdx-remote.d.ts new file mode 100644 index 0000000000..a08606cca3 --- /dev/null +++ b/src/types/next-mdx-remote.d.ts @@ -0,0 +1,28 @@ +declare module 'next-mdx-remote' { + export interface MDXRemoteSerializeResult { + compiledSource: string + scope?: Record + frontmatter?: Record + } + + export interface MDXRemoteProps { + compiledSource: string + scope?: Record + frontmatter?: Record + } + + export function MDXRemote(props: MDXRemoteProps): JSX.Element +} + +declare module 'next-mdx-remote/serialize' { + import { MDXRemoteSerializeResult } from 'next-mdx-remote' + + export function serialize( + source: string, + options?: { + scope?: Record + mdxOptions?: Record + parseFrontmatter?: boolean + } + ): Promise +} \ No newline at end of file diff --git a/src/types/sandbox.ts b/src/types/sandbox.ts new file mode 100644 index 0000000000..c1e017cae1 --- /dev/null +++ b/src/types/sandbox.ts @@ -0,0 +1,29 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import { MDXRemoteSerializeResult } from 'lib/next-mdx-remote' + +// Raw configuration in sandbox.json +interface RawSandboxLab { + title: string + description: string + products: string[] + labId: string + documentation?: string +} + +// Processed version after loading content +export interface SandboxLab { + title: string + description: string + products: string[] + labId: string + documentation?: MDXRemoteSerializeResult +} + +export interface SandboxConfig { + products: string[] + labs: RawSandboxLab[] +} \ No newline at end of file From 82507b6da09159c30580dfe5c7bc51737d78a434 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 30 Apr 2025 16:38:41 -0700 Subject: [PATCH 34/53] update broken tracking/merge error --- src/lib/posthog-events.ts | 4 +++- turbo.json | 17 +++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 turbo.json diff --git a/src/lib/posthog-events.ts b/src/lib/posthog-events.ts index 95aef75e44..fb35e85a10 100644 --- a/src/lib/posthog-events.ts +++ b/src/lib/posthog-events.ts @@ -22,11 +22,13 @@ export const trackSandboxEvent = ( ): void => { if (window?.posthog?.capture) { window.posthog.capture(eventName, properties) + } } - +/** * Enables PostHog video start tracking */ + export function trackVideoStart(url: string): void { if (!window?.posthog) return diff --git a/turbo.json b/turbo.json new file mode 100644 index 0000000000..53392075e7 --- /dev/null +++ b/turbo.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://turborepo.com/schema.json", + "extends": ["//"], + "tasks": { + "build": { + "dependsOn": ["^build"], + "outputs": [".next/**", "!.next/cache/**"] + }, + "check-types": { + "dependsOn": ["^check-types"] + }, + "dev": { + "persistent": true, + "cache": false + } + } +} \ No newline at end of file From 7d2a3fa73f5b0e7e98ce65b7e032dd56fb9f1f20 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 30 Apr 2025 20:01:39 -0700 Subject: [PATCH 35/53] fix broken tests, remove unnecessary imports --- .../__tests__/embed-element.test.tsx | 1 - .../resizable/__tests__/resizable.test.tsx | 1 - .../product-page-content/utils/get-nav-items.ts | 5 +---- .../__tests__/sandbox-dropdown.test.tsx | 4 ++-- .../__tests__/sandbox-item.test.tsx | 1 - .../__tests__/instruqt-lab.test.tsx | 1 - turbo.json | 17 ----------------- 7 files changed, 3 insertions(+), 27 deletions(-) delete mode 100644 turbo.json diff --git a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx index b1199959bb..072d28369a 100644 --- a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx +++ b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx @@ -4,7 +4,6 @@ */ import { render, screen } from '@testing-library/react' -import { useInstruqtEmbed } from 'contexts/instruqt-lab' import EmbedElement from '../index' // Mock the useInstruqtEmbed hook diff --git a/src/components/lab-embed/resizable/__tests__/resizable.test.tsx b/src/components/lab-embed/resizable/__tests__/resizable.test.tsx index 6c57d68314..1e8829c2cf 100644 --- a/src/components/lab-embed/resizable/__tests__/resizable.test.tsx +++ b/src/components/lab-embed/resizable/__tests__/resizable.test.tsx @@ -4,7 +4,6 @@ */ import { render, screen, fireEvent } from '@testing-library/react' -import { useInstruqtEmbed } from 'contexts/instruqt-lab' import Resizable from '../index' import s from '../resizable.module.css' diff --git a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts index 625715a0f1..4dde031161 100644 --- a/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts +++ b/src/components/navigation-header/components/product-page-content/utils/get-nav-items.ts @@ -3,10 +3,7 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { - NavigationHeaderIcon, - NavigationHeaderItem, -} from 'components/navigation-header/types' +import { NavigationHeaderIcon } from 'components/navigation-header/types' import { getDocsNavItems } from 'lib/docs/get-docs-nav-items' import { getIsEnabledProductIntegrations } from 'lib/integrations/get-is-enabled-product-integrations' import { ProductData } from 'types/products' diff --git a/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx b/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx index f6c23eb7bd..a42cbf02b8 100644 --- a/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx +++ b/src/components/navigation-header/components/sandbox-dropdown/__tests__/sandbox-dropdown.test.tsx @@ -136,7 +136,7 @@ describe('SandboxDropdown', () => { fireEvent.click(button) // Find a sandbox item and click it - const sandboxItem = screen.getByText('Vault Playground (test)') + const sandboxItem = screen.getByText('Vault Sandbox') fireEvent.click(sandboxItem.closest('button')) // Verify openLab was called @@ -156,7 +156,7 @@ describe('SandboxDropdown', () => { fireEvent.click(button) // Find a sandbox item and click it - const sandboxItem = screen.getByText('Vault Playground (test)') + const sandboxItem = screen.getByText('Vault Sandbox') fireEvent.click(sandboxItem.closest('button')) // Verify openLab was called diff --git a/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx b/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx index 5b5586900d..d67b46411e 100644 --- a/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx +++ b/src/components/navigation-header/components/sandbox-item/__tests__/sandbox-item.test.tsx @@ -4,7 +4,6 @@ */ import { render, screen, fireEvent } from '@testing-library/react' -import { useInstruqtEmbed } from 'contexts/instruqt-lab' import SandboxItem from '../index' // Mock the hooks diff --git a/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx b/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx index 3a95f07e8e..364444fcf7 100644 --- a/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx +++ b/src/contexts/instruqt-lab/__tests__/instruqt-lab.test.tsx @@ -4,7 +4,6 @@ */ import { render, screen, fireEvent, act } from '@testing-library/react' -import { useRouter } from 'next/router' import InstruqtProvider, { useInstruqtEmbed } from '../index' import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' diff --git a/turbo.json b/turbo.json deleted file mode 100644 index 53392075e7..0000000000 --- a/turbo.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "$schema": "https://turborepo.com/schema.json", - "extends": ["//"], - "tasks": { - "build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**"] - }, - "check-types": { - "dependsOn": ["^check-types"] - }, - "dev": { - "persistent": true, - "cache": false - } - } -} \ No newline at end of file From cd7ab67f8cc855fb1f7e1b292ae6a3ac493fc825 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 30 Apr 2025 20:23:12 -0700 Subject: [PATCH 36/53] fix broken ci tests --- .npmrc | 1 + .../__tests__/embed-element.test.tsx | 3 +- .../components/product-page-content/index.tsx | 6 --- .../components/sandbox-item/index.tsx | 6 +-- .../generate-resources-nav-items.test.ts | 2 - src/content/sandbox/sandbox.json | 14 +++--- src/pages/[productSlug]/sandbox/index.tsx | 43 +++++++++++-------- src/views/tutorial-view/index.tsx | 6 +-- .../tutorial-view/index.tsx | 2 - .../tutorial-view/index.tsx | 2 - 10 files changed, 39 insertions(+), 46 deletions(-) diff --git a/.npmrc b/.npmrc index b6f27f1359..a32230ed05 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1,2 @@ engine-strict=true +@hashicorp:registry=https://registry.npmjs.org/ diff --git a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx index 072d28369a..7d6007b70c 100644 --- a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx +++ b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx @@ -38,8 +38,7 @@ describe('EmbedElement', () => { }) it('has proper focus behavior when mounted', () => { - const { container } = render() - + render() const iframe = screen.getByTitle('Instruqt') expect(document.activeElement).toBe(iframe) }) diff --git a/src/components/navigation-header/components/product-page-content/index.tsx b/src/components/navigation-header/components/product-page-content/index.tsx index 01a12c70c2..88d7924c3c 100644 --- a/src/components/navigation-header/components/product-page-content/index.tsx +++ b/src/components/navigation-header/components/product-page-content/index.tsx @@ -35,12 +35,6 @@ const ProductPageHeaderContent = () => { SANDBOX_CONFIG.labs?.length > 0 && supportedSandboxProducts.includes(currentProduct.slug) - // Get sandbox labs for the current product - const labs = SANDBOX_CONFIG.labs || [] - const currentProductLabs = labs.filter((lab) => - lab.products.includes(currentProduct.slug) - ) - return ( <>

    diff --git a/src/components/navigation-header/components/sandbox-item/index.tsx b/src/components/navigation-header/components/sandbox-item/index.tsx index c888c30644..4f5e4be2f6 100644 --- a/src/components/navigation-header/components/sandbox-item/index.tsx +++ b/src/components/navigation-header/components/sandbox-item/index.tsx @@ -24,7 +24,7 @@ interface SandboxItemProps { } const SandboxItem = ({ item }: SandboxItemProps) => { - const { label, description, products, onClick } = item + const { label, description, products, onClick, labId } = item const handleClick = useCallback( (e) => { @@ -52,9 +52,9 @@ const SandboxItem = ({ item }: SandboxItemProps) => { {label}
    - {products.map((product, index) => ( + {products.map((product) => ( { it('includes sandbox items in the resources navigation', () => { @@ -44,7 +43,6 @@ describe('generateResourcesNavItems', () => { it('includes sandbox link for supported products', () => { // Mock the supported products in SANDBOX_CONFIG - const originalProducts = SANDBOX_CONFIG.products const productSlug = 'nomad' as ProductSlug // Generate the navigation items diff --git a/src/content/sandbox/sandbox.json b/src/content/sandbox/sandbox.json index 864028c876..c5732f3d8c 100644 --- a/src/content/sandbox/sandbox.json +++ b/src/content/sandbox/sandbox.json @@ -21,13 +21,6 @@ "products": ["boundary"], "labId": "hashicorp-learn/tracks/boundary-sandbox?token=em_YHsmJu4K1Wk3hwht", "documentation": "boundary.mdx" - }, - { - "title": "Nomad Sandbox", - "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", - "products": ["nomad", "consul"], - "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", - "documentation": "nomad.mdx" }, { "title": "Consul Sandbox (Service discovery)", @@ -41,6 +34,13 @@ "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM" + }, + { + "title": "Nomad Sandbox", + "description": "A Nomad cluster with three server nodes and one client node, Consul installed and configured, and Access Control Lists (ACLs) enabled for both Nomad and Consul.", + "products": ["nomad", "consul"], + "labId": "hashicorp-learn/tracks/nomad-sandbox?token=em_0wOuIAyyjAQllLkc", + "documentation": "nomad.mdx" } ] } diff --git a/src/pages/[productSlug]/sandbox/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx index 11c53edfd9..45ff43b6fe 100644 --- a/src/pages/[productSlug]/sandbox/index.tsx +++ b/src/pages/[productSlug]/sandbox/index.tsx @@ -20,7 +20,6 @@ import { import Card from 'components/card' import CardsGridList from 'components/cards-grid-list' import { BrandedHeaderCard } from 'views/product-integrations-landing/components/branded-header-card' -import { MenuItem } from 'components/sidebar/types' import { ProductSlug } from 'types/products' import { SandboxLab, SandboxConfig } from 'types/sandbox' import SANDBOX_CONFIG from 'content/sandbox/sandbox.json' assert { type: 'json' } @@ -28,6 +27,7 @@ import ProductIcon from 'components/product-icon' import { serialize } from 'lib/next-mdx-remote/serialize' import DevDotContent from 'components/dev-dot-content' import getDocsMdxComponents from 'views/docs-view/utils/get-docs-mdx-components' +import { SidebarProps } from 'components/sidebar' import fs from 'fs' import path from 'path' import s from './sandbox.module.css' @@ -38,7 +38,7 @@ interface SandboxPageProps { product: (typeof PRODUCT_DATA_MAP)[keyof typeof PRODUCT_DATA_MAP] layoutProps: { breadcrumbLinks: { title: string; url: string }[] - navLevels: any[] + navLevels: SidebarProps[] } availableSandboxes: SandboxLab[] otherSandboxes: SandboxLab[] @@ -113,7 +113,7 @@ export default function SandboxView({

    HashiCorp Sandboxes provide interactive environments where you can experiment with HashiCorp products without any installation or setup. - They're perfect for: + They're perfect for:

      @@ -137,21 +137,21 @@ export default function SandboxView({

      - When you launch a sandbox, you'll be presented with a terminal interface + When you launch a sandbox, you'll be presented with a terminal interface where you can interact with the pre-configured environment. The sandbox - runs in your browser and doesn't require any downloads or installations. + runs in your browser and doesn't require any downloads or installations.

      Each sandbox session lasts for up to 1 hour, giving you plenty of time - to experiment. Your work isn't saved between sessions, so be sure to + to experiment. Your work isn't saved between sessions, so be sure to copy any important configurations before your session ends.

      {availableSandboxes.length > 0 ? ( <> - {availableSandboxes.map((lab, index) => ( -
      + {availableSandboxes.map((lab) => ( +
      handleLabClick(lab.labId)} @@ -160,9 +160,9 @@ export default function SandboxView({
      - {lab.products.map((productSlug, idx) => ( + {lab.products.map((productSlug) => ( - {availableSandboxes.map((lab, index) => ( -
      + {availableSandboxes.map((lab) => ( +
      {lab.documentation && renderDocumentation(lab.documentation)}
      ))} @@ -202,9 +202,9 @@ export default function SandboxView({

      - {otherSandboxes.map((lab, index) => ( + {otherSandboxes.map((lab) => (
      handleLabClick(lab.labId)} > @@ -212,9 +212,9 @@ export default function SandboxView({
      - {lab.products.map((productSlug, idx) => ( + {lab.products.map((productSlug) => ( = async ({ generateProductLandingSidebarNavData(product), ] - const sandboxMenuItems: MenuItem[] = [ + const sandboxMenuItems = [ { title: `${product.name} Sandbox`, fullPath: `/${productSlug}/sandbox`, + path: `/${productSlug}/sandbox`, + href: `/${productSlug}/sandbox`, theme: product.slug, isActive: true, + id: 'sandbox', }, ] - sidebarNavDataLevels.push({ + const sandboxLevel: SidebarProps = { backToLinkProps: { text: `${product.name} Home`, href: `/${product.slug}`, @@ -326,7 +329,9 @@ export const getStaticProps: GetStaticProps = async ({ levelUpButtonText: `${product.name} Home`, levelDownButtonText: 'Previous', }, - }) + } + + sidebarNavDataLevels.push(sandboxLevel) return { props: { diff --git a/src/views/tutorial-view/index.tsx b/src/views/tutorial-view/index.tsx index e5fe1fd26b..bfd7705761 100644 --- a/src/views/tutorial-view/index.tsx +++ b/src/views/tutorial-view/index.tsx @@ -122,8 +122,7 @@ function TutorialView({ }: TutorialViewProps): React.ReactElement { // hooks const currentPath = useCurrentPath({ excludeHash: true, excludeSearch: true }) - const [, setCollectionViewSidebarSections] = - useState(null) + const [, setCollectionViewSidebarSections] = useState(null) const { openLab, closeLab, setActive } = useInstruqtEmbed() // variables @@ -168,6 +167,7 @@ function TutorialView({ text: collectionCtx.current.shortName, href: getCollectionSlug(collectionCtx.current.slug), }, + title: collectionCtx.current.shortName, visuallyHideTitle: true, children: ( Date: Wed, 30 Apr 2025 20:42:38 -0700 Subject: [PATCH 37/53] implement multiproduct lab descriptions --- src/content/sandbox/docs/boundary.mdx | 6 - src/content/sandbox/docs/consul-sd.mdx | 126 +++++++++ src/content/sandbox/docs/consul-sm.mdx | 126 +++++++++ src/content/sandbox/docs/consul.mdx | 263 ------------------ src/content/sandbox/docs/nomad.mdx | 6 - src/content/sandbox/docs/terraform.mdx | 6 - src/content/sandbox/docs/vault.mdx | 6 - src/content/sandbox/sandbox.json | 5 +- src/pages/[productSlug]/sandbox/index.tsx | 20 +- .../[productSlug]/sandbox/sandbox.module.css | 52 +--- 10 files changed, 271 insertions(+), 345 deletions(-) create mode 100644 src/content/sandbox/docs/consul-sd.mdx create mode 100644 src/content/sandbox/docs/consul-sm.mdx delete mode 100644 src/content/sandbox/docs/consul.mdx diff --git a/src/content/sandbox/docs/boundary.mdx b/src/content/sandbox/docs/boundary.mdx index 207ba9852d..ca8d0f0f7f 100644 --- a/src/content/sandbox/docs/boundary.mdx +++ b/src/content/sandbox/docs/boundary.mdx @@ -1,6 +1,3 @@ - - - @@ -267,8 +264,5 @@ Because of the limitations of this platform: 1. All servers can be accessed directly by SSH using their hostnames, bypassing Boundary. 1. The workstation and other servers do not allow root-level access. - - - \ No newline at end of file diff --git a/src/content/sandbox/docs/consul-sd.mdx b/src/content/sandbox/docs/consul-sd.mdx new file mode 100644 index 0000000000..302fd14710 --- /dev/null +++ b/src/content/sandbox/docs/consul-sd.mdx @@ -0,0 +1,126 @@ + + + + + +This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. + +It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. + + + +This is a 3-node Consul community edition datacenter running in a Docker environment. + +Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. + +One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. + +**Architecture** + +Click on the "Architecture" tab to find a diagram of the deployed scenario. + +**Configuration and logs** + +You can find container data, configuration, and logs in the `var` directory. + +You can get an overview of the content using the `tree` command. + +```shell-session +$ tree /root/repository/var +``` + +**Access the nodes** + +The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: + +```shell-session +$ ssh -i certs/id_rsa admin@localhost -p 2222 +``` + +You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. + +**Interact with Consul** + +From the bastion host, you can directly interact with Consul. First, load necessary environment variables. + +```shell-session +$ source assets/scenario/env-consul.env +``` + +After that you can directly use Consul CLI to interact with your datacenter. + +```shell-session +$ consul members +``` + +You can also use the `Consul UI` tab to interact with Consul. + +If you want to login to the UI, use the token present in the `env-consul.env` file. + + + + +This sandbox has the following architecture: + + + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Consul Datacenter DC1 │ +│ │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ +│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-nginx-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-0 │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ +│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ +│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ +│ │ ┼──► consul-server-1 │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ +│ │ │ │ │ │ │ │ │ +│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ +│ │ │ │ │ │ │ │ │ +│ │ └───────────────────┘ │ │ │ │ │ +│ │ │ │ ┌────────────▼────────────┐ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-db-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ └─────────────────────────┘ │ │ +│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────┘ + + + ┌─────────────────────┐ + │ │ + │ Bastion Host │ + │ │ + └─────────────────────┘ +``` + + + + + + +The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. + +The command to start Consul on each node is: + +```shell-session +$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & +``` + +The command starts Consul in the background to not lock the terminal. + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/consul-sm.mdx b/src/content/sandbox/docs/consul-sm.mdx new file mode 100644 index 0000000000..302fd14710 --- /dev/null +++ b/src/content/sandbox/docs/consul-sm.mdx @@ -0,0 +1,126 @@ + + + + + +This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. + +It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. + + + +This is a 3-node Consul community edition datacenter running in a Docker environment. + +Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. + +One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. + +**Architecture** + +Click on the "Architecture" tab to find a diagram of the deployed scenario. + +**Configuration and logs** + +You can find container data, configuration, and logs in the `var` directory. + +You can get an overview of the content using the `tree` command. + +```shell-session +$ tree /root/repository/var +``` + +**Access the nodes** + +The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: + +```shell-session +$ ssh -i certs/id_rsa admin@localhost -p 2222 +``` + +You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. + +**Interact with Consul** + +From the bastion host, you can directly interact with Consul. First, load necessary environment variables. + +```shell-session +$ source assets/scenario/env-consul.env +``` + +After that you can directly use Consul CLI to interact with your datacenter. + +```shell-session +$ consul members +``` + +You can also use the `Consul UI` tab to interact with Consul. + +If you want to login to the UI, use the token present in the `env-consul.env` file. + + + + +This sandbox has the following architecture: + + + +``` +┌──────────────────────────────────────────────────────────────────────────────┐ +│ Consul Datacenter DC1 │ +│ │ +│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ +│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-nginx-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-0 │ │ │ │ │ │ │ +│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ +│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ +│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ +│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ +│ │ ┼──► consul-server-1 │ │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ +│ │ │ │ │ │ │ │ │ +│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ +│ │ │ │ │ │ │ │ │ +│ │ └───────────────────┘ │ │ │ │ │ +│ │ │ │ ┌────────────▼────────────┐ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ │ hashicups-db-0 │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ │ └─────────────────────────┘ │ │ +│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ +│ │ +└──────────────────────────────────────────────────────────────────────────────┘ + + + ┌─────────────────────┐ + │ │ + │ Bastion Host │ + │ │ + └─────────────────────┘ +``` + + + + + + +The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. + +The command to start Consul on each node is: + +```shell-session +$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & +``` + +The command starts Consul in the background to not lock the terminal. + + + \ No newline at end of file diff --git a/src/content/sandbox/docs/consul.mdx b/src/content/sandbox/docs/consul.mdx deleted file mode 100644 index 944c833feb..0000000000 --- a/src/content/sandbox/docs/consul.mdx +++ /dev/null @@ -1,263 +0,0 @@ - - - - - - - - -This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. - -It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. - - - -This is a 3-node Consul community edition datacenter running in a Docker environment. - -Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. - -One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. - -**Architecture** - -Click on the "Architecture" tab to find a diagram of the deployed scenario. - -**Configuration and logs** - -You can find container data, configuration, and logs in the `var` directory. - -You can get an overview of the content using the `tree` command. - -```shell-session -$ tree /root/repository/var -``` - -**Access the nodes** - -The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: - -```shell-session -$ ssh -i certs/id_rsa admin@localhost -p 2222 -``` - -You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. - -**Interact with Consul** - -From the bastion host, you can directly interact with Consul. First, load necessary environment variables. - -```shell-session -$ source assets/scenario/env-consul.env -``` - -After that you can directly use Consul CLI to interact with your datacenter. - -```shell-session -$ consul members -``` - -You can also use the `Consul UI` tab to interact with Consul. - -If you want to login to the UI, use the token present in the `env-consul.env` file. - - - - -This sandbox has the following architecture: - - - -``` -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Consul Datacenter DC1 │ -│ │ -│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ -│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ hashicups-nginx-0 │ │ │ -│ │ │ │ │ │ │ │ -│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ consul-server-0 │ │ │ │ │ │ │ -│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ -│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ -│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ -│ │ ┼──► consul-server-1 │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ -│ │ │ │ │ │ │ │ │ -│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ -│ │ │ │ │ │ │ │ │ -│ │ └───────────────────┘ │ │ │ │ │ -│ │ │ │ ┌────────────▼────────────┐ │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ hashicups-db-0 │ │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ └─────────────────────────┘ │ │ -│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ -│ │ -└──────────────────────────────────────────────────────────────────────────────┘ - - - ┌─────────────────────┐ - │ │ - │ Bastion Host │ - │ │ - └─────────────────────┘ -``` - - - - - - -The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. - -The command to start Consul on each node is: - -```shell-session -$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & -``` - -The command starts Consul in the background to not lock the terminal. - - - - - - - - - - - - - -This environment is not production-ready, as it does not follow our recommendations for production-ready cluster deployments. Refer to the [Consul Deployment Guide](/consul/tutorials/production-vms/deployment-guide) for more information. - -It is meant to serve as a development and testing environment. It is "production-lite" as it enables gossip encryption, TLS, and ACLs. - - - -This is a 3-node Consul community edition datacenter running in a Docker environment. - -Alongside the server nodes 4 client nodes are also added to the datacenter. The nodes are running HashiCups, a demo web application. - -One extra node, Bastion Host, is also added to the scenario to simulate scenarios where there is no direct access to the different nodes composing the Consul datacenter and a bastion host is required to access the nodes. - -**Architecture** - -Click on the "Architecture" tab to find a diagram of the deployed scenario. - -**Configuration and logs** - -You can find container data, configuration, and logs in the `var` directory. - -You can get an overview of the content using the `tree` command. - -```shell-session -$ tree /root/repository/var -``` - -**Access the nodes** - -The recommended method to access the different nodes is using SSH. You can SSH into the bastion host using: - -```shell-session -$ ssh -i certs/id_rsa admin@localhost -p 2222 -``` - -You can also use one of the two `Bastion Host` tabs to get direct access into the bastion host node. - -**Interact with Consul** - -From the bastion host, you can directly interact with Consul. First, load necessary environment variables. - -```shell-session -$ source assets/scenario/env-consul.env -``` - -After that you can directly use Consul CLI to interact with your datacenter. - -```shell-session -$ consul members -``` - -You can also use the `Consul UI` tab to interact with Consul. - -If you want to login to the UI, use the token present in the `env-consul.env` file. - - - - -This sandbox has the following architecture: - - - -``` -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Consul Datacenter DC1 │ -│ │ -│ ┌──────────────────────────────┐ ┌──────────────────────────────────────┐ │ -│ │ SERVERS │ │ ┌─────────────────────────┐ CLIENTS │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ hashicups-nginx-0 │ │ │ -│ │ │ │ │ │ │ │ -│ │ ┌───────────────────┐ │ │ └────┬────────────┬───────┘ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ consul-server-0 │ │ │ │ │ │ │ -│ │ │ │ │ │ │ ┌────────▼────────────────┐ │ │ -│ │ └─▲─────────────────┘ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ hashicups-frontend-0 │ │ │ -│ │ │ ┌───────────────────┐ │ │ │ │ │ │ │ -│ │ │ │ │ │ │ │ └─────────────────────────┘ │ │ -│ │ ┼──► consul-server-1 │ │ │ │ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ └───────────────────┘ │ │ ┌────▼────────────────────┐ │ │ -│ │ │ │ │ │ │ │ │ -│ │ ┌─▼─────────────────┐ │ │ │ hashicups-api-0 │ │ │ -│ │ │ │ │ │ │ │ │ │ -│ │ │ consul-server-2 │ │ │ └────────────┬────────────┘ │ │ -│ │ │ │ │ │ │ │ │ -│ │ └───────────────────┘ │ │ │ │ │ -│ │ │ │ ┌────────────▼────────────┐ │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ │ hashicups-db-0 │ │ │ -│ │ │ │ │ │ │ │ -│ │ │ │ └─────────────────────────┘ │ │ -│ └──────────────────────────────┘ └──────────────────────────────────────┘ │ -│ │ -└──────────────────────────────────────────────────────────────────────────────┘ - - - ┌─────────────────────┐ - │ │ - │ Bastion Host │ - │ │ - └─────────────────────┘ -``` - - - - - - -The Consul nodes do not have systemd installed so Consul needs to be stopped and started manually. - -The command to start Consul on each node is: - -```shell-session -$ consul agent -config-dir=/etc/consul.d > /tmp/logs/consul-server.log 2>&1 & -``` - -The command starts Consul in the background to not lock the terminal. - - - - - - \ No newline at end of file diff --git a/src/content/sandbox/docs/nomad.mdx b/src/content/sandbox/docs/nomad.mdx index 00a9f53949..f2ad29041b 100644 --- a/src/content/sandbox/docs/nomad.mdx +++ b/src/content/sandbox/docs/nomad.mdx @@ -1,6 +1,3 @@ - - - @@ -210,8 +207,5 @@ environments. Nomad jobspecs must be configured to use one of the ports exposed through the Instruqt web browser tabs interface: `3001`, `3333`, or `4444`. - - - \ No newline at end of file diff --git a/src/content/sandbox/docs/terraform.mdx b/src/content/sandbox/docs/terraform.mdx index 045da30e7e..3589e99980 100644 --- a/src/content/sandbox/docs/terraform.mdx +++ b/src/content/sandbox/docs/terraform.mdx @@ -1,6 +1,3 @@ - - - @@ -51,8 +48,5 @@ This sandbox includes the following preinstalled tools and services: This sandbox is configured to use LocalStack, a local AWS API emulator. This sandbox uses the free edition of LocalStack, which has limitations on which resources it will allow you to deploy. For more information on which resources are included in the free version, refer to the [AWS service feature coverage](https://docs.localstack.cloud/user-guide/aws/feature-coverage/) documentation. - - - \ No newline at end of file diff --git a/src/content/sandbox/docs/vault.mdx b/src/content/sandbox/docs/vault.mdx index 11978b206b..43d11ef57e 100644 --- a/src/content/sandbox/docs/vault.mdx +++ b/src/content/sandbox/docs/vault.mdx @@ -1,6 +1,3 @@ - - - @@ -125,8 +122,5 @@ Vault Sandbox features mutual TLS between cluster nodes. You should be aware tha Vault Sandbox uses and exposes the initial root token value for ease of development and testing. You should not rely on root token use for production implementations. - - - \ No newline at end of file diff --git a/src/content/sandbox/sandbox.json b/src/content/sandbox/sandbox.json index c5732f3d8c..4721ebf159 100644 --- a/src/content/sandbox/sandbox.json +++ b/src/content/sandbox/sandbox.json @@ -27,13 +27,14 @@ "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SD", - "documentation": "consul.mdx" + "documentation": "consul-sd.mdx" }, { "title": "Consul Sandbox (Service mesh)", "description": "Learn about the process to register new services when you cannot run a client agent on a node, including how to manage access for external services using access control lists (ACLs).", "products": ["consul"], - "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM" + "labId": "hashicorp-learn/tracks/consul-sandbox?token=em_I5XI2XjO-ZMeH1_w&rtp_SCENARIO=SM", + "documentation": "consul-sm.mdx" }, { "title": "Nomad Sandbox", diff --git a/src/pages/[productSlug]/sandbox/index.tsx b/src/pages/[productSlug]/sandbox/index.tsx index 45ff43b6fe..2b68271c41 100644 --- a/src/pages/[productSlug]/sandbox/index.tsx +++ b/src/pages/[productSlug]/sandbox/index.tsx @@ -28,6 +28,7 @@ import { serialize } from 'lib/next-mdx-remote/serialize' import DevDotContent from 'components/dev-dot-content' import getDocsMdxComponents from 'views/docs-view/utils/get-docs-mdx-components' import { SidebarProps } from 'components/sidebar' +import Tabs, { Tab } from 'components/tabs' import fs from 'fs' import path from 'path' import s from './sandbox.module.css' @@ -180,11 +181,20 @@ export default function SandboxView({ ))} - {availableSandboxes.map((lab) => ( -
      - {lab.documentation && renderDocumentation(lab.documentation)} -
      - ))} +

      Sandbox documentation

      + + {availableSandboxes.some(lab => lab.documentation) && ( + + {availableSandboxes.map((lab) => ( + + {lab.documentation ? + renderDocumentation(lab.documentation) : +

      No documentation is available for this sandbox.

      + } +       + ))} +       + )} ) : (

      diff --git a/src/pages/[productSlug]/sandbox/sandbox.module.css b/src/pages/[productSlug]/sandbox/sandbox.module.css index cfef747164..25040a860a 100644 --- a/src/pages/[productSlug]/sandbox/sandbox.module.css +++ b/src/pages/[productSlug]/sandbox/sandbox.module.css @@ -113,54 +113,4 @@ line-height: 1.6; margin-bottom: 16px; color: var(--token-color-foreground-primary); -} - -.tabs { - display: flex; - gap: 0; - border-bottom: 1px solid var(--token-color-border-primary); - background-color: var(--token-color-surface-primary); - border-top-left-radius: var(--token-border-radius-medium); - border-top-right-radius: var(--token-border-radius-medium); -} - -.tab { - padding: 0.75rem 1.25rem; - font-size: var(--token-typography-body-200-font-size); - line-height: var(--token-typography-body-200-line-height); - font-weight: var(--token-typography-body-200-font-weight); - cursor: pointer; - border: none; - background: none; - color: var(--token-color-foreground-primary); - position: relative; - transition: color 0.2s ease; -} - -.tab:hover { - color: var(--token-color-foreground-strong); -} - -.tabActive { - color: var(--token-color-foreground-strong); - font-weight: var(--token-typography-font-weight-medium); -} - -.tabActive::after { - content: ''; - position: absolute; - bottom: -1px; - left: 0; - right: 0; - height: 2px; - background-color: var(--token-color-palette-blue-200); -} - -.tabContent { - display: none; - padding: 1.5rem; -} - -.tabContentActive { - display: block; -} +} \ No newline at end of file From 1bc409de43aa8153d2308285fe5ac5063d9ba104 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 30 Apr 2025 22:30:35 -0700 Subject: [PATCH 38/53] update styles for sandbox dropdown --- .../components/sandbox-dropdown/index.tsx | 24 ++++++++++--- .../sandbox-dropdown.module.css | 34 ++++++++++++------- src/content/sandbox/sandbox.json | 2 +- 3 files changed, 42 insertions(+), 18 deletions(-) diff --git a/src/components/navigation-header/components/sandbox-dropdown/index.tsx b/src/components/navigation-header/components/sandbox-dropdown/index.tsx index 80c884173c..c77fb86e36 100644 --- a/src/components/navigation-header/components/sandbox-dropdown/index.tsx +++ b/src/components/navigation-header/components/sandbox-dropdown/index.tsx @@ -248,7 +248,6 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => { onClick={() => handleLabClick(lab)} onKeyDown={handleKeyDown} > -

      { > {lab.title} +
      + {lab.products.map((product) => ( + + ))} +
      { onClick={() => handleLabClick(lab)} onKeyDown={handleKeyDown} > -
      { > {lab.title} +
      + {lab.products.map((product) => ( + + ))} +
      Date: Thu, 1 May 2025 13:45:30 -0700 Subject: [PATCH 39/53] add product specific label to learn more --- .../navigation-header/components/sandbox-dropdown/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/navigation-header/components/sandbox-dropdown/index.tsx b/src/components/navigation-header/components/sandbox-dropdown/index.tsx index c77fb86e36..2cccec90db 100644 --- a/src/components/navigation-header/components/sandbox-dropdown/index.tsx +++ b/src/components/navigation-header/components/sandbox-dropdown/index.tsx @@ -221,7 +221,7 @@ const SandboxDropdown = ({ ariaLabel, label }: SandboxDropdownProps) => { onKeyDown={handleKeyDown} > - Learn more about Sandboxes + Learn more about {currentProduct.name} Sandboxes From c6debc4b6197c1d8e40686743d2235fc72ed8e58 Mon Sep 17 00:00:00 2001 From: Erica Thompson Date: Mon, 8 Sep 2025 17:02:32 -0400 Subject: [PATCH 40/53] Refactors lab embed component for robustness Improves the lab embed component with enhanced error handling, loading states, and accessibility features. This commit introduces: - A loading state with a spinner and informative text - An error state with retry functionality and user-friendly messages - Comprehensive testing to cover rendering, state transitions, edge cases, and accessibility - Improved state management using `useState` and `useCallback` for better performance - Mobile device support for the resizable panel The changes also include validation of the sandbox configuration to prevent runtime errors due to configuration issues. improved error handling and simplified logic. This change improves code readability and maintainability, and enables a more declarative approach to rendering the fallback UI. update for consistency and readability. This improves code readability and maintainability. Improves lab embed element resilience Enhances the Instruqt lab embed element by improving error handling and retry logic. This change implements a retry mechanism with a maximum of 3 attempts to address intermittent loading failures, enhancing the user experience. Also provides more informative error messages and screen reader announcements. Enhances Instruqt embed tests and context Refactors the Instruqt embed tests and context for improved clarity and reliability. This includes streamlining mock setups, enhancing test coverage for error and retry states, and improving localStorage persistence. Improves sandbox lab embedding and configuration Enhances the Instruqt lab embedding process by adding a loading delay and retry mechanism for smoother initial loading. Updates the sandbox configuration to use separate `labId` (unique identifier) and `instruqtTrack` (track path) properties for more flexibility and clarity. Introduces a utility function to build the complete lab ID, including tokens and parameters, ensuring proper configuration for embedding. Also fixes minor UI and accessibility issues related to resizing and keyboard support for the lab panel. Enhances Instruqt lab embed usability Improves the resizer component by preventing unwanted CSS transitions, providing a smoother user experience. Enhances keyboard accessibility for resizing. Improves the resilience of the Instruqt lab context by handling potential storage corruption and access issues, such as in private browsing or when storage is full/disabled, allowing the app to continue without persistence. Allows for overriding default sandbox tokens via environment variables. Enhances lab embed loading and responsiveness Improves the perceived performance of lab embed loading by reducing initial delays and implementing a smoother fade-in transition. The timeout delays for initial readiness and iframe source setting are reduced for faster response. The iframe flicker is reduced by using opacity transitions instead of visibility changes. Subtle visual feedback is added to the resizer component on hover. Improves Instruqt embed loading and error handling Refactors the Instruqt embed component to improve loading speed and error handling. Removes unnecessary delays and opacity manipulations that caused flickering during iframe loading, resulting in a smoother user experience. Improves the display of loading and error states by ensuring they cover the entire embed area. Simplifies the iframe reloading logic by directly setting the `src` attribute. Adds error boundary to MDX alert component Wraps the `MdxInlineAlert` component with an error boundary. This change prevents the component from crashing the entire page when it encounters an error, such as invalid props or missing children. Instead, it renders a fallback UI, improving the user experience and providing more graceful error handling. Includes tests for the error boundary component and updates existing tests for the alert component to verify the fallback UI is rendered when errors occur. Also includes configuration validation to prevent the sandbox from initializing with invalid configurations, and displays these errors in the UI. Adds enhanced error boundary component Implements a more robust error boundary with improved fallback UI, reset capabilities, and context sharing. This allows for better error handling and recovery in React applications. It provides mechanisms for resetting the error state and sharing error handling logic across components. Enhances MdxInlineAlert component robustness Improves the MdxInlineAlert component by adding specific tests to handle cases where the children prop is empty or the type prop is invalid. This ensures that the component gracefully handles these scenarios by rendering an error fallback instead of throwing an error, enhancing the component's overall robustness and user experience. Also adds test case for rendering multiple children. Simplifies MdxInlineAlert tests Removes unnecessary comments in MdxInlineAlert tests, improving readability and maintainability. Removes redundant validation error logging Simplifies the error handling within the MdxInlineAlert component by removing redundant logging of validation errors, streamlining the error reporting process. Adds error tracking for MdxInlineAlert Improves error handling for the MdxInlineAlert component by adding error tracking via PostHog and enhanced console logging in development environments. This provides better visibility into component errors and aids in debugging. Improves lab embed UX and stability Refactors the lab embed component for improved user experience and stability. Simplifies iframe loading and error handling to prevent flickering and race conditions. Enhances resizing behavior on mobile devices. Updates testing suite. Adds Instruqt context error tracking Implements error tracking for the Instruqt context using PostHog and console logging. This enhances debugging and monitoring of issues related to sandbox configuration, storage, and lab operations by: - Capturing specific error types, messages, and relevant context. - Logging errors in the console for development environments. - Adding checks before opening labs, and improving error messages. Enhances Instruqt sandbox error tracking Improves error handling and reporting within the Instruqt sandbox context and sandbox page. - Introduces a centralized error tracking function that captures errors and warnings in PostHog and development console. - Implements error tracking for configuration validation, storage operations, lab loading failures, and documentation rendering. - Displays user-friendly toast messages for critical sandbox errors, improving user experience. This enhancement allows for better monitoring and debugging of sandbox-related issues. --- config/base.json | 12 +- config/development.json | 5 +- package-lock.json | 12 - .../mdx-components/mdx-alert/index.test.tsx | 64 +- .../mdx-components/mdx-alert/index.tsx | 37 +- .../__tests__/error-boundary.test.tsx | 126 ++++ src/components/error-boundary/index.tsx | 216 +++++++ .../__tests__/embed-element.test.tsx | 283 +++++++-- .../embed-element/embed-element.module.css | 135 ++++ .../lab-embed/embed-element/index.tsx | 268 +++++++- .../resizable/__tests__/resizable.test.tsx | 38 +- .../resizable/components/resizer.module.css | 4 + .../resizable/components/resizer.tsx | 19 + src/components/lab-embed/resizable/index.tsx | 122 ++-- .../lab-embed/resizable/resizable.module.css | 10 +- .../sandbox-dropdown.module.css | 7 +- .../__tests__/sandbox-item.test.tsx | 2 +- .../components/sandbox-item/index.tsx | 31 +- .../sandbox-item/sandbox-item.module.css | 24 +- .../sandbox-error-boundary/index.tsx | 107 ++++ src/content/sandbox/sandbox.json | 32 +- .../__tests__/instruqt-lab.test.tsx | 457 ++++++++++---- src/contexts/instruqt-lab/index-new.tsx | 297 +++++++++ src/contexts/instruqt-lab/index.tsx | 232 ++++++- .../__tests__/validate-sandbox-config.test.ts | 187 ++++++ src/lib/build-instruqt-url.ts | 152 +++++ src/lib/posthog-events.ts | 7 +- src/lib/validate-sandbox-config.ts | 183 ++++++ src/pages/[productSlug]/sandbox/index.tsx | 594 ++++++++++++++---- src/types/sandbox.ts | 5 + 30 files changed, 3233 insertions(+), 435 deletions(-) create mode 100644 src/components/error-boundary/__tests__/error-boundary.test.tsx create mode 100644 src/components/error-boundary/index.tsx create mode 100644 src/components/sandbox-error-boundary/index.tsx create mode 100644 src/contexts/instruqt-lab/index-new.tsx create mode 100644 src/lib/__tests__/validate-sandbox-config.test.ts create mode 100644 src/lib/build-instruqt-url.ts create mode 100644 src/lib/validate-sandbox-config.ts diff --git a/config/base.json b/config/base.json index 7c0e5392de..d55d17f6d1 100644 --- a/config/base.json +++ b/config/base.json @@ -28,7 +28,17 @@ "clientToken": "pubd5cf774aa1cbbd001accd50cb463925b", "service": "non-prod.developer.hashicorp.com" }, - "product_slugs_with_integrations": ["vault", "nomad", "packer"] + "product_slugs_with_integrations": ["vault", "nomad", "packer"], + "sandbox": { + "instruqt_base_url": "https://play.instruqt.com/embed", + "default_tokens": { + "terraform-sandbox": "em_3vgTsBqCLq2blqtQ", + "vault-cluster-sandbox": "em_MmJD6C6DhTpGm9Ab", + "boundary-sandbox": "em_YHsmJu4K1Wk3hwht", + "consul-sandbox": "em_I5XI2XjO-ZMeH1_w", + "nomad-sandbox": "em_0wOuIAyyjAQllLkc" + } + } }, "learn": { "max_static_paths": 10 diff --git a/config/development.json b/config/development.json index a424fa0f83..be9acacde7 100644 --- a/config/development.json +++ b/config/development.json @@ -4,7 +4,10 @@ "max_static_paths": 1 }, "dev_dot": { - "max_static_paths": 1 + "max_static_paths": 1, + "sandbox": { + "instruqt_base_url": "https://play.instruqt.com/embed" + } }, "learn": { "max_static_paths": 1 diff --git a/package-lock.json b/package-lock.json index 96e190ca09..a33d3f683f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -23257,18 +23257,6 @@ "source-map": "~0.6.1" } }, - "node_modules/escodegen/node_modules/source-map": { - "version": "0.6.1", - "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", - "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", - "dev": true, - "license": "BSD-3-Clause", - "optional": true, - "peer": true, - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/eslint": { "version": "8.57.1", "resolved": "https://registry.npmjs.org/eslint/-/eslint-8.57.1.tgz", diff --git a/src/components/dev-dot-content/mdx-components/mdx-alert/index.test.tsx b/src/components/dev-dot-content/mdx-components/mdx-alert/index.test.tsx index cb19b9b715..5a2eb704c3 100644 --- a/src/components/dev-dot-content/mdx-components/mdx-alert/index.test.tsx +++ b/src/components/dev-dot-content/mdx-components/mdx-alert/index.test.tsx @@ -38,11 +38,8 @@ describe('`MdxInlineAlert` Component', () => { const { queryByText, queryByTestId } = render( {data.body} ) - // icon renders expect(queryByTestId('icon')).toBeInTheDocument() - // default title renders expect(queryByText(data.title)).toBeInTheDocument() - // body text renders expect(queryByText(data.body)).toBeInTheDocument() }) @@ -51,11 +48,8 @@ describe('`MdxInlineAlert` Component', () => { const { queryByText, queryByTestId } = render( {data.body} ) - // icon renders expect(queryByTestId('icon')).toBeInTheDocument() - // default title renders expect(queryByText(data.title)).toBeInTheDocument() - // body text renders expect(queryByText(data.body)).toBeInTheDocument() }) @@ -64,11 +58,8 @@ describe('`MdxInlineAlert` Component', () => { const { queryByText, queryByTestId } = render( {data.body} ) - // icon renders expect(queryByTestId('icon')).toBeInTheDocument() - // default title renders expect(queryByText(data.title)).toBeInTheDocument() - // body text renders expect(queryByText(data.body)).toBeInTheDocument() }) @@ -77,11 +68,8 @@ describe('`MdxInlineAlert` Component', () => { const { queryByText, queryByTestId } = render( {data.body} ) - // icon renders expect(queryByTestId('icon')).toBeInTheDocument() - // default title renders expect(queryByText(data.title)).toBeInTheDocument() - // body text renders expect(queryByText(data.body)).toBeInTheDocument() }) @@ -94,32 +82,42 @@ describe('`MdxInlineAlert` Component', () => { expect(queryByText(TEST_DATA.customTitle)).toBeInTheDocument() }) - it('throws when children are not passed', () => { - // eslint-disable-next-line @typescript-eslint/ban-ts-comment - // @ts-ignore - expect(() => render()).toThrowError( - TEST_DATA.errors.noChildren - ) + it('renders error fallback when children are empty', () => { + const { getByText } = render({''}) + + // Should render the error fallback UI instead of throwing + expect(getByText('Alert Error')).toBeInTheDocument() + expect( + getByText( + 'There was an error rendering this alert. Please check the alert configuration.' + ) + ).toBeInTheDocument() }) - it('throws when type is invalid', () => { - expect(() => - render( - // eslint-disable-next-line @typescript-eslint/ban-ts-comment - // @ts-ignore - I am an MdxInlineAlert + it('renders error fallback when type is invalid', () => { + const invalidType = 'doughnut' as 'tip' | 'highlight' | 'note' | 'warning' + const { getByText } = render( + I am an MdxInlineAlert + ) + + // Should render the error fallback UI instead of throwing + expect(getByText('Alert Error')).toBeInTheDocument() + expect( + getByText( + 'There was an error rendering this alert. Please check the alert configuration.' ) - ).toThrowError(TEST_DATA.errors.invalidType) + ).toBeInTheDocument() }) it('renders multiple children', () => { - expect(() => - render( - -

      Liquorice cake marzipan danish brownie

      -

      Lollipop gingerbread bear claw muffin croissant

      -       - ) - ).not.toThrowError() + const { getByText } = render( + +

      This may render multiple children.

      +

      This should get multiple children.

      +       + ) + + expect(getByText('This may render multiple children.')).toBeInTheDocument() + expect(getByText('This should get multiple children.')).toBeInTheDocument() }) }) diff --git a/src/components/dev-dot-content/mdx-components/mdx-alert/index.tsx b/src/components/dev-dot-content/mdx-components/mdx-alert/index.tsx index 7e4fc9a4ff..a3c79a37cf 100644 --- a/src/components/dev-dot-content/mdx-components/mdx-alert/index.tsx +++ b/src/components/dev-dot-content/mdx-components/mdx-alert/index.tsx @@ -4,6 +4,7 @@ */ import InlineAlert from 'components/inline-alert' +import { withErrorBoundary } from 'components/error-boundary' import { IconInfo24 } from '@hashicorp/flight-icons/svg-react/info-24' import { IconAlertTriangle24 } from '@hashicorp/flight-icons/svg-react/alert-triangle-24' import { IconAlertDiamond24 } from '@hashicorp/flight-icons/svg-react/alert-diamond-24' @@ -22,7 +23,7 @@ const ALERT_DATA: MdxInlineAlertData = { }, } -export function MdxInlineAlert({ +function MdxInlineAlertBase({ children, title, type = 'tip', @@ -55,4 +56,38 @@ export function MdxInlineAlert({ ) } +// Create a fallback UI for when the alert component fails +const AlertErrorFallback = ( +
      + } + title="Alert Error" + description="There was an error rendering this alert. Please check the alert configuration." + color="critical" + className={s.typographyOverride} + /> +
      +) + +export const MdxInlineAlert = withErrorBoundary( + MdxInlineAlertBase, + AlertErrorFallback, + (error, errorInfo) => { + if (typeof window !== 'undefined' && window.posthog?.capture) { + window.posthog.capture('mdx_component_error', { + component_name: 'MdxInlineAlert', + error_message: error.message, + error_stack: error.stack, + component_stack: errorInfo?.componentStack, + timestamp: new Date().toISOString(), + page_url: window.location.href, + }) + } + + if (process.env.NODE_ENV === 'development') { + console.warn('MdxInlineAlert validation error:', error.message, errorInfo) + } + } +) + export { MdxHighlight, MdxTip, MdxNote, MdxWarning } diff --git a/src/components/error-boundary/__tests__/error-boundary.test.tsx b/src/components/error-boundary/__tests__/error-boundary.test.tsx new file mode 100644 index 0000000000..1b72108e1a --- /dev/null +++ b/src/components/error-boundary/__tests__/error-boundary.test.tsx @@ -0,0 +1,126 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import React from 'react' +import { render, screen } from '@testing-library/react' +import { vi } from 'vitest' +import { ErrorBoundary, withErrorBoundary } from '../index' + +// Test component that throws an error +const ThrowError = ({ shouldThrow = false }: { shouldThrow?: boolean }) => { + if (shouldThrow) { + throw new Error('Test error') + } + return
      No error
      +} + +describe('ErrorBoundary', () => { + // Suppress console.error during tests to avoid noise + const originalError = console.error + beforeAll(() => { + console.error = vi.fn() + }) + afterAll(() => { + console.error = originalError + }) + + it('renders children when there is no error', () => { + render( + + + + ) + + expect(screen.getByText('No error')).toBeInTheDocument() + }) + + it('renders default error message when child throws error', () => { + render( + + + + ) + + expect(screen.getByText('Something went wrong.')).toBeInTheDocument() + }) + + it('renders custom fallback when provided', () => { + const customFallback =
      Custom error message
      + + render( + + + + ) + + expect(screen.getByText('Custom error message')).toBeInTheDocument() + expect(screen.queryByText('Something went wrong.')).not.toBeInTheDocument() + }) + + it('calls onError callback when error occurs', () => { + const onError = vi.fn() + + render( + + + + ) + + expect(onError).toHaveBeenCalledWith( + expect.any(Error), + expect.objectContaining({ + componentStack: expect.any(String) + }) + ) + }) + + it('shows error details in development mode', () => { + // Mock NODE_ENV for this test + vi.stubEnv('NODE_ENV', 'development') + + render( + + + + ) + + expect(screen.getByText('Error details (development only)')).toBeInTheDocument() + + // Restore + vi.unstubAllEnvs() + }) +}) + +describe('withErrorBoundary HOC', () => { + const originalError = console.error + beforeAll(() => { + console.error = vi.fn() + }) + afterAll(() => { + console.error = originalError + }) + + it('wraps component with error boundary', () => { + const WrappedComponent = withErrorBoundary(ThrowError) + + render() + expect(screen.getByText('No error')).toBeInTheDocument() + }) + + it('catches errors in wrapped component', () => { + const WrappedComponent = withErrorBoundary(ThrowError) + + render() + expect(screen.getByText('Something went wrong.')).toBeInTheDocument() + }) + + it('uses custom fallback with HOC', () => { + const customFallback =
      HOC custom error
      + const WrappedComponent = withErrorBoundary(ThrowError, customFallback) + + render() + expect(screen.getByText('HOC custom error')).toBeInTheDocument() + }) +}) diff --git a/src/components/error-boundary/index.tsx b/src/components/error-boundary/index.tsx new file mode 100644 index 0000000000..c89937a9ed --- /dev/null +++ b/src/components/error-boundary/index.tsx @@ -0,0 +1,216 @@ +/** + * Copyright (c) HashiCorp, Inc. + * SPDX-License-Identifier: MPL-2.0 + */ + +import React, { + Component, + ErrorInfo, + ReactNode, + useCallback, + useState, + useRef, + createContext, + useContext, +} from 'react' + +interface ErrorBoundaryProps { + children: ReactNode + fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode) + onError?: (error: Error, errorInfo: ErrorInfo) => void + resetOnPropsChange?: boolean + resetKeys?: Array +} + +interface ErrorBoundaryState { + hasError: boolean + error?: Error + errorInfo?: ErrorInfo +} + +interface ErrorBoundaryContextType { + resetErrorBoundary: () => void + captureError: (error: Error) => void +} + +const ErrorBoundaryContext = createContext( + null +) + +/** + * Error boundary component that catches JavaScript errors anywhere in the child component tree, + * logs those errors, and displays a fallback UI. + */ +export class ErrorBoundary extends Component< + ErrorBoundaryProps, + ErrorBoundaryState +> { + constructor(props: ErrorBoundaryProps) { + super(props) + this.state = { hasError: false } + } + + static getDerivedStateFromError(error: Error): ErrorBoundaryState { + return { hasError: true, error } + } + + componentDidCatch(error: Error, errorInfo: ErrorInfo) { + console.error('ErrorBoundary caught an error:', error, errorInfo) + this.setState({ errorInfo }) + + if (this.props.onError) { + this.props.onError(error, errorInfo) + } + } + + componentDidUpdate(prevProps: ErrorBoundaryProps) { + if (this.props.resetKeys && prevProps.resetKeys) { + const hasResetKeyChanged = this.props.resetKeys.some( + (key, index) => key !== prevProps.resetKeys![index] + ) + + if (hasResetKeyChanged && this.state.hasError) { + this.setState({ + hasError: false, + error: undefined, + errorInfo: undefined, + }) + } + } + } + + render(): ReactNode { + if (this.state.hasError && this.state.error) { + if (typeof this.props.fallback === 'function') { + return this.props.fallback(this.state.error, this.state.errorInfo!) + } + + return ( + this.props.fallback || ( +
      + Something went wrong. + {process.env.NODE_ENV === 'development' && this.state.error && ( +
      + Error details (development only) + 
      +									{this.state.error.message}
+									{this.state.errorInfo && (
+										<>
+											
      
+											
      
+											Component Stack:
+											{this.state.errorInfo.componentStack}
+										
+									)}
+
      +
      + )} +
      + ) + ) + } + + return this.props.children + } +} + +export function useErrorBoundary() { + const [resetKey, setResetKey] = useState(0) + const errorRef = useRef(null) + + const resetErrorBoundary = useCallback(() => { + // Increment reset key to trigger error boundary reset + setResetKey((prev) => prev + 1) + errorRef.current = null + }, []) + + const captureError = useCallback((error: Error) => { + errorRef.current = error + throw error + }, []) + + const context = useContext(ErrorBoundaryContext) + + if (context) { + return context + } + + return { + resetErrorBoundary, + captureError, + resetKey, + } +} + +interface ErrorBoundaryWrapperProps + extends Omit { + children: ReactNode +} + +export const ErrorBoundaryWrapper: React.FC = ({ + children, + ...props +}) => { + const [resetKey, setResetKey] = useState(0) + + const resetErrorBoundary = useCallback(() => { + setResetKey((prev) => prev + 1) + }, []) + + const captureError = useCallback((error: Error) => { + throw error + }, []) + + const contextValue: ErrorBoundaryContextType = { + resetErrorBoundary, + captureError, + } + + return ( + + + {children} + + + ) +} + +export function useErrorBoundaryContext() { + const context = useContext(ErrorBoundaryContext) + if (!context) { + throw new Error( + 'useErrorBoundaryContext must be used within an ErrorBoundaryWrapper' + ) + } + return context +} + +export const withErrorBoundary = ( + Component: React.ComponentType, + fallback?: ReactNode | ((error: Error, errorInfo: ErrorInfo) => ReactNode), + onError?: (error: Error, errorInfo: ErrorInfo) => void +) => { + const WrappedComponent = (props: T) => ( + + + + ) + + WrappedComponent.displayName = `withErrorBoundary(${ + Component.displayName || Component.name + })` + + return WrappedComponent +} + +export default ErrorBoundaryWrapper + +export { ErrorBoundary as ErrorBoundaryClass } diff --git a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx index 7d6007b70c..760f5519de 100644 --- a/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx +++ b/src/components/lab-embed/embed-element/__tests__/embed-element.test.tsx @@ -3,63 +3,268 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { render, screen } from '@testing-library/react' +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' +import { render, screen, fireEvent, act } from '@testing-library/react' import EmbedElement from '../index' -// Mock the useInstruqtEmbed hook -const mockUseInstruqtEmbed = vi.fn() +import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import { useRouter } from 'next/router' +import { trackSandboxEvent } from 'lib/posthog-events' + vi.mock('contexts/instruqt-lab', () => ({ - useInstruqtEmbed: () => mockUseInstruqtEmbed(), + useInstruqtEmbed: vi.fn(), +})) + +vi.mock('next/router', () => ({ + useRouter: vi.fn(), })) +vi.mock('lib/posthog-events', () => ({ + trackSandboxEvent: vi.fn(), + SANDBOX_EVENT: { + SANDBOX_LOADED: 'sandbox_loaded', + SANDBOX_ERROR: 'sandbox_error', + SANDBOX_RETRY: 'sandbox_retry', + }, +})) + +const mockUseInstruqtEmbed = vi.mocked(useInstruqtEmbed) +const mockUseRouter = vi.mocked(useRouter) +const mockTrackSandboxEvent = vi.mocked(trackSandboxEvent) + describe('EmbedElement', () => { + const createMockRouter = () => ({ + asPath: '/test-path', + route: '/test-path', + pathname: '/test-path', + query: {}, + basePath: '', + isLocaleDomain: false, + push: vi.fn().mockResolvedValue(true), + replace: vi.fn().mockResolvedValue(true), + reload: vi.fn(), + back: vi.fn(), + forward: vi.fn(), + prefetch: vi.fn().mockResolvedValue(undefined), + beforePopState: vi.fn(), + events: { + on: vi.fn(), + off: vi.fn(), + emit: vi.fn(), + }, + isFallback: false, + isReady: true, + isPreview: false, + locale: undefined, + locales: undefined, + defaultLocale: undefined, + domainLocales: undefined, + }) + + const createMockInstruqtContext = (overrides = {}) => ({ + labId: 'test-lab-id', + active: true, + setActive: vi.fn(), + openLab: vi.fn(), + closeLab: vi.fn(), + hasConfigError: false, + configErrors: [], + ...overrides, + }) + beforeEach(() => { vi.clearAllMocks() - mockUseInstruqtEmbed.mockImplementation(() => ({ - active: true, - labId: 'test-lab-id', - })) + vi.useFakeTimers() + + mockUseRouter.mockReturnValue(createMockRouter()) + mockUseInstruqtEmbed.mockReturnValue(createMockInstruqtContext()) }) - it('renders an iframe with the correct props', () => { - render() - - const iframe = screen.getByTitle('Instruqt') - expect(iframe).toBeInTheDocument() - expect(iframe.tagName).toBe('IFRAME') - expect(iframe).toHaveAttribute( - 'src', - 'https://play.instruqt.com/embed/test-lab-id' - ) - expect(iframe).toHaveAttribute( - 'sandbox', - 'allow-same-origin allow-scripts allow-popups allow-forms allow-modals' - ) + afterEach(() => { + vi.useRealTimers() + vi.clearAllTimers() }) - it('has proper focus behavior when mounted', () => { - render() - const iframe = screen.getByTitle('Instruqt') - expect(document.activeElement).toBe(iframe) + describe('rendering and props', () => { + it('renders an iframe with the correct props', () => { + render() + + const iframe = screen.getByTitle('Instruqt Lab Environment: test-lab-id') + + expect(iframe).toBeInTheDocument() + expect(iframe.tagName).toBe('IFRAME') + expect(iframe).toHaveAttribute( + 'src', + 'https://play.instruqt.com/embed/test-lab-id' + ) + expect(iframe).toHaveAttribute( + 'sandbox', + 'allow-same-origin allow-scripts allow-popups allow-forms allow-modals' + ) + expect(iframe).toHaveAttribute( + 'aria-label', + 'Interactive lab environment for test-lab-id' + ) + expect(iframe).toHaveAttribute('allow', 'fullscreen') + }) + + it('shows loading state initially', () => { + render() + + expect(screen.getByText('Loading your sandbox...')).toBeInTheDocument() + expect( + screen.getByText('This may take a few moments') + ).toBeInTheDocument() + expect( + screen.getByRole('status', { name: /loading sandbox/i }) + ).toBeInTheDocument() + }) }) - it('has the correct styles when active', () => { - render() + describe('state transitions', () => { + it('hides loading state when iframe loads', () => { + render() + + const iframe = screen.getByTitle('Instruqt Lab Environment: test-lab-id') + + fireEvent.load(iframe) + + expect( + screen.queryByText('Loading your sandbox...') + ).not.toBeInTheDocument() + + expect(mockTrackSandboxEvent).toHaveBeenCalledWith('sandbox_loaded', { + labId: 'test-lab-id', + page: '/test-path', + }) + }) + + it('shows error state when timeout occurs', () => { + render() + + act(() => { + vi.advanceTimersByTime(30000) + }) + + expect(screen.getByText('Unable to Load Sandbox')).toBeInTheDocument() + expect( + screen.getAllByText(/Failed to load sandbox/).length + ).toBeGreaterThan(0) + expect(screen.getByRole('alert')).toBeInTheDocument() + }) - const iframe = screen.getByTitle('Instruqt') - expect(iframe.className).not.toContain('_hide_') + it('allows retry when error occurs', () => { + render() + + act(() => { + vi.advanceTimersByTime(30000) + }) + + const retryButton = screen.getByRole('button', { name: /try again/i }) + expect(retryButton).toBeInTheDocument() + + act(() => { + fireEvent.click(retryButton) + }) + + expect(screen.getByText('Loading your sandbox...')).toBeInTheDocument() + + expect(mockTrackSandboxEvent).toHaveBeenCalledWith( + 'sandbox_retry', + expect.objectContaining({ + labId: 'test-lab-id', + page: '/test-path', + }) + ) + }) }) - it('has the correct styles when not active', () => { - // Mock the hook to return active: false - mockUseInstruqtEmbed.mockImplementation(() => ({ - active: false, - labId: 'test-lab-id', - })) + describe('edge cases and error handling', () => { + it('shows no lab selected state when labId is null', () => { + mockUseInstruqtEmbed.mockReturnValue( + createMockInstruqtContext({ + active: true, + labId: null, + }) + ) + + render() + + expect(screen.getByText('No Lab Selected')).toBeInTheDocument() + expect( + screen.getByText(/Please select a lab from the sandbox menu/) + ).toBeInTheDocument() + expect(screen.getByRole('status')).toBeInTheDocument() + }) + + it('has the correct styles when not active', () => { + mockUseInstruqtEmbed.mockReturnValue( + createMockInstruqtContext({ + active: false, + labId: 'test-lab-id', + }) + ) + + render() + + const container = screen + .getByTitle('Instruqt Lab Environment: test-lab-id') + .closest('div') + expect(container).toHaveClass('_hide_4118c4') + }) + + it('shows Try Again button when error occurs', () => { + render() + + // Trigger timeout to get error state + act(() => { + vi.advanceTimersByTime(30000) + }) + + // Verify retry button is present + expect( + screen.getByRole('button', { name: /try again/i }) + ).toBeInTheDocument() + }) + }) + + describe('accessibility', () => { + it('includes proper accessibility attributes', () => { + render() + + const iframe = screen.getByTitle('Instruqt Lab Environment: test-lab-id') + + // Verify accessibility attributes + expect(iframe).toHaveAttribute( + 'aria-label', + 'Interactive lab environment for test-lab-id' + ) + expect(iframe).toHaveAttribute('aria-live', 'polite') + expect(iframe).toHaveAttribute('aria-busy', 'true') // Initially loading + + // Verify screen reader announcements + expect( + screen.getByText('Loading sandbox environment') + ).toBeInTheDocument() + + // Verify loading spinner is hidden from screen readers + const spinner = document.querySelector('[aria-hidden="true"]') + expect(spinner).toBeInTheDocument() + }) + + it('provides proper ARIA roles for different states', () => { + render() + + // Loading state + expect( + screen.getByRole('status', { name: /loading sandbox/i }) + ).toBeInTheDocument() - render() + act(() => { + vi.advanceTimersByTime(30000) + }) - const iframe = screen.getByTitle('Instruqt') - expect(iframe.className).toContain('_hide_') + expect(screen.getByRole('alert')).toBeInTheDocument() + }) }) }) diff --git a/src/components/lab-embed/embed-element/embed-element.module.css b/src/components/lab-embed/embed-element/embed-element.module.css index daafb8ae03..50a100af34 100644 --- a/src/components/lab-embed/embed-element/embed-element.module.css +++ b/src/components/lab-embed/embed-element/embed-element.module.css @@ -11,6 +11,141 @@ } } +.embedContainer { + width: 100%; + height: 100%; + position: relative; +} + .hide { display: none; } + +.loadingContainer { + position: absolute; + top: 0; + left: 0; + right: 0; + bottom: 0; + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + background-color: var(--token-color-surface-primary); + border: 1px solid var(--token-color-border-primary); + border-radius: 8px; + padding: 2rem; + z-index: 1; +} + +.loadingSpinner { + width: 40px; + height: 40px; + border: 3px solid var(--token-color-border-primary); + border-top: 3px solid var(--token-color-palette-blue-200); + border-radius: 50%; + animation: spin 1s linear infinite; + margin-bottom: 1rem; +} + +@keyframes spin { + 0% { transform: rotate(0deg); } + 100% { transform: rotate(360deg); } +} + +.loadingText { + text-align: center; + color: var(--token-color-foreground-primary); + + & h3 { + margin: 0 0 0.5rem 0; + font-size: 1.125rem; + font-weight: 500; + } + + & p { + margin: 0; + color: var(--token-color-foreground-faint); + font-size: 0.875rem; + } +} + +.errorContainer { + position: absolute; + top: 0; + left: 0; + right: 0; + bottom: 0; + display: flex; + align-items: center; + justify-content: center; + background-color: var(--token-color-surface-primary); + border: 1px solid var(--token-color-border-critical); + border-radius: 8px; + padding: 2rem; + z-index: 1; + + &.fullHeight { + position: relative; + height: 100%; + } +} + +.errorContent { + text-align: center; + max-width: 400px; + + & h3 { + margin: 0 0 1rem 0; + color: var(--token-color-foreground-critical); + font-size: 1.125rem; + font-weight: 500; + } + + & p { + margin: 0 0 1.5rem 0; + color: var(--token-color-foreground-primary); + font-size: 0.875rem; + line-height: 1.5; + } +} + +.retryButton { + background-color: var(--token-color-palette-blue-200); + color: white; + border: none; + border-radius: 4px; + padding: 0.75rem 1.5rem; + font-size: 0.875rem; + font-weight: 500; + cursor: pointer; + transition: background-color 0.2s ease; + + &:hover { + background-color: var(--token-color-palette-blue-300); + } + + &:focus { + outline: 2px solid var(--token-color-focus-action-internal); + outline-offset: 2px; + } + + &:disabled { + background-color: var(--token-color-surface-faint); + color: var(--token-color-foreground-disabled); + cursor: not-allowed; + } +} + +/* Screen reader only content */ +.sr-only { + position: absolute !important; + width: 1px !important; + height: 1px !important; + padding: 0 !important; + margin: -1px !important; + overflow: hidden !important; + clip: rect(0, 0, 0, 0) !important; + white-space: nowrap !important; + border: 0 !important; +} diff --git a/src/components/lab-embed/embed-element/index.tsx b/src/components/lab-embed/embed-element/index.tsx index 6ba8a5dfcc..6d08d61f8b 100644 --- a/src/components/lab-embed/embed-element/index.tsx +++ b/src/components/lab-embed/embed-element/index.tsx @@ -3,35 +3,265 @@ * SPDX-License-Identifier: MPL-2.0 */ -import { MutableRefObject, useRef, useEffect } from 'react' +import { useRef, useEffect, useState, useCallback, memo } from 'react' import classNames from 'classnames' +import { useRouter } from 'next/router' import { useInstruqtEmbed } from 'contexts/instruqt-lab' +import { trackSandboxEvent, SANDBOX_EVENT } from 'lib/posthog-events' import s from './embed-element.module.css' -export default function EmbedElement(): JSX.Element { - const ref: MutableRefObject = useRef() +interface EmbedState { + isLoading: boolean + hasError: boolean + errorMessage: string + retryCount: number +} + +/** + * EmbedElement component for displaying Instruqt lab environments + * + */ +const EmbedElement = memo(function EmbedElement(): JSX.Element { + const ref = useRef(null) + const { active, labId } = useInstruqtEmbed() + const router = useRouter() + + const [embedState, setEmbedState] = useState({ + isLoading: true, + hasError: false, + errorMessage: '', + retryCount: 0, + }) + + const resetEmbedState = useCallback(() => { + setEmbedState({ + isLoading: true, + hasError: false, + errorMessage: '', + retryCount: 0, + }) + }, []) + + const handleIframeLoad = useCallback(() => { + setEmbedState((prev) => ({ + ...prev, + isLoading: false, + hasError: false, + })) + + if (labId) { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_LOADED, { + labId, + page: router.asPath, + }) + } + }, [labId, router.asPath]) + + const handleIframeError = useCallback(() => { + setEmbedState((prev) => ({ + ...prev, + isLoading: false, + hasError: true, + errorMessage: + 'Failed to load sandbox. Please check your internet connection and try again.', + })) + + // Track error + if (labId) { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_ERROR, { + labId, + page: router.asPath, + error: 'iframe_load_error', + retryCount: embedState.retryCount, + }) + } + }, [labId, router.asPath, embedState.retryCount]) + + const handleRetry = useCallback(() => { + if (embedState.retryCount < 3) { + setEmbedState((prev) => ({ + ...prev, + isLoading: true, + hasError: false, + errorMessage: '', + retryCount: prev.retryCount + 1, + })) + + if (labId) { + trackSandboxEvent(SANDBOX_EVENT.SANDBOX_RETRY, { + labId, + page: router.asPath, + retryCount: embedState.retryCount + 1, + }) + } + + const iframe = ref.current + if (iframe) { + const expectedSrc = `https://play.instruqt.com/embed/${labId}` + iframe.src = '' + const timeoutId = setTimeout(() => { + if (ref.current) { + ref.current.src = expectedSrc + } + }, 100) + + return () => clearTimeout(timeoutId) + } + } else { + setEmbedState((prev) => ({ + ...prev, + errorMessage: + 'Maximum retry attempts reached. Please refresh the page or try again later.', + })) + } + }, [embedState.retryCount, labId, router.asPath]) + + // Reset state when labId changes + useEffect(() => { + if (labId) { + resetEmbedState() + } + }, [labId, resetEmbedState]) useEffect(() => { - if (!ref.current) { + if (!labId || !ref.current) { return } - // ensures that focus properly shifts when the lab component is mounted - ref.current.focus() - }, []) + const iframe = ref.current + const expectedSrc = `https://play.instruqt.com/embed/${labId}` - const { active, labId } = useInstruqtEmbed() + if (iframe.src !== expectedSrc) { + iframe.src = expectedSrc + } + }, [labId]) + + useEffect(() => { + if (!embedState.isLoading || !labId) { + return + } + + const timeoutId = setTimeout(() => { + setEmbedState((current) => { + if (current.isLoading) { + return { + ...current, + isLoading: false, + hasError: true, + errorMessage: + 'Failed to load sandbox. Please check your internet connection and try again.', + } + } + return current + }) + }, 30000) + + return () => clearTimeout(timeoutId) + }, [embedState.isLoading, labId]) + + useEffect(() => { + const iframe = ref.current + if (!iframe || !active) { + return + } + + iframe.focus() + }, [active]) + + if (!labId) { + return ( +
      +
      +

      No Lab Selected

      +

      Please select a lab from the sandbox menu to get started.

      +
      +
      + ) + } return ( -