feat: ChoiceGroup

demo/+docpress.tsx

@@ -45,6 +45,20 @@ const config: Config = {
   // globalNote: <GlobalNoteWarning />,
   topNavigation: <TopNavigation />,
   navMaxWidth: 1140,
+  choices: {
+    'pkg-manager': {
+      choices: ['npm', 'pnpm', 'yarn', 'bun'],
+      default: 'npm',
+    },
+    server: {
+      choices: ['hono', 'express', 'fastify'],
+      default: 'hono',
+    },
+    'ui-ext': {
+      choices: ['vike-react', 'vike-vue', 'vike-solid'],
+      default: 'vike-react',
+    },
+  },
 }
 
 /*

demo/pages/features/+Page.mdx

@@ -220,3 +220,149 @@ async function onNewTodo(text: string) {
 // https://vike.dev
 const a: number = 1
 ```
+
+## ChoiceGroup
+
+Using `choice=choice-name` meta to group code blocks into multiple choices:
+
+```shell choice=hono
+npm i hono @photonjs/hono
+```
+
+```shell choice=express
+npm i express @photonjs/express
+```
+
+```ts choice=hono file-added
+// server/index.ts
+
+import { Hono } from 'hono'
+import { apply, serve } from 'vike-photon/hono'
+
+function startServer() {
+  const app = new Hono()
+  apply(app)
+  return serve(app)
+}
+
+export default startServer()
+```
+
+```ts choice=express file-added
+// server/index.ts
+
+import express from 'express'
+import { apply, serve } from 'vike-photon/express'
+
+function startServer() {
+  const app = express()
+  apply(app)
+  return serve(app)
+}
+
+export default startServer()
+```
+
+Skipping the first choice from `+docpress.choices['server']` caused it to become the third disabled option in the select options.
+
+```ts choice=express file-added
+// server/index.ts
+
+import express from 'express'
+import { apply, serve } from 'vike-photon/express'
+
+function startServer() {
+  const app = express()
+  apply(app)
+  return serve(app)
+}
+
+export default startServer()
+```
+
+```ts choice=fastify file-added
+// server/index.ts
+
+import fastify from 'fastify'
+import rawBody from 'fastify-raw-body'
+import { apply, serve } from '@photonjs/fastify'
+
+async function startServer() {
+  const app = fastify({
+    // ⚠️ Mandatory for HMR support
+    forceCloseConnections: true
+  })
+  // ⚠️ Mandatory for Vike's SSR middleware
+  await app.register(rawBody)
+  await apply(app)
+  return serve(app)
+}
+
+export default startServer()
+```
+
+Some paragraph.
+
+:::Choice{#express}
+> Express.js is deprecated.
+:::
+
+
+Using `:::Choice{#choice-name} {:mdx}` directive to combine multiple contents for a single choice:
+
+:::Choice{#vike-react}
+```tsx
+import { ClientOnly } from 'vike-react/ClientOnly'
+
+function Page() {
+  return (
+    <ClientOnly fallback={<p>Loading...</p>}>
+      <SomeComponent />
+    </ClientOnly>
+  )
+}
+```
+
+Props:
+- **children**: Content rendered only on the client-side after hydration.
+- **fallback** (optional): Content shown during SSR and before hydration completes.
+:::
+
+:::Choice{#vike-vue}
+```vue
+<template>
+  <ClientOnly>
+    <SomeComponent />
+    <template #fallback>
+      <p>Loading...</p>
+    </template>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { ClientOnly } from 'vike-vue/ClientOnly'
+</script>
+```
+
+Props:
+- **default slot**: Content rendered only on the client-side after hydration.
+- **fallback slot** (optional): Content shown during SSR and before hydration completes.
+:::
+
+:::Choice{#vike-solid}
+```tsx
+import { ClientOnly } from 'vike-solid/ClientOnly'
+
+function Page() {
+  return (
+    <ClientOnly fallback={<p>Loading...</p>}>
+      <SomeComponent />
+    </ClientOnly>
+  )
+}
+```
+
+Props:
+- **children**: Content rendered only on the client-side after hydration.
+- **fallback** (optional): Content shown during SSR and before hydration completes.
+:::

demo/testRun.ts

@@ -152,6 +152,92 @@ function testRun(cmd: 'pnpm run dev' | 'pnpm run preview') {
     }
   })
 
+  test(`${featuresURL} - Choice Group`, async () => {
+    const firstChoiceText1 = 'npm i hono @photonjs/hono'
+    const firstChoiceText2 = "import { Hono } from 'hono'"
+    const secondChoiceText1 = 'pnpm add express @photonjs/express'
+    const secondChoiceText2 = "import express from 'express'"
+    const fastifyChoiceText = "import fastify from 'fastify'"
+
+    const hasFirstChoice = (text: string | null, yes = true) => {
+      expect(text).not.toBe(null)
+      if (yes) {
+        expect(text).toContain(firstChoiceText1)
+        expect(text).toContain(firstChoiceText2)
+      } else {
+        expect(text).not.toContain(firstChoiceText1)
+        expect(text).not.toContain(firstChoiceText2)
+      }
+    }
+
+    const hasSecondChoice = (text: string | null, yes = true) => {
+      expect(text).not.toBe(null)
+      if (yes) {
+        expect(text).toContain(secondChoiceText1)
+        expect(text).toContain(secondChoiceText2)
+      } else {
+        expect(text).not.toContain(secondChoiceText1)
+        expect(text).not.toContain(secondChoiceText2)
+      }
+    }
+
+    const hasFastifyChoice = (text: string | null, yes = true) => {
+      expect(text).not.toBe(null)
+      if (yes) {
+        expect(text).toContain(fastifyChoiceText)
+      } else {
+        expect(text).not.toContain(fastifyChoiceText)
+      }
+    }
+
+    const textFull = await page.textContent('body')
+
+    hasFirstChoice(textFull)
+    hasSecondChoice(textFull)
+    hasFastifyChoice(textFull)
+
+    const expectFirstChoice = async () => {
+      const text = await getVisibleText(page)
+      hasFirstChoice(text)
+      hasSecondChoice(text, false)
+      hasFastifyChoice(text, false)
+    }
+
+    const expectSecondChoice = async () => {
+      const text = await getVisibleText(page)
+      hasFirstChoice(text, false)
+      hasSecondChoice(text)
+      hasFastifyChoice(text, false)
+    }
+
+    const expectFastifyChoice = async () => {
+      await page.locator('select[name="server-choices"]:visible').nth(2).selectOption('fastify')
+      const text = await getVisibleText(page)
+      hasFirstChoice(text, false)
+      hasSecondChoice(text, false)
+      hasFastifyChoice(text)
+    }
+
+    await page.evaluate(() => window.localStorage.clear())
+
+    await expectFirstChoice()
+
+    await page.selectOption(`select[name="pkg-manager-choices"]:visible`, { index: isDev ? 0 : 1 })
+    await page.selectOption(`select[name="server-choices"]:visible`, { index: isDev ? 0 : 1 })
+
+    await autoRetry(
+      async () => {
+        if (isDev) {
+          await expectFirstChoice()
+        } else {
+          await expectSecondChoice()
+          await expectFastifyChoice()
+        }
+      },
+      { timeout: 5 * 1000 },
+    )
+  })
+
   const somePageUrl = '/some-page'
   test(`${somePageUrl} - custom <Pre> injected into nested MDX`, async () => {
     await page.goto(getServerUrl() + somePageUrl)