basalt-core 0.0.0-rc5

package/native/core/PlatformConstantsModule.h

@@ -0,0 +1,64 @@
+// The `PlatformConstants` TurboModule, replacing ReactCxxPlatform's.
+//
+// ReactCxxPlatform ships one, and it hardcodes a React Native version of
+// 1000.0.0 -- the placeholder `main` uses for "not a release" -- in every
+// version, releases included. React Native's JavaScript compares that against
+// the version the bundle was built from and, in a development build, reports
+//
+//     React Native version mismatch.
+//     JavaScript version: 0.87.1
+//     Native version: 1000.0.0
+//
+// which is a `console.error`, so it is noise rather than a crash, but it is
+// noise that every developer on a released version would see forever, and it
+// tells them to do things that will not help. So this reports the version the
+// host was actually built against, which CMake reads out of React Native's own
+// package.json and passes in as BASALT_REACT_NATIVE_VERSION.
+//
+// Worth reporting upstream: nothing in ReactCxxPlatform can match a release
+// while that constant is baked in.
+//
+// Everything else is copied from ReactCxxPlatform's implementation, including
+// the Android-shaped fields, because that is the spec this platform answers.
+// See packages/basalt-core/src/overrides/createPlatform.js for why the
+// Android spec is the right one here.
+
+#pragma once
+
+#include <react/coremodules/PlatformConstantsModule.h>
+
+#include <string>
+
+namespace basalt {
+
+// Note the base class: the generated spec binds each method to the class it is
+// templated on, at compile time, so subclassing ReactCxxPlatform's module and
+// overriding getConstants does nothing at all -- the method table still points
+// at the base. It has to derive from the spec itself. That failure is silent
+// and looks exactly like the provider not being consulted.
+class DesktopPlatformConstantsModule
+    : public facebook::react::NativePlatformConstantsAndroidCxxSpec<DesktopPlatformConstantsModule> {
+ public:
+  explicit DesktopPlatformConstantsModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+      : NativePlatformConstantsAndroidCxxSpec(std::move(jsInvoker)) {}
+
+  std::string getAndroidID(facebook::jsi::Runtime & /*rt*/) {
+    return "";
+  }
+
+  facebook::react::PlatformConstantsAndroid getConstants(facebook::jsi::Runtime &rt);
+
+  // Parses "0.87.1" or "0.88.0-rc.2". Exposed for the tests, which is the only
+  // way to be sure a prerelease tag does not silently become part of the patch
+  // number. The tag itself is not reported: the Android spec types it as an
+  // optional int, so "rc.2" cannot be expressed.
+  struct Version {
+    int major{0};
+    int minor{0};
+    int patch{0};
+    std::string prerelease;
+  };
+  static Version parseVersion(const std::string &text);
+};
+
+} // namespace basalt

package/native/core/PlatformServices.h

@@ -0,0 +1,213 @@
+// The handful of things a core module needs an operating system for.
+//
+// One file rather than five seams, because each of these is two or three
+// functions and splitting them would mean ten files saying very little. What
+// they have in common is that the *module* above each is portable and only the
+// last step is not: putting text on a clipboard, handing a URL to whatever
+// opens it, and putting a modal dialog on screen.
+//
+// The fifth seam, after fonts, the text layout manager, the component registry
+// and the colour scheme.
+
+#pragma once
+
+#include <functional>
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+// --- Clipboard ---------------------------------------------------------------
+
+// The clipboard's text, or empty if it holds none. Called on the main thread.
+std::string clipboardText();
+void setClipboardText(const std::string &text);
+
+// --- Opening things ----------------------------------------------------------
+
+// Whether anything is registered to handle this URL. A desktop cannot always
+// answer honestly -- both implementations here check the scheme rather than
+// asking every installed application -- so this errs towards yes.
+bool canOpenUrl(const std::string &url);
+
+// Hands the URL to the desktop. Returns false if it could not be launched.
+bool openUrl(const std::string &url);
+
+// --- Alerts ------------------------------------------------------------------
+
+struct AlertRequest {
+  std::string title;
+  std::string message;
+  // In React Native's order, which is also the order the callback reports.
+  std::vector<std::string> buttons;
+  // A `prompt`, with the text field pre-filled. Empty means a plain alert.
+  bool hasTextInput{false};
+  std::string defaultText;
+  std::string placeholder;
+};
+
+// Shows a modal alert and calls `onButton` with the index of the button
+// pressed, and the text if the alert had a field.
+//
+// Must not block: it is called from the JavaScript thread's mount step, and a
+// modal run loop there would deadlock the runtime. Implementations marshal to
+// the main thread and return at once.
+using AlertCallback = std::function<void(int buttonIndex, const std::string &text)>;
+void showAlert(const AlertRequest &request, AlertCallback onButton);
+
+// --- File dialogs -------------------------------------------------------------
+
+// One entry in a dialog's file-type filter. `extensions` are without the dot.
+struct FileFilter {
+  std::string name;
+  std::vector<std::string> extensions;
+};
+
+struct FileDialogRequest {
+  enum class Kind {
+    // One or more existing files.
+    OpenFile,
+    // A path to write to, existing or not. The only kind that asks about
+    // overwriting, which every platform does for itself.
+    SaveFile,
+    // A directory.
+    OpenFolder,
+  };
+
+  Kind kind{Kind::OpenFile};
+  std::string title;
+  // Where to start, and for a save, what to call it. A directory for the two
+  // open kinds; a file name, optionally with a directory, for a save.
+  std::string defaultPath;
+  // What the accepting button says. Empty means the system's own word, which
+  // is almost always the right one.
+  std::string confirmLabel;
+  // OpenFile only. Ignored by the other two, because no desktop has a
+  // multiple-selection save.
+  bool multiple{false};
+  std::vector<FileFilter> filters;
+};
+
+// Shows a file dialog and calls `onDone` with what was chosen, or with
+// `canceled` and nothing.
+//
+// Must not block, for the same reason `showAlert` must not: this is called from
+// the JavaScript thread and a modal run loop there would deadlock the runtime.
+// Implementations marshal to the main thread and return at once.
+//
+// Paths are absolute, and are whatever the platform calls a path -- a Windows
+// one has backslashes in it. Nothing here normalises them: an app passes them
+// straight back to `fetch`, to a native module, or to the same dialog next
+// time, and a "tidied" path is one the system may no longer recognise.
+using FileDialogCallback =
+    std::function<void(bool canceled, const std::vector<std::string> &paths)>;
+void showFileDialog(const FileDialogRequest &request, FileDialogCallback onDone);
+
+// --- Menus --------------------------------------------------------------------
+
+// One entry in a popup menu. A separator is an item with an empty label, which
+// is how GMenu, NSMenu and an HMENU each spell it too.
+struct MenuEntry {
+  std::string label;
+  // Shown greyed and not choosable. A menu of only disabled items is still a
+  // menu, which is what makes this better than leaving the entry out.
+  bool enabled{true};
+  // Drawn beside the label -- "Cmd+R", "Ctrl+R". Decoration only: nothing here
+  // binds a key, because the shortcut that opened the menu and the shortcuts
+  // inside it are answered in different places on all three desktops.
+  std::string shortcut;
+
+  static MenuEntry separator() {
+    return MenuEntry{.label = {}, .enabled = false, .shortcut = {}};
+  }
+
+  bool isSeparator() const {
+    return label.empty();
+  }
+};
+
+struct MenuRequest {
+  std::vector<MenuEntry> entries;
+  // Where to put it, in the window's coordinates. A negative point means "wherever
+  // the pointer is", which is what a menu opened from the keyboard wants.
+  double x{-1.0};
+  double y{-1.0};
+};
+
+// Shows a popup menu and calls `onChosen` with the index of the entry picked,
+// or -1 when it was dismissed. Indexes count separators, so they line up with
+// the vector that was passed in.
+//
+// Must not block, for the same reason `showAlert` must not: this can be called
+// from the JavaScript thread, and a menu's own run loop there would deadlock
+// the runtime. Implementations marshal to the main thread and return at once.
+using MenuCallback = std::function<void(int index)>;
+void showMenu(const MenuRequest &request, MenuCallback onChosen);
+
+// --- Sharing ------------------------------------------------------------------
+
+// What an app asked to share. React Native's `Share.share()` takes `message`,
+// `url` and `title`, and marks each as belonging to one platform or the other;
+// a desktop has no reason to honour that split, so all three arrive and each
+// implementation uses what it can.
+struct ShareRequest {
+  std::string message;
+  std::string url;
+  std::string title;
+  // `options.dialogTitle`, which names the picker on the platforms that show
+  // one they did not draw themselves.
+  std::string dialogTitle;
+};
+
+// What became of it. React Native's promise resolves with `sharedAction` or
+// `dismissedAction` and rejects on anything else, so these are the three
+// answers it can carry and no more.
+enum class ShareOutcome { Shared, Dismissed, Failed };
+
+// `message` is meaningful only for Failed, and becomes the rejection's reason.
+using ShareCallback = std::function<void(ShareOutcome outcome, const std::string &message)>;
+
+// Puts the content in front of the user and reports what they did with it.
+//
+// Must not block, for the same reason `showAlert` must not: it is called from
+// the JavaScript thread and a modal run loop there would deadlock the runtime.
+// Implementations marshal to the main thread and return at once, and the
+// callback comes later -- possibly much later, because a share sheet is on
+// screen until a person does something with it.
+//
+// Only macOS has a share service of its own. The other two go through
+// core/ShareFallback.h, which builds a picker from a clipboard and a mail
+// client; see its header for why that is the honest answer rather than a
+// rejection.
+void shareContent(const ShareRequest &request, ShareCallback onDone);
+
+// Runs `work` on the UI thread after `milliseconds`, once.
+//
+// Every gesture recogniser needs this and nothing else does yet: a long press
+// activates because nothing happened for half a second, and a double tap fails
+// because a second tap did not arrive. Both are "wake me if this is still true
+// later", which cannot be expressed by reacting to input alone.
+//
+// The callback runs on the thread that draws -- the same one input arrives on
+// -- so what it touches needs no lock. There is no way to cancel: a recogniser
+// that has moved on checks its own state when it wakes, which is simpler than
+// owning a handle and correct even when the work has already started.
+void postDelayed(double milliseconds, std::function<void()> work);
+
+// Runs `work` on the UI thread, soon, in the order posted.
+//
+// The gesture registry is UI-thread state -- input arrives there and the
+// recognisers run there -- but the module that configures it is called from
+// JavaScript. Rather than lock the registry, its callers hop threads, which is
+// the same rule the mounting managers keep and assert.
+void postToUiThread(std::function<void()> work);
+
+// Whether this is the thread that draws.
+//
+// Fabric dispatches an event from whichever thread produced it -- a touch from
+// the UI thread, a layout event from the JavaScript thread -- and anything that
+// answers by touching a worklet runtime has to know which it is on. That is the
+// one caller today; see core/ReanimatedModule.cpp.
+bool isUiThread();
+
+} // namespace basalt

package/native/core/PointerButtons.h

@@ -0,0 +1,63 @@
+// Which mouse button, and what the three desktops do about it.
+//
+// Header-only and shared, because the numbers are the thing three copies drift
+// on: each toolkit numbers its buttons differently, W3C numbers them a third
+// way, and React Native's `PointerEvent` carries W3C's.
+//
+// ## Why this exists at all
+//
+// React Native's *touch* model has no concept of which button -- a phone has
+// one finger and no buttons -- so until now every host forwarded every click as
+// a touch. That was three different wrongs. GTK set its click gesture to button
+// 0, meaning all of them, and AppKit forwarded `rightMouseDown:` the same as
+// `mouseDown:`, so on both a right-click *activated* whatever it landed on: a
+// `<Pressable>` fired its `onPress` from the wrong button. Windows handled only
+// WM_LBUTTONDOWN, so a right-click there did nothing whatsoever.
+//
+// What a desktop expects is neither. A secondary click is not a press -- the web
+// does not fire `click` for one, and no desktop toolkit treats it as an
+// activation -- it is a request for a context menu. So a secondary or middle
+// click now produces a pointer event and no touch, which is what lets an app
+// answer it without every `<Pressable>` on the screen answering first.
+
+#pragma once
+
+#include <cstdint>
+
+namespace basalt {
+
+// W3C's numbering, which is what `PointerEvent::button` carries. Not the
+// toolkits': GTK counts from 1, AppKit has a separate selector per button, and
+// Windows has a separate message.
+enum class PointerButton : int {
+  Primary = 0,
+  Middle = 1,
+  Secondary = 2,
+};
+
+// Whether this button presses things.
+//
+// The whole question in one place. Only the primary button drives React
+// Native's touch model -- responder negotiation, `onPress`, a gesture handler
+// claiming the pointer -- because that model has no way to say which button it
+// was, and a right-click that pressed things is the bug this exists to stop.
+inline bool isPressButton(PointerButton button) {
+  return button == PointerButton::Primary;
+}
+
+// `PointerEvent::buttons`, the mask of what is held *during* the event. A
+// different number from `button` in the same event, which is exactly the sort
+// of thing worth writing down once: primary is 1, secondary is 2, middle is 4.
+inline std::uint32_t buttonsMaskFor(PointerButton button) {
+  switch (button) {
+    case PointerButton::Primary:
+      return 1;
+    case PointerButton::Middle:
+      return 4;
+    case PointerButton::Secondary:
+      return 2;
+  }
+  return 0;
+}
+
+} // namespace basalt

package/native/core/PullToRefresh.cpp

@@ -0,0 +1,57 @@
+#include "PullToRefresh.h"
+
+namespace basalt {
+
+using facebook::react::Tag;
+
+void PullToRefreshTracker::attach(Tag scrollTag, Tag controlTag) {
+  if (scrollTag == 0 || controlTag == 0) {
+    return;
+  }
+  byScroll_[scrollTag].control = controlTag;
+  scrollByControl_[controlTag] = scrollTag;
+}
+
+void PullToRefreshTracker::forget(Tag tag) {
+  if (const auto asControl = scrollByControl_.find(tag); asControl != scrollByControl_.end()) {
+    byScroll_.erase(asControl->second);
+    scrollByControl_.erase(asControl);
+    return;
+  }
+  if (const auto asScroll = byScroll_.find(tag); asScroll != byScroll_.end()) {
+    scrollByControl_.erase(asScroll->second.control);
+    byScroll_.erase(asScroll);
+  }
+}
+
+Tag PullToRefreshTracker::controlFor(Tag scrollTag) const {
+  const auto found = byScroll_.find(scrollTag);
+  return found != byScroll_.end() ? found->second.control : 0;
+}
+
+bool PullToRefreshTracker::pull(Tag scrollTag, double amount) {
+  const auto found = byScroll_.find(scrollTag);
+  if (found == byScroll_.end()) {
+    return false;
+  }
+  Entry &entry = found->second;
+  if (amount > 0.0) {
+    entry.pulled += amount;
+  }
+  if (entry.fired || entry.pulled < kPullToRefreshThreshold) {
+    return false;
+  }
+  entry.fired = true;
+  return true;
+}
+
+void PullToRefreshTracker::release(Tag scrollTag) {
+  const auto found = byScroll_.find(scrollTag);
+  if (found == byScroll_.end()) {
+    return;
+  }
+  found->second.pulled = 0.0;
+  found->second.fired = false;
+}
+
+} // namespace basalt

package/native/core/PullToRefresh.h

@@ -0,0 +1,73 @@
+// The pull half of <RefreshControl>.
+//
+// A desktop scroll view has no rubber band. There is nothing to drag past the
+// top, no elastic to stretch, and no released-at-a-distance moment to fire on
+// -- which is why React Native's own pull-to-refresh exists on phones and not
+// here. What a desktop does have is a wheel that keeps reporting upward scroll
+// after the offset has already reached zero, and that is the same gesture in
+// every way that matters: the person is asking for something above the top of
+// the list.
+//
+// So this counts that. The scroll view clamps its offset as it always has --
+// nothing here moves anything -- and hands over how far past the top the
+// gesture asked to go. Once that passes the threshold, `onRefresh` fires once,
+// and not again until the gesture stops.
+//
+// Portable for the usual reason: the counting is identical on three desktops
+// and the wheel plumbing is not. It also makes the one part that is easy to get
+// wrong -- firing repeatedly while somebody keeps scrolling -- testable without
+// a mouse.
+
+#pragma once
+
+#include "DesktopControls.h"
+
+#include <react/renderer/core/ReactPrimitives.h>
+
+#include <unordered_map>
+
+namespace basalt {
+
+class PullToRefreshTracker {
+ public:
+  // Says that `controlTag` is the <RefreshControl> belonging to `scrollTag`.
+  // Called by the mounting manager when a PullToRefreshView is parented, which
+  // is the only place the relationship is visible.
+  void attach(facebook::react::Tag scrollTag, facebook::react::Tag controlTag);
+
+  // Drops whatever `tag` was, whether it was a scroll view or a control.
+  void forget(facebook::react::Tag tag);
+
+  // The refresh control for a scroll view, or 0 for a scroll view with none.
+  facebook::react::Tag controlFor(facebook::react::Tag scrollTag) const;
+
+  // How far past the top this gesture has asked to go, accumulated. `amount`
+  // is in points and positive; a downward scroll or any scroll that actually
+  // moved the view calls `release` instead.
+  //
+  // Returns true exactly once per gesture: on the step that crosses the
+  // threshold. A scroll view with no refresh control always returns false, so
+  // the caller needs no separate check.
+  bool pull(facebook::react::Tag scrollTag, double amount);
+
+  // The gesture ended, or moved the scroll view off the top. Re-arms the pull.
+  void release(facebook::react::Tag scrollTag);
+
+ private:
+  struct Entry {
+    facebook::react::Tag control{0};
+    double pulled{0.0};
+    // Whether this gesture has already fired. Without it a wheel held down
+    // fires `onRefresh` sixty times a second, and React Native's contract is
+    // one call per pull.
+    bool fired{false};
+  };
+
+  std::unordered_map<facebook::react::Tag, Entry> byScroll_;
+  // The other direction, so `forget` works when a control is deleted and its
+  // scroll view is not -- which is what unmounting a <RefreshControl> looks
+  // like.
+  std::unordered_map<facebook::react::Tag, facebook::react::Tag> scrollByControl_;
+};
+
+} // namespace basalt

package/native/core/ReanimatedCompat.h

@@ -0,0 +1,47 @@
+// What react-native-reanimated's C++ needs on a platform that is neither
+// Android nor Apple.
+//
+// Force-included ahead of Reanimated's own sources; see cmake/Reanimated.cmake.
+//
+// Reanimated calls `Common/cpp` its portable half and it very nearly is -- the
+// animation clock, the shadow-tree cloning, the CSS engine and the registries
+// are all platform-independent. But about ninety `#ifdef ANDROID` /
+// `#ifdef __APPLE__` branches run through it, and a few of them choose a *type*
+// rather than an implementation:
+//
+//     #ifdef ANDROID
+//     using SynchronouslyUpdateUIPropsFunction = ...
+//     #elif __APPLE__
+//     using SynchronouslyUpdateUIPropsFunction = ...
+//     #endif
+//
+// On a third platform that alias is never declared, and `PlatformDepMethodsHolder`
+// -- which has a member of that type unconditionally -- does not compile.
+//
+// Declaring it here first is enough: the `#elif` chain then skips a definition
+// that already exists, and everything downstream sees the type it expected.
+// Nothing is patched and nothing is vendored, which is the same rule the rest
+// of this project keeps.
+//
+// The Apple shape is the one chosen, for the reason it is chosen everywhere
+// else here: it takes a tag and a dynamic, which is what a desktop mounting
+// manager can act on, while Android's takes two parallel arrays built for JNI.
+//
+// This file is only reached on a build that is neither Android nor Apple, which
+// today means Linux and, later, Windows. On macOS it compiles to nothing.
+
+#pragma once
+
+#if !defined(ANDROID) && !defined(__APPLE__)
+
+#include <folly/dynamic.h>
+
+#include <functional>
+
+namespace reanimated {
+
+using SynchronouslyUpdateUIPropsFunction = std::function<void(const int, const folly::dynamic &)>;
+
+} // namespace reanimated
+
+#endif