@meetreeve/ui 0.11.0 → 0.13.0

package/README.md

@@ -158,6 +158,35 @@ 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).
 
+## InfoTip (DEV-11387)
+
+A "?" circle that reveals a short explanation, so a page can keep caveats and
+definitions one hover away instead of as paragraphs of body copy.
+
+```tsx
+import { InfoTip } from "@meetreeve/ui";
+
+<h2>Human review required</h2>
+<InfoTip label="About human review">
+  These networks are withheld from buying groups until a person checks the evidence.
+</InfoTip>;
+```
+
+Built on Base UI's Popover, not a tooltip, because a tooltip never opens on
+touch: hover opens it for mouse users, click/tap and Enter/Space open it
+everywhere, and Escape or an outside click closes it. `side`/`align` set the
+preferred placement and the bubble flips near a viewport edge.
+
+The trigger keeps the 44px `MIN_SIZES.touchTarget` floor while its glyph is
+16px. The extra height is cancelled so it sits inline in a heading without
+changing the line height, but the full 44px of width stays in the layout — the
+hit area never overlaps the text beside it, so expect the glyph to look
+generously spaced rather than tight against its heading.
+The bubble is portalled to `<body>` and styles from the host's theme tokens, so
+the host must define `--color-popover`, `--color-popover-foreground`,
+`--color-border` and `--color-ring`, and Tailwind consumers must include this
+package's `dist` as a `@source` (see ResponsiveHeader above).
+
 ## Tokens
 
 ```ts

package/dist/index.d.mts

@@ -206,6 +206,35 @@ declare function ResponsiveHeader({ brand, search, nav, brandHref, linkComponent
  */
 declare function useResponsivePlaceholder(desktop: string, mobile?: string): string;
 
+interface InfoTipProps {
+    /** The explanation the tip reveals. Keep it to a sentence or two. */
+    children: ReactNode;
+    /** Accessible name for the "?" trigger. Say what it explains, e.g. "About human review". */
+    label?: string;
+    /** Preferred side for the bubble; it flips when that side would leave the viewport. */
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    className?: string;
+}
+/**
+ * A "?" circle that reveals a short explanation (DEV-11387), so a page can keep
+ * caveats and definitions one hover away instead of as paragraphs of body copy.
+ *
+ * Built on Base UI's Popover, not a tooltip: a tooltip never opens on touch,
+ * and these explanations must be reachable on a phone. Hover opens it for mouse
+ * users; click/tap and Enter/Space open it everywhere; Escape and an outside
+ * click close it. The bubble is portalled and collision-aware, so a tip near a
+ * page edge stays on screen, and it styles from the host's theme tokens.
+ *
+ * The visible glyph is 16px but the button keeps the 44px touch-target floor.
+ * The negative margin is VERTICAL ONLY: it cancels the extra height so the tip
+ * sits inline in a heading without changing its line height, while the full
+ * 44px of inline width stays in the layout. A horizontal cancel would let the
+ * hit area reach ~14px into whatever sits beside it, swallowing hovers and
+ * clicks meant for that text.
+ */
+declare function InfoTip({ children, label, side, align, className }: InfoTipProps): react.JSX.Element;
+
 /**
  * SidebarLadder — the per-tenant JSON artifact (DEV-4351) that pre-calculates
  * every viewport-driven collapse step for AppSidebar. Agent-authored at spawn
@@ -719,6 +748,19 @@ interface ConnectorCredentialTestResult {
      */
     permissions_note?: string | null;
 }
+/**
+ * Connector health as the DEV-1964 probe classifies it — Reeve.Connects-wide
+ * vocabulary, not provider-specific (the same shape the adbuyer surfaces
+ * already read off `GET /api/connects/v1/connections`). Deliberately
+ * tri-state, never a `needs_reconnect` boolean (Matt's call, DEV-7873): a
+ * probe that has not run yet ("unknown") or has not run at all (the whole
+ * field absent) is not the same claim as a probe that ran and failed.
+ */
+interface ConnectorConnectionHealth {
+    status: "healthy" | "unhealthy" | "unknown";
+    error_code?: string | null;
+    checked_at?: string | null;
+}
 interface ConnectableEntry {
     slug: string;
     name: string;
@@ -749,6 +791,21 @@ interface ConnectableEntry {
         } | null;
         /** true = the viewer owns this connection (enables manage-sharing). */
         owned_by_viewer?: boolean;
+        /**
+         * Live health probe for this connection (DEV-1964 / DEV-7873), when the
+         * backend has one. Absent/undefined is NOT "healthy" — it means no probe
+         * has run; the picker only ever reacts to an explicit "unhealthy"
+         * status, so "unknown" and absent both render as a plain connected
+         * tile, same as before this field existed.
+         */
+        health?: ConnectorConnectionHealth | null;
+        /**
+         * Human-readable identity of the external account this connection
+         * authenticated as (an email, a workspace name, whatever the provider's
+         * own identity claim resolves to). Optional and provider-agnostic — the
+         * picker never assumes an email shape or synthesizes this itself.
+         */
+        account_label?: string | null;
     };
     /** true = tenant has a live connection but the entry left the allowlist. */
     deprecated: boolean;
@@ -766,6 +823,15 @@ interface ConnectableEntry {
      * connect button renders, exactly as before.
      */
     credential_fields?: ConnectorCredentialField[] | null;
+    /**
+     * Plain-language description of what a LIVE connection actually reads or
+     * writes (e.g. "Reads recent activity to build your weekly summary") —
+     * entirely server-authored copy, same posture as `category`/`name`.
+     * Rendered only once connected (it describes a live grant, not the
+     * catalog listing); absent renders nothing. This file must never
+     * synthesize this text itself for a specific provider.
+     */
+    access_summary?: string | null;
 }
 interface ConnectorPickerClient {
     listConnectable(opts: {
@@ -829,4 +895,4 @@ interface ConnectorPickerProps {
 }
 declare function ConnectorPicker({ client, purpose, lens, layout, onConnected, }: ConnectorPickerProps): react.JSX.Element | null;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ConnectableCapability, type ConnectableEntry, type ConnectableTransport, type ConnectionKind, type ConnectorCredentialField, type ConnectorCredentialTestResult, type ConnectorGrant, type ConnectorGrantInput, type ConnectorGranteeType, type ConnectorGuideStep, ConnectorPicker, type ConnectorPickerClient, type ConnectorPickerLens, type ConnectorPickerProps, type ConnectorRoleOption, type ConnectorSetupGuide, 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, MARK_WEIGHT, type OrgConnectPolicy, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ConnectableCapability, type ConnectableEntry, type ConnectableTransport, type ConnectionKind, type ConnectorConnectionHealth, type ConnectorCredentialField, type ConnectorCredentialTestResult, type ConnectorGrant, type ConnectorGrantInput, type ConnectorGranteeType, type ConnectorGuideStep, ConnectorPicker, type ConnectorPickerClient, type ConnectorPickerLens, type ConnectorPickerProps, type ConnectorRoleOption, type ConnectorSetupGuide, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, InfoTip, type InfoTipProps, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, MARK_WEIGHT, type OrgConnectPolicy, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };

package/dist/index.d.ts

@@ -206,6 +206,35 @@ declare function ResponsiveHeader({ brand, search, nav, brandHref, linkComponent
  */
 declare function useResponsivePlaceholder(desktop: string, mobile?: string): string;
 
+interface InfoTipProps {
+    /** The explanation the tip reveals. Keep it to a sentence or two. */
+    children: ReactNode;
+    /** Accessible name for the "?" trigger. Say what it explains, e.g. "About human review". */
+    label?: string;
+    /** Preferred side for the bubble; it flips when that side would leave the viewport. */
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    className?: string;
+}
+/**
+ * A "?" circle that reveals a short explanation (DEV-11387), so a page can keep
+ * caveats and definitions one hover away instead of as paragraphs of body copy.
+ *
+ * Built on Base UI's Popover, not a tooltip: a tooltip never opens on touch,
+ * and these explanations must be reachable on a phone. Hover opens it for mouse
+ * users; click/tap and Enter/Space open it everywhere; Escape and an outside
+ * click close it. The bubble is portalled and collision-aware, so a tip near a
+ * page edge stays on screen, and it styles from the host's theme tokens.
+ *
+ * The visible glyph is 16px but the button keeps the 44px touch-target floor.
+ * The negative margin is VERTICAL ONLY: it cancels the extra height so the tip
+ * sits inline in a heading without changing its line height, while the full
+ * 44px of inline width stays in the layout. A horizontal cancel would let the
+ * hit area reach ~14px into whatever sits beside it, swallowing hovers and
+ * clicks meant for that text.
+ */
+declare function InfoTip({ children, label, side, align, className }: InfoTipProps): react.JSX.Element;
+
 /**
  * SidebarLadder — the per-tenant JSON artifact (DEV-4351) that pre-calculates
  * every viewport-driven collapse step for AppSidebar. Agent-authored at spawn
@@ -719,6 +748,19 @@ interface ConnectorCredentialTestResult {
      */
     permissions_note?: string | null;
 }
+/**
+ * Connector health as the DEV-1964 probe classifies it — Reeve.Connects-wide
+ * vocabulary, not provider-specific (the same shape the adbuyer surfaces
+ * already read off `GET /api/connects/v1/connections`). Deliberately
+ * tri-state, never a `needs_reconnect` boolean (Matt's call, DEV-7873): a
+ * probe that has not run yet ("unknown") or has not run at all (the whole
+ * field absent) is not the same claim as a probe that ran and failed.
+ */
+interface ConnectorConnectionHealth {
+    status: "healthy" | "unhealthy" | "unknown";
+    error_code?: string | null;
+    checked_at?: string | null;
+}
 interface ConnectableEntry {
     slug: string;
     name: string;
@@ -749,6 +791,21 @@ interface ConnectableEntry {
         } | null;
         /** true = the viewer owns this connection (enables manage-sharing). */
         owned_by_viewer?: boolean;
+        /**
+         * Live health probe for this connection (DEV-1964 / DEV-7873), when the
+         * backend has one. Absent/undefined is NOT "healthy" — it means no probe
+         * has run; the picker only ever reacts to an explicit "unhealthy"
+         * status, so "unknown" and absent both render as a plain connected
+         * tile, same as before this field existed.
+         */
+        health?: ConnectorConnectionHealth | null;
+        /**
+         * Human-readable identity of the external account this connection
+         * authenticated as (an email, a workspace name, whatever the provider's
+         * own identity claim resolves to). Optional and provider-agnostic — the
+         * picker never assumes an email shape or synthesizes this itself.
+         */
+        account_label?: string | null;
     };
     /** true = tenant has a live connection but the entry left the allowlist. */
     deprecated: boolean;
@@ -766,6 +823,15 @@ interface ConnectableEntry {
      * connect button renders, exactly as before.
      */
     credential_fields?: ConnectorCredentialField[] | null;
+    /**
+     * Plain-language description of what a LIVE connection actually reads or
+     * writes (e.g. "Reads recent activity to build your weekly summary") —
+     * entirely server-authored copy, same posture as `category`/`name`.
+     * Rendered only once connected (it describes a live grant, not the
+     * catalog listing); absent renders nothing. This file must never
+     * synthesize this text itself for a specific provider.
+     */
+    access_summary?: string | null;
 }
 interface ConnectorPickerClient {
     listConnectable(opts: {
@@ -829,4 +895,4 @@ interface ConnectorPickerProps {
 }
 declare function ConnectorPicker({ client, purpose, lens, layout, onConnected, }: ConnectorPickerProps): react.JSX.Element | null;
 
-export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ConnectableCapability, type ConnectableEntry, type ConnectableTransport, type ConnectionKind, type ConnectorCredentialField, type ConnectorCredentialTestResult, type ConnectorGrant, type ConnectorGrantInput, type ConnectorGranteeType, type ConnectorGuideStep, ConnectorPicker, type ConnectorPickerClient, type ConnectorPickerLens, type ConnectorPickerProps, type ConnectorRoleOption, type ConnectorSetupGuide, 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, MARK_WEIGHT, type OrgConnectPolicy, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };
+export { type AppRungItem, AppSidebar, type AppSidebarBrand, type AppSidebarModuleDef, type AppSidebarProps, type AppSidebarTopItem, type Brand, BrandGlyph, type BrandGlyphProps, type ConnectableCapability, type ConnectableEntry, type ConnectableTransport, type ConnectionKind, type ConnectorConnectionHealth, type ConnectorCredentialField, type ConnectorCredentialTestResult, type ConnectorGrant, type ConnectorGrantInput, type ConnectorGranteeType, type ConnectorGuideStep, ConnectorPicker, type ConnectorPickerClient, type ConnectorPickerLens, type ConnectorPickerProps, type ConnectorRoleOption, type ConnectorSetupGuide, type ContextOrgGroup, ContextSwitcher, type ContextSwitcherItem, type ContextSwitcherProps, type FallbackModuleDef, Flyout, type FlyoutChild, type FlyoutProps, GLYPH_CANVAS_FILL, type GroupRungItem, type HeaderNavItem, InfoTip, type InfoTipProps, LOCKUP_GAP, LOCKUP_ROW, MARK_CAP_RATIO, MARK_WEIGHT, type OrgConnectPolicy, REEVE_ACCENT, ResponsiveHeader, type ResponsiveHeaderProps, type RungItem, type SidebarLadder, type SidebarLadderParsed, type SidebarRung, type UseLadderRungOptions, WORDMARK_WEIGHT, deriveFallbackLadder, faviconUrl, groupByOrg, reconcileLadder, resolveLadder, useLadderRung, useResponsivePlaceholder, zSidebarLadder };