@gitbook/react-openapi 1.0.4 → 1.1.0

package/src/OpenAPITabs.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { type Key, Tab, TabList, TabPanel, Tabs, type TabsProps } from 'react-aria-components';
-import { useIntersectionObserver } from 'usehooks-ts';
+import { useEventCallback } from 'usehooks-ts';
 import { Markdown } from './Markdown';
-import { useSyncedTabsGlobalState } from './useSyncedTabsGlobalState';
+import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
 
 export type TabItem = {
     key: Key;
@@ -15,7 +15,7 @@ export type TabItem = {
 
 type OpenAPITabsContextData = {
     items: TabItem[];
-    selectedTab: TabItem;
+    selectedTab: TabItem | null;
 };
 
 const OpenAPITabsContext = createContext<OpenAPITabsContextData | null>(null);
@@ -35,68 +35,54 @@ export function OpenAPITabs(
     props: React.PropsWithChildren<TabsProps & { items: TabItem[]; stateKey?: string }>
 ) {
     const { children, items, stateKey } = props;
-    const [ref, isIntersectionVisible] = useIntersectionObserver({
-        threshold: 0.1,
-        rootMargin: '200px',
-    });
-    const isVisible = stateKey ? isIntersectionVisible : true;
-    const defaultTab = items[0] as TabItem;
-    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState<TabItem>();
-    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<TabItem>(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
-                ref={ref}
                 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

@@ -1,24 +1,21 @@
 'use client';
 
 import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-react';
-import { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
-import { useEventCallback } from 'usehooks-ts';
+import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 
 /**
  * Button which launches the Scalar API Client
  */
-export function ScalarApiButton({
-    method,
-    path,
-    specUrl,
-}: {
-    method: string;
+export function ScalarApiButton(props: {
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     specUrl: string;
 }) {
+    const { method, path, specUrl } = props;
     const [isOpen, setIsOpen] = useState(false);
     const controllerRef = useRef<ScalarModalControllerRef>(null);
     return (
@@ -55,21 +52,18 @@ export function ScalarApiButton({
 }
 
 function ScalarModal(props: {
-    method: string;
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     specUrl: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
+    const { method, path, specUrl, controllerRef } = props;
     return (
         <ApiClientModalProvider
-            configuration={{ spec: { url: props.specUrl } }}
-            initialRequest={{ path: props.path, method: props.method }}
+            configuration={{ spec: { url: specUrl } }}
+            initialRequest={{ method, path }}
         >
-            <ScalarModalController
-                method={props.method}
-                path={props.path}
-                controllerRef={props.controllerRef}
-            />
+            <ScalarModalController method={method} path={path} controllerRef={controllerRef} />
         </ApiClientModalProvider>
     );
 }
@@ -79,28 +73,32 @@ type ScalarModalControllerRef = {
 };
 
 function ScalarModalController(props: {
-    method: string;
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
+    const { method, path, controllerRef } = props;
     const client = useApiClientModal();
-    const openClient = client?.open;
+    const openScalarClient = client?.open;
+    const { onOpenClient: trackClientOpening } = useOpenAPIOperationContext();
+    const openClient = useMemo(() => {
+        if (openScalarClient) {
+            return () => {
+                openScalarClient({ method, path, _source: 'gitbook' });
+                trackClientOpening({ method, path });
+            };
+        }
+        return null;
+    }, [openScalarClient, method, path, trackClientOpening]);
     useImperativeHandle(
-        props.controllerRef,
+        controllerRef,
         () => ({ openClient: openClient ? () => openClient() : undefined }),
         [openClient]
     );
 
-    // Open the client when the component is mounted.
-    const { onOpenClient } = useOpenAPIOperationContext();
-    const trackOpening = useEventCallback(() => {
-        onOpenClient({ method: props.method, path: props.path });
-    });
+    // Open at mount
     useEffect(() => {
-        if (openClient) {
-            openClient();
-            trackOpening();
-        }
+        openClient?.();
     }, [openClient]);
     return null;
 }

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>
+    );
+}

package/src/dereference.ts

@@ -0,0 +1,29 @@
+import { type Filesystem, type OpenAPIV3xDocument, dereference } from '@gitbook/openapi-parser';
+
+const dereferenceCache = new WeakMap<Filesystem, Promise<OpenAPIV3xDocument>>();
+
+/**
+ * Memoized version of `dereferenceSchema`.
+ */
+export function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    if (dereferenceCache.has(filesystem)) {
+        return dereferenceCache.get(filesystem) as Promise<OpenAPIV3xDocument>;
+    }
+
+    const promise = baseDereferenceFilesystem(filesystem);
+    dereferenceCache.set(filesystem, promise);
+    return promise;
+}
+
+/**
+ * Dereference an OpenAPI schema.
+ */
+async function baseDereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    const result = await dereference(filesystem);
+
+    if (!result.schema) {
+        throw new Error('Failed to dereference OpenAPI document');
+    }
+
+    return result.schema as OpenAPIV3xDocument;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from './resolveOpenAPIOperation';
+export * from './models';
 export * from './OpenAPIOperation';
 export * from './OpenAPIOperationContext';
-export type { OpenAPIOperationData } from './types';
+export * from './resolveOpenAPIOperation';
+export type { OpenAPIModelsData, OpenAPIOperationData } from './types';

package/src/models/OpenAPIModels.tsx

@@ -0,0 +1,89 @@
+import clsx from 'clsx';
+import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
+import { OpenAPIRootSchema } from '../OpenAPISchema';
+import { Section, SectionBody } from '../StaticSection';
+import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIModelsData } from '../types';
+
+/**
+ * Display OpenAPI Models.
+ */
+export function OpenAPIModels(props: {
+    className?: string;
+    data: OpenAPIModelsData;
+    context: OpenAPIContextProps;
+}) {
+    const { className, data, context } = props;
+    const { models } = data;
+
+    const clientContext: OpenAPIClientContext = {
+        defaultInteractiveOpened: context.defaultInteractiveOpened,
+        icons: context.icons,
+        blockKey: context.blockKey,
+    };
+
+    if (!models.length) {
+        return null;
+    }
+
+    return (
+        <div className={clsx('openapi-models', className)}>
+            <OpenAPIRootModelsSchema models={models} context={clientContext} />
+        </div>
+    );
+}
+
+/**
+ * Root schema for OpenAPI models.
+ * It displays a single model or a disclosure group for multiple models.
+ */
+function OpenAPIRootModelsSchema(props: {
+    models: OpenAPIModelsData['models'];
+    context: OpenAPIClientContext;
+}) {
+    const { models, context } = props;
+
+    // If there is only one model, we show it directly.
+    if (models.length === 1) {
+        const schema = models?.[0]?.schema;
+
+        if (!schema) {
+            return null;
+        }
+
+        return (
+            <Section>
+                <SectionBody>
+                    <OpenAPIRootSchema schema={schema} context={context} />
+                </SectionBody>
+            </Section>
+        );
+    }
+
+    // If there are multiple models, we use a disclosure group to show them all.
+    return (
+        <OpenAPIDisclosureGroup
+            allowsMultipleExpanded
+            icon={context.icons.chevronRight}
+            groups={models.map(({ name, schema }) => ({
+                id: name,
+                label: (
+                    <div className="openapi-response-tab-content" key={`model-${name}`}>
+                        <span className="openapi-response-statuscode">{name}</span>
+                    </div>
+                ),
+                tabs: [
+                    {
+                        id: 'model',
+                        body: (
+                            <Section className="openapi-section-models">
+                                <SectionBody>
+                                    <OpenAPIRootSchema schema={schema} context={context} />
+                                </SectionBody>
+                            </Section>
+                        ),
+                    },
+                ],
+            }))}
+        />
+    );
+}

package/src/models/index.ts

@@ -0,0 +1,2 @@
+export * from './OpenAPIModels';
+export * from './resolveOpenAPIModels';

package/src/models/resolveOpenAPIModels.ts

@@ -0,0 +1,35 @@
+import {
+    type Filesystem,
+    type OpenAPIV3,
+    type OpenAPIV3_1,
+    type OpenAPIV3xDocument,
+    shouldIgnoreEntity,
+} from '@gitbook/openapi-parser';
+import { dereferenceFilesystem } from '../dereference';
+import type { OpenAPIModel, OpenAPIModelsData } from '../types';
+
+//!!TODO: We should return only the models that are used in the block. Still a WIP awaiting future work.
+
+/**
+ * Resolve an OpenAPI models from a file and compile it to a more usable format.
+ * Models are extracted from the OpenAPI components.schemas
+ */
+export async function resolveOpenAPIModels(
+    filesystem: Filesystem<OpenAPIV3xDocument>
+): Promise<OpenAPIModelsData | null> {
+    const schema = await dereferenceFilesystem(filesystem);
+
+    const models = getOpenAPIComponents(schema);
+
+    return { models };
+}
+
+/**
+ * Get OpenAPI components.schemas that are not ignored.
+ */
+function getOpenAPIComponents(schema: OpenAPIV3.Document | OpenAPIV3_1.Document): OpenAPIModel[] {
+    const schemas = schema.components?.schemas ?? {};
+    return Object.entries(schemas)
+        .filter(([, schema]) => !shouldIgnoreEntity(schema))
+        .map(([key, schema]) => ({ name: key, schema }));
+}

package/src/resolveOpenAPIOperation.ts

@@ -1,16 +1,16 @@
 import { fromJSON, toJSON } from 'flatted';
 
-import {
-    type Filesystem,
-    type OpenAPIV3,
-    type OpenAPIV3_1,
-    type OpenAPIV3xDocument,
-    dereference,
+import type {
+    Filesystem,
+    OpenAPIV3,
+    OpenAPIV3_1,
+    OpenAPIV3xDocument,
 } from '@gitbook/openapi-parser';
+import { dereferenceFilesystem } from './dereference';
 import type { OpenAPIOperationData } from './types';
 import { checkIsReference } from './utils';
 
-export { toJSON, fromJSON };
+export { fromJSON, toJSON };
 
 /**
  * Resolve an OpenAPI operation in a file and compile it to a more usable format.
@@ -23,7 +23,7 @@ export async function resolveOpenAPIOperation(
     }
 ): Promise<OpenAPIOperationData | null> {
     const { path, method } = operationDescriptor;
-    const schema = await memoDereferenceFilesystem(filesystem);
+    const schema = await dereferenceFilesystem(filesystem);
     let operation = getOperationByPathAndMethod(schema, path, method);
 
     if (!operation) {
@@ -69,34 +69,6 @@ export async function resolveOpenAPIOperation(
     };
 }
 
-const dereferenceCache = new WeakMap<Filesystem, Promise<OpenAPIV3xDocument>>();
-
-/**
- * Memoized version of `dereferenceSchema`.
- */
-function memoDereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
-    if (dereferenceCache.has(filesystem)) {
-        return dereferenceCache.get(filesystem) as Promise<OpenAPIV3xDocument>;
-    }
-
-    const promise = dereferenceFilesystem(filesystem);
-    dereferenceCache.set(filesystem, promise);
-    return promise;
-}
-
-/**
- * Dereference an OpenAPI schema.
- */
-async function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
-    const result = await dereference(filesystem);
-
-    if (!result.schema) {
-        throw new Error('Failed to dereference OpenAPI document');
-    }
-
-    return result.schema as OpenAPIV3xDocument;
-}
-
 /**
  * Get a path object from its path.
  */

package/src/types.ts

@@ -55,3 +55,13 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Securities that should be used for this operation */
     securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }
+
+export type OpenAPIModel = {
+    name: string;
+    schema: OpenAPIV3.SchemaObject;
+};
+
+export interface OpenAPIModelsData {
+    /** Components schemas to be used for models */
+    models: OpenAPIModel[];
+}

package/src/useSyncedTabsGlobalState.ts

@@ -1,23 +1,35 @@
 'use client';
 
-import { create } from 'zustand';
-
-interface SyncedTabsState<T> {
-    tabs: Map<string, T>;
-    setTabs: (updater: (tabs: Map<string, T>) => Map<string, T>) => void;
-}
-
-const useSyncedTabsStore = create<SyncedTabsState<any>>()((set) => ({
-    tabs: new Map<string, any>(),
-    setTabs: (updater) =>
-        set((state) => ({
-            tabs: updater(new Map(state.tabs)), // Ensure a new Map is created for reactivity
-        })),
-}));
-
-// Selector for better performance - only re-renders when tabs change
-export function useSyncedTabsGlobalState<T>() {
-    const tabs = useSyncedTabsStore((state) => state.tabs as Map<string, T>);
-    const setTabs = useSyncedTabsStore((state) => state.setTabs as SyncedTabsState<T>['setTabs']);
-    return [tabs, setTabs] as const;
-}
+import { createStore } from 'zustand';
+
+type Key = string | number;
+
+type TabState = {
+    tabKey: Key | null;
+};
+
+type TabActions = { setTabKey: (tab: Key | null) => void };
+
+type TabStore = TabState & TabActions;
+
+const createTabStore = (initialTab?: Key) => {
+    return createStore<TabStore>()((set) => ({
+        tabKey: initialTab ?? null,
+        setTabKey: (tabKey) => {
+            set(() => ({ tabKey }));
+        },
+    }));
+};
+
+const defaultTabStores = new Map<string, ReturnType<typeof createTabStore>>();
+
+const createTabStoreFactory = (stores: typeof defaultTabStores) => {
+    return (storeKey: string, initialKey?: Key) => {
+        if (!stores.has(storeKey)) {
+            stores.set(storeKey, createTabStore(initialKey));
+        }
+        return stores.get(storeKey)!;
+    };
+};
+
+export const getOrCreateTabStoreByKey = createTabStoreFactory(defaultTabStores);