import { useId, type ReactNode } from "react"; import type { AsyncState } from "../../application/view-models/async-state.ts"; import type { AppFailure } from "../../contracts/errors.ts"; import { useLocale } from "../i18n/index.ts"; import { errorMessage } from "./error-copy.ts"; import { AuthRequiredSurface, ForbiddenSurface, type HeadingLevel, NotFoundSurface, } from "./state-surfaces.tsx"; import { Button } from "./ui/button.ts"; export function LoadingSurface({ label, description, }: Readonly<{ label?: string; description?: string }>) { const { message } = useLocale(); // Visible copy doubles as the name unless a separate label is given. const accessibleLabel = label ?? description ?? message("async.loading"); return (
); } export type EmptySurfaceProps = Readonly<{ title?: string; description?: string; action?: ReactNode; /** 08-05. Below the heading of the card or section that holds it. */ headingLevel?: HeadingLevel | undefined; }>; export function EmptySurface({ title, description, action, headingLevel = 2, }: EmptySurfaceProps) { const { message } = useLocale(); const Heading = `h${headingLevel}` as const; return (
{title ?? message("async.empty")} {description ?

{description}

: null} {action}
); } export type TerminalErrorSurfaceProps = Readonly<{ userMessageKey: string; action: AppFailure["action"]; onAction?: () => void; /** Read before the action, inside the same alert. */ description?: string; /** 08-07. The id a user quotes to support, e.g. `AppFailure.requestId`. */ supportReference?: string; /** 08-05. Below the heading of the card or section that holds it. */ headingLevel?: HeadingLevel | undefined; }>; export function TerminalErrorSurface({ userMessageKey, action, onAction, description, supportReference, headingLevel = 2, }: TerminalErrorSurfaceProps) { const { locale, message } = useLocale(); const messageId = useId(); const Heading = `h${headingLevel}` as const; const actionLabels: Readonly< Record, string> > = Object.freeze({ retry: message("action.retry"), reauth: message("action.reauth"), navigate: message("action.navigateSafe"), "reload-once": message("action.reloadOnce"), "contact-support": message("action.contactSupport"), }); return (
{errorMessage(userMessageKey, locale)} {description ?

{description}

: null} {action !== "none" && onAction && ( )} {supportReference ? (

{message("template.supportReference", { reference: supportReference, })}

) : null}
); } export type AsyncSurfaceProps = Readonly<{ state: AsyncState; children?: ReactNode; /** Shown while the query has not started (e.g. disabled); nothing if omitted. */ idle?: ReactNode; onAction?: () => void; onRetry?: () => void; onResolveConflict?: () => void; /** Only `APPLIED` is offered: "not applied" needs evidence the UI lacks. */ onReconcileUnknownEffect?: (resolution: "APPLIED") => void; /** * D-1. Resends the unknown request with its original intent and key. * 0929/03-03. Drawn only when `state.unknownEffectResendable` is `true` * (the coordinator's `canResendUnknownEffect`): a request without a key * would go out as a second, unprotected one, and a state built by hand * without that answer draws no resend either. */ onResendUnknownEffect?: () => void; /** 08-05. Title level of the empty and failure surfaces it renders. */ headingLevel?: HeadingLevel | undefined; /** * 0929/08-04. Shown with an unknown mutation result: the request id of the * save whose effect is unknown (`useAppForm().supportReference`). A * terminal error shows its own `failure.requestId`. */ supportReference?: string | undefined; }>; export function AsyncSurface({ state, children, idle, onAction, onRetry, onResolveConflict, onReconcileUnknownEffect, onResendUnknownEffect, headingLevel, supportReference, }: AsyncSurfaceProps) { const { message } = useLocale(); if (state.base === "idle") return idle ?? null; if (state.base === "initial-loading") return ; if (state.base === "empty") return ; if (state.base === "terminal-error" && state.failure) { const AccessState = ACCESS_SURFACES[state.failure.kind]; if (AccessState) { // 08-11. Access failures use the same surfaces as the design system's // AccessSurface, so a query and the gallery show one copy. return (
{state.failure.requestId ? (

{message("template.supportReference", { reference: state.failure.requestId, })}

) : null}
); } return ( ); } return (
{state.indicator ? (
{message( state.indicator === "stale-degraded" ? "async.staleDegraded" : state.indicator === "mutation-effect-unknown" ? "async.mutationEffectUnknown" : state.indicator === "mutation-conflict" ? "async.mutationConflict" : state.indicator === "mutation-pending" ? "async.mutationPending" : "async.refreshing", )} {state.indicator === "stale-degraded" && onRetry ? ( ) : null} {state.indicator === "mutation-conflict" && onResolveConflict ? ( ) : null} {state.indicator === "mutation-effect-unknown" && onReconcileUnknownEffect ? ( ) : null} {state.indicator === "mutation-effect-unknown" && onResendUnknownEffect && state.unknownEffectResendable === true ? ( ) : null} {state.indicator === "mutation-effect-unknown" && supportReference ? (

{message("template.supportReference", { reference: supportReference, })}

) : null}
) : null} {children}
); } const ACCESS_SURFACES: Readonly< Partial< Record< AppFailure["kind"], ( props: Readonly<{ onAction?: () => void; headingLevel?: HeadingLevel | undefined; }>, ) => ReactNode > > > = Object.freeze({ AUTH_REQUIRED: ({ onAction, headingLevel }) => ( ), FORBIDDEN: ({ onAction, headingLevel }) => ( ), NOT_FOUND: ({ onAction, headingLevel }) => ( ), });