# Widget catalog

Every widget implements a common contract:

- identity and type;
- data query;
- transformations;
- visualization settings;
- thresholds/status mapping;
- behavior and links;
- layout per breakpoint;
- loading/empty/error/stale states;
- permission requirements;
- export capability.

## 1. Stat card

Use for one current value.

Features:
- label and value;
- unit/format;
- state;
- sparkline;
- trend against prior period;
- min/max/average tooltip;
- freshness.

Examples: CPU, RAM, uptime, active containers, free capacity.

## 2. Time series

Features:
- one or more bounded series;
- line/area;
- hover crosshair;
- zoom/pan;
- pause/live;
- event annotations;
- min/max/average;
- legend and series toggles;
- downsampling;
- compare period;
- export.

## 3. Gauge

Use only where a meaningful min/max and thresholds exist.

Examples:
- capacity;
- temperature;
- UPS charge;
- memory limit.

Avoid gauges for values with no stable range.

## 4. Ranked list

- top/bottom N;
- current value;
- mini trend;
- click-to-filter;
- deterministic ID/label tie handling;
- tie handling;
- "other" aggregation where appropriate.

Examples: top container CPU, disk latency, service response time.

## 5. Status grid

The status grid renders bounded text/icon states and supports keyboard click-to-filter for the selected entity.

Compact tiles for many entities.

Required:
- status icon/text;
- entity name;
- optional key value;
- age/freshness;
- grouping and filtering;
- accessible list alternative.

## 6. Table

- server-side pagination/filtering where large;
- sort and column selector;
- pinned identifying columns;
- export;
- row drill-down;
- virtualized rendering;
- explicit stale fields.

## 7. Heatmap

Examples:
- CPU by hour/day;
- disk temperature history;
- service latency distribution.

Must provide a textual/table summary.

## 8. Event timeline

- chronological events;
- severity/type filters;
- entity grouping;
- chart annotation synchronization;
- expandable attributes;
- no secret/raw sensitive payloads.

## 9. Storage map

Visual model of:
- parity;
- array disks;
- pools;
- members;
- filesystems;
- capacity;
- temperature;
- SMART state.

It must remain usable without relying on physical slot colors alone.

## 10. Topology

Nodes:
- applications;
- containers;
- services;
- endpoints;
- dependencies;
- reverse proxy;
- database/storage.

Edges may show status, latency or traffic when reliable. Unknown relationships are visually distinct from discovered/confirmed ones.

## 11. Service matrix

For endpoints/services:
- status;
- latency;
- uptime percentage;
- last incident;
- TLS expiry;
- maintenance.

## 12. Alert/incident summary

- active counts by severity/state;
- newest/highest priority;
- acknowledgement state;
- drill-down;
- no hidden critical item due to pagination.

## 13. Text/annotation

Markdown subset with sanitization.

Use for:
- dashboard instructions;
- maintenance note;
- runbook link;
- scope explanation.

No arbitrary script/HTML.

## 14. Query inspector

Advanced and permission-controlled:
- semantic query;
- generated PromQL;
- execution timing;
- returned series/points;
- limits applied;
- copy for troubleshooting.

It is not enabled as an unrestricted public query console.