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>

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';