@redocly/theme 0.67.0-next.1 → 0.67.0-next.3

package/lib/components/Image/Image.d.ts

@@ -3,11 +3,14 @@ import type { JSX } from 'react';
 export type ImageProps = {
     src?: string;
     srcSet?: string;
+    images?: string[];
     alt?: string;
     className?: string;
     width?: string | number;
     height?: string | number;
     border?: string;
+    caption?: string;
+    framed?: boolean;
     withLightbox?: boolean;
     lightboxStyle?: React.CSSProperties | string;
     style?: React.CSSProperties | string;

package/lib/components/Image/Image.js

@@ -32,17 +32,16 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Image = Image;
 const react_1 = __importStar(require("react"));
-const styled_components_1 = __importDefault(require("styled-components"));
+const styled_components_1 = __importStar(require("styled-components"));
 const utils_1 = require("../../core/utils");
 const hooks_1 = require("../../core/hooks");
+const CloseIcon_1 = require("../../icons/CloseIcon/CloseIcon");
+const Button_1 = require("../../components/Button/Button");
 function Image(props) {
-    const { src, srcSet, alt, className, width, height, border, style, withLightbox, lightboxStyle } = props;
+    const { src, srcSet, images: galleryImages, alt, className, width, height, border, caption, framed, style, withLightbox, lightboxStyle, } = props;
     const lightboxContainerRef = (0, react_1.useRef)(null);
     const [lightboxImage, setLightboxImage] = (0, react_1.useState)(undefined);
     const parsedSourceSetMap = (0, react_1.useMemo)(() => {
@@ -72,12 +71,73 @@ function Image(props) {
     }, [lightboxImage]);
     const combinedStyles = Object.assign(Object.assign(Object.assign({}, (withLightbox && { cursor: 'pointer' })), (border && { border })), (typeof style === 'string' ? (0, utils_1.parseStyleString)(style) : style));
     const lightboxOverlayStyles = typeof lightboxStyle === 'string' ? (0, utils_1.parseStyleString)(lightboxStyle) : lightboxStyle;
+    const images = src ? (react_1.default.createElement("img", { src: src, alt: alt, className: className, width: width, height: height, style: combinedStyles, onClick: () => handleImageClick(src) })) : (Array.from(parsedSourceSetMap).map(([key, value]) => (react_1.default.createElement(ColorModeAwareImage, { key: key, $colorMode: key, src: value, alt: alt, className: className, width: width, height: height, $withLightbox: withLightbox, style: combinedStyles, onClick: () => handleImageClick(value) }))));
+    const hasGallery = Array.isArray(galleryImages) && galleryImages.length > 0;
+    const visibleGalleryImages = hasGallery ? galleryImages.slice(0, 3) : [];
+    const gallery = hasGallery ? (react_1.default.createElement(GalleryRow, null, visibleGalleryImages.map((galleryImageSrc, index) => (react_1.default.createElement("img", { key: `${galleryImageSrc}-${index}`, src: galleryImageSrc, alt: alt, style: withLightbox ? { cursor: 'pointer' } : undefined, onClick: () => handleImageClick(galleryImageSrc) }))))) : null;
+    const hasCaption = Boolean(caption);
+    const hasWrapper = Boolean(framed || hasCaption || hasGallery);
+    const wrapperContent = hasGallery ? gallery : images;
     return (react_1.default.createElement(react_1.default.Fragment, null,
         lightboxImage ? (react_1.default.createElement(LightboxContainer, { ref: lightboxContainerRef, onClick: handleCloseLightbox, onKeyDown: handleLightboxKeyDown, tabIndex: 0 },
             react_1.default.createElement(Overlay, { style: lightboxOverlayStyles }),
-            react_1.default.createElement(Image, { src: lightboxImage, alt: alt }))) : null,
-        src ? (react_1.default.createElement("img", { src: src, alt: alt, className: className, width: width, height: height, style: combinedStyles, onClick: () => handleImageClick(src) })) : (Array.from(parsedSourceSetMap).map(([key, value]) => (react_1.default.createElement(ColorModeAwareImage, { key: key, $colorMode: key, src: value, alt: alt, className: className, width: width, height: height, $withLightbox: withLightbox, style: combinedStyles, onClick: () => handleImageClick(value) }))))));
+            react_1.default.createElement(LightboxContent, null,
+                react_1.default.createElement(CloseButton, { variant: "secondary", "aria-label": "Close image", onClick: handleCloseLightbox },
+                    react_1.default.createElement(CloseIcon_1.CloseIcon, null)),
+                react_1.default.createElement(Image, { src: lightboxImage, alt: alt })))) : null,
+        hasWrapper ? (react_1.default.createElement(ImageFrame, { "data-component-name": "Image/Image", $framed: framed, $gallery: hasGallery },
+            wrapperContent,
+            hasCaption ? react_1.default.createElement(ImageCaption, null, caption) : null)) : (images)));
 }
+const ImageFrame = styled_components_1.default.figure `
+  display: ${({ $gallery }) => ($gallery ? 'block' : 'inline-block')};
+  margin: 0;
+  ${({ $gallery }) => ($gallery ? 'width: 100%;' : '')}
+  max-width: 100%;
+
+  ${({ $framed }) => $framed &&
+    (0, styled_components_1.css) `
+      padding: var(--image-frame-padding);
+      border: var(--border-width) var(--border-style) var(--image-frame-border-color);
+      border-radius: var(--image-frame-border-radius);
+      background-color: var(--image-frame-bg-color);
+    `}
+
+  > img {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    background: transparent center / cover no-repeat;
+
+    ${({ $framed }) => $framed &&
+    (0, styled_components_1.css) `
+        border-radius: var(--image-frame-image-border-radius);
+      `}
+  }
+`;
+const GalleryRow = styled_components_1.default.div `
+  display: flex;
+  align-items: stretch;
+  overflow: hidden;
+  border-radius: var(--image-gallery-border-radius);
+
+  img {
+    flex: 1 1 0;
+    min-width: 0;
+    width: 100%;
+    object-fit: cover;
+    border-radius: 0;
+    background: var(--image-gallery-image-bg-color) 50% / cover no-repeat;
+  }
+`;
+const ImageCaption = styled_components_1.default.figcaption `
+  padding: var(--image-caption-padding);
+  color: var(--image-caption-text-color);
+  font-size: var(--image-caption-font-size);
+  line-height: var(--image-caption-line-height);
+  font-weight: var(--image-caption-font-weight);
+  text-align: center;
+`;
 const ColorModeAwareImage = styled_components_1.default.img `
   html:not(.${(props) => props.$colorMode}) && {
     display: none;
@@ -88,13 +148,38 @@ const ColorModeAwareImage = styled_components_1.default.img `
   `}
 `;
 const Overlay = styled_components_1.default.div `
-  background-color: var(--bg-color-modal-overlay);
+  background-color: var(--image-lightbox-overlay-bg-color);
   grid-column: 1 / 2;
   grid-row: 1 / 2;
   height: 100%;
   width: 100%;
   z-index: -1;
 `;
+const CloseButton = (0, styled_components_1.default)(Button_1.Button) `
+  position: absolute;
+  top: 0;
+  left: 100%;
+  margin-left: var(--image-lightbox-close-offset);
+  width: var(--image-lightbox-close-size);
+  height: var(--image-lightbox-close-size);
+  border-radius: var(--image-lightbox-close-border-radius);
+  z-index: 1;
+
+  svg {
+    width: var(--image-lightbox-close-icon-size);
+    height: var(--image-lightbox-close-icon-size);
+  }
+`;
+const LightboxContent = styled_components_1.default.div `
+  position: relative;
+  grid-column: 1 / 2;
+  grid-row: 1 / 2;
+  margin: auto;
+  width: fit-content;
+  height: fit-content;
+  max-width: var(--image-lightbox-content-max-width);
+  max-height: var(--image-lightbox-content-max-height);
+`;
 const LightboxContainer = styled_components_1.default.div `
   display: grid;
   height: 100vh;
@@ -110,11 +195,14 @@ const LightboxContainer = styled_components_1.default.div `
 
   img {
     cursor: pointer;
-    grid-column: 1 / 2;
-    grid-row: 1 / 2;
-    margin: auto;
-    max-width: 90%;
-    max-height: 90%;
+    display: block;
+    max-width: var(--image-lightbox-image-max-width);
+    max-height: var(--image-lightbox-image-max-height);
+    border-radius: var(--image-lightbox-image-border-radius);
+    background:
+      var(--image-lightbox-image-bg-placeholder) center / cover no-repeat,
+      var(--image-frame-bg-color);
+    box-shadow: var(--image-lightbox-image-shadow);
   }
 `;
 //# sourceMappingURL=Image.js.map

package/lib/components/Image/variables.d.ts

@@ -0,0 +1 @@
+export declare const image: import("styled-components").RuleSet<object>;

package/lib/components/Image/variables.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.image = void 0;
+const styled_components_1 = require("styled-components");
+exports.image = (0, styled_components_1.css) `
+  /* === Image === */
+
+  /**
+    * @tokens Image frame
+    */
+  --image-frame-padding: var(--spacing-xs);
+  --image-frame-border-color: var(--border-color-secondary);
+  --image-frame-border-radius: var(--border-radius-xxl);
+  --image-frame-bg-color: var(--bg-color-raised);
+  --image-frame-image-border-radius: var(--border-radius-lg);
+
+  /**
+    * @tokens Image caption
+    */
+  --image-caption-padding: var(--spacing-sm) var(--spacing-lg) var(--spacing-xxs) var(--spacing-lg);
+  --image-caption-text-color: var(--text-color-primary);
+  --image-caption-font-size: var(--font-size-base);
+  --image-caption-line-height: var(--line-height-base);
+  --image-caption-font-weight: var(--font-weight-regular);
+
+  /**
+    * @tokens Image gallery
+    */
+  --image-gallery-border-radius: var(--border-radius-lg);
+  --image-gallery-image-bg-color: var(--bg-color-tonal);
+
+  /**
+    * @tokens Image lightbox
+    */
+  --image-lightbox-overlay-bg-color: var(--bg-color-modal-overlay);
+  --image-lightbox-content-max-width: 90%;
+  --image-lightbox-content-max-height: 90%;
+
+  --image-lightbox-image-max-width: min(
+    90vw,
+    calc(100vw - 2 * var(--image-lightbox-side-gutter))
+  );
+  --image-lightbox-image-max-height: 90vh;
+  --image-lightbox-image-border-radius: var(--border-radius-xl);
+  --image-lightbox-image-bg-placeholder: var(--bg-color-tonal);
+  --image-lightbox-image-shadow: var(--bg-raised-shadow);
+
+  /**
+    * @tokens Image lightbox close button
+    */
+  --image-lightbox-close-size: 40px;
+  --image-lightbox-close-icon-size: 18px;
+  --image-lightbox-close-offset: var(--spacing-base);
+  --image-lightbox-close-border-radius: var(--border-radius-lg);
+  --image-lightbox-side-gutter: calc(
+    var(--image-lightbox-close-size) + var(--image-lightbox-close-offset) + var(--spacing-sm)
+  );
+`;
+//# sourceMappingURL=variables.js.map

package/lib/core/styles/global.js

@@ -10,43 +10,44 @@ const variables_5 = require("../../components/Breadcrumbs/variables");
 const variables_6 = require("../../components/Tag/variables");
 const variables_7 = require("../../components/TableOfContent/variables");
 const variables_8 = require("../../components/Catalog/variables");
-const variables_9 = require("../../components/Filter/variables");
-const variables_10 = require("../../components/CatalogClassic/variables");
-const variables_11 = require("../../components/Panel/variables");
-const variables_12 = require("../../components/Accordion/variables");
-const variables_13 = require("../../components/Select/variables");
-const variables_14 = require("../../components/Dropdown/variables");
-const variables_15 = require("../../components/Tooltip/variables");
-const variables_16 = require("../../icons/CheckboxIcon/variables");
-const variables_17 = require("../../components/Admonition/variables");
-const variables_18 = require("../../components/Footer/variables");
-const variables_19 = require("../../components/Button/variables");
-const variables_20 = require("../../components/Buttons/variables");
-const variables_21 = require("../../components/Navbar/variables");
-const variables_22 = require("../../components/Search/variables");
-const variables_23 = require("../../components/Menu/variables");
-const variables_24 = require("../../components/CodeBlock/variables");
-const variables_25 = require("../../components/Product/variables");
-const variables_26 = require("../../components/Markdown/variables");
-const variables_27 = require("../../components/Banner/variables");
-const variables_28 = require("../../markdoc/components/Tabs/variables");
-const variables_29 = require("../../markdoc/components/Diagram/variables");
-const variables_30 = require("../../components/LastUpdated/variables");
-const variables_31 = require("../../components/Logo/variables");
-const variables_32 = require("../../components/StatusCode/variables");
-const variables_33 = require("../../components/Segmented/variables");
-const variables_34 = require("../../components/UserMenu/variables");
-const variables_35 = require("../../components/Tags/variables");
-const variables_36 = require("../../components/VersionPicker/variables");
-const variables_37 = require("../../components/DatePicker/variables");
-const variables_38 = require("../../components/Switch/variables");
-const variables_39 = require("../../markdoc/components/Cards/variables");
-const variables_40 = require("../../markdoc/components/CodeWalkthrough/variables");
-const variables_41 = require("../../components/SkipContent/variables");
-const variables_42 = require("../../components/PageActions/variables");
-const variables_43 = require("../../components/SvgViewer/variables");
-const variables_44 = require("../../components/Toast/variables");
-const variables_45 = require("../../components/PageNavigation/variables");
+const variables_9 = require("../../components/Image/variables");
+const variables_10 = require("../../components/Filter/variables");
+const variables_11 = require("../../components/CatalogClassic/variables");
+const variables_12 = require("../../components/Panel/variables");
+const variables_13 = require("../../components/Accordion/variables");
+const variables_14 = require("../../components/Select/variables");
+const variables_15 = require("../../components/Dropdown/variables");
+const variables_16 = require("../../components/Tooltip/variables");
+const variables_17 = require("../../icons/CheckboxIcon/variables");
+const variables_18 = require("../../components/Admonition/variables");
+const variables_19 = require("../../components/Footer/variables");
+const variables_20 = require("../../components/Button/variables");
+const variables_21 = require("../../components/Buttons/variables");
+const variables_22 = require("../../components/Navbar/variables");
+const variables_23 = require("../../components/Search/variables");
+const variables_24 = require("../../components/Menu/variables");
+const variables_25 = require("../../components/CodeBlock/variables");
+const variables_26 = require("../../components/Product/variables");
+const variables_27 = require("../../components/Markdown/variables");
+const variables_28 = require("../../components/Banner/variables");
+const variables_29 = require("../../markdoc/components/Tabs/variables");
+const variables_30 = require("../../markdoc/components/Diagram/variables");
+const variables_31 = require("../../components/LastUpdated/variables");
+const variables_32 = require("../../components/Logo/variables");
+const variables_33 = require("../../components/StatusCode/variables");
+const variables_34 = require("../../components/Segmented/variables");
+const variables_35 = require("../../components/UserMenu/variables");
+const variables_36 = require("../../components/Tags/variables");
+const variables_37 = require("../../components/VersionPicker/variables");
+const variables_38 = require("../../components/DatePicker/variables");
+const variables_39 = require("../../components/Switch/variables");
+const variables_40 = require("../../markdoc/components/Cards/variables");
+const variables_41 = require("../../markdoc/components/CodeWalkthrough/variables");
+const variables_42 = require("../../components/SkipContent/variables");
+const variables_43 = require("../../components/PageActions/variables");
+const variables_44 = require("../../components/SvgViewer/variables");
+const variables_45 = require("../../components/Toast/variables");
+const variables_46 = require("../../components/PageNavigation/variables");
 const palette_1 = require("./palette");
 const dark_1 = require("./dark");
 const themeColors = (0, styled_components_1.css) `
@@ -1255,47 +1256,48 @@ const replay = (0, styled_components_1.css) `
 `;
 exports.styles = (0, styled_components_1.css) `
   :root {
-    ${variables_12.accordion}
-    ${variables_17.admonition}
+    ${variables_13.accordion}
+    ${variables_18.admonition}
     ${apiReferenceDocs}
-    ${variables_11.apiReferencePanels}
+    ${variables_12.apiReferencePanels}
     ${badges}
-    ${variables_27.banner}
+    ${variables_28.banner}
     ${borders}
     ${variables_5.breadcrumbs}
-    ${variables_19.button}
-    ${variables_20.aiAssistantButton}
-    ${variables_20.connectMCPButton}
-    ${variables_39.cards}
+    ${variables_20.button}
+    ${variables_21.aiAssistantButton}
+    ${variables_21.connectMCPButton}
+    ${variables_40.cards}
     ${variables_8.catalog}
-    ${variables_10.catalogClassic}
-    ${variables_24.code}
-    ${variables_40.codeWalkthrough}
+    ${variables_11.catalogClassic}
+    ${variables_25.code}
+    ${variables_41.codeWalkthrough}
     ${docsDropdown}
-    ${variables_14.dropdown}
+    ${variables_15.dropdown}
     ${error}
-    ${variables_9.filter}
-    ${variables_18.footer}
+    ${variables_10.filter}
+    ${variables_19.footer}
     ${headingsTypography}
-    ${variables_35.httpTag}
+    ${variables_36.httpTag}
+    ${variables_9.image}
     ${inputs}
     ${variables_1.languagePicker}
-    ${variables_30.lastUpdated}
+    ${variables_31.lastUpdated}
     ${links}
     ${loadProgressBar}
-    ${variables_31.logo}
-    ${variables_26.markdown}
-    ${variables_28.markdownTabs}
-    ${variables_29.diagram}
-    ${variables_23.menu}
-    ${variables_23.mobileMenu}
+    ${variables_32.logo}
+    ${variables_27.markdown}
+    ${variables_29.markdownTabs}
+    ${variables_30.diagram}
+    ${variables_24.menu}
+    ${variables_24.mobileMenu}
     ${modal}
-    ${variables_21.navbar}
+    ${variables_22.navbar}
     ${pages}
-    ${variables_25.productPicker}
-    ${variables_11.responsePanelColors}
-    ${variables_22.search}
-    ${variables_13.select}
+    ${variables_26.productPicker}
+    ${variables_12.responsePanelColors}
+    ${variables_23.search}
+    ${variables_14.select}
     ${variables_4.sidebar}
     ${sizeAndSpace}
     ${variables_6.tag}
@@ -1303,28 +1305,28 @@ exports.styles = (0, styled_components_1.css) `
     ${palette_1.activeBrandPaletteLight}
     ${tile}
     ${variables_7.toc}
-    ${variables_15.tooltip}
+    ${variables_16.tooltip}
     ${typography}
-    ${variables_34.userMenu}
-    ${variables_36.versionPicker}
+    ${variables_35.userMenu}
+    ${variables_37.versionPicker}
     ${zIndexDepth}
     ${scorecardColors}
-    ${variables_32.statusCode}
+    ${variables_33.statusCode}
     ${tab}
     ${icon}
     ${tree}
-    ${variables_33.segmented}
-    ${variables_38.switcher}
-    ${variables_16.checkbox}
+    ${variables_34.segmented}
+    ${variables_39.switcher}
+    ${variables_17.checkbox}
     ${variables_3.feedback}
     ${variables_2.scorecard}
-    ${variables_37.datePicker}
+    ${variables_38.datePicker}
     ${replay}
-    ${variables_41.skipContent}
-    ${variables_42.pageActions}
-    ${variables_43.svgViewer}
-    ${variables_44.toast}
-    ${variables_45.pageNavigation}
+    ${variables_42.skipContent}
+    ${variables_43.pageActions}
+    ${variables_44.svgViewer}
+    ${variables_45.toast}
+    ${variables_46.pageNavigation}
 
     background-color: var(--bg-color);
     color: var(--text-color-primary);

package/lib/ext/configure-helpers.d.ts

@@ -0,0 +1,35 @@
+export type SecurityDetails = {
+    password?: string;
+    username?: string;
+    token?: {
+        token_type?: string;
+        access_token: string;
+    };
+    client_id?: string;
+    client_secret?: string;
+    scopes?: string[];
+};
+export type ConfigureInputHintAction = {
+    label: string;
+    action: () => void;
+};
+export type ConfigureInputHint = {
+    title: string;
+    text: string;
+    actions?: ConfigureInputHintAction[];
+};
+export type ConfigureRequestValues = {
+    headers?: Record<string, string>;
+    body?: Record<string, any>;
+    query?: Record<string, string>;
+    path?: Record<string, string>;
+    cookie?: Record<string, string>;
+    security?: Record<string, SecurityDetails>;
+    envVariables?: Record<string, string>;
+    serverVariables?: Record<string, string>;
+    inputHints?: Record<string, ConfigureInputHint>;
+};
+export type ConfigureServerRequestValues = {
+    [serverUrl: string]: ConfigureRequestValues;
+};
+export type ConfigureReplayConfig = ConfigureRequestValues | ConfigureServerRequestValues | null | undefined;

package/lib/ext/configure-helpers.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=configure-helpers.js.map

package/lib/ext/configure.d.ts

@@ -1,28 +1,7 @@
 import type { UserClaims, OpenAPIServer } from '../core/types';
-export type SecurityDetails = {
-    password?: string;
-    username?: string;
-    token?: {
-        token_type?: string;
-        access_token: string;
-    };
-    client_id?: string;
-    client_secret?: string;
-    scopes?: string[];
-};
-export type ConfigureRequestValues = {
-    headers?: Record<string, string>;
-    body?: Record<string, any>;
-    query?: Record<string, string>;
-    path?: Record<string, string>;
-    cookie?: Record<string, string>;
-    security?: Record<string, SecurityDetails>;
-    envVariables?: Record<string, string>;
-    serverVariables?: Record<string, string>;
-};
-export type ConfigureServerRequestValues = {
-    [serverUrl: string]: ConfigureRequestValues;
-};
+export * from '../ext/configure-helpers';
+export * from '../ext/helpers/is-direct-configure-request-values';
+import type { ConfigureRequestValues, ConfigureServerRequestValues } from '../ext/configure-helpers';
 type Configure = {
     requestValues?: ConfigureRequestValues | ConfigureServerRequestValues;
 };
@@ -38,4 +17,3 @@ type ContextProps = {
     servers: OpenAPIServer[];
 };
 export declare function configure(_context: ContextProps): Configure;
-export {};

package/lib/ext/configure.js

@@ -1,6 +1,22 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configure = configure;
+__exportStar(require("../ext/configure-helpers"), exports);
+__exportStar(require("../ext/helpers/is-direct-configure-request-values"), exports);
 function configure(_context) {
     // const exampleDefaultRequestValues: ConfigureRequestValues = {
     //   body: {

package/lib/ext/helpers/is-direct-configure-request-values.d.ts

@@ -0,0 +1,15 @@
+import type { ConfigureRequestValues, ConfigureServerRequestValues } from '../../ext/configure-helpers';
+/**
+ * Type guard that distinguishes a direct {@link ConfigureRequestValues} payload (request
+ * values that apply to every server) from a {@link ConfigureServerRequestValues} payload
+ * (request values keyed by server URL).
+ *
+ * A payload is treated as server-keyed when at least one top-level key is *not* a known
+ * request-value key (e.g. `headers`, `security`, `inputHints`) and its value looks like a
+ * nested {@link ConfigureRequestValues}. This keeps mixed shapes — e.g. server-keyed values
+ * alongside a top-level `inputHints` sibling — classified as server-keyed.
+ *
+ * @param value - The configure payload returned from `getReplayConfiguration`.
+ * @returns `true` when `value` is a direct {@link ConfigureRequestValues}, narrowing the type.
+ */
+export declare function isDirectConfigureRequestValues(value: ConfigureRequestValues | ConfigureServerRequestValues): value is ConfigureRequestValues;

package/lib/ext/helpers/is-direct-configure-request-values.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDirectConfigureRequestValues = isDirectConfigureRequestValues;
+const CONFIGURE_REQUEST_VALUE_KEYS = [
+    'headers',
+    'body',
+    'query',
+    'path',
+    'cookie',
+    'security',
+    'envVariables',
+    'serverVariables',
+    'inputHints',
+];
+const CONFIGURE_REQUEST_VALUE_KEY_SET = new Set(CONFIGURE_REQUEST_VALUE_KEYS);
+function hasConfigureRequestValueKeys(value) {
+    return CONFIGURE_REQUEST_VALUE_KEYS.some((key) => key in value);
+}
+/**
+ * Type guard that distinguishes a direct {@link ConfigureRequestValues} payload (request
+ * values that apply to every server) from a {@link ConfigureServerRequestValues} payload
+ * (request values keyed by server URL).
+ *
+ * A payload is treated as server-keyed when at least one top-level key is *not* a known
+ * request-value key (e.g. `headers`, `security`, `inputHints`) and its value looks like a
+ * nested {@link ConfigureRequestValues}. This keeps mixed shapes — e.g. server-keyed values
+ * alongside a top-level `inputHints` sibling — classified as server-keyed.
+ *
+ * @param value - The configure payload returned from `getReplayConfiguration`.
+ * @returns `true` when `value` is a direct {@link ConfigureRequestValues}, narrowing the type.
+ */
+function isDirectConfigureRequestValues(value) {
+    const hasServerKeyedValues = Object.entries(value).some(([key, entry]) => !CONFIGURE_REQUEST_VALUE_KEY_SET.has(key) &&
+        entry != null &&
+        typeof entry === 'object' &&
+        hasConfigureRequestValueKeys(entry));
+    if (hasServerKeyedValues) {
+        return false;
+    }
+    return hasConfigureRequestValueKeys(value);
+}
+//# sourceMappingURL=is-direct-configure-request-values.js.map

package/lib/ext/use-configure-replay.d.ts

@@ -1,4 +1,4 @@
-import type { ConfigureRequestValues, ConfigureServerRequestValues } from '../ext/configure';
+import { type ConfigureRequestValues, type ConfigureServerRequestValues } from '../ext/configure';
 import type { UserClaims, OpenAPIServer, OpenAPIInfo } from '../core/types';
 type ContextProps = {
     operation: {

package/lib/markdoc/tags/img.js

@@ -14,9 +14,20 @@ exports.img = {
                 type: String,
                 resolver: 'imageSrcSet',
             },
+            images: {
+                type: Array,
+                resolver: 'imageGallery',
+            },
             alt: {
                 type: String,
             },
+            caption: {
+                type: String,
+            },
+            framed: {
+                type: Boolean,
+                default: false,
+            },
             withLightbox: {
                 type: Boolean,
                 default: false,
@@ -45,8 +56,31 @@ exports.img = {
             },
         },
         validate: (node) => {
-            if (!node.attributes.src && !node.attributes.srcSet) {
-                return [{ id: '', message: 'src or srcSet is required', level: 'error' }];
+            const { src, srcSet, images } = node.attributes;
+            const hasGallery = Array.isArray(images) && images.length > 0;
+            if (!src && !srcSet && !hasGallery) {
+                return [{ id: '', message: 'src, srcSet, or images is required', level: 'error' }];
+            }
+            if (hasGallery && (src || srcSet)) {
+                return [
+                    {
+                        id: 'invalid-img-source-combination',
+                        message: 'images cannot be used together with src or srcSet',
+                        level: 'error',
+                    },
+                ];
+            }
+            if (src && srcSet) {
+                return [
+                    {
+                        id: 'invalid-img-source-combination',
+                        message: 'src cannot be used together with srcSet',
+                        level: 'error',
+                    },
+                ];
+            }
+            if (Array.isArray(images) && images.length > 3) {
+                return [{ id: '', message: 'images supports a maximum of 3 items', level: 'error' }];
             }
             return [];
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.67.0-next.1",
+  "version": "0.67.0-next.3",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -63,7 +63,7 @@
     "vitest": "4.1.8",
     "vitest-when": "0.6.2",
     "webpack": "5.105.2",
-    "@redocly/realm-asyncapi-sdk": "0.13.0-next.0"
+    "@redocly/realm-asyncapi-sdk": "0.13.0-next.2"
   },
   "dependencies": {
     "@tanstack/react-query": "5.62.3",

package/src/components/Image/Image.tsx

@@ -1,27 +1,45 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import styled from 'styled-components';
+import styled, { css } from 'styled-components';
 
 import type { KeyboardEvent, JSX } from 'react';
 
 import { parseSrcSet, parseStyleString } from '@redocly/theme/core/utils';
 import { useModalScrollLock } from '@redocly/theme/core/hooks';
+import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
+import { Button } from '@redocly/theme/components/Button/Button';
 
 export type ImageProps = {
   src?: string;
   srcSet?: string;
+  images?: string[];
   alt?: string;
   className?: string;
   width?: string | number;
   height?: string | number;
   border?: string;
+  caption?: string;
+  framed?: boolean;
   withLightbox?: boolean;
   lightboxStyle?: React.CSSProperties | string;
   style?: React.CSSProperties | string;
 };
 
 export function Image(props: ImageProps): JSX.Element {
-  const { src, srcSet, alt, className, width, height, border, style, withLightbox, lightboxStyle } =
-    props;
+  const {
+    src,
+    srcSet,
+    images: galleryImages,
+    alt,
+    className,
+    width,
+    height,
+    border,
+    caption,
+    framed,
+    style,
+    withLightbox,
+    lightboxStyle,
+  } = props;
 
   const lightboxContainerRef = useRef<HTMLDivElement>(null);
   const [lightboxImage, setLightboxImage] = useState<string | undefined>(undefined);
@@ -66,6 +84,54 @@ export function Image(props: ImageProps): JSX.Element {
   const lightboxOverlayStyles: React.CSSProperties | undefined =
     typeof lightboxStyle === 'string' ? parseStyleString(lightboxStyle) : lightboxStyle;
 
+  const images = src ? (
+    <img
+      src={src}
+      alt={alt}
+      className={className}
+      width={width}
+      height={height}
+      style={combinedStyles}
+      onClick={() => handleImageClick(src)}
+    />
+  ) : (
+    Array.from(parsedSourceSetMap).map(([key, value]) => (
+      <ColorModeAwareImage
+        key={key}
+        $colorMode={key}
+        src={value}
+        alt={alt}
+        className={className}
+        width={width}
+        height={height}
+        $withLightbox={withLightbox}
+        style={combinedStyles}
+        onClick={() => handleImageClick(value)}
+      />
+    ))
+  );
+
+  const hasGallery = Array.isArray(galleryImages) && galleryImages.length > 0;
+  const visibleGalleryImages = hasGallery ? galleryImages.slice(0, 3) : [];
+
+  const gallery = hasGallery ? (
+    <GalleryRow>
+      {visibleGalleryImages.map((galleryImageSrc, index) => (
+        <img
+          key={`${galleryImageSrc}-${index}`}
+          src={galleryImageSrc}
+          alt={alt}
+          style={withLightbox ? { cursor: 'pointer' } : undefined}
+          onClick={() => handleImageClick(galleryImageSrc)}
+        />
+      ))}
+    </GalleryRow>
+  ) : null;
+
+  const hasCaption = Boolean(caption);
+  const hasWrapper = Boolean(framed || hasCaption || hasGallery);
+  const wrapperContent = hasGallery ? gallery : images;
+
   return (
     <>
       {lightboxImage ? (
@@ -76,39 +142,80 @@ export function Image(props: ImageProps): JSX.Element {
           tabIndex={0}
         >
           <Overlay style={lightboxOverlayStyles} />
-          <Image src={lightboxImage} alt={alt} />
+          <LightboxContent>
+            <CloseButton variant="secondary" aria-label="Close image" onClick={handleCloseLightbox}>
+              <CloseIcon />
+            </CloseButton>
+            <Image src={lightboxImage} alt={alt} />
+          </LightboxContent>
         </LightboxContainer>
       ) : null}
-      {src ? (
-        <img
-          src={src}
-          alt={alt}
-          className={className}
-          width={width}
-          height={height}
-          style={combinedStyles}
-          onClick={() => handleImageClick(src)}
-        />
+      {hasWrapper ? (
+        <ImageFrame data-component-name="Image/Image" $framed={framed} $gallery={hasGallery}>
+          {wrapperContent}
+          {hasCaption ? <ImageCaption>{caption}</ImageCaption> : null}
+        </ImageFrame>
       ) : (
-        Array.from(parsedSourceSetMap).map(([key, value]) => (
-          <ColorModeAwareImage
-            key={key}
-            $colorMode={key}
-            src={value}
-            alt={alt}
-            className={className}
-            width={width}
-            height={height}
-            $withLightbox={withLightbox}
-            style={combinedStyles}
-            onClick={() => handleImageClick(value)}
-          />
-        ))
+        images
       )}
     </>
   );
 }
 
+const ImageFrame = styled.figure<{ $framed?: boolean; $gallery?: boolean }>`
+  display: ${({ $gallery }) => ($gallery ? 'block' : 'inline-block')};
+  margin: 0;
+  ${({ $gallery }) => ($gallery ? 'width: 100%;' : '')}
+  max-width: 100%;
+
+  ${({ $framed }) =>
+    $framed &&
+    css`
+      padding: var(--image-frame-padding);
+      border: var(--border-width) var(--border-style) var(--image-frame-border-color);
+      border-radius: var(--image-frame-border-radius);
+      background-color: var(--image-frame-bg-color);
+    `}
+
+  > img {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    background: transparent center / cover no-repeat;
+
+    ${({ $framed }) =>
+      $framed &&
+      css`
+        border-radius: var(--image-frame-image-border-radius);
+      `}
+  }
+`;
+
+const GalleryRow = styled.div`
+  display: flex;
+  align-items: stretch;
+  overflow: hidden;
+  border-radius: var(--image-gallery-border-radius);
+
+  img {
+    flex: 1 1 0;
+    min-width: 0;
+    width: 100%;
+    object-fit: cover;
+    border-radius: 0;
+    background: var(--image-gallery-image-bg-color) 50% / cover no-repeat;
+  }
+`;
+
+const ImageCaption = styled.figcaption`
+  padding: var(--image-caption-padding);
+  color: var(--image-caption-text-color);
+  font-size: var(--image-caption-font-size);
+  line-height: var(--image-caption-line-height);
+  font-weight: var(--image-caption-font-weight);
+  text-align: center;
+`;
+
 const ColorModeAwareImage = styled.img<{ $colorMode: string; $withLightbox?: boolean }>`
   html:not(.${(props) => props.$colorMode}) && {
     display: none;
@@ -121,7 +228,7 @@ const ColorModeAwareImage = styled.img<{ $colorMode: string; $withLightbox?: boo
 `;
 
 const Overlay = styled.div`
-  background-color: var(--bg-color-modal-overlay);
+  background-color: var(--image-lightbox-overlay-bg-color);
   grid-column: 1 / 2;
   grid-row: 1 / 2;
   height: 100%;
@@ -129,6 +236,33 @@ const Overlay = styled.div`
   z-index: -1;
 `;
 
+const CloseButton = styled(Button)`
+  position: absolute;
+  top: 0;
+  left: 100%;
+  margin-left: var(--image-lightbox-close-offset);
+  width: var(--image-lightbox-close-size);
+  height: var(--image-lightbox-close-size);
+  border-radius: var(--image-lightbox-close-border-radius);
+  z-index: 1;
+
+  svg {
+    width: var(--image-lightbox-close-icon-size);
+    height: var(--image-lightbox-close-icon-size);
+  }
+`;
+
+const LightboxContent = styled.div`
+  position: relative;
+  grid-column: 1 / 2;
+  grid-row: 1 / 2;
+  margin: auto;
+  width: fit-content;
+  height: fit-content;
+  max-width: var(--image-lightbox-content-max-width);
+  max-height: var(--image-lightbox-content-max-height);
+`;
+
 const LightboxContainer = styled.div`
   display: grid;
   height: 100vh;
@@ -144,10 +278,13 @@ const LightboxContainer = styled.div`
 
   img {
     cursor: pointer;
-    grid-column: 1 / 2;
-    grid-row: 1 / 2;
-    margin: auto;
-    max-width: 90%;
-    max-height: 90%;
+    display: block;
+    max-width: var(--image-lightbox-image-max-width);
+    max-height: var(--image-lightbox-image-max-height);
+    border-radius: var(--image-lightbox-image-border-radius);
+    background:
+      var(--image-lightbox-image-bg-placeholder) center / cover no-repeat,
+      var(--image-frame-bg-color);
+    box-shadow: var(--image-lightbox-image-shadow);
   }
 `;

package/src/components/Image/variables.ts

@@ -0,0 +1,56 @@
+import { css } from 'styled-components';
+
+export const image = css`
+  /* === Image === */
+
+  /**
+    * @tokens Image frame
+    */
+  --image-frame-padding: var(--spacing-xs);
+  --image-frame-border-color: var(--border-color-secondary);
+  --image-frame-border-radius: var(--border-radius-xxl);
+  --image-frame-bg-color: var(--bg-color-raised);
+  --image-frame-image-border-radius: var(--border-radius-lg);
+
+  /**
+    * @tokens Image caption
+    */
+  --image-caption-padding: var(--spacing-sm) var(--spacing-lg) var(--spacing-xxs) var(--spacing-lg);
+  --image-caption-text-color: var(--text-color-primary);
+  --image-caption-font-size: var(--font-size-base);
+  --image-caption-line-height: var(--line-height-base);
+  --image-caption-font-weight: var(--font-weight-regular);
+
+  /**
+    * @tokens Image gallery
+    */
+  --image-gallery-border-radius: var(--border-radius-lg);
+  --image-gallery-image-bg-color: var(--bg-color-tonal);
+
+  /**
+    * @tokens Image lightbox
+    */
+  --image-lightbox-overlay-bg-color: var(--bg-color-modal-overlay);
+  --image-lightbox-content-max-width: 90%;
+  --image-lightbox-content-max-height: 90%;
+
+  --image-lightbox-image-max-width: min(
+    90vw,
+    calc(100vw - 2 * var(--image-lightbox-side-gutter))
+  );
+  --image-lightbox-image-max-height: 90vh;
+  --image-lightbox-image-border-radius: var(--border-radius-xl);
+  --image-lightbox-image-bg-placeholder: var(--bg-color-tonal);
+  --image-lightbox-image-shadow: var(--bg-raised-shadow);
+
+  /**
+    * @tokens Image lightbox close button
+    */
+  --image-lightbox-close-size: 40px;
+  --image-lightbox-close-icon-size: 18px;
+  --image-lightbox-close-offset: var(--spacing-base);
+  --image-lightbox-close-border-radius: var(--border-radius-lg);
+  --image-lightbox-side-gutter: calc(
+    var(--image-lightbox-close-size) + var(--image-lightbox-close-offset) + var(--spacing-sm)
+  );
+`;

package/src/core/styles/global.ts

@@ -8,6 +8,7 @@ import { breadcrumbs } from '@redocly/theme/components/Breadcrumbs/variables';
 import { tag } from '@redocly/theme/components/Tag/variables';
 import { toc } from '@redocly/theme/components/TableOfContent/variables';
 import { catalog } from '@redocly/theme/components/Catalog/variables';
+import { image } from '@redocly/theme/components/Image/variables';
 import { filter } from '@redocly/theme/components/Filter/variables';
 import { catalogClassic } from '@redocly/theme/components/CatalogClassic/variables';
 import { apiReferencePanels, responsePanelColors } from '@redocly/theme/components/Panel/variables';
@@ -1301,6 +1302,7 @@ export const styles = css<{ palette?: string }>`
     ${footer}
     ${headingsTypography}
     ${httpTag}
+    ${image}
     ${inputs}
     ${languagePicker}
     ${lastUpdated}

package/src/ext/configure-helpers.ts

@@ -0,0 +1,45 @@
+export type SecurityDetails = {
+  password?: string;
+  username?: string;
+  token?: {
+    token_type?: string;
+    access_token: string;
+  };
+  client_id?: string;
+  client_secret?: string;
+  scopes?: string[];
+};
+
+export type ConfigureInputHintAction = {
+  label: string;
+  action: () => void;
+};
+
+export type ConfigureInputHint = {
+  title: string;
+  text: string;
+  actions?: ConfigureInputHintAction[];
+};
+
+export type ConfigureRequestValues = {
+  headers?: Record<string, string>;
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  body?: Record<string, any>;
+  query?: Record<string, string>;
+  path?: Record<string, string>;
+  cookie?: Record<string, string>;
+  security?: Record<string, SecurityDetails>;
+  envVariables?: Record<string, string>;
+  serverVariables?: Record<string, string>;
+  inputHints?: Record<string, ConfigureInputHint>;
+};
+
+export type ConfigureServerRequestValues = {
+  [serverUrl: string]: ConfigureRequestValues;
+};
+
+export type ConfigureReplayConfig =
+  | ConfigureRequestValues
+  | ConfigureServerRequestValues
+  | null
+  | undefined;

package/src/ext/configure.ts

@@ -1,32 +1,12 @@
 import type { UserClaims, OpenAPIServer } from '@redocly/theme/core/types';
 
-export type SecurityDetails = {
-  password?: string;
-  username?: string;
-  token?: {
-    token_type?: string;
-    access_token: string;
-  };
-  client_id?: string;
-  client_secret?: string;
-  scopes?: string[];
-};
+export * from '@redocly/theme/ext/configure-helpers';
+export * from '@redocly/theme/ext/helpers/is-direct-configure-request-values';
 
-export type ConfigureRequestValues = {
-  headers?: Record<string, string>;
-  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
-  body?: Record<string, any>;
-  query?: Record<string, string>;
-  path?: Record<string, string>;
-  cookie?: Record<string, string>;
-  security?: Record<string, SecurityDetails>;
-  envVariables?: Record<string, string>;
-  serverVariables?: Record<string, string>;
-};
-
-export type ConfigureServerRequestValues = {
-  [serverUrl: string]: ConfigureRequestValues;
-};
+import type {
+  ConfigureRequestValues,
+  ConfigureServerRequestValues,
+} from '@redocly/theme/ext/configure-helpers';
 
 type Configure = {
   requestValues?: ConfigureRequestValues | ConfigureServerRequestValues;

package/src/ext/helpers/is-direct-configure-request-values.ts

@@ -0,0 +1,53 @@
+import type {
+  ConfigureRequestValues,
+  ConfigureServerRequestValues,
+} from '@redocly/theme/ext/configure-helpers';
+
+const CONFIGURE_REQUEST_VALUE_KEYS = [
+  'headers',
+  'body',
+  'query',
+  'path',
+  'cookie',
+  'security',
+  'envVariables',
+  'serverVariables',
+  'inputHints',
+] as const;
+
+const CONFIGURE_REQUEST_VALUE_KEY_SET = new Set<string>(CONFIGURE_REQUEST_VALUE_KEYS);
+
+function hasConfigureRequestValueKeys(value: object): boolean {
+  return CONFIGURE_REQUEST_VALUE_KEYS.some((key) => key in value);
+}
+
+/**
+ * Type guard that distinguishes a direct {@link ConfigureRequestValues} payload (request
+ * values that apply to every server) from a {@link ConfigureServerRequestValues} payload
+ * (request values keyed by server URL).
+ *
+ * A payload is treated as server-keyed when at least one top-level key is *not* a known
+ * request-value key (e.g. `headers`, `security`, `inputHints`) and its value looks like a
+ * nested {@link ConfigureRequestValues}. This keeps mixed shapes — e.g. server-keyed values
+ * alongside a top-level `inputHints` sibling — classified as server-keyed.
+ *
+ * @param value - The configure payload returned from `getReplayConfiguration`.
+ * @returns `true` when `value` is a direct {@link ConfigureRequestValues}, narrowing the type.
+ */
+export function isDirectConfigureRequestValues(
+  value: ConfigureRequestValues | ConfigureServerRequestValues,
+): value is ConfigureRequestValues {
+  const hasServerKeyedValues = Object.entries(value).some(
+    ([key, entry]) =>
+      !CONFIGURE_REQUEST_VALUE_KEY_SET.has(key) &&
+      entry != null &&
+      typeof entry === 'object' &&
+      hasConfigureRequestValueKeys(entry),
+  );
+
+  if (hasServerKeyedValues) {
+    return false;
+  }
+
+  return hasConfigureRequestValueKeys(value);
+}

package/src/ext/use-configure-replay.ts

@@ -1,8 +1,8 @@
 import { useEffect, useState, useCallback } from 'react';
 
-import type {
-  ConfigureRequestValues,
-  ConfigureServerRequestValues,
+import {
+  type ConfigureRequestValues,
+  type ConfigureServerRequestValues,
 } from '@redocly/theme/ext/configure';
 import type { UserClaims, OpenAPIServer, OpenAPIInfo } from '@redocly/theme/core/types';
 

package/src/markdoc/tags/img.ts

@@ -13,9 +13,20 @@ export const img: MarkdocSchemaWrapper = {
         type: String,
         resolver: 'imageSrcSet',
       },
+      images: {
+        type: Array,
+        resolver: 'imageGallery',
+      },
       alt: {
         type: String,
       },
+      caption: {
+        type: String,
+      },
+      framed: {
+        type: Boolean,
+        default: false,
+      },
       withLightbox: {
         type: Boolean,
         default: false,
@@ -44,8 +55,31 @@ export const img: MarkdocSchemaWrapper = {
       },
     },
     validate: (node) => {
-      if (!node.attributes.src && !node.attributes.srcSet) {
-        return [{ id: '', message: 'src or srcSet is required', level: 'error' }];
+      const { src, srcSet, images } = node.attributes;
+      const hasGallery = Array.isArray(images) && images.length > 0;
+      if (!src && !srcSet && !hasGallery) {
+        return [{ id: '', message: 'src, srcSet, or images is required', level: 'error' }];
+      }
+      if (hasGallery && (src || srcSet)) {
+        return [
+          {
+            id: 'invalid-img-source-combination',
+            message: 'images cannot be used together with src or srcSet',
+            level: 'error',
+          },
+        ];
+      }
+      if (src && srcSet) {
+        return [
+          {
+            id: 'invalid-img-source-combination',
+            message: 'src cannot be used together with srcSet',
+            level: 'error',
+          },
+        ];
+      }
+      if (Array.isArray(images) && images.length > 3) {
+        return [{ id: '', message: 'images supports a maximum of 3 items', level: 'error' }];
       }
       return [];
     },