@cboxdk/cbox-ui 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,1383 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentProps, ComponentType } from 'react';
+import { LucideIcon } from 'lucide-react';
+import { ClassValue } from 'clsx';
+
+/**
+ * Identity contract every Cbox-family app must populate.
+ *
+ * Shape mirrors what the future `@cboxdk/cbox-id-client` SDK returns
+ * from id's `/api/v1/me` endpoint plus a small set of platform-level
+ * URLs that each app needs to construct deep-links into id.
+ *
+ * In the id app itself, populate this from Inertia shared props
+ * (id IS the source of truth — no API call needed).
+ *
+ * In cortex / atlas / track / future apps, populate from the
+ * id-client SDK — typically once per session, then refreshed when
+ * the user switches org or updates their profile.
+ *
+ * Components in this package read from the context but never write —
+ * mutations always round-trip through id's API via the id-client.
+ */
+type CboxAppKey = string;
+type CboxUser = {
+    id: number;
+    name: string;
+    email: string;
+    avatar_url?: string | null;
+    /** ISO 639-1 (e.g. "en", "da"). Used by formatters that want a locale. */
+    locale?: string | null;
+    /** IANA tz identifier (e.g. "Europe/Copenhagen"). */
+    timezone?: string | null;
+};
+type CboxOrganization = {
+    id: number;
+    slug: string;
+    name: string;
+    /**
+     * Role of the current user within this org as resolved by id.
+     * Apps should honour this for permission gating in the chrome
+     * (eg "Manage team" link is hidden for members).
+     */
+    role?: 'owner' | 'admin' | 'member' | string;
+};
+type CboxAppLink = {
+    /** Stable key — e.g. "id", "cortex", "atlas", "track". */
+    key: CboxAppKey;
+    /** Display name as shown in the launcher. */
+    name: string;
+    /** Absolute URL the launcher tile links to. */
+    url: string;
+    /**
+     * Short tagline shown under the name. Keep to ~5–8 words —
+     * the launcher truncates after one line.
+     */
+    description?: string;
+    /**
+     * One-letter monogram fallback when no icon is provided.
+     * Defaults to the first letter of `name`.
+     */
+    monogram?: string;
+    /** Optional inline SVG path or URL for the launcher tile icon. */
+    iconUrl?: string;
+    /**
+     * Accent colour for the monogram tile (and current-app highlight).
+     * Hex string or any CSS colour the browser accepts. Falls back to
+     * the neutral chip when missing.
+     */
+    accentColor?: string;
+    /** Tag the user's currently-active app so the launcher highlights it. */
+    current?: boolean;
+    /**
+     * Whether the current org has access to this app. Defaults to
+     * `true` so existing payloads render unchanged. `false` renders
+     * the tile as locked: greyed out, no nav, and (if the host app
+     * passes `onLockedAppClick`) opens an upgrade affordance.
+     */
+    entitled?: boolean;
+    /**
+     * Mark the app as not-yet-released. Renders as a disabled tile
+     * with a "soon" badge — distinct from `entitled: false` which
+     * implies "available, but not in your plan".
+     */
+    comingSoon?: boolean;
+};
+type CboxNotificationPreviewItem = {
+    id: string;
+    title: string;
+    body?: string | null;
+    severity: 'info' | 'warning' | 'critical';
+    /** ISO-8601 timestamp from the notifications service. */
+    createdAt: string;
+    /** Null when the user hasn't opened the notification yet. */
+    readAt?: string | null;
+    /** Optional deep-link — typically into the app that originated
+     *  the notification (id/billing/invoice/123, webhooks/deliveries/x).
+     *  Null when the notification is informational with no follow-up. */
+    ctaUrl?: string | null;
+    ctaLabel?: string | null;
+};
+type CboxNotificationsState = {
+    unreadCount: number;
+    /**
+     * "See all" target — typically the central notifications service
+     * inbox (notifications.cbox.systems/inbox). The bell's POPOVER
+     * shows the preview items inline; only this URL navigates the
+     * user out of the current app.
+     */
+    inboxUrl: string;
+    /**
+     * Last 5 items (mixed read/unread) for the bell-popover preview.
+     * Empty when the host hasn't fetched a preview yet — the bell
+     * still renders the badge from `unreadCount`. Falsy on
+     * pre-auth pages where the chrome shouldn't render the bell at all.
+     */
+    previewItems?: CboxNotificationPreviewItem[];
+    /**
+     * Endpoint pattern for marking a single notification read. The
+     * popover POSTs to `markReadUrl.replace('{id}', notification.id)`
+     * — a host-local route that forwards to the service via M2M.
+     */
+    markReadUrl?: string;
+};
+type CboxIdContextValue = {
+    user: CboxUser;
+    /**
+     * Org the current app context is scoped to. Null on user-only
+     * surfaces (eg the id account-settings landing page).
+     */
+    currentOrganization: CboxOrganization | null;
+    /**
+     * All orgs the user belongs to — feeds the org switcher.
+     * Should be small (≤ a few dozen). For users in many orgs,
+     * the switcher swaps in a search field.
+     */
+    organizations: CboxOrganization[];
+    /**
+     * Sister apps in the Cbox family the user can launch into.
+     * Static-ish — doesn't need to refresh per request.
+     */
+    apps: CboxAppLink[];
+    /**
+     * Deep-links into id used by chrome controls. Each app
+     * constructs these via the id-client SDK; the package
+     * doesn't hardcode URLs because id may live on different
+     * hosts in dev / staging / prod.
+     */
+    urls: {
+        /** Base of the id app — for the "manage account" link. */
+        idBaseUrl: string;
+        /** Absolute URL of the user's id profile page. */
+        accountUrl: string;
+        /** Absolute URL of the current org's settings page in id. */
+        orgSettingsUrl: string | null;
+        /** POST endpoint that signs the user out. */
+        signOutUrl: string;
+        /**
+         * POST endpoint in id that switches the user's active org.
+         * Used by OrgSwitcher as a fallback when `onSwitchOrganization`
+         * is not provided — covers apps that can't do a pure URL swap.
+         */
+        switchOrgUrl?: string;
+    };
+    /**
+     * Notification feed state, or null/undefined when the user has no
+     * inbox configured. id's wire shape sets `null` explicitly; the
+     * type accepts both shapes so apps can pass the payload straight
+     * through without a null→undefined adapter.
+     */
+    notifications?: CboxNotificationsState | null;
+    /**
+     * True when the host app's cached payload is known to be out of
+     * date — id has emitted a domain event (membership/role/sub
+     * change) since the cache was populated. Apps should refetch
+     * via the SDK before rendering anything that depends on the
+     * cached membership / entitlement state. Soft-TTL covers the
+     * case where the event was missed.
+     *
+     * Default: false (treated as fresh).
+     */
+    stale?: boolean;
+    /**
+     * Called when the user picks a different org from the switcher.
+     * Apps own this — typically a same-app URL navigation that
+     * swaps the slug in the current path (`/org/{slug}/...`). The
+     * server validates membership at the destination via
+     * EnsureOrganizationMembership, so this is a pure URL change with
+     * no mutable state to update.
+     */
+    onSwitchOrganization?: (org: CboxOrganization) => void;
+};
+declare function CboxIdProvider({ value, children, }: {
+    value: CboxIdContextValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useCboxId(): CboxIdContextValue;
+/**
+ * Soft variant — returns null instead of throwing. Useful for
+ * components that gracefully degrade on auth-pre pages.
+ */
+declare function useCboxIdOptional(): CboxIdContextValue | null;
+
+type Props$7 = ComponentProps<'main'> & {
+    children: ReactNode;
+};
+/**
+ * Scrolling main column inside an <AppShell>. Wears the soft blue-
+ * tinted gradient canvas so every Cbox app sits on the same
+ * background.
+ */
+declare function AppContent({ children, className, ...props }: Props$7): react_jsx_runtime.JSX.Element;
+
+/**
+ * Top-level chrome. Hosts the desktop sidebar (left) and the
+ * scrollable content column (right) side-by-side. Fits the full
+ * viewport height; only the content column scrolls.
+ *
+ * Pair with <AppContent> inside. Per-app sidebars compose alongside
+ * — cbox-ui doesn't ship one because the nav items are app-specific.
+ */
+declare function AppShell({ children }: {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+type CboxNavItem = {
+    label: string;
+    /**
+     * Absolute path the host's router can navigate to. Apps that
+     * scope nav by org slug should compose the path themselves
+     * (`/org/${slug}/endpoints`) before passing it in — cbox-ui
+     * stays unaware of routing conventions.
+     */
+    href: string;
+    icon: ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+    }>;
+    /** Highlight the row for child routes too (`/endpoints/123`
+     *  matches the `Endpoints` row when this is true). */
+    matchPrefix?: boolean;
+};
+type CboxNavSection = {
+    label: string;
+    items: CboxNavItem[];
+};
+/**
+ * Generic Link contract — apps inject their own (Inertia's `Link`,
+ * Wouter, React Router, plain `<a>`). cbox-ui doesn't depend on
+ * any router so the same chrome works everywhere.
+ */
+type LinkComponent = ComponentType<{
+    href: string;
+    prefetch?: boolean;
+    children: ReactNode;
+    className?: string;
+    title?: string;
+    'aria-label'?: string;
+}>;
+type CboxAppSidebarProps = {
+    /** App key for the brand submark (and aria labels). */
+    appKey: string;
+    /** Optional override for the submark — defaults to `appKey`. */
+    brandSubmark?: string | null;
+    /** Where brand assets live. Default `/brand`. */
+    assetBase?: string;
+    /** Where the brand row links to (typically the app's home). */
+    brandHref?: string;
+    /** Nav sections — top to bottom. */
+    sections: CboxNavSection[];
+    /** Active path — used to highlight the current row. */
+    currentPath: string;
+    /** Apps inject their router's Link primitive. */
+    LinkComponent: LinkComponent;
+    /** Persisted "is the desktop sidebar collapsed?" state. */
+    collapsed?: boolean;
+    className?: string;
+};
+/**
+ * Standard Cbox sidebar. Every app wears this — the only variable
+ * bits are `sections` (per-app nav) and `appKey` (drives the brand
+ * submark).
+ *
+ * Hidden below `lg` — apps render a separate mobile drawer that
+ * shares the same `sections` config.
+ *
+ * No app should ship its own sidebar component. The chrome is the
+ * shape; nav items are the data.
+ */
+declare function CboxAppSidebar({ appKey, brandSubmark, assetBase, brandHref, sections, currentPath, LinkComponent, collapsed, className, }: CboxAppSidebarProps): react_jsx_runtime.JSX.Element;
+
+type CboxAppShellProps = {
+    /** App key — drives the brand submark + aria labels. */
+    appKey: string;
+    /** Override the submark text (defaults to appKey). */
+    brandSubmark?: string | null;
+    /** Asset base for brand pngs. Default `/brand`. */
+    assetBase?: string;
+    /** Brand row href (typically the app's home). */
+    brandHref?: string;
+    /** Sidebar nav config. */
+    sections: CboxNavSection[];
+    /** Active path — used by both sidebar (highlight) and topbar
+     *  (sidebar-collapse toggle aria state). */
+    currentPath: string;
+    /** Apps inject their router's Link primitive. */
+    LinkComponent: LinkComponent;
+    /** Persisted "sidebar collapsed?" state — owned by the host
+     *  (the cookie hook lives there). */
+    sidebarCollapsed?: boolean;
+    /** Click handler for the topbar collapse toggle. Hide the
+     *  toggle entirely by omitting this prop. */
+    onToggleSidebar?: () => void;
+    /**
+     * Topbar centre slot — typically the org switcher / context
+     * bar. Apps that aren't org-scoped (notifications, account
+     * pages) leave this off.
+     */
+    topbarCentre?: ReactNode;
+    /**
+     * Handler to open the in-app command palette / search UI.
+     * Always rendered — when omitted the trigger is a no-op so the
+     * chrome stays visually identical across all apps regardless of
+     * whether a palette has been wired up yet.
+     */
+    onSearchOpen?: () => void;
+    /**
+     * Override the right cluster on the topbar. Default:
+     * `[<SearchTrigger>?] <AppLauncher /> <NotificationsBell /> <UserMenu />`.
+     * Override only when an app needs a completely different mix.
+     */
+    topbarRightCluster?: ReactNode;
+    children: ReactNode;
+};
+/**
+ * Top-level Cbox application shell. Composes sidebar + topbar +
+ * content into the single chrome shape every Cbox app wears.
+ *
+ * Apps reduce to ~30 lines of layout: define nav, render
+ * `<CboxAppShell>{children}</CboxAppShell>`. No app should
+ * compose `<AppShell>`/`<AppContent>`/sidebar/topbar manually —
+ * drift is the whole reason this component exists.
+ */
+declare function CboxAppShell({ appKey, brandSubmark, assetBase, brandHref, sections, currentPath, LinkComponent, sidebarCollapsed, onToggleSidebar, topbarCentre, onSearchOpen, topbarRightCluster, children, }: CboxAppShellProps): react_jsx_runtime.JSX.Element;
+
+type CboxMobileNavDrawerProps = {
+    open: boolean;
+    onClose: () => void;
+    appKey: string;
+    brandSubmark?: string | null;
+    assetBase?: string;
+    brandHref?: string;
+    sections: CboxNavSection[];
+    currentPath: string;
+    LinkComponent: LinkComponent;
+};
+/**
+ * Mobile-only slide-in sidebar. Hidden on `lg` and up — there the
+ * desktop `CboxAppSidebar` is always visible. Shares the same
+ * `sections` shape as the desktop sidebar so apps don't have to
+ * maintain two nav configs.
+ *
+ * State (open/close) lives in `CboxAppShell` so it can wire the
+ * hamburger button + auto-close on `currentPath` change. The drawer
+ * itself just renders; it doesn't track anything.
+ *
+ * Closes on: Escape, scrim click, navigation (parent unsets `open`
+ * when `currentPath` changes). Locks body scroll while open so the
+ * page underneath doesn't scroll on touch.
+ */
+declare function CboxMobileNavDrawer({ open, onClose, appKey, brandSubmark, assetBase, brandHref, sections, currentPath, LinkComponent, }: CboxMobileNavDrawerProps): react_jsx_runtime.JSX.Element;
+
+type CboxBrandProps = {
+    /**
+     * App key — drives the small mono submark beside the wordmark.
+     * Convention: lowercase single word matching the `cbox_apps.key`
+     * row in id (`notifications`, `webhooks`, `id`, `cortex`, …).
+     */
+    appKey: string;
+    /**
+     * Override the submark text. Defaults to `appKey`. Hide it
+     * entirely with `submark={null}`.
+     */
+    submark?: string | null;
+    /** Asset base path. Default `/brand` — apps drop the standard
+     *  png set (`cbox-icon.png`, `cbox-logo.png`, plus `@2x` retina)
+     *  into `public/brand/` and they Just Work. */
+    assetBase?: string;
+    /** Tone of the wordmark. `dark` on light surfaces (default),
+     *  `light` on dark / coloured surfaces. */
+    tone?: 'dark' | 'light';
+    /** Collapsed mode renders only the square icon — used in the
+     *  collapsed-sidebar state. */
+    collapsed?: boolean;
+    className?: string;
+};
+/**
+ * Canonical Cbox brand mark. Every app wears this — the only
+ * variable bit is the `appKey` submark beside the wordmark
+ * ("notifications", "webhooks", …).
+ *
+ * No app should ship its own brand component. If a product needs
+ * a materially different mark, that's a cbox-ui PR (extend this
+ * component), not a per-app fork.
+ */
+declare function CboxBrand({ appKey, submark, assetBase, tone, collapsed, className, }: CboxBrandProps): react_jsx_runtime.JSX.Element;
+
+type CboxOrgContextBarProps = {
+    /**
+     * Apps inject their router's Link primitive — used for the
+     * crumb's brand-side anchor. The dropdown's onSelect calls
+     * `onNavigate(href)` so apps can either `router.visit(href)`
+     * (Inertia) or `<Link>`-style navigate.
+     */
+    LinkComponent: LinkComponent;
+    /**
+     * Called when the user picks a different org from the dropdown.
+     * Receives an absolute path with the slug substituted in. Apps
+     * trigger their router.
+     *
+     * Path-rewrite rule (Cbox suite convention):
+     *   /org/<old-slug>/foo/bar  →  /org/<new-slug>/foo/bar
+     *   /something-else          →  /org/<new-slug>
+     *
+     * Apps that aren't org-scoped (notifications) typically don't
+     * render this component at all — but if they do, switching
+     * lands on the new org's `/org/<slug>` root and lets the host
+     * sort the rest out.
+     */
+    onNavigate: (href: string) => void;
+};
+/**
+ * Standard Cbox topbar org switcher. One crumb, one dropdown,
+ * URL-driven (no POST, no session pin). Mirrors id's pattern 1:1
+ * so the chrome reads identically across the suite — that's the
+ * whole reason it's here, not in each app.
+ *
+ * Apps render this in the `topbarCentre` slot of `CboxAppShell`.
+ * Hides itself when there's no current org (eg pre-auth, or
+ * non-org-scoped surfaces).
+ */
+declare function CboxOrgContextBar({ LinkComponent, onNavigate, }: CboxOrgContextBarProps): react_jsx_runtime.JSX.Element | null;
+
+type Props$6 = {
+    /**
+     * App branding rendered on the left — typically a small logo +
+     * the app name. Rendered inside a fixed-height bar so keep it
+     * visually compact (24-32px tall content).
+     */
+    brand: ReactNode;
+    /** Anything between brand and the right cluster — search, breadcrumbs, etc. */
+    centre?: ReactNode;
+    /**
+     * Override slots if an app needs a different control mix in the
+     * right cluster. Default: AppLauncher → NotificationsBell → UserMenu.
+     */
+    rightCluster?: ReactNode;
+    /**
+     * Whether to show the org switcher next to the brand. Hide on
+     * non-org-scoped surfaces (eg id account-settings).
+     */
+    showOrgSwitcher?: boolean;
+    className?: string;
+};
+/**
+ * Standard Cbox top bar. Same shell across every app — keeps cross-app
+ * navigation (launcher, account, notifications) muscle-memory-stable.
+ */
+declare function TopBar({ brand, centre, rightCluster, showOrgSwitcher, className, }: Props$6): react_jsx_runtime.JSX.Element;
+
+type AppLauncherProps = {
+    className?: string;
+    /**
+     * Called when the user clicks an app they're not entitled to. Use
+     * this to open an upgrade flow / Stripe checkout / Intercom message.
+     * If unset, locked tiles fall through to a static "Add to plan"
+     * affordance — the click is a no-op so we never silently ship the
+     * user to a broken paywall.
+     */
+    onLockedAppClick?: (app: CboxAppLink) => void;
+};
+/**
+ * Cross-app launcher — the 9-dot button in the top bar.
+ *
+ * Renders the Cbox suite as a vertical list with status per app:
+ *   - entitled apps   → full-colour tile, click navigates with ?org=<slug>
+ *   - locked apps     → greyed out + lock badge, opens upgrade flow if the
+ *                       host app provides one (otherwise inert click)
+ *   - coming-soon     → greyed out + "soon" badge, never clickable
+ *   - the current app → highlighted ring on its monogram tile
+ *
+ * Row layout (vs. the old 3-col grid) gives us room for descriptions
+ * and status badges, which makes the entitlement signal readable at a
+ * glance instead of needing a tooltip.
+ */
+declare function AppLauncher({ className, onLockedAppClick }: AppLauncherProps): react_jsx_runtime.JSX.Element | null;
+
+type AppSwitcherProps = {
+    className?: string;
+    /**
+     * Called when the user clicks an app they're not entitled to. Use
+     * this to open an upgrade flow / Stripe checkout / Intercom message.
+     * If unset, locked rows fall through to a static "Add to plan"
+     * affordance — the click is a no-op so we never silently ship the
+     * user to a broken paywall.
+     */
+    onLockedAppClick?: (app: CboxAppLink) => void;
+};
+/**
+ * Left-cluster app picker — the dropdown button that sits beside OrgSwitcher.
+ *
+ * Shows the current app's monogram + name as the trigger so both context
+ * dimensions (which app, which org) are immediately visible in the left
+ * cluster without needing to open anything.
+ *
+ * The dropdown preserves the full AppLauncher row richness: monogram tile
+ * with per-app accent, name, description, and entitlement badges. Entitled
+ * apps are grouped first; locked / coming-soon land in an "Available" section.
+ *
+ * Includes typeahead — auto-focus on open, filters name/description/key as
+ * the user types, arrow-key navigation, Enter to activate, Escape to close.
+ *
+ * Soft-reads via useCboxIdOptional — renders null when no provider is
+ * mounted above (admin shells, pre-auth pages).
+ */
+declare function AppSwitcher({ className, onLockedAppClick }: AppSwitcherProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Bell with unread-count badge + popover preview. Click opens a
+ * dropdown with the last 5 items inline (no navigation), each with
+ * an inline mark-read action and an optional deep-link to the page
+ * that originated the notification. "See all" at the bottom links
+ * to the central notifications service inbox — the only navigation
+ * away from the host app.
+ *
+ * Pattern matches Linear / GitHub / Stripe: glance + mark-read
+ * without leaving context; cross-app jump only when the user
+ * explicitly wants the full list.
+ *
+ * Renders nothing if the context is missing or notifications
+ * aren't configured (eg pre-auth pages).
+ */
+declare function NotificationsBell({ className }: {
+    className?: string;
+}): react_jsx_runtime.JSX.Element | null;
+
+type Props$5 = {
+    /**
+     * Optional renderer override for the trigger so apps can match
+     * their topbar style (filled button vs ghost vs icon-only).
+     */
+    Trigger?: ComponentType<{
+        organization: CboxOrganization | null;
+        onClick: () => void;
+        open: boolean;
+    }>;
+    className?: string;
+};
+/**
+ * Dropdown that surfaces the user's orgs and dispatches the picked
+ * one through `onSwitchOrganization`. Reads everything else from
+ * CboxIdProvider so the same component works in id, cortex, atlas —
+ * no per-app data wiring.
+ *
+ * Includes typeahead — auto-focus on open, filters by name as the
+ * user types, arrow-key navigation, Enter to switch, Escape to close.
+ */
+declare function OrgSwitcher({ Trigger, className }: Props$5): react_jsx_runtime.JSX.Element;
+
+type Props$4 = {
+    /** Click handler — typically dispatches the app's command-palette
+     *  open shortcut. Apps that don't have a palette yet pass a no-op
+     *  so the chrome stays visually consistent across the suite. */
+    onOpen?: () => void;
+    className?: string;
+    label?: string;
+};
+/**
+ * Topbar Search trigger — a visual-only command-palette button.
+ *
+ * Hosted in cbox-ui because every Cbox app's chrome must show the
+ * same search affordance in the same spot, with the same width and
+ * the same shortcut hint. Drift across apps means users see layout
+ * shifts when tabbing between id / webhooks / cortex; that's a UX
+ * tax we don't want to charge them.
+ *
+ * The actual palette stays per-app (commands differ); this primitive
+ * just renders the trigger and dispatches `onOpen`.
+ */
+declare function SearchTrigger({ onOpen, className, label }: Props$4): react_jsx_runtime.JSX.Element;
+
+type Props$3 = {
+    /**
+     * App-specific menu items rendered above the standard
+     * "Manage account" / "Sign out" set. Use sparingly — the goal
+     * is consistency across apps.
+     */
+    extras?: ReactNode;
+    className?: string;
+};
+/**
+ * User-menu dropdown. Always exposes:
+ *   - Manage account ↗   (deep-link into id)
+ *   - Team & billing ↗   (deep-link into id, current org scope)
+ *   - Sign out
+ *
+ * The arrows signal cross-app navigation — id is canonical.
+ */
+declare function UserMenu({ extras, className }: Props$3): react_jsx_runtime.JSX.Element;
+
+/**
+ * Combobox — the canonical select replacement for the Cbox suite.
+ *
+ * **Native `<select>` is forbidden.** It can't host avatars, can't
+ * be searched, can't be styled into the design system, and on mobile
+ * it pops the OS picker which breaks the visual contract. Combobox
+ * solves all of that with a single primitive:
+ *
+ *   - Type-ahead filter on the search input (case-insensitive,
+ *     matches label + secondary).
+ *   - Keyboard contract: ArrowDown / ArrowUp move highlight, Enter
+ *     selects, Escape closes, Home/End jump to bounds, Tab exits.
+ *   - Optional avatar per option, optional secondary line.
+ *   - Optional grouped sections with mono-tracked headers.
+ *   - Optional footer link (eg "+ New environment").
+ *   - Empty-state copy when the filter excludes everything.
+ *
+ * Two modes:
+ *   - Value mode (default): `value` + `onChange` — Combobox manages
+ *     selection state, host treats it like a controlled input.
+ *   - Navigation mode: items carry `href` and `LinkComponent` is
+ *     supplied — clicking an item is a Link visit, not a state mutation.
+ *
+ * Both modes are URL/router-friendly. Value mode is for filter
+ * controls; navigation mode is for context switchers (the Combobox
+ * inside a ContextBar crumb is exactly this).
+ */
+type ComboboxOption = {
+    /** Stable key. Used as React key and for active-state matching. */
+    value: string;
+    /** Visible label — primary line. */
+    label: string;
+    /** Optional secondary line — slug, role, environment, hint. */
+    secondary?: string;
+    /** Optional leading icon (lucide-style — h-3.5 w-3.5). */
+    icon?: ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+    }>;
+    /**
+     * Optional avatar — image src OR `{initials,accent}` chip. When
+     * the option carries an avatar, the trigger renders one too if
+     * the option is the active selection.
+     */
+    avatar?: ComboboxAvatar;
+    /** Disable selection of this option. */
+    disabled?: boolean;
+    /**
+     * Hidden text added to the searchable haystack. Useful for
+     * synonyms ("United States" should match "USA", "us"). Not
+     * displayed.
+     */
+    keywords?: string[];
+    /**
+     * Optional href for navigation mode. When set + LinkComponent is
+     * supplied, clicking the option navigates instead of mutating
+     * value state.
+     */
+    href?: string;
+};
+type ComboboxGroup = {
+    /** Group heading — uppercase mono-tracked. Empty string hides the heading. */
+    label: string;
+    options: ComboboxOption[];
+};
+type ComboboxAvatar = {
+    initials?: string;
+    accent?: string;
+    src?: string;
+};
+type LinkComp$1 = ComponentType<{
+    href: string;
+    prefetch?: boolean;
+    className?: string;
+    children: ReactNode;
+}>;
+type CommonProps = {
+    /** Options or grouped options. Pass an array of either shape. */
+    items: ComboboxOption[] | ComboboxGroup[];
+    /** Placeholder shown in the trigger when no value is selected. */
+    placeholder?: string;
+    /** Search input placeholder. */
+    searchPlaceholder?: string;
+    /** Empty-state copy when the filter matches nothing. */
+    emptyText?: string;
+    /** Optional footer link below the option list ("+ New X"). */
+    footerLink?: {
+        label: string;
+        href: string;
+    };
+    /** Disable the entire combobox (greyed-out trigger). */
+    disabled?: boolean;
+    /** Required-field marker on the trigger. */
+    required?: boolean;
+    /** Aria-label for the trigger. */
+    ariaLabel?: string;
+    /** Trigger className override. Doesn't change padding/height. */
+    triggerClassName?: string;
+    /** Dropdown panel className override. */
+    panelClassName?: string;
+    /** Width policy for the trigger. Defaults to `auto` (intrinsic). */
+    triggerWidth?: 'auto' | 'full';
+    /**
+     * Framework Link adapter for navigation-mode items + footer link.
+     * If unset, navigation falls back to plain `<a>`.
+     */
+    LinkComponent?: LinkComp$1;
+    /** ID for the trigger button (associate with a <Label htmlFor>). */
+    id?: string;
+    /** className for the outer wrapper. */
+    className?: string;
+};
+type ValueModeProps = CommonProps & {
+    /** Selected value or `null` when nothing is selected. */
+    value: string | null;
+    /** Called with the option's `value` when the user picks one. */
+    onChange: (value: string) => void;
+};
+type NavModeProps = CommonProps & {
+    /** Active value for highlight purposes. Optional in nav mode. */
+    value?: string | null;
+    /**
+     * Omitted in nav mode. Items must carry `href`, and a
+     * LinkComponent must be supplied for SPA navigation.
+     */
+    onChange?: never;
+};
+type ComboboxProps = ValueModeProps | NavModeProps;
+declare function Combobox(props: ComboboxProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ContextBar — the topbar breadcrumb-style context selector. One
+ * crumb per level of context (org / project / environment / branch /
+ * deployment). Each crumb renders as a chip (avatar + label +
+ * chevron) and opens a dropdown with the items at that level plus
+ * an optional "+ New X" footer.
+ *
+ * The pattern is the cloud-platform default — Vercel, Render, Forge,
+ * GitHub, Stripe, Cortex all use it. Topbar carries identity and
+ * context; sidebar carries navigation. The two never overlap.
+ *
+ * URL-driven by default — clicking a dropdown item navigates via the
+ * supplied `LinkComponent`. Apps that need a non-navigational select
+ * (post a form, mutate session state) pass `onSelect` instead.
+ *
+ * Separator between crumbs is a muted slash — same as Forge / Cortex.
+ */
+type ContextAvatar = {
+    /** 1–2 character monogram. Defaults to first letter of the label. */
+    initials?: string;
+    /**
+     * Hex / CSS colour applied as the avatar's bg. Falls back to the
+     * neutral chip when missing. Per-item override of the default.
+     */
+    accent?: string;
+    /** Optional avatar image URL — overrides initials when set. */
+    src?: string;
+};
+type ContextItem = {
+    /** Stable identity for the item (slug, id). */
+    id: string;
+    /** Primary display label. */
+    label: string;
+    /** Optional secondary line — slug, role, env name. Mono-tracked. */
+    secondary?: string;
+    /** Avatar specification. Same shape as the crumb's own avatar. */
+    avatar?: ContextAvatar;
+    /** Navigation target — clicking the item navigates here. */
+    href?: string;
+    /** Mark the item as the active selection (gets a check on the right). */
+    current?: boolean;
+    /**
+     * Optional href to a settings page for this item. When set, a
+     * cogwheel button appears on the right of the row on hover/focus
+     * — clicking it navigates straight to settings without going
+     * through the item's normal selection. Cortex-style shortcut.
+     */
+    settingsHref?: string;
+    /**
+     * Aria-label for the optional settings cogwheel. Defaults to
+     * `Settings for <label>`. Override when the label alone isn't
+     * enough context (eg multiple items with the same name).
+     */
+    settingsAriaLabel?: string;
+};
+type ContextCrumb = {
+    /** Stable identity for the crumb (used as React key). */
+    id: string;
+    /** The chip's visible label — typically the active item's name. */
+    label: string;
+    /** The chip's avatar — typically the active item's avatar. */
+    avatar?: ContextAvatar;
+    /** Items shown in the dropdown. Empty array = chip with no menu. */
+    items: ContextItem[];
+    /**
+     * Optional footer link below the items — typically "+ New X" or
+     * "Manage Y". Renders with a + icon and an accent text colour.
+     */
+    footerLink?: {
+        label: string;
+        href: string;
+    };
+    /**
+     * Override per-item navigation. When set, item clicks call this
+     * with the item's id instead of navigating to `item.href`. Useful
+     * for posting a form (eg an org switcher that POSTs to a server-side
+     * endpoint).
+     */
+    onSelect?: (itemId: string) => void;
+    /** Optional aria-label for the chip's button (defaults to "Switch <label>"). */
+    ariaLabel?: string;
+};
+type LinkComp = ComponentType<{
+    href: string;
+    prefetch?: boolean;
+    className?: string;
+    children: ReactNode;
+}>;
+type Props$2 = {
+    crumbs: ContextCrumb[];
+    /**
+     * The framework's link component. Inertia consumers pass the
+     * Inertia Link; TanStack Router consumers pass their typed Link.
+     * Plain `<a>` is the fallback.
+     */
+    LinkComponent?: LinkComp;
+    className?: string;
+};
+declare function ContextBar({ crumbs, LinkComponent, className, }: Props$2): react_jsx_runtime.JSX.Element | null;
+declare function ContextAvatarChip({ avatar, fallbackLabel, size, }: {
+    avatar: ContextAvatar;
+    fallbackLabel: string;
+    size?: 'sm' | 'md';
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Generic panel container — soft border, card surface, subtle shadow.
+ * The default building block for every section on a page.
+ */
+declare function DataPanel({ className, children, ...rest }: ComponentProps<'section'>): react_jsx_runtime.JSX.Element;
+type SectionHeaderProps = {
+    title: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+    className?: string;
+};
+/**
+ * Section header that sits inside a DataPanel. Title in semibold sans,
+ * optional muted lead, right-aligned actions slot.
+ */
+declare function SectionHeader({ title, description, actions, className, }: SectionHeaderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Vertically padded content body for a DataPanel.
+ */
+declare function PanelBody({ className, children, ...rest }: ComponentProps<'div'>): react_jsx_runtime.JSX.Element;
+
+type EmptyStateProps = {
+    icon?: LucideIcon;
+    title: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+    className?: string;
+};
+/**
+ * Centered empty state with an optional icon block, title, body
+ * lede, and a single CTA slot.
+ */
+declare function EmptyState({ icon: Icon, title, description, action, className, }: EmptyStateProps): react_jsx_runtime.JSX.Element;
+
+declare function Heading({ title, description, variant, }: {
+    title: string;
+    description?: string;
+    variant?: 'default' | 'small';
+}): react_jsx_runtime.JSX.Element;
+
+type KeyValueProps = {
+    label: string;
+    children: ReactNode;
+    /** Render the value in monospace. Default true — most values are technical. */
+    mono?: boolean;
+    className?: string;
+};
+/**
+ * Two-column read-only field row. Label in mono caps, value in mono
+ * by default (for slugs/IDs/dates) — pass `mono={false}` for prose.
+ */
+declare function KeyValue({ label, children, mono, className, }: KeyValueProps): react_jsx_runtime.JSX.Element;
+declare function KeyValueList({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+
+type Props$1 = {
+    title: ReactNode;
+    /**
+     * Tiny uppercase lead-in above the title (sections, breadcrumb-light
+     * disambiguation). Shown in mono-tracking caps so it reads as
+     * meta, not as a competing heading.
+     */
+    eyebrow?: ReactNode;
+    description?: ReactNode;
+    actions?: ReactNode;
+    className?: string;
+};
+/**
+ * Title block at the top of every page. Big bold title, optional mono
+ * eyebrow lead-in, muted lead, optional right-aligned actions slot.
+ * Cortex-style — no italics, no brackets — so it carries across many
+ * sibling apps cleanly.
+ */
+declare function PageHeader({ title, eyebrow, description, actions, className, }: Props$1): react_jsx_runtime.JSX.Element;
+
+/**
+ * Width policy for `<PageShell>` — the single horizontal-rhythm
+ * primitive every Cbox-family app shares. Pick the policy that
+ * matches the page's content density:
+ *
+ *   comfortable   max-w-6xl (~1152px) — the default. Reading-friendly
+ *                 column for prose-heavy pages: profile, security,
+ *                 billing forms, audit row detail.
+ *   wide          max-w-7xl (~1280px) — for tables / lists / member
+ *                 rosters where horizontal real estate matters more
+ *                 than reading line length. Audit log, member roster,
+ *                 plan comparison.
+ *   full          no max-width, only the standard horizontal padding —
+ *                 for canvas-heavy pages (flow diagrams, dashboards)
+ *                 where every pixel of viewport should be usable. Use
+ *                 sparingly: raw width without column rules feels
+ *                 chaotic on monitors past 1600px.
+ *   bleed         no max-width AND no horizontal padding. Strict edge
+ *                 -to-edge for content that draws its own padding (a
+ *                 flow canvas with its own pan/zoom region, a fullscreen
+ *                 iframe, an embedded preview environment).
+ */
+type PageWidth = 'comfortable' | 'wide' | 'full' | 'bleed';
+type Props = {
+    children: ReactNode;
+    width?: PageWidth;
+    className?: string;
+};
+/**
+ * The page-level container. Picks one of four width policies (see
+ * PageWidth) and applies the canonical Cbox padding / vertical
+ * rhythm. Every authenticated page in every Cbox app composes
+ * through this — directly via `<PageShell>` or, more usually, via
+ * the per-app `<Page>` wrapper that combines PageShell + PageHeader
+ * + PageTabs.
+ *
+ * Width policy is the only knob exposed here. Padding, max-width,
+ * gutter, vertical spacing between blocks — those are baked in so
+ * the eye never has to track horizontal jitter between sibling
+ * pages.
+ */
+declare function PageShell({ children, width, className, }: Props): react_jsx_runtime.JSX.Element;
+
+/**
+ * Section navigation: every "tab" is a real page with its own URL.
+ * No internal active-state, no callbacks — the host's router is the
+ * source of truth. This is what makes deep links and hard refreshes
+ * lossless: paste any URL, the right tab is active and the right
+ * panel renders, with no client-side coordination required.
+ *
+ * Layout:
+ *   ≥ sm    horizontal underline strip + optional `actions` slot to
+ *           the right; sticky just under the TopBar with a hairline
+ *           border-bottom and a backdrop-blur for the scroll-into
+ *           effect.
+ *   < sm    dropdown showing the active tab + chevron; opens a panel
+ *           with the full list. Actions reflow below the trigger.
+ *
+ * The same primitive runs the section nav across every Cbox app. It
+ * lives here so that the visual contract is single-sourced — there's
+ * no way for a feature page to invent its own slightly-different tab
+ * strip.
+ */
+type PageTabSpec = {
+    /** Display label. Truncates inline if it overflows the strip. */
+    label: string;
+    /** Absolute or app-relative href. The host router renders this. */
+    href: string;
+    /**
+     * Optional leading icon. Constrained to the icon shape we use
+     * everywhere — this is how cbox-ui keeps icon weights aligned
+     * across primitives without depending on `lucide-react`.
+     */
+    icon?: ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+    }>;
+    /**
+     * Optional badge — a count, status pill, or "new" indicator. Use
+     * sparingly; one badge in a row is signal, three is noise.
+     */
+    badge?: ReactNode;
+    /**
+     * Numeric count rendered inline. Convenience for the common
+     * "Members 12" pattern; mutually exclusive with `badge` (badge
+     * wins if both are set).
+     */
+    count?: number;
+    /**
+     * Match the current path by prefix. Use for hub pages whose
+     * nested routes should still highlight the parent tab — e.g.
+     * `/org/<slug>/members` highlights when on
+     * `/org/<slug>/members/<id>`.
+     */
+    matchPrefix?: boolean;
+};
+type PageTabsProps = {
+    items: PageTabSpec[];
+    /** Current pathname, host-supplied. Drives active-state matching. */
+    currentPath: string;
+    /**
+     * The framework's link component. Inertia consumers pass the
+     * Inertia `Link`; TanStack Router consumers pass their typed
+     * `Link`; plain anchors are the fallback. We never invent
+     * navigation here.
+     */
+    LinkComponent?: ComponentType<{
+        href: string;
+        prefetch?: boolean;
+        className?: string;
+        children: ReactNode;
+        'aria-current'?: 'page' | undefined;
+    }>;
+    /**
+     * Right-aligned slot on desktop, reflowed under the dropdown on
+     * mobile. Use for primary section actions (Invite, Add token,
+     * Export…) that belong to the section as a whole rather than the
+     * specific tab. The slot is always reserved on desktop so pages
+     * with and without actions keep identical row geometry — no
+     * layout shift between sibling tabs.
+     */
+    actions?: ReactNode;
+    className?: string;
+};
+declare function PageTabs({ items, currentPath, LinkComponent, actions, className, }: PageTabsProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * A clickable list row — replaces the "name on left + Manage button on
+ * right" pattern with a row that's clickable as a single Link, with a
+ * visible hover state and a focus ring. Trailing content (badges,
+ * action buttons) sits in the `trailing` slot, which renders alongside
+ * the body but stops click-propagation on any nested interactive
+ * control so action buttons there don't trigger row navigation.
+ *
+ *   <RowLink href={editOrg(slug).url} LinkComponent={Link}>
+ *       <Avatar />
+ *       <div>
+ *           <p>Cbox Systems</p>
+ *           <p className="text-mono">cbox-systems</p>
+ *       </div>
+ *   </RowLink>
+ *
+ * With trailing actions:
+ *
+ *   <RowLink href={...} trailing={<StatusPill>owner</StatusPill>}>
+ *
+ * Hit target: the entire row. The Link wraps all content directly so
+ * every pixel inside the row is clickable, including the trailing
+ * area's whitespace. Interactive controls inside `trailing` (buttons,
+ * inputs, anchors, role="button") auto-stop the click via the
+ * onClickCapture handler — no per-button stopPropagation boilerplate.
+ */
+type RowLinkProps = {
+    /** Destination URL — clicking anywhere on the row navigates here. */
+    href: string;
+    /** Row body. Compose freely; common pattern is avatar + text block. */
+    children: ReactNode;
+    /**
+     * Right-aligned slot. Status pills, action buttons, kebab menus.
+     * Interactive controls inside this slot auto-stop the row click
+     * via DOM-traversal (button/a/input/select/textarea/[role=button]
+     * /[data-stop-row-click]). No manual stopPropagation needed.
+     */
+    trailing?: ReactNode;
+    /**
+     * The framework's link component. Inertia consumers pass the
+     * Inertia `Link`; TanStack Router consumers pass their typed
+     * `Link`. Plain `<a>` is the fallback.
+     */
+    LinkComponent?: ComponentType<{
+        href: string;
+        prefetch?: boolean;
+        className?: string;
+        children: ReactNode;
+    }>;
+    /** Highlight as the active row (the user's current selection). */
+    active?: boolean;
+    /** Additional classes for the row container. */
+    className?: string;
+};
+declare function RowLink({ href, children, trailing, LinkComponent, active, className, }: RowLinkProps): react_jsx_runtime.JSX.Element;
+
+type Tone$1 = 'info' | 'success' | 'warning' | 'destructive' | 'neutral';
+type StatTileProps = {
+    label: string;
+    value: ReactNode;
+    /** Small caption under the value. */
+    suffix?: ReactNode;
+    icon: LucideIcon;
+    tone?: Tone$1;
+    className?: string;
+};
+/**
+ * Cortex-style metric tile. Coloured square icon block on the left,
+ * label + value on the right, optional caption below the value.
+ */
+declare function StatTile({ label, value, suffix, icon: Icon, tone, className, }: StatTileProps): react_jsx_runtime.JSX.Element;
+
+type Tone = 'neutral' | 'info' | 'success' | 'warning' | 'destructive' | 'muted';
+type StatusPillProps = {
+    children: React.ReactNode;
+    tone?: Tone;
+    className?: string;
+    /** Show a small dot before the label for "live status" feel. */
+    dot?: boolean;
+};
+/**
+ * Compact pill for plan tier, role, status, etc. Rounded-full like
+ * Cortex's "Running"/"Production" tags. Sized for tabular density,
+ * not editorial impact.
+ */
+declare function StatusPill({ children, tone, className, dot, }: StatusPillProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Cross-app surface contract — the API hosts opt into and that
+ * cbox-ui's runtime renders. Each `SurfaceId` corresponds to a
+ * concrete surface implementation shipped by cbox-ui.
+ *
+ * Surfaces are intentionally a closed set. Adding a new surface
+ * is a cbox-ui PR; hosts can't invent their own. That's the
+ * discipline that keeps the chrome from drifting back into per-app
+ * land.
+ *
+ * The criterion for accepting a new surface: "would it be useful
+ * in *every* Cbox app?" Inbox yes. Search yes. Help yes. "Webhook
+ * delivery details" no — that's a route inside webhooks, not a
+ * cross-app overlay.
+ */
+
+type SurfaceId = 'inbox' | 'search' | 'activity' | 'help';
+type SurfaceArgs = {
+    inbox: {
+        focusUnread?: boolean;
+    };
+    search: {
+        initialQuery?: string;
+    };
+    activity: {
+        scope?: 'user' | 'org';
+    };
+    help: {
+        topic?: string;
+    };
+};
+/**
+ * Auth + transport plumbing the host injects. cbox-ui's surface
+ * implementations call these to reach backend services. The token
+ * function is async + cached so the host can implement it via a
+ * server-side proxy (cookie-authed) or against an in-memory access
+ * token (pure SPA) — both end up callable.
+ */
+type Transport = {
+    /**
+     * Per-service base URLs. Surfaces look these up by service key.
+     * A host can leave a key unset to disable surfaces that depend on it.
+     */
+    urls: Partial<{
+        notifications: string;
+        search: string;
+        audit: string;
+        realtime: string;
+    }>;
+    /**
+     * Mint or fetch a fresh bearer token for a given audience.
+     * cbox-ui caches the result until `expiresAt` minus a 60-second
+     * guard, so the host implementation can be a real HTTP call.
+     */
+    getToken: (audience: string) => Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Optional CSRF token for host-shaped routes (mark-read
+     * forwarders that go through the host's cookie session). Pure
+     * SPA hosts can leave this off.
+     */
+    csrfToken?: () => string;
+};
+type SurfaceConfig = Partial<{
+    search: {
+        placeholder?: string;
+        scopes?: string[];
+    };
+    inbox: {};
+}>;
+/**
+ * Imperative API hosts use to open/close surfaces. Returned from
+ * `useCboxSurfaces()`. The runtime guarantees:
+ *
+ *   - At most one surface open at a time. `open` replaces the
+ *     active surface if any.
+ *   - `Escape` closes the active surface (modal/drawer dismiss).
+ *   - Navigation (Inertia visit, history change) closes the active
+ *     surface so users don't land in another section with a stale
+ *     overlay still up.
+ */
+type SurfaceController = {
+    activeSurface: SurfaceId | null;
+    open: <K extends SurfaceId>(id: K, args?: SurfaceArgs[K]) => void;
+    close: () => void;
+};
+/**
+ * Inbox preview state — surfaced to the bell badge (chrome) even
+ * when the inbox surface itself isn't open. The runtime keeps this
+ * live by listening to realtime events; chrome reads it to render
+ * the unread count without round-tripping the server on every
+ * navigation.
+ *
+ * (Realtime is a follow-up session; the v1 implementation hydrates
+ * from the host's CboxIdProvider notifications state and updates
+ * only when the inbox surface explicitly mutates.)
+ */
+type InboxState = {
+    unreadCount: number;
+    /** ISO timestamp of last successful fetch. */
+    lastFetchedAt: string | null;
+};
+type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'unauthorized' | 'unsupported';
+/**
+ * Shape returned from `useCboxRealtime()` — host code rarely needs
+ * this directly; surfaces consume it internally. Exposed so chrome
+ * components (the bell) can show a connection-state indicator if
+ * desired.
+ */
+type RealtimeState = {
+    status: RealtimeStatus;
+};
+type CboxSurfacesProps = {
+    transport: Transport;
+    surfaces: SurfaceId[];
+    config?: SurfaceConfig;
+    /** Host renders this. cbox-ui mounts the surface runtime + any
+     *  active overlay alongside. */
+    children?: ReactNode;
+};
+
+/**
+ * Mount the cbox-ui surface runtime once per app, alongside the
+ * page tree. The host's chrome (bell, search trigger) reads
+ * `useCboxSurfaces()` to open surfaces; cbox-ui renders the
+ * active one as a modal/drawer over the page.
+ *
+ * Exactly one CboxSurfaces should be in the tree — typically right
+ * inside CboxAppShell. Multiple instances would race their state
+ * machines.
+ */
+declare function CboxSurfaces({ transport, surfaces, config, children, }: CboxSurfacesProps): react_jsx_runtime.JSX.Element;
+/**
+ * Imperative API for triggering surfaces from anywhere in the
+ * host page. The bell-popover's "See all" calls
+ * `useCboxSurfaces().open('inbox')` instead of navigating.
+ */
+declare function useCboxSurfaces(): SurfaceController;
+/**
+ * Optional variant — returns `null` when no `<CboxSurfaces>` host is
+ * mounted. Chrome controls (bell, search trigger) use this to
+ * degrade gracefully to cross-app navigation when the host hasn't
+ * opted into the surface runtime yet.
+ */
+declare function useCboxSurfacesOptional(): SurfaceController | null;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * URL-as-state — typed query-string parsing and serialization.
+ *
+ * The contract: anything that should survive a hard refresh, deep
+ * link, or paste-share lives in the URL, not in React state. Tabs,
+ * filters, search terms, pagination, sort order — every one of those
+ * is a navigation, not a UI mutation. This module provides the typed
+ * parsers and serializers; per-app adapters wire them to the host
+ * router (Inertia's `router.get`, TanStack Router's `navigate`, etc.)
+ * and shape the `[state, update]` ergonomics on top.
+ *
+ * Why not URLSearchParams directly? Because raw query strings throw
+ * away types and have no notion of defaults. The schema declares both
+ * once, and `buildUrlSearch` automatically elides values that match
+ * their default so the URL stays human-readable. `?role=all&page=1`
+ * collapses to `''` when `all` and `1` are the defaults. Going from
+ * `state -> URL -> state` always round-trips.
+ */
+/**
+ * A single field in a URL schema. Encapsulates the three operations
+ * that make typed URL state work:
+ *   - `parse(raw)`   — string|null from the query string → typed value
+ *   - `serialize(v)` — typed value → string|null (null = drop the key)
+ *   - `isDefault(v)` — does this value equal the field's default? If
+ *                     so, `buildUrlSearch` elides it to keep URLs short.
+ */
+type UrlField<T> = {
+    parse: (raw: string | null) => T;
+    serialize: (value: T) => string | null;
+    isDefault: (value: T) => boolean;
+};
+type UrlSchema = Record<string, UrlField<any>>;
+/**
+ * Map a UrlSchema to its inferred state shape — `urlString('')` →
+ * `string`, `urlEnum(['a', 'b'], 'a')` → `'a' | 'b'`, etc.
+ */
+type InferUrlState<S extends UrlSchema> = {
+    [K in keyof S]: S[K] extends UrlField<infer T> ? T : never;
+};
+/**
+ * String field. The empty string is the conventional "absent" value
+ * — it's what an HTML input gives you when the user clears it — so
+ * we treat `'' === default` as "drop the param" by default. Pass an
+ * explicit non-empty default if you genuinely want to persist `''`.
+ */
+declare function urlString(defaultValue?: string): UrlField<string>;
+/**
+ * Integer field with optional clamping. Non-numeric input falls back
+ * to the default rather than NaN; out-of-range input clamps to the
+ * boundary. Both behaviours are belt-and-braces against URL tampering.
+ */
+declare function urlNumber(defaultValue: number, options?: {
+    min?: number;
+    max?: number;
+}): UrlField<number>;
+/**
+ * Enum field — restrict to a fixed set of strings. Unknown values
+ * fall back to the default rather than poisoning typed downstream
+ * code with arbitrary user input. The `as const` on the values array
+ * is what lets TS narrow the field type to the union.
+ */
+declare function urlEnum<T extends string>(values: readonly T[], defaultValue: T): UrlField<T>;
+/**
+ * Boolean field. Only the literal string `'true'` parses to true so
+ * we don't accidentally interpret `?flag=0` or `?flag=false` as truthy.
+ */
+declare function urlBoolean(defaultValue?: boolean): UrlField<boolean>;
+/**
+ * Array-of-strings field — comma-joined in the URL. Useful for
+ * multi-select filters (`?tags=foo,bar,baz`). Empty arrays drop the
+ * param. Per-item parsing isn't customisable on purpose; if you need
+ * a typed array of enums or numbers, build a thin wrapper.
+ */
+declare function urlStringArray(defaultValue?: readonly string[]): UrlField<string[]>;
+/**
+ * Convenience: declare a schema. Pure passthrough — exists to give
+ * call sites a single, named import that reads like a definition
+ * rather than a bare object literal.
+ */
+declare function defineUrlSchema<S extends UrlSchema>(schema: S): S;
+/**
+ * Parse a query string into a typed state object. Accepts both
+ * leading-`?` and bare forms. Unknown keys are silently dropped —
+ * the schema is the closed allow-list, which keeps server- and
+ * client-readable surface area bounded.
+ */
+declare function parseUrlSearch<S extends UrlSchema>(search: string, schema: S): InferUrlState<S>;
+/**
+ * Serialize a typed state back to a query string. Default-valued
+ * fields are elided so URLs stay short and bookmarks stay portable
+ * across schema changes (a URL with `?page=1` keeps working when
+ * `page` later stops being serialised because it's the default).
+ *
+ * Returns the serialised query without a leading `?`. The host
+ * adapter is responsible for prepending or stitching it onto a path.
+ */
+declare function buildUrlSearch<S extends UrlSchema>(state: InferUrlState<S>, schema: S): string;
+
+export { AppContent, AppLauncher, AppShell, AppSwitcher, type CboxAppKey, type CboxAppLink, CboxAppShell, type CboxAppShellProps, CboxAppSidebar, type CboxAppSidebarProps, CboxBrand, type CboxBrandProps, type CboxIdContextValue, CboxIdProvider, CboxMobileNavDrawer, type CboxMobileNavDrawerProps, type CboxNavItem, type CboxNavSection, type CboxNotificationPreviewItem, type CboxNotificationsState, CboxOrgContextBar, type CboxOrgContextBarProps, type CboxOrganization, CboxSurfaces, type CboxSurfacesProps, type CboxUser, Combobox, type ComboboxAvatar, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type ContextAvatar, ContextAvatarChip, ContextBar, type ContextCrumb, type ContextItem, DataPanel, EmptyState, Heading, type InboxState, type InferUrlState, KeyValue, KeyValueList, type LinkComponent, NotificationsBell, OrgSwitcher, PageHeader, PageShell, type PageTabSpec, PageTabs, type PageTabsProps, type PageWidth, PanelBody, type RealtimeState, type RealtimeStatus, RowLink, type RowLinkProps, SearchTrigger, SectionHeader, StatTile, StatusPill, type SurfaceArgs, type SurfaceConfig, type SurfaceController, type SurfaceId, TopBar, type Transport, type UrlField, type UrlSchema, UserMenu, buildUrlSearch, cn, defineUrlSchema, parseUrlSearch, urlBoolean, urlEnum, urlNumber, urlString, urlStringArray, useCboxId, useCboxIdOptional, useCboxSurfaces, useCboxSurfacesOptional };