@the-portland-company/shell 0.3.1 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.4 — 2026-05-14
+
+### Fixed
+
+- `package.json` `exports` for `./css` and `./chrome.css` now ship a `types` entry pointing at a tiny ambient module declaration (`dist/css-modules.d.ts`). Fixes TS2882 errors in fresh consumers importing the side-effect CSS subpaths.
+
+### Documentation
+
+- README install command now pins peer-dep versions explicitly (`react@^18`, `@chakra-ui/react@^2.8`, etc.) so Vite-scaffolded apps on React 19 / Chakra v3 don't silently install incompatible versions.
+- Clarified `@the-portland-company/devnotes` is optional.
+
+## 0.3.3 — 2026-05-14
+
+### Documentation
+
+- Rewrote `README.md` to cover the v0.3.x chrome contract: every component / hook / helper / type, the `<ShellChrome>` binding pattern with a copy-pasteable bridge example, the `chrome.css` + `css` import paths, multi-SPA routing notes for the politogy edge router, and a pointer to `politogy-vrm/react/app/src/providers/ShellChromeBridge.tsx` as the reference implementation. No code changes.
+
+## 0.3.2 — 2026-05-13
+
+### Added
+
+- `<ShellChrome userAvatarUrl />` (and matching `<ShellProvider userAvatarUrl />` prop) — app-supplied avatar URL override for the header `<UserMenu />` avatar. When provided, takes precedence over the avatar URL on the Supabase session's `user_metadata.avatar_url`.
+
+### Fixed
+
+- `<UserMenu />` was rendering only `user.raw.user_metadata.avatar_url`, which missed app-specific avatar sources like `profile.avatar_url`, memoji selections persisted to localStorage, and branded default URLs. Apps with these fallback chains were seeing the initials placeholder instead of the user's portrait. Pass the resolved URL via `userAvatarUrl` to restore parity with the legacy chrome.
+
 ## 0.3.1 — 2026-05-13
 
 Closes the last two visual gaps in the shell-v3 chrome vs production.

package/README.md

@@ -2,47 +2,203 @@
 
 Shared chrome for politogy apps. One install, one wrapper, identical look.
 
+Every politogy product (Email Blast, Contacts, Forms, future apps…) installs this package and gets the full branded experience — sidebar with VRM logo, organization switcher, mode selector, full nav list, header with notifications and support, branded footer with commit info — without rebuilding any of it. Path-based routing lets multiple separately-deployed Vite SPAs feel like a single continuous app on `app.politogy.com`.
+
+> **v0.3.x is a major rewrite.** See the [CHANGELOG](./CHANGELOG.md) for the chrome component, hook, and prop additions over v0.2.x. The minimum viable boot below works for new apps; existing v0.2.x consumers can keep using `OrgSelector`, `useShellAuth`, etc. without changes.
+
+---
+
 ## Install
 
+Pin peer dep versions explicitly — Vite scaffolds React 19 + Chakra v3 by default, neither of which the shell supports:
+
+```bash
+npm install @the-portland-company/shell \
+            react@^18 react-dom@^18 \
+            @chakra-ui/react@^2.8 @emotion/react@^11 @emotion/styled@^11 \
+            framer-motion@^11 \
+            @supabase/supabase-js@~2.95 \
+            react-router-dom@^6 react-icons@^5
 ```
-npm install @the-portland-company/shell @chakra-ui/react @emotion/react @emotion/styled @supabase/supabase-js react react-dom
-```
 
-## Quick start
+`@the-portland-company/devnotes` is **optional** — only needed if you want the dev-notes menu in the header. Skip it if your app doesn't use it.
+
+---
+
+## Minimum viable boot
+
+The simplest possible startup renders the branded chrome with empty defaults — the sidebar appears, the header renders, but the org switcher / mode selector / nav list show "no data" states until you wire them up via `<ShellChrome>` (next section).
 
 ```tsx
-import { ShellProvider, AppLayout, registerShellPrecache } from '@the-portland-company/shell'
-import '@the-portland-company/shell/css'
+// src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import { ShellProvider, AppLayout } from '@the-portland-company/shell'
+import '@the-portland-company/shell/chrome.css'
+import { createClient } from '@supabase/supabase-js'
+import App from './App'
+
+const supabase = createClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_ANON_KEY,
+)
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <ShellProvider currentApp="email" supabaseClient={supabase}>
+    <BrowserRouter>
+      <AppLayout>
+        <App />
+      </AppLayout>
+    </BrowserRouter>
+  </ShellProvider>,
+)
+```
 
-registerShellPrecache().catch(() => {})
+`<AppLayout>` composes the shell `<Header>`, `<Sidebar>`, your routed content, and `<Footer>`. `<ShellProvider>` owns the Supabase auth lifecycle and exposes `useShellAuth()` for status / user / sign-out.
 
-const APPS = [
-  { id: 'crm', label: 'CRM', path: '/' },
-  { id: 'messaging', label: 'Messaging', path: '/messaging' },
-]
+---
 
-export default function App() {
+## Real-world boot: feeding the chrome real data
+
+Most apps have an `<AuthProvider>`, `<OrganizationProvider>`, `<ModeProvider>`, etc. that live *below* `<ShellProvider>` in the tree. To push their data up into the shell's chrome contexts, drop a `<ShellChrome>` binding component as deep in the tree as the data is available:
+
+```tsx
+import {
+  ShellProvider,
+  ShellChrome,
+  AppLayout,
+} from '@the-portland-company/shell'
+
+function ChromeBridge({ children }) {
+  const { currentMode, switchMode, getModeConfig, getAvailableModes } = useMode()
+  const { currentOrg, organizations, switchOrganization } = useOrganization()
+  const { linkedAccounts, ... } = useLinkedAccounts()
+  // …compute the nav-items list for the active mode here…
   return (
-    <ShellProvider currentApp="crm" supabaseClient={supabase} appRegistry={APPS}>
-      <AppLayout>{/* your routes */}</AppLayout>
-    </ShellProvider>
+    <ShellChrome
+      mode={{ currentMode, modes: getAvailableModes(), switchMode, getModeConfig }}
+      organization={{ currentOrg, organizations, switchOrganization }}
+      linkedAccounts={{ linkedAccounts, switchToAccount, onAddAccount, onRemoveAccount }}
+      navItems={navItems}
+      role={{ activeRoleConfig, isSuperAdmin }}
+      footer={{ links, commit, version, releaseName, environmentLabel }}
+      support={{ submitSupportRequest }}
+      brandLogoSrc="/brand/logos/email-mode-logo.png"
+      headerIconsSlot={<MyAppSpecificIcons />}
+      userAvatarUrl={profile.avatar_url ?? storedMemojiUrl ?? defaultAvatarUrl}
+      myProfileHref="/my-profile"
+      organizationSettingsHref={`/organization-settings?org=${currentOrg.id}`}
+    >
+      {children}
+    </ShellChrome>
   )
 }
+
+// Then in main.tsx:
+<ShellProvider currentApp="email" supabaseClient={supabase}>
+  <BrowserRouter>
+    <AuthProvider>
+      <OrganizationProvider>
+        <ModeProvider>
+          <ChromeBridge>
+            <AppLayout>
+              <Routes>…</Routes>
+            </AppLayout>
+          </ChromeBridge>
+        </ModeProvider>
+      </OrganizationProvider>
+    </AuthProvider>
+  </BrowserRouter>
+</ShellProvider>
 ```
 
-## Slot props on `<AppLayout>`
+**Reference implementation:** `politogy-vrm`'s `react/app/src/providers/ShellChromeBridge.tsx` (~600 lines, every chrome wiring pattern). Copy as a starting point for new apps.
+
+All `<ShellChrome>` props are optional — only supply what your app has. The chrome gracefully omits the bits it doesn't get data for (e.g., no `support` prop → no support icon rendered).
+
+---
+
+## What the shell exports
+
+### Components
+
+| Export | Use |
+|---|---|
+| `<ShellProvider>` | Top-level provider. Wraps Chakra + auth + meta contexts. |
+| `<ShellChrome>` | Mid-tree binding component. Feeds chrome contexts from app data. |
+| `<AppLayout>` | Composes Header + Sidebar + main content + Footer. |
+| `<Header>` | Header bar (logo, page title, breadcrumbs, icon stack, user menu). |
+| `<Sidebar>` | Sidebar (branded logo, org pill, mode pill, nav list, footer). |
+| `<Footer>` | Below main content. Usually not rendered separately. |
+| `<UserMenu>` | Avatar dropdown (profile, theme, sign out, switch account). |
+| `<OrgPill>` (alias `<OrgSelector>`) | Organization switcher pill rendered in the sidebar. |
+| `<ModePill>` | Mode (Relationship / Campaign / Petition) switcher. |
+| `<NavItem>` | Single sidebar nav row with active state + hover gradient. |
+| `<SupportRequestButton>` | Header life-buoy icon that opens a support modal. |
+| `<BrandLogo>` | `<img>` wrapper for the branded mode logo. |
+| `<BrandIcon name="...">` | Renders `/brand/icons/<name>.svg` from your `public/`. |
+| `<CommitCopyButton>` | Footer commit/version display with copy-to-clipboard. |
+| `<Card>`, `<PageContainer>`, `<PageHeader>`, `<BreadcrumbBar>`, `<HeaderTabBar>` | Page-level layout primitives. |
+| `<GlobalUiIdProvider>` | Assigns stable UI IDs (for testing/analytics). |
+
+### Hooks
+
+| Hook | Returns |
+|---|---|
+| `useShellAuth()` | `{ status, user, session, signOut }` |
+| `useShellOrganization()` | `{ currentOrg, organizations, switchOrganization, createOrgHref } \| null` |
+| `useShellMode()` | `{ currentMode, modes, switchMode, getModeConfig } \| null` |
+| `useShellNavItems()` | `{ items: ShellNavItem[] } \| null` |
+| `useShellLinkedAccounts()` | `{ linkedAccounts, switchToAccount, onAddAccount, onRemoveAccount } \| null` |
+| `useShellSupport()` | `{ submitSupportRequest } \| null` |
+| `useShellRole()` | `{ activeRoleConfig, isSuperAdmin } \| null` |
+| `useShellFooter()` | `{ links, version, commit, releaseName, … } \| null` |
+| `useShellNavigationPreference()` | `{ showSubMenu } \| null` |
+| `useShellChrome()` | Chrome configuration (`devNotesMenu`, `myProfileHref`, `userAvatarUrl`, `pageTitle`, `breadcrumbs`, `headerActions`, etc.) |
+| `useAppRegistry()`, `useCurrentApp()` | App switcher metadata for cross-app speculation rules. |
+
+### Helpers
 
-| Prop | Position | Use for |
-|---|---|---|
-| `headerExtrasSlot` | Right of header, before user menu | App-specific header widgets |
-| `modalsSlot` | Above main content, position absolute | Modal dialogs |
-| `notificationsSlot` | Inside main, top-right | Toasts, badges |
-| `sidebarFooterSlot` | Bottom of sidebar | Org switcher, status |
-| `overlaySlot` | Top of everything | Always-on-top indicators |
+`normalizeHexColor`, `lightenHexColor`, `hexToRgba`, `getOrganizationBrandColor`, `getOrganizationBadgeLetters`, `getUserDisplayName`.
 
-## Service worker
+### Theme
 
-The package ships a precache SW. Copy it into your `public/` dir during postinstall:
+`politogyTheme` — Chakra theme with brand palette, mode-aware semantic tokens, and component overrides.
+
+---
+
+## CSS imports
+
+```tsx
+import '@the-portland-company/shell/chrome.css'      // :root design tokens (--app-color-brand-*, --mode-*, --app-tab-*, --form-control-*)
+import '@the-portland-company/shell/css'             // view-transitions CSS for cross-app polish
+```
+
+`chrome.css` is required for theme variables. `css` (view-transitions) is optional polish.
+
+---
+
+## Multi-SPA routing on `app.politogy.com`
+
+Multiple politogy apps live behind one domain via a Cloudflare Worker edge router (in `packages/edge-router` of the monorepo).
+
+When you deploy a new app to Cloudflare Pages, add its path prefix to the edge router's `routes.ts`:
+
+```ts
+{
+  pathPrefix: '/email',
+  origin: 'https://politogy-email.pages.dev',
+}
+```
+
+After deploy, users hitting `app.politogy.com/email/*` get transparently proxied to your app. Other paths keep going to whichever app owns them. The shared shell + same Supabase session means it feels like one app.
+
+---
+
+## Service worker (optional polish)
+
+The package ships a precache service worker that caches the shell chrome on first visit so cross-app navigation feels instant.
 
 ```js
 // scripts/copy-shell-sw.mjs
@@ -53,11 +209,13 @@ await copyFile(
 )
 ```
 
-Then call `registerShellPrecache()` at the top of your app.
+Wire it into your build (`"postinstall": "node scripts/copy-shell-sw.mjs"`) and call `registerShellPrecache()` once on app boot.
+
+---
 
-## Speculation Rules
+## Speculation Rules (optional polish)
 
-Emit cross-app prerendering hints:
+Cross-app prerendering hints for the browser:
 
 ```tsx
 import { useAppRegistry, useCurrentApp, buildSpeculationRules } from '@the-portland-company/shell'
@@ -70,3 +228,16 @@ function SpeculationRules() {
   return <script type="speculationrules" dangerouslySetInnerHTML={{ __html: json }} />
 }
 ```
+
+Render once near the app root.
+
+---
+
+## Reference + support
+
+- **Reference bridge:** `politogy-vrm/react/app/src/providers/ShellChromeBridge.tsx` — full chrome wiring for the main politogy app.
+- **Architectural decisions, gotchas, session log:** `politogy-vrm/docs/superpowers/`.
+- **Type definitions:** `node_modules/@the-portland-company/shell/dist/index.d.ts` — every prop and hook is fully typed.
+- **CHANGELOG:** [CHANGELOG.md](./CHANGELOG.md) — every export added per version.
+
+Questions or missing features: file an issue or ping the politogy team.

package/dist/css-modules.d.ts

@@ -0,0 +1,6 @@
+// Side-effect type declarations for the CSS subpath exports so TS consumers
+// can `import '@the-portland-company/shell/css'` and
+// `import '@the-portland-company/shell/chrome.css'` without ambient-shim
+// boilerplate.
+declare module '@the-portland-company/shell/css'
+declare module '@the-portland-company/shell/chrome.css'

package/dist/index.cjs

@@ -1153,7 +1153,8 @@ function ShellProvider({
   linkedAccounts,
   support,
   devNotesMenu,
-  myProfileHref
+  myProfileHref,
+  userAvatarUrl
 }) {
   const [status, setStatus] = react$1.useState("loading");
   const [session, setSession] = react$1.useState(null);
@@ -1195,9 +1196,10 @@ function ShellProvider({
   const chrome = react$1.useMemo(
     () => ({
       devNotesMenu: devNotesMenu ?? null,
-      myProfileHref: myProfileHref ?? "/my-profile"
+      myProfileHref: myProfileHref ?? "/my-profile",
+      userAvatarUrl
     }),
-    [devNotesMenu, myProfileHref]
+    [devNotesMenu, myProfileHref, userAvatarUrl]
   );
   return /* @__PURE__ */ jsxRuntime.jsx(ShellAuthContext.Provider, { value, children: /* @__PURE__ */ jsxRuntime.jsx(ShellMetaContext.Provider, { value: meta, children: /* @__PURE__ */ jsxRuntime.jsx(ShellOrgContext.Provider, { value: organization ?? null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellLinkedAccountsContext.Provider, { value: linkedAccounts ?? null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellSupportProviderContext.Provider, { value: support ?? null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellModeContext.Provider, { value: null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellNavItemsContext.Provider, { value: null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellNavigationPreferenceContext.Provider, { value: null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellRoleContext.Provider, { value: null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellFooterContext.Provider, { value: null, children: /* @__PURE__ */ jsxRuntime.jsx(ShellChromeContext.Provider, { value: chrome, children: /* @__PURE__ */ jsxRuntime.jsx(react.ChakraProvider, { theme: politogyTheme, children }) }) }) }) }) }) }) }) }) }) }) });
 }
@@ -1284,7 +1286,8 @@ function UserMenu() {
     myProfileHref,
     organizationSettingsHref,
     showContinueOnboarding,
-    onContinueOnboarding
+    onContinueOnboarding,
+    userAvatarUrl
   } = useShellChrome();
   const linked = useShellLinkedAccounts();
   const mode = useShellMode();
@@ -1295,7 +1298,7 @@ function UserMenu() {
   const menuListBorderColor = react.useColorModeValue("gray.200", "gray.700");
   if (status !== "authenticated" || !user) return null;
   const displayName = getUserDisplayName(user.raw);
-  const avatarUrl = avatarUrlFromUser(user);
+  const avatarUrl = userAvatarUrl ?? avatarUrlFromUser(user);
   const modeConfig = mode?.getModeConfig() ?? null;
   const currentOrg = org?.currentOrg ?? null;
   const linkedAccounts = linked?.linkedAccounts ?? [];
@@ -2911,7 +2914,8 @@ function ShellChrome({
   onContinueOnboarding,
   pageTitle,
   breadcrumbs,
-  headerActions
+  headerActions,
+  userAvatarUrl
 }) {
   const chrome = react$1.useMemo(
     () => ({
@@ -2924,7 +2928,8 @@ function ShellChrome({
       onContinueOnboarding,
       pageTitle,
       breadcrumbs,
-      headerActions
+      headerActions,
+      userAvatarUrl
     }),
     [
       devNotesMenu,
@@ -2936,7 +2941,8 @@ function ShellChrome({
       onContinueOnboarding,
       pageTitle,
       breadcrumbs,
-      headerActions
+      headerActions,
+      userAvatarUrl
     ]
   );
   const navItemsValue = react$1.useMemo(