Polish Grafana-grid KPI tiles in edit and view modes

[BorisTyshkevich]

Problem

In the grafana-grid@1 Dashboard layout, KPI queries are rendered inside the same generic tile shell used by charts, tables, and logs.

This produces two visual problems:

1. In Dashboard edit mode, KPI rendering does not populate the generic tile footer, but the empty footer remains in the DOM and its top border creates a visible status line.
2. In Dashboard view mode, the generic tile header, border, background, radius, and body padding create a redundant frame around the KPI cards.

The flow layout's explicit KPI bands are already flat card streams. This issue brings Grafana-grid KPI presentation into visual alignment without changing the layout model.

Scope

This issue applies only to KPI tiles rendered by grafana-grid@1.

Do not change:

• ordinary chart, table, logs, text, or image tiles;
• flow-layout KPI bands;
• Workbench KPI preview;
• Dashboard layout schemas or persisted placements;
• query execution or KPI value semantics.

Edit mode

A KPI tile in Dashboard edit mode must retain the outer editing shell because it owns:

• the query title;
• the drag affordance;
• the remove action;
• the resize handle;
• the persisted grid span and height.

Change the KPI edit shell as follows:

• do not render or display .dash-tile-foot;
• remove the footer border and reserved footer height in every KPI state;
• allow the KPI body to extend to the bottom of the tile;
• retain the existing tile border, header, title, drag, remove, and resize affordances;
• retain the current grid placement and fixed authored tile height.

The footer remains unchanged for every non-KPI tile.

View mode

A KPI tile in Dashboard view mode must show only its KPI cards or state card.

Keep an invisible structural wrapper as the CSS-grid item so it continues to own:

• grid-column;
• authored tile height;
• semantic tile order;
• responsive placement;
• an accessible group name.

Do not use display: contents.

For a view-mode KPI tile:

• hide the tile header;
• hide the tile footer;
• remove the outer border;
• remove the outer background;
• remove outer border radius and shadow;
• remove body padding;
• make the wrapper visually transparent;
• keep the KPI cards as the only visible framed surfaces;
• preserve the query title through role="group" and an accessible name;
• do not expose drag, remove, or resize controls.

The visual shell must also remain absent while refreshing.

Loading, error, and unfilled states

A frameless view-mode tile must never become an unexplained blank area.

When a KPI query is loading, blocked by parameters, invalid, or failed:

• render the existing KPI state card as the visible surface;
• give loading and unfilled states role="status";
• give failures role="alert";
• retain the tile/query title in the state card or its accessible name;
• do not temporarily restore the generic outer frame.

A successful refresh replaces the state card with KPI cards without changing the grid item's position.

KPI card layout polish

Equal-width responsive cards

Inside a Grafana-grid KPI tile, arrange KPI cards as an equal-width responsive grid rather than allowing flex items to grow independently.

Requirements:

• cards in the same visual row have equal widths;
• wrapping is deterministic from the available tile width;
• the final row does not stretch a single card across the entire tile unless only one KPI exists;
• cards never overflow horizontally;
• narrow mobile tiles resolve to one card per row.

This affects only KPI cards inside Grafana-grid tiles. Flow KPI bands retain their current stream behavior.

Value and unit

Avoid orphaning a unit onto a separate line, such as:

112310
MiB

The formatted value and unit must behave as one visual value.

Use container-aware typography or an equivalent CSS-only approach:

• scale the KPI value within defined minimum and maximum font sizes;
• keep value and unit together where they fit;
• do not clip, ellipsize, or introduce horizontal scrolling;
• exceptionally long values may use a controlled fallback wrap at the minimum size.

Do not change numeric conversion, unit selection, decimal rules, or persisted field configuration.

Description and delta rhythm

• visually clamp descriptions to two lines;
• retain the complete description in the DOM for assistive technology;
• anchor a present delta row to the bottom of the card;
• keep label, value, description, and delta spacing consistent across cards;
• cards without deltas must not render an empty placeholder or fake value.

Accessibility

• Every KPI card retains its existing accessible metric name.
• A frameless KPI tile is a named group using the query/tile title.
• Hiding the visual header must not remove the title from the accessibility tree.
• Loading and error announcements remain live and correctly classified.
• No meaningful information may depend solely on color or the accent border.

Responsive behavior

Verify the presentation under the Grafana-grid effective column counts:

• 12 columns;
• 6 columns;
• 4 columns;
• 2 columns.

At narrow widths:

• no horizontal Dashboard overflow;
• KPI cards become one per row when necessary;
• value typography remains legible;
• edit controls remain reachable in edit mode;
• view mode remains completely frameless.

Tests

Add unit coverage for:

• KPI edit tile has a header and edit controls but no visible footer;
• KPI view tile has no visible header, footer, border, or outer background;
• the view-mode structural wrapper retains grid placement;
• the hidden query title remains the group's accessible name;
• non-KPI tile footers remain unchanged;
• loading, unfilled, and error state cards remain visible and accessible;
• switching or rerendering cannot leave stale footer or frame classes;
• flow KPI-band markup and styling remain unchanged.

Add real-browser coverage for:

• edit-mode KPI footer line is absent;
• view-mode KPI tiles show only KPI cards;
• equal card widths and predictable wrapping;
• value plus unit does not produce an orphaned unit at representative widths;
• delta rows align consistently;
• 12/6/4/2-column responsive layouts;
• light and dark themes;
• no overflow at a 360px viewport.

Acceptance criteria

• Grafana-grid KPI tiles have no footer or footer separator.
• Edit mode retains the tile header, frame, drag, remove, and resize affordances.
• View mode removes all visible outer tile chrome and leaves only KPI or state cards.
• The invisible wrapper continues to own placement, height, order, and an accessible query-title group name.
• KPI cards use equal-width responsive placement.
• Values and units avoid visually orphaned units.
• Descriptions and deltas have consistent vertical rhythm.
• Loading, unfilled, and error states remain visible and accessible.
• Ordinary tiles and flow KPI bands do not change.
• No Dashboard schema, persistence, execution, or KPI formatting semantics change.
• Unit and real-browser tests pass.

Non-goals

• changing KPI calculations or result interpretation;
• automatic conversion from MiB to GiB;
• locale-aware digit grouping;
• adding new KPI field configuration;
• changing Grafana-grid span or height persistence;
• changing the flow-layout KPI band;
• removing edit-mode tile chrome;
• using display: contents for the grid item;
• redesigning ordinary Dashboard tiles.

[BorisTyshkevich]

Owner decisions pinned at /ship time (pre-implementation):

1. Card polish scope — everywhere. Delta bottom-anchoring, 2-line description clamp, and value+unit typography apply to the shared .kpi-card base (workbench panel + flow bands + grafana-grid tiles), not only grafana-grid. This amends the acceptance bullet "flow KPI-band markup and styling remain unchanged" → flow-band markup and stream layout remain unchanged; the shared card rhythm/typography polish intentionally applies there too. The equal-width responsive grid remains grafana-grid-only.
2. Value+unit fix — presentational span split. kpi-panel.ts renders .kpi-value as number + unit spans (unit pair kept together via CSS); the pure formatter semantics in core/kpi.ts are unchanged.
3. Zero-data ("no rows") state → role="status", not alert — it's an expected unfilled outcome, despite being classified via the errors branch internally.
4. View-mode title a11y — role="group" + aria-label={title} on the tile element, header hidden with display:none (no visually-hidden header text).