Skip to content

[BottomSheet] feat: replace shouldNavigateBack with optional goBack callback#1024

Merged
georgewrmarshall merged 4 commits into
mainfrom
feat/replace-should-navigate-back-with-go-back
Apr 2, 2026
Merged

[BottomSheet] feat: replace shouldNavigateBack with optional goBack callback#1024
georgewrmarshall merged 4 commits into
mainfrom
feat/replace-should-navigate-back-with-go-back

Conversation

@kirillzyusko

@kirillzyusko kirillzyusko commented Apr 1, 2026

Copy link
Copy Markdown
Collaborator

Description

Removed shouldNavigateBack and leave only goBack option.

Since we decided, that we will not create wrapper inside mobile repo for this component it's clear that with new API we need:

  • provide goBack when shouldNavigateBack={true}
  • don't provide goBack when shouldNavigateBack={false}

And this logic is kind of duplicated now. We try to control a single thing (navigation) use two variables. We can optimize it and provide only goBack callback:

  • when it's provided it will be called;
  • when it's not provided it will not be called.

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-639

Manual testing steps

  1. Go to BottomSheet example
  2. Verify that new API works as expected

Screenshots/Recordings

Before

After

Pre-merge author checklist

  • I've followed MetaMask Contributor Docs
  • I've completed the PR template to the best of my ability
  • I’ve included tests if applicable
  • I’ve documented my code using JSDoc format if applicable
  • I’ve applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Medium Risk
This is a breaking API change for BottomSheet consumers: navigation behavior now depends solely on whether goBack is provided. Risk is moderate because it touches close-handling logic and requires downstream updates to avoid unintended back navigation (or missing it).

Overview
Simplifies BottomSheet navigation behavior by removing shouldNavigateBack and making goBack optional; when provided, it is now always invoked once on sheet close.

Updates the close callback logic accordingly, and adjusts stories, unit tests, and README docs to reflect the new API and to drop shouldNavigateBack usage.

Written by Cursor Bugbot for commit 4cf0b95. This will update automatically on new commits. Configure here.

@kirillzyusko kirillzyusko self-assigned this Apr 1, 2026
@github-actions

github-actions Bot commented Apr 1, 2026

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@github-actions

github-actions Bot commented Apr 1, 2026

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@kirillzyusko kirillzyusko marked this pull request as ready for review April 1, 2026 10:10
@kirillzyusko kirillzyusko requested a review from a team as a code owner April 1, 2026 10:10
@github-actions

github-actions Bot commented Apr 1, 2026

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@georgewrmarshall georgewrmarshall left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@github-actions

github-actions Bot commented Apr 2, 2026

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

{...args}
goBack={() => sheetRef.current?.onCloseBottomSheet()}
shouldNavigateBack={false}
>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ScrollableListTemplate still uses removed shouldNavigateBack prop

Medium Severity

The ScrollableListTemplate story was not updated to the new API. It still passes shouldNavigateBack={false} (now removed from types) along with goBack={goBack}. With the old API, shouldNavigateBack={false} prevented goBack from being called. Now that shouldNavigateBack is ignored, providing goBack means it will be called on close — in addition to onClose={goBack}, causing goBack to fire twice per close. To match the old behavior of "don't navigate back," goBack needs to be removed here too.

Fix in Cursor Fix in Web

@georgewrmarshall georgewrmarshall merged commit 3adebbe into main Apr 2, 2026
44 checks passed
@georgewrmarshall georgewrmarshall deleted the feat/replace-should-navigate-back-with-go-back branch April 2, 2026 19:00
@georgewrmarshall georgewrmarshall mentioned this pull request Apr 6, 2026
18 tasks
georgewrmarshall added a commit that referenced this pull request Apr 6, 2026
## Release 29.0.0

This release includes new React Native header and layout primitives,
BottomSheet API updates, shared type migrations, and
documentation/runtime dependency alignment across core design-system
packages.

### 📦 Package Versions

- @metamask/design-system-shared: 0.7.0
- @metamask/design-system-react: 0.14.0
- @metamask/design-system-react-native: 0.14.0

### 🔄 Shared Type Updates (0.7.0)

#### Added

- Added shared types used by new React Native header components,
including HeaderRoot contracts consumed by
@metamask/design-system-react-native (#1029).
- Added shared BoxHorizontal and BoxVertical utility component contracts
for cross-platform layout primitives (#1003).

#### Changed

- Migrated AvatarBase type exports from enum-based definitions to shared
const-object + string-union types, aligned with ADR-0003/ADR-0004
(#1005).
- Updated @metamask/utils dependency to ^11.11.0 (#1033).

### 🌐 React Web Updates (0.14.0)

#### Changed

- BREAKING: Updated AvatarBase exports to consume shared const-object +
string-union types rather than local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for recent releases (#1011).

### 📱 React Native Updates (0.14.0)

#### Added

- Added HeaderRoot as a new root primitive for React Native header
composition (#1029).
- Added HeaderStandard for standardized title + action header layouts in
mobile screens (#1028, #1030).
- Added TextFieldSearch for search-style text input flows on mobile
(#1027).
- Added BoxHorizontal and BoxVertical utility components for directional
layout composition (#1003).

#### Changed

- BREAKING: Replaced BottomSheet shouldNavigateBack with an optional
goBack callback for explicit navigation handling in host apps (#1024).
- Remove shouldNavigateBack usage and pass goBack when sheet close
should navigate back.
- See migration guide:
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- Added panGestureHandlerProps support to BottomSheet for
gesture-handler customization (#1016).
- Migrated React Native package exports from default exports to named
exports for consistent import ergonomics (#1032).
- BREAKING: Updated AvatarBase exports to use shared const-object +
string-union types instead of local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react-native as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for consumers (#1011).

#### Fixed

- Updated BottomSheetHeader action button size to md for consistent
sizing and visual alignment (#1012).

### ⚠️ Breaking Changes

- BottomSheet (React Native): replaced shouldNavigateBack with optional
goBack callback (#1024).
- Migration required where shouldNavigateBack was used; see
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- AvatarBase export type migration (React + React Native): moved from
local enums to shared const-object + string-union types (#1005).
- Marked breaking for type contract changes, but no migration is
expected for typical consumer imports/usage.

### ✅ Checklist

- [x] Changelogs updated with human-readable descriptions
- [x] Changelog validation passed (yarn changelog:validate)
- [x] Version bumps follow semantic versioning
- [x] design-system-shared: minor (0.6.0 to 0.7.0) - shared types and
dependency alignment
- [x] design-system-react: minor (0.13.0 to 0.14.0) - shared type
migration and docs/dependency updates
- [x] design-system-react-native: minor (0.13.0 to 0.14.0) - new
components and API enhancements
- [x] Breaking changes documented with migration guidance
- [x] Migration guides updated with before/after examples (if breaking
changes)
- [x] PR references included in changelog entries

## **Pre-merge author checklist**

- [x] I have followed MetaMask Contributor Docs
- [x] I have reviewed the Release Workflow cursor rule
- [ ] All tests pass (yarn build && yarn test && yarn lint)
- [x] Changelog validation passes (yarn changelog:validate)

## **Pre-merge reviewer checklist**

- [x] I have reviewed the Reviewing Release PRs guide
- [x] Package versions follow semantic versioning
- [x] Changelog entries are consumer-facing (not commit message
regurgitation)
- [x] Breaking changes are documented in MIGRATION.md with examples
- [x] All unreleased changes are accounted for in changelogs

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit 87c05a5. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
georgewrmarshall pushed a commit that referenced this pull request Apr 6, 2026
…k` callback (#1024)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

Removed `shouldNavigateBack` and leave only `goBack` option.

Since we decided, that we will not create wrapper inside `mobile` repo
for this component it's clear that with new API we need:
- provide `goBack` when `shouldNavigateBack={true}`
- don't provide `goBack` when `shouldNavigateBack={false}`

And this logic is kind of duplicated now. We try to control a single
thing (navigation) use two variables. We can optimize it and provide
only `goBack` callback:
- when it's provided it will be called;
- when it's not provided it will not be called.

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-639

## **Manual testing steps**

1. Go to BottomSheet example
2. Verify that new API works as expected

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> This is a small but breaking API change: `shouldNavigateBack` is
removed and close-time navigation now depends solely on whether `goBack`
is provided, which could change consumer behavior if not updated.
> 
> **Overview**
> Simplifies BottomSheet navigation behavior by **removing
`shouldNavigateBack`** and making `goBack` **optional**; when provided,
`goBack` is now always invoked once on sheet close.
> 
> Updates the component implementation, Storybook stories, tests, and
README to reflect the new API and eliminate the previous conditional
navigation flag.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3e2f1f7. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
georgewrmarshall added a commit that referenced this pull request Apr 6, 2026
## Release 29.0.0

This release includes new React Native header and layout primitives,
BottomSheet API updates, shared type migrations, and
documentation/runtime dependency alignment across core design-system
packages.

### 📦 Package Versions

- @metamask/design-system-shared: 0.7.0
- @metamask/design-system-react: 0.14.0
- @metamask/design-system-react-native: 0.14.0

### 🔄 Shared Type Updates (0.7.0)

#### Added

- Added shared types used by new React Native header components,
including HeaderRoot contracts consumed by
@metamask/design-system-react-native (#1029).
- Added shared BoxHorizontal and BoxVertical utility component contracts
for cross-platform layout primitives (#1003).

#### Changed

- Migrated AvatarBase type exports from enum-based definitions to shared
const-object + string-union types, aligned with ADR-0003/ADR-0004
(#1005).
- Updated @metamask/utils dependency to ^11.11.0 (#1033).

### 🌐 React Web Updates (0.14.0)

#### Changed

- BREAKING: Updated AvatarBase exports to consume shared const-object +
string-union types rather than local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for recent releases (#1011).

### 📱 React Native Updates (0.14.0)

#### Added

- Added HeaderRoot as a new root primitive for React Native header
composition (#1029).
- Added HeaderStandard for standardized title + action header layouts in
mobile screens (#1028, #1030).
- Added TextFieldSearch for search-style text input flows on mobile
(#1027).
- Added BoxHorizontal and BoxVertical utility components for directional
layout composition (#1003).

#### Changed

- BREAKING: Replaced BottomSheet shouldNavigateBack with an optional
goBack callback for explicit navigation handling in host apps (#1024).
- Remove shouldNavigateBack usage and pass goBack when sheet close
should navigate back.
- See migration guide:
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- Added panGestureHandlerProps support to BottomSheet for
gesture-handler customization (#1016).
- Migrated React Native package exports from default exports to named
exports for consistent import ergonomics (#1032).
- BREAKING: Updated AvatarBase exports to use shared const-object +
string-union types instead of local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react-native as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for consumers (#1011).

#### Fixed

- Updated BottomSheetHeader action button size to md for consistent
sizing and visual alignment (#1012).

### ⚠️ Breaking Changes

- BottomSheet (React Native): replaced shouldNavigateBack with optional
goBack callback (#1024).
- Migration required where shouldNavigateBack was used; see
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- AvatarBase export type migration (React + React Native): moved from
local enums to shared const-object + string-union types (#1005).
- Marked breaking for type contract changes, but no migration is
expected for typical consumer imports/usage.

### ✅ Checklist

- [x] Changelogs updated with human-readable descriptions
- [x] Changelog validation passed (yarn changelog:validate)
- [x] Version bumps follow semantic versioning
- [x] design-system-shared: minor (0.6.0 to 0.7.0) - shared types and
dependency alignment
- [x] design-system-react: minor (0.13.0 to 0.14.0) - shared type
migration and docs/dependency updates
- [x] design-system-react-native: minor (0.13.0 to 0.14.0) - new
components and API enhancements
- [x] Breaking changes documented with migration guidance
- [x] Migration guides updated with before/after examples (if breaking
changes)
- [x] PR references included in changelog entries

## **Pre-merge author checklist**

- [x] I have followed MetaMask Contributor Docs
- [x] I have reviewed the Release Workflow cursor rule
- [ ] All tests pass (yarn build && yarn test && yarn lint)
- [x] Changelog validation passes (yarn changelog:validate)

## **Pre-merge reviewer checklist**

- [x] I have reviewed the Reviewing Release PRs guide
- [x] Package versions follow semantic versioning
- [x] Changelog entries are consumer-facing (not commit message
regurgitation)
- [x] Breaking changes are documented in MIGRATION.md with examples
- [x] All unreleased changes are accounted for in changelogs

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit 87c05a5. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
georgewrmarshall pushed a commit that referenced this pull request Apr 27, 2026
…k` callback (#1024)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
2. What is the improvement/solution?
-->

Removed `shouldNavigateBack` and leave only `goBack` option.

Since we decided, that we will not create wrapper inside `mobile` repo
for this component it's clear that with new API we need:
- provide `goBack` when `shouldNavigateBack={true}`
- don't provide `goBack` when `shouldNavigateBack={false}`

And this logic is kind of duplicated now. We try to control a single
thing (navigation) use two variables. We can optimize it and provide
only `goBack` callback:
- when it's provided it will be called;
- when it's not provided it will not be called.

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/DSYS-639

## **Manual testing steps**

1. Go to BottomSheet example
2. Verify that new API works as expected

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->

### **After**

<!-- [screenshots/recordings] -->

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs)
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-extension/blob/develop/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> This is a small but breaking API change: `shouldNavigateBack` is
removed and close-time navigation now depends solely on whether `goBack`
is provided, which could change consumer behavior if not updated.
> 
> **Overview**
> Simplifies BottomSheet navigation behavior by **removing
`shouldNavigateBack`** and making `goBack` **optional**; when provided,
`goBack` is now always invoked once on sheet close.
> 
> Updates the component implementation, Storybook stories, tests, and
README to reflect the new API and eliminate the previous conditional
navigation flag.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
3e2f1f7. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
georgewrmarshall added a commit that referenced this pull request Apr 27, 2026
## Release 29.0.0

This release includes new React Native header and layout primitives,
BottomSheet API updates, shared type migrations, and
documentation/runtime dependency alignment across core design-system
packages.

### 📦 Package Versions

- @metamask/design-system-shared: 0.7.0
- @metamask/design-system-react: 0.14.0
- @metamask/design-system-react-native: 0.14.0

### 🔄 Shared Type Updates (0.7.0)

#### Added

- Added shared types used by new React Native header components,
including HeaderRoot contracts consumed by
@metamask/design-system-react-native (#1029).
- Added shared BoxHorizontal and BoxVertical utility component contracts
for cross-platform layout primitives (#1003).

#### Changed

- Migrated AvatarBase type exports from enum-based definitions to shared
const-object + string-union types, aligned with ADR-0003/ADR-0004
(#1005).
- Updated @metamask/utils dependency to ^11.11.0 (#1033).

### 🌐 React Web Updates (0.14.0)

#### Changed

- BREAKING: Updated AvatarBase exports to consume shared const-object +
string-union types rather than local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for recent releases (#1011).

### 📱 React Native Updates (0.14.0)

#### Added

- Added HeaderRoot as a new root primitive for React Native header
composition (#1029).
- Added HeaderStandard for standardized title + action header layouts in
mobile screens (#1028, #1030).
- Added TextFieldSearch for search-style text input flows on mobile
(#1027).
- Added BoxHorizontal and BoxVertical utility components for directional
layout composition (#1003).

#### Changed

- BREAKING: Replaced BottomSheet shouldNavigateBack with an optional
goBack callback for explicit navigation handling in host apps (#1024).
- Remove shouldNavigateBack usage and pass goBack when sheet close
should navigate back.
- See migration guide:
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- Added panGestureHandlerProps support to BottomSheet for
gesture-handler customization (#1016).
- Migrated React Native package exports from default exports to named
exports for consistent import ergonomics (#1032).
- BREAKING: Updated AvatarBase exports to use shared const-object +
string-union types instead of local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react-native as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for consumers (#1011).

#### Fixed

- Updated BottomSheetHeader action button size to md for consistent
sizing and visual alignment (#1012).

### ⚠️ Breaking Changes

- BottomSheet (React Native): replaced shouldNavigateBack with optional
goBack callback (#1024).
- Migration required where shouldNavigateBack was used; see
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- AvatarBase export type migration (React + React Native): moved from
local enums to shared const-object + string-union types (#1005).
- Marked breaking for type contract changes, but no migration is
expected for typical consumer imports/usage.

### ✅ Checklist

- [x] Changelogs updated with human-readable descriptions
- [x] Changelog validation passed (yarn changelog:validate)
- [x] Version bumps follow semantic versioning
- [x] design-system-shared: minor (0.6.0 to 0.7.0) - shared types and
dependency alignment
- [x] design-system-react: minor (0.13.0 to 0.14.0) - shared type
migration and docs/dependency updates
- [x] design-system-react-native: minor (0.13.0 to 0.14.0) - new
components and API enhancements
- [x] Breaking changes documented with migration guidance
- [x] Migration guides updated with before/after examples (if breaking
changes)
- [x] PR references included in changelog entries

## **Pre-merge author checklist**

- [x] I have followed MetaMask Contributor Docs
- [x] I have reviewed the Release Workflow cursor rule
- [ ] All tests pass (yarn build && yarn test && yarn lint)
- [x] Changelog validation passes (yarn changelog:validate)

## **Pre-merge reviewer checklist**

- [x] I have reviewed the Reviewing Release PRs guide
- [x] Package versions follow semantic versioning
- [x] Changelog entries are consumer-facing (not commit message
regurgitation)
- [x] Breaking changes are documented in MIGRATION.md with examples
- [x] All unreleased changes are accounted for in changelogs

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit 87c05a5. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
cursor Bot pushed a commit that referenced this pull request Apr 28, 2026
## Release 29.0.0

This release includes new React Native header and layout primitives,
BottomSheet API updates, shared type migrations, and
documentation/runtime dependency alignment across core design-system
packages.

### 📦 Package Versions

- @metamask/design-system-shared: 0.7.0
- @metamask/design-system-react: 0.14.0
- @metamask/design-system-react-native: 0.14.0

### 🔄 Shared Type Updates (0.7.0)

#### Added

- Added shared types used by new React Native header components,
including HeaderRoot contracts consumed by
@metamask/design-system-react-native (#1029).
- Added shared BoxHorizontal and BoxVertical utility component contracts
for cross-platform layout primitives (#1003).

#### Changed

- Migrated AvatarBase type exports from enum-based definitions to shared
const-object + string-union types, aligned with ADR-0003/ADR-0004
(#1005).
- Updated @metamask/utils dependency to ^11.11.0 (#1033).

### 🌐 React Web Updates (0.14.0)

#### Changed

- BREAKING: Updated AvatarBase exports to consume shared const-object +
string-union types rather than local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for recent releases (#1011).

### 📱 React Native Updates (0.14.0)

#### Added

- Added HeaderRoot as a new root primitive for React Native header
composition (#1029).
- Added HeaderStandard for standardized title + action header layouts in
mobile screens (#1028, #1030).
- Added TextFieldSearch for search-style text input flows on mobile
(#1027).
- Added BoxHorizontal and BoxVertical utility components for directional
layout composition (#1003).

#### Changed

- BREAKING: Replaced BottomSheet shouldNavigateBack with an optional
goBack callback for explicit navigation handling in host apps (#1024).
- Remove shouldNavigateBack usage and pass goBack when sheet close
should navigate back.
- See migration guide:
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- Added panGestureHandlerProps support to BottomSheet for
gesture-handler customization (#1016).
- Migrated React Native package exports from default exports to named
exports for consistent import ergonomics (#1032).
- BREAKING: Updated AvatarBase exports to use shared const-object +
string-union types instead of local enums (#1005).
- No migration required for typical usage; continue importing from
@metamask/design-system-react-native as before.
- Runtime values remain stable while type definitions follow
ADR-0003/ADR-0004.
- Updated @metamask/utils peer dependency to ^11.11.0 (#1033).
- Expanded BannerBase migration documentation to improve upgrade
guidance for consumers (#1011).

#### Fixed

- Updated BottomSheetHeader action button size to md for consistent
sizing and visual alignment (#1012).

### ⚠️ Breaking Changes

- BottomSheet (React Native): replaced shouldNavigateBack with optional
goBack callback (#1024).
- Migration required where shouldNavigateBack was used; see
packages/design-system-react-native/MIGRATION.md#from-version-0130-to-0140.
- AvatarBase export type migration (React + React Native): moved from
local enums to shared const-object + string-union types (#1005).
- Marked breaking for type contract changes, but no migration is
expected for typical consumer imports/usage.

### ✅ Checklist

- [x] Changelogs updated with human-readable descriptions
- [x] Changelog validation passed (yarn changelog:validate)
- [x] Version bumps follow semantic versioning
- [x] design-system-shared: minor (0.6.0 to 0.7.0) - shared types and
dependency alignment
- [x] design-system-react: minor (0.13.0 to 0.14.0) - shared type
migration and docs/dependency updates
- [x] design-system-react-native: minor (0.13.0 to 0.14.0) - new
components and API enhancements
- [x] Breaking changes documented with migration guidance
- [x] Migration guides updated with before/after examples (if breaking
changes)
- [x] PR references included in changelog entries

## **Pre-merge author checklist**

- [x] I have followed MetaMask Contributor Docs
- [x] I have reviewed the Release Workflow cursor rule
- [ ] All tests pass (yarn build && yarn test && yarn lint)
- [x] Changelog validation passes (yarn changelog:validate)

## **Pre-merge reviewer checklist**

- [x] I have reviewed the Reviewing Release PRs guide
- [x] Package versions follow semantic versioning
- [x] Changelog entries are consumer-facing (not commit message
regurgitation)
- [x] Breaking changes are documented in MIGRATION.md with examples
- [x] All unreleased changes are accounted for in changelogs

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit 87c05a5. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants