Skip to content

feat: show an optional tile description as a tooltip - #3352

Merged
kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
taicor-ai:feat/tile-description-tooltip
Oct 19, 2026
Merged

kodiakhq[bot] merged 3 commits into
ClickHouse:mainfrom
taicor-ai:feat/tile-description-tooltip

Conversation

@felipe-carvalho12

Copy link
Copy Markdown
Contributor

Summary

Dashboard tiles have a name but nowhere to explain what they show, what's excluded, or how to read them. This PR adds an optional description field to tiles. The dashboard shows it as an info icon with a tooltip next to the tile name, which is the usual pattern for panel descriptions in dashboard tools.

Changes:

  • Schema (common-utils): optional description on TileSchema, max 1,024 characters.
  • External Dashboards API v2: description added to the tile schema, passed through both converters (convertToInternalTileConfig and convertTileToExternalChart), and documented in the OpenAPI spec. It's omitted from responses when unset.
  • App: DBDashboardPage renders an IconInfoCircle with a Mantine Tooltip beside the tile title when a description exists. Tiles without one render exactly as before.
  • Storage: tiles are stored in a Mixed field, so the Mongo model doesn't change.

There's no editor field yet. Descriptions come from the external API, which is how we manage dashboards as code. An editor input could follow if the field is wanted.

This is separate from #2253, which adds a description to the dashboard as a whole rather than to each tile.

Screenshots or video

Not included. The change is a small icon and tooltip next to the tile title, and only appears on tiles that have a description.

How to test on Vercel preview

N/A. Local mode has no way to set a tile description from the UI yet; the field is set through the external Dashboards API.

Steps (local stack):

  1. Create or update a dashboard through PUT /api/v2/dashboards/:id with a tile that has "description": "What this tile shows.".
  2. Open the dashboard and hover the info icon next to that tile's name.
  3. Verify the tooltip shows the description, and that tiles without one have no icon.

Testing

  • New unit tests cover the round trip through the external and internal tile shapes, and the field being left out when unset.
  • tsc --noEmit passes for api and app.
  • External API tests pass (132).

References

🤖 Generated with Claude Code

Tiles accept an optional description through the internal schema and the
external Dashboards API. The dashboard shows it as an info icon with a
tooltip next to the tile name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@changeset-bot

changeset-bot Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: ad297c7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@hyperdx/common-utils Patch
@hyperdx/api Patch
@hyperdx/app Patch
@hyperdx/otel-collector Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@vercel

vercel Bot commented Oct 10, 2026

Copy link
Copy Markdown

@felipe-carvalho12 is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions github-actions Bot added external needs-vouch Author needs a maintainer to vouch for them labels Oct 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Hi @felipe-carvalho12, thanks for the pull request!

Before we review code from a first-time contributor we ask that a maintainer vouches for you, and you're not on our list yet. This PR stays open — it just isn't in the review queue until someone vouches.

To get vouched, open an issue saying hello and what you're working on:

https://github.com/hyperdxio/hyperdx/issues/new?template=introduce-yourself.md

A maintainer will usually reply within a day or two, and then this PR gets picked up as normal. More detail in our contributing guide.

@@ -1225,9 +1226,20 @@ const Tile = ({
const title = useMemo(
() =>
chart.config.name ? (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Description is never shown on tiles with an empty name

The info icon is rendered inside the chart.config.name ? … : undefined branch. The external schema allows name: '' (externalDashboardTileSchema.name is z.string() in packages/api/src/utils/zod.ts:786), so a stored description on an unnamed tile, such as a markdown note, is invisible. Render the title group when either the name or the description is present.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

containerId: z.string().min(1).optional(),
// For tiles inside a tab container: which tab this tile belongs to
tabId: z.string().min(1).optional(),
description: z.string().max(1024).optional(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The 1024 length cap is written separately in two schemas

TileSchema.description and externalDashboardTileSchema.description (packages/api/src/utils/zod.ts:811) both hardcode max(1024). The neighbouring DASHBOARD_CONTAINER_ID_MAX is exported for exactly this purpose: one shared limit for the internal and external schemas. Export a TILE_DESCRIPTION_MAX next to it and use it in both schemas (and in the OpenAPI JSDoc).

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

config: SavedChartConfig;
containerId?: string;
tabId?: string;
description?: string;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The app's Tile type is a hand-maintained copy of the common-utils Tile type

Every new tile field now has to be added by hand to both the app type here and TileSchema in packages/common-utils/src/types.ts:2047, with no alias or test linking them, which breaks the DRY convention. Alias it instead (export type Tile = _Tile from @hyperdx/common-utils/dist/types) so description and later fields come from one source.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

5 finding(s): 🔴 0 critical · 🟠 2 major · 🔵 3 minor

3 posted as inline comment(s) on the changed lines. 2 listed below.

Findings outside the changed lines

  • 🟠 packages/api/src/mcp/tools/dashboards/patchDashboard.ts:133 — MCP patch_dashboard deletes an existing tile description → mergedTile copies name, layout, containerId and tabId from the existing tile but not description. convertToInternalTileConfig(mergedTile) then writes tiles.$ without it, so any MCP patch to a tile silently deletes the description that was set through the v2 API. Add description to existingInternalTile's type and merge it the same way tabId is merged: 'description' in incoming ? incoming.description : existingInternalTile.description.
  • 🟠 packages/api/src/mcp/tools/dashboards/schemas.ts:645 — MCP tile schemas don't accept description, so MCP saves strip it → Neither mcpTileLayoutSchema nor mcpPatchTileLayoutSchema (line 1195) declares description. Zod drops unknown keys, so this sequence loses data: an agent reads a dashboard (convertToExternalDashboard now returns description), then saves it back with save_dashboard, and every description is gone. Add description: z.string().max(1024).optional() to both layout schemas, matching externalDashboardTileSchema.

Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@greptile-apps

greptile-apps Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] Adds optional description field to dashboard tiles.

The PR should not merge until series tiles preserve descriptions.

Fix All in Claude CodeFindings

  1. P1 Series tiles lose descriptions ▶
  2. P2 Keyboard users cannot open descriptions ▶
  3. P2 Unnamed tiles hide descriptions ▶

Summary

Adds an optional tile description and shows it in a tooltip beside the tile name.

  • Dashboard tiles can show a description beside their name.

Reviews (3) · Last reviewed commit: "Merge branch 'main' into feat/tile-descr..." · Reviewed by Greptile

// valid container id from the editor always fits.
containerId: z.string().min(1).max(DASHBOARD_CONTAINER_ID_MAX).optional(),
tabId: z.string().min(1).max(DASHBOARD_CONTAINER_ID_MAX).optional(),
description: z.string().max(1024).optional(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Series tiles lose descriptions

The new description field is accepted for tiles using series, but only tiles using config preserve it. Both create and update send series tiles through translateExternalChartToTileConfig, which leaves out description. Requests succeed, but the text disappears from storage and responses. Copy the field in that converter too, and test this path through convertExternalTilesToInternal.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

Comment on lines +1232 to +1237
<Tooltip label={chart.description} multiline maw={360} withArrow>
<IconInfoCircle
size={14}
aria-label={chart.description}
data-testid={`tile-description-${chart.id}`}
/>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Keyboard users cannot open descriptions

Tooltip wraps a bare IconInfoCircle with no focusable wrapper or tabIndex. Adding aria-label does not make it reachable with the keyboard, so keyboard users cannot open the description. Use a focusable control and explicitly enable opening the tooltip on focus.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

Comment on lines +1229 to +1232
<Group gap={4} wrap="nowrap">
<Text size="sm">{chart.config.name}</Text>
{chart.description && (
<Tooltip label={chart.description} multiline maw={360} withArrow>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Unnamed tiles hide descriptions

The API accepts name: "", but the new tooltip remains inside the chart.config.name check. An unnamed tile can save a description without showing any way to read it. Render the description icon whenever a description exists, even if the tile has no title.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

The diff adds an optional description to dashboard tiles across the schema, the external Dashboards API v2, and the UI tooltip. The schema and OpenAPI additions are internally consistent and the config-tile round trip works. The one material gap is that the API accepts description on every tile shape but only persists it for config-shaped tiles — series-shaped tiles silently drop it.

🔴 P0/P1 — must fix

  • packages/api/src/utils/externalApi.ts:56 — externalDashboardTileSchema accepts description on all tile shapes, but convertExternalTilesToInternal routes series-shaped tiles to translateExternalChartToTileConfig, which neither destructures nor returns description, so a series tile (time/table/number/search/markdown — the primary external shape) submitted with a description validates, returns 200, and silently loses the field in storage and on every subsequent GET and in the UI tooltip; only config tiles persist it.
    • Fix: Destructure and conditionally spread description in translateExternalChartToTileConfig mirroring the config-tile path, and add a round-trip test through convertExternalTilesToInternal for a series tile.
    • correctness, api-contract, testing, previous-comments

🟡 P2 — recommended

  • packages/app/src/DBDashboardPage.tsx:1146 — the Mantine Tooltip wraps a bare IconInfoCircle SVG that is not in the tab order, so the tooltip is hover-only and keyboard-only users cannot reveal the description despite the aria-label.
    • Fix: Wrap the icon in a focusable control (e.g. ActionIcon or a span/button with tabIndex={0}) so the tooltip's focus trigger fires.
    • kieran-typescript, previous-comments
🔵 P3 nitpicks (1)
  • packages/app/src/DBDashboardPage.tsx:1142 — the entire title node, including the description icon, is gated behind chart.config.name, so a tile that has a description but an empty/undefined name renders no icon and the description is unreachable.
    • Fix: Render the Group when either chart.config.name or chart.description is present.

Reviewers (5): correctness, kieran-typescript, api-contract, testing, previous-comments.

Testing gaps:

  • No test exercises the series-tile path (translateExternalChartToTileConfig via convertExternalTilesToInternal) for description — the exact path that drops it; the new tests only cover the config/markdown path.
  • No boundary test for the new max(1024) length constraint in zod.ts / TileSchema.
  • No UI test asserts the tooltip renders when description is set (a data-testid is plumbed in but referenced by nothing).

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@karl-power

karl-power commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Hi @felipe-carvalho12 Thanks for the PR - this is a nice feature!

It would be great to be able to edit the description in the UI as well - can you please add that?

Please also check the P1 comment here (it should be a small change), and then follow these steps too. Thanks!

@pulpdrew pulpdrew left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM whoops, sorry, missed the Karl had requested some changes here. Agreed it would be great to be able to edit the description in the UI! Please address that and Karl can give the final approval.

@pulpdrew
pulpdrew requested review from pulpdrew and removed request for pulpdrew October 13, 2026 17:51
<Text size="sm">{chart.config.name}</Text>
{chart.description && (
<Tooltip label={chart.description} multiline maw={360} withArrow>
<IconInfoCircle

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Tooltip trigger is a non-focusable SVG, so keyboard users can't open the description

IconInfoCircle gets no tabIndex or role, so the Mantine Tooltip only opens on mouse hover. Keyboard users can't reach the tile description at all. Wrap the icon in a focusable element, e.g. a <span tabIndex={0} role="img" aria-label=...> or an ActionIcon variant="subtle", so focus opens the tooltip.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

containerId: z.string().min(1).optional(),
// For tiles inside a tab container: which tab this tile belongs to
tabId: z.string().min(1).optional(),
description: z.string().max(1024).optional(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Tile description max length is a magic number repeated in two schemas

1024 is hardcoded in TileSchema and again in externalDashboardTileSchema (packages/api/src/utils/zod.ts:811), so the two can drift apart. Export a TILE_DESCRIPTION_MAX constant from common-utils, following the existing DASHBOARD_CONTAINER_ID_MAX pattern, and use it in both schemas.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@vercel

vercel Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Oct 19, 2026 11:12am UTC
hyperdx-storybook Ready Ready Preview Oct 19, 2026 11:12am UTC

Request Review

containerId: z.string().min(1).optional(),
// For tiles inside a tab container: which tab this tile belongs to
tabId: z.string().min(1).optional(),
description: z.string().max(1024).optional(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The 1024 limit is hardcoded in three places

max(1024) is repeated in TileSchema, externalDashboardTileSchema (packages/api/src/utils/zod.ts:811) and the OpenAPI doc. Export a TILE_DESCRIPTION_MAX constant next to the existing DASHBOARD_CONTAINER_ID_MAX in common-utils and use it in both Zod schemas, the way containerId/tabId already do.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

<Text size="sm">{chart.config.name}</Text>
{chart.description && (
<Tooltip label={chart.description} multiline maw={360} withArrow>
<IconInfoCircle

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — Keyboard and screen-reader users can't reach the description

The tooltip is attached to a bare IconInfoCircle SVG. It can't take keyboard focus, so the tooltip only opens on mouse hover, and screen readers announce an aria-label on an SVG with no role unreliably. Wrap the icon in a focusable element (e.g. <ActionIcon variant="subtle" size="xs" aria-label="Tile description">), or give it tabIndex={0} and role="img", so focus opens the tooltip.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

<Text size="sm">{chart.config.name}</Text>
<Group gap={4} wrap="nowrap">
<Text size="sm">{chart.config.name}</Text>
{chart.description && (

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — The tooltip rendering has no test

The new tests only cover the API converters. No test checks that the icon and tooltip appear when chart.description is set and are absent when it isn't. The tile-description-${id} test id is added but nothing uses it. Add a component or E2E test that sets a description and asserts the tooltip shows it.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

@kodiakhq
kodiakhq Bot merged commit 02080f2 into ClickHouse:main Oct 19, 2026
29 checks passed
kodiakhq Bot pushed a commit that referenced this pull request Oct 19, 2026
## Summary

Follow-up to #3352: adds a Description field to the tile editor and fixes series tiles dropping their description in the external API.

- The description is now stored on the tile's chart config next to `name` (`tile.config.description`) instead of on the tile. This lets the editor form save it with the rest of the config. It is added to the builder, raw SQL, and PromQL saved-config schemas, max 1,024 characters, and removed from `TileSchema`.
- Tile editor: a "Description" input next to the "Chart Name" input, shown for dashboard tiles. It stacks under the name below the `lg` breakpoint. Clearing it removes the field.
- External Dashboards API v2: the request and response shape is unchanged (`description` at the top level of the tile). The converters now write it into and read it from `config`, the same way `name` is handled.
- Fixes a bug where tiles sent with `series` lost their `description`, because `translateExternalChartToTileConfig` did not copy it. Both tile shapes are now tested through `convertExternalTilesToInternal`.
- The dashboard tooltip reads `chart.config.description`.

### Screenshot

<img width="1963" height="616" alt="Screenshot 2026-10-19 at 12 57 45" src="https://github.com/user-attachments/assets/c13f1cad-4c3e-4ac8-ba66-43722e4722fb" />

### How to test

1. Open any dashboard and edit a tile.
2. Enter text in the Description field next to Chart Name and click Save.
3. Hover the info icon next to the tile name to see the description.
4. Narrow the window below 1200px and confirm Description stacks under Chart Name.

**External API:** create a dashboard through `POST /api/v2/dashboards` with one `series` tile and one `config` tile that each set `description`. A `GET` returns it on both. On `main` the `series` tile comes back without it.

### References

- Related PRs: #3352

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — ad297c75 Deployed Oct 19, 2026 by vercel[bot]
Preview – hyperdx-storybook — ad297c75 Deployed Oct 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge external needs-vouch Author needs a maintainer to vouch for them

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants