Rename stickyTop->offsetHeader and improve docs

.changeset/rich-singers-double.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Rename `stickyTop` prop name for the PageLayout to `offsetHeader` and improve docs

docs/content/PageLayout.mdx

@@ -170,6 +170,8 @@ See [storybook](https://primer.style/react/storybook?path=/story/layout-pagelayo
 
 ### With a custom sticky header
 
+Add `offsetHeader` prop to specify the height of the custom sticky header along with `sticky` prop
+
 ```jsx live
 <Box sx={{height: 320, overflowY: 'auto', border: '1px solid', borderColor: 'border.default'}}>
   <Box
@@ -190,7 +192,7 @@ See [storybook](https://primer.style/react/storybook?path=/story/layout-pagelayo
     <PageLayout.Content>
       <Placeholder label="Content" height={320} />
     </PageLayout.Content>
-    <PageLayout.Pane position="start" stickyTop={64} sticky>
+    <PageLayout.Pane position="start" sticky offsetHeader={64}>
       <Placeholder label="Pane" height={120} />
     </PageLayout.Pane>
     <PageLayout.Footer>
@@ -370,10 +372,10 @@ See [storybook](https://primer.style/react/storybook?path=/story/layout-pagelayo
     description="Whether the pane should stick to the top of the screen while the content scrolls."
   />
   <PropsTableRow
-    name="stickyTop"
+    name="offsetHeader"
     type="number | string"
     defaultValue="0"
-    description="Use stickyTop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px."
+    description="Use offsetHeader along with the sticky prop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px."
   />
   <PropsTableRow
     name="padding"

docs/content/SplitPageLayout.mdx

@@ -253,7 +253,7 @@ If you need a more flexible layout component, consider using the [PageLayout](/P
     <SplitPageLayout.Content>
       <Placeholder label="Content" height={320} />
     </SplitPageLayout.Content>
-    <SplitPageLayout.Pane stickyTop={64}>
+    <SplitPageLayout.Pane sticky offsetHeader={64}>
       <Placeholder label="Pane" height={120} />
     </SplitPageLayout.Pane>
     <SplitPageLayout.Footer>
@@ -383,10 +383,10 @@ If you need a more flexible layout component, consider using the [PageLayout](/P
     description="Whether the pane should stick to the top of the screen while the content scrolls."
   />
   <PropsTableRow
-    name="stickyTop"
+    name="offsetHeader"
     type="number | string"
     defaultValue="0"
-    description="Use stickyTop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px."
+    description="Use offsetHeader along with the sticky prop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px."
   />
   <PropsTableRow
     name="padding"

src/PageLayout/PageLayout.stories.tsx

@@ -594,7 +594,7 @@ export const CustomStickyHeader: Story = args => (
       sx={{
         position: 'sticky',
         top: 0,
-        height: args.stickyTop,
+        height: args.offsetHeader,
         display: 'grid',
         placeItems: 'center',
         backgroundColor: 'canvas.subtle',
@@ -619,7 +619,7 @@ export const CustomStickyHeader: Story = args => (
           ))}
         </Box>
       </PageLayout.Content>
-      <PageLayout.Pane position="start" padding="normal" divider="line" sticky stickyTop={args.stickyTop}>
+      <PageLayout.Pane position="start" padding="normal" divider="line" sticky offsetHeader={args.offsetHeader}>
         <Box sx={{display: 'grid', gap: 3}}>
           {Array.from({length: args.numParagraphsInPane}).map((_, i) => (
             <Box key={i} as="p" sx={{margin: 0}}>
@@ -643,7 +643,7 @@ CustomStickyHeader.argTypes = {
     type: 'boolean',
     defaultValue: true
   },
-  stickyTop: {
+  offsetHeader: {
     type: 'string',
     defaultValue: '8rem'
   },

src/PageLayout/PageLayout.tsx

@@ -361,7 +361,7 @@ export type PageLayoutPaneProps = {
    */
   dividerWhenNarrow?: 'inherit' | 'none' | 'line' | 'filled'
   sticky?: boolean
-  stickyTop?: string | number
+  offsetHeader?: string | number
   hidden?: boolean | ResponsiveValue<boolean>
 } & SxProp
 
@@ -384,7 +384,7 @@ const Pane: React.FC<React.PropsWithChildren<PageLayoutPaneProps>> = ({
   divider: responsiveDivider = 'none',
   dividerWhenNarrow = 'inherit',
   sticky = false,
-  stickyTop = 0,
+  offsetHeader = 0,
   hidden: responsiveHidden = false,
   children,
   sx = {}
@@ -411,11 +411,11 @@ const Pane: React.FC<React.PropsWithChildren<PageLayoutPaneProps>> = ({
 
   React.useEffect(() => {
     if (sticky) {
-      enableStickyPane?.(stickyTop)
+      enableStickyPane?.(offsetHeader)
     } else {
       disableStickyPane?.()
     }
-  }, [sticky, enableStickyPane, disableStickyPane, stickyTop])
+  }, [sticky, enableStickyPane, disableStickyPane, offsetHeader])
 
   return (
     <Box
@@ -440,9 +440,9 @@ const Pane: React.FC<React.PropsWithChildren<PageLayoutPaneProps>> = ({
               ...(sticky
                 ? {
                     position: 'sticky',
-                    // If stickyTop has value, it will stick the pane to the position where the sticky top ends
-                    // else top will be 0 as the default value of stickyTop
-                    top: typeof stickyTop === 'number' ? `${stickyTop}px` : stickyTop,
+                    // If offsetHeader has value, it will stick the pane to the position where the sticky top ends
+                    // else top will be 0 as the default value of offsetHeader
+                    top: typeof offsetHeader === 'number' ? `${offsetHeader}px` : offsetHeader,
                     overflow: 'hidden',
                     maxHeight: 'var(--sticky-pane-height)'
                   }

src/PageLayout/useStickyPaneHeight.ts

@@ -10,7 +10,7 @@ export function useStickyPaneHeight() {
 
   // Default the height to the viewport height
   const [height, setHeight] = React.useState('100vh')
-  const [stickyTop, setStickyTop] = React.useState<number | string>(0)
+  const [offsetHeader, setOffsetHeader] = React.useState<number | string>(0)
 
   // Create intersection observers to track the top and bottom of the content region
   const [contentTopRef, contentTopInView, contentTopEntry] = useInView()
@@ -29,15 +29,16 @@ export function useStickyPaneHeight() {
     const topRect = contentTopEntry?.target.getBoundingClientRect()
     const bottomRect = contentBottomEntry?.target.getBoundingClientRect()
 
-    const stickyTopWithUnits = typeof stickyTop === 'number' ? `${stickyTop}px` : stickyTop
+    // Custom sticky header's height with units
+    const offsetHeaderWithUnits = typeof offsetHeader === 'number' ? `${offsetHeader}px` : offsetHeader
 
     if (scrollContainer) {
       const scrollRect = scrollContainer.getBoundingClientRect()
 
       const topOffset = topRect ? Math.max(topRect.top - scrollRect.top, 0) : 0
       const bottomOffset = bottomRect ? Math.max(scrollRect.bottom - bottomRect.bottom, 0) : 0
 
-      calculatedHeight = `calc(${scrollRect.height}px - (max(${topOffset}px, ${stickyTopWithUnits}) + ${bottomOffset}px))`
+      calculatedHeight = `calc(${scrollRect.height}px - (max(${topOffset}px, ${offsetHeaderWithUnits}) + ${bottomOffset}px))`
     } else {
       const topOffset = topRect ? Math.max(topRect.top, 0) : 0
       const bottomOffset = bottomRect ? Math.max(window.innerHeight - bottomRect.bottom, 0) : 0
@@ -46,11 +47,11 @@ export function useStickyPaneHeight() {
       // We need to account for this when calculating the offset.
       const overflowScroll = Math.max(window.scrollY + window.innerHeight - document.body.scrollHeight, 0)
 
-      calculatedHeight = `calc(100vh - (max(${topOffset}px, ${stickyTopWithUnits}) + ${bottomOffset}px - ${overflowScroll}px))`
+      calculatedHeight = `calc(100vh - (max(${topOffset}px, ${offsetHeaderWithUnits}) + ${bottomOffset}px - ${overflowScroll}px))`
     }
 
     setHeight(calculatedHeight)
-  }, [contentTopEntry, contentBottomEntry, stickyTop])
+  }, [contentTopEntry, contentBottomEntry, offsetHeader])
 
   // We only want to add scroll and resize listeners if the pane is sticky.
   // Since hooks can't be called conditionally, we need to use state to track
@@ -92,7 +93,7 @@ export function useStickyPaneHeight() {
 
   function enableStickyPane(top: string | number) {
     setIsEnabled(true)
-    setStickyTop(top)
+    setOffsetHeader(top)
   }
 
   function disableStickyPane() {