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 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-04 21:33:07 +04:00
parent 2a3df2fcd8
commit cd082e5ed9
6 changed files with 20 additions and 2 deletions

View File

@ -11,6 +11,7 @@ import type { ErrorStateProps } from './types';
export function ErrorState({ export function ErrorState({
kind = 'error', kind = 'error',
title, title,
headingRef,
description, description,
icon, icon,
onRetry, onRetry,
@ -42,6 +43,7 @@ export function ErrorState({
<StateMessage <StateMessage
role={style.role} role={style.role}
title={title} title={title}
headingRef={headingRef}
description={description} description={description}
footnote={ footnote={
digest && ( digest && (

View File

@ -1,4 +1,4 @@
import type { ReactNode } from 'react'; import type { ReactNode, Ref } from 'react';
import type { IconName } from '../../atoms/icon'; import type { IconName } from '../../atoms/icon';
import type { StateTone } from '../../atoms/state-art'; import type { StateTone } from '../../atoms/state-art';
@ -29,6 +29,8 @@ export type ErrorStateProps = {
kind?: ErrorKind; kind?: ErrorKind;
/** The kind's copy from the translations, such as «مشکلی پیش آمد». */ /** The kind's copy from the translations, such as «مشکلی پیش آمد». */
title: ReactNode; title: ReactNode;
/** Page and app fallbacks focus their heading through it (see StateMessage). */
headingRef?: Ref<HTMLHeadingElement>;
description?: ReactNode; description?: ReactNode;
icon?: IconName; icon?: IconName;
/** Next.js `retry` (error.tsx, catchError) or a refetch. Shows the retry button. */ /** Next.js `retry` (error.tsx, catchError) or a refetch. Shows the retry button. */

View File

@ -8,6 +8,7 @@ import { stateMessageVariants } from './variants';
/** The one anatomy of empty and error states: art, title, description, then actions. */ /** The one anatomy of empty and error states: art, title, description, then actions. */
export function StateMessage({ export function StateMessage({
title, title,
headingRef,
description, description,
footnote, footnote,
icon, icon,
@ -46,8 +47,11 @@ export function StateMessage({
className={isInline ? 'min-w-0 flex-1' : 'max-w-90'} className={isInline ? 'min-w-0 flex-1' : 'max-w-90'}
> >
<Typography <Typography
ref={headingRef}
tabIndex={headingRef ? -1 : undefined}
tag={size === 'page' ? 'h2' : 'h3'} tag={size === 'page' ? 'h2' : 'h3'}
variant={isSmall ? 'label' : 'heading-sm'} variant={isSmall ? 'label' : 'heading-sm'}
className="outline-none"
> >
{title} {title}
</Typography> </Typography>

View File

@ -1,4 +1,4 @@
import type { ReactNode } from 'react'; import type { ReactNode, Ref } from 'react';
import type { IconName } from '../../atoms/icon'; import type { IconName } from '../../atoms/icon';
import type { StateTone } from '../../atoms/state-art'; import type { StateTone } from '../../atoms/state-art';
@ -7,6 +7,11 @@ export type StateMessageSize = 'page' | 'section' | 'compact' | 'inline';
export type StateMessageProps = { export type StateMessageProps = {
title: ReactNode; 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<HTMLHeadingElement>;
/** One or two short sentences: why, and what to do. */ /** One or two short sentences: why, and what to do. */
description?: ReactNode; description?: ReactNode;
/** A small line under the description, such as an error's reference code. */ /** A small line under the description, such as an error's reference code. */

View File

@ -39,6 +39,7 @@ export class HttpError extends Error implements HttpErrorShape {
readonly hint?: string; readonly hint?: string;
readonly requestId?: string; readonly requestId?: string;
readonly retryAfter?: number; readonly retryAfter?: number;
readonly details?: Record<string, unknown>;
readonly method: string; readonly method: string;
readonly url: string; readonly url: string;
@ -50,6 +51,7 @@ export class HttpError extends Error implements HttpErrorShape {
this.hint = init.hint; this.hint = init.hint;
this.requestId = init.requestId; this.requestId = init.requestId;
this.retryAfter = init.retryAfter; this.retryAfter = init.retryAfter;
this.details = init.details;
this.method = init.method; this.method = init.method;
this.url = init.url; this.url = init.url;
} }
@ -64,6 +66,7 @@ export class HttpError extends Error implements HttpErrorShape {
hint: this.hint, hint: this.hint,
requestId: this.requestId, requestId: this.requestId,
retryAfter: this.retryAfter, retryAfter: this.retryAfter,
details: this.details,
method: this.method, method: this.method,
url: this.url, url: this.url,
}; };
@ -223,6 +226,7 @@ export async function errorFromResponse(
(RETRY_AFTER_STATUSES.includes(status) (RETRY_AFTER_STATUSES.includes(status)
? parseRetryAfter(response.headers.get(HEADERS.retryAfter)) ? parseRetryAfter(response.headers.get(HEADERS.retryAfter))
: undefined), : undefined),
details: mapped.details,
method: context.method, method: context.method,
url: context.url, url: context.url,
cause: body, cause: body,

View File

@ -35,6 +35,7 @@ export interface HttpErrorShape {
hint?: string; // how the user can fix it hint?: string; // how the user can fix it
requestId?: string; requestId?: string;
retryAfter?: number; // seconds, from Retry-After on 429 and 503 retryAfter?: number; // seconds, from Retry-After on 429 and 503
details?: Record<string, unknown>; // the server's structured extras, e.g. a changed price; set by mapErrorBody
} }
export interface RetryConfig { export interface RetryConfig {