fix(ui): draw every failed read through a read-failure primitive

Around thirty surfaces drew a failed read their own way: a bare
destructive paragraph with no retry, a muted line saying the data was
still being learned, a skeleton that never ended, an error card nested
in a tile, or nothing at all. None of them told an ended session from a
refusal. They now use QueryErrorRow or QueryErrorCard with the query's
error and a retry, inset where a card already frames them, and keep
their card and title where the page would otherwise jump. Hydration and
caffeine now fail the same way.

The recovery page no longer points to Integrations while Oura's first
resilience level is simply on its way.

A guard reads every read hook's isError branch and refuses hand-rolled
markup there, and refuses a framed error row inside a card.
This commit is contained in:
Marc-André Bombeck committed 2026-10-20 10:10:49 +02:00
1 parent a1b56f0b75
commit 923249dbf6
60 files changed
+579 -175

No files matched your search

@@ -54,12 +54,12 @@ const OURA_SUMMARIES = {
HRV_RMSSD: summary(30),
};
function render(recoveryEmpty: string | null) {
function render(recoveryEmpty: string | null, error: unknown = null) {
analyticsMock.mockReturnValue({
data: { summaries: OURA_SUMMARIES, recoveryEmpty },
data: error ? undefined : { summaries: OURA_SUMMARIES, recoveryEmpty },
isLoading: false,
isEmpty: false,
error: null,
error,
refetch: () => {},
});
const queryClient = new QueryClient({
@@ -81,7 +81,6 @@ beforeEach(() => {
describe("<RecoverySection> empty note", () => {
it.each([
["oura_permission", "heart-health access"],
["oura_no_resilience", "as soon as Oura provides one"],
["general", "WHOOP or Polar"],
])("renders the server's %s reason with the one action", (reason, text) => {
const html = render(reason);
@@ -90,6 +89,20 @@ describe("<RecoverySection> empty note", () => {
expect(html).toContain('href="/settings/integrations"');
});
it("offers nothing to open while Oura's first level is on its way", () => {
// The connection is fine; there is nothing under Integrations to do.
const html = render("oura_no_resilience");
expect(html).toContain('data-empty-case="oura_no_resilience"');
expect(html).toContain("as soon as Oura provides one");
expect(html).not.toContain('href="/settings/integrations"');
});
it("says a failed read instead of a skeleton that never ends", () => {
const html = render(null, new Error("boom"));
expect(html).toContain('data-slot="query-error-card"');
expect(html).not.toContain('data-slot="recovery-loading"');
});
it("shows no note when the server says the page has data", () => {
const html = render(null);
expect(html).not.toContain("data-empty-case");
@@ -15,6 +15,7 @@ import { cn } from "@/lib/utils";
import type { InboundDocumentDto } from "@/lib/validations/inbound-documents";
import { DOCUMENT_KIND_ICONS } from "@/components/documents/document-kind-meta";
import { QueryErrorRow } from "@/components/ui/query-error-row";
/**
* v1.29.x (S7) — the "Choose from documents" picker for attaching stored vault
@@ -181,9 +182,13 @@ export function AttachmentPicker({
))}
</div>
) : list.isError ? (
<p role="alert" className="text-destructive text-sm">
{t("documents.list.loadError")}
</p>
<QueryErrorRow
inset
error={list.error}
slot="coach-attachment-picker-error"
message={t("documents.list.loadError")}
onRetry={() => void list.refetch()}
/>
) : documents.length === 0 ? (
<p className="text-muted-foreground py-6 text-center text-sm">
{t("insights.coach.attach.pickerEmpty")}
@@ -24,6 +24,7 @@ import {
invalidateKeys,
queryKeys,
} from "@/lib/query-keys";
import { QueryErrorRow } from "@/components/ui/query-error-row";
/**
* The quick model choice in the Coach's settings overlay: which provider
@@ -195,21 +196,15 @@ export function CoachModelPicker() {
if (chainQuery.isError || providerQuery.isError) {
return (
<div className="flex flex-col items-start gap-2 text-sm">
<p role="alert" className="text-destructive">
{t("common.loadFailed")}
</p>
<Button
variant="outline"
size="sm"
onClick={() => {
void chainQuery.refetch();
void providerQuery.refetch();
}}
>
{t("common.retry")}
</Button>
</div>
<QueryErrorRow
inset
error={chainQuery.error ?? providerQuery.error}
slot="coach-model-picker-error"
onRetry={() => {
void chainQuery.refetch();
void providerQuery.refetch();
}}
/>
);
}
@@ -7,7 +7,6 @@ import {
MoreHorizontal,
Paperclip,
Pencil,
RotateCw,
Trash2,
} from "lucide-react";
import { toast } from "sonner";
@@ -30,6 +29,7 @@ import {
useCoachConversationHistory,
useDeleteCoachConversationWithUndo,
} from "./use-coach";
import { QueryErrorRow } from "@/components/ui/query-error-row";
/**
* The Coach's conversation list: the full history grouped by recency
@@ -88,6 +88,7 @@ export function HistoryRail({
conversations,
isLoading,
isError,
error,
refetch,
hasNextPage,
isFetchingNextPage,
@@ -160,16 +161,13 @@ export function HistoryRail({
</p>
) : isError && visible.length === 0 ? (
// A load failure must not read as "no conversations yet".
<div
data-slot="coach-history-error"
className="text-muted-foreground flex flex-col items-start gap-2 px-2 py-3 text-sm"
>
<p>{t("common.loadFailed")}</p>
<Button variant="outline" size="sm" onClick={() => refetch()}>
<RotateCw className="size-3.5" aria-hidden="true" />
{t("common.retry")}
</Button>
</div>
<QueryErrorRow
inset
error={error}
slot="coach-history-error"
onRetry={() => void refetch()}
className="px-2 py-3"
/>
) : groups.length === 0 ? (
<p
data-slot="coach-history-empty"
@@ -130,11 +130,12 @@ export function CoachReadStrip({
<CardContent className={STRIP_BODY}>
{isError ? (
<QueryErrorRow
inset
error={error}
slot="coach-read-strip-error"
message={t("insights.coach.readStrip.loadError")}
onRetry={() => void refetch()}
className="flex-row items-center justify-between rounded-none border-0 bg-transparent p-0"
className="flex-row items-center justify-between"
/>
) : (
<Skeleton className="h-5.5 w-3/4" />
@@ -3,16 +3,9 @@
import { useState, type ComponentType } from "react";
import dynamic from "next/dynamic";
import Link from "next/link";
import {
Activity,
Flame,
Gauge,
HeartPulse,
Moon,
RefreshCw,
} from "lucide-react";
import { Activity, Flame, Gauge, HeartPulse, Moon } from "lucide-react";
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import { QueryErrorRow } from "@/components/ui/query-error-row";
import { Skeleton } from "@/components/ui/skeleton";
import { useTranslations } from "@/lib/i18n/context";
import { SectionHeading } from "@/components/ui/section-heading";
@@ -65,6 +58,8 @@ interface ScoreStripProps {
* Vitals slot).
*/
isError?: boolean;
/** The batch query's error, which decides what the error row offers. */
error?: unknown;
/** Refetch the one shared batch query. Recovers both strips at once. */
refetch?: () => void;
/**
@@ -273,6 +268,7 @@ export function WellnessScores({
read,
isLoading,
isError = false,
error = null,
refetch,
extraTile,
hideStrain = false,
@@ -351,24 +347,13 @@ export function WellnessScores({
title={t("insights.derived.scores.sectionTitle")}
subtitle={t("insights.derived.scores.sectionSubtitle")}
/>
<div
data-slot="wellness-scores-error"
role="alert"
className="bg-card border-border text-muted-foreground flex flex-col items-start gap-3 rounded-xl border p-4 text-sm sm:flex-row sm:items-center sm:justify-between"
>
<span>{t("insights.derived.scores.loadError")}</span>
<Button
type="button"
size="sm"
variant="outline"
onClick={() => refetch?.()}
data-slot="wellness-scores-retry"
className="gap-1.5"
>
<RefreshCw className="h-3.5 w-3.5" aria-hidden="true" />
<span>{t("common.retry")}</span>
</Button>
</div>
<QueryErrorRow
error={error}
slot="wellness-scores-error"
retrySlot="wellness-scores-retry"
message={t("insights.derived.scores.loadError")}
onRetry={() => refetch?.()}
/>
</section>
);
}
@@ -23,7 +23,7 @@ import { userDayKey, shiftDateKey, DEFAULT_TIMEZONE } from "@/lib/tz/format";
import { TileHeader } from "@/components/insights/tile-header";
import { DayLink } from "@/components/day/day-link";
import { Button } from "@/components/ui/button";
import { QueryErrorCard } from "@/components/ui/query-error-card";
import { QueryErrorRow } from "@/components/ui/query-error-row";
import { Skeleton } from "@/components/ui/skeleton";
import { axisUnitSuffix } from "@/lib/charts/axis-unit";
import {
@@ -77,7 +77,7 @@ const AXIS_TICKS = [0, 360, 720, 1080, 1440];
* coarser hourly grain instead of an empty chart — `resolution` on the DTO
* tells the caption which, and the tension read is always absent on an
* hourly day (it needs per-sample resolution to stay honest). A failed fetch
* renders `<QueryErrorCard>` with a retry action instead of falling through
* renders `<QueryErrorRow>` with a retry action instead of falling through
* to the empty-day copy.
*
* `initialDateKey` pins the first day shown, for callers that already know
@@ -254,10 +254,11 @@ export function IntradayPulseChart({
{isLoading ? (
<Skeleton className="h-[180px] w-full rounded-lg" />
) : isError ? (
<QueryErrorCard
<QueryErrorRow
inset
error={error}
onRetry={() => refetch()}
className="border-0 bg-transparent shadow-none"
slot="intraday-pulse-error"
onRetry={() => void refetch()}
/>
) : (data?.series?.length ?? 0) < MIN_BUCKETS_FOR_COURSE ? (
// A lone reading or two on a 24-hour axis drew a dot in an empty
@@ -81,6 +81,7 @@ export function MoodWhatStandsOut({
) : null}
{isError ? (
<QueryErrorRow
inset
error={error}
slot="mood-discovery-error"
message={t("insights.pattern.loadError")}
@@ -41,14 +41,24 @@ export function CaffeineCard() {
staleTime: 60_000,
});
// The card keeps its frame and title on a failed read, like the hydration
// card beside it.
if (isError && !data) {
return (
<QueryErrorRow
error={error}
slot="nutrients-caffeine-error"
message={t("nutrients.caffeine.loadError")}
onRetry={() => void refetch()}
/>
<Card data-slot="nutrients-caffeine-card">
<CardHeader>
<TileHeader icon={Coffee} title={t("nutrients.names.caffeine")} />
</CardHeader>
<CardContent>
<QueryErrorRow
inset
error={error}
slot="nutrients-caffeine-error"
message={t("nutrients.caffeine.loadError")}
onRetry={() => void refetch()}
/>
</CardContent>
</Card>
);
}
@@ -4,7 +4,7 @@ import { useQuery } from "@tanstack/react-query";
import { GlassWater } from "lucide-react";
import { Card, CardContent, CardHeader } from "@/components/ui/card";
import { QueryErrorCard } from "@/components/ui/query-error-card";
import { QueryErrorRow } from "@/components/ui/query-error-row";
import { Skeleton } from "@/components/ui/skeleton";
import { TileHeader } from "@/components/insights/tile-header";
import { NutrientDailyBarChartDynamic } from "@/components/charts/nutrient-daily-bar-chart-dynamic";
@@ -38,8 +38,25 @@ export function HydrationCard() {
),
});
if (isError) {
return <QueryErrorCard error={error} onRetry={refetch} />;
// The card keeps its frame and title on a failed read, like the caffeine
// card beside it, so the page does not change shape under the reader.
if (isError && !data) {
return (
<Card data-slot="nutrients-hydration-card">
<CardHeader>
<TileHeader icon={GlassWater} title={t("nutrients.names.water")} />
</CardHeader>
<CardContent>
<QueryErrorRow
inset
error={error}
slot="nutrients-hydration-error"
message={t("nutrients.hydration.loadError")}
onRetry={() => void refetch()}
/>
</CardContent>
</Card>
);
}
const todayTotal = data?.days.at(-1)?.amount ?? 0;
@@ -18,6 +18,7 @@ import { AskCoachIconButton } from "@/components/insights/ask-coach-action";
import { ProseBlocks } from "@/components/insights/prose-blocks";
import { apiGet } from "@/lib/api/api-fetch";
import { InsightSectionCard } from "./insight-section-card";
import { QueryErrorRow } from "@/components/ui/query-error-row";
/**
* v1.11.0 — period-narrative card (Pillar P1).
@@ -121,13 +122,33 @@ export function PeriodNarrativeCard({
);
}
// The route never errors the page; on a fetch error or whenever there is no
// real generated narrative yet (empty account, or a first warm still in
// flight) the card un-mounts itself rather than showing an error, a
// "preparing" husk, or the methodology framing. The query stays mounted and
// polls in the background, so the card appears the moment a narrative lands.
// A failed read is said, with a retry: hiding it would look exactly like
// "no narrative yet". Whenever there is no real generated narrative yet
// (empty account, the capability off, or a first warm still in flight) the
// card un-mounts itself rather than showing a "preparing" husk or the
// methodology framing. The query stays mounted and polls in the background,
// so the card appears the moment a narrative lands.
if (query.isError && !query.data) {
return (
<section
data-slot="period-narrative-section"
aria-label={t("insights.narrativeTitle")}
className={cn("space-y-3", className)}
>
<SectionHeading
icon={CalendarRange}
title={t("insights.narrativeTitle")}
/>
<QueryErrorRow
error={query.error}
slot="period-narrative-error"
onRetry={() => void query.refetch()}
/>
</section>
);
}
const narrative = query.data?.narrative ?? null;
if (query.isError || !narrative) {
if (!narrative) {
return null;
}
@@ -21,6 +21,7 @@ import type {
RecoveryEmptyReason,
} from "@/lib/insights/recovery-empty";
import { ChartSkeleton } from "@/components/charts/chart-skeleton";
import { QueryErrorCard } from "@/components/ui/query-error-card";
import { RestModeBanner } from "@/components/insights/rest-mode-banner";
import type { RestModeAnnotation } from "@/lib/analytics/score/types";
import type { ChartOverlayKey } from "@/lib/dashboard-layout";
@@ -79,7 +80,8 @@ const EMPTY_COPY = {
*/
export function RecoverySection() {
const { t } = useTranslations();
const { data, isLoading } = useInsightsAnalytics("SLEEP_DURATION");
const { data, isLoading, error, refetch } =
useInsightsAnalytics("SLEEP_DURATION");
// v1.18.1 — Rest Mode parity. The annotation rides the thick analytics
// payload's `healthScore` block (server-authoritative; iOS mirrors it). We
// read it off the same `["analytics"]` cache the insights mother page
@@ -190,6 +192,17 @@ export function RecoverySection() {
// answer (`recoveryEmpty`), so web and iOS read one decision.
const emptyReason = data?.recoveryEmpty ?? null;
// A failed read is said, never left as a skeleton that loads forever.
if (error && summaries == null) {
return (
<QueryErrorCard
error={error}
title={t("insights.recovery.loadError")}
onRetry={refetch}
/>
);
}
if (isLoading || summaries == null) {
return (
<div className="space-y-3" data-slot="recovery-loading">
@@ -207,11 +220,15 @@ export function RecoverySection() {
title={t("insights.recovery.emptyTitle")}
description={t(EMPTY_COPY[emptyReason])}
action={
<Button size="sm" variant="outline" asChild>
<Link href="/settings/integrations">
{t("insights.recovery.emptyAction")}
</Link>
</Button>
// Waiting for a first resilience level has nothing to open: the
// connection is fine, the level simply has not arrived.
emptyReason === "oura_no_resilience" ? undefined : (
<Button size="sm" variant="outline" asChild>
<Link href="/settings/integrations">
{t("insights.recovery.emptyAction")}
</Link>
</Button>
)
}
/>
);
@@ -120,6 +120,7 @@ export function WorkoutDetailDayContext({
{sleep.isError ? (
// A failed read is not an absent night.
<QueryErrorRow
inset
error={sleep.error}
onRetry={sleep.refetch}
slot="workout-detail-day-sleep-error"
@@ -170,6 +171,7 @@ export function WorkoutDetailDayContext({
</p>
{mood.isError ? (
<QueryErrorRow
inset
error={mood.error}
onRetry={mood.refetch}
slot="workout-detail-day-mood-error"