From cd082e5ed988e84c8a760e4c7ac2e3837c54199d Mon Sep 17 00:00:00 2001 From: Amiram_se Date: Sun, 4 Oct 2026 21:33:07 +0400 Subject: [PATCH] feat(libs,island): carry API error details and let fallbacks focus their heading - HttpError keeps the server's structured `details` (set by mapErrorBody), so callers can read a changed price or a frozen unfollow - ErrorState and StateMessage accept a headingRef; page fallbacks move focus to it Co-Authored-By: Claude Opus 5.5 --- packages/island/src/molecules/error-state/ErrorState.tsx | 2 ++ packages/island/src/molecules/error-state/types.ts | 4 +++- .../island/src/molecules/state-message/StateMessage.tsx | 4 ++++ packages/island/src/molecules/state-message/types.ts | 7 ++++++- packages/libs/src/http/http-error.ts | 4 ++++ packages/libs/src/http/types.ts | 1 + 6 files changed, 20 insertions(+), 2 deletions(-) diff --git a/packages/island/src/molecules/error-state/ErrorState.tsx b/packages/island/src/molecules/error-state/ErrorState.tsx index 75c0d5d..8d46bf3 100644 --- a/packages/island/src/molecules/error-state/ErrorState.tsx +++ b/packages/island/src/molecules/error-state/ErrorState.tsx @@ -11,6 +11,7 @@ import type { ErrorStateProps } from './types'; export function ErrorState({ kind = 'error', title, + headingRef, description, icon, onRetry, @@ -42,6 +43,7 @@ export function ErrorState({ ; description?: ReactNode; icon?: IconName; /** Next.js `retry` (error.tsx, catchError) or a refetch. Shows the retry button. */ diff --git a/packages/island/src/molecules/state-message/StateMessage.tsx b/packages/island/src/molecules/state-message/StateMessage.tsx index 588eca9..8ff6a4b 100644 --- a/packages/island/src/molecules/state-message/StateMessage.tsx +++ b/packages/island/src/molecules/state-message/StateMessage.tsx @@ -8,6 +8,7 @@ import { stateMessageVariants } from './variants'; /** The one anatomy of empty and error states: art, title, description, then actions. */ export function StateMessage({ title, + headingRef, description, footnote, icon, @@ -46,8 +47,11 @@ export function StateMessage({ className={isInline ? 'min-w-0 flex-1' : 'max-w-90'} > {title} diff --git a/packages/island/src/molecules/state-message/types.ts b/packages/island/src/molecules/state-message/types.ts index 56a022b..aa64e26 100644 --- a/packages/island/src/molecules/state-message/types.ts +++ b/packages/island/src/molecules/state-message/types.ts @@ -1,4 +1,4 @@ -import type { ReactNode } from 'react'; +import type { ReactNode, Ref } from 'react'; import type { IconName } from '../../atoms/icon'; import type { StateTone } from '../../atoms/state-art'; @@ -7,6 +7,11 @@ export type StateMessageSize = 'page' | 'section' | 'compact' | 'inline'; export type StateMessageProps = { title: ReactNode; + /** + * A page or app fallback moves focus to its heading, so keyboard and screen-reader users land on + * the explanation. With a ref the heading takes `tabIndex={-1}`. + */ + headingRef?: Ref; /** One or two short sentences: why, and what to do. */ description?: ReactNode; /** A small line under the description, such as an error's reference code. */ diff --git a/packages/libs/src/http/http-error.ts b/packages/libs/src/http/http-error.ts index e404b94..42664d8 100644 --- a/packages/libs/src/http/http-error.ts +++ b/packages/libs/src/http/http-error.ts @@ -39,6 +39,7 @@ export class HttpError extends Error implements HttpErrorShape { readonly hint?: string; readonly requestId?: string; readonly retryAfter?: number; + readonly details?: Record; readonly method: string; readonly url: string; @@ -50,6 +51,7 @@ export class HttpError extends Error implements HttpErrorShape { this.hint = init.hint; this.requestId = init.requestId; this.retryAfter = init.retryAfter; + this.details = init.details; this.method = init.method; this.url = init.url; } @@ -64,6 +66,7 @@ export class HttpError extends Error implements HttpErrorShape { hint: this.hint, requestId: this.requestId, retryAfter: this.retryAfter, + details: this.details, method: this.method, url: this.url, }; @@ -223,6 +226,7 @@ export async function errorFromResponse( (RETRY_AFTER_STATUSES.includes(status) ? parseRetryAfter(response.headers.get(HEADERS.retryAfter)) : undefined), + details: mapped.details, method: context.method, url: context.url, cause: body, diff --git a/packages/libs/src/http/types.ts b/packages/libs/src/http/types.ts index 0a0d3d5..87a7fd7 100644 --- a/packages/libs/src/http/types.ts +++ b/packages/libs/src/http/types.ts @@ -35,6 +35,7 @@ export interface HttpErrorShape { hint?: string; // how the user can fix it requestId?: string; retryAfter?: number; // seconds, from Retry-After on 429 and 503 + details?: Record; // the server's structured extras, e.g. a changed price; set by mapErrorBody } export interface RetryConfig {