feat!: header parity with frontend-component-header

Bring the shell header closer to visual parity with the old
frontend-component-header used by legacy MFEs.

The logo now links to whichever route claims the homeRole. Active nav
links get highlighted with the same dark navy background the old header
used, matching location.pathname against the link URL with
trailing-slash normalization.

The user dropdown replaces the generic Person icon and DropdownButton
with Paragon's AvatarButton inside a Dropdown, styled as
outline-primary. The user's profile image is shown when available, with
Paragon's default avatar fallback otherwise.

Header and page content now use Container fluid size="xl" instead of
fixed padding, so margins align at all viewport widths.

The root / redirect is now conditional: it only applies when an app
claims the home role, and is appended last so an app with its own /
route takes priority.

BREAKING CHANGE: route handles use a roles array instead of a single
role string.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: arbrandes

docs/how_tos/migrate-frontend-app.md

@@ -725,7 +725,7 @@ const app: App = {
     id: 'example.page',
     Component: ExamplePage,
     handle: {
-      role: 'example'
+      roles: ['example']
     }
   }],
 };
@@ -835,7 +835,7 @@ const siteConfig: SiteConfig = {
         <div>Test App 1</div>
       ),
       handle: {
-        role: 'test-app-1'
+        roles: ['test-app-1']
       }
     }]
   }],

runtime/react/hooks/useActiveRouteRoleWatcher.ts

@@ -14,8 +14,10 @@ const useActiveRouteRoleWatcher = () => {
     // Route roles
     for (const match of matches) {
       if (isRoleRouteObject(match)) {
-        if (!roles.includes(match.handle.role)) {
-          roles.push(match.handle.role);
+        for (const role of match.handle.roles) {
+          if (!roles.includes(role)) {
+            roles.push(role);
+          }
         }
       }
     }

runtime/routing/utils.test.ts

@@ -12,7 +12,7 @@ describe('getUrlByRouteRole', () => {
         appId: 'test-app',
         routes: [{
           path: '/app1',
-          handle: { role: 'test-app-1' },
+          handle: { roles: ['test-app-1'] },
         }],
       }],
     } as any);
@@ -29,7 +29,7 @@ describe('getUrlByRouteRole', () => {
           children: [
             {
               path: 'login',
-              handle: { role: 'org.openedx.frontend.role.login' },
+              handle: { roles: ['org.openedx.frontend.role.login'] },
             },
           ],
         }],

runtime/routing/utils.ts

@@ -8,7 +8,7 @@ function findRoleInRoutes(routes: RouteObject[], role: string, prefix = ''): str
     const segment = route.path ?? '';
     const fullPath = segment.startsWith('/') ? segment : `${prefix}/${segment}`.replace(/\/+/g, '/');
 
-    if (route.handle?.role === role) {
+    if (route.handle?.roles?.includes(role)) {
       return fullPath || null;
     }
 
@@ -48,5 +48,5 @@ export function getUrlByRouteRole(role: string) {
 }
 
 export function isRoleRouteObject(match: RouteObject): match is RoleRouteObject {
-  return match.handle !== undefined && 'role' in match.handle;
+  return match.handle !== undefined && 'roles' in match.handle;
 }

shell/Logo.test.tsx

@@ -16,31 +16,31 @@ describe('Logo component', () => {
     setSiteConfig(originalConfig);
   });
 
-  it('renders the image with default URL when no imageUrl prop is provided and headerLogoImageUrl is not set in site config', async () => {
-    const { getByRole, queryByRole } = render(<Logo />);
+  it('renders the image with default URL and links to / when no props are provided', async () => {
+    const { getByRole } = render(<Logo />);
     const image = getByRole('img');
     expect(image).toHaveAttribute('src', 'https://edx-cdn.org/v3/default/logo.svg');
-    const link = queryByRole('link');
-    expect(link).toBeNull();
+    const link = getByRole('link');
+    expect(link).toHaveAttribute('href', '/');
   });
 
-  it('renders the image with provided imageUrl', async () => {
+  it('renders the image with provided imageUrl and links to / by default', async () => {
     const testUrl = 'https://example.com/test-logo.svg';
-    const { getByRole, queryByRole } = render(<Logo imageUrl={testUrl} />);
+    const { getByRole } = render(<Logo imageUrl={testUrl} />);
     const image = getByRole('img');
     expect(image).toHaveAttribute('src', testUrl);
-    const link = queryByRole('link');
-    expect(link).toBeNull();
+    const link = getByRole('link');
+    expect(link).toHaveAttribute('href', '/');
   });
 
-  it('renders the image with headerLogoImageUrl when set in site config and no imageUrl prop is provided', async () => {
+  it('renders the image with headerLogoImageUrl when set in site config', async () => {
     const configLogoUrl = 'https://example.com/config-logo.svg';
     mergeSiteConfig({ headerLogoImageUrl: configLogoUrl });
-    const { getByRole, queryByRole } = render(<Logo />);
+    const { getByRole } = render(<Logo />);
     const image = getByRole('img');
     expect(image).toHaveAttribute('src', configLogoUrl);
-    const link = queryByRole('link');
-    expect(link).toBeNull();
+    const link = getByRole('link');
+    expect(link).toHaveAttribute('href', '/');
   });
 
   it('renders the image wrapped in a Hyperlink when destinationUrl is provided', async () => {

shell/Logo.tsx

@@ -1,6 +1,8 @@
 import { IntlProvider } from 'react-intl';
 import { Hyperlink, Image } from '@openedx/paragon';
 import { getSiteConfig } from '../runtime/config';
+import { getUrlByRouteRole } from '../runtime/routing';
+import { homeRole } from './constants';
 
 interface LogoProps {
   imageUrl?: string,
@@ -9,7 +11,7 @@ interface LogoProps {
 
 export default function Logo({
   imageUrl = getSiteConfig().headerLogoImageUrl ?? 'https://edx-cdn.org/v3/default/logo.svg',
-  destinationUrl
+  destinationUrl = getUrlByRouteRole(homeRole) || '/'
 }: LogoProps) {
   const image = (
     <Image src={imageUrl} style={{ maxHeight: '2rem' }} />

shell/constants.ts

@@ -1 +1,2 @@
+export const homeRole = 'org.openedx.frontend.role.home';
 export const providesChromelessRolesId = 'org.openedx.frontend.provides.chromelessRoles.v1';

shell/dev/devHome/HomePage.tsx

@@ -1,3 +1,4 @@
+import { Container } from '@openedx/paragon';
 import { Link } from 'react-router-dom';
 import { useIntl } from '../../../runtime';
 import { getUrlByRouteRole } from '../../../runtime/routing';
@@ -10,7 +11,7 @@ export default function HomePage() {
   const intl = useIntl();
 
   return (
-    <div className="p-3">
+    <Container fluid size="xl">
       <p>{intl.formatMessage(messages.homeContent)}</p>
       <ul>
         {coursewareUrl !== null && (
@@ -23,6 +24,6 @@ export default function HomePage() {
           <li><Link to={slotShowcaseUrl}>Go to slot showcase page</Link></li>
         )}
       </ul>
-    </div>
+    </Container>
   );
 }

shell/dev/devHome/app.ts

@@ -1,14 +1,15 @@
 import { App } from '../../../types';
+import { homeRole } from '../../constants';
 import HomePage from './HomePage';
 
 const app: App = {
   appId: 'org.openedx.frontend.app.dev.home',
   routes: [{
-    path: '/',
+    path: '/dev',
     id: 'org.openedx.frontend.route.dev.home',
     Component: HomePage,
     handle: {
-      role: 'org.openedx.frontend.role.devHome'
+      roles: [homeRole],
     }
   }],
 };

shell/dev/slotShowcase/SlotShowcasePage.tsx

@@ -27,7 +27,7 @@ function Section({ title, children }: { title: string, children: ReactNode }) {
 
 export default function SlotShowcasePage() {
   return (
-    <Container size="xl" className="showcase-page py-4">
+    <Container fluid size="xl" className="showcase-page py-4">
       <div className="showcase-full-width">
         <h1>Slot Showcase</h1>
         <p>As a best practice, widgets should pass additional props (<code>...props</code>) to their rendered HTMLElement.  This allows custom layouts to add <code>className</code> and <code>style</code> props as necessary for the layout.</p>