docs: create itdoc playground pages on official documentation#254
docs: create itdoc playground pages on official documentation#254
Conversation
WalkthroughAdds an interactive Playground to the docs site. Docusaurus config receives two server-only plugins: Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Pre-merge checks and finishing touches❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PENEKhun
requested review from
json-choi and
wnghdcjfe
and removed request for
wnghdcjfe
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
script/clean.mjs (2)
22-31: Clean script is safe but could benefit from directory validation.The implementation correctly uses native
fs/promises.rmwithforce: true(no error if missing) andrecursive: truefor nested directories. Error handling is appropriate.Consider adding a safety check to verify the script is running from the expected repository root:
async function main() { + // Verify we're in the correct directory + const packageJsonPath = resolve(process.cwd(), "package.json") + try { + await fs.access(packageJsonPath) + } catch { + console.error("[clean] Must run from repository root (package.json not found)") + process.exitCode = 1 + return + } + const target = resolve(process.cwd(), "build")This prevents accidental deletion if the script is invoked from an unexpected location.
18-18: Narrow the ESLint disable comment.The broad
/* eslint-disable */disables all rules. Consider using more specific disables if only certain rules need to be suppressed, or remove it entirely if no violations exist.-/* eslint-disable */Then run ESLint to see if any specific rules need to be disabled.
itdoc-doc/src/pages/playground.module.css (1)
96-96: Provide a CSS fallback or tighten your browserslist for color-mix() support
Your production targets (>0.5%, not dead) include Safari versions below 16.2, which don’t supportcolor-mix(). To prevent missing backgrounds, add a fallback before your mix—for example:background-color: var(--ifm-color-emphasis-200); background-color: color-mix(in srgb, var(--ifm-color-emphasis-200) 60%, transparent);—or restrict your browserslist to Safari >= 16.2.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
itdoc-doc/pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (14)
itdoc-doc/docusaurus.config.ts(4 hunks)itdoc-doc/i18n/ko/docusaurus-theme-classic/navbar.json(1 hunks)itdoc-doc/package.json(1 hunks)itdoc-doc/src/components/Playground/index.tsx(1 hunks)itdoc-doc/src/components/Playground/styles.module.css(1 hunks)itdoc-doc/src/components/Playground/webcontainerStub.ts(1 hunks)itdoc-doc/src/pages/index.module.css(1 hunks)itdoc-doc/src/pages/index.tsx(1 hunks)itdoc-doc/src/pages/playground.module.css(1 hunks)itdoc-doc/src/pages/playground.tsx(1 hunks)itdoc-doc/static/playground/.gitignore(1 hunks)lib/dsl/interface/testContext.ts(1 hunks)package.json(2 hunks)script/clean.mjs(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (1)
lib/dsl/interface/testContext.ts (1)
lib/dsl/interface/itDoc.ts (2)
testContext(37-47)description(21-48)
🔇 Additional comments (8)
itdoc-doc/package.json (1)
23-32: LGTM! Dependencies align with Playground requirements.The added dependencies appropriately support the interactive Playground feature:
- CodeMirror packages for the in-browser editor
- WebContainer API (v1.6.1) for the browser-based Node.js runtime
- XTerm packages for terminal emulation
The caret version ranges follow standard npm practices for automatic minor/patch updates.
lib/dsl/interface/testContext.ts (2)
20-26: Runtime detection pattern is safe.The IIFE with try-catch ensures graceful fallback if
@webcontainer/envis unavailable or ifisWebContainer()throws.
38-64: No action required: testContext.get() null case is handled
ResponseBuilder coalescestestContext.get()to an empty string (testContext.get() || "").itdoc-doc/src/pages/index.tsx (1)
24-26: LGTM! Playground button follows existing patterns.The implementation mirrors the existing "Introduce itdoc" button pattern and correctly uses Docusaurus
Linkfor client-side routing to the new/playgroundroute.itdoc-doc/static/playground/.gitignore (1)
1-1: LGTM! Appropriately excludes generated tarball.The packaged
itdoc.tgzis a build artifact and should not be committed. This aligns with the Playground packaging workflow that generates the tarball at build time.itdoc-doc/src/pages/index.module.css (2)
27-41: LGTM! Playground button styling follows Docusaurus theming.The
.playgroundButtonclass appropriately uses Docusaurus CSS custom properties for consistent theming across light/dark modes. Hover and focus states are properly defined for accessibility.
19-25: .buttons usage limited to homepageSearch shows
.buttonsis only referenced insrc/pages/index.tsx, so the new column layout affects only the homepage and poses no wider impact.itdoc-doc/i18n/ko/docusaurus-theme-classic/navbar.json (1)
18-21: Approve Korean Playground translation: Default label exists in docusaurus.config.ts and the translation follows the established pattern.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
itdoc-doc/src/components/Playground/styles.module.css (1)
420-432: Past review concern has been resolved.The
display: griddeclaration is now present on line 424, so the run modal will correctly display the terminal beside the generated docs in a grid layout.
🧹 Nitpick comments (3)
itdoc-doc/src/components/Playground/styles.module.css (2)
353-353: Use more reasonable z-index values.The z-index values of
9999999999(line 353) and999999999999(line 988) are unnecessarily high. Consider using more maintainable values in a lower range (e.g., 1000-2000) or establishing a z-index scale via CSS variables to keep stacking contexts manageable across the codebase.Apply this diff to use more reasonable values:
.runModalBackdrop { position: fixed; inset: 0; background: rgba(15, 23, 42, 0.65); display: flex; align-items: center; justify-content: center; padding: clamp(1.5rem, 4vw, 2.5rem); - z-index: 9999999999; + z-index: 1000; }.previewModalBackdrop { position: fixed; inset: 0; background: rgba(15, 23, 42, 0.78); backdrop-filter: blur(4px); display: flex; justify-content: center; align-items: center; padding: clamp(2rem, 6vw, 4rem); - z-index: 999999999999; + z-index: 1100; }Also applies to: 988-988
828-828: Provide fallback or @supports guard for color-mix()
color-mix() is supported from Chrome/Edge 111+, Firefox 113+, Safari/iOS 16.2+, Opera 97+, Samsung Internet 22+—wrap the usages on lines 828 and 870 in an @supports(color-mix()) check or supply a fallback color for older browsers.itdoc-doc/src/components/Playground/index.tsx (1)
336-1256: Consider splitting this large component for improved maintainability.The Playground component is comprehensive (1258 lines) and handles many concerns: WebContainer orchestration, terminal output, code editors, install progress, run modal, and preview modal. While the current implementation is functional, splitting it into smaller, focused components would improve maintainability and testability.
Consider extracting sub-components such as:
PlaygroundTerminal- Terminal display and managementPlaygroundEditor- CodeMirror editor wrapperInstallProgressOverlay- Installation progress UIRunResultsModal- Test run output modalSwaggerPreviewModal- OpenAPI preview modalThis would reduce the cognitive load and make each piece easier to reason about independently.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
itdoc-doc/src/components/Playground/index.tsx(1 hunks)itdoc-doc/src/components/Playground/styles.module.css(1 hunks)package.json(2 hunks)
🧰 Additional context used
🧬 Code graph analysis (1)
itdoc-doc/src/components/Playground/index.tsx (1)
script/makedocs/index.ts (1)
generateDocs(29-75)
🔇 Additional comments (4)
itdoc-doc/src/components/Playground/index.tsx (4)
1096-1103: Verify the empty Swagger Preview placeholder is intentional.The "Swagger Preview" section in the run modal renders an empty placeholder (lines 1096-1102). The actual Redoc preview only appears in the fullscreen modal. If this is intentional to encourage users to click "Fullscreen preview," consider adding a hint message in this placeholder area. Otherwise, if an inline preview is desired here, you'll need to render a second Redoc instance.
Is the empty inline preview placeholder intentional, or should this section render a compact Redoc preview similar to the fullscreen modal?
507-608: LGTM: Robust WebContainer setup and provisioning.The WebContainer initialization effect handles multiple concerns well:
- Proper cancellation pattern to prevent memory leaks
- Graceful fallback from local tarball to npm registry
- Clear error messages with cross-origin isolation hints
- Appropriate cleanup on unmount
The implementation is comprehensive and handles edge cases effectively.
433-505: LGTM: Solid terminal integration with proper lifecycle management.The terminal setup effect demonstrates good practices:
- Defers initialization until the modal is visible
- Handles pending output chunks before terminal is ready
- Uses ResizeObserver and window resize events for responsive fitting
- Proper cleanup and disposal on unmount
- Try-catch blocks prevent fit() errors from breaking the UI
802-847: LGTM: Well-structured test execution flow.The
handleRunfunction handles the test execution lifecycle effectively:
- Writes updated code to the WebContainer filesystem
- Pipes process output to the terminal
- Uses retry logic to handle eventual consistency of generated files
- Provides clear, actionable error messages for different failure scenarios
- Proper state management throughout the async flow
wnghdcjfe
left a comment
wnghdcjfe
left a comment
There was a problem hiding this comment.
I think almost all the codes are good.
However, the swagger privacy does not appear. Please check it.
2025-10-07.11-00-04.mp4
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
itdoc-doc/docusaurus.config.ts (1)
69-74: Consider simplifying or documenting the cache invalidation logic.The
buildDirmtime check on line 74 is somewhat redundant since the plugin always runspnpm run buildwhen repacking (line 85). The check will only trigger if an external build was run between doc builds, but then the plugin rebuilds anyway.This conservative approach works correctly but could be simplified to just check if the tarball exists (unless you want to detect external builds to avoid redundant rebuilds).
Consider either:
- Removing the buildDir mtime check and relying on the force flag for cache invalidation:
const shouldRepack = forceRepack || - !fs.existsSync(targetTarball) || - !fs.existsSync(buildDir) || - fs.statSync(buildDir).mtimeMs > fs.statSync(targetTarball).mtimeMs + !fs.existsSync(targetTarball)
- Or adding a comment explaining the reasoning:
// Repack if: forced, tarball missing, or buildDir was externally rebuilt const shouldRepack = ...
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
itdoc-doc/docusaurus.config.ts(4 hunks)
🔇 Additional comments (4)
itdoc-doc/docusaurus.config.ts (4)
4-7: LGTM! Server-side imports are appropriate.The Node.js module imports (fs, path, os, execFileSync) are correctly added to support the server-side plugin operations below.
39-57: LGTM! SSR alias plugin is correctly implemented.The
webcontainerAliasPlugincorrectly stubs out the WebContainer API for server-side rendering by aliasing it only whenisServeris true. This prevents SSR build failures for browser-only APIs.
58-122: LGTM! Plugin correctly builds and packages itdoc for the playground.The
webcontainerLocalItdocPluginimplementation is solid:
- Proper error handling with try/finally cleanup
- Safe command execution using
execFileSync- Windows compatibility addressed with
shell: trueoption (lines 88, 96)- Careful parsing of pnpm output with null checks
- Conservative caching approach that favors correctness
165-165: LGTM! Playground navbar link is correctly added.The navbar item follows standard Docusaurus configuration and integrates properly with the new playground feature.
sorry my mistake! 
i remove that section. check it please |
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
itdoc-doc/src/components/Playground/index.tsx (1)
1211-1246: A11y: same focus management for the Swagger Preview modal.Mirror the focus trap / initial focus / ESC / restore focus pattern here.
🧹 Nitpick comments (2)
itdoc-doc/src/components/Playground/index.tsx (2)
999-1019: A11y: add modal focus trap, initial focus, ESC to close, and restore focus.Improve keyboard UX/compliance: set initial focus to Close, trap focus within modal, close on Escape, and restore focus to the Run button on exit.
Example (add alongside existing state/effects):
// refs const runButtonRef = useRef<HTMLButtonElement|null>(null) const runCloseRef = useRef<HTMLButtonElement|null>(null) // set ref on the Run button and Close button // <button ref={runButtonRef} ...>Run</button> // <button ref={runCloseRef} ...>Close</button> useEffect(() => { if (!showRunModal) return const prev = document.activeElement as HTMLElement | null runCloseRef.current?.focus() const onKeyDown = (e: KeyboardEvent) => { if (e.key === "Escape") setShowRunModal(false) } window.addEventListener("keydown", onKeyDown) return () => { window.removeEventListener("keydown", onKeyDown) ;(prev ?? runButtonRef.current)?.focus() } }, [showRunModal]) // Optional: implement a simple focus trap by cycling Tab focus within the modal.
398-407: Pin Redoc CDN to v2.5.0 and add SRI or self-host
Replace theREDOC_CDN_URLalias with the exact v2.5.0 URL (e.g.https://cdn.jsdelivr.net/npm/redoc@2.5.0/bundles/redoc.standalone.js), compute and include theintegrityhash per jsDelivr SRI guidelines, or vend the bundle under/staticto eliminate supply-chain risk.
|
I found an additional bug where the API description in the Swagger preview was not visible because both the background and the font were white. I fixed it through b861994 AS-IS
TO-BE
|
2 participants
Changes
how to access playground pages?
loading playground
After loading
aa.mov
How to test for reviewer
clone this branches
run
closed #244
Summary by CodeRabbit
New Features
UI/Style
Localization
Chores