@agent-native/core 0.108.0 → 0.109.0

package/corpus/templates/analytics/actions/slack-messages.ts

@@ -4,9 +4,8 @@ import { z } from "zod";
 import {
   getChannelHistory,
   getTeamInfo,
-  listChannels,
-  resolveUsers,
-  searchMessages,
+  listChannelsWithCoverage,
+  resolveUsersWithCoverage,
   type SlackMessage,
   type Workspace,
 } from "../server/lib/slack";
@@ -41,7 +40,7 @@ function enrichMessages(messages: SlackMessage[]): SlackMessage[] {
 
 export default defineAction({
   description:
-    "Query the analytics app's configured Slack workspace: team info, channels, channel history, multi-channel history, or message search. Slack messages returned by this action are real source evidence; you may count mentions, code themes, classify sentiment, and summarize qualitative patterns from them while stating the sample size.",
+    "Query the analytics app's configured Slack workspace: team info, channels, channel history, or multi-channel history. Slack messages returned by this action are real source evidence; you may count mentions, code themes, classify sentiment, and summarize qualitative patterns from them while stating the sample size. The legacy search mode is preserved for compatibility but returns migration guidance because the configured bot credential cannot call Slack global search; use the Slack provider corpus recipe for channel-scoped exhaustive search.",
   schema: z.object({
     mode: z
       .enum(["team", "channels", "history", "multi-history", "search"])
@@ -68,7 +67,10 @@ export default defineAction({
       .max(200)
       .default(50)
       .describe("Message limit for history"),
-    cursor: z.string().optional().describe("Slack history cursor/latest ts"),
+    cursor: z
+      .string()
+      .optional()
+      .describe("Slack history/latest timestamp or channel-list cursor"),
     cursors: z
       .record(z.string(), z.string())
       .optional()
@@ -99,12 +101,31 @@ export default defineAction({
         const userIds = messages
           .map((message) => message.user)
           .filter((id): id is string => !!id);
-        const users = await resolveUsers(workspace, userIds, messages);
+        const resolution = await resolveUsersWithCoverage(
+          workspace,
+          userIds,
+          messages,
+        );
         return {
           messages,
-          users,
+          users: resolution.users,
           has_more: result.has_more,
           next_cursor: result.next_cursor,
+          truncated: result.truncated,
+          pagination: result.pagination,
+          coverage: {
+            ...result.coverage,
+            coverage_complete:
+              result.coverage.coverage_complete &&
+              resolution.coverage.coverage_complete,
+            truncated:
+              result.coverage.truncated || resolution.coverage.truncated,
+            truncation_reasons: [
+              ...result.coverage.truncation_reasons,
+              ...resolution.coverage.truncation_reasons,
+            ],
+            authors: resolution.coverage,
+          },
         };
       }
 
@@ -113,57 +134,188 @@ export default defineAction({
         const channelIds = args.channels.split(",").filter(Boolean);
         const channelNames = args.names ? args.names.split(",") : channelIds;
         const pageSize = Math.min(args.limit, 200);
-        const results = await Promise.all(
-          channelIds.map((id) =>
-            getChannelHistory(workspace, id, pageSize, args.cursors?.[id]),
+        const channelResults = await Promise.allSettled(
+          channelIds.map((channelId) =>
+            getChannelHistory(
+              workspace,
+              channelId,
+              pageSize,
+              args.cursors?.[channelId],
+            ),
           ),
         );
+        const successfulResults = channelResults.flatMap((entry, index) =>
+          entry.status === "fulfilled"
+            ? [{ channelId: channelIds[index], result: entry.value }]
+            : [],
+        );
+        const failedChannelIds = channelResults.flatMap((entry, index) =>
+          entry.status === "rejected" ? [channelIds[index]] : [],
+        );
 
-        const allMessages: (SlackMessage & { channel_name: string })[] = [];
+        const allMessages: (SlackMessage & {
+          channel_id: string;
+          channel_name: string;
+        })[] = [];
         const perChannelHasMore: Record<string, boolean> = {};
         const nextCursors: Record<string, string> = {};
 
-        results.forEach((result, idx) => {
-          const channelId = channelIds[idx];
+        successfulResults.forEach(({ channelId, result }) => {
           perChannelHasMore[channelId] = result.has_more;
-          if (result.next_cursor) nextCursors[channelId] = result.next_cursor;
           for (const message of result.messages) {
             allMessages.push({
               ...message,
-              channel_name: channelNames[idx] || channelId,
+              channel_id: channelId,
+              channel_name:
+                channelNames[channelIds.indexOf(channelId)] || channelId,
             });
           }
         });
+        failedChannelIds.forEach((channelId) => {
+          perChannelHasMore[channelId] = true;
+        });
 
         allMessages.sort((a, b) => parseFloat(b.ts) - parseFloat(a.ts));
-        const messages = enrichMessages(allMessages.slice(0, pageSize));
+        const pageMessages = allMessages.slice(0, pageSize);
+        const emittedByChannel = new Map<string, SlackMessage[]>();
+        for (const message of pageMessages) {
+          const emitted = emittedByChannel.get(message.channel_id) ?? [];
+          emitted.push(message);
+          emittedByChannel.set(message.channel_id, emitted);
+        }
+        for (const channelId of channelIds) {
+          const emitted = emittedByChannel.get(channelId);
+          const nextCursor = emitted?.[emitted.length - 1]?.ts;
+          if (nextCursor) nextCursors[channelId] = nextCursor;
+          else if (args.cursors?.[channelId]) {
+            nextCursors[channelId] = args.cursors[channelId];
+          }
+        }
+
+        const messages = pageMessages.map((message) => {
+          const enriched = enrichMessages([message])[0] ?? message;
+          const { channel_id: _channelId, ...rest } =
+            enriched as typeof message;
+          return rest;
+        });
         const userIds = messages
           .map((message) => message.user)
           .filter((id): id is string => !!id);
-        const users = await resolveUsers(workspace, userIds, messages);
+        const resolution = await resolveUsersWithCoverage(
+          workspace,
+          userIds,
+          messages,
+        );
+        const providerTruncated = successfulResults.some(
+          ({ result }) => result.truncated,
+        );
+        const mergedResultTruncated = allMessages.length > pageSize;
+        const truncated =
+          providerTruncated ||
+          mergedResultTruncated ||
+          failedChannelIds.length > 0;
+        const truncationReasons = [
+          ...(providerTruncated ? ["provider_has_more"] : []),
+          ...(mergedResultTruncated ? ["merged_result_limit"] : []),
+          ...failedChannelIds.map(
+            (channelId) => `channel_fetch_failed:${channelId}`,
+          ),
+        ];
+        const channelPagination = Object.fromEntries(
+          channelResults.map((entry, index) => [
+            channelIds[index],
+            entry.status === "fulfilled"
+              ? entry.value.pagination
+              : {
+                  cursor_type: "latest_ts" as const,
+                  ...(args.cursors?.[channelIds[index]]
+                    ? { request_cursor: args.cursors[channelIds[index]] }
+                    : {}),
+                },
+          ]),
+        );
+        const channelCoverage = Object.fromEntries(
+          channelResults.map((entry, index) => [
+            channelIds[index],
+            entry.status === "fulfilled"
+              ? entry.value.coverage
+              : {
+                  requested: pageSize,
+                  fetched: 0,
+                  returned: 0,
+                  pages_fetched: 0,
+                  coverage_complete: false,
+                  truncated: true,
+                  truncation_reasons: [
+                    `channel_fetch_failed:${channelIds[index]}`,
+                  ],
+                },
+          ]),
+        );
         return {
           messages,
-          users,
+          users: resolution.users,
           has_more:
             Object.values(perChannelHasMore).some(Boolean) ||
-            allMessages.length > pageSize,
+            allMessages.length > pageSize ||
+            failedChannelIds.length > 0,
           next_cursors: nextCursors,
           total: allMessages.length,
+          truncated,
+          pagination: {
+            cursor_type: "per_channel_latest_ts",
+            request_cursors: args.cursors ?? {},
+            next_cursors: nextCursors,
+            channels: channelPagination,
+          },
+          coverage: {
+            requested: channelIds.length * pageSize,
+            fetched: allMessages.length,
+            returned: messages.length,
+            pages_fetched: successfulResults.length,
+            coverage_complete:
+              !truncated && resolution.coverage.coverage_complete,
+            truncated: truncated || resolution.coverage.truncated,
+            truncation_reasons: [
+              ...truncationReasons,
+              ...resolution.coverage.truncation_reasons,
+            ],
+            channels: channelCoverage,
+            authors: resolution.coverage,
+          },
         };
       }
 
       if (args.mode === "search") {
         if (!args.query) return { error: "query is required" };
-        const result = await searchMessages(workspace, args.query);
-        const userIds = result.messages
-          .map((message) => message.user)
-          .filter((id): id is string => !!id);
-        const users = await resolveUsers(workspace, userIds, result.messages);
-        return { messages: result.messages, users, total: result.total };
+        return {
+          messages: [],
+          users: {},
+          total: 0,
+          unsupported: true,
+          truncated: true,
+          coverage: {
+            requested: 0,
+            fetched: 0,
+            returned: 0,
+            pages_fetched: 0,
+            coverage_complete: false,
+            truncated: true,
+            truncation_reasons: ["bot_token_global_search_unsupported"],
+          },
+          guidance:
+            "Slack global search is not available with the configured bot credential. Resolve a channel id, then use provider-api-catalog(provider='slack') and provider-corpus-job with the Slack conversations.history corpus recipe so cursor pages are fetched inside one resumable operation.",
+        };
       }
 
-      const channels = await listChannels(workspace);
-      return { channels, total: channels.length };
+      const result = await listChannelsWithCoverage(workspace, args.cursor);
+      return {
+        channels: result.channels,
+        total: result.total,
+        truncated: result.truncated,
+        pagination: result.pagination,
+        coverage: result.coverage,
+      };
     } catch (err) {
       return providerError(err);
     }

package/corpus/templates/analytics/app/components/dashboard/SqlChart.tsx

@@ -19,14 +19,12 @@ import {
   useCallback,
   useContext,
   useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   useState,
   type CSSProperties,
   type ReactNode,
 } from "react";
-import { createPortal } from "react-dom";
 import { Link } from "react-router";
 import {
   Area,
@@ -61,6 +59,7 @@ import {
   SelectValue,
 } from "@/components/ui/select";
 import { Skeleton } from "@/components/ui/skeleton";
+import { useChartTooltipFlip } from "@/hooks/use-chart-tooltip-flip";
 
 const PAGE_SIZE_OPTIONS = [10, 25, 50, 100];
 import { createDemoChartTrendRows } from "@/lib/demo-chart-trend";
@@ -90,11 +89,6 @@ const CHART_TOOLTIP_WRAPPER_STYLE: CSSProperties = {
   pointerEvents: "none",
 };
 
-const PORTAL_GUTTER_PADDING = 12;
-const PORTAL_CURSOR_OFFSET = 24;
-const useBrowserLayoutEffect =
-  typeof window === "undefined" ? useEffect : useLayoutEffect;
-
 const CHART_TOOLTIP_PROPS = {
   allowEscapeViewBox: { x: true, y: true },
   wrapperStyle: CHART_TOOLTIP_WRAPPER_STYLE,
@@ -598,7 +592,7 @@ export function SeriesLegend({
   if (!shouldShowLegend(panel, keys.length)) return null;
 
   return (
-    <div className="mt-2 min-h-16 max-h-16 overflow-y-auto overflow-x-hidden pr-1 text-[11px] leading-4 text-muted-foreground">
+    <div className="mt-1 max-h-16 overflow-y-auto overflow-x-hidden pr-1 text-[11px] leading-4 text-muted-foreground">
       <div className="flex flex-wrap gap-x-3 gap-y-1">
         {keys.map((key, i) => {
           const hidden = hiddenKeys?.has(key) ?? false;
@@ -612,7 +606,7 @@ export function SeriesLegend({
             >
               <PopoverAnchor asChild>
                 <div
-                  className="inline-flex min-h-10 max-w-[14rem] items-center"
+                  className="inline-flex min-h-6 max-w-[14rem] items-center"
                   onPointerDown={(event) => {
                     if (!hasLegendActions || event.pointerType === "mouse") {
                       return;
@@ -648,7 +642,7 @@ export function SeriesLegend({
                     }
                     aria-haspopup={hasLegendActions ? "menu" : undefined}
                     data-chart-legend-item={key}
-                    className={`inline-flex min-h-10 max-w-[14rem] min-w-0 items-center gap-1.5 rounded-md px-1.5 text-left transition-[opacity,color] touch-manipulation hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring ${
+                    className={`inline-flex min-h-6 max-w-[14rem] min-w-0 items-center gap-1.5 rounded-md px-1.5 text-left transition-[opacity,color] touch-manipulation hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring ${
                       hidden ? "opacity-35" : "opacity-100"
                     } ${onToggleKey ? "cursor-pointer" : "cursor-default"}`}
                     title={label}
@@ -680,18 +674,18 @@ export function SeriesLegend({
                   align="center"
                   sideOffset={8}
                   collisionPadding={12}
-                  className="w-56 max-w-[calc(100vw-1.5rem)] rounded-lg p-1.5 shadow-lg"
+                  className="w-auto max-w-[calc(100vw-1.5rem)] rounded-lg p-1 shadow-lg"
                   onPointerEnter={clearCloseTimeout}
                   onPointerLeave={scheduleCloseLegendActions}
                   onFocusCapture={clearCloseTimeout}
                 >
-                  <div className="flex w-full items-center gap-1">
+                  <div className="flex items-center gap-0.5">
                     {onFilterKey && (
                       <button
                         type="button"
                         data-chart-legend-action="filter"
                         aria-label={`${t("sqlDashboard.filterSeries")} ${label}`}
-                        className="min-h-11 min-w-0 flex-1 rounded-md px-3 py-2 text-xs font-medium whitespace-nowrap text-popover-foreground outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground"
+                        className="min-h-8 rounded-md px-2.5 py-1 text-xs font-medium whitespace-nowrap text-popover-foreground outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground"
                         onClick={() => {
                           onFilterKey(key);
                           setOpenKey(null);
@@ -706,7 +700,7 @@ export function SeriesLegend({
                         data-chart-legend-action="hide"
                         aria-label={`${t("sqlDashboard.hide")} ${label}`}
                         disabled={hidden}
-                        className="min-h-11 min-w-0 flex-1 rounded-md px-3 py-2 text-xs font-medium whitespace-nowrap text-popover-foreground outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground disabled:pointer-events-none disabled:opacity-40"
+                        className="min-h-8 rounded-md px-2.5 py-1 text-xs font-medium whitespace-nowrap text-popover-foreground outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground disabled:pointer-events-none disabled:opacity-40"
                         onClick={() => {
                           onToggleKey(key);
                           setOpenKey(null);
@@ -886,9 +880,9 @@ function SqlChartLoadingSkeleton({ panel }: { panel: SqlPanel }) {
       <Skeleton
         className={`w-full ${fill ? "h-full min-h-[250px] flex-1" : "h-[250px]"}`}
       />
-      <div className="mt-2 grid min-h-16 grid-cols-2 gap-x-3 gap-y-1 overflow-hidden pr-1 sm:grid-cols-3">
-        {Array.from({ length: 6 }).map((_, index) => (
-          <div key={index} className="flex items-center gap-1.5">
+      <div className="mt-1 flex min-h-6 flex-wrap gap-x-3 gap-y-1 overflow-hidden pr-1">
+        {Array.from({ length: 3 }).map((_, index) => (
+          <div key={index} className="flex min-h-6 items-center gap-1.5">
             <Skeleton className="h-2.5 w-3 shrink-0 rounded-sm" />
             <Skeleton className="h-3 w-20 min-w-0" />
           </div>
@@ -898,7 +892,7 @@ function SqlChartLoadingSkeleton({ panel }: { panel: SqlPanel }) {
   );
 }
 
-function ChartTooltip({
+export function ChartTooltip({
   active,
   payload,
   label,
@@ -918,12 +912,7 @@ function ChartTooltip({
   seriesNameFormatter?: (value: string) => string;
   valueFormatter?: (value: number) => string;
 }) {
-  const anchorRef = useRef<HTMLDivElement | null>(null);
-  const portalRef = useRef<HTMLDivElement | null>(null);
-  const [portalPosition, setPortalPosition] = useState<{
-    left: number;
-    top: number;
-  } | null>(null);
+  const tooltipRef = useChartTooltipFlip<HTMLDivElement>(active);
   const items = useMemo(
     () =>
       sortTooltipPayloadItems(
@@ -932,11 +921,6 @@ function ChartTooltip({
       ),
     [payload],
   );
-  const portalVisible = portalPosition !== null;
-  const clearPortalPosition = useCallback(
-    () => setPortalPosition((prev) => (prev === null ? prev : null)),
-    [],
-  );
 
   const labelText =
     label == null
@@ -945,96 +929,14 @@ function ChartTooltip({
         ? labelFormatter(String(label))
         : String(label);
 
-  useBrowserLayoutEffect(() => {
-    if (!active || items.length === 0 || typeof window === "undefined") {
-      clearPortalPosition();
-      return;
-    }
-
-    const anchor = anchorRef.current;
-    const wrapper = anchor?.parentElement;
-    if (!anchor || !wrapper) return;
-
-    let frame = 0;
-    const apply = () => {
-      frame = 0;
-      if (!(wrapper as HTMLElement).style.transform) return;
-
-      const anchorRect = anchor.getBoundingClientRect();
-      const portalRect = portalRef.current?.getBoundingClientRect();
-      const width = portalRect?.width || anchorRect.width;
-      const height = portalRect?.height || anchorRect.height;
-      if (width === 0 || height === 0) return;
-
-      const sidebar = document.querySelector(".agent-sidebar-panel");
-      const sidebarRect = sidebar?.getBoundingClientRect();
-      const rightLimit =
-        sidebarRect && sidebarRect.width > 0 && sidebarRect.left > 0
-          ? sidebarRect.left - PORTAL_GUTTER_PADDING
-          : window.innerWidth - PORTAL_GUTTER_PADDING;
-      const bottomLimit = window.innerHeight - PORTAL_GUTTER_PADDING;
-
-      let left = anchorRect.left;
-      let top = anchorRect.top;
-
-      if (left + width > rightLimit) {
-        left = anchorRect.left - width - PORTAL_CURSOR_OFFSET;
-      }
-      left = Math.max(
-        PORTAL_GUTTER_PADDING,
-        Math.min(left, rightLimit - width),
-      );
-
-      if (top + height > bottomLimit) {
-        top = bottomLimit - height;
-      }
-      top = Math.max(PORTAL_GUTTER_PADDING, top);
-
-      setPortalPosition((prev) =>
-        prev &&
-        Math.abs(prev.left - left) < 0.5 &&
-        Math.abs(prev.top - top) < 0.5
-          ? prev
-          : { left, top },
-      );
-    };
-
-    const schedule = () => {
-      if (frame) return;
-      frame = window.requestAnimationFrame(apply);
-    };
-
-    schedule();
-
-    const mutationObserver = new MutationObserver(schedule);
-    mutationObserver.observe(wrapper, {
-      attributes: true,
-      attributeFilter: ["style", "class"],
-    });
-
-    const resizeObserver =
-      typeof ResizeObserver === "undefined"
-        ? null
-        : new ResizeObserver(schedule);
-    resizeObserver?.observe(anchor);
-    if (portalRef.current) resizeObserver?.observe(portalRef.current);
-
-    window.addEventListener("resize", schedule);
-    window.addEventListener("scroll", schedule, true);
-
-    return () => {
-      if (frame) window.cancelAnimationFrame(frame);
-      mutationObserver.disconnect();
-      resizeObserver?.disconnect();
-      window.removeEventListener("resize", schedule);
-      window.removeEventListener("scroll", schedule, true);
-    };
-  }, [active, clearPortalPosition, items.length, portalVisible]);
-
   if (!active || items.length === 0) return null;
 
   const tooltip = (
-    <div className="min-w-40 max-w-[280px] rounded-md border border-border bg-card px-3 py-2 text-xs text-foreground shadow-lg">
+    <div
+      ref={tooltipRef}
+      role="tooltip"
+      className="min-w-40 max-w-[280px] rounded-md border border-border bg-card px-3 py-2 text-xs text-foreground shadow-lg"
+    >
       {labelText && (
         <div className="mb-1.5 truncate font-medium text-foreground">
           {labelText}
@@ -1068,31 +970,7 @@ function ChartTooltip({
     </div>
   );
 
-  return (
-    <>
-      <div ref={anchorRef} aria-hidden="true" className="invisible">
-        {tooltip}
-      </div>
-      {portalPosition && typeof document !== "undefined"
-        ? createPortal(
-            <div
-              ref={portalRef}
-              role="tooltip"
-              style={{
-                position: "fixed",
-                left: portalPosition.left,
-                top: portalPosition.top,
-                zIndex: 1000,
-                pointerEvents: "none",
-              }}
-            >
-              {tooltip}
-            </div>,
-            document.body,
-          )
-        : null}
-    </>
-  );
+  return tooltip;
 }
 
 function detectKeys(
@@ -1434,16 +1312,33 @@ function DashboardExtensionPanel({
   // dashboard report screenshots don't capture a blank extension panel.
   const [ready, setReady] = useState(false);
   const [unavailable, setUnavailable] = useState(false);
+  const loadingSkeleton = !ready ? (
+    <Skeleton
+      data-dashboard-extension-loading="true"
+      className="absolute inset-0 z-10 h-full min-h-[180px] w-full rounded-md"
+      aria-hidden="true"
+    />
+  ) : null;
 
   if (slotId) {
     return (
-      <ExtensionSlot
-        id={slotId}
-        context={context}
-        showEmptyAffordance
-        className="min-h-[120px] w-full"
-        toolClassName="w-full"
-      />
+      <div
+        className="relative min-h-[180px] w-full"
+        aria-busy={!ready}
+        data-dashboard-report-loading={ready ? undefined : "true"}
+      >
+        {loadingSkeleton}
+        <div className={ready ? "opacity-100" : "opacity-0"}>
+          <ExtensionSlot
+            id={slotId}
+            context={context}
+            showEmptyAffordance
+            onReady={() => setReady(true)}
+            className="min-h-[120px] w-full"
+            toolClassName="w-full"
+          />
+        </div>
+      </div>
     );
   }
 
@@ -1462,15 +1357,16 @@ function DashboardExtensionPanel({
 
   return (
     <div
-      className="w-full"
+      className="relative min-h-[180px] w-full"
+      aria-busy={!ready}
       data-dashboard-report-loading={ready ? undefined : "true"}
     >
+      {loadingSkeleton}
       <EmbeddedExtension
         extensionId={extensionId!}
         slotId={`dashboard-panel-${panelId}`}
-        className="w-full"
-        // Intentional for v1: extension panels are standalone widgets and do not
-        // receive the dashboard's filters/variables/date range as `context`.
+        context={context}
+        className={ready ? "w-full opacity-100" : "w-full opacity-0"}
         initialHeight={180}
         onReady={() => setReady(true)}
         onUnavailable={() => {

package/corpus/templates/analytics/app/components/ui/chart.tsx

@@ -136,7 +136,7 @@ const ChartTooltipContent = React.forwardRef<
     ref,
   ) => {
     const { config } = useChart();
-    const flipRef = useChartTooltipFlip<HTMLDivElement>();
+    const flipRef = useChartTooltipFlip<HTMLDivElement>(active);
     const setRefs = React.useCallback(
       (node: HTMLDivElement | null) => {
         flipRef.current = node;

package/corpus/templates/analytics/app/hooks/use-chart-tooltip-flip.ts

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from "react";
 
-const RIGHT_GUTTER_PADDING = 12;
+const VIEWPORT_GUTTER_PADDING = 12;
 const FLIP_CURSOR_OFFSET = 24;
 
 /**
@@ -10,10 +10,11 @@ const FLIP_CURSOR_OFFSET = 24;
  * `transform` (cursor moves) and translate the content left when its right
  * edge would land inside `.agent-sidebar-panel`.
  */
-export function useChartTooltipFlip<T extends HTMLElement>() {
+export function useChartTooltipFlip<T extends HTMLElement>(active = true) {
   const ref = useRef<T | null>(null);
 
   useEffect(() => {
+    if (!active) return;
     const el = ref.current;
     if (!el) return;
     const wrapper = el.parentElement;
@@ -32,11 +33,25 @@ export function useChartTooltipFlip<T extends HTMLElement>() {
         sidebarRect && sidebarRect.width > 0 && sidebarRect.left > 0
           ? sidebarRect.left
           : window.innerWidth;
-      const limit = gutterLeft - RIGHT_GUTTER_PADDING;
+      const rightLimit = gutterLeft - VIEWPORT_GUTTER_PADDING;
+      const bottomLimit = window.innerHeight - VIEWPORT_GUTTER_PADDING;
+      let translateX = 0;
+      let translateY = 0;
 
-      if (rect.right > limit) {
-        node.style.transform = `translateX(-${rect.width + FLIP_CURSOR_OFFSET}px)`;
+      if (rect.right > rightLimit) {
+        translateX = -(rect.width + FLIP_CURSOR_OFFSET);
       }
+      if (rect.bottom > bottomLimit) {
+        translateY = bottomLimit - rect.bottom;
+      } else if (rect.top < VIEWPORT_GUTTER_PADDING) {
+        translateY = VIEWPORT_GUTTER_PADDING - rect.top;
+      }
+
+      const transforms = [
+        translateX ? `translateX(${translateX}px)` : "",
+        translateY ? `translateY(${translateY}px)` : "",
+      ].filter(Boolean);
+      node.style.transform = transforms.join(" ");
     };
 
     apply();
@@ -46,7 +61,7 @@ export function useChartTooltipFlip<T extends HTMLElement>() {
       attributeFilter: ["style"],
     });
     return () => observer.disconnect();
-  }, []);
+  }, [active]);
 
   return ref;
 }