Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(tooltips): expose passive diagnostic hints

Bingxi Zhao (Frank)4f47c55d5299
diff --git a/web/app/(workspace)/partners/[partnerId]/page.tsx b/web/app/(workspace)/partners/[partnerId]/page.tsx
index 2f3309117..43d6423eb 100644
--- a/web/app/(workspace)/partners/[partnerId]/page.tsx
+++ b/web/app/(workspace)/partners/[partnerId]/page.tsx
@@ -486,12 +486,15 @@ function PartnerDetail() {
<span className="truncate text-[14px] font-medium text-[var(--foreground)]">
{partner.name}
</span>
- <span
- title={partner.running ? t("Running") : t("Stopped")}
- className={`h-1.5 w-1.5 shrink-0 rounded-full ${
- partner.running ? "bg-emerald-500" : "bg-[var(--border)]"
- }`}
- />
+ <span className="inline-flex shrink-0 items-center gap-1 text-[10px] text-[var(--muted-foreground)]">
+ <span
+ aria-hidden
+ className={`h-1.5 w-1.5 rounded-full ${
+ partner.running ? "bg-emerald-500" : "bg-[var(--border)]"
+ }`}
+ />
+ {partner.running ? t("Running") : t("Stopped")}
+ </span>
</div>
{partner.description ? (
<p className="truncate text-[11.5px] text-[var(--muted-foreground)]">
diff --git a/web/app/(workspace)/partners/page.tsx b/web/app/(workspace)/partners/page.tsx
index 4e606d7c3..39d9a1af7 100644
--- a/web/app/(workspace)/partners/page.tsx
+++ b/web/app/(workspace)/partners/page.tsx
@@ -133,14 +133,15 @@ export default function PartnersPage() {
<span className="truncate text-[14px] font-medium text-[var(--foreground)]">
{partner.name}
</span>
- <span
- title={partner.running ? t("Running") : t("Stopped")}
- className={`h-1.5 w-1.5 shrink-0 rounded-full ${
- partner.running
- ? "bg-emerald-500"
- : "bg-[var(--border)]"
- }`}
- />
+ <span className="inline-flex shrink-0 items-center gap-1 text-[10px] text-[var(--muted-foreground)]">
+ <span
+ aria-hidden
+ className={`h-1.5 w-1.5 rounded-full ${
+ partner.running ? "bg-emerald-500" : "bg-[var(--border)]"
+ }`}
+ />
+ {partner.running ? t("Running") : t("Stopped")}
+ </span>
{partner.can_manage === false ? (
<span className="shrink-0 rounded-full bg-[var(--muted)] px-1.5 py-0.5 text-[10.5px] text-[var(--muted-foreground)]">
{t("Shared with you")}
diff --git a/web/components/courses/CourseResources.tsx b/web/components/courses/CourseResources.tsx
index f55fd5771..4bdf3b80c 100644
--- a/web/components/courses/CourseResources.tsx
+++ b/web/components/courses/CourseResources.tsx
@@ -1,5 +1,6 @@
"use client";
+import Tooltip from "@/shared/ui/Tooltip";
import { MASTERY_HOME, READING_HOME } from "@/lib/learning-routes";
import { useCallback, useEffect, useState } from "react";
@@ -210,14 +211,20 @@ export default function CourseResources({
as a separate cell its varying width pushed the kind name
to a different x-position on every row. */}
{!resource.available ? (
- <span
- className="shrink-0 cursor-help text-[10.5px] text-[var(--muted-foreground)]/80"
- title={t(
+ <Tooltip
+ label={t(
"This target no longer exists — remove the reference, or attach the resource again.",
)}
+ side="top"
>
- · {t("Unavailable")}
- </span>
+ <span
+ role="note"
+ tabIndex={0}
+ className="shrink-0 cursor-help text-[10.5px] text-[var(--muted-foreground)]/80"
+ >
+ · {t("Unavailable")}
+ </span>
+ </Tooltip>
) : null}
</span>
<span className="shrink-0 text-[10.5px] text-[var(--muted-foreground)]/70">
diff --git a/web/components/knowledge/KbIndexVersionsSection.tsx b/web/components/knowledge/KbIndexVersionsSection.tsx
index 087e84757..bf6c3a3e8 100644
--- a/web/components/knowledge/KbIndexVersionsSection.tsx
+++ b/web/components/knowledge/KbIndexVersionsSection.tsx
@@ -473,39 +473,42 @@ function IndexVersionRow({
version.version || (isLegacy ? t("Legacy index") : t("Unknown"));
const created = formatKnowledgeTimestamp(version.created_at);
+ const statusHint = isActive
+ ? t("Active version")
+ : isPhantom
+ ? t("Stale (matches active config but storage is empty)")
+ : isLegacy
+ ? t("Legacy index format")
+ : t("Inactive version");
return (
<li className="flex items-center gap-3 px-3 py-2.5">
- <div
- className={`flex h-7 w-7 shrink-0 items-center justify-center rounded-md ${
- isActive
- ? "bg-emerald-100 text-emerald-600 dark:bg-emerald-950/30 dark:text-emerald-300"
- : isPhantom
- ? "bg-amber-100 text-amber-600 dark:bg-amber-950/30 dark:text-amber-300"
- : "bg-[var(--muted)] text-[var(--muted-foreground)]"
- }`}
- title={
- isActive
- ? t("Active version")
- : isPhantom
- ? t("Stale (matches active config but storage is empty)")
- : isLegacy
- ? t("Legacy index format")
- : t("Inactive version")
- }
- >
- {isActive ? (
- <Star className="h-3.5 w-3.5" fill="currentColor" />
- ) : isBuildingLightRagCandidate ? (
- <Loader2 className="h-3.5 w-3.5 animate-spin" />
- ) : isPhantom ? (
- <AlertTriangle className="h-3.5 w-3.5" />
- ) : isLegacy ? (
- <Clock className="h-3.5 w-3.5" />
- ) : (
- <CheckCircle2 className="h-3.5 w-3.5" />
- )}
- </div>
+ <Tooltip label={statusHint} side="top">
+ <div
+ role="img"
+ aria-label={statusHint}
+ tabIndex={0}
+ className={`flex h-7 w-7 shrink-0 items-center justify-center rounded-md ${
+ isActive
+ ? "bg-emerald-100 text-emerald-600 dark:bg-emerald-950/30 dark:text-emerald-300"
+ : isPhantom
+ ? "bg-amber-100 text-amber-600 dark:bg-amber-950/30 dark:text-amber-300"
+ : "bg-[var(--muted)] text-[var(--muted-foreground)]"
+ }`}
+ >
+ {isActive ? (
+ <Star className="h-3.5 w-3.5" fill="currentColor" />
+ ) : isBuildingLightRagCandidate ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : isPhantom ? (
+ <AlertTriangle className="h-3.5 w-3.5" />
+ ) : isLegacy ? (
+ <Clock className="h-3.5 w-3.5" />
+ ) : (
+ <CheckCircle2 className="h-3.5 w-3.5" />
+ )}
+ </div>
+ </Tooltip>
<div className="min-w-0 flex-1">
<div className="flex items-center gap-2">
diff --git a/web/components/mcp/McpStatusBadge.tsx b/web/components/mcp/McpStatusBadge.tsx
index 909ce810f..1de5dd118 100644
--- a/web/components/mcp/McpStatusBadge.tsx
+++ b/web/components/mcp/McpStatusBadge.tsx
@@ -1,5 +1,6 @@
"use client";
+import Tooltip from "@/shared/ui/Tooltip";
import { useTranslation } from "react-i18next";
import type { McpServerStatus } from "@/lib/mcp-api";
@@ -27,10 +28,11 @@ export default function McpStatusBadge({
needs_auth: "bg-amber-400",
disabled: "bg-[var(--border)]",
};
- return (
+ const badge = (
<span
+ role={status === "error" && error ? "note" : undefined}
+ tabIndex={status === "error" && error ? 0 : undefined}
className="inline-flex items-center gap-1.5 rounded-full border border-[var(--border)] bg-[var(--muted)]/30 px-2 py-0.5 text-[10.5px] font-medium text-[var(--muted-foreground)]"
- title={status === "error" && error ? error : undefined}
>
<span
className={`h-1.5 w-1.5 rounded-full ${dotClass[status]}`}
@@ -39,4 +41,7 @@ export default function McpStatusBadge({
{labels[status]}
</span>
);
+ return status === "error" && error ? (
+ <Tooltip label={error} side="top">{badge}</Tooltip>
+ ) : badge;
}
diff --git a/web/components/memory/MemorySection.tsx b/web/components/memory/MemorySection.tsx
index b02bf8314..f2c02b729 100644
--- a/web/components/memory/MemorySection.tsx
+++ b/web/components/memory/MemorySection.tsx
@@ -815,14 +815,20 @@ export function L1View({
})}
<div className="ml-auto flex items-center gap-2">
{pendingCount > 0 && (
- <span
- className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-700 dark:text-amber-300"
- title={t(
+ <Tooltip
+ label={t(
"Workspace changed since last refresh. Click Refresh to commit these to the changes log.",
)}
+ side="top"
>
- {t("{{n}} pending", { n: pendingCount })}
- </span>
+ <span
+ role="note"
+ tabIndex={0}
+ className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-700 dark:text-amber-300"
+ >
+ {t("{{n}} pending", { n: pendingCount })}
+ </span>
+ </Tooltip>
)}
<Tooltip label={t("Re-scan workspace and record any changes")} side="top">
<button
@@ -847,14 +853,20 @@ export function L1View({
{compact && (
<div className="flex items-center gap-2">
{pendingCount > 0 && (
- <span
- className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-700 dark:text-amber-300"
- title={t(
+ <Tooltip
+ label={t(
"Workspace changed since last refresh. Click Refresh to commit these to the changes log.",
)}
+ side="top"
>
- {t("{{n}} pending", { n: pendingCount })}
- </span>
+ <span
+ role="note"
+ tabIndex={0}
+ className="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-700 dark:text-amber-300"
+ >
+ {t("{{n}} pending", { n: pendingCount })}
+ </span>
+ </Tooltip>
)}
<Tooltip label={t("Re-scan workspace and record any changes")} side="top">
<button
@@ -1138,12 +1150,15 @@ function PendingBadge({
} as const;
const cfg = map[kind];
return (
- <span
- className={`inline-flex items-center rounded-full border px-1.5 py-0 text-[10px] font-medium ${cfg.cls}`}
- title={t("Pending — not yet committed to changes log")}
- >
- {cfg.label}
- </span>
+ <Tooltip label={t("Pending — not yet committed to changes log")} side="top">
+ <span
+ role="note"
+ tabIndex={0}
+ className={`inline-flex items-center rounded-full border px-1.5 py-0 text-[10px] font-medium ${cfg.cls}`}
+ >
+ {cfg.label}
+ </span>
+ </Tooltip>
);
}
diff --git a/web/components/settings/MemoryUsageItem.tsx b/web/components/settings/MemoryUsageItem.tsx
index 24c97820d..320dfaf46 100644
--- a/web/components/settings/MemoryUsageItem.tsx
+++ b/web/components/settings/MemoryUsageItem.tsx
@@ -1,5 +1,6 @@
"use client";
+import Tooltip from "@/shared/ui/Tooltip";
import { Fragment, useCallback, useEffect, useState } from "react";
import { useTranslation } from "react-i18next";
@@ -164,13 +165,14 @@ export default function MemoryUsageItem() {
</span>
</span>
{usage.partial && (
- <span
- title={t(
+ <Tooltip
+ label={t(
"Only the backend and its own children. Start DeepTutor through the launcher to include the web server.",
)}
+ side="top"
>
- {t("(backend only)")}
- </span>
+ <span role="note" tabIndex={0}>{t("(backend only)")}</span>
+ </Tooltip>
)}
</div>
</Fragment>
diff --git a/web/components/space/learning/ReviewTrail.tsx b/web/components/space/learning/ReviewTrail.tsx
index 24584621e..77ea07a55 100644
--- a/web/components/space/learning/ReviewTrail.tsx
+++ b/web/components/space/learning/ReviewTrail.tsx
@@ -1,5 +1,6 @@
"use client";
+import Tooltip from "@/shared/ui/Tooltip";
import { ArrowRight, CheckCircle2, Clock3, Loader2, Play } from "lucide-react";
import { useTranslation } from "react-i18next";
import { useState } from "react";
@@ -46,12 +47,11 @@ export function ReviewTrail({
return (
<section className="flex min-h-0 flex-col overflow-hidden rounded-xl border border-[var(--border)] bg-[var(--card)] lg:max-h-[min(30vh,260px)] lg:shrink-0">
<div className="flex shrink-0 flex-wrap items-center justify-between gap-3 border-b border-[var(--border)] bg-[var(--secondary)] px-4 py-2.5">
- <h2
- className="text-[12px] font-semibold text-[var(--foreground)]"
- title={t("Scheduled by your forgetting curve")}
- >
- {t("Review plan")}
- </h2>
+ <Tooltip label={t("Scheduled by your forgetting curve")} as="div" side="top">
+ <h2 tabIndex={0} className="text-[12px] font-semibold text-[var(--foreground)]">
+ {t("Review plan")}
+ </h2>
+ </Tooltip>
<div className="flex items-center gap-3">
<label className="flex items-center gap-1.5 text-[11px] text-[var(--muted-foreground)]">
<span>{t("Recall target")}</span>
diff --git a/web/components/workspaces/WorkspacePill.tsx b/web/components/workspaces/WorkspacePill.tsx
index c1acbfb1d..141da3eac 100644
--- a/web/components/workspaces/WorkspacePill.tsx
+++ b/web/components/workspaces/WorkspacePill.tsx
@@ -149,13 +149,15 @@ export function WorkspacePill({
</Tooltip>
{error ? (
- <span
- role="alert"
- className="max-w-[180px] truncate text-[11.5px] text-[var(--destructive)]"
- title={error}
- >
- {error}
- </span>
+ <Tooltip label={`${t("Error")}: ${error}`} side="top">
+ <span
+ role="alert"
+ tabIndex={0}
+ className="max-w-[180px] truncate text-[11.5px] text-[var(--destructive)]"
+ >
+ {error}
+ </span>
+ </Tooltip>
) : null}
{open && !disabled && (
diff --git a/web/features/settings/sections/ToolsSettingsSection.tsx b/web/features/settings/sections/ToolsSettingsSection.tsx
index 49528aee4..f5f8db846 100644
--- a/web/features/settings/sections/ToolsSettingsSection.tsx
+++ b/web/features/settings/sections/ToolsSettingsSection.tsx
@@ -447,15 +447,21 @@ export default function ToolsSettingsPage() {
label={t(isEnabled ? "On" : "Off")}
/>
) : (
- <span
- className="inline-flex items-center gap-1 rounded-full bg-[var(--muted)]/40 px-2 py-0.5 text-[10.5px] text-[var(--muted-foreground)]"
- title={t(
+ <Tooltip
+ label={t(
"Auto-mounted by the agent when needed. Not user-toggleable.",
)}
+ side="top"
>
- <Lock className="h-3 w-3" />
- {t("Always on")}
- </span>
+ <span
+ role="note"
+ tabIndex={0}
+ className="inline-flex items-center gap-1 rounded-full bg-[var(--muted)]/40 px-2 py-0.5 text-[10.5px] text-[var(--muted-foreground)]"
+ >
+ <Lock className="h-3 w-3" />
+ {t("Always on")}
+ </span>
+ </Tooltip>
)}
</div>
</div>
diff --git a/web/tests/lightrag-embedding-compatibility.spec.tsx b/web/tests/lightrag-embedding-compatibility.spec.tsx
index 08d97c36d..132894ba1 100644
--- a/web/tests/lightrag-embedding-compatibility.spec.tsx
+++ b/web/tests/lightrag-embedding-compatibility.spec.tsx
@@ -1,5 +1,5 @@
import React from "react";
-import { act, fireEvent, render, screen } from "@testing-library/react";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
import { expect, it, vi } from "vitest";
import KnowledgeBaseDetail from "@/components/knowledge/KnowledgeBaseDetail";
import KbIndexVersionsSection from "@/components/knowledge/KbIndexVersionsSection";
@@ -173,8 +173,16 @@ it("shows the recorded bound version rather than a newer unbound publication", a
});
const boundRow = screen.getByText("version-1").closest("li");
const newerRow = screen.getByText("version-2").closest("li");
- expect(boundRow?.querySelector('[title="Active version"]')).not.toBeNull();
- expect(newerRow?.querySelector('[title="Inactive version"]')).not.toBeNull();
+ const boundTrigger = boundRow?.querySelector<HTMLElement>('[role="img"][aria-label="Active version"]');
+ const newerTrigger = newerRow?.querySelector<HTMLElement>('[role="img"][aria-label="Inactive version"]');
+ expect(boundTrigger?.tabIndex).toBe(0);
+ expect(newerTrigger?.tabIndex).toBe(0);
+ expect(document.getElementById(boundTrigger?.getAttribute("aria-describedby") ?? "")).toHaveTextContent("Active version");
+ expect(document.getElementById(newerTrigger?.getAttribute("aria-describedby") ?? "")).toHaveTextContent("Inactive version");
+ fireEvent.focus(boundTrigger!);
+ await waitFor(() =>
+ expect(document.body.querySelector('[role="tooltip"].fixed')).toHaveTextContent("Active version"),
+ );
});
it.each(["ready", "error"])(