@the-portland-company/shell 0.2.1 → 0.3.1

package/dist/index.d.cts

@@ -101,8 +101,13 @@ interface AppRegistryEntry {
  * fuel/modal/notification components into the relevant slots.
  */
 interface ShellSlots {
-    /** Right side of the header (next to user menu). */
-    headerExtrasSlot?: ReactNode;
+    /**
+     * Right side of the header — rendered in the icon row of the header (next
+     * to user menu). Used by the legacy app to mount FuelPopover,
+     * NewTextBellPopup, SystemAlertsMenu, NavigationToggleMenu, and
+     * ImportProgressIndicator. Replaces the older `headerExtrasSlot`.
+     */
+    headerIconsSlot?: ReactNode;
     /** Modal layer rendered above everything (positioned absolute). */
     modalsSlot?: ReactNode;
     /** Notifications layer (toasts, popovers, badges). */
@@ -112,6 +117,138 @@ interface ShellSlots {
     /** Overlay always-on-top components (e.g., import progress indicator). */
     overlaySlot?: ReactNode;
 }
+/** ---------------- Mode ---------------- */
+/**
+ * Per-mode visual / display config supplied by the app. Mirrors the legacy
+ * `MODE_CONFIG[mode]` shape from `react/app/src/contexts/ModeContext.tsx`.
+ *
+ * `icon` is an already-resolved ReactNode (e.g., <FiUsers />) so the shell
+ * doesn't need to know about react-icons. `iconName` is kept around as an
+ * informational string for tooling that wants to look up the icon component
+ * by name.
+ */
+interface ShellModeConfig {
+    /** Stable mode identifier, e.g., 'relationship'. */
+    id: string;
+    /** Display name, e.g., 'Relationship Mode'. */
+    name: string;
+    /** Mode primary color (hex). */
+    primaryColor: string;
+    /** Mode accent color (hex). */
+    accentColor: string;
+    /** Mode background color (hex). */
+    bgColor: string;
+    /** Mode secondary color (hex) — typically muted text. */
+    secondaryColor: string;
+    /** Mode white color (hex), usually '#FFFFFF'. */
+    white: string;
+    /** Pre-resolved icon element for the mode pill leftIcon. */
+    icon?: ReactNode;
+    /** Informational icon name (for debugging or tooling). */
+    iconName?: string;
+}
+interface ShellModeValue {
+    /** Current mode id, e.g., 'relationship'. */
+    currentMode: string;
+    /** All available modes for the current org/user. */
+    modes: ShellModeConfig[];
+    /** Switch to a different mode. App owns side effects. */
+    switchMode: (modeId: string) => void;
+    /** Returns the config for the current mode (convenience). */
+    getModeConfig: () => ShellModeConfig;
+}
+/** ---------------- Nav items ---------------- */
+/**
+ * One sidebar nav item. Apps build this list themselves (via
+ * `getLinkItemsForMode` + `applySidebarChildAccessState` etc.) and pass it
+ * through to <ShellChrome navItems={...}>. The shell renders the rows.
+ */
+interface ShellNavItem {
+    name: string;
+    /** A react-icons component (e.g., FiHome). Either icon or brandIcon set. */
+    icon?: unknown;
+    /** Brand-icon name keyed off `/brand/icons/<name>.svg`. */
+    brandIcon?: string;
+    /** Route the row navigates to. */
+    href?: string;
+    /** Nested rows. Renders an accordion when set. */
+    children?: ShellNavItem[];
+    /** Small badge shown next to the label (e.g., 'In Development'). */
+    badge?: string;
+    /** Secondary label rendered below the main label. */
+    subLabel?: string;
+    /** When true, the row is rendered disabled/non-interactive. */
+    disabled?: boolean;
+    /** Optional click handler (overrides href). */
+    action?: () => void;
+}
+interface ShellNavItemsValue {
+    items: ShellNavItem[];
+}
+/** ---------------- Nav preference ---------------- */
+/**
+ * User preference for nav rendering — whether sub-menus (accordion children)
+ * are shown in the sidebar.
+ */
+interface ShellNavigationPreferenceValue {
+    showSubMenu: boolean;
+}
+/** ---------------- Role ---------------- */
+/**
+ * Active-role display info for the user-menu role badge. App supplies the
+ * resolved values; shell renders the badge.
+ */
+interface ShellActiveRoleConfig {
+    name: string;
+    color: string;
+}
+interface ShellRoleValue {
+    activeRoleConfig: ShellActiveRoleConfig | null;
+    isSuperAdmin: boolean;
+}
+/** ---------------- Footer ---------------- */
+interface ShellFooterLink {
+    label: string;
+    href: string;
+    /** When true, the link opens in a new tab (target='_blank'). */
+    external?: boolean;
+}
+/**
+ * Footer / sidebar-footer data shipped from the app. The legacy footer
+ * row shows Privacy / Terms / Subscriptions links plus a CommitCopyButton
+ * with version + commit metadata. All fields are optional so apps can
+ * supply only what they have.
+ */
+interface ShellFooterValue {
+    links: ShellFooterLink[];
+    commit?: string;
+    commitFull?: string;
+    commitDate?: string;
+    commitAuthor?: string;
+    commitLog?: string;
+    version?: string;
+    releaseName?: string;
+    /**
+     * Environment label rendered as a colored chip in the sidebar
+     * footer (e.g., 'production' = red, 'staging' = orange,
+     * 'local'/'development' = green).
+     */
+    environmentLabel?: string;
+    /**
+     * Optional pre-rendered environment chip element. When supplied,
+     * <CommitCopyButton> renders this instead of building a default chip
+     * from `environmentLabel`. Use this when the app already has an
+     * <EnvironmentBanner> component it wants to drop in unchanged.
+     */
+    envNode?: ReactNode;
+    /**
+     * When set, <CommitCopyButton> renders a diagnostics icon next to
+     * the version that, when clicked, fires this handler. The shell
+     * does not navigate or open anything — apps wire whatever they want
+     * (modal, route, console dump).
+     */
+    onDiagnosticsClick?: () => void;
+}
 /** Props for the top-level ShellProvider. */
 interface ShellProviderProps {
     children: ReactNode;
@@ -123,11 +260,11 @@ interface ShellProviderProps {
     appRegistry?: AppRegistryEntry[];
     /** Optional override for the base path if the app is mounted under a sub-path (e.g., '/contacts'). */
     basename?: string;
-    /** If provided, shell renders <OrgSelector /> in the header. */
+    /** If provided, shell renders <OrgPill /> in the sidebar. */
     organization?: ShellOrganizationValue;
     /** If provided, UserMenu shows account switcher + add-account button. */
     linkedAccounts?: ShellLinkedAccountsValue;
-    /** If provided, shell renders <SupportRequestButton /> in the header. */
+    /** Drives the modal submission flow used by app-supplied support widgets. */
     support?: ShellSupportValue;
     /** Optional element rendered in the header (typically <DevNotesMenu /> from @the-portland-company/devnotes). */
     devNotesMenu?: ReactNode;
@@ -143,7 +280,7 @@ interface ShellAuthValue {
 }
 /**
  * Organization that the current user belongs to. Apps supply this via
- * ShellProvider so the shell can render <OrgSelector /> in the header.
+ * ShellProvider so the shell can render <OrgPill /> in the sidebar.
  */
 interface ShellOrganization {
     id: string;
@@ -151,6 +288,8 @@ interface ShellOrganization {
     logoUrl?: string | null;
     /** Brand color as a hex string (e.g., '#0066cc'). Used for the org badge fallback. */
     brandColor?: string | null;
+    /** Optional user-facing role label in this organization ('owner' | 'admin' | etc.). */
+    role?: string | null;
 }
 interface ShellOrganizationValue {
     currentOrg: ShellOrganization | null;
@@ -160,6 +299,8 @@ interface ShellOrganizationValue {
     switchOrganization: (orgId: string) => Promise<void> | void;
     /** Optional link rendered at the bottom of the org menu, e.g., '/organizations/new'. */
     createOrgHref?: string;
+    /** True while the app is still resolving the org list (renders a skeleton). */
+    loadingOrgs?: boolean;
 }
 /**
  * An alternate user account the current user can switch into without signing
@@ -202,11 +343,27 @@ interface ShellSupportValue {
 declare const ShellOrgContext: react.Context<ShellOrganizationValue | null>;
 declare const ShellLinkedAccountsContext: react.Context<ShellLinkedAccountsValue | null>;
 declare const ShellSupportProviderContext: react.Context<ShellSupportValue | null>;
-interface ShellChromeValue$1 {
+declare const ShellModeContext: react.Context<ShellModeValue | null>;
+declare const ShellNavItemsContext: react.Context<ShellNavItemsValue | null>;
+declare const ShellNavigationPreferenceContext: react.Context<ShellNavigationPreferenceValue | null>;
+declare const ShellRoleContext: react.Context<ShellRoleValue | null>;
+declare const ShellFooterContext: react.Context<ShellFooterValue | null>;
+interface ShellChromeValue {
     devNotesMenu: ReactNode | null;
     myProfileHref: string;
+    brandLogoSrc?: string;
+    headerIconsSlot?: ReactNode;
+    organizationSettingsHref?: string;
+    showContinueOnboarding?: boolean;
+    onContinueOnboarding?: () => void;
+    pageTitle?: string;
+    breadcrumbs?: Array<{
+        label: string;
+        href?: string;
+    }>;
+    headerActions?: ReactNode;
 }
-declare const ShellChromeContext: react.Context<ShellChromeValue$1 | null>;
+declare const ShellChromeContext: react.Context<ShellChromeValue | null>;
 declare function ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, organization, linkedAccounts, support, devNotesMenu, myProfileHref, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useShellAuth(): ShellAuthValue;
@@ -234,33 +391,108 @@ declare function useShellLinkedAccounts(): ShellLinkedAccountsValue | null;
  */
 declare function useShellSupport(): ShellSupportValue | null;
 
-interface ShellChromeValue {
-    devNotesMenu: ReactNode | null;
-    myProfileHref: string;
-}
 /**
- * Returns chrome-level options supplied to ShellProvider (devNotesMenu slot,
- * myProfileHref). Throws if used outside <ShellProvider>.
+ * Returns chrome-level options supplied to ShellProvider/ShellChrome
+ * (devNotesMenu slot, myProfileHref, header data, brand logo src, etc.).
+ * Throws if used outside <ShellProvider>.
  */
 declare function useShellChrome(): ShellChromeValue;
 
+/**
+ * Returns the mode value supplied to ShellProvider/ShellChrome, or null if
+ * the host app didn't pass a `mode` prop. Components like <ModePill /> use
+ * this to conditionally render.
+ */
+declare function useShellMode(): ShellModeValue | null;
+
+/**
+ * Returns the nav items value supplied to ShellChrome, or null if the host
+ * app didn't pass a `navItems` prop. The sidebar uses this to decide what
+ * rows to render.
+ */
+declare function useShellNavItems(): ShellNavItemsValue | null;
+
+/**
+ * Returns the user's navigation rendering preference supplied to
+ * ShellChrome, or null if not provided. NavItem uses this to decide
+ * whether to expand sub-menus.
+ */
+declare function useShellNavigationPreference(): ShellNavigationPreferenceValue | null;
+
+/**
+ * Returns the active-role info supplied to ShellChrome, or null if not
+ * provided. UserMenu uses this to render the ROLES & ORGANIZATIONS badge.
+ */
+declare function useShellRole(): ShellRoleValue | null;
+
+/**
+ * Returns the footer data supplied to ShellChrome (links, commit/version
+ * info), or null if not provided. The Sidebar footer reads this to render
+ * Privacy / Terms / Subscriptions + commit copy button.
+ */
+declare function useShellFooter(): ShellFooterValue | null;
+
 interface AppLayoutProps extends ShellSlots {
     children: ReactNode;
     buildInfo?: string;
 }
-declare function AppLayout({ children, buildInfo, headerExtrasSlot, modalsSlot, notificationsSlot, sidebarFooterSlot, overlaySlot, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
+/**
+ * Authenticated app shell composition: <Sidebar> on the left, <Header> on
+ * top, <main> for routed children, optional <Footer>, plus modal + overlay
+ * slots. All chrome data flows through ShellProvider/ShellChrome contexts —
+ * AppLayout itself takes only optional slots for modals/overlays/notifs.
+ */
+declare function AppLayout({ children, buildInfo, modalsSlot, notificationsSlot, overlaySlot, }: AppLayoutProps): react_jsx_runtime.JSX.Element;
 
 interface HeaderProps {
-    extrasSlot?: ReactNode;
+    /** Mobile menu open handler (renders the hamburger icon on mobile). */
+    onOpen?: () => void;
+    /** DOM id (defaults to 'mobile-nav-container'). */
+    id?: string;
 }
-declare function Header({ extrasSlot }: HeaderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Politogy header (top bar). Ported from
+ * react/app/src/layouts/AuthenticatedLayout.tsx lines 2545–2924 (2026-05-13).
+ *
+ * Composition (left → right):
+ *  1. Hamburger (mobile only) + small brand logo (mobile only) + title +
+ *     breadcrumbs.
+ *  2. headerActions (app-supplied React node, e.g., page action buttons).
+ *  3. headerIconsSlot (app-supplied React node, e.g., FuelPopover,
+ *     NewTextBellPopup, SystemAlertsMenu, NavigationToggleMenu,
+ *     ImportProgressIndicator, DevNotesMenu, SupportRequestAction).
+ *  4. UserMenu (avatar + name/email VStack + chevron).
+ *
+ * NOTE: app-specific widgets stay in the app. The shell only renders
+ * what the app passes through `headerActions` + `headerIconsSlot`. As of
+ * v0.3.1, the shell no longer renders a separate `devNotesMenu` slot
+ * after `headerIconsSlot` — apps must inline DevNotesMenu inside
+ * `headerIconsSlot` so they have full control of icon ordering. The
+ * `devNotesMenu` prop on <ShellChrome> is still accepted for backward
+ * compat but is ignored.
+ */
+declare function Header({ onOpen, id }: HeaderProps): react_jsx_runtime.JSX.Element;
 
 interface SidebarProps {
-    entries: AppRegistryEntry[];
-    currentApp: string;
-    footerSlot?: ReactNode;
+    /** Mobile close handler (renders the X button on mobile when set). */
+    onClose?: () => void;
+    /** DOM id for the sidebar root (defaults to 'sidebar-container'). */
+    id?: string;
 }
-declare function Sidebar({ entries, currentApp, footerSlot }: SidebarProps): react_jsx_runtime.JSX.Element;
+/**
+ * Politogy sidebar. Ported from
+ * react/app/src/layouts/AuthenticatedLayout.tsx lines 3289–4192 (2026-05-13)
+ * but stripped of the AI-sidebar block (moved to app's navItems pipeline).
+ *
+ * Renders, top to bottom:
+ *  - Brand logo + (mobile) close button
+ *  - Org logo (large) if present
+ *  - <OrgPill /> — organization switcher
+ *  - <ModePill /> — mode switcher
+ *  - Nav items (from useShellNavItems)
+ *  - Footer (Privacy / Terms / Subscriptions links + commit/version display)
+ */
+declare function Sidebar({ onClose, id }: SidebarProps): react_jsx_runtime.JSX.Element;
 
 interface FooterProps {
     buildInfo?: string;
@@ -268,17 +500,111 @@ interface FooterProps {
 declare function Footer({ buildInfo }: FooterProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Avatar dropdown rendered at the right side of the header. Reads auth,
- * linked-accounts, and chrome context from ShellProvider.
+ * Avatar dropdown rendered on the right of the header. Ported to match the
+ * legacy menu in react/app/src/layouts/AuthenticatedLayout.tsx lines
+ * 2680–2898 (2026-05-13).
+ *
+ * Sections (in order):
+ * 1. Trigger — avatar + name/email VStack + chevron (md+ only).
+ * 2. My Profile / Continue Onboarding (gated) / Organization Settings.
+ * 3. ROLES & ORGANIZATIONS — current-org role Badge OR activeRoleConfig.
+ * 4. ACCOUNTS — current account indicator + linkedAccounts list with
+ *    inline FiTrash2 remove + "Add Account" item.
+ * 5. Sign out.
  */
 declare function UserMenu(): react_jsx_runtime.JSX.Element | null;
 
 /**
- * Organization switcher rendered in the header. Reads from
- * useShellOrganization(); renders nothing when no `organization` prop was
- * supplied to ShellProvider.
+ * Sidebar organization switcher pill. Ported from
+ * react/app/src/layouts/AuthenticatedLayout.tsx lines 3795–3957 (2026-05-13).
+ *
+ * Reads useShellOrganization + useShellAuth. Renders nothing when there's
+ * no organization context.
+ */
+declare function OrgPill(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Sidebar mode selector pill. Ported from
+ * react/app/src/layouts/AuthenticatedLayout.tsx lines 3959–4006 (2026-05-13).
+ *
+ * Reads useShellMode. Renders nothing when no mode context is supplied or
+ * when the app has only one mode available.
+ */
+declare function ModePill(): react_jsx_runtime.JSX.Element | null;
+
+interface NavItemSubItem {
+    name: string;
+    icon?: unknown;
+    brandIcon?: string;
+    href?: string;
+    badge?: string;
+    subLabel?: string;
+    disabled?: boolean;
+}
+interface NavItemProps {
+    icon?: unknown;
+    brandIcon?: string;
+    children: ReactNode;
+    href?: string;
+    action?: () => void;
+    subItems?: NavItemSubItem[];
+    badge?: string;
+    subLabel?: string;
+    isSubItem?: boolean;
+    isExpanded?: boolean;
+    onToggle?: (menuKey?: string | null) => void;
+    menuKey?: string;
+    isDisabled?: boolean;
+    disabled?: boolean;
+    /** Catch-all for one-off Chakra Box overrides passed by callers. */
+    [key: string]: unknown;
+}
+/**
+ * Single sidebar nav row. Ported verbatim from
+ * react/app/src/layouts/AuthenticatedLayout.tsx lines 1292–1730 (2026-05-13)
+ * with mode + navigation-preference context reads swapped for shell hooks.
+ *
+ * Renders:
+ * - Top-level rows with optional children (accordion).
+ * - Sub-items inside an expanded parent (children list).
+ * - Active state via `data-nav-item-active` and primary-color fill.
+ * - Mode-aware hover gradient that sweeps left-to-right.
  */
-declare function OrgSelector(): react_jsx_runtime.JSX.Element | null;
+declare function NavItem({ icon, brandIcon, children, href, action, subItems, badge, subLabel, isSubItem, isExpanded, onToggle, menuKey, isDisabled: navIsDisabled, disabled, ...rest }: NavItemProps): react_jsx_runtime.JSX.Element;
+
+interface BrandLogoProps {
+    src?: string;
+    alt?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Mode-aware brand logo rendered in the sidebar header. The host app
+ * supplies `src` (e.g., a different image per mode); the shell wraps it
+ * in a non-draggable <img> so it never accidentally drags on click.
+ *
+ * Render returns null when no src is supplied so consuming chrome can
+ * gracefully omit the slot.
+ */
+declare function BrandLogo({ src, alt, className, style }: BrandLogoProps): react_jsx_runtime.JSX.Element | null;
+
+interface BrandIconProps {
+    /** Brand-icon name keyed off `/brand/icons/<name>.svg` in the app's public dir. */
+    name: string;
+    /** Pixel size shorthand — sets both width and height. */
+    size?: number;
+    className?: string;
+    style?: CSSProperties;
+    alt?: string;
+    /** Optional prefix for the icon path. Defaults to '/brand/icons/'. */
+    basePath?: string;
+}
+/**
+ * Brand-icon component used by sidebar NavItems. The actual SVG assets live
+ * in the consuming app's `public/brand/icons/<name>.svg` — shell never
+ * imports them directly, only references them by URL.
+ */
+declare function BrandIcon({ name, size, className, style, alt, basePath, }: BrandIconProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Support icon + modal rendered in the header. Reads auth, org, and support
@@ -287,9 +613,53 @@ declare function OrgSelector(): react_jsx_runtime.JSX.Element | null;
  */
 declare function SupportRequestButton(): react_jsx_runtime.JSX.Element | null;
 
+interface CommitCopyButtonProps {
+    /**
+     * Pre-rendered environment chip (e.g., the app's own `EnvironmentBanner`).
+     * Takes precedence over `environmentLabel`. Click anywhere on the chip
+     * copies the full commit SHA.
+     */
+    envNode?: ReactNode;
+    /**
+     * Environment label (e.g., 'staging', 'production', 'local'). When
+     * `envNode` is not supplied, the component renders a default chip
+     * keyed off this label with appropriate background/border color.
+     */
+    environmentLabel?: string;
+    /** Full git commit SHA. Last 4 characters are rendered; click copies the full SHA. */
+    commit?: string;
+    /** App version, e.g., '2.34.1'. Renders as `v{version}`. */
+    version?: string;
+    /** ISO date string of the commit. Formatted as 'Mon D'. */
+    commitDate?: string;
+    /** Commit author name (e.g., 'Leland Smith'). First name is shown. */
+    commitAuthor?: string;
+    /** Full commit message body — shown as a tooltip over the env chip. */
+    commitLog?: string;
+    /**
+     * Optional click handler for the diagnostics icon. When unset, the
+     * icon is not rendered.
+     */
+    onDiagnosticsClick?: () => void;
+}
+/**
+ * Footer commit info pill. Ported from
+ * `react/app/src/layouts/AuthenticatedLayout.tsx::CommitCopyButton`
+ * (lines 3017–3284, 2026-05-13).
+ *
+ * Visual: two stacked rows.
+ *   Row 1: [env chip] | {last4 SHA} | v{version} | [diagnostics icon]
+ *   Row 2: | {Mon D} | {firstName} |  (only when date or author present)
+ *
+ * Clicking the env chip copies the full SHA via `useClipboard`, with a
+ * brief "Copied" toast that fades up. Hovering the env chip shows the
+ * full commit log in a tooltip.
+ */
+declare function CommitCopyButton({ envNode, environmentLabel, commit, version, commitDate, commitAuthor, commitLog, onDiagnosticsClick, }: CommitCopyButtonProps): react_jsx_runtime.JSX.Element;
+
 interface ShellChromeProps {
     children: ReactNode;
-    /** Drives <OrgSelector /> in the header. */
+    /** Drives <OrgPill /> in the sidebar. */
     organization?: ShellOrganizationValue | null;
     /** Drives the UserMenu Switch-account section. */
     linkedAccounts?: ShellLinkedAccountsValue | null;
@@ -299,6 +669,35 @@ interface ShellChromeProps {
     devNotesMenu?: ReactNode;
     /** UserMenu profile link target. Defaults to '/my-profile'. */
     myProfileHref?: string;
+    /** Drives <ModePill /> + active row colors. */
+    mode?: ShellModeValue | null;
+    /** The sidebar nav rows. */
+    navItems?: ShellNavItem[];
+    /** User's nav-rendering preference. */
+    navigationPreference?: ShellNavigationPreferenceValue | null;
+    /** Active-role display info for the UserMenu role badge. */
+    role?: ShellRoleValue | null;
+    /** Footer data for the sidebar bottom row. */
+    footer?: ShellFooterValue | null;
+    /** Image src for the sidebar BrandLogo (top-left). */
+    brandLogoSrc?: string;
+    /** Header right-side icon stack (Fuel, NewTextBell, Alerts, Toggle, ImportProgress, etc). */
+    headerIconsSlot?: ReactNode;
+    /** href used by the UserMenu "Organization Settings" item. */
+    organizationSettingsHref?: string;
+    /** When true, UserMenu shows "Continue Onboarding" item. */
+    showContinueOnboarding?: boolean;
+    /** Click handler for UserMenu "Continue Onboarding". */
+    onContinueOnboarding?: () => void;
+    /** Header page title text. */
+    pageTitle?: string;
+    /** Header breadcrumb chips. */
+    breadcrumbs?: Array<{
+        label: string;
+        href?: string;
+    }>;
+    /** Header right-side action buttons (rendered before the icon row). */
+    headerActions?: ReactNode;
 }
 /**
  * Drop-in chrome binding for apps where the org/linked-account/support data
@@ -312,7 +711,56 @@ interface ShellChromeProps {
  * Apps that have all the data available at the ShellProvider construction
  * site can pass the same props to <ShellProvider> directly instead.
  */
-declare function ShellChrome({ children, organization, linkedAccounts, support, devNotesMenu, myProfileHref, }: ShellChromeProps): react_jsx_runtime.JSX.Element;
+declare function ShellChrome({ children, organization, linkedAccounts, support, devNotesMenu, myProfileHref, mode, navItems, navigationPreference, role, footer, brandLogoSrc, headerIconsSlot, organizationSettingsHref, showContinueOnboarding, onContinueOnboarding, pageTitle, breadcrumbs, headerActions, }: ShellChromeProps): react_jsx_runtime.JSX.Element;
+
+/** Returns a normalized 7-char hex color, or null if the input isn't valid. */
+declare function normalizeHexColor(value?: string | null): string | null;
+/**
+ * Returns an `rgba(...)` string lightened toward white by `amount` (0–1),
+ * or null if the input isn't a valid hex.
+ */
+declare function hexToRgba(hex: string, alpha: number): string | null;
+/**
+ * Returns a hex color that is `amount` (0–1) blended from `hex` toward
+ * white. Used for the org-menu hover background.
+ */
+declare function lightenHexColor(hex: string, amount: number): string | null;
+/**
+ * Reads `settings.brand_colors[0].value` off an org-like input and returns
+ * the first valid normalized hex. Returns null if the input doesn't have
+ * a usable brand color.
+ */
+declare function getOrganizationBrandColor(organization?: {
+    brandColor?: string | null;
+    settings?: {
+        brand_colors?: Array<{
+            value?: string | null;
+        }> | null;
+    } | null;
+} | null): string | null;
+/**
+ * Returns the two-letter badge for an organization name (e.g., "The Portland
+ * Company" -> "TP"). Falls back to "OR" when the input has no letters.
+ */
+declare function getOrganizationBadgeLetters(name?: string | null): string;
+
+interface UserLike {
+    profile?: {
+        full_name?: string | null;
+        name?: string | null;
+    } | null;
+    user_metadata?: {
+        full_name?: string | null;
+        name?: string | null;
+    } | null;
+    email?: string | null;
+}
+/**
+ * Resolves a user-facing display name from a user object. Tries profile
+ * fields first, then user_metadata, then the email local-part, then the
+ * raw email, finally falling back to "User".
+ */
+declare function getUserDisplayName(user: UserLike | null | undefined): string;
 
 interface RegisterShellPrecacheOptions {
     /** Path the host app serves the SW from. Default: '/sw-shell.js'. */
@@ -340,4 +788,4 @@ declare function registerShellPrecache(opts?: RegisterShellPrecacheOptions): Pro
  */
 declare function buildSpeculationRules(currentApp: string, registry: AppRegistryEntry[]): string | null;
 
-export { AppLayout, type AppRegistryEntry, BreadcrumbBar, Card, Footer, GlobalUiIdProvider, Header, HeaderTabBar, type HeaderTabBarItem, OrgSelector, PageContainer, PageHeader, type ShellAuthStatus, type ShellAuthValue, ShellChrome, ShellChromeContext, type ShellChromeProps, type ShellLinkedAccount, ShellLinkedAccountsContext, type ShellLinkedAccountsValue, ShellOrgContext, type ShellOrganization, type ShellOrganizationValue, ShellProvider, type ShellProviderProps, type ShellSlots, type ShellSupportContext, ShellSupportProviderContext, type ShellSupportValue, type ShellUser, Sidebar, SupportRequestButton, UserMenu, buildSpeculationRules, politogyTheme, registerShellPrecache, useAppRegistry, useCurrentApp, useShellAuth, useShellChrome, useShellLinkedAccounts, useShellOrganization, useShellSupport };
+export { AppLayout, type AppRegistryEntry, BrandIcon, BrandLogo, BreadcrumbBar, Card, CommitCopyButton, type CommitCopyButtonProps, Footer, GlobalUiIdProvider, Header, HeaderTabBar, type HeaderTabBarItem, ModePill, NavItem, OrgPill, OrgPill as OrgSelector, PageContainer, PageHeader, type ShellActiveRoleConfig, type ShellAuthStatus, type ShellAuthValue, ShellChrome, ShellChromeContext, type ShellChromeProps, type ShellChromeValue, ShellFooterContext, type ShellFooterLink, type ShellFooterValue, type ShellLinkedAccount, ShellLinkedAccountsContext, type ShellLinkedAccountsValue, type ShellModeConfig, ShellModeContext, type ShellModeValue, type ShellNavItem, ShellNavItemsContext, type ShellNavItemsValue, ShellNavigationPreferenceContext, type ShellNavigationPreferenceValue, ShellOrgContext, type ShellOrganization, type ShellOrganizationValue, ShellProvider, type ShellProviderProps, ShellRoleContext, type ShellRoleValue, type ShellSlots, type ShellSupportContext, ShellSupportProviderContext, type ShellSupportValue, type ShellUser, Sidebar, SupportRequestButton, UserMenu, buildSpeculationRules, getOrganizationBadgeLetters, getOrganizationBrandColor, getUserDisplayName, hexToRgba, lightenHexColor, normalizeHexColor, politogyTheme, registerShellPrecache, useAppRegistry, useCurrentApp, useShellAuth, useShellChrome, useShellFooter, useShellLinkedAccounts, useShellMode, useShellNavItems, useShellNavigationPreference, useShellOrganization, useShellRole, useShellSupport };