@octanejs/mdx 0.1.63 → 0.1.65
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/README.md +52 -12
- package/package.json +13 -7
- package/src/compile.js +216 -120
- package/src/{index.ts → index.tsrx} +6 -7
- package/src/index.tsrx.d.ts +25 -0
- package/src/{server.ts → server.tsrx} +11 -12
- package/src/server.tsrx.d.ts +1 -0
- package/types/compile.d.ts +15 -2
- package/src/env.d.ts +0 -16
package/README.md
CHANGED
|
@@ -13,8 +13,8 @@ pnpm add @octanejs/mdx
|
|
|
13
13
|
|
|
14
14
|
The split mirrors `docs/react-library-compat-plan.md` §2: **@mdx-js/mdx's
|
|
15
15
|
compiler is framework-agnostic and reused verbatim** — with `jsx: true` it
|
|
16
|
-
emits
|
|
17
|
-
|
|
16
|
+
emits JSX *source*. A small printer adapter turns the two generated document
|
|
17
|
+
functions into Octane templates before the Octane compiler runs. The pipeline is
|
|
18
18
|
|
|
19
19
|
```
|
|
20
20
|
.mdx / .md → @mdx-js/mdx (JSX/ESM source) → octane/compiler → compiled octane module
|
|
@@ -51,7 +51,8 @@ hazards. SSR target selection matches the octane plugin: per-module
|
|
|
51
51
|
auto-detection, `ssr: true|false` to force.
|
|
52
52
|
|
|
53
53
|
Options: `md: false` (leave `.md` alone), `providerImportSource: null` (disable
|
|
54
|
-
the provider wiring), `
|
|
54
|
+
the provider wiring), `strong` (apply Octane Strong checks to the document),
|
|
55
|
+
`overridableTags`, `remarkPlugins` / `rehypePlugins` / `recmaPlugins`,
|
|
55
56
|
`format`, `mdxOptions` (escape hatch). The default remark set is
|
|
56
57
|
`defaultRemarkPlugins` = GFM + frontmatter + `export const frontmatter`.
|
|
57
58
|
|
|
@@ -84,6 +85,41 @@ A mapping can also be passed per-document: `<Doc components={{ h1: FancyHeading
|
|
|
84
85
|
Mapping values are octane components or replacement host tag names (`{ em: 'i' }`);
|
|
85
86
|
the special `wrapper` key is the document layout.
|
|
86
87
|
|
|
88
|
+
The client and server providers are authored as Strong `.tsrx` templates. Both
|
|
89
|
+
generated document functions also compile as templates. Authored JavaScript
|
|
90
|
+
expressions and exported components retain their normal Octane semantics.
|
|
91
|
+
|
|
92
|
+
### Static hosts and Strong mode
|
|
93
|
+
|
|
94
|
+
By default, every markdown-generated tag can be overridden through a provider
|
|
95
|
+
or the document's `components` prop. For a site with a fixed set of overrides,
|
|
96
|
+
list those tags at build time:
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
octaneMdx({
|
|
100
|
+
strong: true,
|
|
101
|
+
overridableTags: ['table', 'pre'],
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
All other generated tags become static host templates, including Shiki's many
|
|
106
|
+
highlighting spans. Overrides for omitted tags are ignored in both provider
|
|
107
|
+
and document mappings. An empty list makes every generated host static;
|
|
108
|
+
omitting the option retains full MDX override support. This does not restrict
|
|
109
|
+
named components, authored JSX, or the special `wrapper` layout mapping.
|
|
110
|
+
Provider mappings still merge before document props, and an explicit exported
|
|
111
|
+
layout still takes precedence over `wrapper`.
|
|
112
|
+
|
|
113
|
+
Keeping every tag overridable requires a component slot for each generated
|
|
114
|
+
host. For heavily highlighted documents this can increase generated code size;
|
|
115
|
+
use a fixed override list when the application only replaces a few tags.
|
|
116
|
+
|
|
117
|
+
Pass the application's shared Strong setting to `octaneMdx` as well as its
|
|
118
|
+
Octane plugin. Strong checks apply to the whole MDX module, including authored
|
|
119
|
+
expressions; enabling them can reject code accepted in compatibility mode.
|
|
120
|
+
The default remains compatibility mode. Use the same options for client and
|
|
121
|
+
server compilation so their hydration structure agrees.
|
|
122
|
+
|
|
87
123
|
## API (vs @mdx-js/react)
|
|
88
124
|
|
|
89
125
|
- `MDXProvider({ components, disableParentContext, children })` — ported;
|
|
@@ -102,9 +138,9 @@ the special `wrapper` key is the document layout.
|
|
|
102
138
|
## SSR + hydration
|
|
103
139
|
|
|
104
140
|
A document compiled with `mode: 'server'` renders through `octane/server`'s
|
|
105
|
-
`renderToString`, and the resulting
|
|
106
|
-
client-compiled module
|
|
107
|
-
|
|
141
|
+
`renderToString`, and `hydrateRoot` adopts the resulting elements and text
|
|
142
|
+
into the client-compiled module. Embedded `.tsrx` components retain their
|
|
143
|
+
server DOM and stay interactive; internal comment anchors may change.
|
|
108
144
|
|
|
109
145
|
Both mapping routes work on the server:
|
|
110
146
|
|
|
@@ -114,7 +150,7 @@ Both mapping routes work on the server:
|
|
|
114
150
|
disjoint context stores, so each side ships its own provider; server-mode
|
|
115
151
|
documents read `useMDXComponents` from `@octanejs/mdx/server`
|
|
116
152
|
automatically). A document rendered under the server provider hydrates
|
|
117
|
-
|
|
153
|
+
by adopting its DOM into the client `MDXProvider` with the same mapping.
|
|
118
154
|
|
|
119
155
|
## Syntax highlighting (Shiki)
|
|
120
156
|
|
|
@@ -137,11 +173,15 @@ async — it works in the vite plugin and `compileMdx`, not `compileMdxSync`.
|
|
|
137
173
|
|
|
138
174
|
## Notes
|
|
139
175
|
|
|
140
|
-
- Markdown-generated
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
176
|
+
- Markdown-generated document functions use templates. Dynamic host overrides
|
|
177
|
+
still need runtime component slots; `overridableTags` lets fixed sites avoid
|
|
178
|
+
those slots for hosts they never override. This does not promise that arbitrary
|
|
179
|
+
authored expressions or imported components are descriptor-free.
|
|
180
|
+
- Mapped components receive ordinary Octane template children: render them
|
|
181
|
+
with `{children}` rather than inspecting or cloning nested element
|
|
182
|
+
descriptors. A single literal text child remains a string.
|
|
183
|
+
- `.mdx` edits fast-refresh in dev through Octane's template HMR support,
|
|
184
|
+
so live mounts re-render
|
|
145
185
|
the new body in place (no page reload; the vite plugin enables this in serve
|
|
146
186
|
mode automatically). Importers keep the named exports they read, such as
|
|
147
187
|
`frontmatter`, so the update also reaches them when one is no longer
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@octanejs/mdx",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.65",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -26,17 +26,23 @@
|
|
|
26
26
|
"url": "git+https://github.com/octanejs/octane.git",
|
|
27
27
|
"directory": "packages/mdx"
|
|
28
28
|
},
|
|
29
|
-
"main": "src/index.
|
|
30
|
-
"module": "src/index.
|
|
31
|
-
"types": "src/index.ts",
|
|
29
|
+
"main": "src/index.tsrx",
|
|
30
|
+
"module": "src/index.tsrx",
|
|
31
|
+
"types": "src/index.tsrx.d.ts",
|
|
32
32
|
"files": [
|
|
33
33
|
"src",
|
|
34
34
|
"types",
|
|
35
35
|
"README.md"
|
|
36
36
|
],
|
|
37
37
|
"exports": {
|
|
38
|
-
".":
|
|
39
|
-
|
|
38
|
+
".": {
|
|
39
|
+
"types": "./src/index.tsrx.d.ts",
|
|
40
|
+
"default": "./src/index.tsrx"
|
|
41
|
+
},
|
|
42
|
+
"./server": {
|
|
43
|
+
"types": "./src/server.tsrx.d.ts",
|
|
44
|
+
"default": "./src/server.tsrx"
|
|
45
|
+
},
|
|
40
46
|
"./compile": {
|
|
41
47
|
"types": "./types/compile.d.ts",
|
|
42
48
|
"default": "./src/compile.js"
|
|
@@ -61,7 +67,7 @@
|
|
|
61
67
|
"devDependencies": {
|
|
62
68
|
"@octanejs/testing-library": "0.1.63",
|
|
63
69
|
"@shikijs/rehype": "^3.23.0",
|
|
64
|
-
"octane": "0.13.
|
|
70
|
+
"octane": "0.13.7",
|
|
65
71
|
"vite": "^8.1.5",
|
|
66
72
|
"vitest": "^4.1.10"
|
|
67
73
|
},
|
package/src/compile.js
CHANGED
|
@@ -16,23 +16,12 @@
|
|
|
16
16
|
* code to this package's `useMDXComponents` (the octane port of
|
|
17
17
|
* @mdx-js/react's provider).
|
|
18
18
|
*
|
|
19
|
-
* The
|
|
20
|
-
*
|
|
21
|
-
* `
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
* component machinery on client AND server. (The layout branch's
|
|
26
|
-
* `<_createMdxContent {...props}/>` tag needs no help: octane classifies
|
|
27
|
-
* `_`-starting identifier tags as component references, per JSX semantics.)
|
|
28
|
-
*
|
|
29
|
-
* The two former SERVER-mode fixups are gone — their octane gaps are fixed:
|
|
30
|
-
* `ssrComponent` renders a host-tag-STRING comp as a
|
|
31
|
-
* `<!--[--><tag>…</tag><!--]-->` block (the shape the client's componentSlot /
|
|
32
|
-
* de-opt host renderer adopts on hydration), and the server compiler
|
|
33
|
-
* value-lowers a returned fragment through `ssrChild([...])` exactly like the
|
|
34
|
-
* client's descriptor array — so `<_components.h1>` member tags and the
|
|
35
|
-
* document's fragment body take the SAME shape on both sides (hydration-safe).
|
|
19
|
+
* The final recma pass emits both generated document functions as TSRX
|
|
20
|
+
* templates. MDX's existing printer handles their JSX, JavaScript and source
|
|
21
|
+
* locations; a small body handler supplies `@{}` and template control flow.
|
|
22
|
+
* Both layout branches render the document body through a component boundary.
|
|
23
|
+
* Optional `overridableTags` specializes generated hosts without changing
|
|
24
|
+
* authored JSX, named components, or the provider/prop/layout merge rules.
|
|
36
25
|
*
|
|
37
26
|
* Authored in `.js` (like octane's `compiler/vite.js` and @octanejs/stylex's
|
|
38
27
|
* vite entry) so the `…/vite` plugin — which imports this module — loads when a
|
|
@@ -94,6 +83,8 @@ import { SourceMapGenerator } from 'source-map';
|
|
|
94
83
|
* @property {boolean} [hmr] octane compiler HMR wrapping (client only; the vite plugin wires this to serve mode).
|
|
95
84
|
* @property {boolean} [dev] octane compiler dev metadata (client only; same gate as `hmr`).
|
|
96
85
|
* @property {boolean} [profile] octane compiler profiling metadata (client only).
|
|
86
|
+
* @property {boolean} [strong] Apply Octane Strong diagnostics to the document.
|
|
87
|
+
* @property {readonly string[]} [overridableTags] Generated host tags that may be replaced through component mappings. Omit to keep every generated host overridable; an empty list makes all generated hosts native. Named components and layouts remain overridable.
|
|
97
88
|
* @property {string | null} [providerImportSource]
|
|
98
89
|
* Module the emitted document reads the provider mapping from
|
|
99
90
|
* (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
|
|
@@ -195,7 +186,7 @@ function buildMdxOptions(id, options, diagnosticContext) {
|
|
|
195
186
|
seedAuthoredJsxAttributeLocations(diagnosticContext),
|
|
196
187
|
...(options.recmaPlugins ?? []),
|
|
197
188
|
restoreAuthoredJsxAttributeLocations(diagnosticContext),
|
|
198
|
-
recmaOctaneAdapter,
|
|
189
|
+
[recmaOctaneAdapter, { overridableTags: options.overridableTags }],
|
|
199
190
|
],
|
|
200
191
|
};
|
|
201
192
|
}
|
|
@@ -367,12 +358,53 @@ function octaneStage(mdxFile, authoredSource, id, options, diagnosticContext) {
|
|
|
367
358
|
const jsxSource = String(mdxFile.value);
|
|
368
359
|
const mdxMap = mdxFile.map;
|
|
369
360
|
const mode = options.mode ?? 'client';
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
361
|
+
let out;
|
|
362
|
+
try {
|
|
363
|
+
out = octaneCompile(jsxSource, id, {
|
|
364
|
+
mode,
|
|
365
|
+
hmr: mode === 'client' && !!options.hmr,
|
|
366
|
+
dev: mode === 'client' && !!options.dev,
|
|
367
|
+
profile: mode === 'client' && !!options.profile,
|
|
368
|
+
strong: options.strong,
|
|
369
|
+
});
|
|
370
|
+
} catch (error) {
|
|
371
|
+
if (
|
|
372
|
+
mdxMap &&
|
|
373
|
+
typeof error?.loc?.line === 'number' &&
|
|
374
|
+
typeof error.loc.column === 'number' &&
|
|
375
|
+
typeof error.pos === 'number'
|
|
376
|
+
) {
|
|
377
|
+
const trace = new TraceMap(JSON.parse(JSON.stringify(mdxMap)));
|
|
378
|
+
const starts = sourceLineStarts(authoredSource);
|
|
379
|
+
const start = mapDiagnosticPosition(
|
|
380
|
+
trace,
|
|
381
|
+
authoredSource,
|
|
382
|
+
starts,
|
|
383
|
+
error.loc,
|
|
384
|
+
GREATEST_LOWER_BOUND,
|
|
385
|
+
);
|
|
386
|
+
const end =
|
|
387
|
+
typeof error.end === 'number'
|
|
388
|
+
? mapDiagnosticPosition(
|
|
389
|
+
trace,
|
|
390
|
+
authoredSource,
|
|
391
|
+
starts,
|
|
392
|
+
positionForOffset(jsxSource, sourceLineStarts(jsxSource), error.end),
|
|
393
|
+
LEAST_UPPER_BOUND,
|
|
394
|
+
)
|
|
395
|
+
: null;
|
|
396
|
+
if (start !== null) {
|
|
397
|
+
const prefix = `${id}:${error.loc.line}:${error.loc.column + 1}: `;
|
|
398
|
+
if (error.message.startsWith(prefix)) {
|
|
399
|
+
error.message = `${id}:${start.line}:${start.column + 1}: ${error.message.slice(prefix.length)}`;
|
|
400
|
+
}
|
|
401
|
+
error.loc = { line: start.line, column: start.column };
|
|
402
|
+
error.pos = start.offset;
|
|
403
|
+
error.end = Math.max(start.offset, end?.offset ?? start.offset);
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
throw error;
|
|
407
|
+
}
|
|
376
408
|
// Two-stage sourcemap: octane's map targets the INTERMEDIATE JSX text;
|
|
377
409
|
// @mdx-js/mdx's map (via SourceMapGenerator) targets the original .mdx.
|
|
378
410
|
// Compose them (most-recent-first) so generated positions trace all the way
|
|
@@ -398,51 +430,10 @@ function octaneStage(mdxFile, authoredSource, id, options, diagnosticContext) {
|
|
|
398
430
|
id,
|
|
399
431
|
diagnosticContext.authoredAttributes,
|
|
400
432
|
);
|
|
401
|
-
//
|
|
402
|
-
//
|
|
403
|
-
//
|
|
404
|
-
|
|
405
|
-
// PIPELINE knows the emitted shape, so it appends the registration the
|
|
406
|
-
// octane compiler emits for `.tsrx` exports: wrap the default export in the
|
|
407
|
-
// runtime `hmr()`, hand each evaluation's body to the wrapper that importers
|
|
408
|
-
// and live blocks already hold (kept in `hot.data`, so parents never remount
|
|
409
|
-
// the document), and self-accept. Importers keep the bindings they linked
|
|
410
|
-
// against, so the callback invalidates when another export they read
|
|
411
|
-
// changed or cannot be compared. Appending after the fact keeps the source
|
|
412
|
-
// map's earlier segments valid (ESM imports hoist).
|
|
413
|
-
if (mode === 'client' && options.hmr && /\bexport default function MDXContent\b/.test(out.code)) {
|
|
414
|
-
const namedExports = mdxFile.data.octaneNamedExports;
|
|
415
|
-
const changed =
|
|
416
|
-
namedExports === null
|
|
417
|
-
? '_$mdxModule'
|
|
418
|
-
: `_$mdxModule && (${[['default', 'MDXContent'], ...namedExports]
|
|
419
|
-
.map(([name, local]) => `_$mdxModule[${JSON.stringify(name)}] !== ${local}`)
|
|
420
|
-
.join(' || ')})`;
|
|
421
|
-
out.code +=
|
|
422
|
-
"\nimport { hmr as _$mdxHmr, HMR as _$mdxHMR } from 'octane';\n" +
|
|
423
|
-
'MDXContent = _$mdxHmr(MDXContent);\n' +
|
|
424
|
-
'if (import.meta.hot) {\n' +
|
|
425
|
-
' const _$mdxPrevious = import.meta.hot.data?.__octaneMdxContent;\n' +
|
|
426
|
-
' if (_$mdxPrevious) {\n' +
|
|
427
|
-
' if (_$mdxPrevious[_$mdxHMR].update(MDXContent)) MDXContent = _$mdxPrevious;\n' +
|
|
428
|
-
' else import.meta.hot.invalidate();\n' +
|
|
429
|
-
' }\n' +
|
|
430
|
-
' if (import.meta.hot.data) import.meta.hot.data.__octaneMdxContent = MDXContent;\n' +
|
|
431
|
-
' import.meta.hot.accept((_$mdxModule) => {\n' +
|
|
432
|
-
` if (${changed}) import.meta.hot.invalidate();\n` +
|
|
433
|
-
' });\n' +
|
|
434
|
-
'}\n';
|
|
435
|
-
}
|
|
436
|
-
// Register the final public binding after the MDX-specific HMR wrapper. The
|
|
437
|
-
// core compiler may also recognize the generated dispatcher, but its location
|
|
438
|
-
// belongs to intermediate JSX and its registration precedes this wrapper. This
|
|
439
|
-
// document-level registration deliberately overrides both with the authored
|
|
440
|
-
// `.mdx` identity and stable line-one location.
|
|
441
|
-
if (
|
|
442
|
-
mode === 'client' &&
|
|
443
|
-
options.profile &&
|
|
444
|
-
/\bexport default function MDXContent\b/.test(out.code)
|
|
445
|
-
) {
|
|
433
|
+
// Core owns template HMR, including named-export invalidation. Register the
|
|
434
|
+
// final public binding with the authored document identity instead of its
|
|
435
|
+
// generated function location. Appending preserves earlier source-map segments.
|
|
436
|
+
if (mode === 'client' && options.profile && mdxFile.data.octaneDocumentTemplate) {
|
|
446
437
|
const metadata = {
|
|
447
438
|
id: `${id}#MDXContent@1:0`,
|
|
448
439
|
name: 'MDXContent',
|
|
@@ -623,42 +614,154 @@ function remapDiagnostics(diagnostics, mdxMap, jsxSource, source, id, authoredAt
|
|
|
623
614
|
|
|
624
615
|
const MDX_BODY_NAME = '_createMdxContent';
|
|
625
616
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
617
|
+
/** @param {{ overridableTags?: readonly string[] }} options */
|
|
618
|
+
function recmaOctaneAdapter({ overridableTags }) {
|
|
619
|
+
if (
|
|
620
|
+
overridableTags !== undefined &&
|
|
621
|
+
(!Array.isArray(overridableTags) ||
|
|
622
|
+
overridableTags.some((tag) => typeof tag !== 'string' || !/^[a-z][\w:.-]*$/.test(tag)))
|
|
623
|
+
) {
|
|
624
|
+
throw new TypeError('overridableTags must be an array of host tag names.');
|
|
625
|
+
}
|
|
626
|
+
const allowed = overridableTags === undefined ? null : new Set(overridableTags);
|
|
627
|
+
// recma-stringify and recma-jsx already share this printer extension point.
|
|
628
|
+
// Keep their JSX handlers and source-map writer; only our synthetic body
|
|
629
|
+
// needs syntax that ESTree's ordinary JavaScript printer does not know.
|
|
630
|
+
const settings = this.data('settings') ?? {};
|
|
631
|
+
this.data('settings', {
|
|
632
|
+
...settings,
|
|
633
|
+
handlers: { ...settings.handlers, OctaneTemplateBody: printTemplateBody },
|
|
634
|
+
});
|
|
635
|
+
return (tree, file) => ({
|
|
636
|
+
...tree,
|
|
637
|
+
body: tree.body.map((statement) => {
|
|
638
|
+
const fn = statement.type === 'ExportDefaultDeclaration' ? statement.declaration : statement;
|
|
639
|
+
if (
|
|
640
|
+
fn.type !== 'FunctionDeclaration' ||
|
|
641
|
+
(fn.id?.name !== MDX_BODY_NAME && fn.id?.name !== 'MDXContent')
|
|
642
|
+
)
|
|
643
|
+
return statement;
|
|
644
|
+
const body = adaptGeneratedHosts(fn.body, allowed);
|
|
645
|
+
const last = body.body.at(-1);
|
|
646
|
+
if (last?.type !== 'ReturnStatement') return statement;
|
|
647
|
+
const next = {
|
|
648
|
+
...fn,
|
|
649
|
+
body: {
|
|
650
|
+
type: 'OctaneTemplateBody',
|
|
651
|
+
setup: body.body.slice(0, -1),
|
|
652
|
+
output: mapNodes(last.argument, adaptNode),
|
|
653
|
+
},
|
|
654
|
+
};
|
|
655
|
+
if (statement.type === 'ExportDefaultDeclaration') {
|
|
656
|
+
file.data.octaneDocumentTemplate = true;
|
|
657
|
+
return { ...statement, declaration: next };
|
|
658
|
+
}
|
|
659
|
+
return next;
|
|
660
|
+
}),
|
|
661
|
+
});
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
function printTemplateBody(node, state) {
|
|
665
|
+
state.write('@{\n');
|
|
666
|
+
for (const statement of node.setup) {
|
|
667
|
+
this[statement.type](statement, state);
|
|
668
|
+
state.write('\n');
|
|
669
|
+
}
|
|
670
|
+
const output = (expression) => {
|
|
671
|
+
if (expression.type === 'ConditionalExpression') {
|
|
672
|
+
state.write('<>@if (');
|
|
673
|
+
this[expression.test.type](expression.test, state);
|
|
674
|
+
state.write(') {\n');
|
|
675
|
+
output(expression.consequent);
|
|
676
|
+
state.write('\n} @else {\n');
|
|
677
|
+
output(expression.alternate);
|
|
678
|
+
state.write('\n}</>');
|
|
679
|
+
} else if (expression.type === 'JSXElement' || expression.type === 'JSXFragment') {
|
|
680
|
+
this[expression.type](expression, state);
|
|
681
|
+
} else {
|
|
682
|
+
state.write('<>{');
|
|
683
|
+
this[expression.type](expression, state);
|
|
684
|
+
state.write('}</>');
|
|
685
|
+
}
|
|
634
686
|
};
|
|
687
|
+
output(node.output);
|
|
688
|
+
state.write('\n}');
|
|
635
689
|
}
|
|
636
690
|
|
|
637
691
|
/**
|
|
638
|
-
*
|
|
639
|
-
*
|
|
640
|
-
*
|
|
641
|
-
*
|
|
642
|
-
* @param {{ body: any[] }} program
|
|
643
|
-
* @returns {Array<[string, string]> | null}
|
|
692
|
+
* Only MDX-generated host references have defaults in this local map. Explicit
|
|
693
|
+
* JSX is deliberately outside the mapping contract, even when its spelling
|
|
694
|
+
* happens to match a generated reference. Non-identifier tags use MDX aliases.
|
|
644
695
|
*/
|
|
645
|
-
function
|
|
646
|
-
|
|
647
|
-
const
|
|
648
|
-
for (const
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
696
|
+
function adaptGeneratedHosts(body, allowed) {
|
|
697
|
+
const tags = new Set();
|
|
698
|
+
const aliases = new Map();
|
|
699
|
+
for (const statement of body.body) {
|
|
700
|
+
for (const declaration of statement.declarations ?? []) {
|
|
701
|
+
if (declaration.id.name === '_components' && declaration.init?.type === 'ObjectExpression') {
|
|
702
|
+
for (const property of declaration.init.properties) {
|
|
703
|
+
const name = property.key?.name ?? property.key?.value;
|
|
704
|
+
if (property.type === 'Property' && property.value?.value === name) tags.add(name);
|
|
705
|
+
}
|
|
706
|
+
}
|
|
707
|
+
if (
|
|
708
|
+
declaration.init?.type === 'MemberExpression' &&
|
|
709
|
+
declaration.init.object.name === '_components'
|
|
710
|
+
) {
|
|
711
|
+
aliases.set(
|
|
712
|
+
declaration.id.name,
|
|
713
|
+
declaration.init.property.name ?? declaration.init.property.value,
|
|
714
|
+
);
|
|
715
|
+
}
|
|
659
716
|
}
|
|
660
717
|
}
|
|
661
|
-
return
|
|
718
|
+
if (tags.size === 0) return body;
|
|
719
|
+
return mapNodes(body, (node) => {
|
|
720
|
+
if (node.type !== 'JSXElement' || node.data?._mdxExplicitJsx) return null;
|
|
721
|
+
const name = node.openingElement.name;
|
|
722
|
+
const tag =
|
|
723
|
+
name.type === 'JSXMemberExpression' && name.object.name === '_components'
|
|
724
|
+
? name.property.name
|
|
725
|
+
: name.type === 'JSXIdentifier'
|
|
726
|
+
? aliases.get(name.name)
|
|
727
|
+
: undefined;
|
|
728
|
+
if (!tags.has(tag)) return null;
|
|
729
|
+
if (allowed !== null && !allowed.has(tag)) {
|
|
730
|
+
const nativeName = { ...name, type: 'JSXIdentifier', name: tag };
|
|
731
|
+
return {
|
|
732
|
+
...node,
|
|
733
|
+
openingElement: { ...node.openingElement, name: nativeName },
|
|
734
|
+
closingElement: node.closingElement ? { ...node.closingElement, name: nativeName } : null,
|
|
735
|
+
};
|
|
736
|
+
}
|
|
737
|
+
const child = node.children.length === 1 ? node.children[0] : null;
|
|
738
|
+
if (
|
|
739
|
+
child?.type !== 'JSXExpressionContainer' ||
|
|
740
|
+
child.expression.type !== 'Literal' ||
|
|
741
|
+
typeof child.expression.value !== 'string'
|
|
742
|
+
)
|
|
743
|
+
return null;
|
|
744
|
+
// MDX's single string child is already a scalar value. Keep it a prop
|
|
745
|
+
// instead of allocating a template body for every highlighted token.
|
|
746
|
+
// Appending matches nested JSX children winning over attribute spreads.
|
|
747
|
+
return {
|
|
748
|
+
...node,
|
|
749
|
+
openingElement: {
|
|
750
|
+
...node.openingElement,
|
|
751
|
+
selfClosing: true,
|
|
752
|
+
attributes: [
|
|
753
|
+
...node.openingElement.attributes,
|
|
754
|
+
{
|
|
755
|
+
type: 'JSXAttribute',
|
|
756
|
+
name: { type: 'JSXIdentifier', name: 'children' },
|
|
757
|
+
value: child,
|
|
758
|
+
},
|
|
759
|
+
],
|
|
760
|
+
},
|
|
761
|
+
closingElement: null,
|
|
762
|
+
children: [],
|
|
763
|
+
};
|
|
764
|
+
});
|
|
662
765
|
}
|
|
663
766
|
|
|
664
767
|
/** @typedef {{ type: string, [key: string]: unknown }} EstreeNode */
|
|
@@ -694,31 +797,24 @@ function adaptNode(node) {
|
|
|
694
797
|
return null;
|
|
695
798
|
}
|
|
696
799
|
|
|
697
|
-
/**
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
* @param {(n: EstreeNode) => EstreeNode | null} visit
|
|
703
|
-
*/
|
|
704
|
-
function walkReplace(node, visit) {
|
|
705
|
-
for (const key of Object.keys(node)) {
|
|
800
|
+
/** Copy-on-write traversal; upstream and custom recma ASTs remain untouched. */
|
|
801
|
+
function mapNodes(node, visit) {
|
|
802
|
+
if (!isNode(node)) return node;
|
|
803
|
+
let result = visit(node) ?? node;
|
|
804
|
+
for (const key of Object.keys(result)) {
|
|
706
805
|
if (key === 'loc' || key === 'range' || key === 'position' || key === 'data') continue;
|
|
707
|
-
const value =
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
} else if (isNode(value)) {
|
|
717
|
-
const next = visit(value);
|
|
718
|
-
if (next !== null) node[key] = next;
|
|
719
|
-
else walkReplace(value, visit);
|
|
806
|
+
const value = result[key];
|
|
807
|
+
const next = Array.isArray(value)
|
|
808
|
+
? value.map((child) => mapNodes(child, visit))
|
|
809
|
+
: mapNodes(value, visit);
|
|
810
|
+
if (
|
|
811
|
+
Array.isArray(value) ? next.some((child, index) => child !== value[index]) : next !== value
|
|
812
|
+
) {
|
|
813
|
+
if (result === node) result = { ...node };
|
|
814
|
+
result[key] = next;
|
|
720
815
|
}
|
|
721
816
|
}
|
|
817
|
+
return result;
|
|
722
818
|
}
|
|
723
819
|
|
|
724
820
|
/**
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
'use strong';
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* @octanejs/mdx — the runtime provider layer.
|
|
3
5
|
*
|
|
@@ -27,9 +29,9 @@
|
|
|
27
29
|
* SSR provider support lives in `@octanejs/mdx/server` — the same layer
|
|
28
30
|
* mirrored onto `octane/server` context (the two runtimes' context stores are
|
|
29
31
|
* disjoint; server-mode documents import `useMDXComponents` from there). Keep
|
|
30
|
-
* the merge semantics here and in src/server.
|
|
32
|
+
* the merge semantics here and in src/server.tsrx in lockstep.
|
|
31
33
|
*/
|
|
32
|
-
import { createContext,
|
|
34
|
+
import { createContext, useContext, type ComponentBody } from 'octane';
|
|
33
35
|
|
|
34
36
|
/**
|
|
35
37
|
* A components mapping: markdown element name (`h1`, `p`, `code`, …) or
|
|
@@ -85,7 +87,7 @@ export interface MDXProviderProps {
|
|
|
85
87
|
* `MDXProvider`: nested providers MERGE by default (`components` over the
|
|
86
88
|
* inherited mapping); `disableParentContext` starts from scratch.
|
|
87
89
|
*/
|
|
88
|
-
export function MDXProvider(props: MDXProviderProps)
|
|
90
|
+
export function MDXProvider(props: MDXProviderProps) @{
|
|
89
91
|
let allComponents: MDXComponents;
|
|
90
92
|
if (props.disableParentContext) {
|
|
91
93
|
allComponents =
|
|
@@ -95,10 +97,7 @@ export function MDXProvider(props: MDXProviderProps): unknown {
|
|
|
95
97
|
} else {
|
|
96
98
|
allComponents = useMDXComponents(props.components);
|
|
97
99
|
}
|
|
98
|
-
|
|
99
|
-
value: allComponents,
|
|
100
|
-
children: props.children,
|
|
101
|
-
});
|
|
100
|
+
<MDXContext value={allComponents} children={props.children} />
|
|
102
101
|
}
|
|
103
102
|
|
|
104
103
|
/** The props every compiled MDX document component accepts. */
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { ComponentBody } from 'octane';
|
|
2
|
+
|
|
3
|
+
export interface MDXComponents {
|
|
4
|
+
[name: string]: ComponentBody<any> | string | MDXComponents;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
export type MDXComponentsProp = MDXComponents | ((inherited: MDXComponents) => MDXComponents);
|
|
8
|
+
|
|
9
|
+
export interface MDXProviderProps {
|
|
10
|
+
children?: unknown;
|
|
11
|
+
components?: MDXComponentsProp | null;
|
|
12
|
+
disableParentContext?: boolean;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface MDXProps {
|
|
16
|
+
components?: MDXComponents;
|
|
17
|
+
[key: string]: unknown;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export declare function useMDXComponents(
|
|
21
|
+
components?: MDXComponentsProp | null | symbol,
|
|
22
|
+
_slot?: symbol,
|
|
23
|
+
): MDXComponents;
|
|
24
|
+
|
|
25
|
+
export declare function MDXProvider(props: MDXProviderProps): unknown;
|
|
@@ -1,15 +1,17 @@
|
|
|
1
|
+
'use strong';
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* @octanejs/mdx/server — the provider layer for SERVER renders.
|
|
3
5
|
*
|
|
4
6
|
* octane's client and server runtimes are separate modules with disjoint
|
|
5
|
-
* context stores, so the client `MDXProvider` (./index.
|
|
7
|
+
* context stores, so the client `MDXProvider` (./index.tsrx, built on `octane`
|
|
6
8
|
* context) cannot thread a mapping through `renderToString` — its `useContext`
|
|
7
9
|
* runs null-scope on the server and yields the `{}` default. The server
|
|
8
10
|
* runtime has its own full context implementation (`scope.$$ctxValues`,
|
|
9
11
|
* top-down within one render pass), so this entry mirrors the provider layer
|
|
10
12
|
* onto `octane/server` context: same merge, same function-form `components`,
|
|
11
|
-
* same `disableParentContext` — see ./index.
|
|
12
|
-
* notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.
|
|
13
|
+
* same `disableParentContext` — see ./index.tsrx for the @mdx-js/react port
|
|
14
|
+
* notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.tsrx (both are the
|
|
13
15
|
* same ~40-line port; only the runtime import differs).
|
|
14
16
|
*
|
|
15
17
|
* The compile pipeline points a server-mode document's `providerImportSource`
|
|
@@ -18,17 +20,17 @@
|
|
|
18
20
|
* this `MDXProvider` serializes with the same mapping the client provider
|
|
19
21
|
* produces at hydration. Client bundles never import this module.
|
|
20
22
|
*/
|
|
21
|
-
import { createContext,
|
|
22
|
-
import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.
|
|
23
|
+
import { createContext, useContext } from 'octane/server';
|
|
24
|
+
import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.tsrx';
|
|
23
25
|
|
|
24
|
-
export type { MDXComponents, MDXComponentsProp, MDXProviderProps, MDXProps } from './index.
|
|
26
|
+
export type { MDXComponents, MDXComponentsProp, MDXProviderProps, MDXProps } from './index.tsrx';
|
|
25
27
|
|
|
26
28
|
const emptyComponents: MDXComponents = {};
|
|
27
29
|
const MDXContext = createContext<MDXComponents>(emptyComponents);
|
|
28
30
|
|
|
29
31
|
/**
|
|
30
32
|
* Server `useMDXComponents`: the provider context merged with (or mapped
|
|
31
|
-
* through) `components`. Same contract as the client export (./index.
|
|
33
|
+
* through) `components`. Same contract as the client export (./index.tsrx).
|
|
32
34
|
*/
|
|
33
35
|
export function useMDXComponents(
|
|
34
36
|
components?: MDXComponentsProp | null | symbol,
|
|
@@ -48,7 +50,7 @@ export function useMDXComponents(
|
|
|
48
50
|
* document server-rendered under this provider hydrates byte-for-byte into
|
|
49
51
|
* the client `MDXProvider`.
|
|
50
52
|
*/
|
|
51
|
-
export function MDXProvider(props: MDXProviderProps)
|
|
53
|
+
export function MDXProvider(props: MDXProviderProps) @{
|
|
52
54
|
let allComponents: MDXComponents;
|
|
53
55
|
if (props.disableParentContext) {
|
|
54
56
|
allComponents =
|
|
@@ -58,8 +60,5 @@ export function MDXProvider(props: MDXProviderProps): unknown {
|
|
|
58
60
|
} else {
|
|
59
61
|
allComponents = useMDXComponents(props.components);
|
|
60
62
|
}
|
|
61
|
-
|
|
62
|
-
value: allComponents,
|
|
63
|
-
children: props.children,
|
|
64
|
-
});
|
|
63
|
+
<MDXContext value={allComponents} children={props.children} />
|
|
65
64
|
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '@octanejs/mdx';
|
package/types/compile.d.ts
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
// Hand-written declarations for src/compile.js (authored in `.js` so the vite
|
|
2
2
|
// entry's import chain loads under Node's native ESM loader — same convention
|
|
3
3
|
// as @octanejs/vite-plugin's types/). Keep in lockstep with the implementation.
|
|
4
|
-
|
|
4
|
+
// This exported compile-only entry avoids the root's evaluation types, which
|
|
5
|
+
// require a global JSX namespace. Keep the upstream options without that global.
|
|
6
|
+
import type { createFormatAwareProcessors } from '@mdx-js/mdx/internal-create-format-aware-processors';
|
|
7
|
+
|
|
8
|
+
type CompilerInput = NonNullable<Parameters<typeof createFormatAwareProcessors>[0]>;
|
|
9
|
+
type CompileOptions = { -readonly [K in keyof CompilerInput]: CompilerInput[K] };
|
|
5
10
|
|
|
6
11
|
export interface CompileMdxResult {
|
|
7
12
|
code: string;
|
|
@@ -38,11 +43,19 @@ export interface CompileMdxOptions {
|
|
|
38
43
|
dev?: boolean;
|
|
39
44
|
/** octane compiler profiling metadata (client only). */
|
|
40
45
|
profile?: boolean;
|
|
46
|
+
/** Apply Octane Strong diagnostics to the generated document and authored JavaScript. */
|
|
47
|
+
strong?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* Generated host tags that may be replaced through component mappings.
|
|
50
|
+
* Omit to keep every generated host overridable; [] makes them all native.
|
|
51
|
+
* Named components and layouts retain their existing mapping behavior.
|
|
52
|
+
*/
|
|
53
|
+
overridableTags?: readonly string[];
|
|
41
54
|
/**
|
|
42
55
|
* Module the emitted document reads the provider mapping from
|
|
43
56
|
* (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
|
|
44
57
|
* `'@octanejs/mdx/server'` (server), so each runtime reads ITS OWN context
|
|
45
|
-
* store (they are disjoint; see src/server.
|
|
58
|
+
* store (they are disjoint; see src/server.tsrx). Pass `null` to disable the
|
|
46
59
|
* provider wiring entirely (only `props.components` applies).
|
|
47
60
|
*/
|
|
48
61
|
providerImportSource?: string | null;
|
package/src/env.d.ts
DELETED
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
// @types/mdx (pulled in via @mdx-js/mdx's public types) requires a GLOBAL
|
|
2
|
-
// `JSX` namespace, which octane deliberately does not declare in its runtime
|
|
3
|
-
// types (JSX typing lives in the compiler's volar layer, per-`.tsrx` file).
|
|
4
|
-
// Minimal ambient declarations so this package typechecks standalone — no
|
|
5
|
-
// octane code reads these.
|
|
6
|
-
declare namespace JSX {
|
|
7
|
-
type Element = unknown;
|
|
8
|
-
|
|
9
|
-
interface ElementClass {
|
|
10
|
-
[name: string]: unknown;
|
|
11
|
-
}
|
|
12
|
-
|
|
13
|
-
interface IntrinsicElements {
|
|
14
|
-
[name: string]: Record<string, unknown>;
|
|
15
|
-
}
|
|
16
|
-
}
|