@the-portland-company/shell 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -228,7 +228,26 @@ interface ShellFooterValue {
     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 {
@@ -245,12 +264,16 @@ interface ShellProviderProps {
     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;
     /** href used by the UserMenu "My Profile" link. Defaults to '/my-profile'. */
     myProfileHref?: string;
+    /** Optional avatar URL override for the header UserMenu. Useful when the
+     *  app has additional avatar sources (profile.avatar_url, memoji selection
+     *  in localStorage, branded default URL) that aren't in user_metadata. */
+    userAvatarUrl?: string;
 }
 /** Return value of useShellAuth(). */
 interface ShellAuthValue {
@@ -343,9 +366,12 @@ interface ShellChromeValue {
         href?: string;
     }>;
     headerActions?: ReactNode;
+    /** Avatar URL override for UserMenu. Apps that store the avatar in their own
+     *  profile table or localStorage should pass it here. */
+    userAvatarUrl?: string;
 }
 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 ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, organization, linkedAccounts, support, devNotesMenu, myProfileHref, userAvatarUrl, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useShellAuth(): ShellAuthValue;
 
@@ -441,13 +467,16 @@ interface HeaderProps {
  *  2. headerActions (app-supplied React node, e.g., page action buttons).
  *  3. headerIconsSlot (app-supplied React node, e.g., FuelPopover,
  *     NewTextBellPopup, SystemAlertsMenu, NavigationToggleMenu,
- *     ImportProgressIndicator).
- *  4. DevNotesMenu (from useShellChrome().devNotesMenu).
- *  5. UserMenu (avatar + name/email VStack + chevron).
+ *     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` +
- * `devNotesMenu`.
+ * 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;
 
@@ -591,6 +620,50 @@ declare function BrandIcon({ name, size, className, style, alt, basePath, }: Bra
  */
 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 <OrgPill /> in the sidebar. */
@@ -632,6 +705,9 @@ interface ShellChromeProps {
     }>;
     /** Header right-side action buttons (rendered before the icon row). */
     headerActions?: ReactNode;
+    /** Avatar URL override for UserMenu. Pass a value computed from the app's
+     *  profile.avatar_url / localStorage / default fallback chain. */
+    userAvatarUrl?: string;
 }
 /**
  * Drop-in chrome binding for apps where the org/linked-account/support data
@@ -645,7 +721,7 @@ 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, mode, navItems, navigationPreference, role, footer, brandLogoSrc, headerIconsSlot, organizationSettingsHref, showContinueOnboarding, onContinueOnboarding, pageTitle, breadcrumbs, headerActions, }: 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, userAvatarUrl, }: 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;
@@ -722,4 +798,4 @@ declare function registerShellPrecache(opts?: RegisterShellPrecacheOptions): Pro
  */
 declare function buildSpeculationRules(currentApp: string, registry: AppRegistryEntry[]): string | null;
 
-export { AppLayout, type AppRegistryEntry, BrandIcon, BrandLogo, BreadcrumbBar, Card, 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 };
+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 };

package/dist/index.d.ts

@@ -228,7 +228,26 @@ interface ShellFooterValue {
     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 {
@@ -245,12 +264,16 @@ interface ShellProviderProps {
     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;
     /** href used by the UserMenu "My Profile" link. Defaults to '/my-profile'. */
     myProfileHref?: string;
+    /** Optional avatar URL override for the header UserMenu. Useful when the
+     *  app has additional avatar sources (profile.avatar_url, memoji selection
+     *  in localStorage, branded default URL) that aren't in user_metadata. */
+    userAvatarUrl?: string;
 }
 /** Return value of useShellAuth(). */
 interface ShellAuthValue {
@@ -343,9 +366,12 @@ interface ShellChromeValue {
         href?: string;
     }>;
     headerActions?: ReactNode;
+    /** Avatar URL override for UserMenu. Apps that store the avatar in their own
+     *  profile table or localStorage should pass it here. */
+    userAvatarUrl?: string;
 }
 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 ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, organization, linkedAccounts, support, devNotesMenu, myProfileHref, userAvatarUrl, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useShellAuth(): ShellAuthValue;
 
@@ -441,13 +467,16 @@ interface HeaderProps {
  *  2. headerActions (app-supplied React node, e.g., page action buttons).
  *  3. headerIconsSlot (app-supplied React node, e.g., FuelPopover,
  *     NewTextBellPopup, SystemAlertsMenu, NavigationToggleMenu,
- *     ImportProgressIndicator).
- *  4. DevNotesMenu (from useShellChrome().devNotesMenu).
- *  5. UserMenu (avatar + name/email VStack + chevron).
+ *     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` +
- * `devNotesMenu`.
+ * 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;
 
@@ -591,6 +620,50 @@ declare function BrandIcon({ name, size, className, style, alt, basePath, }: Bra
  */
 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 <OrgPill /> in the sidebar. */
@@ -632,6 +705,9 @@ interface ShellChromeProps {
     }>;
     /** Header right-side action buttons (rendered before the icon row). */
     headerActions?: ReactNode;
+    /** Avatar URL override for UserMenu. Pass a value computed from the app's
+     *  profile.avatar_url / localStorage / default fallback chain. */
+    userAvatarUrl?: string;
 }
 /**
  * Drop-in chrome binding for apps where the org/linked-account/support data
@@ -645,7 +721,7 @@ 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, mode, navItems, navigationPreference, role, footer, brandLogoSrc, headerIconsSlot, organizationSettingsHref, showContinueOnboarding, onContinueOnboarding, pageTitle, breadcrumbs, headerActions, }: 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, userAvatarUrl, }: 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;
@@ -722,4 +798,4 @@ declare function registerShellPrecache(opts?: RegisterShellPrecacheOptions): Pro
  */
 declare function buildSpeculationRules(currentApp: string, registry: AppRegistryEntry[]): string | null;
 
-export { AppLayout, type AppRegistryEntry, BrandIcon, BrandLogo, BreadcrumbBar, Card, 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 };
+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 };