@scalar/docusaurus 0.8.56 → 0.8.58
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/CHANGELOG.md +12 -0
- package/README.md +5 -1
- package/dist/ScalarDocusaurus.d.ts +2 -8
- package/dist/ScalarDocusaurus.d.ts.map +1 -1
- package/dist/ScalarDocusaurus.js +5 -13
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -16
- package/dist/mount-reference.d.ts +12 -0
- package/dist/mount-reference.d.ts.map +1 -0
- package/dist/mount-reference.js +71 -0
- package/package.json +8 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @scalar/docusaurus
|
|
2
2
|
|
|
3
|
+
## 0.8.58
|
|
4
|
+
|
|
5
|
+
No changes in this release.
|
|
6
|
+
|
|
7
|
+
## 0.8.57
|
|
8
|
+
|
|
9
|
+
### Patch Changes
|
|
10
|
+
|
|
11
|
+
- [#10908](https://github.com/scalar/scalar/pull/10908): Load Scalar only on API reference routes and destroy its instances when leaving, preventing standalone styles from affecting other Docusaurus pages.
|
|
12
|
+
|
|
13
|
+
The CDN bundle is no longer injected on every page. Sites using `window.Scalar.createApiReference` outside an API reference route must load the bundle explicitly. Upgrade pinned CDN bundles to a release with `Scalar.releaseUnusedStyles` for cleanup when navigation interrupts loading.
|
|
14
|
+
|
|
3
15
|
## 0.8.56
|
|
4
16
|
|
|
5
17
|
## 0.8.55
|
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
<!--
|
|
2
2
|
This file is auto-generated by the Scalar README generator.
|
|
3
3
|
Command: pnpm --filter @scalar-internal/build-scripts start generate-readme
|
|
4
|
-
|
|
4
|
+
|
|
5
5
|
Do not edit this file manually. Changes will be lost when the file is regenerated.
|
|
6
6
|
-->
|
|
7
7
|
|
|
@@ -33,6 +33,10 @@ Scalar is an open-source API platform for teams who want beautiful developer int
|
|
|
33
33
|
|
|
34
34
|
[Read the documentation here](https://scalar.com/products/api-references/integrations/docusaurus)
|
|
35
35
|
|
|
36
|
+
### CDN compatibility
|
|
37
|
+
|
|
38
|
+
Scalar loads only when an API reference route mounts. Sites that call `window.Scalar.createApiReference` on other pages must load the CDN bundle themselves. When pinning `cdn` to an older bundle, upgrade to a release with standalone style cleanup and `Scalar.releaseUnusedStyles`; older bundles can leave styles active after navigation, including when navigation interrupts loading.
|
|
39
|
+
|
|
36
40
|
## Changelog
|
|
37
41
|
|
|
38
42
|
See [CHANGELOG.md](https://github.com/scalar/scalar/blob/main/integrations/docusaurus/CHANGELOG.md) for a list of changes.
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { RouteConfig } from '@docusaurus/types';
|
|
2
|
-
import type { CreateApiReference } from '@scalar/types';
|
|
3
2
|
import React from 'react';
|
|
4
3
|
import './theme.css';
|
|
5
4
|
type Props = {
|
|
@@ -10,15 +9,10 @@ type Props = {
|
|
|
10
9
|
* props, which drops function-valued options like `onBeforeRequest`. See issue #6933.
|
|
11
10
|
*/
|
|
12
11
|
configuration: string;
|
|
12
|
+
/** Standalone bundle URL configured for this route. */
|
|
13
|
+
cdn: string;
|
|
13
14
|
};
|
|
14
15
|
};
|
|
15
|
-
declare global {
|
|
16
|
-
interface Window {
|
|
17
|
-
Scalar: {
|
|
18
|
-
createApiReference: CreateApiReference;
|
|
19
|
-
};
|
|
20
|
-
}
|
|
21
|
-
}
|
|
22
16
|
export declare const ScalarDocusaurus: ({ route }: Props) => React.JSX.Element;
|
|
23
17
|
export default ScalarDocusaurus;
|
|
24
18
|
//# sourceMappingURL=ScalarDocusaurus.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ScalarDocusaurus.d.ts","sourceRoot":"","sources":["../src/ScalarDocusaurus.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;
|
|
1
|
+
{"version":3,"file":"ScalarDocusaurus.d.ts","sourceRoot":"","sources":["../src/ScalarDocusaurus.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,KAA4B,MAAM,OAAO,CAAA;AAIhD,OAAO,aAAa,CAAA;AAEpB,KAAK,KAAK,GAAG;IACX,KAAK,EAAE,WAAW,GAAG;QACnB;;;;WAIG;QACH,aAAa,EAAE,MAAM,CAAA;QACrB,uDAAuD;QACvD,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;CACF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,WAAW,KAAK,sBAgBhD,CAAA;AAED,eAAe,gBAAgB,CAAA"}
|
package/dist/ScalarDocusaurus.js
CHANGED
|
@@ -39,26 +39,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
39
39
|
exports.ScalarDocusaurus = void 0;
|
|
40
40
|
const Layout_1 = __importDefault(require("@theme/Layout"));
|
|
41
41
|
const react_1 = __importStar(require("react"));
|
|
42
|
+
const mount_reference_1 = require("./mount-reference");
|
|
42
43
|
require("./theme.css");
|
|
43
44
|
const ScalarDocusaurus = ({ route }) => {
|
|
44
45
|
const ref = (0, react_1.useRef)(null);
|
|
45
|
-
const id = (0, react_1.useId)();
|
|
46
46
|
(0, react_1.useEffect)(() => {
|
|
47
|
-
if (!
|
|
47
|
+
if (!ref.current) {
|
|
48
48
|
return;
|
|
49
49
|
}
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
// functions do not survive Docusaurus' JSON serialization of route props (see #6933).
|
|
53
|
-
const script = document.createElement('script');
|
|
54
|
-
script.textContent = `window.Scalar.createApiReference(document.getElementById(${JSON.stringify(id)}), ${route.configuration})`;
|
|
55
|
-
document.body.appendChild(script);
|
|
56
|
-
return () => {
|
|
57
|
-
script.remove();
|
|
58
|
-
};
|
|
59
|
-
}, [id, route.configuration]);
|
|
50
|
+
return (0, mount_reference_1.mountReference)(ref.current, route.configuration, route.cdn);
|
|
51
|
+
}, [route.configuration, route.cdn]);
|
|
60
52
|
return (react_1.default.createElement(Layout_1.default, null,
|
|
61
|
-
react_1.default.createElement("div", {
|
|
53
|
+
react_1.default.createElement("div", { ref: ref })));
|
|
62
54
|
};
|
|
63
55
|
exports.ScalarDocusaurus = ScalarDocusaurus;
|
|
64
56
|
exports.default = exports.ScalarDocusaurus;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { LoadContext, Plugin } from '@docusaurus/types';
|
|
2
|
-
import type { AnyApiReferenceConfiguration } from '@scalar/types';
|
|
2
|
+
import type { AnyApiReferenceConfiguration } from '@scalar/types/api-reference';
|
|
3
3
|
export type ScalarOptions = {
|
|
4
4
|
label?: string;
|
|
5
5
|
route?: string;
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAG5D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAG5D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAE/E,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,aAAa,CAAC,EAAE,4BAA4B,CAAA;CAC7C,CAAA;AAeD;;GAEG;AACH,QAAA,MAAM,gBAAgB,GACpB,SAAS,WAAW,EACpB,SAAS,aAAa,KACrB,MAAM,CAAC;IAAE,aAAa,CAAC,EAAE,4BAA4B,CAAA;CAAE,CAqDzD,CAAA;AAED,eAAe,gBAAgB,CAAA"}
|
package/dist/index.js
CHANGED
|
@@ -26,22 +26,6 @@ const ScalarDocusaurus = (context, options) => {
|
|
|
26
26
|
const { baseUrl } = context.siteConfig;
|
|
27
27
|
return {
|
|
28
28
|
name: '@scalar/docusaurus',
|
|
29
|
-
/**
|
|
30
|
-
* Load the Standalone API Reference script
|
|
31
|
-
* This is loaded into the dom once for every plugin thats loaded BUT it only downloads the script once
|
|
32
|
-
*/
|
|
33
|
-
injectHtmlTags() {
|
|
34
|
-
return {
|
|
35
|
-
preBodyTags: [
|
|
36
|
-
{
|
|
37
|
-
tagName: 'script',
|
|
38
|
-
attributes: {
|
|
39
|
-
src: options.cdn ?? 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
|
|
40
|
-
},
|
|
41
|
-
},
|
|
42
|
-
],
|
|
43
|
-
};
|
|
44
|
-
},
|
|
45
29
|
loadContent() {
|
|
46
30
|
return defaultOptions;
|
|
47
31
|
},
|
|
@@ -72,6 +56,7 @@ const ScalarDocusaurus = (context, options) => {
|
|
|
72
56
|
// biome-ignore lint/correctness/noGlobalDirnameFilename: Docusaurus builds this plugin as CommonJS.
|
|
73
57
|
component: node_path_1.default.resolve(__dirname, './ScalarDocusaurus'),
|
|
74
58
|
exact: true,
|
|
59
|
+
cdn: defaultOptions.cdn ?? 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
|
|
75
60
|
configuration: (0, client_side_rendering_1.serializeConfigToJs)(normalizedConfiguration),
|
|
76
61
|
});
|
|
77
62
|
},
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { CreateApiReference } from '@scalar/types/api-reference';
|
|
2
|
+
declare global {
|
|
3
|
+
interface Window {
|
|
4
|
+
Scalar?: {
|
|
5
|
+
createApiReference: CreateApiReference;
|
|
6
|
+
releaseUnusedStyles?: () => void;
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
/** Mount only for this route and release its instance when React cleans up the effect. */
|
|
11
|
+
export declare const mountReference: (container: HTMLElement, configuration: string, cdn: string) => (() => void);
|
|
12
|
+
//# sourceMappingURL=mount-reference.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mount-reference.d.ts","sourceRoot":"","sources":["../src/mount-reference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAE3F,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,MAAM,CAAC,EAAE;YACP,kBAAkB,EAAE,kBAAkB,CAAA;YACtC,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAA;SACjC,CAAA;KACF;CACF;AA4CD,0FAA0F;AAC1F,eAAO,MAAM,cAAc,GAAI,WAAW,WAAW,EAAE,eAAe,MAAM,EAAE,KAAK,MAAM,KAAG,CAAC,MAAM,IAAI,CAoCtG,CAAA"}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.mountReference = void 0;
|
|
4
|
+
const bundles = new Map();
|
|
5
|
+
/** Share downloads across route mounts, retaining each CDN bundle's factory. */
|
|
6
|
+
const loadBundle = (url) => {
|
|
7
|
+
const existing = bundles.get(url);
|
|
8
|
+
if (existing) {
|
|
9
|
+
return existing;
|
|
10
|
+
}
|
|
11
|
+
const promise = new Promise((resolve, reject) => {
|
|
12
|
+
const script = document.createElement('script');
|
|
13
|
+
script.src = url;
|
|
14
|
+
script.onload = () => {
|
|
15
|
+
script.remove();
|
|
16
|
+
if (window.Scalar?.createApiReference) {
|
|
17
|
+
resolve(window.Scalar);
|
|
18
|
+
}
|
|
19
|
+
else {
|
|
20
|
+
reject(new Error(`Scalar did not initialize from ${url}`));
|
|
21
|
+
}
|
|
22
|
+
};
|
|
23
|
+
script.onerror = () => {
|
|
24
|
+
script.remove();
|
|
25
|
+
reject(new Error(`Unable to load Scalar from ${url}`));
|
|
26
|
+
};
|
|
27
|
+
document.head.appendChild(script);
|
|
28
|
+
}).catch((error) => {
|
|
29
|
+
// A subsequent visit can retry a failed download.
|
|
30
|
+
bundles.delete(url);
|
|
31
|
+
throw error;
|
|
32
|
+
});
|
|
33
|
+
bundles.set(url, promise);
|
|
34
|
+
return promise;
|
|
35
|
+
};
|
|
36
|
+
/** Mount only for this route and release its instance when React cleans up the effect. */
|
|
37
|
+
const mountReference = (container, configuration, cdn) => {
|
|
38
|
+
let disposed = false;
|
|
39
|
+
let destroy;
|
|
40
|
+
void loadBundle(cdn)
|
|
41
|
+
.then(({ createApiReference: createReference, releaseUnusedStyles }) => {
|
|
42
|
+
if (disposed) {
|
|
43
|
+
releaseUnusedStyles?.();
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
// A real script preserves serialized callbacks without requiring unsafe-eval under CSP.
|
|
47
|
+
// Keep the instance on the script so React can own its teardown without a global registry.
|
|
48
|
+
const script = document.createElement('script');
|
|
49
|
+
script.createReference = createReference;
|
|
50
|
+
script.container = container;
|
|
51
|
+
script.textContent = `document.currentScript.reference = document.currentScript.createReference(document.currentScript.container, ${configuration})`;
|
|
52
|
+
document.body.appendChild(script);
|
|
53
|
+
const reference = script.reference;
|
|
54
|
+
script.remove();
|
|
55
|
+
destroy = () => {
|
|
56
|
+
reference?.destroy();
|
|
57
|
+
releaseUnusedStyles?.();
|
|
58
|
+
};
|
|
59
|
+
})
|
|
60
|
+
.catch((error) => {
|
|
61
|
+
if (!disposed) {
|
|
62
|
+
console.error(error);
|
|
63
|
+
}
|
|
64
|
+
});
|
|
65
|
+
return () => {
|
|
66
|
+
disposed = true;
|
|
67
|
+
destroy?.();
|
|
68
|
+
destroy = undefined;
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
exports.mountReference = mountReference;
|
package/package.json
CHANGED
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"testing",
|
|
20
20
|
"react"
|
|
21
21
|
],
|
|
22
|
-
"version": "0.8.
|
|
22
|
+
"version": "0.8.58",
|
|
23
23
|
"engines": {
|
|
24
24
|
"node": ">=22"
|
|
25
25
|
},
|
|
@@ -45,11 +45,15 @@
|
|
|
45
45
|
"image": {
|
|
46
46
|
"url": "https://github.com/scalar/scalar/blob/main/integrations/docusaurus/docusaurus.png?raw=true",
|
|
47
47
|
"altText": "Screenshot of the Docusaurus integration"
|
|
48
|
+
},
|
|
49
|
+
"extraContent": {
|
|
50
|
+
"headline": "CDN compatibility",
|
|
51
|
+
"content": "Scalar loads only when an API reference route mounts. Sites that call `window.Scalar.createApiReference` on other pages must load the CDN bundle themselves. When pinning `cdn` to an older bundle, upgrade to a release with standalone style cleanup and `Scalar.releaseUnusedStyles`; older bundles can leave styles active after navigation, including when navigation interrupts loading."
|
|
48
52
|
}
|
|
49
53
|
},
|
|
50
54
|
"dependencies": {
|
|
51
|
-
"@scalar/client-side-rendering": "0.4.
|
|
52
|
-
"@scalar/types": "0.
|
|
55
|
+
"@scalar/client-side-rendering": "0.4.19",
|
|
56
|
+
"@scalar/types": "0.28.1"
|
|
53
57
|
},
|
|
54
58
|
"devDependencies": {
|
|
55
59
|
"@docusaurus/core": "^3.10.2",
|
|
@@ -62,6 +66,7 @@
|
|
|
62
66
|
"@types/react": "^19.3.0",
|
|
63
67
|
"@types/react-dom": "^19.3.0",
|
|
64
68
|
"clsx": "^2.1.1",
|
|
69
|
+
"jsdom": "30.1.3",
|
|
65
70
|
"path": "^0.12.7",
|
|
66
71
|
"postcss": "^8.5.30",
|
|
67
72
|
"postcss-cli": "^12.0.0",
|