@the-portland-company/shell 0.76.15 → 0.77.0

package/dist/index-Cu5frXRQ.d.cts

@@ -0,0 +1,990 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType, CSSProperties } from 'react';
+import { ThemePreference as ThemePreference$1 } from './theme-preference.cjs';
+
+type FormColumnProps = {
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * The ONE constrained layout inside the frame's fluid `<main>` (Brand guideline
+ * "Content width is fluid"): a single left-aligned column, 960px max, for form
+ * and settings pages — single-record edit forms, Organization Settings tabs,
+ * My Profile, activation and setup flows. Data surfaces (tables, dashboards,
+ * maps) never use it; they take the full fluid width.
+ *
+ * It adds no gutter of its own — `<main>` already owns the 24px / 16px gutter —
+ * and it is never centered. There is no width prop on purpose: a per-page
+ * max-width is exactly what the guideline forbids.
+ */
+declare function FormColumn({ children, className }: FormColumnProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * The six canonical top-bar action slots (Reference/Global-Rules v9 → top-bar
+ * icons). Each slot's GLYPH is unique and comes from the Brand API
+ * `topbarIcons.items.*` tokens, exposed as `--topbar-icon-<slot>` CSS vars
+ * whose value is the brand-icon NAME. Every OTHER property — size, gap, color,
+ * hover, selected — is universal across all six slots.
+ */
+type TopBarIconSlot = 'comms-fuel' | 'apps' | 'notifications' | 'alerts' | 'support' | 'dark-mode';
+
+type CommsNotificationKind = 'notification' | 'alert';
+/** One row of the bell feed, as the shell reads it (camelCased). */
+type CommsNotification = {
+    id: string;
+    kind: CommsNotificationKind;
+    title: string;
+    body: string;
+    icon: string | null;
+    link: string | null;
+    readAt: string | null;
+    orgId: string | null;
+    createdAt: string | null;
+};
+type NotificationsFeed = {
+    /** Alerts first, then notifications, newest first (Comms sorts them). */
+    notifications: CommsNotification[];
+    /** One badge number: unread notifications plus unresolved alerts (Spec §6.3). */
+    badge: number;
+};
+type NotificationsAdapter = {
+    /** Read the signed-in viewer's feed, scoped to an org when one is active. */
+    list(orgId: string | null): Promise<NotificationsFeed>;
+    /** Mark one row read. Resolves false on any failure, never throws. */
+    markRead(id: string): Promise<boolean>;
+    /** Archive one row (hides it from the feed). Resolves false on failure. */
+    archive(id: string): Promise<boolean>;
+    /** Resolve one alert. Comms rejects this for non-alert rows. */
+    resolve(id: string): Promise<boolean>;
+};
+/** The empty bell: what every degraded path renders. Always a fresh object. */
+declare function emptyNotificationsFeed(): NotificationsFeed;
+/**
+ * Shape a raw Comms body into the feed. Tolerant on purpose: unknown keys are
+ * ignored, rows without an id are dropped, and archived rows are never shown.
+ */
+declare function normalizeNotificationsFeed(raw: unknown): NotificationsFeed;
+/**
+ * Build the comms-backed adapter over the app's chrome fetcher. A null fetcher
+ * (no chrome proxy wired) yields the empty bell with no network activity.
+ */
+declare function createCommsNotificationsAdapter(fetchJson: NavChromeFetcher | null): NotificationsAdapter;
+
+type NavIconLike = ComponentType<{
+    size?: number;
+    className?: string;
+}>;
+declare const CORE_APP_ORIGIN = "https://app.politogyvrm.com";
+/** Text/Email fuel top-up page (SMS Signal + Email Broadcast). */
+declare const CORE_BILLING_PATH = "/organization-settings/subscription-billing/text-email";
+/** Specs origin — same env-aware-constant pattern as CORE_APP_ORIGIN. */
+declare const SPECS_ORIGIN = "https://specs.politogyvrm.com";
+/**
+ * Resolve an organization logo URL for rendering in ANY app.
+ *
+ * `organizations.logo_url` is authored by VRM core and stored as a ROOT-RELATIVE
+ * core route — `/api/storage/public?bucket=organization-logos&path=<org>/logo.png`
+ * (the signed-storage proxy). VRM core renders it correctly because that path
+ * resolves against its own origin; every other app resolves it against its own
+ * origin (forms.politogyvrm.com/api/storage/public), gets a 404, and shows a
+ * broken image. The chrome API passes the stored value through verbatim, so the
+ * resolution belongs here — one definition for every app, core included.
+ *
+ * Absolute URLs (http/https/data/blob) pass through untouched.
+ */
+declare function resolveOrgLogoUrl(url: string | null | undefined): string | undefined;
+declare function topBarIconButtonClass(tone?: 'default' | 'warning' | 'danger'): string;
+declare function TopBarCountBadge({ count }: {
+    count: number;
+}): react_jsx_runtime.JSX.Element | null;
+/**
+ * The shared hover tooltip every top-bar control renders BELOW itself: an
+ * up-pointing arrow at the icon, a bold title line and a muted description.
+ * Pure CSS (group-hover) so it works on <a>, <button> and <summary> triggers.
+ * The trigger must carry `group/tbtip relative` (topBarIconButtonClass does).
+ */
+declare function TopBarTooltip({ title, description, }: {
+    title: string;
+    description?: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * The up-pointing arrow every top-bar panel renders, anchored under its
+ * trigger icon (panels are right-aligned, so the arrow sits at the trigger's
+ * center: 16px in from the panel's right edge). One definition — every menu
+ * points at its own icon identically.
+ */
+declare function TopBarPanelArrow(): react_jsx_runtime.JSX.Element;
+/**
+ * Wrapper for third-party top-bar widgets that ship their own launcher button
+ * (e.g. DevNotes). Normalizes the trigger to the universal 32px circular slot
+ * (chrome.css `.topbar-widget-slot`) and adds the standard tooltip.
+ */
+declare function TopBarWidgetSlot({ title, description, children, }: {
+    title: string;
+    description?: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+type ThemePreference = ThemePreference$1;
+declare function NavThemeControl({ value, onChange, }: {
+    value: ThemePreference;
+    onChange: (next: ThemePreference) => void;
+}): react_jsx_runtime.JSX.Element;
+type NavChromeFetcher = (path: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<unknown>;
+/** GET me — the authenticated user's chrome identity from the shared API.
+ * userName prefers the VRM-core profile full name over token claims. */
+type ChromeMe = {
+    user: string | null;
+    userName: string | null;
+    avatarUrl: string | null;
+    themePreference: string | null;
+    /** Universal navigation-display choice ('menu'|'tabs'|'both'); null when
+     *  unset or when the profile column is absent in this environment. */
+    navDisplay: string | null;
+    /** The user's durable active-org preference (full org uuid); null when unset
+     *  or when the profile column is absent. Adopted only when the request
+     *  carries no `?org=`/cookie selector — URL → cookie → profile → default. */
+    activeOrg?: string | null;
+    account?: string | null;
+    accountName?: string | null;
+    role?: string | null;
+    /** Contact reply-to, when the profile carries them (optional/tolerant). */
+    email?: string | null;
+    phone?: string | null;
+};
+/**
+ * A shared read cache scoped to one `<NavChromeProvider>` (one fetcher, one
+ * page boot). Every consumer of a given (path, orgId) pair within the TTL
+ * window awaits the SAME promise instead of firing its own request — this is
+ * what collapsed `/orgs` (2-4x), `/me` (2-3x) and `/notifications` (2-3x) per
+ * page load, 1-3.5s each, down to one call apiece (nav-latency-report.md
+ * Table 2). Keying by orgId means switching the active org is itself the
+ * invalidation: the new org gets a fresh key, never the previous org's cached
+ * value. A failed request is evicted immediately so the next consumer retries
+ * rather than replaying the same rejection for the rest of the TTL.
+ */
+declare function createChromeFetchCache(getFetchJson: () => NavChromeFetcher): {
+    dedupedFetch: (path: string, init: Parameters<NavChromeFetcher>[1] | undefined, opts?: {
+        orgId?: string | null;
+        ttlMs?: number;
+    }) => Promise<unknown>;
+    invalidate: (path: string) => void;
+};
+type NavChromeContextValue = {
+    fetchJson: NavChromeFetcher;
+    dedupedFetch: ReturnType<typeof createChromeFetchCache>['dedupedFetch'];
+    invalidateChromeCache: ReturnType<typeof createChromeFetchCache>['invalidate'];
+    me: ChromeMe | null;
+    meLoaded: boolean;
+    /** The bell's feed adapter; null = the legacy contacts-shaped feed. */
+    notificationsAdapter: NotificationsAdapter | null;
+};
+declare function NavChromeProvider({ fetchJson, notificationsAdapter, children, }: {
+    fetchJson: NavChromeFetcher;
+    /**
+     * Omitted: the bell reads the comms feed through the same proxy (default).
+     * An app may inject its own adapter; `null` keeps the legacy feed.
+     */
+    notificationsAdapter?: NotificationsAdapter | null;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** The authenticated user's chrome identity (profile name / avatar / theme). */
+declare function useChromeMe(): {
+    me: ChromeMe | null;
+    loaded: boolean;
+};
+/** The provider's de-duped chrome read (null outside <NavChromeProvider>). */
+declare function useNavChromeDedupedFetch(): NavChromeContextValue['dedupedFetch'] | null;
+/** The injected chrome fetcher (null outside <NavChromeProvider>). */
+declare function useNavChromeFetcher(): NavChromeFetcher | null;
+type FuelChannelStatus = {
+    remainingUnits: number;
+    rawBalanceUnits: number;
+    usedUnits: number;
+    lowFuel: boolean;
+    lowFuelThreshold: number;
+};
+type CommunicationsFuelStatus = {
+    organizationId: string;
+    signal: FuelChannelStatus;
+    broadcast: FuelChannelStatus;
+    combinedAvailableCredits: number;
+};
+type ChromeNotificationAlert = {
+    id: string;
+    title: string;
+    description: string;
+    href: string | null;
+    kind: string;
+    /** Server read state (adapter feeds only); the local watermark still applies. */
+    read?: boolean;
+};
+type ChromeNotificationReply = {
+    id: string;
+    contactId: string | null;
+    name: string;
+    preview: string;
+    /** Optional deep-link to the conversation; the new-reply toast opens it. */
+    href?: string;
+    /**
+     * Optional arrival timestamp. Present, it lets the trigger badge count a
+     * reply as "unseen" only when it is newer than the last time the panel was
+     * opened; absent (older payloads), replies simply don't survive the first
+     * open as unseen. Tolerated either way.
+     */
+    createdAt?: string;
+};
+/** A running or finished contact import surfaced in the notifications panel. */
+type ChromeNotificationImport = {
+    id: string;
+    label: string;
+    /** 0–100 progress, or null when indeterminate (no bar rendered). */
+    percent: number | null;
+    status: 'active' | 'completed';
+    href: string | null;
+};
+/** A cluster of quarantined contacts sharing one phone number. */
+type ChromeNotificationQuarantine = {
+    phone: string;
+    count: number;
+    /** Upstream may omit it; the row already renders conditionally on it. */
+    latestAt: string | null;
+};
+type ChromeNotificationsPayload = {
+    organizationId: string;
+    alerts: ChromeNotificationAlert[];
+    replies: ChromeNotificationReply[];
+    /** Optional — running/finished imports (tolerant when absent). */
+    imports?: ChromeNotificationImport[];
+    /** Optional — clustered quarantined contacts (tolerant when absent). */
+    quarantined?: ChromeNotificationQuarantine[];
+    /** Optional — the server's one badge number (adapter feeds only). */
+    badge?: number;
+};
+type ChromeOrgSummary = {
+    id: string;
+    name: string | null;
+    logoUrl: string | null;
+    brandColor: string | null;
+    role: string | null;
+    /** Un-mapped VRM-core membership role (e.g. "super_admin"). */
+    rawRole?: string | null;
+};
+/**
+ * Fetch the signed-in user's VRM-core organizations through the injected
+ * fetcher. Exposed as a hook so the org switcher in the sidebar and the
+ * org-scoped widgets share one request.
+ */
+declare function useChromeOrgs({ enabled }?: {
+    enabled?: boolean;
+}): {
+    orgs: ChromeOrgSummary[] | null;
+    loading: boolean;
+    error: boolean;
+};
+/**
+ * A top-bar popover: the shared circular trigger + a right-aligned panel.
+ * Closes on outside click / Escape. Purely presentational.
+ *
+ * EXPORTED so an app with a richer panel than the stock actions can render it
+ * inside the SHARED chrome — same 32px trigger, same tooltip, same badge, same
+ * panel surface and arrow — instead of hand-rolling a trigger and drifting.
+ * This is the enabling step for folding VRM's Fuel breakdown, import-progress,
+ * alerts and reply-feed panels into the shared cluster one at a time, without
+ * dropping capability (shell-nav-handoff §4; UI-Platform forbids migrating an
+ * app to a rendering that loses an element it already ships).
+ */
+declare function TopBarPopover({ label, description, slot, fallbackIcon, badge, tone, onOpen, openToken, onOpenChange, hideTooltip, children, panelClassName, }: {
+    label: string;
+    description?: string;
+    slot?: TopBarIconSlot;
+    fallbackIcon: NavIconLike;
+    badge?: number;
+    tone?: 'default' | 'warning' | 'danger';
+    onOpen?: () => void;
+    /**
+     * Imperative "open" signal: whenever this number CHANGES the panel opens
+     * (and `onOpen` fires). Lets a sibling — e.g. the notifications toast — open
+     * the panel without owning the popover's state. Undefined disables it.
+     */
+    openToken?: number;
+    /**
+     * Notified on every open/close. A sibling surface anchored to the same
+     * trigger (e.g. the notifications toast) must know when the panel is open so
+     * the two never render on top of each other — Reference/UI-Platform gives
+     * every top-bar panel ONE surface anchored to its trigger, so a second
+     * surface at the same anchor always occludes it.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Hide the trigger's hover tooltip while a transient nudge (the new-reply
+     * toast, the low-fuel hint) is up under the same trigger. Both are z-50 and
+     * anchored to the trigger, so without this the nudge paints over the
+     * tooltip (measured on a2p: the reply toast covered "Alerts &
+     * Notifications"). Reference/UI-Platform: one surface per trigger.
+     */
+    hideTooltip?: boolean;
+    children: ReactNode;
+    panelClassName?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function FuelAction({ orgId }: {
+    orgId: string | null;
+}): react_jsx_runtime.JSX.Element;
+declare function NotificationsAction({ orgId }: {
+    orgId: string | null;
+}): react_jsx_runtime.JSX.Element;
+declare function SupportAction({ orgId, orgs: knownOrgs, }?: {
+    orgId?: string | null;
+    orgs?: {
+        id: string;
+        name: string | null;
+    }[];
+}): react_jsx_runtime.JSX.Element;
+declare function SpecOverlayAction({ orgId, orgName }?: {
+    orgId?: string | null;
+    orgName?: string | null;
+}): react_jsx_runtime.JSX.Element | null;
+type NavDisplayMode = 'menu' | 'tabs' | 'both';
+declare function NavDisplayAction({ value, onChange, }: {
+    value: NavDisplayMode;
+    onChange: (next: NavDisplayMode) => void;
+}): react_jsx_runtime.JSX.Element;
+declare function useThemePreference(): {
+    value: ThemePreference;
+    setValue: (next: ThemePreference) => void;
+};
+
+/**
+ * Icon slots used by the standard menus. The shell stays icon-library-agnostic:
+ * callers map each key to their own icon components (lucide, react-icons, …).
+ * A missing key simply renders that row without an icon.
+ */
+type StandardNavIconKey = 'home' | 'users' | 'mail' | 'messageSquare' | 'layout' | 'activity' | 'lifeBuoy' | 'grid' | 'list' | 'upload' | 'edit' | 'fileText' | 'send' | 'clock' | 'user' | 'barChart' | 'briefcase' | 'settings' | 'creditCard' | 'dollarSign' | 'share' | 'phone' | 'map' | 'mapPin' | 'target' | 'flag' | 'layoutDashboard' | 'usersRound' | 'mousePointerClick' | 'clipboardList' | 'circleUser' | 'crosshair' | 'landmark' | 'chartNoAxes' | 'doorOpen' | 'signpost';
+/** The operating Mode whose nav tree to build. Defaults to `relationship`. */
+type StandardNavMode = 'relationship' | 'campaign' | 'petition';
+/**
+ * Per-feature availability for the Campaign tree. Campaign Mode ships its apps
+ * incrementally: a disabled feature is omitted from the nav entirely (rather
+ * than rendered as a dead/disabled row), and its flag flips to `true` in a
+ * later patch release as the app goes live. Dashboard and Voter Contact are
+ * core-hosted and always present, so they carry no flag.
+ */
+interface CampaignFeatureAvailability {
+    a2p: boolean;
+    phonebank: boolean;
+    canvass: boolean;
+    signs: boolean;
+    tribes: boolean;
+    polling: boolean;
+}
+/**
+ * Launch state at this shell version: every Campaign feature is deployed and
+ * live (a2p / phonebank / canvass / signs .politogyvrm.com all serve the app
+ * behind SSO as of 2026-07-24), so no row is hidden. The flags remain so a
+ * future feature can ship dark, and so a caller can hide one per-deployment.
+ */
+declare const CAMPAIGN_FEATURE_AVAILABILITY: CampaignFeatureAvailability;
+interface StandardNavOptions {
+    /**
+     * @deprecated app.politogyvrm.com (VRM core) is retired (Reference/UI-Platform
+     * → "Retirement of app.politogyvrm.com"). Every row this tree used to resolve
+     * against VRM core now points at its V2 host directly, so this is unused.
+     * Kept only so existing callers don't need to drop the field immediately.
+     */
+    coreBaseUrl?: string;
+    /** Icon component per slot; omitted slots render icon-less rows. */
+    icons?: Partial<Record<StandardNavIconKey, NavIcon>>;
+    /**
+     * App-local override for the "Contacts" item. `children` are used verbatim
+     * (NOT absolutized) so the owning app nests its own routes; `href` (also
+     * verbatim) feeds active-detection for the group header. When omitted, the
+     * item carries VRM core's own contacts sub-pages as absolute links.
+     * (Relationship tree only.)
+     */
+    contactsItem?: {
+        href?: string;
+        children?: NavItem[];
+        /**
+         * Live contact count shown right-aligned on the Contacts row, already
+         * formatted for display ("31.9K"). Only the owning app knows it.
+         * (Specs/Contacts design: `Contacts · 31.9K`.)
+         */
+        count?: string | number | null;
+    };
+    /**
+     * Top-level rows to OMIT, by label (case-insensitive), e.g. `['Polls','CTAs']`.
+     * The Specs/Contacts design rail lists Relationship → Collect → Account with
+     * exactly Dashboard · Contacts · Email broadcast · SMS/MMS blast / Calls to
+     * action · Forms · Surveys / My profile · Organization settings; apps that
+     * still surface Polls / CTAs keep them by default. A section row with no
+     * remaining items is dropped too.
+     */
+    hiddenItems?: string[];
+    /**
+     * App-local override for the Petition-mode "Dashboard" entry, same contract
+     * as `contactsItem`: `href`/`children` used verbatim so the Petitions app
+     * nests its own routes under the entry. (Petition tree only.)
+     */
+    petitionsItem?: {
+        href?: string;
+        children?: NavItem[];
+    };
+    /**
+     * The trailing "Support" row. VRM core opens its SupportRequestModal here;
+     * other apps supply their own handler (`onClick`) or a link (`href`).
+     * Omitted or `false` → no Support row. Appended to every mode's tree.
+     */
+    supportItem?: {
+        onClick?: () => void;
+        href?: string;
+    } | false;
+    /**
+     * Which mode's tree to build. Default `relationship`, whose output is
+     * byte-for-byte what this function produced before modes existed.
+     */
+    mode?: StandardNavMode;
+    /**
+     * Active organization id (full UUID). EVERY link in EVERY tree carries it as
+     * `?org=<uuid>` — the same convention the Mode switcher and My Account menu
+     * use — so the destination app opens on the same org instead of the user's
+     * default one. Omit it only when the caller genuinely has no active org yet.
+     */
+    activeOrgId?: string | null;
+    /**
+     * Per-feature Campaign availability overrides, merged over
+     * `CAMPAIGN_FEATURE_AVAILABILITY`. Only meaningful for the Campaign tree.
+     */
+    campaignAvailability?: Partial<CampaignFeatureAvailability>;
+}
+/**
+ * Build the standard Politogy VRM menu for the given `mode` (default
+ * `relationship`), in the exact order and wording the main app renders it. See
+ * `StandardNavOptions` for the app-specific hooks (`contactsItem`,
+ * `supportItem`) and the Campaign inputs (`activeOrgId`, `campaignAvailability`).
+ */
+declare function standardPolitogyNav(opts: StandardNavOptions): NavItem[];
+
+type NavIcon = ComponentType<{
+    size?: number;
+    className?: string;
+    strokeWidth?: number;
+}>;
+type NavItem = {
+    /**
+     * What this row IS. Defaults to `'link'` — every existing `NavItem[]` keeps
+     * its exact type and rendering.
+     *
+     * `'section'` is a non-interactive heading that groups the rows beneath it:
+     * uppercase, muted, letterspaced, not focusable, no hover. Only `label` is
+     * read; `href`, `icon`, `onClick` and `children` are ignored.
+     *
+     * The legacy chrome supported this and 0.43 dropped it, so apps faked it by
+     * passing `disabled` rows with no href — which looks approximately right and
+     * is wrong where it counts: a disabled row announces as an unavailable
+     * CONTROL to a screen reader, when it is not a control at all. A section is
+     * its own kind of row (Reference/UI-Platform → Left bar).
+     *
+     * Deliberately a widened field rather than a discriminated union: a union
+     * would make `item.href` a type error for every existing consumer that reads
+     * it, turning an additive feature into a breaking change.
+     */
+    kind?: 'link' | 'section';
+    /** Route to link to. Optional when `onClick` is supplied (renders a button). */
+    href?: string;
+    label: string;
+    icon?: NavIcon;
+    /**
+     * When supplied the row renders as a `<button>` (styled identically to the
+     * link rows) instead of a routed link — used for actions like "Support".
+     */
+    onClick?: () => void;
+    /**
+     * Disables the row: non-interactive and dimmed, with `disabledTitle` shown as
+     * a hover tooltip explaining why. Mirrors `NavTab`'s existing contract so a
+     * gated row looks the same whether it renders in the sidebar or a tab strip.
+     * Without this, an app that gates a section (VRM dims Email / SMS until setup
+     * is complete) had no way to express it and the row rendered fully clickable
+     * (shell-nav-handoff §3).
+     */
+    disabled?: boolean;
+    /** Tooltip for a disabled row — say why, and how to resolve it. */
+    disabledTitle?: string;
+    /**
+     * Right-aligned count/annotation on the row — e.g. the live contact count
+     * on "Contacts" (`31.9K`). Pre-formatted by the app; the shell only draws
+     * it (Specs/Contacts design rail). Omitted/null draws nothing.
+     */
+    badge?: string | number | null;
+    /**
+     * Nested sub-items. When present, the row becomes an expandable GROUP header.
+     * Clicking it always toggles the children open/closed and rotates the
+     * right-aligned chevron; if the item ALSO carries an `onClick`, that runs too,
+     * so a parent can navigate to its section dashboard while expanding
+     * (shell-nav-handoff §2). An `href` alone never navigates from a group header. The sidebar runs a single-open accordion (opening one group closes
+     * the others) and auto-expands whichever group contains the active route —
+     * mirroring the main VRM app's Chakra sidebar. Children render as smaller nav
+     * rows on a lighter panel and support both `href` links and `onClick` actions.
+     */
+    children?: NavItem[];
+};
+type NavLinkProps = {
+    href: string;
+    className?: string;
+    'aria-current'?: 'page' | undefined;
+    children: ReactNode;
+    role?: string;
+    'aria-selected'?: boolean;
+    'aria-label'?: string;
+    title?: string;
+    style?: CSSProperties;
+};
+type NavLinkComponent = ComponentType<NavLinkProps>;
+declare function isNavItemActive(pathname: string, href: string): boolean;
+/** A multi-mode app (VRM core) renders NavAppShell without a registry modeId;
+ * its current mode label still decides the rail colour (Left-Navigation §5). */
+declare function modeIdFromLabel(label: string | undefined): string | undefined;
+/** "Ben Edtl" -> "Ben E." (Left-Navigation §10). One word stays as is. */
+declare function shortUserName(name: string): string;
+/** Short environment name for the rail's build line ("prod", "staging", "local"). */
+declare function shortEnvLabel(label: string): string;
+declare function envChipClasses(label: string): string;
+type NavBrand = {
+    /** Where the logo links to. Defaults to "/". */
+    homeHref?: string;
+    /**
+     * Brand logo image src. When supplied this renders as the wordmark logo
+     * (matching the main app's BrandLogo), and `badgeLabel`/`title`/`subtitle`
+     * are used only as the no-image fallback.
+     */
+    logoSrc?: string;
+    logoAlt?: string;
+    /**
+     * The square mark shown at the top of the COLLAPSED rail (Left-Navigation
+     * §11.6) — Brand `assets.logoSquare`, the all-white vrm tile. Falls back to
+     * the badge when omitted.
+     */
+    logoSquareSrc?: string;
+    /**
+     * The logo URLs are still resolving from the Brand token sheet. The rail
+     * reserves the logo's box and draws nothing — never the badge fallback,
+     * which would flash a stand-in on every load.
+     */
+    logoPending?: boolean;
+    /** Short label shown inside the brand badge fallback (e.g. "P"). */
+    badgeLabel: string;
+    title: string;
+    subtitle?: string;
+};
+type NavOrgOption = {
+    id: string;
+    name: string | null;
+    logoUrl?: string | null;
+    /** The org's Brand Kit icon mark; falls back to `logoUrl`, then initials. */
+    iconUrl?: string | null;
+    brandColor?: string | null;
+    role?: string | null;
+};
+type NavOrg = {
+    name: string | null;
+    /** Full org id. When present, a copy affordance is shown by the label. */
+    id?: string | null;
+    /** Optional org logo for the pill badge; falls back to initials. */
+    logoUrl?: string | null;
+    /**
+     * The org's Brand Kit icon mark, shown on the collapsed rail (32px, on its
+     * white tile). Falls back to `logoUrl` scaled to fit, then initials.
+     */
+    iconUrl?: string | null;
+    /** Solid pill background (the org's brand color). Defaults to the accent. */
+    brandColor?: string | null;
+    /** Org's secondary Brand Kit color; the card's bottom-edge gradient runs
+     * primary → secondary. Falls back to the Politogy gradient when unset. */
+    brandColorSecondary?: string | null;
+    /**
+     * Organization Settings §7.1–§7.2: when the org has no logo yet, an Account
+     * Admin sees an "Upload logo" link in the band instead of the org name.
+     */
+    canUploadLogo?: boolean;
+    uploadLogoHref?: string;
+    onClick?: () => void;
+    /**
+     * The user's organizations. When present (even one), the pill renders as a
+     * dropdown SWITCHER (Reference/UI-Platform "Organization selector": never a
+     * static label in a multi-org app); selecting one calls `onSwitch(id)`.
+     */
+    organizations?: NavOrgOption[];
+    onSwitch?: (id: string) => void;
+    /**
+     * The active org is still resolving from the chrome API. Renders a skeleton
+     * pill instead of a name. Required because the app's own workspace label is
+     * NOT the organization: showing it while the real org loads flashes a wrong
+     * value (Global Rules — async values shimmer, they never render a stand-in).
+     */
+    loading?: boolean;
+};
+type NavModeOption = {
+    id: string;
+    label: string;
+    icon?: NavIcon;
+    /**
+     * Left-Navigation §7: a mode the organization does not hold is always
+     * shown (never hidden), dimmed, and not selectable. Defaults to true.
+     */
+    available?: boolean;
+    /** Tooltip for an unavailable mode, e.g. "Campaign Mode isn't active for
+     * this organization." Appended with "See upgrade options" for an Account
+     * Admin on a paid account (never during a trial). */
+    unavailableTooltip?: string;
+};
+type NavMode = {
+    label: string;
+    icon?: NavIcon;
+    /**
+     * Entitled modes for the active organization. With more than one option the
+     * pill renders as a SELECTOR (dropdown); with zero/one it stays the classic
+     * disabled single-mode pill. Selecting calls onSelect(id).
+     */
+    options?: NavModeOption[];
+    onSelect?: (id: string) => void;
+};
+type NavFooterLink = {
+    label: string;
+    href: string;
+    external?: boolean;
+};
+type NavFooter = {
+    /**
+     * Build metadata (env chip / commit / version / date / author). OPTIONAL:
+     * omit envLabel/version/commit to render a links-only footer — apps show
+     * the meta block to Super Administrators only (Reference/UI-Platform).
+     */
+    envLabel?: string;
+    version?: string;
+    commit?: string;
+    links?: NavFooterLink[];
+    /** ISO date (or any Date-parseable string) of the deployed commit. */
+    commitDate?: string;
+    /** Full name of the commit author (only the first name is shown). */
+    commitAuthor?: string;
+    /**
+     * The signed-in user, drawn as a card (avatar · name · email · chevron)
+     * ABOVE the links row. Reference/UI-Platform v30 → Left bar: "The user —
+     * avatar, name, email and the user menu — lives in the left bar footer."
+     * Clicking it opens the account menu UPWARD. `NavAppShell` fills these from
+     * `topBar.user` / `topBar.userMenu` / `topBar.onSignOut` automatically, so
+     * standalone `NavSidebar` consumers pass them only when they want the card.
+     */
+    user?: NavUser | null;
+    userMenu?: NavUserMenu | null;
+    onSignOut?: () => void;
+};
+type NavSidebarProps = {
+    pathname: string;
+    brand: NavBrand;
+    nav: {
+        groupLabel?: string;
+        items: NavItem[];
+        isActive?: (pathname: string, href: string) => boolean;
+        /**
+         * Render each top-level group's CHILDREN directly at the root of the rail
+         * — no parent header row, no accordion. For an app whose whole tree nests
+         * under one entry (Petitions), that parent row is pure anatomy: V1 never
+         * had it, it duplicates the first child's route, and it costs a level of
+         * indentation. Sections render as sections; rows render with the 'flat'
+         * variant (top-level geometry, wash active treatment). Top-level items
+         * WITHOUT children render unchanged, so a mixed tree degrades sanely.
+         */
+        flatten?: boolean;
+    };
+    org?: NavOrg | null;
+    mode?: NavMode | null;
+    footer?: NavFooter | null;
+    linkComponent?: NavLinkComponent;
+    /**
+     * Small-screen expand state (owned by `NavAppShell`). The rail is never
+     * hidden (Left-Navigation §11.6): at `md` and up it is the full rail, below
+     * `md` it collapses to the 64px icon rail. `open` expands the collapsed
+     * rail to the full rail as a modal drawer with a backdrop, and `onClose`
+     * wires the backdrop, the close button, and Escape. `md` and up ignores
+     * both.
+     */
+    open?: boolean;
+    onClose?: () => void;
+    /**
+     * Expands the collapsed (below `md`) rail. When set, the square logo tile at
+     * the top of the collapsed rail becomes the "Expand navigation" control —
+     * the Left-Navigation Design draws no other toggle and no top-bar hamburger.
+     */
+    onOpen?: () => void;
+    /**
+     * Closes the expanded rail after a nav-link click without counting as the
+     * user's Collapse choice. Defaults to `onClose`.
+     */
+    onNavigate?: () => void;
+};
+declare function NavSidebar({ pathname, brand, nav, org, mode, footer, linkComponent, open, onClose, onOpen, onNavigate, }: NavSidebarProps): react_jsx_runtime.JSX.Element;
+type NavUser = {
+    name: string | null;
+    email?: string | null;
+    /** Profile PHOTO url — highest-precedence avatar source. */
+    avatarUrl?: string | null;
+    /** Memoji url — used when no photo is set; falls back to initials. */
+    memojiUrl?: string | null;
+    tier?: string | null;
+    role?: string | null;
+};
+type NavTopBarAction = {
+    key: string;
+    /**
+     * Canonical top-bar slot. When set, the glyph is sourced by NAME from the
+     * Brand API via `--topbar-icon-<slot>`; `icon` becomes the fallback used
+     * until the runtime Brand stylesheet lands (or when the token is unset).
+     */
+    slot?: TopBarIconSlot;
+    icon: NavIcon;
+    label: string;
+    onClick?: () => void;
+    href?: string;
+    badge?: number | null;
+    tone?: 'default' | 'warning' | 'danger';
+    /** Tooltip body shown under the icon (label is the tooltip title). */
+    description?: string;
+};
+type NavLinkedAccount = {
+    id: string;
+    name: string | null;
+    email?: string | null;
+    avatarUrl?: string | null;
+    active?: boolean;
+};
+type NavRoleBadge = {
+    role: string;
+    orgName?: string | null;
+};
+/**
+ * The My Account menu (avatar dropdown) — mirrors the main VRM app's user
+ * menu: My Profile / Organization Settings links, a ROLES & ORGANIZATIONS
+ * section, an ACCOUNTS switcher, an optional theme control, then Sign out.
+ * Every section renders only when its data is supplied.
+ */
+type NavUserMenu = {
+    myProfileHref?: string;
+    organizationSettingsHref?: string;
+    roles?: NavRoleBadge[];
+    accounts?: NavLinkedAccount[];
+    onSwitchAccount?: (id: string) => void;
+    onRemoveAccount?: (id: string) => void;
+    addAccountHref?: string;
+    onAddAccount?: () => void;
+    /**
+     * Navigation display (Sub Menu / Tabs Only / Both) — lives in the account
+     * menu since 0.68.0; the top-bar `NavDisplayAction` popover is retired from
+     * the standard cluster (design: 4 icon buttons + Help).
+     */
+    navDisplay?: {
+        value: NavDisplayMode;
+        onChange: (next: NavDisplayMode) => void;
+    };
+    /** Theme preference segmented control (Light / System / Dark). */
+    theme?: {
+        value: ThemePreference;
+        onChange: (next: ThemePreference) => void;
+    };
+};
+type NavBreadcrumb = {
+    label: string;
+    href?: string;
+};
+type NavTopBarProps = {
+    /**
+     * Chrome-owned page title line (`<h1>` above main). Omit when the page body
+     * owns its own title (registry `pageTitle: false`, e.g. Contacts).
+     */
+    title?: string;
+    subtitle?: string;
+    /**
+     * Breadcrumb trail rendered UNDER the page title (Reference/UI-Platform:
+     * every page and sub-page/tab shows its location). Last crumb = current
+     * location (non-link); earlier crumbs may carry hrefs.
+     */
+    breadcrumbs?: NavBreadcrumb[];
+    user?: NavUser | null;
+    userMenu?: NavUserMenu;
+    onSignOut?: () => void;
+    /**
+     * Structured icon-button action cluster (32×32 circular buttons with optional
+     * count badges), rendered before the `actions` slot. Matches the main app's
+     * topbar action icons.
+     */
+    actionsList?: NavTopBarAction[];
+    /** App-specific action cluster rendered left of the theme toggle. */
+    actions?: ReactNode;
+    /** Theme toggle slot (injected so this package needs no theme dependency). */
+    themeToggle?: ReactNode;
+    /**
+     * Mobile drawer trigger (owned by `NavAppShell`). Supplying it renders a
+     * hamburger button, hidden at `lg` and up, as the first thing in the header
+     * — below `lg` the sidebar is otherwise unreachable. Omit to render no
+     * hamburger at all (e.g. `NavTopBar` used standalone).
+     */
+    onOpenNav?: () => void;
+    /** Whether the drawer `onOpenNav` opens is currently open (drives `aria-expanded`). */
+    navOpen?: boolean;
+    /**
+     * Universal search — Reference/UI-Platform "Top bar → required elements":
+     * the search field, 320px wide, at the left end of the bar; nothing else
+     * sits on the left. Omit `onChange`/`onSubmit` for a decorative field (an
+     * app that has not wired search yet still gets the correct chrome).
+     */
+    search?: {
+        placeholder?: string;
+        value?: string;
+        onChange?: (value: string) => void;
+        onSubmit?: (value: string) => void;
+    };
+    /**
+     * Build notes — a quiet text button that starts the right-hand group
+     * (Reference/UI-Platform "Top bar → required elements").
+     */
+    /**
+     * Where the My Account trigger lives. `'topbar'` (default for a standalone
+     * `NavTopBar`) keeps the avatar + name + chevron at the right end of the bar;
+     * `'sidebar'` / `'none'` hide it here — `NavAppShell` passes `'sidebar'` and
+     * draws the user card in the left-bar footer instead (UI-Platform v30:
+     * "There is no My Account badge in the top bar").
+     */
+    accountMenu?: 'topbar' | 'sidebar' | 'none';
+    buildNotes?: {
+        label?: string;
+        onOpen?: () => void;
+    };
+};
+declare function NavTopBar({ title, subtitle, breadcrumbs, user, userMenu, onSignOut, actionsList, actions, themeToggle, onOpenNav, navOpen, search, buildNotes, accountMenu, }: NavTopBarProps): react_jsx_runtime.JSX.Element;
+type NavTab = {
+    /** Stable identity (used as the React key). */
+    key: string;
+    /** The tab's visible text. */
+    label: string;
+    /**
+     * A Lucide icon rendered 6px left of the label (Reference/UI-Platform →
+     * Tabs, decided 2026-10-06: "Icon + label. Each tab is a Lucide icon."),
+     * 15px / 1.75 stroke (13px on a small strip), following the label's
+     * selected / unselected / hover color via `currentColor`. Icon-ONLY tabs
+     * (no label) are retired — this always pairs with `label`.
+     */
+    icon?: NavIcon;
+    /** Optional count, drawn as a mono pill after the label. */
+    count?: string | number | null;
+    /** Route to link to (rendered through `linkComponent`). */
+    href?: string;
+    /** Click handler — rendered as a `<button>` when there's no `href`. */
+    onSelect?: () => void;
+    /** Whether this tab is the active one (drives the mode-color underline). */
+    selected?: boolean;
+    /**
+     * Non-interactive, dimmed tab (e.g. Surveys' Canvas/Results before a survey
+     * is chosen). Renders a non-navigating span; `disabledTitle` is the tooltip
+     * explaining why.
+     */
+    disabled?: boolean;
+    disabledTitle?: string;
+};
+type NavTabStripProps = {
+    tabs: NavTab[];
+    /** Accessible name for the tablist. */
+    'aria-label'?: string;
+    /** Routing primitive for `href` tabs (Next `<Link>`, etc). Defaults to <a>. */
+    linkComponent?: NavLinkComponent;
+    /** `'sm'`: 12px text with 8px vertical padding. Default `'md'` (13px / 12px). */
+    size?: 'md' | 'sm';
+    /** Extra classes on the tablist container. */
+    className?: string;
+    /**
+     * Optional tab panel rendered directly below the strip, on the page
+     * surface with no card chrome. Omit to render only the strip and compose
+     * the page body yourself.
+     */
+    children?: ReactNode;
+};
+/**
+ * The canonical page tab strip: underlined text tabs on a 1px rule. Render it
+ * in the page body below the page header; pass the app's `Link` as
+ * `linkComponent` for `href` tabs.
+ */
+declare function NavTabStrip({ tabs, 'aria-label': ariaLabel, linkComponent, size, className, children, }: NavTabStripProps): react_jsx_runtime.JSX.Element;
+/**
+ * sessionStorage key holding the Beta-banner dismissal. sessionStorage — not
+ * localStorage — so the dismissal lasts only for the browser session; and it is
+ * additionally cleared on sign-out (see `clearBetaBannerDismissal`, called from
+ * the chrome frame) so a fresh LOGIN always re-shows the notice.
+ */
+declare const BETA_BANNER_DISMISS_KEY = "politogy_beta_banner_dismissed";
+/**
+ * Re-arm the Beta banner. The chrome frame calls this on sign-out so the notice
+ * reappears at the next login rather than staying hidden across the boundary
+ * (sessionStorage survives an in-tab logout→login round trip on its own).
+ */
+declare function clearBetaBannerDismissal(): void;
+type NavBetaBannerProps = {
+    /** Leading sentence(s) before the link. Defaults to the standard Beta copy. */
+    text?: string;
+    /** Bold + underlined link label. Defaults to the standard Terms copy. */
+    linkLabel?: string;
+    /** Terms & Conditions URL (opens in a new tab). Defaults to the app T&C page. */
+    href?: string;
+    /**
+     * Show a dismiss (×) button that hides the banner for the rest of the browser
+     * session. Cleared on sign-out, so it returns at the next login. Default true.
+     */
+    dismissible?: boolean;
+};
+declare function NavBetaBanner({ text, linkLabel, href, dismissible }: NavBetaBannerProps): react_jsx_runtime.JSX.Element | null;
+type NavAppShellProps = {
+    sidebar: NavSidebarProps;
+    topBar: NavTopBarProps;
+    /**
+     * When supplied, a full-width Beta notice strip renders directly below the top
+     * bar. Presence of the prop enables it; all fields fall back to the standard
+     * Beta copy + Terms & Conditions link.
+     */
+    betaBanner?: NavBetaBannerProps;
+    /**
+     * @deprecated The frame's content area is one fluid `<main>` (Brand
+     * guideline "Content width is fluid"): the 24px gutter (16px below `md`),
+     * no max-width and no centered container. Apps never emit their own page
+     * container, so there is nothing left to choose here.
+     *
+     * `'bare'` is still honored — it renders `children` with no `<main>` and no
+     * gutter — only so VRM core, which renders `NavAppShell` directly around
+     * pages that still carry their own `PageContainer`, does not get a nested
+     * `<main>` before it migrates. It warns in development and will be removed.
+     * `'padded'` is now the same as omitting the prop.
+     */
+    contentWrapper?: 'padded' | 'bare';
+    /**
+     * The operating Mode this frame is scoped to, stamped on the root as
+     * `data-politogy-mode` so the Brand API's per-Mode chrome tokens can target
+     * it (Reference/UI-Platform → "Per-mode branding — one accent per Mode").
+     *
+     * This is app IDENTITY, not app configuration: `PolitogyAppFrame` passes it
+     * from the `POLITOGY_APPS` registry, never from a prop an app supplies, so an
+     * app still cannot choose its own chrome colour.
+     *
+     * Omitted (or a Mode that declares no chrome group in the Brand API) => every
+     * accent falls back to the global one, exactly as before 0.47.
+     */
+    modeId?: string;
+    /**
+     * Where the user card / account menu renders. `'sidebar'` (default since
+     * 0.68.0) draws it in the left-bar footer and hides the top-bar trigger
+     * (Reference/UI-Platform v30); `'topbar'` restores the 0.67 top-right badge.
+     */
+    accountMenuPlacement?: 'sidebar' | 'topbar';
+    children: ReactNode;
+};
+declare function NavAppShell({ sidebar, topBar, betaBanner, contentWrapper, accountMenuPlacement, modeId, children, }: NavAppShellProps): react_jsx_runtime.JSX.Element;
+
+export { NavThemeControl as $, type ChromeOrgSummary as A, BETA_BANNER_DISMISS_KEY as B, type CommsNotification as C, type CommunicationsFuelStatus as D, FuelAction as E, FormColumn as F, type FuelChannelStatus as G, NavAppShell as H, type NavAppShellProps as I, NavBetaBanner as J, type NavBetaBannerProps as K, type NavBrand as L, NavChromeProvider as M, type NavItem as N, NavDisplayAction as O, type NavFooterLink as P, type NavLinkProps as Q, type NavLinkedAccount as R, type StandardNavIconKey as S, type NavModeOption as T, type NavOrg as U, type NavRoleBadge as V, NavSidebar as W, type NavSidebarProps as X, type NavTab as Y, NavTabStrip as Z, type NavTabStripProps as _, type CommsNotificationKind as a, NavTopBar as a0, type NavTopBarAction as a1, type NavTopBarProps as a2, type NavUser as a3, NotificationsAction as a4, SPECS_ORIGIN as a5, SpecOverlayAction as a6, type StandardNavOptions as a7, SupportAction as a8, type ThemePreference as a9, TopBarCountBadge as aa, TopBarPanelArrow as ab, TopBarPopover as ac, TopBarTooltip as ad, TopBarWidgetSlot as ae, clearBetaBannerDismissal as af, envChipClasses as ag, isNavItemActive as ah, modeIdFromLabel as ai, resolveOrgLogoUrl as aj, shortEnvLabel as ak, shortUserName as al, standardPolitogyNav as am, topBarIconButtonClass as an, useChromeMe as ao, useChromeOrgs as ap, useNavChromeDedupedFetch as aq, useNavChromeFetcher as ar, useThemePreference as as, type NotificationsAdapter as b, type NotificationsFeed as c, createCommsNotificationsAdapter as d, emptyNotificationsFeed as e, type NavIcon as f, type NavBreadcrumb as g, type StandardNavMode as h, type NavLinkComponent as i, type NavChromeFetcher as j, type NavMode as k, type NavUserMenu as l, type NavOrgOption as m, normalizeNotificationsFeed as n, type NavFooter as o, type NavDisplayMode as p, CAMPAIGN_FEATURE_AVAILABILITY as q, CORE_APP_ORIGIN as r, CORE_BILLING_PATH as s, type CampaignFeatureAvailability as t, type ChromeMe as u, type ChromeNotificationAlert as v, type ChromeNotificationImport as w, type ChromeNotificationQuarantine as x, type ChromeNotificationReply as y, type ChromeNotificationsPayload as z };