reportDiagnostic

reportDiagnostic(
  code: ToolkitDiagnosticCode,
  message: string,
  error: unknown,
  context?: { component?: string; target?: Element },
): CustomEvent<ToolkitDiagnosticDetail>

Reports an error on the diagnostic channel. The original caught value is required.

Usage

import { reportDiagnostic } from '@studiometa/js-toolkit';

try {
  JSON.parse('{');
} catch (error) {
  reportDiagnostic('carousel.bad-config', 'The config attribute is not valid JSON.', error, {
    component: 'Carousel',
  });
}

Parameters

• code — a namespaced string. Core codes come from DIAGNOSTICS; a consumer uses its own '<namespace>.<name>'.
• message — one sentence, and it should say what to do about it.
• error — required. The original value, passed through untouched.
• context.component — the reporting component's name.
• context.target — the element to dispatch from. Defaults to document.

Return value

• the dispatched event, so a caller can read defaultPrevented.

What happens

1. The event is dispatched — always before any output — with { bubbles: true, composed: true, cancelable: true }.
2. If nothing cancelled it, reportError(detail.error) is called with the original value.

preventDefault() suppresses that call and nothing else.

From a component

$error(code, message, error) is the same call with the component name filled in:

this.$error('carousel.bad-config', 'The config attribute is not valid JSON.', error);

When to report and when to throw

The failure is	Do
something you recovered from	report it
the caller's to handle	throw or reject

Core follows the same rule: decorator and manifest-adapter misuse, shared-runtime incompatibility, service startup rollback, caller-owned teardown, viewTransition() and swap() all throw. A channel is for what was survived.

See also

• warn() — a warning, with no error value
• captureDiagnostics() — reading the channel in a test