basalt-core 0.0.0-rc5 → 0.2.0

package/native/tests/test_image_animation.cpp

@@ -0,0 +1,105 @@
+// core/ImageAnimation.h: the clamp and the frame arithmetic.
+//
+// Both hosts animate from an elapsed time rather than from a clock of their
+// own, so this is where the awkward cases are asserted and each host's suite
+// then asks only whether the right pixels arrived.
+
+#include "TestHarness.h"
+
+#include "ImageAnimation.h"
+
+#include <sstream>
+#include <vector>
+
+namespace {
+
+const std::vector<unsigned> kTwoFrames{100U, 100U};
+
+} // namespace
+
+TEST(image_animation_a_single_frame_is_finished_before_it_starts) {
+  const auto step = basalt::imageAnimationStep({100U}, 0U, 0U);
+  EXPECT_EQ(step.frame, std::size_t(0));
+  EXPECT(step.finished);
+  EXPECT_EQ(step.nextInMs, 0U);
+
+  // And no frames at all, which is what a still image decodes to.
+  const auto none = basalt::imageAnimationStep({}, 0U, 500U);
+  EXPECT_EQ(none.frame, std::size_t(0));
+  EXPECT(none.finished);
+}
+
+TEST(image_animation_the_frame_follows_the_elapsed_time) {
+  const auto at = [](std::uint64_t elapsed) {
+    return basalt::imageAnimationStep(kTwoFrames, 0U, elapsed);
+  };
+
+  EXPECT_EQ(at(0U).frame, std::size_t(0));
+  EXPECT_EQ(at(99U).frame, std::size_t(0));
+  EXPECT_EQ(at(100U).frame, std::size_t(1));
+  EXPECT_EQ(at(199U).frame, std::size_t(1));
+  // A loop count of zero is forever, so the third hundred milliseconds is the
+  // first frame again.
+  EXPECT_EQ(at(200U).frame, std::size_t(0));
+  EXPECT(!at(200U).finished);
+}
+
+TEST(image_animation_says_when_the_next_frame_is_due) {
+  // What a host sets its timer to. The whole delay at the start of a frame, and
+  // what is left of it in the middle.
+  EXPECT_EQ(basalt::imageAnimationStep(kTwoFrames, 0U, 0U).nextInMs, 100U);
+  EXPECT_EQ(basalt::imageAnimationStep(kTwoFrames, 0U, 60U).nextInMs, 40U);
+  EXPECT_EQ(basalt::imageAnimationStep(kTwoFrames, 0U, 199U).nextInMs, 1U);
+}
+
+TEST(image_animation_frames_have_their_own_delays) {
+  // The common shape of a hand-drawn GIF: one long frame and several short
+  // ones. A single delay for the whole file would put the boundaries in the
+  // wrong places, which is invisible in a two-frame test where they are equal.
+  const std::vector<unsigned> uneven{500U, 50U, 50U};
+
+  const auto at = [&](std::uint64_t elapsed) {
+    return basalt::imageAnimationStep(uneven, 0U, elapsed).frame;
+  };
+  EXPECT_EQ(at(0U), std::size_t(0));
+  EXPECT_EQ(at(499U), std::size_t(0));
+  EXPECT_EQ(at(500U), std::size_t(1));
+  EXPECT_EQ(at(549U), std::size_t(1));
+  EXPECT_EQ(at(550U), std::size_t(2));
+  EXPECT_EQ(at(600U), std::size_t(0));
+}
+
+TEST(image_animation_a_delay_of_zero_becomes_a_tenth_of_a_second) {
+  // The browsers' rule, and the reason a GIF written with no delay at all does
+  // not spin at the display's refresh rate.
+  EXPECT_EQ(basalt::clampedImageFrameDelay(0U), 100U);
+  EXPECT_EQ(basalt::clampedImageFrameDelay(10U), 100U);
+  EXPECT_EQ(basalt::clampedImageFrameDelay(11U), 11U);
+  EXPECT_EQ(basalt::clampedImageFrameDelay(1000U), 1000U);
+
+  // And through the arithmetic, where it decides the boundary: without the
+  // clamp two zero-delay frames have no cycle to divide and the first frame
+  // would be the only one ever shown.
+  const std::vector<unsigned> instant{0U, 0U};
+  EXPECT_EQ(basalt::imageAnimationStep(instant, 0U, 0U).frame, std::size_t(0));
+  EXPECT_EQ(basalt::imageAnimationStep(instant, 0U, 100U).frame, std::size_t(1));
+  EXPECT_EQ(basalt::imageAnimationStep(instant, 0U, 100U).nextInMs, 100U);
+}
+
+TEST(image_animation_a_loop_count_stops_on_the_last_frame) {
+  const auto at = [](std::uint64_t elapsed) {
+    return basalt::imageAnimationStep(kTwoFrames, 2U, elapsed);
+  };
+
+  EXPECT_EQ(at(0U).frame, std::size_t(0));
+  EXPECT(!at(0U).finished);
+  // Second pass, still running.
+  EXPECT_EQ(at(300U).frame, std::size_t(1));
+  EXPECT(!at(300U).finished);
+  // Two passes of 200ms are over, so it stops, and on the frame the animation
+  // was drawn to end on rather than back at the first.
+  EXPECT_EQ(at(400U).frame, std::size_t(1));
+  EXPECT(at(400U).finished);
+  EXPECT_EQ(at(400U).nextInMs, 0U);
+  EXPECT(at(100000U).finished);
+}

package/native/tests/test_image_progress.cpp

@@ -0,0 +1,94 @@
+// Which image-fetch ticks become `<Image onProgress>` events.
+//
+// The wiring -- libcurl's callback, the fetch thread, the event emitter -- is
+// each host's and is proved end to end by the scenario that serves an image
+// slowly over http. What is tested here is the decision: see
+// core/ImageProgress.h.
+
+#include "TestHarness.h"
+
+#include "ImageProgress.h"
+
+#include <sstream>
+
+using basalt::ImageProgressTicker;
+
+TEST(image_progress_reports_each_whole_percent) {
+  ImageProgressTicker ticker;
+
+  const auto first = ticker.tick(0, 1000);
+  EXPECT(first.has_value());
+  EXPECT_EQ((long)(*first * 1000), 0L);
+
+  const auto tenth = ticker.tick(100, 1000);
+  EXPECT(tenth.has_value());
+  EXPECT_EQ((long)(*tenth * 1000), 100L);
+  EXPECT_EQ((long)ticker.reportedPercent(), 10L);
+
+  const auto whole = ticker.tick(1000, 1000);
+  EXPECT(whole.has_value());
+  EXPECT_EQ((long)(*whole * 1000), 1000L);
+  EXPECT_EQ((long)ticker.reportedPercent(), 100L);
+}
+
+// The whole reason the gate exists. libcurl calls its progress function once
+// per socket read, which for a large image is thousands of times; without this
+// each one would be a Fabric event and a React render.
+TEST(image_progress_says_nothing_twice) {
+  ImageProgressTicker ticker;
+
+  EXPECT(ticker.tick(500, 100000).has_value());
+  // Five more bytes of a hundred thousand is the same percentage, and a bar
+  // cannot draw the difference.
+  EXPECT(!ticker.tick(501, 100000).has_value());
+  EXPECT(!ticker.tick(502, 100000).has_value());
+  EXPECT(!ticker.tick(999, 100000).has_value());
+  // And the next percentage is.
+  EXPECT(ticker.tick(1000, 100000).has_value());
+}
+
+// A chunked response has no Content-Length, which is not an error: the event
+// carries the bytes and a zero total, and an app shows bytes rather than a
+// fraction. Every tick, because there is no percentage to throttle on.
+TEST(image_progress_an_unknown_total_reports_every_tick) {
+  ImageProgressTicker ticker;
+
+  const auto first = ticker.tick(1000, 0);
+  EXPECT(first.has_value());
+  EXPECT_EQ((long)(*first * 1000), 0L);
+  EXPECT(ticker.tick(1001, 0).has_value());
+  EXPECT(ticker.tick(1002, 0).has_value());
+}
+
+// libcurl's opening tick, before the response headers have been read. Nothing
+// has arrived and nothing is known, so there is nothing to tell an app.
+TEST(image_progress_the_opening_tick_is_not_an_event) {
+  ImageProgressTicker ticker;
+
+  EXPECT(!ticker.tick(0, 0).has_value());
+  EXPECT_EQ((long)ticker.reportedPercent(), -1L);
+  // And the first real tick still is one.
+  EXPECT(ticker.tick(0, 1000).has_value());
+}
+
+// A server that sends more than it promised. `progress` is what an app
+// multiplies its bar's width by, so it may not exceed one.
+TEST(image_progress_never_passes_one) {
+  ImageProgressTicker ticker;
+
+  const auto over = ticker.tick(2000, 1000);
+  EXPECT(over.has_value());
+  EXPECT_EQ((long)(*over * 1000), 1000L);
+  EXPECT_EQ((long)ticker.reportedPercent(), 100L);
+}
+
+// Negative counts, which libcurl has been seen to report for a transfer it has
+// not started: not an event's worth of information, and certainly not a
+// negative bar.
+TEST(image_progress_a_negative_count_is_zero) {
+  ImageProgressTicker ticker;
+
+  const auto negative = ticker.tick(-5, 1000);
+  EXPECT(negative.has_value());
+  EXPECT_EQ((long)(*negative * 1000), 0L);
+}

package/native/tests/test_label_registry.cpp

@@ -0,0 +1,262 @@
+// Resolving `accessibilityLabelledBy`, which is a lookup this project did not
+// have: a view names another by its `nativeID` and the registry is keyed by tag.
+//
+// What is asserted here is the ordering, because that is the whole difficulty.
+// Fabric mounts in tree order, so a field labelled by the text after it is
+// mounted before its label exists; a relation resolved once at mount time would
+// find nothing and stay wrong for the life of the screen. See core/LabelRegistry.h.
+
+#include "TestHarness.h"
+
+#include "LabelRegistry.h"
+
+#include <sstream>
+
+using basalt::LabelRegistry;
+
+namespace {
+
+// The resolution for one tag out of a batch of changes, and whether it was in
+// there at all.
+bool labelsFor(const std::vector<LabelRegistry::Resolved> &changes,
+               LabelRegistry::Tag tag,
+               std::vector<LabelRegistry::Tag> *out) {
+  for (const auto &change : changes) {
+    if (change.tag == tag) {
+      *out = change.labels;
+      return true;
+    }
+  }
+  return false;
+}
+
+} // namespace
+
+TEST(labels_resolve_an_id_to_the_view_that_has_it) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 1L);
+  EXPECT_EQ((long)labels[0], 20L);
+}
+
+// The case that makes this a registry rather than a lookup: the label mounts
+// second, which is what happens whenever the label comes after the field in the
+// tree.
+TEST(labels_a_relation_waits_for_an_id_that_has_not_arrived) {
+  LabelRegistry registry;
+  registry.setLabelledBy(10, {"name-label"});
+
+  std::vector<LabelRegistry::Tag> labels;
+  // Reported, and resolving to nothing: the host has a relation to reset rather
+  // than a reference to a view that does not exist.
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 0L);
+
+  registry.setNativeId(20, "name-label");
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 1L);
+  EXPECT_EQ((long)labels[0], 20L);
+}
+
+// Order is the app's. A field labelled by a heading and a hint is read in that
+// order, and sorting them would change what is said.
+TEST(labels_keep_the_order_the_app_wrote) {
+  LabelRegistry registry;
+  registry.setNativeId(30, "hint");
+  registry.setNativeId(20, "heading");
+  registry.setLabelledBy(10, {"heading", "hint"});
+
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 2L);
+  EXPECT_EQ((long)labels[0], 20L);
+  EXPECT_EQ((long)labels[1], 30L);
+}
+
+// Nothing is reported twice. Applying an unchanged relation again tells
+// assistive technology that something happened when nothing did.
+TEST(labels_an_unchanged_relation_is_not_reported_again) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  EXPECT_EQ((long)registry.changes().size(), 1L);
+  EXPECT_EQ((long)registry.changes().size(), 0L);
+
+  // Re-sending the same props, which every mutation does, changes nothing.
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  EXPECT_EQ((long)registry.changes().size(), 0L);
+}
+
+// A label that goes away leaves a dangling reference, and a screen reader
+// following it would read a view that is no longer on screen.
+TEST(labels_a_label_that_is_unmounted_empties_the_relation) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  registry.changes();
+
+  registry.forget(20);
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 0L);
+}
+
+// And a view that stops asking is reported once, so the host can reset the
+// relation, and then not again.
+TEST(labels_a_view_that_stops_asking_is_reported_once) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  registry.changes();
+
+  registry.setLabelledBy(10, {});
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 0L);
+  EXPECT_EQ((long)registry.changes().size(), 0L);
+}
+
+// A view cannot label itself, which an app can ask for by giving one view both
+// props. Honouring it would be a cycle for anything walking the relation.
+TEST(labels_a_view_does_not_label_itself) {
+  LabelRegistry registry;
+  registry.setNativeId(10, "mine");
+  registry.setLabelledBy(10, {"mine"});
+
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels.size(), 0L);
+}
+
+// An id taken over by another view follows the new one. Two views with the same
+// nativeID is an app bug; what matters is that the old one letting go does not
+// take the id with it.
+TEST(labels_an_id_that_moves_follows_the_view_that_has_it) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  registry.changes();
+
+  registry.setNativeId(30, "name-label");
+  std::vector<LabelRegistry::Tag> labels;
+  EXPECT(labelsFor(registry.changes(), 10, &labels));
+  EXPECT_EQ((long)labels[0], 30L);
+
+  // The view that used to own it goes away without disturbing the new owner.
+  registry.forget(20);
+  EXPECT_EQ((long)registry.changes().size(), 0L);
+}
+
+// A view with no relation costs nothing, which is what `empty()` is for: the
+// hosts ask it before doing any work per transaction.
+TEST(labels_a_registry_with_no_relations_is_empty) {
+  LabelRegistry registry;
+  EXPECT(registry.empty());
+  registry.setNativeId(20, "name-label");
+  EXPECT(registry.empty());
+  registry.setLabelledBy(10, {"name-label"});
+  EXPECT(!registry.empty());
+}
+
+// But not while a relation it applied is still on a widget, which is the half
+// that is easy to get wrong: a host checking `empty()` first would skip the one
+// transaction that had to take the relation off, and it would stay there for the
+// rest of the screen's life. Caught by writing the host side, not by this test.
+TEST(labels_a_registry_is_not_empty_while_a_relation_is_still_applied) {
+  LabelRegistry registry;
+  registry.setNativeId(20, "name-label");
+  registry.setLabelledBy(10, {"name-label"});
+  registry.changes();
+
+  registry.setLabelledBy(10, {});
+  EXPECT(!registry.empty());
+  // Reported once, so the host can reset it, and then it really is empty.
+  EXPECT_EQ((long)registry.changes().size(), 1L);
+  EXPECT(registry.empty());
+}
+
+// `experimental_accessibilityOrder`: the second relation, which shares the
+// `nativeID` index with the first. See core/LabelRegistry.h.
+TEST(label_registry_an_order_resolves_in_the_order_it_was_given) {
+  basalt::LabelRegistry registry;
+  registry.setNativeId(1, "first");
+  registry.setNativeId(2, "second");
+  registry.setNativeId(3, "third");
+  // Deliberately not the mount order: the point of the prop is to override it.
+  registry.setAccessibilityOrder(10, {"third", "first", "second"});
+
+  const auto changes = registry.orderChanges();
+  EXPECT_EQ(changes.size(), std::size_t{1});
+  if (changes.size() == 1) {
+    EXPECT_EQ(changes[0].tag, 10);
+    EXPECT_EQ(changes[0].labels.size(), std::size_t{3});
+    EXPECT_EQ(changes[0].labels[0], 3);
+    EXPECT_EQ(changes[0].labels[1], 1);
+    EXPECT_EQ(changes[0].labels[2], 2);
+  }
+
+  // Reported once: applying an unchanged order again would tell assistive
+  // technology that something happened when nothing did.
+  EXPECT(registry.orderChanges().empty());
+}
+
+// An id that names nothing yet is dropped rather than losing the whole order,
+// and is taken up when it arrives.
+TEST(label_registry_an_order_takes_the_children_it_has) {
+  basalt::LabelRegistry registry;
+  registry.setNativeId(1, "first");
+  registry.setAccessibilityOrder(10, {"first", "later"});
+
+  auto changes = registry.orderChanges();
+  EXPECT_EQ(changes.size(), std::size_t{1});
+  EXPECT(changes.size() == 1 && changes[0].labels.size() == std::size_t{1});
+
+  registry.setNativeId(2, "later");
+  changes = registry.orderChanges();
+  EXPECT_EQ(changes.size(), std::size_t{1});
+  if (changes.size() == 1) {
+    EXPECT_EQ(changes[0].labels.size(), std::size_t{2});
+    EXPECT_EQ(changes[0].labels[1], 2);
+  }
+}
+
+// The two relations do not interfere: the same view can be labelled by one
+// thing and order another, and each is reported on its own.
+TEST(label_registry_the_two_relations_are_independent) {
+  basalt::LabelRegistry registry;
+  registry.setNativeId(1, "label");
+  registry.setNativeId(2, "child");
+  registry.setLabelledBy(10, {"label"});
+  registry.setAccessibilityOrder(10, {"child"});
+
+  const auto labels = registry.changes();
+  EXPECT_EQ(labels.size(), std::size_t{1});
+  EXPECT(labels.size() == 1 && labels[0].labels.size() == std::size_t{1}
+         && labels[0].labels[0] == 1);
+  // Asking for one does not consume the other.
+  const auto order = registry.orderChanges();
+  EXPECT_EQ(order.size(), std::size_t{1});
+  EXPECT(order.size() == 1 && order[0].labels.size() == std::size_t{1}
+         && order[0].labels[0] == 2);
+}
+
+// A view that stops asking is reported empty once, which is a host's cue to
+// take the relation off the widget, and then forgotten.
+TEST(label_registry_an_order_that_goes_away_is_reported_empty) {
+  basalt::LabelRegistry registry;
+  registry.setNativeId(1, "child");
+  registry.setAccessibilityOrder(10, {"child"});
+  EXPECT_EQ(registry.orderChanges().size(), std::size_t{1});
+
+  registry.setAccessibilityOrder(10, {});
+  const auto changes = registry.orderChanges();
+  EXPECT_EQ(changes.size(), std::size_t{1});
+  EXPECT(changes.size() == 1 && changes[0].labels.empty());
+  EXPECT(registry.orderChanges().empty());
+  EXPECT(registry.empty());
+}

package/native/tests/test_legacy_shadow.cpp

@@ -0,0 +1,165 @@
+// The iOS shadow props as a CSS box shadow. See core/LegacyShadow.h.
+//
+// Four props that every pre-`boxShadow` React Native component sets, and which
+// no host here read. The conversion is shared because the alternative is each
+// host doubling a blur radius on its own, which is exactly the kind of arithmetic
+// that comes out half as big on one platform and nobody notices for a year.
+
+#include "TestHarness.h"
+
+#include "LegacyShadow.h"
+
+#include <sstream>
+
+using facebook::react::BaseViewProps;
+using facebook::react::BoxShadow;
+using facebook::react::ColorComponents;
+
+namespace {
+
+// Props as React Native hands them over, with nothing set but the shadow: the
+// defaults for `shadowOffset` and `shadowRadius` are React Native's own, which
+// is what makes "set only a colour and an opacity" a case worth testing.
+//
+// A struct holding the props rather than a function returning them, which is
+// not a style choice: React Native 0.86's `BaseViewProps` has an implicitly
+// deleted copy constructor, so a helper that returns one by value does not
+// compile there at all. 0.87's is copyable, which is why this went unnoticed
+// until a build against the version Expo installs. Taking `.props` off a
+// temporary is a reference into it and lives as long as the full expression.
+struct Shadowed {
+  BaseViewProps props;
+
+  Shadowed(float red, float green, float blue, float alpha, double opacity) {
+    props.shadowColor =
+        facebook::react::colorFromComponents(ColorComponents{red, green, blue, alpha});
+    props.shadowOpacity = opacity;
+  }
+};
+
+ColorComponents componentsOf(const BoxShadow &shadow) {
+  return facebook::react::colorComponentsFromColor(shadow.color);
+}
+
+} // namespace
+
+TEST(legacy_shadow_defaults_are_the_shadow_ios_would_draw) {
+  Shadowed shadowed(0.0F, 0.0F, 0.0F, 1.0F, 0.5);
+  BaseViewProps &props = shadowed.props;
+  const std::optional<BoxShadow> shadow = basalt::legacyShadow(props);
+  EXPECT(shadow.has_value());
+  if (!shadow.has_value()) {
+    return;
+  }
+
+  // React Native's own defaults: offset (0, -3), radius 3.
+  EXPECT_NEAR(shadow->offsetX, 0.0, 0.001);
+  EXPECT_NEAR(shadow->offsetY, -3.0, 0.001);
+  // Doubled, a CALayer radius being a standard deviation where CSS's is twice
+  // one. A conversion that forgot this draws a shadow half as soft, which is
+  // the sort of wrong that looks fine on its own and wrong beside the other
+  // host.
+  EXPECT_NEAR(shadow->blurRadius, 6.0, 0.001);
+  // No spread, and not inset: the legacy props cannot ask for either.
+  EXPECT_NEAR(shadow->spreadDistance, 0.0, 0.001);
+  EXPECT(!shadow->inset);
+}
+
+// `shadowOpacity` multiplies the colour's alpha, which is what
+// `CALayer.shadowOpacity` does on top of `shadowColor`. Both halves matter: an
+// opacity ignored gives a shadow twice as dark, and a colour alpha ignored gives
+// one that cannot be made translucent by its colour.
+TEST(legacy_shadow_opacity_multiplies_the_colours_alpha) {
+  const std::optional<BoxShadow> half =
+      basalt::legacyShadow(Shadowed(0.0F, 0.0F, 0.0F, 1.0F, 0.5).props);
+  EXPECT(half.has_value());
+  EXPECT_NEAR(componentsOf(*half).alpha, 0.5, 0.01);
+
+  const std::optional<BoxShadow> quarter =
+      basalt::legacyShadow(Shadowed(0.0F, 0.0F, 0.0F, 0.5F, 0.5).props);
+  EXPECT(quarter.has_value());
+  EXPECT_NEAR(componentsOf(*quarter).alpha, 0.25, 0.01);
+
+  // And the colour itself is the colour, which an alpha multiply can trample if
+  // it is applied to the wrong component.
+  const std::optional<BoxShadow> red =
+      basalt::legacyShadow(Shadowed(1.0F, 0.0F, 0.0F, 1.0F, 1.0).props);
+  EXPECT(red.has_value());
+  EXPECT_NEAR(componentsOf(*red).red, 1.0, 0.01);
+  EXPECT_NEAR(componentsOf(*red).green, 0.0, 0.01);
+  EXPECT_NEAR(componentsOf(*red).alpha, 1.0, 0.01);
+}
+
+// An opacity over one is a value React Native will pass straight through, and
+// a colour cannot hold an alpha above one.
+TEST(legacy_shadow_a_large_opacity_is_clamped) {
+  const std::optional<BoxShadow> shadow =
+      basalt::legacyShadow(Shadowed(0.0F, 0.0F, 0.0F, 1.0F, 4.0).props);
+  EXPECT(shadow.has_value());
+  EXPECT_NEAR(componentsOf(*shadow).alpha, 1.0, 0.01);
+}
+
+// The gates, which are what keeps every view in every app from gaining a shadow:
+// `shadowOpacity` defaults to zero and `shadowColor` to nothing.
+TEST(legacy_shadow_nothing_is_asked_for_by_default) {
+  const BaseViewProps plain;
+  EXPECT(!basalt::legacyShadow(plain).has_value());
+  EXPECT(basalt::allShadows(plain).empty());
+
+  // A colour with no opacity, which is the default for every styled view that
+  // sets `shadowColor` and forgets the rest.
+  EXPECT(!basalt::legacyShadow(Shadowed(0.0F, 0.0F, 0.0F, 1.0F, 0.0).props).has_value());
+  // An opacity with no colour.
+  BaseViewProps colourless;
+  colourless.shadowOpacity = 0.5;
+  EXPECT(!basalt::legacyShadow(colourless).has_value());
+  // And a transparent colour, which is a colour React Native did parse.
+  EXPECT(!basalt::legacyShadow(Shadowed(0.0F, 0.0F, 0.0F, 0.0F, 0.5).props).has_value());
+}
+
+// Both mechanisms at once, which iOS allows: the layer's own shadow and the
+// extra layers `boxShadow` gets. The legacy one goes last, which is the back of
+// the list, so adding a `boxShadow` to an old component cannot be hidden behind
+// the shadow it already had.
+TEST(legacy_shadow_goes_behind_the_css_shadows) {
+  Shadowed shadowed(0.0F, 0.0F, 0.0F, 1.0F, 0.5);
+  BaseViewProps &props = shadowed.props;
+  BoxShadow css;
+  css.offsetX = 1;
+  css.offsetY = 2;
+  css.blurRadius = 4;
+  css.color = facebook::react::colorFromComponents(ColorComponents{1.0F, 0.0F, 0.0F, 1.0F});
+  props.boxShadow = {css};
+
+  const std::vector<BoxShadow> all = basalt::allShadows(props);
+  EXPECT_EQ((int)all.size(), 2);
+  if (all.size() != 2) {
+    return;
+  }
+  // The CSS one first, as the app wrote it.
+  EXPECT_NEAR(all[0].offsetX, 1.0, 0.001);
+  EXPECT_NEAR(componentsOf(all[0]).red, 1.0, 0.01);
+  // The legacy one behind it, converted.
+  EXPECT_NEAR(all[1].offsetY, -3.0, 0.001);
+  EXPECT_NEAR(all[1].blurRadius, 6.0, 0.001);
+}
+
+// And a `boxShadow` on its own is untouched, which is the case that was already
+// working and must stay that way: nothing is appended, nothing is reordered.
+TEST(legacy_shadow_leaves_a_css_only_view_alone) {
+  BaseViewProps props;
+  BoxShadow css;
+  css.offsetY = 4;
+  css.blurRadius = 8;
+  css.inset = true;
+  css.color = facebook::react::colorFromComponents(ColorComponents{0.0F, 0.0F, 0.0F, 0.25F});
+  props.boxShadow = {css};
+
+  const std::vector<BoxShadow> all = basalt::allShadows(props);
+  EXPECT_EQ((int)all.size(), 1);
+  if (all.empty()) {
+    return;
+  }
+  EXPECT(all[0].inset);
+  EXPECT_NEAR(all[0].blurRadius, 8.0, 0.001);
+}