Skip to main content

day_pieces/
async_image.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! Images decoded from reactive bytes, with a placeholder and optional clipping.
5//! Uses the core decoder and canvas; no toolkit-specific image pipeline or HTTP dependency.
6use crate::{Decorate, Decorated, canvas};
7use day_core::{BuildCx, Dimension, Piece, RNode, TaskHandle};
8use day_reactive::{Scope, Signal, watch};
9use day_spec::{Color, Rect, Shape};
10use std::{cell::RefCell, rc::Rc, sync::Arc};
11
12pub use day_spec::props::ContentMode;
13
14#[derive(Clone, Copy, Debug, Default, PartialEq)]
15enum Clip {
16    #[default]
17    None,
18    Circle,
19    Rounded(f64),
20}
21
22/// A growing image surface. Empty and invalid sources show the placeholder.
23#[must_use]
24pub struct AsyncImage {
25    source: Signal<Option<Arc<Vec<u8>>>>,
26    clip: Clip,
27    mode: ContentMode,
28    placeholder: Color,
29}
30
31/// Decode each source asynchronously. A replacement cancels the previous decode; disposal
32/// cancels the pending task. A failed replacement clears the previous picture.
33pub fn async_image(source: Signal<Option<Arc<Vec<u8>>>>) -> AsyncImage {
34    AsyncImage {
35        source,
36        clip: Clip::None,
37        mode: ContentMode::Fill,
38        placeholder: Color::rgb(0.82, 0.82, 0.84),
39    }
40}
41
42#[crate::builder(AsyncImageBuilder)]
43impl AsyncImage {
44    /// Clip to the centered circle whose diameter is the shorter side.
45    pub fn circle(mut self) -> Self {
46        self.clip = Clip::Circle;
47        self
48    }
49    /// Clip to a rounded rectangle.
50    pub fn rounded(mut self, radius: f64) -> Self {
51        self.clip = Clip::Rounded(radius.max(0.0));
52        self
53    }
54    /// Scale within the frame; defaults to aspect fill.
55    pub fn content_mode(mut self, mode: ContentMode) -> Self {
56        self.mode = mode;
57        self
58    }
59    /// Color displayed while empty, loading, or invalid.
60    pub fn placeholder_color(mut self, color: Color) -> Self {
61        self.placeholder = color;
62        self
63    }
64}
65
66impl Piece for AsyncImage {
67    fn build(self, cx: &mut BuildCx) -> RNode {
68        let Self {
69            source,
70            clip,
71            mode,
72            placeholder,
73        } = self;
74        let bitmap: Signal<Option<day_core::Bitmap>> = Signal::new(None);
75        let pending: Rc<RefCell<Option<TaskHandle>>> = Rc::new(RefCell::new(None));
76        let cancel = pending.clone();
77        Scope::current().on_cleanup(move || {
78            if let Some(task) = cancel.borrow_mut().take() {
79                task.abort();
80            }
81        });
82        let load = move |bytes: Option<Arc<Vec<u8>>>| {
83            if let Some(task) = pending.borrow_mut().take() {
84                task.abort();
85            }
86            bitmap.set(None);
87            if let Some(bytes) = bytes {
88                let task = day_core::task(async move {
89                    bitmap.set(day_core::decode_image(bytes).await.ok());
90                });
91                *pending.borrow_mut() = Some(task);
92            }
93        };
94        load(source.get_untracked());
95        watch(move || source.get(), move |bytes, _| load(bytes.clone()));
96        canvas(move |d, size| {
97            let bounds = Rect::from_size(size);
98            let shape = match clip {
99                Clip::None => Shape::Rect(bounds),
100                Clip::Rounded(radius) => Shape::RoundedRect(bounds, radius),
101                Clip::Circle => {
102                    let side = size.width.min(size.height);
103                    Shape::Ellipse(Rect::new(
104                        (size.width - side) / 2.0,
105                        (size.height - side) / 2.0,
106                        side,
107                        side,
108                    ))
109                }
110            };
111            d.clipped(shape, |d| {
112                d.fill(Shape::Rect(bounds), placeholder);
113                if let Some(image) = bitmap.get() {
114                    let pixels = image.info().pixels;
115                    if pixels.width <= 0.0 || pixels.height <= 0.0 {
116                        return;
117                    }
118                    let rect = if mode == ContentMode::Stretch {
119                        bounds
120                    } else {
121                        let x = size.width / pixels.width;
122                        let y = size.height / pixels.height;
123                        let scale = if mode == ContentMode::Fill {
124                            x.max(y)
125                        } else {
126                            x.min(y)
127                        };
128                        let w = pixels.width * scale;
129                        let h = pixels.height * scale;
130                        Rect::new((size.width - w) / 2.0, (size.height - h) / 2.0, w, h)
131                    };
132                    d.image(&image, rect);
133                }
134            });
135        })
136        .grow(Dimension::Both)
137        .build(cx)
138    }
139}
140
141/// The remote image's conformance cases (docs/testing.md): the bytes path, which needs no
142/// network.
143#[cfg(feature = "conformance")]
144pub mod conformance {
145    use std::sync::Arc;
146
147    use crate::*;
148    use day_core::conformance::{Case, Drive};
149    use day_reactive::Signal;
150    use day_spec::{Cap, Color};
151
152    use super::{ContentMode, async_image};
153
154    /// A 4×2 PNG, red on the left half, blue on the right.
155    const RED_BLUE: [u8; 76] = [
156        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
157        0x52, 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 0x02, 0x08, 0x02, 0x00, 0x00, 0x00, 0xf0,
158        0xca, 0xea, 0x34, 0x00, 0x00, 0x00, 0x13, 0x49, 0x44, 0x41, 0x54, 0x78, 0xda, 0x63, 0xf8,
159        0xcf, 0xc0, 0x00, 0x44, 0x60, 0xe2, 0x3f, 0x03, 0x32, 0x07, 0x00, 0x67, 0xb2, 0x07, 0xf9,
160        0xf7, 0x92, 0x56, 0x82, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60,
161        0x82,
162    ];
163
164    /// A 1×1 opaque green PNG, deliberately a different size as well as a different color.
165    const GREEN: [u8; 69] = [
166        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
167        0x52, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, 0x00, 0x00, 0x00, 0x90,
168        0x77, 0x53, 0xde, 0x00, 0x00, 0x00, 0x0c, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0x63, 0x60,
169        0xf8, 0xcf, 0x00, 0x00, 0x02, 0x02, 0x01, 0x00, 0x7b, 0x09, 0x81, 0x78, 0x00, 0x00, 0x00,
170        0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
171    ];
172
173    /// A 60×20 PNG with equal red, green, blue vertical bands. Filling a square crops to
174    /// green; fitting or stretching preserves the red/blue edges, so these modes differ.
175    const STRIPES: [u8; 104] = [
176        0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
177        0x52, 0x00, 0x00, 0x00, 0x3c, 0x00, 0x00, 0x00, 0x14, 0x08, 0x02, 0x00, 0x00, 0x00, 0x5e,
178        0x61, 0xc9, 0x7e, 0x00, 0x00, 0x00, 0x2f, 0x49, 0x44, 0x41, 0x54, 0x78, 0x9c, 0xed, 0xce,
179        0xb1, 0x09, 0x00, 0x00, 0x0c, 0xc3, 0xb0, 0xfc, 0xff, 0x74, 0xfb, 0x43, 0x4a, 0x37, 0x81,
180        0x57, 0x83, 0x32, 0x49, 0x5d, 0x7f, 0x1e, 0x67, 0x68, 0x68, 0x68, 0x68, 0x68, 0x68, 0x68,
181        0x68, 0x68, 0x68, 0x68, 0x68, 0xe8, 0x8f, 0x79, 0x01, 0x39, 0x0f, 0xab, 0x8d, 0x85, 0x9c,
182        0x89, 0x2d, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4e, 0x44, 0xae, 0x42, 0x60, 0x82,
183    ];
184
185    /// Until bytes arrive the placeholder color shows; once they do, the image draws.
186    #[day_macros::test(day_core)]
187    fn async_image_shows_bytes() -> Case {
188        Case::new()
189            .proves(day_spec::kinds::CANVAS)
190            .requires(Cap::Snapshot)
191            .page(|| {
192                let source: Signal<Option<Arc<Vec<u8>>>> = Signal::new(None);
193                column((
194                    button("Load")
195                        .action(move || source.set(Some(Arc::new(RED_BLUE.to_vec()))))
196                        .id(day_core::id!(async_image::load)),
197                    async_image(source)
198                        .placeholder_color(Color::rgb(0.5, 0.5, 0.5))
199                        .id(day_core::id!(async_image::image))
200                        .frame(120.0, 60.0),
201                ))
202            })
203            .drive(|d: Drive| async move {
204                // Gray: a saturated placeholder shifts under a wide-gamut capture (iOS).
205                d.sample_pixel("async_image::image", 0.5, 0.5, "#808080")
206                    .await?;
207                d.tap("async_image::load").await?;
208                d.sample_pixel("async_image::image", 0.2, 0.5, "#ff0000")
209                    .await?;
210                d.sample_pixel("async_image::image", 0.8, 0.5, "#0000ff")
211                    .await
212            })
213    }
214
215    /// A replacement must not keep the old pixels; absent, empty and corrupt sources all
216    /// restore the placeholder. Unmounting must release native resources and reactive watchers.
217    #[day_macros::test(day_core)]
218    fn async_image_replaces_clears_and_remounts() -> Case {
219        Case::new()
220            .proves(day_spec::kinds::CANVAS)
221            .requires(Cap::Snapshot)
222            .page(|| {
223                let source = Signal::new(Some(Arc::new(RED_BLUE.to_vec())));
224                let shown = Signal::new(true);
225                column((
226                    row((
227                        button("Green")
228                            .action(move || source.set(Some(Arc::new(GREEN.to_vec()))))
229                            .id(day_core::id!(async_image::green)),
230                        button("Clear")
231                            .action(move || source.set(None))
232                            .id(day_core::id!(async_image::clear)),
233                        button("Empty")
234                            .action(move || source.set(Some(Arc::new(Vec::new()))))
235                            .id(day_core::id!(async_image::empty)),
236                    )),
237                    row((
238                        button("Invalid")
239                            .action(move || source.set(Some(Arc::new(vec![1, 2, 3]))))
240                            .id(day_core::id!(async_image::invalid)),
241                        button("Mount")
242                            .action(move || shown.set(!shown.get()))
243                            .id(day_core::id!(async_image::mount)),
244                    )),
245                    when(
246                        move || shown.get(),
247                        move || {
248                            async_image(source)
249                                .placeholder_color(Color::hex(0x0080_8080))
250                                .id(day_core::id!(async_image::image))
251                                .frame(120.0, 60.0)
252                        },
253                    ),
254                ))
255            })
256            .drive(|d: Drive| async move {
257                d.sample_pixel("async_image::image", 0.2, 0.5, "#ff0000")
258                    .await?;
259                for action in [
260                    "async_image::clear",
261                    "async_image::empty",
262                    "async_image::invalid",
263                ] {
264                    d.tap("async_image::green").await?;
265                    d.sample_pixel("async_image::image", 0.2, 0.5, "#00ff00")
266                        .await?;
267                    d.tap(action).await?;
268                    d.sample_pixel("async_image::image", 0.2, 0.5, "#808080")
269                        .await?;
270                }
271                for _ in 0..3 {
272                    d.tap("async_image::mount").await?;
273                    d.assert_missing("async_image::image").await?;
274                    d.tap("async_image::green").await?; // Update while disposed: no stale native callback.
275                    d.tap("async_image::mount").await?;
276                    d.sample_pixel("async_image::image", 0.8, 0.5, "#00ff00")
277                        .await?;
278                    d.tap("async_image::clear").await?;
279                    d.sample_pixel("async_image::image", 0.8, 0.5, "#808080")
280                        .await?;
281                }
282                Ok(())
283            })
284    }
285
286    /// Fit letterboxes; Fill covers the frame without stretching the image.
287    #[day_macros::test(day_core)]
288    fn async_image_fit_and_fill() -> Case {
289        Case::new()
290            .proves(day_spec::kinds::CANVAS)
291            .requires(Cap::Snapshot)
292            .page(|| {
293                let source = Signal::new(Some(Arc::new(STRIPES.to_vec())));
294                column((
295                    async_image(source)
296                        .content_mode(ContentMode::Fit)
297                        .placeholder_color(Color::hex(0x0080_8080))
298                        .id(day_core::id!(async_image::fit))
299                        .frame(100.0, 100.0),
300                    async_image(source)
301                        .content_mode(ContentMode::Fill)
302                        .placeholder_color(Color::hex(0x0080_8080))
303                        .id(day_core::id!(async_image::fill))
304                        .frame(100.0, 100.0),
305                ))
306            })
307            .drive(|d: Drive| async move {
308                d.sample_pixel("async_image::fit", 0.2, 0.1, "#808080")
309                    .await?;
310                d.sample_pixel("async_image::fit", 0.2, 0.5, "#ff0000")
311                    .await?;
312                d.sample_pixel("async_image::fit", 0.8, 0.5, "#0000ff")
313                    .await?;
314                d.sample_pixel("async_image::fill", 0.1, 0.1, "#00ff00")
315                    .await?;
316                d.sample_pixel("async_image::fill", 0.9, 0.9, "#00ff00")
317                    .await?;
318                // Pixel assertions wait for the native render checkpoint; capture afterwards.
319                d.shot("default").await
320            })
321    }
322
323    /// A circle is centered with diameter min(width, height), not a capsule/ellipse. Both
324    /// image and placeholder are clipped; a rounded rectangle must keep its straight edges.
325    #[day_macros::test(day_core)]
326    fn async_image_clips_image_and_placeholder() -> Case {
327        Case::new()
328            .proves(day_spec::kinds::CANVAS)
329            .requires(Cap::Snapshot)
330            // 18 pixel samples, each a snapshot: 18–29 s on the CI Android 36 emulator, and
331            // over the 30 s default on a slow one.
332            .timeout(90.0)
333            .page(|| {
334                let source = Signal::new(Some(Arc::new(GREEN.to_vec())));
335                column((
336                    button("Clear")
337                        .action(move || source.set(None))
338                        .id(day_core::id!(async_image::clear)),
339                    async_image(source)
340                        .circle()
341                        .placeholder_color(Color::hex(0x0080_8080))
342                        .id(day_core::id!(async_image::wide))
343                        .frame(120.0, 60.0),
344                    async_image(source)
345                        .circle()
346                        .placeholder_color(Color::hex(0x0080_8080))
347                        .id(day_core::id!(async_image::tall))
348                        .frame(60.0, 120.0),
349                    async_image(source)
350                        .rounded(20.0)
351                        .placeholder_color(Color::hex(0x0080_8080))
352                        .id(day_core::id!(async_image::rounded))
353                        .frame(120.0, 60.0),
354                ))
355                .background(Color::hex(0x0000_0000))
356            })
357            .drive(|d: Drive| async move {
358                for color in ["#00ff00", "#808080"] {
359                    for id in [
360                        "async_image::wide",
361                        "async_image::tall",
362                        "async_image::rounded",
363                    ] {
364                        d.sample_pixel(id, 0.5, 0.5, color).await?;
365                        d.sample_pixel(id, 0.02, 0.02, "#000000").await?;
366                    }
367                    d.sample_pixel("async_image::wide", 0.1, 0.5, "#000000")
368                        .await?;
369                    d.sample_pixel("async_image::tall", 0.5, 0.1, "#000000")
370                        .await?;
371                    d.sample_pixel("async_image::rounded", 0.1, 0.5, color)
372                        .await?;
373                    d.shot(if color == "#00ff00" {
374                        "default"
375                    } else {
376                        "placeholder"
377                    })
378                    .await?;
379                    d.tap("async_image::clear").await?;
380                }
381                Ok(())
382            })
383    }
384
385    /// Resizing the same native view must move its circular clip, without rebuilding it.
386    #[day_macros::test(day_core)]
387    fn async_image_circle_follows_layout() -> Case {
388        Case::new()
389            .proves(day_spec::kinds::CANVAS)
390            .requires(Cap::Snapshot)
391            .page(|| {
392                let source = Signal::new(Some(Arc::new(GREEN.to_vec())));
393                let narrow = Signal::new(false);
394                // Keep the sampled view directly in the root row: sample_pixel uses the
395                // Day frame, which is relative to the nearest native parent.
396                row((
397                    async_image(source)
398                        .circle()
399                        .id(day_core::id!(async_image::image)),
400                    when(move || narrow.get(), || label("").frame(60.0, 60.0)),
401                    button("Resize")
402                        .action(move || narrow.set(!narrow.get()))
403                        .id(day_core::id!(async_image::resize))
404                        .frame(80.0, 60.0),
405                ))
406                .spacing(0.0)
407                .frame(260.0, 60.0)
408                .background(Color::hex(0x0000_0000))
409            })
410            .drive(|d: Drive| async move {
411                for width in [180.0, 120.0, 180.0] {
412                    d.assert_size("async_image::image", width, 60.0).await?;
413                    d.sample_pixel("async_image::image", 0.5, 0.5, "#00ff00")
414                        .await?;
415                    d.sample_pixel("async_image::image", 0.1, 0.5, "#000000")
416                        .await?;
417                    // A stale 180-wide clip would miss this point after shrinking to 120.
418                    d.sample_pixel("async_image::image", 0.4, 0.5, "#00ff00")
419                        .await?;
420                    d.tap("async_image::resize").await?;
421                }
422                Ok(())
423            })
424    }
425}