Skip to content

Commit 452e5bd

Browse files
dimaMachinahariria
dimaMachina
and
hariria
authoredAug 31, 2024··
[v3] Add <Playground /> component (#3174)
* [nextra] Playground * move to nextra.site * polish * prettier * more * fix types * more * rename * rename * more * more * more * more * add mermaid code block * it works * aaa * dada * ad * fix prettier * polish * more * pnpm i * fix * fix tests * do not increase global bundle size * add changeset --------- Co-authored-by: hariria <hariria@usc.edu>
·
nextra-theme-docs@4.0.0-rc.0nextra@3.0.0-alpha.35
1 parent 177fe84 commit 452e5bd

23 files changed

+285
-257
lines changed
 

‎.changeset/red-humans-judge.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'nextra-theme-docs': patch
3+
---
4+
5+
Add `<Playground />` component
6+
7+
https://nextra-v2-9x7fp6hti-shud.vercel.app/docs/guide/advanced/playground

‎.eslintrc.cjs

+1
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ module.exports = {
6868
'sonarjs/no-unused-collection': 'error',
6969
'unicorn/catch-error-name': 'error',
7070
'unicorn/prefer-optional-catch-binding': 'error',
71+
'unicorn/filename-case': 'error',
7172
// todo: enable
7273
'@typescript-eslint/no-explicit-any': 'off',
7374
'@typescript-eslint/no-non-null-assertion': 'off',

‎.prettierignore

+1
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ examples/swr-site/pages/en/remote/graphql-eslint/_meta.ts
99
examples/swr-site/pages/en/remote/graphql-yoga/_meta.ts
1010

1111
docs/pages/docs/guide/built-ins/cards.mdx
12+
docs/pages/docs/guide/advanced/playground.mdx

‎docs/pages/docs/guide/advanced/_meta.ts

+6-1
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,10 @@ export default {
55
latex: 'LaTeX',
66
table: 'Rendering Tables',
77
typescript: '',
8-
remote: 'Remote Content'
8+
remote: 'Remote Content',
9+
playground: {
10+
theme: {
11+
layout: 'full'
12+
}
13+
}
914
}

‎docs/pages/docs/guide/advanced/playground.mdx

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
import { Mermaid, Playground, Code, Pre, Tabs } from 'nextra/components'
2+
import { useRef, useCallback, useState, useEffect } from 'react'
3+
4+
export function Demo() {
5+
const [rawMdx, setRawMdx] = useState(`Playground components allow you to write Nextra compatible MDX that renders only on the client. It's modeled after the functionality found in [MDX Playground](https://mdxjs.com/playground).
6+
7+
In some instances where remote loading MDX is not an option, this may work as a great alternative.
8+
9+
Here's an example of a codeblock.
10+
11+
\`\`\`ts
12+
console.log("Hello world, this is a playground component!");
13+
\`\`\`
14+
15+
## Caveats
16+
17+
Due to the purely client-side nature of this component, features "Table of Contents" and "Frontmatter" will not work.
18+
19+
## Mermaid Example
20+
21+
\`\`\`mermaid
22+
graph TD
23+
subgraph AA [Consumers]
24+
A[Mobile App]
25+
B[Web App]
26+
C[Node.js Client]
27+
end
28+
subgraph BB [Services]
29+
E[REST API]
30+
F[GraphQL API]
31+
G[SOAP API]
32+
end
33+
Z[GraphQL API]
34+
A --> Z
35+
B --> Z
36+
C --> Z
37+
Z --> E
38+
Z --> F
39+
Z --> G
40+
\`\`\``)
41+
const handleInput = useCallback(e => {
42+
setRawMdx(e.currentTarget.textContent ?? '')
43+
}, [])
44+
45+
const spanRef = useRef(null)
46+
const initialRender = useRef(false)
47+
48+
useEffect(() => {
49+
if (!initialRender.current && spanRef.current) {
50+
initialRender.current = true
51+
spanRef.current.textContent = rawMdx
52+
}
53+
}, []);
54+
55+
return (
56+
<div className="grid grid-cols-2 gap-2 mt-6">
57+
<Pre data-filename="MDX" icon={MdxIcon}>
58+
<Code>
59+
<span
60+
ref={spanRef}
61+
contentEditable
62+
suppressContentEditableWarning
63+
className="outline-none"
64+
onInput={handleInput}
65+
/>
66+
</Code>
67+
</Pre>
68+
<div>
69+
<Playground
70+
fallback={
71+
<div className="flex h-full items-center justify-center text-4xl">
72+
Loading playground...
73+
</div>
74+
}
75+
source={rawMdx}
76+
components={{ Mermaid, $Tabs: Tabs }}
77+
/>
78+
</div>
79+
</div>
80+
)
81+
}
82+
83+
# Playground
84+
85+
<Demo />
86+
87+
## Usage
88+
89+
```mdx filename="Basic Usage"
90+
import { Playground } from 'nextra/components'
91+
92+
# Playground
93+
94+
Below is a playground component. It mixes into the rest of your MDX perfectly.
95+
96+
<Playground source="## Hello world" />
97+
```
98+
99+
You may also specify a fallback component like so:
100+
101+
```mdx filename="Usage with Fallback"
102+
import { Playground } from 'nextra/components'
103+
104+
<Playground
105+
source="## Hello world"
106+
fallback={<div>Loading playground...</div>}
107+
/>
108+
```

‎package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
"prettier-plugin-pkg": "0.18.1",
4242
"prettier-plugin-tailwindcss": "0.6.5",
4343
"rimraf": "6.0.1",
44-
"tsup": "8.1.0",
44+
"tsup": "8.2.4",
4545
"tsx": "^4.7.0",
4646
"turbo": "2.1.1",
4747
"typescript": "5.5.4"
@@ -54,7 +54,7 @@
5454
},
5555
"patchedDependencies": {
5656
"@changesets/assemble-release-plan@6.0.3": "patches/@changesets__assemble-release-plan@6.0.3.patch",
57-
"tsup@8.1.0": "patches/tsup@8.0.1.patch"
57+
"tsup@8.2.4": "patches/tsup.patch"
5858
}
5959
}
6060
}

‎packages/nextra-theme-blog/__test__/collect.spec.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import {
66
config,
77
indexOpts,
88
postsOpts
9-
} from './__fixture__/pageMap'
9+
} from './__fixture__/page-map'
1010

1111
vi.mock('next/router', () => ({
1212
useRouter: vi.fn()

‎packages/nextra-theme-blog/__test__/parent.spec.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { useRouter } from 'next/router'
22
import type { Mock } from 'vitest'
33
import { getParent } from '../src/utils/parent'
4-
import { articleOpts, config } from './__fixture__/pageMap'
4+
import { articleOpts, config } from './__fixture__/page-map'
55

66
vi.mock('next/router', () => ({
77
useRouter: vi.fn()

‎packages/nextra-theme-blog/__test__/tag.spec.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { describe, expect, it } from 'vitest'
22
import { getStaticTags } from '../src/utils/get-tags'
3-
import { articleOpts, indexOpts, postsOpts } from './__fixture__/pageMap'
3+
import { articleOpts, indexOpts, postsOpts } from './__fixture__/page-map'
44

55
describe('parent', () => {
66
it('string', () => {

‎packages/nextra/__test__/normalize-page.spec.ts

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { normalizePages } from '../src/client/normalize-pages.js'
2-
import { cnPageMap, usPageMap } from './fixture/page-maps/pageMap.js'
2+
import { cnPageMap, usPageMap } from './fixture/page-maps/page-map.js'
33

44
describe('normalize-page', () => {
55
it('zh-CN home', () => {

‎packages/nextra/src/client/components/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ export { Th } from './th.js'
1414
export { Tr } from './tr.js'
1515
export { Mermaid } from '@theguild/remark-mermaid/mermaid'
1616
export { MathJax, MathJaxContext } from 'better-react-mathjax'
17+
export { Playground } from './playground.js'

‎packages/nextra/src/client/components/playground.tsx

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { useEffect, useState } from 'react'
2+
import type { ReactElement } from 'react'
3+
import { CrossCircledIcon } from '../icons/index.js'
4+
import type { MDXComponents } from '../mdx.js'
5+
import { Code } from './code.js'
6+
import { Pre } from './pre.js'
7+
import { evaluate } from './remote-content.js'
8+
9+
export function Playground({
10+
source,
11+
scope,
12+
components,
13+
fallback = null
14+
}: {
15+
/**
16+
* String with source MDX
17+
*
18+
* @example '# hello world <br /> nice to see you'
19+
*/
20+
source: string
21+
/**
22+
* An object mapping names to React components.
23+
* The key used will be the name accessible to MDX.
24+
*
25+
* @example `{ ComponentName: Component }` will be accessible in the MDX as `<ComponentName/>`.
26+
*/
27+
components?: MDXComponents
28+
/**
29+
* Pass-through variables for use in the MDX content
30+
*/
31+
scope?: Record<string, unknown>
32+
/**
33+
* Fallback component for loading
34+
*/
35+
fallback?: ReactElement | null
36+
}) {
37+
const [compiledSource, setCompiledSource] = useState('')
38+
const [error, setError] = useState<unknown>()
39+
40+
useEffect(() => {
41+
async function doCompile() {
42+
// Importing in useEffect to not increase global bundle size
43+
const { compileMdx } = await import('../../server/compile.js')
44+
try {
45+
const mdx = await compileMdx(source)
46+
setCompiledSource(mdx.result)
47+
setError(null)
48+
} catch (error) {
49+
setError(error)
50+
}
51+
}
52+
53+
doCompile()
54+
}, [source])
55+
56+
if (error) {
57+
return (
58+
<div className="[&_svg]:_text-red-500">
59+
<Pre
60+
data-filename="Could not compile code"
61+
icon={CrossCircledIcon}
62+
className="_whitespace-pre-wrap"
63+
>
64+
<Code>
65+
<span>
66+
{error instanceof Error
67+
? `${error.name}: ${error.message}`
68+
: String(error)}
69+
</span>
70+
</Code>
71+
</Pre>
72+
</div>
73+
)
74+
}
75+
76+
if (compiledSource) {
77+
const MDXContent = evaluate(compiledSource, scope).default
78+
return <MDXContent components={components} />
79+
}
80+
81+
return fallback
82+
}

‎packages/nextra/src/client/components/remote-content.tsx

+2-2
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ export function RemoteContent({
3030
* An object mapping names to React components.
3131
* The key used will be the name accessible to MDX.
3232
*
33-
* For example: `{ ComponentName: Component }` will be accessible in the MDX as `<ComponentName/>`.
33+
* @example `{ ComponentName: Component }` will be accessible in the MDX as `<ComponentName/>`.
3434
*/
3535
components?: MDXComponents
3636
/**
@@ -45,7 +45,7 @@ export function RemoteContent({
4545
)
4646
}
4747

48-
const { default: MDXContent } = evaluate(compiledSource, scope)
48+
const MDXContent = evaluate(compiledSource, scope).default
4949

5050
return <MDXContent components={components} />
5151
}

‎packages/nextra/src/client/icons/cross-circled.svg

+5
Loading

‎packages/nextra/src/client/icons/index.ts

+1
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,4 @@ export { ReactComponent as PythonIcon } from './python.svg'
2525
export { ReactComponent as RustIcon } from './rust.svg'
2626
export { ReactComponent as TerraformIcon } from './terraform.svg'
2727
export { ReactComponent as MoveIcon } from './move.svg'
28+
export { ReactComponent as CrossCircledIcon } from './cross-circled.svg'

‎packages/nextra/src/env.d.ts

+2-4
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,6 @@ declare module 'next/dist/compiled/webpack/webpack.js' {
1717
}
1818

1919
declare module '*.svg' {
20-
import type { ComponentPropsWithRef, ReactElement } from 'react'
21-
export const ReactComponent: (
22-
_props: ComponentPropsWithRef<'svg'>
23-
) => ReactElement
20+
import type { FC, SVGProps } from 'react'
21+
export const ReactComponent: FC<SVGProps<SVGSVGElement>>
2422
}

‎packages/nextra/src/icon.d.ts

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import type { ComponentProps, ReactElement } from 'react'
1+
import type { FC, SVGProps } from 'react'
22

3-
declare const ReactComponent: (props: ComponentProps<'svg'>) => ReactElement
3+
declare const ReactComponent: FC<SVGProps<SVGElement>>
44

55
export { ReactComponent }

‎packages/nextra/tsconfig.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"compilerOptions": {
3-
"target": "es2016",
3+
"target": "es2018",
44
"module": "ESNext",
55
"declaration": true,
66
"noEmit": true,

‎packages/nextra/tsup.config.ts

+15-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,21 @@ export default defineConfig([
3030
const jsxRuntimeTo = path.join(CWD, 'dist', 'client', 'jsx-runtime.cjs')
3131

3232
await fs.copyFile(jsxRuntimeFrom, jsxRuntimeTo)
33-
}
33+
},
34+
plugins: [
35+
{
36+
// Strip `node:` prefix from imports because
37+
// Next.js only polyfills `path` and not `node:path` for browser
38+
name: 'strip-node-colon',
39+
renderChunk(code) {
40+
const replaced = code.replaceAll(
41+
/ from "node:(?<moduleName>.*?)";/g,
42+
matched => matched.replace('node:', '')
43+
)
44+
return { code: replaced }
45+
}
46+
}
47+
]
3448
},
3549
{
3650
name: 'nextra/icons',

‎patches/tsup@8.0.1.patch ‎patches/tsup.patch

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
diff --git a/dist/rollup.js b/dist/rollup.js
2-
index daba939dbbfab21c360e4021e5723abf8fe997ea..9d9be8a782a6fed1f3ce891c19a40c7543dc1910 100644
2+
index 8c514b6e014a4cda52f4b2538659418861049229..dddccb73c38a2a44b68d18097f6437e433152e6e 100644
33
--- a/dist/rollup.js
44
+++ b/dist/rollup.js
5-
@@ -8160,6 +8160,10 @@ var getRollupConfig = async (options) => {
5+
@@ -8392,6 +8392,10 @@ var getRollupConfig = async (options) => {
66
tsResolveOptions && tsResolvePlugin(tsResolveOptions),
77
json(),
88
ignoreFiles,

‎pnpm-lock.yaml

+43-238
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)
Please sign in to comment.