rapidoc 11.0.0 → 12.0.0

package/src/static/serializer.js

@@ -0,0 +1,216 @@
+/**
+ * Isomorphic HTML serializer for Lit TemplateResult in Node.js, Bun, and SSR/SSG runtimes.
+ *
+ * Flattens declarative Lit templates into pure, static HTML strings without requiring
+ * a browser window, headless browser, or full DOM emulator (JSDOM/HappyDOM).
+ */
+
+// Minimal polyfill for customElements registry in pure Node/Bun environments
+if (typeof globalThis.customElements === "undefined") {
+  globalThis.customElements = {
+    define: () => {},
+    get: () => undefined,
+    whenDefined: () => Promise.resolve(),
+  };
+}
+
+/**
+ * Escapes characters for HTML text nodes and attribute values to prevent injection.
+ * @param {string} str
+ * @returns {string}
+ */
+export function escapeHtml(str) {
+  if (typeof str !== "string") return String(str ?? "");
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Escapes characters for HTML text nodes (quotes are left as is, since they are inert in text).
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeText(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/**
+ * Directives whose value is inserted as markup, matching Lit's behavior in the browser.
+ * Matched by the static `directiveName` (survives minification, unlike class names).
+ */
+const RAW_MARKUP_DIRECTIVES = new Set(["unsafeHTML", "unsafeSVG"]);
+
+/**
+ * Recursively serializes a Lit TemplateResult, directive, CSSResult, primitive, or array
+ * into a pure static HTML string.
+ *
+ * - Event listeners (`@click="..."`) are stripped.
+ * - Non-attribute property bindings (`.prop="..."`) are stripped.
+ * - Boolean attributes (`?disabled="..."`) are converted to standard HTML attributes if truthy, or omitted if falsy.
+ * - Strings from plain bindings are HTML-escaped, as Lit does in the browser (`&<>` in text,
+ *   plus quotes in attribute values). Unquoted attribute bindings (`value=${x}`) are quoted.
+ * - Lit directives (`unsafeHTML`, `ifDefined`, `guard`) are evaluated transparently; only
+ *   `unsafeHTML` / `unsafeSVG` values are inserted as raw markup. An attribute whose whole value is
+ *   `nothing` (e.g. `ifDefined(undefined)`) is omitted.
+ * - CSSResult instances (`css\`...\``) are resolved via their `.cssText` property.
+ *
+ * @param {any} result - The value or TemplateResult to serialize.
+ * @param {Object} [options]
+ * @param {boolean} [options.stripComments=false] - Whether to strip HTML comments.
+ * @returns {string} Serialized HTML string.
+ */
+export function renderTemplateToString(result, options = {}) {
+  return serializeValue(result, options, false);
+}
+
+/**
+ * @param {any} result
+ * @param {Object} options
+ * @param {boolean} inAttribute - Whether the value is bound inside an attribute value.
+ * @returns {string}
+ */
+function serializeValue(result, options, inAttribute) {
+  if (result == null || result === false) {
+    return "";
+  }
+
+  if (typeof result === "string") {
+    return inAttribute ? escapeHtml(result) : escapeText(result);
+  }
+
+  if (typeof result === "number" || typeof result === "bigint") {
+    return String(result);
+  }
+
+  if (typeof result === "symbol") {
+    return "";
+  }
+
+  if (Array.isArray(result)) {
+    return result.map((item) => serializeValue(item, options, inAttribute)).join("");
+  }
+
+  // Handle Lit CSSResult
+  if (typeof result === "object" && result.cssText) {
+    return result.cssText;
+  }
+
+  // Handle Lit directives (unsafeHTML, guard, live)
+  if (typeof result === "object" && result._$litDirective$) {
+    // unsafeHTML(str) / unsafeSVG(str): inserted as markup, never escaped
+    if (RAW_MARKUP_DIRECTIVES.has(result._$litDirective$.directiveName)) {
+      const markup = result.values?.[0];
+      return typeof markup === "string" ? markup : serializeValue(markup, options, inAttribute);
+    }
+    // guard([deps], () => fn)
+    if (result.values && typeof result.values[1] === "function") {
+      return serializeValue(result.values[1](), options, inAttribute);
+    }
+    // live(value) and other value-passing directives
+    if (result.values && result.values.length > 0) {
+      return serializeValue(result.values[0], options, inAttribute);
+    }
+    return "";
+  }
+
+  // Handle Lit TemplateResult
+  if (typeof result === "object" && "strings" in result && "values" in result) {
+    let out = "";
+    let skipNextLeadingQuote = false;
+    // Whether the parser position is inside a start tag (between `<` and `>`), so a binding is an attribute value
+    let inTag = false;
+
+    for (let i = 0; i < result.strings.length; i++) {
+      let str = result.strings[i];
+      const lastOpen = str.lastIndexOf("<");
+      const lastClose = str.lastIndexOf(">");
+      if (lastOpen !== lastClose) {
+        inTag = lastOpen > lastClose;
+      }
+
+      // Strip matching quote from previous expression if skipped
+      if (skipNextLeadingQuote) {
+        if (str.startsWith('"') || str.startsWith("'")) {
+          str = str.slice(1);
+        }
+        skipNextLeadingQuote = false;
+      }
+
+      if (i < result.values.length) {
+        const val = result.values[i];
+
+        // 1. Event bindings: e.g. @click="..." or @click=...
+        const eventMatch = str.match(/@([\w.-]+)=(["']?)$/);
+        if (eventMatch) {
+          str = str.slice(0, eventMatch.index).trimEnd();
+          if (eventMatch[2]) {
+            skipNextLeadingQuote = true;
+          }
+          out += str;
+          continue;
+        }
+
+        // 2. Property bindings: e.g. .config="..." or .config=...
+        const propMatch = str.match(/\.([\w.-]+)=(["']?)$/);
+        if (propMatch) {
+          str = str.slice(0, propMatch.index).trimEnd();
+          if (propMatch[2]) {
+            skipNextLeadingQuote = true;
+          }
+          out += str;
+          continue;
+        }
+
+        // 3. Boolean attributes: e.g. ?disabled="..." or ?disabled=...
+        const boolMatch = str.match(/\?([\w.-]+)=(["']?)$/);
+        if (boolMatch) {
+          const attrName = boolMatch[1];
+          const hasQuote = Boolean(boolMatch[2]);
+          str = str.slice(0, boolMatch.index).trimEnd();
+          if (hasQuote) {
+            skipNextLeadingQuote = true;
+          }
+          const isTruthy = Boolean(val && val !== "false");
+          out += str + (isTruthy ? ` ${attrName}` : "");
+          continue;
+        }
+
+        // 4. Regular attribute or text node
+        const attrMatch = inTag ? str.match(/\s[^\s"'>/=]+=(["']?)$/) : null;
+        if (
+          attrMatch &&
+          typeof val === "symbol" &&
+          (!attrMatch[1] || result.strings[i + 1]?.startsWith(attrMatch[1]))
+        ) {
+          // `nothing` (e.g. ifDefined(undefined)) as the whole attribute value removes the attribute, as Lit does
+          out += str.slice(0, attrMatch.index);
+          skipNextLeadingQuote = Boolean(attrMatch[1]);
+          continue;
+        }
+        if (attrMatch && !attrMatch[1]) {
+          // Unquoted attribute binding: quote it so an escaped value cannot break out into new attributes
+          out += `${str}"${serializeValue(val, options, true)}"`;
+        } else {
+          out += str;
+          out += serializeValue(val, options, inTag);
+        }
+      } else {
+        out += str;
+      }
+    }
+
+    if (options.stripComments) {
+      out = out.replace(/<!--[\s\S]*?-->/g, "");
+    }
+
+    return out;
+  }
+
+  return "";
+}
+
+export default renderTemplateToString;

package/src/styles/auth-styles.js

@@ -0,0 +1,318 @@
+import { css } from "lit";
+
+/**
+ * Authentication: the security-scheme list in the Authentication section and the
+ * security chips on each operation. Loaded by <rapi-doc> and <rapi-doc-mini>.
+ */
+export default css`
+  /* Authentication: one list item per security scheme; OAuth flows nest inside their scheme. */
+  .auth-status {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.5rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .auth-list {
+    container-type: inline-size;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    border: 1px solid var(--border);
+    border-radius: min(var(--radius), 0.5rem);
+    /* Card surface, same as .param-list */
+    background: color-mix(in srgb, var(--card) 80%, transparent);
+    font-size: var(--font-size-small);
+    line-height: 1.5;
+    direction: ltr;
+  }
+
+  .auth-scheme {
+    padding: calc(var(--auth-scheme-padding) * 1.5);
+    margin: 0;
+    overflow-wrap: break-word;
+
+    & + .auth-scheme {
+      border-top: 1px solid var(--border);
+    }
+  }
+
+  /* Each block of a scheme (header, description, hint, controls, flows) is spaced by the same gap */
+  .auth-scheme-body,
+  .oauth-flow {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 0.75em;
+
+    & > * {
+      margin: 0;
+      max-width: 100%;
+    }
+  }
+
+  .auth-scheme-header {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.5em;
+  }
+
+  .auth-scheme-title {
+    font-size: var(--font-size-regular);
+    font-weight: 600;
+  }
+
+  /* Prose (description, "Send X in header") keeps a readable line length */
+  .auth-scheme-body > .m-markdown,
+  .auth-hint,
+  .auth-host-note {
+    max-width: 70ch;
+  }
+
+  /* "Use a different token" under a host note: a text link, not a full-size button */
+  .auth-host-toggle {
+    font-size: var(--font-size-small);
+  }
+
+  /*
+   * Inputs and their button on a grid of equal columns (12em-16em), so a field that wraps to the next
+   * line keeps the width of the one above it; the button sits at the start of its cell.
+   */
+  .auth-controls {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(12em, 16em));
+    align-items: center;
+    gap: 0.5em;
+    width: 100%;
+
+    & > :is(input, select) {
+      width: 100%;
+      min-width: 0;
+      box-sizing: border-box;
+    }
+
+    & > .btn {
+      justify-self: start;
+    }
+  }
+
+  /* OAuth flows: one after another, each opened by its heading and parted from the previous one by a dashed rule */
+  .oauth-flow {
+    padding-block: 1.25em;
+
+    & + .oauth-flow {
+      border-top: 1px dashed var(--border);
+    }
+
+    &:last-child {
+      padding-bottom: 0;
+    }
+
+    & > .tiny-title {
+      margin: 0;
+    }
+  }
+
+  .oauth-urls {
+    display: grid;
+    grid-template-columns: max-content minmax(0, 1fr);
+    gap: 0.25em 1.5em;
+
+    & > dt {
+      color: var(--muted-foreground);
+    }
+
+    & > dd {
+      margin: 0;
+      overflow-wrap: anywhere;
+    }
+  }
+
+  .oauth-scopes-label {
+    color: var(--muted-foreground);
+    margin-bottom: -0.25em;
+  }
+
+  .oauth-scopes {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5em;
+  }
+
+  /* Scope value in the foreground color, its description muted, with a dash between */
+  .oauth-scope-name {
+    color: var(--foreground);
+  }
+
+  .oauth-scope-descr {
+    color: var(--muted-foreground);
+
+    &::before {
+      content: '– ';
+    }
+  }
+
+  /* Toggle + its text; the text wraps beside the toggle, not under it. The toggle is 1.5em tall,
+     the same as one line of text here, so it lines up with the first line. */
+  .auth-toggle {
+    display: inline-flex;
+    align-items: flex-start;
+    gap: 0.625em;
+    cursor: pointer;
+  }
+
+  .oauth-resp-display:empty {
+    display: none;
+  }
+
+  /* Narrow containers: fields take the full row; URL labels stack above their values */
+  @container (max-width: 30rem) {
+    .auth-controls {
+      grid-template-columns: minmax(0, 1fr);
+    }
+
+    .oauth-urls {
+      grid-template-columns: minmax(0, 1fr);
+
+      & > dd + dt {
+        margin-top: 0.375em;
+      }
+    }
+  }
+
+  /*
+   * Operation security: a lock, then a row of chips right under the method and path, one per alternative,
+   * with "OR" between them. The lock marks the row as authorization (and links to the Authentication
+   * section when that is shown); a chip opens its details popover on hover or focus.
+   */
+  .operation-security {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.375em;
+    margin: 0 0 12px;
+    min-width: 0;
+    max-width: 100%;
+    font-size: var(--font-size-small);
+    line-height: 1.25;
+  }
+  .security-chips {
+    align-items: center;
+    row-gap: 6px;
+
+    /* Keeps "OR" centered on the chip beside it */
+    & > li {
+      display: inline-flex;
+      align-items: center;
+    }
+  }
+  .value-list-items.security-chips > li:not(:last-child)::after {
+    content: 'OR';
+    margin-inline: 0.625em;
+    font-size: var(--font-size-xs);
+    letter-spacing: 0.04em;
+  }
+  .security-chip {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375em;
+    min-width: 0;
+    max-width: 100%;
+    padding: 0.25em 0.625em;
+    color: var(--foreground);
+    background: color-mix(in srgb, var(--card) 80%, transparent);
+    border: 1px solid var(--input);
+    /* Same radius as buttons, inputs and the popover it opens */
+    border-radius: var(--radius);
+    transition:
+      color 0.15s ease,
+      border-color 0.15s ease;
+
+    &.has-details {
+      cursor: pointer;
+    }
+    &.has-details:is(:hover, :focus-within) {
+      color: var(--primary);
+      border-color: var(--primary);
+    }
+  }
+  /* Same size as a chip (and .btn-sm), so it lines up with the first row of chips */
+  .security-lock-btn {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    width: calc(1.75em + 2px);
+    height: calc(1.75em + 2px);
+    color: var(--muted-foreground);
+    border-radius: var(--radius);
+  }
+  a.security-lock-btn {
+    transition:
+      color 0.15s ease,
+      background-color 0.15s ease;
+
+    &:hover {
+      color: var(--foreground);
+      background: var(--muted);
+    }
+    &:focus-visible {
+      outline: none;
+      box-shadow: var(--focus-shadow);
+    }
+  }
+  .security-lock {
+    width: 1.25em;
+    height: 1.25em;
+    stroke: currentColor;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+  }
+  .security-chip-label {
+    display: block;
+    max-width: 240px;
+    padding: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    color: inherit;
+    text-decoration: none;
+    font: inherit;
+    background: none;
+    border: none;
+    border-radius: 0;
+    cursor: inherit;
+
+    &:focus-visible {
+      outline: 2px solid var(--ring);
+      outline-offset: 2px;
+    }
+  }
+
+  /* Scheme details for a chip: a top-layer popover anchored below it (above when there is no room) */
+  /* Left edge on the chip's left edge, 6px below it; a page-colored surface with a thin border and a soft, tight shadow */
+  .security-popover {
+    inset: auto;
+    margin: 6px 0 6px 0;
+    position-area: bottom span-right;
+    position-try-fallbacks: flip-block;
+    width: max-content;
+    max-width: min(400px, calc(100vw - 16px));
+    padding: 0.75em 1em;
+    color: var(--foreground);
+    background: var(--background);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    box-shadow:
+      0 1px 2px rgba(0, 0, 0, 0.06),
+      0 4px 12px rgba(0, 0, 0, 0.08);
+    font-family: var(--font-sans);
+    font-size: var(--font-size-description);
+    line-height: 1.5;
+    text-align: start;
+    overflow-wrap: anywhere;
+    cursor: auto;
+  }
+`;

package/src/styles/border-styles.js

@@ -0,0 +1,24 @@
+import { css } from "lit";
+
+export default css`
+  .border-top {
+    border-top: 1px solid var(--border);
+  }
+  .border {
+    border: 1px solid var(--border);
+    border-radius: min(var(--radius), 0.5rem);
+  }
+  .light-border {
+    border: 1px solid var(--border);
+    border-radius: min(var(--radius), 0.5rem);
+  }
+  .pad-8-16 {
+    padding: 8px 16px;
+  }
+  .pad-top-8 {
+    padding-top: 8px;
+  }
+  .mar-top-8 {
+    margin-top: 8px;
+  }
+`;

package/src/styles/css-bundle.js

@@ -0,0 +1,129 @@
+import ThemeTokens, { DEFAULT_THEME } from "./theme-tokens.js";
+import FontStyles from "./font-styles.js";
+import InputStyles from "./input-styles.js";
+import FlexStyles from "./flex-styles.js";
+import AuthStyles from "./auth-styles.js";
+import ParamListStyles from "./param-list-styles.js";
+import EndpointStyles from "./endpoint-styles.js";
+import MicrolighterStyles from "./microlighter-styles.js";
+import TabStyles from "./tab-styles.js";
+import NavStyles from "./nav-styles.js";
+import InfoStyles from "./info-styles.js";
+import DialogBoxStyles from "./dialog-box-styles.js";
+import LayoutStyles from "./layout-styles.js";
+import BorderStyles from "./border-styles.js";
+import SchemaStyles from "./schema-styles.js";
+import CustomStyles from "./custom-styles.js";
+
+export const allStyles = [
+  ThemeTokens,
+  FontStyles,
+  InputStyles,
+  FlexStyles,
+  AuthStyles,
+  ParamListStyles,
+  BorderStyles,
+  EndpointStyles,
+  MicrolighterStyles,
+  TabStyles,
+  NavStyles,
+  InfoStyles,
+  DialogBoxStyles,
+  LayoutStyles,
+  SchemaStyles,
+  CustomStyles,
+];
+
+/**
+ * Returns aggregated CSS text for Declarative Shadow DOM or Light DOM SSR/SSG pre-rendering.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.theme='ember'] - Theme preset name or valid hex color code
+ * @param {'dark'|'light'|'system'} [options.colorScheme='dark'] - Color scheme
+ * @param {string} [options.scope=''] - Optional outer selector (for Light DOM / non-shadow pre-rendering)
+ * @returns {string} Fully concatenated CSS string
+ */
+export function getBundledCss(options = {}) {
+  const { scope = "" } = options;
+
+  let combinedCss = allStyles.map((s) => (s && s.cssText ? s.cssText : String(s || ""))).join("\n");
+
+  // If rendering in Light DOM without Shadow DOM, adapt :host selectors to the container
+  if (scope && scope !== ":host") {
+    combinedCss = combinedCss
+      .replace(/:host\(([^)]+)\)/g, `${scope}$1`)
+      .replace(/:host\b/g, scope)
+      .replace(/::slotted\(([^)]+)\)/g, `$1`);
+  }
+
+  return combinedCss;
+}
+
+/**
+ * Returns RapiDoc's navigation CSS text for shared usage in @rapidoc/portal.
+ *
+ * @param {string} [scope=''] - Optional outer selector
+ * @returns {string} Navigation CSS string
+ */
+export function getNavCss(scope = "") {
+  let navCss = NavStyles && NavStyles.cssText ? NavStyles.cssText : String(NavStyles || "");
+  if (scope && scope !== ":host") {
+    navCss = navCss
+      .replace(
+        /:host\(\[color-scheme='([^']+)'\]\)/g,
+        `[data-theme='$1'] ${scope}, ${scope}[color-scheme='$1']`,
+      )
+      .replace(/:host\(([^)]+)\)/g, `${scope}$1`)
+      .replace(/:host\b/g, scope)
+      .replace(/::slotted\(([^)]+)\)/g, `$1`)
+      .replace(/^\s*\.nav-bar\s*\{/gm, "&.nav-bar, & {");
+    navCss = `${scope} {\n  --sidebar-item-padding: 0.3125rem 1rem 0.3125rem 0.625rem;\n${navCss}\n}\n[data-theme='light'] ${scope} .nav-method.as-colored-block {\n  color: var(--method-badge-fg);\n}\n`;
+  }
+  return navCss;
+}
+
+/**
+ * Returns RapiDoc's design system & theme tokens CSS text for shared usage in @rapidoc/portal.
+ * Converts Web Component :host rules into Light DOM portal selectors (:root, [data-theme='dark'], [data-theme='light']).
+ *
+ * @param {string} [theme='ember'] - Theme preset name (see THEME_PRESETS) or hex color
+ * @param {string} [scope=':root'] - Scope selector
+ * @returns {string} Theme tokens CSS string
+ */
+export function getThemeTokensCss(theme = DEFAULT_THEME, scope = ":root") {
+  let tokensCss =
+    ThemeTokens && ThemeTokens.cssText ? ThemeTokens.cssText : String(ThemeTokens || "");
+  const activeTheme =
+    typeof theme === "string"
+      ? theme.trim().toLowerCase()
+      : typeof theme === "object" && theme?.theme
+        ? String(theme.theme).trim().toLowerCase()
+        : DEFAULT_THEME;
+
+  tokensCss = tokensCss
+    .replace(/:host\(\[theme='([^']+)'\]\[color-scheme='light'\]\)/g, (match, t) =>
+      t === activeTheme ? "[data-theme='light']" : `[data-theme='light'][data-theme-preset='${t}']`,
+    )
+    .replace(/:host\(\[theme='([^']+)'\]\[color-scheme='system'\]\)/g, (match, t) =>
+      t === activeTheme
+        ? "[data-theme='system']"
+        : `[data-theme='system'][data-theme-preset='${t}']`,
+    )
+    .replace(/:host\(\[theme='([^']+)'\]\)/g, (match, t) =>
+      t === activeTheme
+        ? `${scope}, [data-theme='dark']`
+        : `[data-theme='dark'][data-theme-preset='${t}']`,
+    )
+    .replace(/:host\(:not\(\[theme\]\)\[color-scheme='light'\]\)/g, "[data-theme='light']")
+    .replace(/:host\(:not\(\[theme\]\)\[color-scheme='system'\]\)/g, "[data-theme='system']")
+    .replace(/:host\(:not\(\[theme\]\)\)/g, `${scope}, [data-theme='dark']`)
+    .replace(/:host\(\[color-scheme='light'\]\)/g, "[data-theme='light']")
+    .replace(/:host\(\[color-scheme='dark'\]\)/g, "[data-theme='dark']")
+    .replace(/:host\(\[color-scheme='system'\]\)/g, "[data-theme='system']")
+    .replace(/:host\(:not\(\[color-scheme\]\)\)/g, `${scope}, [data-theme='dark']`)
+    .replace(/:host\b/g, scope);
+
+  return tokensCss;
+}
+
+export default getBundledCss;

package/src/styles/custom-styles.js

@@ -0,0 +1,8 @@
+import { css } from "lit";
+
+/*
+This file is reserved for any custom css that developers want to add to
+customize their theme. Simply add your css to this file and yarn build.
+*/
+
+export default css``;