@gitbook/react-openapi 1.1.10 → 1.2.1

package/src/OpenAPICodeSampleSelector.tsx

@@ -6,6 +6,7 @@ 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';
 
@@ -22,25 +23,22 @@ type CodeSampleItem = OpenAPISelectItem & {
     footer?: React.ReactNode;
 };
 
-export function OpenAPICodeSampleHeader(props: {
+function OpenAPICodeSampleHeader(props: {
     items: CodeSampleItem[];
     data: OpenAPIOperationData;
+    selectIcon?: React.ReactNode;
+    context: OpenAPIClientContext;
 }) {
-    const { data, items } = props;
-
-    const state = useCodeSampleState(items[0]?.key ?? '');
-    const selected = items.find((item) => item.key === state.key) || items[0];
+    const { data, items, selectIcon, context } = props;
 
     return (
         <>
-            <OpenAPIPath canCopy={false} withServer={false} data={data} />
+            <OpenAPIPath context={context} canCopy={false} withServer={false} data={data} />
             {items.length > 1 ? (
                 <OpenAPISelect
-                    selectedKey={selected?.key}
-                    onSelectionChange={(key) => {
-                        state.setKey(key);
-                    }}
+                    icon={selectIcon}
                     items={items}
+                    stateKey="codesample"
                     placement="bottom end"
                 >
                     {items.map((item) => (
@@ -59,8 +57,10 @@ export function OpenAPICodeSampleHeader(props: {
 export function OpenAPICodeSampleBody(props: {
     items: CodeSampleItem[];
     data: OpenAPIOperationData;
+    selectIcon?: React.ReactNode;
+    context: OpenAPIClientContext;
 }) {
-    const { items, data } = props;
+    const { items, data, selectIcon, context } = props;
     if (!items[0]) {
         throw new Error('No items provided');
     }
@@ -75,7 +75,14 @@ export function OpenAPICodeSampleBody(props: {
 
     return (
         <StaticSection
-            header={<OpenAPICodeSampleHeader data={data} items={items} />}
+            header={
+                <OpenAPICodeSampleHeader
+                    context={context}
+                    selectIcon={selectIcon}
+                    data={data}
+                    items={items}
+                />
+            }
             className="openapi-codesample"
         >
             <div id={selected.key as string} className="openapi-codesample-panel">

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,26 @@ 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}
+                                placement="bottom end"
                             >
                                 {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

@@ -1,9 +1,8 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
-import { generateSchemaExample } from './generateSchemaExample';
+import type { OpenAPIContext, OpenAPIUniversalContext } from './context';
 import { json2xml } from './json2xml';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIContext } from './types';
-import { checkIsReference } from './utils';
+import { t } from './translate';
 
 /**
  * Display an example.
@@ -17,7 +16,7 @@ export function OpenAPIExample(props: {
     const code = stringifyExample({ example, xml: syntax === 'xml' });
 
     if (code === null) {
-        return <OpenAPIEmptyExample />;
+        return <OpenAPIEmptyExample context={context} />;
     }
 
     return context.renderCodeBlock({ code, syntax });
@@ -44,86 +43,13 @@ function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean
 /**
  * Empty response example.
  */
-export function OpenAPIEmptyExample() {
+export function OpenAPIEmptyExample(props: {
+    context: OpenAPIUniversalContext;
+}) {
+    const { context } = props;
     return (
         <pre className="openapi-example-empty">
-            <p>No Content</p>
+            <p>{t(context.translation, 'no_content')}</p>
         </pre>
     );
 }
-
-/**
- * Generate an example from a reference object.
- */
-export function getExampleFromReference(ref: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
-    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
-}
-
-/**
- * Get examples from a media type object.
- */
-export function getExamplesFromMediaTypeObject(args: {
-    mediaType: string;
-    mediaTypeObject: OpenAPIV3.MediaTypeObject;
-}): { key: string; example: OpenAPIV3.ExampleObject }[] {
-    const { mediaTypeObject, mediaType } = args;
-    if (mediaTypeObject.examples) {
-        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
-            return {
-                key,
-                example: checkIsReference(example) ? getExampleFromReference(example) : example,
-            };
-        });
-    }
-
-    if (mediaTypeObject.example) {
-        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
-    }
-
-    if (mediaTypeObject.schema) {
-        if (mediaType === 'application/xml') {
-            // @TODO normally we should use the name of the schema but we don't have it
-            // fix it when we got the reference name
-            const root = mediaTypeObject.schema.xml?.name ?? 'object';
-            return [
-                {
-                    key: 'default',
-                    example: {
-                        value: {
-                            [root]: generateSchemaExample(mediaTypeObject.schema, {
-                                xml: mediaType === 'application/xml',
-                                mode: 'read',
-                            }),
-                        },
-                    },
-                },
-            ];
-        }
-        return [
-            {
-                key: 'default',
-                example: {
-                    value: generateSchemaExample(mediaTypeObject.schema, {
-                        mode: 'read',
-                    }),
-                },
-            },
-        ];
-    }
-    return [];
-}
-
-/**
- * Get example from a schema object.
- */
-export function getExampleFromSchema(args: {
-    schema: OpenAPIV3.SchemaObject;
-}): OpenAPIV3.ExampleObject {
-    const { schema } = args;
-
-    if (schema.example) {
-        return { value: schema.example };
-    }
-
-    return { value: generateSchemaExample(schema, { mode: 'read' }) };
-}

package/src/OpenAPIMediaType.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+import type { Key } from 'react-aria';
+import { OpenAPIEmptyExample } from './OpenAPIExample';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
+import { StaticSection } from './StaticSection';
+import type { OpenAPIClientContext } from './context';
+
+type OpenAPIMediaTypeItem = OpenAPISelectItem & {
+    body: React.ReactNode;
+    examples?: OpenAPIMediaTypeItem[];
+};
+
+/**
+ * Get the state of the response examples select.
+ */
+export function useMediaTypesState(stateKey: string | undefined, initialKey: Key = 'default') {
+    return useSelectState(stateKey, initialKey);
+}
+
+function useMediaTypeExamplesState(stateKey: string | undefined, initialKey: Key = 'default') {
+    return useSelectState(stateKey, initialKey);
+}
+
+export function OpenAPIMediaTypeContent(props: {
+    items: OpenAPIMediaTypeItem[];
+    selectIcon?: React.ReactNode;
+    stateKey: string;
+    context: OpenAPIClientContext;
+}) {
+    const { stateKey, items, selectIcon, context } = props;
+    const state = useMediaTypesState(stateKey, items[0]?.key);
+
+    const examples = items.find((item) => item.key === state.key)?.examples ?? [];
+
+    if (!items.length && !examples.length) {
+        return null;
+    }
+
+    return (
+        <StaticSection
+            footer={
+                items.length > 1 || examples.length > 1 ? (
+                    <OpenAPIMediaTypeFooter
+                        items={items}
+                        examples={examples}
+                        selectIcon={selectIcon}
+                        stateKey={stateKey}
+                    />
+                ) : null
+            }
+            className="openapi-response-media-types-examples"
+        >
+            <OpenAPIMediaTypeBody
+                context={context}
+                stateKey={stateKey}
+                items={items}
+                examples={examples}
+            />
+        </StaticSection>
+    );
+}
+
+function OpenAPIMediaTypeFooter(props: {
+    items: OpenAPIMediaTypeItem[];
+    examples?: OpenAPIMediaTypeItem[];
+    selectIcon?: React.ReactNode;
+    stateKey: string;
+}) {
+    const { items, examples, stateKey, selectIcon } = props;
+
+    return (
+        <>
+            {items.length > 1 && (
+                <OpenAPISelect
+                    icon={selectIcon}
+                    items={items}
+                    stateKey={stateKey}
+                    placement="bottom start"
+                >
+                    {items.map((item) => (
+                        <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                            <span>{item.label}</span>
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            )}
+
+            {examples && examples.length > 1 ? (
+                <OpenAPISelect
+                    icon={selectIcon}
+                    items={examples}
+                    stateKey={`${stateKey}-examples`}
+                    placement="bottom start"
+                >
+                    {examples.map((example) => (
+                        <OpenAPISelectItem key={example.key} id={example.key} value={example}>
+                            <span>{example.label}</span>
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            ) : null}
+        </>
+    );
+}
+
+function OpenAPIMediaTypeBody(props: {
+    items: OpenAPIMediaTypeItem[];
+    examples?: OpenAPIMediaTypeItem[];
+    stateKey: string;
+    context: OpenAPIClientContext;
+}) {
+    const { stateKey, items, examples, context } = props;
+    const state = useMediaTypesState(stateKey, items[0]?.key);
+
+    const selectedItem = items.find((item) => item.key === state.key) ?? items[0];
+
+    const exampleState = useMediaTypeExamplesState(
+        `${stateKey}-examples`,
+        selectedItem?.examples?.[0]?.key
+    );
+
+    if (!selectedItem) {
+        return null;
+    }
+
+    if (examples) {
+        const selectedExample =
+            examples.find((example) => example.key === exampleState.key) ?? examples[0];
+
+        if (!selectedExample) {
+            return <OpenAPIEmptyExample context={context} />;
+        }
+
+        return selectedExample.body;
+    }
+
+    return selectedItem.body;
+}

package/src/OpenAPIOperation.tsx

@@ -1,18 +1,10 @@
 import clsx from 'clsx';
-
-import type {
-    OpenAPICustomOperationProperties,
-    OpenAPIStability,
-    OpenAPIV3,
-} from '@gitbook/openapi-parser';
-import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
-import { OpenAPIPath } from './OpenAPIPath';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
-import { OpenAPISpec } from './OpenAPISpec';
-import { getOpenAPIClientContext } from './context';
-import type { OpenAPIContext, OpenAPIOperationData } from './types';
-import { resolveDescription } from './utils';
+import { OpenAPIColumnSpec } from './common/OpenAPIColumnSpec';
+import { OpenAPISummary } from './common/OpenAPISummary';
+import { type OpenAPIContextInput, resolveOpenAPIContext } from './context';
+import type { OpenAPIOperationData } from './types';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -20,105 +12,24 @@ import { resolveDescription } from './utils';
 export function OpenAPIOperation(props: {
     className?: string;
     data: OpenAPIOperationData;
-    context: OpenAPIContext;
+    context: OpenAPIContextInput;
 }) {
-    const { className, data, context } = props;
-    const { operation } = data;
+    const { className, data, context: contextInput } = props;
 
-    const clientContext = getOpenAPIClientContext(context);
+    const context = resolveOpenAPIContext(contextInput);
 
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
-                {(operation.deprecated || operation['x-stability']) && (
-                    <div className="openapi-summary-tags">
-                        {operation.deprecated && (
-                            <div className="openapi-deprecated">Deprecated</div>
-                        )}
-                        {operation['x-stability'] && (
-                            <OpenAPIOperationStability stability={operation['x-stability']} />
-                        )}
-                    </div>
-                )}
-                {operation.summary
-                    ? context.renderHeading({
-                          deprecated: operation.deprecated ?? false,
-                          stability: operation['x-stability'],
-                          title: operation.summary,
-                      })
-                    : null}
-                <OpenAPIPath data={data} />
-            </div>
+            <OpenAPISummary data={data} context={context} />
             <div className="openapi-columns">
-                <div className="openapi-column-spec">
-                    {operation['x-deprecated-sunset'] ? (
-                        <div className="openapi-deprecated-sunset openapi-description openapi-markdown">
-                            This operation is deprecated and will be sunset on{' '}
-                            <span className="openapi-deprecated-sunset-date">
-                                {operation['x-deprecated-sunset']}
-                            </span>
-                            {'.'}
-                        </div>
-                    ) : null}
-                    <OpenAPIOperationDescription operation={operation} context={context} />
-                    <OpenAPISpec data={data} context={clientContext} />
-                </div>
+                <OpenAPIColumnSpec data={data} context={context} />
                 <div className="openapi-column-preview">
                     <div className="openapi-column-preview-body">
-                        <OpenAPICodeSample {...props} />
-                        <OpenAPIResponseExample {...props} />
+                        <OpenAPICodeSample data={data} context={context} />
+                        <OpenAPIResponseExample data={data} context={context} />
                     </div>
                 </div>
             </div>
         </div>
     );
 }
-
-function OpenAPIOperationDescription(props: {
-    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
-    context: OpenAPIContext;
-}) {
-    const { operation } = props;
-    if (operation['x-gitbook-description-document']) {
-        return (
-            <div className="openapi-intro">
-                {props.context.renderDocument({
-                    document: operation['x-gitbook-description-document'],
-                })}
-            </div>
-        );
-    }
-
-    const description = resolveDescription(operation);
-    if (!description) {
-        return null;
-    }
-
-    return (
-        <div className="openapi-intro">
-            <Markdown className="openapi-description" source={description} />
-        </div>
-    );
-}
-
-const stabilityEnum = {
-    experimental: 'Experimental',
-    alpha: 'Alpha',
-    beta: 'Beta',
-} as const;
-
-function OpenAPIOperationStability(props: { stability: OpenAPIStability }) {
-    const { stability } = props;
-
-    const foundStability = stabilityEnum[stability];
-
-    if (!foundStability) {
-        return null;
-    }
-
-    return (
-        <div className={`openapi-stability openapi-stability-${foundStability.toLowerCase()}`}>
-            {foundStability}
-        </div>
-    );
-}