basalt-core 0.0.0-rc5 → 0.2.0

package/native/core/SettingsStore.h

@@ -0,0 +1,127 @@
+// `Settings`, which on iOS is `NSUserDefaults` and on a desktop is a file.
+//
+// React Native's `Settings` is four calls -- `get`, `set`, `watchKeys`,
+// `clearWatch` -- over one native module, `SettingsManager`, which is a
+// `getEnforcing` lookup. Nobody answered it here, so an app that reached for
+// the API got React Native's `SettingsFallback`: three `console.warn`s and a
+// null. The module was never even reached, for the same reason `Share` was not
+// -- `Settings.js` branches on `Platform.OS === 'ios'` and everything else
+// takes the fallback -- so this needs the JavaScript override as well; see
+// src/overrides/Settings.ts.
+//
+// ## Why a file rather than each desktop's own settings store
+//
+// Each of the three has one, and none of them is the same shape as this API.
+// macOS has `NSUserDefaults`, which is the thing `Settings` wraps and which a
+// host could use directly. GTK's nearest equivalent is `GSettings`, which
+// refuses a key that is not in a compiled schema -- and this API's whole
+// contract is that an app invents its own keys at runtime, so a schema cannot
+// exist. Windows has the registry, which has no JSON and no arrays.
+//
+// So: a JSON object in a file, identically on all three. One implementation
+// with one set of semantics beats one real answer and two approximations that
+// differ in what they can store. The cost is that macOS settings are not
+// visible to `defaults read`, which is recorded in docs/backlog/modules.md
+// along with the call that would change it.
+//
+// ## What is in the file
+//
+// A single JSON object, written whole on every change. Not a log and not a
+// database: `Settings` is a handful of keys an app remembers between runs --
+// a window's last tab, whether the tour was seen -- and an app with more than
+// that wants AsyncStorage or SQLite, neither of which this pretends to be.
+//
+// Written to a sibling and renamed over, so a process that dies mid-write
+// leaves the previous file rather than half of a new one. That matters more
+// here than it looks: this file is read at startup, and a truncated one would
+// make every later run start empty.
+//
+// ## What is not here
+//
+// `watchKeys` only ever fires for a change this process did not make. That is
+// not a shortcut: iOS sets `_ignoringUpdates` around its own `setValues` for
+// exactly the same reason, because `Settings.set` has already updated
+// JavaScript's copy by the time the native module is called. Firing for an
+// external change means watching the file, which is three different APIs, and
+// is recorded rather than written; see docs/backlog/modules.md.
+
+#pragma once
+
+#include <folly/dynamic.h>
+
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace basalt {
+
+// Where the settings live, or an empty path when there is nowhere to put them.
+//
+// `BASALT_SETTINGS_FILE` wins when it is set, which is how the end-to-end
+// scenario points two runs of a host at the same temporary file instead of at
+// the person's real one, and how a portable install keeps its settings beside
+// itself.
+//
+// Otherwise it is the per-user configuration directory each desktop names --
+// `$XDG_CONFIG_HOME` or `~/.config` on Linux, `~/Library/Application Support`
+// on macOS, `%APPDATA%` on Windows -- plus the application's identifier, plus
+// `settings.json`. The identifier is what `app.identity.json` says, so two
+// applications on one machine do not share a file; an app built by hand has no
+// identity and lands under `basalt`, which is the honest answer for a binary
+// that has not said who it is.
+//
+// Empty when even the home directory is unknown, which is a container with no
+// environment rather than a mistake. A store with no path keeps its values in
+// memory for the life of the process and persists nothing.
+std::filesystem::path settingsFilePath();
+
+// One spelling, in one place, for the same reason kTestQuitFileVar is.
+inline constexpr const char *kSettingsFileVar = "BASALT_SETTINGS_FILE";
+
+// The key-value store behind `SettingsManager`.
+//
+// Loaded in the constructor and saved on every change. Not thread-safe and not
+// required to be: every caller is a TurboModule method, which runs on the
+// JavaScript thread.
+class SettingsStore {
+ public:
+  // Reads `file` if it is there. A missing file is the normal first run; a file
+  // that is not a JSON object is logged and treated as empty, because an app
+  // that refuses to start over a settings file somebody hand-edited would be
+  // worse than one that starts with no settings.
+  explicit SettingsStore(std::filesystem::path file);
+
+  // Every setting, as the object `getConstants().settings` hands to JavaScript.
+  const folly::dynamic &values() const {
+    return values_;
+  }
+
+  // Merges `values` in, one key deep, and answers the keys whose value actually
+  // changed. A key whose new value equals the old one is not in that list,
+  // which is what decides whether anything needs writing.
+  //
+  // A null value deletes the key rather than storing a null. That is iOS's
+  // behaviour -- `RCTSettingsManager` calls `removeObjectForKey:` when
+  // `RCTConvert NSPropertyList:` answers nil -- and an app that sets a key to
+  // null means to forget it.
+  std::vector<std::string> merge(const folly::dynamic &values);
+
+  // Removes `keys`, answering the ones that were actually there.
+  std::vector<std::string> erase(const std::vector<std::string> &keys);
+
+  // Where it is kept, for the host that wants to say so in a log.
+  const std::filesystem::path &file() const {
+    return file_;
+  }
+
+ private:
+  // Writes the whole object, through a sibling and a rename. Failure is logged
+  // and not reported: there is nothing an app could do about a read-only home
+  // directory, and losing a setting is not worth refusing to run over.
+  void save() const;
+
+  std::filesystem::path file_;
+  folly::dynamic values_ = folly::dynamic::object();
+};
+
+} // namespace basalt

package/native/core/ShadowShape.h

@@ -0,0 +1,38 @@
+// The shape a box shadow is cast by: a corner radius grown by the spread.
+//
+// Not an addition, which is the whole reason this is written down. The CSS spec
+// gives a curve: a corner tighter than the spread is rounded off more gently
+// than the spread alone would make it, so a small radius on a widely spread
+// shadow does not turn into a circle.
+//
+// https://drafts.csswg.org/css-backgrounds/#shadow-shape
+//
+// Shared because two hosts compute it and the third does not: GSK's shadow
+// nodes take the view's own outline and grow it themselves, where AppKit builds
+// a `CGPath` and Direct2D a geometry, and both of those have to do this. It is
+// a port of React Native's iOS half, which took it from the same place; a
+// second hand-rolled copy of a cubic is exactly the kind of thing that ends up
+// subtly different on one platform.
+//
+// A negative spread is allowed and shrinks the box, which is what an inset
+// shadow's hole is built from, so `std::abs` is in the ratio rather than a
+// guard against it.
+
+#pragma once
+
+#include <cmath>
+
+namespace basalt {
+
+// `radius` grown by `spread`, never below zero.
+inline double spreadRadius(double radius, double spread) {
+  double adjustment = spread;
+  if (radius < std::abs(spread)) {
+    const double ratio = radius / std::abs(spread);
+    adjustment *= 1.0 + std::pow(ratio - 1.0, 3.0);
+  }
+  const double grown = radius + adjustment;
+  return grown > 0.0 ? grown : 0.0;
+}
+
+} // namespace basalt

package/native/core/SkiaViewComponent.cpp

@@ -0,0 +1,11 @@
+#include "SkiaViewComponent.h"
+
+namespace facebook::react {
+
+// The name the package's JavaScript registers, from
+// `codegenNativeComponent("SkiaView")` in
+// lib/module/specs/SkiaViewNativeComponent.js. 3.x's name; 2.x's is
+// "SkiaPictureView", beside this.
+extern const char SkiaViewComponentName[] = "SkiaView";
+
+} // namespace facebook::react

package/native/core/SkiaViewComponent.h

@@ -0,0 +1,50 @@
+// `SkiaView`, which is what a `<Canvas>` from react-native-skia 3.x mounts.
+//
+// The 2.x one is `SkiaPictureView`, in core/SkiaPictureViewComponent.h beside
+// this, and the rename is the whole difference as far as a component registry
+// is concerned: `lib/module/specs/SkiaViewNativeComponent.js` is
+// `codegenNativeComponent("SkiaView")` where it used to say the longer name.
+// Both are registered, because which one an app mounts is decided by the Skia
+// it installed and a host binary does not know which that is until the app's
+// JavaScript runs.
+//
+// Plain `ViewProps`, for the reason the 2.x header spells out at length: a
+// `<Canvas>` does not carry its content in props. It records in JavaScript and
+// pushes the result through the Skia JSI API keyed by an id, and the only thing
+// the native side needs from props is which id it is -- `nativeID`, an ordinary
+// `ViewProps` field that arrives whatever a view config says.
+//
+// What is dropped, which is a shorter list than 2.x's: `opaque`,
+// `highBitDepth`, `androidSurfaceType`, `androidZOrderOnTop` and
+// `pointerEvents`. The two Android ones select a backing view there and mean
+// nothing to a CAMetalLayer. `opaque` and `highBitDepth` are the backing
+// store's format -- an opaque layer and ten bits a channel -- and a canvas
+// without them draws the same picture into an eight-bit one. `pointerEvents`
+// is already a `ViewProps` field and is handled where every other view's is.
+// When one is wanted it belongs in a props class here and in the peer, which
+// is the same call core/ExpoImageComponent.h makes about blurhash.
+//
+// Registered unconditionally, like the 2.x one and like ExpoImage: it costs a
+// name in a registry, and the alternative is a host that has to be rebuilt to
+// run an app that draws. Without Skia in the build the view mounts and stays
+// empty -- and an app that draws has already failed at
+// `getEnforcing('RNSkiaModule')` long before, which is the error that says
+// what is actually missing.
+
+#pragma once
+
+#include <react/renderer/components/view/ConcreteViewShadowNode.h>
+#include <react/renderer/components/view/ViewEventEmitter.h>
+#include <react/renderer/components/view/ViewProps.h>
+#include <react/renderer/core/ConcreteComponentDescriptor.h>
+
+namespace facebook::react {
+
+extern const char SkiaViewComponentName[];
+
+using SkiaViewShadowNode =
+    ConcreteViewShadowNode<SkiaViewComponentName, ViewProps, ViewEventEmitter>;
+
+using SkiaViewComponentDescriptor = ConcreteComponentDescriptor<SkiaViewShadowNode>;
+
+} // namespace facebook::react

package/native/core/SystemLocale.cpp

@@ -0,0 +1,103 @@
+#include "SystemLocale.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstdlib>
+#include <mutex>
+
+namespace basalt {
+
+namespace {
+
+struct State {
+  std::mutex mutex;
+  SystemLocale locale;
+  bool allowRTL{true};
+  std::optional<bool> forced;
+};
+
+State &state() {
+  static State value;
+  return value;
+}
+
+// The scripts that read right to left, by language code. Short because it is
+// short: Arabic, Hebrew, Persian, Urdu and the two Kurdish and Pashto codes
+// cover what a test needs, and nothing here decides a real locale -- the
+// platforms answer that themselves. See the header.
+bool languageReadsRightToLeft(const std::string &identifier) {
+  std::string language;
+  for (const char letter : identifier) {
+    if (letter == '-' || letter == '_' || letter == '.') {
+      break;
+    }
+    language += static_cast<char>(std::tolower(static_cast<unsigned char>(letter)));
+  }
+  return language == "ar" || language == "he" || language == "iw" || language == "fa" ||
+      language == "ur" || language == "ps" || language == "ckb" || language == "yi";
+}
+
+} // namespace
+
+std::optional<SystemLocale> testLocale() {
+  static const std::optional<SystemLocale> requested = []() -> std::optional<SystemLocale> {
+    const char *const value = std::getenv("BASALT_TEST_LOCALE");
+    if (value == nullptr || *value == '\0') {
+      return std::nullopt;
+    }
+    SystemLocale locale;
+    locale.identifier = value;
+    locale.rightToLeft = languageReadsRightToLeft(locale.identifier);
+    return locale;
+  }();
+  return requested;
+}
+
+void setSystemLocale(SystemLocale locale) {
+  State &shared = state();
+  const std::lock_guard<std::mutex> guard(shared.mutex);
+  shared.locale = std::move(locale);
+}
+
+SystemLocale lastKnownSystemLocale() {
+  if (const std::optional<SystemLocale> requested = testLocale()) {
+    return *requested;
+  }
+  State &shared = state();
+  const std::lock_guard<std::mutex> guard(shared.mutex);
+  return shared.locale;
+}
+
+bool resolveRightToLeft(bool allowRTL, std::optional<bool> forced, bool systemRightToLeft) {
+  if (!allowRTL) {
+    return false;
+  }
+  if (forced.has_value()) {
+    return *forced;
+  }
+  return systemRightToLeft;
+}
+
+bool layoutIsRightToLeft() {
+  const SystemLocale locale = lastKnownSystemLocale();
+  State &shared = state();
+  const std::lock_guard<std::mutex> guard(shared.mutex);
+  return resolveRightToLeft(shared.allowRTL, shared.forced, locale.rightToLeft);
+}
+
+void setAllowRTL(bool allow) {
+  State &shared = state();
+  const std::lock_guard<std::mutex> guard(shared.mutex);
+  shared.allowRTL = allow;
+}
+
+void setForceRTL(bool force) {
+  State &shared = state();
+  const std::lock_guard<std::mutex> guard(shared.mutex);
+  // `forceRTL(false)` clears the force rather than forcing left-to-right,
+  // which is what React Native's own platforms do: an app turning it off goes
+  // back to following the system.
+  shared.forced = force ? std::optional<bool>(true) : std::nullopt;
+}
+
+} // namespace basalt

package/native/core/SystemLocale.h

@@ -0,0 +1,86 @@
+// Which language the desktop is in, and which way it reads.
+//
+// `I18nManager` answered neither until 2026-10-10: `localeIdentifier` was the
+// empty string and `isRTL` was false unless an app had called `forceRTL`. The
+// reason recorded in CoreModules.cpp was that "deciding it from the system
+// locale would need a locale database this does not have", which is true of
+// *parsing a locale name* and not of the question: every desktop publishes the
+// reading direction directly.
+//
+//   GTK      `gtk_widget_get_default_direction()`, which GTK itself resolves
+//            from the locale -- translators ship "default:RTL" for a
+//            right-to-left language and GTK reads it back.
+//   AppKit   `+[NSLocale characterDirectionForLanguage:]`, which answers from
+//            ICU's own data.
+//   Windows  `GetLocaleInfoEx` with `LOCALE_IREADINGLAYOUT`, where 1 is
+//            right-to-left.
+//
+// What this costs if it is wrong is the whole layout mirrored the wrong way,
+// which is why none of the three guesses from the language name.
+//
+// ## Why the layout and not only the flag
+//
+// `I18nManager.isRTL` is what an app branches on, and React Native expects the
+// *layout* to agree: Yoga mirrors `flexDirection: 'row'`, `start`/`end`,
+// padding and margin when it is told the direction, and the host is what tells
+// it, through `LayoutConstraints::layoutDirection`. All three hosts passed
+// `LeftToRight` unconditionally, so even an app calling `forceRTL(true)` and
+// reloading -- which is what React Native's own documentation says to do --
+// got a left-to-right layout with a flag that claimed otherwise.
+
+#pragma once
+
+#include <optional>
+#include <string>
+
+namespace basalt {
+
+struct SystemLocale {
+  // BCP 47 or POSIX, as the platform spells it: `en-US` on Windows, `en_US` on
+  // the other two. Passed through rather than normalised, because React
+  // Native's own platforms do the same -- iOS reports `en_US` and Android
+  // `en_US` too -- and an app parsing it is parsing its platform's spelling.
+  std::string identifier;
+  bool rightToLeft{false};
+};
+
+// What the desktop says, asked once at startup by the host. **Called on the UI
+// thread**: a toolkit's settings are not thread-safe.
+SystemLocale systemLocale();
+
+// What a test asked for, or nothing: `BASALT_TEST_LOCALE=ar-EG` overrides both
+// fields, the direction coming from the language rather than from a database --
+// the five right-to-left scripts are a short list and a test needs no more
+// than that.
+//
+// Here for the same reason `BASALT_TEST_FONT_SCALE` is in core/FontScaling.h:
+// a scenario cannot change the machine's language, and a feature with no test
+// that fails when it is removed is not finished.
+std::optional<SystemLocale> testLocale();
+
+// Remembered by the host at startup, readable from any thread.
+void setSystemLocale(SystemLocale locale);
+SystemLocale lastKnownSystemLocale();
+
+// Whether the layout should be mirrored, which is `I18nManager.isRTL`.
+//
+// React Native's three controls, in its own order of precedence:
+//
+//   allowRTL(false)   never mirrored, whatever the locale says
+//   forceRTL(true)    always mirrored, whatever the locale says
+//   otherwise         whatever the locale says
+//
+// `forceRTL(false)` is not "force left to right": React Native treats it as
+// clearing the force, which is why the forced state is an optional here.
+bool resolveRightToLeft(bool allowRTL, std::optional<bool> forced, bool systemRightToLeft);
+
+// The answer for this process, from what the host reported and what an app has
+// asked for since. Read by the hosts when they build layout constraints and
+// by the I18nManager module.
+bool layoutIsRightToLeft();
+
+// The app's half, from `I18nManager`.
+void setAllowRTL(bool allow);
+void setForceRTL(bool force);
+
+} // namespace basalt

package/native/core/TestDialog.cpp

@@ -72,6 +72,34 @@ std::optional<int> scriptedMenuChoice() {
   return choice;
 }
 
+int scriptedMenuIndex(const std::vector<MenuEntry> &entries, int scripted) {
+  // Out of range answers as a dismissal rather than being clamped, which is the
+  // opposite of what presentAlert does with a button. A menu's entries are not
+  // interchangeable -- picking the nearest one would run something the script
+  // did not ask for -- whereas an alert's last button is always the way out.
+  //
+  // `menuEntryCount` and not `entries.size()`: an index counts every level now,
+  // so the valid range is the whole tree and a script naming a submenu's item
+  // would otherwise be refused for being past the end of the top level.
+  const int count = menuEntryCount(entries);
+  if (scripted < 0 || scripted >= count) {
+    return -1;
+  }
+
+  // And a dismissal for anything a person could not have chosen either: a
+  // parent opens rather than chooses, a separator is a line, an entry naming a
+  // role this desktop cannot perform is not in the menu at all, and a disabled
+  // entry is drawn and refuses the click. The last of those was missing until
+  // an action sheet put its title in the menu as a disabled entry, which a
+  // script could then "choose".
+  const MenuEntry *entry = menuEntryAt(entries, scripted);
+  if (entry == nullptr || entry->isParent() || entry->isSeparator() || !menuEntryShown(*entry) ||
+      !entry->enabled) {
+    return -1;
+  }
+  return scripted;
+}
+
 void presentMenu(const MenuRequest &request, MenuCallback onChosen) {
   const std::optional<int> scripted = scriptedMenuChoice();
   if (!scripted.has_value()) {
@@ -79,12 +107,23 @@ void presentMenu(const MenuRequest &request, MenuCallback onChosen) {
     return;
   }
 
-  // Out of range answers as a dismissal rather than being clamped, which is the
-  // opposite of what presentAlert does with a button. A menu's entries are not
-  // interchangeable -- picking the nearest one would run something the script
-  // did not ask for -- whereas an alert's last button is always the way out.
-  const int last = static_cast<int>(request.entries.size()) - 1;
-  const int index = (*scripted < 0 || *scripted > last) ? -1 : *scripted;
+  const int index = scriptedMenuIndex(request.entries, *scripted);
+
+  // The platform's half of a role still happens: this seam exists to skip the
+  // window a person would have clicked, not to skip what choosing the item does.
+  // Without this, `copy` under test would resolve a promise and copy nothing.
+  //
+  // On the UI thread, which this is not. `showContextMenu` is a TurboModule
+  // call, so this runs on the JavaScript thread, and `performMenuRole` touches
+  // the window and the focused control -- AppKit from the wrong thread does not
+  // return. The symptom was the promise never settling at all: `about` opens a
+  // panel, and the call to open it never came back.
+  if (index >= 0) {
+    const MenuEntry *entry = menuEntryAt(request.entries, index);
+    if (entry != nullptr && !entry->role.empty()) {
+      postToUiThread([role = entry->role] { performMenuRole(role); });
+    }
+  }
   onChosen(index);
 }
 

package/native/core/TestDialog.h

@@ -72,6 +72,21 @@ void presentAlert(const AlertRequest &request, AlertCallback onButton);
 // stops the process where it stands.
 std::optional<int> scriptedMenuChoice();
 
+// Which entry a script naming `scripted` actually lands on, or -1 for a
+// dismissal.
+//
+// What a script can answer is what a real menu can, which is the whole point of
+// the instrument and is four separate refusals: an index past the end of the
+// tree, a separator, a submenu's parent -- which opens rather than chooses --
+// and an entry that is drawn greyed or not drawn at all. Each of those is
+// something a person could not have clicked, so a script that names one is
+// answered the way closing the menu is.
+//
+// Separate from presentMenu so that it can be asserted. The variable is read
+// once and cached for the life of the process, so a test cannot set it, and the
+// arithmetic is the part worth testing anyway.
+int scriptedMenuIndex(const std::vector<MenuEntry> &entries, int scripted);
+
 // `showMenu`, or the scripted answer when there is one. Everything that would
 // put a popup menu on screen goes through here rather than calling the platform
 // directly, for the same reason `presentAlert` exists.