Improve OpenAPI schemas block ungrouped style (#3092)

Author: gregberge

.changeset/strange-chicken-provide.md

@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Improve OpenAPI schemas block ungrouped style. Classnames have changed, please refer to this PR to update GBX.

packages/gitbook/src/app/middleware/(site)/(content)/[[...pathname]]/PageClientLayout.tsx

@@ -11,7 +11,7 @@ import { useScrollPage } from '@/components/hooks';
 export function PageClientLayout(props: { withSections?: boolean }) {
     // We use this hook in the page layout to ensure the elements for the blocks
     // are rendered before we scroll to a hash or to the top of the page
-    useScrollPage({ scrollMarginTop: props.withSections ? 50 : undefined });
+    useScrollPage({ scrollMarginTop: props.withSections ? 48 : undefined });
 
     useStripFallbackQueryParam();
     return null;

packages/gitbook/src/components/DocumentView/Heading.tsx

@@ -20,7 +20,15 @@ export function Heading(props: BlockProps<DocumentBlockHeading>) {
     return (
         <Tag
             id={id}
-            className={tcls(textStyle.textSize, 'heading', 'group', 'relative', 'grid', style)}
+            className={tcls(
+                textStyle.textSize,
+                'heading',
+                'group',
+                'relative',
+                'grid',
+                'scroll-m-12',
+                style
+            )}
         >
             <div
                 className={tcls(

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPIOperation.tsx

@@ -1,18 +1,14 @@
-import type { JSONDocument } from '@gitbook/api';
-import { Icon } from '@gitbook/icons';
 import { OpenAPIOperation as BaseOpenAPIOperation } from '@gitbook/react-openapi';
 
 import { resolveOpenAPIOperationBlock } from '@/lib/openapi/resolveOpenAPIOperationBlock';
 import { tcls } from '@/lib/tailwind';
 
 import type { BlockProps } from '../Block';
-import { PlainCodeBlock } from '../CodeBlock';
-import { DocumentView } from '../DocumentView';
-import { Heading } from '../Heading';
 
 import './scalar.css';
 import './style.css';
 import type { AnyOpenAPIOperationsBlock } from '@/lib/openapi/types';
+import { getOpenAPIContext } from './context';
 
 /**
  * Render an openapi block or an openapi-operation block.
@@ -55,56 +51,7 @@ async function OpenAPIOperationBody(props: BlockProps<AnyOpenAPIOperationsBlock>
     return (
         <BaseOpenAPIOperation
             data={data}
-            context={{
-                specUrl,
-                icons: {
-                    chevronDown: <Icon icon="chevron-down" />,
-                    chevronRight: <Icon icon="chevron-right" />,
-                    plus: <Icon icon="plus" />,
-                },
-                renderCodeBlock: (codeProps) => <PlainCodeBlock {...codeProps} />,
-                renderDocument: (documentProps) => (
-                    <DocumentView
-                        document={documentProps.document as JSONDocument}
-                        context={props.context}
-                        style="space-y-6"
-                        blockStyle="max-w-full"
-                    />
-                ),
-                renderHeading: (headingProps) => (
-                    <Heading
-                        document={props.document}
-                        ancestorBlocks={props.ancestorBlocks}
-                        isEstimatedOffscreen={props.isEstimatedOffscreen}
-                        context={props.context}
-                        style={tcls([
-                            headingProps.deprecated ? 'line-through' : undefined,
-                            headingProps.deprecated || !!headingProps.stability
-                                ? '[&>div]:mt-0'
-                                : undefined,
-                        ])}
-                        block={{
-                            object: 'block',
-                            key: `${block.key}-heading`,
-                            meta: block.meta,
-                            data: {},
-                            type: 'heading-2',
-                            nodes: [
-                                {
-                                    key: `${block.key}-heading-text`,
-                                    object: 'text',
-                                    leaves: [
-                                        { text: headingProps.title, object: 'leaf', marks: [] },
-                                    ],
-                                },
-                            ],
-                        }}
-                    />
-                ),
-                defaultInteractiveOpened: context.mode === 'print',
-                id: block.meta?.id,
-                blockKey: block.key,
-            }}
+            context={getOpenAPIContext({ props, specUrl })}
             className="openapi-block"
         />
     );

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPISchemas.tsx

@@ -1,13 +1,13 @@
 import { resolveOpenAPISchemasBlock } from '@/lib/openapi/resolveOpenAPISchemasBlock';
 import { tcls } from '@/lib/tailwind';
-import { Icon } from '@gitbook/icons';
 import { OpenAPISchemas as BaseOpenAPISchemas } from '@gitbook/react-openapi';
 
 import type { BlockProps } from '../Block';
 
 import './scalar.css';
 import './style.css';
 import type { OpenAPISchemasBlock } from '@/lib/openapi/types';
+import { getOpenAPIContext } from './context';
 
 /**
  * Render an openapi-schemas block.
@@ -49,19 +49,9 @@ async function OpenAPISchemasBody(props: BlockProps<OpenAPISchemasBlock>) {
 
     return (
         <BaseOpenAPISchemas
-            data={data}
+            schemas={data.schemas}
             grouped={block.data.grouped}
-            context={{
-                specUrl,
-                icons: {
-                    chevronDown: <Icon icon="chevron-down" />,
-                    chevronRight: <Icon icon="chevron-right" />,
-                    plus: <Icon icon="plus" />,
-                },
-                defaultInteractiveOpened: context.mode === 'print',
-                id: block.meta?.id,
-                blockKey: block.key,
-            }}
+            context={getOpenAPIContext({ props, specUrl })}
             className="openapi-block"
         />
     );

packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx

@@ -0,0 +1,73 @@
+import type { JSONDocument } from '@gitbook/api';
+import { Icon } from '@gitbook/icons';
+import type { OpenAPIContext } from '@gitbook/react-openapi';
+
+import { tcls } from '@/lib/tailwind';
+
+import type { BlockProps } from '../Block';
+import { PlainCodeBlock } from '../CodeBlock';
+import { DocumentView } from '../DocumentView';
+import { Heading } from '../Heading';
+
+import './scalar.css';
+import './style.css';
+import type { AnyOpenAPIOperationsBlock, OpenAPISchemasBlock } from '@/lib/openapi/types';
+
+/**
+ * Get the OpenAPI context to render a block.
+ */
+export function getOpenAPIContext(args: {
+    props: BlockProps<AnyOpenAPIOperationsBlock | OpenAPISchemasBlock>;
+    specUrl: string;
+}): OpenAPIContext {
+    const { props, specUrl } = args;
+    const { block } = props;
+    return {
+        specUrl,
+        icons: {
+            chevronDown: <Icon icon="chevron-down" />,
+            chevronRight: <Icon icon="chevron-right" />,
+            plus: <Icon icon="plus" />,
+        },
+        renderCodeBlock: (codeProps) => <PlainCodeBlock {...codeProps} />,
+        renderDocument: (documentProps) => (
+            <DocumentView
+                document={documentProps.document as JSONDocument}
+                context={props.context}
+                style="space-y-6"
+                blockStyle="max-w-full"
+            />
+        ),
+        renderHeading: (headingProps) => (
+            <Heading
+                document={props.document}
+                ancestorBlocks={props.ancestorBlocks}
+                isEstimatedOffscreen={props.isEstimatedOffscreen}
+                context={props.context}
+                style={tcls([
+                    headingProps.deprecated ? 'line-through' : undefined,
+                    headingProps.deprecated || !!headingProps.stability
+                        ? '[&>div]:mt-0'
+                        : undefined,
+                ])}
+                block={{
+                    object: 'block',
+                    key: `${block.key}-heading`,
+                    meta: block.meta,
+                    data: {},
+                    type: 'heading-2',
+                    nodes: [
+                        {
+                            key: `${block.key}-heading-text`,
+                            object: 'text',
+                            leaves: [{ text: headingProps.title, object: 'leaf', marks: [] }],
+                        },
+                    ],
+                }}
+            />
+        ),
+        defaultInteractiveOpened: props.context.mode === 'print',
+        id: block.meta?.id,
+        blockKey: block.key,
+    };
+}

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -1,5 +1,6 @@
 /* Layout Components */
-.openapi-operation {
+.openapi-operation,
+.openapi-schemas {
     @apply flex-1 flex flex-col gap-8 mb-14 min-w-0;
 }
 
@@ -17,7 +18,7 @@
 }
 
 .openapi-summary {
-    @apply flex flex-col items-start justify-start gap-3;
+    @apply flex flex-col items-start justify-start gap-3 scroll-m-12;
 }
 
 .openapi-summary-tags {
@@ -483,12 +484,30 @@
     @apply flex flex-row items-center py-2 px-3 justify-end border-t border-tint-subtle;
 }
 
-/* Response Example */
-.openapi-response-example {
+/* Panel */
+.openapi-panel {
     @apply border rounded bg-tint border-tint-subtle;
 }
 
-.openapi-response-example-empty {
+.openapi-panel-heading {
+    @apply font-medium px-4 py-2 text-xs uppercase;
+}
+
+.openapi-panel-body {
+    @apply theme-gradient:bg-tint-12/1 relative;
+    @apply before:w-full before:h-px before:absolute before:bg-tint-6 before:-top-px before:z-10;
+}
+
+.openapi-panel-footer {
+    @apply px-3 py-2 pt-2.5 border-t border-tint-subtle text-[0.813rem] text-tint;
+}
+
+.openapi-panel-footer .openapi-markdown {
+    @apply text-[0.813rem] text-tint;
+}
+
+/* Example */
+.openapi-example-empty {
     @apply relative text-tint bg-tint min-h-20 flex flex-col justify-center items-center;
 }
 
@@ -559,15 +578,6 @@
 
 .openapi-tabs-panel {
     @apply flex-1 text-sm relative focus-visible:outline-none;
-    @apply before:w-full before:h-px before:absolute before:bg-tint-6 before:-top-px before:z-10;
-}
-
-.openapi-tabs-footer {
-    @apply px-3 py-2 pt-2.5 border-t border-tint-subtle text-[0.813rem] text-tint;
-}
-
-.openapi-tabs-footer .openapi-markdown {
-    @apply text-[0.813rem] text-tint;
 }
 
 /* Disclosure group */

packages/gitbook/src/components/SitePage/PageClientLayout.tsx

@@ -11,7 +11,7 @@ import { useScrollPage } from '@/components/hooks';
 export function PageClientLayout(props: { withSections?: boolean }) {
     // We use this hook in the page layout to ensure the elements for the blocks
     // are rendered before we scroll to a hash or to the top of the page
-    useScrollPage({ scrollMarginTop: props.withSections ? 50 : undefined });
+    useScrollPage({ scrollMarginTop: props.withSections ? 48 : undefined });
 
     useStripFallbackQueryParam();
     return null;

packages/gitbook/src/lib/document-sections.ts

@@ -3,6 +3,7 @@ import type { GitBookAnyContext } from '@v2/lib/context';
 
 import { getNodeText } from './document';
 import { resolveOpenAPIOperationBlock } from './openapi/resolveOpenAPIOperationBlock';
+import { resolveOpenAPISchemasBlock } from './openapi/resolveOpenAPISchemasBlock';
 
 export interface DocumentSection {
     id: string;
@@ -52,6 +53,26 @@ export async function getDocumentSections(
                 });
             }
         }
+
+        if (
+            block.type === 'openapi-schemas' &&
+            !block.data.grouped &&
+            block.meta?.id &&
+            block.data.schemas.length === 1
+        ) {
+            const { data } = await resolveOpenAPISchemasBlock({
+                block,
+                context,
+            });
+            const schema = data?.schemas[0];
+            if (schema) {
+                sections.push({
+                    id: block.meta.id,
+                    title: `The ${schema.name} object`,
+                    depth: 1,
+                });
+            }
+        }
     }
 
     return sections;

packages/gitbook/src/lib/openapi/resolveOpenAPISchemasBlock.ts

@@ -1,13 +1,15 @@
-import { OpenAPIParseError } from '@gitbook/openapi-parser';
-import { type OpenAPISchemasData, resolveOpenAPISchemas } from '@gitbook/react-openapi';
+import { OpenAPIParseError, type OpenAPISchema } from '@gitbook/openapi-parser';
+import { resolveOpenAPISchemas } from '@gitbook/react-openapi';
 import { fetchOpenAPIFilesystem } from './fetch';
 import type {
     OpenAPISchemasBlock,
     ResolveOpenAPIBlockArgs,
     ResolveOpenAPIBlockResult,
 } from './types';
 
-type ResolveOpenAPISchemasBlockResult = ResolveOpenAPIBlockResult<OpenAPISchemasData>;
+type ResolveOpenAPISchemasBlockResult = ResolveOpenAPIBlockResult<{
+    schemas: OpenAPISchema[];
+}>;
 
 const weakmap = new WeakMap<OpenAPISchemasBlock, Promise<ResolveOpenAPISchemasBlockResult>>();