@gitbook/react-openapi 1.0.4 → 1.1.0

package/dist/types.d.ts

@@ -51,3 +51,11 @@ 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/dist/useSyncedTabsGlobalState.d.ts

@@ -1 +1,10 @@
-export declare function useSyncedTabsGlobalState<T>(): readonly [Map<string, T>, (updater: (tabs: Map<string, T>) => Map<string, T>) => void];
+type Key = string | number;
+type TabState = {
+    tabKey: Key | null;
+};
+type TabActions = {
+    setTabKey: (tab: Key | null) => void;
+};
+type TabStore = TabState & TabActions;
+export declare const getOrCreateTabStoreByKey: (storeKey: string, initialKey?: Key) => import("zustand").StoreApi<TabStore>;
+export {};

package/dist/useSyncedTabsGlobalState.js

@@ -1,16 +1,20 @@
 'use client';
-import { create } from 'zustand';
-var useSyncedTabsStore = create()(function (set) { return ({
-    tabs: new Map(),
-    setTabs: function (updater) {
-        return set(function (state) { return ({
-            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() {
-    var tabs = useSyncedTabsStore(function (state) { return state.tabs; });
-    var setTabs = useSyncedTabsStore(function (state) { return state.setTabs; });
-    return [tabs, setTabs];
-}
+import { createStore } from 'zustand';
+var createTabStore = function (initialTab) {
+    return createStore()(function (set) { return ({
+        tabKey: initialTab !== null && initialTab !== void 0 ? initialTab : null,
+        setTabKey: function (tabKey) {
+            set(function () { return ({ tabKey: tabKey }); });
+        },
+    }); });
+};
+var defaultTabStores = new Map();
+var createTabStoreFactory = function (stores) {
+    return function (storeKey, initialKey) {
+        if (!stores.has(storeKey)) {
+            stores.set(storeKey, createTabStore(initialKey));
+        }
+        return stores.get(storeKey);
+    };
+};
+export var getOrCreateTabStoreByKey = createTabStoreFactory(defaultTabStores);

package/dist/utils.js

@@ -9,17 +9,25 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
 export function createStateKey(key, scope) {
     return scope ? "".concat(scope, "_").concat(key) : key;
 }
+/**
+ * Check if an object has a description. Either at the root level or in items.
+ */
+function hasDescription(object) {
+    return 'description' in object || 'x-gitbook-description-html' in object;
+}
 /**
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    if ('items' in object && object.items) {
+    // If the object has items and has a description, we resolve the description from items
+    if ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
         return resolveDescription(object.items);
     }
     return 'x-gitbook-description-html' in object &&
@@ -51,8 +59,13 @@ export function resolveFirstExample(object) {
             return object.examples[firstKey];
         }
     }
-    if ('example' in object && object.example !== undefined) {
-        return object.example;
+    // Resolve top level example first
+    if (shouldDisplayExample(object)) {
+        return formatExample(object.example);
+    }
+    // Resolve example from items if it exists
+    if (object.items && typeof object.items === 'object') {
+        return formatExample(object.items.example);
     }
     return undefined;
 }
@@ -84,3 +97,29 @@ export function parameterToProperty(parameter) {
         required: parameter.required,
     };
 }
+/**
+ * Format the example of a schema.
+ */
+function formatExample(example) {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
+    }
+    return stringifyOpenAPI(example);
+}
+/**
+ * Check if an example should be displayed.
+ */
+function shouldDisplayExample(schema) {
+    return ((typeof schema.example === 'string' && !!schema.example) ||
+        typeof schema.example === 'number' ||
+        typeof schema.example === 'boolean' ||
+        (Array.isArray(schema.example) && schema.example.length > 0) ||
+        (typeof schema.example === 'object' &&
+            schema.example !== null &&
+            Object.keys(schema.example).length > 0));
+}

package/package.json

@@ -8,12 +8,12 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.4",
+    "version": "1.1.0",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "1.0.87",
-        "@scalar/oas-utils": "^0.2.101",
+        "@scalar/api-client-react": "^1.1.36",
+        "@scalar/oas-utils": "^0.2.110",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",

package/src/InteractiveSection.tsx

@@ -4,6 +4,7 @@ import clsx from 'clsx';
 import { useRef, useState } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
+import { Section, SectionBody, SectionHeader, SectionHeaderContent } from './StaticSection';
 
 interface InteractiveSectionTab {
     key: string;
@@ -63,7 +64,7 @@ export function InteractiveSection(props: {
     const { isFocusVisible, focusProps } = useFocusRing();
 
     return (
-        <div
+        <Section
             id={id}
             className={clsx(
                 'openapi-section',
@@ -73,20 +74,15 @@ export function InteractiveSection(props: {
             )}
         >
             {header ? (
-                <div
+                <SectionHeader
                     onClick={() => {
                         if (toggeable) {
                             state.toggle();
                         }
                     }}
-                    className={clsx('openapi-section-header', `${className}-header`)}
+                    className={className}
                 >
-                    <div
-                        className={clsx(
-                            'openapi-section-header-content',
-                            `${className}-header-content`
-                        )}
-                    >
+                    <SectionHeaderContent className={className}>
                         {(children || selectedTab?.body) && toggeable ? (
                             <button
                                 {...mergeProps(buttonProps, focusProps)}
@@ -102,7 +98,7 @@ export function InteractiveSection(props: {
                             </button>
                         ) : null}
                         {header}
-                    </div>
+                    </SectionHeaderContent>
                     <div
                         className={clsx(
                             'openapi-section-header-controls',
@@ -133,23 +129,19 @@ export function InteractiveSection(props: {
                             </select>
                         ) : null}
                     </div>
-                </div>
+                </SectionHeader>
             ) : null}
             {(!toggeable || state.isExpanded) && (children || selectedTab?.body) ? (
-                <div
-                    ref={panelRef}
-                    {...panelProps}
-                    className={clsx('openapi-section-body', `${className}-body`)}
-                >
+                <SectionBody ref={panelRef} {...panelProps} className={className}>
                     {children}
                     {selectedTab?.body}
-                </div>
+                </SectionBody>
             ) : null}
             {overlay ? (
                 <div className={clsx('openapi-section-overlay', `${className}-overlay`)}>
                     {overlay}
                 </div>
             ) : null}
-        </div>
+        </Section>
     );
 }

package/src/OpenAPICodeSample.tsx

@@ -1,5 +1,5 @@
-import { InteractiveSection } from './InteractiveSection';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { StaticSection } from './StaticSection';
 import { type CodeSampleInput, codeSampleGenerators } from './code-samples';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
@@ -117,9 +117,9 @@ export function OpenAPICodeSample(props: {
 
     return (
         <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
-            <InteractiveSection header={<OpenAPITabsList />} className="openapi-codesample">
+            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
                 <OpenAPITabsPanels />
-            </InteractiveSection>
+            </StaticSection>
         </OpenAPITabs>
     );
 }

package/src/OpenAPIDisclosure.tsx

@@ -1,51 +1,44 @@
-import type React from 'react';
-import { useRef } from 'react';
-import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
-import { useDisclosureState } from 'react-stately';
+'use client';
+import { useState } from 'react';
+import { Button, Disclosure, DisclosurePanel, Heading } from 'react-aria-components';
 import type { OpenAPIClientContext } from './types';
 
-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): React.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();
+export function OpenAPIDisclosure(props: {
+    context: OpenAPIClientContext;
+    children: React.ReactNode;
+    label: string;
+}): React.JSX.Element {
+    const { context, children, label } = props;
+    const [isExpanded, setIsExpanded] = useState(false);
 
     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>
+        <Disclosure
+            className="openapi-disclosure"
+            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>
+            <DisclosurePanel className="openapi-disclosure-panel">
+                {isExpanded ? children : null}
+            </DisclosurePanel>
+        </Disclosure>
     );
 }

package/src/OpenAPIDisclosureGroup.tsx

@@ -1,3 +1,14 @@
+'use client';
+
+import { createContext, useContext, useRef, useState } from 'react';
+import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
+import {
+    type DisclosureGroupProps,
+    type DisclosureGroupState,
+    useDisclosureGroupState,
+    useDisclosureState,
+} from 'react-stately';
+
 interface Props {
     groups: TDisclosureGroup[];
     icon?: React.ReactNode;
@@ -8,20 +19,11 @@ type TDisclosureGroup = {
     label: string | React.ReactNode;
     tabs?: {
         id: string;
-        label: string | React.ReactNode;
+        label?: string | React.ReactNode;
         body?: React.ReactNode;
     }[];
 };
 
-import { createContext, useContext, useRef, useState } from 'react';
-import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
-import {
-    type DisclosureGroupProps,
-    type DisclosureGroupState,
-    useDisclosureGroupState,
-    useDisclosureState,
-} from 'react-stately';
-
 const DisclosureGroupStateContext = createContext<DisclosureGroupState | null>(null);
 
 /**
@@ -119,7 +121,7 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
                                     </option>
                                 ))}
                             </select>
-                        ) : group.tabs[0] ? (
+                        ) : group.tabs[0]?.label ? (
                             <span>{group.tabs[0].label}</span>
                         ) : null}
                     </div>

package/src/OpenAPIPath.tsx

@@ -1,3 +1,4 @@
+import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import type React from 'react';
 import { ScalarApiButton } from './ScalarApiButton';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
@@ -12,6 +13,7 @@ export function OpenAPIPath(props: {
     const { data, context } = props;
     const { method, path } = data;
     const { specUrl } = context;
+    const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
 
     return (
         <div className="openapi-path">
@@ -19,13 +21,17 @@ export function OpenAPIPath(props: {
             <div className="openapi-path-title" data-deprecated={data.operation.deprecated}>
                 <p>{formatPath(path)}</p>
             </div>
-            {data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
+            {!hideTryItPanel && validateHttpMethod(method) && (
                 <ScalarApiButton method={method} path={path} specUrl={specUrl} />
             )}
         </div>
     );
 }
 
+function validateHttpMethod(method: string): method is OpenAPIV3_1.HttpMethods {
+    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
+}
+
 // Format the path to highlight placeholders
 function formatPath(path: string) {
     // Matches placeholders like {id}, {userId}, etc.

package/src/OpenAPIResponseExample.tsx

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
-import { InteractiveSection } from './InteractiveSection';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { StaticSection } from './StaticSection';
 import { generateSchemaExample } from './generateSchemaExample';
 import { json2xml } from './json2xml';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
@@ -84,9 +84,9 @@ export function OpenAPIResponseExample(props: {
 
     return (
         <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
-            <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
+            <StaticSection header={<OpenAPITabsList />} className="openapi-response-example">
                 <OpenAPITabsPanels />
-            </InteractiveSection>
+            </StaticSection>
         </OpenAPITabs>
     );
 }
@@ -134,12 +134,9 @@ function OpenAPIResponse(props: {
 
     return (
         <OpenAPITabs stateKey={createStateKey('response-media-types')} items={tabs}>
-            <InteractiveSection
-                header={<OpenAPITabsList />}
-                className="openapi-response-media-types"
-            >
+            <StaticSection header={<OpenAPITabsList />} className="openapi-response-media-types">
                 <OpenAPITabsPanels />
-            </InteractiveSection>
+            </StaticSection>
         </OpenAPITabs>
     );
 }
@@ -173,23 +170,19 @@ function OpenAPIResponseMediaType(props: {
             key: example.key,
             label: example.example.summary || example.key,
             body: (
-                <OpenAPIExample
-                    example={firstExample.example}
-                    context={props.context}
-                    syntax={syntax}
-                />
+                <OpenAPIExample example={example.example} context={props.context} syntax={syntax} />
             ),
         };
     });
 
     return (
         <OpenAPITabs stateKey={createStateKey('response-media-type-examples')} items={tabs}>
-            <InteractiveSection
+            <StaticSection
                 header={<OpenAPITabsList />}
                 className="openapi-response-media-type-examples"
             >
                 <OpenAPITabsPanels />
-            </InteractiveSection>
+            </StaticSection>
         </OpenAPITabs>
     );
 }

package/src/OpenAPIResponses.tsx

@@ -1,8 +1,8 @@
 import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
 import { OpenAPIResponse } from './OpenAPIResponse';
+import { StaticSection } from './StaticSection';
 import type { OpenAPIClientContext } from './types';
 
 /**
@@ -15,7 +15,7 @@ export function OpenAPIResponses(props: {
     const { responses, context } = props;
 
     return (
-        <InteractiveSection header="Responses" className="openapi-responses">
+        <StaticSection header="Responses" className="openapi-responses">
             <OpenAPIDisclosureGroup
                 allowsMultipleExpanded
                 icon={context.icons.chevronRight}
@@ -58,6 +58,6 @@ export function OpenAPIResponses(props: {
                     }
                 )}
             />
-        </InteractiveSection>
+        </StaticSection>
     );
 }

package/src/OpenAPISchema.test.ts

@@ -23,18 +23,15 @@ describe('getSchemaAlternatives', () => {
                 ],
             })
         ).toEqual([
-            [
-                {
-                    type: 'number',
-                },
-                {
-                    type: 'boolean',
-                },
-                {
-                    type: 'string',
-                },
-            ],
-            undefined,
+            {
+                type: 'number',
+            },
+            {
+                type: 'boolean',
+            },
+            {
+                type: 'string',
+            },
         ]);
     });
 
@@ -58,22 +55,19 @@ describe('getSchemaAlternatives', () => {
                 ],
             })
         ).toEqual([
-            [
-                {
-                    allOf: [
-                        {
-                            type: 'number',
-                        },
-                        {
-                            type: 'boolean',
-                        },
-                    ],
-                },
-                {
-                    type: 'string',
-                },
-            ],
-            undefined,
+            {
+                allOf: [
+                    {
+                        type: 'number',
+                    },
+                    {
+                        type: 'boolean',
+                    },
+                ],
+            },
+            {
+                type: 'string',
+            },
         ]);
     });
 
@@ -89,13 +83,10 @@ describe('getSchemaAlternatives', () => {
         a.anyOf?.push(a);
 
         expect(getSchemaAlternatives(a)).toEqual([
-            [
-                {
-                    type: 'string',
-                },
-                a,
-            ],
-            undefined,
+            {
+                type: 'string',
+            },
+            a,
         ]);
     });
 });