first commit

docs/ui/react/react-auth-whitelabel/src/errors/react-auth-whitelabel-error.md

@@ -0,0 +1,68 @@
+# `ReactAuthWhitelabelError`
+
+## Purpose
+
+`ReactAuthWhitelabelError` is the canonical error class for every error thrown
+by `@suaveplan/react-auth-whitelabel`. It extends `SuaveplanError` so the
+error participates in the project-wide error substrate (cause-chain traversal,
+redaction-aware wire format, OTel span-event adapter, i18n message resolver).
+Every instance is stamped with `context.tier === "react-auth-whitelabel"` so
+log sinks and dashboards can group white-label auth failures without
+inspecting `error.constructor.name`, which is unstable across minified
+bundles. Construction always carries a `messageKey` so the i18n resolver can
+localise the user-visible error string at the boundary.
+
+## Features
+
+- Type-narrowed `.code` of `ReactAuthWhitelabelCode`.
+- Auto-injected `context.tier` for log/dashboard grouping.
+- Carries a translation key, not a baked English string.
+- Compatible with `SuaveplanError`'s cause-chain walker, wire serialiser,
+  and OTel span-event adapter.
+
+## Usage: Basic
+
+```ts
+import { ReactAuthWhitelabelError } from "@suaveplan/react-auth-whitelabel/errors";
+import { REACT_AUTH_WL_CODES } from "@suaveplan/react-auth-whitelabel/errors";
+
+throw new ReactAuthWhitelabelError(
+    REACT_AUTH_WL_CODES.PROVIDER_OUTSIDE_TREE,
+    "react_auth_wl.error.provider_outside_tree",
+    { context: { hook: "useAuth" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+try {
+    await login(email, password);
+} catch (cause) {
+    throw new ReactAuthWhitelabelError(
+        REACT_AUTH_WL_CODES.AUTH_NETWORK_FAILED,
+        "react_auth_wl.error.network",
+        { cause, context: { authUrl: config.authUrl } }
+    );
+}
+```
+
+The thrown error retains the original `cause` chain so monitoring sinks can
+correlate transport errors with the user-facing failure.
+
+## API Reference
+
+- `new ReactAuthWhitelabelError(code, messageKey, options?)` — constructs an
+  error. `options.context.tier` is always set to `"react-auth-whitelabel"`,
+  even if the caller passes a different value (the helper merges, then
+  overrides `tier`).
+- `.code` — `ReactAuthWhitelabelCode` literal.
+- `.message` — short English description sourced from `messageKey` (the i18n
+  resolver substitutes a localised translation when available).
+
+## Implementation Notes
+
+The constructor merges caller-supplied `context` with the canonical `tier`
+stamp. Callers must NOT pass a different `tier` — it will silently win at
+merge time, but the contract is that this package's errors are always
+tagged `"react-auth-whitelabel"`.