From 5109153c9577c6546fa7c20401cefe196601adf6 Mon Sep 17 00:00:00 2001
From: Max Ghenis <mghenis@gmail.com>
Date: Sun, 10 May 2026 17:46:15 -0400
Subject: [PATCH] Add PolicyEngine shell components

---
 changelog.d/policyengine-shell.added.md |   1 +
 src/layout/PolicyEngineFooter.tsx       |  26 ++++++
 src/layout/PolicyEngineHeader.tsx       |  52 ++++++++++++
 src/layout/PolicyEngineShell.tsx        |  39 +++++++++
 src/layout/PolicyEngineSiteConfig.ts    | 102 ++++++++++++++++++++++++
 src/layout/index.ts                     |  21 +++++
 tests/layout/Layout.test.tsx            |  39 +++++++++
 7 files changed, 280 insertions(+)
 create mode 100644 changelog.d/policyengine-shell.added.md
 create mode 100644 src/layout/PolicyEngineFooter.tsx
 create mode 100644 src/layout/PolicyEngineHeader.tsx
 create mode 100644 src/layout/PolicyEngineShell.tsx
 create mode 100644 src/layout/PolicyEngineSiteConfig.ts

diff --git a/changelog.d/policyengine-shell.added.md b/changelog.d/policyengine-shell.added.md
new file mode 100644
index 0000000..c71e9c0
--- /dev/null
+++ b/changelog.d/policyengine-shell.added.md
@@ -0,0 +1 @@
+Add canonical PolicyEngine header, footer, and shell components for child applications.
diff --git a/src/layout/PolicyEngineFooter.tsx b/src/layout/PolicyEngineFooter.tsx
new file mode 100644
index 0000000..bb5add4
--- /dev/null
+++ b/src/layout/PolicyEngineFooter.tsx
@@ -0,0 +1,26 @@
+import { Footer, type FooterProps } from './Footer';
+import {
+  DEFAULT_POLICYENGINE_BASE_URL,
+  getPolicyEngineFooterLinks,
+  type PolicyEngineCountryId,
+} from './PolicyEngineSiteConfig';
+
+export interface PolicyEngineFooterProps extends Omit<FooterProps, 'links'> {
+  country?: PolicyEngineCountryId;
+  baseUrl?: string;
+  links?: FooterProps['links'];
+}
+
+export function PolicyEngineFooter({
+  country = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+  links,
+  ...props
+}: PolicyEngineFooterProps) {
+  return (
+    <Footer
+      links={links ?? getPolicyEngineFooterLinks(country, baseUrl)}
+      {...props}
+    />
+  );
+}
diff --git a/src/layout/PolicyEngineHeader.tsx b/src/layout/PolicyEngineHeader.tsx
new file mode 100644
index 0000000..9f593aa
--- /dev/null
+++ b/src/layout/PolicyEngineHeader.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+import { Header, type CountryConfig, type HeaderProps, type NavItemConfig } from './header';
+import {
+  DEFAULT_POLICYENGINE_BASE_URL,
+  getPolicyEngineCountryUrl,
+  getPolicyEngineNavItems,
+  policyEngineCountries,
+  type PolicyEngineCountryId,
+} from './PolicyEngineSiteConfig';
+
+export interface PolicyEngineHeaderProps
+  extends Omit<
+    HeaderProps,
+    'navItems' | 'countries' | 'currentCountry' | 'logoHref' | 'onCountryChange'
+  > {
+  country?: PolicyEngineCountryId;
+  baseUrl?: string;
+  navItems?: NavItemConfig[];
+  countries?: CountryConfig[];
+  logoHref?: string;
+  onCountryChange?: (id: string) => void;
+}
+
+export function PolicyEngineHeader({
+  country = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+  navItems,
+  countries = policyEngineCountries,
+  logoHref,
+  onCountryChange,
+  ...props
+}: PolicyEngineHeaderProps) {
+  const handleCountryChange =
+    onCountryChange ??
+    ((countryId: string) => {
+      if (typeof window !== 'undefined') {
+        window.location.href = getPolicyEngineCountryUrl(countryId, baseUrl);
+      }
+    });
+
+  return (
+    <Header
+      navItems={navItems ?? getPolicyEngineNavItems(country, baseUrl)}
+      countries={countries}
+      currentCountry={country}
+      logoHref={logoHref ?? getPolicyEngineCountryUrl(country, baseUrl)}
+      onCountryChange={handleCountryChange}
+      {...props}
+    />
+  );
+}
diff --git a/src/layout/PolicyEngineShell.tsx b/src/layout/PolicyEngineShell.tsx
new file mode 100644
index 0000000..f17dc59
--- /dev/null
+++ b/src/layout/PolicyEngineShell.tsx
@@ -0,0 +1,39 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { cn } from '../utils/cn';
+import { PolicyEngineFooter, type PolicyEngineFooterProps } from './PolicyEngineFooter';
+import { PolicyEngineHeader, type PolicyEngineHeaderProps } from './PolicyEngineHeader';
+import { DEFAULT_POLICYENGINE_BASE_URL, type PolicyEngineCountryId } from './PolicyEngineSiteConfig';
+
+export interface PolicyEngineShellProps {
+  children: ReactNode;
+  country?: PolicyEngineCountryId;
+  baseUrl?: string;
+  showFooter?: boolean;
+  headerProps?: Omit<PolicyEngineHeaderProps, 'country' | 'baseUrl'>;
+  footerProps?: Omit<PolicyEngineFooterProps, 'country' | 'baseUrl'>;
+  className?: string;
+  mainClassName?: string;
+}
+
+export function PolicyEngineShell({
+  children,
+  country = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+  showFooter = true,
+  headerProps,
+  footerProps,
+  className,
+  mainClassName,
+}: PolicyEngineShellProps) {
+  return (
+    <div className={cn('min-h-screen flex flex-col', className)}>
+      <PolicyEngineHeader country={country} baseUrl={baseUrl} {...headerProps} />
+      <main className={cn('flex-1', mainClassName)}>{children}</main>
+      {showFooter && (
+        <PolicyEngineFooter country={country} baseUrl={baseUrl} {...footerProps} />
+      )}
+    </div>
+  );
+}
diff --git a/src/layout/PolicyEngineSiteConfig.ts b/src/layout/PolicyEngineSiteConfig.ts
new file mode 100644
index 0000000..43a827d
--- /dev/null
+++ b/src/layout/PolicyEngineSiteConfig.ts
@@ -0,0 +1,102 @@
+import type { CountryConfig, NavItemConfig } from './header';
+import type { FooterProps } from './Footer';
+
+export type PolicyEngineCountryId = 'us' | 'uk' | (string & {});
+
+export const DEFAULT_POLICYENGINE_BASE_URL = 'https://policyengine.org';
+
+export const policyEngineCountries: CountryConfig[] = [
+  { id: 'us', label: 'United States' },
+  { id: 'uk', label: 'United Kingdom' },
+];
+
+function normalizeBaseUrl(baseUrl = DEFAULT_POLICYENGINE_BASE_URL) {
+  return baseUrl.replace(/\/+$/, '');
+}
+
+export function getPolicyEngineCountryUrl(
+  country: PolicyEngineCountryId = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+) {
+  return `${normalizeBaseUrl(baseUrl)}/${country}`;
+}
+
+export function getPolicyEngineUrl(
+  country: PolicyEngineCountryId = 'us',
+  path = '',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+) {
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${getPolicyEngineCountryUrl(country, baseUrl)}${normalizedPath}`;
+}
+
+export function getPolicyEngineNavItems(
+  country: PolicyEngineCountryId = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+): NavItemConfig[] {
+  return [
+    {
+      label: 'Research',
+      href: getPolicyEngineUrl(country, 'research', baseUrl),
+    },
+    {
+      label: 'Model',
+      href: getPolicyEngineUrl(country, 'model', baseUrl),
+    },
+    {
+      label: 'API',
+      href: getPolicyEngineUrl(country, 'api', baseUrl),
+    },
+    {
+      label: 'Python',
+      href: getPolicyEngineUrl(country, 'python', baseUrl),
+    },
+    {
+      label: 'About',
+      href: getPolicyEngineUrl(country, 'team', baseUrl),
+      children: [
+        {
+          label: 'Team',
+          href: getPolicyEngineUrl(country, 'team', baseUrl),
+          description: 'Meet the PolicyEngine team',
+        },
+        {
+          label: 'Supporters',
+          href: getPolicyEngineUrl(country, 'supporters', baseUrl),
+          description: 'Organizations supporting PolicyEngine',
+        },
+        {
+          label: 'Citations',
+          href: getPolicyEngineUrl(country, 'citations', baseUrl),
+          description: 'How to cite PolicyEngine',
+        },
+      ],
+    },
+    {
+      label: 'Donate',
+      href: getPolicyEngineUrl(country, 'donate', baseUrl),
+    },
+  ];
+}
+
+export function getPolicyEngineFooterLinks(
+  country: PolicyEngineCountryId = 'us',
+  baseUrl = DEFAULT_POLICYENGINE_BASE_URL,
+): NonNullable<FooterProps['links']> {
+  return [
+    { text: 'About us', href: getPolicyEngineUrl(country, 'team', baseUrl) },
+    { text: 'Donate', href: getPolicyEngineUrl(country, 'donate', baseUrl) },
+    {
+      text: 'Developer tools',
+      href: getPolicyEngineUrl(country, 'dev-tools', baseUrl),
+    },
+    {
+      text: 'Privacy policy',
+      href: getPolicyEngineUrl(country, 'privacy', baseUrl),
+    },
+    {
+      text: 'Terms and conditions',
+      href: getPolicyEngineUrl(country, 'terms', baseUrl),
+    },
+  ];
+}
diff --git a/src/layout/index.ts b/src/layout/index.ts
index e8ebe71..b845fc8 100644
--- a/src/layout/index.ts
+++ b/src/layout/index.ts
@@ -10,6 +10,27 @@ export { SidebarNavItem, type SidebarNavItemProps } from './SidebarNavItem';
 export { SidebarSection, type SidebarSectionProps } from './SidebarSection';
 export { SidebarDivider } from './SidebarDivider';
 export { Footer, type FooterProps } from './Footer';
+export {
+  PolicyEngineFooter,
+  type PolicyEngineFooterProps,
+} from './PolicyEngineFooter';
+export {
+  PolicyEngineHeader,
+  type PolicyEngineHeaderProps,
+} from './PolicyEngineHeader';
+export {
+  PolicyEngineShell,
+  type PolicyEngineShellProps,
+} from './PolicyEngineShell';
+export {
+  DEFAULT_POLICYENGINE_BASE_URL,
+  getPolicyEngineCountryUrl,
+  getPolicyEngineFooterLinks,
+  getPolicyEngineNavItems,
+  getPolicyEngineUrl,
+  policyEngineCountries,
+  type PolicyEngineCountryId,
+} from './PolicyEngineSiteConfig';
 export {
   Header,
   type HeaderProps,
diff --git a/tests/layout/Layout.test.tsx b/tests/layout/Layout.test.tsx
index 09b6e7c..d1ba6c5 100644
--- a/tests/layout/Layout.test.tsx
+++ b/tests/layout/Layout.test.tsx
@@ -5,6 +5,12 @@ import { SidebarLayout } from '../../src/layout/SidebarLayout';
 import { SingleColumnLayout } from '../../src/layout/SingleColumnLayout';
 import { Header } from '../../src/layout/header';
 import { InputPanel } from '../../src/layout/InputPanel';
+import {
+  getPolicyEngineNavItems,
+  PolicyEngineFooter,
+  PolicyEngineHeader,
+  PolicyEngineShell,
+} from '../../src/layout';
 import { ResultsPanel } from '../../src/layout/ResultsPanel';
 
 describe('DashboardShell', () => {
@@ -44,6 +50,39 @@ describe('Header', () => {
   });
 });
 
+describe('PolicyEngine shell components', () => {
+  it('builds country-aware navigation URLs', () => {
+    const navItems = getPolicyEngineNavItems('uk');
+
+    expect(navItems).toContainEqual({
+      label: 'API',
+      href: 'https://policyengine.org/uk/api',
+    });
+  });
+
+  it('renders the canonical PolicyEngine header', () => {
+    render(<PolicyEngineHeader country="uk" />);
+
+    expect(screen.getAllByText('Research').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('Model').length).toBeGreaterThan(0);
+    expect(screen.getAllByText('API').length).toBeGreaterThan(0);
+  });
+
+  it('renders the canonical PolicyEngine footer', () => {
+    render(<PolicyEngineFooter country="us" />);
+
+    expect(screen.getByText('Privacy policy')).toBeInTheDocument();
+    expect(screen.getByText(/PolicyEngine/)).toBeInTheDocument();
+  });
+
+  it('wraps app content with the canonical PolicyEngine shell', () => {
+    render(<PolicyEngineShell country="us">Tool content</PolicyEngineShell>);
+
+    expect(screen.getByText('Tool content')).toBeInTheDocument();
+    expect(screen.getAllByText('Donate').length).toBeGreaterThan(0);
+  });
+});
+
 describe('InputPanel', () => {
   it('renders title and children', () => {
     render(<InputPanel title="Settings">Fields</InputPanel>);