docs: fix menu clipping in resizable examples + configurable dev port (#42470)

* docs: prevent menus from being clipped in resizable examples

The resizable container needs overflow: hidden for the CSS resize handle to
work, which clips menus/dropdowns when they open. Render them with a fixed
positioning strategy in the live preview only so they can spill outside the
container, leaving the displayed markup untouched.

* docs: make the Astro dev server port configurable via PORT

Default to 9001 but allow PORT to override the dev/preview server port so
multiple worktrees can run side by side without colliding.

diff --git a/package.json b/package.json
index b35343ccbbfaea2a29ab4554c8fcc8ee95dd7e9d..00e2bf414a1713c212e8ac6ca3d9c56b1f05fa4d 100644 (file)
--- a/package.json
+++ b/package.json
@@ -112,9 +112,9 @@
     "watch-js-main": "nodemon --watch js/src/ --ext js --exec \"npm-run-all js-lint js-compile\"",
     "watch-js-docs": "nodemon --watch site/src/assets/ --ext js --exec \"npm run js-lint\"",
     "astro-clean": "rm -rf site/.astro site/node_modules/.astro",
-    "astro-dev": "astro dev --root site --port 9001",
+    "astro-dev": "astro dev --root site",
     "astro-build": "astro build --root site && rm -rf _site && cp -r site/dist _site && pagefind --site _site",
-    "astro-preview": "astro preview --root site --port 9001",
+    "astro-preview": "astro preview --root site",
     "spellcheck": "cspell --config .cspell.json \"**/*.{md,mdx}\""
   },
   "peerDependencies": {

diff --git a/site/astro.config.ts b/site/astro.config.ts
index a8cdc6dbb6320b2cd60b8127d9fa13bade73662b..b9f31c05c79b6a758c2e68247264433609d8ed81 100644 (file)
--- a/site/astro.config.ts
+++ b/site/astro.config.ts
@@ -17,9 +17,13 @@ const bootstrapBundlePath = fileURLToPath(new URL('../dist/js/bootstrap.bundle.j
 
 const isDev = process.env.NODE_ENV === 'development'
 
+// Allow the dev/preview server port to be overridden via `PORT` (falling back to
+// 9001) so multiple worktrees can run side by side without colliding.
+const port = Number.parseInt(process.env.PORT ?? '', 10) || 9001
+
 const site = isDev
   ? // In development mode, use the local dev server.
-    'http://localhost:9001'
+    `http://localhost:${port}`
   : process.env.DEPLOY_PRIME_URL !== undefined
     ? // If deploying on Netlify, use the `DEPLOY_PRIME_URL` environment variable.
       process.env.DEPLOY_PRIME_URL
@@ -66,6 +70,9 @@ export default defineConfig({
   devToolbar: {
     enabled: false
   },
+  server: {
+    port
+  },
   site,
   vite: {
     plugins: [stackblitzPlugin()],

diff --git a/site/src/components/shortcodes/ResizableExample.astro b/site/src/components/shortcodes/ResizableExample.astro
index 0dffc70530fdbd083f92ba2a1b7e1b8e1dbd4573..525ebed8d78a9119356220a334c2a9273c9f4255 100644 (file)
--- a/site/src/components/shortcodes/ResizableExample.astro
+++ b/site/src/components/shortcodes/ResizableExample.astro
@@ -47,6 +47,15 @@ const containerClass = className || classFromClass
 let markup = Array.isArray(code) ? code.join('\n') : code
 markup = replacePlaceholdersInHtml(markup)
 
+// The resizable container needs `overflow: hidden` for the CSS `resize` handle
+// to work, which clips popovers like menus/dropdowns when they open. Render them
+// with a fixed positioning strategy in the live preview only so they can spill
+// outside the container. The displayed markup below is left untouched.
+const previewMarkup = markup.replace(
+  /data-bs-toggle="(menu|dropdown)"(?![^>]*\bdata-bs-strategy=)/g,
+  'data-bs-toggle="$1" data-bs-strategy="fixed"'
+)
+
 const simplifiedMarkup = markup.replace(
   /<svg.*class="bd-placeholder-img(?:-lg)?(?: *?bd-placeholder-img-lg)? ?(.*?)".*?<\/svg>/g,
   (match, classes) => `<img src="..."${classes ? ` class="${classes}"` : ''} alt="...">`
@@ -59,7 +68,7 @@ const simplifiedMarkup = markup.replace(
       class:list={['bd-resizable-container', containerClass]}
       style={`width: ${initialWidth}; min-width: ${minWidth};`}
     >
-      <Fragment set:html={markup} />
+      <Fragment set:html={previewMarkup} />
     </div>
   </div>
   {showMarkup && <Code code={simplifiedMarkup} lang="html" nestedInExample={true} />}