@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 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.62",
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.ts",
30
- "module": "src/index.ts",
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
- ".": "./src/index.ts",
39
- "./server": "./src/server.ts",
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.0",
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(String(out.value), out.map, source, id, options, diagnosticContext);
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(String(out.value), out.map, source, id, options, diagnosticContext);
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} jsxSource
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(jsxSource, mdxMap, authoredSource, id, options, diagnosticContext) {
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 exact registration 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()` (identity-stable across edits — parents keep their mounted
407
- // wrapper) + a self-accepting `import.meta.hot` block that swaps the body
408
- // and re-renders live blocks in place. Appending after the fact keeps the
409
- // source map's earlier segments valid (ESM imports hoist).
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.accept((module) => {\n' +
416
- ' module && MDXContent[_$mdxHMR].update(module.default);\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` +
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
- /** @param {unknown} tree */
612
- return (tree) => {
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.ts in lockstep.
32
+ * the merge semantics here and in src/server.tsrx in lockstep.
31
33
  */
32
- import { createContext, createElement, useContext, type ComponentBody } from 'octane';
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): unknown {
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
- return createElement(MDXContext as ComponentBody<any>, {
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.ts, built on `octane`
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.ts for the @mdx-js/react port
12
- * notes. KEEP THE MERGE SEMANTICS IN LOCKSTEP with ./index.ts (both are the
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, createElement, useContext } from 'octane/server';
22
- import type { MDXComponents, MDXComponentsProp, MDXProviderProps } from './index.js';
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.js';
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.ts).
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): unknown {
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
- return createElement(MDXContext as any, {
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';
@@ -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
- import type { CompileOptions } from '@mdx-js/mdx';
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.ts). Pass `null` to disable the
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
- }