basalt-core 0.0.0-rc5 → 0.1.0

package/native/core/ScrollMomentum.h

@@ -70,4 +70,18 @@ class ScrollMomentum {
   double decelerationRate_{kNormalDeceleration};
 };
 
+// How far a fling at `velocity` would travel before it stopped, signed like
+// the velocity.
+//
+// The closed form of the decay `advance` steps through, and it exists for
+// `core/ScrollSnap.h`: a snapping list has to know where momentum *would* have
+// carried it before it can decide which point to settle on, which is what
+// `disableIntervalMomentum` turns off. Nothing animates from this -- the fling
+// above is still what moves a list that is not snapping.
+//
+// Integrated to the speed the fling stops at rather than to zero, because that
+// is where `advance` gives up: the tail below it is never travelled, and a
+// projection that included it would reach past every real fling.
+double scrollMomentumDistance(double velocity, double decelerationRate);
+
 } // namespace basalt

package/native/core/ScrollSnap.cpp

@@ -1,12 +1,25 @@
 #include "ScrollSnap.h"
 
+#include <string>
+
+#include "ScrollMomentum.h"
+
 #include <algorithm>
 #include <cmath>
+#include <cstdio>
 
 namespace basalt {
 
 namespace {
 
+// `%g` without a trailing `.000000`, which is what every other number in a tree
+// dump is printed with.
+std::string shortNumber(double value) {
+  char text[32];
+  std::snprintf(text, sizeof(text), "%g", value);
+  return text;
+}
+
 // What the alignment shifts by: a centred snap lines the middle of the
 // container up with a point, an end-aligned one lines up its trailing edge.
 double alignmentShift(ScrollSnapAlignment alignment, double containerLength) {
@@ -27,19 +40,54 @@ double clampToContent(double offset, double containerLength, double contentLengt
 }
 
 // The nearest of an explicit list, with a flick moving at least one entry.
-std::optional<double> nearestOffset(const std::vector<double> &offsets,
+//
+// `landing` is where the fling would have come to rest and `offset` is where
+// the finger left; for a release the two are the same. The candidates are the
+// listed offsets *and* the content's own two edges, which is what
+// `snapToStart` and `snapToEnd` are about -- "by default the beginning of the
+// list counts as a snap offset", in upstream's words, and those two props turn
+// the default off.
+std::optional<double> nearestOffset(const ScrollSnapConfig &config,
                                     double offset,
-                                    double velocity) {
-  if (offsets.empty()) {
+                                    double landing,
+                                    double velocity,
+                                    double furthest) {
+  if (config.offsets.empty()) {
     return std::nullopt;
   }
-  std::vector<double> sorted = offsets;
+  std::vector<double> sorted = config.offsets;
+  std::sort(sorted.begin(), sorted.end());
+  const double first = sorted.front();
+  const double last = sorted.back();
+
+  // Free scrolling between an edge and the listed point nearest it, when the
+  // app asked for that. Upstream's own two conditions, and both halves matter:
+  // a list already past the last point coasts, and one that is *not* yet past
+  // it still settles there rather than sailing into the gap.
+  if (!config.snapToEnd && landing >= last) {
+    if (offset >= last) {
+      return std::nullopt;
+    }
+    return last;
+  }
+  if (!config.snapToStart && landing <= first) {
+    if (offset <= first) {
+      return std::nullopt;
+    }
+    return first;
+  }
+
+  // The content's edges as candidates, which is the default behaviour the two
+  // props above switch off. Inserted rather than special-cased so that
+  // "nearest" and "next in that direction" both see them.
+  sorted.insert(sorted.begin(), 0.0);
+  sorted.push_back(furthest);
   std::sort(sorted.begin(), sorted.end());
 
   auto nearest = sorted.begin();
-  double best = std::abs(sorted.front() - offset);
+  double best = std::abs(sorted.front() - landing);
   for (auto it = sorted.begin(); it != sorted.end(); ++it) {
-    const double distance = std::abs(*it - offset);
+    const double distance = std::abs(*it - landing);
     if (distance < best) {
       best = distance;
       nearest = it;
@@ -47,10 +95,12 @@ std::optional<double> nearestOffset(const std::vector<double> &offsets,
   }
 
   if (velocity > kScrollSnapFlickVelocity) {
-    // The first entry strictly past where we are. A flick forwards must not
-    // settle back on the point it started from.
+    // The first entry at or past where the fling would have landed. A flick
+    // forwards must not settle back on the point it started from, which is
+    // what the `> offset` rather than `>= landing` guard is for when the two
+    // are the same.
     for (auto it = sorted.begin(); it != sorted.end(); ++it) {
-      if (*it > offset) {
+      if (*it >= landing && *it > offset) {
         return *it;
       }
     }
@@ -58,7 +108,7 @@ std::optional<double> nearestOffset(const std::vector<double> &offsets,
   }
   if (velocity < -kScrollSnapFlickVelocity) {
     for (auto it = sorted.rbegin(); it != sorted.rend(); ++it) {
-      if (*it < offset) {
+      if (*it <= landing && *it < offset) {
         return *it;
       }
     }
@@ -69,6 +119,55 @@ std::optional<double> nearestOffset(const std::vector<double> &offsets,
 
 } // namespace
 
+std::string describeScrollSnap(const ScrollSnapConfig &config) {
+  std::string out;
+  if (config.enabled()) {
+    out += " snap=";
+    if (config.paging) {
+      // The container's own length, which only the host knows; naming the mode
+      // is the whole of what this line can say.
+      out += "paging";
+    } else if (!config.offsets.empty()) {
+      out += "offsets:" + std::to_string(config.offsets.size());
+    } else {
+      out += "interval:" + shortNumber(config.interval);
+    }
+    switch (config.alignment) {
+      case ScrollSnapAlignment::Center:
+        out += ",align=center";
+        break;
+      case ScrollSnapAlignment::End:
+        out += ",align=end";
+        break;
+      case ScrollSnapAlignment::Start:
+        break;
+    }
+    // Printed only when false, both of them: true is the default and every
+    // scroll view would otherwise carry two words that say nothing.
+    if (!config.snapToStart) {
+      out += ",start=off";
+    }
+    if (!config.snapToEnd) {
+      out += ",end=off";
+    }
+    if (config.disableIntervalMomentum) {
+      out += ",momentum=off";
+    }
+  }
+  // Beside the snapping because that is what it is for here: the rate decides
+  // where a fling would have landed, which is the point a snap is chosen from.
+  // Only when it is not React Native's own default, so an ordinary list says
+  // nothing.
+  //
+  // Compared with a tolerance rather than exactly: the prop is a `float` in
+  // ReactCommon, so the default arrives here as 0.99800002574920654 and an
+  // equality test would print a line for every scroll view in every app.
+  if (std::abs(config.decelerationRate - ScrollMomentum::kNormalDeceleration) > 1e-6) {
+    out += " decel=" + shortNumber(config.decelerationRate);
+  }
+  return out;
+}
+
 std::optional<double> scrollSnapTarget(const ScrollSnapConfig &config,
                                        double offset,
                                        double velocity,
@@ -78,11 +177,21 @@ std::optional<double> scrollSnapTarget(const ScrollSnapConfig &config,
     return std::nullopt;
   }
 
+  // Where the fling would have come to rest, which is the offset a snap point
+  // is chosen next to unless the app asked for the paged behaviour. Zero for a
+  // release, for `pagingEnabled` -- one page per flick, whatever it was worth --
+  // and for `disableIntervalMomentum`, which is the prop for asking that a
+  // spacing behave like a page.
+  const double landing = config.paging || config.disableIntervalMomentum
+      ? offset
+      : offset + scrollMomentumDistance(velocity, config.decelerationRate);
+
   // An explicit list wins over a spacing, and a spacing over paging only when
   // paging is off: `pagingEnabled` is the coarsest statement and iOS lets it
   // take precedence.
   if (!config.paging && !config.offsets.empty()) {
-    const auto target = nearestOffset(config.offsets, offset, velocity);
+    const auto target = nearestOffset(
+        config, offset, landing, velocity, std::max(0.0, contentLength - containerLength));
     if (!target) {
       return std::nullopt;
     }
@@ -98,7 +207,7 @@ std::optional<double> scrollSnapTarget(const ScrollSnapConfig &config,
   // up with a multiple is the container's leading edge, its middle, or its
   // trailing edge.
   const double shift = alignmentShift(config.alignment, containerLength);
-  const double aligned = offset + shift;
+  const double aligned = landing + shift;
 
   double index = std::floor(aligned / interval);
   const double within = aligned - index * interval;

package/native/core/ScrollSnap.h

@@ -29,10 +29,29 @@
 //
 // Below that threshold the nearest point wins, which is the behaviour of
 // letting go without meaning anything by it.
+//
+// ## Next to *where*, which is the part `disableIntervalMomentum` is about
+//
+// For `pagingEnabled` the answer is the next page and nothing further, however
+// hard the list was thrown: that is what a paged view does on iOS, where
+// UIScrollView turns one page per flick.
+//
+// `snapToInterval` and `snapToOffsets` are not that. There the momentum is
+// real -- a hard throw crosses several points and settles at the one it
+// arrives near -- so the point is chosen from where the fling *would have
+// landed*, projected with the same friction model `core/ScrollMomentum.h`
+// animates. `disableIntervalMomentum` is the prop that asks for the other
+// behaviour, and gives the paged one: the next point from where the finger
+// left.
+//
+// Upstream decides this the same way, in `RCTEnhancedScrollView`'s
+// `scrollViewWillEndDragging`, except that it is handed iOS's own predicted
+// target rather than projecting one.
 
 #pragma once
 
 #include <optional>
+#include <string>
 #include <vector>
 
 namespace basalt {
@@ -56,6 +75,22 @@ struct ScrollSnapConfig {
   // spacing.
   std::vector<double> offsets;
   ScrollSnapAlignment alignment{ScrollSnapAlignment::Start};
+  // `snapToStart` and `snapToEnd`, which are about `snapToOffsets` and nothing
+  // else: by default the content's own start and end count as snap points
+  // beside the listed ones, and `false` lets the list scroll freely between an
+  // edge and the nearest listed point. Both default to true, as upstream's
+  // props and `ScrollView.js` do.
+  bool snapToStart{true};
+  bool snapToEnd{true};
+  // `disableIntervalMomentum`: a fling stops at the point next to where the
+  // *finger* left rather than where the coasting would have carried it. For a
+  // page less wide than the list, which is what React Native's own
+  // documentation says it is for.
+  bool disableIntervalMomentum{false};
+  // `decelerationRate`, needed to know where a fling would have landed. The
+  // same per-millisecond factor `core/ScrollMomentum.h` takes, defaulting to
+  // React Native's `'normal'`; a host that reads the prop passes its own.
+  double decelerationRate{0.998};
 
   bool enabled() const {
     return paging || interval > 0.0 || !offsets.empty();
@@ -67,6 +102,16 @@ struct ScrollSnapConfig {
 // the wobble of letting go does not.
 inline constexpr double kScrollSnapFlickVelocity = 250.0;
 
+// What a scroll view's snapping is set to, as a tree dump prints it: a
+// fragment like ` snap=interval:420,momentum=off decel=0.99`, or empty when
+// there is nothing to say.
+//
+// Here rather than in each host so that the three dumps cannot drift, which is
+// the same argument `core/TextAlignments.h` makes for the names it resolves.
+// It exists because none of this is visible any other way: a snap point changes
+// where a fling *ends*, and a tree dump is taken when nothing is moving.
+std::string describeScrollSnap(const ScrollSnapConfig &config);
+
 // The offset to settle at, or nothing when no snapping is configured.
 //
 // `velocity` is in pixels per second, positive meaning the content offset is

package/native/core/ScrollVisiblePosition.cpp

@@ -0,0 +1,68 @@
+#include "ScrollVisiblePosition.h"
+
+#include <cmath>
+
+namespace basalt {
+
+namespace {
+
+// Below this an adjustment is rounding rather than movement. Upstream's number,
+// and the reason for having one at all is that layout arithmetic repeats to
+// within a fraction of a point: a list that moved by that on every transaction
+// would drift under the person reading it.
+constexpr double kMinimumMove = 0.5;
+
+} // namespace
+
+ScrollPinnedChild firstVisibleChild(const std::vector<ScrollChildBox> &children,
+                                    int minIndexForVisible,
+                                    double offset) {
+  if (children.empty()) {
+    return {};
+  }
+  const auto first = static_cast<size_t>(minIndexForVisible < 0 ? 0 : minIndexForVisible);
+  if (first >= children.size()) {
+    // A `minIndexForVisible` past the end of the list, which a list that has
+    // not rendered its rows yet produces. Nothing to watch rather than the last
+    // child: the index is the app saying which children it does not want
+    // watched.
+    return {};
+  }
+
+  for (size_t index = first; index < children.size(); index++) {
+    const ScrollChildBox &child = children[index];
+    const bool visible = child.leading + child.length > offset;
+    // The last child is watched whether or not it is visible: a list scrolled
+    // past everything has no visible child, and watching nothing would mean
+    // adjusting by nothing.
+    if (visible || index + 1 == children.size()) {
+      return ScrollPinnedChild{.has = true, .tag = child.tag, .leading = child.leading};
+    }
+  }
+  return {};
+}
+
+ScrollVisibleAdjustment visiblePositionAdjustment(
+    double previousLeading,
+    double currentLeading,
+    double offset,
+    std::optional<int> autoscrollToStartThreshold) {
+  const double delta = currentLeading - previousLeading;
+  if (std::abs(delta) <= kMinimumMove) {
+    return {};
+  }
+
+  ScrollVisibleAdjustment adjustment;
+  adjustment.move = true;
+  adjustment.delta = delta;
+  // Measured against the offset as it stands, before the adjustment: the
+  // question is where the person was looking, not where they are about to be
+  // put. Upstream reads the offset into a local for exactly that reason.
+  if (autoscrollToStartThreshold.has_value()
+      && offset <= static_cast<double>(*autoscrollToStartThreshold)) {
+    adjustment.autoscrollToStart = true;
+  }
+  return adjustment;
+}
+
+} // namespace basalt

package/native/core/ScrollVisiblePosition.h

@@ -0,0 +1,101 @@
+// `maintainVisibleContentPosition`: keeping the content still while items are
+// added above it.
+//
+// A chat list is the case the prop exists for. Messages arrive at the top of a
+// list that is scrolled to the bottom, or older ones are prepended when the
+// person pulls up, and without this the content under their eyes jumps by the
+// height of whatever was inserted. React Native's answer is to measure one
+// child before the mutation and again after, and to move the scroll offset by
+// however far that child moved -- so the child stays where it was and the
+// insertion happens off screen.
+//
+// ## Why this is arithmetic and not a host's business
+//
+// The whole of it is: which child to watch, how far it moved, and whether the
+// list was near enough to the start to be taken there instead. None of that
+// needs a toolkit, and all three hosts would otherwise spell it themselves --
+// which is how the three scroll ranges and three snapping rules started, before
+// `core/ScrollBounds.h` and `core/ScrollSnap.h`.
+//
+// What a host does provide is the children's boxes before and after, which is
+// the one part a toolkit knows and this does not.
+//
+// ## The rules, which are upstream's
+//
+// `RCTScrollViewComponentView` does this in two halves, around the mounting
+// transaction: `_prepareForMaintainVisibleScrollPosition` before and
+// `_adjustForMaintainVisibleContentPosition` after. The three rules worth
+// naming, each of which has a test:
+//
+//   - **The child watched is the first one that is even partly visible**, from
+//     `minIndexForVisible` onwards: the first whose trailing edge is past the
+//     offset. A list may keep a header out of this with that index, which is
+//     what it is for.
+//   - **The last child is the fallback.** When everything is scrolled past,
+//     there is no visible child to watch and the last one is watched anyway;
+//     without that a list scrolled to its end would adjust by nothing.
+//   - **Half a point is not a move.** Layout arithmetic repeats to within a
+//     rounding error, and an adjustment of a fraction of a pixel on every
+//     transaction would be a list that drifts.
+//
+// And `autoscrollToTopThreshold`, which is the opposite behaviour and reads
+// oddly until the case is named: a chat list sitting *at* the top, where new
+// messages arrive, should follow them rather than hold still. So a list within
+// that many points of the start is taken to the start instead.
+
+#pragma once
+
+#include <optional>
+#include <vector>
+
+namespace basalt {
+
+// One child of the content view, on the axis that scrolls. `leading` is its
+// top (or left) in the content's own coordinates and `length` its height (or
+// width).
+//
+// The tag travels with it because the child watched has to be found again after
+// the mutation, and its position in the list is exactly what may have changed.
+struct ScrollChildBox {
+  int tag{0};
+  double leading{0.0};
+  double length{0.0};
+};
+
+// The child a scroll view is watching, remembered across a transaction.
+struct ScrollPinnedChild {
+  bool has{false};
+  int tag{0};
+  double leading{0.0};
+};
+
+// Which child to watch, given the children before the mutation.
+//
+// Empty when there are no children at or after `minIndexForVisible`, which is
+// also what an empty list gives: there is nothing to keep still.
+ScrollPinnedChild firstVisibleChild(const std::vector<ScrollChildBox> &children,
+                                   int minIndexForVisible,
+                                   double offset);
+
+// What to do once the mutation has happened and the watched child has moved.
+struct ScrollVisibleAdjustment {
+  // False when nothing moved far enough to be worth moving the list for.
+  bool move{false};
+  // How far the offset should change, signed the same way the offset is.
+  double delta{0.0};
+  // `autoscrollToTopThreshold`: the list was near the start, so it follows the
+  // new content to the start rather than holding its place. The caller animates
+  // this one, where the adjustment above is instant -- which is upstream's
+  // division too.
+  bool autoscrollToStart{false};
+};
+
+// `previousLeading` is where the watched child was before the mutation and
+// `currentLeading` where it is now; `offset` is the scroll offset as it stands,
+// which is the one the threshold is measured against.
+ScrollVisibleAdjustment visiblePositionAdjustment(double previousLeading,
+                                                  double currentLeading,
+                                                  double offset,
+                                                  std::optional<int> autoscrollToStartThreshold);
+
+} // namespace basalt

package/native/core/SettingsStore.cpp

@@ -0,0 +1,199 @@
+#include "SettingsStore.h"
+
+#include "AppIdentity.h"
+
+#include <folly/json.h>
+
+#include <glog/logging.h>
+
+#include <cstdlib>
+#include <fstream>
+#include <sstream>
+#include <system_error>
+#include <utility>
+
+namespace basalt {
+
+namespace {
+
+std::string environmentValue(const char *name) {
+  const char *value = std::getenv(name);
+  return value == nullptr ? std::string{} : std::string(value);
+}
+
+// The per-user configuration directory, by each desktop's own rule.
+//
+// Read from the environment rather than asked of an API on purpose: the
+// authoritative calls are `g_get_user_config_dir`, `-[NSFileManager
+// URLsForDirectory:inDomains:]` and `SHGetKnownFolderPath`, which are three
+// libraries this file does not link and which all three answer from the same
+// variables anyway. A host that wants the real call can pass a path through
+// `BASALT_SETTINGS_FILE`.
+std::filesystem::path userConfigDirectory() {
+#if defined(_WIN32)
+  const std::string appData = environmentValue("APPDATA");
+  if (!appData.empty()) {
+    return std::filesystem::path(appData);
+  }
+  const std::string profile = environmentValue("USERPROFILE");
+  if (profile.empty()) {
+    return {};
+  }
+  return std::filesystem::path(profile) / "AppData" / "Roaming";
+#else
+  const std::string home = environmentValue("HOME");
+#if defined(__APPLE__)
+  // Where a macOS application's own files go. `~/Library/Preferences` is where
+  // `NSUserDefaults` writes, and writing a file of our own into it would put
+  // something that is not a plist where `defaults` expects one.
+  if (home.empty()) {
+    return {};
+  }
+  return std::filesystem::path(home) / "Library" / "Application Support";
+#else
+  const std::string configHome = environmentValue("XDG_CONFIG_HOME");
+  if (!configHome.empty()) {
+    return std::filesystem::path(configHome);
+  }
+  if (home.empty()) {
+    return {};
+  }
+  return std::filesystem::path(home) / ".config";
+#endif
+#endif
+}
+
+} // namespace
+
+std::filesystem::path settingsFilePath() {
+  const std::string chosen = environmentValue(kSettingsFileVar);
+  if (!chosen.empty()) {
+    return std::filesystem::path(chosen);
+  }
+
+  const std::filesystem::path directory = userConfigDirectory();
+  if (directory.empty()) {
+    return {};
+  }
+
+  const AppIdentity &identity = appIdentity();
+  return directory / (identity.identifier.empty() ? std::string("basalt") : identity.identifier) /
+      "settings.json";
+}
+
+SettingsStore::SettingsStore(std::filesystem::path file) : file_(std::move(file)) {
+  if (file_.empty()) {
+    return;
+  }
+
+  std::ifstream stream(file_);
+  if (!stream) {
+    // The normal first run. Not a warning: an application that has never
+    // written a setting has no settings file, and saying so at every startup
+    // would train people to ignore the log.
+    return;
+  }
+  std::stringstream contents;
+  contents << stream.rdbuf();
+
+  try {
+    folly::dynamic parsed = folly::parseJson(contents.str());
+    if (parsed.isObject()) {
+      values_ = std::move(parsed);
+      return;
+    }
+    LOG(WARNING) << file_.string() << " holds " << parsed.typeName()
+                 << " rather than an object; starting with no settings";
+  } catch (const std::exception &error) {
+    LOG(WARNING) << "could not read " << file_.string() << ": " << error.what();
+  }
+}
+
+std::vector<std::string> SettingsStore::merge(const folly::dynamic &values) {
+  std::vector<std::string> changed;
+  if (!values.isObject()) {
+    return changed;
+  }
+
+  for (const auto &pair : values.items()) {
+    if (!pair.first.isString()) {
+      // JavaScript object keys are strings, so this is unreachable from the
+      // module and reachable from a caller in C++.
+      continue;
+    }
+    const std::string key = pair.first.asString();
+
+    if (pair.second.isNull()) {
+      if (values_.count(key) > 0) {
+        values_.erase(key);
+        changed.push_back(key);
+      }
+      continue;
+    }
+
+    if (values_.count(key) > 0 && values_[key] == pair.second) {
+      continue;
+    }
+    values_[key] = pair.second;
+    changed.push_back(key);
+  }
+
+  if (!changed.empty()) {
+    save();
+  }
+  return changed;
+}
+
+std::vector<std::string> SettingsStore::erase(const std::vector<std::string> &keys) {
+  std::vector<std::string> removed;
+  for (const std::string &key : keys) {
+    if (values_.count(key) == 0) {
+      continue;
+    }
+    values_.erase(key);
+    removed.push_back(key);
+  }
+  if (!removed.empty()) {
+    save();
+  }
+  return removed;
+}
+
+void SettingsStore::save() const {
+  if (file_.empty()) {
+    return;
+  }
+
+  std::error_code error;
+  if (file_.has_parent_path()) {
+    std::filesystem::create_directories(file_.parent_path(), error);
+    if (error) {
+      LOG(WARNING) << "could not create " << file_.parent_path().string() << ": "
+                   << error.message();
+      return;
+    }
+  }
+
+  // A sibling rather than the temporary directory, because the rename below has
+  // to stay on one filesystem to be atomic.
+  const std::filesystem::path pending(file_.string() + ".new");
+  {
+    std::ofstream stream(pending, std::ios::binary | std::ios::trunc);
+    stream << folly::toPrettyJson(values_) << "\n";
+    if (!stream) {
+      LOG(WARNING) << "could not write " << pending.string();
+      std::error_code ignored;
+      std::filesystem::remove(pending, ignored);
+      return;
+    }
+  }
+
+  std::filesystem::rename(pending, file_, error);
+  if (error) {
+    LOG(WARNING) << "could not replace " << file_.string() << ": " << error.message();
+    std::error_code ignored;
+    std::filesystem::remove(pending, ignored);
+  }
+}
+
+} // namespace basalt