@gitbook/react-openapi 1.0.3 → 1.0.5

package/src/OpenAPISchema.tsx

@@ -4,11 +4,11 @@ import { useId } from 'react';
 
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
+import { OpenAPISchemaName } from './OpenAPISchemaName';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIClientContext } from './types';
 import { checkIsReference, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
-import { OpenAPISchemaName } from './OpenAPISchemaName';
-import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
@@ -27,7 +27,7 @@ export function OpenAPISchemaProperty(
         circularRefs?: CircularRefsIds;
         context: OpenAPIClientContext;
         className?: string;
-    },
+    }
 ) {
     const {
         schema,
@@ -49,20 +49,13 @@ export function OpenAPISchemaProperty(
 
     if (alternatives?.[0]?.length) {
         return (
-            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
-                <OpenAPISchemaPresentation {...props} />
-                {alternatives[0].map((alternative, index) => (
-                    <OpenAPISchemaAlternative
-                        key={`alternative-${index}`}
-                        schema={alternative}
-                        circularRefs={circularRefs}
-                        context={context}
-                    />
-                ))}
-                {parentCircularRef ? (
-                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
-                ) : null}
-            </InteractiveSection>
+            <OpenAPISchemaAlternativesItem
+                {...props}
+                circularRefs={circularRefs}
+                context={context}
+                alternatives={alternatives}
+                parentCircularRef={parentCircularRef}
+            />
         );
     }
 
@@ -126,9 +119,9 @@ export function OpenAPISchemaProperties(props: {
 
     return (
         <div id={id} className="openapi-schema-properties">
-            {properties.map((property) => (
+            {properties.map((property, index) => (
                 <OpenAPISchemaProperty
-                    key={property.propertyName}
+                    key={index}
                     circularRefs={circularRefs}
                     {...property}
                     context={context}
@@ -173,6 +166,25 @@ function OpenAPISchemaAlternative(props: {
     const id = useId();
     const subProperties = getSchemaProperties(schema);
     const description = resolveDescription(schema);
+    const alternatives = getSchemaAlternatives(schema, new Set(circularRefs?.keys()));
+
+    if (alternatives?.[0]?.length && !subProperties?.length) {
+        return (
+            <>
+                {description ? (
+                    <Markdown source={description} className="openapi-schema-description" />
+                ) : null}
+                <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                    <OpenAPISchemaAlternativesItem
+                        schema={schema}
+                        circularRefs={circularRefs}
+                        context={context}
+                        alternatives={alternatives}
+                    />
+                </OpenAPIDisclosure>
+            </>
+        );
+    }
 
     return (
         <>
@@ -193,6 +205,35 @@ function OpenAPISchemaAlternative(props: {
     );
 }
 
+function OpenAPISchemaAlternativesItem(
+    props: OpenAPISchemaPropertyEntry & {
+        circularRefs?: CircularRefsIds;
+        context: OpenAPIClientContext;
+        alternatives: OpenAPISchemaAlternatives;
+        parentCircularRef?: string;
+    }
+) {
+    const id = useId();
+    const { schema, circularRefs, context, alternatives, parentCircularRef } = props;
+
+    return (
+        <InteractiveSection id={id} className={clsx('openapi-schema')}>
+            <OpenAPISchemaPresentation {...props} />
+            {alternatives[0].map((alternative, index) => (
+                <OpenAPISchemaAlternative
+                    key={`alternative-${index}`}
+                    schema={alternative}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            ))}
+            {parentCircularRef ? (
+                <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+            ) : null}
+        </InteractiveSection>
+    );
+}
+
 /**
  * Render a circular reference to a schema.
  */
@@ -336,13 +377,18 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
     return null;
 }
 
+type OpenAPISchemaAlternatives = [
+    OpenAPIV3.SchemaObject[],
+    OpenAPIV3.DiscriminatorObject | undefined,
+];
+
 /**
  * Get the alternatives to display for a schema.
  */
 export function getSchemaAlternatives(
     schema: OpenAPIV3.SchemaObject,
-    ancestors: Set<OpenAPIV3.SchemaObject> = new Set(),
-): null | [OpenAPIV3.SchemaObject[], OpenAPIV3.DiscriminatorObject | undefined] {
+    ancestors: Set<OpenAPIV3.SchemaObject> = new Set()
+): null | OpenAPISchemaAlternatives {
     const downAncestors = new Set(ancestors).add(schema);
 
     if (schema.anyOf) {
@@ -363,14 +409,16 @@ export function getSchemaAlternatives(
 function flattenAlternatives(
     alternativeType: 'oneOf' | 'allOf' | 'anyOf',
     alternatives: OpenAPIV3.SchemaObject[],
-    ancestors: Set<OpenAPIV3.SchemaObject>,
+    ancestors: Set<OpenAPIV3.SchemaObject>
 ): OpenAPIV3.SchemaObject[] {
     return alternatives.reduce((acc, alternative) => {
         if (!!alternative[alternativeType] && !ancestors.has(alternative)) {
-            return [...acc, ...(getSchemaAlternatives(alternative, ancestors)?.[0] || [])];
+            acc.push(...(getSchemaAlternatives(alternative, ancestors)?.[0] || []));
+        } else {
+            acc.push(alternative);
         }
 
-        return [...acc, alternative];
+        return acc;
     }, [] as OpenAPIV3.SchemaObject[]);
 }
 
@@ -378,7 +426,7 @@ export function getSchemaTitle(
     schema: OpenAPIV3.SchemaObject,
 
     /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
-    discriminator?: OpenAPIV3.DiscriminatorObject,
+    discriminator?: OpenAPIV3.DiscriminatorObject
 ): string {
     // Try using the discriminator
     if (discriminator?.propertyName && schema.properties) {
@@ -406,7 +454,9 @@ export function getSchemaTitle(
         if (schema.format) {
             type += ` · ${schema.format}`;
         }
-    } else if ('anyOf' in schema) {
+    }
+
+    if ('anyOf' in schema) {
         type = 'any of';
     } else if ('oneOf' in schema) {
         type = 'one of';

package/src/OpenAPISchemaName.tsx

@@ -1,8 +1,9 @@
-import { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type React from 'react';
 
 interface OpenAPISchemaNameProps {
     schema?: OpenAPIV3.SchemaObject;
-    propertyName?: string | JSX.Element;
+    propertyName?: string | React.JSX.Element;
     required?: boolean;
     type?: string;
 }
@@ -11,7 +12,7 @@ interface OpenAPISchemaNameProps {
  * Display the schema name row.
  * It includes the property name, type, required and deprecated status.
  */
-export function OpenAPISchemaName(props: OpenAPISchemaNameProps): JSX.Element {
+export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
     const { schema, type, propertyName, required } = props;
 
     const additionalItems = schema && getAdditionalItems(schema);
@@ -52,7 +53,7 @@ function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
     }
 
     if (schema.nullable) {
-        additionalItems = ` | nullable`;
+        additionalItems = ' | nullable';
     }
 
     return additionalItems;

package/src/OpenAPISecurities.tsx

@@ -1,8 +1,8 @@
 import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
+import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { resolveDescription } from './utils';
 
 /**
@@ -65,7 +65,7 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                 return <OpenAPISchemaName propertyName="Authorization" type="string" required />;
             }
 
-            if (security.scheme == 'bearer') {
+            if (security.scheme === 'bearer') {
                 const description = resolveDescription(security);
                 return (
                     <>
@@ -73,7 +73,7 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                         {/** Show a default description if none is provided */}
                         {!description ? (
                             <Markdown
-                                source={`Bearer authentication header of the form Bearer ${`&lt;token&gt;`}.`}
+                                source={`Bearer authentication header of the form Bearer ${'&lt;token&gt;'}.`}
                                 className="openapi-securities-description"
                             />
                         ) : null}

package/src/OpenAPISpec.tsx

@@ -1,12 +1,10 @@
-'use client';
-
 import type { OpenAPI } from '@gitbook/openapi-parser';
 
-import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRequestBody } from './OpenAPIRequestBody';
 import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
+import { StaticSection } from './StaticSection';
 import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { parameterToProperty } from './utils';
 
@@ -32,7 +30,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
 
             {parameterGroups.map((group) => {
                 return (
-                    <InteractiveSection
+                    <StaticSection
                         key={group.key}
                         className="openapi-parameters"
                         header={group.label}
@@ -41,7 +39,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                             properties={group.parameters.map(parameterToProperty)}
                             context={context}
                         />
-                    </InteractiveSection>
+                    </StaticSection>
                 );
             })}
 

package/src/OpenAPITabs.tsx

@@ -1,12 +1,12 @@
 'use client';
 
-import { createContext, useContext, useEffect, useMemo, useState } from 'react';
-import { Key, Tab, TabList, TabPanel, Tabs, TabsProps } from 'react-aria-components';
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { type Key, Tab, TabList, TabPanel, Tabs, type TabsProps } from 'react-aria-components';
+import { useEventCallback } from 'usehooks-ts';
 import { Markdown } from './Markdown';
-import { useSyncedTabsGlobalState } from './useSyncedTabsGlobalState';
-import { useIntersectionObserver } from 'usehooks-ts';
+import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
 
-export type Tab = {
+export type TabItem = {
     key: Key;
     label: string;
     body: React.ReactNode;
@@ -14,8 +14,8 @@ export type Tab = {
 };
 
 type OpenAPITabsContextData = {
-    items: Tab[];
-    selectedTab: Tab;
+    items: TabItem[];
+    selectedTab: TabItem | null;
 };
 
 const OpenAPITabsContext = createContext<OpenAPITabsContextData | null>(null);
@@ -32,71 +32,57 @@ function useOpenAPITabsContext() {
  * The OpenAPI Tabs wrapper component.
  */
 export function OpenAPITabs(
-    props: React.PropsWithChildren<TabsProps & { items: Tab[]; stateKey?: string }>,
+    props: React.PropsWithChildren<TabsProps & { items: TabItem[]; stateKey?: string }>
 ) {
     const { children, items, stateKey } = props;
-    const isVisible = stateKey
-        ? useIntersectionObserver({
-              threshold: 0.1,
-              rootMargin: '200px',
-          })
-        : true;
-    const defaultTab = items[0] as Tab;
-    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState<Tab>();
-    const [selectedTabKey, setSelectedTabKey] = useState(() => {
-        if (isVisible && stateKey && syncedTabs && syncedTabs.has(stateKey)) {
-            const tabFromState = syncedTabs.get(stateKey);
-            return tabFromState?.key ?? items[0]?.key;
+    const [tabKey, setTabKey] = useState<Key | null>(() => {
+        if (stateKey && typeof window !== 'undefined') {
+            const store = getOrCreateTabStoreByKey(stateKey);
+            const tabKey = store.getState().tabKey;
+            if (tabKey) {
+                return tabKey;
+            }
         }
-        return items[0]?.key;
+        return items[0]?.key ?? null;
     });
-    const [selectedTab, setSelectedTab] = useState<Tab>(defaultTab);
-
-    const handleSelectionChange = (key: Key) => {
-        setSelectedTabKey(key);
-        if (stateKey) {
-            const tab = items.find((item) => item.key === key);
-
-            if (!tab) {
-                return;
-            }
-
-            setSyncedTabs((state) => {
-                const newState = new Map(state);
-                newState.set(stateKey, tab);
-                return newState;
-            });
+    const selectTab = useEventCallback((key: Key | null) => {
+        if (!key || key === tabKey) {
+            return;
         }
-    };
-
+        const tab = items.find((item) => item.key === key);
+        if (!tab) {
+            return;
+        }
+        setTabKey(key);
+    });
+    const selectedTab = items.find((item) => item.key === tabKey) ?? items[0] ?? null;
+    const cancelDeferRef = useRef<(() => void) | null>(null);
     useEffect(() => {
-        if (isVisible && stateKey && syncedTabs && syncedTabs.has(stateKey)) {
-            const tabFromState = syncedTabs.get(stateKey);
-
-            if (!items.some((item) => item.key === tabFromState?.key)) {
-                return setSelectedTab(defaultTab);
-            }
-
-            if (tabFromState && tabFromState?.key !== selectedTab?.key) {
-                const tabFromItems = items.find((item) => item.key === tabFromState.key);
-
-                if (!tabFromItems) {
-                    return;
-                }
-
-                setSelectedTab(tabFromItems);
-            }
+        if (!stateKey) {
+            return undefined;
         }
-    }, [isVisible, stateKey, syncedTabs, selectedTabKey]);
-
+        const store = getOrCreateTabStoreByKey(stateKey);
+        return store.subscribe((state) => {
+            cancelDeferRef.current?.();
+            cancelDeferRef.current = defer(() => selectTab(state.tabKey));
+        });
+    }, [stateKey, selectTab]);
+    useEffect(() => {
+        return () => cancelDeferRef.current?.();
+    }, []);
     const contextValue = useMemo(() => ({ items, selectedTab }), [items, selectedTab]);
-
     return (
         <OpenAPITabsContext.Provider value={contextValue}>
             <Tabs
                 className="openapi-tabs"
-                onSelectionChange={handleSelectionChange}
-                selectedKey={selectedTab?.key}
+                onSelectionChange={(tabKey) => {
+                    selectTab(tabKey);
+                    if (stateKey) {
+                        const store = getOrCreateTabStoreByKey(stateKey);
+                        store.setState({ tabKey });
+                    }
+                }}
+                selectedKey={tabKey}
             >
                 {children}
             </Tabs>
@@ -104,6 +90,11 @@ export function OpenAPITabs(
     );
 }
 
+const defer = (fn: () => void) => {
+    const id = setTimeout(fn, 0);
+    return () => clearTimeout(id);
+};
+
 /**
  * The OpenAPI Tabs list component.
  * This component should be used as a child of the OpenAPITabs component.
@@ -116,14 +107,14 @@ export function OpenAPITabsList() {
         <TabList className="openapi-tabs-list">
             {items.map((tab) => (
                 <Tab
+                    key={tab.key}
+                    id={tab.key}
                     style={({ isFocusVisible }) => ({
                         outline: isFocusVisible
                             ? '2px solid rgb(var(--primary-color-500)/0.4)'
                             : 'none',
                     })}
                     className="openapi-tabs-tab"
-                    key={`Tab-${tab.key}`}
-                    id={tab.key}
                 >
                     {tab.label}
                 </Tab>
@@ -144,12 +135,10 @@ export function OpenAPITabsPanels() {
         return null;
     }
 
+    const key = selectedTab.key.toString();
+
     return (
-        <TabPanel
-            key={`TabPanel-${selectedTab.key}`}
-            id={selectedTab.key.toString()}
-            className="openapi-tabs-panel"
-        >
+        <TabPanel key={key} id={key} className="openapi-tabs-panel">
             {selectedTab.body}
             {selectedTab.description ? (
                 <Markdown source={selectedTab.description} className="openapi-tabs-footer" />

package/src/ScalarApiButton.tsx

@@ -4,8 +4,8 @@ import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-re
 import { useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
-import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 import { useEventCallback } from 'usehooks-ts';
+import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 
 /**
  * Button which launches the Scalar API Client
@@ -48,7 +48,7 @@ export function ScalarApiButton({
                         path={path}
                         specUrl={specUrl}
                     />,
-                    document.body,
+                    document.body
                 )}
         </div>
     );
@@ -88,7 +88,7 @@ function ScalarModalController(props: {
     useImperativeHandle(
         props.controllerRef,
         () => ({ openClient: openClient ? () => openClient() : undefined }),
-        [openClient],
+        [openClient]
     );
 
     // Open the client when the component is mounted.

package/src/StaticSection.tsx

@@ -0,0 +1,59 @@
+import clsx from 'clsx';
+import { type ComponentPropsWithoutRef, forwardRef } from 'react';
+
+export function Section(props: ComponentPropsWithoutRef<'div'>) {
+    return <div {...props} className={clsx('openapi-section', props.className)} />;
+}
+
+export function SectionHeader(props: ComponentPropsWithoutRef<'div'>) {
+    return (
+        <div
+            {...props}
+            className={clsx(
+                'openapi-section-header',
+                props.className && `${props.className}-header`
+            )}
+        />
+    );
+}
+
+export function SectionHeaderContent(props: ComponentPropsWithoutRef<'div'>) {
+    return (
+        <div
+            {...props}
+            className={clsx(
+                'openapi-section-header-content',
+                props.className && `${props.className}-header-content`
+            )}
+        />
+    );
+}
+
+export const SectionBody = forwardRef(function SectionBody(
+    props: ComponentPropsWithoutRef<'div'>,
+    ref: React.ForwardedRef<HTMLDivElement>
+) {
+    return (
+        <div
+            ref={ref}
+            {...props}
+            className={clsx('openapi-section-body', props.className && `${props.className}-body`)}
+        />
+    );
+});
+
+export function StaticSection(props: {
+    className: string;
+    header: React.ReactNode;
+    children: React.ReactNode;
+}) {
+    const { className, header, children } = props;
+    return (
+        <Section className={className}>
+            <SectionHeader className={className}>
+                <SectionHeaderContent className={className}>{header}</SectionHeaderContent>
+            </SectionHeader>
+            <SectionBody className={className}>{children}</SectionBody>
+        </Section>
+    );
+}