@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/components/account-settings-labels.ts

@@ -0,0 +1,190 @@
+import { useMemo } from "react";
+import { useKitLabelOverrides } from "../i18n/kit-labels";
+
+/**
+ * The `accountSettings` namespace of `<UiKitProvider labels>`: one record per section —
+ * `profile`, `password`, `twoFactor`, `passkeys` — each merged key by key, so an app
+ * can translate `accountSettings.twoFactor.scanHint` alone.
+ *
+ * Before 0.12.0 every section took a REQUIRED `labels` prop and had no English of its
+ * own, so each app spelled out 30-odd keys at the call site and still hard-coded some
+ * (kastlan's profile page passed `email: "Email"` in English to a German page). The
+ * prop stays, now partial, and wins over the provider as everywhere else in the kit.
+ *
+ * Its own module, beside the components rather than in them, so `PasskeysSetting`
+ * (its own file) and the older three read one tree without importing each other.
+ */
+
+export interface ProfileSettingLabels {
+  title: string;
+  email: string;
+  role: string;
+  memberSince: string;
+  displayName: string;
+  save: string;
+}
+
+export interface PasswordSettingLabels {
+  title: string;
+  current: string;
+  next: string;
+  confirm: string;
+  submit: string;
+  tooShort: string;
+  mismatch: string;
+}
+
+export interface TwoFactorSettingLabels {
+  status: string;
+  enabledText: string;
+  disabledText: string;
+  enable: string;
+  scanHint: string;
+  codeLabel: string;
+  verify: string;
+  disableSection: string;
+  password: string;
+  disable: string;
+  /**
+   * Alt text for the setup QR code, which shipped as a hardcoded `alt="QR"`.
+   *
+   * OPTIONAL, like the two keys below, and not because it matters less: this interface
+   * is annotated at consumer call sites (`const LABELS: TwoFactorSettingLabels = {…}`),
+   * so a new REQUIRED key is a compile error in every app on the next `npm update` —
+   * the additive-API rule in the README. Each falls back to the provider's
+   * `accountSettings.twoFactor`, then English.
+   */
+  qrAlt?: string;
+  /** The line over the manual-entry key, for a phone that cannot scan its own screen. */
+  secretHint?: string;
+  /** The copy button beside that key. */
+  copySecret?: string;
+}
+
+export interface PasskeysSettingLabels {
+  title: string;
+  /** The line under the title saying what a passkey is for. */
+  description: string;
+  empty: string;
+  loading: string;
+  /** Accessible name of the list. */
+  list: string;
+  nameLabel: string;
+  namePlaceholder: string;
+  add: string;
+  /** The add button while the app's WebAuthn ceremony runs — the OS prompt is open. */
+  adding: string;
+  rename: string;
+  /** The row's rename button, named for its passkey — it starts with `rename`, the
+   *  visible text, so voice control finds it by what it says. */
+  renameItem: (name: string) => string;
+  /** Accessible name of the inline rename field. */
+  renameField: (name: string) => string;
+  save: string;
+  cancel: string;
+  delete: string;
+  /** The row's delete button, named for its passkey (see `renameItem`). */
+  deleteItem: (name: string) => string;
+  /** The inline question a delete asks first. */
+  deleteConfirm: (name: string) => string;
+  /** The destructive button that answers it. */
+  confirmDelete: string;
+  /** `date` arrives formatted in the provider's locale. */
+  created: (date: string) => string;
+  lastUsed: (date: string) => string;
+  neverUsed: string;
+}
+
+export interface AccountSettingsLabels {
+  profile: ProfileSettingLabels;
+  password: PasswordSettingLabels;
+  twoFactor: Required<TwoFactorSettingLabels>;
+  passkeys: PasskeysSettingLabels;
+}
+
+export const DEFAULT_ACCOUNT_SETTINGS_LABELS: AccountSettingsLabels = {
+  profile: {
+    title: "Profile",
+    email: "Email",
+    role: "Role",
+    memberSince: "Member since",
+    displayName: "Display name",
+    save: "Save",
+  },
+  password: {
+    title: "Change password",
+    current: "Current password",
+    next: "New password",
+    confirm: "Confirm new password",
+    submit: "Change password",
+    tooShort: "The new password is too short.",
+    mismatch: "The passwords don’t match.",
+  },
+  twoFactor: {
+    status: "Two-factor authentication",
+    enabledText: "On",
+    disabledText: "Off",
+    enable: "Set up two-factor authentication",
+    scanHint: "Scan this code with your authenticator app, then enter the code it shows.",
+    codeLabel: "Verification code",
+    verify: "Verify and turn on",
+    disableSection: "Turn off two-factor authentication",
+    password: "Current password",
+    disable: "Turn off",
+    // Unchanged from the fallback it had before the namespace (i18n-labels.test pins it).
+    qrAlt: "QR code",
+    secretHint: "Can’t scan it? Enter this key in the app instead:",
+    copySecret: "Copy key",
+  },
+  passkeys: {
+    title: "Passkeys",
+    description: "Sign in with your fingerprint, face or device PIN instead of a password.",
+    empty: "No passkeys yet",
+    loading: "Loading passkeys…",
+    list: "Your passkeys",
+    nameLabel: "Name (optional)",
+    namePlaceholder: "e.g. Laptop, Phone",
+    add: "Add passkey",
+    adding: "Waiting for your device…",
+    rename: "Rename",
+    renameItem: (name) => `Rename ${name}`,
+    renameField: (name) => `New name for ${name}`,
+    save: "Save",
+    cancel: "Cancel",
+    delete: "Delete",
+    deleteItem: (name) => `Delete ${name}`,
+    deleteConfirm: (name) => `Delete “${name}”? It can no longer be used to sign in.`,
+    confirmDelete: "Delete passkey",
+    created: (date) => `Added ${date}`,
+    lastUsed: (date) => `Last used ${date}`,
+    neverUsed: "Never used",
+  },
+};
+
+/**
+ * One section of the namespace, resolved: English, then the provider's
+ * `accountSettings.<section>`, then the component's own `labels` prop. An `undefined`
+ * in either source is skipped, so a prop object built from optional values cannot
+ * blank out a default.
+ */
+export function useAccountSettingsLabels<K extends keyof AccountSettingsLabels>(
+  section: K,
+  prop?: Partial<AccountSettingsLabels[K]>,
+): AccountSettingsLabels[K] {
+  const fromProvider = useKitLabelOverrides("accountSettings")?.[section] as
+    | Partial<AccountSettingsLabels[K]>
+    | undefined;
+  return useMemo(
+    () => ({
+      ...DEFAULT_ACCOUNT_SETTINGS_LABELS[section],
+      ...definedOnly(fromProvider),
+      ...definedOnly(prop),
+    }),
+    [section, fromProvider, prop],
+  );
+}
+
+function definedOnly<T extends object>(value: T | undefined): Partial<T> {
+  if (!value) return {};
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}

package/src/components/account-settings.tsx

@@ -2,24 +2,37 @@ import { useId, useState } from "react";
 import type { KeyboardEvent, ReactNode } from "react";
 import { Button, Card, FIELD_WRITABLE_LOOK, Input } from "./ui";
 import { UserAvatar } from "./user-avatar";
+import { CopyButton } from "./copy-button";
+import { QrCode } from "./qr-code";
 import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
+import { useAccountSettingsLabels } from "./account-settings-labels";
+import type {
+  PasswordSettingLabels,
+  ProfileSettingLabels,
+  TwoFactorSettingLabels,
+} from "./account-settings-labels";
+
+// The label types moved beside the namespace's defaults (0.12.0); re-exported here so
+// every existing `import type { ProfileSettingLabels }` keeps resolving.
+export type {
+  AccountSettingsLabels,
+  PasskeysSettingLabels,
+  PasswordSettingLabels,
+  ProfileSettingLabels,
+  TwoFactorSettingLabels,
+} from "./account-settings-labels";
+export { DEFAULT_ACCOUNT_SETTINGS_LABELS } from "./account-settings-labels";
 
 /**
  * App-agnostic account-settings SECTIONS (feedback #333). The presentation lives
  * in @hb/ui; each app injects its own auth-API handlers + translated labels and
  * arranges these next to its own app-specific cards (appearance, budgets, …).
  * Every section is a self-contained <Card> owning its transient form state.
+ *
+ * Every `labels` prop is optional since 0.12.0: the strings come from the provider's
+ * `accountSettings` namespace, then English (see account-settings-labels.ts).
  */
 
-export interface ProfileSettingLabels {
-  title: string;
-  email: string;
-  role: string;
-  memberSince: string;
-  displayName: string;
-  save: string;
-}
-
 export function ProfileSetting({
   name,
   email,
@@ -29,7 +42,7 @@ export function ProfileSetting({
   onChange,
   onSave,
   saving,
-  labels,
+  labels: labelsProp,
 }: {
   name?: string | null;
   email?: string | null;
@@ -39,8 +52,10 @@ export function ProfileSetting({
   onChange: (value: string) => void;
   onSave: () => void;
   saving?: boolean;
-  labels: ProfileSettingLabels;
+  /** Prop > `<UiKitProvider labels={{ accountSettings: { profile } }}>` > English. */
+  labels?: Partial<ProfileSettingLabels>;
 }) {
+  const labels = useAccountSettingsLabels("profile", labelsProp);
   const dirty = value.trim().length > 0 && value.trim() !== (name ?? "");
   // Generated, not the literal "display-name" it was: two of these on one page (an
   // admin editing someone else's profile beside their own) shared an id, and the
@@ -52,7 +67,12 @@ export function ProfileSetting({
         <UserAvatar name={name} email={email} size="lg" />
         <div className="min-w-0">
           <div className="text-sm font-medium">{labels.title}</div>
-          <div className="truncate font-mono text-xs text-[var(--text-muted)]">{email ?? "—"}</div>
+          <div className="truncate font-mono text-xs text-[var(--text-muted)]">
+            {/* `email` was a required key that nothing rendered; it names the address
+                for a screen reader, which otherwise hears a bare string under a title. */}
+            <span className="sr-only">{labels.email}: </span>
+            {email ?? "—"}
+          </div>
         </div>
       </div>
       <div className="grid grid-cols-[max-content_1fr] gap-x-3 gap-y-1 text-sm">
@@ -75,28 +95,20 @@ export function ProfileSetting({
   );
 }
 
-export interface PasswordSettingLabels {
-  title: string;
-  current: string;
-  next: string;
-  confirm: string;
-  submit: string;
-  tooShort: string;
-  mismatch: string;
-}
-
 export function PasswordSetting({
   onSubmit,
   pending,
   minLength = 8,
-  labels,
+  labels: labelsProp,
 }: {
   /** Called with the validated (current, new) pair; return a promise to auto-clear on success. */
   onSubmit: (currentPassword: string, newPassword: string) => void | Promise<unknown>;
   pending?: boolean;
   minLength?: number;
-  labels: PasswordSettingLabels;
+  /** Prop > `<UiKitProvider labels={{ accountSettings: { password } }}>` > English. */
+  labels?: Partial<PasswordSettingLabels>;
 }) {
+  const labels = useAccountSettingsLabels("password", labelsProp);
   const [current, setCurrent] = useState("");
   const [next, setNext] = useState("");
   const [confirm, setConfirm] = useState("");
@@ -136,34 +148,35 @@ export function PasswordSetting({
   );
 }
 
-export interface TwoFactorSettingLabels {
-  status: string;
-  enabledText: string;
-  disabledText: string;
-  enable: string;
-  scanHint: string;
-  codeLabel: string;
-  verify: string;
-  disableSection: string;
-  password: string;
-  disable: string;
-  /**
-   * Alt text for the setup QR image, which shipped as a hardcoded `alt="QR"`.
-   *
-   * OPTIONAL, alone among these keys, and not because it matters less: this
-   * interface is annotated at consumer call sites (`const LABELS:
-   * TwoFactorSettingLabels = {…}`), so a new REQUIRED key is a compile error in
-   * every app on the next `npm update` — the additive-API rule in the README. It
-   * falls back to English here the way `AmountInput`'s label keys do. Make it
-   * required in the next major, when the three apps can be updated with it.
-   */
-  qrAlt?: string;
+/**
+ * What the app's setup call returned.
+ *
+ * `otpauthUri` (0.12.0) is what an authenticator backend actually hands out; the kit
+ * draws the QR code itself ({@link QrCode}) and reads the manual-entry key out of the
+ * URI's `secret` parameter when `secret` is not given. The `qrSvg` shape — a
+ * base64-encoded SVG image — is what the section took before, which made every app
+ * render a QR library to a static string and base64 it only for the kit to draw it back.
+ */
+export type TwoFactorSetupData =
+  | { qrSvg: string; secret: string }
+  | { otpauthUri: string; secret?: string };
+
+/** The `secret` parameter of an `otpauth://` URI, or null. */
+function otpauthSecret(uri: string): string | null {
+  const match = /[?&]secret=([^&#]*)/i.exec(uri);
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1]) || null;
+  } catch {
+    return match[1] || null;
+  }
 }
 
-/** `qrAlt`'s English fallback, kept beside the interface rather than inline so the
- *  one English word in this section is findable by the same `DEFAULT_*` grep as
- *  every other one. Module-private: the key goes required in the next major. */
-const DEFAULT_QR_ALT = "QR code";
+/** "JBSW Y3DP EHPK 3PXP": the key in groups of four, which is how an authenticator's
+ *  manual-entry screen shows it and how a person copies it by eye. */
+function groupSecret(secret: string): string {
+  return secret.replace(/\s+/g, "").replace(/(.{4})(?=.)/g, "$1 ");
+}
 
 export function TwoFactorSetting({
   enabled,
@@ -172,17 +185,23 @@ export function TwoFactorSetting({
   onEnable,
   onDisable,
   busy,
-  labels,
+  renderQr,
+  labels: labelsProp,
 }: {
   enabled: boolean;
-  /** QR + secret returned by the app's setup call; null before setup starts. */
-  setup: { qrSvg: string; secret: string } | null;
+  /** What the app's setup call returned; null before setup starts. */
+  setup: TwoFactorSetupData | null;
   onStartSetup: () => void;
   onEnable: (code: string) => void;
   onDisable: (password: string, code: string) => void;
   busy?: boolean;
-  labels: TwoFactorSettingLabels;
+  /** Draw the code yourself (a branded QR, a library you already ship). Given the
+   *  `otpauthUri`; the kit's own {@link QrCode} otherwise. Unused with `qrSvg`. */
+  renderQr?: (otpauthUri: string) => ReactNode;
+  /** Prop > `<UiKitProvider labels={{ accountSettings: { twoFactor } }}>` > English. */
+  labels?: Partial<TwoFactorSettingLabels>;
 }) {
+  const labels = useAccountSettingsLabels("twoFactor", labelsProp);
   const [code, setCode] = useState("");
   const [password, setPassword] = useState("");
   // Browsers autofill one-time-code fields with the saved username; keep the
@@ -195,6 +214,9 @@ export function TwoFactorSetting({
   // Only for the "Status: Enabled" composition — the punctuation between a field's
   // name and its value is the language's (see `CommonLabels.fieldValue`).
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const secret = setup
+    ? (setup.secret ?? ("otpauthUri" in setup ? otpauthSecret(setup.otpauthUri) : null))
+    : null;
 
   return (
     <Card className="p-4 space-y-3">
@@ -216,15 +238,40 @@ export function TwoFactorSetting({
               their quiet zone. On the dark theme a surface-coloured backing makes it
               slow to acquire, and on a warm light preset it lowers the contrast ratio
               the spec is written against. This is the one place in the kit where a
-              literal colour is the correct answer. */}
-          <div className="inline-block rounded-md bg-white p-2">
-            <img
-              alt={labels.qrAlt ?? DEFAULT_QR_ALT}
-              src={`data:image/svg+xml;base64,${setup.qrSvg}`}
-              className="h-48 w-48"
-            />
-          </div>
-          <div className="break-all font-mono text-xs">{setup.secret}</div>
+              literal colour is the correct answer. `data-private`: the code IS the
+              second factor, and demo mode blurs it like any other secret. */}
+          {"otpauthUri" in setup ? (
+            // No backing of its own: QrCode draws its quiet zone white inside the SVG.
+            <div data-private className="inline-block overflow-hidden rounded-md">
+              {renderQr ? (
+                renderQr(setup.otpauthUri)
+              ) : (
+                <QrCode value={setup.otpauthUri} label={labels.qrAlt} className="size-48" />
+              )}
+            </div>
+          ) : (
+            <div data-private className="inline-block rounded-md bg-white p-2">
+              <img
+                alt={labels.qrAlt}
+                src={`data:image/svg+xml;base64,${setup.qrSvg}`}
+                className="h-48 w-48"
+              />
+            </div>
+          )}
+          {secret && (
+            <div className="space-y-1">
+              <div className="text-xs text-[var(--text-secondary)]">{labels.secretHint}</div>
+              <div className="flex items-center gap-1">
+                {/* `dir="ltr"`: a base32 key is Latin letters and digits in a fixed
+                    order, and in an RTL page the groups would otherwise be laid out
+                    right to left. */}
+                <code data-private dir="ltr" className="break-all font-mono text-xs select-all">
+                  {groupSecret(secret)}
+                </code>
+                <CopyButton text={secret} label={labels.copySecret} size="xs" tone="muted" />
+              </div>
+            </div>
+          )}
           <Input
             inputMode="numeric"
             autoComplete="one-time-code"

package/src/components/amount-input.tsx

@@ -38,6 +38,15 @@ interface AmountInputProps {
   className?: string;
   id?: string;
   ariaLabel?: string;
+  /**
+   * Set on the `<input>`, with `id` above. Declared so `Field`'s render-prop spread —
+   * `{(ids) => <AmountInput {...ids} … />}` — is typed and reaches the input: the
+   * hint and error are described, a required amount is announced as required, and
+   * `aria-invalid` paints {@link FIELD_INVALID} the way `invalid` does.
+   */
+  "aria-describedby"?: string;
+  "aria-invalid"?: boolean | "true" | "false";
+  "aria-required"?: boolean | "true" | "false";
   /** Every user-facing string this component and the two it composes own, so a
    *  translating host can supply its own. Each key optional, and each a per-field
    *  override of the kit-wide translation in `<UiKitProvider labels>`: `currency`
@@ -183,9 +192,10 @@ function isResultOf(previous: string, text: string): boolean {
 }
 
 export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
-  ({ value, onChange, currency, onCurrencyChange, placeholder, label, disabled, invalid, className, id, ariaLabel, autoFocus, tone = "neutral", negative = false, onNegativeChange, variant = "field", align = "start", labels, currencyNames }, ref) => {
+  ({ value, onChange, currency, onCurrencyChange, placeholder, label, disabled, invalid: invalidProp, className, id, ariaLabel, "aria-describedby": ariaDescribedBy, "aria-invalid": ariaInvalid, "aria-required": ariaRequired, autoFocus, tone = "neutral", negative = false, onNegativeChange, variant = "field", align = "start", labels, currencyNames }, ref) => {
     const generatedId = useId();
     const fieldId = id ?? generatedId;
+    const invalid = Boolean(invalidProp) || ariaInvalid === true || ariaInvalid === "true";
     const editable = !!onCurrencyChange;
     // On phones we suppress the OS keyboard (inputMode="none" below) and show our
     // own calculator numpad, so the desktop popover trigger is hidden. The
@@ -350,6 +360,8 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
             invalid && FIELD_INVALID,
           )}
           aria-invalid={invalid || undefined}
+          aria-describedby={ariaDescribedBy}
+          aria-required={ariaRequired}
         />
         {label !== undefined && (
           // The display shape drops the label VISUALLY, not from the accessibility

package/src/components/authed-image.tsx

@@ -0,0 +1,190 @@
+import { useState } from "react";
+import type { ImgHTMLAttributes, ReactNode } from "react";
+import { ImageOff } from "lucide-react";
+
+import { cn } from "../lib/cn";
+import { useKitLabels } from "../i18n/kit-labels";
+import { SKELETON_CLASS } from "./skeleton";
+import { useAuthedSrc } from "../hooks/use-authed-src";
+import type { AuthedFetcher, UseAuthedSrcResult } from "../hooks/use-authed-src";
+
+/** The two states an image can be in besides "there". */
+export interface AuthedImageLabels {
+  /** Read out while the bytes are on their way (the skeleton itself is silent). */
+  loading: string;
+  /** Shown, small, in place of an image that could not be fetched or decoded. */
+  loadError: string;
+  /** The failed tile's accessible name, given the image's alt. */
+  failedImage: (alt: string) => string;
+}
+
+export const DEFAULT_AUTHED_IMAGE_LABELS: AuthedImageLabels = {
+  loading: "Loading image…",
+  loadError: "Image couldn’t be loaded",
+  failedImage: (alt) => `${alt}: image couldn’t be loaded`,
+};
+
+export interface AuthedImageProps
+  extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "children"> {
+  /** The image's URL — an API path when a {@link fetcher} is given. */
+  src: string | null | undefined;
+  /** Required: an image without a text alternative is a gap a reader falls into.
+   *  `""` for a purely decorative one. */
+  alt: string;
+  /** The app's authenticated GET (see {@link useAuthedSrc}). Left out, `src` is loaded
+   *  by the browser as usual and this is an `<img>` with loading and error states. */
+  fetcher?: AuthedFetcher | null;
+  /** Classes for the box around the image (the placeholders fill it). */
+  wrapperClassName?: string;
+  /**
+   * Wrap the image in a link to itself, opening in a new tab — kastlan's
+   * `AuthedImage` did, because an object URL is the only address of a protected image
+   * a browser tab can open. The link's href is the `blob:` URL, never the API path.
+   */
+  link?: boolean;
+  /** Replaces the default skeleton while loading. */
+  loadingFallback?: ReactNode;
+  /** Replaces the default "couldn't load" tile. */
+  errorFallback?: ReactNode;
+  labels?: Partial<AuthedImageLabels>;
+}
+
+/**
+ * An image with a loading state, an error state and — given a `fetcher` — the app's
+ * authentication. Replaces kastlan's `shared/components/authed-image.tsx`, which
+ * rendered NOTHING until the blob arrived and nothing at all if it never did: a card
+ * with a photo slot either had the photo or was silently shorter.
+ *
+ * Two failures are one state here: the fetch failing (401, 404, offline) and the
+ * browser failing to decode what arrived (`onError` on the `<img>`, e.g. a PDF served
+ * where an image was expected).
+ */
+export function AuthedImage({
+  src,
+  alt,
+  fetcher,
+  wrapperClassName,
+  className,
+  link,
+  loadingFallback,
+  errorFallback,
+  labels: labelsProp,
+  onLoad,
+  onError,
+  ...rest
+}: AuthedImageProps) {
+  const labels = useKitLabels("authedImage", DEFAULT_AUTHED_IMAGE_LABELS, labelsProp);
+  const fetched = useAuthedSrc(src, { fetcher });
+  return (
+    <ImageStates
+      fetched={fetched}
+      alt={alt}
+      labels={labels}
+      className={className}
+      wrapperClassName={wrapperClassName}
+      link={link}
+      loadingFallback={loadingFallback}
+      errorFallback={errorFallback}
+      imgProps={rest}
+      onLoad={onLoad}
+      onError={onError}
+    />
+  );
+}
+
+/**
+ * The rendering half of {@link AuthedImage}, for a caller that already holds a
+ * {@link useAuthedSrc} result (the lightbox needs the object URL for its download link
+ * as well). Internal to the package.
+ */
+export function ImageStates({
+  fetched,
+  alt,
+  labels,
+  className,
+  wrapperClassName,
+  link,
+  loadingFallback,
+  errorFallback,
+  imgProps,
+  onLoad,
+  onError,
+}: {
+  fetched: UseAuthedSrcResult;
+  alt: string;
+  labels: AuthedImageLabels;
+  className?: string;
+  wrapperClassName?: string;
+  link?: boolean;
+  loadingFallback?: ReactNode;
+  errorFallback?: ReactNode;
+  imgProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "children" | "onLoad" | "onError">;
+  onLoad?: ImgHTMLAttributes<HTMLImageElement>["onLoad"];
+  onError?: ImgHTMLAttributes<HTMLImageElement>["onError"];
+}) {
+  // Decode state, per src: keyed so a new picture starts over rather than inheriting
+  // the previous one's "loaded" or "broken".
+  const [decode, setDecode] = useState<{ src: string | null; state: "loaded" | "error" } | null>(null);
+  const decoded = decode && decode.src === fetched.src ? decode.state : "pending";
+  const failed = fetched.status === "error" || decoded === "error";
+  const waiting = !failed && (fetched.status === "loading" || (fetched.src !== null && decoded === "pending"));
+
+  const img = fetched.src !== null && !failed && (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- load/error are resource events, not interactions
+    <img
+      {...imgProps}
+      src={fetched.src}
+      alt={alt}
+      onLoad={(e) => {
+        setDecode({ src: fetched.src, state: "loaded" });
+        onLoad?.(e);
+      }}
+      onError={(e) => {
+        setDecode({ src: fetched.src, state: "error" });
+        onError?.(e);
+      }}
+      className={cn(
+        // Kept in the tree while it decodes (the browser needs it there to load at
+        // all), but invisible, so the skeleton is what shows.
+        decoded === "pending" && "opacity-0",
+        className,
+      )}
+    />
+  );
+
+  return (
+    <span
+      data-image-state={failed ? "error" : waiting ? "loading" : fetched.status === "idle" ? "idle" : "ready"}
+      className={cn("relative block overflow-hidden", wrapperClassName)}
+      aria-busy={waiting || undefined}
+    >
+      {link && img && fetched.src ? (
+        <a href={fetched.src} target="_blank" rel="noreferrer noopener" className="block h-full w-full">
+          {img}
+        </a>
+      ) : (
+        img
+      )}
+      {waiting &&
+        (loadingFallback ?? (
+          <span className={cn(SKELETON_CLASS, "absolute inset-0 block rounded-none")}>
+            <span className="sr-only">{labels.loading}</span>
+          </span>
+        ))}
+      {failed &&
+        (errorFallback ?? (
+          <span
+            // `role="img"` with the alt as its name: the picture that failed still
+            // occupies its place in the reading order, and "couldn't be loaded" is
+            // the one fact a reader needs about it.
+            role="img"
+            aria-label={alt ? labels.failedImage(alt) : labels.loadError}
+            className="flex h-full min-h-16 w-full flex-col items-center justify-center gap-1 bg-[var(--bg-hover)] p-2 text-center text-xs text-[var(--text-muted)]"
+          >
+            <ImageOff aria-hidden className="size-5 shrink-0" />
+            <span aria-hidden className="line-clamp-2">{labels.loadError}</span>
+          </span>
+        ))}
+    </span>
+  );
+}