basalt-appkit 0.0.0-rc5 → 0.1.0

package/native/appkit/AppKitScrollView.h

@@ -38,13 +38,16 @@
 #include "ScrollBounds.h"
 #include "ScrollIndicator.h"
 #include "ScrollSnap.h"
+#include "ScrollVisiblePosition.h"
 
 #include <react/renderer/components/scrollview/ScrollViewShadowNode.h>
 #include <react/renderer/core/EventEmitter.h>
 #include <react/renderer/mounting/ShadowView.h>
 
 #include <functional>
+#include <optional>
 #include <unordered_map>
+#include <vector>
 
 namespace basalt {
 
@@ -65,6 +68,17 @@ class AppKitScrollViewManager {
   void update(RnAppKitView *view, const facebook::react::ShadowView &shadowView);
 
   void remove(facebook::react::Tag tag);
+  // `maintainVisibleContentPosition`, in the two halves a mounting transaction
+  // needs: the children are measured before the mutations and the offset is
+  // moved after, so content under the eye stays where it is while items are
+  // inserted above it. The arithmetic is core/ScrollVisiblePosition.h's.
+  //
+  // Public because the mounting manager is what knows when a transaction starts
+  // and ends, which is upstream's division too: `mountingTransactionWillMount`
+  // and `...DidMount` on iOS.
+  void prepareMaintainVisiblePosition();
+  void adjustForMaintainVisiblePosition();
+
 
   // ScrollView's imperative commands: scrollTo, scrollToEnd. Returns false if
   // the command is not one this handles.
@@ -124,6 +138,35 @@ class AppKitScrollViewManager {
 
     double offsetX{0};
     double offsetY{0};
+
+    // `maintainVisibleContentPosition`, as React Native hands it over: a
+    // minimum index and an optional threshold, or nothing at all when the list
+    // never asked.
+    std::optional<facebook::react::ScrollViewMaintainVisibleContentPosition> maintainVisible{};
+    // The child being held still across the current transaction, measured by
+    // `prepareMaintainVisiblePosition` and used by the adjust that follows.
+    ScrollPinnedChild pinned{};
+    // `indicatorStyle`: which colour the overlay thumb is drawn in. Held as
+    // core's enum rather than React Native's, the view layer below knowing
+    // nothing about either.
+    ScrollIndicatorStyle indicatorStyle{ScrollIndicatorStyle::Default};
+
+    // `centerContent`: whether content smaller than the container is centred in
+    // it. Acted on through the content inset, which is how iOS does it too --
+    // see `update`.
+    bool centerContent{false};
+
+    // The last `contentOffset` prop seen, and nothing when none has been.
+    //
+    // The *initial* value of that prop arrives through the state rather than
+    // here -- `ScrollViewShadowNode::initialStateData` seeds the state with it
+    // -- and is adopted below. What this is for is every later change, which
+    // arrives as an ordinary prop update and is applied when it *changes*,
+    // never merely when it differs from where the list is: an app that sets the
+    // prop once and re-renders for an unrelated reason must not have the list
+    // dragged back under the person reading it. The same rule a `<TextInput>`'s
+    // `text` is under, for the same reason.
+    std::optional<facebook::react::Point> lastPropContentOffset{};
     double lastEmitSeconds{0};
     bool dragging{false};
     // Coasting after the fingers left. Tracked for the same reason `dragging`
@@ -140,6 +183,11 @@ class AppKitScrollViewManager {
     double animationLastSeconds{0};
   };
 
+  // The rows of the content view, on whichever axis scrolls, for
+  // `maintainVisibleContentPosition`. The one part of that prop a toolkit
+  // knows: core decides what to do with the boxes.
+  std::vector<ScrollChildBox> contentChildBoxes(const Entry &entry) const;
+
   void applyOffset(Entry &entry, double x, double y, bool emitEvent);
   // Recomputes both overlay scrollbars and hands them to the view to draw.
   // Called wherever the offset, the content size or the container size can

package/native/appkit/AppKitScrollView.mm

@@ -1,5 +1,7 @@
 #import "AppKitScrollView.h"
 
+#include "ScrollSnap.h"
+
 #import <QuartzCore/QuartzCore.h>
 
 #include <react/renderer/components/scrollview/ScrollEvent.h>
@@ -178,6 +180,71 @@ void AppKitScrollViewManager::update(RnAppKitView *view, const ShadowView &shado
         entry.snap.alignment = ScrollSnapAlignment::Start;
         break;
     }
+    // The three modifiers of snapping, all of which `core/ScrollSnap.h` acts
+    // on: whether the content's own edges count as snap points beside the
+    // listed ones, and whether a fling across a spacing carries or stops at the
+    // next point.
+    // `centerContent`, applied below once the content size is known.
+    entry.centerContent = props->centerContent;
+
+    // `maintainVisibleContentPosition`, remembered for the next transaction:
+    // the work it asks for happens around the mutations rather than while a
+    // prop is being read. See `prepareMaintainVisiblePosition`.
+    entry.maintainVisible = props->maintainVisibleContentPosition;
+
+    // `indicatorStyle`, resolved to a colour by core so that all three hosts
+    // draw the same thumb for the same prop.
+    switch (props->indicatorStyle) {
+      case facebook::react::ScrollViewIndicatorStyle::White:
+        entry.indicatorStyle = ScrollIndicatorStyle::White;
+        break;
+      case facebook::react::ScrollViewIndicatorStyle::Black:
+        entry.indicatorStyle = ScrollIndicatorStyle::Black;
+        break;
+      case facebook::react::ScrollViewIndicatorStyle::Default:
+      default:
+        entry.indicatorStyle = ScrollIndicatorStyle::Default;
+        break;
+    }
+
+    entry.snap.snapToStart = props->snapToStart;
+    entry.snap.snapToEnd = props->snapToEnd;
+    entry.snap.disableIntervalMomentum = props->disableIntervalMomentum;
+
+    // `contentOffset`, which an app writes to open a list part way down. Its
+    // first value reached here through the state and is adopted below; this is
+    // every later change, applied the way upstream applies it --
+    // `oldScrollViewProps.contentOffset != newScrollViewProps.contentOffset` in
+    // `RCTScrollViewComponentView` -- rather than whenever the prop differs
+    // from where the list is.
+    //
+    // The offset is set rather than animated to, which is what assigning
+    // `UIScrollView.contentOffset` does, and the clamp below is what keeps a
+    // value past the end of the content from showing empty space.
+    if (!entry.lastPropContentOffset.has_value()
+        || *entry.lastPropContentOffset != props->contentOffset) {
+      entry.lastPropContentOffset = props->contentOffset;
+      entry.offsetX = props->contentOffset.x;
+      entry.offsetY = props->contentOffset.y;
+      // Whatever the list was animating towards is somewhere the app has just
+      // said it does not want to be. No fling to stop: the momentum on this
+      // host is not this host's to run.
+      stopAnimation(entry);
+    }
+    // `decelerationRate`, which this host does not animate with -- the fling
+    // itself is AppKit's, at its own friction -- but does need for the
+    // *projection*: where a fling would have landed is the point a snap is
+    // chosen from, and a fast list stops sooner. Zero is what an app that
+    // never set the prop leaves behind.
+    if (props->decelerationRate > 0) {
+      entry.snap.decelerationRate = static_cast<double>(props->decelerationRate);
+    }
+
+    // What all of that came to, for the tree dump. None of these props is
+    // visible any other way: they decide where a fling *ends*, and a dump is
+    // taken when nothing is moving. The string is core's, so the three hosts
+    // cannot drift; see describeScrollSnap.
+    view.rnScrollSnap = @(basalt::describeScrollSnap(entry.snap).c_str());
   }
 
   if (const auto state =
@@ -195,6 +262,27 @@ void AppKitScrollViewManager::update(RnAppKitView *view, const ShadowView &shado
     }
   }
 
+  // `centerContent`: content smaller than its container sits in the middle of
+  // it. Expressed as an inset of half the slack at each end, which leaves the
+  // range below a single offset to be at -- so the clamp that was already here
+  // is what centres the content and what keeps it centred.
+  //
+  // It replaces the app's own `contentInset` rather than adding to it, which is
+  // what iOS does: `centerContentIfNeeded` assigns the inset outright, and
+  // `RCTScrollViewComponentView` skips the `contentInset` prop entirely while
+  // `centerContent` is set. Recomputed here rather than where the prop is read
+  // because it needs the content size, which arrives with the state.
+  if (entry.centerContent) {
+    const ScrollAxisInsets horizontal =
+        centeringInsets(entry.containerSize.width, entry.contentSize.width);
+    const ScrollAxisInsets vertical =
+        centeringInsets(entry.containerSize.height, entry.contentSize.height);
+    entry.contentInset.left = static_cast<facebook::react::Float>(horizontal.leading);
+    entry.contentInset.right = static_cast<facebook::react::Float>(horizontal.trailing);
+    entry.contentInset.top = static_cast<facebook::react::Float>(vertical.leading);
+    entry.contentInset.bottom = static_cast<facebook::react::Float>(vertical.trailing);
+  }
+
   // Re-clamp: the content may have shrunk under a scrolled offset.
   const double x = clampScrollOffset(entry.offsetX,
                                      entry.containerSize.width,
@@ -212,6 +300,117 @@ void AppKitScrollViewManager::update(RnAppKitView *view, const ShadowView &shado
   updateIndicators(entry);
 }
 
+// ---------------------------------------------------------------------------
+// maintainVisibleContentPosition
+//
+// Two halves around a mounting transaction: measure the child being held still
+// before the mutations, and move the offset by however far it moved after. The
+// arithmetic -- which child, how far, and whether the list was near enough to
+// the start to follow the new content instead -- is core/ScrollVisiblePosition.h.
+//
+// What is here is the part only a toolkit knows: where this host's children
+// are. React Native wraps a ScrollView's children in exactly one content view,
+// so the rows are that view's children.
+// ---------------------------------------------------------------------------
+
+namespace {
+
+// Whether the list scrolls sideways, decided the way upstream decides it: by
+// the content being wider than the view rather than by a prop, there being no
+// prop for it.
+bool scrollsHorizontally(const Size &container, const Size &content) {
+  return content.width > container.width;
+}
+
+} // namespace
+
+std::vector<ScrollChildBox> AppKitScrollViewManager::contentChildBoxes(const Entry &entry) const {
+  std::vector<ScrollChildBox> boxes;
+  if (entry.view == nil) {
+    return boxes;
+  }
+  // The content view, which React Native always makes and always makes exactly
+  // one of. `rnChildrenInPaintOrder` rather than `subviews` because the overlay
+  // scrollbar is a subview too and is not a row; for children with no zIndex --
+  // which rows do not have -- that order is the order they were inserted in.
+  RnAppKitView *const content = [entry.view rnChildrenInPaintOrder].firstObject;
+  if (content == nil) {
+    return boxes;
+  }
+
+  const bool horizontal = scrollsHorizontally(entry.containerSize, entry.contentSize);
+  for (RnAppKitView *row in [content rnChildrenInPaintOrder]) {
+    const NSRect frame = row.frame;
+    boxes.push_back(ScrollChildBox{
+        .tag = static_cast<int>(row.rnTag),
+        .leading = horizontal ? frame.origin.x : frame.origin.y,
+        .length = horizontal ? frame.size.width : frame.size.height});
+  }
+  return boxes;
+}
+
+void AppKitScrollViewManager::prepareMaintainVisiblePosition() {
+  for (auto &[tag, entry] : entries_) {
+    entry.pinned = {};
+    if (!entry.maintainVisible.has_value()) {
+      continue;
+    }
+    const bool horizontal = scrollsHorizontally(entry.containerSize, entry.contentSize);
+    entry.pinned = firstVisibleChild(contentChildBoxes(entry),
+                                     entry.maintainVisible->minIndexForVisible,
+                                     horizontal ? entry.offsetX : entry.offsetY);
+  }
+}
+
+void AppKitScrollViewManager::adjustForMaintainVisiblePosition() {
+  for (auto &[tag, entry] : entries_) {
+    if (!entry.maintainVisible.has_value() || !entry.pinned.has) {
+      continue;
+    }
+    const bool horizontal = scrollsHorizontally(entry.containerSize, entry.contentSize);
+    const double offset = horizontal ? entry.offsetX : entry.offsetY;
+
+    // The same child, found again by tag: its *position in the list* is exactly
+    // what the mutation may have changed, so an index would find a different
+    // row. A child that is gone is not adjusted for, which is upstream's
+    // behaviour too -- it gives up rather than guessing.
+    const ScrollPinnedChild pinned = entry.pinned;
+    entry.pinned = {};
+    std::optional<double> leading;
+    for (const ScrollChildBox &box : contentChildBoxes(entry)) {
+      if (box.tag == pinned.tag) {
+        leading = box.leading;
+        break;
+      }
+    }
+    if (!leading.has_value()) {
+      continue;
+    }
+
+    const ScrollVisibleAdjustment adjustment = visiblePositionAdjustment(
+        pinned.leading, *leading, offset, entry.maintainVisible->autoscrollToTopThreshold);
+    if (!adjustment.move) {
+      continue;
+    }
+
+    if (horizontal) {
+      applyOffset(entry, offset + adjustment.delta, entry.offsetY, true);
+    } else {
+      applyOffset(entry, entry.offsetX, offset + adjustment.delta, true);
+    }
+
+    // And the start, animated, when the list was near enough to it to be
+    // following the new content rather than holding its place.
+    if (adjustment.autoscrollToStart) {
+      if (horizontal) {
+        scrollTowards(entry, 0.0, entry.offsetY, true);
+      } else {
+        scrollTowards(entry, entry.offsetX, 0.0, true);
+      }
+    }
+  }
+}
+
 void AppKitScrollViewManager::remove(Tag tag) {
   const auto it = entries_.find(tag);
   if (it == entries_.end()) {
@@ -394,6 +593,17 @@ void AppKitScrollViewManager::updateIndicators(const Entry &entry) {
                                horizontalInsets(entry.indicatorInset))
           : ScrollIndicator{};
 
+  const ScrollIndicatorColour thumb = scrollIndicatorColourFor(entry.indicatorStyle);
+  [entry.view setRnScrollIndicatorColourRed:thumb.red
+                                      green:thumb.green
+                                       blue:thumb.blue
+                                      alpha:thumb.alpha];
+  const basalt::ScrollIndicatorColour edge =
+      basalt::scrollIndicatorBorderColourFor(entry.indicatorStyle);
+  [entry.view setRnScrollIndicatorBorderColourRed:edge.red
+                                            green:edge.green
+                                             blue:edge.blue
+                                            alpha:edge.alpha];
   [entry.view setRnScrollIndicatorVerticalOffset:vertical.offset
                                   verticalLength:vertical.length
                                 horizontalOffset:horizontal.offset

package/native/appkit/AppKitTextInput.h

@@ -32,6 +32,7 @@
 #include <optional>
 #include <string>
 #include <unordered_map>
+#include <vector>
 
 namespace basalt {
 
@@ -51,6 +52,19 @@ class AppKitTextInputManager {
 
   void remove(facebook::react::Tag tag);
 
+  // Focuses whatever `autoFocus` asked for, once the transaction is on screen.
+  //
+  // It cannot be done where the prop is read. Props are applied by
+  // MountingWalk::create, immediately after `createView` and before any Insert,
+  // so the view has no superview and `view.window` is nil -- and a
+  // `makeFirstResponder:` to nil is a silent no-op. Worse, the flag that guarded
+  // it is `try_emplace`'s "first time this tag was seen", which is false by the
+  // time the Insert arrives, so it never ran twice either. Deferred to the end of
+  // the transaction, which is where resolveRefreshControls already lives for the
+  // same reason: Fabric inserts a subtree bottom-up, so even "just after
+  // insertChild" is too early.
+  void flushAutoFocus();
+
   // focus, blur, and setTextAndSelection. Returns false for anything else.
   bool dispatchCommand(facebook::react::Tag tag,
                        const std::string &name,
@@ -59,7 +73,10 @@ class AppKitTextInputManager {
   // Called by the Objective-C delegate. Public because the trampoline has to
   // reach them; not part of anything a caller would use.
   void handleChanged(facebook::react::Tag tag);
-  void handleSubmit(facebook::react::Tag tag);
+  // Return. What it does is `submitBehavior`'s to say: report a submit, report
+  // one and give up focus, or insert a newline. Returns true when the key was
+  // used up, which is what tells AppKit whether to insert the newline itself.
+  bool handleSubmit(facebook::react::Tag tag);
   void handleFocus(facebook::react::Tag tag);
   void handleBlur(facebook::react::Tag tag);
 
@@ -74,6 +91,11 @@ class AppKitTextInputManager {
   bool handleKeyDown(void *event);
 
  private:
+  // Set when a field is created with `autoFocus`, cleared by flushAutoFocus.
+  // A list rather than one tag because nothing stops two fields asking; the last
+  // one to be focused wins, which is what AppKit would do anyway.
+  std::vector<facebook::react::Tag> pendingAutoFocus_;
+
   struct Entry {
     // The selection as JavaScript last saw it, so one movement is one event.
     facebook::react::AttributedString::Range lastReportedSelection{0, 0};
@@ -94,9 +116,24 @@ class AppKitTextInputManager {
     bool applying{false};
 
     bool secure{false};
+    // `submitBehavior`, already resolved: React Native's `Default` means
+    // `newline` for a multiline field and `blurAndSubmit` for a single-line
+    // one, and `getNonDefaultSubmitBehavior()` is what says so. Read where
+    // Return arrives, which is a delegate callback on both peers.
+    facebook::react::SubmitBehavior submitBehavior{
+        facebook::react::SubmitBehavior::BlurAndSubmit};
+
     // A multiline field is an NSTextView rather than an NSTextField, so a
     // change here rebuilds the peer exactly as `secure` does.
     bool multiline{false};
+
+    // `clearTextOnFocus` and `selectTextOnFocus`: what happens when the field
+    // takes focus. Kept here because focus arrives long after the props do, and
+    // because the second has to be known in `flushAutoFocus` as well -- a field
+    // that asked to select its text must not have the selection collapsed
+    // behind it.
+    bool clearTextOnFocus{false};
+    bool selectTextOnFocus{false};
     std::string lastReportedText;
 
     // The last `text` prop actually seen, and whether one has been seen at all.