@scalar/client-side-rendering 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @scalar/client-side-rendering
+
+## 0.1.0
+
+### Minor Changes
+
+- [#8431](https://github.com/scalar/scalar/pull/8431): feat: init :)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Scalar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Scalar Client-Side Rendering
+
+[![Version](https://img.shields.io/npm/v/%40scalar/client-side-rendering)](https://www.npmjs.com/package/@scalar/client-side-rendering)
+[![Downloads](https://img.shields.io/npm/dm/%40scalar/client-side-rendering)](https://www.npmjs.com/package/@scalar/client-side-rendering)
+[![License](https://img.shields.io/npm/l/%40scalar%2Fclient-side-rendering)](https://www.npmjs.com/package/@scalar/client-side-rendering)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+Render the Scalar API Reference as static HTML using the CDN. No server-side dependencies required.
+
+## Installation
+
+```bash
+npm install @scalar/client-side-rendering
+```
+
+## Usage
+
+```ts
+import { renderApiReference } from '@scalar/client-side-rendering'
+
+const html = renderApiReference({
+  pageTitle: 'My API Reference',
+  config: {
+    url: 'https://registry.scalar.com/@scalar/apis/galaxy?format=json',
+  },
+})
+```
+
+## Community
+
+We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

package/dist/html-rendering.d.ts

@@ -0,0 +1,26 @@
+import type { AnyApiReferenceConfiguration } from '@scalar/types/api-reference';
+/**
+ * Render the Scalar API Reference as a complete HTML document using the CDN.
+ *
+ * Generates static HTML that loads the @scalar/api-reference standalone bundle
+ * from a CDN and renders client-side. No server-side dependencies required.
+ *
+ * For server-side rendering with hydration, use the server module instead.
+ */
+export declare function renderApiReference(options: {
+    /** The API reference configuration. */
+    config: AnyApiReferenceConfiguration;
+    /** Page title. Defaults to "Scalar API Reference". */
+    pageTitle?: string;
+    /** CDN URL for the standalone bundle. Defaults to jsDelivr. */
+    cdn?: string;
+}, customTheme?: string): string;
+/**
+ * The script tags to load the @scalar/api-reference package from the CDN.
+ */
+export declare function getScriptTags(configuration: Record<string, unknown>, cdn?: string): string;
+/**
+ * The configuration to pass to the @scalar/api-reference package.
+ */
+export declare const getConfiguration: (givenConfiguration: Record<string, unknown>) => Record<string, unknown>;
+//# sourceMappingURL=html-rendering.d.ts.map

package/dist/html-rendering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-rendering.d.ts","sourceRoot":"","sources":["../src/html-rendering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAA;AAwD/E;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE;IACP,uCAAuC;IACvC,MAAM,EAAE,4BAA4B,CAAA;IACpC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,EACD,WAAW,SAAK,GACf,MAAM,CA0BR;AASD;;GAEG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAwC1F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,oBAAoB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAcpG,CAAA"}

package/dist/html-rendering.js

@@ -0,0 +1,139 @@
+const DEFAULT_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
+/**
+ * Escape HTML special characters in user-provided strings.
+ */
+const escapeHtml = (str) => {
+    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+};
+/**
+ * Helper function to add consistent indentation to multiline strings
+ * @param str The string to indent
+ * @param spaces Number of spaces for each level
+ * @param initialIndent Whether to indent the first line
+ */
+const addIndent = (str, spaces = 2, initialIndent = false) => {
+    const indent = ' '.repeat(spaces);
+    const lines = str.split('\n');
+    return lines
+        .map((line, index) => {
+        if (index === 0 && !initialIndent) {
+            return line;
+        }
+        return `${indent}${line}`;
+    })
+        .join('\n');
+};
+/**
+ * Generate the style tag with custom theme if needed
+ */
+const getStyles = (configuration, customTheme) => {
+    const styles = [];
+    if (configuration.customCss) {
+        styles.push('/* Custom CSS */');
+        styles.push(configuration.customCss);
+    }
+    if (!configuration.theme && customTheme) {
+        styles.push('/* Custom Theme */');
+        styles.push(customTheme);
+    }
+    if (styles.length === 0) {
+        return '';
+    }
+    return `
+    <style type="text/css">
+      ${addIndent(styles.join('\n\n'), 6)}
+    </style>`;
+};
+/**
+ * Render the Scalar API Reference as a complete HTML document using the CDN.
+ *
+ * Generates static HTML that loads the @scalar/api-reference standalone bundle
+ * from a CDN and renders client-side. No server-side dependencies required.
+ *
+ * For server-side rendering with hydration, use the server module instead.
+ */
+export function renderApiReference(options, customTheme = '') {
+    const { config: givenConfig, pageTitle, cdn } = options;
+    const title = escapeHtml(pageTitle ?? 'Scalar API Reference');
+    const unwrapped = Array.isArray(givenConfig) ? givenConfig[0] : givenConfig;
+    const { customCss, theme, ...rest } = (unwrapped ?? {});
+    const configuration = getConfiguration({
+        ...rest,
+        ...(theme ? { theme } : {}),
+        ...(customCss !== undefined ? { customCss } : {}),
+    });
+    return `<!doctype html>
+<html>
+  <head>
+    <title>${title}</title>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />${getStyles(configuration, customTheme)}
+  </head>
+  <body>
+    <div id="app"></div>${getScriptTags(configuration, cdn)}
+  </body>
+</html>`;
+}
+/**
+ * Helper function to serialize arrays that may contain functions
+ */
+const serializeArrayWithFunctions = (arr) => {
+    return `[${arr.map((item) => (typeof item === 'function' ? item.toString() : JSON.stringify(item))).join(', ')}]`;
+};
+/**
+ * The script tags to load the @scalar/api-reference package from the CDN.
+ */
+export function getScriptTags(configuration, cdn) {
+    const restConfig = { ...configuration };
+    const functionProps = [];
+    for (const [key, value] of Object.entries(configuration)) {
+        if (typeof value === 'function') {
+            functionProps.push(`"${key}": ${value.toString()}`);
+            delete restConfig[key];
+        }
+        else if (Array.isArray(value) && value.some((item) => typeof item === 'function')) {
+            functionProps.push(`"${key}": ${serializeArrayWithFunctions(value)}`);
+            delete restConfig[key];
+        }
+    }
+    const jsonString = JSON.stringify(restConfig, null, 2);
+    const indentedJsonString = jsonString
+        .split('\n')
+        .map((line, index) => (index === 0 ? line : `      ${line}`))
+        .join('\n');
+    let configString = indentedJsonString;
+    if (functionProps.length > 0) {
+        if (jsonString === '{}') {
+            configString = `{\n        ${functionProps.join(',\n        ')}\n      }`;
+        }
+        else {
+            const jsonWithoutClosingBrace = indentedJsonString.split('\n').slice(0, -1).join('\n');
+            configString = `${jsonWithoutClosingBrace},\n        ${functionProps.join(',\n        ')}\n      }`;
+        }
+    }
+    return `
+    <!-- Load the Script -->
+    <script src="${cdn ?? DEFAULT_CDN}"></script>
+
+    <!-- Initialize the Scalar API Reference -->
+    <script type="text/javascript">
+      Scalar.createApiReference('#app', ${configString})
+    </script>`;
+}
+/**
+ * The configuration to pass to the @scalar/api-reference package.
+ */
+export const getConfiguration = (givenConfiguration) => {
+    const configuration = { ...givenConfiguration };
+    // Execute content if it's a function
+    if (typeof configuration.content === 'function') {
+        configuration.content = configuration.content();
+    }
+    // Only remove content if url is provided
+    if (configuration.content && configuration.url) {
+        delete configuration.content;
+    }
+    return configuration;
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { getConfiguration, getScriptTags, renderApiReference } from './html-rendering.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { getConfiguration, getScriptTags, renderApiReference } from './html-rendering.js';

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@scalar/client-side-rendering",
+  "description": "Client-side rendering for the Scalar API Reference using the CDN",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalar/scalar.git",
+    "directory": "packages/client-side-rendering"
+  },
+  "keywords": [],
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@scalar/types": "0.8.0"
+  },
+  "devDependencies": {
+    "vite": "8.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "test": "vitest",
+    "types:check": "tsc --noEmit"
+  }
+}