nmdc-runtime 1.3.1__py3-none-any.whl → 2.12.0__py3-none-any.whl

nmdc_runtime/api/swagger_ui/assets/EndpointSearchWidget.js

@@ -0,0 +1,369 @@
+/**
+ * This JavaScript file contains the implementation of a Web Component designed for use with Swagger UI.
+ * Reference: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
+ *
+ * Developer notes:
+ * 
+ * 1. Because we define our CSS and HTML within `String.raw` tagged templates [1],
+ *    the popular "lit-html" extension [2] (if installed) for VS Code will apply
+ *    CSS and HTML syntax highlighting to those strings.
+ * 
+ *    References:
+ *    - [1] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals
+ *    - [2] https://marketplace.visualstudio.com/items?itemName=bierner.lit-html
+ *
+ *****************************************************************************/
+
+// If FastAPI's Swagger UI JavaScript hasn't been executed yet, throw an error explaining the situation.
+// Note: FastAPI runs the Swagger UI JavaScript in a way that creates a global variable named `ui`.
+// Note: We do a `typeof` check because, if we did `ui === undefined` and `ui` weren't defined,
+//       JavaScript would raise its own `ReferenceError` exception with its own message.
+if (typeof ui === "undefined") {
+    throw new Error("FastAPI's Swagger UI JavaScript has not been executed yet.");
+}
+
+/**
+ * Endpoint search widget, implemented as a Web Component.
+ * 
+ * The widget provides a search input field, and a results panel that lists
+ * the API endpoints whose URL paths match the search term. When the user
+ * clicks on a search result, the browser navigates to the corresponding
+ * endpoint in the Swagger UI page (via a full page refresh/"deep link").
+ *
+ * References:
+ * - https://developer.mozilla.org/en-US/docs/Web/API/Web_components
+ * - https://open-wc.org/codelabs/basics/web-components#2
+ */
+class EndpointSearchWidget extends HTMLElement {
+    constructor() {
+        super();
+
+        // Initialize all instance properties.
+        this.inputEl = null;
+        this.resultsPanelEl = null;
+        this.noEndpointsMessageEl = null;
+        this.resultsListEl = null;
+        this.endpoints = [];
+
+        // Redefine each callback method so that, within that method, the "this" variable
+        // refers to this instance of the class.
+        //
+        // Note: If we didn't do this, the value of the "this" variable would depend upon how
+        //       the method was invoked (e.g. if invoked via an event listener, the "this"
+        //       variable would refer to the element that triggered the event; e.g. a text field).
+        //
+        // Reference:
+        // - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind#creating_a_bound_function
+        //
+        this._handleInput = this._handleInput.bind(this);
+    }
+
+    /**
+     * Initializes the custom HTML element after it's been added to the DOM.
+     * 
+     * Note: The `connectedCallback` function gets called automatically when
+     *       this HTML element gets added to the DOM.
+     * 
+     * References:
+     * - https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+     */
+    connectedCallback() {
+        // Create a Shadow DOM tree specific to this custom HTML element, so that its styles don't
+        // impact other elements on the page and so styles on the page don't impact this element. [1]
+        //
+        // Note: This will populate the instance's inherited `this.shadowRoot` property [2]
+        //       with a reference to the root node of this Shadow DOM tree. [3]
+        //
+        // References: 
+        // - [1] https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#creating_a_shadow_dom
+        // - [2] https://developer.mozilla.org/en-US/docs/Web/API/Element/shadowRoot
+        // - [3] https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot
+        //
+        this.attachShadow({ mode: "open" });
+
+        // Implement the structure and style of the widget.
+        //
+        // Note: We chose the specific style rules shown below in an attempt to
+        //       match the "look and feel" of the Swagger UI page. At least some
+        //       of the seemingly-arbitrarily-chosen values were copied verbatim
+        //       from native Swagger UI elements (via a web browser's DevTools).
+        //
+        this.shadowRoot.innerHTML = String.raw`
+            <style>
+                :host {
+                    display: block;
+                    margin: 0 auto;
+                    max-width: 1460px;
+                    font-family: sans-serif;
+                    font-size: 14px;
+                    color: #3b4151;
+                }
+                .container {
+                    margin: 20px 20px 0px 20px;
+                }
+                input {
+                    padding: 8px 10px;
+                    box-sizing: border-box;
+                    border: 1px solid #d9d9d9;
+                    border-radius: 4px;
+                    width: 100%;
+                }
+                .results-panel {
+                    background-color: rgba(0, 0, 0, .05);
+                    border-radius: 4px;
+                }
+                .results-panel p.no-endpoints {
+                    font-size: 14px;
+                    padding: 26px;
+                }
+                ul {
+                    list-style-type: none;
+                    padding-left: 26px;
+                    padding-right: 26px;
+                    font-family: monospace;
+                }
+                ul > li:first-child {
+                    padding-top: 26px;
+                }
+                ul > li:last-child {
+                    padding-bottom: 26px;
+                }
+                li > a {
+                    color: #4990e2;
+                    text-decoration: none;
+                }
+                li > a:hover {
+                    color: #1f69c0;
+                }
+                li > a .http-method {
+                    display: inline-block;
+                    min-width: 52px;
+                    margin-right: 10px;
+                }
+                .matching-substring {
+                    background-color: #f9f871;
+                }
+                .hidden {
+                    /* 
+                    Note: When we hide elements via 'display: none', we do not have to also set 'aria-hidden="true"'.
+                    MDN says: 'aria-hidden="true" should not be added when [...] The element [...] is hidden with 'display: none'.
+                    Reference: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden
+                    */
+                    display: none;
+                }
+            </style>
+
+            <div class="container">
+                <input name="search-term" placeholder="Find an endpoint..." aria-label="Search term for finding an endpoint" />
+                <div class="results-panel">
+                    <p class="no-endpoints hidden">No matching endpoints.</p>
+                    <ul class="results-list"></ul>
+                </div>
+            </div>
+        `;
+        this.inputEl = this.shadowRoot.querySelector("input");
+        this.resultsPanelEl = this.shadowRoot.querySelector(".results-panel");
+        this.noEndpointsMessageEl = this.shadowRoot.querySelector(".no-endpoints");
+        this.resultsListEl = this.shadowRoot.querySelector(".results-list");
+
+        // Make an array of all the endpoints that Swagger UI knows about. This will be our search index.
+        //
+        // Note: In an earlier implementation of this step, we queried the DOM for this information.
+        //       However, that didn't work when any of the endpoint groups were collapsed. So, instead,
+        //       we access the data structure returned by the `SwaggerUI()` constructor, which is
+        //       invoked by the JavaScript code built into FastAPI (that JavaScript code assigns
+        //       the return value to a global variable named `ui`, which we access here).
+        //
+        // Note: Should we eventually choose to display endpoint's description also, we can be obtain it
+        //       via the endpoint's operation Map; i.e. `opMap.get("operation").get("description")`.
+        //
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get
+        //
+        const operationMaps = Array.from(ui.specSelectors.operations());
+        this.endpoints = operationMaps.map(opMap => ({
+            urlPath: opMap.get("path"), // e.g. "/studies/{study_id}"
+            httpMethod: opMap.get("method").toUpperCase(), // e.g. "GET"
+            operationId: opMap.get("operation").get("operationId"), // e.g. "find_studies_studies_get"
+            tag: opMap.get("operation").get("tags").get(0), // e.g. "Metadata access: Find"
+        }));
+        console.debug(`Found ${this.endpoints.length} endpoints in OpenAPI schema`);
+
+        // Make it so the search results list gets updated whenever the user changes the search input.
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event
+        this.inputEl.addEventListener("input", this._handleInput);
+    }
+
+    /**
+     * Callback function that handles the "input" event on the endpoint search input field.
+     * The main role of this method is to extract the search term from the event object
+     * and pass it to the method that updates the search results to reflect that search term.
+     * 
+     * @param {Event} event The "input" event.
+     */
+    _handleInput(event) {
+        this.updateSearchResults(event.target.value);
+    }
+
+    /**
+     * Callback function designed to be passed in as the `compareFn` argument to `Array.prototype.sort()`.
+     * This callback function that sorts endpoint objects by comparing the URL paths and, if those are
+     * equal, comparing the HTTP methods.
+     * 
+     * @param {{ urlPath: string, httpMethod: string }} a 
+     * @param {{ urlPath: string, httpMethod: string }} b 
+     * @returns {number} A negative number if `a` comes before `b`,
+     *                   a positive number if `a` comes after `b`,
+     *                   and 0 if `a` and `b` are equivalent.
+     * 
+     * References:
+     * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#comparefn
+     * - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare
+     */
+    _sortEndpoints(a, b) {
+        if (a.urlPath.localeCompare(b.urlPath) === 0) {
+            return a.httpMethod.localeCompare(b.httpMethod);
+        } else {
+            return a.urlPath.localeCompare(b.urlPath);
+        }
+    }
+
+    /**
+     * Wraps the part of the full string that matches the test string (case insensitively),
+     * in a `<span>` element having the class "matching-substring".
+     * 
+     * Note: That will allow us to style that part of the string differently from the other parts.
+     * 
+     * @param {string} fullStr The full string.
+     * @param {string} searchTermStr The string to search for within the full string.
+     * @returns {HTMLSpanElement} A `<span>` element containing the full string, with the matching
+     *                            substring—if any—wrapped in a `<span class="matching-substring">`.
+     */
+    _wrapMatchingSubstring(fullStr, searchTermStr) {
+        // Create the outer `<span>` element.
+        const fullStrSpanEl = document.createElement("span");
+        
+        // Return early if we know the search term string _cannot_ exist within the full string.
+        if (fullStr.length === 0 || searchTermStr.length === 0 || searchTermStr.length > fullStr.length) {
+            fullStrSpanEl.textContent = fullStr;
+            return fullStrSpanEl;
+        }
+        
+        // Lowercase both strings to enable case-insensitive comparison.
+        const fullStrLowercase = fullStr.toLowerCase();
+        const searchTermStrLowercase = searchTermStr.toLowerCase();
+        
+        // Locate the (lowercased) substring within the (lowercased) full string.
+        const substrCharIdx = fullStrLowercase.indexOf(searchTermStrLowercase);
+        
+        // Return early if we know the search term string _doesn't_ exist within the full string.
+        if (substrCharIdx === -1) {
+            fullStrSpanEl.textContent = fullStr;
+            return fullStrSpanEl;
+        }
+        
+        // Split the full string into three parts.
+        const preSubstrChars = fullStr.substring(0, substrCharIdx);
+        const substringChars = fullStr.substring(substrCharIdx, substrCharIdx + searchTermStr.length)
+        const postSubstrChars = fullStr.substring(substrCharIdx + searchTermStr.length);
+        
+        // Create and populate the inner `<span>` element containing the matching substring.
+        const matchingSubstrSpanEl = document.createElement("span");
+        matchingSubstrSpanEl.classList.add("matching-substring");
+        matchingSubstrSpanEl.textContent = substringChars;
+
+        // Populate the outer `<span>` element.
+        fullStrSpanEl.replaceChildren(preSubstrChars, matchingSubstrSpanEl, postSubstrChars);
+        return fullStrSpanEl;
+    }
+
+    /**
+     * Returns a Swagger UI-compliant "Deep Link" URL pointing to the specific API endpoint
+     * on a Swagger UI page.
+     * 
+     * @param {string} tagNameStr Name of the tag of the endpoint being linked to.
+     * @param {string} operationIdStr Operation ID of the endpoint being linked to.
+     * @returns {string} A Swagger UI-compliant "Deep Link" URL that points to the
+     *                   specified API endpoint on a Swagger UI page.
+     * 
+     * Reference: https://swagger.io/docs/open-source-tools/swagger-ui/usage/deep-linking/#usage
+     */
+    _buildSwaggerUIDeepLinkUrl(tagNameStr, operationIdStr) {
+        const urlWithoutQueryStr = window.location.origin + window.location.pathname;
+        const encodedTagNameStr = encodeURIComponent(tagNameStr);
+        const encodedOperationIdPart = encodeURIComponent(operationIdStr);
+        return `${urlWithoutQueryStr}/#${encodedTagNameStr}/${encodedOperationIdPart}`;
+    }
+
+    /**
+     * Updates the search results list so it shows the endpoints whose URL paths contain the search term.
+     * 
+     * @param {string} searchTerm The search term.
+     */
+    updateSearchResults(searchTerm) {
+        // Special case: If the search term is empty, clear the search results.
+        if (searchTerm.trim().length === 0) {
+            this.resultsListEl.replaceChildren();
+            this.noEndpointsMessageEl.classList.add("hidden");
+            return;
+        }
+
+        // Lowercase the search term to enable case-insensitive comparison.
+        const lowercaseSearchTerm = searchTerm.toLowerCase();
+        
+        // Make a list of all endpoints whose URL paths contains the search term.
+        const matchingEndpoints = this.endpoints.filter(item => {
+            const lowercaseUrlPath = item.urlPath.toLowerCase();
+            return lowercaseUrlPath.includes(lowercaseSearchTerm);
+        });
+        
+        // If there are no matching endpoints, clear the search results.
+        if (matchingEndpoints.length === 0) {
+            this.resultsListEl.replaceChildren();
+            this.noEndpointsMessageEl.classList.remove("hidden");
+            return;
+        } else {
+            this.noEndpointsMessageEl.classList.add("hidden");
+        }
+
+        // Make an array of hyperlinks to the matching endpoints.
+        const resultEls = matchingEndpoints.sort(this._sortEndpoints).map(matchingEndpoint => {
+            // Wrap the part of the URL path that matches the search term, so that we can
+            // style it differently from the rest of the URL path.
+            const urlPathSpanEl = this._wrapMatchingSubstring(matchingEndpoint.urlPath, lowercaseSearchTerm);
+            
+            // Build a hyperlink that points to the matching endpoint.
+            //
+            // Note: The reason we don't use something like `scrollTo` or `scrollIntoView`
+            //       is that the target element may not be mounted to the DOM right now,
+            //       due to it being within a collapsed section. Instead, we send the
+            //       browser to the "deep link" URL (Swagger UI will automatically expand
+            //       the relevant section when the page loads that "deep link" URL).
+            //
+            const aEl = document.createElement("a");
+            const httpMethodSpanEl = document.createElement("span");
+            httpMethodSpanEl.classList.add("http-method");  // e.g. "<span class="http-method">GET</span>"
+            httpMethodSpanEl.textContent = matchingEndpoint.httpMethod;
+            aEl.href = this._buildSwaggerUIDeepLinkUrl(matchingEndpoint.tag, matchingEndpoint.operationId);
+            aEl.replaceChildren(httpMethodSpanEl, urlPathSpanEl);
+            
+            // Return a list item consisting of the hyperlink.
+            const liEl = document.createElement("li");
+            liEl.replaceChildren(aEl);
+            return liEl;
+        });
+        this.resultsListEl.replaceChildren(...resultEls);
+    }
+
+    /**
+     * Callback function that will be automatically invoked when the element is removed from the DOM.
+     * 
+     * References:
+     * - https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+     */
+    disconnectedCallback() {
+        console.debug("Cleaning up event listener(s)");
+        if (this.inputEl !== null) {
+            this.inputEl.removeEventListener("input", this._handleInput);
+        }
+    }
+}

nmdc_runtime/api/swagger_ui/assets/script.js

@@ -0,0 +1,252 @@
+console.debug("Listening for event: nmdcInit");
+window.addEventListener("nmdcInit", (event) => {
+    console.debug("Detected event: nmdcInit");
+
+    // Get the DOM elements we'll be referencing below.
+    const bodyEl = document.querySelector("body");
+
+    // Add the NMDC logo to the top of the page, next to the title.
+    // Note: The logo image will be added as a background image via CSS.
+    const addLogo = () => {
+        console.debug("Adding logo");
+        const headingGroupEl = document.querySelector(".information-container hgroup.main");
+        const titleEl = headingGroupEl.querySelector(".title");
+        const openapiSchemaLinkEl = headingGroupEl.querySelector("a.link");
+        const titleWrapperEl = document.createElement("div");
+        const logoEl = document.createElement("div");
+        logoEl.classList.add("nmdc-logo");
+        headingGroupEl.classList.add("nmdc-heading-group");
+        titleWrapperEl.replaceChildren(titleEl, openapiSchemaLinkEl);
+        headingGroupEl.replaceChildren(logoEl, titleWrapperEl);
+    };
+    addLogo();
+
+    // If there is a non-empty access token present in the DOM (see `main.py`), create and add a banner
+    // displaying the token along with buttons to show/hide it and copy it to the clipboard.
+    const accessToken = document.getElementById("nmdc-access-token")?.getAttribute("data-token");
+    if (typeof accessToken === "string" && accessToken.trim().length > 0) {
+        console.debug("Adding token banner");
+
+        // Create the banner.
+        const sectionEl = document.createElement("section");
+        sectionEl.classList.add("nmdc-info", "nmdc-info-token", "block", "col-12");
+        sectionEl.innerHTML = `
+            <p>You are now authorized. Prefer a command-line interface (CLI)? Use this header for HTTP requests:</p>
+            <p>
+                <code>
+                    <span>Authorization: Bearer </span>
+                    <span id="token" data-state="masked">***</span>
+                </code>
+            </p>
+            <p>
+                <button id="token-mask-toggler">Show token</button>
+                <button id="token-copier">Copy token</button>
+                <span id="token-copier-message"></span>
+            </p>
+        `;
+
+        // Mount the banner to the DOM.
+        document.querySelector(".information-container").append(sectionEl);
+
+        // Get references to DOM elements within the banner that was mounted to the DOM.
+        const tokenMaskTogglerEl = document.getElementById("token-mask-toggler");
+        const tokenEl = document.getElementById("token");
+        const tokenCopierEl = document.getElementById("token-copier");
+        const tokenCopierMessageEl = document.getElementById("token-copier-message");
+
+        // Set up the token visibility toggler.
+        console.debug("Setting up token visibility toggler");
+        tokenMaskTogglerEl.addEventListener("click", (event) => {
+            if (tokenEl.dataset.state == "masked") {
+                console.debug("Unmasking token");
+                tokenEl.dataset.state = "unmasked";
+                tokenEl.textContent = accessToken;
+                event.target.textContent = "Hide token";
+            } else {
+                console.debug("Masking token");
+                tokenEl.dataset.state = "masked";
+                tokenEl.textContent = "***";
+                event.target.textContent = "Show token";
+            }
+        });
+
+        // Set up the token copier.
+        // Reference: https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText
+        console.debug("Setting up token copier");
+        tokenCopierEl.addEventListener("click", async (event) => {
+            tokenCopierMessageEl.textContent = "";
+            try {
+                await navigator.clipboard.writeText(accessToken);
+                tokenCopierMessageEl.innerHTML = "<span class='nmdc-success'>Copied to clipboard</span>";
+            } catch (error) {
+                console.error(error.message);
+                tokenCopierMessageEl.innerHTML = "<span class='nmdc-error'>Copying failed</span>";
+            }
+        });
+    }
+
+    /**
+     * Customizes the login form in the following ways:
+     * - Changes the header text of the username/password login form to "User login".
+     * - Changes the header text of the client credentials login form to "Site client login".
+     * - Augments the "Logout" button on the `bearerAuth` login form so that, when it is clicked,
+     *   it clears and expires the `user_id_token` cookie, and reloads the web page.
+     * - Focuses on the username input field whenever the login form appears.
+     * - Adds a "Login with ORCID" widget to the login form.
+     * 
+     * Reference: https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie
+     * 
+     * Prerequisite: The login form must be present in the DOM.
+     */
+    const customizeLoginForm = () => {
+        const modalContentEl = document.querySelector('.auth-wrapper .modal-ux-content');
+        const formHeaderEls = modalContentEl.querySelectorAll('.auth-container h4');
+        formHeaderEls.forEach(el => {
+            switch (el.textContent.trim()) {
+                case "OAuth2PasswordOrClientCredentialsBearer (OAuth2, password)":
+                    console.debug(`Customizing "password" login form header`);
+                    el.textContent = "User login";
+                    break;
+                case "OAuth2PasswordOrClientCredentialsBearer (OAuth2, clientCredentials)":
+                    console.debug(`Customizing "clientCredentials" login form header`);
+                    el.textContent = "Site client login";
+                    break;
+                // Note: This string has a `U+00a0` character before the regular space.
+                case "bearerAuth  (http, Bearer)":
+                    const buttonEls = el.closest(".auth-container").querySelectorAll("button");
+                    buttonEls.forEach(buttonEl => {
+                        if (buttonEl.textContent.trim() === "Logout") {
+                            console.debug(`Augmenting "bearerAuth" form logout button`);
+                            buttonEl.addEventListener("click", () => {
+                                console.debug("Clearing and expiring `user_id_token` cookie");
+                                document.cookie = "user_id_token=; max-age=0; path=/;";
+                                // Reload the web page so that any in-memory authentication state is reset.
+                                // Note: If we had full control over the Swagger UI code, we would just
+                                //       manipulate that state directly instead of reloading the page.
+                                console.debug("Reloading web page");
+                                window.location.reload();
+                            });
+                        }
+                    });
+                    break;
+                default:
+                    console.debug(`Unrecognized header: ${el.textContent}`);
+            }
+        });
+        // Add a "Login with ORCID" widget to the login form.
+        //
+        // TODO: Consider disabling this when the user is already logged in.
+        //
+        // TODO: Consider moving this up next to (or into) the regular "User login" form,
+        //       once our system administrators have implemented a practical process for
+        //       managing "allowances" of users whose usernames are ORCID IDs. Putting it
+        //       at the bottom of the modal (I think) makes it less likely people will use it.
+        //
+        console.debug("Adding ORCID Login widget to login form");
+        const orcidLoginUrl = document.getElementById("nmdc-orcid-login-url")?.getAttribute("data-url");
+        const orcidLoginWidgetEl = document.createElement("div");
+        orcidLoginWidgetEl.classList.add("auth-container", "nmdc-orcid-login");
+        orcidLoginWidgetEl.innerHTML = `
+            <h4>User login with ORCID</h4>
+            <div class="nmdc-orcid-login-icon-link">
+                <img src="/static/ORCID-iD_icon_vector.svg" height="16" width="16"/>
+                <a href="${orcidLoginUrl}">Login with ORCID</a>
+            </div>
+        `;
+        modalContentEl.appendChild(orcidLoginWidgetEl);
+
+        console.debug("Focusing on username field if present");
+        const usernameInputEl = modalContentEl.querySelector("input#oauth_username");
+        if (usernameInputEl !== null) {
+            usernameInputEl.focus();
+        }
+    };
+    console.debug("Setting up event listener for customizing login form");
+    //
+    // Listen for a "click" event on the `body` element, check whether the element that was clicked
+    // was the "Authorize" button (or one of its descendants), and if so, customize the modal login
+    // form that will have been mounted to the DOM by the time the "click" event propagated to the
+    // `body` element and our event handler was called.
+    //
+    // Note: We attach this event listener to the `body` element because that's the lowest-level
+    //       element where we found that mounting it doesn't cause our event handler to run too early
+    //       (i.e. doesn't cause it to run _before_ the event handlers that mount the modal login form
+    //       to the DOM have run). Our event handler needs that form to be mounted so it can access
+    //       its elements.
+    //       
+    //       If we were to attach it to a lower-level element (e.g. directly to the "Authorize" button),
+    //       we would have to, for example, make its body a `setTimeout(fn, 0)` callback in order to
+    //       defer its execution until all the event handlers for the "click" even have run.
+    //
+    bodyEl.addEventListener("click", (event) => {
+        // Check whether the clicked element was the "Authorize" button or any of its descendants.
+        if (event.target.closest(".auth-wrapper > .btn.authorize:not(.modal-btn)") !== null) {
+            customizeLoginForm();
+        }
+    });
+
+    // If the `EllipsesButton` class is defined, define a corresponding custom HTML element
+    // and set up the tag description details togglers.
+    // Docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_a_custom_element
+    //
+    // If the `<ellipses-button>` custom HTML element is available, set up the tag
+    // description details togglers.
+    //
+    // Note: At the time of this writing, all of our tag descriptions begin with a
+    //       single-paragraph summary of the tag. Some of the tag descriptions have
+    //       additional paragraphs that provide more _details_ about the tag. In an
+    //       attempt to keep the Swagger UI page "initially concise" (only showing
+    //       more information when the user requests it), for the tag descriptions
+    //       that have additional paragraphs, we add a toggler button that the user
+    //       can press to toggle the visibility of the additional paragraphs.
+    //
+    if (typeof EllipsesButton === "function") {
+        console.debug("Setting up tag description details togglers");
+        customElements.define("ellipses-button", EllipsesButton);
+        const tagSectionEls = bodyEl.querySelectorAll(".opblock-tag-section");
+        Array.from(tagSectionEls).forEach(el => {
+
+            // Check whether the description contains more than one element (i.e. paragraph).
+            const descriptionEl = el.querySelector("h3 > small > .renderedMarkdown");
+            if (descriptionEl.children.length > 1) {
+
+                // Wrap the additional elements (i.e. paragraphs) in a hidable `<div>`.
+                const detailsEl = document.createElement("div");
+                detailsEl.classList.add("tag-description-details", "hidden");
+                Array.from(descriptionEl.children).slice(1).forEach(el => {
+                    detailsEl.appendChild(el);
+                });
+                descriptionEl.replaceChildren(descriptionEl.firstChild, detailsEl);
+
+                // Add a button that, when clicked, toggles the visibility of the tag
+                // description details (but does not propagate the click event upward,
+                // so the visibility of the containing tag section isn't toggled).
+                const toggleButtonEl = document.createElement("ellipses-button");
+                toggleButtonEl.textContent = "Show details"; // populates the "slot"
+                descriptionEl.firstChild.appendChild(toggleButtonEl);
+                toggleButtonEl.addEventListener("click", (event) => {
+                    detailsEl.classList.toggle("hidden");
+                    event.stopPropagation();
+
+                    // Update the button's "is-open" attribute so the button's icon changes.
+                    if (toggleButtonEl.getAttribute("is-open") === "true") {
+                        toggleButtonEl.setAttribute("is-open", "false");
+                        toggleButtonEl.textContent = "Show details";
+                    } else {
+                        toggleButtonEl.setAttribute("is-open", "true");
+                        toggleButtonEl.textContent = "Hide details";
+                    }
+                });
+            }
+        });
+    };
+
+    // If the `EndpointSearchWidget` class is defined, define a corresponding custom HTML element and add it to the DOM.
+    // Docs: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#using_a_custom_element
+    if (typeof EndpointSearchWidget === "function") {
+        console.debug("Setting up endpoint search widget");
+        customElements.define("endpoint-search-widget", EndpointSearchWidget);
+        const endpointSearchWidgetEl = document.createElement("endpoint-search-widget");
+        bodyEl.querySelector(".scheme-container").after(endpointSearchWidgetEl); // put it below the "Authorize" section
+    }
+});