Initial Commit

packages/api-stack/api/api-openapi-ui-redoc/src/html/render-shell.md

@@ -0,0 +1,81 @@
+# `html/render-shell` — ReDoc HTML shell renderer
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module exposes `renderRedocShell`, the pure function that produces the
+ReDoc HTML shell consumed by both the global and per-plugin handlers. It
+embeds the OpenAPI document URL into a `<redoc spec-url="…">` custom element,
+ships a JSON option island for the runtime to read, and injects the runtime
+runtime asset reference based on the chosen asset strategy. Keeping the
+renderer separate from the handler factories lets host operators embed the
+shell in custom adapters (e.g. SSR, Edge functions) without reaching for the
+handler builder.
+
+## Features
+
+- HTML-escapes every user-supplied value (`title`, `openapiUrl`, etc.) so
+  option strings cannot break out of attribute or text-node scope.
+- Inlines the runtime body when `strategy === "inline"` and emits a
+  `<script src="…">` tag for `cdn` / `bundled` strategies.
+- Embeds `theme`, `hideDownloadButton`, `nativeScrollbars`, and
+  `expandResponses` into the JSON options island the runtime reads.
+- Tags the body element with `data-redoc-theme` so external stylesheets can
+  override the colour scheme.
+- Pure — no I/O, no clocks, no globals.
+
+## Usage: Basic
+
+```ts
+import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";
+import {
+    parseRedocUiOptions,
+    resolveRedocAsset,
+} from "@suaveplan/api-openapi-ui-redoc";
+
+const html = renderRedocShell({
+    options: parseRedocUiOptions({ openapiUrl: "/openapi.json" }),
+    resolvedAsset: resolveRedocAsset({ strategy: "cdn" }),
+});
+```
+
+## Usage: Advanced
+
+Pre-render the shell for a multi-tenant host that picks up the OpenAPI URL
+from the request path:
+
+```ts
+import { renderRedocShell } from "@suaveplan/api-openapi-ui-redoc/html";
+
+const options = parseRedocUiOptions({ openapiUrl: "/openapi.json", theme: "dark" });
+const resolvedAsset = resolveRedocAsset({ strategy: "cdn" });
+
+function htmlForTenant(tenant: string): string {
+    return renderRedocShell({
+        options,
+        resolvedAsset,
+        openapiUrlOverride: `/${tenant}/openapi.json`,
+    });
+}
+```
+
+## API Reference
+
+| Symbol                   | Kind | Description |
+| ------------------------ | ---- | ----------- |
+| `RenderRedocShellInput`  | type | `{ options, resolvedAsset, openapiUrlOverride? }` |
+| `renderRedocShell`       | fn   | Render the HTML shell as a string |
+
+## Implementation Notes
+
+The escape function covers the five HTML special characters (`&`, `<`, `>`,
+`"`, `'`) plus the apostrophe — the same surface as the WHATWG HTML
+serialization-attribute rules. The JSON island is serialised via
+`JSON.stringify` and HTML-escaped so embedded `</script>` sequences in
+option values cannot escape the `<script>` context. The shell's bottom-of-
+body initialiser calls `window.Redoc.init` when the runtime defines it,
+falling back gracefully when the runtime is unavailable (e.g. during DOM
+unit tests that don't load the standalone bundle).