@the-portland-company/shell 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
 import { User, Session, SupabaseClient } from '@supabase/supabase-js';
 
@@ -122,6 +123,16 @@ 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. */
+    organization?: ShellOrganizationValue;
+    /** If provided, UserMenu shows account switcher + add-account button. */
+    linkedAccounts?: ShellLinkedAccountsValue;
+    /** If provided, shell renders <SupportRequestButton /> in the header. */
+    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;
 }
 /** Return value of useShellAuth(). */
 interface ShellAuthValue {
@@ -130,14 +141,109 @@ interface ShellAuthValue {
     session: Session | null;
     signOut: () => Promise<void>;
 }
+/**
+ * Organization that the current user belongs to. Apps supply this via
+ * ShellProvider so the shell can render <OrgSelector /> in the header.
+ */
+interface ShellOrganization {
+    id: string;
+    name: string;
+    logoUrl?: string | null;
+    /** Brand color as a hex string (e.g., '#0066cc'). Used for the org badge fallback. */
+    brandColor?: string | null;
+}
+interface ShellOrganizationValue {
+    currentOrg: ShellOrganization | null;
+    /** All orgs the user belongs to. */
+    organizations: ShellOrganization[];
+    /** Switch to the org with the given id. App owns the side effects. */
+    switchOrganization: (orgId: string) => Promise<void> | void;
+    /** Optional link rendered at the bottom of the org menu, e.g., '/organizations/new'. */
+    createOrgHref?: string;
+}
+/**
+ * An alternate user account the current user can switch into without signing
+ * out. App supplies the data + handlers; shell renders the UI inside UserMenu.
+ */
+interface ShellLinkedAccount {
+    id: string;
+    email: string;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+}
+interface ShellLinkedAccountsValue {
+    linkedAccounts: ShellLinkedAccount[];
+    switchToAccount: (accountId: string) => Promise<void> | void;
+    /** Called when the user clicks "Add account" in UserMenu. App opens its own modal. */
+    onAddAccount: () => void;
+    /** Called when the user wants to remove a linked account. App opens its own confirm. */
+    onRemoveAccount: (accountId: string) => void;
+}
+/** Context emitted to the host's submitSupportRequest handler. */
+interface ShellSupportContext {
+    pathname: string;
+    search: string;
+    pageTitle?: string;
+    organizationName?: string;
+}
+interface ShellSupportValue {
+    /**
+     * Submit a support request. Host app handles persistence/email/etc.
+     * Shell renders the modal and calls this on submit.
+     */
+    submitSupportRequest: (input: {
+        email: string;
+        phone: string;
+        message: string;
+        context: ShellSupportContext;
+    }) => Promise<void>;
+}
 
-declare function ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
+declare const ShellOrgContext: react.Context<ShellOrganizationValue | null>;
+declare const ShellLinkedAccountsContext: react.Context<ShellLinkedAccountsValue | null>;
+declare const ShellSupportProviderContext: react.Context<ShellSupportValue | null>;
+interface ShellChromeValue$1 {
+    devNotesMenu: ReactNode | null;
+    myProfileHref: string;
+}
+declare const ShellChromeContext: react.Context<ShellChromeValue$1 | null>;
+declare function ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, organization, linkedAccounts, support, devNotesMenu, myProfileHref, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useShellAuth(): ShellAuthValue;
 
 declare function useAppRegistry(): AppRegistryEntry[];
 declare function useCurrentApp(): string;
 
+/**
+ * Returns the organization value supplied to ShellProvider, or null if the
+ * host app didn't pass an `organization` prop. Returning null lets chrome
+ * components (e.g., <OrgSelector />) render nothing instead of erroring.
+ */
+declare function useShellOrganization(): ShellOrganizationValue | null;
+
+/**
+ * Returns the linked-accounts value supplied to ShellProvider, or null if not
+ * provided. UserMenu uses this to decide whether to render the
+ * "switch account" section.
+ */
+declare function useShellLinkedAccounts(): ShellLinkedAccountsValue | null;
+
+/**
+ * Returns the support handler supplied to ShellProvider, or null if not
+ * provided. SupportRequestButton uses this to decide whether to render.
+ */
+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>.
+ */
+declare function useShellChrome(): ShellChromeValue;
+
 interface AppLayoutProps extends ShellSlots {
     children: ReactNode;
     buildInfo?: string;
@@ -161,6 +267,53 @@ 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.
+ */
+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.
+ */
+declare function OrgSelector(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Support icon + modal rendered in the header. Reads auth, org, and support
+ * handler from ShellProvider. Renders nothing when the host app didn't supply
+ * a `support` prop.
+ */
+declare function SupportRequestButton(): react_jsx_runtime.JSX.Element | null;
+
+interface ShellChromeProps {
+    children: ReactNode;
+    /** Drives <OrgSelector /> in the header. */
+    organization?: ShellOrganizationValue | null;
+    /** Drives the UserMenu Switch-account section. */
+    linkedAccounts?: ShellLinkedAccountsValue | null;
+    /** Drives <SupportRequestButton /> and modal submission. */
+    support?: ShellSupportValue | null;
+    /** Rendered in the header (typically <DevNotesMenu />). */
+    devNotesMenu?: ReactNode;
+    /** UserMenu profile link target. Defaults to '/my-profile'. */
+    myProfileHref?: string;
+}
+/**
+ * Drop-in chrome binding for apps where the org/linked-account/support data
+ * lives in React contexts nested BELOW <ShellProvider> (e.g., an
+ * <OrganizationProvider> that itself depends on <AuthProvider>).
+ *
+ * Use this component inside those providers to feed the values into the
+ * shell's chrome contexts. Nested <Context.Provider> overrides the empty
+ * defaults set by <ShellProvider> at the top of the tree.
+ *
+ * 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;
+
 interface RegisterShellPrecacheOptions {
     /** Path the host app serves the SW from. Default: '/sw-shell.js'. */
     scriptUrl?: string;
@@ -187,4 +340,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, PageContainer, PageHeader, type ShellAuthStatus, type ShellAuthValue, ShellProvider, type ShellProviderProps, type ShellSlots, type ShellUser, Sidebar, buildSpeculationRules, politogyTheme, registerShellPrecache, useAppRegistry, useCurrentApp, useShellAuth };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
 import { User, Session, SupabaseClient } from '@supabase/supabase-js';
 
@@ -122,6 +123,16 @@ 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. */
+    organization?: ShellOrganizationValue;
+    /** If provided, UserMenu shows account switcher + add-account button. */
+    linkedAccounts?: ShellLinkedAccountsValue;
+    /** If provided, shell renders <SupportRequestButton /> in the header. */
+    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;
 }
 /** Return value of useShellAuth(). */
 interface ShellAuthValue {
@@ -130,14 +141,109 @@ interface ShellAuthValue {
     session: Session | null;
     signOut: () => Promise<void>;
 }
+/**
+ * Organization that the current user belongs to. Apps supply this via
+ * ShellProvider so the shell can render <OrgSelector /> in the header.
+ */
+interface ShellOrganization {
+    id: string;
+    name: string;
+    logoUrl?: string | null;
+    /** Brand color as a hex string (e.g., '#0066cc'). Used for the org badge fallback. */
+    brandColor?: string | null;
+}
+interface ShellOrganizationValue {
+    currentOrg: ShellOrganization | null;
+    /** All orgs the user belongs to. */
+    organizations: ShellOrganization[];
+    /** Switch to the org with the given id. App owns the side effects. */
+    switchOrganization: (orgId: string) => Promise<void> | void;
+    /** Optional link rendered at the bottom of the org menu, e.g., '/organizations/new'. */
+    createOrgHref?: string;
+}
+/**
+ * An alternate user account the current user can switch into without signing
+ * out. App supplies the data + handlers; shell renders the UI inside UserMenu.
+ */
+interface ShellLinkedAccount {
+    id: string;
+    email: string;
+    displayName?: string | null;
+    avatarUrl?: string | null;
+}
+interface ShellLinkedAccountsValue {
+    linkedAccounts: ShellLinkedAccount[];
+    switchToAccount: (accountId: string) => Promise<void> | void;
+    /** Called when the user clicks "Add account" in UserMenu. App opens its own modal. */
+    onAddAccount: () => void;
+    /** Called when the user wants to remove a linked account. App opens its own confirm. */
+    onRemoveAccount: (accountId: string) => void;
+}
+/** Context emitted to the host's submitSupportRequest handler. */
+interface ShellSupportContext {
+    pathname: string;
+    search: string;
+    pageTitle?: string;
+    organizationName?: string;
+}
+interface ShellSupportValue {
+    /**
+     * Submit a support request. Host app handles persistence/email/etc.
+     * Shell renders the modal and calls this on submit.
+     */
+    submitSupportRequest: (input: {
+        email: string;
+        phone: string;
+        message: string;
+        context: ShellSupportContext;
+    }) => Promise<void>;
+}
 
-declare function ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
+declare const ShellOrgContext: react.Context<ShellOrganizationValue | null>;
+declare const ShellLinkedAccountsContext: react.Context<ShellLinkedAccountsValue | null>;
+declare const ShellSupportProviderContext: react.Context<ShellSupportValue | null>;
+interface ShellChromeValue$1 {
+    devNotesMenu: ReactNode | null;
+    myProfileHref: string;
+}
+declare const ShellChromeContext: react.Context<ShellChromeValue$1 | null>;
+declare function ShellProvider({ children, supabaseClient, currentApp, appRegistry, basename, organization, linkedAccounts, support, devNotesMenu, myProfileHref, }: ShellProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function useShellAuth(): ShellAuthValue;
 
 declare function useAppRegistry(): AppRegistryEntry[];
 declare function useCurrentApp(): string;
 
+/**
+ * Returns the organization value supplied to ShellProvider, or null if the
+ * host app didn't pass an `organization` prop. Returning null lets chrome
+ * components (e.g., <OrgSelector />) render nothing instead of erroring.
+ */
+declare function useShellOrganization(): ShellOrganizationValue | null;
+
+/**
+ * Returns the linked-accounts value supplied to ShellProvider, or null if not
+ * provided. UserMenu uses this to decide whether to render the
+ * "switch account" section.
+ */
+declare function useShellLinkedAccounts(): ShellLinkedAccountsValue | null;
+
+/**
+ * Returns the support handler supplied to ShellProvider, or null if not
+ * provided. SupportRequestButton uses this to decide whether to render.
+ */
+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>.
+ */
+declare function useShellChrome(): ShellChromeValue;
+
 interface AppLayoutProps extends ShellSlots {
     children: ReactNode;
     buildInfo?: string;
@@ -161,6 +267,53 @@ 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.
+ */
+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.
+ */
+declare function OrgSelector(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Support icon + modal rendered in the header. Reads auth, org, and support
+ * handler from ShellProvider. Renders nothing when the host app didn't supply
+ * a `support` prop.
+ */
+declare function SupportRequestButton(): react_jsx_runtime.JSX.Element | null;
+
+interface ShellChromeProps {
+    children: ReactNode;
+    /** Drives <OrgSelector /> in the header. */
+    organization?: ShellOrganizationValue | null;
+    /** Drives the UserMenu Switch-account section. */
+    linkedAccounts?: ShellLinkedAccountsValue | null;
+    /** Drives <SupportRequestButton /> and modal submission. */
+    support?: ShellSupportValue | null;
+    /** Rendered in the header (typically <DevNotesMenu />). */
+    devNotesMenu?: ReactNode;
+    /** UserMenu profile link target. Defaults to '/my-profile'. */
+    myProfileHref?: string;
+}
+/**
+ * Drop-in chrome binding for apps where the org/linked-account/support data
+ * lives in React contexts nested BELOW <ShellProvider> (e.g., an
+ * <OrganizationProvider> that itself depends on <AuthProvider>).
+ *
+ * Use this component inside those providers to feed the values into the
+ * shell's chrome contexts. Nested <Context.Provider> overrides the empty
+ * defaults set by <ShellProvider> at the top of the tree.
+ *
+ * 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;
+
 interface RegisterShellPrecacheOptions {
     /** Path the host app serves the SW from. Default: '/sw-shell.js'. */
     scriptUrl?: string;
@@ -187,4 +340,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, PageContainer, PageHeader, type ShellAuthStatus, type ShellAuthValue, ShellProvider, type ShellProviderProps, type ShellSlots, type ShellUser, Sidebar, buildSpeculationRules, politogyTheme, registerShellPrecache, useAppRegistry, useCurrentApp, useShellAuth };
+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 };