Separate current width from default width in PageLayout.Pane resizable API

[Copilot]

The width prop currently conflates two concepts: named sizes and default constraints. This refactor separates concerns: width defines constraints and defaults, while resizable.width holds the current controlled value.

API Changes

Before (proposed in PR #7348 but never shipped):

// Ambiguous: is width the default or current value?
const [width, setWidth] = useState(350)
<PageLayout.Pane 
  width={width}
  resizable={{persist: setWidth}}
/>

After:

// Clear separation: width = constraints, resizable.width = current
const [currentWidth, setCurrentWidth] = useState(350)
<PageLayout.Pane 
  width={{min: '256px', default: '296px', max: '600px'}}
  resizable={{
    width: currentWidth,  // current controlled value
    persist: setCurrentWidth
  }}
/>

Implementation

• Types: Extended PersistConfig with optional width?: number for current controlled value
• Hook logic: Priority order is now resizable.width → localStorage → width.default
• State sync: When resizable.width changes or is removed, state updates appropriately
• Backward compatible: Existing code without resizable.width works unchanged
• Simplified types: Removed number from PaneWidthValue union type (was never shipped, so no deprecation needed)

Changelog

New

• resizable.width?: number - Optional property to control current pane width

Changed

• width prop now defines constraints only (named sizes or CustomWidthOptions)
• usePaneWidth initialization prioritizes resizable.width when provided

Removed

• number type from PaneWidthValue (was never part of a public release)
• isNumericWidth helper function (no longer needed)

Rollout strategy

• Minor release
• Patch release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Fully backward compatible. Existing APIs continue to work without modification.

Testing & Reviewing

• Review new tests covering resizable.width initialization, updates, and removal
• Check stories demonstrating the new controlled width pattern
• Verify existing examples still work without modification
• All 90 PageLayout tests pass (73 usePaneWidth + 17 PageLayout)

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github (Learn more about how to run integration tests)

Original prompt

Summary

Refactor the PageLayout.Pane API in PR #7348 to separate "current width" from "default width" by moving the current/controlled width value into the resizable configuration object.

Current State

The width prop currently accepts three things:

1. Named sizes ('small' | 'medium' | 'large')
2. A number (current pixel width)
3. CustomWidthOptions with min, default, max

This creates ambiguity - when passing width={350}, it's unclear if that's the default or the current controlled value.

Desired Change

Separate the concerns:

• width prop - Should define constraints only: default value, min, max
• resizable config - Should include the current controlled width value

New API Shape

// width = constraints (default, min, max)
<PageLayout.Pane 
  width={{
    default: 'medium',  // or a number like 350
    min: 256,
    max: 600
  }}
  // resizable = current controlled state + persistence
  resizable={{
    width: currentWidth,  // the live/current value
    save: (w) => setCurrentWidth(w)
  }}
/>

// If resizable.width is not provided, use width.default (or the default from named size)
<PageLayout.Pane 
  width="medium"
  resizable={{save: (w) => setCurrentWidth(w)}}
/>

Tasks

1. Update the resizable type to include an optional width property for the current controlled value
2. Update the width prop types to focus on constraints (remove number as a direct value, keep it only in CustomWidthOptions.default)
3. Update usePaneWidth hook to read current width from resizable.width when provided, falling back to the default from width prop
4. Update all related unit tests to match the new API
5. Update stories to demonstrate the new API pattern
6. Update JSDoc/documentation to clarify the separation of concerns

Acceptance Criteria

• resizable.width is the source of truth for current width when provided
• width prop defines defaults and constraints only
• All existing tests updated to pass with new API
• Clear separation between "current value" and "default/constraints"

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 80df7ec

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Or, apply the integration-tests: skipped manually label to skip these checks.

[mattcosta7]

@copilot

We don't need to deprecate we can just remove these since we never used them right?

[Copilot]

You're right! Removed the number type entirely since it was never shipped. This simplifies the API and removes the deprecation notice. The changes include:

• Removed number from PaneWidthValue union type
• Removed isNumericWidth helper function
• Cleaned up JSDoc comments
• Simplified CSS variable logic in PageLayout.tsx

Commit: 80df7ec