[⏪ Reverted] Deprecate position prop for PageLayout.Pane, update stories and tests.

.changeset/hungry-spies-remember.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": patch
+---
+
+Deprecates position prop for PageLayout.Pane. Users will receive a console warning when it is used.

generated/components.json

@@ -2797,7 +2797,8 @@
               "name": "position",
               "type": "| 'start' | 'end' | { narrow?: | 'start' | 'end' regular?: | 'start' | 'end' wide?: | 'start' | 'end' }",
               "defaultValue": "'end'",
-              "description": ""
+              "description": "",
+              "deprecated": true
             },
             {
               "name": "positionWhenNarrow",

src/PageLayout/PageLayout.docs.json

@@ -137,7 +137,8 @@
           "name": "position",
           "type": "| 'start' | 'end' | { narrow?: | 'start' | 'end' regular?: | 'start' | 'end' wide?: | 'start' | 'end' }",
           "defaultValue": "'end'",
-          "description": ""
+          "description": "",
+          "deprecated": true
         },
         {
           "name": "positionWhenNarrow",

src/PageLayout/PageLayout.features.stories.tsx

@@ -83,49 +83,42 @@ export const StickyPane: Story = args => (
     <PageLayout.Header padding="normal" divider="line">
       <Placeholder label="Header" height={64} />
     </PageLayout.Header>
-    <PageLayout.Content padding="normal" width="large">
+    <PageLayout.Pane resizable padding="normal" divider="line" sticky={args.sticky} aria-label="Side pane">
       <Box sx={{display: 'grid', gap: 3}}>
-        {Array.from({length: args.numParagraphsInContent}).map((_, i) => {
-          const testId = `content${i}`
+        {Array.from({length: args.numParagraphsInPane}).map((_, i) => {
+          const testId = `paragraph${i}`
           return (
             <Box key={i} as="p" sx={{margin: 0}}>
               <span data-testid={testId}>
                 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
                 ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius tellus
                 et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec sit amet
-                massa purus. Nunc sem lectus, bibendum a sapien nec, tristique tempus felis. Ut porttitor auctor tellus
-                in imperdiet. Ut blandit tincidunt augue, quis fringilla nunc tincidunt sed. Vestibulum auctor euismod
-                nisi. Nullam tincidunt est in mi tincidunt dictum. Sed consectetur aliquet velit ut ornare.
+                massa purus.
               </span>
             </Box>
           )
         })}
       </Box>
-    </PageLayout.Content>
-    <PageLayout.Pane
-      position="start"
-      resizable
-      padding="normal"
-      divider="line"
-      sticky={args.sticky}
-      aria-label="Side pane"
-    >
+    </PageLayout.Pane>
+    <PageLayout.Content padding="normal" width="large">
       <Box sx={{display: 'grid', gap: 3}}>
-        {Array.from({length: args.numParagraphsInPane}).map((_, i) => {
-          const testId = `paragraph${i}`
+        {Array.from({length: args.numParagraphsInContent}).map((_, i) => {
+          const testId = `content${i}`
           return (
             <Box key={i} as="p" sx={{margin: 0}}>
               <span data-testid={testId}>
                 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
                 ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius tellus
                 et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec sit amet
-                massa purus.
+                massa purus. Nunc sem lectus, bibendum a sapien nec, tristique tempus felis. Ut porttitor auctor tellus
+                in imperdiet. Ut blandit tincidunt augue, quis fringilla nunc tincidunt sed. Vestibulum auctor euismod
+                nisi. Nullam tincidunt est in mi tincidunt dictum. Sed consectetur aliquet velit ut ornare.
               </span>
             </Box>
           )
         })}
       </Box>
-    </PageLayout.Pane>
+    </PageLayout.Content>
     <PageLayout.Footer padding="normal" divider="line">
       <Placeholder label="Footer" height={64} />
     </PageLayout.Footer>
@@ -158,32 +151,32 @@ export const NestedScrollContainer: Story = args => (
         <PageLayout.Header padding="normal" divider="line">
           <Placeholder label="Header" height={64} />
         </PageLayout.Header>
-        <PageLayout.Content padding="normal" width="large">
+        <PageLayout.Pane padding="normal" divider="line" sticky aria-label="Side pane">
           <Box sx={{display: 'grid', gap: 3}}>
-            {Array.from({length: args.numParagraphsInContent}).map((_, i) => (
+            {Array.from({length: args.numParagraphsInPane}).map((_, i) => (
               <Box key={i} as="p" sx={{margin: 0}}>
                 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
                 ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius tellus
                 et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec sit amet
-                massa purus. Nunc sem lectus, bibendum a sapien nec, tristique tempus felis. Ut porttitor auctor tellus
-                in imperdiet. Ut blandit tincidunt augue, quis fringilla nunc tincidunt sed. Vestibulum auctor euismod
-                nisi. Nullam tincidunt est in mi tincidunt dictum. Sed consectetur aliquet velit ut ornare.
+                massa purus.
               </Box>
             ))}
           </Box>
-        </PageLayout.Content>
-        <PageLayout.Pane position="start" padding="normal" divider="line" sticky aria-label="Side pane">
+        </PageLayout.Pane>
+        <PageLayout.Content padding="normal" width="large">
           <Box sx={{display: 'grid', gap: 3}}>
-            {Array.from({length: args.numParagraphsInPane}).map((_, i) => (
+            {Array.from({length: args.numParagraphsInContent}).map((_, i) => (
               <Box key={i} as="p" sx={{margin: 0}}>
                 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
                 ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius tellus
                 et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec sit amet
-                massa purus.
+                massa purus. Nunc sem lectus, bibendum a sapien nec, tristique tempus felis. Ut porttitor auctor tellus
+                in imperdiet. Ut blandit tincidunt augue, quis fringilla nunc tincidunt sed. Vestibulum auctor euismod
+                nisi. Nullam tincidunt est in mi tincidunt dictum. Sed consectetur aliquet velit ut ornare.
               </Box>
             ))}
           </Box>
-        </PageLayout.Pane>
+        </PageLayout.Content>
         <PageLayout.Footer padding="normal" divider="line">
           <Placeholder label="Footer" height={64} />
         </PageLayout.Footer>
@@ -228,6 +221,23 @@ export const CustomStickyHeader: Story = args => (
       Custom sticky header
     </Box>
     <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
+      <PageLayout.Pane padding="normal" divider="line" aria-label="Aside pane" sticky offsetHeader={args.offsetHeader}>
+        <Box sx={{display: 'grid', gap: 3}}>
+          {Array.from({length: args.numParagraphsInPane}).map((_, i) => {
+            const testId = `paragraph${i}`
+            return (
+              <Box key={i} as="p" sx={{margin: 0}}>
+                <span data-testid={testId}>
+                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
+                  ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius
+                  tellus et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec
+                  sit amet massa purus.
+                </span>
+              </Box>
+            )
+          })}
+        </Box>
+      </PageLayout.Pane>
       <PageLayout.Content padding="normal" width="large">
         <Box sx={{display: 'grid', gap: 3}} data-testid="scrollContainer">
           {Array.from({length: args.numParagraphsInContent}).map((_, i) => {
@@ -248,30 +258,6 @@ export const CustomStickyHeader: Story = args => (
           })}
         </Box>
       </PageLayout.Content>
-      <PageLayout.Pane
-        position="start"
-        padding="normal"
-        divider="line"
-        aria-label="Aside pane"
-        sticky
-        offsetHeader={args.offsetHeader}
-      >
-        <Box sx={{display: 'grid', gap: 3}}>
-          {Array.from({length: args.numParagraphsInPane}).map((_, i) => {
-            const testId = `paragraph${i}`
-            return (
-              <Box key={i} as="p" sx={{margin: 0}}>
-                <span data-testid={testId}>
-                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam at enim id lorem tempus egestas a non
-                  ipsum. Maecenas imperdiet ante quam, at varius lorem molestie vel. Sed at eros consequat, varius
-                  tellus et, auctor felis. Donec pulvinar lacinia urna nec commodo. Phasellus at imperdiet risus. Donec
-                  sit amet massa purus.
-                </span>
-              </Box>
-            )
-          })}
-        </Box>
-      </PageLayout.Pane>
       <PageLayout.Footer padding="normal" divider="line">
         <Placeholder label="Footer" height={64} />
       </PageLayout.Footer>
@@ -306,7 +292,7 @@ export const ResizablePane: Story = () => (
     <PageLayout.Header>
       <Placeholder height={64} label="Header" />
     </PageLayout.Header>
-    <PageLayout.Pane resizable position="start">
+    <PageLayout.Pane resizable>
       <Placeholder height={320} label="Pane" />
     </PageLayout.Pane>
     <PageLayout.Content>
@@ -323,7 +309,7 @@ export const ScrollContainerWithinPageLayoutPane: Story = () => (
     <Box sx={{overflow: 'auto'}}>
       <Placeholder label="Above inner scroll container" height={120} />
       <PageLayout rowGap="none" columnGap="none" padding="none" containerWidth="full">
-        <PageLayout.Pane position="start" padding="normal" divider="line" sticky aria-label="Sticky pane">
+        <PageLayout.Pane padding="normal" divider="line" sticky aria-label="Sticky pane">
           <Box sx={{overflow: 'auto'}}>
             <PageLayout.Pane padding="normal">
               <Placeholder label="Inner scroll container" height={800} />

src/PageLayout/PageLayout.stories.tsx

@@ -34,9 +34,6 @@ const meta: Meta = {
     'Content.hidden.regular': false,
     'Content.hidden.narrow': false,
     'Content.hidden.wide': false,
-    'Pane.position.regular': 'end',
-    'Pane.position.narrow': 'end',
-    'Pane.position.wide': 'end',
     'Pane.width': 'medium',
     'Pane.sticky': false,
     'Pane.resizable': false,
@@ -205,31 +202,6 @@ const meta: Meta = {
       table: {category: 'Content props'},
     },
 
-    // Pane prop controls
-    'Pane.position.regular': {
-      type: {
-        name: 'enum',
-        value: ['start', 'end'],
-      },
-      control: {type: 'radio'},
-      table: {category: 'Pane props'},
-    },
-    'Pane.position.narrow': {
-      type: {
-        name: 'enum',
-        value: ['start', 'end'],
-      },
-      control: {type: 'radio'},
-      table: {category: 'Pane props'},
-    },
-    'Pane.position.wide': {
-      type: {
-        name: 'enum',
-        value: ['start', 'end'],
-      },
-      control: {type: 'radio'},
-      table: {category: 'Pane props'},
-    },
     'Pane.width': {
       type: {
         name: 'enum',
@@ -382,11 +354,6 @@ const Template: Story = args => (
     </PageLayout.Content>
     {args['Render pane?'] ? (
       <PageLayout.Pane
-        position={{
-          narrow: args['Pane.position.narrow'],
-          regular: args['Pane.position.regular'],
-          wide: args['Pane.position.wide'],
-        }}
         width={args['Pane.width']}
         minWidth={args['Pane.minWidth']}
         sticky={args['Pane.sticky']}

src/PageLayout/PageLayout.test.tsx

@@ -53,10 +53,10 @@ describe('PageLayout', () => {
           <PageLayout.Header divider="line" dividerWhenNarrow="filled">
             Header
           </PageLayout.Header>
-          <PageLayout.Content>Content</PageLayout.Content>
-          <PageLayout.Pane position="start" divider="line" dividerWhenNarrow="filled">
+          <PageLayout.Pane divider="line" dividerWhenNarrow="filled">
             Pane
           </PageLayout.Pane>
+          <PageLayout.Content>Content</PageLayout.Content>
           <PageLayout.Footer dividerWhenNarrow="line">Footer</PageLayout.Footer>
         </PageLayout>
       </ThemeProvider>,

src/PageLayout/PageLayout.tsx

@@ -107,7 +107,20 @@ const Root: React.FC<React.PropsWithChildren<PageLayoutProps>> = ({
           }}
         >
           {slots.header}
-          <Box sx={{display: 'flex', flex: '1 1 100%', flexWrap: 'wrap', maxWidth: '100%'}}>{rest}</Box>
+          <Box
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            sx={(theme: any) => ({
+              display: 'flex',
+              flex: '1 1 100%',
+              flexWrap: 'wrap',
+              maxWidth: '100%',
+              [`@media screen and (min-width: ${theme.breakpoints[1]})`]: {
+                columnGap: SPACING_MAP[columnGap],
+              },
+            })}
+          >
+            {rest}
+          </Box>
           {slots.footer}
         </Box>
       </Box>
@@ -428,7 +441,6 @@ const Content: React.FC<React.PropsWithChildren<PageLayoutContentProps>> = ({
         {
           display: isHidden ? 'none' : 'flex',
           flexDirection: 'column',
-          order: REGION_ORDER.content,
           // Set flex-basis to 0% to allow flex-grow to control the width of the content region.
           // Without this, the content region could wrap onto a different line
           // than the pane region on wide viewports if its contents are too wide.
@@ -530,7 +542,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
     {
       'aria-label': label,
       'aria-labelledby': labelledBy,
-      position: responsivePosition = 'end',
+      position: responsivePosition = undefined,
       positionWhenNarrow = 'inherit',
       width = 'medium',
       minWidth = 256,
@@ -548,6 +560,13 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
     },
     forwardRef,
   ) => {
+    if (responsivePosition !== undefined) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'The `position` prop will be removed on the next major version. You should order your markup as you want it to render instead.',
+      )
+    }
+
     // Combine position and positionWhenNarrow for backwards compatibility
     const positionProp =
       !isResponsiveValue(responsivePosition) && positionWhenNarrow !== 'inherit'
@@ -678,7 +697,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
             {
               // Narrow viewports
               display: isHidden ? 'none' : 'flex',
-              order: panePositions[position],
+              order: position !== undefined ? panePositions[position] : undefined,
               width: '100%',
               marginX: 0,
               ...(position === 'end'
@@ -698,9 +717,7 @@ const Pane = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageLayout
                       maxHeight: 'var(--sticky-pane-height)',
                     }
                   : {}),
-                ...(position === 'end'
-                  ? {flexDirection: 'row', marginLeft: SPACING_MAP[columnGap]}
-                  : {flexDirection: 'row-reverse', marginRight: SPACING_MAP[columnGap]}),
+                ...(position === 'end' ? {flexDirection: 'row'} : {flexDirection: 'row-reverse'}),
               },
             },
             sx,