ITWorx-Pulse-Public/docs/product/WIDGET_CATALOG.md

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.