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 30ff03cf14..4ef3abf69a 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 2273d27370..bbf6405c56 100644
--- a/packages/api/src/routers/external-api/v2/utils/dashboards.ts
+++ b/packages/api/src/routers/external-api/v2/utils/dashboards.ts
@@ -661,6 +661,7 @@ function convertTileToExternalChart(
config: convertToExternalTileChartConfig(tile.config) ?? defaultTileConfig,
...(containerId !== undefined ? { containerId } : {}),
...(tabId !== undefined ? { tabId } : {}),
+ ...(tile.description ? { description: tile.description } : {}),
};
}
@@ -1027,7 +1028,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,
@@ -1036,6 +1037,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 61f78b91ef..fb2fa510b7 100644
--- a/packages/app/src/DBDashboardPage.tsx
+++ b/packages/app/src/DBDashboardPage.tsx
@@ -107,6 +107,7 @@ import {
IconDotsVertical,
IconDownload,
IconFilterEdit,
+ IconInfoCircle,
IconLayoutSidebarRightCollapse,
IconLayoutSidebarRightExpand,
IconPencil,
@@ -1139,9 +1140,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 814f70bb3e..8d827e8ab9 100644
--- a/packages/common-utils/src/types.ts
+++ b/packages/common-utils/src/types.ts
@@ -2143,6 +2143,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({