Repository navigation
feat: show an optional tile description as a tooltip - #3352
Conversation
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 detectedLatest commit: ad297c7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
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 |
|
@felipe-carvalho12 is attempting to deploy a commit to the HyperDX Team on Vercel. A member of the Team first needs to authorize it. |
|
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 ? ( | |||
There was a problem hiding this comment.
🔵 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(), |
There was a problem hiding this comment.
🔵 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; |
There was a problem hiding this comment.
🔵 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
PR Review
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
Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides. |
[Medium impact] Adds optional description field to dashboard tiles. The PR should not merge until
|
| // 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(), |
There was a problem hiding this comment.
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.
| <Tooltip label={chart.description} multiline maw={360} withArrow> | ||
| <IconInfoCircle | ||
| size={14} | ||
| aria-label={chart.description} | ||
| data-testid={`tile-description-${chart.id}`} | ||
| /> |
There was a problem hiding this comment.
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.
| <Group gap={4} wrap="nowrap"> | ||
| <Text size="sm">{chart.config.name}</Text> | ||
| {chart.description && ( | ||
| <Tooltip label={chart.description} multiline maw={360} withArrow> |
There was a problem hiding this comment.
Deep ReviewThe diff adds an optional 🔴 P0/P1 — must fix
🟡 P2 — recommended
🔵 P3 nitpicks (1)
Reviewers (5): correctness, kieran-typescript, api-contract, testing, previous-comments. Testing gaps:
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 |
|
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! |
| <Text size="sm">{chart.config.name}</Text> | ||
| {chart.description && ( | ||
| <Tooltip label={chart.description} multiline maw={360} withArrow> | ||
| <IconInfoCircle |
There was a problem hiding this comment.
🔵 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(), |
There was a problem hiding this comment.
🔵 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
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
| 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(), |
There was a problem hiding this comment.
🔵 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 |
There was a problem hiding this comment.
🔵 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 && ( |
There was a problem hiding this comment.
🔵 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
## 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
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
descriptionfield 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:
descriptiononTileSchema, max 1,024 characters.descriptionadded to the tile schema, passed through both converters (convertToInternalTileConfigandconvertTileToExternalChart), and documented in the OpenAPI spec. It's omitted from responses when unset.DBDashboardPagerenders anIconInfoCirclewith a MantineTooltipbeside the tile title when a description exists. Tiles without one render exactly as before.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):
PUT /api/v2/dashboards/:idwith a tile that has"description": "What this tile shows.".Testing
tsc --noEmitpasses for api and app.References
🤖 Generated with Claude Code