Skip to content

feat: [DSRN] Added HeaderStandard#1028

Merged
brianacnguyen merged 4 commits into
mainfrom
dsrn/headerstandard
Apr 1, 2026
Merged

feat: [DSRN] Added HeaderStandard#1028
brianacnguyen merged 4 commits into
mainfrom
dsrn/headerstandard

Conversation

@brianacnguyen

@brianacnguyen brianacnguyen commented Apr 1, 2026

Copy link
Copy Markdown
Contributor

Description

Adds HeaderStandard to @metamask/design-system-react-native: a header built on HeaderBase with a centered title / subtitle (string or node, with optional titleProps / subtitleProps), default horizontal padding (px-2), and convenience wiring for back (onBack, backButtonProps → arrow ButtonIcon) and close (onClose, closeButtonProps → close ButtonIcon), while still supporting HeaderBase behavior (children overrides title UI, startButtonIconProps / endButtonIconProps, variant, insets, etc.).

Also adds Storybook stories (Components/HeaderStandard), registers them in apps/storybook-react-native/.storybook/storybook.requires.js, unit tests (HeaderStandard.test.tsx), typed props (HeaderStandard.types.ts), and a README with usage examples.


Related issues

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

Manual testing steps

  1. From the repo root, run React Native Storybook (yarn storybook:ios and/or yarn storybook:android).
  2. Open Components → HeaderStandard and exercise stories: title only, title + subtitle, back, close, custom children, combinations with extra end icons if applicable.
  3. Optionally run unit tests for the package:
    yarn workspace @metamask/design-system-react-native run jest -- HeaderStandard
    (or your usual Jest invocation for that workspace).

Screenshots/Recordings

Before

After

Simulator.Screen.Recording.-.iPhone.15.Pro.Max.-.2026-04-01.at.11.11.25.mov

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

Low Risk
Low risk: this is a new UI component and export with accompanying stories/tests/docs, with minimal impact on existing runtime behavior aside from expanding the public API surface.

Overview
Introduces HeaderStandard, a new HeaderBase-based header that centers title/subtitle content (or custom children), applies default px-2 padding, and provides convenience wiring for back (arrow ButtonIcon) and close (close ButtonIcon) actions plus optional end icons.

Adds comprehensive Storybook stories, unit tests, and a README, and exposes the component via the design-system components/index.ts export; updates the React Native Storybook autogen storybook.requires.js to include the new story.

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

@brianacnguyen brianacnguyen self-assigned this Apr 1, 2026
@brianacnguyen brianacnguyen requested a review from a team as a code owner April 1, 2026 18:25
@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

@github-actions

github-actions Bot commented Apr 1, 2026

Copy link
Copy Markdown
Contributor

📖 Storybook Preview

@brianacnguyen brianacnguyen enabled auto-merge (squash) April 1, 2026 20:05

@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.

Approved! Left some non-blocking comments

@brianacnguyen brianacnguyen merged commit 8f916f0 into main Apr 1, 2026
44 checks passed
@brianacnguyen brianacnguyen deleted the dsrn/headerstandard branch April 1, 2026 22:20
iconName: IconName.ArrowLeft,
...(backButtonProps || {}),
onPress: backButtonProps?.onPress ?? onBack,
} as ButtonIconProps;

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.

non-blocking: Can we avoid as ButtonIconProps here and rely on typed object construction instead?

export { HeaderBase, HeaderBaseVariant } from './HeaderBase';
export type { HeaderBaseProps } from './HeaderBase';

export { default as HeaderStandard } from './HeaderStandard';

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.

non-blocking: Could we avoid default as here and export a named HeaderStandard symbol from the component module instead?

@@ -0,0 +1,2 @@
export { default } from './HeaderStandard';

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.

non-blocking: Could we avoid default re-export style here (export { default } from ...) and use named exports for consistency?

startButtonIconProps={resolvedStartButtonIconProps}
endButtonIconProps={resolvedEndButtonIconProps}
{...headerBaseProps}
twClassName={`px-2 ${twClassName}`.trim()}

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.

non-blocking: Is .trim() necessary here? Shouldn’t twrnc handle extra whitespace parsing in class names?

}}
bottomAccessory={
subtitle ? (
<Box twClassName="-mt-0.5">

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.

non-blocking: Is this subtitle Box wrapper necessary? It adds an extra element and consumers cannot target it via props.

@brianacnguyen

Copy link
Copy Markdown
Contributor Author

non-blocking: Nice addition overall with strong tests/docs. A few follow-ups for cleanup:

non-blocking: Can we avoid as ButtonIconProps and rely on typed object construction instead?

non-blocking: Is the subtitle wrapper Box necessary? It adds an extra element that consumers cannot target via props.

non-blocking: Is .trim() necessary on twClassName composition? Shouldn't twrnc handle extra whitespace parsing?

non-blocking: Can we avoid default re-export patterns (export { default } from ... and default as) and use named exports for consistency?

Will create a follow up PR

@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
## **Description**

Adds **`HeaderStandard`** to `@metamask/design-system-react-native`: a
header built on **`HeaderBase`** with a centered **title** /
**subtitle** (string or node, with optional `titleProps` /
`subtitleProps`), default horizontal padding (`px-2`), and convenience
wiring for **back** (`onBack`, `backButtonProps` → arrow `ButtonIcon`)
and **close** (`onClose`, `closeButtonProps` → close `ButtonIcon`),
while still supporting **`HeaderBase`** behavior (`children` overrides
title UI, `startButtonIconProps` / `endButtonIconProps`, variant,
insets, etc.).

Also adds **Storybook** stories (`Components/HeaderStandard`), registers
them in
**`apps/storybook-react-native/.storybook/storybook.requires.js`**,
**unit tests** (`HeaderStandard.test.tsx`), **typed props**
(`HeaderStandard.types.ts`), and a **README** with usage examples.

---

## **Related issues**

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

## **Manual testing steps**

1. From the repo root, run React Native Storybook (`yarn storybook:ios`
and/or `yarn storybook:android`).
2. Open **Components → HeaderStandard** and exercise stories: title
only, title + subtitle, back, close, custom children, combinations with
extra end icons if applicable.
3. Optionally run unit tests for the package:  
`yarn workspace @metamask/design-system-react-native run jest --
HeaderStandard`
   (or your usual Jest invocation for that workspace).

---

## **Screenshots/Recordings**

### **Before**


### **After**


https://github.com/user-attachments/assets/d8804ede-579c-49ce-ad6c-98853fd773ee

---

## **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]
> **Low Risk**
> Low risk: this is a new UI component and export with accompanying
stories/tests/docs, with minimal impact on existing runtime behavior
aside from expanding the public API surface.
> 
> **Overview**
> Introduces **`HeaderStandard`**, a new `HeaderBase`-based header that
centers title/subtitle content (or custom `children`), applies default
`px-2` padding, and provides convenience wiring for **back** (arrow
`ButtonIcon`) and **close** (close `ButtonIcon`) actions plus optional
end icons.
> 
> Adds comprehensive **Storybook stories**, **unit tests**, and a
**README**, and exposes the component via the design-system
`components/index.ts` export; updates the React Native Storybook autogen
`storybook.requires.js` to include the new story.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
960dc0d. 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
## **Description**

Adds **`HeaderStandard`** to `@metamask/design-system-react-native`: a
header built on **`HeaderBase`** with a centered **title** /
**subtitle** (string or node, with optional `titleProps` /
`subtitleProps`), default horizontal padding (`px-2`), and convenience
wiring for **back** (`onBack`, `backButtonProps` → arrow `ButtonIcon`)
and **close** (`onClose`, `closeButtonProps` → close `ButtonIcon`),
while still supporting **`HeaderBase`** behavior (`children` overrides
title UI, `startButtonIconProps` / `endButtonIconProps`, variant,
insets, etc.).

Also adds **Storybook** stories (`Components/HeaderStandard`), registers
them in
**`apps/storybook-react-native/.storybook/storybook.requires.js`**,
**unit tests** (`HeaderStandard.test.tsx`), **typed props**
(`HeaderStandard.types.ts`), and a **README** with usage examples.

---

## **Related issues**

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

## **Manual testing steps**

1. From the repo root, run React Native Storybook (`yarn storybook:ios`
and/or `yarn storybook:android`).
2. Open **Components → HeaderStandard** and exercise stories: title
only, title + subtitle, back, close, custom children, combinations with
extra end icons if applicable.
3. Optionally run unit tests for the package:  
`yarn workspace @metamask/design-system-react-native run jest --
HeaderStandard`
   (or your usual Jest invocation for that workspace).

---

## **Screenshots/Recordings**

### **Before**


### **After**


https://github.com/user-attachments/assets/d8804ede-579c-49ce-ad6c-98853fd773ee

---

## **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]
> **Low Risk**
> Low risk: this is a new UI component and export with accompanying
stories/tests/docs, with minimal impact on existing runtime behavior
aside from expanding the public API surface.
> 
> **Overview**
> Introduces **`HeaderStandard`**, a new `HeaderBase`-based header that
centers title/subtitle content (or custom `children`), applies default
`px-2` padding, and provides convenience wiring for **back** (arrow
`ButtonIcon`) and **close** (close `ButtonIcon`) actions plus optional
end icons.
> 
> Adds comprehensive **Storybook stories**, **unit tests**, and a
**README**, and exposes the component via the design-system
`components/index.ts` export; updates the React Native Storybook autogen
`storybook.requires.js` to include the new story.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
960dc0d. 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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants