add-dashboard-visualization

name	add-dashboard-visualization
description	Use when adding a new visualization type (chart, table, stat, gauge, etc.) to the dashboard panel system, or adding options to an existing one. Guides creating the spec schema, the read-only renderer component, registering both, and keeping the viz-gallery dashboard exhaustive.
user-invocable	true

Adding a Dashboard Visualization

Follow these steps to add a new visualization type to the dashboard panel system.

Dashboards are read-only: they are defined as code (Perses YAML/JSON in a source repo) and reconciled into Everr with everr apply. There is no in-app editor or chart-type picker. A visualization is therefore a pure renderer — it takes its parsed spec options plus the query results and draws them. Selecting a visualization for a panel happens in the dashboard file (plugin.kind), not in the UI.

Architecture

Visualizations live in packages/app/src/components/dashboards/visualizations/. Each type gets its own subdirectory with a renderer and a zod spec schema:

visualizations/
├── index.tsx                          # Registry — maps plugin.kind to { schema, component, inset }
├── parse-spec.ts                      # Lenient spec parsing (invalid options → defaults + warnings)
├── table/
│   ├── spec.ts                        # Zod schema for the plugin's options
│   └── table-visualization.tsx        # Renders the visualization
└── <your-new-type>/
    ├── spec.ts
    └── <type>-visualization.tsx

The schema is used twice: everr apply validates dashboard files against it (strict, via data/dashboards/plugin-specs.ts), and at render time the raw spec is parsed leniently — invalid options fall back to their defaults and surface as a warning icon in the panel header.

Key interfaces

The visualization component receives its parsed spec (the output of its schema — defaulted and typed, never the raw plugin config) and the results of running the panel's queries:

// From visualizations/index.tsx
interface VisualizationProps<TSpec = unknown> {
  spec: TSpec;                // parsed output of the visualization's spec schema
  data?: QueryResultRow[][];  // one frame (row[]) per panel query; undefined while loading
  timeRange?: ResolvedTimeRange;                 // { from: Date; to: Date }
  onTimeRangeChange?: (range: ResolvedTimeRange) => void; // e.g. drag-to-zoom
}

data is an array of query frames — one entry per query on the panel, each a list of rows. Loading, error, and empty states are handled by the panel shell and by the renderer's own !data branch.

Steps

1. Create the visualization directory

packages/app/src/components/dashboards/visualizations/<kind>/

Use the lowercase kebab-case of the kind value (e.g., TimeSeriesChart → time-series-chart/).

2. Define the spec schema

File: <kind>/spec.ts — pure zod, no React imports (it is loaded from server code).

import * as z from "zod";

export const <kind>Spec = z.looseObject({
  showLegend: z.boolean().default(false),
  unit: z.string().default(""),
});

export type <Kind>Spec = z.infer<typeof <kind>Spec>;

Two contracts to respect:

• looseObject, never object/strictObject — unknown option keys must flow through verbatim (validation is never stricter than Perses on shape).
• {} must parse — every known field needs .default(...) or .optional(). The lenient render path relies on this to fall back to defaults when an option is invalid.

3. Create the visualization component

File: <kind>/<kind>-visualization.tsx

import type { VisualizationProps } from "../index";
import type { <Kind>Spec } from "./spec";

export function <Kind>Visualization({
  spec,
  data,
}: VisualizationProps<<Kind>Spec>) {
  // Options are already validated and defaulted — read them directly
  // (e.g. spec.showLegend), no typeof narrowing or casts.
  // Render `data` (one frame per panel query); render an empty state when !data
}

• Render the query results passed in data; handle the !data / empty cases
• Available chart library: Recharts (Bar, Line, Area, ComposedChart, ScatterChart, etc.)
• Available chart wrapper: ChartContainer from @everr/ui/components/chart
• Available table: DataTable from @everr/ui/components/data-table

Hover tooltips use the shared CursorTooltip (@/components/cursor-tooltip) — do not hand-roll positioning or use recharts' <Tooltip> (it anchors at the shape's center, not the cursor). CursorTooltip is a portaled card that follows the pointer and flips at viewport edges instead of clipping; you provide the content, it provides the card chrome and positioning. Track hover yourself and render it conditionally:

const [hover, setHover] = useState<{ datum: D; x: number; y: number } | null>(null);
// on each shape: onMouseEnter={(e) => setHover({ datum, x: e.clientX, y: e.clientY })}
//                onMouseLeave={() => setHover(null)}
// on the chart container, keep the position tracking the pointer:
//                onMouseMove={(e) => setHover((h) => (h ? { ...h, x: e.clientX, y: e.clientY } : h))}
{hover && (
  <CursorTooltip x={hover.x} y={hover.y}>
    {/* time-series-style content: muted header, then swatch · label · tabular-nums value */}
  </CursorTooltip>
)}

The TimeSeriesChart, GeoMap, and Treemap visualizations all use it — match their tooltip content structure for visual consistency.

Scrolling and overflow are visualization concerns. PanelShell provides min-h-0 flex-1 on its content area but no overflow. Each visualization must manage its own scroll container. For example, the table visualization wraps itself in a flex column with a scrollable inner div:

<div className="flex h-full flex-col">
  <div className="min-h-0 flex-1 overflow-auto">
    {/* visualization content */}
  </div>
</div>

Never add overscroll-none to these containers: an overflow:auto element is a scroll container even when its content fits, and overscroll-behavior: none then swallows wheel events instead of chaining them — making the dashboard unscrollable while the cursor is over the panel.

For flush-content visualizations that need a top border separating the header from content, place border-t border-border on the outer wrapper — outside the scroll container so it stays fixed:

<div className="flex h-full flex-col border-t border-border">
  <div className="min-h-0 flex-1 overflow-auto">
    {/* content */}
  </div>
</div>

4. Register the visualization

In packages/app/src/components/dashboards/visualizations/index.tsx, import the component and its schema, then add a defineVisualization entry to the registry object — it type-checks that the component's props match the schema's output:

import { <kind>Spec } from "./<kind>/spec";
import { <Kind>Visualization } from "./<kind>/<kind>-visualization";

const registry: Record<string, VisualizationEntry> = {
  // ... existing entries
  <Kind>: defineVisualization({
    schema: <kind>Spec,
    component: <Kind>Visualization,
    inset: "default",               // or "flush-content" for edge-to-edge content like tables
  }),
};

The inset option controls padding inside the panel card:

• "default" — standard padding (use for charts, stats)
• "flush-content" — no horizontal padding or bottom padding (use for tables, maps)

5. Register the schema for apply-time validation

In packages/app/src/data/dashboards/plugin-specs.ts, add the schema under the plugin kind:

export const panelPluginSpecs: Record<string, z.ZodType> = {
  // ... existing entries
  <Kind>: <kind>Spec,
};

Without this, everr apply accepts any spec for the new kind instead of rejecting invalid option values with the file and option path. There is a test asserting every registered schema parses {} (visualizations/parse-spec.test.ts).

6. Document the options

Add the new kind and its option table to packages/docs/content/docs/dashboards/visualizations.mdx, and update the everr-setup-resources skill in crates/everr-core/assets/skills/ so dashboard-authoring agents know the options exist.

7. Add it to the gallery dashboard

The dashboards/viz-gallery/ directory (project demo) is the visual regression sheet, split by visualization type into one dashboard per kind — time-series.yaml, stat.yaml, table.yaml, and geo-map.yaml. Together they must exercise every visualization kind with every spec option — including each enum value — and every meaningful data-shape behavior (multi-query, grouped pivot, no time column, empty/no-data states) at least once. This step applies to ANY spec change, not just new kinds: when you add an option (or enum value) to an existing visualization, add or extend a panel in the matching per-type file that exercises it.

The gallery's panels are driven by the TestData query kind (a deterministic, ClickHouse-free dev data source), not real telemetry — so the sheet renders identical output every time. When you add an option that needs specific data to be visible, drive the new panel with a TestData scenario (random_walk for time series/stats, table for tabular data, csv for exact small frames) rather than a ClickHouseSQL query. See the TestData section in packages/docs/content/docs/dashboards/panels-and-visualizations.mdx for the scenario options.

• One panel per meaningful option combination; put the options it exercises in the panel's display.description (e.g. "curveType: stepAfter · unit: ms").
• Reference each new panel from the layout grid at the bottom of the same per-type file.
• Reconcile and eyeball it: everr apply ./dashboards, then open /dashboards/demo/viz-gallery-time-series (or -stat / -table / -geo-map).

8. Use it in a dashboard

There is no UI picker — a panel selects this visualization by setting plugin.kind in a dashboard file. Add a panel to a Perses dashboard (.yaml/.json) in a source repo:

spec:
  panels:
    myNewPanel:
      kind: Panel
      spec:
        display: { name: Panel Title, description: Optional description }
        plugin:
          kind: <Kind>            # matches the registry key from step 4
          spec: { showLegend: true }   # validated against the spec schema from step 2
        queries:
          - kind: ClickHouseSQL
            spec:
              plugin: { kind: ClickHouseSQL, spec: { query: "SELECT ..." } }

Reference the panel from a layout item in the same dashboard, then reconcile it:

everr apply ./dashboards --dry-run   # preview the diff
everr apply ./dashboards             # write it

The dashboard's project comes from metadata.project (default "default"). Open /dashboards/<project>/<slug> to see it render with live query results.

Reference: Table visualization

The Table visualization is a complete example:

• Spec schema: visualizations/table/spec.ts — stickyHeader boolean, defaulted
• Visualization: visualizations/table/table-visualization.tsx — uses DataTable from @everr/ui, renders the data frames, reads spec.stickyHeader
• Registry: inset: "flush-content" so the table sits edge-to-edge in the panel