Revert 'only allow resizing for non-hero'

Author: viktorrenkema

packages/gitbook/src/components/PageBody/PageCover.tsx

@@ -22,9 +22,8 @@ export async function PageCover(props: {
     cover: RevisionPageDocumentCover;
     context: GitBookSiteContext;
 }) {
-    const { as: coverType, page, cover, context } = props;
-
-    const height = getCoverHeight(cover, coverType);
+    const { as, page, cover, context } = props;
+    const height = getCoverHeight(cover);
 
     if (!height) {
         return null;
@@ -35,18 +34,25 @@ export async function PageCover(props: {
         cover.refDark ? resolveContentRef(cover.refDark, context) : null,
     ]);
 
+    // Calculate sizes based on cover type and page layout
+    // Hero covers: max-w-3xl (768px) on regular pages, max-w-screen-2xl (1536px) on wide pages
+    // Full covers: Can expand to full viewport width with negative margins (up to ~1920px+ on large screens)
+    const isWidePage = page.layout.width === 'wide';
+    const maxWidth = as === 'full' ? 1920 : isWidePage ? 1536 : 768;
+
     const sizes = [
-        // Cover takes the full width on mobile/table
+        // Cover takes the full width on mobile
         {
             media: '(max-width: 768px)',
             width: 768,
         },
+        // Tablet sizes
         {
             media: '(max-width: 1024px)',
             width: 1024,
         },
-        // Maximum size of the cover
-        { width: 1248 },
+        // Maximum size based on cover type and page layout
+        { width: maxWidth },
     ];
 
     const getImage = async (resolved: ResolvedContentRef | null, returnNull = false) => {
@@ -85,12 +91,12 @@ export async function PageCover(props: {
     return (
         <div
             id="page-cover"
-            data-full={String(coverType === 'full')}
+            data-full={String(as === 'full')}
             className={tcls(
                 'overflow-hidden',
                 // Negative margin to balance the container padding
                 '-mx-4',
-                coverType === 'full'
+                as === 'full'
                     ? [
                           'sm:-mx-6',
                           'md:-mx-8',
@@ -117,7 +123,6 @@ export async function PageCover(props: {
                 }}
                 y={cover.yPos}
                 height={height}
-                coverType={coverType}
             />
         </div>
     );

packages/gitbook/src/components/PageBody/PageCoverImage.tsx

@@ -1,6 +1,7 @@
 'use client';
 import { tcls } from '@/lib/tailwind';
 import type { ImageSize } from '../utils';
+import { getRecommendedCoverDimensions } from './coverDimensions';
 import { useCoverPosition } from './useCoverPosition';
 
 interface ImageAttributes {
@@ -17,16 +18,15 @@ interface Images {
     dark?: ImageAttributes;
 }
 
-const PAGE_COVER_SIZE: ImageSize = { width: 1990, height: 480 };
-
-export function PageCoverImage({
-    imgs,
-    y,
-    height,
-    coverType,
-}: { imgs: Images; y: number; height: number; coverType: 'hero' | 'full' }) {
+export function PageCoverImage({ imgs, y, height }: { imgs: Images; y: number; height: number }) {
     const { containerRef, objectPositionY, isLoading } = useCoverPosition(imgs, y);
 
+    // Calculate the recommended aspect ratio for this height
+    // This maintains the 4:1 ratio, allowing images to scale proportionally
+    // and adapt their height when container width doesn't match the ideal ratio
+    const recommendedDimensions = getRecommendedCoverDimensions(height);
+    const aspectRatio = recommendedDimensions.width / recommendedDimensions.height;
+
     if (isLoading) {
         return (
             <div className="h-full w-full overflow-hidden" ref={containerRef}>
@@ -36,23 +36,17 @@ export function PageCoverImage({
     }
 
     return (
-        <div className="h-full w-full overflow-hidden" ref={containerRef}>
+        <div className="h-full w-full overflow-hidden" ref={containerRef} style={{ height }}>
             <img
                 src={imgs.light.src}
                 srcSet={imgs.light.srcSet}
                 sizes={imgs.light.sizes}
                 fetchPriority="high"
                 alt="Page cover"
-                className={tcls(
-                    'w-full',
-                    coverType === 'hero' ? 'object-contain' : 'object-cover',
-                    imgs.dark ? 'dark:hidden' : ''
-                )}
+                className={tcls('w-full', 'object-cover', imgs.dark ? 'dark:hidden' : '')}
                 style={{
-                    aspectRatio:
-                        coverType === 'hero' ? `${height}/${PAGE_COVER_SIZE.height}` : undefined,
+                    aspectRatio: `${aspectRatio}`,
                     objectPosition: `50% ${objectPositionY}%`,
-                    height: coverType === 'full' ? `${height}px` : undefined,
                 }}
             />
             {imgs.dark && (
@@ -64,7 +58,7 @@ export function PageCoverImage({
                     alt="Page cover"
                     className={tcls('w-full', 'object-cover', 'dark:inline', 'hidden')}
                     style={{
-                        aspectRatio: `${PAGE_COVER_SIZE.width}/${PAGE_COVER_SIZE.height}`,
+                        aspectRatio: `${aspectRatio}`,
                         objectPosition: `50% ${objectPositionY}%`,
                     }}
                 />

packages/gitbook/src/components/PageBody/coverDimensions.ts

@@ -0,0 +1,75 @@
+/**
+ * Calculates the ideal cover image dimensions based on the cover type,
+ * page layout, and viewport constraints.
+ *
+ * The dimensions are optimized for:
+ * - Hero covers: max-w-3xl (768px) on regular pages, max-w-screen-2xl (1536px) on wide pages
+ * - Full covers: Can expand to full viewport width with negative margins (up to ~1920px+ on large screens)
+ * - Responsive sizes: 768px (mobile), 1024px (tablet), up to 1920px+ (large desktop)
+ *
+ * The recommended aspect ratio is optimized to work well across all these scenarios.
+ */
+
+export const DEFAULT_COVER_HEIGHT = 240;
+
+/**
+ * Calculate recommended cover image dimensions based on actual rendering widths.
+ *
+ * Analysis of actual rendering widths:
+ * - Hero, regular page: max-w-3xl = 768px
+ * - Hero, wide page: max-w-screen-2xl = 1536px
+ * - Full cover (mobile): ~768px (full viewport minus padding)
+ * - Full cover (tablet): ~1024px (full viewport minus padding)
+ * - Full cover (desktop): Can be 768px (hero regular) to ~1920px (full wide) on large screens
+ *
+ * The recommended aspect ratio (4:1) is a standard format that works well for:
+ * - Default height of 240px → 960px width (close to tablet size of 1024px)
+ * - Works well when cropped to 768px (hero regular), 1024px (tablet), 1536px (hero wide), and 1920px (full wide)
+ * - With `object-cover`, images maintain their natural aspect ratio while filling the container,
+ *   so the 4:1 ratio provides good coverage across all scenarios
+ *
+ * This ratio ensures images look good across all scenarios (hero/full, regular/wide, all viewports)
+ * while maintaining good image quality for responsive srcSet generation and being easy to remember.
+ *
+ * @param height - The cover height in pixels (default: 240)
+ * @returns Recommended width and height for the cover image
+ */
+export function getRecommendedCoverDimensions(height: number = DEFAULT_COVER_HEIGHT): {
+    width: number;
+    height: number;
+} {
+    // Standard 4:1 aspect ratio - a common and easy-to-work-with format
+    // At 240px height: 960px width
+    // This ratio works well for:
+    // - Hero covers on regular pages (768px width) - image will scale to cover
+    // - Hero covers on wide pages (1536px width) - image will scale to cover
+    // - Full covers across all breakpoints (768px - 1920px+) - image will scale proportionally
+    //
+    // Since we use `object-cover`, the image will scale to fill the container while maintaining
+    // its aspect ratio, so the 4:1 ratio provides excellent coverage across all scenarios.
+    //
+    // Examples for different heights:
+    // - 240px height → 960px width (recommended for default)
+    // - 400px height → 1600px width (recommended for taller covers)
+    // - 500px height → 2000px width (recommended for very tall covers)
+    const aspectRatio = 4;
+
+    return {
+        width: Math.round(height * aspectRatio),
+        height,
+    };
+}
+
+/**
+ * Get the maximum cover width based on cover type and page layout.
+ * Used for determining the upper bound of image dimensions.
+ */
+export function getMaxCoverWidth(coverType: 'hero' | 'full', isWidePage: boolean): number {
+    if (coverType === 'hero') {
+        // Hero covers: max-w-3xl (768px) or max-w-screen-2xl (1536px)
+        return isWidePage ? 1536 : 768;
+    }
+    // Full covers can expand to viewport width, typically up to 1920px on large screens
+    // Accounting for some margins, we use 1920px as the maximum
+    return 1920;
+}

packages/gitbook/src/components/PageBody/coverHeight.ts

@@ -14,17 +14,12 @@ function clampCoverHeight(height: number | null | undefined): number {
 }
 
 export function getCoverHeight(
-    cover: RevisionPageDocumentCover | null | undefined,
-    as: 'hero' | 'full'
+    cover: RevisionPageDocumentCover | null | undefined
 ): number | undefined {
     // Cover (and thus height) is not defined
     if (!cover) {
         return undefined;
     }
 
-    if (as === 'hero') {
-        return DEFAULT_COVER_HEIGHT;
-    }
-
     return clampCoverHeight((cover as RevisionPageDocumentCover).height ?? DEFAULT_COVER_HEIGHT);
 }