basalt-core 0.0.0-rc5 → 0.2.0

package/native/tests/test_live_regions.cpp

@@ -0,0 +1,108 @@
+// Noticing that a status message changed, which is what
+// `accessibilityLiveRegion` asks for.
+//
+// The prop is not a property of a view on either desktop -- GTK announces at a
+// moment, AppKit posts a notification -- so honouring it is change detection,
+// and the two rules that make it bearable rather than deafening are asserted
+// here. See core/LiveRegions.h.
+
+#include "TestHarness.h"
+
+#include "LiveRegions.h"
+
+#include <sstream>
+
+using basalt::LiveRegionPoliteness;
+using basalt::LiveRegionRegistry;
+
+// Mounting a status line is not news: nothing changed, the screen appeared. A
+// host that announced here would have every screen with a status message read
+// itself out on arrival.
+TEST(live_regions_the_first_text_is_not_announced) {
+  LiveRegionRegistry registry;
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+
+  EXPECT(!registry.noticed(10, "Saved").has_value());
+}
+
+TEST(live_regions_a_change_is_announced_with_the_politeness_asked_for) {
+  LiveRegionRegistry registry;
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  registry.noticed(10, "Saving");
+
+  const auto polite = registry.noticed(10, "Saved");
+  EXPECT(polite.has_value());
+  EXPECT(polite.value() == LiveRegionPoliteness::Polite);
+
+  registry.setPoliteness(11, LiveRegionPoliteness::Assertive);
+  registry.noticed(11, "");
+  const auto assertive = registry.noticed(11, "Offline");
+  EXPECT(assertive.has_value());
+  EXPECT(assertive.value() == LiveRegionPoliteness::Assertive);
+}
+
+// A view re-renders for every reason under the sun, and React Native re-sends
+// identical props on each mutation. A region that announced every time would
+// talk over the rest of the application.
+TEST(live_regions_the_same_text_twice_is_not_announced) {
+  LiveRegionRegistry registry;
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  registry.noticed(10, "Saving");
+  EXPECT(registry.noticed(10, "Saved").has_value());
+
+  EXPECT(!registry.noticed(10, "Saved").has_value());
+  EXPECT(!registry.noticed(10, "Saved").has_value());
+  // And a change after that is news again.
+  EXPECT(registry.noticed(10, "Saved just now").has_value());
+}
+
+// A region that cleared itself has nothing to read out. Announcing an empty
+// string is silence with a beat of interruption in front of it.
+TEST(live_regions_clearing_the_text_announces_nothing) {
+  LiveRegionRegistry registry;
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  registry.noticed(10, "Saved");
+  EXPECT(!registry.noticed(10, "").has_value());
+  // But the clearing was remembered, so the text coming back is a change.
+  EXPECT(registry.noticed(10, "Saved").has_value());
+}
+
+// A view that is not a live region never announces, whatever its text does.
+TEST(live_regions_a_view_without_the_prop_is_silent) {
+  LiveRegionRegistry registry;
+  EXPECT(!registry.noticed(10, "Saving").has_value());
+  EXPECT(!registry.noticed(10, "Saved").has_value());
+
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  registry.setPoliteness(10, LiveRegionPoliteness::None);
+  EXPECT(!registry.noticed(10, "Saved again").has_value());
+}
+
+// A region that is unmounted and comes back is new again, rather than compared
+// against the text of a screen that is no longer there.
+TEST(live_regions_a_region_that_goes_away_forgets_what_it_said) {
+  LiveRegionRegistry registry;
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  registry.noticed(10, "Saved");
+
+  registry.forget(10);
+  registry.setPoliteness(10, LiveRegionPoliteness::Polite);
+  EXPECT(!registry.noticed(10, "Offline").has_value());
+  EXPECT(registry.noticed(10, "Saved").has_value());
+}
+
+// The hosts ask `empty()` before doing any work per transaction, collecting a
+// region's text being a walk of its subtree.
+TEST(live_regions_a_registry_with_no_regions_is_empty) {
+  LiveRegionRegistry registry;
+  EXPECT(registry.empty());
+  EXPECT_EQ((long)registry.tags().size(), 0L);
+
+  registry.setPoliteness(10, LiveRegionPoliteness::Assertive);
+  EXPECT(!registry.empty());
+  EXPECT_EQ((long)registry.tags().size(), 1L);
+  EXPECT_EQ((long)registry.tags()[0], 10L);
+
+  registry.setPoliteness(10, LiveRegionPoliteness::None);
+  EXPECT(registry.empty());
+}

package/native/tests/test_menu_entries.cpp

@@ -0,0 +1,192 @@
+// The portable half of a popup menu: how its entries are numbered, which of them
+// are drawn, and where a radio group begins and ends.
+//
+// This is where a popup menu's real bugs have been, and none of them were in the
+// drawing. An index is an entry's position in a pre-order walk of the whole menu,
+// and both sides of a JSI boundary have to agree on it: the hosts tag their items
+// with it and `itemAt` in useContextMenu.ts walks the tree the app passed. The
+// first attempt at roles filtered unsupported ones out of the vector, which would
+// have had the two sides numbering different lists, and on Linux every item after
+// an `about` would have run the handler of the one before it.
+//
+// The drawing is not here and is not asserted anywhere: `presentMenu` answers
+// BASALT_TEST_MENU before `showMenu` is reached, so an automated run never builds
+// a native menu at all. See docs/backlog/desktop-capabilities.md.
+
+#include "TestHarness.h"
+
+#include "PlatformServices.h"
+#include "TestDialog.h"
+
+#include <sstream>
+#include <string>
+#include <vector>
+
+namespace {
+
+using basalt::MenuEntry;
+
+MenuEntry item(std::string label) {
+  MenuEntry entry;
+  entry.label = std::move(label);
+  return entry;
+}
+
+MenuEntry radio(std::string label, bool checked) {
+  MenuEntry entry = item(std::move(label));
+  entry.mark = MenuEntry::Mark::Radio;
+  entry.checked = checked;
+  return entry;
+}
+
+MenuEntry check(std::string label, bool checked) {
+  MenuEntry entry = item(std::move(label));
+  entry.mark = MenuEntry::Mark::Check;
+  entry.checked = checked;
+  return entry;
+}
+
+MenuEntry parent(std::string label, std::vector<MenuEntry> children) {
+  MenuEntry entry = item(std::move(label));
+  entry.submenu = std::move(children);
+  return entry;
+}
+
+} // namespace
+
+TEST(menu_indexes_are_preorder_and_count_separators_and_parents) {
+  // A flat list is numbered by position, which is what an index meant before a
+  // popup could nest, so no caller's meaning changed when nesting arrived.
+  const std::vector<MenuEntry> flat = {item("a"), MenuEntry::separator(), item("b")};
+  EXPECT_EQ(basalt::menuEntryCount(flat), 3);
+  EXPECT_EQ(basalt::menuEntryAt(flat, 0)->label, std::string("a"));
+  EXPECT(basalt::menuEntryAt(flat, 1)->isSeparator());
+  EXPECT_EQ(basalt::menuEntryAt(flat, 2)->label, std::string("b"));
+
+  // Nested: the parent, then its children, then what follows it.
+  const std::vector<MenuEntry> nested = {
+      item("first"),
+      parent("branch", {item("leaf one"), item("leaf two")}),
+      item("last"),
+  };
+  EXPECT_EQ(basalt::menuEntryCount(nested), 5);
+  EXPECT_EQ(basalt::menuEntryAt(nested, 0)->label, std::string("first"));
+  EXPECT_EQ(basalt::menuEntryAt(nested, 1)->label, std::string("branch"));
+  EXPECT_EQ(basalt::menuEntryAt(nested, 2)->label, std::string("leaf one"));
+  EXPECT_EQ(basalt::menuEntryAt(nested, 3)->label, std::string("leaf two"));
+  // The one that matters: a parent's children do not push what follows it off by
+  // their own count, they are counted where they are.
+  EXPECT_EQ(basalt::menuEntryAt(nested, 4)->label, std::string("last"));
+  EXPECT(basalt::menuEntryAt(nested, 5) == nullptr);
+}
+
+TEST(menu_entries_the_platform_drops_still_count) {
+  // A role this desktop cannot perform is not drawn. It keeps its index anyway,
+  // because the index is into the list JavaScript passed: numbering only what was
+  // drawn would move every entry after it onto the wrong handler.
+  MenuEntry unsupported = item("about");
+  unsupported.role = "not-a-role-any-platform-has";
+  const std::vector<MenuEntry> entries = {item("before"), unsupported, item("after")};
+
+  EXPECT(!basalt::menuEntryShown(entries[1]));
+  EXPECT(basalt::menuEntryShown(entries[0]));
+  EXPECT_EQ(basalt::menuEntryCount(entries), 3);
+  EXPECT_EQ(basalt::menuEntryAt(entries, 2)->label, std::string("after"));
+}
+
+TEST(a_parent_with_nothing_drawable_under_it_is_not_drawn) {
+  MenuEntry unsupported = item("about");
+  unsupported.role = "not-a-role-any-platform-has";
+  const MenuEntry empty = parent("branch", {unsupported});
+  EXPECT(!basalt::menuEntryShown(empty));
+
+  // One drawable child is enough to keep the parent.
+  MenuEntry another = item("about");
+  another.role = "not-a-role-any-platform-has";
+  const MenuEntry mixed = parent("branch", {another, item("real")});
+  EXPECT(basalt::menuEntryShown(mixed));
+}
+
+TEST(a_radio_run_is_the_adjacent_radio_siblings) {
+  // Ended by a non-radio entry, by a separator, and by the end of the level.
+  const std::vector<MenuEntry> entries = {
+      item("plain"),            // 0
+      radio("one", true),       // 1
+      radio("two", false),      // 2
+      MenuEntry::separator(),   // 3
+      radio("three", false),    // 4
+      radio("four", false),     // 5
+  };
+
+  // The first run is 1..3, stopping at the separator rather than running on.
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 1).first, 1);
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 1).second, 3);
+  // Asking about any member gives the same run, which is what lets every member
+  // of a group share one action named after where the run starts.
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 2).first, 1);
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 2).second, 3);
+  // The second run is 4..6, ended by the end of the level.
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 4).first, 4);
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 4).second, 6);
+  // A non-radio entry is its own degenerate run, so a caller need not special-case.
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 0).first, 0);
+  EXPECT_EQ(basalt::menuRadioRun(entries, 0, 0).second, 0);
+}
+
+TEST(a_radio_run_is_offset_by_the_level_it_is_on) {
+  // Inside a submenu the indexes are the pre-order ones, not positions in the
+  // sibling vector, which is what `firstIndexOfLevel` carries. A run named after
+  // a sibling position would collide between levels.
+  const std::vector<MenuEntry> children = {radio("a", false), radio("b", true)};
+  EXPECT_EQ(basalt::menuRadioRun(children, 7, 0).first, 7);
+  EXPECT_EQ(basalt::menuRadioRun(children, 7, 0).second, 9);
+  EXPECT_EQ(basalt::menuRadioRun(children, 7, 1).first, 7);
+}
+
+TEST(a_mark_does_not_change_whether_an_entry_is_drawn_or_counted) {
+  // A checked item is an ordinary choosable leaf. All three desktops can draw a
+  // mark, so nothing here is dropped for carrying one, and the index contract is
+  // untouched by it.
+  const std::vector<MenuEntry> entries = {check("ticked", true), radio("chosen", true),
+                                          check("unticked", false)};
+  for (const MenuEntry &entry : entries) {
+    EXPECT(basalt::menuEntryShown(entry));
+    EXPECT(!entry.isSeparator());
+    EXPECT(!entry.isParent());
+  }
+  EXPECT_EQ(basalt::menuEntryCount(entries), 3);
+}
+
+// --- What a script may answer ------------------------------------------------
+//
+// `BASALT_TEST_MENU` skips the presentation and nothing else, so the index it
+// names has to be one a person could have clicked. Four things are not: an
+// index past the end of the tree, a separator, a submenu's parent, and an entry
+// that is drawn greyed. The last was missing until an action sheet put its title
+// into the menu as a disabled entry; see core/ActionSheet.h.
+
+TEST(a_script_may_only_answer_what_a_person_could_have_clicked) {
+  const std::vector<MenuEntry> entries = {item("first"), MenuEntry::separator(),
+                                          parent("more", {item("nested")}), item("last")};
+
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 0), 0);
+  // The separator, which is a line.
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 1), -1);
+  // The parent, which opens rather than chooses -- and its child, which is a
+  // real choice at index 3 of the pre-order walk.
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 2), -1);
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 3), 3);
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 4), 4);
+  // Past the end, and a dismissal, which is already one.
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 5), -1);
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, -1), -1);
+}
+
+TEST(a_script_cannot_choose_a_disabled_entry) {
+  MenuEntry greyed = item("not now");
+  greyed.enabled = false;
+  const std::vector<MenuEntry> entries = {greyed, item("go")};
+
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 0), -1);
+  EXPECT_EQ(basalt::scriptedMenuIndex(entries, 1), 1);
+}

package/native/tests/test_momentum.cpp

@@ -136,3 +136,48 @@ TEST(momentum_a_deceleration_rate_of_one_would_never_stop) {
   EXPECT(flight.frames < 6000);
   EXPECT(!momentum.isRunning());
 }
+
+// The projection, which is the same model asked where it would end up rather
+// than stepped there.
+//
+// It exists for `core/ScrollSnap.h`: a snapping list has to know where momentum
+// would have carried it before it can choose a point. So the test that matters
+// is that the closed form and the animation agree -- an integral that drifted
+// from the frames would make a list settle somewhere it was never heading.
+TEST(momentum_the_projection_agrees_with_the_frames) {
+  ScrollMomentum momentum;
+  EXPECT(momentum.start(0, 1200, ScrollMomentum::kNormalDeceleration));
+  const Flight flight = flyY(momentum);
+
+  const double projected =
+      basalt::scrollMomentumDistance(1200, ScrollMomentum::kNormalDeceleration);
+  EXPECT(projected > 0);
+  // Within a few per cent. The stepped version is deliberately the cruder of
+  // the two -- it moves at the velocity each frame *started* with, which
+  // overshoots slightly -- and ScrollMomentum.cpp says so where it does it.
+  EXPECT(projected > flight.distanceY * 0.9);
+  EXPECT(projected < flight.distanceY * 1.1);
+}
+
+TEST(momentum_the_projection_keeps_the_sign_and_scales_with_the_throw) {
+  const double gentle = basalt::scrollMomentumDistance(400, ScrollMomentum::kNormalDeceleration);
+  const double hard = basalt::scrollMomentumDistance(2000, ScrollMomentum::kNormalDeceleration);
+  EXPECT(gentle > 0);
+  EXPECT(hard > gentle * 2);
+
+  // Backwards travels backwards, which is the sign convention everything else
+  // here uses: positive velocity grows the content offset.
+  EXPECT_NEAR(basalt::scrollMomentumDistance(-2000, ScrollMomentum::kNormalDeceleration),
+              -hard,
+              0.0001);
+
+  // A faster rate stops sooner, the same way the stepped model does.
+  EXPECT(basalt::scrollMomentumDistance(2000, ScrollMomentum::kFastDeceleration) < hard);
+}
+
+TEST(momentum_a_release_is_projected_nowhere) {
+  // The same threshold `start` refuses at: below it there is no fling, so there
+  // is nothing to project and a snapping list should settle where it is.
+  EXPECT_NEAR(basalt::scrollMomentumDistance(10, ScrollMomentum::kNormalDeceleration), 0.0, 0.0001);
+  EXPECT_NEAR(basalt::scrollMomentumDistance(0, ScrollMomentum::kNormalDeceleration), 0.0, 0.0001);
+}

package/native/tests/test_scroll_bounds.cpp

@@ -64,3 +64,45 @@ TEST(bounds_both_insets_extend_both_ends) {
   EXPECT_NEAR(range.maximum, 330.0, 0.001);
   EXPECT_NEAR(range.length(), 350.0, 0.001);
 }
+
+// --- centerContent -----------------------------------------------------------
+//
+// An inset rather than a position, because the range above is already the thing
+// that decides where content rests: half the slack at each end leaves exactly
+// one offset to be at, and the clamp every host runs on every mutation puts the
+// content there. iOS reaches it the same way, assigning a `contentInset`.
+
+TEST(bounds_centering_insets_are_half_the_slack_at_each_end) {
+  const basalt::ScrollAxisInsets insets = basalt::centeringInsets(300, 200);
+  EXPECT_NEAR(insets.leading, 50.0, 0.0001);
+  EXPECT_NEAR(insets.trailing, 50.0, 0.0001);
+}
+
+TEST(bounds_centering_leaves_one_offset_to_rest_at) {
+  // The whole point: a range of no length, in the middle. So a view that was at
+  // zero is pulled to -50, which draws the content half the slack further down.
+  const basalt::ScrollRange range =
+      basalt::scrollRangeFor(300, 200, basalt::centeringInsets(300, 200));
+  EXPECT_NEAR(range.minimum, -50.0, 0.0001);
+  EXPECT_NEAR(range.maximum, -50.0, 0.0001);
+  EXPECT_NEAR(basalt::clampScrollOffset(0, 300, 200, basalt::centeringInsets(300, 200)),
+              -50.0,
+              0.0001);
+}
+
+TEST(bounds_centering_does_nothing_to_content_that_can_scroll) {
+  // Content longer than its container has no slack to share out, and an inset
+  // here would be a list that could be pulled past its own first row.
+  const basalt::ScrollAxisInsets insets = basalt::centeringInsets(300, 4000);
+  EXPECT_NEAR(insets.leading, 0.0, 0.0001);
+  EXPECT_NEAR(insets.trailing, 0.0, 0.0001);
+  EXPECT_NEAR(basalt::clampScrollOffset(0, 300, 4000, insets), 0.0, 0.0001);
+}
+
+TEST(bounds_centering_content_exactly_the_container_is_not_centred) {
+  // The boundary, and the one that would divide by nothing useful: there is no
+  // slack, so there is no inset and the view rests at zero.
+  const basalt::ScrollAxisInsets insets = basalt::centeringInsets(300, 300);
+  EXPECT_NEAR(insets.leading, 0.0, 0.0001);
+  EXPECT_NEAR(insets.trailing, 0.0, 0.0001);
+}

package/native/tests/test_scroll_indicator.cpp

@@ -147,3 +147,64 @@ TEST(indicator_content_that_fits_but_can_be_pulled_still_has_a_bar) {
       basalt::scrollIndicatorFor(100.0, 100.0, 0.0, basalt::ScrollAxisInsets{50.0, 0.0});
   EXPECT(indicator.visible);
 }
+
+// --- indicatorStyle ----------------------------------------------------------
+//
+// The colour the thumb is drawn in, decided here so that the three hosts cannot
+// answer the same prop differently -- each one used to spell its own black.
+
+TEST(indicator_white_is_white) {
+  const basalt::ScrollIndicatorColour white =
+      basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::White);
+  EXPECT_NEAR(white.red, 1.0, 0.0001);
+  EXPECT_NEAR(white.green, 1.0, 0.0001);
+  EXPECT_NEAR(white.blue, 1.0, 0.0001);
+}
+
+TEST(indicator_the_default_is_black) {
+  const basalt::ScrollIndicatorColour black =
+      basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::Default);
+  EXPECT_NEAR(black.red, 0.0, 0.0001);
+  EXPECT_NEAR(black.green, 0.0, 0.0001);
+  EXPECT_NEAR(black.blue, 0.0, 0.0001);
+}
+
+TEST(indicator_default_and_black_share_a_fill_and_differ_by_a_border) {
+  // Which is exactly how iOS's two differ:
+  // `UIScrollViewIndicatorStyleDefault` is "black with a white border" and
+  // `.black` is black alone. The fill being the same is half the claim and
+  // used to be the whole of it, back when neither drew a border.
+  const basalt::ScrollIndicatorColour fallback =
+      basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::Default);
+  const basalt::ScrollIndicatorColour black =
+      basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::Black);
+  EXPECT_NEAR(fallback.red, black.red, 0.0001);
+  EXPECT_NEAR(fallback.alpha, black.alpha, 0.0001);
+
+  // And the border is the other half: white, and on `default` alone.
+  const basalt::ScrollIndicatorColour border =
+      basalt::scrollIndicatorBorderColourFor(basalt::ScrollIndicatorStyle::Default);
+  EXPECT_NEAR(border.red, 1.0, 0.0001);
+  EXPECT_NEAR(border.green, 1.0, 0.0001);
+  EXPECT_NEAR(border.blue, 1.0, 0.0001);
+  EXPECT(border.alpha > basalt::kScrollIndicatorAlpha);
+
+  // The two styles an app picks because it knows what is behind the thumb have
+  // none: iOS draws neither with an outline, and adding one would be this
+  // platform inventing a look.
+  EXPECT_NEAR(basalt::scrollIndicatorBorderColourFor(basalt::ScrollIndicatorStyle::Black).alpha,
+              0.0, 0.0001);
+  EXPECT_NEAR(basalt::scrollIndicatorBorderColourFor(basalt::ScrollIndicatorStyle::White).alpha,
+              0.0, 0.0001);
+}
+
+TEST(indicator_both_colours_are_equally_translucent) {
+  // A white thumb more opaque than the black one would read as a different
+  // control rather than the same one in another colour.
+  EXPECT_NEAR(basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::White).alpha,
+              basalt::kScrollIndicatorAlpha,
+              0.0001);
+  EXPECT_NEAR(basalt::scrollIndicatorColourFor(basalt::ScrollIndicatorStyle::Black).alpha,
+              basalt::kScrollIndicatorAlpha,
+              0.0001);
+}

package/native/tests/test_scroll_snap.cpp

@@ -101,6 +101,100 @@ TEST(snap_centre_alignment_lines_up_the_middle) {
   EXPECT_EQ(snapped(config, 210, 0), 200.0);
 }
 
+// --- disableIntervalMomentum, and the momentum it disables -----------------
+//
+// A spacing is not a page: upstream lets the fling carry across several points
+// and settles at the one it arrives near, which is what `snapToInterval` means
+// on iOS. The prop asks for the paged behaviour instead.
+//
+// The projection is `core/ScrollMomentum.h`'s, so these numbers are the
+// friction model's rather than a target: 2000px/s at the normal rate is about
+// 984 pixels, which puts the next 250-point boundary at 1000.
+
+TEST(snap_a_flick_carries_as_far_as_it_was_thrown) {
+  ScrollSnapConfig config;
+  config.interval = 250;
+  EXPECT_EQ(snapped(config, 0, 2000), 1000.0);
+  // And a gentler one carries less, which is the rule the header states and
+  // the reason the projection is velocity-dependent rather than a page.
+  EXPECT_EQ(snapped(config, 0, 400), 250.0);
+}
+
+TEST(snap_momentum_across_an_interval_can_be_disabled) {
+  ScrollSnapConfig config;
+  config.interval = 250;
+  config.disableIntervalMomentum = true;
+  // The next point from where the finger left, however hard the throw.
+  EXPECT_EQ(snapped(config, 0, 2000), 250.0);
+  EXPECT_EQ(snapped(config, 0, 400), 250.0);
+}
+
+TEST(snap_paging_turns_one_page_however_hard_it_is_thrown) {
+  // Not a regression test for the projection so much as a statement that it
+  // does not apply here: a paged view turns one page per flick on iOS, and a
+  // throw worth two and a half pages still turns one.
+  ScrollSnapConfig config;
+  config.paging = true;
+  EXPECT_EQ(snapped(config, 0, 4000), kContainer);
+}
+
+// --- snapToStart and snapToEnd ---------------------------------------------
+//
+// Both default to true, and what they are the default *of* is that the
+// content's own edges count as snap points beside the listed ones. Which is
+// easy to miss: a list of offsets that does not include 0 could not be scrolled
+// back to the top and held there.
+
+TEST(snap_the_content_edges_are_snap_points_by_default) {
+  ScrollSnapConfig config;
+  config.offsets = {300, 600};
+
+  // Nearer the top than the first listed point, released: the top.
+  EXPECT_EQ(snapped(config, 100, 0), 0.0);
+  // And nearer the end than the last listed point: the end, which is the
+  // content minus the container.
+  EXPECT_EQ(snapped(config, 1500, 0), kContent - kContainer);
+}
+
+TEST(snap_to_start_false_scrolls_freely_before_the_first_offset) {
+  ScrollSnapConfig config;
+  config.offsets = {300, 600};
+  config.snapToStart = false;
+  // No answer at all, which is what lets the list coast: each host treats a
+  // target of nothing as "not a snapping gesture" and runs the fling.
+  EXPECT(!scrollSnapTarget(config, 100, 0, kContainer, kContent).has_value());
+  // The listed points still snap, so this is the gap being freed rather than
+  // snapping being switched off.
+  EXPECT_EQ(snapped(config, 320, 0), 300.0);
+}
+
+TEST(snap_to_end_false_scrolls_freely_past_the_last_offset) {
+  ScrollSnapConfig config;
+  config.offsets = {300, 600};
+  config.snapToEnd = false;
+  EXPECT(!scrollSnapTarget(config, 1500, 0, kContainer, kContent).has_value());
+  // The listed points still snap: it is the gap past the last of them that was
+  // freed, not snapping itself. A list at 620 is in that gap and coasts, which
+  // is what the assertion above says; one at 320 is not.
+  EXPECT_EQ(snapped(config, 320, 0), 300.0);
+}
+
+TEST(snap_a_freed_edge_is_still_reached_from_before_it) {
+  // The half of upstream's rule that is easy to drop: a list thrown from
+  // *inside* the snapping region towards a freed edge settles on the last
+  // listed point rather than sailing into the gap. Only a list already in the
+  // gap coasts.
+  ScrollSnapConfig config;
+  config.offsets = {300, 600};
+  config.snapToEnd = false;
+  EXPECT_EQ(snapped(config, 500, 2000), 600.0);
+
+  ScrollSnapConfig fromTheOtherEnd;
+  fromTheOtherEnd.offsets = {300, 600};
+  fromTheOtherEnd.snapToStart = false;
+  EXPECT_EQ(snapped(fromTheOtherEnd, 500, -2000), 300.0);
+}
+
 TEST(snap_content_shorter_than_the_container_stays_at_zero) {
   ScrollSnapConfig config;
   config.paging = true;
@@ -110,3 +204,38 @@ TEST(snap_content_shorter_than_the_container_stays_at_zero) {
 }
 
 } // namespace
+
+// What a tree dump says a scroll view's snapping is, which is the only way an
+// end-to-end run can see any of these props: a snap point changes where a fling
+// *ends*, and a dump is taken when nothing is moving.
+TEST(scroll_snap_describes_itself_for_a_dump) {
+  ScrollSnapConfig plain;
+  EXPECT(basalt::describeScrollSnap(plain).empty());
+
+  ScrollSnapConfig paged;
+  paged.paging = true;
+  EXPECT(basalt::describeScrollSnap(paged) == " snap=paging");
+
+  ScrollSnapConfig interval;
+  interval.interval = 420.0;
+  interval.disableIntervalMomentum = true;
+  EXPECT(basalt::describeScrollSnap(interval) == " snap=interval:420,momentum=off");
+
+  ScrollSnapConfig offsets;
+  offsets.offsets = {0.0, 100.0, 250.0};
+  offsets.alignment = ScrollSnapAlignment::Center;
+  offsets.snapToEnd = false;
+  EXPECT(basalt::describeScrollSnap(offsets) == " snap=offsets:3,align=center,end=off");
+
+  // The rate rides along, and only when it is not React Native's `'normal'`:
+  // it is what the landing point of a fling is projected with, which is the
+  // point a snap is chosen from.
+  ScrollSnapConfig fast;
+  fast.interval = 100.0;
+  fast.decelerationRate = 0.99;
+  EXPECT(basalt::describeScrollSnap(fast) == " snap=interval:100 decel=0.99");
+
+  ScrollSnapConfig rateOnly;
+  rateOnly.decelerationRate = 0.9;
+  EXPECT(basalt::describeScrollSnap(rateOnly) == " decel=0.9");
+}