fix merge conflict

Author: rezrah

.changeset/quiet-otters-dance.md

@@ -0,0 +1,13 @@
+---
+'@primer/react-brand': minor
+---
+
+⚠️ Breaking change: Removed the `imageBackgroundColor` prop from `River.Visual`, `RiverBreakout.Visual`, and `RiverBreakoutTabs.Visual`.
+
+The `gridline` variant now applies the full-bleed visual background layout by default. Remove `imageBackgroundColor="subtle"` from `River.Visual` and `RiverBreakout.Visual` when using the `gridline` variant.
+
+Remove `imageBackgroundColor` from `RiverBreakoutTabs.Visual` without replacement. Its default visual treatment is unchanged.
+
+The background treatment is not applied to the default `River` or `RiverBreakout` variants.
+
+Updated the River `gridline` variant tablet layout with a `618px` max-width and lateral gridlines.

.changeset/river-visual-layout.md

@@ -3,13 +3,13 @@
 '@primer/brand-css': minor
 ---
 
-Added opt-in `position` and `padding` controls to `River.Visual` media in the `gridline` variants. Existing Rivers remain unchanged.
+Added opt-in `position` and `padding` controls to `River.Visual` media in the `gridline` variant.
 
 🔗 Storybook examples:
 
-- [Center position](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-center)
-- [Block-end position](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end)
-- [Block-end inline-start position](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end-inline-start)
-- [Block-end inline-end position](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end-inline-end)
-- [No padding](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-padding-none)
-- [Padding on all sides](https://stunning-chainsaw-j82glqz.pages.github.io/?path=/story/components-river-features-gridline-variants--grid-line-visual-padding-all)
+- [Center position](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-center)
+- [Block-end position](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end)
+- [Block-end inline-start position](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end-inline-start)
+- [Block-end inline-end position](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-position-block-end-inline-end)
+- [No padding](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-padding-none)
+- [Padding on all sides](https://stunning-chainsaw-j82glqz.pages.github.io/brand/storybook/?path=/story/components-river-features-gridline-variants--grid-line-visual-padding-all)

.changeset/silver-pandas-draw.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': patch
+---
+
+Improve `RiverAccordion` gridline layout on tablet viewports and update its accordion toggle icon from chevrons to triangles.

.changeset/tidy-traps-focus.md

@@ -0,0 +1,5 @@
+---
+'@primer/react-brand': minor
+---
+
+Exported `useFocusTrap` from the package root and created stable container and initial-focus refs when they are not provided.

apps/next-docs/content/components/River/react.mdx

@@ -74,12 +74,12 @@ import {River, RiverBreakout} from '@primer/react-brand'
 
 ### GridLine variant
 
-The `gridline` variant adds lateral padding for bordered layouts. Use `imageBackgroundColor` to add contrast, `position` to align media, and `padding` to control its inset.
+The `gridline` variant adds lateral padding and applies a full-bleed visual background by default. Use `position` to align media and `padding` to control its inset.
 
 ```jsx live
 <Stack style={{width: '100%'}}>
   <River variant="gridline">
-    <River.Visual imageBackgroundColor="subtle">
+    <River.Visual>
       <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
     </River.Visual>
     <River.Content>
@@ -89,7 +89,7 @@ The `gridline` variant adds lateral padding for bordered layouts. Use `imageBack
     </River.Content>
   </River>
   <River variant="gridline" align="end">
-    <River.Visual imageBackgroundColor="subtle">
+    <River.Visual>
       <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
     </River.Visual>
     <River.Content>
@@ -99,7 +99,7 @@ The `gridline` variant adds lateral padding for bordered layouts. Use `imageBack
     </River.Content>
   </River>
   <River variant="gridline">
-    <River.Visual imageBackgroundColor="subtle" position="block-end-inline-end">
+    <River.Visual position="block-end-inline-end">
       <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
     </River.Visual>
     <River.Content>
@@ -108,7 +108,7 @@ The `gridline` variant adds lateral padding for bordered layouts. Use `imageBack
     </River.Content>
   </River>
   <River variant="gridline">
-    <River.Visual imageBackgroundColor="subtle" position="block-end-inline-start">
+    <River.Visual position="block-end-inline-start">
       <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
     </River.Visual>
     <River.Content>
@@ -117,7 +117,7 @@ The `gridline` variant adds lateral padding for bordered layouts. Use `imageBack
     </River.Content>
   </River>
   <River variant="gridline">
-    <River.Visual imageBackgroundColor="subtle" padding="none">
+    <River.Visual padding="none">
       <img src="/images/placeholder.png" alt="placeholder, blank area with a gray background color" />
     </River.Visual>
     <River.Content>
@@ -264,22 +264,21 @@ The `gridline` variant adds lateral padding for bordered layouts. Use `imageBack
 
 ### River.Visual <Label>Required</Label>
 
-| Name                   | Type                        |   Default   | Description                                                                                                                                                                 |
-| :--------------------- | :-------------------------- | :---------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fillMedia`            | `boolean`                   |    true     | Automatically styles images and video to fill and fit the width of the parent. Disable this setting if you have bespoke styling requirements.                               |
-| `children`             | `ReactElement`              |             | Bring your own component (BYOC) `img` or `ReactElement` (E.g. Next.js `Image` component)                                                                                    |
-| `imageBackgroundColor` | `'default'`, `'subtle'`     |             | Applies a background color around the media independently of visual position and padding controls.                                                                          |
-| `position`             | <RiverVisualPositionProp /> | `'default'` | Positions media within the gridline visual region. Explicit positions remain fixed across viewports; `default` preserves responsive behavior.                               |
-| `padding`              | <RiverVisualPaddingProp />  | `'default'` | Controls media inset within the gridline visual region. `none` fills the visual region and removes corner radius regardless of `rounded`; `all` adds padding on every side. |
-| `hasShadow`            | `boolean`                   |   `false`   | Shadow applied to the `children`. Set be `false` when the child node has a transparent background.                                                                          |
-| `className`            | `string`                    |             | Sets a custom class on the root element                                                                                                                                     |
-| `id`                   | `string`                    |             | Sets a custom id                                                                                                                                                            |
-| `ref`                  | `React.RefObject`           |             | Forward a Ref to the underlying DOM node                                                                                                                                    |
-| `rounded`              | `boolean`                   |   `true`    | Toggle visually rounded corners. Enabled by default.                                                                                                                        |
+| Name        | Type                        |   Default   | Description                                                                                                                                                                 |
+| :---------- | :-------------------------- | :---------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fillMedia` | `boolean`                   |    true     | Automatically styles images and video to fill and fit the width of the parent. Disable this setting if you have bespoke styling requirements.                               |
+| `children`  | `ReactElement`              |             | Bring your own component (BYOC) `img` or `ReactElement` (E.g. Next.js `Image` component)                                                                                    |
+| `position`  | <RiverVisualPositionProp /> | `'default'` | Positions media within the gridline visual region. Explicit positions remain fixed across viewports; `default` preserves responsive behavior.                               |
+| `padding`   | <RiverVisualPaddingProp />  | `'default'` | Controls media inset within the gridline visual region. `none` fills the visual region and removes corner radius regardless of `rounded`; `all` adds padding on every side. |
+| `hasShadow` | `boolean`                   |   `false`   | Shadow applied to the `children`. Set be `false` when the child node has a transparent background.                                                                          |
+| `className` | `string`                    |             | Sets a custom class on the root element                                                                                                                                     |
+| `id`        | `string`                    |             | Sets a custom id                                                                                                                                                            |
+| `ref`       | `React.RefObject`           |             | Forward a Ref to the underlying DOM node                                                                                                                                    |
+| `rounded`   | `boolean`                   |   `true`    | Toggle visually rounded corners. Enabled by default.                                                                                                                        |
 
 ### RiverBreakout.Visual <Label>Required</Label>
 
-`RiverBreakout.Visual` supports the `children`, `fillMedia`, `imageBackgroundColor`, `hasShadow`, `rounded`, and standard HTML props listed above. The `position` and `padding` props are specific to `River.Visual`.
+`RiverBreakout.Visual` supports the `children`, `fillMedia`, `hasShadow`, `rounded`, and standard HTML props listed above. The `position` and `padding` props are specific to `River.Visual`.
 
 ### River.Content and RiverBreakout.Content <Label>Required</Label>
 

apps/next-docs/content/components/RiverBreakoutTabs/index.mdx

@@ -166,9 +166,8 @@ import {RiverBreakoutTabs} from '@primer/react-brand'
 
 ### RiverBreakoutTabs.Visual <Label>Required</Label>
 
-| Name                   | Type                    | Default | Description                       |
-| :--------------------- | :---------------------- | :-----: | :-------------------------------- |
-| `children`             | `React.ReactElement`    |         | Item visual media                 |
-| `imageBackgroundColor` | `'default' \| 'subtle'` |         | Optional background around visual |
+| Name       | Type                 | Default | Description       |
+| :--------- | :------------------- | :-----: | :---------------- |
+| `children` | `React.ReactElement` |         | Item visual media |
 
 `RiverBreakoutTabs.Visual` extends `River.Visual` and supports all `River.Visual` props.

packages/react/src/hooks/useFocusTrap.ssr.test.tsx

@@ -0,0 +1,16 @@
+/** @jest-environment node */
+
+import React from 'react'
+import {renderToString} from 'react-dom/server'
+import {useFocusTrap} from './useFocusTrap'
+
+describe('useFocusTrap SSR', () => {
+  it('renders without a document', () => {
+    const TestComponent = () => {
+      useFocusTrap()
+      return null
+    }
+
+    expect(() => renderToString(<TestComponent />)).not.toThrow()
+  })
+})

packages/react/src/hooks/useFocusTrap.test.tsx

@@ -0,0 +1,113 @@
+import React from 'react'
+import {focusTrap} from '@primer/behaviors'
+import {render, renderHook} from '@testing-library/react'
+import {useFocusTrap} from './useFocusTrap'
+
+jest.mock('@primer/behaviors', () => ({
+  focusTrap: jest.fn(),
+}))
+
+const mockFocusTrap = jest.mocked(focusTrap)
+
+describe('useFocusTrap', () => {
+  const ToggleFocusTrapTestComponent = ({
+    disabled,
+    restoreFocusOnCleanUp = false,
+  }: {
+    disabled: boolean
+    restoreFocusOnCleanUp?: boolean
+  }) => {
+    const {containerRef} = useFocusTrap<HTMLDivElement>({disabled, restoreFocusOnCleanUp})
+    return <div ref={containerRef} />
+  }
+
+  beforeEach(() => {
+    mockFocusTrap.mockReturnValue(new AbortController())
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('creates stable refs when refs are not provided', () => {
+    const {result, rerender} = renderHook(() => useFocusTrap({disabled: true}))
+    const initialContainerRef = result.current.containerRef
+    const initialFocusRef = result.current.initialFocusRef
+
+    expect(initialContainerRef.current).toBeNull()
+    expect(initialFocusRef.current).toBeNull()
+
+    rerender()
+
+    expect(result.current.containerRef).toBe(initialContainerRef)
+    expect(result.current.initialFocusRef).toBe(initialFocusRef)
+  })
+
+  it('preserves provided refs', () => {
+    const containerRef = React.createRef<HTMLDivElement>()
+    const initialFocusRef = React.createRef<HTMLButtonElement>()
+    const {result} = renderHook(() => useFocusTrap({containerRef, initialFocusRef, disabled: true}))
+
+    expect(result.current.containerRef).toBe(containerRef)
+    expect(result.current.initialFocusRef).toBe(initialFocusRef)
+  })
+
+  it('passes generated ref elements to the focus trap', () => {
+    const TestComponent = () => {
+      const {containerRef, initialFocusRef} = useFocusTrap<HTMLDivElement, HTMLButtonElement>()
+
+      return (
+        <div ref={containerRef}>
+          <button ref={initialFocusRef} />
+        </div>
+      )
+    }
+
+    const {container} = render(<TestComponent />)
+
+    expect(mockFocusTrap).toHaveBeenCalledWith(container.querySelector('div'), container.querySelector('button'))
+  })
+
+  it('starts and aborts the focus trap when disabled changes', () => {
+    const abortController = new AbortController()
+    const abortSpy = jest.spyOn(abortController, 'abort')
+    mockFocusTrap.mockReturnValue(abortController)
+
+    const {rerender} = render(<ToggleFocusTrapTestComponent disabled />)
+
+    expect(mockFocusTrap).not.toHaveBeenCalled()
+
+    rerender(<ToggleFocusTrapTestComponent disabled={false} />)
+
+    expect(mockFocusTrap).toHaveBeenCalledTimes(1)
+
+    rerender(<ToggleFocusTrapTestComponent disabled />)
+
+    expect(abortSpy).toHaveBeenCalled()
+  })
+
+  it('captures fresh focus after cleaning up a non-HTMLElement active element', () => {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
+    svg.setAttribute('tabindex', '0')
+    document.body.append(svg)
+    svg.focus()
+
+    const nextFocusedElement = document.createElement('button')
+    document.body.append(nextFocusedElement)
+
+    const {rerender} = render(<ToggleFocusTrapTestComponent disabled={false} restoreFocusOnCleanUp />)
+
+    rerender(<ToggleFocusTrapTestComponent disabled restoreFocusOnCleanUp />)
+    nextFocusedElement.focus()
+
+    const focusSpy = jest.spyOn(nextFocusedElement, 'focus')
+
+    rerender(<ToggleFocusTrapTestComponent disabled={false} restoreFocusOnCleanUp />)
+    rerender(<ToggleFocusTrapTestComponent disabled restoreFocusOnCleanUp />)
+
+    expect(focusSpy).toHaveBeenCalled()
+
+    svg.remove()
+    nextFocusedElement.remove()
+  })
+})