nordisk/facett

facett UI error codes — guide

How to use the facet-<component>-<n> error-code scheme (facett_core::errcode).

Raise an error in a pane

use facett_core::facet_err;

// In the empty-state / failure branch of your Facet::ui:
let e = facet_err!(map, 2, "no positions to plot");   // code = "facet-map-2"
e.render(ui);                                          // message (red) + pink code (debug)

facet_err!(component, n, "msg", args…):

• component is the slug ident (map, graph3d, …).
• n is the literal integer (append-only per component — see the registry).
• the message is an ordinary format! string.

The code (facet-<component>-<n>) is formed at compile time; the codeberg URL is resolved from errcode::REGISTRY.

Put the code in state_json

Always fold the code into the pane's observable state so tests + consumers key off it:

fn state_json(&self) -> serde_json::Value {
    let mut j = serde_json::json!({ /* … normal state … */ });
    if let Some(e) = &self.error {          // your pane holds the raised FacetError
        j["error"] = e.to_json();           // { code, component, n, message, codeberg_url, severity }
    }
    j
}

Report structural severity

A pane that raised a FacetError should also report it structurally so the Robot-UI HARD GATE reads it:

fn severity(&self) -> facett_core::Severity {
    if self.error.is_some() { facett_core::Severity::Error } else { facett_core::Severity::Info }
}

FacetError::render already attaches a Severity::Error a11y atom carrying the code, so a headless robot reads the code off the AccessKit tree.

Add a NEW error code

1. Add a row to errcode::REGISTRY in facett-core/src/errcode.rs with the next free n for that component, the canonical message, the crate dir + source file.
2. Raise it with facet_err! at the site.
3. The uniqueness guard test fails the build if the n (or code) collides.
4. Re-export the registry to markdown (.nornir/facett-error-codes-registry.md + workspace_nordisk/facett-error-codes-registry.md).

Never renumber or reuse an existing n — the catalog is append-only.

Consumer mount-prefix (Phase 2)

A consumer that mounts a facett component namespaces the code with its mount:

let mounted = e.with_consumer_prefix("korp/cases");   // korp/cases:facet-map-2
mounted.to_json();  // carries BOTH `code` (base) and `mounted_code`

Showcase (facett-demo)

• Errors tab — the pink codes, git-hash stamp, codeberg links, mount-prefix demo, and the error-code MATRIX slide.
• Manual tab — the in-app manual.
• About / Diagnostics popup (the legend toggle) — git hash + codeberg per component.

Use FacetError::render_demo (neutral a11y atom, Severity::Info) — NOT render — in any surface that displays codes as a catalog rather than a live failure, so it does not trip the Robot-UI gate.