@meetreeve/ui 0.2.0 → 0.5.2

package/README.md

@@ -102,6 +102,18 @@ import { ResponsiveHeader } from "@meetreeve/ui";
 
 Search is the primary slot — always inline, floored at a minimum width from `@meetreeve/ui/tokens`. Under width pressure everything ELSE collapses first: the wordmark drops to glyph-only, secondary controls fold into a hamburger disclosure below `md`.
 
+### CSS container-query collapse (DEV-4260)
+
+The wordmark↔glyph and inline-actions↔hamburger split is pure CSS — a Tailwind v4 `@container` on the header plus container-query variants (`@min-[768px]:...`) — not JS/`matchMedia`. Both the desktop and mobile structures are always in the DOM; CSS alone decides which is visible at the header's *current container width* (not the viewport — the header can be narrower than the viewport, e.g. inside a sidebar). This means: no desktop first-paint FOUC, and a no-JS viewer gets the correct layout for their actual width instead of always falling back to the mobile/hamburger markup. JS is used only for the hamburger's open/close state and one `ResizeObserver` that closes an open mobile menu when the header's own container regrows past the split.
+
+**Your Tailwind build must scan this package's dist for these classes to work** — same requirement as `AppSidebar`'s `md:flex` (DEV-4351). Tailwind v4 ignores `.gitignore`'d paths (`node_modules`) by default, so add:
+
+```css
+@source "../../node_modules/@meetreeve/ui/dist";
+```
+
+to your `globals.css` (adjust the relative path to your app). See `reeve-tenant-frontend`'s `src/app/globals.css` for the existing precedent. Without this, `ResponsiveHeader`'s container-variant classes (and `AppSidebar`'s) never make it into your compiled CSS, and the header renders as if `display: none` applied everywhere.
+
 ## BrandGlyph
 
 ```tsx
@@ -112,6 +124,40 @@ import { BrandGlyph } from "@meetreeve/ui";
 
 Resolution order: favicon → logo → initials monogram.
 
+## ContextSwitcher (DEV-4408)
+
+One reusable, data-driven, org-grouped dropdown for switching the active
+"context" — a brand, a tenant, or whatever `refId`-addressable entity a host
+app maps onto `ContextSwitcherItem[]`. Fully headless: no data fetching, no
+app-specific types. Host apps write a thin wrapper that pulls their own data
+source (e.g. `useBrand()`) and maps it to items — see reeve-frontend's
+`BrandContextSwitcher` for the pattern.
+
+```tsx
+import { ContextSwitcher, type ContextSwitcherItem } from "@meetreeve/ui";
+
+const items: ContextSwitcherItem[] = brands.map((b) => ({
+  refId: b.id,
+  name: b.name,
+  favicon: faviconUrl(b.slug), // pre-resolve any host-specific favicon rules yourself
+  logo: b.logo_url,
+  orgId: b.org_id,
+  orgName: b.org_name,
+}));
+
+<ContextSwitcher
+  items={items}
+  activeRefId={activeBrand?.id ?? null}
+  onSelect={(item) => switchBrand(item.refId)}
+  placeholder="Select brand"
+/>;
+```
+
+Org headers render only when items span more than one org — the common
+single-org case stays a flat list. `collapsed` swaps the trigger for an
+icon-only button (56px nav rail); `footer` adds a slot below the list (e.g.
+an "Add brand" CTA).
+
 ## Tokens
 
 ```ts

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, RefObject } from 'react';
+import { ReactNode, ElementType, RefObject } from 'react';
 import { z } from 'zod';
 
 /**
@@ -10,9 +10,11 @@ import { z } from 'zod';
  * order:
  *   1. `brand.favicon` — the site's own square icon,
  *   2. `brand.logo` rendered `object-contain` (no squish),
- *   3. a high-contrast letter monogram in a deterministic brand colour.
+ *   3. a single-letter monogram in the brand colour + an accent dot
+ *      (DEV-4539 — modeled on Reeve's own "R." canon; no boxed container).
  * Each image load error advances to the next candidate.
  */
+declare const REEVE_ACCENT = "#FF6B2B";
 interface Brand {
     /** Display name — drives the wordmark and the monogram fallback. */
     name: string;
@@ -20,8 +22,17 @@ interface Brand {
     favicon?: string | null;
     /** Wider brand logo URL (second cascade step, rendered `object-contain`). */
     logo?: string | null;
-    /** Override the deterministic monogram background colour. */
+    /** Override the deterministic monogram letter colour. */
     color?: string | null;
+    /**
+     * Accent-dot colour for the single-letter monogram fallback (DEV-4539) —
+     * the "family mark". Pass the brand DNA's own strong accent colour when
+     * one is known; falls back to Reeve's own accent dot (REEVE_ACCENT)
+     * otherwise, the same "part of the Reeve ecosystem" signal the backend
+     * logo generator resolves. `null`/omitted both mean "use the fallback" —
+     * this field becomes a brand-manifest-owned value once C2 lands.
+     */
+    accentColor?: string | null;
 }
 /**
  * Favicon URL for a brand's canonical domain. Returns null unless `domain`
@@ -38,6 +49,49 @@ interface BrandGlyphProps {
 }
 declare function BrandGlyph({ brand, size, subtle, className }: BrandGlyphProps): react.JSX.Element;
 
+/**
+ * Brand lockup metric rules (DEV-5139) — the single source of truth for how a
+ * lettermark relates to its wordmark. Grounded in standard identity-system
+ * practice: the measurement unit for a lockup is the WORDMARK'S CAP HEIGHT,
+ * proportions are locked as ratios, and the pieces share one baseline.
+ *
+ * Rules v1:
+ *  1. Baseline lock — mark, accent dot, and wordmark sit on ONE shared
+ *     baseline. Flex `items-baseline` in the lockup; never `items-center`
+ *     for text marks (center-aligning boxes ≠ aligning baselines — measured
+ *     3px baseline float on cadasense, DEV-5139).
+ *  2. Cap-height parity + optical overshoot — the mark's cap height is
+ *     MARK_CAP_RATIO × the wordmark's cap height. A lone round glyph
+ *     (C/G/O/Q/S) optically undershoots flat caps, so exact parity reads
+ *     small; 1.08 restores perceived equality (measured 0.93 before).
+ *  3. Lockup gap — mark→wordmark gap is 0.5–0.8× the wordmark cap height.
+ *  4. Clearspace — ≥1 cap height of empty space around the whole lockup
+ *     (the header's own padding satisfies this; consumers embedding the
+ *     lockup elsewhere own the rule).
+ *  5. Standalone glyph fill — on a square canvas (favicon, avatar), the
+ *     letter's cap height is ~60–70% of the canvas edge; ghost-tile below
+ *     20px (DEV-4539).
+ *  6. Ratios are locked — scale the lockup uniformly; never resize one
+ *     element of it. These constants are that lock.
+ *
+ * The generated-asset pipeline (reeve-services brand_identity
+ * svg_templates) mirrors these values — see DEV-5140. Change them together.
+ */
+/** Rule 2 — mark cap height ÷ wordmark cap height. */
+declare const MARK_CAP_RATIO = 1.08;
+/**
+ * Rule 3, applied: 8px gap ≈ 0.79× the wordmark's ~10.1px cap height —
+ * inside the 0.5–0.8 band. Named so nobody "fixes" it per-surface.
+ */
+declare const LOCKUP_GAP = "gap-2";
+/**
+ * Rule 1, applied: the lockup is one locked unit — baseline-aligned inside,
+ * centered as a whole by whatever wraps it (e.g. a touch target).
+ */
+declare const LOCKUP_ROW = "flex items-baseline";
+/** Rule 5 — standalone glyph cap height as a fraction of the canvas edge. */
+declare const GLYPH_CANVAS_FILL = 0.65;
+
 interface HeaderNavItem {
     label: string;
     href?: string;
@@ -53,6 +107,19 @@ interface ResponsiveHeaderProps {
     search: ReactNode;
     /** Secondary nav links — inline on desktop, in the menu on mobile. */
     nav?: HeaderNavItem[];
+    /**
+     * Optional destination for the brand lockup. When set, the glyph + wordmark
+     * become a single clickable link to this href (restores the "click the logo
+     * to go home" affordance). When omitted, the lockup is a plain, non-link div.
+     */
+    brandHref?: string;
+    /**
+     * Link renderer for the brand lockup and `nav` href items. Defaults to a bare
+     * `"a"` so the package stays framework-agnostic; consumers pass their router's
+     * link (e.g. `next/link`) for client-side navigation. Action-only nav items
+     * (no href) stay `<button>` regardless.
+     */
+    linkComponent?: ElementType;
     /** Auth control (avatar / sign-in) — secondary. */
     auth?: ReactNode;
     /** Theme toggle — secondary. */
@@ -70,9 +137,53 @@ interface ResponsiveHeaderProps {
  *   brand wordmark drops to glyph-only and the secondary controls fold into a
  *   hamburger disclosure. The search is never touched.
  *
- * A `"use client"` leaf: it's interactive (matchMedia + disclosure state).
+ * CSS container-query collapse (DEV-4260): the wordmark<->glyph and
+ * inline-actions<->hamburger split is pure CSS (`@container` on the header +
+ * Tailwind v4 container-query variants), NOT JS/matchMedia. Both the desktop
+ * and mobile structures render in EVERY environment — SSR, first paint, and
+ * with JS fully disabled — so there's no desktop first-paint FOUC and no
+ * "no-JS users get hamburger-only" fallback (DEV-4248 follow-up).
+ *
+ * The split is pinned to `BREAKPOINTS.md` (768px) via an ARBITRARY container
+ * variant (`@min-[768px]:...`) rather than Tailwind's *named* `@md` container
+ * variant: Tailwind v4's default container scale (`@md` = 448px) is a
+ * different scale than the viewport breakpoint scale and does NOT match
+ * `BREAKPOINTS.md`. Because Tailwind's build-time scanner needs a literal
+ * class string (it greps compiled output, it doesn't evaluate JS), "768" is a
+ * hardcoded literal in the classNames below, not interpolated from
+ * `BREAKPOINTS.md` — `responsive-header.test.tsx`'s className-contract tests
+ * assert against `BREAKPOINTS.md` directly so drift between the token and the
+ * literal fails loudly.
+ *
+ * Consumers must add `@meetreeve/ui/dist` to their Tailwind `@source` scan
+ * (see this package's README) or these container-variant classes never make
+ * it into the consumer's compiled CSS — same requirement as AppSidebar's
+ * `md:flex` (DEV-4351).
+ *
+ * JS is used ONLY for two things: the hamburger disclosure's open/close
+ * state, and ONE ResizeObserver on the header itself (deliberately NOT a
+ * viewport matchMedia — the point of DEV-4260/DEV-4248 is that the collapse
+ * reacts to the header's own *container* width, e.g. a narrow sidebar on a
+ * wide viewport) that tears down an open mobile menu when the header's
+ * container regrows past the CSS split.
  */
-declare function ResponsiveHeader({ brand, search, nav, auth, themeToggle, menuLabel, className, }: ResponsiveHeaderProps): react.JSX.Element;
+declare function ResponsiveHeader({ brand, search, nav, brandHref, linkComponent, auth, themeToggle, menuLabel, className, }: ResponsiveHeaderProps): react.JSX.Element;
+
+/**
+ * Pick a viewport-appropriate placeholder string: the `desktop` copy at/above
+ * `md`, the shorter `mobile` copy below it (falling back to `desktop` when no
+ * mobile string is supplied). Fixes the "long search prompt clips in the
+ * 200px-floored mobile slot" class of bug without the consumer wiring up its
+ * own media query.
+ *
+ * Built on the package's guarded `useMediaQuery`, which returns `false` when
+ * `matchMedia` is unavailable — so SSR and the first client paint yield the
+ * MOBILE string. That mobile-first default is intentional: the short string
+ * never clips, and the value reconciles up to the desktop string on mount once
+ * the viewport is measured `>= md` (consistent with the DEV-4260 FOUC note; no
+ * hydration mismatch, since server and first client render both read `false`).
+ */
+declare function useResponsivePlaceholder(desktop: string, mobile?: string): string;
 
 /**
  * SidebarLadder — the per-tenant JSON artifact (DEV-4351) that pre-calculates
@@ -325,4 +436,69 @@ interface FlyoutProps {
  */
 declare function Flyout({ label, icon, active, children, className }: FlyoutProps): react.JSX.Element;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, type GroupRungItem, type HeaderNavItem, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, reconcileLadder, resolveLadder, useLadderRung, zSidebarLadder };
+/**
+ * ContextSwitcher (DEV-4408) — promoted out of reeve-frontend's
+ * src/components/context/context-switcher.tsx (DEV-2513), which was already
+ * fully headless (props in, no app-specific data fetching). One reusable,
+ * data-driven, org-grouped dropdown for switching the active "context" —
+ * whatever refId-addressable entity a host app's own thin wrapper maps onto
+ * `ContextSwitcherItem[]` (reeve-frontend's brand, reeve-tenant-frontend's
+ * tenant, or — once the spawned-company substrate lands — a company
+ * cockpit). Orgs are pure visual groupers — headers render ONLY for
+ * multi-org accounts; the common single-org case stays a flat list.
+ *
+ * The menu renders through Radix DropdownMenu so it portals out of a
+ * narrow/collapsible rail and stays on-screen — Radix handles collision
+ * flip/shift. `collapsed` swaps the trigger for an icon-only button that
+ * fits a 56px collapsed rail.
+ */
+interface ContextSwitcherItem {
+    /** Stable identity for this context — a brand id, tenant id, etc. */
+    refId: string;
+    name: string;
+    /**
+     * Pre-resolved favicon URL (BrandGlyph's favicon-first cascade). Any
+     * host-specific favicon rules (e.g. reeve-frontend's synthetic-domain
+     * guard around `faviconUrl`) must be applied by the host BEFORE mapping
+     * into this item — this package stays agnostic of any one host's domain
+     * conventions.
+     */
+    favicon?: string | null;
+    /** Wider brand/tenant logo URL (BrandGlyph's second cascade step). */
+    logo?: string | null;
+    /** Override BrandGlyph's deterministic monogram letter colour. */
+    color?: string | null;
+    /** Override BrandGlyph's monogram accent-dot colour (DEV-4539). */
+    accentColor?: string | null;
+    orgId?: string | null;
+    orgName?: string | null;
+}
+interface ContextOrgGroup {
+    orgId: string | null;
+    orgName: string | null;
+    items: ContextSwitcherItem[];
+}
+/** Group contexts by owning org. Items sort by name; groups by org name. */
+declare function groupByOrg(items: ContextSwitcherItem[]): ContextOrgGroup[];
+interface ContextSwitcherProps {
+    items: ContextSwitcherItem[];
+    /** refId of the active context. */
+    activeRefId: string | null;
+    onSelect: (item: ContextSwitcherItem) => void;
+    /** Optional dropdown footer slot, e.g. an "Add brand" CTA. */
+    footer?: React.ReactNode;
+    /** Trigger label when nothing is active. */
+    placeholder?: string;
+    /** Icon-only trigger — for a collapsed (56px) nav rail. */
+    collapsed?: boolean;
+    /** Dropdown placement (Radix). Defaults to bottom/start; Radix auto-flips. */
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
+    /** Extra classes merged onto the portaled DropdownMenuContent — e.g. a
+     *  higher z-index so the dropdown clears a high-z overlay (a mobile
+     *  drawer above the default z-50 content). */
+    contentClassName?: string;
+}
+declare function ContextSwitcher({ items, activeRefId, onSelect, footer, placeholder, collapsed, side, align, contentClassName, }: ContextSwitcherProps): react.JSX.Element;
+
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode, RefObject } from 'react';
+import { ReactNode, ElementType, RefObject } from 'react';
 import { z } from 'zod';
 
 /**
@@ -10,9 +10,11 @@ import { z } from 'zod';
  * order:
  *   1. `brand.favicon` — the site's own square icon,
  *   2. `brand.logo` rendered `object-contain` (no squish),
- *   3. a high-contrast letter monogram in a deterministic brand colour.
+ *   3. a single-letter monogram in the brand colour + an accent dot
+ *      (DEV-4539 — modeled on Reeve's own "R." canon; no boxed container).
  * Each image load error advances to the next candidate.
  */
+declare const REEVE_ACCENT = "#FF6B2B";
 interface Brand {
     /** Display name — drives the wordmark and the monogram fallback. */
     name: string;
@@ -20,8 +22,17 @@ interface Brand {
     favicon?: string | null;
     /** Wider brand logo URL (second cascade step, rendered `object-contain`). */
     logo?: string | null;
-    /** Override the deterministic monogram background colour. */
+    /** Override the deterministic monogram letter colour. */
     color?: string | null;
+    /**
+     * Accent-dot colour for the single-letter monogram fallback (DEV-4539) —
+     * the "family mark". Pass the brand DNA's own strong accent colour when
+     * one is known; falls back to Reeve's own accent dot (REEVE_ACCENT)
+     * otherwise, the same "part of the Reeve ecosystem" signal the backend
+     * logo generator resolves. `null`/omitted both mean "use the fallback" —
+     * this field becomes a brand-manifest-owned value once C2 lands.
+     */
+    accentColor?: string | null;
 }
 /**
  * Favicon URL for a brand's canonical domain. Returns null unless `domain`
@@ -38,6 +49,49 @@ interface BrandGlyphProps {
 }
 declare function BrandGlyph({ brand, size, subtle, className }: BrandGlyphProps): react.JSX.Element;
 
+/**
+ * Brand lockup metric rules (DEV-5139) — the single source of truth for how a
+ * lettermark relates to its wordmark. Grounded in standard identity-system
+ * practice: the measurement unit for a lockup is the WORDMARK'S CAP HEIGHT,
+ * proportions are locked as ratios, and the pieces share one baseline.
+ *
+ * Rules v1:
+ *  1. Baseline lock — mark, accent dot, and wordmark sit on ONE shared
+ *     baseline. Flex `items-baseline` in the lockup; never `items-center`
+ *     for text marks (center-aligning boxes ≠ aligning baselines — measured
+ *     3px baseline float on cadasense, DEV-5139).
+ *  2. Cap-height parity + optical overshoot — the mark's cap height is
+ *     MARK_CAP_RATIO × the wordmark's cap height. A lone round glyph
+ *     (C/G/O/Q/S) optically undershoots flat caps, so exact parity reads
+ *     small; 1.08 restores perceived equality (measured 0.93 before).
+ *  3. Lockup gap — mark→wordmark gap is 0.5–0.8× the wordmark cap height.
+ *  4. Clearspace — ≥1 cap height of empty space around the whole lockup
+ *     (the header's own padding satisfies this; consumers embedding the
+ *     lockup elsewhere own the rule).
+ *  5. Standalone glyph fill — on a square canvas (favicon, avatar), the
+ *     letter's cap height is ~60–70% of the canvas edge; ghost-tile below
+ *     20px (DEV-4539).
+ *  6. Ratios are locked — scale the lockup uniformly; never resize one
+ *     element of it. These constants are that lock.
+ *
+ * The generated-asset pipeline (reeve-services brand_identity
+ * svg_templates) mirrors these values — see DEV-5140. Change them together.
+ */
+/** Rule 2 — mark cap height ÷ wordmark cap height. */
+declare const MARK_CAP_RATIO = 1.08;
+/**
+ * Rule 3, applied: 8px gap ≈ 0.79× the wordmark's ~10.1px cap height —
+ * inside the 0.5–0.8 band. Named so nobody "fixes" it per-surface.
+ */
+declare const LOCKUP_GAP = "gap-2";
+/**
+ * Rule 1, applied: the lockup is one locked unit — baseline-aligned inside,
+ * centered as a whole by whatever wraps it (e.g. a touch target).
+ */
+declare const LOCKUP_ROW = "flex items-baseline";
+/** Rule 5 — standalone glyph cap height as a fraction of the canvas edge. */
+declare const GLYPH_CANVAS_FILL = 0.65;
+
 interface HeaderNavItem {
     label: string;
     href?: string;
@@ -53,6 +107,19 @@ interface ResponsiveHeaderProps {
     search: ReactNode;
     /** Secondary nav links — inline on desktop, in the menu on mobile. */
     nav?: HeaderNavItem[];
+    /**
+     * Optional destination for the brand lockup. When set, the glyph + wordmark
+     * become a single clickable link to this href (restores the "click the logo
+     * to go home" affordance). When omitted, the lockup is a plain, non-link div.
+     */
+    brandHref?: string;
+    /**
+     * Link renderer for the brand lockup and `nav` href items. Defaults to a bare
+     * `"a"` so the package stays framework-agnostic; consumers pass their router's
+     * link (e.g. `next/link`) for client-side navigation. Action-only nav items
+     * (no href) stay `<button>` regardless.
+     */
+    linkComponent?: ElementType;
     /** Auth control (avatar / sign-in) — secondary. */
     auth?: ReactNode;
     /** Theme toggle — secondary. */
@@ -70,9 +137,53 @@ interface ResponsiveHeaderProps {
  *   brand wordmark drops to glyph-only and the secondary controls fold into a
  *   hamburger disclosure. The search is never touched.
  *
- * A `"use client"` leaf: it's interactive (matchMedia + disclosure state).
+ * CSS container-query collapse (DEV-4260): the wordmark<->glyph and
+ * inline-actions<->hamburger split is pure CSS (`@container` on the header +
+ * Tailwind v4 container-query variants), NOT JS/matchMedia. Both the desktop
+ * and mobile structures render in EVERY environment — SSR, first paint, and
+ * with JS fully disabled — so there's no desktop first-paint FOUC and no
+ * "no-JS users get hamburger-only" fallback (DEV-4248 follow-up).
+ *
+ * The split is pinned to `BREAKPOINTS.md` (768px) via an ARBITRARY container
+ * variant (`@min-[768px]:...`) rather than Tailwind's *named* `@md` container
+ * variant: Tailwind v4's default container scale (`@md` = 448px) is a
+ * different scale than the viewport breakpoint scale and does NOT match
+ * `BREAKPOINTS.md`. Because Tailwind's build-time scanner needs a literal
+ * class string (it greps compiled output, it doesn't evaluate JS), "768" is a
+ * hardcoded literal in the classNames below, not interpolated from
+ * `BREAKPOINTS.md` — `responsive-header.test.tsx`'s className-contract tests
+ * assert against `BREAKPOINTS.md` directly so drift between the token and the
+ * literal fails loudly.
+ *
+ * Consumers must add `@meetreeve/ui/dist` to their Tailwind `@source` scan
+ * (see this package's README) or these container-variant classes never make
+ * it into the consumer's compiled CSS — same requirement as AppSidebar's
+ * `md:flex` (DEV-4351).
+ *
+ * JS is used ONLY for two things: the hamburger disclosure's open/close
+ * state, and ONE ResizeObserver on the header itself (deliberately NOT a
+ * viewport matchMedia — the point of DEV-4260/DEV-4248 is that the collapse
+ * reacts to the header's own *container* width, e.g. a narrow sidebar on a
+ * wide viewport) that tears down an open mobile menu when the header's
+ * container regrows past the CSS split.
  */
-declare function ResponsiveHeader({ brand, search, nav, auth, themeToggle, menuLabel, className, }: ResponsiveHeaderProps): react.JSX.Element;
+declare function ResponsiveHeader({ brand, search, nav, brandHref, linkComponent, auth, themeToggle, menuLabel, className, }: ResponsiveHeaderProps): react.JSX.Element;
+
+/**
+ * Pick a viewport-appropriate placeholder string: the `desktop` copy at/above
+ * `md`, the shorter `mobile` copy below it (falling back to `desktop` when no
+ * mobile string is supplied). Fixes the "long search prompt clips in the
+ * 200px-floored mobile slot" class of bug without the consumer wiring up its
+ * own media query.
+ *
+ * Built on the package's guarded `useMediaQuery`, which returns `false` when
+ * `matchMedia` is unavailable — so SSR and the first client paint yield the
+ * MOBILE string. That mobile-first default is intentional: the short string
+ * never clips, and the value reconciles up to the desktop string on mount once
+ * the viewport is measured `>= md` (consistent with the DEV-4260 FOUC note; no
+ * hydration mismatch, since server and first client render both read `false`).
+ */
+declare function useResponsivePlaceholder(desktop: string, mobile?: string): string;
 
 /**
  * SidebarLadder — the per-tenant JSON artifact (DEV-4351) that pre-calculates
@@ -325,4 +436,69 @@ interface FlyoutProps {
  */
 declare function Flyout({ label, icon, active, children, className }: FlyoutProps): react.JSX.Element;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, type GroupRungItem, type HeaderNavItem, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, reconcileLadder, resolveLadder, useLadderRung, zSidebarLadder };
+/**
+ * ContextSwitcher (DEV-4408) — promoted out of reeve-frontend's
+ * src/components/context/context-switcher.tsx (DEV-2513), which was already
+ * fully headless (props in, no app-specific data fetching). One reusable,
+ * data-driven, org-grouped dropdown for switching the active "context" —
+ * whatever refId-addressable entity a host app's own thin wrapper maps onto
+ * `ContextSwitcherItem[]` (reeve-frontend's brand, reeve-tenant-frontend's
+ * tenant, or — once the spawned-company substrate lands — a company
+ * cockpit). Orgs are pure visual groupers — headers render ONLY for
+ * multi-org accounts; the common single-org case stays a flat list.
+ *
+ * The menu renders through Radix DropdownMenu so it portals out of a
+ * narrow/collapsible rail and stays on-screen — Radix handles collision
+ * flip/shift. `collapsed` swaps the trigger for an icon-only button that
+ * fits a 56px collapsed rail.
+ */
+interface ContextSwitcherItem {
+    /** Stable identity for this context — a brand id, tenant id, etc. */
+    refId: string;
+    name: string;
+    /**
+     * Pre-resolved favicon URL (BrandGlyph's favicon-first cascade). Any
+     * host-specific favicon rules (e.g. reeve-frontend's synthetic-domain
+     * guard around `faviconUrl`) must be applied by the host BEFORE mapping
+     * into this item — this package stays agnostic of any one host's domain
+     * conventions.
+     */
+    favicon?: string | null;
+    /** Wider brand/tenant logo URL (BrandGlyph's second cascade step). */
+    logo?: string | null;
+    /** Override BrandGlyph's deterministic monogram letter colour. */
+    color?: string | null;
+    /** Override BrandGlyph's monogram accent-dot colour (DEV-4539). */
+    accentColor?: string | null;
+    orgId?: string | null;
+    orgName?: string | null;
+}
+interface ContextOrgGroup {
+    orgId: string | null;
+    orgName: string | null;
+    items: ContextSwitcherItem[];
+}
+/** Group contexts by owning org. Items sort by name; groups by org name. */
+declare function groupByOrg(items: ContextSwitcherItem[]): ContextOrgGroup[];
+interface ContextSwitcherProps {
+    items: ContextSwitcherItem[];
+    /** refId of the active context. */
+    activeRefId: string | null;
+    onSelect: (item: ContextSwitcherItem) => void;
+    /** Optional dropdown footer slot, e.g. an "Add brand" CTA. */
+    footer?: React.ReactNode;
+    /** Trigger label when nothing is active. */
+    placeholder?: string;
+    /** Icon-only trigger — for a collapsed (56px) nav rail. */
+    collapsed?: boolean;
+    /** Dropdown placement (Radix). Defaults to bottom/start; Radix auto-flips. */
+    side?: "top" | "right" | "bottom" | "left";
+    align?: "start" | "center" | "end";
+    /** Extra classes merged onto the portaled DropdownMenuContent — e.g. a
+     *  higher z-index so the dropdown clears a high-z overlay (a mobile
+     *  drawer above the default z-50 content). */
+    contentClassName?: string;
+}
+declare function ContextSwitcher({ items, activeRefId, onSelect, footer, placeholder, collapsed, side, align, contentClassName, }: ContextSwitcherProps): react.JSX.Element;
+
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };