@gitbook/react-openapi 0.7.1 → 1.0.1

package/src/InteractiveSection.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import classNames from 'classnames';
-import React from 'react';
-import { atom, useRecoilState } from 'recoil';
+import clsx from 'clsx';
+import { useRef, useState } from 'react';
+import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
+import { useDisclosureState } from 'react-stately';
 
 interface InteractiveSectionTab {
     key: string;
@@ -10,11 +11,6 @@ interface InteractiveSectionTab {
     body: React.ReactNode;
 }
 
-const syncedTabsAtom = atom<Record<string, string>>({
-    key: 'syncedTabState',
-    default: {},
-});
-
 /**
  * To optimize rendering, most of the components are server-components,
  * and the interactiveness is mainly handled by a few key components like this one.
@@ -27,21 +23,18 @@ export function InteractiveSection(props: {
     toggeable?: boolean;
     /** Default state of the toggle */
     defaultOpened?: boolean;
-    /** Icons to display for the toggle */
-    toggleOpenIcon?: React.ReactNode;
-    toggleCloseIcon?: React.ReactNode;
+    /** Icon to display for the toggle */
+    toggleIcon?: React.ReactNode;
     /** Tabs of content to display */
     tabs?: Array<InteractiveSectionTab>;
     /** Default tab to have opened */
     defaultTab?: string;
     /** Content of the header */
-    header: React.ReactNode;
+    header?: React.ReactNode;
     /** Body of the section */
     children?: React.ReactNode;
     /** Children to display within the container */
     overlay?: React.ReactNode;
-    /** An optional key referencing a value in global state */
-    stateKey?: string;
 }) {
     const {
         id,
@@ -53,99 +46,110 @@ export function InteractiveSection(props: {
         header,
         children,
         overlay,
-        toggleOpenIcon = '▶',
-        toggleCloseIcon = '▼',
-        stateKey,
+        toggleIcon = '▶',
     } = props;
-    const [syncedTabs, setSyncedTabs] = useRecoilState(syncedTabsAtom);
-    const tabFromState =
-        stateKey && stateKey in syncedTabs
-            ? tabs.find((tab) => tab.key === syncedTabs[stateKey])
-            : undefined;
 
-    const [opened, setOpened] = React.useState(defaultOpened);
-    const [selectedTabKey, setSelectedTab] = React.useState(tabFromState?.key ?? defaultTab);
+    const [selectedTabKey, setSelectedTab] = useState(defaultTab);
     const selectedTab: InteractiveSectionTab | undefined =
-        tabFromState ?? tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
+        tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
+
+    const state = useDisclosureState({
+        defaultExpanded: defaultOpened,
+    });
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
+    const { buttonProps } = useButton(triggerProps, triggerRef);
+    const { isFocusVisible, focusProps } = useFocusRing();
 
     return (
         <div
             id={id}
-            className={classNames(
+            className={clsx(
                 'openapi-section',
                 toggeable ? 'openapi-section-toggeable' : null,
                 className,
-                toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null,
+                toggeable ? `${className}-${state.isExpanded ? 'opened' : 'closed'}` : null,
             )}
         >
-            <div
-                onClick={() => {
-                    if (toggeable) {
-                        setOpened(!opened);
-                    }
-                }}
-                className={classNames('openapi-section-header', `${className}-header`)}
-            >
+            {header ? (
                 <div
-                    className={classNames(
-                        'openapi-section-header-content',
-                        `${className}-header-content`,
-                    )}
+                    onClick={() => {
+                        if (toggeable) {
+                            state.toggle();
+                        }
+                    }}
+                    className={clsx('openapi-section-header', `${className}-header`)}
                 >
-                    {header}
+                    <div
+                        className={clsx(
+                            'openapi-section-header-content',
+                            `${className}-header-content`,
+                        )}
+                    >
+                        {(children || selectedTab?.body) && toggeable ? (
+                            <button
+                                {...mergeProps(buttonProps, focusProps)}
+                                ref={triggerRef}
+                                className={clsx('openapi-section-toggle', `${className}-toggle`)}
+                                style={{
+                                    outline: isFocusVisible
+                                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                                        : 'none',
+                                }}
+                            >
+                                {toggleIcon}
+                            </button>
+                        ) : null}
+                        {header}
+                    </div>
+                    <div
+                        className={clsx(
+                            'openapi-section-header-controls',
+                            `${className}-header-controls`,
+                        )}
+                        onClick={(event) => {
+                            event.stopPropagation();
+                        }}
+                    >
+                        {tabs.length > 1 ? (
+                            <select
+                                className={clsx(
+                                    'openapi-section-select',
+                                    'openapi-select',
+                                    `${className}-tabs-select`,
+                                )}
+                                value={selectedTab?.key ?? ''}
+                                onChange={(event) => {
+                                    setSelectedTab(event.target.value);
+                                    state.expand();
+                                }}
+                            >
+                                {tabs.map((tab) => (
+                                    <option key={tab.key} value={tab.key}>
+                                        {tab.label}
+                                    </option>
+                                ))}
+                            </select>
+                        ) : null}
+                    </div>
                 </div>
+            ) : null}
+            {(!toggeable || state.isExpanded) && (children || selectedTab?.body) ? (
                 <div
-                    className={classNames(
-                        'openapi-section-header-controls',
-                        `${className}-header-controls`,
-                    )}
-                    onClick={(event) => {
-                        event.stopPropagation();
-                    }}
+                    ref={panelRef}
+                    {...panelProps}
+                    className={clsx('openapi-section-body', `${className}-body`)}
                 >
-                    {tabs.length ? (
-                        <select
-                            className={classNames(
-                                'openapi-section-select',
-                                'openapi-select',
-                                `${className}-tabs-select`,
-                            )}
-                            value={selectedTab.key}
-                            onChange={(event) => {
-                                setSelectedTab(event.target.value);
-                                if (stateKey) {
-                                    setSyncedTabs((state) => ({
-                                        ...state,
-                                        [stateKey]: event.target.value,
-                                    }));
-                                }
-                                setOpened(true);
-                            }}
-                        >
-                            {tabs.map((tab) => (
-                                <option key={tab.key} value={tab.key}>
-                                    {tab.label}
-                                </option>
-                            ))}
-                        </select>
-                    ) : null}
-                    {(children || selectedTab?.body) && toggeable ? (
-                        <button
-                            className={classNames('openapi-section-toggle', `${className}-toggle`)}
-                            onClick={() => setOpened(!opened)}
-                        >
-                            {opened ? toggleCloseIcon : toggleOpenIcon}
-                        </button>
-                    ) : null}
-                </div>
-            </div>
-            {(!toggeable || opened) && (children || selectedTab?.body) ? (
-                <div className={classNames('openapi-section-body', `${className}-body`)}>
                     {children}
                     {selectedTab?.body}
                 </div>
             ) : null}
-            {overlay}
+            {overlay ? (
+                <div className={clsx('openapi-section-overlay', `${className}-overlay`)}>
+                    {overlay}
+                </div>
+            ) : null}
         </div>
     );
 }

package/src/Markdown.tsx

@@ -1,12 +1,11 @@
-import * as React from 'react';
-import classNames from 'classnames';
+import clsx from 'clsx';
 
 export function Markdown(props: { source: string; className?: string }) {
     const { source, className } = props;
 
     return (
         <div
-            className={classNames('openapi-markdown', className)}
+            className={clsx('openapi-markdown', className)}
             dangerouslySetInnerHTML={{ __html: source }}
         />
     );

package/src/OpenAPICodeSample.tsx

@@ -1,13 +1,12 @@
-import * as React from 'react';
-
 import { CodeSampleInput, codeSampleGenerators } from './code-samples';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
-import { ScalarApiButton } from './ScalarApiButton';
-import { OpenAPIContextProps } from './types';
-import { noReference } from './utils';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { createStateKey } from './utils';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { checkIsReference } from './utils';
 
 /**
  * Display code samples to execute the operation.
@@ -22,25 +21,20 @@ export function OpenAPICodeSample(props: {
     const searchParams = new URLSearchParams();
     const headersObject: { [k: string]: string } = {};
 
-    data.operation.parameters?.forEach((rawParam) => {
-        const param = noReference(rawParam);
+    data.operation.parameters?.forEach((param) => {
         if (!param) {
             return;
         }
 
         if (param.in === 'header' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
-            if (example !== undefined) {
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            if (example !== undefined && param.name) {
                 headersObject[param.name] =
-                    typeof example !== 'string' ? JSON.stringify(example) : example;
+                    typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
-            if (example !== undefined) {
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
                     String(Array.isArray(example) ? example[0] : example),
@@ -49,8 +43,13 @@ export function OpenAPICodeSample(props: {
         }
     });
 
-    const requestBody = noReference(data.operation.requestBody);
-    const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
+    const requestBody = !checkIsReference(data.operation.requestBody)
+        ? data.operation.requestBody
+        : undefined;
+    const requestBodyContentEntries = requestBody?.content
+        ? Object.entries(requestBody.content)
+        : undefined;
+    const requestBodyContent = requestBodyContentEntries?.[0];
 
     const input: CodeSampleInput = {
         url:
@@ -108,21 +107,17 @@ export function OpenAPICodeSample(props: {
     const codeSamplesDisabled =
         data['x-codeSamples'] === false || data.operation['x-codeSamples'] === false;
     const samples = customCodeSamples ?? (!codeSamplesDisabled ? autoCodeSamples : []);
+
     if (samples.length === 0) {
         return null;
     }
 
     return (
-        <InteractiveSection
-            header="Request"
-            className="openapi-codesample"
-            tabs={samples}
-            overlay={
-                data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
-                    <ScalarApiButton method={data.method} path={data.path} />
-                )
-            }
-        />
+        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-codesample">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
     );
 }
 
@@ -130,6 +125,7 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     [key: string]: string;
 } {
     const security = securities[0];
+
     if (!security) {
         return {};
     }
@@ -137,12 +133,28 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     switch (security[1].type) {
         case 'http': {
             let scheme = security[1].scheme;
-            if (scheme === 'bearer') {
+            let format = security[1].bearerFormat ?? 'YOUR_SECRET_TOKEN';
+
+            if (scheme?.includes('bearer')) {
                 scheme = 'Bearer';
+            } else if (scheme?.includes('basic')) {
+                scheme = 'Basic';
+                format = 'username:password';
+            } else if (scheme?.includes('token')) {
+                scheme = 'Token';
             }
 
             return {
-                Authorization: scheme + ' ' + (security[1].bearerFormat ?? '<token>'),
+                Authorization: scheme + ' ' + format,
+            };
+        }
+        case 'apiKey': {
+            if (security[1].in !== 'header') return {};
+
+            const name = security[1].name ?? 'Authorization';
+
+            return {
+                [name]: 'YOUR_API_KEY',
             };
         }
         default: {

package/src/OpenAPIDisclosure.tsx

@@ -0,0 +1,50 @@
+import { useRef } from 'react';
+import type { OpenAPIClientContext } from './types';
+import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
+import { useDisclosureState } from 'react-stately';
+
+interface Props {
+    context: OpenAPIClientContext;
+    children: React.ReactNode;
+    label?: string;
+}
+
+/**
+ * Display an interactive OpenAPI disclosure.
+ * The label is optional and defaults to "child attributes".
+ */
+export function OpenAPIDisclosure({ context, children, label }: Props): JSX.Element {
+    const state = useDisclosureState({});
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
+    const { buttonProps } = useButton(triggerProps, triggerRef);
+    const { isFocusVisible, focusProps } = useFocusRing();
+
+    return (
+        <div className="openapi-disclosure">
+            <button
+                ref={triggerRef}
+                {...mergeProps(buttonProps, focusProps)}
+                slot="trigger"
+                className="openapi-disclosure-trigger"
+                style={{
+                    outline: isFocusVisible
+                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                        : 'none',
+                }}
+            >
+                {context.icons.plus}
+                <span>
+                    {`${state.isExpanded ? 'Hide' : 'Show'} ${label ? label : `child attributes`}`}
+                </span>
+            </button>
+
+            {state.isExpanded && (
+                <div ref={panelRef} {...panelProps} className="openapi-disclosure-panel">
+                    {children}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/OpenAPIDisclosureGroup.tsx

@@ -0,0 +1,136 @@
+interface Props {
+    groups: TDisclosureGroup[];
+    icon?: React.ReactNode;
+}
+
+type TDisclosureGroup = {
+    id: string;
+    label: string | React.ReactNode;
+    tabs?: {
+        id: string;
+        label: string | React.ReactNode;
+        body?: React.ReactNode;
+    }[];
+};
+
+import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
+import {
+    DisclosureGroupProps,
+    DisclosureGroupState,
+    useDisclosureGroupState,
+    useDisclosureState,
+} from 'react-stately';
+import { createContext, useContext, useRef, useState } from 'react';
+
+const DisclosureGroupStateContext = createContext<DisclosureGroupState | null>(null);
+
+/**
+ * Display an interactive OpenAPI disclosure group.
+ */
+export function OpenAPIDisclosureGroup(props: DisclosureGroupProps & Props) {
+    const { icon, groups } = props;
+
+    const state = useDisclosureGroupState(props);
+
+    return (
+        <DisclosureGroupStateContext.Provider value={state}>
+            {groups.map((group) => (
+                <DisclosureItem icon={icon} key={group.id} group={group} />
+            ))}
+        </DisclosureGroupStateContext.Provider>
+    );
+}
+
+function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode }) {
+    const { icon, group } = props;
+
+    const defaultId = useId();
+    const id = group.id || defaultId;
+    const groupState = useContext(DisclosureGroupStateContext);
+    const isExpanded = groupState?.expandedKeys.has(id) || false;
+    const state = useDisclosureState({
+        isExpanded,
+        onExpandedChange() {
+            if (groupState) {
+                groupState.toggleKey(id);
+            }
+        },
+    });
+
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const isDisabled = groupState?.isDisabled || !group.tabs?.length || false;
+    const { buttonProps: triggerProps, panelProps } = useDisclosure(
+        {
+            ...props,
+            isExpanded,
+            isDisabled,
+        },
+        state,
+        panelRef,
+    );
+    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);
+
+    return (
+        <div className="openapi-disclosure-group" aria-expanded={state.isExpanded}>
+            <div className="openapi-disclosure-group-header">
+                <button
+                    slot="trigger"
+                    ref={triggerRef}
+                    {...mergeProps(buttonProps, focusProps)}
+                    disabled={isDisabled}
+                    style={{
+                        outline: isFocusVisible
+                            ? '2px solid rgb(var(--primary-color-500)/0.4)'
+                            : 'none',
+                    }}
+                    className="openapi-disclosure-group-trigger"
+                >
+                    <div className="openapi-disclosure-group-icon">
+                        {icon || (
+                            <svg viewBox="0 0 24 24" className="openapi-disclosure-group-icon">
+                                <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+                            </svg>
+                        )}
+                    </div>
+
+                    {group.label}
+                </button>
+                {group.tabs ? (
+                    <div className="openapi-disclosure-group-mediatype">
+                        {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);
+                                    state.expand();
+                                }}
+                            >
+                                {group.tabs.map((tab) => (
+                                    <option key={tab.id} value={tab.id}>
+                                        {tab.label}
+                                    </option>
+                                ))}
+                            </select>
+                        ) : !!group.tabs[0] ? (
+                            <span>{group.tabs[0].label}</span>
+                        ) : null}
+                    </div>
+                ) : null}
+            </div>
+
+            {state.isExpanded && selectedTab && (
+                <div className="openapi-disclosure-group-panel" ref={panelRef} {...panelProps}>
+                    {selectedTab.body}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/OpenAPIOperation.tsx

@@ -1,14 +1,12 @@
-import * as React from 'react';
-import classNames from 'classnames';
-import { ApiClientModalProvider } from '@scalar/api-client-react';
+import clsx from 'clsx';
 
-import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
 import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
-import { OpenAPIServerURL } from './OpenAPIServerURL';
 import { OpenAPISpec } from './OpenAPISpec';
-import { OpenAPIClientContext, OpenAPIContextProps } from './types';
+import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { OpenAPIPath } from './OpenAPIPath';
+import { resolveDescription } from './utils';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -19,7 +17,7 @@ export function OpenAPIOperation(props: {
     context: OpenAPIContextProps;
 }) {
     const { className, data, context } = props;
-    const { operation, servers, method, path } = data;
+    const { operation } = data;
 
     const clientContext: OpenAPIClientContext = {
         defaultInteractiveOpened: context.defaultInteractiveOpened,
@@ -27,46 +25,42 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
+    const description = resolveDescription(operation)?.trim();
+
     return (
-        <ApiClientModalProvider
-            configuration={{ spec: { url: context.specUrl } }}
-            initialRequest={{ path: data.path, method: data.method }}
-        >
-            <div className={classNames('openapi-operation', className)}>
-                <div className="openapi-intro">
-                    <h2 className="openapi-summary" id={context.id}>
-                        {operation.summary}
-                    </h2>
-                    {operation.description ? (
-                        <Markdown className="openapi-description" source={operation.description} />
+        <div className={clsx('openapi-operation', className)}>
+            <div className="openapi-summary" id={context.id}>
+                <h2 className="openapi-summary-title" data-deprecated={operation.deprecated}>
+                    {operation.summary}
+                </h2>
+                {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
+            </div>
+            <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}
-                    <div className="openapi-target">
-                        <span
-                            className={classNames(
-                                'openapi-method',
-                                `openapi-method-${method.toLowerCase()}`,
-                            )}
-                        >
-                            {method.toUpperCase()}
-                        </span>
-                        <span className="openapi-url">
-                            <OpenAPIServerURL servers={servers} />
-                            {path}
-                        </span>
-                    </div>
-                </div>
-                <div className={classNames('openapi-columns')}>
-                    <div className={classNames('openapi-column-spec')}>
-                        <OpenAPISpec rawData={toJSON(data)} context={clientContext} />
-                    </div>
-                    <div className={classNames('openapi-column-preview')}>
-                        <div className={classNames('openapi-column-preview-body')}>
-                            <OpenAPICodeSample {...props} />
-                            <OpenAPIResponseExample {...props} />
+                    {description ? (
+                        <div className="openapi-intro">
+                            <Markdown className="openapi-description" source={description} />
                         </div>
+                    ) : null}
+                    <OpenAPIPath data={data} context={context} />
+                    <OpenAPISpec data={data} context={clientContext} />
+                </div>
+                <div className="openapi-column-preview">
+                    <div className="openapi-column-preview-body">
+                        <OpenAPICodeSample {...props} />
+                        <OpenAPIResponseExample {...props} />
                     </div>
                 </div>
             </div>
-        </ApiClientModalProvider>
+        </div>
     );
 }