@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 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
+ ```
@@ -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
+ }