[Feature Request]: Contextual Hover-Help Tooltips in UI

[crivetimihai]

[Feature Request]: Contextual Hover-Help Tooltips

🧭 Epic

Title: Contextual Hover-Help Tooltips
Goal: Surface concise, always-visible explanations for every primary action in the Admin UI by adding lightweight hover (and focus) tooltips.
Why now: New administrators often ask what "Add New Tool" or the ⚙️ "Test" icon actually do. Embedding the guidance inline eliminates context-switching to docs and reduces onboarding time.

---

🧭 Type of Feature

• Enhancement to existing functionality

---

🙋‍♂️ User Story 1 – Creation Buttons

As a: Gateway administrator
I want: clear tooltips on every "Add New …" button
So that: I instantly understand what gets created before clicking.

✅ Acceptance Criteria

Scenario: Tooltip on "Add New Server"
  Given I am on the "Virtual Servers Catalog" panel
  When I hover OR keyboard-focus the "➕ Add New Server" control
  Then a tooltip appears within 200 ms reading
       "Creates a new Virtual Server by combining Tools, Resources & Prompts from global catalogs."
  And the tooltip disappears when the control loses hover/focus

Scenario: Tooltip on other creation buttons
  Given I am on each catalog panel (Tools, Resources, Prompts, Gateways, Roots)
  When I hover/focus the respective "Add New …" control
  Then I see the tooltip text listed in "Tooltip Copy Map" (below)

---

🙋‍♂️ User Story 2 – Action Buttons

As a: Gateway administrator
I want: hover help for critical row-level actions (⚙️ Test, 🔄 Activate/Deactivate, 🗑️ Delete)
So that: I avoid unintended destructive operations.

✅ Acceptance Criteria

Scenario: Tooltip on Deactivate action
  Given a tool row shows "Deactivate"
  When I hover/focus the link
  Then a tooltip reads "Temporarily disables this item (can be re-activated)."

Scenario: Tooltip on Delete action
  Given a row shows "Delete"
  When I hover/focus the link
  Then a tooltip reads "Permanently deletes this item – cannot be undone."

---

🙋‍♂️ User Story 3 – Accessibility & Theme Support

As a: keyboard-only or screen-reader user
I want: tooltips to appear on focus and expose ARIA aria-describedby text
So that: the guidance is available without a mouse and in both light/dark modes.

✅ Acceptance Criteria

Scenario: Keyboard focus
  When I tab to any actionable element with a tooltip
  Then the tooltip becomes visible
  And the element has aria-describedby linking to the tooltip content

Scenario: Dark mode
  Given I toggle dark mode
  Then tooltip styling remains legible (contrast ratio ≥ 4.5:1)

---

📝 Tooltip Copy Map

Location	Control	Tooltip text
Virtual Servers Catalog	Add New Server	Creates a new Virtual Server by combining Tools, Resources & Prompts from global catalogs.
Global Tools	Add New Tool	Registers a new Tool from an existing REST or MCP endpoint.
Global Resources	Add New Resource	Uploads or links a reusable data asset (file, URI, or text).
Global Prompts	Add New Prompt	Creates a reusable message template with parameters.
Gateways / MCP Servers	Add New Gateway	Registers an external MCP server and imports its catalogs.
Roots	Add New Root	Registers a base directory that MCP servers can browse for files.
Row action – Test	Test	Execute this Tool with sample inputs.
Row action – Activate	Activate	Re-enable an inactive item.
Row action – Deactivate	Deactivate	Temporarily disable this item (can be re-activated).
Row action – Delete	Delete	Permanently delete this item – cannot be undone.

---

📐 Design Sketch (optional)

sequenceDiagram
    participant User
    participant UI
    participant Tooltip

    User->>UI: hover/focus Add New Tool
    UI->>Tooltip: show(text, position)
    User-->>UI: mouseout/blur
    UI->>Tooltip: hide()

Loading

---

🔗 MCP Standards Check

• Pure front-end change; no protocol impact
• No breaking changes to existing MCP integrations

---

🔄 Alternatives Considered

Approach	Pros	Cons
Inline help text under each control	Always visible	Visual clutter, harder to scan
Link to docs	Zero code	Forces context-switch; slows workflow
Onboarding tour	Rich guidance	One-off; doesn’t help day-to-day

Chosen: Always-available tooltips—minimal effort, maximal clarity.

---

📓 Additional Context

• Use a lightweight Tailwind + Alpine pattern (relative wrapper ➜ absolute tooltip) to avoid extra JS libraries.
• Ensure tooltip hides on scroll to prevent orphaned bubbles.
• Follow IBM accessibility guidelines for timing (appear ≤ 200 ms, disappear ≤ 300 ms).
• Not yet in scope: strings added to i18n bundle