From 2def1a8febe1acaf463219c08e25ee085bcc0362 Mon Sep 17 00:00:00 2001 From: Felipe Carvalho Date: Sat, 10 Oct 2026 18:31:41 -0300 Subject: [PATCH] feat: show an optional tile description as a tooltip 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 --- .changeset/tile-description-tooltip.md | 8 ++++++++ packages/api/openapi.json | 6 ++++++ .../src/routers/external-api/v2/dashboards.ts | 5 +++++ .../v2/utils/__tests__/dashboards.test.ts | 19 +++++++++++++++++++ .../external-api/v2/utils/dashboards.ts | 4 +++- packages/api/src/utils/zod.ts | 1 + packages/app/src/DBDashboardPage.tsx | 16 ++++++++++++++-- packages/app/src/dashboard.ts | 1 + packages/common-utils/src/types.ts | 1 + 9 files changed, 58 insertions(+), 3 deletions(-) create mode 100644 .changeset/tile-description-tooltip.md diff --git a/.changeset/tile-description-tooltip.md b/.changeset/tile-description-tooltip.md new file mode 100644 index 0000000000..9a5db5a4df --- /dev/null +++ b/.changeset/tile-description-tooltip.md @@ -0,0 +1,8 @@ +--- +'@hyperdx/common-utils': patch +'@hyperdx/api': patch +'@hyperdx/app': patch +--- + +Add an optional tile description, accepted by the external Dashboards API and +shown as an info tooltip next to the tile name. diff --git a/packages/api/openapi.json b/packages/api/openapi.json index 1ac293d77f..bf9628c491 100644 --- a/packages/api/openapi.json +++ b/packages/api/openapi.json @@ -3317,6 +3317,12 @@ "maxLength": 256, "description": "References a tab inside the tile's container by id. Requires containerId to be set, and the container to declare a matching tab.", "example": "errors" + }, + "description": { + "type": "string", + "maxLength": 1024, + "description": "Short explanation of the tile, shown as a tooltip next to its name.", + "example": "Share of API requests that returned a 5xx response." } } }, diff --git a/packages/api/src/routers/external-api/v2/dashboards.ts b/packages/api/src/routers/external-api/v2/dashboards.ts index 1b221b19ce..2efb020ef7 100644 --- a/packages/api/src/routers/external-api/v2/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/dashboards.ts @@ -1882,6 +1882,11 @@ const EXTERNAL_DASHBOARD_PROJECTION = { * maxLength: 256 * description: References a tab inside the tile's container by id. Requires containerId to be set, and the container to declare a matching tab. * example: "errors" + * description: + * type: string + * maxLength: 1024 + * description: Short explanation of the tile, shown as a tooltip next to its name. + * example: "Share of API requests that returned a 5xx response." * * TileOutput: * description: Response format for dashboard tiles diff --git a/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts b/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts index 259a4a8313..11ad83d8cc 100644 --- a/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts +++ b/packages/api/src/routers/external-api/v2/utils/__tests__/dashboards.test.ts @@ -92,6 +92,25 @@ describe('convertToInternalTileConfig', () => { }); }); +describe('tile description', () => { + it('round-trips through the external and internal tile shapes', () => { + const internal = convertToInternalTileConfig( + makeMarkdownTile('# Hello', { description: 'What this tile shows.' }), + ); + expect(internal.description).toBe('What this tile shows.'); + + const ext = convertToExternalDashboard(makeDoc({ tiles: [internal] })); + expect(ext.tiles[0].description).toBe('What this tile shows.'); + }); + + it('omits the field when unset', () => { + const internal = convertToInternalTileConfig(makeMarkdownTile('# Hello')); + expect(internal).not.toHaveProperty('description'); + const ext = convertToExternalDashboard(makeDoc({ tiles: [internal] })); + expect(ext.tiles[0]).not.toHaveProperty('description'); + }); +}); + describe('dashboard container validation helpers', () => { // Drives the two helpers in sequence (mirroring production usage: // schema-level structure check, then handler-level tile-ref check) diff --git a/packages/api/src/routers/external-api/v2/utils/dashboards.ts b/packages/api/src/routers/external-api/v2/utils/dashboards.ts index c535ae9a69..e3852c701a 100644 --- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts +++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts @@ -659,6 +659,7 @@ function convertTileToExternalChart( config: convertToExternalTileChartConfig(tile.config) ?? defaultTileConfig, ...(containerId !== undefined ? { containerId } : {}), ...(tabId !== undefined ? { tabId } : {}), + ...(tile.description ? { description: tile.description } : {}), }; } @@ -1021,7 +1022,7 @@ export function convertToInternalTileConfig( // name on `config`, not at the top level (`strippedConfig` carries it). // Stripping the top-level `name` brings the runtime shape back in line // with `DashboardDocument['tiles'][number]`. - const { id, x, y, w, h, containerId, tabId } = externalTile; + const { id, x, y, w, h, containerId, tabId, description } = externalTile; return { id, x, @@ -1030,6 +1031,7 @@ export function convertToInternalTileConfig( h, ...(containerId !== undefined ? { containerId } : {}), ...(tabId !== undefined ? { tabId } : {}), + ...(description ? { description } : {}), config: strippedConfig, }; } diff --git a/packages/api/src/utils/zod.ts b/packages/api/src/utils/zod.ts index c126dfb313..ca469a7e45 100644 --- a/packages/api/src/utils/zod.ts +++ b/packages/api/src/utils/zod.ts @@ -808,6 +808,7 @@ export const externalDashboardTileSchema = z // 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(), }) .superRefine((data, ctx) => { if (data.series && data.config) { diff --git a/packages/app/src/DBDashboardPage.tsx b/packages/app/src/DBDashboardPage.tsx index 40520a3e07..05bf362ad2 100644 --- a/packages/app/src/DBDashboardPage.tsx +++ b/packages/app/src/DBDashboardPage.tsx @@ -104,6 +104,7 @@ import { IconDotsVertical, IconDownload, IconFilterEdit, + IconInfoCircle, IconLayoutSidebarRightCollapse, IconLayoutSidebarRightExpand, IconPencil, @@ -1225,9 +1226,20 @@ const Tile = ({ const title = useMemo( () => chart.config.name ? ( - {chart.config.name} + + {chart.config.name} + {chart.description && ( + + + + )} + ) : undefined, - [chart.config.name], + [chart.config.name, chart.description, chart.id], ); // Render chart content (used in both tile and fullscreen views) diff --git a/packages/app/src/dashboard.ts b/packages/app/src/dashboard.ts index b727c532d9..ebc112afc4 100644 --- a/packages/app/src/dashboard.ts +++ b/packages/app/src/dashboard.ts @@ -36,6 +36,7 @@ export type Tile = { config: SavedChartConfig; containerId?: string; tabId?: string; + description?: string; }; export type Dashboard = { diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts index 1d2ab24e29..d067572102 100644 --- a/packages/common-utils/src/types.ts +++ b/packages/common-utils/src/types.ts @@ -2033,6 +2033,7 @@ export const TileSchema = z.object({ 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(), }); export const TileTemplateSchema = TileSchema.extend({