@eifi1/ui-kit 0.10.0 → 0.12.0

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/alert-banner.tsx

@@ -140,6 +140,31 @@ interface AlertBannerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "on
   variant?: "box" | "inline" | "strip";
   /** See {@link AlertSize}. Default `md`. */
   size?: AlertSize;
+  /**
+   * `inline` only (0.11.0): lay the message out as a BLOCK — a full-width `flex` row,
+   * the glyph on the text's FIRST line when it wraps — instead of the `inline-flex`,
+   * centred line it is by default. keksdose writes `className="flex"` on nearly every
+   * inline banner it has (accounts-page:564, holdings-panel:631, import-map-step:66/314,
+   * guest-key-control:84) to get a line of its own under a total or a field, and a
+   * two-line hint there then centres its glyph between the lines.
+   *
+   * An option rather than the new default, because the inline-flex is load-bearing for
+   * the callers the variant was made for: lenkbank's corner-motion toolbar
+   * (corner-motion.tsx:178) sets it as a `shrink-0` item beside the controls, kastlan's
+   * import page and keksdose's rules page place it in a run of content — a block would
+   * take the whole row in the second kind, and top-align the first against a taller
+   * control. Ignored by `box` and `strip`, which are blocks already.
+   */
+  block?: boolean;
+  /**
+   * `false` opts an inline banner out of its live region (no `role="alert"` /
+   * `role="status"`), for a message that is static page content rather than the answer
+   * to something the user just did: keksdose's CAMT review step (camt-review-step:214)
+   * renders "unresolved rows block the import" as part of the step, and as
+   * `role="alert"` a screen reader interrupted with it on every mount. A `role` you pass
+   * still wins. Default `true`; the box and the strip are role-less either way.
+   */
+  live?: boolean;
   /**
    * An opaque, raised surface (a shadow, and no translucency in dark mode) for a
    * notice that floats over the page — see {@link TONE_ELEVATED}. `box` and `strip`
@@ -200,6 +225,8 @@ export function AlertBanner({
   tone = "danger",
   variant = "box",
   size = "md",
+  block = false,
+  live = true,
   elevated = false,
   action,
   icon,
@@ -217,11 +244,13 @@ export function AlertBanner({
   const strip = variant === "strip";
   const sm = size === "sm";
   const interactive = href !== undefined || onClick !== undefined;
-  const resolvedRole = role ?? (inline ? (tone === "danger" ? "alert" : "status") : undefined);
+  // A block-laid inline banner behaves like a box for layout: a row that may wrap.
+  const inlineRow = inline && !block;
+  const resolvedRole = role ?? (inline && live ? (tone === "danger" ? "alert" : "status") : undefined);
 
   const Glyph = TONE_GLYPH[tone];
   // Onto the first line of a box's text: 2px at 14px/20px, 1px at 12px/16px.
-  const nudge = inline || strip ? undefined : sm ? "mt-px" : "mt-0.5";
+  const nudge = inlineRow || strip ? undefined : sm ? "mt-px" : "mt-0.5";
   const glyph =
     icon === null ? null : icon !== undefined ? (
       <span
@@ -239,7 +268,7 @@ export function AlertBanner({
   // column, so the action drops under it instead. A box may wrap its text, so it
   // top-aligns and nudges the glyph onto the first line.
   const row = cn(
-    inline ? "inline-flex items-center" : strip ? "flex flex-wrap items-center gap-y-1" : "flex items-start",
+    inlineRow ? "inline-flex items-center" : strip ? "flex flex-wrap items-center gap-y-1" : "flex items-start",
     sm ? "gap-1.5 text-xs" : inline ? "gap-1.5 text-sm" : "gap-2 text-sm",
   );
   const frame = inline
@@ -254,7 +283,7 @@ export function AlertBanner({
   const content = (
     <>
       {glyph}
-      <span className={cn(!inline && "flex-1", "min-w-0 text-start")}>{children}</span>
+      <span className={cn(!inlineRow && "flex-1", "min-w-0 text-start")}>{children}</span>
       {interactive && (
         <ChevronRight
           aria-hidden
@@ -288,7 +317,7 @@ export function AlertBanner({
   // `relative z-10` so it stays clickable over a whole-row banner's stretched target.
   const trailing =
     action !== undefined && action !== null ? (
-      <div className={cn("relative z-10 flex shrink-0 items-center gap-2", !strip && !inline && "self-center", strip && "ms-auto")}>
+      <div className={cn("relative z-10 flex shrink-0 items-center gap-2", !strip && !inlineRow && "self-center", strip && "ms-auto")}>
         {action}
       </div>
     ) : null;
@@ -319,12 +348,12 @@ export function AlertBanner({
     ? cn(
         "flex min-w-0 flex-1 text-start",
         sm ? "gap-1.5" : "gap-2",
-        inline || strip ? "items-center" : "items-start",
+        inlineRow || strip ? "items-center" : "items-start",
         "outline-none after:absolute after:inset-0 after:content-['']",
         strip ? "after:rounded-none" : "after:rounded-md",
         "focus-visible:after:ring-2 focus-visible:after:ring-[var(--brand)]",
       )
-    : cn(row, !inline && "w-full", frame, TONE_TEXT[tone], hover, focusRing, className);
+    : cn(row, !inlineRow && "w-full", frame, TONE_TEXT[tone], hover, focusRing, className);
   // The div's attributes are the row element's: an `id`, a test id or an
   // `aria-describedby` belongs on the thing that takes focus. The live-region role is
   // NOT carried over — a button or a link that is also a `status` is neither.

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>
+  );
+}

package/src/components/breadcrumbs.tsx

@@ -2,7 +2,8 @@ import { Fragment, useEffect, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 import { ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../lib/cn";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 
 export interface BreadcrumbsLabels {
   /** The `nav` landmark's name — what a screen reader lists it as. */
@@ -35,7 +36,8 @@ export interface BreadcrumbLinkProps {
 
 export interface BreadcrumbsProps extends Omit<ComponentPropsWithoutRef<"nav">, "children"> {
   items: BreadcrumbItem[];
-  /** Your router's link. Default `<a>`. The API `Chip`, `StatTile` and `ListItem` share. */
+  /** Your router's link. Default: the `<UiKitProvider linkComponent>` (for an in-app
+   *  `href`), then `<a>`. The API `Chip`, `StatTile` and `ListItem` share. */
   renderLink?: (props: BreadcrumbLinkProps) => ReactElement;
   /**
    * The mark between crumbs. Default a chevron, mirrored in RTL — a chevron pointing
@@ -78,6 +80,7 @@ export function Breadcrumbs({
   ...rest
 }: BreadcrumbsProps) {
   const labels = useKitLabels("breadcrumbs", DEFAULT_BREADCRUMBS_LABELS, labelsProp);
+  const kitLink = useKitLink();
   const [expanded, setExpanded] = useState(false);
   // The "…" button vanishes when pressed; focus goes to the first crumb it revealed,
   // not back to the top of the document.
@@ -121,8 +124,11 @@ export function Breadcrumbs({
             );
           } else if (item.href !== undefined) {
             const props: BreadcrumbLinkProps = { href: item.href, className: linkClass, children: item.label };
+            const kit = pickLinkRenderer<BreadcrumbLinkProps>(undefined, kitLink, item.href);
             content = renderLink ? (
               renderLink(props)
+            ) : kit ? (
+              <RenderedKitLink render={kit} props={props} />
             ) : (
               <a href={props.href} className={props.className}>
                 {props.children}