@octanejs/mdx 0.1.62 → 0.1.64
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 +9 -1
- package/package.json +13 -7
- package/src/compile.js +61 -14
- 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 +7 -2
- package/src/env.d.ts +0 -16
package/README.md
CHANGED
|
@@ -84,6 +84,11 @@ A mapping can also be passed per-document: `<Doc components={{ h1: FancyHeading
|
|
|
84
84
|
Mapping values are octane components or replacement host tag names (`{ em: 'i' }`);
|
|
85
85
|
the special `wrapper` key is the document layout.
|
|
86
86
|
|
|
87
|
+
The client and server providers are authored as Strong `.tsrx` templates and
|
|
88
|
+
compiled by the consuming application's Octane plugin. This applies to the
|
|
89
|
+
provider boundary; generated MDX document elements still use the value-position
|
|
90
|
+
rendering path described below.
|
|
91
|
+
|
|
87
92
|
## API (vs @mdx-js/react)
|
|
88
93
|
|
|
89
94
|
- `MDXProvider({ components, disableParentContext, children })` — ported;
|
|
@@ -143,7 +148,10 @@ async — it works in the vite plugin and `compileMdx`, not `compileMdxSync`.
|
|
|
143
148
|
- `.mdx` edits fast-refresh in dev: the pipeline wraps the document's default
|
|
144
149
|
export in octane's runtime `hmr()` and self-accepts, so live mounts re-render
|
|
145
150
|
the new body in place (no page reload; the vite plugin enables this in serve
|
|
146
|
-
mode automatically).
|
|
151
|
+
mode automatically). Importers keep the named exports they read, such as
|
|
152
|
+
`frontmatter`, so the update also reaches them when one is no longer
|
|
153
|
+
identical. An object export, `frontmatter` included, is a new object after
|
|
154
|
+
every edit.
|
|
147
155
|
|
|
148
156
|
## Status
|
|
149
157
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@octanejs/mdx",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.64",
|
|
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.6",
|
|
65
71
|
"vite": "^8.1.5",
|
|
66
72
|
"vitest": "^4.1.10"
|
|
67
73
|
},
|
package/src/compile.js
CHANGED
|
@@ -135,7 +135,7 @@ export async function compileMdx(source, id, options = {}) {
|
|
|
135
135
|
{ value: source, path: id },
|
|
136
136
|
buildMdxOptions(id, options, diagnosticContext),
|
|
137
137
|
);
|
|
138
|
-
return octaneStage(
|
|
138
|
+
return octaneStage(out, source, id, options, diagnosticContext);
|
|
139
139
|
}
|
|
140
140
|
|
|
141
141
|
/**
|
|
@@ -157,7 +157,7 @@ export function compileMdxSync(source, id, options = {}) {
|
|
|
157
157
|
{ value: source, path: id },
|
|
158
158
|
buildMdxOptions(id, options, diagnosticContext),
|
|
159
159
|
);
|
|
160
|
-
return octaneStage(
|
|
160
|
+
return octaneStage(out, source, id, options, diagnosticContext);
|
|
161
161
|
}
|
|
162
162
|
|
|
163
163
|
/**
|
|
@@ -356,15 +356,16 @@ function restoreAuthoredJsxAttributeLocations(context) {
|
|
|
356
356
|
}
|
|
357
357
|
|
|
358
358
|
/**
|
|
359
|
-
* @param {string}
|
|
360
|
-
* @param {unknown} mdxMap
|
|
359
|
+
* @param {{ value: unknown, map?: unknown, data: Record<string, any> }} mdxFile
|
|
361
360
|
* @param {string} authoredSource
|
|
362
361
|
* @param {string} id
|
|
363
362
|
* @param {CompileMdxOptions} options
|
|
364
363
|
* @param {DiagnosticMappingContext} diagnosticContext
|
|
365
364
|
* @returns {CompileMdxResult}
|
|
366
365
|
*/
|
|
367
|
-
function octaneStage(
|
|
366
|
+
function octaneStage(mdxFile, authoredSource, id, options, diagnosticContext) {
|
|
367
|
+
const jsxSource = String(mdxFile.value);
|
|
368
|
+
const mdxMap = mdxFile.map;
|
|
368
369
|
const mode = options.mode ?? 'client';
|
|
369
370
|
const out = octaneCompile(jsxSource, id, {
|
|
370
371
|
mode,
|
|
@@ -401,19 +402,34 @@ function octaneStage(jsxSource, mdxMap, authoredSource, id, options, diagnosticC
|
|
|
401
402
|
// `@{}`-form components in `hmr(...)` — `MDXContent` (a passthrough function
|
|
402
403
|
// returning a ternary of descriptors) isn't recognized as one, so the octane
|
|
403
404
|
// `hmr` flag alone leaves `.mdx` edits as full module invalidations. The
|
|
404
|
-
// PIPELINE knows the emitted shape, so it appends the
|
|
405
|
+
// PIPELINE knows the emitted shape, so it appends the registration the
|
|
405
406
|
// octane compiler emits for `.tsrx` exports: wrap the default export in the
|
|
406
|
-
// runtime `hmr()
|
|
407
|
-
//
|
|
408
|
-
// and
|
|
409
|
-
//
|
|
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).
|
|
410
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(' || ')})`;
|
|
411
421
|
out.code +=
|
|
412
422
|
"\nimport { hmr as _$mdxHmr, HMR as _$mdxHMR } from 'octane';\n" +
|
|
413
423
|
'MDXContent = _$mdxHmr(MDXContent);\n' +
|
|
414
424
|
'if (import.meta.hot) {\n' +
|
|
415
|
-
' import.meta.hot.
|
|
416
|
-
'
|
|
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` +
|
|
417
433
|
' });\n' +
|
|
418
434
|
'}\n';
|
|
419
435
|
}
|
|
@@ -608,12 +624,43 @@ function remapDiagnostics(diagnostics, mdxMap, jsxSource, source, id, authoredAt
|
|
|
608
624
|
const MDX_BODY_NAME = '_createMdxContent';
|
|
609
625
|
|
|
610
626
|
function recmaOctaneAdapter() {
|
|
611
|
-
/**
|
|
612
|
-
|
|
627
|
+
/**
|
|
628
|
+
* @param {unknown} tree
|
|
629
|
+
* @param {{ data: Record<string, unknown> }} file
|
|
630
|
+
*/
|
|
631
|
+
return (tree, file) => {
|
|
613
632
|
walkReplace(/** @type {EstreeNode} */ (tree), adaptNode);
|
|
633
|
+
file.data.octaneNamedExports = namedExportBindings(/** @type {any} */ (tree));
|
|
614
634
|
};
|
|
615
635
|
}
|
|
616
636
|
|
|
637
|
+
/**
|
|
638
|
+
* The document's named exports as [exportName, localName] pairs, or null when
|
|
639
|
+
* one has no single module binding to compare: a re-export, `export *`, or a
|
|
640
|
+
* destructuring declaration.
|
|
641
|
+
*
|
|
642
|
+
* @param {{ body: any[] }} program
|
|
643
|
+
* @returns {Array<[string, string]> | null}
|
|
644
|
+
*/
|
|
645
|
+
function namedExportBindings(program) {
|
|
646
|
+
/** @type {Array<[string, string]>} */
|
|
647
|
+
const bindings = [];
|
|
648
|
+
for (const node of program.body) {
|
|
649
|
+
if (node.type === 'ExportAllDeclaration') return null;
|
|
650
|
+
if (node.type !== 'ExportNamedDeclaration') continue;
|
|
651
|
+
if (node.source) return null;
|
|
652
|
+
const declaration = node.declaration;
|
|
653
|
+
for (const { id } of declaration?.declarations ?? (declaration ? [declaration] : [])) {
|
|
654
|
+
if (id.type !== 'Identifier') return null;
|
|
655
|
+
bindings.push([id.name, id.name]);
|
|
656
|
+
}
|
|
657
|
+
for (const specifier of node.specifiers) {
|
|
658
|
+
bindings.push([specifier.exported.name ?? specifier.exported.value, specifier.local.name]);
|
|
659
|
+
}
|
|
660
|
+
}
|
|
661
|
+
return bindings;
|
|
662
|
+
}
|
|
663
|
+
|
|
617
664
|
/** @typedef {{ type: string, [key: string]: unknown }} EstreeNode */
|
|
618
665
|
|
|
619
666
|
/**
|
|
@@ -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;
|
|
@@ -42,7 +47,7 @@ export interface CompileMdxOptions {
|
|
|
42
47
|
* Module the emitted document reads the provider mapping from
|
|
43
48
|
* (`useMDXComponents`). Defaults per mode — `'@octanejs/mdx'` (client) /
|
|
44
49
|
* `'@octanejs/mdx/server'` (server), so each runtime reads ITS OWN context
|
|
45
|
-
* store (they are disjoint; see src/server.
|
|
50
|
+
* store (they are disjoint; see src/server.tsrx). Pass `null` to disable the
|
|
46
51
|
* provider wiring entirely (only `props.components` applies).
|
|
47
52
|
*/
|
|
48
53
|
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
|
-
}
|