Deprecate HeaderPage in favor of Header in @backstage/ui (#33188)

* Deprecate HeaderPage in favor of Header in @backstage/ui

Rename the HeaderPage component to Header, keeping HeaderPage as a
deprecated alias for backwards compatibility. Also deprecate
HeaderPageProps, HeaderPageOwnProps, HeaderPageBreadcrumb, and
HeaderPageDefinition with new Header* equivalents. Update all internal
usages, stories, and docs-ui documentation to use the new names.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

* Rename HeaderPage files and directories to Header

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

* Add changeset for mui-to-bui Header rename

Document the plugin release impact of switching the MUI to BUI theme converter page to the renamed Header component.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor

---------

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.changeset/deprecate-headerpage-to-header.md

@@ -0,0 +1,5 @@
+---
+'@backstage/ui': patch
+---
+
+Deprecated the `HeaderPage` component name in favor of `Header`. The old `HeaderPage`, `HeaderPageProps`, `HeaderPageOwnProps`, `HeaderPageBreadcrumb`, and `HeaderPageDefinition` exports are still available as deprecated aliases.

.changeset/mui-to-bui-header.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-mui-to-bui': patch
+---
+
+Updated the MUI to BUI theme converter page to use the renamed `Header` component from `@backstage/ui`.

docs-ui/src/app/components/header/components.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { HeaderPage } from '../../../../../packages/ui/src/components/HeaderPage/HeaderPage';
+import { Header } from '../../../../../packages/ui/src/components/Header/Header';
 import { Button } from '../../../../../packages/ui/src/components/Button/Button';
 import { ButtonIcon } from '../../../../../packages/ui/src/components/ButtonIcon/ButtonIcon';
 import {
@@ -31,7 +31,7 @@ const breadcrumbs = [
 
 export const WithEverything = () => (
   <MemoryRouter>
-    <HeaderPage
+    <Header
       title="Page Title"
       tabs={tabs.slice(0, 2)}
       breadcrumbs={breadcrumbs.slice(0, 2)}
@@ -47,28 +47,25 @@ export const WithEverything = () => (
 
 export const WithLongBreadcrumbs = () => (
   <MemoryRouter>
-    <HeaderPage title="Page Title" breadcrumbs={breadcrumbs.slice(0, 2)} />
+    <Header title="Page Title" breadcrumbs={breadcrumbs.slice(0, 2)} />
   </MemoryRouter>
 );
 
 export const WithTabs = () => (
   <MemoryRouter>
-    <HeaderPage title="Page Title" tabs={tabs.slice(0, 3)} />
+    <Header title="Page Title" tabs={tabs.slice(0, 3)} />
   </MemoryRouter>
 );
 
 export const WithCustomActions = () => (
   <MemoryRouter>
-    <HeaderPage
-      title="Page Title"
-      customActions={<Button>Custom action</Button>}
-    />
+    <Header title="Page Title" customActions={<Button>Custom action</Button>} />
   </MemoryRouter>
 );
 
 export const WithMenu = () => (
   <MemoryRouter>
-    <HeaderPage
+    <Header
       title="Page Title"
       customActions={
         <MenuTrigger>

docs-ui/src/app/components/header/page.mdx

@@ -19,11 +19,11 @@ import {
 } from './snippets';
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
-import { HeaderPageDefinition } from '../../../utils/definitions';
+import { HeaderDefinition } from '../../../utils/definitions';
 import { ChangelogComponent } from '@/components/ChangelogComponent';
 
 <PageTitle
-  title="HeaderPage"
+  title="Header"
   description="A secondary header with title, breadcrumbs, tabs, and actions."
 />
 
@@ -61,6 +61,6 @@ Use `customActions` to add a dropdown menu.
 
 <Snippet open preview={<WithMenu />} code={withMenu} />
 
-<Theming definition={HeaderPageDefinition} />
+<Theming definition={HeaderDefinition} />
 
-<ChangelogComponent component="header-page" />
+<ChangelogComponent component="header" />

docs-ui/src/app/components/header/props-definition.tsx

@@ -50,7 +50,7 @@ export const headerPagePropDefs: Record<string, PropDef> = {
     type: 'complex',
     description: 'Breadcrumb trail displayed above the title.',
     complexType: {
-      name: 'HeaderPageBreadcrumb[]',
+      name: 'HeaderBreadcrumb[]',
       properties: {
         label: {
           type: 'string',

docs-ui/src/app/components/header/snippets.ts

@@ -1,8 +1,8 @@
-export const usage = `import { HeaderPage } from '@backstage/ui';
+export const usage = `import { Header } from '@backstage/ui';
 
-<HeaderPage title="Page Title" />`;
+<Header title="Page Title" />`;
 
-export const defaultSnippet = `<HeaderPage
+export const defaultSnippet = `<Header
   title="Page Title"
   breadcrumbs={[
     { label: 'Home', href: '/' },
@@ -20,7 +20,7 @@ export const defaultSnippet = `<HeaderPage
   }
 />`;
 
-export const withBreadcrumbs = `<HeaderPage
+export const withBreadcrumbs = `<Header
   title="Page Title"
   breadcrumbs={[
     { label: 'Home', href: '/' },
@@ -28,7 +28,7 @@ export const withBreadcrumbs = `<HeaderPage
   ]}
 />`;
 
-export const withTabs = `<HeaderPage
+export const withTabs = `<Header
   title="Page Title"
   tabs={[
     { id: 'overview', label: 'Overview', href: '/overview' },
@@ -37,12 +37,12 @@ export const withTabs = `<HeaderPage
   ]}
 />`;
 
-export const withCustomActions = `<HeaderPage
+export const withCustomActions = `<Header
   title="Page Title"
   customActions={<Button>Custom action</Button>}
 />`;
 
-export const withMenu = `<HeaderPage
+export const withMenu = `<Header
   title="Page Title"
   customActions={
     <MenuTrigger>

docs-ui/src/app/components/plugin-header/components.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { PluginHeader } from '../../../../../packages/ui/src/components/PluginHeader/PluginHeader';
-import { HeaderPage } from '../../../../../packages/ui/src/components/HeaderPage/HeaderPage';
+import { Header } from '../../../../../packages/ui/src/components/Header/Header';
 import { ButtonIcon } from '../../../../../packages/ui/src/components/ButtonIcon/ButtonIcon';
 import { Button } from '../../../../../packages/ui/src/components/Button/Button';
 import { MemoryRouter } from 'react-router-dom';
@@ -58,11 +58,11 @@ export const WithAllOptions = () => (
   </MemoryRouter>
 );
 
-export const WithHeaderPage = () => (
+export const WithHeader = () => (
   <MemoryRouter>
     <>
       <PluginHeader title="My plugin" titleLink="/" tabs={tabs.slice(0, 2)} />
-      <HeaderPage
+      <Header
         title="Page title"
         tabs={tabs2}
         customActions={<Button>Custom action</Button>}

docs-ui/src/app/components/plugin-header/page.mdx

@@ -4,7 +4,7 @@ import { Snippet } from '@/components/Snippet';
 import {
   WithAllOptionsAndTabs,
   WithAllOptions,
-  WithHeaderPage,
+  WithHeader,
 } from './components';
 import { headerPropDefs } from './props-definition';
 import {
@@ -12,7 +12,7 @@ import {
   simple,
   defaultSnippet,
   withTabs,
-  withHeaderPage,
+  withHeader,
 } from './snippets';
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
@@ -46,11 +46,11 @@ Tabs use React Router and highlight automatically based on the current route.
 
 <Snippet preview={<WithAllOptionsAndTabs />} code={withTabs} open />
 
-### Plugin header with HeaderPage
+### Plugin header with Header
 
-Combine with [HeaderPage](/components/header-page) for multi-level navigation.
+Combine with [Header](/components/header) for multi-level navigation.
 
-<Snippet preview={<WithHeaderPage />} code={withHeaderPage} open />
+<Snippet preview={<WithHeader />} code={withHeader} open />
 
 <Theming definition={PluginHeaderDefinition} />
 

docs-ui/src/app/components/plugin-header/snippets.ts

@@ -43,7 +43,7 @@ export const withTabs = `<PluginHeader
   ]}
 />`;
 
-export const withHeaderPage = `<PluginHeader
+export const withHeader = `<PluginHeader
   title="My plugin"
   titleLink="/"
   tabs={[
@@ -51,7 +51,7 @@ export const withHeaderPage = `<PluginHeader
     { id: 'checks', label: 'Checks', href: '/checks' },
   ]}
 />
-<HeaderPage
+<Header
   title="Page title"
   tabs={[
     { id: 'banana', label: 'Banana', href: '/banana' },

docs-ui/src/utils/changelogs/v0.9.0.ts

@@ -114,7 +114,7 @@ After:
       'switch',
       'skeleton',
       'plugin-header',
-      'header-page',
+      'header',
       'tabs',
     ],
     version: '0.9.0',

docs-ui/src/utils/data.ts

@@ -62,8 +62,8 @@ export const components: Page[] = [
     slug: 'plugin-header',
   },
   {
-    title: 'HeaderPage',
-    slug: 'header-page',
+    title: 'Header',
+    slug: 'header',
   },
   {
     title: 'Link',

docs-ui/src/utils/types.ts

@@ -15,7 +15,7 @@ export type Component =
   | 'flex'
   | 'grid'
   | 'plugin-header'
-  | 'header-page'
+  | 'header'
   | 'heading'
   | 'icon'
   | 'link'

packages/ui/report.api.md

@@ -1401,10 +1401,10 @@ export interface GridProps
 }
 
 // @public
-export const HeaderPage: (props: HeaderPageProps) => JSX_2.Element;
+export const Header: (props: HeaderProps) => JSX_2.Element;
 
 // @public
-export interface HeaderPageBreadcrumb {
+export interface HeaderBreadcrumb {
   // (undocumented)
   href: string;
   // (undocumented)
@@ -1412,7 +1412,7 @@ export interface HeaderPageBreadcrumb {
 }
 
 // @public
-export const HeaderPageDefinition: {
+export const HeaderDefinition: {
   readonly styles: {
     readonly [key: string]: string;
   };
@@ -1433,9 +1433,9 @@ export const HeaderPageDefinition: {
 };
 
 // @public
-export interface HeaderPageOwnProps {
+export interface HeaderOwnProps {
   // (undocumented)
-  breadcrumbs?: HeaderPageBreadcrumb[];
+  breadcrumbs?: HeaderBreadcrumb[];
   // (undocumented)
   className?: string;
   // (undocumented)
@@ -1446,8 +1446,41 @@ export interface HeaderPageOwnProps {
   title?: string;
 }
 
+// @public @deprecated (undocumented)
+export const HeaderPage: (props: HeaderProps) => JSX_2.Element;
+
+// @public @deprecated (undocumented)
+export type HeaderPageBreadcrumb = HeaderBreadcrumb;
+
+// @public @deprecated (undocumented)
+export const HeaderPageDefinition: {
+  readonly styles: {
+    readonly [key: string]: string;
+  };
+  readonly classNames: {
+    readonly root: 'bui-HeaderPage';
+    readonly content: 'bui-HeaderPageContent';
+    readonly breadcrumbs: 'bui-HeaderPageBreadcrumbs';
+    readonly tabsWrapper: 'bui-HeaderPageTabsWrapper';
+    readonly controls: 'bui-HeaderPageControls';
+  };
+  readonly propDefs: {
+    readonly title: {};
+    readonly customActions: {};
+    readonly tabs: {};
+    readonly breadcrumbs: {};
+    readonly className: {};
+  };
+};
+
+// @public @deprecated (undocumented)
+export type HeaderPageOwnProps = HeaderOwnProps;
+
+// @public @deprecated (undocumented)
+export type HeaderPageProps = HeaderProps;
+
 // @public
-export interface HeaderPageProps extends HeaderPageOwnProps {}
+export interface HeaderProps extends HeaderOwnProps {}
 
 // @public
 export interface HeaderTab {

packages/ui/src/components/Header/Header.stories.tsx

@@ -16,7 +16,7 @@
 
 import preview from '../../../../../.storybook/preview';
 import type { StoryFn } from '@storybook/react-vite';
-import { HeaderPage } from './HeaderPage';
+import { Header } from './Header';
 import type { HeaderTab } from '../PluginHeader/types';
 import { MemoryRouter } from 'react-router-dom';
 import {
@@ -31,8 +31,8 @@ import {
 import { RiMore2Line } from '@remixicon/react';
 
 const meta = preview.meta({
-  title: 'Backstage UI/HeaderPage',
-  component: HeaderPage,
+  title: 'Backstage UI/Header',
+  component: Header,
   parameters: {
     layout: 'fullscreen',
   },
@@ -145,7 +145,7 @@ export const WithTabs = meta.story({
 export const WithCustomActions = meta.story({
   decorators: [withRouter],
   render: () => (
-    <HeaderPage
+    <Header
       {...Default.input.args}
       customActions={
         <>
@@ -196,7 +196,7 @@ export const WithLongBreadcrumbs = meta.story({
 export const WithEverything = meta.story({
   decorators: [withRouter],
   render: () => (
-    <HeaderPage
+    <Header
       {...Default.input.args}
       tabs={tabs}
       customActions={<Button>Custom action</Button>}
@@ -239,7 +239,7 @@ export const WithTabsMatchingStrategies = meta.story({
   },
   render: args => (
     <MemoryRouter initialEntries={['/mentorship/events']}>
-      <HeaderPage {...args} />
+      <Header {...args} />
       <Container>
         <Text>
           <strong>Current URL:</strong> /mentorship/events
@@ -292,7 +292,7 @@ export const WithTabsExactMatching = meta.story({
   },
   render: args => (
     <MemoryRouter initialEntries={['/mentorship/events']}>
-      <HeaderPage {...args} />
+      <Header {...args} />
       <Container>
         <Text>
           <strong>Current URL:</strong> /mentorship/events
@@ -334,7 +334,7 @@ export const WithTabsPrefixMatchingDeep = meta.story({
   },
   render: args => (
     <MemoryRouter initialEntries={['/catalog/users/john/details']}>
-      <HeaderPage {...args} />
+      <Header {...args} />
       <Container>
         <Text as="p">
           <strong>Current URL:</strong> /catalog/users/john/details

packages/ui/src/components/Header/Header.tsx

@@ -14,23 +14,23 @@
  * limitations under the License.
  */
 
-import type { HeaderPageProps } from './types';
+import type { HeaderProps } from './types';
 import { Text } from '../Text';
 import { RiArrowRightSLine } from '@remixicon/react';
 import { Tabs, TabList, Tab } from '../Tabs';
 import { useDefinition } from '../../hooks/useDefinition';
-import { HeaderPageDefinition } from './definition';
+import { HeaderDefinition } from './definition';
 import { Container } from '../Container';
 import { Link } from '../Link';
 import { Fragment } from 'react/jsx-runtime';
 
 /**
- * A component that renders a header page.
+ * A secondary header with title, breadcrumbs, tabs, and actions.
  *
  * @public
  */
-export const HeaderPage = (props: HeaderPageProps) => {
-  const { ownProps } = useDefinition(HeaderPageDefinition, props);
+export const Header = (props: HeaderProps) => {
+  const { ownProps } = useDefinition(HeaderDefinition, props);
   const { classes, title, tabs, customActions, breadcrumbs } = ownProps;
 
   return (
@@ -81,3 +81,9 @@ export const HeaderPage = (props: HeaderPageProps) => {
     </Container>
   );
 };
+
+/**
+ * @public
+ * @deprecated Use {@link Header} instead.
+ */
+export const HeaderPage = Header;

packages/ui/src/components/Header/definition.ts

@@ -15,14 +15,14 @@
  */
 
 import { defineComponent } from '../../hooks/useDefinition';
-import type { HeaderPageOwnProps } from './types';
-import styles from './HeaderPage.module.css';
+import type { HeaderOwnProps } from './types';
+import styles from './Header.module.css';
 
 /**
- * Component definition for HeaderPage
+ * Component definition for Header
  * @public
  */
-export const HeaderPageDefinition = defineComponent<HeaderPageOwnProps>()({
+export const HeaderDefinition = defineComponent<HeaderOwnProps>()({
   styles,
   classNames: {
     root: 'bui-HeaderPage',
@@ -39,3 +39,9 @@ export const HeaderPageDefinition = defineComponent<HeaderPageOwnProps>()({
     className: {},
   },
 });
+
+/**
+ * @public
+ * @deprecated Use {@link HeaderDefinition} instead.
+ */
+export const HeaderPageDefinition = HeaderDefinition;

packages/ui/src/components/Header/index.tsx

@@ -14,9 +14,12 @@
  * limitations under the License.
  */
 
-export { HeaderPage } from './HeaderPage';
-export { HeaderPageDefinition } from './definition';
+export { Header, HeaderPage } from './Header';
+export { HeaderDefinition, HeaderPageDefinition } from './definition';
 export type {
+  HeaderOwnProps,
+  HeaderProps,
+  HeaderBreadcrumb,
   HeaderPageOwnProps,
   HeaderPageProps,
   HeaderPageBreadcrumb,

packages/ui/src/components/Header/types.ts

@@ -17,31 +17,49 @@
 import type { HeaderTab } from '../PluginHeader/types';
 
 /**
- * Own props for the HeaderPage component.
+ * Own props for the Header component.
  *
  * @public
  */
-export interface HeaderPageOwnProps {
+export interface HeaderOwnProps {
   title?: string;
   customActions?: React.ReactNode;
   tabs?: HeaderTab[];
-  breadcrumbs?: HeaderPageBreadcrumb[];
+  breadcrumbs?: HeaderBreadcrumb[];
   className?: string;
 }
 
 /**
- * Props for the main HeaderPage component.
+ * Props for the Header component.
  *
  * @public
  */
-export interface HeaderPageProps extends HeaderPageOwnProps {}
+export interface HeaderProps extends HeaderOwnProps {}
 
 /**
  * Represents a breadcrumb item in the header.
  *
  * @public
  */
-export interface HeaderPageBreadcrumb {
+export interface HeaderBreadcrumb {
   label: string;
   href: string;
 }
+
+/**
+ * @public
+ * @deprecated Use {@link HeaderOwnProps} instead.
+ */
+export type HeaderPageOwnProps = HeaderOwnProps;
+
+/**
+ * @public
+ * @deprecated Use {@link HeaderProps} instead.
+ */
+export type HeaderPageProps = HeaderProps;
+
+/**
+ * @public
+ * @deprecated Use {@link HeaderBreadcrumb} instead.
+ */
+export type HeaderPageBreadcrumb = HeaderBreadcrumb;

packages/ui/src/components/PluginHeader/PluginHeader.stories.tsx

@@ -20,7 +20,7 @@ import { PluginHeader } from './PluginHeader';
 import type { HeaderTab } from './types';
 import {
   Button,
-  HeaderPage,
+  Header,
   Container,
   Text,
   ButtonIcon,
@@ -35,7 +35,7 @@ import {
   RiCloudy2Line,
   RiMore2Line,
 } from '@remixicon/react';
-import { HeaderPageBreadcrumb } from '../HeaderPage/types';
+import { HeaderBreadcrumb } from '../Header/types';
 
 const meta = preview.meta({
   title: 'Backstage UI/PluginHeader',
@@ -117,7 +117,7 @@ const menuItems = [
   },
 ];
 
-const breadcrumbs: HeaderPageBreadcrumb[] = [
+const breadcrumbs: HeaderBreadcrumb[] = [
   {
     label: 'Home',
     href: '/',
@@ -246,7 +246,7 @@ export const WithAllOptionsAndTabs = WithCustomActions.extend({
   },
 });
 
-export const WithHeaderPage = meta.story({
+export const WithHeader = meta.story({
   args: {
     ...WithAllOptionsAndTabs.input.args,
   },
@@ -263,7 +263,7 @@ export const WithHeaderPage = meta.story({
           </>
         }
       />
-      <HeaderPage
+      <Header
         title="Page title"
         tabs={tabs2}
         customActions={<Button>Custom action</Button>}
@@ -278,7 +278,7 @@ export const WithLayout = meta.story({
   render: args => (
     <>
       <PluginHeader {...args} tabs={tabs} />
-      <HeaderPage
+      <Header
         title="Page title"
         tabs={tabs2}
         customActions={<Button>Custom action</Button>}
@@ -293,7 +293,7 @@ export const WithLayoutNoTabs = meta.story({
   render: args => (
     <>
       <PluginHeader {...args} />
-      <HeaderPage title="Page title" tabs={tabs2} />
+      <Header title="Page title" tabs={tabs2} />
     </>
   ),
 });
@@ -316,7 +316,7 @@ export const WithEverything = meta.story({
           </>
         }
       />
-      <HeaderPage
+      <Header
         title="Page title"
         tabs={tabs2}
         customActions={

packages/ui/src/definitions.ts

@@ -43,7 +43,10 @@ export {
   GridItemDefinition,
 } from './components/Grid/definition';
 export { PluginHeaderDefinition } from './components/PluginHeader/definition';
-export { HeaderPageDefinition } from './components/HeaderPage/definition';
+export {
+  HeaderDefinition,
+  HeaderPageDefinition,
+} from './components/Header/definition';
 export { LinkDefinition } from './components/Link/definition';
 export { MenuDefinition } from './components/Menu/definition';
 export { PasswordFieldDefinition } from './components/PasswordField/definition';

packages/ui/src/guidelines/CardsWithTable.stories.tsx

@@ -32,7 +32,7 @@ import {
   useTable,
   type ColumnConfig,
   PluginHeader,
-  HeaderPage,
+  Header,
   Button,
 } from '..';
 
@@ -235,7 +235,7 @@ const CardsWithTableLayout = () => {
   return (
     <>
       <PluginHeader title="Plugin" />
-      <HeaderPage
+      <Header
         title="Page title"
         customActions={<Button>Custom action</Button>}
       />

packages/ui/src/index.ts

@@ -36,7 +36,7 @@ export * from './components/Card';
 export * from './components/Dialog';
 export * from './components/FieldLabel';
 export * from './components/PluginHeader';
-export * from './components/HeaderPage';
+export * from './components/Header';
 export * from './components/ButtonIcon';
 export * from './components/ButtonLink';
 export * from './components/Checkbox';

plugins/mui-to-bui/src/components/BuiThemerPage/BuiThemerPage.tsx

@@ -16,7 +16,7 @@
 
 import { useApi } from '@backstage/core-plugin-api';
 import { appThemeApiRef } from '@backstage/core-plugin-api';
-import { Box, Card, Container, Flex, HeaderPage, Text } from '@backstage/ui';
+import { Box, Card, Container, Flex, Header, Text } from '@backstage/ui';
 import { ThemeContent } from './ThemeContent';
 import { MuiThemeExtractor } from './MuiThemeExtractor';
 
@@ -26,7 +26,7 @@ export const BuiThemerPage = () => {
 
   return (
     <Container>
-      <HeaderPage title="BUI Theme Converter" />
+      <Header title="BUI Theme Converter" />
       <Box m="4">
         <Text variant="body-medium" color="secondary">
           Convert your MUI v5 theme into BUI CSS variables. Pick a theme to view