@gitbook/react-openapi 1.1.9 → 1.2.0

package/src/OpenAPICodeSampleInteractive.tsx

@@ -1,86 +1,70 @@
 'use client';
 import clsx from 'clsx';
-import { useCallback } from 'react';
-import { useStore } from 'zustand';
 import type { MediaTypeRenderer } from './OpenAPICodeSample';
-import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
-
-type MediaTypeState = {
-    mediaType: string;
-    setMediaType: (mediaType: string) => void;
-};
-
-function useMediaTypeState(
-    data: { method: string; path: string },
-    defaultKey: string
-): MediaTypeState {
-    const { method, path } = data;
-    const store = useStore(getOrCreateTabStoreByKey(`media-type-${method}-${path}`, defaultKey));
-    if (typeof store.tabKey !== 'string') {
-        throw new Error('Media type key is not a string');
-    }
-    return {
-        mediaType: store.tabKey,
-        setMediaType: useCallback((index: string) => store.setTabKey(index), [store.setTabKey]),
-    };
-}
-
-function useMediaTypeSampleIndexState(data: { method: string; path: string }, mediaType: string) {
-    const { method, path } = data;
-    const store = useStore(
-        getOrCreateTabStoreByKey(`media-type-sample-${mediaType}-${method}-${path}`, 0)
-    );
-    if (typeof store.tabKey !== 'number') {
-        throw new Error('Example key is not a number');
-    }
-    return {
-        index: store.tabKey,
-        setIndex: useCallback((index: number) => store.setTabKey(index), [store.setTabKey]),
-    };
-}
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
+import { createStateKey } from './utils';
 
 export function OpenAPIMediaTypeExamplesSelector(props: {
     method: string;
     path: string;
     renderers: MediaTypeRenderer[];
+    selectIcon?: React.ReactNode;
+    blockKey?: string;
 }) {
-    const { method, path, renderers } = props;
+    const { method, path, renderers, selectIcon, blockKey } = props;
     if (!renderers[0]) {
         throw new Error('No renderers provided');
     }
-    const state = useMediaTypeState({ method, path }, renderers[0].mediaType);
-    const selected = renderers.find((r) => r.mediaType === state.mediaType) || renderers[0];
+    const stateKey = createStateKey('request-body-media-type', blockKey);
+    const state = useSelectState(stateKey, renderers[0].mediaType);
+    const selected = renderers.find((r) => r.mediaType === state.key) || renderers[0];
 
     return (
         <div className="openapi-codesample-selectors">
-            <MediaTypeSelector state={state} renderers={renderers} />
-            <ExamplesSelector method={method} path={path} renderer={selected} />
+            <MediaTypeSelector selectIcon={selectIcon} stateKey={stateKey} renderers={renderers} />
+            <ExamplesSelector
+                selectIcon={selectIcon}
+                method={method}
+                path={path}
+                renderer={selected}
+            />
         </div>
     );
 }
 
 function MediaTypeSelector(props: {
-    state: MediaTypeState;
+    stateKey: string;
     renderers: MediaTypeRenderer[];
+    selectIcon?: React.ReactNode;
 }) {
-    const { renderers, state } = props;
+    const { renderers, stateKey, selectIcon } = props;
 
     if (renderers.length < 2) {
         return null;
     }
 
+    const items = renderers.map((renderer) => ({
+        key: renderer.mediaType,
+        label: renderer.mediaType,
+    }));
+
     return (
-        <select
+        <OpenAPISelect
             className={clsx('openapi-select')}
-            value={state.mediaType}
-            onChange={(e) => state.setMediaType(e.target.value)}
+            items={renderers.map((renderer) => ({
+                key: renderer.mediaType,
+                label: renderer.mediaType,
+            }))}
+            icon={selectIcon}
+            stateKey={stateKey}
+            placement="bottom start"
         >
-            {renderers.map((renderer) => (
-                <option key={renderer.mediaType} value={renderer.mediaType}>
-                    {renderer.mediaType}
-                </option>
+            {items.map((item) => (
+                <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                    {item.label}
+                </OpenAPISelectItem>
             ))}
-        </select>
+        </OpenAPISelect>
     );
 }
 
@@ -88,25 +72,31 @@ function ExamplesSelector(props: {
     method: string;
     path: string;
     renderer: MediaTypeRenderer;
+    selectIcon?: React.ReactNode;
 }) {
-    const { method, path, renderer } = props;
-    const state = useMediaTypeSampleIndexState({ method, path }, renderer.mediaType);
+    const { method, path, renderer, selectIcon } = props;
     if (renderer.examples.length < 2) {
         return null;
     }
 
+    const items = renderer.examples.map((example, index) => ({
+        key: index,
+        label: example.example.summary || `Example ${index + 1}`,
+    }));
+
     return (
-        <select
-            className={clsx('openapi-select')}
-            value={String(state.index)}
-            onChange={(e) => state.setIndex(Number(e.target.value))}
+        <OpenAPISelect
+            items={items}
+            icon={selectIcon}
+            stateKey={`media-type-sample-${renderer.mediaType}-${method}-${path}`}
+            placement="bottom start"
         >
-            {renderer.examples.map((example, index) => (
-                <option key={index} value={index}>
-                    {example.example.summary || `Example ${index + 1}`}
-                </option>
+            {items.map((item) => (
+                <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                    {item.label}
+                </OpenAPISelectItem>
             ))}
-        </select>
+        </OpenAPISelect>
     );
 }
 
@@ -114,14 +104,18 @@ export function OpenAPIMediaTypeExamplesBody(props: {
     method: string;
     path: string;
     renderers: MediaTypeRenderer[];
+    blockKey?: string;
 }) {
-    const { renderers, method, path } = props;
+    const { renderers, method, path, blockKey } = props;
     if (!renderers[0]) {
         throw new Error('No renderers provided');
     }
-    const mediaTypeState = useMediaTypeState({ method, path }, renderers[0].mediaType);
-    const selected =
-        renderers.find((r) => r.mediaType === mediaTypeState.mediaType) ?? renderers[0];
+
+    const mediaTypeState = useSelectState(
+        createStateKey('request-body-media-type', blockKey),
+        renderers[0].mediaType
+    );
+    const selected = renderers.find((r) => r.mediaType === mediaTypeState.key) ?? renderers[0];
     if (selected.examples.length === 0) {
         return selected.element;
     }
@@ -130,10 +124,13 @@ export function OpenAPIMediaTypeExamplesBody(props: {
 
 function ExamplesBody(props: { method: string; path: string; renderer: MediaTypeRenderer }) {
     const { method, path, renderer } = props;
-    const exampleState = useMediaTypeSampleIndexState({ method, path }, renderer.mediaType);
-    const example = renderer.examples[exampleState.index] ?? renderer.examples[0];
+    const exampleState = useSelectState(
+        `media-type-sample-${renderer.mediaType}-${method}-${path}`,
+        renderer.mediaType
+    );
+    const example = renderer.examples[Number(exampleState.key)] ?? renderer.examples[0];
     if (!example) {
-        throw new Error(`No example found for index ${exampleState.index}`);
+        throw new Error(`No example found for key ${exampleState.key}`);
     }
     return example.element;
 }

package/src/OpenAPICodeSampleSelector.tsx

@@ -0,0 +1,94 @@
+'use client';
+
+import { useCallback } from 'react';
+import type { Key } from 'react-aria';
+import { useStore } from 'zustand';
+import { OpenAPIPath } from './OpenAPIPath';
+import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
+import { StaticSection } from './StaticSection';
+import type { OpenAPIClientContext } from './context';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
+import type { OpenAPIOperationData } from './types';
+
+function useCodeSampleState(initialKey: Key = 'default') {
+    const store = useStore(getOrCreateStoreByKey('codesample', initialKey));
+    return {
+        key: store.key,
+        setKey: useCallback((key: Key) => store.setKey(key), [store.setKey]),
+    };
+}
+
+type CodeSampleItem = OpenAPISelectItem & {
+    body: React.ReactNode;
+    footer?: React.ReactNode;
+};
+
+function OpenAPICodeSampleHeader(props: {
+    items: CodeSampleItem[];
+    data: OpenAPIOperationData;
+    selectIcon?: React.ReactNode;
+    context: OpenAPIClientContext;
+}) {
+    const { data, items, selectIcon, context } = props;
+
+    return (
+        <>
+            <OpenAPIPath context={context} canCopy={false} withServer={false} data={data} />
+            {items.length > 1 ? (
+                <OpenAPISelect
+                    icon={selectIcon}
+                    items={items}
+                    stateKey="codesample"
+                    placement="bottom end"
+                >
+                    {items.map((item) => (
+                        <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                            {item.label}
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            ) : items[0] ? (
+                <span className="openapi-codesample-label">{items[0].label}</span>
+            ) : null}
+        </>
+    );
+}
+
+export function OpenAPICodeSampleBody(props: {
+    items: CodeSampleItem[];
+    data: OpenAPIOperationData;
+    selectIcon?: React.ReactNode;
+    context: OpenAPIClientContext;
+}) {
+    const { items, data, selectIcon, context } = props;
+    if (!items[0]) {
+        throw new Error('No items provided');
+    }
+
+    const state = useCodeSampleState(items[0]?.key);
+
+    const selected = items.find((item) => item.key === state.key) || items[0];
+
+    if (!selected) {
+        return null;
+    }
+
+    return (
+        <StaticSection
+            header={
+                <OpenAPICodeSampleHeader
+                    context={context}
+                    selectIcon={selectIcon}
+                    data={data}
+                    items={items}
+                />
+            }
+            className="openapi-codesample"
+        >
+            <div id={selected.key as string} className="openapi-codesample-panel">
+                {selected.body ? selected.body : null}
+                {selected.footer ? selected.footer : null}
+            </div>
+        </StaticSection>
+    );
+}

package/src/OpenAPICopyButton.tsx

@@ -2,11 +2,14 @@
 
 import { useState } from 'react';
 import { Button, type ButtonProps, Tooltip, TooltipTrigger } from 'react-aria-components';
+import type { OpenAPIClientContext } from './context';
+import { t } from './translate';
 
 export function OpenAPICopyButton(
     props: ButtonProps & {
         value: string;
         children: React.ReactNode;
+        context: OpenAPIClientContext;
         label?: string;
         /**
          * Whether to show a tooltip.
@@ -15,7 +18,7 @@ export function OpenAPICopyButton(
         withTooltip?: boolean;
     }
 ) {
-    const { value, label, children, onPress, className, withTooltip = true } = props;
+    const { value, label, children, onPress, className, context, withTooltip = true } = props;
     const [copied, setCopied] = useState(false);
     const [isOpen, setIsOpen] = useState(false);
 
@@ -60,7 +63,9 @@ export function OpenAPICopyButton(
                 offset={4}
                 className="openapi-tooltip"
             >
-                {copied ? 'Copied' : label || 'Copy to clipboard'}
+                {copied
+                    ? t(context.translation, 'copied')
+                    : label || t(context.translation, 'copy_to_clipboard')}
             </Tooltip>
         </TooltipTrigger>
     );

package/src/OpenAPIDisclosure.tsx

@@ -1,41 +1,39 @@
 'use client';
+import clsx from 'clsx';
+import type React from 'react';
 import { useState } from 'react';
-import { Button, Disclosure, DisclosurePanel, Heading } from 'react-aria-components';
-import type { OpenAPIClientContext } from './types';
+import { Button, Disclosure, DisclosurePanel } from 'react-aria-components';
 
 /**
  * Display an interactive OpenAPI disclosure.
  */
 export function OpenAPIDisclosure(props: {
-    context: OpenAPIClientContext;
+    icon: React.ReactNode;
     children: React.ReactNode;
-    label: string;
+    label: string | ((isExpanded: boolean) => string);
+    className?: string;
 }): React.JSX.Element {
-    const { context, children, label } = props;
+    const { icon, children, label, className } = props;
     const [isExpanded, setIsExpanded] = useState(false);
 
     return (
         <Disclosure
-            className="openapi-disclosure"
+            className={clsx('openapi-disclosure', className)}
             isExpanded={isExpanded}
             onExpandedChange={setIsExpanded}
         >
-            <Heading>
-                <Button
-                    slot="trigger"
-                    className="openapi-disclosure-trigger"
-                    style={({ isFocusVisible }) => ({
-                        outline: isFocusVisible
-                            ? '2px solid rgb(var(--primary-color-500) / 0.4)'
-                            : 'none',
-                    })}
-                >
-                    {context.icons.plus}
-                    <span>
-                        {isExpanded ? 'Hide' : 'Show'} {label}
-                    </span>
-                </Button>
-            </Heading>
+            <Button
+                slot="trigger"
+                className="openapi-disclosure-trigger"
+                style={({ isFocusVisible }) => ({
+                    outline: isFocusVisible
+                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                        : 'none',
+                })}
+            >
+                {icon}
+                <span>{typeof label === 'function' ? label(isExpanded) : label}</span>
+            </Button>
             <DisclosurePanel className="openapi-disclosure-panel">
                 {isExpanded ? children : null}
             </DisclosurePanel>

package/src/OpenAPIDisclosureGroup.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createContext, useContext, useRef, useState } from 'react';
+import { createContext, useContext, useRef } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
 import {
     type DisclosureGroupProps,
@@ -8,18 +8,23 @@ import {
     useDisclosureGroupState,
     useDisclosureState,
 } from 'react-stately';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
 
 interface Props {
     groups: TDisclosureGroup[];
     icon?: React.ReactNode;
+    /** State key to use with a store */
+    selectStateKey?: string;
+    /** Icon to display for the select */
+    selectIcon?: React.ReactNode;
 }
 
 type TDisclosureGroup = {
-    id: string;
+    key: string;
     label: string | React.ReactNode;
     tabs?: {
-        id: string;
-        label?: string | React.ReactNode;
+        key: string;
+        label: string | React.ReactNode;
         body?: React.ReactNode;
     }[];
 };
@@ -30,24 +35,35 @@ const DisclosureGroupStateContext = createContext<DisclosureGroupState | null>(n
  * Display an interactive OpenAPI disclosure group.
  */
 export function OpenAPIDisclosureGroup(props: DisclosureGroupProps & Props) {
-    const { icon, groups } = props;
+    const { icon, groups, selectStateKey, selectIcon } = props;
 
     const state = useDisclosureGroupState(props);
 
     return (
         <DisclosureGroupStateContext.Provider value={state}>
             {groups.map((group) => (
-                <DisclosureItem icon={icon} key={group.id} group={group} />
+                <DisclosureItem
+                    selectStateKey={selectStateKey}
+                    selectIcon={selectIcon}
+                    icon={icon}
+                    key={group.key}
+                    group={group}
+                />
             ))}
         </DisclosureGroupStateContext.Provider>
     );
 }
 
-function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode }) {
-    const { icon, group } = props;
+function DisclosureItem(props: {
+    group: TDisclosureGroup;
+    icon?: React.ReactNode;
+    selectStateKey?: string;
+    selectIcon?: React.ReactNode;
+}) {
+    const { icon, group, selectStateKey, selectIcon } = props;
 
     const defaultId = useId();
-    const id = group.id || defaultId;
+    const id = group.key || defaultId;
     const groupState = useContext(DisclosureGroupStateContext);
     const isExpanded = groupState?.expandedKeys.has(id) || false;
     const state = useDisclosureState({
@@ -74,9 +90,9 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
     const { buttonProps } = useButton(triggerProps, triggerRef);
     const { isFocusVisible, focusProps } = useFocusRing();
 
-    const defaultTab = group.tabs?.[0]?.id || '';
-    const [selectedTabKey, setSelectedTabKey] = useState(defaultTab);
-    const selectedTab = group.tabs?.find((tab) => tab.id === selectedTabKey);
+    const defaultTab = group.tabs?.[0]?.key || '';
+    const store = useSelectState(selectStateKey, defaultTab);
+    const selectedTab = group.tabs?.find((tab) => tab.key === store.key) || group.tabs?.[0];
 
     return (
         <div className="openapi-disclosure-group" aria-expanded={state.isExpanded}>
@@ -104,23 +120,25 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
                     {group.label}
                 </button>
                 {group.tabs ? (
-                    <div className="openapi-disclosure-group-mediatype">
+                    <div
+                        className="openapi-disclosure-group-mediatype"
+                        onClick={(e) => e.stopPropagation()}
+                    >
                         {group.tabs?.length > 1 ? (
-                            <select
-                                className="openapi-section-select openapi-select openapi-disclosure-group-tabs-select"
-                                onClick={(event) => event.stopPropagation()}
-                                value={selectedTab?.id}
-                                onChange={(event) => {
-                                    setSelectedTabKey(event.target.value);
+                            <OpenAPISelect
+                                icon={selectIcon}
+                                stateKey={selectStateKey}
+                                onSelectionChange={() => {
                                     state.expand();
                                 }}
+                                items={group.tabs}
                             >
                                 {group.tabs.map((tab) => (
-                                    <option key={tab.id} value={tab.id}>
+                                    <OpenAPISelectItem key={tab.key} id={tab.key} value={tab}>
                                         {tab.label}
-                                    </option>
+                                    </OpenAPISelectItem>
                                 ))}
-                            </select>
+                            </OpenAPISelect>
                         ) : group.tabs[0]?.label ? (
                             <span>{group.tabs[0].label}</span>
                         ) : null}

package/src/OpenAPIExample.tsx

@@ -0,0 +1,55 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIContext, OpenAPIUniversalContext } from './context';
+import { json2xml } from './json2xml';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { t } from './translate';
+
+/**
+ * Display an example.
+ */
+export function OpenAPIExample(props: {
+    example: OpenAPIV3.ExampleObject;
+    context: OpenAPIContext;
+    syntax: string;
+}) {
+    const { example, context, syntax } = props;
+    const code = stringifyExample({ example, xml: syntax === 'xml' });
+
+    if (code === null) {
+        return <OpenAPIEmptyExample context={context} />;
+    }
+
+    return context.renderCodeBlock({ code, syntax });
+}
+
+function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
+    const { example, xml } = args;
+
+    if (!example.value) {
+        return null;
+    }
+
+    if (typeof example.value === 'string') {
+        return example.value;
+    }
+
+    if (xml) {
+        return json2xml(example.value);
+    }
+
+    return stringifyOpenAPI(example.value, null, 2);
+}
+
+/**
+ * Empty response example.
+ */
+export function OpenAPIEmptyExample(props: {
+    context: OpenAPIUniversalContext;
+}) {
+    const { context } = props;
+    return (
+        <pre className="openapi-example-empty">
+            <p>{t(context.translation, 'no_content')}</p>
+        </pre>
+    );
+}