Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .changeset/tile-description-tooltip.md
Original file line number Diff line number Diff line change
@@ -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.
6 changes: 6 additions & 0 deletions packages/api/openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
},
Expand Down
5 changes: 5 additions & 0 deletions packages/api/src/routers/external-api/v2/dashboards.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -661,6 +661,7 @@ function convertTileToExternalChart(
config: convertToExternalTileChartConfig(tile.config) ?? defaultTileConfig,
...(containerId !== undefined ? { containerId } : {}),
...(tabId !== undefined ? { tabId } : {}),
...(tile.description ? { description: tile.description } : {}),
};
}

Expand Down Expand Up @@ -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,
Expand All @@ -1036,6 +1037,7 @@ export function convertToInternalTileConfig(
h,
...(containerId !== undefined ? { containerId } : {}),
...(tabId !== undefined ? { tabId } : {}),
...(description ? { description } : {}),
config: strippedConfig,
};
}
Expand Down
1 change: 1 addition & 0 deletions packages/api/src/utils/zod.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(),

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

})
.superRefine((data, ctx) => {
if (data.series && data.config) {
Expand Down
16 changes: 14 additions & 2 deletions packages/app/src/DBDashboardPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ import {
IconDotsVertical,
IconDownload,
IconFilterEdit,
IconInfoCircle,
IconLayoutSidebarRightCollapse,
IconLayoutSidebarRightExpand,
IconPencil,
Expand Down Expand Up @@ -1139,9 +1140,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

<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

<Tooltip label={chart.description} multiline maw={360} withArrow>
Comment on lines +1143 to +1146

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

<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

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

size={14}
aria-label={chart.description}
data-testid={`tile-description-${chart.id}`}
/>
Comment on lines +1146 to +1151

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

</Tooltip>
)}
</Group>
) : undefined,
[chart.config.name],
[chart.config.name, chart.description, chart.id],
);

// Render chart content (used in both tile and fullscreen views)
Expand Down
1 change: 1 addition & 0 deletions packages/app/src/dashboard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ export type Tile = {
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

};

export type Dashboard = {
Expand Down
1 change: 1 addition & 0 deletions packages/common-utils/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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(),

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

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

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

});

export const TileTemplateSchema = TileSchema.extend({
Expand Down
Loading