feat: add tooltip integration with glossary docs

[Abejithp]

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:

1129.1.mp4

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:
• 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
• 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.

[Copilot]

Pull request overview

This PR introduces a centralized glossary system that serves as a single source of truth for terminology definitions used across both Superset's application tooltips and documentation site. The implementation uses an encoding pattern to transform existing tooltip descriptions into interactive elements that link to glossary documentation.

Key Changes:

• Adds glossary infrastructure with type-safe term definitions organized by topics (Query, Advanced Analytics)
• Wraps the Tooltip component to detect glossary-encoded strings and enhance them with "Click to Learn More" links
• Integrates glossary terms into chart controls (Dimensions, Metrics, Series, Row Limit, Sort, Time Shift) across multiple plugins
• Creates a dynamic glossary documentation page that renders from the same source definitions

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
superset-frontend/packages/superset-ui-core/src/glossary/index.ts	Exports glossary models and utilities for public consumption
superset-frontend/packages/superset-ui-core/src/glossary/glossaryUtils.ts	Implements glossary encoding/decoding logic and URL building with hardcoded localhost base URL
superset-frontend/packages/superset-ui-core/src/glossary/glossaryModels.ts	Defines GlossaryTerm, GlossaryTopic, and GlossaryMap classes with circular dependency on glossaryUtils
superset-frontend/packages/superset-ui-core/src/glossary/glossary.ts	Contains centralized term definitions with local translation function that shadows imported one
superset-frontend/packages/superset-ui-core/src/components/Tooltip/index.tsx	Enhances Tooltip component to detect glossary strings and wrap with links
superset-frontend/packages/superset-ui-core/src/index.ts	Adds glossary exports to core package public API
superset-frontend/src/explore/controlPanels/sections.tsx	Replaces hardcoded Time Shift description with glossary-encoded string
superset-frontend/src/explore/components/ControlHeader.tsx	Removes unused tooltipOnClick prop and simplifies Tooltip usage
superset-frontend/plugins/legacy-preset-chart-nvd3/src/NVD3Controls.tsx	Replaces Time Shift description with glossary reference
superset-frontend/plugins/legacy-plugin-chart-rose/src/controlPanel.tsx	Replaces Time Shift description with glossary reference
superset-frontend/plugins/legacy-plugin-chart-partition/src/controlPanel.tsx	Replaces Time Shift description with glossary reference
superset-frontend/packages/superset-ui-chart-controls/src/shared-controls/sharedControls.tsx	Replaces Series and Row Limit descriptions with glossary references
superset-frontend/packages/superset-ui-chart-controls/src/shared-controls/dndControls.tsx	Replaces Dimension, Metric, and Sort descriptions with glossary references
superset-frontend/packages/superset-ui-chart-controls/src/sections/timeComparison.tsx	Replaces Time Shift description with glossary reference
superset-frontend/packages/superset-ui-chart-controls/src/sections/advancedAnalytics.tsx	Replaces Time Shift description with glossary reference
docs/docs/glossary.mdx	Creates interactive glossary documentation page with scroll-to-term functionality
docs/sidebars.js	Adds Glossary entry to documentation sidebar
docs/webpack.extend.ts	Removes commented-out alias configuration
docs/package.json	Downgrades antd and caniuse-lite dependencies
docs/yarn.lock	Updates lock file with dependency version changes

[Copilot]

The local t() function shadows the imported t function from @superset-ui/core (used in glossaryUtils.ts line 22). This can cause confusion and translation issues. The local identity function should be renamed (e.g., to identity or noTranslate) to avoid shadowing the actual translation function, or the real translation function should be used consistently throughout.

[Copilot]

The useEffect hook is missing scrollToRow in its dependency array, which violates React's rules of hooks. This could lead to stale closures or unexpected behavior. Add scrollToRow to the dependency array or use useCallback to memoize the scrollToRow function.

[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]

CodeAnt AI finished reviewing your PR.

[codeant-ai-for-open-source]

CodeAnt AI is running Incremental review

[codeant-ai-for-open-source]

CodeAnt AI is running Incremental review

[rusackas]

I promise I'll follow up here!