Specification
| Field |
Value |
| Project |
anywidget-instruments (core of the family) |
| Author |
Sébastien Celles |
| Document type |
Software requirements specification |
| Notation |
EARS (Easy Approach to Requirements Syntax); priorities MoSCoW: M must, S should, C could |
| Version |
0.1 |
| Date |
2026-09-30 |
1. Scope
anywidget-instruments is the core the widget libraries of the family are built
on: anywidget-instruments-industrial and anywidget-instruments-automotive. It
holds what every instrument family shares, and no widget. The requirements
below were first written for anywidget-instruments-industrial, which held this
code before it was extracted; they keep their identifiers, and the libraries
refer to them.
2. Family (FAM)
| ID |
Pri |
Requirement |
| FAM-001 |
M |
The package shall provide the base view, the base Python class, the base trait contract and its generator, the styles and themes, and the kernel liveness, and no widget. |
| FAM-002 |
M |
A widget library shall depend on this package only, and not on another widget library of the family. |
| FAM-003 |
M |
The package shall ship its TypeScript sources unbuilt: each library bundles them with its own widgets, so that a library's bundle carries its own copy. |
| FAM-004 |
M |
Each library shall register the contracts of its widgets, keyed by _kind; the base view shall read the traits of a widget through the contract registered for its kind, and read them as they come when none is registered. |
| FAM-005 |
M |
The $id of the base schemas shall start with https://anywidgetinstruments.github.io/anywidget-instruments/schema/; a library's schemas shall extend them by that $id. |
| ID |
Pri |
Requirement |
| API-001 |
M |
The package shall provide a common base class from which every widget of the family derives. |
| API-003 |
M |
Every widget shall expose a mode trait accepting the values "control" and "indicator"; a library may restrict it to one of them. |
| API-004 |
M |
While a widget is in indicator mode, the widget shall ignore user pointer and keyboard input that would modify value. |
| API-006 |
M |
When the user changes the value of a widget in control mode, the widget shall send the new value to the kernel. |
| API-007 |
M |
Every widget shall expose label, disabled, visible and tooltip traits. |
| API-009 |
M |
Every widget shall support registration of Python callbacks via an observe-compatible interface and via an on_change(callback) convenience method. |
| API-010 |
S |
Every widget shall accept a size trait (width and height in CSS pixels). |
| API-011 |
M |
While disabled is true, the widget shall render in a greyed style and shall reject user input. |
4. Styles and themes (STYLE)
| ID |
Pri |
Requirement |
| STYLE-001 |
M |
The package shall provide three visual styles: modern, classic (flat, low detail) and system (follows the host theme colors). |
| STYLE-002 |
M |
While the host is in dark mode, widgets using the system style shall use dark-theme colors. |
| STYLE-003 |
M |
The package shall define all widget colors through CSS custom properties (--awi-*), so that users can override them per widget or per page. |
| STYLE-004 |
S |
The package shall provide a global function to set the default style for all widgets created afterwards. |
| STYLE-006 |
M |
If a supplied skin SVG contains scripts, event handler attributes or external references, then the package shall strip them before rendering. |
| STYLE-007 |
S |
Every widget shall accept a theme of auto, light, dark or system (system follows the host or operating system color scheme whatever the style); light and dark shall apply their palette whatever the host theme, and the package shall provide a function switching every open widget. |
5. Robustness and liveness (ROB, HOST)
| ID |
Pri |
Requirement |
| ROB-001 |
M |
If the kernel is disconnected or restarted, then every widget shall display a stale-data indication and shall reject user input until the connection is restored. |
| ROB-002 |
M |
If a Python callback raises an exception, then the package shall log the exception in the notebook output and shall keep the widget operational. |
| ROB-003 |
M |
If a trait is assigned a value of an invalid type, then the package shall raise a TraitError with a message naming the widget and trait. |
| HOST-001 |
M |
The package shall describe the traits common to every widget in a JSON Schema shipped in the package, and shall provide the generator that flattens a library's schemas into its front-end trait types and its host description file (contract.json). |
| HOST-002 |
M |
When the front end reads a trait of a widget that has a schema, the front end shall read it through the schema: a value of the wrong type shall be replaced by the schema default, a number outside the schema bounds shall be clamped to them, and non-finite floats encoded as strings shall be decoded. |
| HOST-003 |
M |
The front end shall enable the stale-data indication only when the host announces heartbeats, with a non-empty _session and a _heartbeat period greater than 0. The class defaults of these two traits shall announce nothing, and the Python package shall announce them for every widget it creates. |
| HOST-007 |
M |
The class default of every synchronized trait of the base class shall equal the default given by the base schema. |
| ID |
Pri |
Requirement |
| GEN-010 |
M |
When a library is imported, it shall not modify global notebook state or register global CSS outside its own widget roots (.awi-root). |
| PERF-003 |
S |
The base view shall coalesce successive updates arriving within one animation frame, and render only the latest. |
| PERF-005 |
S |
While a widget is not visible in the viewport, the base view shall skip rendering and resume on becoming visible. |
| SEC-001 |
M |
The front-end code shall not use eval, new Function or innerHTML with data coming from traits. |
| SEC-002 |
M |
The package shall render label and tooltip strings as text, never as HTML. |
| A11Y-005 |
S |
Where the user agent requests reduced motion, the widgets shall disable animations. |
Revision history
| Version |
Date |
Changes |
| 0.1 |
2026-09-30 |
First version: the base view, contract, themes, liveness and Python base class extracted from anywidget-instruments-industrial (its specification 0.15); FAM-001 .. FAM-005 added. |