chore: more polish and qa feedbacks for guide toolbar v2

.changeset/violet-heads-go.md

@@ -0,0 +1,5 @@
+---
+"@knocklabs/react": patch
+---
+
+[Guides] Address more polish + feedback items in guide toolbar v2

packages/react/src/modules/guide/components/Toolbar/V2/FocusChin.tsx

@@ -7,6 +7,7 @@ import { ChevronLeft, ChevronRight, X } from "lucide-react";
 import * as React from "react";
 
 import { GUIDE_ROW_DATA_SELECTOR } from "./GuideRow";
+import { sharedTooltipProps } from "./helpers";
 import { InspectionResultOk } from "./useInspectGuideClientStore";
 
 // Extra scroll overshoot so the focused guide plus ~1-2 neighbors are visible,
@@ -88,7 +89,7 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
           Focus mode: {currentKey}
         </Text>
         <Stack align="center" gap="1" style={{ flexShrink: 0 }}>
-          <Tooltip label="Focus previous guide">
+          <Tooltip label="Focus previous guide" {...sharedTooltipProps}>
             <Button
               size="0"
               variant="ghost"
@@ -117,7 +118,7 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
               }}
             />
           </Tooltip>
-          <Tooltip label="Focus next guide">
+          <Tooltip label="Focus next guide" {...sharedTooltipProps}>
             <Button
               size="0"
               variant="ghost"
@@ -148,7 +149,7 @@ export const FocusChin = ({ guides, guideListRef }: Props) => {
               }}
             />
           </Tooltip>
-          <Tooltip label="Exit focus lock">
+          <Tooltip label="Exit focus mode" {...sharedTooltipProps}>
             <Button
               size="0"
               variant="ghost"

packages/react/src/modules/guide/components/Toolbar/V2/GuideAnnotatedStatusDot.tsx

@@ -1,6 +1,8 @@
 import { Stack } from "@telegraph/layout";
 import { Tooltip } from "@telegraph/tooltip";
 
+import { sharedTooltipProps } from "./helpers";
+
 export type StatusColor = "blue" | "red" | "yellow" | "gray";
 
 // Directly copied from the design prototype.
@@ -59,7 +61,7 @@ export const GuideAnnotatedStatusDot = ({
   tooltip: string;
 }) => {
   return (
-    <Tooltip label={tooltip}>
+    <Tooltip label={tooltip} {...sharedTooltipProps}>
       <Stack
         as="span"
         align="center"

packages/react/src/modules/guide/components/Toolbar/V2/GuideContextDetails.tsx

@@ -4,6 +4,8 @@ import { Toggle } from "@telegraph/toggle";
 import { Tooltip } from "@telegraph/tooltip";
 import { Text } from "@telegraph/typography";
 
+import { sharedTooltipProps } from "./helpers";
+
 export const GuideContextDetails = () => {
   const { client } = useGuideContext();
   const { debugSettings } = useStore(client.store, (state) => ({
@@ -18,7 +20,10 @@ export const GuideContextDetails = () => {
         </Text>
         <Stack direction="column" gap="1">
           <Stack direction="row" gap="2" align="center" h="7">
-            <Tooltip label="Contain engagement actions to client side only">
+            <Tooltip
+              label="When enabled, engagement actions are not sent to Knock."
+              {...sharedTooltipProps}
+            >
               <Box width="36" mt="1">
                 <Text
                   as="span"
@@ -45,7 +50,10 @@ export const GuideContextDetails = () => {
             />
           </Stack>
           <Stack direction="row" gap="2" align="center" h="7">
-            <Tooltip label="Ignore throttle and show next guide immediately">
+            <Tooltip
+              label="Ignore throttle and show next guide immediately"
+              {...sharedTooltipProps}
+            >
               <Box width="36" mt="1">
                 <Text
                   as="span"
@@ -77,13 +85,11 @@ export const GuideContextDetails = () => {
         <Tooltip
           label={
             <Text as="span" size="1">
-              The tenant and data payload passed to the guide client that are
-              used for targeting
-              <br />
-              (via the targetParams prop to KnockGuideProvider)
+              The tenant and data payload passed to KnockGuideProvider.
+              Available for use in runtime conditions.
             </Text>
           }
-          delayDuration={500}
+          {...sharedTooltipProps}
         >
           <Text
             as="span"

packages/react/src/modules/guide/components/Toolbar/V2/GuideRow.tsx

@@ -17,7 +17,7 @@ import {
   StatusSummary,
   getSelectableStatusSummary,
 } from "./GuideRowDetails";
-import { FOCUS_ERRORS } from "./helpers";
+import { sharedTooltipProps } from "./helpers";
 import {
   AnnotatedGuide,
   AnnotatedStatuses,
@@ -259,6 +259,7 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
           </Stack>
           <Tooltip
             label={`${guide.key}${guide.bypass_global_group_limit ? " (unthrottled)" : ""}`}
+            {...sharedTooltipProps}
           >
             <Text
               as="code"
@@ -281,7 +282,7 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
         {/* Right section: verdict + pills + focus */}
         <Stack align="center" gap="1_5" style={{ flexShrink: 0 }}>
           {!hasFocus && (
-            <Tooltip label={summary.description}>
+            <Tooltip label={summary.description} {...sharedTooltipProps}>
               <Tag size="0" variant="soft" color={summary.color}>
                 {summary.label}
               </Tag>
@@ -332,38 +333,24 @@ export const GuideRow = ({ guide, orderIndex, isExpanded, onClick }: Props) => {
             />
           </Pill>
 
-          <Tooltip
-            label={
-              isUncommittedGuide(guide)
-                ? FOCUS_ERRORS.focusUncommittedGuide
-                : guide.annotation.selectable.status === undefined
-                  ? FOCUS_ERRORS.focusUnselectableGuide
-                  : ""
-            }
-            enabled={
+          <Button
+            size="0"
+            variant={isFocused ? "solid" : "outline"}
+            color={isFocused ? "blue" : "gray"}
+            disabled={
               isUncommittedGuide(guide) ||
               guide.annotation.selectable.status === undefined
             }
+            onClick={(e: React.MouseEvent) => {
+              e.stopPropagation();
+              client.setDebug({
+                ...debugSettings,
+                focusedGuideKeys: isFocused ? {} : { [guide.key]: true },
+              });
+            }}
           >
-            <Button
-              size="0"
-              variant={isFocused ? "solid" : "outline"}
-              color={isFocused ? "blue" : "gray"}
-              disabled={
-                isUncommittedGuide(guide) ||
-                guide.annotation.selectable.status === undefined
-              }
-              onClick={(e: React.MouseEvent) => {
-                e.stopPropagation();
-                client.setDebug({
-                  ...debugSettings,
-                  focusedGuideKeys: isFocused ? {} : { [guide.key]: true },
-                });
-              }}
-            >
-              Focus
-            </Button>
-          </Tooltip>
+            Focus
+          </Button>
         </Stack>
       </Stack>
 

packages/react/src/modules/guide/components/Toolbar/V2/GuideRowDetails.tsx

@@ -6,7 +6,7 @@ import {
   StatusColor,
   GuideAnnotatedStatusDot as StatusDot,
 } from "./GuideAnnotatedStatusDot";
-import { FOCUS_ERRORS } from "./helpers";
+import { sharedTooltipProps } from "./helpers";
 import {
   AnnotatedGuide,
   UncommittedGuide,
@@ -35,7 +35,7 @@ const CardContainer = ({
     <Text as="span" size="0" color="gray" weight="medium">
       {title}
     </Text>
-    <Stack direction="column" gap="1" mt="1">
+    <Stack direction="column" gap="1">
       {children}
     </Stack>
   </Stack>
@@ -46,25 +46,32 @@ const StatusRow = ({
   value,
   color,
   tooltip,
+  children,
 }: {
   label: string;
   value: string;
   color: StatusColor;
   tooltip?: React.ReactNode;
+  children?: React.ReactNode;
 }) => {
   return (
     <Stack align="center" gap="1">
-      <Tooltip enabled={!!tooltip} label={tooltip} delayDuration={500}>
-        <Stack as="span" align="center" gap="1" display="inline-flex">
+      <Tooltip enabled={!!tooltip} label={tooltip} {...sharedTooltipProps}>
+        <Stack align="center" gap="1" display="inline-flex">
           <StatusDot color={color} tooltip={`${label}: ${value}`} />
           <Text as="span" size="1" weight="medium">
             {label}:
           </Text>
-          <Text as="span" size="1" weight="medium" color={color}>
-            {value}
-          </Text>
+          {/* User children over value when provided, for cases when we want to
+              have its own tooltip over it */}
+          {!children && (
+            <Text as="span" size="1" weight="medium" color={color}>
+              {value}
+            </Text>
+          )}
         </Stack>
       </Tooltip>
+      {children}
     </Stack>
   );
 };
@@ -83,26 +90,26 @@ export const getSelectableStatusSummary = (
       return {
         label: "Ready to display",
         color: "blue",
-        description: "This guide is queried and ready to display",
+        description: "The guide is queried and ready to render.",
       };
     case "throttled":
       return {
         label: "Throttled",
         color: "yellow",
-        description:
-          "This guide is queried and ready to display, but throttled currently",
+        description: "The guide is queried but held back by throttle settings.",
       };
     case "queried":
       return {
         label: "Queued",
         color: "gray",
-        description: "This guide is queried but is not ready to display",
+        description:
+          "The guide is queried but waiting behind higher-priority guides.",
       };
     default:
       return {
         label: "Not queried",
         color: "red",
-        description: `This guide is not queried (${FOCUS_ERRORS.focusUnselectableGuide.toLowerCase()})`,
+        description: "No useGuide(s) call on this page matches this guide.",
       };
   }
 };
@@ -134,19 +141,19 @@ export const GuideRowDetails = ({
           label="Active"
           value={annotation.active.status ? "Yes" : "No"}
           color={annotation.active.status ? "blue" : "red"}
-          tooltip="Eligible if the guide is currently active"
+          tooltip="Whether the guide is active in this environment."
         />
         <StatusRow
           label="Archived"
           value={annotation.archived.status ? "Yes" : "No"}
           color={annotation.archived.status ? "red" : "blue"}
-          tooltip="Eligible if the guide has not been dismissed/archived by the user already"
+          tooltip="Whether the current user has dismissed this guide."
         />
         <StatusRow
           label="Targeting"
           value={annotation.targetable.status ? "Yes" : "No"}
           color={annotation.targetable.status ? "blue" : "red"}
-          tooltip="Eligible if the user meets the guide's targeting conditions"
+          tooltip="Whether the current user matches the guide's targeting conditions."
         />
       </CardContainer>
 
@@ -155,23 +162,28 @@ export const GuideRowDetails = ({
           label="Activation"
           value={annotation.activatable.status ? "Yes" : "No"}
           color={annotation.activatable.status ? "blue" : "red"}
-          tooltip="Visible when the user's current location matches the guide's activation rules"
+          tooltip="Whether the current page matches the guide's activation rules."
         />
         <StatusRow
           label="Display"
           value={selectableStatusSummary.label}
           color={selectableStatusSummary.color}
-          tooltip={
-            <Text as="span" size="1">
-              Visible when the guide is queried via `useGuide(s)` in the current
-              page,
-              <br />
-              and ready to display per its position in the display pipeline:
-              <br />
-              {selectableStatusSummary.description}
+          tooltip="Whether the guide has been queried and is ready to render on the current page."
+        >
+          <Tooltip
+            label={selectableStatusSummary.description}
+            {...sharedTooltipProps}
+          >
+            <Text
+              as="span"
+              size="1"
+              weight="medium"
+              color={selectableStatusSummary.color}
+            >
+              {selectableStatusSummary.label}
             </Text>
-          }
-        />
+          </Tooltip>
+        </StatusRow>
       </CardContainer>
     </Stack>
   );