@lekoarts/satteri-sandpack 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +22 -0
- package/README.md +161 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +74 -0
- package/package.json +75 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LekoArts
|
|
4
|
+
Copyright (c) 2022 thecuvii
|
|
5
|
+
|
|
6
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
7
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
8
|
+
in the Software without restriction, including without limitation the rights
|
|
9
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
10
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
11
|
+
furnished to do so, subject to the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be included in all
|
|
14
|
+
copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
17
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
19
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
20
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
21
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
22
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# sätteri-sandpack
|
|
2
|
+
|
|
3
|
+
Author [Sandpack](https://sandpack.codesandbox.io/docs) files as fenced code blocks in MDX compiled by [Sätteri](https://github.com/bruits/satteri).
|
|
4
|
+
|
|
5
|
+
`@lekoarts/satteri-sandpack` is a native, synchronous Sätteri MDAST plugin. It's a port of my [remark-sandpack](https://github.com/LekoArts/remark-sandpack) package.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
This package is ESM only and requires Node.js 22 or newer. It supports Sätteri `>=0.10.5`.
|
|
10
|
+
|
|
11
|
+
```shell
|
|
12
|
+
npm install @lekoarts/satteri-sandpack satteri
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Install and render a Sandpack component separately, such as `@codesandbox/sandpack-react`. This plugin only creates the component's `files` prop during MDX compilation.
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
Given this MDX:
|
|
20
|
+
|
|
21
|
+
````mdx
|
|
22
|
+
<Sandpack template="react">
|
|
23
|
+
|
|
24
|
+
```js name=App.js active
|
|
25
|
+
import { NAME } from './constants.js'
|
|
26
|
+
|
|
27
|
+
export default function App() {
|
|
28
|
+
return <h1>Hello {NAME}</h1>
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```js name=constants.js readOnly
|
|
33
|
+
export const NAME = 'World'
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
</Sandpack>
|
|
37
|
+
````
|
|
38
|
+
|
|
39
|
+
The plugin appends a `files` expression equivalent to:
|
|
40
|
+
|
|
41
|
+
```jsx
|
|
42
|
+
<Sandpack
|
|
43
|
+
template="react"
|
|
44
|
+
files={{
|
|
45
|
+
'App.js': {
|
|
46
|
+
code: 'import { NAME } from \'./constants.js\'\n\nexport default function App() {\n return <h1>Hello {NAME}</h1>\n}',
|
|
47
|
+
active: true,
|
|
48
|
+
},
|
|
49
|
+
'constants.js': {
|
|
50
|
+
code: 'export const NAME = \'World\'',
|
|
51
|
+
readOnly: true,
|
|
52
|
+
},
|
|
53
|
+
}}
|
|
54
|
+
>
|
|
55
|
+
{/* Existing MDX children remain here. */}
|
|
56
|
+
</Sandpack>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Existing attributes and children are preserved. If the component already has a `files` attribute, the generated attribute is appended after it. If multiple blocks use the same filename, the final block wins.
|
|
60
|
+
|
|
61
|
+
### Direct `mdxToJs` integration
|
|
62
|
+
|
|
63
|
+
```js
|
|
64
|
+
import satteriSandpack from '@lekoarts/satteri-sandpack'
|
|
65
|
+
import { mdxToJs } from 'satteri'
|
|
66
|
+
|
|
67
|
+
const result = mdxToJs(source, {
|
|
68
|
+
mdastPlugins: [satteriSandpack()],
|
|
69
|
+
})
|
|
70
|
+
|
|
71
|
+
console.log(result.code)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The plugin is synchronous, so adding it does not make `mdxToJs` return a Promise.
|
|
75
|
+
|
|
76
|
+
### Vite integration
|
|
77
|
+
|
|
78
|
+
Use the plugin through `vite-plugin-satteri`:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import satteriSandpack from '@lekoarts/satteri-sandpack'
|
|
82
|
+
import react from '@vitejs/plugin-react'
|
|
83
|
+
import { defineConfig } from 'vite'
|
|
84
|
+
import satteri from 'vite-plugin-satteri'
|
|
85
|
+
|
|
86
|
+
export default defineConfig({
|
|
87
|
+
plugins: [
|
|
88
|
+
react(),
|
|
89
|
+
satteri({
|
|
90
|
+
mdastPlugins: [satteriSandpack({ componentName: ['Playground'] })],
|
|
91
|
+
}),
|
|
92
|
+
],
|
|
93
|
+
})
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
A complete Vite + React application is available in [`examples/vite-react`](./examples/vite-react/).
|
|
97
|
+
|
|
98
|
+
## Code-block metadata
|
|
99
|
+
|
|
100
|
+
Every fenced code block inside a matching component requires non-empty metadata containing `name=...`:
|
|
101
|
+
|
|
102
|
+
````md
|
|
103
|
+
```js name=filename.js active
|
|
104
|
+
console.log('Hello World')
|
|
105
|
+
```
|
|
106
|
+
````
|
|
107
|
+
|
|
108
|
+
The filename may be followed by any of these boolean Sandpack file flags:
|
|
109
|
+
|
|
110
|
+
- `active`: forwards `active: true`
|
|
111
|
+
- `hidden`: forwards `hidden: true`
|
|
112
|
+
- `readOnly`: forwards `readOnly: true`
|
|
113
|
+
- `showReadOnly`: forwards `showReadOnly: true`, commonly alongside `readOnly`
|
|
114
|
+
|
|
115
|
+
Flags may appear in any order and are included only when present. Code blocks nested more deeply inside the matching MDX flow component are collected recursively.
|
|
116
|
+
|
|
117
|
+
Invalid metadata throws during compilation:
|
|
118
|
+
|
|
119
|
+
- missing metadata: code blocks cannot have empty metadata
|
|
120
|
+
- missing or empty `name=...`: code blocks must have a `name` attribute
|
|
121
|
+
- unknown tokens: only `active`, `hidden`, `readOnly`, and `showReadOnly` are accepted after the filename
|
|
122
|
+
|
|
123
|
+
## Configuration
|
|
124
|
+
|
|
125
|
+
The default component name is `Sandpack`:
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
satteriSandpack()
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Use `componentName` for a custom component:
|
|
132
|
+
|
|
133
|
+
```js
|
|
134
|
+
satteriSandpack({ componentName: ['Playground'] })
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Pass multiple names when the same document uses more than one wrapper:
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
satteriSandpack({
|
|
141
|
+
componentName: ['Playground', 'MinimalPlayground'],
|
|
142
|
+
})
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Only matching MDX flow elements are transformed. Nameless and unmatched elements are left unchanged.
|
|
146
|
+
|
|
147
|
+
## API
|
|
148
|
+
|
|
149
|
+
The package has one runtime export: the default `satteriSandpack` factory. It also exports its configuration type as `Options`.
|
|
150
|
+
|
|
151
|
+
### `satteriSandpack(options?)`
|
|
152
|
+
|
|
153
|
+
Returns a named Sätteri `MdastPluginDefinition`.
|
|
154
|
+
|
|
155
|
+
### `Options`
|
|
156
|
+
|
|
157
|
+
```ts
|
|
158
|
+
interface Options {
|
|
159
|
+
componentName?: Array<string>
|
|
160
|
+
}
|
|
161
|
+
```
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import "satteri";
|
|
2
|
+
//#region src/types.d.ts
|
|
3
|
+
interface SatteriSandpackOptions {
|
|
4
|
+
/**
|
|
5
|
+
* Specify one or more component names to transform.
|
|
6
|
+
* These components will receive a `files` prop with the parsed code blocks.
|
|
7
|
+
* @default 'Sandpack'
|
|
8
|
+
*/
|
|
9
|
+
componentName?: Array<string>;
|
|
10
|
+
}
|
|
11
|
+
//#endregion
|
|
12
|
+
//#region src/transform.d.ts
|
|
13
|
+
export default function satteriSandpack(options?: Readonly<SatteriSandpackOptions>): {
|
|
14
|
+
name: string;
|
|
15
|
+
mdxJsxFlowElement(node: Readonly<import("satteri").MdxJsxFlowElement>): import("satteri").MdxJsxFlowElement | null;
|
|
16
|
+
};
|
|
17
|
+
//#endregion
|
|
18
|
+
export type { SatteriSandpackOptions as Options };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { defineMdastPlugin } from "satteri";
|
|
2
|
+
//#region src/utils.ts
|
|
3
|
+
const CODE_META_OPTIONS = [
|
|
4
|
+
"active",
|
|
5
|
+
"hidden",
|
|
6
|
+
"readOnly",
|
|
7
|
+
"showReadOnly"
|
|
8
|
+
];
|
|
9
|
+
function isCodeMetaOption(key) {
|
|
10
|
+
return CODE_META_OPTIONS.includes(key);
|
|
11
|
+
}
|
|
12
|
+
const ERRORS = {
|
|
13
|
+
EMPTY_META: "Code blocks inside <Sandpack> components cannot have empty metadata. Be sure to provide a file name.",
|
|
14
|
+
INVALID_META: (attr) => `Invalid meta attribute "${attr}" found in a code block inside <Sandpack> component. Be sure to use one of these valid attributes: ${CODE_META_OPTIONS.join(", ")}.`,
|
|
15
|
+
MISSING_NAME: "Code blocks inside <Sandpack> components must have a \"name\" attribute in their metadata."
|
|
16
|
+
};
|
|
17
|
+
//#endregion
|
|
18
|
+
//#region src/node.ts
|
|
19
|
+
function resolveCodeMeta(codeNode) {
|
|
20
|
+
if (!codeNode.meta?.trim()) throw new Error(ERRORS.EMPTY_META);
|
|
21
|
+
const meta = {};
|
|
22
|
+
for (const attr of codeNode.meta.trim().split(/\s+/)) if (attr.startsWith("name=")) meta.name = attr.slice(5);
|
|
23
|
+
else if (isCodeMetaOption(attr)) meta[attr] = true;
|
|
24
|
+
else throw new Error(ERRORS.INVALID_META(attr));
|
|
25
|
+
if (!meta.name) throw new Error(ERRORS.MISSING_NAME);
|
|
26
|
+
return meta;
|
|
27
|
+
}
|
|
28
|
+
function collectSandpackFiles(node) {
|
|
29
|
+
const files = {};
|
|
30
|
+
for (const child of node.children) collectCodeFiles(child, files);
|
|
31
|
+
return files;
|
|
32
|
+
}
|
|
33
|
+
function transformSandpackNode(node) {
|
|
34
|
+
const files = collectSandpackFiles(node);
|
|
35
|
+
const filesAttribute = {
|
|
36
|
+
type: "mdxJsxAttribute",
|
|
37
|
+
name: "files",
|
|
38
|
+
value: {
|
|
39
|
+
type: "mdxJsxAttributeValueExpression",
|
|
40
|
+
value: JSON.stringify(files)
|
|
41
|
+
}
|
|
42
|
+
};
|
|
43
|
+
return {
|
|
44
|
+
...node,
|
|
45
|
+
attributes: [...node.attributes, filesAttribute]
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
function collectCodeFiles(node, files) {
|
|
49
|
+
if (node.type === "code") {
|
|
50
|
+
const meta = resolveCodeMeta(node);
|
|
51
|
+
files[meta.name] = {
|
|
52
|
+
code: node.value,
|
|
53
|
+
...meta.active && { active: true },
|
|
54
|
+
...meta.hidden && { hidden: true },
|
|
55
|
+
...meta.readOnly && { readOnly: true },
|
|
56
|
+
...meta.showReadOnly && { showReadOnly: true }
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
if ("children" in node) for (const child of node.children) collectCodeFiles(child, files);
|
|
60
|
+
}
|
|
61
|
+
//#endregion
|
|
62
|
+
//#region src/transform.ts
|
|
63
|
+
function satteriSandpack(options) {
|
|
64
|
+
const componentName = options?.componentName ?? ["Sandpack"];
|
|
65
|
+
return defineMdastPlugin({
|
|
66
|
+
name: "satteri-sandpack",
|
|
67
|
+
mdxJsxFlowElement(node) {
|
|
68
|
+
if (!node.name || !componentName.includes(node.name)) return null;
|
|
69
|
+
return transformSandpackNode(node);
|
|
70
|
+
}
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
//#endregion
|
|
74
|
+
export { satteriSandpack as default };
|
package/package.json
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@lekoarts/satteri-sandpack",
|
|
3
|
+
"type": "module",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"packageManager": "pnpm@11.5.0",
|
|
6
|
+
"description": "Author Sandpack examples in MDX with Sätteri",
|
|
7
|
+
"author": "LekoArts",
|
|
8
|
+
"license": "MIT",
|
|
9
|
+
"homepage": "https://github.com/LekoArts/satteri-sandpack#readme",
|
|
10
|
+
"repository": {
|
|
11
|
+
"type": "git",
|
|
12
|
+
"url": "git+https://github.com/LekoArts/satteri-sandpack.git"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/LekoArts/satteri-sandpack/issues"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"satteri",
|
|
19
|
+
"sandpack",
|
|
20
|
+
"MDX"
|
|
21
|
+
],
|
|
22
|
+
"publishConfig": {
|
|
23
|
+
"access": "public"
|
|
24
|
+
},
|
|
25
|
+
"sideEffects": false,
|
|
26
|
+
"exports": {
|
|
27
|
+
".": {
|
|
28
|
+
"types": "./dist/index.d.ts",
|
|
29
|
+
"import": "./dist/index.js",
|
|
30
|
+
"default": "./dist/index.js"
|
|
31
|
+
},
|
|
32
|
+
"./package.json": "./package.json"
|
|
33
|
+
},
|
|
34
|
+
"main": "./dist/index.js",
|
|
35
|
+
"module": "./dist/index.js",
|
|
36
|
+
"types": "./dist/index.d.ts",
|
|
37
|
+
"files": [
|
|
38
|
+
"dist"
|
|
39
|
+
],
|
|
40
|
+
"engines": {
|
|
41
|
+
"node": ">=22"
|
|
42
|
+
},
|
|
43
|
+
"scripts": {
|
|
44
|
+
"lint": "eslint",
|
|
45
|
+
"lint:fix": "eslint --fix",
|
|
46
|
+
"build": "tsdown",
|
|
47
|
+
"dev": "tsdown --watch",
|
|
48
|
+
"test": "vitest run",
|
|
49
|
+
"test:watch": "vitest watch",
|
|
50
|
+
"typecheck": "tsc --noEmit",
|
|
51
|
+
"changeset": "changeset",
|
|
52
|
+
"version": "changeset version",
|
|
53
|
+
"version:ci": "changeset version && pnpm install --lockfile-only",
|
|
54
|
+
"release": "pnpm build && changeset publish",
|
|
55
|
+
"check": "publint && attw --pack . --profile esm-only"
|
|
56
|
+
},
|
|
57
|
+
"peerDependencies": {
|
|
58
|
+
"satteri": "^0.10.5"
|
|
59
|
+
},
|
|
60
|
+
"devDependencies": {
|
|
61
|
+
"@antfu/eslint-config": "^9.0.0",
|
|
62
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
63
|
+
"@changesets/changelog-github": "^1.0.1",
|
|
64
|
+
"@changesets/cli": "^3.0.2",
|
|
65
|
+
"@types/node": "^24.13.3",
|
|
66
|
+
"eslint": "^10.10.0",
|
|
67
|
+
"eslint-plugin-format": "^2.0.1",
|
|
68
|
+
"playwright": "^1.63.0",
|
|
69
|
+
"publint": "^0.3.24",
|
|
70
|
+
"satteri": "^0.10.5",
|
|
71
|
+
"tsdown": "^0.23.0",
|
|
72
|
+
"typescript": "^6.0.3",
|
|
73
|
+
"vitest": "^5.0.0"
|
|
74
|
+
}
|
|
75
|
+
}
|