1 ADR 0045 progressive image component
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

ADR 0045: ProgressiveImage Shared Component Pattern

Status: proposed Date: 2026-06-06

Context

After the UX Overhaul (spec 006), the app lost progressive image loading. The previous implementation used blurred 512px thumbnails that showed immediately, with sharp 2048px previews swapping in once ready. The redesign replaced this with skeleton placeholders that jump directly to full quality.

At least six pages share this pattern: media grid, media detail, face thumbnails in People, person detail, album covers, and search results. Each needs the same blur→HQ dual-layer behavior with a smooth crossfade transition, prefers-reduced-motion support, and consistent accessibility.

Without a shared component, implementing progressive loading in each page independently would mean:

  • Duplicating 30+ lines of template, state, and transition logic across 6+ call sites
  • Inconsistent accessibility handling (some pages forgetting aria-hidden on the blur layer, missing decoding="async")
  • Transition behavior diverging between pages over time

Decision

Extract ProgressiveImage.svelte as a shared Svelte 5 component that encapsulates:

  • Blur thumbnail layer: always shown when thumbnailUrl is provided
  • HQ preview layer: conditional on previewReady && previewUrl
  • Crossfade transition: opacity transition on HQ load
  • prefers-reduced-motion support: disables crossfade, shows HQ instantly
  • loading="lazy" + decoding="async" on both <img> elements
  • aria-hidden="true" on the blur layer (decorative)

Props

Prop Type Description
thumbnailUrl string | null Blurred thumbnail URL (512px)
previewUrl string | null Sharp preview URL (2048px)
previewReady boolean Whether preview URL is available for display
alt string Alt text for the image
objectFit 'cover' | 'contain' CSS object-fit (default: 'cover')
class string | undefined Additional CSS classes

Behavior

thumbnailUrl present  →  blur layer visible (always)
previewReady && previewUrl  →  HQ layer fades in over blur layer
!previewReady  →  blur layer shown alone (or skeleton if no thumbnail)
prefers-reduced-motion  →  no crossfade, HQ appears instantly

Alternatives Considered

  1. Inline snippets per page: Duplicate 30+ lines across 6+ pages. Drift risk, inconsistent a11y, no single place to fix bugs. Rejected.

  2. Wrapper component around <img>: Only handles single-layer display. Does not support the dual-layer blur+HQ pattern where both layers coexist simultaneously during crossfade. Rejected.

  3. CSS-only approach (image-set() or @supports): Cannot gate HQ display on a runtime previewStatus state. No way to trigger crossfade on async readiness. Rejected.

Rationale

  • DRY: 6+ call sites need identical logic — component eliminates duplication
  • Encapsulation: transition, a11y, and load state managed in one place
  • Testable: isolated component with clear props interface, no page-level coupling
  • No new dependencies: pure Svelte 5 runes + Tailwind CSS

Constraints

  • Svelte 5 runes only ($state, $props, $derived)
  • No new runtime libraries
  • Component does not manage its own IntersectionObserver — parent controls viewport gating via previewReady prop
  • Must accept arbitrary URL patterns (face thumbnails use different URL structures than media thumbnails)

Consequences

  • Progressive loading restored across all image contexts with consistent behavior
  • Single place to maintain transition timing, a11y attributes, and load optimization
  • Pages only need to provide thumbnailUrl, previewUrl, and previewReady — component handles the rest
  • Future changes to progressive loading behavior (e.g., adding blur-up filter, LQIP placeholders) happen in one file
  • No impact on backend or worker systems — purely a frontend presentation pattern

References

  • Spec 013: specs/013-progressive-image-loading/spec.md
  • Requirements R1–R5
  • Existing blur pattern: MediaGrid.svelte lines 650–684