rapidoc 12.0.0 → 12.1.0

package/src/components/README.md

@@ -0,0 +1,91 @@
+# RapiDoc Sub-Components
+
+## Overview
+
+Lit 3 elements that `<rapi-doc>` (and `@rapidoc/prerender`, which constructs the schema renderers
+directly) composes into each operation's request and response panels. Each file is a TypeScript
+class with `@customElement` / `@property` decorators and shadow DOM.
+
+This folder owns the request panel (parameters, body, Try, cURL, live response), the response
+panel, the schema tree/table renderers, the JSON example viewer and the tag editor. It does not own
+the surrounding templates (`../templates/`), styles (`../styles/`), or the parsing, URL, cURL and
+fetch helpers (`../utils/`). Callers: `../rapidoc.ts`, `../templates/*` and
+`../static/render.js` (`renderSchema` uses `SchemaTable` / `SchemaTree`).
+
+## Interface
+
+- `<api-request>` [api-request.ts:ApiRequest] — request panel; the only component that calls
+  `fetch`. Dispatches `before-try`, `after-try` and `request-aborted`.
+- `<api-response>` [api-response.ts:ApiResponse] — status buttons, MIME dropdown, Example/Schema
+  tabs, response headers. `resetSelection()` is called by `<rapi-doc>` when focused mode reuses one
+  instance. Dispatches no events.
+- `SchemaBaseElement` [schema-base-element.ts:SchemaBaseElement] — unregistered base class for the
+  schema renderers: config sync, hide rules, description cells, expand/collapse.
+- `<schema-tree>` [schema-tree.ts:SchemaTree] and `<schema-table>` [schema-table.ts:SchemaTable] —
+  render a schema AST (from `../utils/schema-utils.js`) as a bracketed tree or a
+  Field/Type/Description table via `renderAST(node, parentType, schemaLevel, indentLevel)`.
+- `<json-tree>` [json-tree.ts:JsonTree] — collapsible JSON viewer with a Copy button.
+- `<tag-input>` [tag-input.ts:TagInput] — tag editor for array-valued parameters; dispatches
+  `change` then `input` with `detail: { value }`.
+
+The `before-try`, `after-try`, `request-aborted`, `change` and `input` events are all
+`bubbles: true, composed: true`. Property lists, CSS parts and event detail fields are in the code.
+
+## Invariants
+
+- Flags passed from `<rapi-doc>` are strings, compared with `=== "true"` / `=== "false"`, not
+  booleans (`allowTry`, `showCurlBeforeTry`, `webhook`, `callback`, the `schema*` flags).
+- `<api-request>` omits the Try bar only when `allowTry === "false"`, and sets
+  `allowTry = "false"` after every update while `webhook === "true"`
+  [api-request.ts:ApiRequest.updated].
+- Config sync runs in `willUpdate` only when `config` is set and changed. `<api-request>` and
+  `<api-response>` map a defined `config.schemaHide*` of `"never"` to `"false"` and any other value
+  to the direction default (requests hide read-only, responses hide write-only; webhooks invert
+  both) [api-request.ts:ApiRequest.willUpdate; api-response.ts:ApiResponse.willUpdate].
+  `SchemaBaseElement` maps `"never"` to `"false"`, copies a literal `"true"` / `"false"`, and
+  otherwise keeps the value the template set [schema-base-element.ts:hideFlagFromConfig].
+- `SchemaBaseElement.willUpdate` resets a falsy or `< 1` `schemaExpandLevel` to `99999`, and
+  resets `schemaDescriptionExpanded` to `"false"` and either hide flag to `"true"` when the value
+  is not `"true"` or `"false"`.
+- `isFieldHidden(node)` hides read-only / write-only nodes per the hide flags, and `renderAST`
+  skips a hidden node's whole subtree [schema-base-element.ts:SchemaBaseElement.isFieldHidden].
+- A node starts expanded iff `schemaLevel < schemaExpandLevel`; children render at
+  `schemaLevel + 1`. Union options stay at the parent's level in `<schema-tree>` but go one level
+  deeper in `<schema-table>`.
+- Markdown descriptions are passed through `sanitizeHTML` before `unsafeHTML`; plain-text schema
+  descriptions skip markdown and rely on Lit escaping
+  [schema-base-element.ts:SchemaBaseElement.renderDescrCell; api-response.ts:ApiResponse].
+- Each Try gets its own `AbortController`; `before-try` listeners may change the request (`url`,
+  `method`, `headers`, `credentials`, `body`) before the `Request` is built, and `loading` is reset
+  in `finally` [api-request.ts:ApiRequest.onTryClick].
+- `<tag-input value="a,b">` is a comma-separated list: blank parts are dropped, values are not
+  trimmed, and removing the attribute sets `value` to `[]` [tag-input.ts:TagInput]. Events fire
+  only after user edits (paste, Enter, Backspace/Delete on an empty input, blur), never on
+  attribute or property sets.
+
+## Side Effects
+
+- Network: `ApiRequest.onTryClick` calls `fetch`; `disconnectedCallback` aborts an in-flight
+  request.
+- Object URLs for blob responses are revoked before each Try, in `clearResponseData`, and in
+  `disconnectedCallback` (they are created in `../utils/response-utils.js`).
+- `ApiRequest.updated` schedules `syncTryBarState` with `queueMicrotask` and calls
+  `scheduleHighlight` on the host's shadow root; example selection uses `window.setTimeout`.
+- `<api-request>` reads outside its shadow root: `buildFetchHeaders` takes `Accept` from the
+  sibling `<api-response>`'s `selectedMimeType` via `this.closest(...)`.
+- Direct DOM writes without reactive state: example fill/clear writes input values;
+  `<api-response>` toggles `.example` panel `display`; expand/collapse swaps classes.
+- Clipboard: `<json-tree>` copies JSON; `<tag-input>` reads pasted text and prevents the default.
+- `renderMarkdownDescription` keeps a module-level cache shared by all schema renderers, cleared
+  when it reaches 5000 entries [schema-base-element.ts:renderMarkdownDescription].
+- `willUpdate` overwrites reactive properties from `config`, so a `config` change replaces values
+  set by attribute.
+
+## Verification
+
+- Run `npm run test:unit` from the repo root (`tests/unit/*.test.js`, Node test runner).
+- Unit tests that render or load these components: `semantic-markup.test.js` (heading outline,
+  `exportparts`), `schema-modernization.test.js`, `schema-nullable.test.js`,
+  `multipart-form-curl.test.js` (`<tag-input>` converter), `static-renderer.test.js`;
+  `css-variables.test.js` checks every `var(--x)` read here is defined.
+- Template rendering is also covered by `npm run test:component` and `npm run test:e2e`.

package/src/components/api-request.ts

@@ -16,6 +16,7 @@ import {
   constructFetchHeaders,
   buildUrlEncodedBody,
   buildMultipartFormData,
+  serializeMultipartBody,
 } from "~/utils/request-utils";
 import { processFetchResponse } from "../utils/response-utils.js";
 import { inputParametersTemplate } from "~/templates/request-params-template";
@@ -78,6 +79,10 @@ export default class ApiRequest extends LitElement {
   @state() selectedRequestBodyExample = "";
   @state() fileInputKeys: any = {};
   @state() loading = false;
+  // Try-bar buttons follow the fields: Fill Example shows only when a field has an example,
+  // Clear is enabled only while a field holds a value
+  @state() hasExampleToFill = false;
+  @state() hasValueToClear = false;
 
   activeAbortController: any = null;
 
@@ -342,6 +347,8 @@ export default class ApiRequest extends LitElement {
 
   render() {
     return html`<div
+      @input="${this.syncTryBarState}"
+      @change="${this.syncTryBarState}"
       class="col regular-font request-panel ${
         "read focused".includes(this.renderStyle) || this.callback === "true"
           ? "read-mode"
@@ -379,6 +386,8 @@ export default class ApiRequest extends LitElement {
     if (this.webhook === "true") {
       this.allowTry = "false";
     }
+    // After the fields are in the DOM; deferred so the update is not requested mid-update
+    queueMicrotask(() => this.syncTryBarState());
   }
 
   // This method is called before navigation change in focused mode
@@ -452,6 +461,7 @@ export default class ApiRequest extends LitElement {
         }
       }
     });
+    this.syncTryBarState();
   }
 
   async onClearRequestData(e) {
@@ -462,6 +472,20 @@ export default class ApiRequest extends LitElement {
     requestPanelInputEls.forEach((el) => {
       el.value = "";
     });
+    this.syncTryBarState();
+  }
+
+  // Reads the request fields (the same ones Fill Example and Clear act on) and updates the
+  // try-bar flags; setting a flag to its current value schedules no render
+  syncTryBarState() {
+    const requestPanelEl = this.shadowRoot?.querySelector(".request-panel");
+    const inputEls: any[] = requestPanelEl
+      ? [...requestPanelEl.querySelectorAll("input, tag-input, textarea:not(.is-hidden)")]
+      : [];
+    this.hasExampleToFill = inputEls.some((el) => !!el.dataset.example);
+    this.hasValueToClear = inputEls.some((el) =>
+      Array.isArray(el.value) ? el.value.length > 0 : el.value !== "",
+    );
   }
 
   buildFetchURL(requestPanelEl) {
@@ -493,6 +517,7 @@ export default class ApiRequest extends LitElement {
         explode,
         allowReserved,
         isArray,
+        itemType: el.dataset.itemType || "",
       });
     });
 
@@ -582,6 +607,15 @@ export default class ApiRequest extends LitElement {
           isArray: el.dataset.array !== "false",
         }));
         fetchOptions.body = buildMultipartFormData(fields);
+        // Content-Type of the parts that need one (application/json for objects, or the spec's encoding)
+        const partContentTypes = Object.fromEntries(
+          formDataEls
+            .filter((el: any) => el.dataset.contentType)
+            .map((el: any) => [el.dataset.pname, el.dataset.contentType]),
+        );
+        if (Object.keys(partContentTypes).length > 0) {
+          fetchOptions.partContentTypes = partContentTypes;
+        }
       } else if (
         /^audio\/|^image\/|^video\/|^font\/|tar$|zip$|7z$|rtf$|msword$|excel$|\/pdf$|\/octet-stream$/.test(
           requestBodyType,
@@ -651,6 +685,14 @@ export default class ApiRequest extends LitElement {
       credentials: tempRequest.credentials,
       body: tempRequest.body,
     };
+    // FormData can't give a text part a Content-Type, so such bodies are serialized here
+    if (tempRequest.body instanceof FormData && tempRequest.partContentTypes) {
+      const multipart = serializeMultipartBody(tempRequest.body, tempRequest.partContentTypes);
+      const headers = new Headers(tempRequest.headers);
+      headers.set("Content-Type", multipart.contentType);
+      updatedFetchOptions.headers = headers;
+      updatedFetchOptions.body = multipart.body;
+    }
     let fetchRequest;
     let fetchResponse;
     let responseClone;
@@ -776,6 +818,7 @@ export default class ApiRequest extends LitElement {
       headers: fetchHeaders,
       body,
       contentType: requestBodyType,
+      partContentTypes: fetchOptions?.partContentTypes,
     });
   }
 

package/src/components/api-response.ts

@@ -4,6 +4,7 @@ import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { sanitizeHTML } from "../utils/sanitize.js";
 import { marked } from "marked";
 import { prepareResponseDefinitions } from "../utils/response-utils.js";
+import { exampleLabel } from "~/utils/schema-utils";
 import FontStyles from "~/styles/font-styles";
 import FlexStyles from "~/styles/flex-styles";
 import ParamListStyles from "~/styles/param-list-styles";
@@ -435,11 +436,16 @@ export default class ApiResponse extends LitElement {
             }`
           : html`
               <div class="example-panel">
-                <select aria-label="response examples" class="select-sm example-select" @change="${(e) => this.onSelectExample(e)}">
+                <select
+                  aria-label="response examples"
+                  class="select-sm example-select"
+                  title="${exampleLabel(mimeRespDetails.examples.find((v) => v.exampleId === mimeRespDetails.selectedExample))}"
+                  @change="${(e) => this.onSelectExample(e)}"
+                >
                   ${mimeRespDetails.examples.map(
                     (v) =>
-                      html`<option value="${v.exampleId}" ?selected=${v.exampleId === mimeRespDetails.selectedExample}>
-                        ${v.exampleSummary.length > 80 ? v.exampleId : v.exampleSummary}
+                      html`<option value="${v.exampleId}" title="${exampleLabel(v)}" ?selected=${v.exampleId === mimeRespDetails.selectedExample}>
+                        ${exampleLabel(v)}
                       </option>`,
                   )}
                 </select>
@@ -450,7 +456,6 @@ export default class ApiResponse extends LitElement {
                       data-example="${v.exampleId}"
                       style="display: ${v.exampleId === mimeRespDetails.selectedExample ? "block" : "none"}"
                     >
-                      ${v.exampleSummary && v.exampleSummary.length > 80 ? html`<div style="padding: 4px 0">${v.exampleSummary}</div>` : ""}
                       ${
                         v.exampleDescription
                           ? html`<div class="m-markdown-small" style="padding: 4px 0">

package/src/components/schema-base-element.ts

@@ -56,6 +56,16 @@ function renderMarkdownDescription(text, title) {
   return rendered;
 }
 
+/**
+ * The host's `schema-hide-*` flags are `"default"` | `"never"`: `"never"` shows the fields, `"default"` keeps
+ * the `"true"` | `"false"` the template chose for this element (requests hide read-only, responses write-only).
+ */
+function hideFlagFromConfig(configValue, current) {
+  if (configValue === "never") return "false";
+  if (configValue === "true" || configValue === "false") return configValue;
+  return current;
+}
+
 export default class SchemaBaseElement extends LitElement {
   @property({ type: Object }) config: any;
   @property({ type: Object }) data: any;
@@ -76,10 +86,14 @@ export default class SchemaBaseElement extends LitElement {
         this.schemaDescriptionExpanded = this.config.schemaDescriptionExpanded;
       if (this.config.allowSchemaDescriptionExpandToggle !== undefined)
         this.allowSchemaDescriptionExpandToggle = this.config.allowSchemaDescriptionExpandToggle;
-      if (this.config.schemaHideReadOnly !== undefined)
-        this.schemaHideReadOnly = this.config.schemaHideReadOnly;
-      if (this.config.schemaHideWriteOnly !== undefined)
-        this.schemaHideWriteOnly = this.config.schemaHideWriteOnly;
+      this.schemaHideReadOnly = hideFlagFromConfig(
+        this.config.schemaHideReadOnly,
+        this.schemaHideReadOnly,
+      );
+      this.schemaHideWriteOnly = hideFlagFromConfig(
+        this.config.schemaHideWriteOnly,
+        this.schemaHideWriteOnly,
+      );
     }
     if (!this.schemaExpandLevel || this.schemaExpandLevel < 1) {
       this.schemaExpandLevel = 99999;

package/src/components/schema-table.ts

@@ -150,6 +150,25 @@ export default class SchemaTable extends SchemaBaseElement {
             }
           }
         }
+
+        /* Narrow schemas: the description spans the row, under the field and type, with no column of its own (#1074) */
+        @container (width < 500px) {
+          .table {
+            /* no column for descriptions, and field and type share the width instead of scrolling sideways */
+            & .table-container {
+              grid-template-columns: minmax(0, 1fr) minmax(0, max-content) 0;
+            }
+            & .tr > .key-descr {
+              grid-column: 1 / -1;
+            }
+            & .table-header > .key-descr {
+              display: none;
+            }
+            &.collapsed-all-descr .tr:not(.expanded-descr) {
+              max-height: calc(2 * (var(--font-size-small) + 16px));
+            }
+          }
+        }
       `,
       CustomStyles,
     ];
@@ -390,18 +409,29 @@ export default class SchemaTable extends SchemaBaseElement {
           ${this.renderDescrCell(node.description)}
         </div>
         <div class="object-body">
-          ${node.options?.map(
-            (opt, i) => html`
-              <div class="tr expanded xxx-of-option" data-obj="OPTION ${opt.optionIndex || i + 1}">
-                <div class="td key" style="padding-left:${leftPadding + 16}px">
-                  <span class="xxx-of-key">OPT ${opt.optionIndex || i + 1}</span>
-                  ${opt.optionTitle ? html`<span class="xxx-of-descr">${opt.optionTitle}</span>` : ""}
-                </div>
-                <div class="td key-type"></div>
-                <div class="td key-descr"></div>
-              </div>
-              <div class="object-body">${this.renderAST(opt, "xxx-of-option", schemaLevel + 1, indentLevel + 1)}</div>
-            `,
+          ${node.options?.map((opt, i) =>
+            opt.kind === "primitive"
+              ? // A primitive option fits on a single row: the badge, then its type and description
+                html`<div class="object-body">
+                  ${this.renderAST(opt, "xxx-of-option", schemaLevel + 1, indentLevel + 1)}
+                </div>`
+              : html`
+                  <div class="tr expanded xxx-of-option" data-obj="OPTION ${opt.optionIndex || i + 1}">
+                    <div class="td key" style="padding-left:${leftPadding + 16}px">
+                      <span class="xxx-of-key">OPT ${opt.optionIndex || i + 1}</span>
+                      ${
+                        opt.optionTitle
+                          ? html`<span class="xxx-of-descr">${opt.optionTitle}</span>`
+                          : ""
+                      }
+                    </div>
+                    <div class="td key-type"></div>
+                    <div class="td key-descr"></div>
+                  </div>
+                  <div class="object-body">
+                    ${this.renderAST(opt, "xxx-of-option", schemaLevel + 1, indentLevel + 1)}
+                  </div>
+                `,
           )}
         </div>
       `;
@@ -410,11 +440,26 @@ export default class SchemaTable extends SchemaBaseElement {
     // 4. Primitive kind
     if (node.kind === "primitive") {
       const dataTypeCss = this.getDataTypeCss(node.type);
+      // Primitive option of a oneOf / anyOf: the OPT n badge (and the title) takes the place of the name
+      const isOption = parentType === "xxx-of-option" && !!node.optionIndex;
 
       return html`
         <div class="tr primitive ${nullClass}" title="${node.deprecated ? "Deprecated" : nothing}">
           <div class="td key ${node.deprecated ? "deprecated" : ""}" style="padding-left:${leftPadding}px">
-            ${deprecatedIcon}${node.name ? html`<span class="key-label" title="${node.name}">${node.name}</span>` : ""}
+            ${
+              isOption
+                ? html`<span class="xxx-of-key">OPT ${node.optionIndex}</span
+                  >${
+                    node.optionTitle
+                      ? html`<span class="xxx-of-descr">${node.optionTitle}</span>`
+                      : ""
+                  }`
+                : ""
+            }${deprecatedIcon}${
+              node.name && !isOption
+                ? html`<span class="key-label" title="${node.name}">${node.name}</span>`
+                : ""
+            }
             ${node.required ? html`<span style="color:var(--destructive);">*</span>` : ""}
           </div>
           <div class="td key-type ${dataTypeCss}" title="${readWriteTip || nothing}">

package/src/components/schema-tree.ts

@@ -76,6 +76,13 @@ export default class SchemaTree extends SchemaBaseElement {
           }
         }
 
+        /* Narrow schemas: a collapsed row holds its field line and the description's line under it (#1074) */
+        @container (width < 500px) {
+          .tree.collapsed-all-descr .tr:not(.expanded-descr) {
+            max-height: calc(2 * (var(--font-size-small) + 8px));
+          }
+        }
+
         .inside-bracket {
           &.xxx-of-option {
             border-left: 1px solid transparent;

package/src/components/tag-input.ts

@@ -8,6 +8,11 @@ export default class TagInput extends LitElement {
   @property({
     type: Array,
     attribute: "value",
+    converter: {
+      // `value="a,b"` is a comma-separated list, not the JSON Lit's Array converter expects
+      fromAttribute: (value) => (value ? value.split(",").filter((v) => v.trim() !== "") : []),
+      toAttribute: (value) => (Array.isArray(value) ? value.join(",") : value),
+    },
     hasChanged(newVal, oldVal) {
       if (newVal === oldVal) return false;
       if (!Array.isArray(newVal) || !Array.isArray(oldVal)) return true;
@@ -48,15 +53,6 @@ export default class TagInput extends LitElement {
     }
   }
 
-  attributeChangedCallback(name, oldVal, newVal) {
-    if (name === "value") {
-      if (newVal && oldVal !== newVal) {
-        this.value = newVal.split(",").filter((v) => v.trim() !== "");
-      }
-    }
-    super.attributeChangedCallback(name, oldVal, newVal);
-  }
-
   dispatchEvents() {
     this.dispatchEvent(
       new CustomEvent("change", { bubbles: true, composed: true, detail: { value: this.value } }),

package/src/flow.js

@@ -0,0 +1,3 @@
+import RapiFlow from "~/rapi-flow";
+
+export default RapiFlow;