feat: add tooltip integration with glossary docs

[Abejithp]

User description

SUMMARY

This PR introduces an integrated glossary system that establishes a single source of truth for term definitions used across both Superset's documentation site and the application itself. Previously, terminology explanations were fragmented across scattered tooltip descriptions, documentation pages, and various help text throughout the codebase, leading to inconsistencies and maintenance challenges when definitions needed updates.

Key Features:

• Centralizes all term definitions in a single source that powers both in-app tooltips and the documentation site
• "Write once, use everywhere" approach ensures automatic consistency when definitions are added or updated
• Eliminates outdated or contradictory explanations across the platform

Implementation:

• Wraps the existing Tooltip component to detect glossary-encoded strings and transform them into interactive elements
• Uses simple encoding pattern (e.g., glossary.Query.Row_Limit.encode()) with type safety and IDE autocompletion
• Documentation page dynamically renders from the same source definitions as tooltips
• Interactive tooltips include "Click to Learn More" links that navigate to the glossary docs

Current Scope & Future Plans:

• Initial implementation focuses on the Explore interface with a small subset of chart controls (Dimensions, Metrics, Series, Row Limit, Sort, Time Shift)
• Architecture designed to scale application-wide
• Future expansion planned for dashboards, SQL Lab, dataset configuration, and other interfaces throughout Superset

---

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Before:

After:

https://github.com/user-attachments/assets/2b69fd20-5ccb-45ae-8417-8b11d5dce58e

TESTING INSTRUCTIONS

Prerequisites

• Superset backend running on http://localhost:8088
• Python virtual environment activated

Steps

1. Start the frontend development server:

cd superset-frontend
npm install
npm run dev-server

2. Start the documentation server:

cd docs
yarn install
yarn docusaurus start 

Note: Set the docs version dropdown to "next" in the top navigation bar to see the glossary page. The glossary feature is only available in the next version documentation.

3. Navigate to a chart in Explore view

   • Open http://localhost:9000 in your browser
   • Navigate to Charts → Select any existing chart (e.g., "Games per Genre over time")

4. Test glossary-integrated tooltips

   Currently, only a small subset of controls have been integrated with the glossary. Test the following:

   Query Section:

   • Hover over the info icon (ℹ️) next to these control labels:
     • "Dimensions" - Shows description about qualitative categorization data
     • "Metrics" - Shows description about aggregation functions
     • "Series" or "Series Limit" - Shows description about limiting series displayed
     • "Row Limit" - Shows description about limiting rows displayed
     • "Sort" - Shows description about query result ordering

   Advanced Analytics Section (if visible):

   • "Time Shift" - Shows description about overlaying relative time periods

5. Verify glossary tooltip interaction

   For any glossary-integrated tooltip:

   a. Hover behavior:

   • Hover over the info icon to display the tooltip
   • Verify the tooltip shows the term description
   • Verify the tooltip includes "Click to Learn More" text at the bottom
   • Verify the info icon is highlighted in blue when hovering

   b. Click behavior:

   • Click on the info icon with the tooltip displayed
   • Verify it opens http://localhost:3000/docs/glossary in a new tab
   • Verify the URL includes a hash fragment (e.g., #Query__Row_Limit)
   • Verify the corresponding term row is highlighted on the glossary page
   • Verify the page scrolls to center the term in view

Additional controls will be integrated in future iterations.

ADDITIONAL INFORMATION

• [ ] Has associated issue:
• [ ] Required feature flags:
• [x] Changes UI
• [ ] Includes DB Migration
  • [ ] Migration is atomic, supports rollback & is backwards-compatible
  • [ ] Confirm DB migration upgrade and downgrade tested
  • [ ] Runtime estimates and downtime expectations provided
• [x] Introduces new feature or API
• [ ] Removes existing feature or API

---

CodeAnt-AI Description

Add centralized glossary with clickable tooltips and a documentation Glossary page

What Changed

• Tooltips and control descriptions now use a single, centralized glossary for short definitions; controls such as Time shift, Dimensions, Metrics, Series, Row limit, and Sort show the glossary text instead of disparate inline descriptions.
• The Tooltip component recognizes glossary-encoded strings and, when present, shows the glossary short description and makes the tooltip target a link that opens the glossary entry in a new tab with a "Click to Learn More" prompt.
• A new Glossary documentation page lists topics and terms in a searchable table, supports deep-linking to specific terms via URL hashes, and highlights the referenced row when opened.
• The glossary data is exported for reuse across the frontend and docs so the same definitions power both in-app tooltips and the documentation page.

Impact

✅ Consistent tooltip text across controls ✅ Click-to-learn-more links from control tooltips ✅ Glossary index page in docs for quick term lookup

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

[rusackas]

Thanks for your patience here... we want to give this a thorough review, we're just trying to catch up with the backlog 😅

Meanwhile, re-running CI 🤞

[codeant-ai-for-open-source[bot]]

CodeAnt AI is reviewing your PR.

[codeant-ai-for-open-source[bot]]

Nitpicks 🔍

🔒 No security issues identified

⚡ Recommended areas for review [ ] Runtime Error The resolver uses an undefined variable t in term.getShort(t). This will throw a ReferenceError at runtime when a glossary term is resolved, causing the Tooltip (and potentially other consumers) to crash. The glossary lookup code must be fixed or guarded at the call site. [ ] decodeURIComponent can throw decodeURIComponent(window.location.hash.slice(1)) can throw if the hash contains malformed percent-encoding. This will break the effect and may cause an uncaught exception on page load. [ ] Behavioral Change The component returns children early when title is not a string. Previously the wrapper always rendered an Antd Tooltip and forwarded props. This change removes tooltips for non-string title values (e.g., React nodes) and is a breaking behavioral change that can remove intended tooltips across the app. [ ] Unexpected default export The file exports an empty default object (export default {}) while also re-exporting a glossary named export from glossaryUtils. Consumers may import the default expecting the glossary implementation and get an empty object instead, causing runtime bugs or confusing API surface. [ ] Build & type declarations Adding this re-export requires confirming that the build pipeline and type declarations include the glossary module (JS and .d.ts). Verify package exports/tsconfig and the published package include the module so consumers don't get runtime or typing errors. [ ] Potential circular import Re-exporting a module from a central barrel can introduce circular dependencies if ./glossary imports from other re-exported modules. Check for cycles to avoid runtime errors. [ ] Missing doc file The sidebar references a doc id glossary. If there is no corresponding docs/glossary.md (or docs/glossary/index.md) this will cause the Docusaurus build to fail. Confirm the doc file exists and that the id matches the document frontmatter id (if present). [ ] Hardcoded Base URL The base docs URL is hardcoded to 'http://localhost:3000/docs'. This will be incorrect in non-dev environments and forces http. It should be configurable (env/runtime) and default to the current origin or a build-time config so links are correct and use the appropriate scheme (https) in production.

[codeant-ai-for-open-source[bot]]

CodeAnt AI finished reviewing your PR.

[codeant-ai-for-open-source[bot]]

CodeAnt AI is running Incremental review

[codeant-ai-for-open-source[bot]]

CodeAnt AI is running Incremental review