Specification
Version 0.4 (2026-09-30). Requirements use the Easy Approach to Requirements
Syntax (EARS). Priorities follow MoSCoW: M must, S should, C could,
W won't (this time). Design choices are explained in Design.
Model shim (MOD)
| ID |
Pri |
Requirement |
| MOD-001 |
M |
The model shim shall provide get, set, save_changes, on, off, send and widget_manager with the signatures of @anywidget/types 0.4.0. |
| MOD-002 |
M |
When the widget calls set with a value that differs structurally from the current one, the model shall store it and fire change:<trait>, then change. |
| MOD-003 |
M |
When the widget calls set with a value structurally equal to the current one, the model shall fire no event. |
| MOD-004 |
M |
The model shall not notify the host of widget changes before save_changes. |
| MOD-005 |
M |
When the widget calls save_changes, the model shall pass the changed traits since the last save, with their latest values, to the host, and then clear them. |
| MOD-006 |
M |
When the host updates traits, the model shall fire the change events without queuing the traits for the next save_changes. |
| MOD-007 |
M |
When off is called with an event and a callback, the model shall remove that callback; with an event only, every callback of the event; with no argument, every callback. |
| MOD-008 |
M |
When the widget calls send(content, callbacks, buffers), the model shall pass the content and the buffers to the host handler. |
| MOD-009 |
M |
When the host sends a custom message, the model shall fire msg:custom with the content and the buffers as DataView objects. |
| MOD-010 |
S |
If an event handler throws, then the model shall log the error and still call the other handlers. |
| MOD-011 |
S |
When widget_manager.get_model is called, the model shall reject with an error stating that the host has no widget manager. |
Loader (LOAD)
| ID |
Pri |
Requirement |
| LOAD-001 |
M |
The loader shall accept a module whose default export is a widget object or a function returning one, synchronously or as a promise. |
| LOAD-002 |
M |
If the module exports neither initialize nor render as functions, then the loader shall reject with an error naming the module and the expected exports. |
| LOAD-003 |
M |
The loader shall await initialize once per model before the first render. |
| LOAD-004 |
M |
When a widget is removed, the loader shall abort the render signal, run the render cleanup, then abort the model signal and run the initialize cleanup. |
| LOAD-005 |
M |
The loader shall load built-in widgets from a registry bundled with the plugin (mode A). |
| LOAD-006 |
M |
Where remote loading is enabled, the loader shall load a module from an https: or same-origin URL (mode B). |
| LOAD-007 |
M |
While remote loading is disabled, when a panel requests a URL, the panel shall show an error message and load nothing. |
| LOAD-008 |
M |
If loading or running a module fails, then the panel shall show the error message instead of crashing. |
| LOAD-009 |
S |
The loader shall apply the widget CSS (_css trait, text or URL, or the CSS of a registry entry) inside a shadow root that holds the widget. |
| LOAD-010 |
S |
The loader shall mark the widget container with the Grafana theme (data-theme="light" or "dark"). |
| LOAD-011 |
S |
The loader shall pass signal, host and experimental to initialize and render; host and experimental.invoke shall reject with a descriptive error. |
| LOAD-012 |
C |
Where isolation is turned off, the loader shall render the widget in the panel element without a shadow root. |
Mapping (MAP)
| ID |
Pri |
Requirement |
| MAP-001 |
M |
The mapping shall set a trait from a field of a data frame reduced with a Grafana reducer (default: last non-null value). |
| MAP-002 |
M |
The mapping shall set a trait from all the values of a field, as an array. |
| MAP-003 |
M |
The mapping shall set a trait from a static JSON value. |
| MAP-004 |
M |
The mapping shall set a trait from a dashboard variable, resolved with replaceVariables, parsed as text, number or JSON. |
| MAP-005 |
M |
The mapping shall set a trait from the time range (start, end, or both, in milliseconds). |
| MAP-006 |
M |
If a source cannot be resolved (field absent, empty frame, only null values, unresolved variable, invalid number), then the mapping shall leave the trait unchanged and report a diagnostic. |
| MAP-007 |
M |
When the widget saves a trait bound to a dashboard variable, the panel shall update that variable. |
| MAP-008 |
S |
When the widget saves a trait bound to the panel options, the panel shall store the value in its static traits. |
| MAP-009 |
M |
When the widget saves a trait without a write-back binding, the panel shall ignore it and log one console warning for that trait. |
| MAP-010 |
S |
Where the options ask for it, the panel shall set the width and height traits to the panel size in pixels. |
| MAP-011 |
S |
Where the widget is an anywidget-instruments-industrial graph fed by messages (Sparkline, KPITile, TrendChart, WaveformChart, XYGraph), the panel shall answer its sync_request with the message its contract describes, built from the query results: the number fields of the frames, with the time field as the time of a TrendChart and the x of an XYGraph that has a single number field. |
| MAP-012 |
S |
When the query results change, the panel shall send the widget of MAP-011 a new message built from them. |
| MAP-013 |
S |
Where the static traits and the bindings set no pens (TrendChart), series (XYGraph) or n_traces (WaveformChart), the panel shall derive them from the number fields, named after the fields. |
Panel and editor (PNL)
| ID |
Pri |
Requirement |
| PNL-001 |
M |
When the panel receives new data, it shall update the traits of the running widget without rendering it again. |
| PNL-002 |
M |
When the panel is resized, it shall update the size traits when they are enabled. |
| PNL-003 |
M |
When the panel is removed, it shall run the widget cleanups and remove every subscription. |
| PNL-004 |
M |
When the widget source changes, the panel shall remove the running widget and load the new one. |
| PNL-005 |
M |
The options editor shall let the user choose a built-in widget or enter a URL, edit the trait bindings, and edit the static traits as JSON. |
| PNL-006 |
S |
If the static traits are not a valid JSON object, then the editor shall show the parse error and the panel shall keep the last valid traits. |
| PNL-007 |
C |
Where diagnostics are enabled, the panel shall list the unresolved bindings under the widget. |
Integrations (INT)
| ID |
Pri |
Requirement |
| INT-001 |
M |
The registry shall include the widgets of anywidget-instruments-industrial, named anywidget_instruments_industrial:<Class> and bundled without modification of their code. |
| INT-002 |
S |
The registry shall include the widgets of anywidget-instruments-automotive, named anywidget_instruments_automotive:<Class> and bundled without modification of their code; the demo shall show an automotive cluster built from them. |
| INT-003 |
M |
The repository shall include three demonstration widgets: a counter (write-back), a gauge (scalar value) and a sparkline (series). |
| INT-004 |
M |
The development server shall provision a demo dashboard on the TestData data source with one panel per demonstration widget. |
| INT-005 |
M |
The registry descriptions and the documentation of the automotive widgets shall carry the safety notice: the widgets are not vehicle instruments, and none is meant to be operated while driving. |
| INT-006 |
M |
The registry shall include the widgets of anywidget-instruments-aeronautics, named anywidget_instruments_aeronautics:<Class> and bundled without modification of their code, each carrying the notice that it is not certified avionics and never to be used to fly an aircraft or to navigate. |
Quality and documentation (QA, DOC)
| ID |
Pri |
Requirement |
| QA-001 |
M |
Unit, component and end-to-end tests shall pass locally and in the continuous integration workflow. |
| QA-002 |
M |
Type checking, linting and the Grafana plugin validator shall report no blocking error. |
| DOC-001 |
M |
The documentation shall state the limits of the host: send without a kernel, binary buffers, widgets that assume a Python kernel. |
| DOC-002 |
M |
The documentation shall include an AFM compatibility matrix. |
| DOC-003 |
M |
The documentation build shall produce llms.txt and llms-full.txt. |
| DOC-004 |
W |
Signing and publishing to the Grafana plugin catalog. |
Revision history
| Version |
Date |
Changes |
| 0.1 |
2026-09-28 |
First version. |
| 0.2 |
2026-09-30 |
INT-001, INT-002: the libraries are named anywidget-instruments-industrial and anywidget-instruments-automotive, with the prefixes anywidget_instruments_industrial: and anywidget_instruments_automotive: (the former prefixes are removed); the automotive widgets are bundled instead of previews drawn with industrial widgets. INT-005: safety notice of the automotive widgets. |
| 0.3 |
2026-09-30 |
MAP-011 .. MAP-013: the graphs of anywidget-instruments-industrial are fed from the query results through their messages (answer to sync_request, new message on every data change, pens, series and traces derived from the fields). |
| 0.4 |
2026-09-30 |
INT-006: the widgets of anywidget-instruments-aeronautics, with their safety notice. |