npm - @wildo-ai/saas-frontend-lib - Versions diffs - 1.1.9 → 1.1.11 - Mend

@wildo-ai/saas-frontend-lib 1.1.9 → 1.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1566) hide show

package/dist/esm/core/errors/user-facing-error-message.frontend.utils.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"user-facing-error-message.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/errors/user-facing-error-message.frontend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n User-facing error message resolution — the ONE place a caught error becomes words a person reads.\n \n ## The policy this implements\n \n The text shown for an error comes from the i18n tree, never from the error object:\n \n - a backend error's `message` IS its `customMessageReference` (`\"validation\"`), which is an i18n\n * KEY, not a sentence — the HTTP client copies it onto the thrown error, so `e.message` renders a\n * key to the person;\n * - `details.message` / `context.message` / `context.originalMessage` are server-authored English\n * meant for developers and logs — untranslatable, and frequently a Zod issue\n * (`Invalid option: expected one of …`);\n * - a plain `Error` thrown in the browser (a WebAuthn `DOMException`, an invariant message) is\n * developer text as well.\n \n None of those may reach a person. What may is, in order:\n \n Translated text always beats untranslated text (decided 2026-09-15). In order:\n \n 1. Localized user guidance — `errors_guidance.{guidanceKey ?? ref}.explanation`, then `.resolution`.\n * 2. The reference label — `errors_messages.{ref}.msg` — unless the reference is only the GENERIC\n * bucket of its error type AND that bucket's wording is {@link GenericErrorWording.SURFACE} AND the\n * surface supplied its own words. See {@link GENERIC_ERROR_WORDING_BY_ERROR_TYPE}.\n * 3. The surface's own words — the label of the screen that failed (\"Passkey sign-in failed. Try\n * again.\"), passed by the caller.\n * 4. The framework's default label — `errors_messages.default.msg`.\n * 5. Raw user guidance — the backend's `userGuidance.explanation` / `.resolution` string. It is the\n * field DESIGNED for display (see `buildErrorWithGuidance`), so it is kept, but it is untranslated:\n * it appears only when no authored label of any kind exists.\n * 6. The default label's KEY PATH. A missing label must LOOK missing so somebody adds it\n * (`.claude/rules/display-text-comes-from-i18n.md`); an empty string would hide the failure entirely,\n * because every error surface renders only a truthy message.\n \n ## Why a generic reference can lose to the surface\n \n A generic bucket (`validation`, `internal`, `authentication`, …) is the reference an error carries\n * when the server named NO specific reason. Its label was written without knowing where it would be\n * shown, so for some buckets it misleads: a passkey button the person typed nothing into would read\n * \"Some information is invalid. Please review it.\" The surface knows what failed; the bucket does\n * not. For other buckets the generic label tells the person something the surface cannot know and\n * can act on — \"Check your connection\", \"Please wait a moment\" — and it wins. That split is a\n * property of the error-type vocabulary, so it lives in one total record over {@link ErrorType}.\n \n Measured 2026-09-15: a passkey sign-in answered `400 validation`, and the sign-in screen rendered\n * the literal word `validation` in its alert, in every locale.\n /\n\nimport {\n ERROR_DEFINITIONS,\n ErrorCustomMessageReference,\n ErrorType,\n type ErrorUserGuidance,\n} from '@wildo-ai/saas-models';\nimport { LabellingTypes } from '@wildo-ai/presets-components-models';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Generic-bucket wording\n// ─────────────────────────────────────────────────────────────────────────────\n\n/\n Whose words a person sees when an error carries only the GENERIC reference of its type.\n \n Only consulted when the caller supplied surface words; with none, the reference label is used\n * whatever the classification, because there is nothing more precise to say.\n /\nexport enum GenericErrorWording {\n /\n The surface's own words win. For buckets whose generic label only says \"it failed\", or points the\n * person at something the surface may not have asked them for (their input, signing in again, a\n * missing item). The surface that failed says it more precisely.\n /\n SURFACE = 'SURFACE',\n /\n The generic reference label wins. For buckets whose label carries a fact the surface cannot know\n * and the person can act on: connectivity, permission, a state conflict, throttling, an unavailable\n * dependency, a plan limit.\n /\n REFERENCE = 'REFERENCE',\n}\n\n/\n The wording decision for every {@link ErrorType}'s generic bucket.\n \n TOTAL over the enum on purpose: a new error type is a compile error here until someone decides what\n * its generic bucket should say to a person, instead of silently inheriting a default.\n /\nexport const GENERIC_ERROR_WORDING_BY_ERROR_TYPE: Readonly<Record<ErrorType, GenericErrorWording>> = {\n [ErrorType.NETWORK]: GenericErrorWording.REFERENCE,\n [ErrorType.AUTHENTICATION]: GenericErrorWording.SURFACE,\n [ErrorType.AUTHORIZATION]: GenericErrorWording.REFERENCE,\n [ErrorType.VALIDATION]: GenericErrorWording.SURFACE,\n [ErrorType.PAYLOAD_TOO_LARGE]: GenericErrorWording.REFERENCE,\n [ErrorType.NOT_FOUND]: GenericErrorWording.SURFACE,\n [ErrorType.CONFLICT]: GenericErrorWording.REFERENCE,\n [ErrorType.RATE_LIMIT]: GenericErrorWording.REFERENCE,\n [ErrorType.INTERNAL]: GenericErrorWording.SURFACE,\n [ErrorType.DATABASE]: GenericErrorWording.SURFACE,\n [ErrorType.EXTERNAL_SERVICE]: GenericErrorWording.REFERENCE,\n [ErrorType.UNKNOWN]: GenericErrorWording.SURFACE,\n [ErrorType.UNCAUGHT_EXCEPTION]: GenericErrorWording.SURFACE,\n [ErrorType.UNHANDLED_REJECTION]: GenericErrorWording.SURFACE,\n [ErrorType.BUSINESS_RULE]: GenericErrorWording.SURFACE,\n [ErrorType.INFRASTRUCTURE]: GenericErrorWording.SURFACE,\n [ErrorType.CONFIGURATION]: GenericErrorWording.SURFACE,\n [ErrorType.FEATURE_NOT_AVAILABLE]: GenericErrorWording.REFERENCE,\n [ErrorType.FEATURE_LIMIT_EXCEEDED]: GenericErrorWording.REFERENCE,\n [ErrorType.INSUFFICIENT_CREDITS]: GenericErrorWording.REFERENCE,\n};\n\n/\n Generic reference → the error types whose default it is. Derived from `ERROR_DEFINITIONS`, so a\n * reference is \"generic\" exactly when some error type falls back to it — no second list to keep.\n /\nconst GENERIC_REFERENCE_OWNERS: ReadonlyMap<string, readonly ErrorType[]> = (() => {\n const owners = new Map<string, ErrorType[]>();\n for (const definition of Object.values(ERROR_DEFINITIONS)) {\n const reference = definition.defaultCustomMessageReference;\n owners.set(reference, [...(owners.get(reference) ?? []), definition.type]);\n }\n return owners;\n})();\n\nconst ERROR_TYPE_VALUES: ReadonlySet<string> = new Set(Object.values(ErrorType));\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Translators\n// ─────────────────────────────────────────────────────────────────────────────\n\n/* The two i18n resolvers error display needs — the matching members of `I18nContextType`. /\nexport interface ErrorMessageTranslators {\n /* Resolves `errors_messages.{ref}.{key}`; returns the key path when the label is missing. /\n tErrorMessage: (errorRef: string, key?: string, params?: Record<string, string \| number>) => string;\n /* Resolves `errors_guidance.{guidanceKey}.{field}`; returns `''` when the label is missing. /\n tErrorGuidance: (guidanceKey: string, field: string, params?: Record<string, string \| number>) => string;\n}\n\n/\n The localized `errors_messages.{ref}.msg` label, or `undefined` when none is authored.\n \n `tErrorMessage` fails OPEN — a missing label comes back as its own key path — so every caller that\n * must not show a key needs this guard. It used to be hand-copied at each such caller.\n /\nexport function resolveErrorReferenceLabel(\n tErrorMessage: ErrorMessageTranslators['tErrorMessage'],\n errorRef: string \| undefined,\n): string \| undefined {\n if (!errorRef) return undefined;\n const resolved = tErrorMessage(errorRef);\n if (!resolved \|\| resolved.endsWith(`.${errorRef}.msg`)) return undefined;\n return resolved;\n}\n\n/\n Words for a DECLARED REFUSAL CODE — the machine code a custom implementation returns in the error's\n * `details.code` (#1048), e.g. `SECRET_SLUG_NOT_DECLARED`.\n \n Tried in order, first answer wins:\n * 1. the code as an `ErrorCustomMessageReference` value — some declared codes ARE vocabulary members,\n * and their words live in `errors_messages`;\n * 2. `errors_refusals.<code>.msg`, which the labelling planner derives from every\n * `errorScenarios[].errorCode` a resource specification declares, with its `when` text as context.\n \n `undefined` when neither is authored, so the caller falls through to the error's generic REFERENCE\n * label. That fallback is itself authored, less specific text — never an invented sentence — and the\n * server's own `details.message` is never shown: it is English prose (RFC 9457 §3.1.4 says consumers\n * SHOULD NOT parse `detail`; the machine-readable member is what a client reads).\n \n spec-cite: RFC 9457 §3.1.4 — https://www.rfc-editor.org/rfc/rfc9457#section-3.1.4\n /\nexport function resolveRefusalCodeLabel(\n translators: { tErrorMessage: ErrorMessageTranslators['tErrorMessage']; t: (key: string) => string },\n code: string \| undefined,\n): string \| undefined {\n if (!code) return undefined;\n const asReference = resolveErrorReferenceLabel(translators.tErrorMessage, code);\n if (asReference) return asReference;\n const key = `${LabellingTypes.ERRORS_REFUSALS}.${code}.msg`;\n const resolved = translators.t(key);\n return resolved && resolved !== key ? resolved : undefined;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Reading an error\n// ─────────────────────────────────────────────────────────────────────────────\n\n/* The only facts about an error that display is allowed to read. Deliberately has no `message`. /\nexport interface DisplayableErrorFacts {\n errorType?: ErrorType;\n customMessageReference?: string;\n userGuidance?: ErrorUserGuidance;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> \| undefined {\n return value !== null && typeof value === 'object' ? (value as Record<string, unknown>) : undefined;\n}\n\nfunction nonEmptyString(value: unknown): string \| undefined {\n return typeof value === 'string' && value.trim().length > 0 ? value : undefined;\n}\n\n/\n Read the displayable facts from whatever a `catch` received.\n \n Three shapes reach a catch in this frontend, and the facts sit at different depths in each:\n * - the HTTP client's rejected axios error, carrying the normalized `wildoError` it attached, plus\n * `customMessageReference` / `errorType` copied flat, plus the raw `response.data.error` envelope;\n * - a `WildoError_Frontend` / `WildoError_Backend` itself (`type`, `customMessageReference`);\n * - anything else — a plain `Error`, a `DOMException`, a string — which has no displayable facts.\n /\nexport function readDisplayableErrorFacts(error: unknown): DisplayableErrorFacts {\n const candidate = asRecord(error);\n if (!candidate) return {};\n\n const attached = asRecord(candidate.wildoError);\n const envelope = asRecord(asRecord(asRecord(candidate.response)?.data)?.error);\n\n // Each candidate is validated BEFORE one is chosen: a `type` that is not an ErrorType (a DOM event's\n // `'click'`) must not shadow a valid `errorType` further down the list.\n const errorType = [attached?.type, candidate.type, candidate.errorType, envelope?.type]\n .find((value): value is ErrorType => typeof value === 'string' && ERROR_TYPE_VALUES.has(value));\n\n // The envelope names its reference `code` first, exactly as `ErrorManagementService.extractErrorDetails`\n // reads it — needed when no `wildoError` was attached (a rejection raised before `handleHttpError`).\n const customMessageReference = nonEmptyString(attached?.customMessageReference)\n ?? nonEmptyString(candidate.customMessageReference)\n ?? nonEmptyString(envelope?.code)\n ?? nonEmptyString(envelope?.customMessageReference);\n\n const userGuidance = (asRecord(attached?.userGuidance) ?? asRecord(candidate.userGuidance) ?? asRecord(envelope?.userGuidance)) as\n \| ErrorUserGuidance\n \| undefined;\n\n return { errorType, customMessageReference, userGuidance };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Resolution\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst GUIDANCE_DISPLAY_FIELDS = ['explanation', 'resolution'] as const;\n\n/* Guidance resolved through `errors_guidance` — translated, so it outranks every other source. /\nfunction resolveLocalizedGuidanceText(facts: DisplayableErrorFacts, translators: ErrorMessageTranslators): string \| undefined {\n const guidance = facts.userGuidance;\n const guidanceKey = guidance?.guidanceKey ?? facts.customMessageReference;\n if (!guidance \|\| !guidanceKey) return undefined;\n for (const field of GUIDANCE_DISPLAY_FIELDS) {\n const localized = translators.tErrorGuidance(guidanceKey, field, guidance.params);\n if (localized) return localized;\n }\n return undefined;\n}\n\n/* The backend's raw guidance string — untranslated, so it yields to every authored label. /\nfunction resolveRawGuidanceText(facts: DisplayableErrorFacts): string \| undefined {\n const guidance = facts.userGuidance;\n if (!guidance) return undefined;\n for (const field of GUIDANCE_DISPLAY_FIELDS) {\n const raw = nonEmptyString(guidance[field]);\n if (raw) return raw;\n }\n return undefined;\n}\n\n/* The error type whose generic bucket `ref` is, preferring the error's own type when it is an owner. /\nfunction genericReferenceOwner(ref: string \| undefined, errorType: ErrorType \| undefined): ErrorType \| undefined {\n if (!ref) return undefined;\n const owners = GENERIC_REFERENCE_OWNERS.get(ref);\n if (!owners \|\| owners.length === 0) return undefined;\n return errorType && owners.includes(errorType) ? errorType : owners[0];\n}\n\nexport interface ResolveUserFacingErrorMessageOptions {\n translators: ErrorMessageTranslators;\n /\n The failing surface's own words, already localized — e.g. `t(UserAuthLabel.PASSKEY_ERROR)`. Omit it\n * when there is no surface to speak for (the global error toast): generic buckets then use their\n * reference label.\n /\n surfaceMessage?: string;\n}\n\n/\n Turn a caught error into the message a person reads. See the file header for the order and why.\n * Never returns the error's `message`, its `details`/`context` text, or a raw reference.\n */\nexport function resolveUserFacingErrorMessage(error: unknown, options: ResolveUserFacingErrorMessageOptions): string {\n const { translators } = options;\n const facts = readDisplayableErrorFacts(error);\n\n const localizedGuidance = resolveLocalizedGuidanceText(facts, translators);\n if (localizedGuidance) return localizedGuidance;\n\n const surfaceWords = nonEmptyString(options.surfaceMessage);\n const referenceLabel = resolveErrorReferenceLabel(translators.tErrorMessage, facts.customMessageReference);\n\n if (referenceLabel) {\n const owner = genericReferenceOwner(facts.customMessageReference, facts.errorType);\n const surfaceSpeaksMorePrecisely = owner !== undefined\n && GENERIC_ERROR_WORDING_BY_ERROR_TYPE[owner] === GenericErrorWording.SURFACE\n && surfaceWords !== undefined;\n if (!surfaceSpeaksMorePrecisely) return referenceLabel;\n }\n\n if (surfaceWords) return surfaceWords;\n\n // Translated beats untranslated: the authored default label outranks the backend's raw guidance, which in\n // turn outranks the default's key path. Never '' and never the error's own text.\n return resolveErrorReferenceLabel(translators.tErrorMessage, ErrorCustomMessageReference.DEFAULT)\n ?? resolveRawGuidanceText(facts)\n ?? translators.tErrorMessage(ErrorCustomMessageReference.DEFAULT);\n}\n"]}
1	+ {"version":3,"file":"user-facing-error-message.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/errors/user-facing-error-message.frontend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n User-facing error message resolution — the ONE place a caught error becomes words a person reads.\n \n ## The policy this implements\n \n The text shown for an error comes from the i18n tree, never from the error object:\n \n - a backend error's `message` IS its `customMessageReference` (`\"validation\"`), which is an i18n\n * KEY, not a sentence — the HTTP client copies it onto the thrown error, so `e.message` renders a\n * key to the person;\n * - `details.message` / `context.message` / `context.originalMessage` are server-authored English\n * meant for developers and logs — untranslatable, and frequently a Zod issue\n * (`Invalid option: expected one of …`);\n * - a plain `Error` thrown in the browser (a WebAuthn `DOMException`, an invariant message) is\n * developer text as well.\n \n None of those may reach a person. What may is, in order:\n \n Translated text always beats untranslated text (decided 2026-09-15). In order:\n \n 1. Localized user guidance — `errors_guidance.{guidanceKey ?? ref}.explanation`, then `.resolution`.\n * 2. The reference label — `errors_messages.{ref}.msg` — unless the reference is only the GENERIC\n * bucket of its error type AND that bucket's wording is {@link GenericErrorWording.SURFACE} AND the\n * surface supplied its own words. See {@link GENERIC_ERROR_WORDING_BY_ERROR_TYPE}.\n * 3. The surface's own words — the label of the screen that failed (\"Passkey sign-in failed. Try\n * again.\"), passed by the caller.\n * 4. The framework's default label — `errors_messages.default.msg`.\n * 5. Raw user guidance — the backend's `userGuidance.explanation` / `.resolution` string. It is the\n * field DESIGNED for display (see `buildErrorWithGuidance`), so it is kept, but it is untranslated:\n * it appears only when no authored label of any kind exists.\n * 6. The default label's KEY PATH. A missing label must LOOK missing so somebody adds it\n * (`.claude/rules/display-text-comes-from-i18n.md`); an empty string would hide the failure entirely,\n * because every error surface renders only a truthy message.\n \n ## Why a generic reference can lose to the surface\n \n A generic bucket (`validation`, `internal`, `authentication`, …) is the reference an error carries\n * when the server named NO specific reason. Its label was written without knowing where it would be\n * shown, so for some buckets it misleads: a passkey button the person typed nothing into would read\n * \"Some information is invalid. Please review it.\" The surface knows what failed; the bucket does\n * not. For other buckets the generic label tells the person something the surface cannot know and\n * can act on — \"Check your connection\", \"Please wait a moment\" — and it wins. That split is a\n * property of the error-type vocabulary, so it lives in one total record over {@link ErrorType}.\n \n Measured 2026-09-15: a passkey sign-in answered `400 validation`, and the sign-in screen rendered\n * the literal word `validation` in its alert, in every locale.\n /\n\nimport {\n ERROR_DEFINITIONS,\n ErrorCustomMessageReference,\n ErrorType,\n type ErrorUserGuidance,\n} from '@wildo-ai/saas-models';\nimport { LabellingTypes, ResourceOperationTextSlot } from '@wildo-ai/presets-components-models';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Generic-bucket wording\n// ─────────────────────────────────────────────────────────────────────────────\n\n/\n Whose words a person sees when an error carries only the GENERIC reference of its type.\n \n Only consulted when the caller supplied surface words; with none, the reference label is used\n * whatever the classification, because there is nothing more precise to say.\n /\nexport enum GenericErrorWording {\n /\n The surface's own words win. For buckets whose generic label only says \"it failed\", or points the\n * person at something the surface may not have asked them for (their input, signing in again, a\n * missing item). The surface that failed says it more precisely.\n /\n SURFACE = 'SURFACE',\n /\n The generic reference label wins. For buckets whose label carries a fact the surface cannot know\n * and the person can act on: connectivity, permission, a state conflict, throttling, an unavailable\n * dependency, a plan limit.\n /\n REFERENCE = 'REFERENCE',\n}\n\n/\n The wording decision for every {@link ErrorType}'s generic bucket.\n \n TOTAL over the enum on purpose: a new error type is a compile error here until someone decides what\n * its generic bucket should say to a person, instead of silently inheriting a default.\n /\nexport const GENERIC_ERROR_WORDING_BY_ERROR_TYPE: Readonly<Record<ErrorType, GenericErrorWording>> = {\n [ErrorType.NETWORK]: GenericErrorWording.REFERENCE,\n [ErrorType.AUTHENTICATION]: GenericErrorWording.SURFACE,\n [ErrorType.AUTHORIZATION]: GenericErrorWording.REFERENCE,\n [ErrorType.VALIDATION]: GenericErrorWording.SURFACE,\n [ErrorType.PAYLOAD_TOO_LARGE]: GenericErrorWording.REFERENCE,\n [ErrorType.NOT_FOUND]: GenericErrorWording.SURFACE,\n [ErrorType.CONFLICT]: GenericErrorWording.REFERENCE,\n [ErrorType.RATE_LIMIT]: GenericErrorWording.REFERENCE,\n [ErrorType.INTERNAL]: GenericErrorWording.SURFACE,\n [ErrorType.DATABASE]: GenericErrorWording.SURFACE,\n [ErrorType.EXTERNAL_SERVICE]: GenericErrorWording.REFERENCE,\n [ErrorType.UNKNOWN]: GenericErrorWording.SURFACE,\n [ErrorType.UNCAUGHT_EXCEPTION]: GenericErrorWording.SURFACE,\n [ErrorType.UNHANDLED_REJECTION]: GenericErrorWording.SURFACE,\n [ErrorType.BUSINESS_RULE]: GenericErrorWording.SURFACE,\n [ErrorType.INFRASTRUCTURE]: GenericErrorWording.SURFACE,\n [ErrorType.CONFIGURATION]: GenericErrorWording.SURFACE,\n [ErrorType.FEATURE_NOT_AVAILABLE]: GenericErrorWording.REFERENCE,\n [ErrorType.FEATURE_LIMIT_EXCEEDED]: GenericErrorWording.REFERENCE,\n [ErrorType.INSUFFICIENT_CREDITS]: GenericErrorWording.REFERENCE,\n};\n\n/\n Generic reference → the error types whose default it is. Derived from `ERROR_DEFINITIONS`, so a\n * reference is \"generic\" exactly when some error type falls back to it — no second list to keep.\n /\nconst GENERIC_REFERENCE_OWNERS: ReadonlyMap<string, readonly ErrorType[]> = (() => {\n const owners = new Map<string, ErrorType[]>();\n for (const definition of Object.values(ERROR_DEFINITIONS)) {\n const reference = definition.defaultCustomMessageReference;\n owners.set(reference, [...(owners.get(reference) ?? []), definition.type]);\n }\n return owners;\n})();\n\nconst ERROR_TYPE_VALUES: ReadonlySet<string> = new Set(Object.values(ErrorType));\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Translators\n// ─────────────────────────────────────────────────────────────────────────────\n\n/* The two i18n resolvers error display needs — the matching members of `I18nContextType`. /\nexport interface ErrorMessageTranslators {\n /* Resolves `errors_messages.{ref}.{key}`; returns the key path when the label is missing. /\n tErrorMessage: (errorRef: string, key?: string, params?: Record<string, string \| number>) => string;\n /* Resolves `errors_guidance.{guidanceKey}.{field}`; returns `''` when the label is missing. /\n tErrorGuidance: (guidanceKey: string, field: string, params?: Record<string, string \| number>) => string;\n}\n\n/\n The localized `errors_messages.{ref}.msg` label, or `undefined` when none is authored.\n \n `tErrorMessage` fails OPEN — a missing label comes back as its own key path — so every caller that\n * must not show a key needs this guard. It used to be hand-copied at each such caller.\n /\nexport function resolveErrorReferenceLabel(\n tErrorMessage: ErrorMessageTranslators['tErrorMessage'],\n errorRef: string \| undefined,\n): string \| undefined {\n if (!errorRef) return undefined;\n const resolved = tErrorMessage(errorRef);\n if (!resolved \|\| resolved.endsWith(`.${errorRef}.msg`)) return undefined;\n return resolved;\n}\n\n/* The `tResourceOperation` member of `I18nContextType`, narrowed to what refusal display needs. /\nexport type ResourceOperationTranslator = (resource: string, operation: string, key: `${ResourceOperationTextSlot}`) => string;\n\n/\n The reason the APPLICATION wrote for why an operation cannot run — `resources.<r>.operations.<op>\n * .unavailableReason`, generated from the operation specification's `unavailableWhen` — or `undefined`\n * when none is authored (or its bundle is still loading).\n \n `tResourceOperation` answers a miss with the key path once the bundle settled and `''` before, so\n * both are a miss here. One reader for every surface that explains an unavailable or refused\n * operation, so the bar's disabled state and a refused row's reason are the same words.\n /\nexport function resolveAuthoredOperationUnavailableReason(\n tResourceOperation: ResourceOperationTranslator,\n resourceType: string,\n operationIdentifier: string,\n): string \| undefined {\n const keyPath = `${LabellingTypes.RESOURCES}.${resourceType}.operations.${operationIdentifier}.${ResourceOperationTextSlot.UNAVAILABLE_REASON}`;\n const resolved = tResourceOperation(resourceType, operationIdentifier, ResourceOperationTextSlot.UNAVAILABLE_REASON);\n return resolved && resolved !== keyPath ? resolved : undefined;\n}\n\n/\n Words for a refusal of a KNOWN operation (#2264).\n \n `SERVICE_RESOURCE_OPERATION_DISABLED` is the reference the server answers when an operation's\n * `enabledCondition` is false for the row it was asked to act on. The reference is generic by\n * construction — one reference for every operation of every resource — while the application has\n * already written WHY that operation cannot run on such a row: its `unavailableReason`, the very words\n * the action bar shows when it disables the same action before the request. A surface that knows which\n * operation was refused therefore says that, and falls back to the reference's own label only when the\n * application wrote no reason. Every other reference is the reference's label, unchanged.\n \n Measured 2026-10-02 in Wonder Todos: an administrator's background \"Change status\" refused the one\n * completed todo, and the failures panel read \"Service item action disabled\" while the bar would have\n * said \"Completed todos cannot change status…\".\n /\nexport function resolveOperationRefusalLabel(args: {\n tErrorMessage: ErrorMessageTranslators['tErrorMessage'];\n tResourceOperation: ResourceOperationTranslator;\n resourceType: string \| undefined;\n operationIdentifier: string \| undefined;\n customMessageReference: string \| undefined;\n}): string \| undefined {\n const { tErrorMessage, tResourceOperation, resourceType, operationIdentifier, customMessageReference } = args;\n if (customMessageReference === ErrorCustomMessageReference.SERVICE_RESOURCE_OPERATION_DISABLED && resourceType && operationIdentifier) {\n const authored = resolveAuthoredOperationUnavailableReason(tResourceOperation, resourceType, operationIdentifier);\n if (authored) return authored;\n }\n return resolveErrorReferenceLabel(tErrorMessage, customMessageReference);\n}\n\n/\n Words for a DECLARED REFUSAL CODE — the machine code a custom implementation returns in the error's\n * `details.code` (#1048), e.g. `SECRET_SLUG_NOT_DECLARED`.\n \n Tried in order, first answer wins:\n * 1. the code as an `ErrorCustomMessageReference` value — some declared codes ARE vocabulary members,\n * and their words live in `errors_messages`;\n * 2. `errors_refusals.<code>.msg`, which the labelling planner derives from every\n * `errorScenarios[].errorCode` a resource specification declares, with its `when` text as context.\n \n `undefined` when neither is authored, so the caller falls through to the error's generic REFERENCE\n * label. That fallback is itself authored, less specific text — never an invented sentence — and the\n * server's own `details.message` is never shown: it is English prose (RFC 9457 §3.1.4 says consumers\n * SHOULD NOT parse `detail`; the machine-readable member is what a client reads).\n \n spec-cite: RFC 9457 §3.1.4 — https://www.rfc-editor.org/rfc/rfc9457#section-3.1.4\n /\nexport function resolveRefusalCodeLabel(\n translators: { tErrorMessage: ErrorMessageTranslators['tErrorMessage']; t: (key: string) => string },\n code: string \| undefined,\n): string \| undefined {\n if (!code) return undefined;\n const asReference = resolveErrorReferenceLabel(translators.tErrorMessage, code);\n if (asReference) return asReference;\n const key = `${LabellingTypes.ERRORS_REFUSALS}.${code}.msg`;\n const resolved = translators.t(key);\n return resolved && resolved !== key ? resolved : undefined;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Reading an error\n// ─────────────────────────────────────────────────────────────────────────────\n\n/* The only facts about an error that display is allowed to read. Deliberately has no `message`. /\nexport interface DisplayableErrorFacts {\n errorType?: ErrorType;\n customMessageReference?: string;\n userGuidance?: ErrorUserGuidance;\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> \| undefined {\n return value !== null && typeof value === 'object' ? (value as Record<string, unknown>) : undefined;\n}\n\nfunction nonEmptyString(value: unknown): string \| undefined {\n return typeof value === 'string' && value.trim().length > 0 ? value : undefined;\n}\n\n/\n Read the displayable facts from whatever a `catch` received.\n \n Three shapes reach a catch in this frontend, and the facts sit at different depths in each:\n * - the HTTP client's rejected axios error, carrying the normalized `wildoError` it attached, plus\n * `customMessageReference` / `errorType` copied flat, plus the raw `response.data.error` envelope;\n * - a `WildoError_Frontend` / `WildoError_Backend` itself (`type`, `customMessageReference`);\n * - anything else — a plain `Error`, a `DOMException`, a string — which has no displayable facts.\n /\nexport function readDisplayableErrorFacts(error: unknown): DisplayableErrorFacts {\n const candidate = asRecord(error);\n if (!candidate) return {};\n\n const attached = asRecord(candidate.wildoError);\n const envelope = asRecord(asRecord(asRecord(candidate.response)?.data)?.error);\n\n // Each candidate is validated BEFORE one is chosen: a `type` that is not an ErrorType (a DOM event's\n // `'click'`) must not shadow a valid `errorType` further down the list.\n const errorType = [attached?.type, candidate.type, candidate.errorType, envelope?.type]\n .find((value): value is ErrorType => typeof value === 'string' && ERROR_TYPE_VALUES.has(value));\n\n // The envelope's reference first and its `code` only in its absence, exactly as `ErrorManagementService.extractErrorDetails`\n // reads them — needed when no `wildoError` was attached (a rejection raised before `handleHttpError`). A refusal's code\n // is not its reference: it has words of its own only where a surface asks `resolveRefusalCodeLabel` (#1643).\n const customMessageReference = nonEmptyString(attached?.customMessageReference)\n ?? nonEmptyString(candidate.customMessageReference)\n ?? nonEmptyString(envelope?.customMessageReference)\n ?? nonEmptyString(envelope?.code);\n\n const userGuidance = (asRecord(attached?.userGuidance) ?? asRecord(candidate.userGuidance) ?? asRecord(envelope?.userGuidance)) as\n \| ErrorUserGuidance\n \| undefined;\n\n return { errorType, customMessageReference, userGuidance };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Resolution\n// ─────────────────────────────────────────────────────────────────────────────\n\nconst GUIDANCE_DISPLAY_FIELDS = ['explanation', 'resolution'] as const;\n\n/* Guidance resolved through `errors_guidance` — translated, so it outranks every other source. /\nfunction resolveLocalizedGuidanceText(facts: DisplayableErrorFacts, translators: ErrorMessageTranslators): string \| undefined {\n const guidance = facts.userGuidance;\n const guidanceKey = guidance?.guidanceKey ?? facts.customMessageReference;\n if (!guidance \|\| !guidanceKey) return undefined;\n for (const field of GUIDANCE_DISPLAY_FIELDS) {\n const localized = translators.tErrorGuidance(guidanceKey, field, guidance.params);\n if (localized) return localized;\n }\n return undefined;\n}\n\n/* The backend's raw guidance string — untranslated, so it yields to every authored label. /\nfunction resolveRawGuidanceText(facts: DisplayableErrorFacts): string \| undefined {\n const guidance = facts.userGuidance;\n if (!guidance) return undefined;\n for (const field of GUIDANCE_DISPLAY_FIELDS) {\n const raw = nonEmptyString(guidance[field]);\n if (raw) return raw;\n }\n return undefined;\n}\n\n/* The error type whose generic bucket `ref` is, preferring the error's own type when it is an owner. /\nfunction genericReferenceOwner(ref: string \| undefined, errorType: ErrorType \| undefined): ErrorType \| undefined {\n if (!ref) return undefined;\n const owners = GENERIC_REFERENCE_OWNERS.get(ref);\n if (!owners \|\| owners.length === 0) return undefined;\n return errorType && owners.includes(errorType) ? errorType : owners[0];\n}\n\nexport interface ResolveUserFacingErrorMessageOptions {\n translators: ErrorMessageTranslators;\n /\n The failing surface's own words, already localized — e.g. `t(UserAuthLabel.PASSKEY_ERROR)`. Omit it\n * when there is no surface to speak for (the global error toast): generic buckets then use their\n * reference label.\n /\n surfaceMessage?: string;\n}\n\n/\n Turn a caught error into the message a person reads. See the file header for the order and why.\n * Never returns the error's `message`, its `details`/`context` text, or a raw reference.\n */\nexport function resolveUserFacingErrorMessage(error: unknown, options: ResolveUserFacingErrorMessageOptions): string {\n const { translators } = options;\n const facts = readDisplayableErrorFacts(error);\n\n const localizedGuidance = resolveLocalizedGuidanceText(facts, translators);\n if (localizedGuidance) return localizedGuidance;\n\n const surfaceWords = nonEmptyString(options.surfaceMessage);\n const referenceLabel = resolveErrorReferenceLabel(translators.tErrorMessage, facts.customMessageReference);\n\n if (referenceLabel) {\n const owner = genericReferenceOwner(facts.customMessageReference, facts.errorType);\n const surfaceSpeaksMorePrecisely = owner !== undefined\n && GENERIC_ERROR_WORDING_BY_ERROR_TYPE[owner] === GenericErrorWording.SURFACE\n && surfaceWords !== undefined;\n if (!surfaceSpeaksMorePrecisely) return referenceLabel;\n }\n\n if (surfaceWords) return surfaceWords;\n\n // Translated beats untranslated: the authored default label outranks the backend's raw guidance, which in\n // turn outranks the default's key path. Never '' and never the error's own text.\n return resolveErrorReferenceLabel(translators.tErrorMessage, ErrorCustomMessageReference.DEFAULT)\n ?? resolveRawGuidanceText(facts)\n ?? translators.tErrorMessage(ErrorCustomMessageReference.DEFAULT);\n}\n"]}

package/dist/esm/core/events/EventBusContext.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"EventBusContext.js","sourceRoot":"","sources":["../../../../../src/core/events/EventBusContext.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAoB,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIlF,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AAEpG,MAAM,MAAM,GAA0B,qBAAqB,CAAC,SAAS,EAAE,CAAC;AACxE,MAAM,QAAQ,GAAiE,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;AACrH,MAAM,CAAC,mBAAmB,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,eAAe,GAAoC,aAAa,CAAmB,gBAAgB,CAAC,CAAC;AAOlH,MAAM,CAAC,MAAM,gBAAgB,GAAoC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE;IACrF,OAAO,CACL,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,GAAG,IAAI,gBAAgB,YACrD,QAAQ,GACgB,CAC5B,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import React, { createContext } from 'react';\nimport isEqual from 'lodash/isEqual.js';\nimport { FrontendEventBus, frontendEventBus } from './event-bus.frontend.service';\nimport { FrontendEvents, FrontendEventPayloads, SubscribeOptions } from './events.frontend.schemas';\nimport { FrontendResourceOperationContext } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\nconst logger: LoggerFrontendService = LoggerFrontendService.getLogger();\nconst logDebug: (message: string, context?: Record<string, unknown>) => void = logger.debugByType('EventBusContext');\nlogger.setDebugTypeLogging('EventBusContext', false);\n\nexport const EventBusContext: React.Context<FrontendEventBus> = createContext<FrontendEventBus>(frontendEventBus);\n\ntype EventBusProviderProps = {\n children: React.ReactNode;\n bus?: FrontendEventBus;\n};\n\nexport const EventBusProvider: React.FC<EventBusProviderProps> = ({ children, bus }) => {\n return (\n <EventBusContext.Provider value={bus ?? frontendEventBus}>\n {children}\n </EventBusContext.Provider>\n );\n};\n\n\n\n\n/\nMulti-component usage examples (custom + resource + direct on/emit)\n==================================================================\n\nRoot provider setup\n-------------------\nimport React from 'react';\nimport { EventBusProvider } from './EventBusContext';\n\nexport function RootApp(): React.JSX.Element {\n return (\n <EventBusProvider>\n <App />\n </EventBusProvider>\n );\n}\n\n\nCustom loading across components (with typed data)\n-------------------------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { FrontendEvents } from './events.frontend.schemas';\n\n// Component A: triggers start/end in response to an action\nexport function Uploader(): React.JSX.Element {\n const { customLoadingEvent, emit } = useEventBus();\n const { isLoading, startLoading, endLoading } = customLoadingEvent<{ requestId: string }>('upload-file');\n\n const handleUpload = async () => {\n const requestId = 'req-' + Date.now();\n startLoading({ requestId });\n try {\n // ... perform async work\n await new Promise(r => setTimeout(r, 800));\n // Optionally notify user\n emit(FrontendEvents.NOTIFY_CUSTOM_SUCCESS, { identifier: 'A_TEMP_REF', data: { message: 'Upload done' } });\n } catch (e) {\n emit(FrontendEvents.NOTIFY_CUSTOM_ERROR, { identifier: 'A_TEMP_REF', data: { message: 'Upload failed' } });\n } finally {\n endLoading({ requestId });\n }\n };\n\n return (\n <button onClick={handleUpload} disabled={isLoading}>\n {isLoading ? 'Uploading…' : 'Upload'}\n </button>\n );\n}\n\n// Component B: reacts to the same identifier, anywhere in the tree\nexport function UploadIndicator(): React.JSX.Element {\n const { customLoadingEvent } = useEventBus();\n const { isLoading } = customLoadingEvent('upload-file');\n return isLoading ? <div>Uploading… please wait</div> : null;\n}\n\n\nResource loading across components\n----------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\n\n// Component C: triggers the resource load\nexport function UserListLoader(): React.JSX.Element {\n const { resourceLoadingEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { isLoading, startLoading, endLoading } = resourceLoadingEvent({ ctx, optionalDiscriminator });\n\n const loadUsers = async () => {\n startLoading();\n try {\n // ... fetch users with ctx\n await new Promise(r => setTimeout(r, 500));\n } finally {\n endLoading();\n }\n };\n\n return (\n <button onClick={loadUsers} disabled={isLoading}>\n {isLoading ? 'Loading users…' : 'Load users'}\n </button>\n );\n}\n\n// Component D: reacts to the same operation context\nexport function UserListSpinner(): React.JSX.Element {\n const { resourceLoadingEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { isLoading } = resourceLoadingEvent({ ctx, optionalDiscriminator });\n return isLoading ? <div>Loading…</div> : null;\n}\n\n\nResource refresh across components\n----------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\n\n// Component E: triggers refresh\nexport function UserListRefresher(): React.JSX.Element {\n const { resourceRefreshEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { refresh } = resourceRefreshEvent({ ctx, optionalDiscriminator });\n return <button onClick={refresh}>Refresh users</button>;\n}\n\n// Component F: observes refresh timestamps\nexport function UserListLastRefreshed(): React.JSX.Element {\n const { resourceRefreshEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { lastRefreshAt } = resourceRefreshEvent({ ctx, optionalDiscriminator });\n return <div>Last refresh: {lastRefreshAt ? ~~new Date~~(lastRefreshAt)~~.toLocaleTimeString()~~ : 'never'}</div>;\n}\n\n\nDirect on/emit usage (typed)\n----------------------------\nimport React from 'react';\nimport { useEventBus, useEventSubscription } from './EventBusContext';\nimport { FrontendEvents } from './events.frontend.schemas';\n\nexport function Notifier(): React.JSX.Element {\n const { emit } = useEventBus();\n const notify = () => emit(FrontendEvents.NOTIFY_CUSTOM_INFO, { identifier: 'A_TEMP_REF', data: { message: 'Hi!' } });\n return <button onClick={notify}>Notify</button>;\n}\n\nexport function NotificationListener(): React.JSX.Element {\n useEventSubscription(\n FrontendEvents.NOTIFY_CUSTOM_INFO,\n (p) => {\n // p is fully typed\n console.log('Info notification:', p.data);\n },\n // Only react to a specific identifier\n (p) => p.identifier === 'A_TEMP_REF'\n );\n return null;\n}\n/\n"]}
1	+ {"version":3,"file":"EventBusContext.js","sourceRoot":"","sources":["../../../../../src/core/events/EventBusContext.tsx"],"names":[],"mappings":";AAAA,OAAc,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAoB,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAIlF,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AAEpG,MAAM,MAAM,GAA0B,qBAAqB,CAAC,SAAS,EAAE,CAAC;AACxE,MAAM,QAAQ,GAAiE,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAC;AACrH,MAAM,CAAC,mBAAmB,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;AAErD,MAAM,CAAC,MAAM,eAAe,GAAoC,aAAa,CAAmB,gBAAgB,CAAC,CAAC;AAOlH,MAAM,CAAC,MAAM,gBAAgB,GAAoC,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,EAAE;IACrF,OAAO,CACL,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,GAAG,IAAI,gBAAgB,YACrD,QAAQ,GACgB,CAC5B,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import React, { createContext } from 'react';\nimport isEqual from 'lodash/isEqual.js';\nimport { FrontendEventBus, frontendEventBus } from './event-bus.frontend.service';\nimport { FrontendEvents, FrontendEventPayloads, SubscribeOptions } from './events.frontend.schemas';\nimport { FrontendResourceOperationContext } from '~wildo-frontend-lib/core/resources/resources.frontend.schemas';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\n\nconst logger: LoggerFrontendService = LoggerFrontendService.getLogger();\nconst logDebug: (message: string, context?: Record<string, unknown>) => void = logger.debugByType('EventBusContext');\nlogger.setDebugTypeLogging('EventBusContext', false);\n\nexport const EventBusContext: React.Context<FrontendEventBus> = createContext<FrontendEventBus>(frontendEventBus);\n\ntype EventBusProviderProps = {\n children: React.ReactNode;\n bus?: FrontendEventBus;\n};\n\nexport const EventBusProvider: React.FC<EventBusProviderProps> = ({ children, bus }) => {\n return (\n <EventBusContext.Provider value={bus ?? frontendEventBus}>\n {children}\n </EventBusContext.Provider>\n );\n};\n\n\n\n\n/\nMulti-component usage examples (custom + resource + direct on/emit)\n==================================================================\n\nRoot provider setup\n-------------------\nimport React from 'react';\nimport { EventBusProvider } from './EventBusContext';\n\nexport function RootApp(): React.JSX.Element {\n return (\n <EventBusProvider>\n <App />\n </EventBusProvider>\n );\n}\n\n\nCustom loading across components (with typed data)\n-------------------------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { FrontendEvents } from './events.frontend.schemas';\n\n// Component A: triggers start/end in response to an action\nexport function Uploader(): React.JSX.Element {\n const { customLoadingEvent, emit } = useEventBus();\n const { isLoading, startLoading, endLoading } = customLoadingEvent<{ requestId: string }>('upload-file');\n\n const handleUpload = async () => {\n const requestId = 'req-' + Date.now();\n startLoading({ requestId });\n try {\n // ... perform async work\n await new Promise(r => setTimeout(r, 800));\n // Optionally notify user\n emit(FrontendEvents.NOTIFY_CUSTOM_SUCCESS, { identifier: 'A_TEMP_REF', data: { message: 'Upload done' } });\n } catch (e) {\n emit(FrontendEvents.NOTIFY_CUSTOM_ERROR, { identifier: 'A_TEMP_REF', data: { message: 'Upload failed' } });\n } finally {\n endLoading({ requestId });\n }\n };\n\n return (\n <button onClick={handleUpload} disabled={isLoading}>\n {isLoading ? 'Uploading…' : 'Upload'}\n </button>\n );\n}\n\n// Component B: reacts to the same identifier, anywhere in the tree\nexport function UploadIndicator(): React.JSX.Element {\n const { customLoadingEvent } = useEventBus();\n const { isLoading } = customLoadingEvent('upload-file');\n return isLoading ? <div>Uploading… please wait</div> : null;\n}\n\n\nResource loading across components\n----------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\n\n// Component C: triggers the resource load\nexport function UserListLoader(): React.JSX.Element {\n const { resourceLoadingEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { isLoading, startLoading, endLoading } = resourceLoadingEvent({ ctx, optionalDiscriminator });\n\n const loadUsers = async () => {\n startLoading();\n try {\n // ... fetch users with ctx\n await new Promise(r => setTimeout(r, 500));\n } finally {\n endLoading();\n }\n };\n\n return (\n <button onClick={loadUsers} disabled={isLoading}>\n {isLoading ? 'Loading users…' : 'Load users'}\n </button>\n );\n}\n\n// Component D: reacts to the same operation context\nexport function UserListSpinner(): React.JSX.Element {\n const { resourceLoadingEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { isLoading } = resourceLoadingEvent({ ctx, optionalDiscriminator });\n return isLoading ? <div>Loading…</div> : null;\n}\n\n\nResource refresh across components\n----------------------------------\nimport React from 'react';\nimport { useEventBus } from './EventBusContext';\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\n\n// Component E: triggers refresh\nexport function UserListRefresher(): React.JSX.Element {\n const { resourceRefreshEvent } = useEventBus();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { refresh } = resourceRefreshEvent({ ctx, optionalDiscriminator });\n return <button onClick={refresh}>Refresh users</button>;\n}\n\n// Component F: observes refresh timestamps. The time goes through `useI18n().formatTime`, which reads it in\n// the reader's zone and locale; `toLocaleTimeString()` would use the browser's instead (#2242).\nexport function UserListLastRefreshed(): React.JSX.Element {\n const { resourceRefreshEvent } = useEventBus();\n const { formatTime } = useI18n();\n const ctx = frontendResourceUtils.createFrontendResourceOperationContextWithPath({ \n resourceType: 'users', \n operationIdentifier: 'list',\n operation: {},\n contextResourceIdentifiers: {}\n });\n const optionalDiscriminator = 'tab:1';\n const { lastRefreshAt } = resourceRefreshEvent({ ctx, optionalDiscriminator });\n return <div>Last refresh: {lastRefreshAt ? formatTime(lastRefreshAt) : 'never'}</div>;\n}\n\n\nDirect on/emit usage (typed)\n----------------------------\nimport React from 'react';\nimport { useEventBus, useEventSubscription } from './EventBusContext';\nimport { FrontendEvents } from './events.frontend.schemas';\n\nexport function Notifier(): React.JSX.Element {\n const { emit } = useEventBus();\n const notify = () => emit(FrontendEvents.NOTIFY_CUSTOM_INFO, { identifier: 'A_TEMP_REF', data: { message: 'Hi!' } });\n return <button onClick={notify}>Notify</button>;\n}\n\nexport function NotificationListener(): React.JSX.Element {\n useEventSubscription(\n FrontendEvents.NOTIFY_CUSTOM_INFO,\n (p) => {\n // p is fully typed\n console.log('Info notification:', p.data);\n },\n // Only react to a specific identifier\n (p) => p.identifier === 'A_TEMP_REF'\n );\n return null;\n}\n/\n"]}

package/dist/esm/core/events/NotificationContext.d.ts CHANGED Viewed

@@ -15,7 +15,7 @@
  */
 import React from 'react';
 import { FrontendResourceOperationContext } from '../../core/resources/resources.frontend.schemas';
-import { UserPreferences, FrontendDisplayHints } from '@wildo-ai/saas-models';
+import { UserPreferences, FrontendDisplayHints, type InAppNotificationDestination } from '@wildo-ai/saas-models';
 import { NotificationType, NotificationSource, NotifyOptions } from './notification-display-policy.frontend.schemas';
 export type { NotificationType, NotificationSource };
 export interface Notification {
@@ -92,6 +92,18 @@ export interface NotificationContextType {
     notificationsPreferences: UserPreferences['notifications'] | null;
     getNotificationsPreferences: () => UserPreferences['notifications'] | null;
 }
+/**
+ * The interpolation values a backend notice carries for its words (`data.i18nParams`), keeping only strings and
+ * numbers. The backend words them already, in the recipient's language, because a notice can name something whose
+ * labels this page has not loaded: an operation approval's ending names the operation by its title (#2813).
+ * `undefined` when the notice carries none.
+ */
+export declare function backendNotificationI18nParams(data: Record<string, unknown> | undefined): Record<string, string | number> | undefined;
+/**
+ * Where a backend notice leads (`data.destination`, #2578), or `undefined` when it names nowhere. Read through the same
+ * schema the websocket ingress validated it with, so a value that is not a path inside this frontend opens nothing.
+ */
+export declare function backendNotificationDestination(data: Record<string, unknown> | undefined): InAppNotificationDestination | undefined;
 /**
  * The milestone label a notification about a milestone should show, or `null` when the
  * notification is NOT about a milestone.

package/dist/esm/core/events/NotificationContext.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"NotificationContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/NotificationContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAuF,MAAM,OAAO,CAAC;AAQ5G,OAAO,EAAE,gCAAgC,EAAE,MAAM,+DAA+D,CAAC;AAEjH,OAAO,~~EAAE~~,eAAe,~~EAAE~~,oBAAoB,~~EAA6D~~,MAAM,uBAAuB,CAAC;~~AAMzI~~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~~CAu2BhG~~"}
1	+ {"version":3,"file":"NotificationContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/events/NotificationContext.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/events/NotificationContext.js CHANGED Viewed

@@ -19,12 +19,12 @@ import { toast } from './toast.js';
 import { useEventBus } from './useEventBus.js';
 import { FrontendEvents, } from './events.frontend.schemas.js';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
-import { userNotificationTargetIsSuppressibleByRecipientPreference } from '@wildo-ai/saas-models';
+import { InAppNotificationDestinationSchema, UserNotificationPreferenceChannel, userNotificationPreferencesAllow, userNotificationTargetIsSuppressibleByRecipientPreference, } from '@wildo-ai/saas-models';
 import { APP_LEVEL_NAVIGATION_SOURCE } from '../../core/navigation/navigation.schemas.js';
 import { FrontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
 import { FrontendComponentType, LabellingTypes } from '@wildo-ai/presets-components-models';
 import { useI18n } from '../../core/i18n/useI18n.js';
-import { resolveErrorReferenceLabel, resolveRefusalCodeLabel } from '../../core/errors/user-facing-error-message.frontend.utils.js';
+import { resolveOperationRefusalLabel, resolveRefusalCodeLabel } from '../../core/errors/user-facing-error-message.frontend.utils.js';
 import { getNotificationDisplayBehavior, } from './notification-display-policy.frontend.schemas.js';
 const notifLogger = LoggerFrontendService.getLogger();
 const logDebug = notifLogger.debugByType('NotificationContext');
@@ -92,6 +92,50 @@ function notificationReducer(state, action) {
 function resolvedLabelOrNull(answer, keyNamespace) {
     return answer === '' || answer.startsWith(`${keyNamespace}.`) ? null : answer;
 }
+/**
+ * The interpolation values a backend notice carries for its words (`data.i18nParams`), keeping only strings and
+ * numbers. The backend words them already, in the recipient's language, because a notice can name something whose
+ * labels this page has not loaded: an operation approval's ending names the operation by its title (#2813).
+ * `undefined` when the notice carries none.
+ */
+export function backendNotificationI18nParams(data) {
+    const params = data?.i18nParams;
+    if (!params || typeof params !== 'object' || Array.isArray(params))
+        return undefined;
+    const kept = Object.entries(params)
+        .filter((entry) => typeof entry[1] === 'string' || typeof entry[1] === 'number');
+    return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+}
+/**
+ * Where a backend notice leads (`data.destination`, #2578), or `undefined` when it names nowhere. Read through the same
+ * schema the websocket ingress validated it with, so a value that is not a path inside this frontend opens nothing.
+ */
+export function backendNotificationDestination(data) {
+    const parsed = InAppNotificationDestinationSchema.safeParse(data?.destination);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Show a toast at the notice's own level: the one mapping from {@link NotificationType} to a Sonner toast, used with and
+ * without an action. Sonner offers `action` on every level, so a warning that leads somewhere stays a warning; it used
+ * to be shown as a success whenever it carried an action (#2578).
+ */
+function toastAtLevel(type, message, options) {
+    switch (type) {
+        case 'success':
+            toast.success(message, options);
+            break;
+        case 'error':
+            toast.error(message, options);
+            break;
+        case 'warning':
+            toast.warning(message, options);
+            break;
+        case 'info':
+        default:
+            toast.info(message, options);
+            break;
+    }
+}
 /**
  * The milestone label a notification about a milestone should show, or `null` when the
  * notification is NOT about a milestone.
@@ -192,22 +236,7 @@ export function NotificationProvider({ children }) {
      * Show ephemeral toast notification using sonner
      */
     const showToast = useCallback((type, message, duration) => {
-        const toastOptions = duration ? { duration } : undefined;
-        switch (type) {
-            case 'success':
-                toast.success(message, toastOptions);
-                break;
-            case 'error':
-                toast.error(message, toastOptions);
-                break;
-            case 'warning':
-                toast.warning(message, toastOptions);
-                break;
-            case 'info':
-            default:
-                toast.info(message, toastOptions);
-                break;
-        }
+        toastAtLevel(type, message, duration ? { duration } : undefined);
         logDebug('Toast displayed', { type, message, duration });
     }, []);
     /**
@@ -367,7 +396,18 @@ export function NotificationProvider({ children }) {
             const refusal = resolveRefusalCodeLabel({ tErrorMessage: tErrorMessageRef.current, t: tRef.current }, typeof payload?.errorRefusalCode === 'string' ? payload.errorRefusalCode : undefined);
             if (refusal)
                 return refusal;
-            const resolvedError = resolveErrorReferenceLabel(tErrorMessageRef.current, carriedErrorRef);
+            // A refusal of a KNOWN operation speaks with that operation's authored `unavailableReason` when the
+            // reference is the generic "operation disabled" one (#2264) — the same words the action bar shows
+            // when it disables that action. Any other reference is its own label, as before.
+            const resolvedError = resolveOperationRefusalLabel({
+                tErrorMessage: tErrorMessageRef.current,
+                tResourceOperation: tResourceOperationRef.current,
+                resourceType: options.resourceContext?.resourceType,
+                operationIdentifier: options.resourceContext?.operationIdentifier !== undefined
+                    ? String(options.resourceContext.operationIdentifier)
+                    : undefined,
+                customMessageReference: carriedErrorRef,
+            });
             if (resolvedError)
                 return resolvedError;
         }
@@ -481,10 +521,15 @@ export function NotificationProvider({ children }) {
         const suppressibleServerMessage = options.serverNotification !== undefined
             && !options.serverNotification.alwaysDeliver
             && userNotificationTargetIsSuppressibleByRecipientPreference(options.serverNotification.target);
-        if (notificationsPreferences?.inApp === false && (source === 'backend' || suppressibleServerMessage)) {
+        // The in-app switch, then the person's choice for this kind of notification (#2318): the same rule the
+        // dispatcher's email gate reads. A backend message names no resource, so only the switch governs it.
+        const kindResourceType = suppressibleServerMessage ? options.resourceContext?.resourceType : undefined;
+        if ((source === 'backend' || suppressibleServerMessage)
+            && !userNotificationPreferencesAllow(notificationsPreferences, kindResourceType, UserNotificationPreferenceChannel.IN_APP)) {
             logDebug('Suppressing personal server notification: recipient switched in-app notifications off', {
                 type,
                 identifier: options.identifier,
+                resourceType: kindResourceType,
             });
             return;
         }
@@ -540,6 +585,27 @@ export function NotificationProvider({ children }) {
                 },
             };
         }
+        else if (options.destination) {
+            /*
+             * A backend notice that names where it leads (#2578). The action's words are the notice's own, at
+             * `notifications_custom.<identifier>.nextStepLabel`; an unauthored label shows its key, and a notice with no
+             * identifier shows the path itself, so the gap looks missing rather than being filled with invented words.
+             *
+             * The path is opened through the runtime's NAVIGATION_REQUEST bridge, which hands it to the router: this
+             * provider sits above the router, and `window.location` would reload the application and ignore its base path.
+             */
+            const destination = options.destination;
+            const label = options.identifier ? tNotificationCustomRef.current(options.identifier, 'nextStepLabel') : destination;
+            resolvedNextStep = {
+                label,
+                onClick: () => {
+                    emit(FrontendEvents.NAVIGATION_REQUEST, {
+                        urlPath: destination,
+                        initiator: { sourceZone: APP_LEVEL_NAVIGATION_SOURCE },
+                    });
+                },
+            };
+        }
         logDebug('Processing notification', {
             type,
             source,
@@ -577,8 +643,8 @@ export function NotificationProvider({ children }) {
         // Branch: Standard display (with optional nextStep action in toast)
         if (displayBehavior.showToast) {
             if (resolvedNextStep) {
-                // Enhanced toast with action button (Sonner supports `action`)
-                toast.success(message, {
+                // Enhanced toast with action button (Sonner supports `action`), at the notice's own level.
+                toastAtLevel(type, message, {
                     duration: displayBehavior.toastDuration,
                     action: {
                         label: resolvedNextStep.label,
@@ -683,6 +749,7 @@ export function NotificationProvider({ children }) {
                 identifier: payload.identifier,
                 message,
                 data,
+                ...(isBackendNotification ? { i18nParams: backendNotificationI18nParams(data), destination: backendNotificationDestination(data) } : {}),
                 overridePolicy,
                 frontendDisplayHints,
             });