Module widgets 

Dashboard widget system for umbral-admin.

Plugins register widgets via AdminPlugin::register_widget. Each widget has a key, title, kind, default_span, optional permission, and an async data function. The admin dashboard renders a 12-column grid of the user’s saved layout (defaulting to all permitted widgets).

Registration shape

admin.register_widget(Widget {
    key:          "umbral_total_models",
    title:        "Total Models".to_string(),
    kind:         WidgetKind::Kpi,
    default_span: Span { cols: 3, rows: 1 },
    permission:   None,
    data:         WidgetDataFn::new(|_user| async move {
        WidgetPayload::Kpi(KpiPayload {
            value:     "42".to_string(),
            unit:      None,
            delta:     None,
            sparkline: None,
        })
    }),
});

Endpoint contract

• GET /admin/api/dashboard/catalog — [{key, title, kind, default_span}]
• GET /admin/api/dashboard/layout — user’s saved layout or default
• PUT /admin/api/dashboard/layout — save user’s layout
• GET /admin/api/dashboard/widgets/{key}/data — typed payload JSON

Structs

BarPayload

Bar chart payload (same shape as Line).

CardPayload

Summary card payload. Renders as:

CatalogEntry

Serialized catalog entry returned by GET /admin/api/dashboard/catalog.

ChartPoint

X/Y data point. X is a string for flexible labeling.

DonutPayload

Donut chart payload — categorical breakdown summing to 100%.

DonutSlice

One slice of a donut chart.

FeedItem

One item in an activity feed.

FeedPayload

Activity feed payload.

HeatmapCell

One cell in a HeatmapRow — an x-axis bucket and its magnitude.

HeatmapPayload

Heatmap payload — a 2-D grid of cells colored by magnitude (ApexCharts heatmap). Every row shares the same ordered x-axis. Use for “activity by time” patterns (day-of-week × hour), cohort retention, or per-region load.

HeatmapRow

One row (series) of a HeatmapPayload — a label plus its cells across the shared x-axis.

KpiPayload

KPI card payload.

LinePayload

Line chart payload.

ProgressItem

One row of a ProgressPayload — a labeled horizontal bar.

ProgressPayload

Progress-bar list payload — a ranked set of labeled horizontal bars, each filled relative to the largest value (or an explicit target). The “top N by metric” tile: revenue by product, traffic by source, completion per category. Rendered as pure HTML — no chart library.

RadialPayload

Radial gauge payload — one or more 0–100% tracks rendered as concentric arcs (ApexCharts radialBar). Use for “progress toward a goal” metrics: quota attainment, capacity used, completion rate.

RadialTrack

One arc of a RadialPayload gauge — a labeled 0–100% value.

Series

One data series for Line or Bar charts.

Span

Grid span in the 12-column dashboard grid.

TableColumn

Table widget column descriptor.

TablePayload

Table widget payload.

Widget

A registered dashboard widget.

WidgetDataFn

Wrapper around the async data closure. Build via WidgetDataFn::new (closure ignores per-request params) or WidgetDataFn::with_params (closure reads WidgetParams to honour period / date-range filters from the request URL).

WidgetInstance

One entry in a user’s saved layout JSON.

WidgetParams

Per-request parameters a widget’s data closure can read. Sourced from the query string on GET /admin/api/dashboard/widgets/<key>/data?<params>.

WidgetSection

A named group of widgets on the dashboard. Each section renders as its own heading + (optional) subtitle + widget grid, so a dashboard with 20 widgets reads as themed clusters rather than one mega-grid.

Enums

WidgetKind

The visual kind of a dashboard widget. Drives how the payload is rendered.

WidgetPayload

Union of all widget payloads. The JSON discriminant is the variant name.

Functions

format_thousands

Format a number with thousands separators and (when fractional) two decimal places. Use for values where the full digits matter (currency totals, audit counts) — for compact display use humanize_number.

humanize_number

Humanize a number into a compact display string: