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