exlab_wizard.ui.notifications

Canonical notification helpers (Frontend Spec §2.2).

This module is the only module in the codebase that calls NiceGUI’s ui.notify. The pre-commit hook no-direct-ui-notify (see .pre-commit-config.yaml) enforces this rule across the package; an additional unit test scans for stray ui.notify( calls in exlab_wizard/ui/.

Surfaces:

• notify_success() / notify_info() / notify_warning() / notify_error() – toasts (Frontend §2.2.2). 4 s for info / success, 8 s for warning / error, extended to 12 s when an action is attached.

• notify_field_error() / notify_form_error() – inline messages (Frontend §2.2.4). Stored in module-level registries so wizards can pull them per-field at render time.

• show_banner() / clear_banner() – persistent banners (Frontend §2.2.3). The five-banner closed set is enforced via BannerId. Stacking is capped at 2 simultaneous banners; a 3rd collapses to “…and N more issues”.

Functions

banner_overflow_count([container])	How many banners exceed the stacking cap of 2 (Frontend §2.2.3).
clear_banner(banner_id)	Deactivate a banner if it was active.
clear_field_error(field_id)	Clear a previously registered field-level error.
clear_form_errors(form_id)	Clear all form-level errors registered against form_id.
get_field_error(field_id)	Return the registered field-level error for field_id or None.
get_form_error(form_id)	Return the registered form-level error for form_id or None.
list_active_banners([container])	Return active banners, optionally filtered by container.
notify_error(message, *[, action])	Show an error toast (Frontend §2.2.2).
notify_field_error(field_id, message)	Register a field-level inline error (Frontend §2.2.4).
notify_form_error(form_id, message)	Register a form-level inline error (Frontend §2.2.4).
notify_info(message, *[, action])	Show an info toast (Frontend §2.2.2).
notify_success(message, *[, action])	Show a success toast (Frontend §2.2.2).
notify_warning(message, *[, action])	Show a warning toast (Frontend §2.2.2).
reset_for_tests()	Clear all module-level state.
show_banner(banner_id, *, container, ...[, ...])	Activate a banner from the closed §2.2.3 set.

Classes

ActionSpec(label, on_click)	A single action affordance attached to a notification.
BannerId(*values)	Closed-set banner triggers (Frontend §2.2.3).
ContainerId(*values)	Banner placement scopes (Frontend §2.2.3).
Severity(*values)	Banner severity (Frontend §2.2.3).

class exlab_wizard.ui.notifications.ActionSpec(label, on_click)

Bases: object

A single action affordance attached to a notification.

At most one action per toast (Frontend §2.2.2); multi-action requirements escalate to a modal.

Parameters:

• label (str)

• on_click (Callable[[], None])

label: str

on_click: Callable[[], None]

class exlab_wizard.ui.notifications.BannerId(*values)

Bases: StrEnum

Closed-set banner triggers (Frontend §2.2.3).

Adding a new banner is a deliberate spec change: update §2.2.3 and add a value here. Unknown ids are rejected at runtime in show_banner().

LIMS_UNREACHABLE = 'lims_unreachable'

NAS_UNREACHABLE = 'nas_unreachable'

RECONNECTING = 'reconnecting'

SETUP_INCOMPLETE = 'setup_incomplete'

SYNC_BLOCKED_ON_SUCCESS_CARD = 'sync_blocked_on_success_card'

class exlab_wizard.ui.notifications.ContainerId(*values)

Bases: StrEnum

Banner placement scopes (Frontend §2.2.3).

GLOBAL = 'global'

SETTINGS = 'settings'

WIZARD = 'wizard'

class exlab_wizard.ui.notifications.Severity(*values)

Bases: StrEnum

Banner severity (Frontend §2.2.3).

DANGER = 'danger'

INFO = 'info'

SUCCESS = 'success'

WARNING = 'warning'

exlab_wizard.ui.notifications.banner_overflow_count(container=None)

How many banners exceed the stacking cap of 2 (Frontend §2.2.3).

Parameters:

container (ContainerId | None)

Return type:

int

exlab_wizard.ui.notifications.clear_banner(banner_id)

Deactivate a banner if it was active.

Parameters:

banner_id (BannerId)

Return type:

None

exlab_wizard.ui.notifications.clear_field_error(field_id)

Clear a previously registered field-level error.

Parameters:

field_id (str)

Return type:

None

exlab_wizard.ui.notifications.clear_form_errors(form_id)

Clear all form-level errors registered against form_id.

Parameters:

form_id (str)

Return type:

None

exlab_wizard.ui.notifications.get_field_error(field_id)

Return the registered field-level error for field_id or None.

Parameters:

field_id (str)

Return type:

str | None

exlab_wizard.ui.notifications.get_form_error(form_id)

Return the registered form-level error for form_id or None.

Parameters:

form_id (str)

Return type:

str | None

exlab_wizard.ui.notifications.list_active_banners(container=None)

Return active banners, optionally filtered by container.

Banners are returned in registration order; banner-stack rendering rules (max 2 visible, 3rd+ collapses to “…and N more issues”) are applied by the consumer (typically the banner_stack component).

Parameters:

container (ContainerId | None)

Return type:

list[tuple[BannerId, dict[str, object]]]

exlab_wizard.ui.notifications.notify_error(message, *, action=None)

Show an error toast (Frontend §2.2.2).

8 s default duration; 12 s when an action is attached.

Parameters:

• message (str)

• action (ActionSpec | None)

Return type:

None

exlab_wizard.ui.notifications.notify_field_error(field_id, message)

Register a field-level inline error (Frontend §2.2.4).

Parameters:

• field_id (str)

• message (str)

Return type:

None

exlab_wizard.ui.notifications.notify_form_error(form_id, message)

Register a form-level inline error (Frontend §2.2.4).

Parameters:

• form_id (str)

• message (str)

Return type:

None

exlab_wizard.ui.notifications.notify_info(message, *, action=None)

Show an info toast (Frontend §2.2.2).

Parameters:

• message (str)

• action (ActionSpec | None)

Return type:

None

exlab_wizard.ui.notifications.notify_success(message, *, action=None)

Show a success toast (Frontend §2.2.2).

4 s default duration; 12 s when an action is attached.

Parameters:

• message (str)

• action (ActionSpec | None)

Return type:

None

exlab_wizard.ui.notifications.notify_warning(message, *, action=None)

Show a warning toast (Frontend §2.2.2).

8 s default duration; 12 s when an action is attached.

Parameters:

• message (str)

• action (ActionSpec | None)

Return type:

None

exlab_wizard.ui.notifications.reset_for_tests()

Clear all module-level state. Test fixtures only.

Return type:

None

exlab_wizard.ui.notifications.show_banner(banner_id, *, container, severity, message, action=None, dismissible=True)

Activate a banner from the closed §2.2.3 set.

Raises:

ValueError – when banner_id is not a member of BannerId.

Parameters:

• banner_id (BannerId)

• container (ContainerId)

• severity (Severity)

• message (str)

• action (ActionSpec | None)

• dismissible (bool)

Return type:

None